forma-arch 0.11.0 → 0.11.2

package/README.md

@@ -9,16 +9,19 @@ Forma is the companion to `arbiter`: arbiter governs the process, Forma shows th
 guarantees the picture matches reality.
 
 **[▶ Live demo](https://LucaDominici.github.io/forma/)** — **not** this repo. It is `haben`, a
-private 53-package Go application, generated by forma at haben commit `b1bb318`: six domains over
-53 packages, 192 edges read from real `import` blocks, and box text quoted from that repo's own
-feature matrix. A tool proving itself on its own 28 nodes proves nothing you care about.
+private 53-package Go application, generated by forma at haben commit `4c9b6880`: six domains over
+53 packages, 193 edges read from real `import` blocks, and box text quoted from that repo's own
+feature matrix. Its five-checkpoint architecture timeline is governed by haben's current product
+boundary: the 63-node AS-IS baseline grows cumulatively to 66 nodes and 196 edges, while the final
+operational checkpoint honestly reports no architecture change. A tool proving itself on its own
+28 nodes proves nothing you care about.
 
 What you are looking at is checked, not asserted: at that commit `node scripts/presentable.mjs`
 exits 0 on the model — every level under 24 boxes, every box carrying prose rather than a file
 count, every level with more than one box drawing at least one arrow — and `forma check` exits 0
 against haben's source at the same commit. The curation that turns 53 flat packages into six
-domains is one human decision, checked in at [`docs/demo/curate.mjs`](docs/demo/curate.mjs) with
-the commands to rebuild it.
+domains and maps the governed boundary to typed timeline patches is one human decision, checked in
+at [`docs/demo/curate.mjs`](docs/demo/curate.mjs) with the commands to rebuild it.
 
 The one thing the demo does not do is regenerate itself: haben is private, so Pages publishes a
 snapshot committed from a local run rather than cloning it in CI. Nothing automated will notice
@@ -88,7 +91,7 @@ and validates every cumulative state before replacing the last model.
   "timeline": {
     "source": "docs/architecture/FUTURE.md",
     "checkpoints": [{
-      "id": "g1", "label": "G1 · UAT", "badge": "9 item · 1 P0",
+      "id": "g1", "label": "G1 · UAT", "badge": "9 board · 1 P0",
       "patch": {
         "nodes": {
           "add": [{ "node": {
@@ -112,14 +115,17 @@ and validates every cumulative state before replacing the last model.
 ```
 
 Node patches support `add`, non-structural `update`, and child-first `remove`; edge patches support
-`add`, exact-match `rewire`, and `remove`. Every operation carries the prose shown as “Change from
-previous”. IDs, parents, levels and kinds cannot be edited in place, ambiguous edge selectors fail,
-and a node cannot disappear while children or incident relations survive. The source path must
-exist. `AS-IS` is implicit and reserved; the last checkpoint is the target, so `target` is forbidden
-inside timeline patches. With a timeline the viewer replaces CURRENT/TARGET with the checkpoints,
-supports `?checkpoint=g1`, accents only the local patch, and keeps drill, layout, re-verification
-and export working on the cumulative graph. Without one, the legacy controls and model are
-unchanged.
+`add`, exact-match `rewire`, and `remove`. Every operation carries governed change prose; a live
+node changed locally exposes it as “Change from previous”, while the graph accents changed nodes
+and relations without keeping a second change log or drawing ghosts for removals. IDs, parents,
+levels and kinds cannot be edited in place, ambiguous edge selectors fail, and a node cannot
+disappear while children or incident relations survive. The source path must exist. `AS-IS` is
+implicit and reserved; the last checkpoint is the target, so `target` is forbidden inside timeline
+patches. With a timeline the viewer replaces CURRENT/TARGET with the checkpoints, supports
+`?checkpoint=g1`, accents only the local patch, and keeps drill, layout, re-verification and export
+working on the cumulative graph. A future checkpoint with no local patch says “no architecture
+changes”; its display-only badge is not interpreted. Without a timeline, the legacy controls and
+model are unchanged.
 
 **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/viewer/c4-hologram.html

@@ -41,9 +41,6 @@ select#skin option{background:#08202e;color:var(--nm)}
 .cpstep.active .dot{border-color:var(--cyan);background:var(--bg);box-shadow:0 0 10px rgba(62,231,255,.8)}
 #checkpoint-summary{text-align:right;color:var(--ter2);font-size:8.5px;letter-spacing:.08em;margin-top:5px;min-height:11px}
 #checkpoint-summary b{color:var(--cyan);font-weight:600}
-#checkpoint-changes{display:grid;gap:3px;margin-top:7px;max-height:92px;overflow:auto}
-.cpchange{color:var(--text);font-size:9px;line-height:1.35;padding-left:8px;border-left:2px solid var(--cyan)}
-.cpchange b{color:var(--cyan);font-weight:600;letter-spacing:.08em}.cpchange span{color:var(--ter2)}
 #crumb{font-size:11px;color:var(--sec);margin:8px 0}
 #crumb .agg{float:right;color:var(--ter2);letter-spacing:.05em}
 #crumb .agg i{display:inline-block;width:7px;height:7px;border-radius:50%;margin:0 3px 0 8px;vertical-align:baseline}
@@ -190,9 +187,8 @@ html[data-skin="blueprint"] .nd.delta rect,html[data-skin="blueprint"] .edge.del
   </div>
  </div>
  <nav id="timeline">
- <div id="timeline-track"></div>
- <div id="checkpoint-summary"></div>
-  <div id="checkpoint-changes"></div>
+  <div id="timeline-track"></div>
+  <div id="checkpoint-summary"></div>
  </nav>
  <div id="crumb"></div>
  <div id="stamp"></div>
@@ -229,7 +225,7 @@ var STRINGS={
   detDecl:"Declared in", detCover:"Coverage", detRoll:"Rolled up from", rollPart:"mean of the {n} of {t} parts inside that anyone ruled on", coverWhole:"the document names this module itself",
   coverPart:"{n} of {t} units named by the document",
   legHint:"— animated arrow = active flow · dashed = to build", legCheckpoint:"CHANGE IN THIS CHECKPOINT",
-  timelineLabel:"Architecture checkpoints", asIs:"AS-IS", asIsBadge:"verified code", cumulativeHint:"the graph is always cumulative",
+  timelineLabel:"Architecture checkpoints", asIs:"AS-IS", asIsBadge:"verified code", cumulativeHint:"the graph is always cumulative", noArchChanges:"no architecture changes",
   deltaAdd:"ADD", deltaUpdate:"UPDATE", deltaRewire:"REWIRE", deltaRemove:"REMOVE",
   crumbRoot:"Context", crumbLevel:"C4", lvlContext:"CONTEXT",
   lvlNames:{context:"Context",container:"Container",component:"Components",leaf:"Leaves"},
@@ -253,7 +249,7 @@ var STRINGS={
   detDecl:"Dichiarato in", detCover:"Copertura", detRoll:"Somma dal basso", rollPart:"media delle {n} parti su {t} qui dentro su cui qualcuno si e pronunciato", coverWhole:"il documento nomina il modulo stesso",
   coverPart:"{n} unità su {t} nominate dal documento",
   legHint:"— freccia animata = flusso attivo · tratteggio = da costruire", legCheckpoint:"CAMBIO IN QUESTO CHECKPOINT",
-  timelineLabel:"Checkpoint architetturali", asIs:"AS-IS", asIsBadge:"codice verificato", cumulativeHint:"il grafo è sempre cumulativo",
+  timelineLabel:"Checkpoint architetturali", asIs:"AS-IS", asIsBadge:"codice verificato", cumulativeHint:"il grafo è sempre cumulativo", noArchChanges:"nessun cambio architetturale",
   deltaAdd:"ADD", deltaUpdate:"UPDATE", deltaRewire:"REWIRE", deltaRemove:"REMOVE",
   crumbRoot:"Contesto", crumbLevel:"C4", lvlContext:"CONTESTO",
   lvlNames:{context:"Contesto",container:"Container",component:"Componenti",leaf:"Foglie"},
@@ -396,6 +392,14 @@ function timelineStates(base){
  }
  return {errors:errors,states:states};
 }
+function timelineSummary(id,delta){
+ var c=(delta&&delta.counts)||{},parts=[];
+ if(c.add)parts.push({key:"deltaAdd",count:c.add});
+ if(c.update)parts.push({key:"deltaUpdate",count:c.update});
+ if(c.rewire)parts.push({key:"deltaRewire",count:c.rewire});
+ if(c.remove)parts.push({key:"deltaRemove",count:c.remove});
+ return {parts:parts,empty:id!=="as-is"&&!parts.length};
+}
 var BASE=null,M=null,TSTATES=[],CPID="as-is",CPDELTA={nodes:[],edges:[],removedNodes:[],removedEdges:[],counts:{add:0,update:0,rewire:0,remove:0}}
 var stack=[null],mode="now",POS={},POSALL={},drag=null,justDragged=false,CATNODES={},FETCHED=false
 var VBOX={}; // last fitted viewBox per level — frozen while dragging so the canvas does not rescale
@@ -462,7 +466,6 @@ function makeCatalogNode(pid,g){
 }
 function hasKids(id){for(var i=0;i<M.nodes.length;i++)if(M.nodes[i].parent===id)return true;return false;}
 function node(id){for(var i=0;i<M.nodes.length;i++)if(M.nodes[i].id===id)return M.nodes[i];return null;}
-function nameOf(id){var n=node(id);return n?n.name:id;}
 function srcOf(n){if(CPID!=="as-is"&&nodeProjected(n.id)&&BASE&&BASE.timeline)return BASE.timeline.source;
  if(n.verify){if(typeof n.verify==="string")return n.verify;if(n.verify.source)return n.verify.source;if(n.verify.ref)return n.verify.ref;if(n.verify.issue)return "#"+n.verify.issue;}
  var ev=(n.evidence||[]).filter(function(e){return e.type==="doc"||e.type==="path";})[0];
@@ -475,25 +478,16 @@ function edgeChange(e){
 function emptyDelta(){return {nodes:[],edges:[],removedNodes:[],removedEdges:[],counts:{add:0,update:0,rewire:0,remove:0}};}
 function renderTimeline(){
  var nav=$("timeline"),legacy=$("legacytime"),legend=$("lg-checkpoint-wrap");
- if(!BASE||!BASE.timeline){nav.style.display="none";legacy.style.display="inline-flex";legend.style.display="none";$("checkpoint-changes").innerHTML="";return;}
+ if(!BASE||!BASE.timeline){nav.style.display="none";legacy.style.display="inline-flex";legend.style.display="none";return;}
  nav.style.display="block";legacy.style.display="none";legend.style.display="inline";
  nav.setAttribute("aria-label",STR.timelineLabel);
  var html='<button class="cpstep real'+(CPID==="as-is"?" active":"")+'" data-checkpoint="as-is" type="button"><span class="dot"></span>'+esc(STR.asIs)+'<span class="cpbadge">'+esc(STR.asIsBadge)+'</span></button>';
  for(var i=0;i<TSTATES.length;i++){var s=TSTATES[i];html+='<button class="cpstep'+(CPID===s.id?" active":"")+'" data-checkpoint="'+esc(s.id)+'" type="button"><span class="dot"></span>'+esc(s.label)+(s.badge?'<span class="cpbadge">'+esc(s.badge)+'</span>':'')+'</button>';}
  $("timeline-track").innerHTML=html;
- var c=CPDELTA.counts,parts=[];
- if(c.add)parts.push('<b>'+STR.deltaAdd+'</b> '+c.add);
- if(c.update)parts.push('<b>'+STR.deltaUpdate+'</b> '+c.update);
- if(c.rewire)parts.push('<b>'+STR.deltaRewire+'</b> '+c.rewire);
- if(c.remove)parts.push('<b>'+STR.deltaRemove+'</b> '+c.remove);
- $("checkpoint-summary").innerHTML=(parts.length?parts.join(" · ")+" · ":"")+esc(STR.cumulativeHint);
- var changes=[],d=CPDELTA,i,nm,subject;
- function row(type,what,why){changes.push('<div class="cpchange"><b>'+esc(type)+'</b> '+esc(what)+' <span>— '+esc(why)+'</span></div>');}
- for(i=0;i<d.nodes.length;i++){nm=node(d.nodes[i].id);row(d.nodes[i].type,nm?nm.name:d.nodes[i].id,d.nodes[i].change);}
- for(i=0;i<d.edges.length;i++){subject=nameOf(d.edges[i].from)+" → "+nameOf(d.edges[i].to)+(d.edges[i].label?" · "+d.edges[i].label:"");row(d.edges[i].type,subject,d.edges[i].change);}
- for(i=0;i<d.removedEdges.length;i++){subject=nameOf(d.removedEdges[i].from)+" → "+nameOf(d.removedEdges[i].to)+(d.removedEdges[i].label?" · "+d.removedEdges[i].label:"");row(d.removedEdges[i].type,subject,d.removedEdges[i].change);}
- for(i=0;i<d.removedNodes.length;i++)row(d.removedNodes[i].type,d.removedNodes[i].name||d.removedNodes[i].id,d.removedNodes[i].change);
- $("checkpoint-changes").innerHTML=changes.join("");
+ var summary=timelineSummary(CPID,CPDELTA),parts=[];
+ for(i=0;i<summary.parts.length;i++)parts.push('<b>'+STR[summary.parts[i].key]+'</b> '+summary.parts[i].count);
+ $("checkpoint-summary").innerHTML=parts.length?parts.join(" · ")+" · "+esc(STR.cumulativeHint)
+  :(summary.empty?'<b>'+esc(STR.noArchChanges)+'</b> · ':'')+esc(STR.cumulativeHint);
 }
 function checkpointUrl(id){
  try{var u=new URL(location.href);if(id==="as-is")u.searchParams.delete("checkpoint");else u.searchParams.set("checkpoint",id);history.replaceState(null,"",u.toString());}catch(e){}

package/package.json

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