@deftai/directive-core 0.55.0

package/dist/triage/subscribe/index.js

@@ -0,0 +1,303 @@
+import { randomUUID } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { basename, join, resolve } from "node:path";
+export const SUBSCRIPTION_HISTORY_REL_PATH = "vbrief/.eval/subscription-history.jsonl";
+export const SUBSCRIPTION_HISTORY_SCHEMA = "deft.triage.subscription-change.v1";
+export const PROJECT_DEFINITION_REL_PATH = "vbrief/PROJECT-DEFINITION.vbrief.json";
+/** Python ``!r``-style quoting for parity with triage_subscribe.py messages. */
+export function pyRepr(value) {
+    return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+}
+export class ProjectDefinitionIOError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ProjectDefinitionIOError";
+    }
+}
+function projectDefinitionPath(projectRoot) {
+    return join(resolve(projectRoot), PROJECT_DEFINITION_REL_PATH);
+}
+export function loadProjectDefinitionForMutation(projectRoot) {
+    const path = projectDefinitionPath(projectRoot);
+    if (!existsSync(path)) {
+        throw new ProjectDefinitionIOError(`PROJECT-DEFINITION not found at ${path}; run task triage:welcome / ` +
+            "task triage:bootstrap to scaffold one first.");
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, { encoding: "utf8" });
+    }
+    catch (exc) {
+        throw new ProjectDefinitionIOError(`Could not read PROJECT-DEFINITION at ${path}: ${String(exc)}`);
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (exc) {
+        throw new ProjectDefinitionIOError(`PROJECT-DEFINITION at ${path} is not valid JSON: ${String(exc)}`);
+    }
+    if (typeof data !== "object" || data === null || Array.isArray(data)) {
+        throw new ProjectDefinitionIOError(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
+    }
+    return [data, path];
+}
+export function atomicWriteProjectDefinition(path, data) {
+    const parent = join(path, "..");
+    mkdirSync(parent, { recursive: true });
+    const payload = JSON.stringify(data, null, 2);
+    const tmpName = join(parent, `${basename(path)}.${process.pid}.${Date.now()}.tmp`);
+    try {
+        writeFileSync(tmpName, payload.endsWith("\n") ? payload : `${payload}\n`, {
+            encoding: "utf8",
+        });
+        renameSync(tmpName, path);
+    }
+    catch (exc) {
+        try {
+            unlinkSync(tmpName);
+        }
+        catch {
+            // ignore
+        }
+        throw exc;
+    }
+}
+function snapshotRules(rules) {
+    return JSON.parse(JSON.stringify(rules));
+}
+function utcIso(dt) {
+    const d = dt ?? new Date();
+    return d.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function resolveActor(actor) {
+    if (typeof actor === "string" && actor.trim().length > 0) {
+        return actor;
+    }
+    const envActor = process.env.DEFT_TRIAGE_ACTOR;
+    if (typeof envActor === "string" && envActor.trim().length > 0) {
+        return envActor;
+    }
+    try {
+        const user = process.env.USER ?? process.env.USERNAME ?? "unknown";
+        return `user:${user}`;
+    }
+    catch {
+        return "user:unknown";
+    }
+}
+export function recordSubscriptionChange(projectRoot, options) {
+    const historyPath = join(resolve(projectRoot), SUBSCRIPTION_HISTORY_REL_PATH);
+    const record = {
+        schema: SUBSCRIPTION_HISTORY_SCHEMA,
+        change_id: randomUUID(),
+        timestamp: utcIso(),
+        actor: resolveActor(options.actor),
+        op: options.op,
+        label: options.label ?? null,
+        milestone: options.milestone ?? null,
+        issue: options.issue ?? null,
+        author: options.author ?? null,
+        before: options.before ?? [],
+        after: options.after ?? [],
+    };
+    if (options.extra !== null && options.extra !== undefined) {
+        record.extra = options.extra;
+    }
+    const sortedRecord = Object.fromEntries(Object.keys(record)
+        .sort()
+        .map((k) => [k, record[k]]));
+    const line = JSON.stringify(sortedRecord);
+    try {
+        mkdirSync(join(historyPath, ".."), { recursive: true });
+        appendFileSync(historyPath, `${line}\n`, { encoding: "utf8" });
+    }
+    catch {
+        // observability only
+    }
+}
+function applySubscribe(rules, label, milestone, issue, issueNote) {
+    if (label !== null && label !== undefined) {
+        for (const rule of rules) {
+            if (typeof rule === "object" &&
+                rule !== null &&
+                rule.rule === "labels" &&
+                Array.isArray(rule["any-of"])) {
+                const anyOf = rule["any-of"];
+                if (anyOf.includes(label)) {
+                    return [false, `already-subscribed (labels.any-of contains ${pyRepr(label)})`];
+                }
+                anyOf.push(label);
+                return [true, `added ${pyRepr(label)} to existing labels.any-of`];
+            }
+        }
+        rules.push({ rule: "labels", "any-of": [label] });
+        return [true, `created new labels.any-of rule for ${pyRepr(label)}`];
+    }
+    if (milestone !== null && milestone !== undefined) {
+        for (const rule of rules) {
+            if (typeof rule === "object" &&
+                rule !== null &&
+                rule.rule === "milestone" &&
+                rule.name === milestone) {
+                return [false, `already-subscribed (milestone ${pyRepr(milestone)})`];
+            }
+        }
+        rules.push({ rule: "milestone", name: milestone });
+        return [true, `added milestone rule for ${pyRepr(milestone)}`];
+    }
+    if (issue !== null && issue !== undefined) {
+        for (const rule of rules) {
+            if (typeof rule === "object" &&
+                rule !== null &&
+                rule.rule === "explicit-watch" &&
+                Array.isArray(rule.issues)) {
+                const issues = rule.issues;
+                if (issues.some((e) => e.n === issue)) {
+                    return [false, `already-subscribed (explicit-watch issue #${issue})`];
+                }
+                issues.push({ n: issue, note: issueNote });
+                return [true, `added #${issue} to existing explicit-watch`];
+            }
+        }
+        rules.push({
+            rule: "explicit-watch",
+            issues: [{ n: issue, note: issueNote }],
+        });
+        return [true, `created new explicit-watch rule for #${issue}`];
+    }
+    return [false, "no-op"];
+}
+function applyUnsubscribe(rules, label, milestone, issue) {
+    if (label !== null && label !== undefined) {
+        for (let i = 0; i < rules.length; i += 1) {
+            const rule = rules[i];
+            if (rule === undefined)
+                continue;
+            if (typeof rule !== "object" || rule === null || rule.rule !== "labels") {
+                continue;
+            }
+            for (const key of ["any-of", "all-of"]) {
+                const items = rule[key];
+                if (Array.isArray(items) && items.includes(label)) {
+                    const idx = items.indexOf(label);
+                    items.splice(idx, 1);
+                    if (items.length === 0) {
+                        rules.splice(i, 1);
+                    }
+                    return [true, `removed ${pyRepr(label)} from labels.${key}`];
+                }
+            }
+        }
+        return [false, `not-subscribed (no labels rule mentions ${pyRepr(label)})`];
+    }
+    if (milestone !== null && milestone !== undefined) {
+        for (let i = 0; i < rules.length; i += 1) {
+            const rule = rules[i];
+            if (rule === undefined)
+                continue;
+            if (typeof rule === "object" &&
+                rule !== null &&
+                rule.rule === "milestone" &&
+                rule.name === milestone) {
+                rules.splice(i, 1);
+                return [true, `removed milestone rule for ${pyRepr(milestone)}`];
+            }
+        }
+        return [false, `not-subscribed (no milestone rule for ${pyRepr(milestone)})`];
+    }
+    if (issue !== null && issue !== undefined) {
+        for (let i = 0; i < rules.length; i += 1) {
+            const rule = rules[i];
+            if (rule === undefined)
+                continue;
+            if (typeof rule !== "object" || rule === null || rule.rule !== "explicit-watch") {
+                continue;
+            }
+            const items = rule.issues;
+            if (!Array.isArray(items)) {
+                continue;
+            }
+            const newItems = items.filter((e) => !(typeof e === "object" && e !== null && e.n === issue));
+            if (newItems.length !== items.length) {
+                if (newItems.length === 0) {
+                    rules.splice(i, 1);
+                }
+                else {
+                    rule.issues = newItems;
+                }
+                return [true, `removed #${issue} from explicit-watch`];
+            }
+        }
+        return [false, `not-subscribed (no explicit-watch entry for #${issue})`];
+    }
+    return [false, "no-op"];
+}
+function mutate(projectRoot, options) {
+    const chosen = [
+        ["label", options.label],
+        ["milestone", options.milestone],
+        ["issue", options.issue],
+    ]
+        .filter(([, val]) => val !== null && val !== undefined)
+        .map(([name]) => name);
+    if (chosen.length !== 1) {
+        throw new Error(`${options.op}() requires exactly one of --label / --milestone / --issue; got ${JSON.stringify(chosen)}`);
+    }
+    const [data, path] = loadProjectDefinitionForMutation(projectRoot);
+    if (typeof data.plan !== "object" || data.plan === null || Array.isArray(data.plan)) {
+        throw new Error(`PROJECT-DEFINITION at ${path} has a non-object 'plan' key`);
+    }
+    const plan = data.plan;
+    if (typeof plan.policy !== "object" || plan.policy === null || Array.isArray(plan.policy)) {
+        if (plan.policy === undefined) {
+            plan.policy = {};
+        }
+        else {
+            throw new Error(`PROJECT-DEFINITION at ${path} has a non-object 'plan.policy' key`);
+        }
+    }
+    const policy = plan.policy;
+    if (!Array.isArray(policy.triageScope)) {
+        if (policy.triageScope === undefined) {
+            policy.triageScope = [];
+        }
+        else {
+            throw new Error(`PROJECT-DEFINITION at ${path} has a non-list 'plan.policy.triageScope'`);
+        }
+    }
+    const rules = policy.triageScope;
+    const before = snapshotRules(rules);
+    let changed;
+    let message;
+    if (options.op === "subscribe") {
+        [changed, message] = applySubscribe(rules, options.label, options.milestone, options.issue, options.issueNote ?? "added via task triage:subscribe");
+    }
+    else {
+        [changed, message] = applyUnsubscribe(rules, options.label, options.milestone, options.issue);
+    }
+    if (!changed) {
+        return [false, message];
+    }
+    atomicWriteProjectDefinition(path, data);
+    const after = snapshotRules(rules);
+    recordSubscriptionChange(projectRoot, {
+        op: options.op,
+        label: options.label,
+        milestone: options.milestone,
+        issue: options.issue,
+        before,
+        after,
+        actor: options.actor,
+    });
+    return [true, message];
+}
+export function subscribe(projectRoot, options = {}) {
+    return mutate(projectRoot, { op: "subscribe", ...options });
+}
+export function unsubscribe(projectRoot, options = {}) {
+    return mutate(projectRoot, { op: "unsubscribe", ...options });
+}
+export const RECONCILE_HINT = "  Reconciliation: run `task triage:bootstrap -- --resume` to " +
+    "backfill / mark out-of-scope cached entries.";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,70 @@
+import { loadProjectDefinition, PROJECT_DEFINITION_REL_PATH } from "../../policy/resolve.js";
+import { DEFAULT_WIP_CAP } from "../../policy/wip.js";
+export declare const MAX_LINE_CHARS = 120;
+export { DEFAULT_WIP_CAP, PROJECT_DEFINITION_REL_PATH };
+export declare const CACHE_DIR_NAME = ".deft-cache";
+export declare const CACHE_SOURCE = "github-issue";
+export declare const CANDIDATES_LOG_REL_PATH = "vbrief/.eval/candidates.jsonl";
+export declare const SUMMARY_HISTORY_REL_PATH = "vbrief/.eval/summary-history.jsonl";
+export declare const SUMMARY_HISTORY_SCHEMA = "deft.triage.summary.v1";
+export declare const EMPTY_CACHE_LINE = "[triage] cache empty -- run task triage:bootstrap";
+export declare const WIP_LIFECYCLE_DIRS: readonly ["pending", "active"];
+export declare const FILESYSTEM_IN_FLIGHT_FOLDER = "active";
+export declare const FILESYSTEM_IN_FLIGHT_STATUS = "running";
+export declare const WIP_WARN_GLYPH = "\u26A0";
+export declare const IN_FLIGHT_DECISIONS: Set<string>;
+export declare const TRIAGED_DECISIONS: Set<string>;
+export declare const STALE_DEFER_DECISIONS: Set<string>;
+export interface SummaryResult {
+    readonly cacheEmpty: boolean;
+    readonly untriaged: number;
+    readonly staleDefer: number;
+    readonly inFlight: number;
+    readonly wipCount: number;
+    readonly wipCap: number;
+    readonly repos: readonly string[];
+    readonly scopeDrift: number;
+    readonly inFlightFilesystem: number;
+    readonly inFlightCacheScoped: number;
+    readonly triageScopeConfigured: boolean;
+    readonly reconcilable: number;
+}
+export interface ComputeSummaryOptions {
+    readonly cacheRoot?: string;
+    readonly auditLogPath?: string;
+}
+/** ISO-8601 UTC with explicit `Z` suffix. */
+export declare function utcIso(date?: Date): string;
+export declare function isPosIntDirName(name: string): boolean;
+/** Walk `<cache_root>/github-issue/<owner>/<repo>/<N>/` cache entries. */
+export declare function iterCachedIssues(cacheRoot: string): Array<[string, number]>;
+export declare function readAuditLog(logPath: string): Record<string, unknown>[];
+/** Collapse audit-log entries to `{(repo, issue_number): decision}`. */
+export declare function latestDecisions(entries: Iterable<Record<string, unknown>>): Map<string, string>;
+/** Count filesystem-truth in-flight vBRIEFs (#1270). */
+export declare function countFilesystemInFlight(projectRoot: string): number;
+/** True iff `plan.policy.triageScope` is a non-empty list of dict rules. */
+export declare function isTriageScopeExplicitlyConfigured(projectRoot: string): boolean;
+/** Read `plan.policy.wipCap`; always returns an integer cap. */
+export declare function resolveWipCapInt(projectRoot: string): number;
+export declare function computeSummary(projectRoot: string, options?: ComputeSummaryOptions): SummaryResult;
+export declare function formatOneLiner(result: SummaryResult, options?: {
+    maxChars?: number;
+}): string;
+export declare function formatScopeDiscrepancyLine(result: SummaryResult): string | null;
+export declare function formatReconcileHintLine(result: SummaryResult): string | null;
+export declare function formatSummary(result: SummaryResult, options?: {
+    maxChars?: number;
+}): string;
+export declare function summaryResultToRecord(result: SummaryResult, options: {
+    emittedAt: string;
+    line: string;
+}): Record<string, unknown>;
+/** Match Python `json.dumps(..., sort_keys=True, ensure_ascii=False)` spacing. */
+export declare function pythonStyleStringify(value: unknown): string;
+/** Append a single JSONL record to summary-history.jsonl. Never throws. */
+export declare function appendHistory(historyPath: string, result: SummaryResult, line: string, options?: {
+    emittedAt?: string;
+}): string;
+export { loadProjectDefinition };
+//# sourceMappingURL=index.d.ts.map