Skip to content

Latest commit

 

History

History
77 lines (59 loc) · 3.77 KB

REPORT_FORMAT.md

File metadata and controls

77 lines (59 loc) · 3.77 KB
Raw

Report Format

The canonical use for the library results in an output report. This report is a zip archive with a custom file extension, containing multiple report files. These files are partitioned groups of discovered methods (the number per partition is determined by cloud service constraints). There are currently three types of files - "meta data", "methods", and "method uses".

Meta Data Report

The "meta data" report is located in the root of the report directory of the expanded report file, in the metaData.json file. This file contains the following elements:

  • hostName
    • The name of the host the analysis was performed on
  • analyzedDirectory
    • The local path of the directory analyzed
  • codeLocationName
    • Optional. A human-readable label for the project/directory analyzed

Methods Report

The "methods" report(s) are within the referenced-methods directory of the expanded report file. Each of these files is a JSON file, containing several elements:

  • methodIds[]
    • Array of identifiers for each unique method reference found in the report
  • methodIds[].signature
    • A unique, opaque ID referring to a specific discovered method, and is contained as an identifier within the other report formats for linking data together, described in the "ID Generation" section
  • methodIds[].methodOwner
    • A unique, opaque ID referring to the qualified class name which defines the discovered method
  • methodIds[].methodName
    • A unique, opaque ID referring to the name of the discovered method
  • methodIds[].inputs
    • A unique, opaque ID referring to the input types of the discovered method
  • methodIds[].outputs
    • A unique, opaque ID referring to the output type of the discovered method

Method Uses Report

The "method uses" report(s) are within the referenced-method-uses directory of the expanded report file. Each of these files is a JSON file, containing several elements:

  • methodUses[]
    • Array of all references described by this report
  • methodUses[].method
    • Description of the method reference found
  • methodUses[].method.id
    • Opaque identifier of the referenced method - links to values in the "methods" report
  • methodUses[].method.methodOwner
    • Qualifier class name which defines the referenced method
  • methodUses[].method.methodName
    • Simple name of the referenced method
  • methodUses[].method.inputs
    • Ordered list of zero or more fully-qualified class names used as input parameters of the method
  • methodUses[].method.output
    • Qualified class name of the output of the method, or void if defined with a void return type
  • methodUses[].uses[]
    • Array of recording documenting where in the project the method is used
  • methodUses[].uses[].qualifiedMethodName
    • The qualified class and method name the reference is located in
  • methodUses[].uses[].lineNumber
    • Optional - the line number the reference is made on within the source file

Broken Files Report

The "broken files" report(s) are within the "broken-files" directory of the expanded report file. Each of these files is a JSON file, containing several elements:

  • brokenFiles[]
    • Array of all broken files described by this report
  • brokenFiles[].path
    • Path of the file which failed to parse
  • brokenFiles[].error
    • Optional. Short text string describing the error which prevented parsing

ID Generation

The methodology for ID generation is determined by a consuming cloud service. This identifier should be considered opaque, and not depended on to take a particular form by other consumers - the only property it is expected to consistently have is a unique value per referenced method.

Currently, the ID is generated by formatting the referenced method into a string like so:

<method owner>.<method name>(<CSV of method inputs>):<method output>

which is then hashed with SHA-256, and Base64 encoded