| name | structure-audit |
| version | 0.8.0 |
| description | Deterministic, advisory import-structure audit for Python. Builds the internal import graph (stdlib ast), enumerates import cycles (Tarjan SCC), and flags god-modules by fan-in/fan-out, emitting RESTRUCTURE findings to the shared code-health finding schema. Never mutates source.
|
structure-audit
Overview
Reports import cycles, god-modules, and optional layering violations as advisory
RESTRUCTURE findings.
Quick Start
python3 scripts/structure_audit.py \
--root /path/to/repo \
--source-prefix src/pkg/ \
--out-dir /tmp/structure
Output
structure_findings.json — sorted findings (shared schema).structure_report.md — summary.
Exit Codes
0 clean, 1 advisory findings present, 2 config error.
Config
--source-prefix is repeatable. --config JSON keys: max_fan_out,
max_fan_in, layers (ordered top-to-bottom prefix list). See
skills/structure-audit/references/rubric.md. Findings are deterministic.
Limits
- Advisory only — emits RESTRUCTURE findings and never moves code or mutates
source.
- Python only: the import graph is built from Python source via the stdlib
ast module.
- Static top-level imports only: dynamic imports (
importlib, __import__,
conditional imports) are not modeled.
- Internal imports only: only modules under the given
--source-prefix form
the graph; third-party and stdlib edges are out of scope.
- God-module flags are threshold-based on fan-in/fan-out and need human
judgment.
- Deterministic and offline; no network access.
