From a905f01301d767731a04f90d825387f6ec1fd1f3 Mon Sep 17 00:00:00 2001 From: Xingyu Chen Date: Wed, 10 Jun 2026 18:17:08 -0700 Subject: [PATCH] Add Standard page, multi-language excludes, Codex/AGENTS.md support --- AGENTS.md | 35 ++++++++++++++++++ README.md | 38 +++++++++++++++++++- assets/template.html | 81 ++++++++++++++++++++++++++++++++++++++++++ reference/STANDARDS.md | 17 +++++++++ scripts/scan.py | 17 ++++++--- 5 files changed, 182 insertions(+), 6 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..4e47c7a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,35 @@ +# codemap — agent instructions + +This repository **is the codemap tool**: it builds and incrementally maintains an +interactive architecture map + per-module code-quality audit for any codebase. It is a +Claude Code skill, but the engine is tool-agnostic — **Codex, Cursor, Aider, or any +agent that can read instructions and spawn sub-tasks can drive it.** + +## Read these first +- **`SKILL.md`** — the full workflow and the `generate / check / update / test / fix` + commands. Follow it exactly. +- **`reference/STANDARDS.md`** — the fixed scoring rubric, smell taxonomy (with + per-language equivalents), severity levels, and the **exact per-module audit prompt**. +- **`reference/DATA_MODEL.md`** — the `modules.json` schema (the source of truth). + +## Non-negotiable rules +1. **`modules.json` is the source of truth.** The HTML and MD are generated by + `scripts/render.py` — never hand-edit them. +2. **Every module's score comes from a separate, independent sub-task** (one module per + sub-task), using the prompt in `reference/STANDARDS.md`. Never score many modules in + one pass; never reuse one module's score for another. +3. For `fix`: keep the **four roles separate** — test-author, fixer, acceptance/verifier, + auditor. A fix is accepted only when an independent acceptance step shows the pre-fix + green tests are still green and the build is clean. + +## The scripts (deterministic, Python 3 stdlib, no install) +``` +python scripts/scan.py --root --state [--write] # LoC + hash + staleness +python scripts/query.py --state --max-grade C --format ids # pick targets cheaply +python scripts/apply_audit.py --state --id --json '' +python scripts/render.py --state --template assets/template.html \ + --out-html --out-md +``` +Use `query.py` (`--format ids|paths|findings`) to target work without reading the whole +`modules.json`. Only scoring / fixing / test-writing need the model; everything else is +a plain script call. diff --git a/README.md b/README.md index 4f69acf..1d0e5d9 100644 --- a/README.md +++ b/README.md @@ -31,12 +31,26 @@ The HTML and MD are **generated** from `modules.json` and must never be hand-edi recede to a muted green — colorblind-friendly, the cue is saturation not just hue). - **Filters**: by grade level (≤ B/C/D/F) and by issue tag; live match count. - **Audit report** view: averages, grade spread, worst offenders, cross-cutting themes. +- **Standard page**: a built-in "Standard" view explaining the score→grade rubric, the + finding severities, and every smell tag — so the scores are self-documenting. - **i18n**: set `meta.lang` to `"en"` or `"zh"` (module names are never translated). +## Languages + +Language-agnostic. The scripts count LoC and hash bytes for **any** text source, and +`paths` are plain globs, so it works for Python, **TypeScript/JS, Rust, C#/.NET, C/C++**, +Go, Java, Swift, and more. Build/test/generated trees are excluded out of the box +(`target/`, `bin/`, `obj/`, `node_modules/`, `cmake-build*`, `__pycache__/`, `dist/`, +`*.d.ts`, `*.Designer.cs`, …). The audit rubric names *behaviors*, not syntax — +`reference/STANDARDS.md` maps each smell to its per-language form (e.g. `any-escape` = +`as any` / `dynamic` / `void*` / `reinterpret_cast` / `unsafe`). + ## Requirements - **Python 3** (standard library only — no `pip install`, no external packages). -- **Claude Code** (the skill orchestrates subagents for the audit/fix/test steps). +- **An AI coding agent** to drive the audit/fix/test steps — **Claude Code** (native + skill) or **any other agent that can read instructions and spawn sub-tasks**, e.g. + OpenAI **Codex** (see [Using with Codex / other agents](#using-with-codex--other-agents)). - A browser to open the generated HTML. That's it. ## Install @@ -81,6 +95,28 @@ python3 $S/scripts/render.py --state .claude/codemap/modules.json \ > On Windows use `python` instead of `python3`. +## Using with Codex / other agents + +The skill mechanism is Claude-specific, but the **engine is tool-agnostic**: the four +scripts are deterministic stdlib Python, and the workflow + rubric are plain Markdown +(`SKILL.md`, `reference/STANDARDS.md`). Any capable agent can drive it. + +**OpenAI Codex** auto-reads an `AGENTS.md` in the working directory — this repo ships one +that points Codex at the workflow and rubric. To use codemap from Codex (or Cursor, +Aider, etc.): + +1. Make the tool available — clone this repo somewhere the agent can read it, e.g. + `git clone ~/.codemap` (or vendor it into your project). +2. Tell the agent: *"Use the codemap tool at `` to build/update the architecture + map for this project. Follow its `SKILL.md`; score each module with a separate + sub-task using `reference/STANDARDS.md`."* +3. The agent runs the same commands shown above (`scan.py` → per-module audit → + `apply_audit.py` → `render.py`), using `query.py` to pick targets cheaply. + +The deterministic parts (scan / query / render / apply_audit) you can also run **by +hand** with no agent at all — only the *scoring*, *fixing*, and *test-writing* need a +model, and those just follow `reference/STANDARDS.md`. + ## How it works ``` diff --git a/assets/template.html b/assets/template.html index aee41ad..3019b82 100644 --- a/assets/template.html +++ b/assets/template.html @@ -126,6 +126,19 @@ .grade-A{color:#76b39a;border-color:#3a5249} .grade-B{color:#b9c0c7;border-color:var(--border2)} .grade-C{color:#d9a441;border-color:#5a4720} .grade-D{color:#e08a4a;border-color:#5a3a20} .grade-F{color:#e0524b;border-color:#5a2420} .scrollnote{position:absolute;right:14px;bottom:12px;z-index:5;font-size:10.5px;color:var(--faint);font-family:var(--mono);pointer-events:none;background:#0e1012aa;padding:3px 8px;border-radius:6px;border:1px solid var(--border)} + .modal{position:fixed;inset:0;z-index:60;display:none;background:#0a0b0ccc;overflow:auto;padding:46px 20px} + .modal.open{display:block} + .modal .sheet{position:relative;max-width:740px;margin:0 auto;background:var(--panel);border:1px solid var(--border);border-radius:12px;padding:24px 26px 30px} + .modal .sheet h2{font-size:17px;font-weight:650;margin:0 0 3px;letter-spacing:.1px} + .modal .sheet .intro{font-size:12.5px;color:var(--faint);margin:0 0 6px;line-height:1.5} + .modal .xbtn{position:absolute;top:16px;right:16px} + .std-h4{font-size:10.5px;text-transform:uppercase;letter-spacing:1px;color:var(--faint);margin:22px 0 4px} + .std-row{display:flex;gap:13px;align-items:baseline;padding:8px 0;border-top:1px solid var(--border)} + .std-badge{flex:0 0 56px;font-family:var(--mono);font-weight:700;font-size:12px;text-align:center;border-radius:6px;padding:3px 0;color:#0c0d0e} + .std-range{flex:0 0 56px;font-family:var(--mono);font-size:11px;color:var(--muted)} + .std-key{flex:0 0 116px} + .std-row .sev{font-family:var(--mono);font-size:9px;font-weight:700;padding:2px 6px;border-radius:4px;letter-spacing:.4px} + .std-desc{flex:1;font-size:12.5px;color:#cfd3d8;line-height:1.5} ::-webkit-scrollbar{width:11px;height:11px} ::-webkit-scrollbar-thumb{background:#2c3137;border-radius:6px;border:3px solid var(--bg2)} ::-webkit-scrollbar-track{background:transparent} @@ -153,6 +166,7 @@ + @@ -170,6 +184,7 @@ +