airgen-cli 0.16.0 → 0.17.1

package/dist/commands/lint.js

@@ -1,5 +1,5 @@
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
-import { UhtClient } from "../uht-client.js";
+import { UhtClient, decodeHexTraits } from "../uht-client.js";
 import { isJsonMode } from "../output.js";
 const TRAIT_CHECKS = [
     // Physical Layer (1-8)
@@ -693,6 +693,7 @@ export function registerLintCommands(program, client) {
         .option("--threshold <n>", "Jaccard similarity threshold (0.0-1.0)", "0.6")
         .option("--spray-threshold <n>", "Outgoing trace link count for spray pattern detection", "8")
         .option("--min-severity <level>", "Only show findings at this severity or above: low, medium, high", "low")
+        .option("--substrate-namespace <ns>", "Use existing Substrate entity classifications instead of re-classifying (e.g. SE, SE:naval)")
         .action(async (tenant, project, opts) => {
         const uht = new UhtClient();
         if (!uht.isConfigured) {
@@ -721,26 +722,69 @@ export function registerLintCommands(program, client) {
         const conceptRefs = extractConcepts(requirements);
         const top = topConcepts(conceptRefs, maxConcepts);
         console.error(`  ${conceptRefs.size} unique concepts found, classifying top ${top.length}.`);
-        // Step 3: Classify concepts via UHT (parallelized)
-        console.error("Classifying concepts via UHT...");
-        const classifyResults = await parallelMap(top, async ([name]) => uht.classify(name), 5);
+        // Step 3: Classify concepts — use Substrate namespace if provided, else fresh classify
+        const ns = opts.substrateNamespace;
+        console.error(ns
+            ? `Looking up concepts in Substrate namespace "${ns}"...`
+            : "Classifying concepts via UHT...");
         const concepts = [];
-        for (let i = 0; i < classifyResults.length; i++) {
-            const entry = classifyResults[i];
-            const [name, refs] = top[i];
-            if (entry.result) {
-                const traitNames = entry.result.traits.map(t => t.name).filter(Boolean);
-                concepts.push({
-                    name,
-                    hexCode: entry.result.hex_code,
-                    traits: traitNames,
-                    traitSet: new Set(traitNames),
-                    reqs: refs,
-                });
-                console.error(`  ✓ ${name} → ${entry.result.hex_code} (${traitNames.length} traits)`);
+        if (ns) {
+            // Namespace mode: look up pre-classified entities
+            const lookupResults = await parallelMap(top, async ([name]) => uht.lookupEntity(name, ns), 5);
+            for (let i = 0; i < lookupResults.length; i++) {
+                const [name, refs] = top[i];
+                const entity = lookupResults[i].result;
+                if (entity) {
+                    const traitNames = decodeHexTraits(entity.hex_code);
+                    concepts.push({
+                        name: entity.name, // Use canonical name from Substrate
+                        hexCode: entity.hex_code,
+                        traits: traitNames,
+                        traitSet: new Set(traitNames),
+                        reqs: refs,
+                    });
+                    console.error(`  ✓ ${name} → ${entity.name} (${entity.hex_code}, ${traitNames.length} traits)`);
+                }
+                else {
+                    // Fall back to fresh classification
+                    try {
+                        const result = await uht.classify(name);
+                        const traitNames = result.traits.map(t => t.name).filter(Boolean);
+                        concepts.push({
+                            name,
+                            hexCode: result.hex_code,
+                            traits: traitNames,
+                            traitSet: new Set(traitNames),
+                            reqs: refs,
+                        });
+                        console.error(`  ~ ${name} → ${result.hex_code} (${traitNames.length} traits, not in namespace — classified fresh)`);
+                    }
+                    catch (err) {
+                        console.error(`  ✗ ${name}: ${err.message}`);
+                    }
+                }
             }
-            else if (entry.error) {
-                console.error(`  ✗ ${name}: ${entry.error.message}`);
+        }
+        else {
+            // Fresh classification mode (original behavior)
+            const classifyResults = await parallelMap(top, async ([name]) => uht.classify(name), 5);
+            for (let i = 0; i < classifyResults.length; i++) {
+                const entry = classifyResults[i];
+                const [name, refs] = top[i];
+                if (entry.result) {
+                    const traitNames = entry.result.traits.map(t => t.name).filter(Boolean);
+                    concepts.push({
+                        name,
+                        hexCode: entry.result.hex_code,
+                        traits: traitNames,
+                        traitSet: new Set(traitNames),
+                        reqs: refs,
+                    });
+                    console.error(`  ✓ ${name} → ${entry.result.hex_code} (${traitNames.length} traits)`);
+                }
+                else if (entry.error) {
+                    console.error(`  ✗ ${name}: ${entry.error.message}`);
+                }
             }
         }
         // Step 4: Cross-compare concepts in batches

package/dist/uht-client.d.ts

@@ -4,6 +4,8 @@
  * 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
  */
+/** Decode an 8-char hex code into trait names by reading the 32-bit field. */
+export declare function decodeHexTraits(hexCode: string): string[];
 export interface UhtClassification {
     entity: string;
     hex_code: string;
@@ -12,6 +14,13 @@ export interface UhtClassification {
         justification: string;
     }>;
 }
+export interface UhtEntityRecord {
+    uuid: string;
+    name: string;
+    hex_code: string;
+    description: string | null;
+    source: string;
+}
 export interface UhtComparison {
     candidate: string;
     hex_code: string;
@@ -42,4 +51,7 @@ export declare class UhtClient {
     private request;
     classify(entity: string): Promise<UhtClassification>;
     batchCompare(entity: string, candidates: string[]): Promise<UhtBatchResult>;
+    /** Look up an entity by name in a Substrate namespace. Returns null if not found.
+     *  Only returns exact name matches (case-insensitive) — no fuzzy fallback. */
+    lookupEntity(name: string, namespace: string): Promise<UhtEntityRecord | null>;
 }

package/dist/uht-client.js

@@ -8,6 +8,30 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 const DEFAULT_UHT_URL = "https://substrate.universalhex.org/api";
+// All 32 UHT v2 canonical trait names, indexed by bit position (1-based)
+const TRAIT_NAMES = {
+    1: "Physical Object", 2: "Synthetic", 3: "Biological/Biomimetic", 4: "Powered",
+    5: "Structural", 6: "Observable", 7: "Physical Medium", 8: "Active",
+    9: "Intentionally Designed", 10: "Outputs Effect", 11: "Processes Signals/Logic", 12: "State-Transforming",
+    13: "Human-Interactive", 14: "System-integrated", 15: "Functionally Autonomous", 16: "System-Essential",
+    17: "Symbolic", 18: "Signalling", 19: "Rule-governed", 20: "Compositional",
+    21: "Normative", 22: "Meta", 23: "Temporal", 24: "Digital/Virtual",
+    25: "Social Construct", 26: "Institutionally Defined", 27: "Identity-Linked", 28: "Regulated",
+    29: "Economically Significant", 30: "Politicised", 31: "Ritualised", 32: "Ethically Significant",
+};
+/** Decode an 8-char hex code into trait names by reading the 32-bit field. */
+export function decodeHexTraits(hexCode) {
+    const binary = parseInt(hexCode, 16).toString(2).padStart(32, "0");
+    const traits = [];
+    for (let i = 0; i < 32; i++) {
+        if (binary[i] === "1") {
+            const name = TRAIT_NAMES[i + 1];
+            if (name)
+                traits.push(name);
+        }
+    }
+    return traits;
+}
 function loadUhtConfigToken() {
     try {
         const configPath = join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "uht-substrate", "config.json");
@@ -52,4 +76,11 @@ export class UhtClient {
     async batchCompare(entity, candidates) {
         return this.request("POST", "/batch-compare", { entity, candidates });
     }
+    /** Look up an entity by name in a Substrate namespace. Returns null if not found.
+     *  Only returns exact name matches (case-insensitive) — no fuzzy fallback. */
+    async lookupEntity(name, namespace) {
+        const data = await this.request("GET", `/entities?namespace=${encodeURIComponent(namespace)}&name=${encodeURIComponent(name)}&limit=10`);
+        // Exact match only — the API does substring filtering, so we must check
+        return data.entities.find(e => e.name.toLowerCase() === name.toLowerCase()) ?? null;
+    }
 }

package/package.json

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