Providence Analytics: QueryResult

When an Analyzer has run, it returns a QueryResult. This is a json object that contains all meta info (mainly configuration parameters) and the query output. A QueryResult always contains the analysis of one project (a target project). Optionally, it can contain a reference project as well.

Anatomy

A QueryResult starts with a meta section, followed by the actual results

Meta

The meta section lists all configuration options the analyzer was run with. Here, you see an example of a find-imports QueryResult:

  "meta": {
    "searchType": "ast-analyzer",
    "analyzerMeta": {
      "name": "find-imports",
      "requiredAst": "babel",
      "identifier": "importing-target-project_0.0.2-target-mock__1970011674",
      "targetProject": {
        "name": "importing-target-project",
        "commitHash": "3e5014d6ecdff1fc71138cdb29aaf7bf367588f5",
        "version": "0.0.2-target-mock"
      },
      "configuration": {
        "keepInternalSources": false
      }
    }
  },

Output

The output is usually more specifically tied to the Analyzer. What most regular Analyzers (not being MatchAnalyzers that require a referenceProjectPath) have in common, is that their results are being shown per "entry" (an entry corresponds with an AST generated by Babel, which in turn corresponds to a file found in a target or reference project).

Below an example is shown of find-imports QueryOutput:

  "queryOutput": [
    {
      "project": {
        "name": "importing-target-project",
        "mainEntry": "./target-src/match-imports/root-level-imports.js",
        "version": "0.0.2-target-mock",
        "commitHash": "3e5014d6ecdff1fc71138cdb29aaf7bf367588f5"
      },
      "entries": [
        {
          "file": "./target-src/find-imports/all-notations.js",
          "result": [
            {
              "importSpecifiers": [
                "[file]"
              ],
              "source": "imported/source",
              "normalizedSource": "imported/source",
              "fullSource": "imported/source"
            },
            {
              "importSpecifiers": [
                "[default]"
              ],
              "source": "imported/source-a",
              "normalizedSource": "imported/source-a",
              "fullSource": "imported/source-a"
            },
            ...

MatchAnalyzers usually do post processing on the entries. The output below (for the match-imports Analyzer) shows an ordering by matched specifier.

 "queryOutput": [
    {
      "exportSpecifier": {
        "name": "[default]",
        "project": "exporting-ref-project",
        "filePath": "./index.js",
        "id": "[default]::./index.js::exporting-ref-project"
      },
      "matchesPerProject": [
        {
          "project": "importing-target-project",
          "files": [
            "./target-src/match-imports/root-level-imports.js",
            "./target-src/match-subclasses/internalProxy.js"
          ]
        }
      ]
    },
    ...

Due to some legacy decisions, the QueryOutput allows for multiple target- and reference projects. Aggregation of data now takes place in the dashboard. QueryOutputs always contain one or a combination of two projects. This means that the QueryOutput structure could be simplified in the future.

Environment agnosticism

The output files stored in the file system always need to be machine independent: this means that all machine specific information, like a complete filepath, needs to be removed from a QueryOutput (paths relative from project root are still allowed). In that way, the caching mechanism (based on hash comparisons) as described in Analyzer is guaranteed to work across different machines.