fix(extract): stop walking JSON Schema files as config manifests (#2255) - #4048

Problem

_is_config_json() decides whether a .json file is worth AST-walking. It matches by filename first, then falls back to a root-key probe:

_CONFIG_JSON_KEYS = frozenset({
    "dependencies", ..., "extends", "$ref", "$schema", "compilerOptions",
})

$schema belongs in that set — configs legitimately carry it. But it is also the defining marker of a JSON Schema, so every schema document satisfied the probe and was walked in full. That re-opens the keyword-node explosion #1224 closed for data JSON.

Measured impact from the report: one 160 KB contract contributed 362 nodes labelled with bare schema keywords (description ×113, type ×83, $ref ×53, required ×20, properties ×20, …) plus ~12 schema-only communities, which pollutes clustering, god-node analysis and GRAPH_REPORT.md — 13% of a 2,725-node graph.

A minimal reproduction of my own (a 20-line schema with $id + $defs) already yields 34 nodes / 34 edges, with description ×7 and type ×7 as graph nodes.

Implementation

Two changes, both ahead of the existing probe:

1. Drop $ref from the probe keys. A root-level $ref is a schema construct and never a config signal. Unambiguous — no real config has one.

2. Return False when the root object carries $schema plus a schema-definition marker ($defs, definitions, or $id). This is what separates "this file IS a schema" from "this config POINTS AT a schema": the latter points $schema at its own tool's schema (biomejs.dev, docs.renovatebot.com) and never carries these markers.

The root keys are now collected once into a set, so the schema check and the config probe read the file the same way instead of walking the root twice.

Why this is low-risk

The filename branches run before the probe, so biome.json / renovate.json / angular.json / package.json / tsconfig.json never depended on it. Only arbitrarily-named files did.

I built a control matrix and ran it before and after — every config shape keeps byte-identical node counts:

I deliberately used the structural markers rather than inspecting the $schema value for json-schema.org. The value check is tempting but unreliable (a custom meta-schema can be a local path) and it would make classification depend on URL substring matching — worse for the determinism invariant than spec-defined key names.

Documented limitation

A hand-written schema carrying $schema but no $defs / definitions / $id is still walked. Closing that needs a keyword-density heuristic, which risks skipping a real config whose keys happen to overlap schema vocabulary — the worse error, since it drops structure silently, exactly what #1224 was about.

Rather than guess, it is documented in the _is_config_json docstring and pinned by test_minimal_schema_without_defs_or_id_is_still_walked, so closing it later is a deliberate change with a test rather than an accident. Happy to attempt the heuristic if you'd prefer fuller coverage.

Also updated the now-inaccurate extract_json docstring, which still advertised $ref as a probe signal.

Verification

uv run pytest tests/test_json_schema_config.py -q    # 14 passed
uv run pytest tests/ -q                              # 28 failed, 6262 passed, 101 skipped
uv run ruff check .                                  # All checks passed!
uv run pyright                                       # 636 errors

• 5 of the 14 new tests fail on the pre-fix tree (confirmed by reverting json_config.py and re-running). The other 9 are deliberate: config-side guards against over-correcting, plus the documented-limit case.
• Baseline captured on a clean v0.9.75 checkout: 28 failed, 6248 passed, 101 skipped. The 28 failures are byte-identical between the two runs — diffed test-id-by-test-id, not compared by count. They are missing tree-sitter grammars for erlang/R/solidity/vbnet plus ollama retry tests. Passing delta is exactly +14, my new tests.
• pyright at parity: 636 before and after. (The count moved 635→636 between v0.9.74 and v0.9.75 upstream, not from this change — I measured the baseline on this exact commit.)

tests/test_json_schema_config.py is the first test module for json_config; it follows the existing inline-SRC convention from test_scala_self_type.py. Tests cover the schema side ($defs, legacy definitions, subdirectory placement, bare $ref, and that no keyword labels leak into the graph), the config side (all seven shapes above, including two configs that carry $schema themselves), the documented boundary, and determinism across repeated calls.

Notes

• Single concern, one extractor module. No config changes, no skillgen output, no CLI surface.
• A skipped schema returns the existing {"skipped": "data json (not a config/manifest)"} marker with zero nodes — the same AST pass explodes data .json into orphan key-nodes (CODE_EXTENSIONS includes .json) — 561 isolated nodes on a real repo #1224 treatment data JSON already gets. Whether the file still gets a file node is detect()'s concern, untouched here.
• CI will sit at action required until a maintainer approves the workflow run (expected for outside contributors).

🤖 Generated with Claude Code