@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/artifacts/audit/cli.js

@@ -0,0 +1,183 @@
+/**
+ * `aiwg index doctor --rlm-audit` subcommand.
+ *
+ * Audits enriched index entries for content drift. Per-entry workflow:
+ *   1. Read stored SemanticFields.
+ *   2. Compute current artifact content hash.
+ *   3. If hashes match: ok (or stale-age if past freshness window).
+ *   4. If hashes differ: classify status as 'skip' (no recomputed input)
+ *      or 'drift' (overlap/symbol thresholds exceeded).
+ *
+ * To classify drift the audit needs a *recomputed* enrichment for each
+ * mismatching entry. Producing that requires an RLM dispatch, which lives
+ * in agent skills, not the CLI. So this command operates in two passes:
+ *
+ *   Pass 1 (default):  Hash check only. Reports ok / stale-age / would-need-recompute.
+ *   Pass 2 (--apply):  Operator supplies a directory of recomputed JSON
+ *                      files (one per entry) and the audit classifies drift.
+ *
+ * @implements #1208
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { computeContentHash, list as listEnrichments, resolveSemanticRoot, get as getEnrichment, } from '../enrichment/store.js';
+import { validateEnrichmentOutput } from '../enrichment/prompt.js';
+import { projectAiwgPath } from '../../config/project-artifacts.js';
+import { detectDrift } from './drift.js';
+import { DEFAULT_THRESHOLDS } from './types.js';
+export async function main(args) {
+    if (!args.includes('--rlm-audit')) {
+        printUsage();
+        if (args.length > 0)
+            process.exitCode = 1;
+        return;
+    }
+    const filter = flagValue(args, '--filter');
+    const strict = args.includes('--strict');
+    const json = args.includes('--json');
+    const recompDir = flagValue(args, '--recomputed-dir');
+    const thresholds = loadThresholds();
+    const root = resolveSemanticRoot();
+    // Build current-hash map for every enrichment that has a corresponding artifact
+    const allSummaries = listEnrichments(root, /* currentHashes */ {});
+    let summaries = allSummaries;
+    if (filter) {
+        const re = new RegExp(filter);
+        summaries = allSummaries.filter((s) => re.test(s.artifactId));
+    }
+    const rows = [];
+    for (const s of summaries) {
+        const stored = getEnrichment(root, s.artifactId);
+        let currentHash;
+        try {
+            currentHash = computeContentHash(readFileSync(s.artifactId));
+        }
+        catch {
+            rows.push({
+                artifactId: s.artifactId,
+                status: 'skip',
+                reason: 'artifact not readable from configured path',
+                storedHash: stored.enrichedHash,
+                currentHash: null,
+                ageDays: null,
+            });
+            continue;
+        }
+        let recomputed = null;
+        if (recompDir && stored.enrichedHash !== currentHash) {
+            const sanitized = s.artifactId.replace(/\//g, '__');
+            const candidate = join(recompDir, `${sanitized}.json`);
+            if (existsSync(candidate)) {
+                try {
+                    const raw = JSON.parse(readFileSync(candidate, 'utf-8'));
+                    const issues = validateEnrichmentOutput(raw);
+                    if (issues.length === 0) {
+                        recomputed = {
+                            summary: raw['summary'],
+                            declaredSymbols: raw['declared_symbols'],
+                            citations: raw['citations'],
+                            inferredTags: raw['inferred_tags'],
+                            openQuestions: raw['open_questions'],
+                            enrichedAt: new Date().toISOString(),
+                            enrichedBy: 'audit-recompute',
+                            enrichedHash: currentHash,
+                        };
+                    }
+                }
+                catch { /* leave recomputed null → status: skip */ }
+            }
+        }
+        rows.push(detectDrift({
+            artifactId: s.artifactId,
+            stored,
+            currentHash,
+            recomputed,
+            thresholds,
+        }));
+    }
+    const report = {
+        total: rows.length,
+        ok: rows.filter((r) => r.status === 'ok').length,
+        drift: rows.filter((r) => r.status === 'drift').length,
+        staleAge: rows.filter((r) => r.status === 'stale-age').length,
+        skipped: rows.filter((r) => r.status === 'skip').length,
+        thresholds,
+        rows,
+    };
+    if (json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        printHumanReport(report);
+    }
+    if (strict && (report.drift > 0 || report.staleAge > 0)) {
+        process.exitCode = 1;
+    }
+}
+function loadThresholds() {
+    // Try .aiwg/index/audit.config.yaml → fall back to defaults
+    const path = projectAiwgPath(process.cwd(), 'index', 'audit.config.yaml');
+    if (!existsSync(path))
+        return DEFAULT_THRESHOLDS;
+    try {
+        const yamlMod = require('js-yaml');
+        const raw = (yamlMod.load(readFileSync(path, 'utf-8')) ?? {});
+        const div = (raw['divergence'] ?? {});
+        return {
+            keywordOverlapMin: typeof div['keyword_overlap_min'] === 'number' ? div['keyword_overlap_min'] : DEFAULT_THRESHOLDS.keywordOverlapMin,
+            symbolChangeCritical: typeof div['symbol_change_critical'] === 'boolean' ? div['symbol_change_critical'] : DEFAULT_THRESHOLDS.symbolChangeCritical,
+            freshnessMaxDays: typeof div['freshness_max_days'] === 'number' ? div['freshness_max_days'] : DEFAULT_THRESHOLDS.freshnessMaxDays,
+        };
+    }
+    catch {
+        return DEFAULT_THRESHOLDS;
+    }
+}
+function printHumanReport(r) {
+    console.log(`Audited ${r.total} enriched entries`);
+    console.log(`  ok:        ${r.ok}`);
+    console.log(`  drift:     ${r.drift}`);
+    console.log(`  stale-age: ${r.staleAge}`);
+    console.log(`  skipped:   ${r.skipped}`);
+    console.log('');
+    if (r.drift === 0 && r.staleAge === 0)
+        return;
+    console.log(`Thresholds: overlap ≥${(r.thresholds.keywordOverlapMin * 100).toFixed(0)}%, freshness ≤${r.thresholds.freshnessMaxDays}d`);
+    console.log('');
+    for (const row of r.rows) {
+        if (row.status === 'ok' || row.status === 'skip')
+            continue;
+        const icon = row.status === 'drift' ? '⚠' : '⏰';
+        console.log(`${icon} ${row.artifactId}`);
+        console.log(`    ${row.reason}`);
+        if (row.symbolDelta && (row.symbolDelta.added.length > 0 || row.symbolDelta.removed.length > 0)) {
+            if (row.symbolDelta.added.length > 0)
+                console.log(`    + ${row.symbolDelta.added.join(', ')}`);
+            if (row.symbolDelta.removed.length > 0)
+                console.log(`    - ${row.symbolDelta.removed.join(', ')}`);
+        }
+        if (row.remediation) {
+            console.log(`    fix: ${row.remediation}`);
+        }
+        console.log('');
+    }
+}
+function flagValue(args, flag) {
+    const i = args.indexOf(flag);
+    return i !== -1 && args[i + 1] ? args[i + 1] : undefined;
+}
+function printUsage() {
+    console.log('aiwg index doctor --rlm-audit [options]');
+    console.log('');
+    console.log('Audits enriched index entries for content drift against the stored');
+    console.log('semantic summary and declared-symbol set.');
+    console.log('');
+    console.log('Options:');
+    console.log('  --filter <regex>             Restrict audit to artifact IDs matching regex');
+    console.log('  --recomputed-dir <path>      Directory of recomputed enrichment JSONs');
+    console.log('  --strict                     Exit non-zero on any drift or stale-age');
+    console.log('  --json                       Emit JSON report');
+    console.log('');
+    console.log('Threshold config: .aiwg/index/audit.config.yaml');
+}
+//# sourceMappingURL=cli.js.map

package/dist/src/artifacts/audit/drift.js

@@ -0,0 +1,122 @@
+/**
+ * Drift detection logic.
+ *
+ * Pure functions — given a stored SemanticFields and a current artifact
+ * snapshot, classify status and produce a DriftRow. The CLI layer
+ * orchestrates filesystem I/O around these primitives.
+ *
+ * @implements #1208
+ */
+import { DEFAULT_THRESHOLDS } from './types.js';
+const STOP_WORDS = new Set([
+    'the', 'a', 'an', 'and', 'or', 'but', 'if', 'on', 'in', 'at', 'to',
+    'for', 'of', 'is', 'are', 'was', 'were', 'be', 'been', 'this', 'that',
+    'with', 'from', 'as', 'by', 'it',
+]);
+/** Tokenize and de-stop a string into a content keyword set. */
+export function keywords(text) {
+    const tokens = text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 2 && !STOP_WORDS.has(t));
+    return new Set(tokens);
+}
+/** Jaccard-like overlap ratio between two keyword sets. */
+export function keywordOverlap(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    let intersect = 0;
+    for (const t of a)
+        if (b.has(t))
+            intersect++;
+    const union = a.size + b.size - intersect;
+    return union === 0 ? 1 : intersect / union;
+}
+/** Symmetric difference between two symbol arrays. */
+export function symbolDelta(stored, current) {
+    const sset = new Set(stored);
+    const cset = new Set(current);
+    const added = [];
+    const removed = [];
+    for (const c of cset)
+        if (!sset.has(c))
+            added.push(c);
+    for (const s of sset)
+        if (!cset.has(s))
+            removed.push(s);
+    added.sort();
+    removed.sort();
+    return { added, removed };
+}
+/** Classify drift for a single entry. */
+export function detectDrift(input) {
+    const t = { ...DEFAULT_THRESHOLDS, ...(input.thresholds ?? {}) };
+    const now = input.now ?? new Date();
+    const ageDays = Math.max(0, Math.floor((now.getTime() - new Date(input.stored.enrichedAt).getTime()) / 86_400_000));
+    // Hash matches → entry is content-fresh; only flag if past freshness window
+    if (input.stored.enrichedHash === input.currentHash) {
+        if (ageDays > t.freshnessMaxDays) {
+            return {
+                artifactId: input.artifactId,
+                status: 'stale-age',
+                reason: `enriched ${ageDays}d ago (>${t.freshnessMaxDays}d threshold), content unchanged`,
+                storedHash: input.stored.enrichedHash,
+                currentHash: input.currentHash,
+                ageDays,
+            };
+        }
+        return {
+            artifactId: input.artifactId,
+            status: 'ok',
+            reason: 'content unchanged',
+            storedHash: input.stored.enrichedHash,
+            currentHash: input.currentHash,
+            ageDays,
+        };
+    }
+    // Hash differs but no recomputation supplied → can't classify drift, skip
+    if (!input.recomputed) {
+        return {
+            artifactId: input.artifactId,
+            status: 'skip',
+            reason: 'hash differs but no recomputed enrichment supplied',
+            storedHash: input.stored.enrichedHash,
+            currentHash: input.currentHash,
+            ageDays,
+        };
+    }
+    // Hash differs AND recomputed → check semantic divergence
+    const overlap = keywordOverlap(keywords(input.stored.summary), keywords(input.recomputed.summary));
+    const delta = symbolDelta(input.stored.declaredSymbols, input.recomputed.declaredSymbols);
+    const symbolDriftSignificant = t.symbolChangeCritical && (delta.added.length > 0 || delta.removed.length > 0);
+    const overlapDriftSignificant = overlap < t.keywordOverlapMin;
+    if (overlapDriftSignificant || symbolDriftSignificant) {
+        const reasons = [];
+        if (overlapDriftSignificant)
+            reasons.push(`summary overlap ${(overlap * 100).toFixed(0)}% < ${(t.keywordOverlapMin * 100).toFixed(0)}%`);
+        if (symbolDriftSignificant)
+            reasons.push(`symbols changed (+${delta.added.length}/-${delta.removed.length})`);
+        return {
+            artifactId: input.artifactId,
+            status: 'drift',
+            reason: reasons.join('; '),
+            storedHash: input.stored.enrichedHash,
+            currentHash: input.currentHash,
+            ageDays,
+            overlap,
+            symbolDelta: delta,
+            remediation: `aiwg index enrich --using-rlm --files "${input.artifactId}" --force`,
+        };
+    }
+    return {
+        artifactId: input.artifactId,
+        status: 'ok',
+        reason: 'hash differs but semantic content within thresholds',
+        storedHash: input.stored.enrichedHash,
+        currentHash: input.currentHash,
+        ageDays,
+        overlap,
+        symbolDelta: delta,
+    };
+}
+//# sourceMappingURL=drift.js.map

package/dist/src/artifacts/audit/types.js

@@ -0,0 +1,12 @@
+/**
+ * Drift audit — type definitions.
+ *
+ * @implements #1208
+ * @see .aiwg/architecture/adr-rlm-index-features-impl-plan.md
+ */
+export const DEFAULT_THRESHOLDS = {
+    keywordOverlapMin: 0.70,
+    symbolChangeCritical: true,
+    freshnessMaxDays: 90,
+};
+//# sourceMappingURL=types.js.map

package/dist/src/artifacts/backends/graphology-backend.js

@@ -0,0 +1,160 @@
+/**
+ * Graphology Graph Backend
+ *
+ * Optional implementation of GraphBackend using the graphology library.
+ * Provides typed/attributed edges, BFS/DFS traversal, community detection,
+ * and shortest-path algorithms.
+ *
+ * Install: npm install graphology graphology-types graphology-operators graphology-traversal
+ *
+ * @implements #728
+ * @source @src/artifacts/graph-backend.ts
+ * @tests @test/unit/artifacts/graphology-backend.test.ts
+ */
+import { normalizeEdges } from '../types.js';
+/**
+ * Graphology-backed graph with rich traversal and operator ecosystem.
+ *
+ * Uses dynamic import so the graphology package is only loaded when this
+ * backend is explicitly selected. Projects that don't install graphology
+ * pay zero cost.
+ */
+export class GraphologyBackend {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    graph;
+    constructor(graphInstance) {
+        this.graph = graphInstance;
+    }
+    /**
+     * Factory: creates a GraphologyBackend with a fresh directed multigraph.
+     * Throws a clear error if graphology is not installed.
+     */
+    static async create() {
+        try {
+            const graphology = await import('graphology');
+            const Graph = graphology.default ?? graphology;
+            const graph = new Graph({ type: 'directed', multi: true });
+            return new GraphologyBackend(graph);
+        }
+        catch {
+            throw new Error('graphology backend requires: npm install graphology graphology-types graphology-operators graphology-traversal');
+        }
+    }
+    // --- Mutation ---
+    addNode(id, attrs) {
+        if (!this.graph.hasNode(id)) {
+            this.graph.addNode(id, attrs ?? {});
+        }
+        else if (attrs) {
+            this.graph.mergeNodeAttributes(id, attrs);
+        }
+    }
+    addEdge(source, target, type = 'depends-on', attrs) {
+        if (!this.graph.hasNode(source))
+            this.graph.addNode(source, {});
+        if (!this.graph.hasNode(target))
+            this.graph.addNode(target, {});
+        this.graph.addEdge(source, target, { type, ...attrs });
+    }
+    // --- Query ---
+    hasNode(id) {
+        return this.graph.hasNode(id);
+    }
+    hasEdge(source, target, edgeType) {
+        if (!edgeType)
+            return this.graph.hasEdge(source, target);
+        const edges = this.graph.edges(source, target);
+        return edges.some((e) => this.graph.getEdgeAttribute(e, 'type') === edgeType);
+    }
+    getNodeAttrs(id) {
+        if (!this.graph.hasNode(id))
+            return undefined;
+        return this.graph.getNodeAttributes(id);
+    }
+    nodes() {
+        return this.graph.nodes();
+    }
+    // --- Traversal ---
+    neighbors(nodeId, direction, edgeType) {
+        if (!this.graph.hasNode(nodeId))
+            return [];
+        let edgeIterator;
+        if (direction === 'in') {
+            edgeIterator = this.graph.inEdges(nodeId);
+        }
+        else if (direction === 'out') {
+            edgeIterator = this.graph.outEdges(nodeId);
+        }
+        else {
+            edgeIterator = this.graph.edges(nodeId);
+        }
+        const results = new Set();
+        for (const edgeKey of edgeIterator) {
+            if (edgeType && this.graph.getEdgeAttribute(edgeKey, 'type') !== edgeType)
+                continue;
+            const src = this.graph.source(edgeKey);
+            const tgt = this.graph.target(edgeKey);
+            // Add the "other" node
+            results.add(src === nodeId ? tgt : src);
+        }
+        return [...results];
+    }
+    // --- Set operations ---
+    intersection(setA, setB) {
+        const b = new Set(setB);
+        return setA.filter(x => b.has(x));
+    }
+    difference(setA, setB) {
+        const b = new Set(setB);
+        return setA.filter(x => !b.has(x));
+    }
+    union(setA, setB) {
+        return [...new Set([...setA, ...setB])];
+    }
+    // --- Persistence ---
+    serialize() {
+        const result = {};
+        this.graph.forEachNode((id) => {
+            const upstream = [];
+            const downstream = [];
+            for (const edgeKey of this.graph.inEdges(id)) {
+                upstream.push({
+                    path: this.graph.source(edgeKey),
+                    type: this.graph.getEdgeAttribute(edgeKey, 'type') ?? 'depends-on',
+                });
+            }
+            for (const edgeKey of this.graph.outEdges(id)) {
+                downstream.push({
+                    path: this.graph.target(edgeKey),
+                    type: this.graph.getEdgeAttribute(edgeKey, 'type') ?? 'depends-on',
+                });
+            }
+            result[id] = { upstream, downstream };
+        });
+        return result;
+    }
+    deserialize(data) {
+        this.graph.clear();
+        // First pass: add all declared nodes
+        for (const id of Object.keys(data)) {
+            if (!this.graph.hasNode(id))
+                this.graph.addNode(id, {});
+        }
+        // Second pass: add edges (upstream edges define the directed relationships)
+        for (const [id, node] of Object.entries(data)) {
+            const upEdges = normalizeEdges(node.upstream);
+            for (const edge of upEdges) {
+                if (!this.graph.hasNode(edge.path))
+                    this.graph.addNode(edge.path, {});
+                this.graph.addEdge(edge.path, id, { type: edge.type });
+            }
+        }
+    }
+    nodeCount() {
+        return this.graph.order;
+    }
+    edgeCount() {
+        return this.graph.size;
+    }
+}
+//# sourceMappingURL=graphology-backend.js.map

package/dist/src/artifacts/backends/json-backend.js

@@ -0,0 +1,129 @@
+/**
+ * JSON Graph Backend
+ *
+ * Default zero-dependency implementation of GraphBackend wrapping the
+ * existing DependencyGraph adjacency list format. Suitable for projects
+ * with <5k nodes.
+ *
+ * @implements #727
+ * @source @src/artifacts/graph-backend.ts
+ * @tests @test/unit/artifacts/graph-backend.test.ts
+ */
+import { normalizeEdges } from '../types.js';
+/**
+ * JSON-backed graph using plain objects and JS Set operations.
+ *
+ * This is the default backend — always available, no external dependencies.
+ */
+export class JsonGraphBackend {
+    graph = new Map();
+    // --- Mutation ---
+    addNode(id, attrs) {
+        if (!this.graph.has(id)) {
+            this.graph.set(id, { upstream: [], downstream: [], attrs: attrs ?? {} });
+        }
+        else if (attrs) {
+            const node = this.graph.get(id);
+            Object.assign(node.attrs, attrs);
+        }
+    }
+    addEdge(source, target, type = 'depends-on', attrs) {
+        // Ensure both nodes exist
+        this.addNode(source);
+        this.addNode(target);
+        const sourceNode = this.graph.get(source);
+        const targetNode = this.graph.get(target);
+        // Add downstream edge on source
+        sourceNode.downstream.push({ path: target, type, ...attrs });
+        // Add upstream edge on target
+        targetNode.upstream.push({ path: source, type, ...attrs });
+    }
+    // --- Query ---
+    hasNode(id) {
+        return this.graph.has(id);
+    }
+    hasEdge(source, target, edgeType) {
+        const node = this.graph.get(source);
+        if (!node)
+            return false;
+        return node.downstream.some(e => e.path === target && (!edgeType || e.type === edgeType));
+    }
+    getNodeAttrs(id) {
+        return this.graph.get(id)?.attrs;
+    }
+    nodes() {
+        return [...this.graph.keys()];
+    }
+    // --- Traversal ---
+    neighbors(nodeId, direction, edgeType) {
+        const node = this.graph.get(nodeId);
+        if (!node)
+            return [];
+        const results = new Set();
+        if (direction === 'in' || direction === 'both') {
+            for (const edge of node.upstream) {
+                if (!edgeType || edge.type === edgeType) {
+                    results.add(edge.path);
+                }
+            }
+        }
+        if (direction === 'out' || direction === 'both') {
+            for (const edge of node.downstream) {
+                if (!edgeType || edge.type === edgeType) {
+                    results.add(edge.path);
+                }
+            }
+        }
+        return [...results];
+    }
+    // --- Set operations ---
+    intersection(setA, setB) {
+        const b = new Set(setB);
+        return setA.filter(x => b.has(x));
+    }
+    difference(setA, setB) {
+        const b = new Set(setB);
+        return setA.filter(x => !b.has(x));
+    }
+    union(setA, setB) {
+        return [...new Set([...setA, ...setB])];
+    }
+    // --- Persistence ---
+    serialize() {
+        const result = {};
+        for (const [id, node] of this.graph) {
+            result[id] = {
+                upstream: [...node.upstream],
+                downstream: [...node.downstream],
+            };
+        }
+        return result;
+    }
+    deserialize(data) {
+        this.graph.clear();
+        for (const [id, node] of Object.entries(data)) {
+            const upstream = normalizeEdges(node.upstream);
+            const downstream = normalizeEdges(node.downstream);
+            this.graph.set(id, { upstream, downstream, attrs: {} });
+        }
+        // Ensure all referenced nodes exist
+        for (const [, node] of this.graph) {
+            for (const edge of [...node.upstream, ...node.downstream]) {
+                if (!this.graph.has(edge.path)) {
+                    this.graph.set(edge.path, { upstream: [], downstream: [], attrs: {} });
+                }
+            }
+        }
+    }
+    nodeCount() {
+        return this.graph.size;
+    }
+    edgeCount() {
+        let count = 0;
+        for (const [, node] of this.graph) {
+            count += node.downstream.length;
+        }
+        return count;
+    }
+}
+//# sourceMappingURL=json-backend.js.map