airgen-cli 0.21.1 → 0.23.0

package/dist/commands/baselines.js

@@ -1,4 +1,10 @@
+import { writeFileSync } from "node:fs";
 import { output, printTable, isJsonMode } from "../output.js";
+function refFromRequirementId(id) {
+    // Composite IDs are tenant:project:REF
+    const parts = id.split(":");
+    return parts[parts.length - 1];
+}
 export function registerBaselineCommands(program, client) {
     const cmd = program.command("baselines").alias("bl").description("Baseline snapshots");
     cmd
@@ -52,4 +58,135 @@ export function registerBaselineCommands(program, client) {
         const data = await client.get(`/baselines/${tenant}/${project}/compare`, { from: opts.from, to: opts.to });
         output(data);
     });
+    cmd
+        .command("show")
+        .description("Show baseline contents (requirements with full text, rationale, tags)")
+        .argument("<tenant>", "Tenant slug")
+        .argument("<project>", "Project slug")
+        .argument("<baseline-ref>", "Baseline ref")
+        .option("--ref <pattern>", "Filter to requirements whose ref matches this substring")
+        .action(async (tenant, project, baselineRef, opts) => {
+        const snap = await client.get(`/baselines/${tenant}/${project}/${encodeURIComponent(baselineRef)}`);
+        let reqs = snap.requirementVersions ?? [];
+        if (opts.ref) {
+            const needle = opts.ref;
+            reqs = reqs.filter(r => refFromRequirementId(r.requirementId).includes(needle));
+        }
+        if (isJsonMode()) {
+            output({ baseline: snap.baseline, requirementVersions: reqs });
+            return;
+        }
+        console.log(`Baseline: ${snap.baseline.ref ?? snap.baseline.id}`);
+        console.log(`Label:    ${snap.baseline.label ?? ""}`);
+        console.log(`Created:  ${snap.baseline.createdAt ?? ""}`);
+        console.log(`Requirements: ${reqs.length}\n`);
+        for (const r of reqs) {
+            const ref = refFromRequirementId(r.requirementId);
+            console.log(`── ${ref} (v${r.versionNumber}) ──`);
+            console.log(`text:       ${r.text}`);
+            if (r.pattern)
+                console.log(`pattern:    ${r.pattern}`);
+            if (r.verification)
+                console.log(`verify:     ${r.verification}`);
+            if (r.rationale)
+                console.log(`rationale:  ${r.rationale}`);
+            if (r.complianceStatus)
+                console.log(`compliance: ${r.complianceStatus}`);
+            if (r.tags?.length)
+                console.log(`tags:       ${r.tags.join(", ")}`);
+            console.log("");
+        }
+    });
+    cmd
+        .command("export")
+        .description("Export full baseline snapshot as JSON")
+        .argument("<tenant>", "Tenant slug")
+        .argument("<project>", "Project slug")
+        .argument("<baseline-ref>", "Baseline ref")
+        .option("-o, --output <file>", "Write JSON to file instead of stdout")
+        .action(async (tenant, project, baselineRef, opts) => {
+        const snap = await client.get(`/baselines/${tenant}/${project}/${encodeURIComponent(baselineRef)}`);
+        const json = JSON.stringify(snap, null, 2);
+        if (opts.output) {
+            writeFileSync(opts.output, json);
+            console.error(`Wrote ${opts.output} (${(json.length / 1024).toFixed(1)} KB, ${snap.requirementVersions?.length ?? 0} requirements)`);
+        }
+        else {
+            process.stdout.write(json + "\n");
+        }
+    });
+    cmd
+        .command("restore")
+        .description("Restore requirements from a baseline (PATCHes live requirements with snapshot values)")
+        .argument("<tenant>", "Tenant slug")
+        .argument("<project>", "Project slug")
+        .argument("<baseline-ref>", "Baseline ref")
+        .option("--ref <pattern>", "Restore only requirements whose ref includes this substring")
+        .option("--fields <list>", "Comma-separated fields to restore (default: rationale,text,pattern,verification,complianceStatus,complianceRationale,tags)", "rationale,text,pattern,verification,complianceStatus,complianceRationale,tags")
+        .option("--dry-run", "Print what would be restored without making changes")
+        .option("--yes", "Skip confirmation prompt")
+        .action(async (tenant, project, baselineRef, opts) => {
+        const snap = await client.get(`/baselines/${tenant}/${project}/${encodeURIComponent(baselineRef)}`);
+        let reqs = snap.requirementVersions ?? [];
+        if (opts.ref) {
+            const needle = opts.ref;
+            reqs = reqs.filter(r => refFromRequirementId(r.requirementId).includes(needle));
+        }
+        const fields = opts.fields.split(",").map(f => f.trim()).filter(Boolean);
+        const allowed = new Set(["text", "pattern", "verification", "rationale", "complianceStatus", "complianceRationale", "tags"]);
+        const invalid = fields.filter(f => !allowed.has(f));
+        if (invalid.length > 0) {
+            console.error(`Invalid fields: ${invalid.join(", ")}`);
+            console.error(`Allowed: ${[...allowed].join(", ")}`);
+            process.exit(1);
+        }
+        console.error(`Baseline:    ${snap.baseline.ref ?? snap.baseline.id}`);
+        console.error(`Label:       ${snap.baseline.label ?? ""}`);
+        console.error(`Created:     ${snap.baseline.createdAt ?? ""}`);
+        console.error(`Requirements to restore: ${reqs.length}`);
+        console.error(`Fields:      ${fields.join(", ")}`);
+        console.error("");
+        if (opts.dryRun) {
+            for (const r of reqs) {
+                const ref = refFromRequirementId(r.requirementId);
+                const summary = fields.map(f => {
+                    const v = r[f];
+                    if (v == null)
+                        return `${f}=(none)`;
+                    const s = typeof v === "string" ? v : JSON.stringify(v);
+                    return `${f}=${s.length > 40 ? s.slice(0, 40) + "…" : s}`;
+                }).join(" | ");
+                console.log(`[dry-run] ${ref}: ${summary}`);
+            }
+            console.error(`\n[dry-run] Would restore ${reqs.length} requirements. Re-run without --dry-run to apply.`);
+            return;
+        }
+        if (!opts.yes) {
+            console.error(`This will OVERWRITE current values for ${reqs.length} requirements.`);
+            console.error("Pass --yes to proceed, or --dry-run to preview.");
+            process.exit(1);
+        }
+        let ok = 0;
+        let failed = 0;
+        for (const r of reqs) {
+            const ref = refFromRequirementId(r.requirementId);
+            const body = {};
+            for (const f of fields) {
+                const v = r[f];
+                if (v !== undefined)
+                    body[f] = v;
+            }
+            try {
+                await client.patch(`/requirements/${tenant}/${project}/${encodeURIComponent(ref)}`, body);
+                ok++;
+                if (ok % 25 === 0)
+                    console.error(`  restored ${ok}/${reqs.length}…`);
+            }
+            catch (err) {
+                failed++;
+                console.error(`  FAILED ${ref}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        console.error(`\nDone. Restored ${ok}, failed ${failed}.`);
+    });
 }

package/dist/commands/diff.js

@@ -159,10 +159,21 @@ export function registerDiffCommand(program, client) {
         .argument("<tenant>", "Tenant slug")
         .argument("<project>", "Project slug")
         .requiredOption("--from <ref>", "Source baseline ref (earlier)")
-        .requiredOption("--to <ref>", "Target baseline ref (later)")
+        .option("--to <ref>", "Target baseline ref (later). If omitted, lists available baselines.")
         .option("--format <fmt>", "Output format: text, markdown", "text")
         .option("-o, --output <file>", "Write report to file")
         .action(async (tenant, project, opts) => {
+        if (!opts.to) {
+            // Show available baselines when --to is omitted
+            const blData = await client.get(`/baselines/${tenant}/${project}`);
+            const baselines = blData.items ?? [];
+            console.error(`Available baselines (use --to <ref>):\n`);
+            for (const b of baselines) {
+                const marker = b.ref === opts.from ? " ← --from" : "";
+                console.error(`  ${b.ref}  ${b.label ?? ""}  ${b.createdAt ?? ""}${marker}`);
+            }
+            process.exit(1);
+        }
         const data = await client.get(`/baselines/${tenant}/${project}/compare`, { from: opts.from, to: opts.to });
         let result;
         if (isJsonMode()) {

package/dist/commands/import-export.js

@@ -42,12 +42,18 @@ export function registerImportExportCommands(program, client) {
     const exp = program.command("export").description("Export data");
     exp
         .command("requirements")
-        .description("Export requirements as markdown or JSON")
+        .description("Export requirements as markdown or JSON (current state or from a baseline)")
         .argument("<tenant>", "Tenant slug")
         .argument("<project>", "Project slug")
         .option("--document <slug>", "Export specific document as markdown")
         .option("--format <fmt>", "Format: json, markdown", "json")
+        .option("--baseline <ref>", "Export requirement state captured in a baseline (instead of current)")
         .action(async (tenant, project, opts) => {
+        if (opts.baseline) {
+            const snap = await client.get(`/baselines/${tenant}/${project}/${encodeURIComponent(opts.baseline)}`);
+            output({ baseline: snap.baseline, requirements: snap.requirementVersions ?? [] });
+            return;
+        }
         if (opts.document && opts.format === "markdown") {
             const data = await client.get(`/markdown/${tenant}/${project}/${opts.document}/content`);
             if (isJsonMode()) {

package/dist/commands/lint.js

@@ -1,6 +1,12 @@
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { UhtClient, decodeHexTraits } from "../uht-client.js";
 import { isJsonMode } from "../output.js";
+function sourceRef(l) {
+    return l.sourceRequirement?.ref ?? l.sourceRequirementId ?? "";
+}
+function targetRef(l) {
+    return l.targetRequirement?.ref ?? l.targetRequirementId ?? "";
+}
 const TRAIT_CHECKS = [
     // Physical Layer (1-8)
     { trait: "Physical Object", bit: 1, severity: "high", inverted: true,
@@ -225,12 +231,16 @@ async function parallelMap(items, fn, concurrency) {
 function extractConcepts(requirements) {
     const conceptRefs = new Map();
     const skip = new Set(["system", "the system", "it", "this", "all", "each", "any", "user", "operator"]);
+    // Mode names are system-level operating states, not decomposable concepts
+    const modePattern = /^(?:normal|degraded|emergency|standby|idle|startup|shutdown|maintenance|manual|automatic|autonomous|safe|fault|failsafe|backup|override|test|diagnostic|calibration)\s+(?:mode|operation|state|condition|running|navigation)/i;
     function addConcept(concept, ref) {
         const normalized = concept.toLowerCase().trim();
         if (normalized.length < 3 || normalized.length > 60)
             return;
         if (skip.has(normalized))
             return;
+        if (modePattern.test(normalized))
+            return;
         const refs = conceptRefs.get(normalized) ?? [];
         if (!refs.includes(ref))
             refs.push(ref);
@@ -450,7 +460,7 @@ function analyzeFindings(concepts, comparisons, requirements, traceLinks, reqTie
     if (traceLinks.length > 0) {
         const outgoing = new Map();
         for (const link of traceLinks) {
-            const src = link.sourceRef ?? link.sourceRequirementId ?? "";
+            const src = sourceRef(link);
             if (!outgoing.has(src))
                 outgoing.set(src, []);
             outgoing.get(src).push(link);
@@ -571,6 +581,80 @@ function analyzeFindings(concepts, comparisons, requirements, traceLinks, reqTie
             });
         }
     }
+    // ── 11. Quantitative value consistency across subsystems ────
+    // Extract numeric values + units, group by value across document tiers, flag duplicates without derivation links
+    const valuePattern = /(\d+(?:\.\d+)?)\s*(ms|s|sec|seconds?|minutes?|min|hours?|hr|Hz|kHz|MHz|GHz|V|kV|mV|A|mA|W|kW|MW|m|km|cm|mm|m\/s|km\/h|mph|dB|dBm|°C|°F|K|Pa|kPa|MPa|bar|psi|kg|g|lb|N|kN|%)/gi;
+    const valueOccurrences = new Map();
+    for (const req of requirements) {
+        if (!req.text || !req.ref)
+            continue;
+        const tier = reqTierMap.get(req.ref) ?? "?";
+        let vm;
+        while ((vm = valuePattern.exec(req.text)) !== null) {
+            const key = `${vm[1]}${vm[2].toLowerCase()}`;
+            const list = valueOccurrences.get(key) ?? [];
+            list.push({ ref: req.ref, tier });
+            valueOccurrences.set(key, list);
+        }
+    }
+    // Flag values appearing across different subsystems without trace links
+    for (const [value, occurrences] of valueOccurrences) {
+        const tiers = new Set(occurrences.map(o => o.tier));
+        if (tiers.size < 2)
+            continue; // Only flag cross-tier
+        // Check if any pair has a derives trace link
+        const refs = occurrences.map(o => o.ref);
+        const hasDerivation = traceLinks.some(l => l.linkType === "derives" &&
+            refs.includes(sourceRef(l)) && refs.includes(targetRef(l)));
+        if (!hasDerivation && occurrences.length >= 2) {
+            findings.push({
+                severity: "medium",
+                category: "Value Consistency",
+                title: `Threshold "${value}" appears across ${tiers.size} document tiers without derivation`,
+                description: `"${value}" appears in ${occurrences.length} requirements across tiers ${[...tiers].join(", ")} with no derives trace link connecting them.`,
+                affectedReqs: refs.slice(0, 10),
+                recommendation: `Add derivation rationale or trace links explaining why "${value}" is used across subsystems.`,
+            });
+        }
+    }
+    // ── 12. Round-number threshold detector ───────────────────
+    const roundPattern = /\b(\d+)\s*(ms|s|Hz|V|W|kW|MW|m|km|km\/h|mph|dB|%)\b/gi;
+    const roundCounts = new Map();
+    for (const req of requirements) {
+        if (!req.text || !req.ref)
+            continue;
+        let rm;
+        while ((rm = roundPattern.exec(req.text)) !== null) {
+            const num = parseInt(rm[1], 10);
+            // Only flag round numbers (multiples of 10, 50, 100, 500, 1000)
+            if (num >= 10 && (num % 10 === 0 || num % 50 === 0 || num % 100 === 0)) {
+                const key = `${num}${rm[2].toLowerCase()}`;
+                const refs = roundCounts.get(key) ?? [];
+                if (!refs.includes(req.ref))
+                    refs.push(req.ref);
+                roundCounts.set(key, refs);
+            }
+        }
+    }
+    for (const [value, refs] of roundCounts) {
+        if (refs.length <= 3)
+            continue; // Only flag if >3 occurrences
+        // Check if any has derivation rationale
+        const hasRationale = refs.some(ref => {
+            const req = requirements.find(r => r.ref === ref);
+            return req?.rationale && /derived from|allocated from|calculated|analysis|budget/i.test(req.rationale);
+        });
+        if (!hasRationale) {
+            findings.push({
+                severity: "low",
+                category: "Design Assumption",
+                title: `Round threshold "${value}" appears ${refs.length} times without derivation rationale`,
+                description: `"${value}" is used in ${refs.length} requirements — likely an undocumented design assumption.`,
+                affectedReqs: refs.slice(0, 10),
+                recommendation: `Add rationale explaining why "${value}" was chosen, or trace to the source requirement that allocates this value.`,
+            });
+        }
+    }
     return findings.sort((a, b) => {
         const sev = { high: 0, medium: 1, low: 2 };
         return sev[a.severity] - sev[b.severity];

package/dist/commands/requirements.js

@@ -221,12 +221,16 @@ export function registerRequirementCommands(program, client) {
         else if (opts.tags) {
             body.tags = opts.tags.split(",").map(t => t.trim());
         }
-        await client.patch(`/requirements/${tenant}/${project}/${resolvedId}`, body);
+        const result = await client.patch(`/requirements/${tenant}/${project}/${resolvedId}`, body);
+        const warnings = result?.warnings ?? [];
         if (isJsonMode()) {
-            output({ ok: true });
+            output({ ok: true, warnings });
         }
         else {
             console.log("Requirement updated.");
+            for (const w of warnings) {
+                console.error(`  warning: ${w}`);
+            }
         }
     });
     cmd

package/package.json

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