@deftai/directive-core 0.94.0 → 0.96.0

package/dist/triage/author-filter.js

@@ -0,0 +1,152 @@
+/**
+ * Shared `--author` filter for triage:queue and triage:classify (#3129 / #1318 Layer 1).
+ *
+ * Matches existing bulk/bootstrap semantics: exact login match on cached author.login
+ * (or user.login). `@me` resolves via authenticated `gh api user --jq .login`.
+ * Comma allow-lists are accepted. Missing author on cache rows is "unknown" — not a match,
+ * and callers should disclose the unknown count rather than silent-drop.
+ */
+import { spawnSync } from "node:child_process";
+import { extractAuthor } from "./scope-drift/cache-walker.js";
+/** Split comma allow-list; trim; drop empties. */
+export function parseAuthorTokens(raw) {
+    return raw
+        .split(",")
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+}
+/**
+ * Resolve `@me` (and bare tokens) into an AuthorFilter.
+ * Returns error when raw is empty/whitespace-only or `@me` cannot be resolved.
+ */
+export function resolveAuthorFilter(raw, resolveMe) {
+    const resolveAuthenticated = resolveMe ?? defaultResolveAuthenticatedLogin;
+    const tokens = parseAuthorTokens(raw);
+    if (tokens.length === 0) {
+        return { error: "argument --author: expected a non-empty login (or @me)" };
+    }
+    let usedMe = false;
+    let meLogin;
+    const allow = [];
+    const displayParts = [];
+    for (const token of tokens) {
+        if (token === "@me" || token.toLowerCase() === "@me") {
+            usedMe = true;
+            if (meLogin === undefined) {
+                meLogin = resolveAuthenticated();
+            }
+            if (meLogin === null || meLogin.length === 0) {
+                return {
+                    error: "argument --author: @me could not be resolved (gh api user --jq .login failed; authenticate gh or pass an explicit login)",
+                };
+            }
+            allow.push(meLogin);
+            displayParts.push(`@me (resolved -> ${meLogin})`);
+        }
+        else {
+            allow.push(token);
+            displayParts.push(token);
+        }
+    }
+    // Dedup while preserving order
+    const seen = new Set();
+    const allowLogins = [];
+    for (const login of allow) {
+        if (!seen.has(login)) {
+            seen.add(login);
+            allowLogins.push(login);
+        }
+    }
+    return {
+        filter: {
+            raw,
+            allowLogins,
+            usedMe,
+            display: displayParts.join(", "),
+        },
+    };
+}
+/**
+ * Default `@me` resolution via live `gh` (not ghx — multi-arg api --jq; #2275 / #954).
+ */
+export function defaultResolveAuthenticatedLogin() {
+    try {
+        const result = spawnSync("gh", ["api", "user", "--jq", ".login"], {
+            encoding: "utf8",
+            env: process.env,
+            windowsHide: true,
+        });
+        if (result.status !== 0) {
+            return null;
+        }
+        const text = String(result.stdout ?? "").trim();
+        if (text.length === 0) {
+            return null;
+        }
+        // jq may emit a JSON string with quotes; strip surrounding quotes when present
+        if ((text.startsWith('"') && text.endsWith('"')) ||
+            (text.startsWith("'") && text.endsWith("'"))) {
+            return text.slice(1, -1);
+        }
+        return text;
+    }
+    catch {
+        return null;
+    }
+}
+/** Login from a CachedIssue.author string (empty = unknown). */
+export function normalizeAuthorLogin(login) {
+    if (login === null || login === undefined) {
+        return null;
+    }
+    const trimmed = login.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+/**
+ * Login from a raw cache payload (author.login / user.login / string author).
+ * Empty / missing → null (unknown).
+ */
+export function authorLoginFromRawIssue(issue) {
+    if (issue === null || issue === undefined) {
+        return null;
+    }
+    return normalizeAuthorLogin(extractAuthor(issue));
+}
+/** Exact allow-list match (bulk parity). Unknown/missing never matches. */
+export function matchesAuthorFilter(login, filter) {
+    const normalized = normalizeAuthorLogin(login);
+    if (normalized === null) {
+        return false;
+    }
+    return filter.allowLogins.includes(normalized);
+}
+/**
+ * Partition items by author filter. Unknown (missing login) counted separately
+ * and excluded from matched — callers disclose unknownCount in headers.
+ */
+export function partitionByAuthorFilter(items, getLogin, filter) {
+    const matched = [];
+    let unknownCount = 0;
+    let nonMatchingCount = 0;
+    for (const item of items) {
+        const login = normalizeAuthorLogin(getLogin(item));
+        if (login === null) {
+            unknownCount += 1;
+            continue;
+        }
+        if (filter.allowLogins.includes(login)) {
+            matched.push(item);
+        }
+        else {
+            nonMatchingCount += 1;
+        }
+    }
+    return { matched, unknownCount, nonMatchingCount };
+}
+/** Single-line header fragment for queue / classify digest. */
+export function formatAuthorFilterLine(filter, options = {}) {
+    const unknown = options.unknownCount ?? 0;
+    const unknownPart = unknown > 0 ? `; ${unknown} cached issue(s) missing author (unknown — excluded)` : "";
+    return `author filter: ${filter.display}${unknownPart}`;
+}
+//# sourceMappingURL=author-filter.js.map

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

@@ -85,4 +85,13 @@ export declare function validateProject(projectRoot: string): {
 };
 /** Render --list output for a project root. */
 export declare function listProject(projectRoot: string): string;
+import { buildLabelMirrorDigest, type ClassifyAction, DEFAULT_APPLY_BATCH_SIZE, DEFAULT_APPLY_DELAY_MS, DEFAULT_DIGEST_SAMPLE_LIMIT, DEFAULT_IDEMPOTENCY_LABEL, defaultLabelMirrorPolicy, desiredLabelsForClassification, type LabelMirrorDigest, type LabelMirrorEngine, type LabelMirrorFilters, type LabelMirrorItem, type LabelMirrorOptions as LabelMirrorOptionsCore, type LabelMirrorOutcome, type LabelMirrorPolicy, type LabelMirrorSleepFn, type LabelMirrorStatus, labelMirrorOutcomeToJson, type ResolvedLabelMirrorPolicy, renderLabelMirrorReport, resolveLabelMirrorPolicy, validateLabelMirrorPolicy, validateTriageLabelMirrorOnPlan as validateTriageLabelMirrorOnPlanFromModule } from "./label-mirror.js";
+export { buildLabelMirrorDigest, type ClassifyAction, DEFAULT_APPLY_BATCH_SIZE, DEFAULT_APPLY_DELAY_MS, DEFAULT_DIGEST_SAMPLE_LIMIT, DEFAULT_IDEMPOTENCY_LABEL, defaultLabelMirrorPolicy, desiredLabelsForClassification, type LabelMirrorDigest, type LabelMirrorEngine, type LabelMirrorFilters, type LabelMirrorItem, type LabelMirrorOutcome, type LabelMirrorPolicy, type LabelMirrorSleepFn, type LabelMirrorStatus, labelMirrorOutcomeToJson, type ResolvedLabelMirrorPolicy, renderLabelMirrorReport, resolveLabelMirrorPolicy, validateLabelMirrorPolicy, validateTriageLabelMirrorOnPlanFromModule as validateTriageLabelMirrorOnPlan, };
+/** Public options: engine is optional (defaults to this module's classify API). */
+export type LabelMirrorOptions = Omit<LabelMirrorOptionsCore, "engine"> & {
+    readonly engine?: LabelMirrorEngine;
+};
+export { extractReferencedRepoIssueKeys } from "./label-mirror.js";
+/** Tier-1 label mirror with the #1129 classify engine bound in. */
+export declare function mirrorLabels(projectRoot: string, options?: LabelMirrorOptions): [number, LabelMirrorOutcome];
 //# sourceMappingURL=index.d.ts.map

package/dist/triage/classify/index.js

@@ -721,7 +721,9 @@ export function validateProject(projectRoot) {
     const rel = projectDefinitionPath(root);
     const classifyErrs = validateTriageAutoClassifyOnPlan(plan, rel);
     const holderErrs = validateTriageHoldMarkersOnPlan(plan, rel);
-    const errors = [...classifyErrs, ...holderErrs];
+    // label-mirror validates plan.policy.triageLabelMirror (#1423); imported via re-export graph.
+    const mirrorErrs = validateTriageLabelMirrorOnPlanFromModule(plan, rel);
+    const errors = [...classifyErrs, ...holderErrs, ...mirrorErrs];
     if (errors.length > 0) {
         const lines = errors.map((err) => `FAIL: ${err}`);
         lines.push("");
@@ -732,7 +734,7 @@ export function validateProject(projectRoot) {
     const markers = resolveHoldMarkers({ projectRoot: root });
     return {
         code: 0,
-        stdout: "OK: triageAutoClassify[] + triageHoldMarkers[] valid " +
+        stdout: "OK: triageAutoClassify[] + triageHoldMarkers[] + triageLabelMirror valid " +
             `(${rules.length} rules, ${markers.length} hold markers).\n`,
         stderr: "",
     };
@@ -744,4 +746,34 @@ export function listProject(projectRoot) {
     const markers = resolveHoldMarkers({ projectRoot: root });
     return `${renderList(rules, { holdMarkers: markers })}\n`;
 }
+// ---------------------------------------------------------------------------
+// Tier-1 label mirror (#1423 Wave 1)
+// label-mirror.ts does not import this module (avoids ESM/SLizard cycle).
+// Public mirrorLabels injects the classify engine into the pure implementation.
+// ---------------------------------------------------------------------------
+import { buildLabelMirrorDigest, DEFAULT_APPLY_BATCH_SIZE, DEFAULT_APPLY_DELAY_MS, DEFAULT_DIGEST_SAMPLE_LIMIT, DEFAULT_IDEMPOTENCY_LABEL, defaultLabelMirrorPolicy, desiredLabelsForClassification, labelMirrorOutcomeToJson, mirrorLabels as mirrorLabelsCore, renderLabelMirrorReport, resolveLabelMirrorPolicy, validateLabelMirrorPolicy, validateTriageLabelMirrorOnPlan as validateTriageLabelMirrorOnPlanFromModule, } from "./label-mirror.js";
+export { buildLabelMirrorDigest, DEFAULT_APPLY_BATCH_SIZE, DEFAULT_APPLY_DELAY_MS, DEFAULT_DIGEST_SAMPLE_LIMIT, DEFAULT_IDEMPOTENCY_LABEL, defaultLabelMirrorPolicy, desiredLabelsForClassification, labelMirrorOutcomeToJson, renderLabelMirrorReport, resolveLabelMirrorPolicy, validateLabelMirrorPolicy, validateTriageLabelMirrorOnPlanFromModule as validateTriageLabelMirrorOnPlan, };
+function defaultLabelMirrorEngine() {
+    return {
+        classifyIssue: (issue, options) => classifyIssue(issue, {
+            rules: options?.rules,
+            holdMarkers: options?.holdMarkers,
+            vbriefReferenced: options?.vbriefReferenced,
+            hasTriageDecision: options?.hasTriageDecision,
+            now: options?.now,
+        }),
+        resolveClassifyRules,
+        resolveHoldMarkers,
+        extractReferencedIssues,
+    };
+}
+export { extractReferencedRepoIssueKeys } from "./label-mirror.js";
+/** Tier-1 label mirror with the #1129 classify engine bound in. */
+export function mirrorLabels(projectRoot, options = {}) {
+    const { engine, ...rest } = options;
+    return mirrorLabelsCore(projectRoot, {
+        ...rest,
+        engine: engine ?? defaultLabelMirrorEngine(),
+    });
+}
 //# sourceMappingURL=index.js.map

package/dist/triage/classify/label-mirror.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Tier-1 deterministic SCM label mirror (#1423 Wave 1 + Wave 2 bootstrap).
+ *
+ * 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.
+ *
+ * Wave 2 (#3125): open-only default, operator digest (totals + by state/rule/action
+ * + samples), batched rate-limit-aware apply. Bootstrap mass-triage entrypoint is
+ * `triage:classify -- --mirror` with these filters (not triage:accept).
+ *
+ * Intentionally does NOT import from ./index.js (SLizard P1 cycle). The classify
+ * engine is injected via LabelMirrorEngine / mirrorLabels() wrapper in index.ts.
+ */
+import type { LabelClient } from "../../vbrief-reconcile/types.js";
+import { type AuthorFilter } from "../author-filter.js";
+export declare const DEFAULT_IDEMPOTENCY_LABEL = "triaged";
+export declare const CACHE_DIR_NAME = ".deft-cache";
+export declare const CACHE_SOURCE = "github-issue";
+/** Default apply batch size for rate-limit awareness (#3125). */
+export declare const DEFAULT_APPLY_BATCH_SIZE = 10;
+/** Default delay between apply batches in ms (#3125). */
+export declare const DEFAULT_APPLY_DELAY_MS = 1000;
+/** Default sample count in human digest (#3125). */
+export declare const DEFAULT_DIGEST_SAMPLE_LIMIT = 15;
+export type ClassifyAction = "defer" | "archive" | "escalate" | "accept";
+/** Minimal issue shape used by the mirror (matches classify GitHubIssue). */
+export interface MirrorGitHubIssue {
+    readonly number?: number;
+    readonly state?: string;
+    readonly body?: string | null;
+    readonly labels?: ReadonlyArray<{
+        name?: string;
+    } | string>;
+    readonly updated_at?: string;
+    readonly created_at?: string;
+}
+export interface MirrorClassificationResult {
+    readonly action: string;
+    readonly reason: string;
+    readonly ruleIndex: number;
+    readonly ruleSource: string;
+    readonly ruleKind: string;
+    readonly resumeOn: string | null;
+}
+/** Injected classify engine — avoids a runtime import cycle with classify/index.ts. */
+export interface LabelMirrorEngine {
+    readonly classifyIssue: (issue: MirrorGitHubIssue, options?: {
+        rules?: readonly unknown[];
+        holdMarkers?: string[] | null;
+        vbriefReferenced?: ReadonlySet<number> | null;
+        hasTriageDecision?: boolean;
+        now?: Date;
+    }) => MirrorClassificationResult | null;
+    readonly resolveClassifyRules: (options?: {
+        projectRoot?: string;
+        projectDefinition?: Record<string, unknown> | null;
+    }) => readonly unknown[];
+    readonly resolveHoldMarkers: (options?: {
+        projectRoot?: string;
+        projectDefinition?: Record<string, unknown> | null;
+    }) => string[];
+    /** Optional; label-mirror prefers repo-qualified keys and only needs numbers as fallback. */
+    readonly extractReferencedIssues?: (projectRoot?: string) => Set<number>;
+}
+/**
+ * Repo-qualified xBRIEF github-issue keys (`owner/name\\0number`).
+ * Unlike number-only extractReferencedIssues, this never collides across repos.
+ */
+export declare function extractReferencedRepoIssueKeys(projectRoot?: string, lifecycleFolders?: readonly string[]): Set<string>;
+export interface LabelMirrorPolicy {
+    /** When false, mirror is a no-op (default true when policy object is used). */
+    readonly enabled?: boolean;
+    /** Idempotency marker; issues already carrying this label are skipped. Default: triaged. */
+    readonly idempotencyLabel?: string;
+    /** Labels always applied on a successful classification (default: [idempotencyLabel]). */
+    readonly alwaysLabels?: readonly string[];
+    /** Map classify action -> additional labels to apply. */
+    readonly actionLabels?: Readonly<Partial<Record<ClassifyAction, readonly string[]>>>;
+}
+export interface ResolvedLabelMirrorPolicy {
+    readonly enabled: boolean;
+    readonly idempotencyLabel: string;
+    readonly alwaysLabels: readonly string[];
+    readonly actionLabels: Readonly<Partial<Record<ClassifyAction, readonly string[]>>>;
+}
+export type LabelMirrorStatus = "planned" | "applied" | "unchanged" | "skipped_already_triaged" | "skipped_no_match" | "skipped_unreadable" | "skipped_closed" | "skipped_author" | "skipped_disabled" | "error";
+export interface LabelMirrorItem {
+    readonly repo: string;
+    readonly issue_number: number;
+    /** Issue state from cache (open/closed/unknown). */
+    readonly state: string | null;
+    readonly action: string | null;
+    readonly reason: string | null;
+    readonly ruleKind: string | null;
+    readonly current: readonly string[];
+    readonly desired: readonly string[];
+    readonly add: readonly string[];
+    readonly status: LabelMirrorStatus;
+    readonly message?: string;
+}
+/** Operator digest aggregates for bootstrap mass-triage (#3125 / #1423 Wave 2). */
+export interface LabelMirrorDigest {
+    readonly by_state: Readonly<Record<string, number>>;
+    readonly by_rule: Readonly<Record<string, number>>;
+    readonly by_action: Readonly<Record<string, number>>;
+    readonly samples: readonly LabelMirrorItem[];
+    readonly sample_limit: number;
+    readonly sample_truncated: boolean;
+}
+export interface LabelMirrorFilters {
+    /** When false (default), closed issues are skipped before classify. */
+    readonly include_closed: boolean;
+    readonly repo: string | null;
+    /** Active author allow-list display (#3129); null when no author filter. */
+    readonly author: string | null;
+    /** Resolved author logins for machine consumers. */
+    readonly author_logins: readonly string[] | null;
+}
+export interface LabelMirrorOutcome {
+    readonly project_root: string;
+    readonly dry_run: boolean;
+    readonly scanned: number;
+    readonly planned: number;
+    readonly applied: number;
+    readonly unchanged: number;
+    readonly skipped_already_triaged: number;
+    readonly skipped_no_match: number;
+    readonly skipped_unreadable: number;
+    /** Closed issues skipped by open-only default (#3125). */
+    readonly skipped_closed: number;
+    /** Issues skipped by --author filter (#3129). */
+    readonly skipped_author: number;
+    readonly errors: number;
+    readonly filters: LabelMirrorFilters;
+    readonly digest: LabelMirrorDigest;
+    readonly items: readonly LabelMirrorItem[];
+    readonly policy: ResolvedLabelMirrorPolicy;
+    /** Apply path: successful writes in this run (same as applied). */
+    readonly batch_size?: number;
+    readonly delay_ms?: number;
+}
+export type LabelMirrorSleepFn = (ms: number) => void;
+export interface LabelMirrorOptions {
+    readonly dryRun?: boolean;
+    readonly repo?: string | null;
+    readonly cacheRoot?: string;
+    readonly client?: LabelClient;
+    readonly allowCrossRepo?: boolean;
+    readonly repoAllowlist?: readonly string[];
+    /** Prefer live SCM labels when true (default: !dryRun). Cache labels used for dry-run. */
+    readonly useLiveLabels?: boolean;
+    readonly now?: Date;
+    /**
+     * Include closed issues in classify+mirror. Default false (open-only) for safe
+     * bootstrap mass-triage (#3125). Opt in with CLI `--include-closed`.
+     */
+    readonly includeClosed?: boolean;
+    /**
+     * Resolved author filter applied before plan/apply walk (#3129).
+     * Composes with open-only (AND). CLI resolves `@me` before passing this.
+     */
+    readonly authorFilter?: AuthorFilter | null;
+    /** Max planned/applied samples in human digest (default 15). */
+    readonly sampleLimit?: number;
+    /** SCM writes per batch before delay (default 10; apply path only). */
+    readonly batchSize?: number;
+    /** Delay in ms between apply batches (default 1000; apply path only). */
+    readonly delayMs?: number;
+    /** Injectable sleep for tests (receives ms). Default busy-wait when delayMs > 0. */
+    readonly sleepMs?: LabelMirrorSleepFn;
+    /** Required: classify engine (provided by classify/index mirrorLabels wrapper). */
+    readonly engine: LabelMirrorEngine;
+}
+/** Validate plan.policy.triageLabelMirror payload. */
+export declare function validateLabelMirrorPolicy(raw: unknown): {
+    errors: string[];
+    warnings: string[];
+};
+/** Default resolved policy when triageLabelMirror is absent. */
+export declare function defaultLabelMirrorPolicy(): ResolvedLabelMirrorPolicy;
+/** Resolve effective label-mirror policy from PROJECT-DEFINITION or inline object. */
+export declare function resolveLabelMirrorPolicy(options?: {
+    projectRoot?: string;
+    projectDefinition?: Record<string, unknown> | null;
+    override?: LabelMirrorPolicy | null;
+}): ResolvedLabelMirrorPolicy;
+/** Labels to apply for a classified action (always + action-mapped). */
+export declare function desiredLabelsForClassification(action: string, policy: ResolvedLabelMirrorPolicy): string[];
+/** Build digest aggregates + samples from mirror items (#3125). */
+export declare function buildLabelMirrorDigest(items: readonly LabelMirrorItem[], sampleLimit?: number): LabelMirrorDigest;
+/**
+ * Run Tier-1 label mirror over the github-issue cache (bootstrap mass-triage surface).
+ * Dry-run by default (no SCM writes). Pass dryRun: false to apply.
+ * Default state filter is open-only (#3125); pass includeClosed: true for archive stamps.
+ * Requires options.engine (classify/index wrapper injects it).
+ * Never calls triage:accept / never writes proposed/ xBRIEFs.
+ */
+export declare function mirrorLabels(projectRoot: string, options: LabelMirrorOptions): [number, LabelMirrorOutcome];
+/** Human-readable digest for dry-run / apply reports (bootstrap mass-triage UX). */
+export declare function renderLabelMirrorReport(outcome: LabelMirrorOutcome): string;
+/** JSON-serializable outcome including Wave 2 digest aggregates. */
+export declare function labelMirrorOutcomeToJson(outcome: LabelMirrorOutcome): Record<string, unknown>;
+/** Validate triageLabelMirror on a plan object (vbrief_validate hook). */
+export declare function validateTriageLabelMirrorOnPlan(plan: unknown, filepath: string): string[];
+//# sourceMappingURL=label-mirror.d.ts.map