@rasensio/aidlc 1.2.1 → 1.4.0

package/dist/cost/sync.js

@@ -0,0 +1,191 @@
+/**
+ * Post-hoc reconciliation: `aidlc cost sync` (FR4).
+ *
+ * Correlates platform usage records with instances via sessions.ndjson.
+ * Platform-id sessions match records by id equality; agent-id sessions
+ * match by interval overlap with a strict single-candidate rule. Appends
+ * `reconciled` entries only where coverage is not already held at equal or
+ * higher fidelity. Idempotent by construction; never guesses — ambiguity
+ * goes to the report, unattributable usage to unattributed.ndjson.
+ *
+ * Design: design.md §4.4
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { readEntries, appendEntry, ledgerPath, unattributedPath } from './ledger.js';
+import { sessionsPath, readSessionEvents, resolveIntervals } from './sessions.js';
+import { getProvider } from './providers/provider.js';
+import { transcriptRoot } from './providers/claude-code.js';
+import { phaseWindows } from './recorder.js';
+import { logCapture } from './recorder.js';
+function coveredWindows(entries, sessionId, minRank) {
+    const rank = { metered: 3, reconciled: 2, estimated: 1, unknown: 0 };
+    return entries
+        .filter((e) => e.session_id === sessionId && rank[e.fidelity] >= minRank && e.units !== null)
+        .map((e) => ({ from: Date.parse(e.coverage.from), to: Date.parse(e.coverage.to) }));
+}
+function overlapsAny(at, windows) {
+    return windows.some((w) => at >= w.from && at <= w.to);
+}
+/**
+ * Reconcile one or all instances. Streams platform records session by
+ * session; reports everything it skipped and why (FR4.3).
+ */
+export async function syncCosts(projectRoot, instanceFilter, claimTimeoutMinutes, env = { projectRoot }) {
+    const report = { attributed: 0, skipped: [], unattributed: 0 };
+    const stateDir = join(projectRoot, '.aidlc', 'state');
+    if (!existsSync(stateDir))
+        return report;
+    const instances = readdirSync(stateDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name)
+        .filter((n) => instanceFilter === null || n === instanceFilter);
+    const perInstance = instances.map((instance) => ({
+        instance,
+        intervals: resolveIntervals(readSessionEvents(sessionsPath(projectRoot, instance)), claimTimeoutMinutes),
+    }));
+    // Gather every session id seen anywhere.
+    const sessions = new Map();
+    for (const { intervals } of perInstance) {
+        for (const iv of intervals) {
+            sessions.set(iv.session_id, { id_source: iv.id_source, agent: iv.agent });
+        }
+    }
+    for (const [sessionId, meta] of sessions) {
+        const provider = getProvider(meta.agent);
+        if (!provider) {
+            report.skipped.push(`${sessionId}: no provider for agent "${meta.agent}"`);
+            continue;
+        }
+        // Locate the record file.
+        let recordPath = null;
+        if (meta.id_source === 'platform') {
+            recordPath = locateById(provider.name, sessionId, env);
+            if (!recordPath) {
+                report.skipped.push(`${sessionId}: no local ${provider.name} records found`);
+                continue;
+            }
+        }
+        else {
+            const candidates = locateByInterval(provider.name, sessionId, perInstance, env);
+            if (candidates.length === 0) {
+                report.skipped.push(`${sessionId}: agent-id session, no overlapping ${provider.name} records`);
+                continue;
+            }
+            if (candidates.length > 1) {
+                report.skipped.push(`${sessionId}: agent-id session, ${candidates.length} candidate records — ambiguous, not guessing`);
+                continue;
+            }
+            recordPath = candidates[0];
+        }
+        let segments;
+        try {
+            segments = await provider.extract({ provider: provider.name, path: recordPath }, null, env);
+        }
+        catch {
+            logCapture(projectRoot, 'sync-extract', 'extract-failed');
+            report.skipped.push(`${sessionId}: extraction failed`);
+            continue;
+        }
+        for (const seg of segments) {
+            const at = Date.parse(seg.at);
+            let target = { instance: null, phase: null };
+            for (const { instance, intervals } of perInstance) {
+                const mine = intervals.filter((iv) => iv.session_id === sessionId);
+                if (mine.some((iv) => at >= Date.parse(iv.from) && at <= Date.parse(iv.to))) {
+                    const windows = phaseWindows(projectRoot, instance, 'implementation');
+                    const phase = windows.find((w) => at >= w.from && at < w.to)?.phase ?? null;
+                    target = { instance, phase };
+                    break;
+                }
+            }
+            const targetPath = target.instance !== null
+                ? ledgerPath(projectRoot, target.instance)
+                : unattributedPath(projectRoot);
+            const existing = readEntries(targetPath);
+            // Skip segments already covered at reconciled-or-better fidelity.
+            if (overlapsAny(at, coveredWindows(existing, sessionId, 2)))
+                continue;
+            const entry = {
+                timestamp: new Date().toISOString(),
+                session_id: sessionId,
+                phase: target.phase,
+                provider: provider.name,
+                fidelity: 'reconciled',
+                coverage: { from: seg.at, to: seg.at },
+                cursor: seg.cursor,
+                units: seg.units,
+            };
+            try {
+                appendEntry(targetPath, entry);
+                if (target.instance !== null)
+                    report.attributed++;
+                else
+                    report.unattributed++;
+            }
+            catch {
+                logCapture(projectRoot, 'sync-append', 'validation-rejected');
+            }
+        }
+    }
+    return report;
+}
+/** Locate a platform record file by session id equality. */
+function locateById(providerName, sessionId, env) {
+    if (providerName === 'claude-code') {
+        const root = transcriptRoot(env);
+        if (!existsSync(root))
+            return null;
+        for (const dir of readdirSync(root, { withFileTypes: true })) {
+            if (!dir.isDirectory())
+                continue;
+            const candidate = join(root, dir.name, `${sessionId}.jsonl`);
+            if (existsSync(candidate))
+                return candidate;
+        }
+        return null;
+    }
+    if (providerName === 'kiro') {
+        const provider = getProvider('kiro');
+        const source = provider?.resolveSource({ session_id: sessionId }, env);
+        return source?.path ?? null;
+    }
+    return null;
+}
+/**
+ * For agent-id sessions: find record files whose usage overlaps the
+ * session's claim intervals. Strict — several candidates means ambiguity.
+ */
+function locateByInterval(providerName, sessionId, perInstance, env) {
+    if (providerName !== 'claude-code')
+        return [];
+    const intervals = perInstance
+        .flatMap(({ intervals }) => intervals)
+        .filter((iv) => iv.session_id === sessionId);
+    if (intervals.length === 0)
+        return [];
+    const root = transcriptRoot(env);
+    if (!existsSync(root))
+        return [];
+    const matches = [];
+    for (const dir of readdirSync(root, { withFileTypes: true })) {
+        if (!dir.isDirectory())
+            continue;
+        for (const f of readdirSync(join(root, dir.name))) {
+            if (!f.endsWith('.jsonl'))
+                continue;
+            const path = join(root, dir.name, f);
+            try {
+                const mtime = statSync(path).mtimeMs;
+                if (intervals.some((iv) => mtime >= Date.parse(iv.from) && mtime <= Date.parse(iv.to) + 60 * 60 * 1000)) {
+                    matches.push(path);
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return matches;
+}
+//# sourceMappingURL=sync.js.map

package/dist/cost/sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../src/cost/sync.ts"],"names":[],"mappings":"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"}

package/dist/cost/types.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Cost-tracking domain types.
+ *
+ * The ledger records raw usage units (tokens, credits) — never dollars.
+ * Dollars are computed at report time from a rate table (see rates.ts).
+ *
+ * Design: .aidlc/state/cost-tracking/design.md §2
+ */
+/** Token usage for a single model within a coverage window. */
+export interface TokenUnits {
+    kind: 'tokens';
+    model: string;
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_tokens: number;
+    cache_write_tokens: number;
+}
+/** Credit usage (Kiro-style metering) within a coverage window. */
+export interface CreditUnits {
+    kind: 'credits';
+    credits: number;
+    model: string | null;
+}
+export type CostUnits = TokenUnits | CreditUnits;
+/** Provenance of a ledger entry's numbers. */
+export type CostFidelity = 'metered' | 'reconciled' | 'estimated' | 'unknown';
+/** One line in costs.ndjson / unattributed.ndjson. */
+export interface CostEntry {
+    /** ISO 8601 UTC append time. */
+    timestamp: string;
+    session_id: string | null;
+    /** Phase the usage occurred in; null only in unattributed.ndjson. */
+    phase: string | null;
+    provider: string;
+    fidelity: CostFidelity;
+    /** Usage window this entry covers. */
+    coverage: {
+        from: string;
+        to: string;
+    };
+    /** Provider resume point after this entry (e.g. transcript message uuid). */
+    cursor: string | null;
+    /** null ⇔ fidelity 'unknown' (attribution interval marker). */
+    units: CostUnits | null;
+}
+/** One line in sessions.ndjson. */
+export interface SessionEvent {
+    event: 'claim' | 'renew' | 'release';
+    session_id: string;
+    id_source: 'platform' | 'agent';
+    agent: string;
+    timestamp: string;
+}
+/** A resolved session↔instance attribution interval. */
+export interface ClaimInterval {
+    session_id: string;
+    id_source: 'platform' | 'agent';
+    agent: string;
+    from: string;
+    /** Release time, or claim-timeout bound for unreleased claims. */
+    to: string;
+    /** True when bounded by timeout rather than an explicit release. */
+    open: boolean;
+}
+/** Active-session stash entry (.aidlc/cost/active-sessions/<id>.json). */
+export interface ActiveSession {
+    session_id: string;
+    agent: string;
+    cwd: string;
+    transcript_path?: string;
+    started_at: string;
+}
+/** A usage segment extracted by a provider, pre-attribution. */
+export interface UsageSegment {
+    /** ISO 8601 timestamp of the usage event. */
+    at: string;
+    units: CostUnits;
+    /** Provider resume point after this segment. */
+    cursor: string;
+}
+/** Validated pointer to a provider's usage records. */
+export interface SourceRef {
+    provider: string;
+    path: string;
+}
+/** Input to `aidlc cost record` in hook mode (parsed from stdin). */
+export interface RecordInput {
+    session_id: string;
+    transcript_path?: string;
+    cwd?: string;
+}
+/** Per-model (or per-unit) pricing entry. */
+export interface RateEntry {
+    input_per_mtok?: number;
+    output_per_mtok?: number;
+    cache_read_per_mtok?: number;
+    cache_write_per_mtok?: number;
+    /** For unit-priced providers (e.g. kiro-credit). */
+    per_unit?: number;
+}
+/** A rate table snapshot with provenance. */
+export interface RateSnapshot {
+    snapshot_version: string;
+    effective_date: string;
+    rates: Record<string, RateEntry>;
+}
+/** Cost section of .aidlc/config.yaml. */
+export interface CostConfig {
+    rates_url?: string;
+    rates?: Record<string, RateEntry>;
+}
+/** Session-id format shared by validation and path construction (FR3.9). */
+export declare const SESSION_ID_RE: RegExp;
+/** Model-id format allowed in ledger entries. */
+export declare const MODEL_ID_RE: RegExp;
+//# sourceMappingURL=types.d.ts.map

package/dist/cost/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/cost/types.ts"],"names":[],"mappings":"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"}

package/dist/cost/types.js

@@ -0,0 +1,13 @@
+/**
+ * Cost-tracking domain types.
+ *
+ * The ledger records raw usage units (tokens, credits) — never dollars.
+ * Dollars are computed at report time from a rate table (see rates.ts).
+ *
+ * Design: .aidlc/state/cost-tracking/design.md §2
+ */
+/** Session-id format shared by validation and path construction (FR3.9). */
+export const SESSION_ID_RE = /^[A-Za-z0-9_-]{8,64}$/;
+/** Model-id format allowed in ledger entries. */
+export const MODEL_ID_RE = /^[A-Za-z0-9_.:/@-]{1,128}$/;
+//# sourceMappingURL=types.js.map

package/dist/cost/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/cost/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAoHH,4EAA4E;AAC5E,MAAM,CAAC,MAAM,aAAa,GAAG,uBAAuB,CAAC;AAErD,iDAAiD;AACjD,MAAM,CAAC,MAAM,WAAW,GAAG,4BAA4B,CAAC"}

package/dist/setup/setup-compute.d.ts

@@ -34,6 +34,12 @@ export interface SetupConfig {
     actions: string[];
     stalled_threshold_days: number;
     claim_timeout_minutes: number;
+    /**
+     * Sections computeSetup does not own (cost, orchestrator, secret_patterns,
+     * anything future) carry through rebuilds untouched — re-running init must
+     * never drop a hand-added config section.
+     */
+    [key: string]: unknown;
 }
 /**
  * Compute the setup result by merging existing config with new answers.

package/dist/setup/setup-compute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup-compute.d.ts","sourceRoot":"","sources":["../../src/setup/setup-compute.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMnD,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE;QACR,KAAK,EAAE,UAAU,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAkCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,WAAW,GAAG,IAAI,EAC5B,OAAO,EAAE,YAAY,GACpB,WAAW,CAcb"}
+{"version":3,"file":"setup-compute.d.ts","sourceRoot":"","sources":["../../src/setup/setup-compute.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMnD,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE;QACR,KAAK,EAAE,UAAU,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qBAAqB,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAkCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,WAAW,GAAG,IAAI,EAC5B,OAAO,EAAE,YAAY,GACpB,WAAW,CAiBb"}

package/dist/setup/setup-compute.js

@@ -52,6 +52,9 @@ function sortedUnion(a, b) {
 export function computeSetup(existing, answers) {
     const base = existing ?? DEFAULT_CONFIG;
     return {
+        // Unknown keys first so owned fields below always win (DD8: preserve
+        // the whole class of hand-added sections, not just known ones).
+        ...base,
         version: base.version,
         defaults: {
             scope: answers.scope ?? base.defaults.scope,

package/dist/setup/setup-compute.js.map

@@ -1 +1 @@
-{"version":3,"file":"setup-compute.js","sourceRoot":"","sources":["../../src/setup/setup-compute.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAqCH,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E,MAAM,cAAc,GAAgB;IAClC,OAAO,EAAE,CAAC;IACV,QAAQ,EAAE;QACR,KAAK,EAAE,OAAO;QACd,QAAQ,EAAE,YAAY;KACvB;IACD,SAAS,EAAE,EAAE;IACb,OAAO,EAAE,EAAE;IACX,sBAAsB,EAAE,CAAC;IACzB,qBAAqB,EAAE,EAAE;CAC1B,CAAC;AAEF,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;GAEG;AACH,SAAS,WAAW,CAAC,CAAW,EAAE,CAAW;IAC3C,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IAClC,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AACzB,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAC1B,QAA4B,EAC5B,OAAqB;IAErB,MAAM,IAAI,GAAG,QAAQ,IAAI,cAAc,CAAC;IAExC,OAAO;QACL,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,QAAQ,EAAE;YACR,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK;YAC3C,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ;SACrD;QACD,SAAS,EAAE,WAAW,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC;QAC/D,OAAO,EAAE,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;QACzD,sBAAsB,EAAE,IAAI,CAAC,sBAAsB;QACnD,qBAAqB,EAAE,IAAI,CAAC,qBAAqB;KAClD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"setup-compute.js","sourceRoot":"","sources":["../../src/setup/setup-compute.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA2CH,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E,MAAM,cAAc,GAAgB;IAClC,OAAO,EAAE,CAAC;IACV,QAAQ,EAAE;QACR,KAAK,EAAE,OAAO;QACd,QAAQ,EAAE,YAAY;KACvB;IACD,SAAS,EAAE,EAAE;IACb,OAAO,EAAE,EAAE;IACX,sBAAsB,EAAE,CAAC;IACzB,qBAAqB,EAAE,EAAE;CAC1B,CAAC;AAEF,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;GAEG;AACH,SAAS,WAAW,CAAC,CAAW,EAAE,CAAW;IAC3C,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IAClC,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AACzB,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAC1B,QAA4B,EAC5B,OAAqB;IAErB,MAAM,IAAI,GAAG,QAAQ,IAAI,cAAc,CAAC;IAExC,OAAO;QACL,qEAAqE;QACrE,gEAAgE;QAChE,GAAG,IAAI;QACP,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,QAAQ,EAAE;YACR,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK;YAC3C,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ;SACrD;QACD,SAAS,EAAE,WAAW,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC;QAC/D,OAAO,EAAE,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;QACzD,sBAAsB,EAAE,IAAI,CAAC,sBAAsB;QACnD,qBAAqB,EAAE,IAAI,CAAC,qBAAqB;KAClD,CAAC;AACJ,CAAC"}

package/dist/traceability/cache.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Status-column coverage cache (AC-17, NFR2): `aidlc status` must stay
+ * filesystem-cheap, so coverage is cached at
+ * `.aidlc/cache/traceability/<instance>.json` — outside tracked state
+ * (derived data, design F5) — keyed by a stat hash of every input coverage
+ * depends on, including ALL instances' requirements.md (the uniqueness rule
+ * makes coverage cross-instance, design F2). Cache hit costs stats only;
+ * corrupt or absent cache degrades to recompute (fail-soft).
+ *
+ * Requirements: traceability-ids/AC-17
+ */
+import type { CoverageSummary } from './types.js';
+/**
+ * Coverage summary for the status column, cached by input stat hash.
+ *
+ * @returns null when the criterion does not apply to the instance.
+ */
+export declare function coverageForStatus(projectRoot: string, instanceName: string): CoverageSummary | null;
+/** Format a coverage summary for the status table cell. */
+export declare function formatCoverage(coverage: CoverageSummary): string;
+//# sourceMappingURL=cache.d.ts.map

package/dist/traceability/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/traceability/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAyDlD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,eAAe,GAAG,IAAI,CA6BxB;AAED,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAGhE"}

package/dist/traceability/cache.js

@@ -0,0 +1,106 @@
+/**
+ * Status-column coverage cache (AC-17, NFR2): `aidlc status` must stay
+ * filesystem-cheap, so coverage is cached at
+ * `.aidlc/cache/traceability/<instance>.json` — outside tracked state
+ * (derived data, design F5) — keyed by a stat hash of every input coverage
+ * depends on, including ALL instances' requirements.md (the uniqueness rule
+ * makes coverage cross-instance, design F2). Cache hit costs stats only;
+ * corrupt or absent cache degrades to recompute (fail-soft).
+ *
+ * Requirements: traceability-ids/AC-17
+ */
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DEFAULT_TEST_GLOBS, discoverTestFiles } from './scanner.js';
+import { evaluateTraceabilityCriterion, loadTraceabilityConfig } from './gate-criterion.js';
+function statLine(path) {
+    try {
+        const s = statSync(path);
+        return `${s.mtimeMs}:${s.size}`;
+    }
+    catch {
+        return 'absent';
+    }
+}
+/** Hash every input the coverage matrix depends on (design DD5). */
+function computeInputsHash(projectRoot, instanceName) {
+    const stateDir = join(projectRoot, '.aidlc', 'state');
+    const hash = createHash('sha256');
+    hash.update(statLine(join(stateDir, instanceName, 'requirements.md')) + '\n');
+    hash.update(statLine(join(stateDir, instanceName, 'testing.md')) + '\n');
+    // Every instance's requirements.md, sorted — bare-ref uniqueness (AC-24).
+    let instances = [];
+    try {
+        instances = readdirSync(stateDir).sort();
+    }
+    catch {
+        // No state dir — hash stays partial-but-deterministic.
+    }
+    for (const name of instances) {
+        hash.update(`${name}:${statLine(join(stateDir, name, 'requirements.md'))}\n`);
+    }
+    const globs = loadTraceabilityConfig(projectRoot)?.test_globs ?? DEFAULT_TEST_GLOBS;
+    hash.update(globs.join('\0') + '\n');
+    const discovery = discoverTestFiles(projectRoot, globs);
+    for (const file of discovery.files) {
+        hash.update(`${file}:${statLine(join(projectRoot, ...file.split('/')))}\n`);
+    }
+    return hash.digest('hex');
+}
+function summarize(projectRoot, instanceName) {
+    const result = evaluateTraceabilityCriterion(projectRoot, instanceName, 'testing');
+    if (result === null || result.entries.length === 0)
+        return null;
+    const active = result.entries.filter((e) => e.status !== 'retired');
+    const stale = result.warnings.filter((w) => w.includes('(stale reference)')).length;
+    return {
+        covered: active.filter((e) => e.status === 'covered').length,
+        total: active.length,
+        stale,
+    };
+}
+/**
+ * Coverage summary for the status column, cached by input stat hash.
+ *
+ * @returns null when the criterion does not apply to the instance.
+ */
+export function coverageForStatus(projectRoot, instanceName) {
+    const cacheDir = join(projectRoot, '.aidlc', 'cache', 'traceability');
+    const cachePath = join(cacheDir, `${instanceName}.json`);
+    const inputsHash = computeInputsHash(projectRoot, instanceName);
+    try {
+        const cached = JSON.parse(readFileSync(cachePath, 'utf8'));
+        if (cached.inputsHash === inputsHash && cached.coverage)
+            return cached.coverage;
+    }
+    catch {
+        // Miss — recompute below.
+    }
+    const coverage = summarize(projectRoot, instanceName);
+    if (coverage === null)
+        return null;
+    try {
+        mkdirSync(cacheDir, { recursive: true });
+        // Self-ignoring cache dir: derived data must never land in git, even in
+        // consumer repos whose .gitignore predates this feature (design F5).
+        const ignorePath = join(projectRoot, '.aidlc', 'cache', '.gitignore');
+        try {
+            readFileSync(ignorePath);
+        }
+        catch {
+            writeFileSync(ignorePath, '*\n');
+        }
+        writeFileSync(cachePath, JSON.stringify({ inputsHash, coverage }));
+    }
+    catch {
+        // Cache write failure never breaks status.
+    }
+    return coverage;
+}
+/** Format a coverage summary for the status table cell. */
+export function formatCoverage(coverage) {
+    const base = `${coverage.covered}/${coverage.total}`;
+    return coverage.stale > 0 ? `${base} ⚠${coverage.stale}` : base;
+}
+//# sourceMappingURL=cache.js.map

package/dist/traceability/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/traceability/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxF,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,EAAE,6BAA6B,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAO5F,SAAS,QAAQ,CAAC,IAAY;IAC5B,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QACzB,OAAO,GAAG,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC;AAED,oEAAoE;AACpE,SAAS,iBAAiB,CAAC,WAAmB,EAAE,YAAoB;IAClE,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IACtD,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IAClC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,EAAE,iBAAiB,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC9E,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,EAAE,YAAY,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEzE,0EAA0E;IAC1E,IAAI,SAAS,GAAa,EAAE,CAAC;IAC7B,IAAI,CAAC;QACH,SAAS,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,uDAAuD;IACzD,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,iBAAiB,CAAC,CAAC,IAAI,CAAC,CAAC;IAChF,CAAC;IAED,MAAM,KAAK,GAAG,sBAAsB,CAAC,WAAW,CAAC,EAAE,UAAU,IAAI,kBAAkB,CAAC;IACpF,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;IACrC,MAAM,SAAS,GAAG,iBAAiB,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IACxD,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,KAAK,EAAE,CAAC;QACnC,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC;AAED,SAAS,SAAS,CAAC,WAAmB,EAAE,YAAoB;IAC1D,MAAM,MAAM,GAAG,6BAA6B,CAAC,WAAW,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC;IACnF,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAChE,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC;IACpE,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC,CAAC,MAAM,CAAC;IACpF,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,MAAM;QAC5D,KAAK,EAAE,MAAM,CAAC,MAAM;QACpB,KAAK;KACN,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,WAAmB,EACnB,YAAoB;IAEpB,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC;IACtE,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,EAAE,GAAG,YAAY,OAAO,CAAC,CAAC;IACzD,MAAM,UAAU,GAAG,iBAAiB,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IAEhE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAc,CAAC;QACxE,IAAI,MAAM,CAAC,UAAU,KAAK,UAAU,IAAI,MAAM,CAAC,QAAQ;YAAE,OAAO,MAAM,CAAC,QAAQ,CAAC;IAClF,CAAC;IAAC,MAAM,CAAC;QACP,0BAA0B;IAC5B,CAAC;IAED,MAAM,QAAQ,GAAG,SAAS,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IACtD,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,CAAC;QACH,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,wEAAwE;QACxE,qEAAqE;QACrE,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;QACtE,IAAI,CAAC;YACH,YAAY,CAAC,UAAU,CAAC,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,aAAa,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QACnC,CAAC;QACD,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,UAAU,EAAE,QAAQ,EAAsB,CAAC,CAAC,CAAC;IACzF,CAAC;IAAC,MAAM,CAAC;QACP,2CAA2C;IAC7C,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,cAAc,CAAC,QAAyB;IACtD,MAAM,IAAI,GAAG,GAAG,QAAQ,CAAC,OAAO,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;IACrD,OAAO,QAAQ,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAClE,CAAC"}

package/dist/traceability/coverage-block.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `ac-coverage` block parser (FR3, D2): a fenced code block in the instance's
+ * testing.md whose info string is `ac-coverage`, one `AC-n: evidence` line
+ * per entry. The explicit escape hatch for manually or indirectly verified
+ * criteria — block entries union with scanned references (AC-9).
+ *
+ * Requirements: traceability-ids/AC-9, AC-10
+ */
+export interface CoverageBlockEntry {
+    acId: number;
+    evidence: string;
+    /** 1-based line within testing.md. */
+    line: number;
+}
+export interface CoverageBlockResult {
+    entries: CoverageBlockEntry[];
+    warnings: string[];
+}
+/** Parse all `ac-coverage` blocks from testing.md content. */
+export declare function parseCoverageBlock(content: string): CoverageBlockResult;
+//# sourceMappingURL=coverage-block.d.ts.map

package/dist/traceability/coverage-block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-block.d.ts","sourceRoot":"","sources":["../../src/traceability/coverage-block.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;CACd;AAMD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,8DAA8D;AAC9D,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,CAwBvE"}

package/dist/traceability/coverage-block.js

@@ -0,0 +1,41 @@
+/**
+ * `ac-coverage` block parser (FR3, D2): a fenced code block in the instance's
+ * testing.md whose info string is `ac-coverage`, one `AC-n: evidence` line
+ * per entry. The explicit escape hatch for manually or indirectly verified
+ * criteria — block entries union with scanned references (AC-9).
+ *
+ * Requirements: traceability-ids/AC-9, AC-10
+ */
+const FENCE_OPEN_RE = /^\s*```ac-coverage\s*$/;
+const FENCE_CLOSE_RE = /^\s*```\s*$/;
+const ENTRY_RE = /^\s*AC-([1-9][0-9]*):\s*(.*\S)\s*$/;
+/** Parse all `ac-coverage` blocks from testing.md content. */
+export function parseCoverageBlock(content) {
+    const entries = [];
+    const warnings = [];
+    const lines = content.split('\n');
+    let inBlock = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!inBlock) {
+            if (FENCE_OPEN_RE.test(line))
+                inBlock = true;
+            continue;
+        }
+        if (FENCE_CLOSE_RE.test(line)) {
+            inBlock = false;
+            continue;
+        }
+        if (line.trim() === '')
+            continue;
+        const m = ENTRY_RE.exec(line);
+        if (m) {
+            entries.push({ acId: Number(m[1]), evidence: m[2], line: i + 1 });
+        }
+        else {
+            warnings.push(`ac-coverage block line ${i + 1}: unparseable entry "${line.trim()}"`);
+        }
+    }
+    return { entries, warnings };
+}
+//# sourceMappingURL=coverage-block.js.map

package/dist/traceability/coverage-block.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-block.js","sourceRoot":"","sources":["../../src/traceability/coverage-block.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,MAAM,aAAa,GAAG,wBAAwB,CAAC;AAC/C,MAAM,cAAc,GAAG,aAAa,CAAC;AACrC,MAAM,QAAQ,GAAG,oCAAoC,CAAC;AAOtD,8DAA8D;AAC9D,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,MAAM,OAAO,GAAyB,EAAE,CAAC;IACzC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,OAAO,GAAG,IAAI,CAAC;YAC7C,SAAS;QACX,CAAC;QACD,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9B,OAAO,GAAG,KAAK,CAAC;YAChB,SAAS;QACX,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,SAAS;QACjC,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,CAAC,EAAE,CAAC;YACN,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpE,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,IAAI,CAAC,0BAA0B,CAAC,GAAG,CAAC,wBAAwB,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AAC/B,CAAC"}

package/dist/traceability/gate-criterion.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Traceability gate criterion (FR4): computed live at the command layer
+ * after `evaluateGate`, following the knowledge-criterion precedent — it
+ * therefore evaluates even when phase state is `complete` (AC-11) and never
+ * touches `evaluateGate`'s contract (DD1).
+ *
+ * Applicability tri-state (DD7):
+ *   null                      phase ≠ testing, phase-testing.yaml absent, or
+ *                             zero AC-shaped lines (AC-3, AC-13)
+ *   result, empty entries     only near-misses — warnings surface (AC-22)
+ *   result with entries       ≥1 valid definition — full evaluation
+ *
+ * Requirements: traceability-ids/AC-3, AC-11..AC-15
+ */
+import type { ParsedRequirements, TraceabilityConfig, TraceabilityResult } from './types.js';
+/** Message template callers use for unsatisfied criteria / violations. */
+export declare function uncoveredMessage(acId: number): string;
+/** Tolerant reader for the optional `traceability:` config section (AC-7). */
+export declare function loadTraceabilityConfig(projectRoot: string): TraceabilityConfig | null;
+/**
+ * Parse every instance's requirements.md — the registry backing the bare-
+ * reference uniqueness rule (AC-24, D5). Reads by explicit path; the
+ * scanner's `.aidlc` exclusion governs test discovery only.
+ */
+export declare function loadRegistry(projectRoot: string): Map<string, ParsedRequirements>;
+/**
+ * Evaluate the traceability criterion for one instance.
+ *
+ * @returns null when the criterion does not evaluate (AC-3, AC-13); otherwise
+ *   a result whose `uncoveredActive` entries the caller turns into
+ *   unsatisfied criteria / gate violations via {@link uncoveredMessage}.
+ */
+export declare function evaluateTraceabilityCriterion(projectRoot: string, instanceName: string, phaseName: string): TraceabilityResult | null;
+//# sourceMappingURL=gate-criterion.d.ts.map

package/dist/traceability/gate-criterion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate-criterion.d.ts","sourceRoot":"","sources":["../../src/traceability/gate-criterion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAM7F,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,8EAA8E;AAC9E,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAarF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAkBjF;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAChB,kBAAkB,GAAG,IAAI,CAuD3B"}