forma-arch 0.7.0 → 0.7.2

package/README.md

@@ -61,7 +61,7 @@ Column roles are detected by header name (`capability`/`feature`/`description`
   "verify": { "source": "ADR-040 on main" }, "issues": ["#534"] } } }
 ```
 
-The overlay is the authority: every field it sets wins over anything derived, and `check` stops re-deriving that field. To describe one box by hand without a table, put the sentence in `descriptions`, keyed `"<containerId>/<node-name-without-extension>"` — `"core/alpha"` for the leaf `alpha.js` in container `core`, `"core/core"` for the container itself, since a container is its own container. It outranks every other source.
+The overlay is the authority: every field it sets wins over anything derived, and `check` stops re-deriving that field. You do not have to hand-edit that JSON — `forma gen --status-apply <file>` merges `{"nodes":{"<id>":{…}}}` into it, validating every patch **before** it touches disk, so a rejected fill leaves the committed overlay untouched. It is the state counterpart of `--enrich-apply`, for the fields no document can supply. To describe one box by hand without a table, put the sentence in `descriptions`, keyed `"<containerId>/<node-name-without-extension>"` — `"core/alpha"` for the leaf `alpha.js` in container `core`, `"core/core"` for the container itself, since a container is its own container. It outranks every other source.
 
 **Curated state, verified against reality.** `forma verify` asks your `gh` CLI for the state of every issue the model references (`--gh-repo owner/repo`, or `meta.ghRepo` in the topology), marks the nodes whose issues are closed as done, and prefixes their `current` with dated evidence. It touches state, never structure, and re-running it never stacks the evidence. It is opt-in and separate on purpose: `gen` and `check` never open a socket. In the served viewer, **RE-VERIFY** re-reads the model without losing your level, layout or mode.
 

package/lib/gen.mjs

@@ -2,7 +2,7 @@
 // gen-c4-model.mjs — emit docs/architecture/c4-model.json from real code + curated topology.
 // Leaves are walked LIVE from src/ (always current). Topology/context/runtime-edges are curated.
 // Usage: node gen-c4-model.mjs [--repo <path>] [--topology <path>] [--out <path>]
-import { readFileSync, writeFileSync, readdirSync, existsSync, statSync } from 'node:fs'
+import { readFileSync, writeFileSync, readdirSync, existsSync, statSync, mkdirSync } from 'node:fs'
 import { join, dirname, basename, relative } from 'node:path'
 import { execSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
@@ -26,6 +26,7 @@ const ENRICH_MODEL = arg('--enrich-model', null)
 const STATUS = arg('--status', join(REPO, 'docs/architecture/c4-status.json')) // curated programme state, optional
 const STATUS_SET = process.argv.includes('--status')
 const APPLY = arg('--enrich-apply', null)          // prose written by the agent driving forma
+const STATUS_APPLY = arg('--status-apply', null)   // §WP-A7: programme STATE written by that agent
 
 const topo = JSON.parse(readFileSync(TOPO, 'utf-8'))
 const rp = (p) => join(REPO, p)
@@ -134,8 +135,12 @@ if (docRows.length) console.log(`[gen-c4] docSources: ${docRows.length} row(s)
 
 // enrich: fill hologram defaults (category, 6-status, completion, current/target) where absent
 for (const n of nodes) {
-  const par = n.parent ? byId.get(n.parent) : null
-  if (!n.category) n.category = n.kind === 'leaf' ? (par && par.category) || 'leaf' : n.kind
+  // A leaf's category is the CONTAINER it belongs to, not its parent's category. Inheriting the
+  // parent's handed every leaf in the repo the literal string "container", and the viewer's
+  // catalogue collapse groups childless siblings BY CATEGORY — so a repo's leaves collapsed into a
+  // single box labelled "container" (53 of them on the Go repo this was measured on). With the real
+  // container they group the way that feature was written for, or stay apart when they belong apart.
+  if (!n.category) n.category = n.kind === 'leaf' ? (byId.get(containerOf(n, byId)) || {}).name || 'leaf' : n.kind
   // Progress a DOCUMENT states outright — the only generated alternative to hand-writing the
   // overlay. Derived, so it is re-derived by `check` rather than trusted; the curated overlay
   // (§WP-A1, applied further down) still overrides every field of it.
@@ -177,6 +182,53 @@ for (const n of nodes) {
 // what a module DOES comes from its docs (§1a), what it's WORTH is programme state.
 const STATUS_FIELDS = new Set(['status2', 'completion', 'statusWord', 'current', 'target', 'verify', 'issues'])
 const STATUS2 = new Set(['done', 'in-progress', 'next', 'planned', 'problem'])
+// One validator, two callers: the overlay FILE below, and --status-apply just above it. A writer
+// that validated differently from the reader would commit a c4-status.json the very next `gen`
+// rejects. Returns the complaints; the caller decides whether that is a fail or a refusal to write.
+function statusPatchErrors(id, patch, known) {
+  const out = []
+  if (!known(id)) out.push(`unknown node id "${id}" — it is not in the model (stale overlay?)`)
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) return [...out, `"${id}" must map to an object of state fields`]
+  for (const [k, v] of Object.entries(patch)) {
+    if (k.startsWith('$')) continue // $comment and friends
+    if (!STATUS_FIELDS.has(k)) { out.push(`"${id}" has field "${k}"; allowed: ${[...STATUS_FIELDS].join(', ')}${k === 'func' ? ' (func comes from the docs, not the overlay)' : ''}`); continue }
+    if (k === 'status2' && !STATUS2.has(v)) out.push(`"${id}" status2 "${v}" — expected one of ${[...STATUS2].join('|')}`)
+    if (k === 'completion' && !(Number.isInteger(v) && v >= 0 && v <= 100)) out.push(`"${id}" completion must be an integer 0-100, got ${JSON.stringify(v)}`)
+    if (k === 'issues') {
+      if (!Array.isArray(v)) out.push(`"${id}" issues must be an array`)
+      else for (const is of v) if (!/^#?\d+$/.test(String(is))) out.push(`"${id}" issue ${JSON.stringify(is)} — expected "#123"`)
+    }
+  }
+  return out
+}
+
+// §WP-A7) --status-apply: the WRITER the overlay never had. `c4-status.json` is the authority —
+// every field it sets outranks anything §17 derives from a document — and nothing in the repo has
+// ever written one, so on a fresh repo the authority channel was reachable only by hand-editing
+// JSON. This is the state counterpart of `--enrich-apply`: an agent or a human hands in the fields
+// a document cannot supply, and they land in the curated file, reviewed in the diff like any other.
+if (STATUS_APPLY) {
+  if (!existsSync(STATUS_APPLY)) fail(`--status-apply: file missing: ${STATUS_APPLY}`)
+  let incoming
+  try { incoming = JSON.parse(readFileSync(STATUS_APPLY, 'utf-8')).nodes } catch (e) { fail(`--status-apply: ${STATUS_APPLY} is not valid JSON: ${(e && e.message) || e}`) }
+  if (!incoming || typeof incoming !== 'object' || Array.isArray(incoming)) fail(`--status-apply: ${STATUS_APPLY} must contain {"nodes":{"<id>":{…}}}`)
+  // Validate EVERYTHING before touching disk. A half-written overlay is a file the next `gen`
+  // refuses to read, in a repo where that file is committed.
+  const errs = Object.entries(incoming).flatMap(([id, patch]) => statusPatchErrors(id, patch, (x) => byId.has(x)))
+  if (errs.length) fail(`--status-apply: ${STATUS_APPLY} rejected, ${relative(REPO, STATUS)} left untouched:\n - ` + errs.join('\n - '))
+  let base = { nodes: {} }
+  if (existsSync(STATUS)) {
+    try { base = JSON.parse(readFileSync(STATUS, 'utf-8')) } catch (e) { fail(`--status-apply: existing ${relative(REPO, STATUS)} is not valid JSON: ${(e && e.message) || e}`) }
+    base.nodes = base.nodes || {}
+  }
+  for (const [id, patch] of Object.entries(incoming)) base.nodes[id] = { ...(base.nodes[id] || {}), ...patch }
+  // The first apply on a repo IS the one that creates the overlay, and a repo that has never run
+  // `forma doc` has no docs/architecture/ to create it in.
+  mkdirSync(dirname(STATUS), { recursive: true })
+  writeFileSync(STATUS, JSON.stringify(base, null, 2) + '\n')
+  console.log(`[gen-c4] --status-apply: ${Object.keys(incoming).length} node(s) merged into ${relative(REPO, STATUS)}`)
+}
+
 let statusPath = null
 if (existsSync(STATUS) || STATUS_SET) {
   if (!existsSync(STATUS)) fail(`--status: file missing: ${STATUS}`)
@@ -184,19 +236,10 @@ if (existsSync(STATUS) || STATUS_SET) {
   try { ov = JSON.parse(readFileSync(STATUS, 'utf-8')) } catch (e) { fail(`--status: ${STATUS} is not valid JSON: ${(e && e.message) || e}`) }
   let decorated = 0
   for (const [id, patch] of Object.entries(ov.nodes || {})) {
+    const errs = statusPatchErrors(id, patch, (x) => byId.has(x))
+    if (errs.length) fail('status overlay: ' + errs.join('\n[gen-c4] FAIL: status overlay: '))
     const target = byId.get(id)
-    if (!target) fail(`status overlay: unknown node id "${id}" — it is not in the model (stale overlay?)`)
-    for (const [k, v] of Object.entries(patch)) {
-      if (k.startsWith('$')) continue // $comment and friends
-      if (!STATUS_FIELDS.has(k)) fail(`status overlay: "${id}" has field "${k}"; allowed: ${[...STATUS_FIELDS].join(', ')}${k === 'func' ? ' (func comes from the docs, not the overlay)' : ''}`)
-      if (k === 'status2' && !STATUS2.has(v)) fail(`status overlay: "${id}" status2 "${v}" — expected one of ${[...STATUS2].join('|')}`)
-      if (k === 'completion' && !(Number.isInteger(v) && v >= 0 && v <= 100)) fail(`status overlay: "${id}" completion must be an integer 0-100, got ${JSON.stringify(v)}`)
-      if (k === 'issues') {
-        if (!Array.isArray(v)) fail(`status overlay: "${id}" issues must be an array`)
-        for (const is of v) if (!/^#?\d+$/.test(String(is))) fail(`status overlay: "${id}" issue ${JSON.stringify(is)} — expected "#123"`)
-      }
-      target[k] = v
-    }
+    for (const [k, v] of Object.entries(patch)) { if (!k.startsWith('$')) target[k] = v }
     decorated++
   }
   statusPath = relative(REPO, STATUS)

package/lib/init.mjs

@@ -5,6 +5,7 @@
 // existing topology unless --force.
 import { readdirSync, statSync, existsSync, writeFileSync, mkdirSync } from 'node:fs'
 import { join, relative, basename } from 'node:path'
+import { execFileSync } from 'node:child_process'
 import { goPackages } from './lang.mjs'
 import { loadDocRows } from './docmap.mjs'
 
@@ -132,8 +133,19 @@ const docSources = []
   }
 })(join(REPO, 'docs'), 0)
 
+// `forma verify` is the one command that derives progress from something other than a claim in a
+// document — the live state of a GitHub issue — and it needs `meta.ghRepo` to know where to look.
+// `init` never wrote it, so on a freshly seeded repo verify had nowhere to point and exited. The
+// remote already says it. Handles scp-style (git@host:owner/repo.git) and URL remotes alike.
+const ghRepo = (() => {
+  let url
+  try { url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd: REPO, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() } catch { return null }
+  const m = /(?:github\.com[:/])([^/]+\/[^/]+?)(?:\.git)?$/.exec(url)
+  return m ? m[1] : null
+})()
+
 const topo = {
-  meta: { repo: basename(REPO), stack: lang, seededBy: 'forma init' },
+  meta: { repo: basename(REPO), stack: lang, seededBy: 'forma init', ...(ghRepo ? { ghRepo } : {}) },
   docPath: 'docs/architecture/ARCHITECTURE.md',
   levels: ['context', 'container', 'component', 'leaf'],
   nodes,

package/lib/viewer/c4-hologram.html

@@ -225,6 +225,21 @@ var LABEL_AUTO_MAX=14;    // above this many arrows in the current level, fixed
 var LABELS=null;          // null = auto (by arrow count); true/false = user override for this session
 var SKINS=[["holo","◆ holo"],["blueprint","▭ blueprint"]], SKIN_IDS=["holo","blueprint"];
 var STMAP={done:"done","in-progress":"prog",next:"next",planned:"plan",problem:"prob",unknown:"unk"};
+// The per-level tally. The mean is over the nodes that CARRY a completion, and it reports how many
+// those were: on a real Go repo, 25 containers at 100% next to 28 nobody has ruled on rendered as
+// "progress 100%" — the invented green this tool exists to kill, in the one number a stakeholder
+// reads first. Dividing by every child instead would be the mirror lie: a node with no verdict is
+// not 0% done, which is exactly why `gen` refuses to write a completion nobody curated. So the
+// percentage keeps its honest denominator and shows it.
+function tallyOf(kids){
+ var cnt={},tot=0,sum=0,nc=0,st3,j;
+ for(j=0;j<kids.length;j++){
+  st3=STMAP[kids[j].status2]||(kids[j].status==="planned"?"plan":"unk");
+  cnt[st3]=(cnt[st3]||0)+1;tot++;
+  if(kids[j].completion!=null){sum+=(+kids[j].completion||0);nc++;}
+ }
+ return {cnt:cnt,tot:tot,ruled:nc,mean:nc?Math.round(sum/nc):null};
+}
 var M=null, stack=[null], mode="now", POS={}, drag=null, justDragged=false, CATNODES={}, FETCHED=false
 var VBOX={}; // last fitted viewBox per level — frozen while dragging so the canvas does not rescale
 function $(i){return document.getElementById(i)}
@@ -414,19 +429,15 @@ function draw(animate){
  var lvlIdx=((M.levels||[]).indexOf(lvlKey));
  var cb=(lvlIdx>-1?STR.crumbLevel+"-L"+(lvlIdx+1):STR.crumbLevel)+" · "+lvl.toUpperCase()+"  &nbsp;&nbsp; <a data-d='-1'>"+esc(STR.crumbRoot)+"</a>";
  for(var w=0;w<chain.length;w++)cb+=" &rsaquo; "+(w===chain.length-1?"<b>"+esc(chain[w].name)+"</b>":"<a data-d='"+w+"'>"+esc(chain[w].name)+"</a>");
- // Per-level programme tally — the status-board essence in one glance: the status mix of THIS
- // view plus mean completion. Counts use the real children (a collapsed catalogue still counts
- // its members), so the tally never changes when the catalogue threshold does.
- var cnt={},tot=0,sum=0,nc=0,st3;
- for(j=0;j<realKids.length;j++){
-  st3=STMAP[realKids[j].status2]||(realKids[j].status==="planned"?"plan":"unk");
-  cnt[st3]=(cnt[st3]||0)+1;tot++;
-  if(realKids[j].completion!=null){sum+=(+realKids[j].completion||0);nc++;}
- }
- if(tot){
+ // Per-level programme tally — the status-board essence in one glance. Counts use the real
+ // children (a collapsed catalogue still counts its members), so the tally never changes when the
+ // catalogue threshold does.
+ var T=tallyOf(realKids);
+ if(T.tot){
   var DOT={done:"#2fe08a",prog:"#ffc74d",next:"#3ee7ff",plan:"#2d5a72",prob:"#ff5d5d",unk:"#7d8f99"},ord=["done","prog","next","plan","prob","unk"],agg="";
-  for(j=0;j<ord.length;j++)if(cnt[ord[j]])agg+='<i style="background:'+DOT[ord[j]]+'"></i>'+cnt[ord[j]];
-  if(nc)agg+=' &nbsp;'+esc(STR.aggProgress)+' <b>'+Math.round(sum/nc)+'%</b>';
+  for(j=0;j<ord.length;j++)if(T.cnt[ord[j]])agg+='<i style="background:'+DOT[ord[j]]+'"></i>'+T.cnt[ord[j]];
+  // The coverage rides WITH the percentage, never without it. See tallyOf.
+  if(T.ruled)agg+=' &nbsp;'+esc(STR.aggProgress)+' <b>'+T.mean+'%</b> '+T.ruled+'/'+T.tot;
   cb='<span class="agg">'+agg+'</span>'+cb;
  }
  $("crumb").innerHTML=cb;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forma-arch",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Forma — present your architecture instead of slides. An interactive, stack-agnostic C4 explorer (context → container → component → leaf) generated from your code and kept true to it by a deterministic drift check.",
   "keywords": [
     "architecture",