@anhcodo13/lattice 0.0.0-stage → 0.2.0

package/dist/cli.js

@@ -0,0 +1,1059 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { writeFile as writeFile2 } from "fs/promises";
+import { realpathSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname as dirname2, join as join8, resolve as resolve7 } from "path";
+import { Command, CommanderError } from "commander";
+
+// src/analysis/analyze.ts
+import { mkdir as mkdir2, readFile as readFile4, writeFile } from "fs/promises";
+import { basename, join as join5, resolve as resolve3 } from "path";
+
+// src/analysis/config.ts
+import { readFile } from "fs/promises";
+import { join } from "path";
+var defaultThresholds = {
+  maxFanIn: 8,
+  maxFanOut: 10,
+  maxChainDepth: 6,
+  maxComponentLines: 200,
+  maxJsxDepth: 6,
+  maxComplexity: 15
+};
+var defaultWeights = {
+  architecture: 40,
+  imports: 25,
+  components: 20,
+  complexity: 15
+};
+function record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function patterns(value, label) {
+  if (!Array.isArray(value) || value.length === 0 || !value.every((item) => typeof item === "string" && item.trim())) {
+    throw new Error(`${label} must be a nonempty string array`);
+  }
+  return value;
+}
+async function loadAnalysisConfig(root) {
+  const path = join(root, ".nklattice.json");
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    if (record(error) && error.code === "ENOENT") return { thresholds: { ...defaultThresholds }, weights: { ...defaultWeights }, policies: [] };
+    throw error;
+  }
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new Error("Malformed .nklattice.json");
+  }
+  if (!record(value)) throw new Error(".nklattice.json must be an object");
+  const analysis = value.analysis === void 0 ? {} : value.analysis;
+  if (!record(analysis)) throw new Error("analysis must be an object");
+  const overrides = analysis.thresholds === void 0 ? {} : analysis.thresholds;
+  if (!record(overrides)) throw new Error("analysis.thresholds must be an object");
+  const thresholds = { ...defaultThresholds };
+  for (const [name, limit] of Object.entries(overrides)) {
+    if (!Object.hasOwn(thresholds, name) || !Number.isInteger(limit) || limit < 0) {
+      throw new Error(`Invalid analysis threshold ${name}`);
+    }
+    thresholds[name] = limit;
+  }
+  const rawWeights = analysis.weights === void 0 ? defaultWeights : analysis.weights;
+  if (!record(rawWeights) || Object.keys(rawWeights).length !== Object.keys(defaultWeights).length) {
+    throw new Error("analysis.weights must define every category and total 100");
+  }
+  const weights = { ...defaultWeights };
+  for (const [name, weight] of Object.entries(rawWeights)) {
+    if (!Object.hasOwn(weights, name) || typeof weight !== "number" || !Number.isFinite(weight) || weight < 0) {
+      throw new Error(`Invalid analysis weight ${name}`);
+    }
+    weights[name] = weight;
+  }
+  if (Object.values(weights).reduce((sum, weight) => sum + weight, 0) !== 100) {
+    throw new Error("analysis.weights must total 100");
+  }
+  const rawPolicies = value.policies ?? [];
+  if (!Array.isArray(rawPolicies)) throw new Error("policies must be an array");
+  const policies = [];
+  const ids = /* @__PURE__ */ new Set();
+  for (const raw of rawPolicies) {
+    if (!record(raw) || typeof raw.id !== "string" || !/^[a-z][a-z0-9-]*$/.test(raw.id) || typeof raw.description !== "string" || !raw.description.trim()) {
+      throw new Error("Invalid policy id or description");
+    }
+    if (ids.has(raw.id)) throw new Error(`Duplicate policy id ${raw.id}`);
+    ids.add(raw.id);
+    if (raw.enabled === false) continue;
+    const from = patterns(raw.from, `${raw.id}.from`);
+    const hasAllow = raw.allow !== void 0;
+    const hasDisallow = raw.disallow !== void 0;
+    if (hasAllow === hasDisallow) throw new Error(`Policy ${raw.id} must choose exactly one of allow or disallow`);
+    if (!["info", "warning", "error"].includes(String(raw.severity))) throw new Error(`Invalid severity in ${raw.id}`);
+    if (raw.recommendation !== void 0 && typeof raw.recommendation !== "string") {
+      throw new Error(`Invalid recommendation in ${raw.id}`);
+    }
+    policies.push({
+      id: raw.id,
+      description: raw.description,
+      from,
+      ...hasAllow ? { allow: patterns(raw.allow, `${raw.id}.allow`) } : { disallow: patterns(raw.disallow, `${raw.id}.disallow`) },
+      severity: raw.severity,
+      recommendation: raw.recommendation
+    });
+  }
+  return { thresholds, weights, policies };
+}
+
+// src/analysis/graph.ts
+function buildGraph(_modules) {
+  const modules = [..._modules].sort((a, b) => a.path.localeCompare(b.path));
+  const edges = modules.flatMap((module) => module.imports.filter((imported) => imported.resolved).map((imported) => ({
+    from: module.path,
+    to: imported.resolved,
+    line: imported.line,
+    specifier: imported.specifier,
+    importedNames: imported.importedNames,
+    isTypeOnly: imported.isTypeOnly
+  })));
+  return { modules, edges };
+}
+function findCycles(graph) {
+  const adjacent = new Map(graph.modules.map((module) => [module.path, graph.edges.filter((edge) => edge.from === module.path && !edge.isTypeOnly).map((edge) => edge.to)]));
+  const index = /* @__PURE__ */ new Map();
+  const low = /* @__PURE__ */ new Map();
+  const stack = [];
+  const inStack = /* @__PURE__ */ new Set();
+  const cycles = [];
+  let counter = 0;
+  function visit(path) {
+    index.set(path, counter);
+    low.set(path, counter++);
+    stack.push(path);
+    inStack.add(path);
+    for (const target of adjacent.get(path) ?? []) {
+      if (!index.has(target)) {
+        visit(target);
+        low.set(path, Math.min(low.get(path), low.get(target)));
+      } else if (inStack.has(target)) {
+        low.set(path, Math.min(low.get(path), index.get(target)));
+      }
+    }
+    if (low.get(path) !== index.get(path)) return;
+    const component = [];
+    while (stack.length) {
+      const current = stack.pop();
+      inStack.delete(current);
+      component.push(current);
+      if (current === path) break;
+    }
+    if (component.length > 1 || (adjacent.get(path) ?? []).includes(path)) cycles.push(component.sort());
+  }
+  for (const module of graph.modules) if (!index.has(module.path)) visit(module.path);
+  return cycles.sort((a, b) => a[0].localeCompare(b[0]));
+}
+
+// src/analysis/history.ts
+import { randomUUID } from "crypto";
+import { access, mkdir, rename } from "fs/promises";
+import { join as join2 } from "path";
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function archivePrevious(outputDirectory) {
+  const json = join2(outputDirectory, "analysis.json");
+  const html = join2(outputDirectory, "report.html");
+  if (!await exists(json) && !await exists(html)) return;
+  const name = `${(/* @__PURE__ */ new Date()).toISOString().replaceAll(/[:.]/g, "-")}-${randomUUID().slice(0, 8)}`;
+  const destination = join2(outputDirectory, "history", name);
+  await mkdir(destination, { recursive: true });
+  if (await exists(json)) await rename(json, join2(destination, "analysis.json"));
+  if (await exists(html)) await rename(html, join2(destination, "report.html"));
+}
+
+// src/analysis/recommend.ts
+function recommendActions(findings) {
+  const points = { error: 5, warning: 2, info: 1 };
+  const grouped = /* @__PURE__ */ new Map();
+  for (const finding of findings) grouped.set(finding.file, [...grouped.get(finding.file) ?? [], finding]);
+  const ranked = [...grouped.entries()].map(([file, items]) => ({ file, items, priority: items.reduce((sum, item) => sum + points[item.severity], 0) })).sort((a, b) => b.priority - a.priority || a.file.localeCompare(b.file));
+  const hotspots = ranked.slice(0, 8).map(({ file, items, priority }) => ({
+    file,
+    findingCount: items.length,
+    estimatedRecovery: `Estimate: up to ${Math.min(15, priority)} points if these findings are resolved`
+  }));
+  const quickWins = findings.filter((finding) => finding.severity === "info" || finding.ruleId === "duplicate-import").slice(0, 8).map((finding) => ({ file: finding.file, ruleId: finding.ruleId, recommendation: finding.recommendation }));
+  const roadmap = ranked.slice(0, 8).map(({ file, items, priority }) => ({
+    file,
+    priority,
+    summary: `Review ${items.map((item) => item.ruleId).join(", ")} in ${file}`
+  }));
+  return { hotspots, quickWins, roadmap };
+}
+
+// src/analysis/report.ts
+function escapeHtml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+}
+function renderHtml(report) {
+  const data = JSON.stringify(report).replaceAll("<", "\\u003c");
+  const title = escapeHtml(report.project.name);
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title} \xB7 NKLattice architecture report</title>
+<style>
+:root{color-scheme:dark;--bg:#0b1118;--panel:#111c27;--panel2:#172532;--line:#284150;--text:#e6f0f3;--muted:#99adb9;--accent:#69e0bd;--warn:#f3bd72;--error:#fa8e9a}
+*{box-sizing:border-box}body{margin:0;background:radial-gradient(circle at 5% 0%,#17343b 0,transparent 28%),var(--bg);color:var(--text);font:15px/1.55 system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif}
+button,input,select{font:inherit}button,select,input{color:var(--text);background:var(--panel);border:1px solid var(--line);border-radius:9px;padding:8px 11px}button{cursor:pointer}button:hover,button:focus-visible{border-color:var(--accent)}a{color:var(--accent)}
+.layout{display:grid;grid-template-columns:210px minmax(0,1fr);min-height:100vh}.rail{border-right:1px solid var(--line);background:#0c1720;padding:28px 18px;position:sticky;top:0;height:100vh}.brand{font-size:21px;font-weight:800;letter-spacing:-.05em;color:var(--accent)}.rail p{color:var(--muted);font-size:12px;margin:0 0 32px}.rail a{display:block;padding:9px 11px;border-radius:8px;text-decoration:none;color:var(--muted)}.rail a:hover,.rail a:focus-visible{background:var(--panel2);color:var(--text)}main{max-width:1280px;width:100%;margin:auto;padding:34px clamp(20px,4vw,64px) 80px}.eyebrow{text-transform:uppercase;letter-spacing:.16em;font-size:11px;color:var(--accent);font-weight:800}h1{font-size:clamp(30px,4vw,53px);line-height:1.07;margin:8px 0 10px;letter-spacing:-.05em}h2{font-size:24px;letter-spacing:-.035em;margin:0 0 16px}h3{margin:0 0 5px;font-size:16px}.muted{color:var(--muted)}.summary{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:12px;margin:30px 0 52px}.metric,.panel{border:1px solid var(--line);background:linear-gradient(145deg,var(--panel),#0e1a22);border-radius:15px;padding:20px}.metric strong{display:block;font-size:29px;line-height:1.1}.metric span{color:var(--muted);font-size:12px}.score{color:var(--accent)}section{scroll-margin-top:24px;margin:0 0 55px}.split{display:grid;grid-template-columns:1fr 1fr;gap:18px}.bars{display:grid;gap:12px}.barhead{display:flex;justify-content:space-between;font-size:13px}.bar{height:8px;border-radius:100px;background:#243443;overflow:hidden}.bar i{display:block;height:100%;background:var(--accent);border-radius:100px}.panel p{margin:3px 0 12px}.controls{display:flex;flex-wrap:wrap;gap:9px;margin-bottom:15px}.controls input{flex:1;min-width:180px}.findings{display:grid;gap:8px}.finding{border:1px solid var(--line);border-radius:11px;padding:13px 16px;background:var(--panel)}.finding-head{display:flex;align-items:center;gap:9px;flex-wrap:wrap}.finding p{margin:7px 0}.finding small{color:var(--muted)}.chip{font-size:11px;font-weight:800;padding:2px 7px;border-radius:5px;background:#294136;color:var(--accent)}.chip.error{background:#51313a;color:var(--error)}.chip.warning{background:#4c3d27;color:var(--warn)}.chip.info{background:#25445b;color:#90d0fa}.path{font-family:ui-monospace,SFMono-Regular,Consolas,monospace;font-size:12px;color:var(--muted);overflow-wrap:anywhere}.graph-wrap{overflow:auto}.graph{width:100%;height:auto;min-height:360px;background:#0b1820;border:1px solid var(--line);border-radius:12px}.graph line{stroke:#365565;stroke-width:1}.graph circle{fill:#173e45;stroke:var(--accent);stroke-width:2;cursor:pointer}.graph circle:hover,.graph circle:focus{fill:#2c766e}.graph text{fill:var(--text);font-size:10px;pointer-events:none}.list{list-style:none;margin:0;padding:0}.list li{padding:12px 0;border-bottom:1px solid var(--line)}.list li:last-child{border:0}.empty{color:var(--muted);padding:16px}.footer{border-top:1px solid var(--line);padding-top:24px;color:var(--muted);font-size:12px}
+@media(max-width:850px){.layout{display:block}.rail{height:auto;position:static;display:flex;flex-wrap:wrap;align-items:center;gap:4px;border-right:0;border-bottom:1px solid var(--line);padding:12px 16px}.rail p{display:none}.rail a{display:inline-block;padding:6px 8px;font-size:12px}.summary{grid-template-columns:repeat(2,1fr)}.split{grid-template-columns:1fr}}
+@media(max-width:520px){.summary{grid-template-columns:1fr 1fr}.metric{padding:14px}.metric strong{font-size:24px}main{padding:25px 16px 55px}.rail a{font-size:11px}}
+</style></head><body>
+<div class="layout"><nav class="rail" aria-label="Report sections"><div class="brand">NKLattice</div><p>Architecture report</p><a href="#overview">Overview</a><a href="#score">Score</a><a href="#findings">Findings</a><a href="#hotspots">Hotspots</a><a href="#graph">Graph</a><a href="#roadmap">Roadmap</a></nav>
+<main><header id="overview"><div class="eyebrow">Local architecture analysis</div><h1>${title}</h1><p class="muted">Generated <time id="generated-at"></time>. Findings are based on static analysis; score recovery is an estimate.</p></header>
+<div class="summary"><div class="metric"><strong class="score" id="score-value"></strong><span>Architecture score</span></div><div class="metric"><strong id="grade-value"></strong><span>Grade</span></div><div class="metric"><strong id="module-count"></strong><span>Modules</span></div><div class="metric"><strong id="finding-count"></strong><span>Findings</span></div></div>
+<section id="score"><h2>Score breakdown</h2><div class="split"><div class="panel"><div id="category-bars" class="bars"></div></div><div class="panel"><h3>How the score is calculated</h3><p>Starts at 100. Category deductions are weighted, then bounded maintenance and critical-risk adjustments are applied.</p><p id="score-formula" class="path"></p><p class="muted">Category weights and thresholds can be changed in the project configuration.</p></div></div></section>
+<section id="findings"><h2>Findings</h2><div class="controls"><label><span class="muted">Severity </span><select id="findings-filter"><option value="all">All</option><option value="error">Error</option><option value="warning">Warning</option><option value="info">Info</option></select></label><label><span class="muted">Category </span><select id="category-filter"><option value="all">All</option></select></label><input id="findings-search" type="search" aria-label="Search findings" placeholder="Search file, rule, or evidence"></div><div id="findings-list" class="findings"></div></section>
+<section id="hotspots"><h2>Hotspots and quick wins</h2><div class="split"><div class="panel"><h3>Hotspots</h3><ul id="hotspot-list" class="list"></ul></div><div class="panel"><h3>Quick wins</h3><ul id="quickwin-list" class="list"></ul></div></div></section>
+<section id="graph"><h2>Local dependency graph</h2><p class="muted">Select a node to inspect it. The canvas shows up to 32 connected modules; all modules and edges remain in analysis.json.</p><div class="graph-wrap"><svg id="module-graph" class="graph" viewBox="0 0 900 520" role="img" aria-label="Interactive local module dependency graph"></svg></div><p id="graph-detail" class="path" aria-live="polite">Select a module.</p></section>
+<section id="roadmap"><h2>Refactoring roadmap</h2><ol id="roadmap-list" class="list"></ol></section>
+<footer class="footer">NKLattice \xB7 Offline report \xB7 No source upload or remote scripts</footer></main></div>
+<script type="application/json" id="report-data">${data}</script>
+<script>
+(() => {
+  const report = JSON.parse(document.getElementById('report-data').textContent);
+  const byId = id => document.getElementById(id);
+  const text = (id, value) => { byId(id).textContent = String(value); };
+  const add = (parent, tag, value, className) => { const node = document.createElement(tag); if(className) node.className=className; node.textContent=String(value); parent.append(node); return node; };
+  text('generated-at', new Date(report.generatedAt).toLocaleString());
+  text('score-value', report.score.score.toFixed(2)); text('grade-value', report.score.grade);
+  text('module-count', report.graph.modules.length); text('finding-count', report.findings.length);
+  text('score-formula', '100 \u2212 ' + report.score.weightedDeduction + ' weighted \u2212 ' + report.score.maintenanceAdjustment + ' maintenance \u2212 ' + report.score.criticalAdjustment + ' critical = ' + report.score.score);
+  for(const category of report.score.categories){
+    const wrap=add(byId('category-bars'),'div',''); const head=add(wrap,'div','', 'barhead');
+    add(head,'span',category.id + ' \xB7 ' + category.weight + '%'); add(head,'strong',category.score.toFixed(2));
+    const bar=add(wrap,'div','', 'bar'); const fill=add(bar,'i',''); fill.style.width=category.score+'%';
+  }
+  const categories=[...new Set(report.findings.map(item=>item.category))].sort();
+  for(const category of categories){ const option=add(byId('category-filter'),'option',category); option.value=category; }
+  const renderFindings=()=>{
+    const list=byId('findings-list'); list.replaceChildren();
+    const severity=byId('findings-filter').value, category=byId('category-filter').value, query=byId('findings-search').value.toLowerCase();
+    const visible=report.findings.filter(item=>(severity==='all'||item.severity===severity)&&(category==='all'||item.category===category)&&[item.file,item.ruleId,item.evidence].join(' ').toLowerCase().includes(query));
+    if(!visible.length){add(list,'div','No findings match these filters.','empty');return;}
+    for(const item of visible){const card=add(list,'article','', 'finding');const head=add(card,'div','', 'finding-head');add(head,'span',item.severity,item.severity+' chip');add(head,'strong',item.ruleId);add(head,'span',item.file+':'+item.line,'path');add(card,'p',item.evidence);add(card,'small',item.recommendation);}
+  };
+  for(const id of ['findings-filter','category-filter','findings-search']) byId(id).addEventListener('input',renderFindings);
+  renderFindings();
+  for(const hotspot of report.actions.hotspots){const item=add(byId('hotspot-list'),'li','');add(item,'strong',hotspot.file);add(item,'div',hotspot.findingCount+' findings \xB7 '+hotspot.estimatedRecovery,'muted');}
+  for(const win of report.actions.quickWins){const item=add(byId('quickwin-list'),'li','');add(item,'strong',win.file+' \xB7 '+win.ruleId);add(item,'div',win.recommendation,'muted');}
+  for(const step of report.actions.roadmap){const item=add(byId('roadmap-list'),'li','');add(item,'strong',step.file);add(item,'div',step.summary,'muted');}
+  const svg=byId('module-graph'), ns='http://www.w3.org/2000/svg';
+  const degrees=new Map(report.graph.modules.map(module=>[module.path,0]));
+  for(const edge of report.graph.edges){degrees.set(edge.from,(degrees.get(edge.from)||0)+1);degrees.set(edge.to,(degrees.get(edge.to)||0)+1);}
+  const modules=[...report.graph.modules].sort((a,b)=>(degrees.get(b.path)||0)-(degrees.get(a.path)||0)||a.path.localeCompare(b.path)).slice(0,32);
+  const positions=new Map(modules.map((module,index)=>[module.path,{x:450+355*Math.cos(2*Math.PI*index/modules.length),y:260+195*Math.sin(2*Math.PI*index/modules.length)}]));
+  for(const edge of report.graph.edges){const from=positions.get(edge.from),to=positions.get(edge.to);if(!from||!to)continue;const line=document.createElementNS(ns,'line');for(const [key,value] of Object.entries({x1:from.x,y1:from.y,x2:to.x,y2:to.y}))line.setAttribute(key,String(value));svg.append(line);}
+  for(const module of modules){const position=positions.get(module.path);const group=document.createElementNS(ns,'g');const circle=document.createElementNS(ns,'circle');circle.setAttribute('cx',position.x);circle.setAttribute('cy',position.y);circle.setAttribute('r','8');circle.setAttribute('tabindex','0');circle.setAttribute('role','button');circle.setAttribute('aria-label','Inspect '+module.path);const inspect=()=>text('graph-detail',module.path+' \xB7 '+(degrees.get(module.path)||0)+' connections \xB7 '+module.lines+' lines');circle.addEventListener('click',inspect);circle.addEventListener('keydown',event=>{if(event.key==='Enter'||event.key===' '){event.preventDefault();inspect();}});group.append(circle);const label=document.createElementNS(ns,'text');label.setAttribute('x',position.x+12);label.setAttribute('y',position.y+4);label.textContent=module.path.split('/').pop();group.append(label);svg.append(group);}
+})();
+</script></body></html>`;
+}
+
+// src/analysis/rules.ts
+import { matchesGlob } from "path";
+function evaluateRules(graph, config) {
+  const findings = [];
+  const outgoing = new Map(graph.modules.map((module) => [module.path, graph.edges.filter((edge) => edge.from === module.path && !edge.isTypeOnly)]));
+  const incoming = new Map(graph.modules.map((module) => [module.path, graph.edges.filter((edge) => edge.to === module.path && !edge.isTypeOnly)]));
+  const allIncoming = new Map(graph.modules.map((module) => [module.path, graph.edges.filter((edge) => edge.to === module.path)]));
+  for (const cycle of findCycles(graph)) {
+    findings.push({
+      ruleId: "module-cycle",
+      category: "architecture",
+      severity: "error",
+      file: cycle[0],
+      line: 1,
+      evidence: `Circular imports connect ${cycle.join(" \u2192 ")} \u2192 ${cycle[0]}.`,
+      recommendation: "Move shared contracts into a lower-level module and remove one import direction."
+    });
+  }
+  for (const module of graph.modules) {
+    const out = outgoing.get(module.path) ?? [];
+    const into = incoming.get(module.path) ?? [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const imported of module.imports) {
+      if (imported.isTypeOnly) continue;
+      if (seen.has(imported.specifier)) {
+        findings.push({
+          ruleId: "duplicate-import",
+          category: "imports",
+          severity: "warning",
+          file: module.path,
+          line: imported.line,
+          evidence: `Repeated import from ${imported.specifier}.`,
+          recommendation: "Combine imports from the same module."
+        });
+      }
+      seen.add(imported.specifier);
+    }
+    if (out.length > config.thresholds.maxFanOut) {
+      findings.push({
+        ruleId: "high-fan-out",
+        category: "architecture",
+        severity: "warning",
+        file: module.path,
+        line: 1,
+        evidence: `${out.length} outgoing module dependencies exceed ${config.thresholds.maxFanOut}.`,
+        recommendation: "Separate unrelated responsibilities and narrow direct dependencies."
+      });
+    }
+    if (into.length > config.thresholds.maxFanIn) {
+      findings.push({
+        ruleId: "high-fan-in",
+        category: "architecture",
+        severity: "warning",
+        file: module.path,
+        line: 1,
+        evidence: `${into.length} incoming module dependencies exceed ${config.thresholds.maxFanIn}.`,
+        recommendation: "Stabilize this shared interface before making breaking changes."
+      });
+    }
+    if (into.length === 0 && out.length === 0 && graph.modules.length > 1 && !module.isRoute) {
+      findings.push({
+        ruleId: "orphan-module",
+        category: "architecture",
+        severity: "info",
+        file: module.path,
+        line: 1,
+        evidence: "No local module imports to or from this file were resolved.",
+        recommendation: "Confirm whether the file is an entry point or unused code."
+      });
+    }
+    if (into.length > 0 && !module.isRoute) {
+      const usedNames = new Set((allIncoming.get(module.path) ?? []).flatMap((edge) => edge.importedNames));
+      if (!usedNames.has("*")) {
+        for (const name of module.exports) {
+          if (name === "*" || module.typeExports.includes(name)) continue;
+          if (!usedNames.has(name)) {
+            findings.push({
+              ruleId: "unused-export",
+              category: "imports",
+              severity: "info",
+              file: module.path,
+              line: 1,
+              evidence: `Export ${name} has no resolved local importer.`,
+              recommendation: "Remove the export or document its external entry-point usage."
+            });
+          }
+        }
+      }
+    }
+    if (module.componentCount > 0 && module.lines > config.thresholds.maxComponentLines) {
+      findings.push({
+        ruleId: "large-component",
+        category: "components",
+        severity: "warning",
+        file: module.path,
+        line: 1,
+        evidence: `A component file has ${module.lines} lines; limit is ${config.thresholds.maxComponentLines}.`,
+        recommendation: "Extract cohesive child components or hooks."
+      });
+    }
+    if (module.jsxDepth > config.thresholds.maxJsxDepth) {
+      findings.push({
+        ruleId: "deep-jsx",
+        category: "components",
+        severity: "warning",
+        file: module.path,
+        line: 1,
+        evidence: `JSX nesting depth ${module.jsxDepth} exceeds ${config.thresholds.maxJsxDepth}.`,
+        recommendation: "Split deeply nested JSX into named components."
+      });
+    }
+    if (module.complexity > config.thresholds.maxComplexity) {
+      findings.push({
+        ruleId: "high-complexity",
+        category: "complexity",
+        severity: "warning",
+        file: module.path,
+        line: 1,
+        evidence: `Approximate branch complexity ${module.complexity} exceeds ${config.thresholds.maxComplexity}.`,
+        recommendation: "Simplify branches and extract focused functions."
+      });
+    }
+    for (const policy of config.policies) {
+      if (!policy.from.some((pattern) => matchesGlob(module.path, pattern))) continue;
+      for (const edge of out) {
+        const allowed = policy.allow?.some((pattern) => matchesGlob(edge.to, pattern));
+        const disallowed = policy.disallow?.some((pattern) => matchesGlob(edge.to, pattern));
+        if (policy.allow && !allowed || policy.disallow && disallowed) {
+          findings.push({
+            ruleId: policy.id,
+            category: "architecture",
+            severity: policy.severity,
+            file: module.path,
+            line: edge.line,
+            evidence: `${module.path} imports ${edge.to}, violating ${policy.description}.`,
+            recommendation: policy.recommendation ?? "Refactor the import to respect this module boundary."
+          });
+        }
+      }
+    }
+  }
+  const maxDepth = config.thresholds.maxChainDepth;
+  for (const module of graph.modules) {
+    if (maxDepth <= 0) continue;
+    const visit = (path, visited, depth) => {
+      if (depth > maxDepth) return true;
+      for (const edge of outgoing.get(path) ?? []) {
+        if (visited.has(edge.to)) continue;
+        const next = new Set(visited);
+        next.add(edge.to);
+        if (visit(edge.to, next, depth + 1)) return true;
+      }
+      return false;
+    };
+    if (visit(module.path, /* @__PURE__ */ new Set([module.path]), 0)) {
+      findings.push({
+        ruleId: "deep-dependency-chain",
+        category: "architecture",
+        severity: "warning",
+        file: module.path,
+        line: 1,
+        evidence: `A dependency chain exceeds ${maxDepth} local hops.`,
+        recommendation: "Introduce a stable boundary or flatten unnecessary layers."
+      });
+    }
+  }
+  return findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.ruleId.localeCompare(b.ruleId));
+}
+
+// src/analysis/scan.ts
+import { readFile as readFile3 } from "fs/promises";
+import { join as join4, resolve as resolve2 } from "path";
+import fastGlob from "fast-glob";
+
+// src/analysis/parse.ts
+import ts from "typescript";
+function hasModifier(node, kind) {
+  return ts.canHaveModifiers(node) && ts.getModifiers(node)?.some((modifier) => modifier.kind === kind) === true;
+}
+function containsJsx(node) {
+  if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) return true;
+  return ts.forEachChild(node, containsJsx) === true;
+}
+function importNames(clause) {
+  if (!clause) return [];
+  const names = [];
+  if (clause.name) names.push("default");
+  if (clause.namedBindings) {
+    if (ts.isNamespaceImport(clause.namedBindings)) names.push("*");
+    else for (const item of clause.namedBindings.elements) names.push(item.propertyName?.text ?? item.name.text);
+  }
+  return names;
+}
+function sourceKind(path) {
+  if (path.endsWith(".tsx")) return ts.ScriptKind.TSX;
+  if (path.endsWith(".jsx")) return ts.ScriptKind.JSX;
+  if (path.endsWith(".js") || path.endsWith(".mjs") || path.endsWith(".cjs")) return ts.ScriptKind.JS;
+  return ts.ScriptKind.TS;
+}
+function parseModule(path, contents) {
+  const source = ts.createSourceFile(path, contents, ts.ScriptTarget.Latest, true, sourceKind(path));
+  const imports = [];
+  const exports = [];
+  const typeExports = [];
+  let jsxDepth = 0;
+  let complexity = 1;
+  let componentCount = 0;
+  for (const node of source.statements) {
+    if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+      imports.push({
+        specifier: node.moduleSpecifier.text,
+        line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1,
+        importedNames: importNames(node.importClause),
+        isTypeOnly: node.importClause?.isTypeOnly ?? false
+      });
+    }
+    if (ts.isExportDeclaration(node)) {
+      if (node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+        imports.push({
+          specifier: node.moduleSpecifier.text,
+          line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1,
+          importedNames: node.exportClause && ts.isNamedExports(node.exportClause) ? node.exportClause.elements.map((item) => item.propertyName?.text ?? item.name.text) : ["*"],
+          isTypeOnly: node.isTypeOnly
+        });
+      }
+      if (node.exportClause && ts.isNamedExports(node.exportClause)) {
+        exports.push(...node.exportClause.elements.map((item) => item.name.text));
+        if (node.isTypeOnly) typeExports.push(...node.exportClause.elements.map((item) => item.name.text));
+      }
+    }
+    if (hasModifier(node, ts.SyntaxKind.ExportKeyword)) {
+      if (hasModifier(node, ts.SyntaxKind.DefaultKeyword)) exports.push("default");
+      else if (ts.isVariableStatement(node)) {
+        for (const declaration of node.declarationList.declarations) {
+          if (ts.isIdentifier(declaration.name)) exports.push(declaration.name.text);
+        }
+      } else if ("name" in node && node.name && ts.isIdentifier(node.name)) {
+        const name = node.name.text;
+        exports.push(name);
+        if (ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node)) typeExports.push(name);
+      }
+    }
+    if (ts.isFunctionDeclaration(node) && node.name && /^[A-Z]/.test(node.name.text) && containsJsx(node)) {
+      componentCount++;
+    }
+    if (ts.isVariableStatement(node)) {
+      for (const declaration of node.declarationList.declarations) {
+        if (ts.isIdentifier(declaration.name) && /^[A-Z]/.test(declaration.name.text) && declaration.initializer && containsJsx(declaration.initializer)) {
+          componentCount++;
+        }
+      }
+    }
+  }
+  function visit(node, depth) {
+    const isJsx = ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node);
+    const nextDepth = depth + (isJsx ? 1 : 0);
+    jsxDepth = Math.max(jsxDepth, nextDepth);
+    if (ts.isIfStatement(node) || ts.isForStatement(node) || ts.isForOfStatement(node) || ts.isForInStatement(node) || ts.isWhileStatement(node) || ts.isDoStatement(node) || ts.isCatchClause(node) || ts.isConditionalExpression(node) || ts.isCaseBlock(node)) complexity++;
+    if (ts.isBinaryExpression(node) && [ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken].includes(node.operatorToken.kind)) {
+      complexity++;
+    }
+    ts.forEachChild(node, (child) => visit(child, nextDepth));
+  }
+  visit(source, 0);
+  return {
+    path,
+    imports,
+    exports: [...new Set(exports)].sort(),
+    typeExports: [...new Set(typeExports)].sort(),
+    lines: contents.split(/\r?\n/).length,
+    jsxDepth,
+    componentCount,
+    complexity,
+    isRoute: /(^|\/)(app|pages)\/.+(page|layout|route|index)\.[cm]?[jt]sx?$/.test(path) || /(^|\/)app\/(page|layout|route)\.[cm]?[jt]sx?$/.test(path)
+  };
+}
+
+// src/analysis/resolve.ts
+import { readFile as readFile2 } from "fs/promises";
+import { join as join3, relative, resolve, sep } from "path";
+import ts2 from "typescript";
+async function compilerOptions(root) {
+  const path = join3(root, "tsconfig.json");
+  let content;
+  try {
+    content = await readFile2(path, "utf8");
+  } catch {
+    return {};
+  }
+  const json = ts2.parseConfigFileTextToJson(path, content);
+  if (json.error) return {};
+  const parsed = ts2.parseJsonConfigFileContent(json.config, ts2.sys, root);
+  return parsed.options;
+}
+async function resolveImports(root, modules) {
+  const options = await compilerOptions(root);
+  const files = new Set(modules.map((module) => module.path));
+  for (const module of modules) {
+    const from = join3(root, module.path);
+    for (const imported of module.imports) {
+      const result = ts2.resolveModuleName(imported.specifier, from, options, ts2.sys).resolvedModule;
+      if (!result) continue;
+      const path = relative(root, resolve(result.resolvedFileName));
+      if (path === ".." || path.startsWith(`..${sep}`)) continue;
+      const normalized = path.replaceAll("\\", "/");
+      if (files.has(normalized)) imported.resolved = normalized;
+    }
+  }
+}
+
+// src/analysis/scan.ts
+async function scanProject(projectRoot) {
+  const root = resolve2(projectRoot);
+  const files = await fastGlob("**/*.{ts,tsx,js,jsx,mts,mjs,cts,cjs}", {
+    cwd: root,
+    onlyFiles: true,
+    unique: true,
+    followSymbolicLinks: false,
+    ignore: ["**/node_modules/**", "**/.git/**", "**/.next/**", "**/dist/**", "**/coverage/**", "**/*.d.ts"]
+  });
+  const modules = await Promise.all(files.sort().map(async (path) => parseModule(
+    path.replaceAll("\\", "/"),
+    await readFile3(join4(root, path), "utf8")
+  )));
+  await resolveImports(root, modules);
+  return modules;
+}
+
+// src/analysis/score.ts
+function round(value) {
+  return Math.round(value * 100) / 100;
+}
+function grade(score) {
+  if (score >= 95) return "A+";
+  if (score >= 90) return "A";
+  if (score >= 80) return "B";
+  if (score >= 70) return "C";
+  if (score >= 55) return "D";
+  return "F";
+}
+function scoreFindings(findings, config) {
+  const penalties = { error: 18, warning: 7, info: 2 };
+  const categories = Object.entries(config.weights).map(([id, weight]) => {
+    const categoryFindings = findings.filter((finding) => finding.category === id).sort((a, b) => a.ruleId.localeCompare(b.ruleId) || a.file.localeCompare(b.file));
+    const occurrences = /* @__PURE__ */ new Map();
+    let deduction = 0;
+    for (const finding of categoryFindings) {
+      const occurrence = (occurrences.get(finding.ruleId) ?? 0) + 1;
+      occurrences.set(finding.ruleId, occurrence);
+      deduction += penalties[finding.severity] / Math.sqrt(occurrence);
+    }
+    deduction = Math.min(100, deduction);
+    return { id, weight, score: round(100 - deduction), deduction: round(deduction), findingCount: categoryFindings.length };
+  });
+  const weightedDeduction = round(categories.reduce((sum, category) => sum + category.deduction * category.weight / 100, 0));
+  const maintenanceAdjustment = round(Math.min(5, Math.max(0, findings.length - 10) * 0.15));
+  const criticalAdjustment = round(Math.min(10, findings.filter((finding) => finding.severity === "error").length * 1.5));
+  const score = round(Math.max(0, Math.min(100, 100 - weightedDeduction - maintenanceAdjustment - criticalAdjustment)));
+  return { score, grade: grade(score), weightedDeduction, maintenanceAdjustment, criticalAdjustment, categories };
+}
+
+// src/analysis/analyze.ts
+async function analyzeProject(projectRoot, options = {}) {
+  const root = resolve3(projectRoot);
+  const config = await loadAnalysisConfig(root);
+  const modules = await scanProject(root);
+  if (modules.length === 0) throw new Error("No supported source files found");
+  const graph = buildGraph(modules);
+  const findings = evaluateRules(graph, config);
+  let name = basename(root);
+  try {
+    const manifest = JSON.parse(await readFile4(join5(root, "package.json"), "utf8"));
+    if (manifest && typeof manifest === "object" && "name" in manifest && typeof manifest.name === "string") name = manifest.name;
+  } catch {
+  }
+  const report = {
+    schema: "urn:nklattice:analysis:1",
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    project: { name },
+    graph,
+    findings,
+    score: scoreFindings(findings, config),
+    actions: recommendActions(findings)
+  };
+  const outputDirectory = resolve3(options.outputDirectory ?? join5(root, ".nklattice-report"));
+  await mkdir2(outputDirectory, { recursive: true });
+  await archivePrevious(outputDirectory);
+  await writeFile(join5(outputDirectory, "analysis.json"), `${JSON.stringify(report, null, 2)}
+`);
+  await writeFile(join5(outputDirectory, "report.html"), renderHtml(report));
+  return report;
+}
+
+// src/governance/check.ts
+import { resolve as resolve5, relative as relative4, sep as sep3 } from "path";
+import { satisfies, subset, valid, validRange } from "semver";
+
+// src/governance/discover.ts
+import { readFile as readFile5 } from "fs/promises";
+import { join as join6, relative as relative2 } from "path";
+import fastGlob2 from "fast-glob";
+var profiles = /* @__PURE__ */ new Set(["next", "vite-react", "react"]);
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function dependencyMap(manifest) {
+  const result = {};
+  for (const section2 of ["dependencies", "devDependencies", "optionalDependencies"]) {
+    const entries = manifest[section2];
+    if (entries === void 0) continue;
+    if (!isRecord(entries)) throw new Error(`Invalid ${section2} in package.json`);
+    for (const [name, version] of Object.entries(entries)) {
+      if (typeof version !== "string") throw new Error(`Invalid version for ${name}`);
+      if (result[name] !== void 0 && result[name] !== version) {
+        throw new Error(`Conflicting declarations for ${name}`);
+      }
+      result[name] = version;
+    }
+  }
+  return result;
+}
+function profileFor(manifest, dependencies) {
+  const config = manifest.nklattice;
+  if (config !== void 0) {
+    if (!isRecord(config) || typeof config.profile !== "string" || !profiles.has(config.profile)) {
+      throw new Error("Invalid nklattice.profile in package.json");
+    }
+    return config.profile;
+  }
+  if (dependencies.next !== void 0) return "next";
+  if (dependencies.vite !== void 0 && dependencies.react !== void 0) return "vite-react";
+  if (dependencies.react !== void 0) return "react";
+  return void 0;
+}
+async function discoverApps(scanRoot, workspaceRoot) {
+  const manifests = await fastGlob2(["package.json", "**/package.json"], {
+    cwd: scanRoot,
+    onlyFiles: true,
+    unique: true,
+    followSymbolicLinks: false,
+    ignore: ["**/node_modules/**", "**/.git/**", "**/dist/**", "**/.next/**", "**/coverage/**"]
+  });
+  const apps = [];
+  for (const path of manifests.sort()) {
+    const directory = join6(scanRoot, path, "..");
+    let parsed;
+    try {
+      parsed = JSON.parse(await readFile5(join6(scanRoot, path), "utf8"));
+    } catch {
+      throw new Error(`Invalid package.json: ${path}`);
+    }
+    if (!isRecord(parsed)) throw new Error(`Invalid package.json: ${path}`);
+    const dependencies = dependencyMap(parsed);
+    const profile = profileFor(parsed, dependencies);
+    if (!profile) continue;
+    apps.push({
+      directory,
+      relativePath: relative2(workspaceRoot, directory).replaceAll("\\", "/") || ".",
+      profile,
+      dependencies
+    });
+  }
+  return apps;
+}
+
+// src/governance/lockfiles.ts
+import { access as access2, readFile as readFile6 } from "fs/promises";
+import { dirname, join as join7, relative as relative3, resolve as resolve4, sep as sep2 } from "path";
+import YAML from "yaml";
+function record2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function exists2(path) {
+  try {
+    await access2(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function within(parent, child) {
+  const rel = relative3(parent, child);
+  return rel === "" || rel !== ".." && !rel.startsWith(`..${sep2}`);
+}
+async function findLockfile(appDirectory, workspaceRoot) {
+  let directory = resolve4(appDirectory);
+  const boundary = resolve4(workspaceRoot);
+  if (!within(boundary, directory)) throw new Error("Application is outside workspace root");
+  while (within(boundary, directory)) {
+    const npm = join7(directory, "package-lock.json");
+    const pnpm = join7(directory, "pnpm-lock.yaml");
+    const [hasNpm, hasPnpm] = await Promise.all([exists2(npm), exists2(pnpm)]);
+    if (hasNpm && hasPnpm) throw new Error(`Ambiguous lockfiles in ${directory}`);
+    if (hasNpm) return { path: npm, kind: "npm", root: directory };
+    if (hasPnpm) return { path: pnpm, kind: "pnpm", root: directory };
+    if (directory === boundary) break;
+    directory = dirname(directory);
+  }
+  throw new Error(`No lockfile found for ${appDirectory}`);
+}
+function section(importer, name) {
+  for (const key of ["dependencies", "devDependencies", "optionalDependencies"]) {
+    const entries = importer[key];
+    if (record2(entries) && Object.hasOwn(entries, name)) return entries[name];
+  }
+  return void 0;
+}
+function readNpm(raw, root, app, name) {
+  let lock;
+  try {
+    lock = JSON.parse(raw);
+  } catch {
+    throw new Error("Malformed npm lockfile JSON");
+  }
+  if (!record2(lock) || lock.lockfileVersion !== 3 || !record2(lock.packages)) {
+    throw new Error("Unsupported or malformed npm lockfile");
+  }
+  const importerKey = relative3(root, app.directory).replaceAll("\\", "/");
+  const importer = lock.packages[importerKey];
+  if (!record2(importer)) throw new Error(`Missing npm lockfile importer ${importerKey || "."}`);
+  const specifier = section(importer, name);
+  if (specifier !== void 0 && typeof specifier !== "string") {
+    throw new Error(`Malformed npm lockfile specifier for ${name}`);
+  }
+  let resolved;
+  const segments = importerKey ? importerKey.split("/") : [];
+  while (true) {
+    const prefix = segments.length ? `${segments.join("/")}/` : "";
+    resolved = lock.packages[`${prefix}node_modules/${name}`];
+    if (resolved !== void 0 || segments.length === 0) break;
+    segments.pop();
+  }
+  if (specifier !== void 0 && !record2(resolved)) {
+    throw new Error(`Missing npm lockfile package resolution for ${name}`);
+  }
+  if (record2(resolved) && typeof resolved.version !== "string") {
+    throw new Error(`Malformed npm lockfile package version for ${name}`);
+  }
+  return { specifier, version: record2(resolved) ? resolved.version : void 0 };
+}
+function readPnpm(raw, root, app, name) {
+  let lock;
+  try {
+    lock = YAML.parse(raw);
+  } catch {
+    throw new Error("Malformed pnpm lockfile YAML");
+  }
+  if (!record2(lock) || String(lock.lockfileVersion) !== "9.0" || !record2(lock.importers) || !record2(lock.packages) || !record2(lock.snapshots)) {
+    throw new Error("Unsupported or malformed pnpm lockfile");
+  }
+  const importerKey = relative3(root, app.directory).replaceAll("\\", "/") || ".";
+  const importer = lock.importers[importerKey];
+  if (!record2(importer)) throw new Error(`Missing pnpm lockfile importer ${importerKey}`);
+  const entry = section(importer, name);
+  if (entry === void 0) return {};
+  if (!record2(entry) || typeof entry.specifier !== "string" || typeof entry.version !== "string") {
+    throw new Error(`Malformed pnpm lockfile dependency for ${name}`);
+  }
+  const version = entry.version.match(/^(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/)?.[1];
+  if (!version) throw new Error(`Unsupported pnpm resolution for ${name}`);
+  const packageKeys = [`${name}@${version}`, `/${name}@${version}`];
+  if (!packageKeys.some((key) => record2(lock.packages) && Object.hasOwn(lock.packages, key))) {
+    throw new Error(`Missing pnpm package entry for ${name}@${version}`);
+  }
+  const snapshotKeys = [`${name}@${entry.version}`, `/${name}@${entry.version}`, ...packageKeys];
+  if (!snapshotKeys.some((key) => Object.hasOwn(lock.snapshots, key))) {
+    throw new Error(`Missing pnpm snapshot for ${name}@${entry.version}`);
+  }
+  return { specifier: entry.specifier, version };
+}
+async function readResolution(app, workspaceRoot, name) {
+  const lockfile = await findLockfile(app.directory, workspaceRoot);
+  const raw = await readFile6(lockfile.path, "utf8");
+  return lockfile.kind === "npm" ? readNpm(raw, lockfile.root, app, name) : readPnpm(raw, lockfile.root, app, name);
+}
+
+// src/governance/check.ts
+async function checkGovernance(options) {
+  const scanRoot = resolve5(options.scanRoot);
+  const workspaceRoot = resolve5(options.workspaceRoot ?? scanRoot);
+  const path = relative4(workspaceRoot, scanRoot);
+  if (path === ".." || path.startsWith(`..${sep3}`)) {
+    throw new Error("Scan root must be inside workspace root");
+  }
+  const apps = await discoverApps(scanRoot, workspaceRoot);
+  if (apps.length === 0) throw new Error("No managed applications found");
+  const findings = [];
+  for (const app of apps) {
+    const requirements = options.policy.profiles[app.profile];
+    if (!requirements) throw new Error(`Policy does not define profile ${app.profile}`);
+    for (const [packageName, expected] of Object.entries(requirements)) {
+      const declared = app.dependencies[packageName];
+      const resolution = declared === void 0 ? { specifier: void 0, version: void 0 } : await readResolution(app, workspaceRoot, packageName);
+      const reasons = [];
+      const declaredRange = declared === void 0 ? null : validRange(declared);
+      if (declared === void 0) reasons.push("required manifest declaration missing");
+      else if (declaredRange === null) reasons.push("unsupported manifest range");
+      else if (!subset(declaredRange, expected)) reasons.push("manifest range allows versions below minimum");
+      if (resolution.specifier !== declared) reasons.push("lockfile specifier differs");
+      if (resolution.version === void 0) reasons.push("lockfile resolution missing");
+      else if (!valid(resolution.version)) reasons.push("invalid lockfile resolution");
+      else {
+        if (!satisfies(resolution.version, expected)) reasons.push("lockfile resolution does not satisfy minimum");
+        if (declaredRange !== null && !satisfies(resolution.version, declaredRange)) {
+          reasons.push("lockfile resolution outside manifest range");
+        }
+      }
+      if (reasons.length) {
+        findings.push({
+          app: app.relativePath,
+          packageName,
+          expected,
+          declared,
+          lockfileSpecifier: resolution.specifier,
+          locked: resolution.version,
+          reason: reasons.join("; ")
+        });
+      }
+    }
+  }
+  return {
+    appsChecked: apps.length,
+    findings,
+    policyVersion: options.policy.policyVersion,
+    policySource: options.policy.source,
+    policySha256: options.policy.sha256
+  };
+}
+
+// src/governance/policy.ts
+import { createHash } from "crypto";
+import { readFile as readFile7 } from "fs/promises";
+import { resolve as resolve6 } from "path";
+import { valid as valid2 } from "semver";
+var exactVersion = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+var minimumVersion = /^>=(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+function record3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parsePolicy(raw, source) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`Policy at ${source} is not valid JSON`);
+  }
+  if (!record3(parsed) || parsed.schemaVersion !== 2) {
+    throw new Error("Policy schemaVersion must be 2");
+  }
+  if (typeof parsed.policyVersion !== "string" || !exactVersion.test(parsed.policyVersion) || valid2(parsed.policyVersion) === null) {
+    throw new Error("Policy policyVersion must be an exact version");
+  }
+  if (!record3(parsed.profiles) || Object.keys(parsed.profiles).length === 0) {
+    throw new Error("Policy profiles must be a nonempty object");
+  }
+  const profiles2 = {};
+  for (const [name, rules] of Object.entries(parsed.profiles)) {
+    if (!record3(rules) || Object.keys(rules).length === 0) {
+      throw new Error(`Policy profile ${name} must list packages`);
+    }
+    const versions = {};
+    for (const [packageName, version] of Object.entries(rules)) {
+      if (typeof version !== "string" || !minimumVersion.test(version) || valid2(version.slice(2)) === null) {
+        throw new Error(`Policy minimum version (>=X.Y.Z) required for ${packageName} in ${name}`);
+      }
+      versions[packageName] = version;
+    }
+    profiles2[name] = versions;
+  }
+  return {
+    schemaVersion: 2,
+    policyVersion: parsed.policyVersion,
+    profiles: profiles2,
+    source,
+    sha256: createHash("sha256").update(raw).digest("hex")
+  };
+}
+async function loadPolicy(source) {
+  if (/^https?:\/\//i.test(source)) {
+    if (!source.startsWith("https://")) {
+      throw new Error("Remote policy requires HTTPS");
+    }
+    const response = await fetch(source);
+    if (response.url && !response.url.startsWith("https://")) {
+      throw new Error("Remote policy redirects must remain on HTTPS");
+    }
+    if (!response.ok) {
+      throw new Error(`Policy fetch failed with HTTP ${response.status}`);
+    }
+    return parsePolicy(await response.text(), source);
+  }
+  return parsePolicy(await readFile7(resolve6(source), "utf8"), source);
+}
+
+// src/runtime.ts
+function isSupportedNodeVersion(version) {
+  const major = Number(version.split(".", 1)[0]);
+  return Number.isInteger(major) && major >= 24;
+}
+
+// src/cli.ts
+var defaultOutput = {
+  out: (text) => process.stdout.write(text),
+  err: (text) => process.stderr.write(text)
+};
+async function runCli(arguments_, output = defaultOutput) {
+  if (!isSupportedNodeVersion(process.versions.node)) {
+    output.err(`NKLattice error: Node.js 24 or newer is required; found ${process.version}.
+`);
+    return 3;
+  }
+  let exitCode = 0;
+  const program = new Command();
+  program.name("lattice").description("Architecture analysis and dependency governance for React teams").version("0.2.0");
+  program.configureOutput({ writeOut: output.out, writeErr: output.err });
+  program.exitOverride();
+  program.command("analyze [path]").description("Analyze local architecture and write offline reports").option("--output <directory>", "Output directory").action(async (path, flags) => {
+    const root = resolve7(path ?? ".");
+    const destination = resolve7(flags.output ?? join8(root, ".nklattice-report"));
+    const report = await analyzeProject(root, { outputDirectory: destination });
+    output.out(`NKLattice analyzed ${report.graph.modules.length} modules. Score ${report.score.score} (${report.score.grade}); ${report.findings.length} findings.
+`);
+    output.out(`Reports: ${join8(destination, "report.html")} and ${join8(destination, "analysis.json")}
+`);
+  });
+  program.command("doctor [path]").description("Check whether a directory contains supported source files").action(async (path) => {
+    const modules = await scanProject(path ?? ".");
+    if (modules.length === 0) throw new Error("No supported source files found");
+    output.out(`NKLattice doctor: Node ${process.version}; ${modules.length} supported source file${modules.length === 1 ? "" : "s"} found.
+`);
+  });
+  program.command("init [path]").description("Create a project configuration file").action(async (path) => {
+    const destination = join8(resolve7(path ?? "."), ".nklattice.json");
+    await writeFile2(destination, '{\n  "analysis": {},\n  "policies": []\n}\n', { flag: "wx" });
+    output.out(`Created ${destination}
+`);
+  });
+  program.command("governance").description("Check centrally approved dependency versions").command("check [path]").option("--policy <source>", "Local file or HTTPS policy URL").option("--workspace-root <path>", "Repository root containing a shared lockfile").option("--expect-apps <count>", "Required number of managed applications").option("--json", "Machine-readable result").action(async (path, flags) => {
+    let expectedApps;
+    if (flags.expectApps !== void 0) {
+      if (!/^[1-9]\d*$/.test(flags.expectApps)) throw new Error("--expect-apps must be a positive integer");
+      expectedApps = Number(flags.expectApps);
+      if (!Number.isSafeInteger(expectedApps)) throw new Error("--expect-apps must be a positive integer");
+    }
+    const policyPath = flags.policy ?? resolve7(dirname2(fileURLToPath(import.meta.url)), "../governance/policy.json");
+    const policy = await loadPolicy(policyPath);
+    const result = await checkGovernance({
+      scanRoot: path ?? ".",
+      workspaceRoot: flags.workspaceRoot,
+      policy
+    });
+    if (expectedApps !== void 0 && result.appsChecked !== expectedApps) {
+      throw new Error(`Expected ${expectedApps} managed applications, found ${result.appsChecked}`);
+    }
+    if (flags.json) {
+      output.out(`${JSON.stringify(result, null, 2)}
+`);
+    } else if (result.findings.length === 0) {
+      output.out(`${result.appsChecked} application${result.appsChecked === 1 ? "" : "s"} checked; governance passed. Policy ${result.policyVersion} (${result.policySource}).
+`);
+    } else {
+      output.out(`${result.appsChecked} application${result.appsChecked === 1 ? "" : "s"} checked; ${result.findings.length} dependency mismatch${result.findings.length === 1 ? "" : "es"}.
+`);
+      for (const finding of result.findings) {
+        output.out(`${finding.app}: ${finding.packageName} required ${finding.expected}; declared ${finding.declared ?? "missing"}; lockfile specifier ${finding.lockfileSpecifier ?? "missing"}; locked ${finding.locked ?? "missing"} (${finding.reason}).
+`);
+      }
+    }
+    if (result.findings.length > 0) exitCode = 7;
+  });
+  try {
+    await program.parseAsync(arguments_, { from: "user" });
+  } catch (error) {
+    if (error instanceof CommanderError && ["commander.version", "commander.helpDisplayed"].includes(error.code)) return 0;
+    const message = error instanceof Error ? error.message : String(error);
+    output.err(`NKLattice error: ${message}
+`);
+    return 3;
+  }
+  return exitCode;
+}
+if (process.argv[1] && realpathSync(resolve7(process.argv[1])) === realpathSync(fileURLToPath(import.meta.url))) {
+  runCli(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+  });
+}
+export {
+  runCli
+};