@deftai/directive-core 0.94.0 → 0.95.0

package/dist/triage/classify/label-mirror.js

@@ -0,0 +1,684 @@
+/**
+ * Tier-1 deterministic SCM label mirror (#1423 Wave 1).
+ *
+ * Classifies cached issues with the existing #1129 engine, then mirrors the
+ * outcome as SCM labels (dry-run default, --apply to write). Never accepts into
+ * the xBRIEF lifecycle and never writes proposed/ scopes.
+ *
+ * Intentionally does NOT import from ./index.js (SLizard P1 cycle). The classify
+ * engine is injected via LabelMirrorEngine / mirrorLabels() wrapper in index.ts.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { referenceTypeMatches } from "@deftai/directive-types";
+import { hasArtifactSuffix, resolveLifecycleRoot, resolveProjectDefinitionPath, } from "../../layout/resolve.js";
+import { readPlanPolicy } from "../../policy/plan-extensions.js";
+import { ScmLabelClient } from "../../vbrief-reconcile/labels.js";
+import { isRepoMutationAllowed } from "../../vbrief-reconcile/repo-guard.js";
+import { latestDecisions, readAuditLog } from "../actions/candidates-log.js";
+import { resolveCandidatesLogPath } from "../cache-path.js";
+import { iterCachedIssues } from "../summary/index.js";
+export const DEFAULT_IDEMPOTENCY_LABEL = "triaged";
+export const CACHE_DIR_NAME = ".deft-cache";
+export const CACHE_SOURCE = "github-issue";
+const VALID_ACTIONS = new Set(["defer", "archive", "escalate", "accept"]);
+/**
+ * Repo-qualified xBRIEF github-issue keys (`owner/name\\0number`).
+ * Unlike number-only extractReferencedIssues, this never collides across repos.
+ */
+export function extractReferencedRepoIssueKeys(projectRoot, lifecycleFolders = ["pending", "active"]) {
+    const referenced = new Set();
+    let root;
+    try {
+        root = resolveLifecycleRoot(projectRoot ?? process.cwd());
+    }
+    catch {
+        return referenced;
+    }
+    for (const folder of lifecycleFolders) {
+        const folderPath = join(root, folder);
+        let entries;
+        try {
+            entries = readdirSync(folderPath).filter((f) => hasArtifactSuffix(f));
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            try {
+                const raw = readFileSync(join(folderPath, name), { encoding: "utf8" });
+                const data = JSON.parse(raw);
+                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 refs = plan.references ?? [];
+                if (!Array.isArray(refs)) {
+                    continue;
+                }
+                for (const ref of refs) {
+                    if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
+                        continue;
+                    }
+                    const r = ref;
+                    if (!referenceTypeMatches(String(r.type ?? ""), "github-issue")) {
+                        continue;
+                    }
+                    const uri = r.uri;
+                    if (typeof uri !== "string") {
+                        continue;
+                    }
+                    const cleaned = uri.trim().replace(/\/+$/, "");
+                    const parts = cleaned
+                        .split("://")
+                        .pop()
+                        ?.split("/")
+                        .filter((p) => p.length > 0) ?? [];
+                    if (parts.length >= 4 &&
+                        parts[parts.length - 2] === "issues" &&
+                        /^\d+$/.test(parts[parts.length - 1] ?? "")) {
+                        const owner = parts[parts.length - 4] ?? "";
+                        const repoName = parts[parts.length - 3] ?? "";
+                        const n = Number.parseInt(parts[parts.length - 1] ?? "", 10);
+                        if (owner.length > 0 && repoName.length > 0 && Number.isFinite(n)) {
+                            referenced.add(`${owner}/${repoName}\0${n}`.toLowerCase());
+                        }
+                    }
+                }
+            }
+            catch {
+                // tolerate corrupt artifacts
+            }
+        }
+    }
+    return referenced;
+}
+function asStringList(value) {
+    if (!Array.isArray(value)) {
+        return null;
+    }
+    const out = [];
+    for (const item of value) {
+        if (typeof item !== "string" || item.trim().length === 0) {
+            return null;
+        }
+        out.push(item);
+    }
+    return out;
+}
+function sanitizeReportFragment(value) {
+    return value.replace(/\r?\n/g, " ");
+}
+/** Validate plan.policy.triageLabelMirror payload. */
+export function validateLabelMirrorPolicy(raw) {
+    const errors = [];
+    const warnings = [];
+    if (raw === undefined || raw === null) {
+        return { errors, warnings };
+    }
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        errors.push("plan.policy.triageLabelMirror must be an object");
+        return { errors, warnings };
+    }
+    const obj = raw;
+    if ("enabled" in obj && typeof obj.enabled !== "boolean") {
+        errors.push("plan.policy.triageLabelMirror.enabled must be a boolean when set");
+    }
+    if ("idempotencyLabel" in obj) {
+        if (typeof obj.idempotencyLabel !== "string" || obj.idempotencyLabel.trim().length === 0) {
+            errors.push("plan.policy.triageLabelMirror.idempotencyLabel must be a non-empty string");
+        }
+    }
+    if ("alwaysLabels" in obj) {
+        const list = asStringList(obj.alwaysLabels);
+        if (list === null) {
+            errors.push("plan.policy.triageLabelMirror.alwaysLabels must be a list of non-empty strings");
+        }
+    }
+    if ("actionLabels" in obj) {
+        const al = obj.actionLabels;
+        if (typeof al !== "object" || al === null || Array.isArray(al)) {
+            errors.push("plan.policy.triageLabelMirror.actionLabels must be an object");
+        }
+        else {
+            for (const [key, value] of Object.entries(al)) {
+                if (!VALID_ACTIONS.has(key)) {
+                    errors.push(`plan.policy.triageLabelMirror.actionLabels.${key}: action must be one of ${[...VALID_ACTIONS].sort().join(", ")}`);
+                    continue;
+                }
+                const list = asStringList(value);
+                if (list === null) {
+                    errors.push(`plan.policy.triageLabelMirror.actionLabels.${key} must be a list of non-empty strings`);
+                }
+            }
+        }
+    }
+    const known = new Set(["enabled", "idempotencyLabel", "alwaysLabels", "actionLabels"]);
+    const extra = Object.keys(obj)
+        .filter((k) => !known.has(k))
+        .sort();
+    if (extra.length > 0) {
+        warnings.push(`plan.policy.triageLabelMirror: ignoring unrecognised key(s) ${extra.join(", ")}`);
+    }
+    return { errors, warnings };
+}
+/** Default resolved policy when triageLabelMirror is absent. */
+export function defaultLabelMirrorPolicy() {
+    return {
+        enabled: true,
+        idempotencyLabel: DEFAULT_IDEMPOTENCY_LABEL,
+        alwaysLabels: [DEFAULT_IDEMPOTENCY_LABEL],
+        actionLabels: {},
+    };
+}
+function loadProjectDefinition(projectRoot) {
+    let path;
+    try {
+        path = resolveProjectDefinitionPath(projectRoot);
+    }
+    catch {
+        path = join(projectRoot, "xbrief", "PROJECT-DEFINITION.xbrief.json");
+    }
+    try {
+        const raw = readFileSync(path, { encoding: "utf8" });
+        const data = JSON.parse(raw);
+        return typeof data === "object" && data !== null && !Array.isArray(data)
+            ? data
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Resolve effective label-mirror policy from PROJECT-DEFINITION or inline object. */
+export function resolveLabelMirrorPolicy(options) {
+    if (options?.override !== undefined && options.override !== null) {
+        return materializePolicy(options.override);
+    }
+    const data = options?.projectDefinition !== undefined
+        ? options.projectDefinition
+        : loadProjectDefinition(options?.projectRoot ?? process.cwd());
+    if (data === null) {
+        return defaultLabelMirrorPolicy();
+    }
+    const plan = data.plan;
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+        return defaultLabelMirrorPolicy();
+    }
+    const policy = readPlanPolicy(plan);
+    if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
+        return defaultLabelMirrorPolicy();
+    }
+    const raw = policy.triageLabelMirror;
+    if (raw === undefined || raw === null) {
+        return defaultLabelMirrorPolicy();
+    }
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        return defaultLabelMirrorPolicy();
+    }
+    return materializePolicy(raw);
+}
+function materializePolicy(raw) {
+    const idempotencyLabel = typeof raw.idempotencyLabel === "string" && raw.idempotencyLabel.trim().length > 0
+        ? raw.idempotencyLabel.trim()
+        : DEFAULT_IDEMPOTENCY_LABEL;
+    const alwaysFromPolicy = asStringList(raw.alwaysLabels ?? null);
+    const alwaysLabels = alwaysFromPolicy !== null ? alwaysFromPolicy : [idempotencyLabel].filter((x) => x.length > 0);
+    const actionLabels = {};
+    const al = raw.actionLabels;
+    if (typeof al === "object" && al !== null && !Array.isArray(al)) {
+        for (const action of VALID_ACTIONS) {
+            const list = asStringList(al[action]);
+            if (list !== null && list.length > 0) {
+                actionLabels[action] = list;
+            }
+        }
+    }
+    return {
+        enabled: raw.enabled !== false,
+        idempotencyLabel,
+        alwaysLabels,
+        actionLabels,
+    };
+}
+/** Labels to apply for a classified action (always + action-mapped). */
+export function desiredLabelsForClassification(action, policy) {
+    const desired = new Set(policy.alwaysLabels);
+    const mapped = policy.actionLabels[action];
+    if (mapped !== undefined) {
+        for (const label of mapped) {
+            desired.add(label);
+        }
+    }
+    // Always include the idempotency marker even if alwaysLabels was customized empty.
+    if (policy.idempotencyLabel.length > 0) {
+        desired.add(policy.idempotencyLabel);
+    }
+    return [...desired].sort();
+}
+function issueLabelNames(issue) {
+    const raw = issue.labels ?? [];
+    const names = [];
+    if (!Array.isArray(raw)) {
+        return names;
+    }
+    for (const item of raw) {
+        if (typeof item === "object" && item !== null && "name" in item) {
+            const name = item.name;
+            if (typeof name === "string" && name.length > 0) {
+                names.push(name);
+            }
+        }
+        else if (typeof item === "string" && item.length > 0) {
+            names.push(item);
+        }
+    }
+    return names;
+}
+function readCachedRawIssue(cacheRoot, repo, issueNumber) {
+    const [owner, name] = repo.split("/", 2);
+    const rawPath = join(cacheRoot, CACHE_SOURCE, owner ?? "", name ?? "", String(issueNumber), "raw.json");
+    if (!existsSync(rawPath)) {
+        return null;
+    }
+    try {
+        const data = JSON.parse(readFileSync(rawPath, { encoding: "utf8" }));
+        if (typeof data !== "object" || data === null || Array.isArray(data)) {
+            return null;
+        }
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+/** Load latest decisions as Map keyed by `repo\0number` for hasTriageDecision. */
+function loadLatestDecisionMap(projectRoot) {
+    try {
+        const path = resolveCandidatesLogPath(projectRoot);
+        return latestDecisions(readAuditLog(path));
+    }
+    catch {
+        return new Map();
+    }
+}
+function decisionMapHas(map, repo, issueNumber) {
+    return map.has(`${repo}\0${issueNumber}`);
+}
+/**
+ * Run Tier-1 label mirror over the github-issue cache.
+ * Dry-run by default (no SCM writes). Pass dryRun: false to apply.
+ * Requires options.engine (classify/index wrapper injects it).
+ */
+export function mirrorLabels(projectRoot, options) {
+    const root = resolve(projectRoot);
+    const dryRun = options.dryRun ?? true;
+    const policy = resolveLabelMirrorPolicy({ projectRoot: root });
+    const cacheRoot = options.cacheRoot ?? join(root, CACHE_DIR_NAME);
+    const useLiveLabels = options.useLiveLabels ?? !dryRun;
+    const client = options.client ?? (useLiveLabels || !dryRun ? new ScmLabelClient() : undefined);
+    const engine = options.engine;
+    const items = [];
+    const outcomeBase = {
+        project_root: root,
+        dry_run: dryRun,
+        policy,
+    };
+    if (!policy.enabled) {
+        return [
+            0,
+            {
+                ...outcomeBase,
+                scanned: 0,
+                planned: 0,
+                applied: 0,
+                unchanged: 0,
+                skipped_already_triaged: 0,
+                skipped_no_match: 0,
+                skipped_unreadable: 0,
+                errors: 0,
+                items: [
+                    {
+                        repo: "",
+                        issue_number: 0,
+                        action: null,
+                        reason: null,
+                        ruleKind: null,
+                        current: [],
+                        desired: [],
+                        add: [],
+                        status: "skipped_disabled",
+                        message: "plan.policy.triageLabelMirror.enabled is false",
+                    },
+                ],
+            },
+        ];
+    }
+    const rules = engine.resolveClassifyRules({ projectRoot: root });
+    const holdMarkers = engine.resolveHoldMarkers({ projectRoot: root });
+    // Repo-qualified xBRIEF keys avoid number-only collisions across multi-repo
+    // caches and do not require project identity (#1423 Greptile P1 class).
+    const referencedKeys = extractReferencedRepoIssueKeys(root);
+    const decisions = loadLatestDecisionMap(root);
+    const now = options.now ?? new Date();
+    let pairs = iterCachedIssues(cacheRoot);
+    if (options.repo !== undefined && options.repo !== null && options.repo.trim().length > 0) {
+        const want = options.repo.trim().toLowerCase();
+        pairs = pairs.filter(([repo]) => repo.toLowerCase() === want);
+    }
+    let planned = 0;
+    let applied = 0;
+    let unchanged = 0;
+    let skippedAlready = 0;
+    let skippedNoMatch = 0;
+    let skippedUnreadable = 0;
+    let errors = 0;
+    for (const [repo, issueNumber] of pairs) {
+        const issue = readCachedRawIssue(cacheRoot, repo, issueNumber);
+        if (issue === null) {
+            skippedUnreadable += 1;
+            items.push({
+                repo,
+                issue_number: issueNumber,
+                action: null,
+                reason: null,
+                ruleKind: null,
+                current: [],
+                desired: [],
+                add: [],
+                status: "skipped_unreadable",
+                message: "missing or unreadable raw.json",
+            });
+            continue;
+        }
+        let current;
+        if (useLiveLabels && client !== undefined) {
+            try {
+                current = client.fetchLabels(repo, issueNumber);
+            }
+            catch (exc) {
+                current = issueLabelNames(issue);
+                if (!dryRun) {
+                    errors += 1;
+                    items.push({
+                        repo,
+                        issue_number: issueNumber,
+                        action: null,
+                        reason: null,
+                        ruleKind: null,
+                        current,
+                        desired: [],
+                        add: [],
+                        status: "error",
+                        message: `fetchLabels failed: ${exc instanceof Error ? exc.message : String(exc)}`,
+                    });
+                    continue;
+                }
+            }
+        }
+        else {
+            current = issueLabelNames(issue);
+        }
+        if (current.includes(policy.idempotencyLabel)) {
+            skippedAlready += 1;
+            items.push({
+                repo,
+                issue_number: issueNumber,
+                action: null,
+                reason: null,
+                ruleKind: null,
+                current: [...current].sort(),
+                desired: [...current].sort(),
+                add: [],
+                status: "skipped_already_triaged",
+                message: `already has ${policy.idempotencyLabel}`,
+            });
+            continue;
+        }
+        // Pass number set only when this exact repo+number is referenced from xBRIEF.
+        const key = `${repo.toLowerCase()}\0${issueNumber}`;
+        const vbriefReferenced = referencedKeys.has(key)
+            ? new Set([issueNumber])
+            : new Set();
+        const classification = engine.classifyIssue(issue, {
+            rules: rules,
+            holdMarkers,
+            vbriefReferenced,
+            hasTriageDecision: decisionMapHas(decisions, repo, issueNumber),
+            now,
+        });
+        if (classification === null) {
+            skippedNoMatch += 1;
+            items.push({
+                repo,
+                issue_number: issueNumber,
+                action: null,
+                reason: null,
+                ruleKind: null,
+                current: [...current].sort(),
+                desired: [],
+                add: [],
+                status: "skipped_no_match",
+            });
+            continue;
+        }
+        const desired = desiredLabelsForClassification(classification.action, policy);
+        const currentSet = new Set(current);
+        const add = desired.filter((label) => !currentSet.has(label)).sort();
+        if (add.length === 0) {
+            unchanged += 1;
+            items.push({
+                repo,
+                issue_number: issueNumber,
+                action: classification.action,
+                reason: classification.reason,
+                ruleKind: classification.ruleKind,
+                current: [...current].sort(),
+                desired,
+                add: [],
+                status: "unchanged",
+            });
+            continue;
+        }
+        if (dryRun) {
+            planned += 1;
+            items.push({
+                repo,
+                issue_number: issueNumber,
+                action: classification.action,
+                reason: classification.reason,
+                ruleKind: classification.ruleKind,
+                current: [...current].sort(),
+                desired,
+                add,
+                status: "planned",
+            });
+            continue;
+        }
+        // --apply path: SCM boundary + write
+        const mutateGate = isRepoMutationAllowed(repo, root, {
+            allowCrossRepo: options.allowCrossRepo,
+            allowlist: options.repoAllowlist,
+            explicitRepo: options.repo ?? null,
+        });
+        if (!mutateGate.allowed) {
+            errors += 1;
+            items.push({
+                repo,
+                issue_number: issueNumber,
+                action: classification.action,
+                reason: classification.reason,
+                ruleKind: classification.ruleKind,
+                current: [...current].sort(),
+                desired,
+                add,
+                status: "error",
+                message: mutateGate.reason ?? `refusing cross-repo mutation on ${repo}`,
+            });
+            continue;
+        }
+        if (client === undefined) {
+            errors += 1;
+            items.push({
+                repo,
+                issue_number: issueNumber,
+                action: classification.action,
+                reason: classification.reason,
+                ruleKind: classification.ruleKind,
+                current: [...current].sort(),
+                desired,
+                add,
+                status: "error",
+                message: "no LabelClient available for apply",
+            });
+            continue;
+        }
+        try {
+            client.apply(repo, issueNumber, add, []);
+            applied += 1;
+            items.push({
+                repo,
+                issue_number: issueNumber,
+                action: classification.action,
+                reason: classification.reason,
+                ruleKind: classification.ruleKind,
+                current: [...current].sort(),
+                desired,
+                add,
+                status: "applied",
+            });
+        }
+        catch (exc) {
+            errors += 1;
+            items.push({
+                repo,
+                issue_number: issueNumber,
+                action: classification.action,
+                reason: classification.reason,
+                ruleKind: classification.ruleKind,
+                current: [...current].sort(),
+                desired,
+                add,
+                status: "error",
+                message: exc instanceof Error ? exc.message : String(exc),
+            });
+        }
+    }
+    const outcome = {
+        ...outcomeBase,
+        scanned: pairs.length,
+        planned,
+        applied,
+        unchanged,
+        skipped_already_triaged: skippedAlready,
+        skipped_no_match: skippedNoMatch,
+        skipped_unreadable: skippedUnreadable,
+        errors,
+        items,
+    };
+    return [errors > 0 ? 1 : 0, outcome];
+}
+/** Human-readable digest for dry-run / apply reports. */
+export function renderLabelMirrorReport(outcome) {
+    const lines = [];
+    const mode = outcome.dry_run ? "dry-run" : "apply";
+    lines.push(`triage:classify --mirror (${mode})`);
+    lines.push(`scanned=${outcome.scanned} planned=${outcome.planned} applied=${outcome.applied} ` +
+        `unchanged=${outcome.unchanged} already_triaged=${outcome.skipped_already_triaged} ` +
+        `no_match=${outcome.skipped_no_match} unreadable=${outcome.skipped_unreadable} ` +
+        `errors=${outcome.errors}`);
+    lines.push(`idempotencyLabel=${outcome.policy.idempotencyLabel} alwaysLabels=${JSON.stringify(outcome.policy.alwaysLabels)}`);
+    lines.push("");
+    const plannedOrApplied = outcome.items.filter((i) => i.status === "planned" || i.status === "applied");
+    lines.push(outcome.dry_run ? "Would add labels:" : "Added labels:");
+    if (plannedOrApplied.length === 0) {
+        lines.push("- none");
+    }
+    else {
+        for (const item of plannedOrApplied) {
+            const actionPart = item.action !== null ? ` action=${item.action}` : "";
+            const rulePart = item.ruleKind !== null ? ` rule=${item.ruleKind}` : "";
+            const addPart = sanitizeReportFragment(item.add.join(", +"));
+            lines.push(`- ${item.repo}#${item.issue_number}:${actionPart}${rulePart} +${addPart}`);
+        }
+    }
+    const already = outcome.items.filter((i) => i.status === "skipped_already_triaged");
+    if (already.length > 0) {
+        lines.push("");
+        lines.push(`Skipped (already ${outcome.policy.idempotencyLabel}): ${already.length}`);
+    }
+    const noMatch = outcome.items.filter((i) => i.status === "skipped_no_match");
+    if (noMatch.length > 0) {
+        lines.push(`Skipped (no classify match): ${noMatch.length}`);
+    }
+    const errs = outcome.items.filter((i) => i.status === "error");
+    if (errs.length > 0) {
+        lines.push("");
+        lines.push("Errors:");
+        for (const item of errs) {
+            const msg = sanitizeReportFragment(item.message ?? "unknown error");
+            lines.push(`- ${item.repo}#${item.issue_number}: ${msg}`);
+        }
+    }
+    if (outcome.dry_run && plannedOrApplied.length > 0) {
+        lines.push("");
+        lines.push("Dry-run -- re-run with --mirror --apply to write these labels via SCM.");
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** JSON-serializable outcome (stable key order not required). */
+export function labelMirrorOutcomeToJson(outcome) {
+    return {
+        project_root: outcome.project_root,
+        dry_run: outcome.dry_run,
+        scanned: outcome.scanned,
+        planned: outcome.planned,
+        applied: outcome.applied,
+        unchanged: outcome.unchanged,
+        skipped_already_triaged: outcome.skipped_already_triaged,
+        skipped_no_match: outcome.skipped_no_match,
+        skipped_unreadable: outcome.skipped_unreadable,
+        errors: outcome.errors,
+        policy: {
+            enabled: outcome.policy.enabled,
+            idempotencyLabel: outcome.policy.idempotencyLabel,
+            alwaysLabels: [...outcome.policy.alwaysLabels],
+            actionLabels: Object.fromEntries(Object.entries(outcome.policy.actionLabels).map(([k, v]) => [k, [...(v ?? [])]])),
+        },
+        items: outcome.items.map((i) => ({
+            repo: i.repo,
+            issue_number: i.issue_number,
+            action: i.action,
+            reason: i.reason,
+            ruleKind: i.ruleKind,
+            current: [...i.current],
+            desired: [...i.desired],
+            add: [...i.add],
+            status: i.status,
+            ...(i.message !== undefined ? { message: i.message } : {}),
+        })),
+    };
+}
+/** Validate triageLabelMirror on a plan object (vbrief_validate hook). */
+export function validateTriageLabelMirrorOnPlan(plan, filepath) {
+    const out = [];
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+        return out;
+    }
+    const policy = readPlanPolicy(plan);
+    const raw = typeof policy === "object" && policy !== null && !Array.isArray(policy)
+        ? policy.triageLabelMirror
+        : undefined;
+    if (raw === undefined || raw === null) {
+        return out;
+    }
+    const { errors } = validateLabelMirrorPolicy(raw);
+    for (const err of errors) {
+        out.push(`${filepath}: ${err} (#1423)`);
+    }
+    return out;
+}
+//# sourceMappingURL=label-mirror.js.map