forma-arch 0.11.2 → 0.12.0

package/README.md

@@ -1,5 +1,9 @@
 # Forma
 
+[![npm version](https://img.shields.io/npm/v/forma-arch?label=npm)](https://www.npmjs.com/package/forma-arch)
+[![npm downloads](https://img.shields.io/npm/dm/forma-arch)](https://www.npmjs.com/package/forma-arch)
+[![license](https://img.shields.io/npm/l/forma-arch)](https://www.npmjs.com/package/forma-arch)
+
 **Present your architecture instead of slides.** Forma turns any codebase into an interactive,
 stack-agnostic C4 explorer — big-picture → drill-down to the leaf — generated *from the code* and
 kept true to it by a deterministic drift check. No more slide decks that lie the day after you draw

package/lib/gen.mjs

@@ -338,6 +338,19 @@ if (!process.argv.includes('--no-auto-edges') && isGo(topo.meta && topo.meta.sta
     try { for (const f of readdirSync(dir)) { const fp = join(dir, f); if (statSync(fp).isFile()) t += '\n' + readFileSync(fp, 'utf-8') } } catch {}
     text.set(s.parent, t)
   }
+  // ponytail: per-line kind is a heuristic (import > drives > reads > references); the count `c` below
+  // is untouched, and curated edges always win where precision matters. The verb is what an executive
+  // reads; the count lives in `weight` so the viewer can roll it up without parsing the label.
+  const VERB = [[/^\s*(?:import|export)\b[\s\S]*?\bfrom\b|^\s*const\s+\S+\s*=\s*require\s*\(/, 'imports'],
+    [/\b(?:spawn|exec)(?:Sync|File)?\s*\(/, 'drives'],
+    [/\breadFileSync\s*\(|\breaddirSync\s*\(|\breadJson\b/, 'reads']]
+  const RANK = { imports: 3, drives: 2, reads: 1, references: 0 }
+  const classify = (line) => { for (const [re, v] of VERB) if (re.test(line)) return v; return 'references' }
+  const exposesRe = new Map()
+  for (const to of exposes.keys()) {
+    const alts = exposes.get(to).map((nm) => nm.replace(/[.*+?^${}()|[\]\\\/-]/g, '\\$&')).join('|')
+    exposesRe.set(to, alts ? new RegExp('(^|[^\\w-])(?:' + alts + ')([^\\w-]|$)') : null)
+  }
   const have = new Set((topo.edges || []).flatMap((e) => [e.from + '|' + e.to, e.to + '|' + e.from]))
   const derived = []
   for (const from of exposes.keys()) {
@@ -350,7 +363,13 @@ if (!process.argv.includes('--no-auto-edges') && isGo(topo.meta && topo.meta.sta
       // repo, i.e. most JS/TS ones, rendered edges=0). `-` and `.` are word separators here, so
       // the boundary is spelled out instead of using \b (which sits INSIDE "session-store").
       for (const nm of exposes.get(to)) { if (new RegExp('(^|[^\\w-])' + nm.replace(/[.*+?^${}()|[\]\\\/-]/g, '\\$&') + '([^\\w-]|$)').test(t)) c++ }
-      if (c > 0) { derived.push({ from, to, label: c + '×', kind: 'import', estatus: 'active' }); have.add(from + '|' + to); have.add(to + '|' + from) }
+      if (c > 0) {
+        let verb = 'references'
+        const re = exposesRe.get(to)
+        if (re) for (const line of t.split('\n')) { if (re.test(line)) { const v = classify(line); if (RANK[v] > RANK[verb]) verb = v } }
+        derived.push({ from, to, label: verb, weight: c, kind: 'import', estatus: 'inferred' })
+        have.add(from + '|' + to); have.add(to + '|' + from)
+      }
     }
   }
   topo.edges = [...(topo.edges || []), ...derived]

package/lib/lang.mjs

@@ -96,7 +96,7 @@ export function goEdges({ repo, nodes, edges }) {
       const k = p.container + '|' + to
       if (have.has(k)) continue
       have.add(k)
-      out.push({ from: p.container, to, label: c + '×', kind: 'import', estatus: 'active' })
+      out.push({ from: p.container, to, label: 'imports', weight: c, kind: 'import', estatus: 'inferred' })
     }
   }
   return out

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

@@ -571,6 +571,11 @@
           "level": {
             "type": "string"
           },
+          "weight": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Reference count for a derived edge; the viewer sums it when rolling up. Optional; falls back to parsing the label."
+          },
           "kind": {
             "type": "string",
             "description": "import | runtime | ci \u2014 provenance of the relationship."
@@ -605,9 +610,10 @@
             "type": "string",
             "enum": [
               "active",
-              "to-build"
+              "to-build",
+              "inferred"
             ],
-            "description": "active = animated flow; to-build = dashed."
+            "description": "active = animated flow (curated); to-build = dashed; inferred = derived from code references (heuristic, drawn softer)."
           }
         }
       }

package/lib/viewer/c4-hologram.html

@@ -90,6 +90,7 @@ svg{width:100%;height:100%;display:block}
 .mode-t .nd .tt,.mode-t .nd .pp{fill:var(--next)!important}
 .edge{stroke:var(--edge);stroke-width:1.3;fill:none;marker-end:url(#ar);cursor:help}
 .edge.flow{stroke-dasharray:5 7;animation:dash 1.1s linear infinite}
+.edge.inferred{stroke-dasharray:1 3;opacity:.5}
 .edge.plan{stroke:var(--edgeplan);stroke-dasharray:3 6;opacity:.6;marker-end:url(#arp)}
 .edge.hot{stroke:var(--cyan);stroke-width:2.6;opacity:1}
 .edge.delta{stroke:var(--cyan);stroke-width:2.5;opacity:1;filter:drop-shadow(0 0 4px rgba(62,231,255,.7))}
@@ -224,7 +225,7 @@ var STRINGS={
   legUnk:"UNKNOWN (no curated state)", stUnk:"?",
   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",
+  legHint:"— animated arrow = active flow · dotted = inferred · dashed = to build", legCheckpoint:"CHANGE IN THIS CHECKPOINT",
   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",
@@ -248,7 +249,7 @@ var STRINGS={
   legUnk:"IGNOTO (stato non curato)", stUnk:"?",
   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",
+  legHint:"— freccia animata = flusso attivo · puntini = derivato · tratteggio = da costruire", legCheckpoint:"CAMBIO IN QUESTO CHECKPOINT",
   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",
@@ -608,7 +609,7 @@ function draw(animate){
   +'<defs><marker id="ar" markerWidth="9" markerHeight="7" refX="9" refY="3.5" orient="auto"><polygon points="0 0,9 3.5,0 7" fill="'+cssv("--edge")+'"/></marker>'
   +'<marker id="arp" markerWidth="9" markerHeight="7" refX="9" refY="3.5" orient="auto"><polygon points="0 0,9 3.5,0 7" fill="'+cssv("--edgeplan")+'"/></marker></defs>';
  for(j=0;j<geo.length;j++){
-  var e=geo[j].g,ed=geo[j].e,cl=(ed.estatus==="to-build"?"plan":"flow");
+  var e=geo[j].g,ed=geo[j].e,cl=(ed.estatus==="to-build"?"plan":ed.estatus==="inferred"?"inferred":"flow");
   s+='<path class="edge '+cl+(ed.delta?" delta":"")+'" data-e="'+geo[j].i+'" d="'+e.d+'"/>';
   s+='<path class="edgehit" data-e="'+geo[j].i+'" data-label="'+esc(ed.label||"")+'" d="'+e.d+'"/>';
   if(showLbl&&ed.label){var lb=String(ed.label);if(lb.length>28)lb=lb.slice(0,27)+"…";
@@ -740,7 +741,7 @@ function rollEdges(edges,vis,parent){
   f=null;cur=e.from;guard=0;while(cur!=null&&guard++<64){if(vis[cur]){f=vis[cur];break;}cur=parent[cur];}
   t=null;cur=e.to;guard=0;while(cur!=null&&guard++<64){if(vis[cur]){t=vis[cur];break;}cur=parent[cur];}
   if(!f||!t||f===t)continue;
-  c=parseInt(String(e.label),10);if(!(c>0))c=1;
+  c=(e.weight>0)?e.weight:parseInt(String(e.label),10);if(!(c>0))c=1;
   k=f+"|"+t;
   if(ix[k]==null){ix[k]=out.length;out.push({from:f,to:t,label:e.label,estatus:e.estatus,n:c,delta:typeof edgeChange==="function"?edgeChange(e):null});}
   else{g=out[ix[k]];g.n+=c;g.label=g.n+"×";if(e.estatus!=="to-build")g.estatus=e.estatus;if(!g.delta&&typeof edgeChange==="function")g.delta=edgeChange(e);}
@@ -763,11 +764,16 @@ function edgePath(a,b){
 }
 function levelName(l){return (STR.lvlNames&&STR.lvlNames[l])||l||"—";}
 function cssv(v){try{return getComputedStyle(document.documentElement).getPropertyValue(v).trim()||"#2b6e8a";}catch(e){return "#2b6e8a";}}
+function detailState(n,timeline){
+ // Function prose says what a box is. It is not also a checkpoint state: unchanged timeline nodes
+ // without curated `current` used to repeat the same sentence under both labels.
+ return timeline?(n.current||""):(n.current||n.func||n.description||"");
+}
 
 function showDetail(n){
  if(n&&n.__catalog)return showRoster(n);
- var src=srcOf(n),cur=n.current||n.func||n.description||"",showSrc=src&&String(cur).indexOf(src)<0;
- var timeline=!!(BASE&&BASE.timeline),change=timeline?nodeChange(n.id):null;
+ var timeline=!!(BASE&&BASE.timeline),src=srcOf(n),cur=detailState(n,timeline),showSrc=src&&String(cur).indexOf(src)<0;
+ var change=timeline?nodeChange(n.id):null;
  $("detail").innerHTML='<span class="cl" id="dc">'+esc(STR.detClose)+'</span><h3>'+esc(n.name)+' <span class="cat">· '+esc(n.category||n.kind||"")+(n.tech?" · "+esc(n.tech):"")+'</span></h3>'
   +(n.func?'<div class="row"><span class="lbl">'+esc(STR.detFunc)+'</span><span class="func">'+esc(n.func)+'</span></div>':'')
   +(cur&&(timeline||cur!==n.func)?'<div class="row"><span class="lbl">'+esc(timeline?STR.detCheckpoint:STR.detNow)+'</span><span class="now">'+esc(cur)+'</span></div>':'')

package/package.json

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