@yottameta/yotta-code-quality 0.3.0

package/references/examples.md

@@ -0,0 +1,59 @@
+# Examples — tone and score calibration
+
+Use these to keep reviews consistent. Do **not** copy findings into real reports unless the code matches.
+
+---
+
+## Example A — Good Warning (R2)
+
+**Context:** PR renames a domain field and also “cleans up” unrelated formatting in 12 files.
+
+```
+### 🟡 Warning
+**Change Propagation — Unrelated drive-by edits**
+Symptom: Diff touches 12 files; only 2 mention the renamed field `expires_at`; the rest are import reorder / whitespace.
+Source: Fowler — Refactoring — Shotgun Surgery / Divergent Change
+Consequence: Reviewers cannot see the real contract change; regressions hide in noise; blame history is polluted.
+Remedy: Split into (1) rename + call sites, (2) optional format-only PR — or revert non-functional hunks.
+```
+
+**Score impact (balanced):** −5.
+
+---
+
+## Example B — Over-flag to avoid (R1)
+
+**Bad:** Mark a 80-line React component Critical solely because `function > 20 lines`, when it is mostly JSX layout with one `map`.
+
+**Better:** No finding, or Suggestion: extract presentational subcomponents *when editing nearby* — Source Editorial / Code Complete heuristics as hints.
+
+---
+
+## Example C — Editorial Critical (R7)
+
+```
+### 🔴 Critical
+**Release / Supply-chain Safety — Plaintext cloud credentials in publish script**
+Symptom: `publish-*.ps1` embeds AccessKeyId/Secret as string literals committed to the repo.
+Source: Editorial — Release Safety
+Consequence: Anyone with repo (or old clone) access can abuse the cloud account; rotation is urgent.
+Remedy: Remove secrets from VCS history of the file; load from env / local config ignored by git; rotate keys in the provider console now.
+```
+
+**Score impact (balanced):** −15.
+
+---
+
+## Example D — Health Score arithmetic
+
+Findings: 1 Critical, 2 Warning, 1 Suggestion; `strictness: balanced`.  
+`100 − 15 − 5 − 5 − 1 = 74` → **Health Score: 74/100**.
+
+Disclaimer in report: per-run deduction index, not “the project is 74% healthy.”
+
+---
+
+## Example E — Quick mode depth
+
+User pastes a 30-line function. **Do not** load all of `source-coverage.md`.  
+Use SKILL cheat-sheet; open `decay-risks.md` only if you are about to emit Critical.

package/references/hooks.json

@@ -0,0 +1,10 @@
+{
+  "comment": "PreToolUse safety hooks for yotta-code-quality. Blocks obviously dangerous commands before they run. Compatible with Claude Code / Codex hook schema (PreToolUse on Bash). Adapt the matcher to your agent's hook format if needed.",
+  "hooks": [
+    {
+      "matcher": "Bash",
+      "type": "PreToolUse",
+      "command": "node -e \"const c=process.env.BASH_COMMAND||(process.argv[2]||'');const deny=[/rm\\s+-rf?\\s+\\//,/rm\\s+-rf?\\s+[A-Za-z]:\\\\?\\\\?/,/git\\s+push\\s+--force/,/git\\s+push\\s+-f\\b/,/git\\s+reset\\s+--hard/,/git\\s+clean\\s+-[a-z]*[fdx]/,/mkfs/,/:\\(\\)\\s*\\{\\s*:\\|:\\|/,/dd\\s+if=/,/chmod\\s+-R\\s+777\\s+\\//];if(deny.some(r=>r.test(c))){console.error('[yotta-code-quality] BLOCKED dangerous command by policy: '+c);process.exit(1);}process.exit(0);\""
+    }
+  ]
+}

package/references/pr-review-guide.md

@@ -0,0 +1,93 @@
+# PR Review Guide — Mode 1
+
+**Purpose:** Analyze a code diff or specific files for decay risks directly visible in the changed
+code. Every finding must follow the Iron Law: Symptom → Source → Consequence → Remedy.
+
+## Before You Start
+- **Auto-generated files:** If the diff contains generated files (protobuf stubs, OpenAPI clients,
+  ORM migrations, lock files, minified bundles), skip them entirely. Note which were skipped and why.
+- **Scope calibration:** Adjust analysis depth by PR size before starting.
+
+| PR Size | Approach |
+|---------|----------|
+| < 50 lines | Steps 1–3 only; Step 6a only if imports changed; Step 6b if any class/method/variable was renamed or introduced |
+| 50–300 lines | Full process, all steps |
+| > 300 lines | Full process; note in Scope that review is sampled — cover highest-risk areas, not every file |
+
+For PRs > 500 lines: flag in the Summary that a PR this size is itself a Change Propagation signal.
+
+## Analysis Process (work through in order, do not skip)
+
+### Step 1: Understand the scope
+- What is the stated purpose of this change? Which files were modified?
+- Flag immediately if the PR changes > 10 unrelated files → 🟡 Warning: Change Propagation.
+
+### Step 2: Scan for Change Propagation (R2) — first
+- Does this change touch modules with no conceptual connection to the stated purpose?
+- Does any modified class change for > 1 business reason?
+- Does any method use more data from another class than its own?
+- If no cross-module changes beyond what the feature requires → skip, no finding.
+
+### Step 3: Scan for Cognitive Overload (R1)
+- New/modified functions > 20 lines? Nesting > 3? > 4 params? Magic numbers? Unreadable names?
+- Train-wreck chains (3+ calls chained)?
+
+### Step 4: Scan for Knowledge Duplication (R3)
+- Does this change introduce logic that already exists elsewhere?
+- A new name for a concept that already has a name?
+- A class added to a hierarchy that has a parallel in another module?
+
+### Step 5: Scan for Accidental Complexity (R4)
+- Abstraction with only one concrete use?
+- A class that only wraps/delegates?
+- Config options or extension points serving no current requirement?
+
+### Step 6a: Scan for Dependency Disorder (R5)
+- New imports from high-level module to low-level one (domain service imports DB driver/HTTP client)?
+- New imports introducing a cycle between modules?
+- An interface forcing callers to depend on methods they don't use?
+- If no new imports/structural changes → skip, no finding.
+
+### Step 6b: Scan for Domain Model Distortion (R6)
+- New class/variable names match the business language?
+- A new class holding only data with no behavior where behavior was expected?
+- Logic that belongs to the domain placed in a service/utility layer?
+
+## Severity Calibration
+Apply the Iron Law format from `references/common.md`. Use `references/decay-risks.md` severity
+guides as primary reference. Boundary tiebreaker:
+- 🔴 Critical — actively breaking velocity or creating production risk *today*.
+- 🟡 Warning — will if left unaddressed through the next few features.
+- 🟢 Suggestion — worth fixing when nearby, not urgent.
+If > 5 findings, add a one-line "Recommended fix order" at the end of Findings.
+
+## Step 7: Quick Test Check (run last; three signals only)
+Skip entirely if the diff contains only generated files, config, or docs with no production logic.
+
+**Signal 1: Do tests exist for the changed behavior?**
+- Diff modifies production code but no corresponding test changes included → 🟡 Warning: Coverage Illusion (Feathers — Working Effectively with Legacy Code, Ch. 1).
+- Pure refactor with existing tests covering behavior → no finding.
+
+**Signal 2: Quick Mock Abuse sniff** (only if diff includes test changes)
+- Mock setup obviously longer than test logic? Primary assertions `expect(mock).toHaveBeenCalledWith(...)` with no behavior verification? Production methods added only for tests?
+- If yes → 🟡 Warning: Mock Abuse (Osherove — The Art of Unit Testing).
+
+**Signal 3: Quick Test Obscurity sniff** (only if diff includes test changes)
+- Test names express scenario and expected outcome? Assertions have message strings?
+- If vague/no messages → 🟢 Suggestion: Test Obscurity (Meszaros — xUnit Test Patterns, Assertion Roulette p.224).
+
+**Output rule:** If all three signals clean → no Test findings, proceed to report. If findings exist →
+add them in Iron Law format, labeled with the test risk name. Note in Summary: "Consider a full
+test-quality review for systemic test problems."
+
+## Step 8 (optional): Release / first-paint skim
+
+When the user asked for a ship gate, or the diff touches updater, CSP, signing, publish scripts,
+DevTools features, splash/loading, or license/status labels:
+
+- Skim `editorial-extensions.md` (R7, UX1).
+- Do not expand into a full Architecture audit unless asked.
+
+## Output
+Use the standard Report Template from `references/common.md`.
+Mode: PR Review. Scope: list files reviewed (excluding skipped generated files).

package/references/source-coverage.md

@@ -0,0 +1,89 @@
+---
+books:
+  - The Mythical Man-Month
+  - Code Complete
+  - Refactoring
+  - Clean Architecture
+  - The Pragmatic Programmer
+  - Domain-Driven Design
+  - A Philosophy of Software Design
+  - Software Engineering at Google
+  - xUnit Test Patterns
+  - The Art of Unit Testing
+  - Working Effectively with Legacy Code
+  - How Google Tests Software
+---
+
+# Source Coverage Matrix
+
+Use this file in **Architecture / Tech Debt** modes, or when two sources disagree on a finding.
+Skip on Quick passes. It exists to prevent shallow "book-name citation" reviews.
+
+## Review Discipline
+- Cite a book only when the observed symptom actually matches that book's principle.
+- A threshold crossing is a hint, not a verdict. Check context, intent, and blast radius.
+- Look for justified tradeoffs before flagging a smell as debt.
+- Prefer concrete architectural or domain consequences over abstract style complaints.
+- If two books pull in different directions, state the tradeoff instead of pretending there is no tension.
+
+---
+
+## Frederick Brooks — *The Mythical Man-Month*
+**Encoded today:** Change propagation as communication overhead; Second-System Effect; Conceptual Integrity.
+**Do not ignore:** Whether the design shows a single coherent idea or competing local optimizations; whether cross-team coordination cost is becoming part of feature cost.
+**Do not over-flag:** Large systems are not automatically second systems; multi-module designs are acceptable when they preserve conceptual integrity.
+
+## Steve McConnell — *Code Complete*
+**Encoded today:** Routine length, nesting, naming, magic numbers; construction-phase YAGNI; defensive programming and error-handling discipline.
+**Do not ignore:** Whether low-level readability choices compound into operational risk; whether missing error handling makes failure modes invisible.
+**Do not over-flag:** Small, explicit guard clauses are not cognitive overload; a long routine may be acceptable when linear, well-named, single-purpose.
+
+## Martin Fowler — *Refactoring*
+**Encoded today:** Long Method, Long Parameter List, Message Chains, Shotgun Surgery, Divergent Change, Feature Envy, Inappropriate Intimacy, Duplicate Code, Speculative Generality, Lazy Class, Middle Man, Data Class, Flag Arguments, Primitive Obsession.
+**Do not ignore:** Whether the smell is local or systemic; whether a refactoring target has a natural home in the model.
+**Do not over-flag:** Temporary duplication during an active extraction is not always debt; a DTO/boundary record may legitimately be data-focused.
+
+## Robert C. Martin — *Clean Architecture*
+**Encoded today:** DIP, ADP, SDP, SAP, layering direction; ISP; LSP; SRP and OCP.
+**Do not ignore:** Policy vs detail boundaries; whether dependency arrows preserve replaceability and testability.
+**Do not over-flag:** Composition roots may depend on concrete infrastructure by design; thin adapter layers can import both directions when explicitly boundary glue.
+
+## Andrew Hunt & David Thomas — *The Pragmatic Programmer*
+**Encoded today:** Orthogonality; DRY; Law of Demeter.
+**Do not ignore:** Whether knowledge duplication is really duplicated decision-making; whether coupling is accidental or deliberate local simplification.
+**Do not over-flag:** Similar code in different bounded contexts is not automatically a DRY violation; direct object access inside a cohesive aggregate is not always a Demeter problem.
+
+## Eric Evans — *Domain-Driven Design*
+**Encoded today:** Ubiquitous Language; Bounded Context; Anemic Domain Model; Entity vs Value Object; Aggregate Roots.
+**Do not ignore:** Aggregate boundaries, invariant ownership, anti-corruption layers; whether names match the business language.
+**Do not over-flag:** CRUD-heavy workflows may legitimately use transaction scripts; thin entities are acceptable when the domain is simple.
+
+## John Ousterhout — *A Philosophy of Software Design*
+**Encoded today:** Deep vs shallow modules; Strategic vs tactical programming; Information Leakage.
+**Do not ignore:** Interface complexity relative to hidden complexity; whether repeated tactical patches raise long-term cognitive load; whether a "helper" exposes internal design decisions callers shouldn't know.
+**Do not over-flag:** Internal implementation complexity is fine when the interface stays simple; a small wrapper is acceptable when it meaningfully absorbs volatility.
+
+## Titus Winters, Tom Manshreck, Hyrum Wright — *Software Engineering at Google*
+**Encoded today:** Hyrum's Law; dependency management and upgrade blockage; code sustainability (multi-year maintainability); backward compatibility.
+**Do not ignore:** De facto APIs created by observable behavior; the maintenance cost of too much surface area; whether the dependency graph allows independent upgrades.
+**Do not over-flag:** A stable public API is not a liability if intentionally supported; fan-out alone is not disorder when dependency policy is explicit and governed.
+
+## Gerard Meszaros — *xUnit Test Patterns*
+**Encoded today:** Assertion Roulette, Mystery Guest, General Fixture; Eager Test, Lazy Test, Test Code Duplication, Behavior Verification; Erratic Test.
+**Do not ignore:** Whether test failures are diagnosable; whether the suite shape amplifies maintenance cost.
+**Do not over-flag:** Multiple assertions are acceptable when they express one behavior with one failure story; shared fixtures are acceptable when every field is relevant.
+
+## Roy Osherove — *The Art of Unit Testing*
+**Encoded today:** Test naming discipline; test isolation; mock usage guidelines; completeness of edge-path tests.
+**Do not ignore:** Whether tests verify behavior rather than wiring; whether seams simplify tests or contort production code for testability.
+**Do not over-flag:** A mock is acceptable when the dependency is nondeterministic and the assertion still verifies behavior; naming conventions are guidance, clarity is the goal.
+
+## Michael Feathers — *Working Effectively with Legacy Code*
+**Encoded today:** Legacy code as code without tests; Sensing and Separation; Seams; Characterization Tests.
+**Do not ignore:** Whether the team can change a risky area safely today; whether the code offers any seam for isolating behavior under change.
+**Do not over-flag:** Untested code is not automatically legacy if stable and not under active change; characterization tests matter most before modifying unclear existing behavior.
+
+## Google Engineering — *How Google Tests Software*
+**Encoded today:** Change coverage vs line coverage; pyramid shape and suite portfolio economics.
+**Do not ignore:** Whether the suite reflects business risk, not just percentages; whether expensive tests dominate feedback loops.
+**Do not over-flag:** A non-70:20:10 ratio can be healthy when justified by platform constraints or product risk; high coverage is useful when paired with meaningful branch and change protection.

package/references/test-decay-risks.md

@@ -0,0 +1,201 @@
+# Test Decay Risk Reference
+
+Six patterns that cause test suites to degrade. Apply the Iron Law to each finding.
+
+## Risk T1: Test Obscurity
+
+**Diagnostic question:** How much effort does it take to understand what this test verifies?
+
+Unclear test intent breeds distrust, missed failures, and duplicates — one step from an abandoned suite.
+
+### Symptoms
+- Assertion Roulette: multiple assertions with no message string.
+- Mystery Guest: test depends on external state (files, DB rows, shared fixtures) invisible in the body.
+- Test names that do not express scenario and expected outcome (`test1`, `shouldWork`, `testLogin`).
+- General Fixture: oversized setUp/beforeEach shared by unrelated tests.
+- Test body requires reading production code to understand what is verified.
+
+### Sources
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Assertion Roulette | Meszaros — xUnit Test Patterns | Assertion Roulette (p.224) |
+| Mystery Guest | Meszaros — xUnit Test Patterns | Mystery Guest (p.411) |
+| General Fixture | Meszaros — xUnit Test Patterns | General Fixture (p.316) |
+| Test naming | Osherove — The Art of Unit Testing | method_scenario_expected naming |
+
+### Severity Guide
+- 🔴 Critical: no test name describes the behavior; all assertions lack messages.
+- 🟡 Warning: multiple Mystery Guests; several ambiguous test names.
+- 🟢 Suggestion: minor naming issues; isolated General Fixture.
+
+### What Not to Flag
+- Multiple assertions are acceptable when they describe one coherent behavior and fail with a clear story.
+- Shared setup is fine when every initialized value is relevant to nearly every test.
+- Concise test names are acceptable if scenario and expected outcome are still obvious.
+
+---
+
+## Risk T2: Test Brittleness
+
+**Diagnostic question:** Do tests break when you refactor without changing behavior?
+
+Brittle tests punish refactoring — eventually developers stop refactoring to protect the suite.
+
+### Symptoms
+- Tests assert on private method results, internal state, or implementation details.
+- Eager Test: one method verifies multiple unrelated behaviors.
+- Over-specified: assertions enforce mock call order or exact param values irrelevant to behavior.
+- Renaming/extracting a method causes > 5 tests to fail with no behavior change.
+- Erratic Test: different results across runs without production change (race, time, random, shared state).
+
+### Sources
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Eager Test | Meszaros — xUnit Test Patterns | Eager Test (p.228) |
+| Erratic Test | Meszaros — xUnit Test Patterns | Erratic Test |
+| Implementation coupling | Osherove — The Art of Unit Testing | Test isolation principle |
+| Orthogonality violation | Hunt & Thomas — The Pragmatic Programmer | Ch. 2: Orthogonality |
+
+### Severity Guide
+- 🔴 Critical: behavior-preserving refactor causes test failures; > 5 tests coupled to one impl detail.
+- 🟡 Warning: Eager Tests common; moderate implementation-detail assertions.
+- 🟢 Suggestion: isolated over-specification in non-critical tests.
+
+### What Not to Flag
+- Verifying an externally observable event or emitted command is not implementation coupling.
+- One test with several assertions is acceptable when all support one behavior claim.
+- A fake/in-memory adapter is not brittleness if the test still asserts behavior, not wiring.
+
+---
+
+## Risk T3: Test Duplication
+
+**Diagnostic question:** Is the same test scenario expressed in more than one place?
+
+Duplicated tests must change in multiple places and create false confidence without testing distinct behavior.
+
+### Symptoms
+- Test Code Duplication: same setup/assertion logic copy-pasted without extraction.
+- Lazy Test: multiple tests verifying identical behavior with no differentiation.
+- Same boundary condition tested identically at unit, integration, and E2E with no layer differentiation.
+- Test helpers/fixtures duplicated across files instead of shared.
+
+### Sources
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Test Code Duplication | Meszaros — xUnit Test Patterns | Test Code Duplication (p.213) |
+| Lazy Test | Meszaros — xUnit Test Patterns | Lazy Test (p.232) |
+| DRY violation in tests | Hunt & Thomas — The Pragmatic Programmer | DRY |
+
+### Severity Guide
+- 🔴 Critical: core scenario fully duplicated across all three test layers with no differentiation.
+- 🟡 Warning: common scenario setup repeated in 5+ tests without extraction.
+- 🟢 Suggestion: minor helper duplication; isolated Lazy Tests.
+
+### What Not to Flag
+- The same scenario may appear at unit and integration level when each verifies a distinct risk.
+- Small local setup duplication can be clearer than an over-abstracted fixture maze.
+- Similar assertions against different domain rules are not Lazy Tests if business intent differs.
+
+---
+
+## Risk T4: Mock Abuse
+
+**Diagnostic question:** Is the test more complex than the behavior it tests?
+
+Mock abuse produces tests that pass while verifying nothing — production code can be fully broken as
+long as the mocks are wired up.
+
+### Symptoms
+- Mock setup code longer than the test logic itself.
+- Primary assertion is `expect(mock).toHaveBeenCalledWith(...)` — verifies a mock was called, not real behavior.
+- Test-only methods added to production classes for lifecycle management in tests.
+- Single unit test uses > 3 mocks.
+- Incomplete Mock: mock missing fields downstream code will access (silent integration failures).
+- Hard-Coded Test Data: no resemblance to real data shapes/constraints.
+
+### Sources
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Mock count > 3 | Osherove — The Art of Unit Testing | Mock usage guidelines |
+| Testing mock behavior | Meszaros — xUnit Test Patterns | Behavior Verification (p.544) |
+| Test-only production methods | Feathers — Working Effectively with Legacy Code | Ch. 3: Sensing and Separation |
+| Hard-Coded Test Data | Meszaros — xUnit Test Patterns | Hard-Coded Test Data (p.534) |
+| Incomplete Mock | Osherove — The Art of Unit Testing | Mock completeness requirement |
+
+### Severity Guide
+- 🔴 Critical: mock setup > 50% of test code; production class has methods only called from tests.
+- 🟡 Warning: mocks consistently > 3 per test; primary assertions are mock call verifications.
+- 🟢 Suggestion: isolated Incomplete Mocks; minor Hard-Coded Test Data.
+
+### What Not to Flag
+- A small number of mocks around nondeterministic dependencies is acceptable when assertions still verify behavior.
+- Fakes and spies used to observe state transitions are not mock abuse by default.
+- One interaction assertion may be appropriate when the interaction itself is the behavior under test.
+
+---
+
+## Risk T5: Coverage Illusion
+
+**Diagnostic question:** Does the test suite actually protect against the failures that matter?
+
+Coverage measures execution, not verification. 90% line coverage can still miss every critical
+failure mode.
+
+### Symptoms
+- High line coverage but error-handling branches, boundaries, exception paths untested.
+- Happy-path only: no sad paths, no null/empty/zero inputs, no concurrency edge cases.
+- Legacy code areas actively modified with no tests (Feathers: "legacy code is code without tests").
+- Coverage % treated as a sign-off criterion; critical change paths remain untested.
+- Tests assert return values but not important side effects (DB writes, event publishes, state transitions).
+
+### Sources
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Legacy code = no tests | Feathers — Working Effectively with Legacy Code | Ch. 1 |
+| Change coverage vs line coverage | Google — How Google Tests Software | Ch. 11: Testing at Google Scale |
+| Happy-path only | Osherove — The Art of Unit Testing | Test completeness principle |
+
+### Severity Guide
+- 🔴 Critical: legacy code area actively modified with no tests; error-handling paths entirely absent.
+- 🟡 Warning: coverage > 80% but edge and exception paths systematically absent.
+- 🟢 Suggestion: a few non-critical paths missing sad-path tests.
+
+### What Not to Flag
+- High line coverage is useful when paired with branch, boundary, and change-path coverage.
+- A new module may have limited coverage early if still private and low-risk.
+- Side-effect assertions may live in integration tests without implying a gap.
+
+---
+
+## Risk T6: Architecture Mismatch
+
+**Diagnostic question:** Does the test suite structure reflect the system's actual risk profile?
+
+Wrong suite shape is slow and expensive — not from bad tests, but from using the wrong type at the
+wrong layer.
+
+### Symptoms
+- Inverted test pyramid: E2E/integration count exceeds unit count → slow, fragile suite.
+- Legacy code with no seam points (no interfaces, DI, or seams) → impossible to test in isolation.
+- Legacy areas modified with no Characterization Tests to capture current behavior before changes.
+- Full suite execution > 10 minutes (architectural problem, not performance).
+- High-risk and low-risk paths tested at identical density; no risk-based prioritization.
+
+### Sources
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Inverted pyramid | Google — How Google Tests Software | 70:20:10 unit:integration:E2E ratio |
+| No seam points | Feathers — Working Effectively with Legacy Code | Ch. 4: Seam Model |
+| Missing Characterization Tests | Feathers — Working Effectively with Legacy Code | Ch. 13: Characterization Tests |
+| Suite execution time | Meszaros — xUnit Test Patterns | Slow Tests (p.253) |
+
+### Severity Guide
+- 🔴 Critical: legacy code modified has no seams and no characterization tests; pyramid fully inverted.
+- 🟡 Warning: suite > 10 min; integration/E2E count exceeds unit tests.
+- 🟢 Suggestion: localized pyramid deviation; a few legacy areas missing characterization tests.
+
+### What Not to Flag
+- Deviating from 70:20:10 can be justified by platform constraints or product risk.
+- A suite heavy on integration tests can be healthy if feedback is fast and purposefully layered.
+- A small number of critical-path E2E tests is desirable, not a smell.