ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity

refactor(scripts): move 7 code_path_audit files from src/ to scripts/code_path_audit/

Browse Source 
The 7 code_path_audit*.py files (2604 lines total) are pure static
analysis tools. They do AST traversal of src/, no intrusive profiling,
no runtime markers. They were inlaid with src/ but only import:
- src.result_types (the Result[T] convention type)
- each other (the 6 siblings)

After the move:
- src/ is now pure application code; line-count audit metrics are clean
- scripts/code_path_audit/ is a new namespace-isolated subdir per
  AGENTS.md 'scripts are namespace-isolated by directory' rule

TIER-3 READ AGENTS.md + conductor/workflow.md + conductor/edit_workflow.md
+ conductor/code_styleguides/code_path_audit.md + the 7 files before
this commit.

Changes:
- 7 files moved: src/code_path_audit*.py -> scripts/code_path_audit/
- 7 files updated: internal imports rom src.code_path_audit_X ->
  rom code_path_audit_X (siblings in same subdir)
- 7 files updated: add sys.path.insert(0, str(Path(__file__).resolve().parents[2] / 'src'))
  to find src.result_types when run standalone
- 5 test files updated: rom src.code_path_audit -> rom code_path_audit
  + sys.path setup to find the new subdir
- 6 throwaway scripts in scripts/tier2/artifacts/ updated: import path
  + sys.path setup (parents[3] / 'src' + parents[3] / 'scripts' / 'code_path_audit')
- 2 styleguide/spec references updated: conductor/code_styleguides/code_path_audit.md
  + conductor/tracks/code_path_audit_20260607/spec_v2.md
- 1 meta-audit docstring updated: scripts/audit_code_path_audit_coverage.py
- 1 type registry entry deleted: docs/type_registry/src_code_path_audit.md
  (the type is no longer in src/)
- 1 type registry index updated: docs/type_registry/index.md (22 files, was 23)

Verification:
- 7/7 audit gates pass --strict (weak_types 102<=112, type_registry 22 files,
  main_thread_imports OK, no_models_config_io OK, code_path_audit_coverage 0
  violations, exception_handling 0 violations, optional_in_3_files 0 violations)
- 6/6 test files pass: test_code_path_audit, test_code_path_audit_integration,
  test_code_path_audit_phase78, test_code_path_audit_phase89,
  test_code_path_audit_ssdl_behavioral, test_metadata_nil_sentinel
- src/ line count: 29997 lines (down from 32621 = -2624 lines)
- scripts/code_path_audit/ line count: 2620 lines
This commit is contained in:
ed
2026-06-25 09:29:24 -04:00
parent f7a2917938
commit 5ac0618a33
24 changed files with 110 additions and 257 deletions
Download Patch File Download Diff File Expand all files Collapse all files
conductor/tracks/code_path_audit_20260607/spec_v2.md
+10 -10
View File
@@ -7,7 +7,7 @@
**Folder:** `conductor/tracks/code_path_audit_20260607/`
**Files:** `spec.md` (v1; preserved), `spec_v2.md` (this file), `plan.md` (v1; preserved), `plan_v2.md` (after this spec is approved)
> **v2 revision note (2026-06-22).** The v1 spec.md (approved 2026-06-07; revised 2026-06-08) was never executed (no `state.toml`, no `metadata.json`, no `src/code_path_audit.py` in the working tree). The 14-day gap saw 4 foundational tracks ship (`qwen_llama_grok_integration_20260606`, `data_oriented_error_handling_20260606`, `data_structure_strengthening_20260606`, `mcp_architecture_refactor_20260606`), the entire 5-sub-track `result_migration` campaign ship (2026-06-16 through 2026-06-21; 100% complete), and the `nagent_review` corpus grow from v1 to v3.1. v2 re-scopes the audit from "expensive operations per action" to "data pipelines per aggregate" — the v1 framing was correct at the time (the 4 tracks were future) but is now stale. v2 also cross-validates the `data_structure_strengthening_20260606` + `data_oriented_error_handling_20260606` deductions directly, which v1 could not (those tracks didn't exist on 2026-06-07). See §"Why v2" below.
> **v2 revision note (2026-06-22).** The v1 spec.md (approved 2026-06-07; revised 2026-06-08) was never executed (no `state.toml`, no `metadata.json`, no `scripts/code_path_audit/code_path_audit.py` in the working tree). The 14-day gap saw 4 foundational tracks ship (`qwen_llama_grok_integration_20260606`, `data_oriented_error_handling_20260606`, `data_structure_strengthening_20260606`, `mcp_architecture_refactor_20260606`), the entire 5-sub-track `result_migration` campaign ship (2026-06-16 through 2026-06-21; 100% complete), and the `nagent_review` corpus grow from v1 to v3.1. v2 re-scopes the audit from "expensive operations per action" to "data pipelines per aggregate" — the v1 framing was correct at the time (the 4 tracks were future) but is now stale. v2 also cross-validates the `data_structure_strengthening_20260606` + `data_oriented_error_handling_20260606` deductions directly, which v1 could not (those tracks didn't exist on 2026-06-07). See §"Why v2" below.
---
@@ -31,7 +31,7 @@ The user's framing (2026-06-22):
## Overview
Build `src/code_path_audit.py` v2 — a data-oriented static-analysis tool that audits the data pipelines in `src/` and produces per-data-aggregate profiles. The output (custom postfix `.dsl` data + markdown + prefix tree text, organized per-aggregate) is the artifact that informs per-aggregate refactor decisions. The actual code changes are follow-up tracks (the 3 high-priority candidates from `decomposition_matrix.md`).
Build `scripts/code_path_audit/code_path_audit.py` v2 — a data-oriented static-analysis tool that audits the data pipelines in `src/` and produces per-data-aggregate profiles. The output (custom postfix `.dsl` data + markdown + prefix tree text, organized per-aggregate) is the artifact that informs per-aggregate refactor decisions. The actual code changes are follow-up tracks (the 3 high-priority candidates from `decomposition_matrix.md`).
The v2 audit's primary value is **cross-validation**: it consumes the JSON outputs of the 5 existing audit scripts and synthesizes them with the per-aggregate producer/consumer call graph. The result is a per-aggregate report that says "this aggregate has 12 weak-type sites (cross-checks `data_structure_strengthening`), 5 exception-handling sites (cross-checks `data_oriented_error_handling`), and 1 high-priority optimization candidate (decomposition direction: componentize)." The user reads one report per aggregate, not one per action.
@@ -51,7 +51,7 @@ The v2 audit is **read-only** on `src/` (the only new file is the tool itself +
3. **`scripts/audit_exception_handling.py`** — the exception-handling CI gate (per `error_handling.md`). v2 consumes its JSON output. v2 does not modify this script.
4. **`scripts/audit_optional_in_3_files.py`** — the `Optional[T]` ban CI gate for the 3 refactored files (`mcp_client.py`, `ai_client.py`, `rag_engine.py`). v2 extends this script by 1 line (add `src/code_path_audit.py` to the baseline list); the convention is the same.
4. **`scripts/audit_optional_in_3_files.py`** — the `Optional[T]` ban CI gate for the 3 refactored files (`mcp_client.py`, `ai_client.py`, `rag_engine.py`). v2 extends this script by 1 line (add `scripts/code_path_audit/code_path_audit.py` to the baseline list); the convention is the same.
5. **`scripts/audit_no_models_config_io.py`** — the config-I/O ownership CI gate (per `conductor/code_styleguides/config_state_owner.md`). v2 consumes its JSON output. v2 does not modify this script.
@@ -108,11 +108,11 @@ The v2 audit is **read-only** on `src/` (the only new file is the tool itself +
- A cross-audit integration layer that consumes the 6 input JSON streams and produces per-aggregate `cross_audit_findings` + 2 coverage metrics (`result_coverage`, `type_alias_coverage`).
- The v2 postfix DSL (14 new tagged words + the v1's 7 preserved). The flat-section format (streamable, tag-scannable).
- Output: per-aggregate `.dsl` + `.md` + `.tree` files + 4 top-level rollup files (summary.md, cross_audit_summary.md, decomposition_matrix.md, candidates.md).
- A CLI (`python -m src.code_path_audit --all --date <date>`) and an MCP tool (`code_path_audit_v2(action=None) -> dict`).
- A CLI (`python scripts/code_path_audit/code_path_audit.py --all --date <date>`) and an MCP tool (`code_path_audit_v2(action=None) -> dict`).
- A meta-audit (`scripts/audit_code_path_audit_coverage.py`) that validates the v2 audit's output schema.
- The actual audit run on the 13 aggregates, with the report committed to `docs/reports/code_path_audit/<date>/`.
- A new styleguide (`conductor/code_styleguides/code_path_audit.md`) documenting the v2 audit's contract.
- A 1-line extension to `scripts/audit_optional_in_3_files.py` to include `src/code_path_audit.py` in the baseline.
- A 1-line extension to `scripts/audit_optional_in_3_files.py` to include `scripts/code_path_audit/code_path_audit.py` in the baseline.
---
@@ -130,7 +130,7 @@ The v2 audit is **read-only** on `src/` (the only new file is the tool itself +
## Functional Requirements
The 11 public functions in `src/code_path_audit.py`. All return `Result[T]` per the `error_handling.md` hard rule (or return a deterministic `T` when no runtime failure is possible).
The 11 public functions in `scripts/code_path_audit/code_path_audit.py`. All return `Result[T]` per the `error_handling.md` hard rule (or return a deterministic `T` when no runtime failure is possible).
| # | Function | Returns | Failure mode |
|---|---|---|---|
@@ -146,7 +146,7 @@ The 11 public functions in `src/code_path_audit.py`. All return `Result[T]` per
| 10 | `to_markdown(profile)` | `str` | n/a (deterministic) |
| 11 | `to_tree(profile)` | `str` | n/a (deterministic) |
Plus the CLI (`python -m src.code_path_audit ...`) and the MCP tool (`code_path_audit_v2`).
Plus the CLI (`python scripts/code_path_audit/code_path_audit.py ...`) and the MCP tool (`code_path_audit_v2`).
---
@@ -158,10 +158,10 @@ Plus the CLI (`python -m src.code_path_audit ...`) and the MCP tool (`code_path_
- **Type hints required** for all public functions.
- **No comments in Python source** (documentation lives in `/docs`).
- **`Result[T]` return types** for all functions that can fail at runtime (per the `error_handling.md` hard rule). The new file is held to the same standard as the 3 refactored files.
- **`Optional[T]` return types are FORBIDDEN** in `src/code_path_audit.py`. Verified by the extended `scripts/audit_optional_in_3_files.py` (1-line extension).
- **`Optional[T]` return types are FORBIDDEN** in `scripts/code_path_audit/code_path_audit.py`. Verified by the extended `scripts/audit_optional_in_3_files.py` (1-line extension).
- **Per-task commits** (1 task = 1 commit). Per `conductor/workflow.md` TDD protocol.
- **Per-task git notes** (each commit gets a `git notes add -m "..."` summary).
- **Coverage target: >80%** for `src/code_path_audit.py`. The 4 audit scripts (`audit_exception_handling.py --strict`, `audit_weak_types.py --strict`, `audit_main_thread_imports.py`, `audit_no_models_config_io.py`) are the verification gates.
- **Coverage target: >80%** for `scripts/code_path_audit/code_path_audit.py`. The 4 audit scripts (`audit_exception_handling.py --strict`, `audit_weak_types.py --strict`, `audit_main_thread_imports.py`, `audit_no_models_config_io.py`) are the verification gates.
- **The audit's runtime is bounded.** The full audit run against the real `src/` (65 files) completes in <60s on a developer machine. The unit + integration tests complete in <30s. The live_gui E2E tests are opt-in.
---
@@ -481,7 +481,7 @@ uv run python scripts/audit_no_models_config_io.py
### 9.4 End-of-track verification
```bash
uv run python -m src.code_path_audit --all --date 2026-06-22
uv run python scripts/code_path_audit/code_path_audit.py --all --date 2026-06-22
uv run python scripts/audit_exception_handling.py --strict
uv run python scripts/audit_weak_types.py --strict
uv run python scripts/audit_main_thread_imports.py