airgen-cli 0.1.6 → 0.1.8

package/dist/commands/diagrams.js

@@ -1,4 +1,205 @@
+import { writeFileSync } from "node:fs";
 import { output, printTable, isJsonMode } from "../output.js";
+// ── Mermaid rendering helpers ─────────────────────────────────
+function sanitizeId(id) {
+    return id.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+function mermaidNodeShape(block) {
+    const id = sanitizeId(block.id);
+    const label = block.name.replace(/"/g, "'");
+    const stereo = block.stereotype?.replace(/[«»<>]/g, "") ?? block.kind ?? "block";
+    const display = `"«${stereo}»\\n${label}"`;
+    switch (block.kind) {
+        case "system": return `${id}[${display}]`;
+        case "subsystem": return `${id}[${display}]`;
+        case "actor": return `${id}([${display}])`;
+        case "external": return `${id}>${display}]`;
+        case "interface": return `${id}{{${display}}}`;
+        default: return `${id}[${display}]`; // component
+    }
+}
+function mermaidArrow(kind) {
+    switch (kind) {
+        case "flow": return "==>";
+        case "dependency": return "-.->";
+        case "composition": return "--*";
+        default: return "-->"; // association
+    }
+}
+function mermaidStyle(block) {
+    const id = sanitizeId(block.id);
+    switch (block.kind) {
+        case "system": return `style ${id} fill:#ebf8ff,stroke:#1a365d,color:#1a365d`;
+        case "subsystem": return `style ${id} fill:#f0f5ff,stroke:#2c5282,color:#2c5282`;
+        case "actor": return `style ${id} fill:#f0fff4,stroke:#276749,color:#276749`;
+        case "external": return `style ${id} fill:#fffbeb,stroke:#92400e,color:#92400e`;
+        case "interface": return `style ${id} fill:#faf5ff,stroke:#6b21a8,color:#6b21a8`;
+        default: return null;
+    }
+}
+// ── Terminal (layered) rendering ─────────────────────────────
+const KIND_ICONS = {
+    system: "■", subsystem: "□", component: "◦",
+    actor: "☺", external: "◇", interface: "◈",
+};
+function kindArrow(kind) {
+    switch (kind) {
+        case "flow": return "══▶";
+        case "dependency": return "--▷";
+        case "composition": return "◆──";
+        default: return "──▶";
+    }
+}
+function renderTerminal(blocks, connectors) {
+    const blockMap = new Map(blocks.map(b => [b.id, b]));
+    // Build adjacency
+    const outEdges = new Map();
+    const inEdges = new Map();
+    const inDegree = new Map();
+    for (const b of blocks)
+        inDegree.set(b.id, 0);
+    for (const c of connectors) {
+        const out = outEdges.get(c.source) ?? [];
+        out.push({ target: c.target, label: c.label ?? "", kind: c.kind });
+        outEdges.set(c.source, out);
+        const inn = inEdges.get(c.target) ?? [];
+        inn.push({ source: c.source, label: c.label ?? "", kind: c.kind });
+        inEdges.set(c.target, inn);
+        inDegree.set(c.target, (inDegree.get(c.target) ?? 0) + 1);
+    }
+    // BFS layering (Kahn's algorithm, cycles go to last layer)
+    const layer = new Map();
+    const queue = [];
+    for (const b of blocks) {
+        if ((inDegree.get(b.id) ?? 0) === 0) {
+            queue.push(b.id);
+            layer.set(b.id, 0);
+        }
+    }
+    let maxLayer = 0;
+    while (queue.length > 0) {
+        const id = queue.shift();
+        const curLayer = layer.get(id);
+        for (const e of outEdges.get(id) ?? []) {
+            if (layer.has(e.target))
+                continue;
+            const newDeg = (inDegree.get(e.target) ?? 1) - 1;
+            inDegree.set(e.target, newDeg);
+            if (newDeg <= 0) {
+                const nextLayer = curLayer + 1;
+                layer.set(e.target, nextLayer);
+                maxLayer = Math.max(maxLayer, nextLayer);
+                queue.push(e.target);
+            }
+        }
+    }
+    // Assign remaining (cycle members) to maxLayer + 1
+    for (const b of blocks) {
+        if (!layer.has(b.id)) {
+            layer.set(b.id, maxLayer + 1);
+            maxLayer = maxLayer + 1;
+        }
+    }
+    // Group blocks by layer
+    const layers = [];
+    for (let i = 0; i <= maxLayer; i++)
+        layers.push([]);
+    for (const b of blocks) {
+        layers[layer.get(b.id)].push(b);
+    }
+    // Compute column widths for the block name column
+    const nameColWidth = Math.max(...blocks.map(b => b.name.length + 4), 20);
+    const icon = (b) => KIND_ICONS[b.kind ?? ""] ?? "□";
+    const lines = [];
+    const PAD = "  ";
+    for (let li = 0; li < layers.length; li++) {
+        const layerBlocks = layers[li];
+        if (layerBlocks.length === 0)
+            continue;
+        // Layer header
+        const layerLabel = li === 0 ? "Sources" : li === layers.length - 1 ? "Outputs" : `Layer ${li}`;
+        lines.push(`${PAD}┄┄ ${layerLabel} ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄`);
+        lines.push("");
+        for (const b of layerBlocks) {
+            const blockIcon = icon(b);
+            const stereo = b.stereotype?.replace(/[«»<>]/g, "") ?? b.kind ?? "block";
+            const nameStr = `${blockIcon} ${b.name}`;
+            const paddedName = nameStr + " ".repeat(Math.max(0, nameColWidth - nameStr.length));
+            // Incoming connections for this block
+            const incoming = inEdges.get(b.id) ?? [];
+            // Outgoing connections
+            const outgoing = outEdges.get(b.id) ?? [];
+            // Build the box line
+            const boxTop = `${PAD}  ┌${"─".repeat(nameColWidth + 2)}┐`;
+            const boxSte = `${PAD}  │ «${stereo}»${" ".repeat(Math.max(0, nameColWidth - stereo.length - 2))} │`;
+            const boxNam = `${PAD}  │ ${paddedName} │`;
+            const boxBot = `${PAD}  └${"─".repeat(nameColWidth + 2)}┘`;
+            lines.push(boxTop);
+            lines.push(boxSte);
+            lines.push(boxNam);
+            lines.push(boxBot);
+            // Show incoming connections (who feeds this block)
+            if (incoming.length > 0) {
+                for (const e of incoming) {
+                    const srcBlock = blockMap.get(e.source);
+                    const srcName = srcBlock?.name ?? "?";
+                    const arrow = kindArrow(e.kind);
+                    const label = e.label ? ` (${e.label})` : "";
+                    lines.push(`${PAD}    ◀── ${srcName}${label}`);
+                }
+            }
+            // Show outgoing connections (where this block sends data)
+            if (outgoing.length > 0) {
+                for (const e of outgoing) {
+                    const tgtBlock = blockMap.get(e.target);
+                    const tgtName = tgtBlock?.name ?? "?";
+                    const arrow = kindArrow(e.kind);
+                    const label = e.label ? ` ${e.label} ` : " ";
+                    lines.push(`${PAD}    ${arrow}${label}──▶ ${tgtName}`);
+                }
+            }
+            lines.push("");
+        }
+        // Visual separator between layers
+        if (li < layers.length - 1) {
+            lines.push(`${PAD}        │`);
+            lines.push(`${PAD}        ▼`);
+            lines.push("");
+        }
+    }
+    // Legend
+    lines.push(`${PAD}┄┄ Legend ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄`);
+    lines.push(`${PAD}  ☺ actor   ■ system   □ subsystem   ◦ component   ◇ external   ◈ interface`);
+    lines.push(`${PAD}  ──▶ association   ══▶ flow   ◆── composition   --▷ dependency`);
+    return lines.join("\n");
+}
+function renderMermaid(blocks, connectors, direction) {
+    const lines = [`flowchart ${direction}`];
+    // Nodes
+    for (const b of blocks) {
+        lines.push(`  ${mermaidNodeShape(b)}`);
+    }
+    // Edges
+    for (const c of connectors) {
+        const src = sanitizeId(c.source);
+        const tgt = sanitizeId(c.target);
+        const arrow = mermaidArrow(c.kind);
+        if (c.label) {
+            lines.push(`  ${src} ${arrow}|"${c.label.replace(/"/g, "'")}"| ${tgt}`);
+        }
+        else {
+            lines.push(`  ${src} ${arrow} ${tgt}`);
+        }
+    }
+    // Styles
+    const styles = blocks.map(mermaidStyle).filter(Boolean);
+    if (styles.length > 0) {
+        lines.push("");
+        for (const s of styles)
+            lines.push(`  ${s}`);
+    }
+    return lines.join("\n");
+}
 export function registerDiagramCommands(program, client) {
     const cmd = program.command("diagrams").alias("diag").description("Architecture diagrams");
     cmd
@@ -35,6 +236,60 @@ export function registerDiagramCommands(program, client) {
         ]);
         output({ blocks, connectors });
     });
+    cmd
+        .command("render")
+        .description("Render a diagram in the terminal or as Mermaid syntax")
+        .argument("<tenant>", "Tenant slug")
+        .argument("<project>", "Project slug")
+        .argument("<id>", "Diagram ID")
+        .option("--format <fmt>", "Output format: text, mermaid", "text")
+        .option("--direction <dir>", "Layout direction for mermaid: TB, LR, BT, RL", "TB")
+        .option("-o, --output <file>", "Write to file instead of stdout")
+        .option("--wrap", "Wrap mermaid in markdown fenced code block")
+        .action(async (tenant, project, id, opts) => {
+        // Fetch diagram metadata + blocks + connectors in parallel
+        const [diagramData, blocksData, connectorsData] = await Promise.all([
+            client.get(`/architecture/diagrams/${tenant}/${project}`),
+            client.get(`/architecture/blocks/${tenant}/${project}/${id}`),
+            client.get(`/architecture/connectors/${tenant}/${project}/${id}`),
+        ]);
+        const diagram = (diagramData.diagrams ?? []).find(d => d.id === id);
+        const blocks = blocksData.blocks ?? [];
+        const connectors = connectorsData.connectors ?? [];
+        if (blocks.length === 0) {
+            console.log("Empty diagram — no blocks to render.");
+            return;
+        }
+        let rendered;
+        if (opts.format === "mermaid") {
+            rendered = renderMermaid(blocks, connectors, opts.direction);
+            if (isJsonMode()) {
+                output({ mermaid: rendered, blocks: blocks.length, connectors: connectors.length });
+                return;
+            }
+            if (opts.wrap)
+                rendered = "```mermaid\n" + rendered + "\n```";
+        }
+        else {
+            // Terminal text format
+            const header = diagram?.name ?? id;
+            const headerLine = `  ${header}`;
+            const underline = `  ${"═".repeat(header.length)}`;
+            const stats = `  ${blocks.length} blocks, ${connectors.length} connectors`;
+            rendered = [headerLine, underline, stats, "", renderTerminal(blocks, connectors)].join("\n");
+            if (isJsonMode()) {
+                output({ text: rendered, blocks: blocks.length, connectors: connectors.length });
+                return;
+            }
+        }
+        if (opts.output) {
+            writeFileSync(opts.output, rendered + "\n", "utf-8");
+            console.log(`Diagram written to ${opts.output}`);
+        }
+        else {
+            console.log(rendered);
+        }
+    });
     cmd
         .command("create")
         .description("Create a new diagram")

package/dist/commands/lint.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import type { AirgenClient } from "../client.js";
+export declare function registerLintCommands(program: Command, client: AirgenClient): void;

package/dist/commands/lint.js

@@ -0,0 +1,415 @@
+import { writeFileSync } from "node:fs";
+import { UhtClient } from "../uht-client.js";
+import { isJsonMode } from "../output.js";
+// ── Constants ────────────────────────────────────────────────
+const PAGE_SIZE = 100;
+const MAX_PAGES = 50;
+// ── Helpers ──────────────────────────────────────────────────
+async function fetchAllRequirements(client, tenant, project) {
+    const all = [];
+    for (let page = 1; page <= MAX_PAGES; page++) {
+        const data = await client.get(`/requirements/${tenant}/${project}`, {
+            page: String(page),
+            limit: String(PAGE_SIZE),
+        });
+        all.push(...(data.data ?? []));
+        if (page >= (data.meta?.totalPages ?? 1))
+            break;
+    }
+    return all.filter(r => !r.deleted && !r.deletedAt);
+}
+/**
+ * Extract domain concepts from requirement text.
+ * Looks for:
+ *  - Subjects: "The <concept> shall..."
+ *  - References: "using the <concept>", "via the <concept>", "from the <concept>"
+ *  - Named systems: multi-word capitalized terms, known patterns
+ */
+function extractConcepts(requirements) {
+    const conceptRefs = new Map();
+    function addConcept(concept, ref) {
+        const normalized = concept.toLowerCase().trim();
+        if (normalized.length < 3 || normalized.length > 60)
+            return;
+        // Skip generic words
+        const skip = new Set(["system", "the system", "it", "this", "all", "each", "any"]);
+        if (skip.has(normalized))
+            return;
+        const refs = conceptRefs.get(normalized) ?? [];
+        if (!refs.includes(ref))
+            refs.push(ref);
+        conceptRefs.set(normalized, refs);
+    }
+    for (const req of requirements) {
+        if (!req.text || !req.ref)
+            continue;
+        const text = req.text;
+        // "The <concept> shall"
+        const subjectMatch = text.match(/^(?:the|a|an)\s+(.+?)\s+shall\b/i);
+        if (subjectMatch)
+            addConcept(subjectMatch[1], req.ref);
+        // "If the <concept> detects/is/has..."
+        const ifMatch = text.match(/^if\s+the\s+(.+?)\s+(?:detects?|is|has|does|fails?|receives?)\b/i);
+        if (ifMatch)
+            addConcept(ifMatch[1], req.ref);
+        // "While the <concept> is..."
+        const whileMatch = text.match(/^while\s+(?:the\s+)?(.+?)\s+is\b/i);
+        if (whileMatch)
+            addConcept(whileMatch[1], req.ref);
+        // "When the <concept> designates/detects..."
+        const whenMatch = text.match(/^when\s+the\s+(.+?)\s+(?:designates?|detects?|receives?|completes?)\b/i);
+        if (whenMatch)
+            addConcept(whenMatch[1], req.ref);
+        // References: "using the X", "via X", "from the X", "to the X"
+        const refPatterns = [
+            /using\s+(?:the\s+)?(.+?)(?:\s+(?:for|to|at|in|with)\b|[.,;]|$)/gi,
+            /via\s+(?:the\s+)?(.+?)(?:\s+(?:for|to|at|in|with)\b|[.,;]|$)/gi,
+            /from\s+the\s+(.+?)(?:\s+(?:for|to|at|in|with)\b|[.,;]|$)/gi,
+            /(?:to|into)\s+the\s+(.+?)(?:\s+(?:for|to|at|in|with)\b|[.,;]|$)/gi,
+            /(?:against|per|in accordance with)\s+(.+?)(?:\s+(?:for|to|at|in|with)\b|[.,;]|$)/gi,
+        ];
+        for (const pat of refPatterns) {
+            let m;
+            while ((m = pat.exec(text)) !== null) {
+                addConcept(m[1], req.ref);
+            }
+        }
+    }
+    return conceptRefs;
+}
+/**
+ * Rank concepts by frequency and pick top N.
+ */
+function topConcepts(conceptRefs, maxCount) {
+    return [...conceptRefs.entries()]
+        .sort((a, b) => b[1].length - a[1].length)
+        .slice(0, maxCount);
+}
+// ── Analysis ─────────────────────────────────────────────────
+function analyzeFindings(concepts, comparisons, requirements) {
+    const findings = [];
+    const conceptMap = new Map(concepts.map(c => [c.name, c]));
+    // 1. Physical mismatch: non-physical concepts with environmental/physical requirements
+    const envKeywords = /temperature|shock|vibrat|humidity|nbc|contamina|electromagnetic|emc|climatic/i;
+    for (const c of concepts) {
+        if (c.isPhysical)
+            continue;
+        const envReqs = c.reqs.filter(ref => {
+            const req = requirements.find(r => r.ref === ref);
+            return req?.text && envKeywords.test(req.text);
+        });
+        if (envReqs.length > 0) {
+            findings.push({
+                severity: "high",
+                category: "Ontological Mismatch",
+                title: `"${c.name}" lacks Physical Object trait but has physical constraints`,
+                description: `UHT classifies "${c.name}" (${c.hexCode}) without the Physical Object trait, but ${envReqs.length} requirement(s) impose physical/environmental constraints on it.`,
+                affectedReqs: envReqs,
+                recommendation: `Add a requirement defining the physical embodiment of "${c.name}" (e.g., housing, LRU, equipment rack).`,
+            });
+        }
+    }
+    // 2. Abstract metrics without statistical parameters
+    const metricKeywords = /probability|rate|percentage|ratio|mtbf|availability/i;
+    const statKeywords = /confidence|sample size|number of|minimum of \d+ |statistical/i;
+    for (const c of concepts) {
+        if (c.traits.length > 3)
+            continue; // very abstract = few traits
+        const metricReqs = c.reqs.filter(ref => {
+            const req = requirements.find(r => r.ref === ref);
+            return req?.text && metricKeywords.test(req.text);
+        });
+        if (metricReqs.length === 0)
+            continue;
+        const hasStats = metricReqs.some(ref => {
+            const req = requirements.find(r => r.ref === ref);
+            return req?.text && statKeywords.test(req.text);
+        });
+        if (!hasStats) {
+            findings.push({
+                severity: "medium",
+                category: "Missing Statistical Context",
+                title: `"${c.name}" is an abstract metric without statistical parameters`,
+                description: `"${c.name}" (${c.hexCode}) has only ${c.traits.length} UHT traits (very abstract). Requirements set thresholds but don't specify confidence level, sample size, or test conditions.`,
+                affectedReqs: metricReqs,
+                recommendation: `Add statistical parameters (confidence level, sample size, conditions) to requirements referencing "${c.name}".`,
+            });
+        }
+    }
+    // 3. Verification requirements mixed with functional requirements
+    const verificationReqs = requirements.filter(r => r.text && /shall be verified|verification|shall be demonstrated|shall be tested/i.test(r.text));
+    const functionalReqs = requirements.filter(r => r.text && /shall\b/i.test(r.text) && !/shall be verified|verification/i.test(r.text));
+    if (verificationReqs.length > 0 && functionalReqs.length > 0) {
+        const ratio = verificationReqs.length / requirements.length;
+        if (ratio > 0.05 && ratio < 0.95) {
+            findings.push({
+                severity: "medium",
+                category: "Structural Issue",
+                title: "Verification requirements mixed with functional requirements",
+                description: `${verificationReqs.length} verification requirement(s) (${(ratio * 100).toFixed(0)}%) are co-mingled with ${functionalReqs.length} functional requirements. This makes traceability harder.`,
+                affectedReqs: verificationReqs.map(r => r.ref).filter(Boolean),
+                recommendation: "Move verification requirements to a separate document or tag them with a distinct pattern. Create trace links to parent functional requirements.",
+            });
+        }
+    }
+    // 4. Degraded mode gaps: requirements mentioning "manual", "reversion", "fallback" without performance criteria
+    const degradedReqs = requirements.filter(r => r.text && /manual\s+(?:reversion|mode|override|backup)|fallback|degraded/i.test(r.text));
+    for (const req of degradedReqs) {
+        const hasPerf = /\d+%|\d+\s*(?:second|ms|metre|meter|m\b)/i.test(req.text ?? "");
+        if (!hasPerf) {
+            findings.push({
+                severity: "medium",
+                category: "Coverage Gap",
+                title: `Degraded mode without performance criteria: ${req.ref}`,
+                description: `${req.ref} specifies a degraded/manual mode but provides no acceptance criteria for performance in that mode.`,
+                affectedReqs: [req.ref],
+                recommendation: "Add measurable performance criteria for degraded operation (e.g., acceptable accuracy, response time, available subsystems).",
+            });
+        }
+    }
+    // 5. Cross-comparison: high similarity between concepts in different categories
+    for (const batch of comparisons) {
+        for (const comp of batch.comparisons) {
+            const a = conceptMap.get(batch.entity);
+            const b = conceptMap.get(comp.candidate);
+            if (!a || !b)
+                continue;
+            // Different physical classification but high similarity = potential confusion
+            if (comp.jaccard_similarity > 0.6 && a.isPhysical !== b.isPhysical) {
+                findings.push({
+                    severity: "low",
+                    category: "Ontological Ambiguity",
+                    title: `"${a.name}" and "${b.name}" are similar (${(comp.jaccard_similarity * 100).toFixed(0)}%) but differ in physical classification`,
+                    description: `"${a.name}" is ${a.isPhysical ? "" : "not "}a Physical Object; "${b.name}" is ${b.isPhysical ? "" : "not "}. High Jaccard similarity (${comp.jaccard_similarity.toFixed(3)}) suggests they should be treated consistently.`,
+                    affectedReqs: [...a.reqs, ...b.reqs],
+                    recommendation: `Review whether both concepts should have consistent physical classification. Consider adding clarifying requirements.`,
+                });
+            }
+        }
+    }
+    // 6. Requirements without "shall" (weak language)
+    const weakReqs = requirements.filter(r => r.text && !/\bshall\b/i.test(r.text) && !/shall be verified/i.test(r.text));
+    if (weakReqs.length > 0) {
+        findings.push({
+            severity: "low",
+            category: "Language Quality",
+            title: `${weakReqs.length} requirement(s) lack "shall" keyword`,
+            description: `Requirements without "shall" may be informational text rather than testable requirements.`,
+            affectedReqs: weakReqs.map(r => r.ref).filter(Boolean),
+            recommendation: 'Rephrase using "shall" for testable requirements, or move informational text to notes/rationale.',
+        });
+    }
+    return findings.sort((a, b) => {
+        const sev = { high: 0, medium: 1, low: 2 };
+        return sev[a.severity] - sev[b.severity];
+    });
+}
+// ── Report formatting ────────────────────────────────────────
+function formatReport(tenant, project, requirements, concepts, comparisons, findings) {
+    const lines = [];
+    const high = findings.filter(f => f.severity === "high").length;
+    const med = findings.filter(f => f.severity === "medium").length;
+    const low = findings.filter(f => f.severity === "low").length;
+    lines.push("  Semantic Lint Report");
+    lines.push("  ════════════════════");
+    lines.push(`  Project: ${project} (${tenant})`);
+    lines.push(`  Requirements: ${requirements.length} | Concepts classified: ${concepts.length}`);
+    lines.push(`  Findings: ${findings.length} (${high} high, ${med} medium, ${low} low)`);
+    lines.push("");
+    // Concept classifications table
+    lines.push("  ┄┄ Concept Classifications ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄");
+    lines.push("");
+    const nameW = Math.max(...concepts.map(c => c.name.length), 10);
+    for (const c of concepts) {
+        const phys = c.isPhysical ? "Physical" : "Abstract";
+        const pad = " ".repeat(Math.max(0, nameW - c.name.length));
+        lines.push(`    ${c.name}${pad}  ${c.hexCode}  ${phys.padEnd(8)}  ${c.traits.slice(0, 4).join(", ")}${c.traits.length > 4 ? "..." : ""}`);
+    }
+    lines.push("");
+    // Cross-comparison highlights
+    if (comparisons.length > 0) {
+        lines.push("  ┄┄ Key Similarities ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄");
+        lines.push("");
+        for (const batch of comparisons) {
+            for (const comp of batch.comparisons) {
+                if (comp.jaccard_similarity >= 0.4) {
+                    const pct = (comp.jaccard_similarity * 100).toFixed(0);
+                    lines.push(`    ${batch.entity} ↔ ${comp.candidate}: ${pct}% Jaccard`);
+                }
+            }
+        }
+        lines.push("");
+    }
+    // Findings
+    lines.push("  ┄┄ Findings ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄");
+    lines.push("");
+    for (let i = 0; i < findings.length; i++) {
+        const f = findings[i];
+        const sevIcon = f.severity === "high" ? "!!!" : f.severity === "medium" ? " ! " : " . ";
+        lines.push(`  ${i + 1}. [${sevIcon}] ${f.title}`);
+        lines.push(`     Category: ${f.category}`);
+        lines.push(`     ${f.description}`);
+        lines.push(`     Affects: ${f.affectedReqs.join(", ")}`);
+        lines.push(`     Fix: ${f.recommendation}`);
+        lines.push("");
+    }
+    if (findings.length === 0) {
+        lines.push("  No findings — requirements look clean.");
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function formatMarkdown(tenant, project, requirements, concepts, comparisons, findings) {
+    const lines = [];
+    const high = findings.filter(f => f.severity === "high").length;
+    const med = findings.filter(f => f.severity === "medium").length;
+    const low = findings.filter(f => f.severity === "low").length;
+    lines.push("## Semantic Lint Report");
+    lines.push(`**Project:** ${project} (\`${tenant}\`)  `);
+    lines.push(`**Requirements:** ${requirements.length} | **Concepts classified:** ${concepts.length}  `);
+    lines.push(`**Findings:** ${findings.length} (${high} high, ${med} medium, ${low} low)`);
+    lines.push("");
+    // Concept table
+    lines.push("### Concept Classifications");
+    lines.push("| Concept | UHT Code | Physical? | Key Traits |");
+    lines.push("|---|---|---|---|");
+    for (const c of concepts) {
+        lines.push(`| ${c.name} | \`${c.hexCode}\` | ${c.isPhysical ? "Yes" : "No"} | ${c.traits.slice(0, 4).join(", ")} |`);
+    }
+    lines.push("");
+    // Similarities
+    if (comparisons.length > 0) {
+        lines.push("### Key Similarities");
+        lines.push("| Pair | Jaccard |");
+        lines.push("|---|---|");
+        for (const batch of comparisons) {
+            for (const comp of batch.comparisons) {
+                if (comp.jaccard_similarity >= 0.4) {
+                    lines.push(`| ${batch.entity} / ${comp.candidate} | **${(comp.jaccard_similarity * 100).toFixed(0)}%** |`);
+                }
+            }
+        }
+        lines.push("");
+    }
+    // Findings
+    lines.push("### Findings");
+    lines.push("| # | Severity | Title | Affected |");
+    lines.push("|---|---|---|---|");
+    for (let i = 0; i < findings.length; i++) {
+        const f = findings[i];
+        lines.push(`| ${i + 1} | **${f.severity}** | ${f.title} | ${f.affectedReqs.join(", ")} |`);
+    }
+    lines.push("");
+    for (const f of findings) {
+        lines.push(`#### ${f.title}`);
+        lines.push(`- **Severity:** ${f.severity} | **Category:** ${f.category}`);
+        lines.push(`- ${f.description}`);
+        lines.push(`- **Affects:** ${f.affectedReqs.join(", ")}`);
+        lines.push(`- **Recommendation:** ${f.recommendation}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+// ── Command registration ─────────────────────────────────────
+export function registerLintCommands(program, client) {
+    program
+        .command("lint")
+        .description("Semantic requirements lint — classifies domain concepts via UHT and flags ontological issues")
+        .argument("<tenant>", "Tenant slug")
+        .argument("<project>", "Project slug")
+        .option("--concepts <n>", "Max concepts to classify", "15")
+        .option("--format <fmt>", "Output format: text, markdown, json", "text")
+        .option("-o, --output <file>", "Write report to file")
+        .action(async (tenant, project, opts) => {
+        const uht = new UhtClient();
+        if (!uht.isConfigured) {
+            console.error("UHT not configured. Set UHT_TOKEN environment variable.");
+            console.error("Get a token at https://universalhex.org");
+            process.exit(1);
+        }
+        const maxConcepts = parseInt(opts.concepts, 10) || 15;
+        // Step 1: Fetch all requirements
+        console.error("Fetching requirements...");
+        const requirements = await fetchAllRequirements(client, tenant, project);
+        if (requirements.length === 0) {
+            console.error("No requirements found.");
+            process.exit(1);
+        }
+        console.error(`  ${requirements.length} requirements loaded.`);
+        // Step 2: Extract domain concepts
+        console.error("Extracting domain concepts...");
+        const conceptRefs = extractConcepts(requirements);
+        const top = topConcepts(conceptRefs, maxConcepts);
+        console.error(`  ${conceptRefs.size} unique concepts found, classifying top ${top.length}.`);
+        // Step 3: Classify each concept via UHT
+        console.error("Classifying concepts via UHT...");
+        const concepts = [];
+        for (const [name, refs] of top) {
+            try {
+                const result = await uht.classify(name);
+                const traitNames = result.traits.map(t => t.name).filter(Boolean);
+                concepts.push({
+                    name,
+                    hexCode: result.hex_code,
+                    isPhysical: traitNames.includes("Physical Object"),
+                    traits: traitNames,
+                    reqs: refs,
+                });
+                console.error(`  ✓ ${name} → ${result.hex_code} (${traitNames.length} traits)`);
+            }
+            catch (err) {
+                console.error(`  ✗ ${name}: ${err.message}`);
+            }
+        }
+        // Step 4: Cross-compare concepts in batches
+        console.error("Cross-comparing concepts...");
+        const comparisons = [];
+        if (concepts.length >= 2) {
+            // Compare top concept against others, then second against rest
+            const names = concepts.map(c => c.name);
+            const batchSize = Math.min(names.length - 1, 15);
+            try {
+                const result = await uht.batchCompare(names[0], names.slice(1, batchSize + 1));
+                comparisons.push(result);
+                console.error(`  ✓ ${names[0]} vs ${batchSize} others`);
+            }
+            catch (err) {
+                console.error(`  ✗ batch compare: ${err.message}`);
+            }
+            if (names.length > 3) {
+                try {
+                    const mid = Math.floor(names.length / 2);
+                    const candidates = [...names.slice(0, mid), ...names.slice(mid + 1)].slice(0, 10);
+                    const result = await uht.batchCompare(names[mid], candidates);
+                    comparisons.push(result);
+                    console.error(`  ✓ ${names[mid]} vs ${candidates.length} others`);
+                }
+                catch (err) {
+                    console.error(`  ✗ batch compare: ${err.message}`);
+                }
+            }
+        }
+        // Step 5: Analyze findings
+        console.error("Analyzing...");
+        const findings = analyzeFindings(concepts, comparisons, requirements);
+        // Step 6: Output report
+        let report;
+        if (opts.format === "json" || isJsonMode()) {
+            const data = { tenant, project, requirements: requirements.length, concepts, comparisons, findings };
+            report = JSON.stringify(data, null, 2);
+        }
+        else if (opts.format === "markdown") {
+            report = formatMarkdown(tenant, project, requirements, concepts, comparisons, findings);
+        }
+        else {
+            report = formatReport(tenant, project, requirements, concepts, comparisons, findings);
+        }
+        if (opts.output) {
+            writeFileSync(opts.output, report + "\n", "utf-8");
+            console.error(`Report written to ${opts.output}`);
+        }
+        else {
+            console.log(report);
+        }
+    });
+}

package/dist/index.js

@@ -19,6 +19,7 @@ import { registerReportCommands } from "./commands/reports.js";
 import { registerImportExportCommands } from "./commands/import-export.js";
 import { registerActivityCommands } from "./commands/activity.js";
 import { registerImplementationCommands } from "./commands/implementation.js";
+import { registerLintCommands } from "./commands/lint.js";
 const program = new Command();
 // Lazy-init: only create client when a command actually runs
 let client = null;
@@ -67,6 +68,7 @@ registerReportCommands(program, clientProxy);
 registerImportExportCommands(program, clientProxy);
 registerActivityCommands(program, clientProxy);
 registerImplementationCommands(program, clientProxy);
+registerLintCommands(program, clientProxy);
 // Handle async errors from Commander action handlers
 process.on("uncaughtException", (err) => {
     console.error(`Error: ${err.message}`);

package/dist/uht-client.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Minimal UHT (Universal Hex Taxonomy) API client.
+ *
+ * Talks to the UHT Substrate factory API for entity classification and comparison.
+ * Token resolution: UHT_TOKEN env → UHT_API_KEY env → ~/.config/uht-substrate/config.json
+ */
+export interface UhtClassification {
+    entity: string;
+    hex_code: string;
+    traits: Array<{
+        name: string;
+        justification: string;
+    }>;
+}
+export interface UhtComparison {
+    candidate: string;
+    hex_code: string;
+    jaccard_similarity: number;
+    hamming_distance: number;
+    shared_traits: Array<{
+        name: string;
+    }>;
+    traits_entity_only: Array<{
+        name: string;
+    }>;
+    traits_candidate_only: Array<{
+        name: string;
+    }>;
+}
+export interface UhtBatchResult {
+    entity: string;
+    hex_code: string;
+    comparisons: UhtComparison[];
+    best_match: string;
+    best_jaccard: number;
+}
+export declare class UhtClient {
+    private baseUrl;
+    private token;
+    constructor();
+    get isConfigured(): boolean;
+    private request;
+    classify(entity: string): Promise<UhtClassification>;
+    batchCompare(entity: string, candidates: string[]): Promise<UhtBatchResult>;
+}

package/dist/uht-client.js

@@ -0,0 +1,55 @@
+/**
+ * Minimal UHT (Universal Hex Taxonomy) API client.
+ *
+ * Talks to the UHT Substrate factory API for entity classification and comparison.
+ * Token resolution: UHT_TOKEN env → UHT_API_KEY env → ~/.config/uht-substrate/config.json
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const DEFAULT_UHT_URL = "https://substrate.universalhex.org/api";
+function loadUhtConfigToken() {
+    try {
+        const configPath = join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "uht-substrate", "config.json");
+        const config = JSON.parse(readFileSync(configPath, "utf-8"));
+        return config.token ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+export class UhtClient {
+    baseUrl;
+    token;
+    constructor() {
+        this.baseUrl = (process.env.UHT_API_URL ?? DEFAULT_UHT_URL).replace(/\/+$/, "");
+        this.token = process.env.UHT_TOKEN || process.env.UHT_API_KEY || loadUhtConfigToken();
+    }
+    get isConfigured() {
+        return this.token.length > 0;
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {};
+        if (body)
+            headers["Content-Type"] = "application/json";
+        if (this.token)
+            headers["Authorization"] = `Bearer ${this.token}`;
+        const res = await globalThis.fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`UHT API error (${res.status}): ${text}`);
+        }
+        return (await res.json());
+    }
+    async classify(entity) {
+        return this.request("POST", "/classify", { entity, context: "", use_semantic_priors: false });
+    }
+    async batchCompare(entity, candidates) {
+        return this.request("POST", "/batch-compare", { entity, candidates });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "airgen-cli",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "AIRGen CLI — requirements engineering from the command line",
   "type": "module",
   "main": "dist/index.js",