Skip to content

design.md

Latest commit

 

History

History
81 lines (57 loc) · 2.93 KB

design.md

File metadata and controls

81 lines (57 loc) · 2.93 KB
Raw
summary Full code+docs audit harness; produced the 57-finding report.

Code & Docs Audit — Design

Date: 2026-06-12 Status: Approved

Goal

Full audit of the modern-di codebase and documentation, producing a severity-ranked findings report. No fixes are applied during the audit; the user reviews the report and selects which findings to fix, and that selection becomes the implementation plan.

Scope

All four improvement lenses are in scope:

  1. Bugs + doc/code drift — real defects, unhandled edge cases, error-message problems, and docs that contradict or lag the code.
  2. Code quality & internals — dead code, performance issues, type-hint gaps, refactoring opportunities with no public-API change.
  3. API design & DX — public API ergonomics, confusing naming, missing features. Flagged separately because findings here may imply breaking changes.
  4. Docs completeness — undocumented behaviors, gaps in recipes/troubleshooting, weak examples.

Audit surface: modern_di/ (all source files), tests/, docs/ (all sections), README.md, benchmarks/.

Method: thorough single-pass — every source file, test, and doc page is read directly and cross-checked, without multi-agent fan-out.

Process

1. Baseline

Run just lint-ci and just test before reading anything, so every finding is distinguishable from pre-existing breakage. If the baseline fails, that failure is finding #1 and the audit proceeds against the broken baseline rather than fixing it silently.

2. Code audit

Read every file in modern_di/ with four lenses:

  • Correctness: edge cases in types_parser (generics, Optional/Union, forward refs, inheritance), scope-chain walking in Container.find_container, cache/override interplay, finalizer ordering, thread/async safety of the four registries, cycle detection (validate).
  • Failure behavior: error-message quality, exception types, what happens on misuse.
  • Internals: dead code, perf, type-hint gaps, refactor opportunities.
  • Public API: ergonomics and naming (DX category).

3. Test audit

Identify coverage gaps against the behaviors enumerated in step 2, and tests that pass without asserting what their name claims.

4. Docs cross-check

  • Every code example in docs/ and README.md verified against the actual API; executed where self-contained.
  • Every behavioral claim traced to source.
  • Inverse check: behaviors present in code with no docs coverage (completeness lens).

5. Report

Single document at planning/audits/2026-06-12-code-docs-audit-report.md. Findings grouped by category — Bug / Drift / Quality / DX / Docs gap — each with:

  • severity (high / medium / low),
  • file:line evidence,
  • a proposed fix.

Deliverable & follow-up

The report is the deliverable of this phase. The user marks which findings to fix; the selected set is handed to the planning phase to produce the implementation plan.