Precise Impact Analysis

This example uses Sourcegraph's precise code intelligence to identify breaking changes that could affect symbol (function/method/enum) consumers.

Warning

This example uses Sourcegraph's debug API to access precise code intel data.

The GraphQL API is intended primarily for debugging use cases. It does not have backwards-compatibility guarantees, and may not remain stable across Sourcegraph releases.

For more information, please refer to the Sourcegraph API page.

Prerequisites: Precise Indexing

This tool relies entirely on SCIP indexes — not search heuristics. Both sides of the analysis must be indexed:

• Symbol producers (the library under analysis) must have a completed precise index uploaded for each release tag or commit being compared (old_ref and new_ref).
  • If both references are not indexed, the tool will fail to start.
• Symbol consumers (downstream repositories) must also have precise indexes so that cross-repository reference lookups return accurate results.

Without precise indexes on both sides, the tool cannot discover symbol definitions or resolve cross-repo usages.

How It Works

File Diffs via RepositoryComparisonDiffs

The RepositoryComparisonDiffs GraphQL query compares the two revisions and returns every changed file. Each diff is classified as added, deleted, modified, or renamed, then filtered by file extension so only relevant source files are carried forward.

Symbol Collection via codeGraphData → occurrences

Changed files are split into old-side and new-side path sets based on their diff classification. For each side, the tool pages through the codeGraphData → occurrences API at the corresponding revision, collecting every SCIP occurrence with a DEFINITION or FORWARD_DEFINITION role. Local symbols are discarded and duplicates are removed.

Symbol Diffing from SCIP Data

Old and new definitions are compared using two normalized identities derived from the SCIP symbol string:

• Exact id: the symbol string with its version token stripped. If an old symbol's exact id appears in the new set it is unchanged.
• Stem id: the exact id with parameter and type-parameter signatures erased. A unique stem match marks the symbol as changed.
  • With zero or multiple matches, it is marked as removed.

For every removed or changed symbol, the tool queries usagesForSymbol for PRECISE cross-repo references, excluding the library's own repository, and reports the affected downstream repositories and usage locations.

The final output is written as JSON to --output (default symbol_diff.json).

CLI

precise-impact-analyis reads Sourcegraph auth/config from environment:

1. SRC_ENDPOINT (for example https://sourcegraph.example.com)
2. SRC_ACCESS_TOKEN

The GraphQL endpoint is derived as SRC_ENDPOINT/.api/graphql.

SRC_ENDPOINT=https://sourcegraph.example.com \
SRC_ACCESS_TOKEN=... \
uv run precise-impact-analyis \
  --repo github.com/example/library \
  --old-ref v1.0.0 \
  --new-ref v1.1.0 \
  --include-changed \
  --output impact_report.json