Audit Code

Code Audit Skill

Deep audit of Epoch stack components across 3 phases: code smell detection, fix application, and cross-stack connectivity verification.

Usage

/audit-code xy_bars
/audit-code bar_chart --phase 2
/audit-code histogram --phase 4
/audit-code lines_chart --phase all

Phases

Default: runs all phases sequentially (2 → 3 → 4).

Stack Layers

Key Paths

BACKEND=/home/adesola/EpochDev/EpochBackend
PORTAL=/home/adesola/EpochDev/EpochPortal

# Metadata
$BACKEND/packages/epoch-script/src/transforms/metadata/

# Implementation
$BACKEND/packages/epoch-script/src/transforms/components/reports/

# Tests
$BACKEND/packages/epoch-script/test/unit/transforms/reports/
$BACKEND/packages/epoch-dashboard/tests/

# Proto definitions
$BACKEND/packages/epoch-protos/proto/

# Builders
$BACKEND/packages/epoch-dashboard/include/epoch_dashboard/tearsheet/
$BACKEND/packages/epoch-dashboard/src/tearsheet/

# Frontend types (package copy — authoritative)
$PORTAL/packages/epoch-protos/src/protos.d.ts

# Frontend types (local copy — may be stale)
$PORTAL/src/types/dashboard/protos.d.ts

# Frontend components
$PORTAL/src/components/dashboard/charts/
$PORTAL/src/utils/dashboard/protoToHighcharts.ts

Phase 2: Code Smell Audit

Scope: Per-File

Phase 2 operates on one file at a time. Each file gets its own complete deep read and independent audit report. If the argument names a component (e.g., xy_bars), resolve it to specific files and audit each separately:

/audit-code xy_bars
  → File 1: epoch-script/src/transforms/components/reports/bars.cpp
  → File 2: epoch-script/test/unit/transforms/reports/.../bars_test.cpp
  → File 3: epoch-dashboard/src/tearsheet/bar_chart_builder.cpp
  → File 4: EpochPortal/src/components/dashboard/charts/BarChart.tsx
  (each gets its own Phase 2 audit)

/audit-code bars.cpp
  → Single file audit

/audit-code BarChart.tsx
  → Single file audit

Method

For each file, read it completely and evaluate every code block against these 5 questions:

Procedure (repeat for each file)

1. Read the file completely (not skimming — every line)
2. Identify the corresponding test file (if auditing an impl, find its tests; if auditing a test, find its impl)
3. For each logical block (function, branch, loop), answer all 5 questions
4. Catalog findings for this file in a numbered list with severity:

## Code Smell Audit: <file_path>

| # | Severity | Question | Location | Finding | Impact |
|---|----------|----------|----------|---------|--------|
| 1 | CRITICAL | Correct for all inputs? | line 305 | Empty values → NaN but caller expects 0 | Silent data corruption |
| 2 | HIGH | Fails explicitly? | line 370 | Infinite aggregation silently becomes 0 | Misleading chart values |
| 3 | MEDIUM | Is it tested? | line 145 | groupPadding option not tested | Regression risk |
| 4 | LOW | Is it consistent? | lines 120,180 | Same pattern but different default | Confusing maintenance |

5. Move to the next file — do NOT bundle findings across files

Severity Definitions

Code Smell Patterns to Watch For

• NaN→0 conversions: Arrow C++ sum([NaN,...]) returns 0, not NaN. Any aggregation of NaN-heavy data silently zeroes out.
• Empty container assumptions: .front() / .back() on empty vector. values[0] without size check.
• Option declared but never read: Metadata declares an option, implementation never calls getOption().
• Test that can never fail: Assertion checks condition that code guarantees (e.g., testing NaN throws when code explicitly allows NaN).
• Copy-paste divergence: Two similar code paths (e.g., labeled mode vs series mode) where one has a fix the other doesn't.
• Silent fallback: Catch-all else or default: that returns a plausible value instead of erroring.
• Unreachable validation: Validation that runs after the value is already coerced (e.g., checking for negative after abs()).

Phase 3: Fix Pattern

Method

For each issue found in Phase 2, fix one at a time in this order:

1. Write/update the test first — the test should fail (or be missing) before the fix
2. Apply the minimal code fix — smallest change that resolves the issue
3. Build and run tests — verify the fix passes and nothing regresses
4. Move to the next issue

Procedure

For each issue (ordered CRITICAL → HIGH → MEDIUM → LOW):

  1. ASSESS: Is this truly a bug, or a design choice? If design choice, document and skip.

  2. TEST FIRST:
     - Find the test file for this component
     - Add a test case that exercises the exact bug condition
     - Build and confirm the NEW test fails (or add it alongside the fix if it's a missing-coverage issue)

  3. FIX:
     - Make the minimal code change
     - Do NOT refactor surrounding code
     - Do NOT add features
     - Do NOT fix other issues in the same edit

  4. VERIFY:
     - Build the test target:
       ./cpp_tools/run_tests.sh <test_target>
     - ALL existing tests must still pass
     - The new test must pass
     - If build fails, fix the build error before moving on

  5. REPORT:
     Issue #N: <title>
     - Test: <test file>:<line> — <test name>
     - Fix: <impl file>:<line> — <description>
     - Result: ✅ All tests pass (X assertions)

Fix Anti-patterns (DO NOT)

• Do NOT bundle multiple fixes in one edit
• Do NOT "improve" code that isn't broken
• Do NOT add defensive checks for impossible states
• Do NOT change function signatures unless the bug requires it
• Do NOT skip the test step ("it's obvious this works")

Phase 4: Cross-Stack Connectivity

Method

For every field in the target proto message, trace the full path through all layers and verify it's connected end-to-end.

Procedure

Step 1: Enumerate all proto fields

Read the .proto file for the target component. List every field with its type and number.

Example for BarDef:
  1. chart_def (ChartDef)
  2. data (repeated BarData)
  3. vertical (bool)
  4. stack_type (StackType)
  5. overlay_lines (repeated NumericLine)
  ...

Step 2: Trace each field through all layers

For each field, check:

Step 3: Build connectivity matrix

## Connectivity Matrix: <Component>

| Field | Metadata | Impl | Builder | Proto | TS Types | Component | Highcharts | Status |
|-------|----------|------|---------|-------|----------|-----------|------------|--------|
| vertical | ✅ b_vertical | ✅ getOption | ✅ setVertical | ✅ field 3 | ✅ vertical | ✅ data.vertical | ✅ chart type | CONNECTED |
| stackLabels | ✅ b_stack_labels | ✅ getOption | ✅ setStackLabels | ✅ field 10 | ✅ stackLabels | ❌ not read | ❌ | BROKEN at Component |
| overlayLines | — (code-set) | ✅ addOverlayLine | ✅ addOverlayLine | ✅ field 5 | ❌ missing | ❌ | ❌ | BROKEN at TS Types |

Step 4: Diagnose disconnections

For each BROKEN field:

1. Identify the break point — which layer is the first ❌?
2. Determine the fix — is it missing code, wrong field name, stale generated types?
3. Assess severity:
   • User-facing field that doesn't work → CRITICAL
   • Internal optimization field → LOW
   • Field used by some chart types but not others → MEDIUM

Step 5: Fix disconnections

Apply Phase 3 fix pattern to each disconnection, working from the deepest layer outward:

1. Fix proto/types first (regenerate if needed)
2. Fix frontend component
3. Verify with build

Common Disconnection Patterns

Output Format

After completing all requested phases, produce a final summary:

## Audit Summary: <component>

### Phase 2: Code Smells
- **Found:** X issues (Y critical, Z high, ...)
- **Key findings:** [1-2 sentence summary]

### Phase 3: Fixes Applied
- **Fixed:** X of Y issues
- **Skipped:** Z issues (with reasons)
- **Tests:** All passing (N assertions)

### Phase 4: Connectivity
- **Fields traced:** X
- **Connected:** Y (Z%)
- **Disconnected:** W (list)
- **Fixed:** V disconnections

### Remaining Work
- [ ] Item 1
- [ ] Item 2

ARGUMENTS: $ARGUMENTS