@company-semantics/contracts 0.12.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -16,6 +16,10 @@
       "types": "./src/guards/index.ts",
       "default": "./src/guards/index.ts"
     },
+    "./compatibility": {
+      "types": "./src/compatibility.ts",
+      "default": "./src/compatibility.ts"
+    },
     "./schemas/guard-result.schema.json": "./schemas/guard-result.schema.json"
   },
   "types": "./src/index.ts",

package/src/compatibility.ts

@@ -0,0 +1,35 @@
+/**
+ * Contracts Compatibility Manifest
+ *
+ * Machine-readable version policy for CI guards.
+ * Enables consumer repos to programmatically validate their installed version.
+ *
+ * @see ADR-2025-12-011 in DECISIONS.md
+ */
+
+/**
+ * Deprecation entry for a semver range.
+ * Consumers matching this range will receive advisory warnings.
+ */
+export interface Deprecation {
+  /** Semver range (e.g., "0.12.x") */
+  range: string
+  /** Human-readable reason for deprecation */
+  reason: string
+  /** Version in which support will be removed */
+  removeIn: string
+}
+
+/**
+ * Compatibility manifest exported as data.
+ * CI guards read this to determine freshness warnings/errors.
+ */
+export const COMPATIBILITY = {
+  /** Minimum version that all consumers should use */
+  minSupported: '0.14.0',
+
+  /** Versions that still work but should upgrade (with reasons) */
+  deprecations: [] as Deprecation[],
+} as const
+
+export type Compatibility = typeof COMPATIBILITY

package/src/guards/config.ts

@@ -136,6 +136,71 @@ export type GuardCheckFactory = (
  */
 export type BoundGuardCheck = () => Promise<CheckResult> | CheckResult;
 
+/**
+ * Contracts freshness baseline configuration.
+ * Consumer repos import COMPATIBILITY from contracts and pass it here.
+ *
+ * @see ADR-2025-12-014 for design rationale
+ */
+export interface ContractsFreshnessBaseline {
+  /** Path to lockfile relative to repo root (e.g., 'pnpm-lock.yaml') */
+  lockfilePath: string;
+
+  /**
+   * Compatibility manifest from @company-semantics/contracts.
+   * Import and pass directly: `import { COMPATIBILITY } from '@company-semantics/contracts'`
+   */
+  compatibility: {
+    minSupported: string;
+    deprecations: readonly { range: string; reason: string; removeIn: string }[];
+  };
+
+  /**
+   * Skip this guard. Use for repos with workspace:* dependency (always current).
+   * @default false
+   */
+  skip?: boolean;
+}
+
+/**
+ * Evolution guard baselines.
+ * Product repos provide DATA only; CI orchestrator owns guard implementations.
+ *
+ * Design invariant: Product repos must NEVER import CI guard code.
+ * They export baselines; CI injects guards at runtime.
+ */
+export interface EvolutionBaselines {
+  /** Source directory (explicit, no assumptions). Defaults to 'src' if omitted. */
+  srcDir?: string;
+
+  /** Export count baseline per file. Key is file path relative to srcDir. */
+  exports?: Record<string, number>;
+
+  /** Import count baseline per file. Key is file path relative to srcDir. */
+  imports?: Record<string, number>;
+
+  /** File count baseline per domain. Key is domain path. */
+  domains?: Record<string, number>;
+
+  /** Drift thresholds (optional, guards have sensible defaults) */
+  thresholds?: {
+    /** Max allowed export drift before warning */
+    exportDrift?: number;
+    /** Max allowed import drift before warning */
+    importDrift?: number;
+    /** Max allowed domain file count drift before warning */
+    domainDrift?: number;
+  };
+
+  /**
+   * Contracts freshness check configuration.
+   * CI injects checkContractsFreshness based on this config.
+   *
+   * @see ADR-2025-12-014
+   */
+  contractsFreshness?: ContractsFreshnessBaseline;
+}
+
 /**
  * Registry of checks grouped by tier.
  * Each repo exports this from guard-entries.ts for universal orchestration.
@@ -152,10 +217,21 @@ export interface GuardCheckRegistry {
     structural?: BoundGuardCheck[];
     behavioral?: BoundGuardCheck[];
     invariants?: BoundGuardCheck[];
+    /**
+     * @deprecated Evolution guards are CI-owned. Use evolutionBaselines instead.
+     * Product repos should not provide evolution check implementations.
+     */
     evolution?: BoundGuardCheck[];
     /** Meta-guards: protect the guard system itself (coverage correctness) */
     meta?: BoundGuardCheck[];
   };
+
+  /**
+   * Evolution guard baselines.
+   * CI orchestrator injects evolution guards based on these baselines.
+   * Product repos provide data only, never guard implementations.
+   */
+  evolutionBaselines?: EvolutionBaselines;
 }
 
 // =============================================================================

package/src/guards/index.ts

@@ -29,6 +29,8 @@ export type {
   GuardCheckFactory,
   BoundGuardCheck,
   GuardCheckRegistry,
+  EvolutionBaselines,
+  ContractsFreshnessBaseline,
 } from './config.js';
 
 // Config constants (type-level defaults)

package/src/index.ts

@@ -55,6 +55,8 @@ export type {
   GuardCheckFactory,
   BoundGuardCheck,
   GuardCheckRegistry,
+  EvolutionBaselines,
+  ContractsFreshnessBaseline,
 } from './guards/index.js'
 
 export {
@@ -64,3 +66,8 @@ export {
   DEFAULT_DOMAIN_SECTIONS,
   DEFAULT_INFRA_SECTIONS,
 } from './guards/index.js'
+
+// Compatibility manifest (CI guard vocabulary)
+// @see ADR-2025-12-011 for design rationale
+export { COMPATIBILITY } from './compatibility.js'
+export type { Compatibility, Deprecation } from './compatibility.js'