@company-semantics/contracts 0.13.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.13.0",
+  "version": "0.15.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,68 @@ 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;
+}
+
+/**
+ * Scripts-devDependencies guard configuration.
+ * Checks that tools used in package.json scripts are declared in devDependencies.
+ */
+export interface ScriptsDepsBaseline {
+  /** Path to package.json relative to repo root */
+  packageJsonPath: string;
+
+  /**
+   * Additional tools to exempt from checking.
+   * Runtime-provided tools (node, pnpm, npm, npx) are always exempt.
+   */
+  exempt?: string[];
+
+  /**
+   * If true, violations are errors. If false, violations are warnings.
+   * @default false
+   */
+  strict?: boolean;
+}
+
+/**
+ * Structural 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 StructuralBaselines {
+  /**
+   * Scripts-devDependencies check configuration.
+   * CI injects checkScriptsDeps based on this config.
+   */
+  scriptsDeps?: ScriptsDepsBaseline;
+}
+
 /**
  * Evolution guard baselines.
  * Product repos provide DATA only; CI orchestrator owns guard implementations.
@@ -165,6 +227,14 @@ export interface EvolutionBaselines {
     /** 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;
 }
 
 /**
@@ -192,6 +262,13 @@ export interface GuardCheckRegistry {
     meta?: BoundGuardCheck[];
   };
 
+  /**
+   * Structural guard baselines.
+   * CI orchestrator injects structural guards based on these baselines.
+   * Product repos provide data only, never guard implementations.
+   */
+  structuralBaselines?: StructuralBaselines;
+
   /**
    * Evolution guard baselines.
    * CI orchestrator injects evolution guards based on these baselines.

package/src/guards/index.ts

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

package/src/index.ts

@@ -56,6 +56,7 @@ export type {
   BoundGuardCheck,
   GuardCheckRegistry,
   EvolutionBaselines,
+  ContractsFreshnessBaseline,
 } from './guards/index.js'
 
 export {
@@ -65,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'