@deftai/directive-core 0.93.0 → 0.95.0

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

@@ -0,0 +1,143 @@
+/**
+ * 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 type { LabelClient } from "../../vbrief-reconcile/types.js";
+export declare const DEFAULT_IDEMPOTENCY_LABEL = "triaged";
+export declare const CACHE_DIR_NAME = ".deft-cache";
+export declare const CACHE_SOURCE = "github-issue";
+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_disabled" | "error";
+export interface LabelMirrorItem {
+    readonly repo: string;
+    readonly issue_number: number;
+    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;
+}
+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;
+    readonly errors: number;
+    readonly items: readonly LabelMirrorItem[];
+    readonly policy: ResolvedLabelMirrorPolicy;
+}
+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;
+    /** 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[];
+/**
+ * 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 declare function mirrorLabels(projectRoot: string, options: LabelMirrorOptions): [number, LabelMirrorOutcome];
+/** Human-readable digest for dry-run / apply reports. */
+export declare function renderLabelMirrorReport(outcome: LabelMirrorOutcome): string;
+/** JSON-serializable outcome (stable key order not required). */
+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