@specferret/core 0.3.0 → 0.4.1

package/dist/audit/index.d.ts

@@ -0,0 +1,27 @@
+import type { DBStore } from '../store/types.js';
+import type { ImportIntegrityReport, ReconcileReport } from '../reconciler/index.js';
+import type { UpwardDriftResult } from '../extractor/upward-classifier.js';
+import type { StatusReport } from '../status/index.js';
+export interface AuditSummary {
+    totalContracts: number;
+    stable: number;
+    needsReview: number;
+    roadmap: number;
+    downwardBreaking: number;
+    downwardNonBreaking: number;
+    upwardBreaking: number;
+    upwardNonBreaking: number;
+    integrityViolationCount: number;
+}
+export interface AuditReport {
+    version: '1.0';
+    timestamp: string;
+    summary: AuditSummary;
+    downwardDrift: ReconcileReport['flagged'];
+    upwardDrift: UpwardDriftResult[];
+    integrityViolations: ImportIntegrityReport;
+    importSuggestions: ReconcileReport['importSuggestions'];
+    statusReport: StatusReport;
+}
+export declare function buildAuditReport(store: DBStore, projectRoot: string): Promise<AuditReport>;
+//# sourceMappingURL=index.d.ts.map

package/dist/audit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACrF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAQvD,MAAM,WAAW,YAAY;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,KAAK,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,YAAY,CAAC;IACtB,aAAa,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAC1C,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,mBAAmB,EAAE,qBAAqB,CAAC;IAC3C,iBAAiB,EAAE,eAAe,CAAC,mBAAmB,CAAC,CAAC;IACxD,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA+EhG"}

package/dist/audit/index.js

@@ -0,0 +1,89 @@
+// Audit layer — read-only bidirectional drift report.
+// Combines downward drift (reconciler), upward drift (code → spec), and status.
+// No mutations. No side effects beyond reading the store and filesystem.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { Reconciler } from '../reconciler/index.js';
+import { classifyUpwardDrift } from '../extractor/upward-classifier.js';
+import { buildStatusReport } from '../status/index.js';
+import { extractContractsFromTypeScript } from '../extractor/typescript.js';
+import { extractFromContractFile } from '../extractor/typescript-contract.js';
+export async function buildAuditReport(store, projectRoot) {
+    const reconciler = new Reconciler(store);
+    const reconcileReport = await reconciler.reconcile();
+    const statusReport = await buildStatusReport(store);
+    const contracts = await store.getContracts();
+    const breakingTriggerIds = new Set(contracts.filter((c) => c.status === 'needs-review').map((c) => c.id));
+    // Upward drift detection — re-extract live TypeScript and compare to declared schema.
+    const upwardDrift = [];
+    const tsExtractionCache = new Map();
+    for (const contract of contracts) {
+        if (!contract.code_source_file || !contract.code_source_symbol)
+            continue;
+        const sourceAbsPath = path.resolve(projectRoot, contract.code_source_file);
+        if (!fs.existsSync(sourceAbsPath))
+            continue;
+        let codeShape;
+        try {
+            if (sourceAbsPath.endsWith('.contract.ts')) {
+                let tsExtraction = tsExtractionCache.get(sourceAbsPath);
+                if (!tsExtraction) {
+                    tsExtraction = await extractFromContractFile(sourceAbsPath);
+                    tsExtractionCache.set(sourceAbsPath, tsExtraction);
+                }
+                const found = tsExtraction.contracts.find((c) => c.id === contract.code_source_symbol);
+                if (!found)
+                    continue;
+                codeShape = found.shape;
+            }
+            else {
+                const fileContent = fs.readFileSync(sourceAbsPath, 'utf-8');
+                const extraction = extractContractsFromTypeScript(sourceAbsPath, fileContent);
+                const found = extraction.contracts.find((c) => c.sourceSymbol === contract.code_source_symbol);
+                if (!found)
+                    continue;
+                codeShape = found.shape;
+            }
+        }
+        catch {
+            continue;
+        }
+        let declaredSchema = {};
+        try {
+            declaredSchema = JSON.parse(contract.shape_schema);
+        }
+        catch { }
+        const result = classifyUpwardDrift(contract.id, declaredSchema, codeShape, contract.code_source_file, contract.code_source_symbol);
+        if (result.driftClass !== 'NOOP') {
+            upwardDrift.push(result);
+        }
+    }
+    const downwardBreaking = reconcileReport.flagged.filter((f) => breakingTriggerIds.has(f.triggeredByContractId)).length;
+    const downwardNonBreaking = reconcileReport.flagged.filter((f) => !breakingTriggerIds.has(f.triggeredByContractId)).length;
+    const upwardBreaking = upwardDrift.filter((d) => d.driftClass === 'BREAKING').length;
+    const upwardNonBreaking = upwardDrift.filter((d) => d.driftClass === 'NON_BREAKING').length;
+    const integrityViolationCount = reconcileReport.integrityViolations.unresolvedImports.length +
+        reconcileReport.integrityViolations.selfImports.length +
+        reconcileReport.integrityViolations.circularImports.length;
+    return {
+        version: '1.0',
+        timestamp: new Date().toISOString(),
+        summary: {
+            totalContracts: contracts.length,
+            stable: statusReport.stable,
+            needsReview: statusReport.needsReview,
+            roadmap: statusReport.roadmap,
+            downwardBreaking,
+            downwardNonBreaking,
+            upwardBreaking,
+            upwardNonBreaking,
+            integrityViolationCount,
+        },
+        downwardDrift: reconcileReport.flagged,
+        upwardDrift,
+        integrityViolations: reconcileReport.integrityViolations,
+        importSuggestions: reconcileReport.importSuggestions,
+        statusReport,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/audit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -15,4 +15,6 @@ export * from './config.js';
 export * from './utils/paths.js';
 export * from './contract.js';
 export * from './status/index.js';
+export * from './watch/index.js';
+export * from './audit/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oCAAoC,CAAC;AACnD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qBAAqB,CAAC;AACpC,cAAc,kCAAkC,CAAC;AACjD,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oCAAoC,CAAC;AACnD,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oCAAoC,CAAC;AACnD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qBAAqB,CAAC;AACpC,cAAc,kCAAkC,CAAC;AACjD,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oCAAoC,CAAC;AACnD,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -17,4 +17,6 @@ export * from './config.js';
 export * from './utils/paths.js';
 export * from './contract.js';
 export * from './status/index.js';
+export * from './watch/index.js';
+export * from './audit/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAC9B,4EAA4E;AAE5E,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oCAAoC,CAAC;AACnD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qBAAqB,CAAC;AACpC,cAAc,kCAAkC,CAAC;AACjD,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oCAAoC,CAAC;AACnD,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAC9B,4EAA4E;AAE5E,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oCAAoC,CAAC;AACnD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qBAAqB,CAAC;AACpC,cAAc,kCAAkC,CAAC;AACjD,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oCAAoC,CAAC;AACnD,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC"}

package/dist/watch/index.d.ts

@@ -0,0 +1,11 @@
+export interface WatcherOptions {
+    specDir: string;
+    projectRoot: string;
+    debounceMs?: number;
+    onChange: (changedFiles: string[]) => void | Promise<void>;
+}
+export interface ContractWatcher {
+    close: () => void;
+}
+export declare function createContractWatcher(options: WatcherOptions): ContractWatcher;
+//# sourceMappingURL=index.d.ts.map

package/dist/watch/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/watch/index.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,cAAc,GAAG,eAAe,CAmC9E"}

package/dist/watch/index.js

@@ -0,0 +1,42 @@
+// Watch layer — file system watcher with debounce for contract files.
+// No business logic. No parsing. No traversal.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export function createContractWatcher(options) {
+    const { specDir, projectRoot, debounceMs = 300, onChange } = options;
+    const watchDir = path.resolve(projectRoot, specDir);
+    let debounceTimer = null;
+    let pendingFiles = new Set();
+    let running = false;
+    const watcher = fs.watch(watchDir, { recursive: true }, (_eventType, filename) => {
+        if (!filename)
+            return;
+        const normalized = filename.replace(/\\/g, '/');
+        if (!normalized.endsWith('.contract.md') && !normalized.endsWith('.contract.ts'))
+            return;
+        pendingFiles.add(path.join(specDir, normalized).replace(/\\/g, '/'));
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(async () => {
+            if (running)
+                return;
+            running = true;
+            const files = [...pendingFiles];
+            pendingFiles = new Set();
+            try {
+                await onChange(files);
+            }
+            finally {
+                running = false;
+            }
+        }, debounceMs);
+    });
+    return {
+        close: () => {
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            watcher.close();
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/watch/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/watch/index.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,+CAA+C;AAE/C,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAalC,MAAM,UAAU,qBAAqB,CAAC,OAAuB;IAC3D,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,GAAG,GAAG,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IACrE,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAEpD,IAAI,aAAa,GAAyC,IAAI,CAAC;IAC/D,IAAI,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,MAAM,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,EAAE;QAC/E,IAAI,CAAC,QAAQ;YAAE,OAAO;QACtB,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAChD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,cAAc,CAAC;YAAE,OAAO;QAEzF,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;QAErE,IAAI,aAAa;YAAE,YAAY,CAAC,aAAa,CAAC,CAAC;QAC/C,aAAa,GAAG,UAAU,CAAC,KAAK,IAAI,EAAE;YACpC,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,MAAM,KAAK,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC;YAChC,YAAY,GAAG,IAAI,GAAG,EAAE,CAAC;YACzB,IAAI,CAAC;gBACH,MAAM,QAAQ,CAAC,KAAK,CAAC,CAAC;YACxB,CAAC;oBAAS,CAAC;gBACT,OAAO,GAAG,KAAK,CAAC;YAClB,CAAC;QACH,CAAC,EAAE,UAAU,CAAC,CAAC;IACjB,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,KAAK,EAAE,GAAG,EAAE;YACV,IAAI,aAAa;gBAAE,YAAY,CAAC,aAAa,CAAC,CAAC;YAC/C,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specferret/core",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "SpecFerret core engine — spec drift detection.",
   "type": "module",
   "main": "./dist/index.js",

package/src/audit/index.ts

@@ -0,0 +1,120 @@
+// Audit layer — read-only bidirectional drift report.
+// Combines downward drift (reconciler), upward drift (code → spec), and status.
+// No mutations. No side effects beyond reading the store and filesystem.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { DBStore } from '../store/types.js';
+import type { ImportIntegrityReport, ReconcileReport } from '../reconciler/index.js';
+import type { UpwardDriftResult } from '../extractor/upward-classifier.js';
+import type { StatusReport } from '../status/index.js';
+import type { ExtractionResult } from '../extractor/frontmatter.js';
+import { Reconciler } from '../reconciler/index.js';
+import { classifyUpwardDrift } from '../extractor/upward-classifier.js';
+import { buildStatusReport } from '../status/index.js';
+import { extractContractsFromTypeScript } from '../extractor/typescript.js';
+import { extractFromContractFile } from '../extractor/typescript-contract.js';
+
+export interface AuditSummary {
+  totalContracts: number;
+  stable: number;
+  needsReview: number;
+  roadmap: number;
+  downwardBreaking: number;
+  downwardNonBreaking: number;
+  upwardBreaking: number;
+  upwardNonBreaking: number;
+  integrityViolationCount: number;
+}
+
+export interface AuditReport {
+  version: '1.0';
+  timestamp: string;
+  summary: AuditSummary;
+  downwardDrift: ReconcileReport['flagged'];
+  upwardDrift: UpwardDriftResult[];
+  integrityViolations: ImportIntegrityReport;
+  importSuggestions: ReconcileReport['importSuggestions'];
+  statusReport: StatusReport;
+}
+
+export async function buildAuditReport(store: DBStore, projectRoot: string): Promise<AuditReport> {
+  const reconciler = new Reconciler(store);
+  const reconcileReport = await reconciler.reconcile();
+  const statusReport = await buildStatusReport(store);
+
+  const contracts = await store.getContracts();
+  const breakingTriggerIds = new Set(contracts.filter((c) => c.status === 'needs-review').map((c) => c.id));
+
+  // Upward drift detection — re-extract live TypeScript and compare to declared schema.
+  const upwardDrift: UpwardDriftResult[] = [];
+  const tsExtractionCache = new Map<string, ExtractionResult>();
+
+  for (const contract of contracts) {
+    if (!contract.code_source_file || !contract.code_source_symbol) continue;
+    const sourceAbsPath = path.resolve(projectRoot, contract.code_source_file);
+    if (!fs.existsSync(sourceAbsPath)) continue;
+
+    let codeShape: unknown;
+    try {
+      if (sourceAbsPath.endsWith('.contract.ts')) {
+        let tsExtraction = tsExtractionCache.get(sourceAbsPath);
+        if (!tsExtraction) {
+          tsExtraction = await extractFromContractFile(sourceAbsPath);
+          tsExtractionCache.set(sourceAbsPath, tsExtraction);
+        }
+        const found = tsExtraction.contracts.find((c) => c.id === contract.code_source_symbol);
+        if (!found) continue;
+        codeShape = found.shape;
+      } else {
+        const fileContent = fs.readFileSync(sourceAbsPath, 'utf-8');
+        const extraction = extractContractsFromTypeScript(sourceAbsPath, fileContent);
+        const found = extraction.contracts.find((c) => c.sourceSymbol === contract.code_source_symbol);
+        if (!found) continue;
+        codeShape = found.shape;
+      }
+    } catch {
+      continue;
+    }
+
+    let declaredSchema: unknown = {};
+    try {
+      declaredSchema = JSON.parse(contract.shape_schema);
+    } catch {}
+
+    const result = classifyUpwardDrift(contract.id, declaredSchema, codeShape, contract.code_source_file, contract.code_source_symbol);
+    if (result.driftClass !== 'NOOP') {
+      upwardDrift.push(result);
+    }
+  }
+
+  const downwardBreaking = reconcileReport.flagged.filter((f) => breakingTriggerIds.has(f.triggeredByContractId)).length;
+  const downwardNonBreaking = reconcileReport.flagged.filter((f) => !breakingTriggerIds.has(f.triggeredByContractId)).length;
+  const upwardBreaking = upwardDrift.filter((d) => d.driftClass === 'BREAKING').length;
+  const upwardNonBreaking = upwardDrift.filter((d) => d.driftClass === 'NON_BREAKING').length;
+  const integrityViolationCount =
+    reconcileReport.integrityViolations.unresolvedImports.length +
+    reconcileReport.integrityViolations.selfImports.length +
+    reconcileReport.integrityViolations.circularImports.length;
+
+  return {
+    version: '1.0',
+    timestamp: new Date().toISOString(),
+    summary: {
+      totalContracts: contracts.length,
+      stable: statusReport.stable,
+      needsReview: statusReport.needsReview,
+      roadmap: statusReport.roadmap,
+      downwardBreaking,
+      downwardNonBreaking,
+      upwardBreaking,
+      upwardNonBreaking,
+      integrityViolationCount,
+    },
+    downwardDrift: reconcileReport.flagged,
+    upwardDrift,
+    integrityViolations: reconcileReport.integrityViolations,
+    importSuggestions: reconcileReport.importSuggestions,
+    statusReport,
+  };
+}

package/src/index.ts

@@ -18,3 +18,5 @@ export * from './config.js';
 export * from './utils/paths.js';
 export * from './contract.js';
 export * from './status/index.js';
+export * from './watch/index.js';
+export * from './audit/index.js';

package/src/watch/index.ts

@@ -0,0 +1,53 @@
+// Watch layer — file system watcher with debounce for contract files.
+// No business logic. No parsing. No traversal.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export interface WatcherOptions {
+  specDir: string;
+  projectRoot: string;
+  debounceMs?: number;
+  onChange: (changedFiles: string[]) => void | Promise<void>;
+}
+
+export interface ContractWatcher {
+  close: () => void;
+}
+
+export function createContractWatcher(options: WatcherOptions): ContractWatcher {
+  const { specDir, projectRoot, debounceMs = 300, onChange } = options;
+  const watchDir = path.resolve(projectRoot, specDir);
+
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  let pendingFiles = new Set<string>();
+  let running = false;
+
+  const watcher = fs.watch(watchDir, { recursive: true }, (_eventType, filename) => {
+    if (!filename) return;
+    const normalized = filename.replace(/\\/g, '/');
+    if (!normalized.endsWith('.contract.md') && !normalized.endsWith('.contract.ts')) return;
+
+    pendingFiles.add(path.join(specDir, normalized).replace(/\\/g, '/'));
+
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(async () => {
+      if (running) return;
+      running = true;
+      const files = [...pendingFiles];
+      pendingFiles = new Set();
+      try {
+        await onChange(files);
+      } finally {
+        running = false;
+      }
+    }, debounceMs);
+  });
+
+  return {
+    close: () => {
+      if (debounceTimer) clearTimeout(debounceTimer);
+      watcher.close();
+    },
+  };
+}