@deftai/directive-core 0.55.0

package/dist/triage/queue/render.js

@@ -0,0 +1,35 @@
+import { GROUP_DISPLAY } from "./constants.js";
+function truncate(text, width) {
+    if (width <= 1 || text.length <= width) {
+        return text;
+    }
+    return `${text.slice(0, width - 1)}...`;
+}
+/** Pretty-print the ranked queue. Mirrors scripts/triage_queue.py::render_queue. */
+export function renderQueue(options) {
+    const lines = [];
+    lines.push(`triage:queue -- ${options.repo}`);
+    const rankingLabels = options.rankingLabels ?? [];
+    if (rankingLabels.length > 0) {
+        lines.push(`  consumer ranking labels (in declared order): ${rankingLabels.join(", ")}`);
+    }
+    else {
+        lines.push("  consumer ranking labels: <empty> (framework default; within-group = updated_at desc)");
+    }
+    if (options.limit !== null && options.limit !== undefined) {
+        lines.push(`  limit: ${options.limit}`);
+    }
+    lines.push("");
+    if (options.items.length === 0) {
+        lines.push("  (no cached issues -- run `task triage:bootstrap` first)");
+        return lines.join("\n");
+    }
+    for (const item of options.items) {
+        const marker = GROUP_DISPLAY[item.group] ?? `[${item.group}] `;
+        const labelHint = item.matchedLabel !== null ? ` (label: ${item.matchedLabel})` : "";
+        const title = truncate(item.title, 72);
+        lines.push(`  ${marker}#${item.number}  ${title}  -- updated ${item.updatedAt}${labelHint}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=render.js.map

package/dist/triage/queue/repo.d.ts

@@ -0,0 +1,5 @@
+/** Best-effort: read git remote get-url origin inside projectRoot. */
+export declare function inferRepoFromGit(projectRoot: string | null): string | null;
+/** Resolve effective owner/name repo slug (#1238). */
+export declare function resolveRepo(explicit: string | null | undefined, projectRoot: string): string | null;
+//# sourceMappingURL=repo.d.ts.map

package/dist/triage/queue/repo.js

@@ -0,0 +1,36 @@
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+import { parseGitHubRemoteRepo } from "../../text/redos-safe.js";
+import { ENV_TRIAGE_REPO } from "./constants.js";
+/** Best-effort: read git remote get-url origin inside projectRoot. */
+export function inferRepoFromGit(projectRoot) {
+    const cwd = projectRoot !== null ? resolve(projectRoot) : undefined;
+    try {
+        const stdout = execFileSync("git", ["remote", "get-url", "origin"], {
+            cwd,
+            encoding: "utf8",
+            timeout: 10_000,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const url = stdout.trim();
+        if (url.length === 0) {
+            return null;
+        }
+        return parseGitHubRemoteRepo(url);
+    }
+    catch {
+        return null;
+    }
+}
+/** Resolve effective owner/name repo slug (#1238). */
+export function resolveRepo(explicit, projectRoot) {
+    if (explicit !== null && explicit !== undefined && explicit.trim().length > 0) {
+        return explicit.trim();
+    }
+    const envRepo = process.env[ENV_TRIAGE_REPO]?.trim() ?? "";
+    if (envRepo.length > 0) {
+        return envRepo;
+    }
+    return inferRepoFromGit(projectRoot);
+}
+//# sourceMappingURL=repo.js.map

package/dist/triage/queue/scope-walk.d.ts

@@ -0,0 +1,13 @@
+/** Extract issue numbers from a plan's x-vbrief/github-issue references. */
+export declare function issueNumbersFromPlan(plan: Record<string, unknown>): ReadonlySet<number>;
+/** Return plan.metadata.rank as an int, or null when absent/invalid. */
+export declare function scopeMetadataRank(plan: unknown): number | null;
+/** Return true when a scope is blocked (#1286). */
+export declare function scopeIsBlocked(plan: unknown, completedIds: ReadonlySet<string>): boolean;
+/** Issue numbers referenced by any vbrief/active/*.vbrief.json. */
+export declare function activeReferencedIssueNumbers(projectRoot: string): ReadonlySet<number>;
+/** Map referenced issue numbers to plan.metadata.rank. */
+export declare function rankByIssueNumber(projectRoot: string, folders?: readonly string[]): ReadonlyMap<number, number>;
+/** Map referenced issue numbers to blocked state (#1286). */
+export declare function blockedByIssueNumber(projectRoot: string, folders?: readonly string[]): ReadonlySet<number>;
+//# sourceMappingURL=scope-walk.d.ts.map

package/dist/triage/queue/scope-walk.js

@@ -0,0 +1,170 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+function loadPlan(path) {
+    try {
+        const data = JSON.parse(readFileSync(path, { encoding: "utf8" }));
+        if (typeof data !== "object" || data === null) {
+            return null;
+        }
+        const plan = data.plan;
+        return typeof plan === "object" && plan !== null ? plan : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Extract issue numbers from a plan's x-vbrief/github-issue references. */
+export function issueNumbersFromPlan(plan) {
+    const out = new Set();
+    const refs = plan.references;
+    if (!Array.isArray(refs)) {
+        return out;
+    }
+    for (const ref of refs) {
+        if (typeof ref !== "object" || ref === null) {
+            continue;
+        }
+        const typed = ref;
+        if (typed.type !== "x-vbrief/github-issue") {
+            continue;
+        }
+        const uri = typed.uri;
+        if (typeof uri !== "string") {
+            continue;
+        }
+        const tail = uri.replace(/\/+$/, "").split("/").pop() ?? "";
+        if (/^\d+$/.test(tail)) {
+            out.add(Number.parseInt(tail, 10));
+        }
+    }
+    return out;
+}
+/** Return plan.metadata.rank as an int, or null when absent/invalid. */
+export function scopeMetadataRank(plan) {
+    if (typeof plan !== "object" || plan === null) {
+        return null;
+    }
+    const metadata = plan.metadata;
+    if (typeof metadata !== "object" || metadata === null) {
+        return null;
+    }
+    const rank = metadata.rank;
+    if (typeof rank === "boolean") {
+        return null;
+    }
+    if (typeof rank === "number" && Number.isInteger(rank)) {
+        return rank;
+    }
+    if (typeof rank === "string") {
+        const trimmed = rank.trim();
+        if (/^-?\d+$/.test(trimmed)) {
+            return Number.parseInt(trimmed, 10);
+        }
+    }
+    return null;
+}
+function dependsOnIds(plan) {
+    const metadata = plan.metadata;
+    if (typeof metadata !== "object" || metadata === null) {
+        return [];
+    }
+    const swarm = metadata.swarm;
+    if (typeof swarm !== "object" || swarm === null) {
+        return [];
+    }
+    const raw = swarm.depends_on;
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw
+        .filter((dep) => typeof dep === "string" && dep.trim().length > 0)
+        .map((dep) => dep.trim());
+}
+function completedPlanIds(projectRoot) {
+    const out = new Set();
+    const base = join(resolve(projectRoot), "vbrief", "completed");
+    if (!existsSync(base)) {
+        return out;
+    }
+    for (const name of readdirSync(base).filter((entry) => entry.endsWith(".vbrief.json"))) {
+        const plan = loadPlan(join(base, name));
+        if (plan === null) {
+            continue;
+        }
+        const pid = plan.id;
+        if (typeof pid === "string" && pid.trim().length > 0) {
+            out.add(pid.trim());
+        }
+    }
+    return out;
+}
+/** Return true when a scope is blocked (#1286). */
+export function scopeIsBlocked(plan, completedIds) {
+    if (typeof plan !== "object" || plan === null) {
+        return false;
+    }
+    const typed = plan;
+    if (typed.status === "blocked") {
+        return true;
+    }
+    const deps = dependsOnIds(typed);
+    return deps.length > 0 && deps.some((dep) => !completedIds.has(dep));
+}
+function walkScopeFolders(projectRoot, folders, visitor) {
+    const base = join(resolve(projectRoot), "vbrief");
+    for (const folder of folders) {
+        const folderDir = join(base, folder);
+        if (!existsSync(folderDir)) {
+            continue;
+        }
+        for (const name of readdirSync(folderDir)
+            .filter((entry) => entry.endsWith(".vbrief.json"))
+            .sort()) {
+            const plan = loadPlan(join(folderDir, name));
+            if (plan !== null) {
+                visitor(plan, name);
+            }
+        }
+    }
+}
+/** Issue numbers referenced by any vbrief/active/*.vbrief.json. */
+export function activeReferencedIssueNumbers(projectRoot) {
+    const out = new Set();
+    walkScopeFolders(projectRoot, ["active"], (plan) => {
+        for (const n of issueNumbersFromPlan(plan)) {
+            out.add(n);
+        }
+    });
+    return out;
+}
+/** Map referenced issue numbers to plan.metadata.rank. */
+export function rankByIssueNumber(projectRoot, folders = ["pending", "active"]) {
+    const out = new Map();
+    walkScopeFolders(projectRoot, folders, (plan) => {
+        const rank = scopeMetadataRank(plan);
+        if (rank === null) {
+            return;
+        }
+        for (const n of issueNumbersFromPlan(plan)) {
+            if (!out.has(n)) {
+                out.set(n, rank);
+            }
+        }
+    });
+    return out;
+}
+/** Map referenced issue numbers to blocked state (#1286). */
+export function blockedByIssueNumber(projectRoot, folders = ["pending", "active"]) {
+    const out = new Set();
+    const completedIds = completedPlanIds(projectRoot);
+    walkScopeFolders(projectRoot, folders, (plan) => {
+        if (!scopeIsBlocked(plan, completedIds)) {
+            return;
+        }
+        for (const n of issueNumbersFromPlan(plan)) {
+            out.add(n);
+        }
+    });
+    return out;
+}
+//# sourceMappingURL=scope-walk.js.map

package/dist/triage/queue/selection.d.ts

@@ -0,0 +1,28 @@
+import type { CachedIssue } from "./types.js";
+export type DateSortKey = readonly [number, string];
+export type SelectionOrderingKey = readonly [
+    number,
+    number,
+    readonly [number, string],
+    number,
+    number,
+    DateSortKey
+];
+/** Within-group date tiebreak: created_at asc, else updated_at desc via complement. */
+export declare function dateSortKey(issue: CachedIssue): DateSortKey;
+/** Canonical RFC #1419 Layer-3 lexicographic selection key. */
+export declare function selectionOrderingKey(options: {
+    readonly labelIndex: number;
+    readonly isContinuation: boolean;
+    readonly continuationOrder?: string;
+    readonly bucketDeficit?: number | null;
+    readonly rank?: number | null;
+    readonly dateKey?: DateSortKey;
+}): SelectionOrderingKey;
+/** Intra-bucket sort key for a cached-issue row. */
+export declare function withinGroupSortKey(issue: CachedIssue, rankingLabels: readonly string[]): SelectionOrderingKey;
+/** Return the first ranking-label the issue matches, or null. */
+export declare function matchedLabelFor(issue: CachedIssue, rankingLabels: readonly string[]): string | null;
+/** Compare two selection keys lexicographically (ascending). */
+export declare function compareSelectionKeys(a: SelectionOrderingKey, b: SelectionOrderingKey): number;
+//# sourceMappingURL=selection.d.ts.map

package/dist/triage/queue/selection.js

@@ -0,0 +1,109 @@
+/** Within-group date tiebreak: created_at asc, else updated_at desc via complement. */
+export function dateSortKey(issue) {
+    const createdAt = issue.createdAt ?? "";
+    if (createdAt.length > 0) {
+        return [0, createdAt];
+    }
+    const updatedAt = issue.updatedAt ?? "";
+    if (updatedAt.length === 0) {
+        return [1, "\u0000"];
+    }
+    const inv = [...updatedAt]
+        .map((char) => {
+        const code = char.charCodeAt(0);
+        return String.fromCharCode(Math.max(0, 0x7f - code));
+    })
+        .join("");
+    return [1, inv];
+}
+/** Canonical RFC #1419 Layer-3 lexicographic selection key. */
+export function selectionOrderingKey(options) {
+    const continuationBucket = options.isContinuation ? 0 : 1;
+    let secondary;
+    if (options.isContinuation) {
+        const order = options.continuationOrder ?? "";
+        secondary = order.length > 0 ? [0, order] : [1, ""];
+    }
+    else if (typeof options.bucketDeficit === "number" && Number.isFinite(options.bucketDeficit)) {
+        secondary = [-options.bucketDeficit, ""];
+    }
+    else {
+        secondary = [0, ""];
+    }
+    let rankBucket;
+    let rankValue;
+    if (typeof options.rank === "number" && Number.isInteger(options.rank)) {
+        rankBucket = 0;
+        rankValue = options.rank;
+    }
+    else {
+        rankBucket = 1;
+        rankValue = 0;
+    }
+    return [
+        options.labelIndex,
+        continuationBucket,
+        secondary,
+        rankBucket,
+        rankValue,
+        options.dateKey ?? [1, ""],
+    ];
+}
+/** Intra-bucket sort key for a cached-issue row. */
+export function withinGroupSortKey(issue, rankingLabels) {
+    let rankIndex = rankingLabels.length;
+    if (rankingLabels.length > 0) {
+        const labels = issue.labels ?? [];
+        for (let i = 0; i < rankingLabels.length; i += 1) {
+            const candidate = rankingLabels[i];
+            if (candidate !== undefined && labels.includes(candidate)) {
+                rankIndex = i;
+                break;
+            }
+        }
+    }
+    const resolvedRank = issue._resolvedRank;
+    const rank = typeof resolvedRank === "number" && Number.isInteger(resolvedRank) ? resolvedRank : null;
+    return selectionOrderingKey({
+        labelIndex: rankIndex,
+        isContinuation: Boolean(issue._continuation),
+        continuationOrder: String(issue._continuationOrder ?? ""),
+        bucketDeficit: issue._bucketDeficit ?? null,
+        rank,
+        dateKey: dateSortKey(issue),
+    });
+}
+/** Return the first ranking-label the issue matches, or null. */
+export function matchedLabelFor(issue, rankingLabels) {
+    if (rankingLabels.length === 0) {
+        return null;
+    }
+    const labels = issue.labels ?? [];
+    for (const candidate of rankingLabels) {
+        if (labels.includes(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/** Compare two selection keys lexicographically (ascending). */
+export function compareSelectionKeys(a, b) {
+    for (let i = 0; i < a.length; i += 1) {
+        const left = a[i];
+        const right = b[i];
+        if (Array.isArray(left) && Array.isArray(right)) {
+            if (left[0] !== right[0]) {
+                return left[0] < right[0] ? -1 : 1;
+            }
+            if (left[1] !== right[1]) {
+                return left[1] < right[1] ? -1 : 1;
+            }
+            continue;
+        }
+        if (left !== right) {
+            return left < right ? -1 : 1;
+        }
+    }
+    return 0;
+}
+//# sourceMappingURL=selection.js.map

package/dist/triage/queue/types.d.ts

@@ -0,0 +1,58 @@
+import type { QueueGroup } from "./constants.js";
+/** One ranked row in buildQueue. */
+export interface QueueItem {
+    readonly number: number;
+    readonly title: string;
+    readonly state: string;
+    readonly labels: readonly string[];
+    readonly updatedAt: string;
+    readonly group: QueueGroup;
+    readonly latestDecision: string | null;
+    readonly matchedLabel: string | null;
+    readonly repo: string;
+}
+/** Bundled options for buildQueue. */
+export interface QueueBuildOptions {
+    readonly rankingLabels?: readonly string[];
+    readonly activeReferenced?: ReadonlySet<number>;
+    readonly orphanIssueNumbers?: ReadonlySet<number>;
+    readonly rankByNumber?: ReadonlyMap<number, number>;
+    readonly continuationNumbers?: ReadonlySet<number>;
+    readonly continuationOrderByNumber?: ReadonlyMap<number, string>;
+    readonly deficitByNumber?: ReadonlyMap<number, number>;
+    readonly finishBeforeStart?: boolean;
+    readonly wipAtCap?: boolean;
+    readonly blockedIssueNumbers?: ReadonlySet<number>;
+    readonly includeBlocked?: boolean;
+    readonly limit?: number | null;
+}
+/** Cached issue row produced by loadCachedIssues. */
+export interface CachedIssue {
+    readonly number: number;
+    readonly title: string;
+    readonly state: string;
+    readonly labels: readonly string[];
+    readonly updatedAt: string;
+    readonly createdAt: string;
+    readonly metadataRank: number | null;
+    readonly continuation: boolean;
+    readonly continuationOrder: string;
+    readonly bucketDeficit: number | null;
+    readonly blocked: boolean;
+    /** Mutable annotations stamped during buildQueue. */
+    _latestDecision?: string | null;
+    _blocked?: boolean;
+    _resolvedRank?: number | null;
+    _continuation?: boolean;
+    _continuationOrder?: string;
+    _bucketDeficit?: number | null;
+}
+/** Audit log entry shape (candidates.jsonl row). */
+export interface AuditEntry {
+    readonly timestamp?: string;
+    readonly repo?: string;
+    readonly issue_number?: number;
+    readonly decision?: string;
+    readonly [key: string]: unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/triage/queue/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/triage/reconcile/audit.d.ts

@@ -0,0 +1,4 @@
+export declare function scanLifecycleRefs(folder: string): Array<[string | null, number, string]>;
+export declare function existingAuditRefs(auditPath: string): Set<string>;
+export declare function auditKey(repo: string, issueNumber: number): string;
+//# sourceMappingURL=audit.d.ts.map

package/dist/triage/reconcile/audit.js

@@ -0,0 +1,62 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { extractIssueRef } from "./parse-uri.js";
+export function scanLifecycleRefs(folder) {
+    const results = [];
+    if (!existsSync(folder))
+        return results;
+    const files = readdirSync(folder)
+        .filter((name) => name.endsWith(".vbrief.json"))
+        .sort();
+    for (const name of files) {
+        const path = join(folder, name);
+        let data;
+        try {
+            data = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (typeof data !== "object" || data === null || Array.isArray(data))
+            continue;
+        const [repo, number] = extractIssueRef(data);
+        if (number === null)
+            continue;
+        results.push([repo, number, path]);
+    }
+    return results;
+}
+export function existingAuditRefs(auditPath) {
+    const seen = new Set();
+    if (!existsSync(auditPath))
+        return seen;
+    let text;
+    try {
+        text = readFileSync(auditPath, "utf8");
+    }
+    catch {
+        return seen;
+    }
+    for (const raw of text.split("\n")) {
+        const stripped = raw.trim();
+        if (!stripped)
+            continue;
+        try {
+            const entry = JSON.parse(stripped);
+            if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+                continue;
+            const rec = entry;
+            const repo = rec.repo;
+            const number = rec.issue_number;
+            if (typeof repo === "string" && typeof number === "number" && Number.isInteger(number)) {
+                seen.add(`${repo}:${number}`);
+            }
+        }
+        catch { }
+    }
+    return seen;
+}
+export function auditKey(repo, issueNumber) {
+    return `${repo}:${issueNumber}`;
+}
+//# sourceMappingURL=audit.js.map

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

@@ -0,0 +1,5 @@
+export { auditKey, existingAuditRefs, scanLifecycleRefs } from "./audit.js";
+export { extractIssueRef, parseGithubIssueUri } from "./parse-uri.js";
+export { countReconcilable, type FindReconcilableOptions, findReconcilable, inferRepoFromGit, type ReconcileOptions, reconcile, } from "./reconcile.js";
+export { AUDIT_LOG_RELPATH, BACKFILL_FOLDERS, emitReconcileJson, RECONCILE_ACTOR, type ReconcileItem, type ReconcileResult, reconcileSummary, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/triage/reconcile/index.js

@@ -0,0 +1,5 @@
+export { auditKey, existingAuditRefs, scanLifecycleRefs } from "./audit.js";
+export { extractIssueRef, parseGithubIssueUri } from "./parse-uri.js";
+export { countReconcilable, findReconcilable, inferRepoFromGit, reconcile, } from "./reconcile.js";
+export { AUDIT_LOG_RELPATH, BACKFILL_FOLDERS, emitReconcileJson, RECONCILE_ACTOR, reconcileSummary, } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/triage/reconcile/parse-uri.d.ts

@@ -0,0 +1,4 @@
+/** Parse (repo, issue_number) from a github-issue reference URI. */
+export declare function parseGithubIssueUri(uri: unknown): [string | null, number | null];
+export declare function extractIssueRef(data: Record<string, unknown>): [string | null, number | null];
+//# sourceMappingURL=parse-uri.d.ts.map

package/dist/triage/reconcile/parse-uri.js

@@ -0,0 +1,43 @@
+/** Parse (repo, issue_number) from a github-issue reference URI. */
+export function parseGithubIssueUri(uri) {
+    if (typeof uri !== "string")
+        return [null, null];
+    const cleaned = uri.trim().replace(/\/$/, "");
+    if (!cleaned)
+        return [null, null];
+    const noScheme = cleaned.includes("://") ? cleaned.split("://").slice(1).join("://") : cleaned;
+    const parts = noScheme.split("/").filter(Boolean);
+    if (parts.length >= 4 && parts[parts.length - 2] === "issues") {
+        const tail = parts[parts.length - 1] ?? "";
+        if (/^\d+$/.test(tail)) {
+            const owner = parts[parts.length - 4];
+            const repo = parts[parts.length - 3];
+            if (owner && repo)
+                return [`${owner}/${repo}`, Number(tail)];
+        }
+    }
+    const tail = parts[parts.length - 1] ?? "";
+    if (/^\d+$/.test(tail))
+        return [null, Number(tail)];
+    return [null, null];
+}
+export function extractIssueRef(data) {
+    const plan = data.plan;
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan))
+        return [null, null];
+    const refs = plan.references;
+    if (!Array.isArray(refs))
+        return [null, null];
+    for (const ref of refs) {
+        if (typeof ref !== "object" || ref === null || Array.isArray(ref))
+            continue;
+        const rec = ref;
+        if (rec.type !== "x-vbrief/github-issue")
+            continue;
+        const [repo, number] = parseGithubIssueUri(rec.uri);
+        if (number !== null)
+            return [repo, number];
+    }
+    return [null, null];
+}
+//# sourceMappingURL=parse-uri.js.map

package/dist/triage/reconcile/reconcile.d.ts

@@ -0,0 +1,17 @@
+import { type ReconcileItem, type ReconcileResult } from "./types.js";
+export declare function inferRepoFromGit(cwd: string): string | null;
+export interface FindReconcilableOptions {
+    readonly defaultRepo?: string | null;
+    readonly auditLogPath?: string;
+}
+export declare function findReconcilable(projectRoot: string, options?: FindReconcilableOptions): ReconcileItem[];
+export interface ReconcileOptions {
+    readonly repo?: string | null;
+    readonly auditLogPath?: string;
+    readonly dryRun?: boolean;
+}
+export declare function reconcile(projectRoot: string, options?: ReconcileOptions): ReconcileResult;
+export declare function countReconcilable(projectRoot: string, options?: FindReconcilableOptions & {
+    readonly restrictTo?: Iterable<[string, number]>;
+}): number;
+//# sourceMappingURL=reconcile.d.ts.map