forma-arch 0.2.0 → 0.3.0

package/README.md

@@ -25,11 +25,15 @@ npx forma-arch <command>        # or: npm i -D forma-arch
 | Command | What it does |
 |---|---|
 | `forma init` | Seed `docs/architecture/c4-topology.json` from your source dirs (best-effort; then curate) |
-| `forma gen` | Walk `src/` leaves + derive container edges from cross-references to exported symbol names → `c4-model.json` |
+| `forma gen` | Walk `src/` leaves + derive container edges from cross-references; fill box text from docstrings/READMEs; group flat containers into components → `c4-model.json` |
 | `forma check` | Deterministic drift check — **fails if the model no longer matches the code** |
-| `forma doc` | Project the arc42 scaffold (`ARCHITECTURE.scaffold.md`) from the model |
+| `forma doc` | Project the arc42 scaffold (`ARCHITECTURE.scaffold.md`), or `--attach <file>` to inject a governed block into an existing doc |
 | `forma serve` | Open the live explorer at `http://localhost:4173` |
 
+**Box text comes from your docs.** `gen` fills each box with the module's docstring (Python `"""…"""`, JS/TS leading block), else the directory `README.md`, else a mapped arc42 section — so the explorer shows meaning, not a list of symbols. On a flat directory of many `foo_*` files it also synthesizes a **component** layer (`--no-cluster` to disable).
+
+**One source of truth.** `forma doc --attach docs/architecture/arc42.md` injects the generated diagrams/tables between `<!-- forma:begin -->` / `<!-- forma:end -->` markers in your existing doc; your prose lives outside them, and `forma check` fails if that block drifts. Where a repo lacks docs, `forma gen --enrich` can fill the remaining box holes with an LLM (opt-in, cached, never on the deterministic gate; `--enricher anthropic|openai|ollama`).
+
 ## How it fits together
 
 ```

package/lib/check.mjs

@@ -6,6 +6,9 @@
 import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { containerOf } from './cluster.mjs'
+import { renderBlock, extractBetween, norm } from './render.mjs'
+import { descInputHash } from './enrich.mjs'
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 const arg = (f, d) => { const i = process.argv.indexOf(f); return i > -1 ? process.argv[i + 1] : d }
@@ -20,6 +23,7 @@ if (!existsSync(MODEL)) { console.error('[check-c4] FAIL: model missing (no SKIP
 if (!existsSync(TOPO)) { console.error('[check-c4] FAIL: topology missing: ' + TOPO); process.exit(1) }
 const model = JSON.parse(readFileSync(MODEL, 'utf-8'))
 const topo = JSON.parse(readFileSync(TOPO, 'utf-8'))
+const byId = new Map((model.nodes || []).map((n) => [n.id, n]))
 
 // 1) schemaVersion present + basic shape
 if (!/^\d+\.\d+\.\d+$/.test(model.schemaVersion || '')) fail('missing/invalid schemaVersion')
@@ -36,7 +40,7 @@ function walk(spec) {
 }
 for (const spec of topo.leafSources) {
   const live = walk(spec).length
-  const inModel = model.nodes.filter((n) => n.parent === spec.parent && n.kind === 'leaf' && n.status === 'current').length
+  const inModel = model.nodes.filter((n) => n.kind === 'leaf' && n.status === 'current' && containerOf(n, byId) === spec.parent).length
   if (live === 0) fail(`phantom parent "${spec.parent}": src glob ${spec.dir} matches 0 files`)
   if (live !== inModel) fail(`DRIFT: ${spec.parent} — src has ${live} files, model has ${inModel}. Regenerate c4-model.json.`)
 }
@@ -69,5 +73,26 @@ for (const p of topo.plannedLeaves || []) if (p.sourceMustContain) {
   if (!existsSync(f) || !readFileSync(f, 'utf-8').includes(p.sourceMustContain)) fail(`planned "${p.name}" premise broken in ${p.sourceRef}`)
 }
 
+// 6) attach-mode doc-block freshness — if docPath carries forma markers, the region between them
+// must equal a freshly rendered block. Opt-in: no markers → nothing runs. No LLM, no network.
+const docRel = model.source && model.source.docPath
+if (docRel && existsSync(rp(docRel))) {
+  const text = readFileSync(rp(docRel), 'utf-8')
+  const inner = extractBetween(text)
+  if (inner != null) {
+    if (norm(inner) !== norm(renderBlock(model, { repo: REPO }))) fail(`DOC BLOCK DRIFT: ${docRel} forma block is stale — run \`forma doc --attach\`.`)
+  } else if (text.includes('<!-- forma:begin') || text.includes('<!-- forma:end')) {
+    fail(`DOC BLOCK: malformed forma markers in ${docRel} (begin/end mismatch).`)
+  }
+}
+
+// SOFT: LLM-enriched prose whose inputs changed is only a reminder, never a gate failure (structure
+// is the gate; enrichment freshness is advisory). check never calls the LLM — it recomputes the hash.
+for (const n of model.nodes || []) {
+  if (n.descSource === 'llm' && n.descInputHash && n.descInputHash !== descInputHash(n, { repo: REPO, byId, containerOf })) {
+    console.warn(`[check-c4] note: enrichment stale for ${n.id} — run \`forma gen --enrich\` to refresh (non-blocking).`)
+  }
+}
+
 if (errs.length) { console.error('[check-c4] FAIL (' + errs.length + '):\n - ' + errs.join('\n - ')); process.exit(1) }
 console.log('[check-c4] OK — model is adherent to src/ (leaves, table count, evidence, planned premises all verified)')

package/lib/cluster.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// cluster.mjs — shared structural helpers for the C4 model. Pure, no side effects at import.
+// containerOf: climb the parent chain to the enclosing CONTAINER. Leaves may be re-parented under
+//   synthetic component nodes (§2), so "the container" is no longer simply node.parent.
+// componentsFor: deterministic prefix-cluster synthesis for flat containers (§2).
+
+const slug = (s) => String(s).toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_|_$/g, '') || 'x'
+
+// The id of the nearest container-kind ancestor (or self). byId = Map(id → node).
+export function containerOf(node, byId) {
+  let n = node, guard = 0
+  while (n && n.kind !== 'container' && n.parent && guard++ < 64) n = byId.get(n.parent)
+  return n ? n.id : null
+}
+
+// Group a flat container's leaves by common `foo_*` prefix. Deterministic: sorted group keys.
+// Returns { components: Node[], reparent: Map(leafId → componentId) }. Leftovers stay under the container.
+export function componentsFor(container, leaves, opts = {}) {
+  const groupMin = opts.groupMin || 3
+  const groups = new Map()
+  for (const l of leaves) {
+    const base = String(l.name)
+    const i = base.indexOf('_')
+    if (i <= 0) continue // no prefix (e.g. "health", "version") → stays flat
+    const prefix = base.slice(0, i)
+    if (!groups.has(prefix)) groups.set(prefix, [])
+    groups.get(prefix).push(l)
+  }
+  const keys = [...groups.keys()].filter((k) => groups.get(k).length >= groupMin).sort()
+  if (keys.length === 0) return { components: [], reparent: new Map() }
+  // no structural gain if a single surviving group swallows every leaf
+  const covered = keys.reduce((s, k) => s + groups.get(k).length, 0)
+  if (keys.length === 1 && covered === leaves.length) return { components: [], reparent: new Map() }
+  const components = [], reparent = new Map()
+  for (const k of keys) {
+    const cid = `${container.id}__grp__${slug(k)}`
+    components.push({
+      id: cid, level: 'component', kind: 'component', parent: container.id, name: k,
+      status: 'current', category: container.category || 'container',
+    })
+    for (const l of groups.get(k)) reparent.set(l.id, cid)
+  }
+  return { components, reparent }
+}

package/lib/describe.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// describe.mjs — deterministic description resolver (§1a). Pure parsing, NO network.
+// Fills a node's plain-language `func` from EXISTING docs (curated → docstring → README → arc42),
+// so boxes show MEANING, not a bare filename. A generated string is only the last resort.
+import { readFileSync, existsSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+
+const norm = (s) => String(s).toLowerCase().trim()
+
+// First non-empty paragraph, markdown/whitespace stripped, capped to the viewer's ~2-line clamp.
+const firstPara = (text) => {
+  let out = ''
+  for (const line of String(text).replace(/\r\n/g, '\n').split('\n')) {
+    const l = line.trim()
+    if (/^#{1,6}\s/.test(l)) continue // skip markdown headings
+    if (!l) { if (out) break; else continue } // blank ends the paragraph (once started)
+    out += (out ? ' ' : '') + l
+  }
+  out = out.replace(/[*_`>]+/g, '').replace(/\s+/g, ' ').trim()
+  return out ? out.slice(0, 240) : null
+}
+
+// ponytail: leading-block heuristic, no AST — a docstring placed AFTER code is missed.
+function moduleDocstring(absPath) {
+  let src; try { src = readFileSync(absPath, 'utf-8') } catch { return null }
+  const body = src.replace(/^/, '').replace(/^#![^\n]*\n/, '')
+  if (/\.py$/i.test(absPath)) {
+    const m = body.match(/^\s*(?:#[^\n]*\n\s*)*(?:r|u|b)?("""|''')([\s\S]*?)\1/i)
+    return m ? firstPara(m[2]) : null
+  }
+  if (/\.(mjs|cjs|js|jsx|ts|tsx|mts|cts)$/i.test(absPath)) {
+    const block = body.match(/^\s*\/\*\*?([\s\S]*?)\*\//)
+    if (block) return firstPara(block[1].replace(/^\s*\*\s?/gm, '').replace(/@\w+/g, ''))
+    const cmt = []
+    for (const l of body.replace(/^\s+/, '').split('\n')) { const t = l.trim(); if (t.startsWith('//')) cmt.push(t.replace(/^\/\/+\s?/, '')); else break }
+    return cmt.length ? firstPara(cmt.join(' ')) : null
+  }
+  return null
+}
+
+function readmeFirstPara(dir, cache) {
+  if (cache.has(dir)) return cache.get(dir)
+  let out = null
+  try { const p = join(dir, 'README.md'); if (existsSync(p)) out = firstPara(readFileSync(p, 'utf-8')) } catch {}
+  cache.set(dir, out)
+  return out
+}
+
+// Map(normalizedHeading → lead paragraph) from the mapped arc42 doc, read once. ponytail: exact
+// normalized-heading match, no fuzzy mapping.
+function buildArc42Index(repo, docPath) {
+  const idx = new Map()
+  if (!docPath) return idx
+  let text; try { text = readFileSync(join(repo, docPath), 'utf-8') } catch { return idx }
+  const parts = text.split(/^#{1,6}\s+(.+)$/m) // [pre, heading, body, heading, body, ...]
+  for (let i = 1; i < parts.length; i += 2) {
+    const lead = firstPara(parts[i + 1] || '')
+    if (parts[i] && lead) idx.set(norm(parts[i]), lead)
+  }
+  return idx
+}
+
+export function makeDescribeCtx({ repo, byId, descriptions, docPath, containerOf }) {
+  return { repo, byId, D: descriptions || {}, containerOf, readmeCache: new Map(), arc42: buildArc42Index(repo, docPath) }
+}
+
+// First hit wins. descSource records provenance for §7 enrichment + debugging.
+export function resolveDescription(node, ctx) {
+  const cont = ctx.containerOf(node, ctx.byId)
+  const stem = String(node.name).replace(/\.\w+$/, '').replace(/ .*/, '')
+  const key = cont ? `${cont}/${stem}` : null
+  if (key && ctx.D[key]) return { func: ctx.D[key], descSource: 'curated' }
+  if (node.description) return { func: node.description, descSource: 'curated' }
+  const pth = (node.evidence || []).find((e) => e.type === 'path')
+  if (pth) {
+    const abs = join(ctx.repo, pth.ref)
+    const ds = moduleDocstring(abs)
+    if (ds) return { func: ds, descSource: 'docstring' }
+    const rd = readmeFirstPara(dirname(abs), ctx.readmeCache)
+    if (rd) return { func: rd, descSource: 'readme' }
+  }
+  const a = ctx.arc42.get(norm(node.name)) || ctx.arc42.get(norm(node.id))
+  if (a) return { func: a, descSource: 'arc42' }
+  if (node.kind === 'leaf') {
+    const cn = (ctx.byId.get(cont) || {}).name || cont || node.parent
+    return { func: `Component of module ${cn}.`, descSource: 'fallback' }
+  }
+  if (node.kind === 'component') return { func: `Groups related files under ${node.name}.`, descSource: 'fallback' }
+  return { func: node.description || '', descSource: 'fallback' }
+}

package/lib/doc.mjs

@@ -4,8 +4,9 @@
 // are filled from the model — so they can never drift from it. The JUDGMENT sections (goals,
 // strategy, decisions, risks) are stubbed with TODO(forma) for a human/agent to write.
 // Output: docs/architecture/ARCHITECTURE.scaffold.md (never overwrites a real ARCHITECTURE.md).
-import { readFileSync, writeFileSync, existsSync, readdirSync } from 'node:fs'
-import { join, relative } from 'node:path'
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
+import { join, relative, isAbsolute } from 'node:path'
+import { renderParts, renderBlock, replaceBetween } from './render.mjs'
 
 const arg = (f, d) => { const i = process.argv.indexOf(f); return i > -1 ? process.argv[i + 1] : d }
 const REPO = arg('--repo', process.cwd())
@@ -13,38 +14,9 @@ const MODEL = arg('--model', join(REPO, 'docs/architecture/c4-model.json'))
 const OUT = arg('--out', join(REPO, 'docs/architecture/ARCHITECTURE.scaffold.md'))
 if (!existsSync(MODEL)) { console.error('[forma doc] model missing: ' + MODEL + ' — run `forma gen` first.'); process.exit(1) }
 const m = JSON.parse(readFileSync(MODEL, 'utf-8'))
-const byId = new Map(m.nodes.map((n) => [n.id, n]))
-const sid = (s) => String(s).replace(/[^A-Za-z0-9_]/g, '_')
-const name = (id) => (byId.get(id) || { name: id }).name
-const C4 = { person: 'Person', system: 'System', external: 'System_Ext', container: 'Container', component: 'Component', store: 'ContainerDb', boundary: 'Container_Boundary', leaf: 'Component' }
-const q = (s) => String(s == null ? '' : s).replace(/"/g, '')
-const el = (n) => `${C4[n.kind] || 'Container'}(${sid(n.id)}, "${q(n.name)}"${n.tech ? `, "${q(n.tech)}"` : ''})`
-const rels = (ids) => m.edges.filter((e) => ids.has(e.from) && ids.has(e.to)).map((e) => `  Rel(${sid(e.from)}, ${sid(e.to)}, "${(e.label || '').replace(/"/g, '')}")`).join('\n')
-
-// context = nodes with no parent
-const ctx = m.nodes.filter((n) => !n.parent)
-const ctxIds = new Set(ctx.map((n) => n.id))
-const contextDiagram = `\`\`\`mermaid\nC4Context\n  title System Context\n${ctx.map((n) => '  ' + el(n)).join('\n')}\n${rels(ctxIds)}\n\`\`\``
-
-// containers = children of the system node
-const sys = ctx.find((n) => n.kind === 'system') || ctx[0]
-const containers = m.nodes.filter((n) => n.parent === (sys && sys.id))
-const contIds = new Set(containers.map((n) => n.id))
-const containerDiagram = containers.length ? `\`\`\`mermaid\nC4Container\n  title Container view — ${sys.name}\n${containers.map((n) => '  ' + el(n)).join('\n')}\n${rels(contIds)}\n\`\`\`` : '_No containers in the model yet._'
-const leafCount = (id) => m.nodes.filter((n) => n.parent === id && n.kind === 'leaf').length
-const containerTable = containers.length
-  ? ['| Container | Tech | Leaves | What it does |', '|---|---|---|---|', ...containers.map((n) => `| ${n.name} | ${n.tech || '—'} | ${leafCount(n.id)} | ${(n.func || n.description || 'TODO(forma): describe').replace(/\n/g, ' ')} |`)].join('\n')
-  : '_No containers yet._'
-
-// ADR index if present
-const adrDir = join(REPO, 'docs/adr')
-let adrs = '_No `docs/adr/` found — record decisions as ADRs._'
-if (existsSync(adrDir)) {
-  const files = readdirSync(adrDir).filter((f) => /\.md$/.test(f) && !/readme|template/i.test(f)).sort()
-  if (files.length) adrs = files.map((f) => { const t = (readFileSync(join(adrDir, f), 'utf-8').match(/^#\s+(.+)/m) || [, f])[1]; return `- [${t}](../adr/${f})`; }).join('\n')
-}
-
-const stack = (m.meta && m.meta.stack) || (sys && sys.tech) || 'TODO'
+// Deterministic, model-derived sections come from the shared side-effect-free renderer, so
+// `forma doc` (writer) and `forma check` (attach freshness gate) render the block identically.
+const { contextDiagram, containerTable, containerDiagram, adrs, stack, sys, containers } = renderParts(m, { repo: REPO })
 const TODO = (s) => `> TODO(forma): ${s}`
 const md = `<!-- forma: arc42 scaffold projected from c4-model.json. Deterministic sections are generated;
      do not edit them by hand — re-run \`forma doc\`. Fill the TODO(forma) prose, then promote to ARCHITECTURE.md. -->
@@ -96,6 +68,24 @@ ${TODO('known risks and debt, with links to any register.')}
 ## 12. Glossary
 ${TODO('domain and project terms.')}
 `
+// --attach <file>: inject the deterministic block between sentinel markers in an EXISTING doc
+// (default: model.source.docPath), leaving human prose outside the markers untouched. `forma check`
+// then governs that block. Default (no --attach) writes the standalone scaffold, exactly as before.
+const attachIdx = process.argv.indexOf('--attach')
+if (attachIdx > -1) {
+  const next = process.argv[attachIdx + 1]
+  let target = (next && !next.startsWith('--')) ? next : (m.source && m.source.docPath)
+  if (!target) { console.error('[forma doc] --attach: no target (pass a file or set docPath in the model)'); process.exit(1) }
+  target = isAbsolute(target) ? target : join(REPO, target)
+  const prior = existsSync(target) ? readFileSync(target, 'utf-8') : ''
+  let out
+  try { out = replaceBetween(prior, renderBlock(m, { repo: REPO })) }
+  catch { console.error('[forma doc] --attach: malformed forma markers in ' + relative(REPO, target) + ' — fix by hand'); process.exit(1) }
+  mkdirSync(join(target, '..'), { recursive: true })
+  writeFileSync(target, out)
+  console.log(`[forma doc] spliced generated block into ${relative(REPO, target)} — ${containers.length} container(s); prose outside the markers untouched.`)
+  process.exit(0)
+}
 writeFileSync(OUT, md)
 console.log(`[forma doc] wrote ${relative(REPO, OUT)} — ${containers.length} container(s), context + container diagrams from the model.`)
 console.log('[forma doc] deterministic sections filled; write the TODO(forma) prose, then promote to ARCHITECTURE.md.')

package/lib/gen.mjs

@@ -6,13 +6,21 @@ import { readFileSync, writeFileSync, readdirSync, existsSync, statSync } from '
 import { join, dirname, basename, relative } from 'node:path'
 import { execSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
+import { containerOf, componentsFor } from './cluster.mjs'
+import { makeDescribeCtx, resolveDescription } from './describe.mjs'
+import { loadCache, mergeCache, enrich } from './enrich.mjs'
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 const arg = (f, d) => { const i = process.argv.indexOf(f); return i > -1 ? process.argv[i + 1] : d }
 const REPO = arg('--repo', process.cwd())
 const TOPO = arg('--topology', join(REPO, 'docs/architecture/c4-topology.json'))
 const OUT = arg('--out', join(REPO, 'docs/architecture/c4-model.json'))
-const SCHEMA_VERSION = '1.1.0'
+const SCHEMA_VERSION = '1.2.0'
+const CLUSTER = !process.argv.includes('--no-cluster') // §2: auto-cluster flat containers; --no-cluster to disable
+const ENRICH = process.argv.includes('--enrich')       // §7: opt-in LLM prose for description holes
+const ENRICHER = arg('--enricher', 'anthropic')
+const ENRICH_MODEL = arg('--enrich-model', null)
+const CLUSTER_MIN = 8, GROUP_MIN = 3
 
 const topo = JSON.parse(readFileSync(TOPO, 'utf-8'))
 const rp = (p) => join(REPO, p)
@@ -86,6 +94,20 @@ for (const p of topo.plannedLeaves || []) {
         evidence: [{ type: 'doc', ref: p.sourceRef }] })
 }
 
+// §2) synthesize a component layer for flat containers (auto; --no-cluster to disable).
+// Runs BEFORE the enrich/func loops so components inherit category/status/func. Leaves that
+// join a component are re-parented to it; containerOf() keeps edge/check logic container-scoped.
+if (CLUSTER) for (const cid of [...new Set(topo.leafSources.map((s) => s.parent))]) {
+  const container = byId.get(cid); if (!container) continue
+  const leaves = nodes.filter((n) => n.kind === 'leaf' && n.parent === cid) // pre-reparent: plain filter valid here
+  if (leaves.length <= CLUSTER_MIN) continue
+  const { components, reparent } = componentsFor(container, leaves, { groupMin: GROUP_MIN })
+  if (!components.length) { console.log(`[gen-c4] container ${cid}: ${leaves.length} leaf non-clusterable (flat)`); continue }
+  for (const c of components) add(c)
+  for (const n of leaves) { const to = reparent.get(n.id); if (to) n.parent = to }
+  console.log(`[gen-c4] container ${cid}: clustered ${leaves.length} leaves into ${components.length} component(s)`)
+}
+
 // enrich: fill hologram defaults (category, 5-status, completion, current/target) where absent
 for (const n of nodes) {
   const par = n.parent ? byId.get(n.parent) : null
@@ -96,11 +118,19 @@ for (const n of nodes) {
   if (n.target == null) n.target = ''
 }
 
-// func: plain-language "what it does" (non-dev). Leaves from the descriptions map; else the description.
-const D = topo.descriptions || {}
-for (const n of nodes) {
-  const key = n.parent ? `${n.parent}/${String(n.name).replace(/\.\w+$/, '').replace(/ .*/, '')}` : null
-  n.func = (key && D[key]) || n.description || (n.kind === 'leaf' ? `Component of module ${(byId.get(n.parent) || {}).name || n.parent}.` : '')
+// §1a) func: plain-language "what it does" resolved from existing docs (curated → docstring → README
+// → arc42 → generated fallback), with provenance in descSource. No LLM here — pure parsing.
+const dctx = makeDescribeCtx({ repo: REPO, byId, descriptions: topo.descriptions || {}, docPath: topo.docPath, containerOf })
+for (const n of nodes) { const r = resolveDescription(n, dctx); n.func = r.func; n.descSource = r.descSource }
+
+// §7) enrichment (prose only, never structure/gate). Cache-merge ALWAYS: preserve prior LLM prose
+// whose inputs are unchanged, so a plain regen doesn't discard it. --enrich additionally fills the
+// remaining holes over the network (best-effort — a failure keeps the deterministic fallback).
+const ectx = { repo: REPO, byId, containerOf }
+mergeCache(nodes, ectx, loadCache(OUT))
+if (ENRICH) {
+  try { const r = await enrich(nodes, ectx, { provider: ENRICHER, model: ENRICH_MODEL }); console.log(`[gen-c4] --enrich (${ENRICHER}): filled ${r.filled}/${r.holes} description hole(s)`) }
+  catch (e) { console.error('[gen-c4] --enrich skipped: ' + String((e && e.message) || e)) }
 }
 
 // 4b) derive container↔container edges from REAL code references (deterministic, additive).
@@ -113,7 +143,7 @@ if (!process.argv.includes('--no-auto-edges')) {
   const srcs = (topo.leafSources || []).filter((s) => byId.has(s.parent))
   const exposes = new Map(), text = new Map()
   for (const s of srcs) {
-    exposes.set(s.parent, [...new Set(nodes.filter((n) => n.parent === s.parent && n.kind === 'leaf')
+    exposes.set(s.parent, [...new Set(nodes.filter((n) => n.kind === 'leaf' && containerOf(n, byId) === s.parent)
       .map((n) => String(n.name)).filter((nm) => nm.length >= 5 && !STOP.has(nm.toLowerCase())))])
     let t = ''; const dir = rp(s.dir)
     try { for (const f of readdirSync(dir)) { const fp = join(dir, f); if (statSync(fp).isFile()) t += '\n' + readFileSync(fp, 'utf-8') } } catch {}

package/lib/init.mjs

@@ -11,6 +11,12 @@ const REPO = arg('--repo', process.cwd())
 const OUT = arg('--out', join(REPO, 'docs/architecture/c4-topology.json'))
 const FORCE = process.argv.includes('--force')
 const IGNORE = new Set(['node_modules', '.git', 'dist', 'build', 'target', 'out', 'vendor', 'coverage', '.next', '.gradle', 'bin', 'obj'])
+// A real directory that holds files but is not an architecture container (data/fixtures/docs).
+// Kept separate from IGNORE (which is build/VCS junk, invisible even to language detection).
+const DATA_DIRS = new Set(['docs', 'fixtures', 'testdata', 'demo', 'corpus', 'assets', 'examples'])
+const SKIP_TESTS = process.argv.includes('--skip-tests') // test/ is real code by default; opt in to skip it
+const KEEP = new Set((arg('--include', '') || '').split(',').map((s) => s.trim().toLowerCase()).filter(Boolean))
+const SKIP_DIRS = new Set([...DATA_DIRS, ...(SKIP_TESTS ? ['test', 'tests'] : [])])
 const EXT = { ts: 'TypeScript', tsx: 'TypeScript', js: 'JavaScript', jsx: 'JavaScript', mjs: 'JavaScript', cjs: 'JavaScript', mts: 'TypeScript', cts: 'TypeScript', py: 'Python', go: 'Go', java: 'Java', rs: 'Rust', rb: 'Ruby', php: 'PHP', cs: 'C#', kt: 'Kotlin', swift: 'Swift', cpp: 'C++', c: 'C' }
 const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_|_$/g, '') || 'x'
 
@@ -58,6 +64,7 @@ const hasSrc = (dir) => { try { return readdirSync(dir).some((f) => { const p =
 // (A dir with direct sources is a container; a dir with none is descended into. Works for nested
 // layouts like src/app/routes/*.ts or Python packages, not just one level.)
 const seen = new Set()
+const skipped = []
 ;(function findContainers(dir, depth) {
   if (depth > 10) return
   let ents; try { ents = readdirSync(dir) } catch { return }
@@ -65,6 +72,7 @@ const seen = new Set()
     const p = join(dir, e)
     let st; try { st = statSync(p) } catch { continue }
     if (!st.isDirectory()) continue
+    if (SKIP_DIRS.has(e.toLowerCase()) && !KEEP.has(e.toLowerCase())) { skipped.push({ dir: relative(REPO, p), reason: 'data/fixtures/docs dir (name match) — curate if wrong' }); continue }
     if (hasSrc(p)) {
       const rel = relative(root, p) || e
       let id = slug(rel.replace(/[\\/]+/g, '_'))
@@ -88,9 +96,10 @@ const topo = {
   leafSources,
   edges: [],
   descriptions: {},
+  _skipped: skipped,
 }
 // ensure output dir exists
 mkdirSync(join(OUT, '..'), { recursive: true })
 writeFileSync(OUT, JSON.stringify(topo, null, 2) + '\n')
-console.log(`[forma init] wrote ${relative(REPO, OUT)} — ${lang}, ${leafSources.length} container(s) seeded from ${relative(REPO, root) || '.'}/`)
+console.log(`[forma init] wrote ${relative(REPO, OUT)} — ${lang}, ${leafSources.length} container(s) seeded from ${relative(REPO, root) || '.'}/${skipped.length ? `, ${skipped.length} data/doc dir(s) skipped` : ''}`)
 console.log('[forma init] NEXT: curate names/descriptions + add context externals + run `forma gen`.')

package/lib/render.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// render.mjs — pure, side-effect-free renderers for the arc42 projection.
+// Shared by `forma doc` (writer) and `forma check` (attach-mode freshness gate) so both render the
+// governed block identically. NO writeFileSync / console / process at module scope.
+import { readFileSync, existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { containerOf } from './cluster.mjs'
+
+export const BEGIN = '<!-- forma:begin (generated — do not edit) -->'
+export const END = '<!-- forma:end -->'
+
+// The deterministic, model-derived parts (never the TODO judgment prose, never volatile fields).
+export function renderParts(model, opts = {}) {
+  const repo = opts.repo || process.cwd()
+  const m = model
+  const byId = new Map(m.nodes.map((n) => [n.id, n]))
+  const sid = (s) => String(s).replace(/[^A-Za-z0-9_]/g, '_')
+  const C4 = { person: 'Person', system: 'System', external: 'System_Ext', container: 'Container', component: 'Component', store: 'ContainerDb', boundary: 'Container_Boundary', leaf: 'Component' }
+  const q = (s) => String(s == null ? '' : s).replace(/"/g, '')
+  const el = (n) => `${C4[n.kind] || 'Container'}(${sid(n.id)}, "${q(n.name)}"${n.tech ? `, "${q(n.tech)}"` : ''})`
+  const rels = (ids) => m.edges.filter((e) => ids.has(e.from) && ids.has(e.to)).map((e) => `  Rel(${sid(e.from)}, ${sid(e.to)}, "${(e.label || '').replace(/"/g, '')}")`).join('\n')
+
+  const ctx = m.nodes.filter((n) => !n.parent)
+  const ctxIds = new Set(ctx.map((n) => n.id))
+  const contextDiagram = `\`\`\`mermaid\nC4Context\n  title System Context\n${ctx.map((n) => '  ' + el(n)).join('\n')}\n${rels(ctxIds)}\n\`\`\``
+
+  const sys = ctx.find((n) => n.kind === 'system') || ctx[0]
+  const containers = m.nodes.filter((n) => n.parent === (sys && sys.id))
+  const contIds = new Set(containers.map((n) => n.id))
+  const containerDiagram = containers.length ? `\`\`\`mermaid\nC4Container\n  title Container view — ${sys.name}\n${containers.map((n) => '  ' + el(n)).join('\n')}\n${rels(contIds)}\n\`\`\`` : '_No containers in the model yet._'
+  const leafCount = (id) => m.nodes.filter((n) => n.kind === 'leaf' && containerOf(n, byId) === id).length
+  const containerTable = containers.length
+    ? ['| Container | Tech | Leaves | What it does |', '|---|---|---|---|', ...containers.map((n) => `| ${n.name} | ${n.tech || '—'} | ${leafCount(n.id)} | ${(n.func || n.description || 'TODO(forma): describe').replace(/\n/g, ' ')} |`)].join('\n')
+    : '_No containers yet._'
+
+  const adrDir = join(repo, 'docs/adr')
+  let adrs = '_No `docs/adr/` found — record decisions as ADRs._'
+  if (existsSync(adrDir)) {
+    const files = readdirSync(adrDir).filter((f) => /\.md$/.test(f) && !/readme|template/i.test(f)).sort()
+    if (files.length) adrs = files.map((f) => { const t = (readFileSync(join(adrDir, f), 'utf-8').match(/^#\s+(.+)/m) || [, f])[1]; return `- [${t}](../adr/${f})`; }).join('\n')
+  }
+  const stack = (m.meta && m.meta.stack) || (sys && sys.tech) || 'TODO'
+  return { contextDiagram, containerTable, containerDiagram, adrs, stack, sys, containers }
+}
+
+// The governed region injected between the sentinel markers (deterministic subset only).
+export function renderBlock(model, opts = {}) {
+  const p = renderParts(model, opts)
+  return [
+    '### Context', '', p.contextDiagram, '',
+    '### Building blocks', '', p.containerTable, '', p.containerDiagram, '',
+    '### Architecture decisions', '', p.adrs,
+  ].join('\n')
+}
+
+// Comparison normalizer: CRLF→LF, strip trailing whitespace, trim surrounding blank lines.
+export const norm = (s) => String(s).replace(/\r\n/g, '\n').replace(/[ \t]+$/gm, '').replace(/^\n+|\n+$/g, '')
+
+// Inner content between markers, or null unless BOTH are present and ordered.
+export function extractBetween(text) {
+  const b = text.indexOf(BEGIN), e = text.indexOf(END)
+  if (b === -1 || e === -1 || e < b) return null
+  return text.slice(b + BEGIN.length, e)
+}
+
+// Splice the block between markers; append at EOF (creating them) if absent; throw if exactly one present.
+export function replaceBetween(text, block) {
+  const b = text.indexOf(BEGIN), e = text.indexOf(END)
+  const body = `${BEGIN}\n\n${block}\n\n${END}`
+  if (b !== -1 && e !== -1 && e > b) return text.slice(0, b) + body + text.slice(e + END.length)
+  if (b !== -1 || e !== -1) throw new Error('malformed forma markers')
+  const sep = text && !text.endsWith('\n') ? '\n\n' : (text ? '\n' : '')
+  return text + sep + body + '\n'
+}

package/lib/schema/c4-model.schema.json

@@ -203,6 +203,22 @@
           "func": {
             "type": "string",
             "description": "Plain-language 'what it does' for non-developers."
+          },
+          "descSource": {
+            "type": "string",
+            "enum": [
+              "curated",
+              "docstring",
+              "readme",
+              "arc42",
+              "fallback",
+              "llm"
+            ],
+            "description": "Provenance of func: how the description was resolved (§1a chain; 'llm' = optional enrichment)."
+          },
+          "descInputHash": {
+            "type": "string",
+            "description": "sha256 of the inputs that produced an LLM-enriched func; check recomputes it to flag stale prose."
           }
         }
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forma-arch",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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",