structural-checks.md

Structural Checks Reference

26 dependency-aware checks that run after file edits. These analyze the project graph to detect cross-file issues that single-file lint can't catch.

Tier 1 — Fast (sub-100ms, every edit)

Check	Config Key	Description
Export Surface	export_surface	Detects breaking changes to exported symbols (renamed, removed, type-changed)
Import Resolution	import_resolution	Validates all imports resolve to real files — catches typos and deleted modules
Duplicate Symbols	duplicate_symbols	Flags identical export names across files that could cause ambiguous imports
Co-Dependency Staleness	co_dependency_staleness	Warns when a file's dependencies were recently edited but this file wasn't updated
Dead Imports	dead_imports	Detects imports that are no longer used after an edit
Dead Exports	dead_exports	Detects exports with no importers in the project
Hallucinated Imports	hallucinated_imports	Catches imports of symbols that don't exist in the target module
Cross-Package Imports	cross_package_imports	Warns on imports that cross monorepo package boundaries incorrectly
Undefined Env Vars	undefined_env_vars	Flags process.env references not documented in .env.example
Sibling Awareness	sibling_awareness	Suggests related files that may need updates when editing a module
Stale Read Warning	stale_read_warning	Warns when reading a file that was modified earlier in the session but not re-read
Recently Failed	recently_failed	Warns when editing a file that had check failures earlier in the session
Redundant Re-read	redundant_reread	Detects reading a file that was already read and hasn't changed
Route Context	route_context	Adds HTTP route/endpoint context when editing handler files
Completion Tracking	completion_tracking	Tracks pending follow-up edits from export surface changes

Tier 2 — Medium (sub-1s, every edit)

Check	Config Key	Description
Import Cycles	import_cycles	Detects circular import chains that can cause runtime issues
New Import Cycle	new_import_cycle	Delta check: warns only on the specific edit that closes a new circular import chain (silent on cycles that already existed)
Interface Change Impact	interface_change_impact	Identifies files affected when an interface or type definition changes
Test Proximity	test_proximity	Suggests running related tests when editing source files
Blast Radius	blast_radius	Estimates how many files are affected by changes to a hub module
Layer Violations	layer_violations	Enforces architectural layering rules (e.g., UI must not import from DB layer)
Test First	test_first	Nudge agent to write/run tests before editing source files
Cross-File Switch Discriminant	cross_file_switch_discriminant	Flags the same switch discriminant (.kind/.type/.tag) appearing in multiple files — usually a polymorphism opportunity
Single-Implementation Interface	single_implementation_interface	Flags exported interfaces with exactly one implementor — possible premature abstraction

Tier 3 — Conditional (1-5s, only when needed)

Check	Config Key	Description
Smart TypeScript Check	smart_tsc	Runs tsc only on the edited file when export surface didn't change (avoids full project rebuild)
Impact Analysis	impact_analysis	Full dependency graph analysis showing breaking changes and affected downstream files