ray/hermes-config

Fork 0

Files

T

ray dab5a4ebc6 initial commit

2026-07-12 10:17:17 -04:00

7.7 KiB

Raw Permalink Blame History

name, description, version, author, license, platforms, metadata

name

description

version

author

license

platforms

metadata

codebase-audit

Systematic deep audit and bulk remediation of an existing codebase — parallel subagent review, shared utility creation, fix application, and verification. Absorbed codebase-inspection (pygount-based LOC and language breakdown).

1.0.0

Hermes Agent

MIT

linux

macos

hermes

Codebase Audit & Bulk Remediation

Comprehensive error finding and fix application across a existing codebase (not a git diff). Scales to 30+ files using parallel subagents for review, shared utilities for fixes, and script-based verification.

When to use: User asks you to "check the code for errors", "find all the bugs", "audit the project", "make all the fixes" — any request to systematically scan an existing codebase (not just a diff or a single file).

When NOT to use: Pre-commit review of small changes (use requesting-code-review), single-file analysis, debugging a specific bug (use systematic-debugging).

Phase 1 — Survey

Before any review, understand the codebase structure:

# Get a file inventory
find /path/to/project -type f -name '*.js' -o -name '*.html' -o -name '*.css' | sort

# Quick size check per file
wc -l /path/to/project/**/*.js

Codebase Size & Language Breakdown (pygount, absorbed from `codebase-inspection`)

For a structured overview of the codebase size, language composition, and code-vs-comment ratios, use pygount:

pip install --break-system-packages pygount 2>/dev/null || pip install pygount

pygount --format=summary \
  --folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,.next,.tox,.eggs,*.egg-info,vendor,third_party" \
  .

Always use --folders-to-skip — without it, pygount crawls node_modules and can hang.

Language-specific filtering:

# Only count Python files
pygount --suffix=py --format=summary .

Output columns: Language, Files, Code lines, Comment lines, % of total.

Pseudo-languages to expect: __empty__, __binary__, __generated__, __duplicate__, __unknown__.

Pitfall: Markdown content is classified as comments (0 code lines). This is expected.

Identify the stack, key files, and group files into review batches of 5-8 files each. Keep related files together (e.g., all shared/ files in one batch).

Phase 2 — Parallel Subagent Review

Use delegate_task(tasks=[...]) with up to max_concurrent_children subagents. Each subagent gets a batch of files and a clear review mandate.

Per-task structure:

{
    "goal": "Review these files for errors, bugs, security issues, and code quality problems. Report everything you find.",
    "context": "File paths, what each file does, what to prioritize",
    "toolsets": ["file"]
}

Review categories to check every file for:

🔴 Critical (will crash): ReferenceError on undefined variables, TypeError on null/undefined access (.toDate() on null, .toUpperCase() on undefined), malformed API URLs, variable shadowing in closures
🟠 Security: XSS via innerHTML with unsanitized user/Firestore data, inline onclick handlers with string interpolation (onclick="fn('${data}')"), client-side API keys, eval()-like patterns, subresource integrity (SRI) missing on CDN scripts, Content-Security-Policy absent
🟡 Logic bugs: Infinite retries with no backoff, memory leaks (accumulating event listeners on re-render, timer nuking that clears ALL browser timers), duplicate field names in data models, missing null guards on optional fields
🟢 Accessibility: Missing role="dialog"/aria-modal on modals, missing aria-live on dynamic content, missing aria-label on icon-only buttons, no focus trapping in modals, no skip-to-content link
⚪ Quality: Dead code (empty files, unreachable branches), excessive console.log, redundant duplicate code, hardcoded magic numbers

Phase 3 — Prioritize and Plan Fixes

Aggregate all findings from subagents, group by severity, and plan the fix order:

Critical crashes first — these break the app at runtime
Security vulnerabilities — XSS, exposed keys, CSP/SRI
Logic bugs — retries, memory leaks, data integrity
Accessibility — screen reader support
Code quality — cleanup

Phase 4 — Create Shared Utilities

Before fixing individual files, create any shared helpers the fixes need:

// shared/sanitize.js — XSS prevention
export function escapeHtml(value) {
    if (value == null) return '';
    const str = String(value);
    const div = document.createElement('div');
    div.appendChild(document.createTextNode(str));
    return div.innerHTML;
}

Create this FIRST so all fix subagents can import it.

Phase 5 — Apply Fixes in Parallel

Use delegate_task(tasks=[...]) again, this time for fixes. Group related fixes:

Batch structure (common groupings):

Bug-fix batch: 1 subagent per large file (dashboard.js, repair-orders.js)
XSS batch: 1 subagent to add escapeHtml imports + wrap all interpolations across 5-8 files
HTML/a11y batch: index.html and all other HTML pages
Config batch: firebase.json, etc.

Fix patterns to apply:

// Before (XSS via innerHTML):
element.innerHTML = `<div>${userData}</div>`;

// After:
element.innerHTML = `<div>${escapeHtml(userData)}</div>`;

// Before (null crash):
writeupTime: doc.data().writeupTime.toDate()

// After (optional chaining):
writeupTime: doc.data().writeupTime?.toDate?.() ?? new Date()

// Before (infinite retry):
setTimeout(() => loadData(), 3000);

// After (bounded retry):
let retryCount = 0;
function retry(fn, max = 3, delay = 3000) {
    retryCount++;
    if (retryCount > max) return;
    setTimeout(fn, delay * Math.pow(2, retryCount - 1));
}

Per-fix-subagent instructions must be SPECIFIC — list exact line ranges or search patterns, exact old_string → new_string, and how to find them (e.g., "search for onclick=\"...\${...} patterns in repair-orders.js").

Phase 6 — Verification

After all fixes, run a grep-based verification script to confirm each fix was applied:

from hermes_tools import terminal

checks = [
    ('file.js', 'pattern_to_confirm'),
    ('file.js', 'escapeHtml'),  # check XSS fix applied
]

for file, pat in checks:
    r = terminal(f"grep -c '{pat}' '{path}' 2>/dev/null || echo '0'")
    count = r['output'].strip().split('\n')[0]
    ok = count != '0'
    print(f"{'✅' if ok else '❌'} {file}: '{pat}' -> {count}")

Pitfalls

Subagents exceed tool iteration limits — big files (3000+ lines) may hit 50-iteration cap. Split fixes across multiple subagents or fix smaller batches at a time.
Patch tool finds multiple matches — when a pattern appears in two similar functions (e.g., both getPriorityAnalysis and handleAiWrite), use replace_all=True or add more context lines to disambiguate.
Re-read warnings — subagents that modify files you previously read will trigger "file was last read with partial view" warnings. Re-read the file before further patches.
XSS is pervasive — in a ~30 file codebase, expect 80-120+ interpolation points. Don't try to fix them all in one subagent task; batch by file group.
Timer nuking is a common anti-pattern in prototyped apps — watch for for (let i = 0; i < highestTimeoutId; i++) clearTimeout(i) patterns.
delegate_task max_concurrent_children defaults to 3. If you need more parallelism, mention it to the user.
Don't fix what you can't verify — API keys marked *** can't be fixed to real values; mark them as TODO. Empty cloud functions stubs with no exports are intentional blanks.

7.7 KiB Raw Permalink Blame History