symbol_diff.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/sourcegraph-community/precise-impact-analysis/symbol_diff.schema.json",
  "title": "Symbol Diff",
  "description": "Output of precise-impact-analysis: file-level and symbol-level diffs between two revisions of a repository, with cross-repository impact data.",
  "type": "object",
  "required": ["schema_version", "repository", "old_ref", "new_ref", "file_diffs", "symbol_diffs"],
  "additionalProperties": false,
  "properties": {
    "schema_version": {
      "type": "string",
      "description": "Schema version identifier.",
      "const": "1"
    },
    "repository": {
      "type": "string",
      "description": "Fully-qualified repository name (e.g. \"github.com/owner/repo\")."
    },
    "old_ref": {
      "type": "string",
      "description": "Git ref (tag, branch, or commit) for the old revision."
    },
    "new_ref": {
      "type": "string",
      "description": "Git ref (tag, branch, or commit) for the new revision."
    },
    "file_diffs": {
      "type": "array",
      "description": "List of file-level changes between the two revisions.",
      "items": { "$ref": "#/$defs/FileDiff" }
    },
    "symbol_diffs": {
      "type": "array",
      "description": "List of symbol-level changes with optional cross-repository impact.",
      "items": { "$ref": "#/$defs/SymbolDiff" }
    }
  },
  "$defs": {
    "FileDiff": {
      "type": "object",
      "description": "A single file-level change.",
      "required": ["old_path", "new_path", "change_type"],
      "additionalProperties": false,
      "properties": {
        "old_path": {
          "type": ["string", "null"],
          "description": "Path in the old revision. Null for ADDED files."
        },
        "new_path": {
          "type": ["string", "null"],
          "description": "Path in the new revision. Null for DELETED files."
        },
        "change_type": {
          "type": "string",
          "enum": ["ADDED", "MODIFIED", "DELETED", "RENAMED"],
          "description": "Kind of file change."
        }
      }
    },
    "SymbolDiff": {
      "type": "object",
      "description": "A single symbol-level change with optional impact data.",
      "required": ["change_type", "reason", "old_symbol", "new_symbol", "impact"],
      "additionalProperties": false,
      "properties": {
        "change_type": {
          "type": "string",
          "enum": ["REMOVED", "CHANGED"],
          "description": "Kind of symbol change."
        },
        "reason": {
          "type": "string",
          "description": "Human-readable reason for the change (e.g. \"missing_in_new\")."
        },
        "old_symbol": {
          "$ref": "#/$defs/SymbolDefinition",
          "description": "Symbol definition in the old revision."
        },
        "new_symbol": {
          "oneOf": [
            { "$ref": "#/$defs/SymbolDefinition" },
            { "type": "null" }
          ],
          "description": "Symbol definition in the new revision, or null if removed."
        },
        "impact": {
          "oneOf": [
            { "$ref": "#/$defs/SymbolImpact" },
            { "type": "null" }
          ],
          "description": "Cross-repository usage impact, or null if not computed."
        }
      }
    },
    "SymbolDefinition": {
      "type": "object",
      "description": "Location and identity of a symbol in a specific revision.",
      "required": ["scip_symbol", "path", "range"],
      "additionalProperties": false,
      "properties": {
        "scip_symbol": {
          "type": "string",
          "description": "SCIP symbol identifier."
        },
        "path": {
          "type": "string",
          "description": "File path within the repository."
        },
        "range": {
          "$ref": "#/$defs/Range",
          "description": "Source range of the symbol name."
        }
      }
    },
    "SymbolImpact": {
      "type": "object",
      "description": "Cross-repository impact summary for a changed or removed symbol.",
      "required": ["total_usages", "repositories_affected", "usage_samples"],
      "additionalProperties": false,
      "properties": {
        "total_usages": {
          "type": "integer",
          "minimum": 0,
          "description": "Total number of usages found across all repositories."
        },
        "repositories_affected": {
          "type": "array",
          "items": { "type": "string" },
          "description": "List of repository names that reference this symbol."
        },
        "usage_samples": {
          "type": "array",
          "items": { "$ref": "#/$defs/SymbolUsage" },
          "description": "Sample usages of this symbol from other repositories."
        }
      }
    },
    "SymbolUsage": {
      "type": "object",
      "description": "A single usage of a symbol in another repository.",
      "required": ["repository", "revision", "path", "range"],
      "additionalProperties": false,
      "properties": {
        "repository": {
          "type": "string",
          "description": "Repository containing this usage."
        },
        "revision": {
          "type": ["string", "null"],
          "description": "Commit SHA of the revision, or null if unknown."
        },
        "path": {
          "type": "string",
          "description": "File path within the repository."
        },
        "range": {
          "$ref": "#/$defs/Range",
          "description": "Source range of the usage."
        }
      }
    },
    "Range": {
      "type": "object",
      "description": "A source range defined by start and end positions.",
      "required": ["start", "end"],
      "additionalProperties": false,
      "properties": {
        "start": { "$ref": "#/$defs/Position" },
        "end": { "$ref": "#/$defs/Position" }
      }
    },
    "Position": {
      "type": "object",
      "description": "A zero-indexed line/character position in a source file.",
      "required": ["line", "character"],
      "additionalProperties": false,
      "properties": {
        "line": {
          "type": "integer",
          "minimum": 0,
          "description": "Zero-indexed line number."
        },
        "character": {
          "type": "integer",
          "minimum": 0,
          "description": "Zero-indexed character offset within the line."
        }
      }
    }
  }
}