@deftai/directive-core 0.55.0

package/dist/triage/summary/index.js

@@ -0,0 +1,431 @@
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve as pathResolve } from "node:path";
+import { loadProjectDefinition, PROJECT_DEFINITION_REL_PATH } from "../../policy/resolve.js";
+import { countVbriefWip, DEFAULT_WIP_CAP, resolveWipCap } from "../../policy/wip.js";
+import { countReconcilable } from "./reconcilable.js";
+import { computeScopeDriftTotal } from "./scope-drift.js";
+// ---------------------------------------------------------------------------
+// Public constants
+// ---------------------------------------------------------------------------
+export const MAX_LINE_CHARS = 120;
+export { DEFAULT_WIP_CAP, PROJECT_DEFINITION_REL_PATH };
+export const CACHE_DIR_NAME = ".deft-cache";
+export const CACHE_SOURCE = "github-issue";
+export const CANDIDATES_LOG_REL_PATH = "vbrief/.eval/candidates.jsonl";
+export const SUMMARY_HISTORY_REL_PATH = "vbrief/.eval/summary-history.jsonl";
+export const SUMMARY_HISTORY_SCHEMA = "deft.triage.summary.v1";
+export const EMPTY_CACHE_LINE = "[triage] cache empty -- run task triage:bootstrap";
+export const WIP_LIFECYCLE_DIRS = ["pending", "active"];
+export const FILESYSTEM_IN_FLIGHT_FOLDER = "active";
+export const FILESYSTEM_IN_FLIGHT_STATUS = "running";
+export const WIP_WARN_GLYPH = "\u26a0";
+export const IN_FLIGHT_DECISIONS = new Set(["accept"]);
+export const TRIAGED_DECISIONS = new Set([
+    "accept",
+    "reject",
+    "defer",
+    "needs-ac",
+    "mark-duplicate",
+    "resume-eligible",
+]);
+export const STALE_DEFER_DECISIONS = new Set(["resume-eligible"]);
+// ---------------------------------------------------------------------------
+// Time helpers
+// ---------------------------------------------------------------------------
+/** ISO-8601 UTC with explicit `Z` suffix. */
+export function utcIso(date) {
+    const moment = date ?? new Date();
+    const iso = moment.toISOString();
+    return iso.replace(/\.\d{3}Z$/, "Z");
+}
+// ---------------------------------------------------------------------------
+// Filesystem walkers
+// ---------------------------------------------------------------------------
+export function isPosIntDirName(name) {
+    if (name.length === 0) {
+        return false;
+    }
+    for (const ch of name) {
+        if (ch < "0" || ch > "9") {
+            return false;
+        }
+    }
+    return true;
+}
+/** Walk `<cache_root>/github-issue/<owner>/<repo>/<N>/` cache entries. */
+export function iterCachedIssues(cacheRoot) {
+    const base = join(cacheRoot, CACHE_SOURCE);
+    if (!existsSync(base)) {
+        return [];
+    }
+    const out = [];
+    for (const ownerEntry of readdirSync(base, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!ownerEntry.isDirectory()) {
+            continue;
+        }
+        const ownerDir = join(base, ownerEntry.name);
+        for (const repoEntry of readdirSync(ownerDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!repoEntry.isDirectory()) {
+                continue;
+            }
+            const repo = `${ownerEntry.name}/${repoEntry.name}`;
+            const repoDir = join(ownerDir, repoEntry.name);
+            const issueDirs = readdirSync(repoDir, { withFileTypes: true })
+                .filter((e) => e.isDirectory() && isPosIntDirName(e.name))
+                .sort((a, b) => Number.parseInt(a.name, 10) - Number.parseInt(b.name, 10));
+            for (const issueEntry of issueDirs) {
+                const n = Number.parseInt(issueEntry.name, 10);
+                if (Number.isFinite(n)) {
+                    out.push([repo, n]);
+                }
+            }
+        }
+    }
+    return out;
+}
+export function readAuditLog(logPath) {
+    if (!existsSync(logPath)) {
+        return [];
+    }
+    let text;
+    try {
+        text = readFileSync(logPath, { encoding: "utf8" });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const raw of text.split("\n")) {
+        const stripped = raw.trim();
+        if (stripped.length === 0) {
+            continue;
+        }
+        try {
+            const obj = JSON.parse(stripped);
+            if (typeof obj === "object" && obj !== null && !Array.isArray(obj)) {
+                out.push(obj);
+            }
+        }
+        catch {
+            // tolerate malformed lines
+        }
+    }
+    return out;
+}
+/** Collapse audit-log entries to `{(repo, issue_number): decision}`. */
+export function latestDecisions(entries) {
+    const rows = [];
+    for (const entry of entries) {
+        const repo = entry.repo;
+        const issueNumber = entry.issue_number;
+        const decision = entry.decision;
+        const timestamp = entry.timestamp;
+        if (typeof repo !== "string" ||
+            typeof issueNumber !== "number" ||
+            !Number.isInteger(issueNumber) ||
+            typeof decision !== "string" ||
+            typeof timestamp !== "string") {
+            continue;
+        }
+        rows.push([timestamp, repo, issueNumber, decision]);
+    }
+    rows.sort((a, b) => a[0].localeCompare(b[0]));
+    const out = new Map();
+    for (const [_ts, repo, n, decision] of rows) {
+        out.set(`${repo}\0${n}`, decision);
+    }
+    return out;
+}
+function decisionKey(repo, issueNumber) {
+    return `${repo}\0${issueNumber}`;
+}
+// ---------------------------------------------------------------------------
+// vBRIEF counters
+// ---------------------------------------------------------------------------
+/** Count filesystem-truth in-flight vBRIEFs (#1270). */
+export function countFilesystemInFlight(projectRoot) {
+    const folder = join(pathResolve(projectRoot), "vbrief", FILESYSTEM_IN_FLIGHT_FOLDER);
+    if (!existsSync(folder)) {
+        return 0;
+    }
+    let total = 0;
+    for (const entry of readdirSync(folder, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith(".vbrief.json")) {
+            continue;
+        }
+        try {
+            const data = JSON.parse(readFileSync(join(folder, entry.name), { encoding: "utf8" }));
+            if (typeof data !== "object" || data === null || Array.isArray(data)) {
+                continue;
+            }
+            const plan = data.plan;
+            if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+                continue;
+            }
+            const status = plan.status;
+            if (status === FILESYSTEM_IN_FLIGHT_STATUS) {
+                total += 1;
+            }
+        }
+        catch {
+            // tolerate corrupt vBRIEFs
+        }
+    }
+    return total;
+}
+/** True iff `plan.policy.triageScope` is a non-empty list of dict rules. */
+export function isTriageScopeExplicitlyConfigured(projectRoot) {
+    const path = join(pathResolve(projectRoot), PROJECT_DEFINITION_REL_PATH);
+    if (!existsSync(path)) {
+        return false;
+    }
+    try {
+        const data = JSON.parse(readFileSync(path, { encoding: "utf8" }));
+        if (typeof data !== "object" || data === null || Array.isArray(data)) {
+            return false;
+        }
+        const plan = data.plan;
+        if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+            return false;
+        }
+        const policy = plan.policy;
+        if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
+            return false;
+        }
+        const scope = policy.triageScope;
+        if (!Array.isArray(scope) || scope.length === 0) {
+            return false;
+        }
+        return scope.some((rule) => typeof rule === "object" && rule !== null && !Array.isArray(rule));
+    }
+    catch {
+        return false;
+    }
+}
+/** Read `plan.policy.wipCap`; always returns an integer cap. */
+export function resolveWipCapInt(projectRoot) {
+    return resolveWipCap(projectRoot).cap;
+}
+// ---------------------------------------------------------------------------
+// compute / format / persist
+// ---------------------------------------------------------------------------
+export function computeSummary(projectRoot, options = {}) {
+    const root = pathResolve(projectRoot);
+    const resolvedCacheRoot = options.cacheRoot ?? join(root, CACHE_DIR_NAME);
+    const resolvedLogPath = options.auditLogPath ?? join(root, CANDIDATES_LOG_REL_PATH);
+    const cached = iterCachedIssues(resolvedCacheRoot);
+    const repos = [...new Set(cached.map(([repo]) => repo))].sort();
+    const wipCap = resolveWipCapInt(root);
+    const wipCount = countVbriefWip(root);
+    const inFlightFilesystem = countFilesystemInFlight(root);
+    const triageScopeConfigured = isTriageScopeExplicitlyConfigured(root);
+    if (cached.length === 0) {
+        return {
+            cacheEmpty: true,
+            untriaged: 0,
+            staleDefer: 0,
+            inFlight: inFlightFilesystem,
+            wipCount,
+            wipCap,
+            repos: repos.slice(0, 8),
+            scopeDrift: 0,
+            inFlightFilesystem,
+            inFlightCacheScoped: 0,
+            triageScopeConfigured,
+            reconcilable: 0,
+        };
+    }
+    const entries = readAuditLog(resolvedLogPath);
+    const decisions = latestDecisions(entries);
+    let untriaged = 0;
+    let inFlightCacheScoped = 0;
+    let staleDefer = 0;
+    const noDecisionKeys = [];
+    for (const [repo, issueNumber] of cached) {
+        const decision = decisions.get(decisionKey(repo, issueNumber));
+        if (decision === undefined || decision === "reset" || !TRIAGED_DECISIONS.has(decision)) {
+            untriaged += 1;
+        }
+        if (decision === undefined) {
+            noDecisionKeys.push([repo, issueNumber]);
+        }
+        else if (IN_FLIGHT_DECISIONS.has(decision)) {
+            inFlightCacheScoped += 1;
+        }
+        if (decision !== undefined && STALE_DEFER_DECISIONS.has(decision)) {
+            staleDefer += 1;
+        }
+    }
+    const scopeDrift = computeScopeDriftTotal(root, resolvedCacheRoot);
+    const repoSet = new Set(noDecisionKeys.map(([r]) => r));
+    const defaultRepo = repoSet.size === 1 ? ([...repoSet][0] ?? null) : null;
+    const reconcilable = countReconcilable(root, {
+        defaultRepo,
+        auditLogPath: resolvedLogPath,
+        restrictTo: noDecisionKeys,
+    });
+    return {
+        cacheEmpty: false,
+        untriaged,
+        staleDefer,
+        inFlight: inFlightFilesystem,
+        wipCount,
+        wipCap,
+        repos: repos.slice(0, 8),
+        scopeDrift,
+        inFlightFilesystem,
+        inFlightCacheScoped,
+        triageScopeConfigured,
+        reconcilable,
+    };
+}
+function truncate(text, maxChars) {
+    if (text.length <= maxChars) {
+        return text;
+    }
+    if (maxChars <= 3) {
+        return text.slice(0, maxChars);
+    }
+    return `${text.slice(0, maxChars - 3)}...`;
+}
+export function formatOneLiner(result, options = {}) {
+    const maxChars = options.maxChars ?? MAX_LINE_CHARS;
+    if (result.cacheEmpty) {
+        return truncate(EMPTY_CACHE_LINE, maxChars);
+    }
+    const parts = [`[triage] ${result.untriaged} untriaged`];
+    if (result.staleDefer >= 1) {
+        parts.push(`${result.staleDefer} stale-defer (resume condition met)`);
+    }
+    parts.push(`${result.inFlight} in-flight`);
+    let wipField = `WIP ${result.wipCount}/${result.wipCap}`;
+    if (result.wipCount >= result.wipCap) {
+        wipField = `${wipField} ${WIP_WARN_GLYPH}`;
+    }
+    parts.push(wipField);
+    if (result.scopeDrift > 0) {
+        parts.push(`[scope-drift] ${result.scopeDrift}`);
+    }
+    let candidate = parts.join(" \u00b7 ");
+    if (candidate.length <= maxChars) {
+        return candidate;
+    }
+    if (wipField.includes(WIP_WARN_GLYPH)) {
+        const wipFieldNoWarn = `WIP ${result.wipCount}/${result.wipCap}`;
+        const rebuilt = [...parts.slice(0, -1), wipFieldNoWarn];
+        candidate = rebuilt.join(" \u00b7 ");
+        if (candidate.length <= maxChars) {
+            return candidate;
+        }
+    }
+    if (result.staleDefer >= 1) {
+        candidate = [
+            parts[0],
+            `${result.inFlight} in-flight`,
+            `WIP ${result.wipCount}/${result.wipCap}`,
+        ].join(" \u00b7 ");
+        if (candidate.length <= maxChars) {
+            return candidate;
+        }
+    }
+    return truncate(candidate, maxChars);
+}
+export function formatScopeDiscrepancyLine(result) {
+    if (result.cacheEmpty) {
+        return null;
+    }
+    const delta = Math.abs(result.inFlightFilesystem - result.inFlightCacheScoped);
+    if (delta === 0) {
+        return null;
+    }
+    if (result.triageScopeConfigured) {
+        return (`[triage:scope] ${delta} in-flight outside ` +
+            "plan.policy.triageScope[] (uncounted in queue ranking)");
+    }
+    return (`[triage:scope] ${delta} in-flight; ` +
+        "plan.policy.triageScope[] not configured " +
+        "(uncounted in queue ranking)");
+}
+export function formatReconcileHintLine(result) {
+    if (result.cacheEmpty || result.reconcilable <= 0) {
+        return null;
+    }
+    return (`[triage:reconcile] ${result.reconcilable} accepted on disk but ` +
+        "missing from the audit log -- run `task triage:reconcile` to restore");
+}
+export function formatSummary(result, options = {}) {
+    const lines = [formatOneLiner(result, options)];
+    const scopeLine = formatScopeDiscrepancyLine(result);
+    if (scopeLine !== null) {
+        lines.push(scopeLine);
+    }
+    const reconcileLine = formatReconcileHintLine(result);
+    if (reconcileLine !== null) {
+        lines.push(reconcileLine);
+    }
+    return lines.join("\n");
+}
+export function summaryResultToRecord(result, options) {
+    return {
+        schema: SUMMARY_HISTORY_SCHEMA,
+        emitted_at: options.emittedAt,
+        line: options.line,
+        cache_empty: result.cacheEmpty,
+        untriaged: result.untriaged,
+        stale_defer: result.staleDefer,
+        in_flight: result.inFlight,
+        in_flight_filesystem: result.inFlightFilesystem,
+        in_flight_cache_scoped: result.inFlightCacheScoped,
+        triage_scope_configured: result.triageScopeConfigured,
+        wip_count: result.wipCount,
+        wip_cap: result.wipCap,
+        repos: [...result.repos],
+        scope_drift: result.scopeDrift,
+        reconcilable: result.reconcilable,
+    };
+}
+function sortKeysDeep(value) {
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(sortKeysDeep);
+    }
+    const obj = value;
+    const sorted = {};
+    for (const key of Object.keys(obj).sort()) {
+        sorted[key] = sortKeysDeep(obj[key]);
+    }
+    return sorted;
+}
+/** Match Python `json.dumps(..., sort_keys=True, ensure_ascii=False)` spacing. */
+export function pythonStyleStringify(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => pythonStyleStringify(v)).join(", ")}]`;
+    }
+    const obj = sortKeysDeep(value);
+    const pairs = Object.keys(obj).map((k) => `${JSON.stringify(k)}: ${pythonStyleStringify(obj[k])}`);
+    return `{${pairs.join(", ")}}`;
+}
+/** Append a single JSONL record to summary-history.jsonl. Never throws. */
+export function appendHistory(historyPath, result, line, options = {}) {
+    const record = summaryResultToRecord(result, {
+        emittedAt: options.emittedAt ?? utcIso(),
+        line,
+    });
+    const payload = pythonStyleStringify(record);
+    try {
+        mkdirSync(join(historyPath, ".."), { recursive: true });
+        appendFileSync(historyPath, `${payload}\n`, { encoding: "utf8" });
+    }
+    catch {
+        // observability only — never crash the ritual
+    }
+    return historyPath;
+}
+// Re-export loadProjectDefinition for tests that need PROJECT-DEFINITION helpers.
+export { loadProjectDefinition };
+//# sourceMappingURL=index.js.map

package/dist/triage/summary/reconcilable.d.ts

@@ -0,0 +1,12 @@
+/** Lifecycle folders scanned for reconcilable vBRIEFs (#1468). */
+export declare const BACKFILL_FOLDERS: readonly ["proposed", "pending", "active"];
+export declare const CANDIDATES_LOG_REL_PATH = "vbrief/.eval/candidates.jsonl";
+/**
+ * Count reconcilable issues (#1468) — mirrors `triage_reconcile.count_reconcilable`.
+ */
+export declare function countReconcilable(projectRoot: string, options?: {
+    defaultRepo?: string | null;
+    auditLogPath?: string;
+    restrictTo?: ReadonlyArray<readonly [string, number]>;
+}): number;
+//# sourceMappingURL=reconcilable.d.ts.map

package/dist/triage/summary/reconcilable.js

@@ -0,0 +1,150 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** Lifecycle folders scanned for reconcilable vBRIEFs (#1468). */
+export const BACKFILL_FOLDERS = ["proposed", "pending", "active"];
+export const CANDIDATES_LOG_REL_PATH = "vbrief/.eval/candidates.jsonl";
+function parseGithubIssueUri(uri) {
+    if (typeof uri !== "string" || uri.length === 0) {
+        return [null, null];
+    }
+    const match = /github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)/i.exec(uri);
+    if (match !== null) {
+        const owner = match[1];
+        const name = match[2];
+        const number = Number.parseInt(match[3] ?? "", 10);
+        if (owner !== undefined && name !== undefined && Number.isFinite(number)) {
+            return [`${owner}/${name}`, number];
+        }
+    }
+    const bare = /\/issues\/(\d+)/i.exec(uri);
+    if (bare !== null) {
+        const number = Number.parseInt(bare[1] ?? "", 10);
+        if (Number.isFinite(number)) {
+            return [null, number];
+        }
+    }
+    return [null, null];
+}
+function extractIssueRef(data) {
+    const refs = data["x-vbrief"];
+    if (!Array.isArray(refs)) {
+        return [null, null];
+    }
+    for (const ref of refs) {
+        if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
+            continue;
+        }
+        const obj = ref;
+        if (obj.type !== "x-vbrief/github-issue") {
+            continue;
+        }
+        const [repo, number] = parseGithubIssueUri(obj.uri);
+        if (number !== null) {
+            return [repo, number];
+        }
+    }
+    return [null, null];
+}
+function existingAuditRefs(auditPath) {
+    const seen = new Set();
+    if (!existsSync(auditPath)) {
+        return seen;
+    }
+    let text;
+    try {
+        text = readFileSync(auditPath, { encoding: "utf8" });
+    }
+    catch {
+        return seen;
+    }
+    for (const raw of text.split("\n")) {
+        const stripped = raw.trim();
+        if (stripped.length === 0) {
+            continue;
+        }
+        try {
+            const entry = JSON.parse(stripped);
+            if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+                continue;
+            }
+            const obj = entry;
+            const repo = obj.repo;
+            const issueNumber = obj.issue_number;
+            if (typeof repo === "string" &&
+                typeof issueNumber === "number" &&
+                Number.isInteger(issueNumber)) {
+                seen.add(`${repo}\0${issueNumber}`);
+            }
+        }
+        catch {
+            // tolerate malformed lines
+        }
+    }
+    return seen;
+}
+function auditKey(repo, issueNumber) {
+    return `${repo}\0${issueNumber}`;
+}
+/**
+ * Count reconcilable issues (#1468) — mirrors `triage_reconcile.count_reconcilable`.
+ */
+export function countReconcilable(projectRoot, options = {}) {
+    try {
+        const auditPath = options.auditLogPath ?? join(projectRoot, CANDIDATES_LOG_REL_PATH);
+        const existing = existingAuditRefs(auditPath);
+        const defaultRepo = options.defaultRepo ?? null;
+        const keys = new Set();
+        const vbriefRoot = join(projectRoot, "vbrief");
+        for (const folderName of BACKFILL_FOLDERS) {
+            const folder = join(vbriefRoot, folderName);
+            if (!existsSync(folder)) {
+                continue;
+            }
+            const entries = readdirSync(folder, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isFile() || !entry.name.endsWith(".vbrief.json")) {
+                    continue;
+                }
+                const path = join(folder, entry.name);
+                let data;
+                try {
+                    data = JSON.parse(readFileSync(path, { encoding: "utf8" }));
+                }
+                catch {
+                    continue;
+                }
+                if (typeof data !== "object" || data === null || Array.isArray(data)) {
+                    continue;
+                }
+                const [refRepo, number] = extractIssueRef(data);
+                if (number === null) {
+                    continue;
+                }
+                const effectiveRepo = refRepo ?? defaultRepo;
+                if (effectiveRepo === null) {
+                    continue;
+                }
+                const key = auditKey(effectiveRepo, number);
+                if (existing.has(key) || keys.has(key)) {
+                    continue;
+                }
+                keys.add(key);
+            }
+        }
+        if (options.restrictTo !== undefined) {
+            const restricted = new Set(options.restrictTo.map(([repo, n]) => auditKey(repo, n)));
+            let count = 0;
+            for (const key of keys) {
+                if (restricted.has(key)) {
+                    count += 1;
+                }
+            }
+            return count;
+        }
+        return keys.size;
+    }
+    catch {
+        return 0;
+    }
+}
+//# sourceMappingURL=reconcilable.js.map

package/dist/triage/summary/scope-drift.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Compute scope-drift total (#1133) — mirrors `triage_scope_drift.compute_drift().total`.
+ */
+export declare function computeScopeDriftTotal(projectRoot: string, cacheRoot: string): number;
+//# sourceMappingURL=scope-drift.d.ts.map