faf-cli 7.10.0 → 7.11.0

package/dist/core/drift.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Context-drift engine — SINGLE SOURCE.
+ *
+ * A pure, snapshot comparison: given a `project.faf` and its directory, report
+ * the mtime relationship between the .faf and each AI-context file it feeds
+ * (CLAUDE.md, AGENTS.md, .cursorrules, GEMINI.md). A target NEWER than the .faf
+ * has drifted — the human edited the context file and the DNA hasn't caught up.
+ *
+ * No console, no ANSI, no process.exit. The CLI `faf drift` renders the human
+ * table on top of this; `faf drift --json` emits this shape with a metadata
+ * header; the VS Code extension imports `computeDrift` directly (faf-cli as a
+ * library, never a shell-out). One comparison, every consumer.
+ */
+/** AI-context files the .faf feeds — the drift targets, in report order. */
+export declare const CONTEXT_FILES: string[];
+/** mtime window (ms) inside which a target counts as in sync with the .faf. */
+export declare const DRIFT_TOLERANCE_MS = 1000;
+/** 'newer' = target newer than the .faf → needs sync. */
+export type DriftStatus = 'newer' | 'older' | 'in-sync' | 'missing';
+export interface DriftTarget {
+    /** Context-file name, e.g. 'CLAUDE.md'. */
+    file: string;
+    /** Whether the file exists alongside the .faf. */
+    exists: boolean;
+    /** File mtime in epoch ms, or null when missing. */
+    mtime_ms: number | null;
+    /** 'newer' = target newer than the .faf → needs sync. */
+    status: DriftStatus;
+    /** mtime_ms - source_mtime_ms, or null when missing. */
+    delta_ms: number | null;
+}
+export interface DriftReport {
+    /** The `project.faf` path compared against. */
+    source: string;
+    /** .faf mtime in epoch ms. */
+    source_mtime_ms: number;
+    targets: DriftTarget[];
+    /** Count of targets with status 'newer' or 'older'. */
+    drifted: number;
+    /** Count of targets with status 'in-sync'. */
+    in_sync: number;
+    /** Count of targets with status 'missing'. */
+    missing: number;
+}
+/**
+ * Compare a `project.faf` against its AI-context files by mtime.
+ *
+ * @param fafPath  path to `project.faf`
+ * @param dir      directory holding the context files; defaults to the .faf's
+ *                 own directory. Never `process.cwd()` — the CLI passes it
+ *                 explicitly, and a library caller (the VS Code extension)
+ *                 passes the .faf's directory, which for a monorepo sub-package
+ *                 is the package dir, not the workspace root.
+ */
+export declare function computeDrift(fafPath: string, dir?: string): DriftReport;

package/dist/index.d.ts

@@ -5,6 +5,8 @@ export { FAF_HEX } from './ui/colors.js';
 export { enrichScore, scoreFafYaml } from './core/scorer.js';
 export { validateFaf } from './core/schema.js';
 export { findFafFile, readFaf, readFafRaw } from './interop/faf.js';
+export { computeDrift } from './core/drift.js';
+export type { DriftReport, DriftTarget, DriftStatus } from './core/drift.js';
 export { generateProjectHtml, writeProjectHtml } from './interop/projecthtml.js';
 export { generateServerCard, writeServerCard, fafContextBlock, registryMeta, registryName, REGISTRY_PUBLISHER_KEY, } from './interop/servercard.js';
 export type { ServerCardOptions } from './interop/servercard.js';