diff --git a/README.md b/README.md index 3338f3e..4ff05d7 100644 --- a/README.md +++ b/README.md @@ -17,11 +17,16 @@ Three coupled artifacts, kept in sync: | File | What | Where (default) | |---|---|---| -| `modules.json` | the **source of truth** (modules, deps, coupling, LoC, hash, score, findings) | `/.claude/codemap/` | -| `architecture-map.html` | self-contained **interactive map** (health coloring, filters, dependency highlighting, audit report) | `/docs/` | -| `architecture-audit.md` | the written **report** (per-layer scores, LoC table, worst offenders, themes) | `/docs/` | +| `config.json` | your saved **preferences** (UI language, output location, title) | `/.codemap/` | +| `modules.json` | the **source of truth** (modules, deps, coupling, LoC, hash, score, findings) | `/.codemap/` | +| `architecture-map.html` | self-contained **interactive map** (health coloring, filters, dependency highlighting, audit report) | `/.codemap/` | +| `architecture-audit.md` | the written **report** (per-layer scores, LoC table, worst offenders, themes) | `/.codemap/` | -The HTML and MD are **generated** from `modules.json` and must never be hand-edited. +Everything lives in **`/.codemap/`** by default. On first run (`generate`) the +tool asks your preferences — UI language, output location (point it at `docs/` if you +want the HTML/MD committed/visible), project title — and saves them to +`.codemap/config.json`. The HTML and MD are **generated** from `modules.json` and must +never be hand-edited. ### Interactive map features - Layered bands top→bottom along the data-flow; click a module to highlight what it @@ -84,16 +89,16 @@ You can also run the deterministic scripts directly (no AI needed for these): S=~/.claude/skills/codemap # what changed since last audit — incl. a `git` block listing the commits since the # last codemap run (meta.rev) and which modules they touched -python3 $S/scripts/scan.py --root . --state .claude/codemap/modules.json +python3 $S/scripts/scan.py --root . --state .codemap/modules.json # after an update, cache the current HEAD as the new baseline for next time -python3 $S/scripts/scan.py --root . --state .claude/codemap/modules.json --stamp-rev +python3 $S/scripts/scan.py --root . --state .codemap/modules.json --stamp-rev # find modules to act on without reading the whole state (token-cheap, for agents) -python3 $S/scripts/query.py --state .claude/codemap/modules.json --max-grade C --format ids -python3 $S/scripts/query.py --state .claude/codemap/modules.json --tag dual-format +python3 $S/scripts/query.py --state .codemap/modules.json --max-grade C --format ids +python3 $S/scripts/query.py --state .codemap/modules.json --tag dual-format # regenerate the HTML + MD from the state -python3 $S/scripts/render.py --state .claude/codemap/modules.json \ +python3 $S/scripts/render.py --state .codemap/modules.json \ --template $S/assets/template.html \ - --out-html docs/architecture-map.html --out-md docs/architecture-audit.md + --out-html .codemap/architecture-map.html --out-md .codemap/architecture-audit.md ``` > On Windows use `python` instead of `python3`. @@ -162,10 +167,10 @@ severities, coupling, and the issue tags with descriptions). Two ways to customi - **In the map**: open the **Standard** page (header button), click **Edit**, change any description, add your own tags (`+ Tag`), then **Export** → save the downloaded - `standard.json` to `/.claude/codemap/standard.json`. Edits are kept in the + `standard.json` to `/.codemap/standard.json`. Edits are kept in the browser until you export. Custom tags flow through the whole map (cards, filters, report) and are used by future audits. -- **By file**: copy `reference/standard.json` to `/.claude/codemap/standard.json` +- **By file**: copy `reference/standard.json` to `/.codemap/standard.json` and edit it. `render.py` prefers the project file over the skill default. The prose version + the exact subagent audit prompt live in `reference/STANDARDS.md` diff --git a/SKILL.md b/SKILL.md index c13ce75..7016623 100644 --- a/SKILL.md +++ b/SKILL.md @@ -36,9 +36,9 @@ schema is in **`reference/DATA_MODEL.md`**. Do not improvise scoring or invent t **The standard is configurable per project.** A machine-readable copy lives in `reference/standard.json` (rubric, severities, coupling, and the tag list with descriptions). A project may override it by placing its own `standard.json` next to the -state file (`/.claude/codemap/standard.json`) — `render.py` picks the project +state file (`/.codemap/standard.json`) — `render.py` picks the project file first, else the skill default, and injects it into the map's editable **Standard** -page. **Honor the project's tag set:** when `.claude/codemap/standard.json` exists, audit +page. **Honor the project's tag set:** when `.codemap/standard.json` exists, audit modules using *its* tags (including any custom tags the user added) — that is how users capture their own definition of a problem. Keep `STANDARDS.md` (the prose + subagent prompt) and `standard.json` (the machine copy) in sync if you change the defaults. @@ -47,12 +47,16 @@ prompt) and `standard.json` (the machine copy) in sync if you change the default - `SKILL_DIR` = this skill's directory. Scripts are at `SKILL_DIR/scripts/*.py`, template at `SKILL_DIR/assets/template.html`. Use python3, stdlib only. -- Default artifact locations (override if the user/project prefers): state (the data) - at `/.claude/codemap/modules.json`; the generated outputs at - `/dev_docs/architecture-map.html` and `dev_docs/architecture-audit.md`. The - state lives under `.claude/` (tooling data, kept out of the docs tree); only the two - human-facing artifacts go in `dev_docs/`. Set `meta.htmlPath` / `meta.mdPath` so the - reciprocal links are correct. +- **Everything lives under `/.codemap/`** — one folder, not `.claude/`: + - `config.json` — the user's saved preferences (UI language, output location, title…). + - `modules.json` — the state (source of truth). + - `standard.json` — optional per-project custom audit standard. + - `architecture-map.html` + `architecture-audit.md` — the generated outputs (default). + + The output location is a user preference: if they want the HTML/MD committed/visible, + let them point it at `docs/` instead (ask — see `generate` step 0). Set + `meta.htmlPath` / `meta.mdPath` to wherever the outputs land so the reciprocal links + are correct (both outputs sit in the same dir, so the in-page link uses the basename). - A re-render command (run after any state change): ``` python3 SKILL_DIR/scripts/render.py --state \ @@ -111,8 +115,24 @@ per-module subagent loop — never load the full `modules.json` just to pick tar ## Command: `generate` (first build) -Use when no `modules.json` exists yet. +Use when no `modules.json` exists yet (this is also "init"). +0. **Ask the user for preferences first** (use the AskUserQuestion tool), then save them to + `/.codemap/config.json`: + - **UI language** — `en` or `zh` (localizes the map chrome + report; module names are + never translated). → `meta.lang`. + - **Output location** — where the HTML/MD go. Default `.codemap/` (kept with the tool + data); offer `docs/` if they want them committed/visible. → `meta.htmlPath` / `meta.mdPath`. + - **Project title** (defaults to the repo/folder name) and an optional one-line subtitle, + in the chosen language. → `meta.project` / `meta.subtitle`. + + Write `config.json` like: + ```json + {"lang":"zh","project":"My App","subtitle":"…","outputDir":".codemap", + "htmlFile":"architecture-map.html","mdFile":"architecture-audit.md"} + ``` + and apply it to `meta` when you build `modules.json`. Re-read `config.json` on later + runs so preferences persist. 1. **Decompose the project into functional modules.** Explore the tree (parallel Explore agents for big repos). Identify capabilities and group them into **bands** (visual layers in data-flow order, e.g. UI → stores → transport → │wire│ → app → handlers → diff --git a/assets/template.html b/assets/template.html index 6c5e40e..e751cc7 100644 --- a/assets/template.html +++ b/assets/template.html @@ -221,8 +221,8 @@ const I18N = { btnStd:"Standard", stdTitle:"Audit standard", stdIntro:"How modules are scored — the same rubric for every module, language, and run. Click Edit to add your own issue tags.", stdRubric:"Score → grade", stdSeverity:"Finding severity", stdTags:"Issue tags", stdCoupling:"Coupling (structural, not quality)", close:"Close", stdEditBtn:"Edit", stdDone:"Done", stdExport:"Export", stdReset:"Reset", stdAddTag:"+ Tag", - stdEditHint:"Editing — changes save in this browser. Export → save as .claude/codemap/standard.json to make them permanent and used by audits.", - stdNewTagId:"New tag id (e.g. perf-risk, security):", stdExported:"Saved standard.json — put it in .claude/codemap/", + stdEditHint:"Editing — changes save in this browser. Export → save as .codemap/standard.json to make them permanent and used by audits.", + stdNewTagId:"New tag id (e.g. perf-risk, security):", stdExported:"Saved standard.json — put it in .codemap/", copyFix:"Copy fix prompt", copied:"Copied — paste into Claude Code / Codex", trackedLoc:(l,f)=>`${l} tracked LoC · ${f} files` }, zh:{ mapSuffix:"· 功能架构图", sub:"功能模块 · 调用层级 · 耦合 · 质量评分 · 代码行数", @@ -240,8 +240,8 @@ const I18N = { btnStd:"评判标准", stdTitle:"评判标准", stdIntro:"模块如何打分 —— 所有模块、所有语言、每一次运行都用同一套标准。点「编辑」可加入你自己的问题标签。", stdRubric:"分数 → 等级", stdSeverity:"问题严重度", stdTags:"问题标签", stdCoupling:"耦合（结构维度，非质量）", close:"关闭", stdEditBtn:"编辑", stdDone:"完成", stdExport:"导出", stdReset:"重置", stdAddTag:"+ 标签", - stdEditHint:"编辑中 —— 改动保存在本浏览器。导出 → 存为 .claude/codemap/standard.json 即永久生效并被审计采用。", - stdNewTagId:"新标签 id（如 perf-risk、security）：", stdExported:"已生成 standard.json —— 放到 .claude/codemap/ 下", + stdEditHint:"编辑中 —— 改动保存在本浏览器。导出 → 存为 .codemap/standard.json 即永久生效并被审计采用。", + stdNewTagId:"新标签 id（如 perf-risk、security）：", stdExported:"已生成 standard.json —— 放到 .codemap/ 下", copyFix:"复制修复指令", copied:"已复制 —— 粘贴到 Claude Code / Codex", trackedLoc:(l,f)=>`${l} 行（已跟踪）· ${f} 个文件` }, }; @@ -251,7 +251,7 @@ function stdText(o){ return o ? (LANG==="zh" ? (o.zh||o.en||"") : (o.en||o.zh||" /* ---------- the audit standard — editable, configurable, its own page ---------- Effective standard = a saved browser draft (user edits), else the injected file - (DATA.standard, from .claude/codemap/standard.json or the skill default), else + (DATA.standard, from .codemap/standard.json or the skill default), else this built-in fallback. Edit it on the Standard page and Export to standard.json to make it permanent and used by audits. Custom tags flow through the whole map. */ const BUILTIN_STD = { diff --git a/reference/DATA_MODEL.md b/reference/DATA_MODEL.md index 5f11c85..efaeb0a 100644 --- a/reference/DATA_MODEL.md +++ b/reference/DATA_MODEL.md @@ -15,8 +15,8 @@ subagents edit it) and re-render. "generatedAt": "2026-01-01", "rev": "abc1234", // git HEAD at the last codemap run (the baseline // `update`/`check` diff from; set by scan.py --stamp-rev) - "htmlPath": "docs/architecture-map.html", // for reciprocal links - "mdPath": "docs/architecture-audit.md", + "htmlPath": ".codemap/architecture-map.html", // output location (for reciprocal links) + "mdPath": ".codemap/architecture-audit.md", "spineDesc": "A user edits … → … → persistence.", // shown on the spine view "tracked_loc": 184900, // filled by scan.py --write (union, de-duped) "tracked_files": 980, @@ -107,6 +107,6 @@ independent: a `core` module can be clean (A) and a `low` leaf can be broken (F) The scoring standard is data, not code: `reference/standard.json` holds the rubric, severities, coupling levels, and the issue `tags` (each `{id,label,labelZh,bad,en,zh}`). -A project overrides it at `/.claude/codemap/modules.json`'s sibling +A project overrides it at `/.codemap/modules.json`'s sibling `standard.json`. The map renders + lets you edit it on the **Standard** page (Export to save). Audits must use the project standard's tags when present — including custom ones.