@deftai/directive-core 0.55.0

package/dist/cache/test-helpers.js

@@ -0,0 +1,17 @@
+/** Fixed clock for deterministic TTL tests. */
+export class FixedClock {
+    current;
+    constructor(start) {
+        this.current = start;
+    }
+    now() {
+        return new Date(this.current);
+    }
+    setNow(dt) {
+        this.current = dt;
+    }
+    advanceSeconds(seconds) {
+        this.current = new Date(this.current.getTime() + seconds * 1000);
+    }
+}
+//# sourceMappingURL=test-helpers.js.map

package/dist/cache/time.d.ts

@@ -0,0 +1,9 @@
+/** Injectable clock seam for TTL tests. */
+export interface Clock {
+    now(): Date;
+}
+export declare const systemClock: Clock;
+export declare function utcIso(clock: Clock, dt?: Date): string;
+export declare function parseIso(stamp: string): Date;
+export declare function addSeconds(date: Date, seconds: number): Date;
+//# sourceMappingURL=time.d.ts.map

package/dist/cache/time.js

@@ -0,0 +1,20 @@
+export const systemClock = {
+    now() {
+        return new Date();
+    },
+};
+export function utcIso(clock, dt) {
+    const date = dt ?? clock.now();
+    return date.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+export function parseIso(stamp) {
+    let text = stamp.trim();
+    if (text.endsWith("Z")) {
+        text = `${text.slice(0, -1)}+00:00`;
+    }
+    return new Date(text);
+}
+export function addSeconds(date, seconds) {
+    return new Date(date.getTime() + seconds * 1000);
+}
+//# sourceMappingURL=time.js.map

package/dist/cache/types.d.ts

@@ -0,0 +1,50 @@
+import type { ScanFlag, ScanResult } from "./scanner.js";
+export interface PutResult {
+    source: string;
+    key: string;
+    entryDir: string;
+    meta: Record<string, unknown>;
+    scanResult: ScanResult;
+    contentWritten: boolean;
+}
+export interface GetResult {
+    source: string;
+    key: string;
+    entryDir: string;
+    meta: Record<string, unknown>;
+    contentPath: string | null;
+    stale: boolean;
+}
+export interface FetchAllReport {
+    issuesWritten: number;
+    alreadyFresh: number;
+    issuesFailed: number;
+    failures: Array<{
+        key: string;
+        reason: string;
+    }>;
+}
+export interface StateRefreshReport {
+    revisited: number;
+    closedRewritten: number;
+    stillOpen: number;
+    refreshFailed: number;
+    failures: Array<{
+        key: string;
+        reason: string;
+    }>;
+}
+export interface CachePutOptions {
+    ttlSeconds?: number | null;
+    cacheRoot?: string;
+    fetchedAt?: Date;
+    caps?: import("./quota.js").CacheCaps | null;
+    clock?: import("./time.js").Clock;
+}
+export interface CacheGetOptions {
+    cacheRoot?: string;
+    allowStale?: boolean;
+    clock?: import("./time.js").Clock;
+}
+export type ScanFlagMeta = ScanFlag;
+//# sourceMappingURL=types.d.ts.map

package/dist/cache/types.js

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

package/dist/cache/validate.d.ts

@@ -0,0 +1,3 @@
+/** Validate meta against cache-meta.schema.json (mirrors `_cache_validate.validate_meta`). */
+export declare function validateMeta(meta: unknown, allowedSources?: readonly string[]): void;
+//# sourceMappingURL=validate.d.ts.map

package/dist/cache/validate.js

@@ -0,0 +1,118 @@
+import { ALLOWED_SOURCES } from "./constants.js";
+import { CacheValidationError } from "./errors.js";
+const VALID_DATETIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+const VALID_SEMVER_RE = /^\d+\.\d+\.\d+$/;
+const META_REQUIRED = [
+    "source",
+    "key",
+    "fetched_at",
+    "ttl_seconds",
+    "expires_at",
+    "scan_result",
+    "size_bytes",
+    "stale",
+];
+const META_ALLOWED = new Set([...META_REQUIRED, "etag"]);
+const SCAN_RESULT_REQUIRED = ["passed", "scanned_at", "scanner_version", "flags"];
+const SCAN_RESULT_ALLOWED = new Set(SCAN_RESULT_REQUIRED);
+const SCAN_FLAG_REQUIRED = ["category", "severity", "detail"];
+const SCAN_FLAG_ALLOWED = new Set([...SCAN_FLAG_REQUIRED, "match_count"]);
+const SCAN_FLAG_CATEGORIES = new Set(["injection-heading", "credentials", "invisible-unicode"]);
+const SCAN_FLAG_SEVERITIES = new Set(["fence-and-pass", "hard-fail", "strip-and-pass"]);
+function requireKeys(obj, required, path) {
+    const missing = required.filter((k) => !(k in obj));
+    if (missing.length > 0) {
+        throw new CacheValidationError(`meta.json validation failure at ${path}: missing required keys ${JSON.stringify(missing)}`);
+    }
+}
+function disallowExtras(obj, allowed, path) {
+    const extra = Object.keys(obj).filter((k) => !allowed.has(k));
+    if (extra.length > 0) {
+        throw new CacheValidationError(`meta.json validation failure at ${path}: unknown keys ${JSON.stringify(extra.sort())}`);
+    }
+}
+function isNonNegativeInt(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+function validateDatetime(value, path) {
+    if (typeof value !== "string" || !VALID_DATETIME_RE.test(value)) {
+        throw new CacheValidationError(`meta.json validation failure at ${path}: not a UTC-suffixed ISO-8601 timestamp (${JSON.stringify(value)})`);
+    }
+}
+function validateScanFlag(flag, index) {
+    const path = `.scan_result.flags[${index}]`;
+    if (flag === null || typeof flag !== "object" || Array.isArray(flag)) {
+        throw new CacheValidationError(`meta.json validation failure at ${path}: expected object`);
+    }
+    const obj = flag;
+    requireKeys(obj, SCAN_FLAG_REQUIRED, path);
+    disallowExtras(obj, SCAN_FLAG_ALLOWED, path);
+    if (!SCAN_FLAG_CATEGORIES.has(String(obj.category))) {
+        throw new CacheValidationError(`meta.json validation failure at ${path}.category: ${JSON.stringify(obj.category)} not in ${JSON.stringify([...SCAN_FLAG_CATEGORIES].sort())}`);
+    }
+    if (!SCAN_FLAG_SEVERITIES.has(String(obj.severity))) {
+        throw new CacheValidationError(`meta.json validation failure at ${path}.severity: ${JSON.stringify(obj.severity)} not in ${JSON.stringify([...SCAN_FLAG_SEVERITIES].sort())}`);
+    }
+    if (typeof obj.detail !== "string") {
+        throw new CacheValidationError(`meta.json validation failure at ${path}.detail: expected string`);
+    }
+    if ("match_count" in obj && !isNonNegativeInt(obj.match_count)) {
+        throw new CacheValidationError(`meta.json validation failure at ${path}.match_count: expected non-negative int (got ${JSON.stringify(obj.match_count)})`);
+    }
+}
+function validateScanResult(scanResult) {
+    if (scanResult === null || typeof scanResult !== "object" || Array.isArray(scanResult)) {
+        throw new CacheValidationError("meta.json validation failure at .scan_result: expected object");
+    }
+    const obj = scanResult;
+    requireKeys(obj, SCAN_RESULT_REQUIRED, ".scan_result");
+    disallowExtras(obj, SCAN_RESULT_ALLOWED, ".scan_result");
+    if (typeof obj.passed !== "boolean") {
+        throw new CacheValidationError("meta.json validation failure at .scan_result.passed: expected bool");
+    }
+    validateDatetime(obj.scanned_at, ".scan_result.scanned_at");
+    const sv = obj.scanner_version;
+    if (typeof sv !== "string" || !VALID_SEMVER_RE.test(sv)) {
+        throw new CacheValidationError(`meta.json validation failure at .scan_result.scanner_version: not a SemVer string (${JSON.stringify(sv)})`);
+    }
+    if (!Array.isArray(obj.flags)) {
+        throw new CacheValidationError("meta.json validation failure at .scan_result.flags: expected array");
+    }
+    for (let i = 0; i < obj.flags.length; i += 1) {
+        validateScanFlag(obj.flags[i], i);
+    }
+}
+function validateMetaEnvelope(meta, allowedSources) {
+    if (!allowedSources.includes(String(meta.source))) {
+        throw new CacheValidationError(`meta.json validation failure at .source: ${JSON.stringify(meta.source)} not in ${JSON.stringify([...allowedSources].sort())}`);
+    }
+    if (typeof meta.key !== "string" || meta.key.length === 0) {
+        throw new CacheValidationError("meta.json validation failure at .key: expected non-empty string");
+    }
+    validateDatetime(meta.fetched_at, ".fetched_at");
+    validateDatetime(meta.expires_at, ".expires_at");
+    if (!isNonNegativeInt(meta.ttl_seconds)) {
+        throw new CacheValidationError(`meta.json validation failure at .ttl_seconds: expected non-negative int (got ${JSON.stringify(meta.ttl_seconds)})`);
+    }
+    if (!isNonNegativeInt(meta.size_bytes)) {
+        throw new CacheValidationError(`meta.json validation failure at .size_bytes: expected non-negative int (got ${JSON.stringify(meta.size_bytes)})`);
+    }
+    if (typeof meta.stale !== "boolean") {
+        throw new CacheValidationError(`meta.json validation failure at .stale: expected bool (got ${JSON.stringify(meta.stale)})`);
+    }
+    if ("etag" in meta && typeof meta.etag !== "string") {
+        throw new CacheValidationError(`meta.json validation failure at .etag: expected string when present (got ${JSON.stringify(meta.etag)})`);
+    }
+}
+/** Validate meta against cache-meta.schema.json (mirrors `_cache_validate.validate_meta`). */
+export function validateMeta(meta, allowedSources = ALLOWED_SOURCES) {
+    if (meta === null || typeof meta !== "object" || Array.isArray(meta)) {
+        throw new CacheValidationError(`meta.json validation failure at <root>: expected object, got ${Array.isArray(meta) ? "array" : typeof meta}`);
+    }
+    const obj = meta;
+    requireKeys(obj, META_REQUIRED, "<root>");
+    disallowExtras(obj, META_ALLOWED, "<root>");
+    validateMetaEnvelope(obj, allowedSources);
+    validateScanResult(obj.scan_result);
+}
+//# sourceMappingURL=validate.js.map

package/dist/capacity/backfill.d.ts

@@ -0,0 +1,52 @@
+export declare const COMPLETED_FOLDER = "completed";
+export declare const CACHE_RELPATH: readonly [".deft-cache", "github-issue"];
+export interface BackfillItem {
+    readonly rel_path: string;
+    readonly issue_number: number | null;
+    readonly bucket: string;
+    readonly source: string;
+    readonly set_bucket: boolean;
+    readonly set_completed_at: boolean;
+}
+export interface BackfillResult {
+    project_root: string;
+    dry_run: boolean;
+    scanned: number;
+    stamped_bucket: number;
+    stamped_completed_at: number;
+    already_classified: number;
+    matched: number;
+    defaulted: number;
+    fetched: number;
+    skipped_out_of_window: number;
+    skipped_unreadable: number;
+    window_only: boolean;
+    window_days: number;
+    items: BackfillItem[];
+    low_confidence: BackfillItem[];
+    error: string | null;
+    exit_code: number;
+}
+export declare function extractIssueRef(plan: Record<string, unknown>): [string | null, number | null];
+export declare function cachedIssueLabels(projectRoot: string, repo: string, issueNumber: number, cacheDir?: string): Set<string> | null;
+export declare function gitLandingTime(repoRelPath: string, projectRoot: string): string | null;
+export declare function fetchIssueLabels(repo: string, issueNumber: number): Promise<Set<string> | null>;
+export interface BackfillOptions {
+    cacheDir?: string;
+    dryRun?: boolean;
+    windowOnly?: boolean;
+    fetch?: boolean;
+    now?: Date;
+}
+/** Backfill capacityBucket / completedAt on completed vBRIEFs. */
+export declare function backfill(projectRoot: string, options?: BackfillOptions): Promise<BackfillResult>;
+export declare function renderBackfillSummary(result: BackfillResult): string;
+export declare function emitBackfillJson(result: BackfillResult): string;
+export interface CapacityBackfillCliResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/** CLI entry point. */
+export declare function runCapacityBackfillCli(argv: string[]): Promise<CapacityBackfillCliResult>;
+//# sourceMappingURL=backfill.d.ts.map