GCC Middle and Back End API Reference
sarif_builder Class Reference
Collaboration diagram for sarif_builder:

Public Member Functions

 sarif_builder (diagnostic_context *context, bool formatted)
 
void end_diagnostic (diagnostic_context *context, const diagnostic_info &diagnostic, diagnostic_t orig_diag_kind)
 
void emit_diagram (diagnostic_context *context, const diagnostic_diagram &diagram)
 
void end_group ()
 
void flush_to_file (FILE *outf)
 
json::arraymake_locations_arr (const diagnostic_info &diagnostic)
 
json::objectmake_location_object (const rich_location &rich_loc, const logical_location *logical_loc)
 
json::objectmake_message_object (const char *msg) const
 
json::objectmake_message_object_for_diagram (diagnostic_context *context, const diagnostic_diagram &diagram)
 

Private Member Functions

sarif_resultmake_result_object (diagnostic_context *context, const diagnostic_info &diagnostic, diagnostic_t orig_diag_kind)
 
void set_any_logical_locs_arr (json::object *location_obj, const logical_location *logical_loc)
 
json::objectmake_location_object (const diagnostic_event &event)
 
json::objectmake_code_flow_object (const diagnostic_path &path)
 
json::objectmake_thread_flow_location_object (const diagnostic_event &event, int path_event_idx)
 
json::arraymaybe_make_kinds_array (diagnostic_event::meaning m) const
 
json::objectmaybe_make_physical_location_object (location_t loc)
 
json::objectmake_artifact_location_object (location_t loc)
 
json::objectmake_artifact_location_object (const char *filename)
 
json::objectmake_artifact_location_object_for_pwd () const
 
json::objectmaybe_make_region_object (location_t loc) const
 
json::objectmaybe_make_region_object_for_context (location_t loc) const
 
json::objectmake_region_object_for_hint (const fixit_hint &hint) const
 
json::objectmake_multiformat_message_string (const char *msg) const
 
json::objectmake_top_level_object (sarif_invocation *invocation_obj, json::array *results)
 
json::objectmake_run_object (sarif_invocation *invocation_obj, json::array *results)
 
json::objectmake_tool_object () const
 
json::objectmake_driver_tool_component_object () const
 
json::arraymaybe_make_taxonomies_array () const
 
json::objectmaybe_make_cwe_taxonomy_object () const
 
json::objectmake_tool_component_reference_object_for_cwe () const
 
json::objectmake_reporting_descriptor_object_for_warning (diagnostic_context *context, const diagnostic_info &diagnostic, diagnostic_t orig_diag_kind, const char *option_text)
 
json::objectmake_reporting_descriptor_object_for_cwe_id (int cwe_id) const
 
json::objectmake_reporting_descriptor_reference_object_for_cwe_id (int cwe_id)
 
json::objectmake_artifact_object (const char *filename)
 
charget_source_lines (const char *filename, int start_line, int end_line) const
 
json::objectmaybe_make_artifact_content_object (const char *filename) const
 
json::objectmaybe_make_artifact_content_object (const char *filename, int start_line, int end_line) const
 
json::objectmake_fix_object (const rich_location &rich_loc)
 
json::objectmake_artifact_change_object (const rich_location &richloc)
 
json::objectmake_replacement_object (const fixit_hint &hint) const
 
json::objectmake_artifact_content_object (const char *text) const
 
int get_sarif_column (expanded_location exploc) const
 

Private Attributes

diagnostic_contextm_context
 
sarif_invocationm_invocation_obj
 
json::arraym_results_array
 
sarif_resultm_cur_group_result
 
hash_set< const char * > m_filenames
 
bool m_seen_any_relative_paths
 
hash_set< free_string_hashm_rule_id_set
 
json::arraym_rules_arr
 
hash_set< int_hash< int, 0, 1 > > m_cwe_id_set
 
int m_tabstop
 
bool m_formatted
 

Detailed Description

A class for managing SARIF output (for -fdiagnostics-format=sarif-stderr
and -fdiagnostics-format=sarif-file).

As diagnostics occur, we build "result" JSON objects, and
accumulate state:
- which source files are referenced
- which warnings are emitted
- which CWEs are used

At the end of the compile, we use the above to build the full SARIF
object tree, adding the result objects to the correct place, and
creating objects for the various source files, warnings and CWEs
referenced.

Implemented:
- fix-it hints
- CWE metadata
- diagnostic groups (see limitations below)
- logical locations (e.g. cfun)

Known limitations:
- GCC supports one-deep nesting of diagnostics (via auto_diagnostic_group),
  but we only capture location and message information from such nested
  diagnostics (e.g. we ignore fix-it hints on them)
- doesn't yet capture command-line arguments: would be run.invocations
  property (SARIF v2.1.0 section 3.14.11), as invocation objects
  (SARIF v2.1.0 section 3.20), but we'd want to capture the arguments to
  toplev::main, and the response files.
- doesn't capture escape_on_output_p
- doesn't capture secondary locations within a rich_location
  (perhaps we should use the "relatedLocations" property: SARIF v2.1.0
  section 3.27.22)
- doesn't capture "artifact.encoding" property
  (SARIF v2.1.0 section 3.24.9).
- doesn't capture hashes of the source files
  ("artifact.hashes" property (SARIF v2.1.0 section 3.24.11).
- doesn't capture the "analysisTarget" property
  (SARIF v2.1.0 section 3.27.13).
- doesn't capture labelled ranges
- doesn't capture -Werror cleanly
- doesn't capture inlining information (can SARIF handle this?)
- doesn't capture macro expansion information (can SARIF handle this?).   

Constructor & Destructor Documentation

◆ sarif_builder()

sarif_builder::sarif_builder ( diagnostic_context * context,
bool formatted )
class sarif_builder.   
sarif_builder's ctor.   

Member Function Documentation

◆ emit_diagram()

void sarif_builder::emit_diagram ( diagnostic_context * context,
const diagnostic_diagram & diagram )
Implementation of diagnostic_context::m_diagrams.m_emission_cb
for SARIF output.   

References gcc_assert, ggc_alloc(), m_cur_group_result, and sarif_result::on_diagram().

Referenced by sarif_output_format::on_diagram().

◆ end_diagnostic()

◆ end_group()

void sarif_builder::end_group ( )
Implementation of "end_group_cb" for SARIF output.   

References m_cur_group_result, and NULL.

Referenced by sarif_output_format::on_end_group().

◆ flush_to_file()

void sarif_builder::flush_to_file ( FILE * outf)
Create a top-level object, and add it to all the results
(and other entities) we've seen so far.

Flush it all to OUTF.   

References ggc_alloc(), m_context, m_formatted, m_invocation_obj, m_results_array, make_top_level_object(), NULL, and sarif_invocation::prepare_to_flush().

Referenced by sarif_file_output_format::~sarif_file_output_format(), and sarif_stream_output_format::~sarif_stream_output_format().

◆ get_sarif_column()

int sarif_builder::get_sarif_column ( expanded_location exploc) const
private

◆ get_source_lines()

char * sarif_builder::get_source_lines ( const char * filename,
int start_line,
int end_line ) const
private
Attempt to read the given range of lines from FILENAME; return
a freshly-allocated 0-terminated buffer containing them, or NULL.   

References diagnostic_context::get_file_cache(), file_cache::get_source_line(), ggc_alloc(), i, m_context, and NULL.

Referenced by maybe_make_artifact_content_object().

◆ make_artifact_change_object()

json::object * sarif_builder::make_artifact_change_object ( const rich_location & richloc)
private
Make an artifactChange object (SARIF v2.1.0 section 3.56) for RICHLOC.   

References ggc_alloc(), i, make_artifact_location_object(), and make_replacement_object().

Referenced by make_fix_object().

◆ make_artifact_content_object()

json::object * sarif_builder::make_artifact_content_object ( const char * text) const
private
Make an artifactContent object (SARIF v2.1.0 section 3.3) for TEXT.   

References ggc_alloc().

Referenced by make_replacement_object().

◆ make_artifact_location_object() [1/2]

json::object * sarif_builder::make_artifact_location_object ( const char * filename)
private
Make an artifactLocation object (SARIF v2.1.0 section 3.4) for FILENAME,
or return NULL.   

References ggc_alloc(), m_seen_any_relative_paths, and PWD_PROPERTY_NAME.

◆ make_artifact_location_object() [2/2]

json::object * sarif_builder::make_artifact_location_object ( location_t loc)
private
Make an artifactLocation object (SARIF v2.1.0 section 3.4) for LOC,
or return NULL.   

References LOCATION_FILE, and make_artifact_location_object().

Referenced by make_artifact_change_object(), make_artifact_location_object(), make_artifact_object(), and maybe_make_physical_location_object().

◆ make_artifact_location_object_for_pwd()

json::object * sarif_builder::make_artifact_location_object_for_pwd ( ) const
private
Make an artifactLocation object (SARIF v2.1.0 section 3.4) for the pwd,
for use in the "run.originalUriBaseIds" property (SARIF v2.1.0
section 3.14.14) when we have any relative paths.   

References free(), gcc_assert, ggc_alloc(), and make_pwd_uri_str().

Referenced by make_run_object().

◆ make_artifact_object()

json::object * sarif_builder::make_artifact_object ( const char * filename)
private

◆ make_code_flow_object()

json::object * sarif_builder::make_code_flow_object ( const diagnostic_path & path)
private
Make a codeFlow object (SARIF v2.1.0 section 3.36) for PATH.   

References ggc_alloc(), i, and make_thread_flow_location_object().

Referenced by make_result_object().

◆ make_driver_tool_component_object()

json::object * sarif_builder::make_driver_tool_component_object ( ) const
private
Make a toolComponent object (SARIF v2.1.0 section 3.19) for what SARIF
calls the "driver" (see SARIF v2.1.0 section 3.18.1).   

References free(), diagnostic_context::get_client_data_hooks(), ggc_alloc(), m_context, and m_rules_arr.

Referenced by make_tool_object().

◆ make_fix_object()

json::object * sarif_builder::make_fix_object ( const rich_location & richloc)
private
Make a fix object (SARIF v2.1.0 section 3.55) for RICHLOC.   

References ggc_alloc(), and make_artifact_change_object().

Referenced by make_result_object().

◆ make_location_object() [1/2]

json::object * sarif_builder::make_location_object ( const diagnostic_event & event)
private
Make a location object (SARIF v2.1.0 section 3.28) for EVENT
within a diagnostic_path.   

References ggc_alloc(), make_message_object(), maybe_make_physical_location_object(), and set_any_logical_locs_arr().

◆ make_location_object() [2/2]

json::object * sarif_builder::make_location_object ( const rich_location & rich_loc,
const logical_location * logical_loc )
Make a location object (SARIF v2.1.0 section 3.28) for RICH_LOC
and LOGICAL_LOC.   

References ggc_alloc(), maybe_make_physical_location_object(), and set_any_logical_locs_arr().

Referenced by make_locations_arr(), and make_thread_flow_location_object().

◆ make_locations_arr()

json::array * sarif_builder::make_locations_arr ( const diagnostic_info & diagnostic)
Make an array suitable for use as the "locations" property of:
- a "result" object (SARIF v2.1.0 section 3.27.12), or
- a "notification" object (SARIF v2.1.0 section 3.58.4).   

References diagnostic_context::get_client_data_hooks(), ggc_alloc(), m_context, make_location_object(), and NULL.

Referenced by make_result_object().

◆ make_message_object()

json::object * sarif_builder::make_message_object ( const char * msg) const
Make a message object (SARIF v2.1.0 section 3.11) for MSG.   

References ggc_alloc(), and msg.

Referenced by make_location_object(), and make_result_object().

◆ make_message_object_for_diagram()

json::object * sarif_builder::make_message_object_for_diagram ( diagnostic_context * context,
const diagnostic_diagram & diagram )
Make a message object (SARIF v2.1.0 section 3.11) for DIAGRAM.
We emit the diagram as a code block within the Markdown part
of the message.   

References ggc_alloc(), NULL, pp_clear_output_area(), pp_formatted_text(), pp_set_prefix(), pp_take_prefix(), and diagnostic_context::printer.

◆ make_multiformat_message_string()

json::object * sarif_builder::make_multiformat_message_string ( const char * msg) const
private
Make a multiformatMessageString object (SARIF v2.1.0 section 3.12)
for MSG.   

References ggc_alloc(), and msg.

Referenced by maybe_make_cwe_taxonomy_object().

◆ make_region_object_for_hint()

json::object * sarif_builder::make_region_object_for_hint ( const fixit_hint & hint) const
private
Make a region object (SARIF v2.1.0 section 3.30) for the deletion region
of HINT (as per SARIF v2.1.0 section 3.57.3).   

References expand_location(), get_sarif_column(), and ggc_alloc().

Referenced by make_replacement_object().

◆ make_replacement_object()

json::object * sarif_builder::make_replacement_object ( const fixit_hint & hint) const
private
Make a replacement object (SARIF v2.1.0 section 3.57) for HINT.   

References ggc_alloc(), make_artifact_content_object(), and make_region_object_for_hint().

Referenced by make_artifact_change_object().

◆ make_reporting_descriptor_object_for_cwe_id()

json::object * sarif_builder::make_reporting_descriptor_object_for_cwe_id ( int cwe_id) const
private
Make a reportingDescriptor object (SARIF v2.1.0 section 3.49)
for CWE_ID, for use within the CWE taxa array.   

References free(), get_cwe_url(), ggc_alloc(), pp_formatted_text(), and pp_printf().

Referenced by maybe_make_cwe_taxonomy_object().

◆ make_reporting_descriptor_object_for_warning()

json::object * sarif_builder::make_reporting_descriptor_object_for_warning ( diagnostic_context * context,
const diagnostic_info & diagnostic,
diagnostic_t orig_diag_kind,
const char * option_text )
private
Make a reportingDescriptor object (SARIF v2.1.0 section 3.49)
for a GCC warning.   

References free(), ggc_alloc(), and diagnostic_context::make_option_url().

Referenced by make_result_object().

◆ make_reporting_descriptor_reference_object_for_cwe_id()

json::object * sarif_builder::make_reporting_descriptor_reference_object_for_cwe_id ( int cwe_id)
private
Make a reportingDescriptorReference object (SARIF v2.1.0 section 3.52)
referencing CWE_ID, for use within a result object.
Also, add CWE_ID to m_cwe_id_set.   

References hash_set< KeyId, Lazy, Traits >::add(), gcc_assert, ggc_alloc(), m_cwe_id_set, make_tool_component_reference_object_for_cwe(), pp_formatted_text(), and pp_printf().

Referenced by make_result_object().

◆ make_result_object()

◆ make_run_object()

json::object * sarif_builder::make_run_object ( sarif_invocation * invocation_obj,
json::array * results )
private
Make a run object (SARIF v2.1.0 section 3.14).
Take ownership of INVOCATION_OBJ and RESULTS.   

References ggc_alloc(), m_filenames, m_seen_any_relative_paths, make_artifact_location_object_for_pwd(), make_artifact_object(), make_tool_object(), maybe_make_taxonomies_array(), and PWD_PROPERTY_NAME.

Referenced by make_top_level_object().

◆ make_thread_flow_location_object()

json::object * sarif_builder::make_thread_flow_location_object ( const diagnostic_event & ev,
int path_event_idx )
private
Make a threadFlowLocation object (SARIF v2.1.0 section 3.38) for EVENT.   

References ggc_alloc(), make_location_object(), and maybe_make_kinds_array().

Referenced by make_code_flow_object().

◆ make_tool_component_reference_object_for_cwe()

json::object * sarif_builder::make_tool_component_reference_object_for_cwe ( ) const
private
Make a toolComponentReference object (SARIF v2.1.0 section 3.54) that
references the CWE taxonomy.   

References ggc_alloc().

Referenced by make_reporting_descriptor_reference_object_for_cwe_id().

◆ make_tool_object()

◆ make_top_level_object()

json::object * sarif_builder::make_top_level_object ( sarif_invocation * invocation_obj,
json::array * results )
private
Make a top-level sarifLog object (SARIF v2.1.0 section 3.13).
Take ownership of INVOCATION_OBJ and RESULTS.   

References ggc_alloc(), make_run_object(), SARIF_SCHEMA, and SARIF_VERSION.

Referenced by flush_to_file().

◆ maybe_make_artifact_content_object() [1/2]

json::object * sarif_builder::maybe_make_artifact_content_object ( const char * filename) const
private
Make an artifactContent object (SARIF v2.1.0 section 3.3) for the
full contents of FILENAME.   

References diagnostic_context::get_file_cache(), file_cache::get_source_file_content(), ggc_alloc(), m_context, and NULL.

Referenced by make_artifact_object(), and maybe_make_region_object_for_context().

◆ maybe_make_artifact_content_object() [2/2]

json::object * sarif_builder::maybe_make_artifact_content_object ( const char * filename,
int start_line,
int end_line ) const
private
Make an artifactContent object (SARIF v2.1.0 section 3.3) for the given
run of lines within FILENAME (including the endpoints).   

References free(), get_source_lines(), ggc_alloc(), and NULL.

◆ maybe_make_cwe_taxonomy_object()

json::object * sarif_builder::maybe_make_cwe_taxonomy_object ( ) const
private
If we've seen any CWE IDs, make a toolComponent object
(SARIF v2.1.0 section 3.19) representing the CWE taxonomy, as per 3.19.3.
Populate the "taxa" property with all of the CWE IDs in m_cwe_id_set.

Otherwise return NULL.   

References ggc_alloc(), hash_set< KeyId, Lazy, Traits >::is_empty(), m_cwe_id_set, make_multiformat_message_string(), make_reporting_descriptor_object_for_cwe_id(), and NULL.

Referenced by maybe_make_taxonomies_array().

◆ maybe_make_kinds_array()

◆ maybe_make_physical_location_object()

json::object * sarif_builder::maybe_make_physical_location_object ( location_t loc)
private
Make a physicalLocation object (SARIF v2.1.0 section 3.29) for LOC,
or return NULL;
Add any filename to the m_artifacts.   

References hash_set< KeyId, Lazy, Traits >::add(), BUILTINS_LOCATION, ggc_alloc(), LOCATION_FILE, m_filenames, make_artifact_location_object(), maybe_make_region_object(), maybe_make_region_object_for_context(), and NULL.

Referenced by make_location_object(), and make_location_object().

◆ maybe_make_region_object()

json::object * sarif_builder::maybe_make_region_object ( location_t loc) const
private
Make a region object (SARIF v2.1.0 section 3.30) for LOC,
or return NULL.   

References BUILTINS_LOCATION, expand_location(), get_finish(), get_pure_location(), get_sarif_column(), get_start(), ggc_alloc(), and NULL.

Referenced by maybe_make_physical_location_object().

◆ maybe_make_region_object_for_context()

json::object * sarif_builder::maybe_make_region_object_for_context ( location_t loc) const
private
Make a region object (SARIF v2.1.0 section 3.30) for the "contextRegion"
property (SARIF v2.1.0 section 3.29.5) of a physicalLocation.

This is similar to maybe_make_region_object, but ignores column numbers,
covering the line(s) as a whole, and including a "snippet" property
embedding those source lines, making it easier for consumers to show
the pertinent source.   

References BUILTINS_LOCATION, expand_location(), get_finish(), get_pure_location(), get_start(), ggc_alloc(), maybe_make_artifact_content_object(), and NULL.

Referenced by maybe_make_physical_location_object().

◆ maybe_make_taxonomies_array()

json::array * sarif_builder::maybe_make_taxonomies_array ( ) const
private
If we've seen any CWE IDs, make an array for the "taxonomies" property
(SARIF v2.1.0 section 3.14.8) of a run object, containting a singl
toolComponent (3.19) as per 3.19.3, representing the CWE.

Otherwise return NULL.   

References ggc_alloc(), maybe_make_cwe_taxonomy_object(), and NULL.

Referenced by make_run_object().

◆ set_any_logical_locs_arr()

void sarif_builder::set_any_logical_locs_arr ( json::object * location_obj,
const logical_location * logical_loc )
private
If LOGICAL_LOC is non-NULL, use it to create a "logicalLocations" property
within LOCATION_OBJ (SARIF v2.1.0 section 3.28.4).   

References ggc_alloc(), and make_sarif_logical_location_object().

Referenced by make_location_object(), and make_location_object().

Field Documentation

◆ m_context

◆ m_cur_group_result

sarif_result* sarif_builder::m_cur_group_result
private

◆ m_cwe_id_set

hash_set<int_hash <int, 0, 1> > sarif_builder::m_cwe_id_set
private

◆ m_filenames

hash_set<const char *> sarif_builder::m_filenames
private

◆ m_formatted

bool sarif_builder::m_formatted
private

Referenced by flush_to_file().

◆ m_invocation_obj

sarif_invocation* sarif_builder::m_invocation_obj
private

Referenced by end_diagnostic(), and flush_to_file().

◆ m_results_array

json::array* sarif_builder::m_results_array
private

Referenced by end_diagnostic(), and flush_to_file().

◆ m_rule_id_set

hash_set<free_string_hash> sarif_builder::m_rule_id_set
private

Referenced by make_result_object().

◆ m_rules_arr

json::array* sarif_builder::m_rules_arr
private

◆ m_seen_any_relative_paths

bool sarif_builder::m_seen_any_relative_paths
private

◆ m_tabstop

int sarif_builder::m_tabstop
private

Referenced by get_sarif_column().


The documentation for this class was generated from the following file: