@tekyzinc/gsd-t 4.0.26 → 4.0.27

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [4.0.27] - 2026-06-04 (M79 Diagram Quality - patch)
+
+### Fixed - scan-report diagrams were generic boilerplate, clashed with the dark theme, and one was actively misleading
+
+The HTML scan report's six diagrams had three problems. (1) Four of them rendered a hardcoded "Tasks/Projects/Auth" template because `collectScanData` never populated the `services`/`layers`/`endpoints`/`states` inputs the generators read. (2) The database-schema diagram picked the wrong schema file on large repos (a 5-table video shim instead of the 417-table `src/lib/schema/index.ts`) and emitted `unknown` column types — a misleading diagram is worse than none. (3) All diagrams rendered on a white background with sharp corners and shrink-wrapped labels, clashing with the report's dark theme. The sequence diagram also failed to render because `validate & sanitize` broke the Mermaid sequence parser.
+
+- `bin/scan-data-collector.js`: parse real `services`/`layers`/`endpoints` from `docs/architecture.md` and `states` from `docs/workflows.md` (strict transition-chain detection — prose noise yields `[]` so generators keep their good defaults).
+- `bin/scan-diagrams-generators.js`: `genSystemArchitecture` draws up to 12 real feature domains with rounded `classDef`s; `genSequence` uses `validate and sanitize` (no `&` entity).
+- `bin/scan-diagrams.js`: database-schema diagram suppressed by default via `SUPPRESSED_TYPES`; re-enable per call with `options.includeSchemaDiagram` once the schema extractor is fixed.
+- `bin/scan-renderer.js`: shared `MERMAID_CONFIG` (dark `base` theme, rounded corners, node padding/spacing) applied via `mmdc -c`, plus `-b transparent` so diagrams blend into the dark panel.
+- `test/m79-diagram-quality.test.js`: regression test (services extracted, schema suppressed + opt-in, sequence has no `&`, config injected).
+- `test/scan.test.js`, `test/verify-gates.js`: updated to the 5-diagrams-by-default contract (schema via opt-in).
+
 ## [4.0.26] - 2026-06-03 (M78 Plain-English Grouped + Batched - patch)
 
 ### Fixed - plain-english companion was a flat ungrouped list + would stall on large registers

package/bin/scan-data-collector.js

@@ -165,6 +165,55 @@ function parseQualityFindings(text) {
   return findings.slice(0, 3);
 }
 
+// M79: derive the diagram inputs (services/layers/endpoints/states) from the DEEP
+// living docs (docs/architecture.md, docs/workflows.md) so the architecture/data-flow
+// diagrams reflect the project's REAL feature domains instead of falling back to the
+// generic "Tasks/Projects" templates. Falls back to scan/architecture.md, then [].
+function parseServices(docArch) {
+  if (!docArch) return [];
+  // Top-level numbered domain sections: "## 5. Multi-Tenant School and Location Model"
+  const svc = [];
+  for (const m of docArch.matchAll(/^##\s+\d+\.\s+(.+?)\s*$/gm)) {
+    const name = m[1].trim();
+    // skip meta sections that aren't feature domains
+    if (/^(system overview|technology stack|application structure|table of contents)/i.test(name)) continue;
+    svc.push(name);
+  }
+  return svc;
+}
+function parseLayers(docArch) {
+  if (!docArch) return [];
+  // "### Controller Layer", "## 4. Authentication and Session Layer", etc.
+  const layers = [];
+  for (const m of docArch.matchAll(/^#{2,3}\s+(?:\d+\.\s+)?(.+?\bLayer)\s*$/gmi)) {
+    const n = m[1].trim(); if (!layers.includes(n)) layers.push(n);
+  }
+  return layers;
+}
+function parseEndpoints(docArch) {
+  if (!docArch) return [];
+  // real route lines like `GET /feature-flags/resolve/:flagKey` or `POST /api/...`
+  const eps = [];
+  for (const m of docArch.matchAll(/\b(GET|POST|PUT|PATCH|DELETE)\s+(\/[A-Za-z0-9_\-\/:{}.]+)/g)) {
+    const e = m[1] + ' ' + m[2]; if (!eps.includes(e)) eps.push(e);
+  }
+  return eps;
+}
+function parseStates(docWorkflows) {
+  if (!docWorkflows) return [];
+  // Only accept REAL state transitions written as "Draft -> Open" / "Draft → Open"
+  // where BOTH sides look like status enum values (short, capitalized, no spaces).
+  // If we can't find a genuine transition chain, return [] so the generator keeps
+  // its (good) default state machine rather than rendering doc-prose noise. (M79:
+  // a loose match previously pulled "Domains/Source/Schedule" from prose headers.)
+  const isState = (w) => /^[A-Z][A-Za-z]{1,14}$/.test(w) && /(Draft|Open|Progress|Review|Done|Block|Cancel|Pending|Active|Closed|Approved|Rejected|Queued|Failed|Complete)/i.test(w);
+  const states = [];
+  for (const m of docWorkflows.matchAll(/\b([A-Z][A-Za-z]+)\s*(?:->|→)\s*([A-Z][A-Za-z]+)\b/g)) {
+    if (isState(m[1]) && isState(m[2])) for (const s of [m[1], m[2]]) if (!states.includes(s)) states.push(s);
+  }
+  return states.length >= 3 ? states : [];
+}
+
 function collectScanData(projectRoot) {
   const scanDir = path.join(projectRoot, '.gsd-t', 'scan');
   const rs = (f) => read(path.join(scanDir, f));
@@ -175,6 +224,9 @@ function collectScanData(projectRoot) {
   const secText   = rs('security.md');
   const qualText  = rs('quality.md');
   const debtText  = rr('.gsd-t/techdebt.md');
+  // Deep living docs — the real architecture knowledge (M79).
+  const docArch   = rr('docs/architecture.md');
+  const docFlow   = rr('docs/workflows.md');
 
   let projectName = path.basename(projectRoot);
   try { projectName = JSON.parse(rr('package.json')).name || projectName; } catch {}
@@ -188,8 +240,15 @@ function collectScanData(projectRoot) {
   const qualFinds = parseQualityFindings(qualText);
   const findings  = secFinds.concat(qualFinds).slice(0, 10);
 
+  // Diagram inputs from the deep docs (M79).
+  const services  = parseServices(docArch);
+  const layers    = parseLayers(docArch);
+  const endpoints = parseEndpoints(docArch);
+  const states    = parseStates(docFlow);
+
   return { projectName, filesScanned, totalLoc, debtCritical, debtHigh, debtMedium,
-           testCoverage, domains, techDebt, findings };
+           testCoverage, domains, techDebt, findings,
+           services, layers, endpoints, states };
 }
 
 module.exports = { collectScanData };

package/bin/scan-diagrams-generators.js

@@ -2,14 +2,22 @@
 
 function genSystemArchitecture(analysisData) {
   try {
-    const services = (analysisData.services || []).slice(0, 4);
+    // M79: when real feature domains were extracted from docs/architecture.md, draw
+    // them as the system's services (User -> Backend -> each domain). Show up to 12.
+    const services = (analysisData.services || []).slice(0, 12);
     if (services.length >= 2) {
       const lines = ['graph TB',
-        '  classDef user fill:#0d2035,stroke:#06b6d4,color:#a5f3fc',
-        '  classDef svc fill:#1a0f3a,stroke:#7c3aed,color:#ddd6fe',
-        '  classDef db fill:#0a2318,stroke:#10b981,color:#a7f3d0',
-        '  User(["👤 User"]):::user'];
-      services.forEach((s, i) => { lines.push('  S' + i + '["' + s + '"]:::svc'); lines.push('  User --> S' + i); });
+        '  User(["👤 User"]):::user',
+        '  API["⚡ Backend / API"]:::core',
+        '  User -->|"HTTPS"| API'];
+      services.forEach((s, i) => {
+        const label = String(s).replace(/"/g, "'");
+        lines.push('  S' + i + '["' + label + '"]:::svc');
+        lines.push('  API --> S' + i);
+      });
+      lines.push('  classDef user fill:#0d2035,stroke:#22d3ee,color:#a5f3fc,rx:8,ry:8');
+      lines.push('  classDef core fill:#1a0f3a,stroke:#a78bfa,color:#ede9fe,rx:8,ry:8');
+      lines.push('  classDef svc fill:#0f1d3a,stroke:#60a5fa,color:#bfdbfe,rx:8,ry:8');
       return lines.join('\n');
     }
     return `graph TB
@@ -150,7 +158,7 @@ function genSequence(analysisData) {
   participant Queue
   User->>Client: Submit form
   Client->>API: ${ep}
-  API->>API: validate & sanitize
+  API->>API: validate and sanitize
   alt invalid input
     API-->>Client: 400 Bad Request
   else valid

package/bin/scan-diagrams.js

@@ -42,11 +42,20 @@ function buildPlaceholder(def, mmd) {
   };
 }
 
+// M79: the database-schema diagram is SUPPRESSED by default. The schema extractor
+// picks the wrong file on large repos (grabbed a 5-table video shim instead of the
+// 417-table src/lib/schema/index.ts) and emits `unknown` column types — a misleading
+// diagram is worse than none. Re-enable per-call with options.includeSchemaDiagram
+// once parseDrizzle/detectOrm are fixed to use the real schema.
+const SUPPRESSED_TYPES = new Set(['database-schema']);
+
 function generateDiagrams(analysisData, schemaData, options) {
   try {
     const { renderDiagram } = require('./scan-renderer');
+    const opts = options || {};
     const results = [];
     for (const def of DIAGRAM_DEFS) {
+      if (SUPPRESSED_TYPES.has(def.type) && !opts.includeSchemaDiagram) continue;
       try {
         const mmd = def.gen(analysisData, schemaData);
         const isDbSchema = def.type === 'database-schema';

package/bin/scan-renderer.js

@@ -17,19 +17,50 @@ function makePlaceholder() {
   return PLACEHOLDER_HTML;
 }
 
+// M79: shared Mermaid config — coherent dark palette that sits well on the report's
+// dark page, ROUNDED node corners, and generous PADDING/spacing so labels (e.g.
+// "assign", "resolve") aren't shrink-wrapped against the box edges. Applied to every
+// diagram via mmdc's -c flag so all diagrams share one consistent look.
+const MERMAID_CONFIG = {
+  theme: 'base',
+  themeVariables: {
+    background: '#0a0f1e',
+    primaryColor: '#172554',          // node fill (deep blue, reads on dark)
+    primaryBorderColor: '#3b82f6',
+    primaryTextColor: '#e2e8f0',
+    lineColor: '#64748b',
+    secondaryColor: '#1e1b4b',
+    tertiaryColor: '#0a2318',
+    fontFamily: 'ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif',
+    fontSize: '15px',
+    clusterBkg: '#0b1220',
+    clusterBorder: '#1e3a5f',
+    nodeBorder: '#3b82f6',
+    edgeLabelBackground: '#0b1220',
+  },
+  flowchart: { curve: 'basis', padding: 18, nodeSpacing: 55, rankSpacing: 70, htmlLabels: true, useMaxWidth: true },
+  state: { padding: 16, nodeSpacing: 55, rankSpacing: 70 },
+  sequence: { useMaxWidth: true, boxMargin: 12 },
+};
+
 function tryMmdc(mmdContent) {
   const ts = Date.now();
   const tmpIn = path.join(os.tmpdir(), 'gsd-scan-' + ts + '.mmd');
   const tmpOut = path.join(os.tmpdir(), 'gsd-scan-' + ts + '.svg');
+  const tmpCfg = path.join(os.tmpdir(), 'gsd-scan-' + ts + '.config.json');
   try {
     fs.writeFileSync(tmpIn, mmdContent, 'utf8');
-    execFileSync('mmdc', ['-i', tmpIn, '-o', tmpOut, '-t', 'dark', '--quiet'], { timeout: 30000, stdio: 'pipe' });
+    fs.writeFileSync(tmpCfg, JSON.stringify(MERMAID_CONFIG), 'utf8');
+    // -b transparent so the diagram blends into the report's dark panel instead of a
+    // white box; -c applies the shared theme/padding/rounded config.
+    execFileSync('mmdc', ['-i', tmpIn, '-o', tmpOut, '-c', tmpCfg, '-b', 'transparent', '--quiet'], { timeout: 30000, stdio: 'pipe' });
     const svg = fs.readFileSync(tmpOut, 'utf8');
     return { svgContent: stripSvgDimensions(svg), rendered: true, rendererUsed: 'mermaid-cli' };
   } catch { return null; }
   finally {
     try { fs.unlinkSync(tmpIn); } catch {}
     try { fs.unlinkSync(tmpOut); } catch {}
+    try { fs.unlinkSync(tmpCfg); } catch {}
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "4.0.26",
+  "version": "4.0.27",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",