@company-semantics/contracts 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -12,6 +12,10 @@
       "types": "./src/index.ts",
       "default": "./src/index.ts"
     },
+    "./guards": {
+      "types": "./src/guards/index.ts",
+      "default": "./src/guards/index.ts"
+    },
     "./schemas/guard-result.schema.json": "./schemas/guard-result.schema.json"
   },
   "types": "./src/index.ts",
@@ -33,14 +37,15 @@
     "guard:export:json": "npx tsx scripts/ci/export-guard.ts --json",
     "guard:vocabulary": "npx tsx scripts/ci/vocabulary-guard.ts",
     "guard:vocabulary:json": "npx tsx scripts/ci/vocabulary-guard.ts --json",
-    "guard:test": "vitest run scripts/ci/__tests__"
+    "guard:test": "vitest run scripts/ci/__tests__",
+    "test": "vitest run scripts/ci/__tests__"
   },
   "packageManager": "pnpm@10.25.0",
   "devDependencies": {
     "@types/node": "^25.0.3",
     "husky": "^9",
-    "lint-staged": "^15",
-    "markdownlint-cli2": "^0.17",
+    "lint-staged": "^16.2.7",
+    "markdownlint-cli2": "^0.20.0",
     "tsx": "^4.21.0",
     "typescript": "^5",
     "vitest": "^4.0.16"

package/schemas/guard-result.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://company-semantics.dev/schemas/guard-result.json",
   "title": "Guard Result",
-  "description": "JSON output envelope for CI guard --json mode. schemaVersion reflects the JSON schema version, not the guard tool version.",
+  "description": "JSON output envelope for CI guard --json mode (v2.0.0). Results are tiered, not flattened.",
   "type": "object",
   "required": ["tool", "schemaVersion", "timestamp", "results"],
   "properties": {
@@ -12,7 +12,7 @@
     },
     "schemaVersion": {
       "type": "string",
-      "description": "Schema version (not tool version). Bump on breaking schema changes.",
+      "description": "Schema version (not tool version). v2.0.0 introduces tiered results.",
       "pattern": "^\\d+\\.\\d+\\.\\d+$"
     },
     "timestamp": {
@@ -21,29 +21,18 @@
       "description": "ISO 8601 timestamp of when the guard ran"
     },
     "results": {
-      "type": "object",
-      "description": "Flat structure: all errors/warnings from all tiers are aggregated here",
-      "required": ["errors", "warnings"],
-      "properties": {
-        "errors": {
-          "type": "array",
-          "items": { "$ref": "#/definitions/GuardMessage" }
-        },
-        "warnings": {
-          "type": "array",
-          "items": { "$ref": "#/definitions/GuardMessage" }
-        }
-      }
+      "$ref": "#/definitions/GuardResults"
     }
   },
   "definitions": {
     "GuardMessage": {
       "type": "object",
+      "description": "A single guard message (error or warning)",
       "required": ["file", "message"],
       "properties": {
         "file": {
           "type": "string",
-          "description": "Path to the file with the issue"
+          "description": "Path to the file with the issue (relative to repo root)"
         },
         "message": {
           "type": "string",
@@ -51,11 +40,49 @@
         },
         "line": {
           "type": "number",
-          "description": "Optional line number (when available)"
+          "description": "Line number where the issue occurs (when available)"
         },
         "rule": {
           "type": "string",
-          "description": "Optional rule identifier (when available)"
+          "description": "Rule identifier that triggered this message (e.g., 'file-size', 'readme')"
+        }
+      }
+    },
+    "GuardTierResult": {
+      "type": "object",
+      "description": "Result for a single tier (errors + warnings)",
+      "required": ["errors", "warnings"],
+      "properties": {
+        "errors": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/GuardMessage" }
+        },
+        "warnings": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/GuardMessage" }
+        }
+      }
+    },
+    "GuardResults": {
+      "type": "object",
+      "description": "Full guard results organized by tier. Tier awareness is preserved end-to-end.",
+      "required": ["structural", "behavioral", "invariants", "evolution"],
+      "properties": {
+        "structural": {
+          "$ref": "#/definitions/GuardTierResult",
+          "description": "File sizes, READMEs, naming (fast, syntactic)"
+        },
+        "behavioral": {
+          "$ref": "#/definitions/GuardTierResult",
+          "description": "Import layers, dependencies (semantic)"
+        },
+        "invariants": {
+          "$ref": "#/definitions/GuardTierResult",
+          "description": "Domain rules, trust boundaries (business logic)"
+        },
+        "evolution": {
+          "$ref": "#/definitions/GuardTierResult",
+          "description": "Uncovered patterns, growth tracking (observational)"
         }
       }
     }

package/src/guards/README.md

@@ -0,0 +1,52 @@
+# Guard Types
+
+Canonical type vocabulary for CI guard systems across all Company Semantics repos.
+
+## Purpose
+
+Defines the contract between guard implementations (in workspace scripts) and consumers (backend, site).
+This module exports **types only** — runtime helper functions live in the workspace-level guard library.
+
+## Invariants
+
+- **Tier awareness preserved**: Results are always structured by tier, never flattened
+- **Types only**: No runtime code (functions, classes) per contracts policy
+- **Schema alignment**: Types match `schemas/guard-result.schema.json` exactly
+- **Backward compatibility**: Breaking changes require major version bump
+
+## Public API
+
+### Message Types
+
+- `GuardMessage` — Single error/warning with file, message, optional line/rule
+- `GuardTierResult` — Errors + warnings for one tier
+- `GuardResults` — Full results organized by tier
+- `GuardOutput` — JSON envelope for `--json` mode
+
+### Tier Types
+
+- `GuardTier` — `'structural' | 'behavioral' | 'invariants' | 'evolution'`
+- `GUARD_TIERS` — Ordered array for iteration
+
+### Check Types
+
+- `CheckResult` — Return type from individual guard checks
+- `GuardCheck` — Function signature `(root, config) => Promise<CheckResult>`
+- `GuardCheckFactory` — Factory signature `(overrides?) => GuardCheck`
+
+### Config Types
+
+- `RoleLimit` — Three-tier limit (target, warning, hard)
+- `GuardConfig` — Polymorphic configuration for guards
+
+### Constants
+
+- `GUARD_SCHEMA_VERSION` — `'2.0.0'` current schema version
+- `DEFAULT_SKIP_DIRECTORIES` — Standard dirs to skip
+- `DEFAULT_DOMAIN_SECTIONS` — Required README sections for domains
+- `DEFAULT_INFRA_SECTIONS` — Required README sections for infra
+
+## Dependencies
+
+- No external dependencies (types only)
+- Consumed by: backend `scripts/ci/`, site `scripts/ci/`, workspace `scripts/ci/`

package/src/guards/config.ts

@@ -0,0 +1,163 @@
+/**
+ * Guard Configuration Vocabulary
+ *
+ * Polymorphic configuration types that allow guard implementations
+ * to be reused across repos with different settings.
+ *
+ * Design principle: Configuration is data, not code.
+ * Each repo provides its own config values; shared guards consume them.
+ */
+
+import type { GuardTier, CheckResult } from './types.js';
+
+// =============================================================================
+// Size Limits
+// =============================================================================
+
+/**
+ * Three-tier size limit for a file role.
+ * - target: Ideal maximum (for new code)
+ * - warning: Soft limit (CI warns but passes)
+ * - hard: Hard limit (CI fails)
+ */
+export interface RoleLimit {
+  target: number;
+  warning: number;
+  hard: number;
+}
+
+// =============================================================================
+// Guard Configuration
+// =============================================================================
+
+/**
+ * Configuration for guard checks.
+ * Repos provide their own values; shared guards consume polymorphically.
+ */
+export interface GuardConfig {
+  /**
+   * File size limits by role name.
+   * Keys are role names (e.g., 'Service', 'Component', 'Handler').
+   */
+  limits: Record<string, RoleLimit>;
+
+  /**
+   * Role detection patterns.
+   * Keys are role names, values are regex patterns as strings.
+   * Example: { 'Service': 'Service\\.ts$', 'Handler': 'Handler\\.ts$' }
+   */
+  rolePatterns: Record<string, string>;
+
+  /**
+   * Glob patterns for auto-exempt files.
+   * Files matching these are skipped by size/complexity checks.
+   * Example: ['index.ts', '*.generated.ts', '*.schema.ts']
+   */
+  exemptPatterns: string[];
+
+  /**
+   * README section requirements by semantic root role.
+   * Keys are role names (e.g., 'domain', 'infra').
+   * Values are required section headers.
+   */
+  semanticRootSections: Record<string, string[]>;
+
+  /**
+   * Universal size limit for files without a detected role.
+   * Applied when no rolePattern matches.
+   */
+  universalSizeLimit: number;
+
+  /**
+   * Universal warning threshold.
+   * Files above this but below universalSizeLimit get warnings.
+   */
+  universalWarningThreshold: number;
+
+  /**
+   * Export complexity thresholds.
+   * Files with more exports than these limits are flagged.
+   */
+  exportLimits?: {
+    warning: number;
+    error: number;
+  };
+
+  /**
+   * Import fanout thresholds.
+   * Files with more imports than these limits are flagged.
+   */
+  importLimits?: {
+    warning: number;
+    error: number;
+  };
+
+  /**
+   * Domain directories to check for READMEs.
+   * Example: ['src/domain', 'src/providers', 'src/interfaces']
+   */
+  domainDirectories?: string[];
+
+  /**
+   * Directories to skip when walking the file tree.
+   * Example: ['node_modules', 'dist', '.git']
+   */
+  skipDirectories?: string[];
+}
+
+// =============================================================================
+// Guard Check Signature
+// =============================================================================
+
+/**
+ * Signature for a guard check function.
+ * Guards receive the repo root and config, return structured results.
+ */
+export type GuardCheck = (
+  repoRoot: string,
+  config: GuardConfig
+) => Promise<CheckResult>;
+
+/**
+ * Signature for a guard check factory.
+ * Factories create check functions with optional overrides.
+ */
+export type GuardCheckFactory = (
+  overrides?: Partial<GuardConfig>
+) => GuardCheck;
+
+// =============================================================================
+// Default Values
+// =============================================================================
+
+/**
+ * Default directories to skip when walking file trees.
+ */
+export const DEFAULT_SKIP_DIRECTORIES = [
+  'node_modules',
+  'dist',
+  '.git',
+  '.next',
+  'coverage',
+  '.tsbuild',
+];
+
+/**
+ * Default README sections for domain directories.
+ */
+export const DEFAULT_DOMAIN_SECTIONS = [
+  'Purpose',
+  'Invariants',
+  'Public API',
+  'Dependencies',
+];
+
+/**
+ * Default README sections for infrastructure directories.
+ */
+export const DEFAULT_INFRA_SECTIONS = [
+  'Purpose',
+  'How it works',
+  'Integration',
+  'Maintenance',
+];

package/src/guards/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Guard Types Barrel
+ *
+ * Re-exports all guard vocabulary types.
+ * Import from '@company-semantics/contracts/guards' or '@company-semantics/contracts'.
+ *
+ * Note: This module exports types only (no runtime code per contracts policy).
+ * Helper functions for working with these types live in workspace scripts.
+ */
+
+// Types
+export type {
+  GuardMessage,
+  GuardTierResult,
+  GuardTier,
+  GuardResults,
+  CheckResult,
+  GuardOutput,
+} from './types.js';
+
+// Constants (these are type-level, not runtime)
+export { GUARD_SCHEMA_VERSION, GUARD_TIERS } from './types.js';
+
+// Config types
+export type {
+  RoleLimit,
+  GuardConfig,
+  GuardCheck,
+  GuardCheckFactory,
+} from './config.js';
+
+// Config constants (type-level defaults)
+export {
+  DEFAULT_SKIP_DIRECTORIES,
+  DEFAULT_DOMAIN_SECTIONS,
+  DEFAULT_INFRA_SECTIONS,
+} from './config.js';

package/src/guards/types.ts

@@ -0,0 +1,121 @@
+/**
+ * Guard Type Vocabulary (v2.0.0)
+ *
+ * Canonical types for CI guard output across all Company Semantics repos.
+ * These types define the contract between guard implementations and consumers.
+ *
+ * Design invariants:
+ * - Tier awareness is preserved end-to-end (no flattening)
+ * - CheckResult shape matches aggregation needs (errors/warnings separated)
+ * - GuardOutput envelope is JSON-serializable for CI integration
+ *
+ * @see schemas/guard-result.schema.json for JSON Schema
+ */
+
+// =============================================================================
+// Message Types
+// =============================================================================
+
+/**
+ * A single guard message (error or warning).
+ * The atomic unit of guard output.
+ */
+export interface GuardMessage {
+  /** Path to the file with the issue (relative to repo root) */
+  file: string;
+  /** Human-readable description of the issue */
+  message: string;
+  /** Line number where the issue occurs (when available) */
+  line?: number;
+  /** Rule identifier that triggered this message (e.g., 'file-size', 'readme') */
+  rule?: string;
+}
+
+// =============================================================================
+// Tier Types
+// =============================================================================
+
+/**
+ * Result for a single tier (errors + warnings).
+ */
+export interface GuardTierResult {
+  errors: GuardMessage[];
+  warnings: GuardMessage[];
+}
+
+/**
+ * Guard tier names.
+ * Ordered by enforcement phase:
+ * - structural: file sizes, READMEs, naming (fast, syntactic)
+ * - behavioral: import layers, dependencies (semantic)
+ * - invariants: domain rules, trust boundaries (business logic)
+ * - evolution: uncovered patterns, growth tracking (observational)
+ */
+export type GuardTier = 'structural' | 'behavioral' | 'invariants' | 'evolution';
+
+/**
+ * Full guard results, organized by tier.
+ * Preserves tier awareness for reporting and filtering.
+ */
+export type GuardResults = {
+  [K in GuardTier]: GuardTierResult;
+};
+
+// =============================================================================
+// Check Types (for guard implementations)
+// =============================================================================
+
+/**
+ * Result from a single guard check.
+ * Designed for clean aggregation into GuardResults.
+ */
+export interface CheckResult {
+  /** Which tier this check belongs to */
+  tier: GuardTier;
+  /** Rule identifier (e.g., 'file-size', 'readme-sections') */
+  rule: string;
+  /** Errors that should fail CI */
+  errors: GuardMessage[];
+  /** Warnings that should be reported but not fail CI */
+  warnings: GuardMessage[];
+  /** Informational messages (optional, for observability) */
+  info?: GuardMessage[];
+}
+
+// =============================================================================
+// JSON Output Envelope
+// =============================================================================
+
+/**
+ * JSON output envelope for --json mode.
+ * This is the top-level structure emitted by guard tools.
+ *
+ * Invariant: results are tiered, not flattened.
+ */
+export interface GuardOutput {
+  /** Guard tool name (e.g., 'architecture-guard', 'vocabulary-guard') */
+  tool: string;
+  /** Schema version (not tool version). Bump on breaking schema changes. */
+  schemaVersion: string;
+  /** ISO 8601 timestamp of when the guard ran */
+  timestamp: string;
+  /** Tiered results preserving full structure */
+  results: GuardResults;
+}
+
+/**
+ * Current schema version.
+ * v2.0.0: Tiered results (breaking change from v1.x flattened structure)
+ */
+export const GUARD_SCHEMA_VERSION = '2.0.0';
+
+/**
+ * All guard tiers in order.
+ * Useful for iteration when aggregating results.
+ */
+export const GUARD_TIERS: readonly GuardTier[] = [
+  'structural',
+  'behavioral',
+  'invariants',
+  'evolution',
+] as const;

package/src/index.ts

@@ -39,3 +39,26 @@ export type {
   DiagramSpec,
   DiagramSnapshot,
 } from './system/index.js'
+
+// Guard types (CI guard vocabulary)
+// @see schemas/guard-result.schema.json for JSON Schema
+export type {
+  GuardMessage,
+  GuardTierResult,
+  GuardTier,
+  GuardResults,
+  CheckResult,
+  GuardOutput,
+  RoleLimit,
+  GuardConfig,
+  GuardCheck,
+  GuardCheckFactory,
+} from './guards/index.js'
+
+export {
+  GUARD_SCHEMA_VERSION,
+  GUARD_TIERS,
+  DEFAULT_SKIP_DIRECTORIES,
+  DEFAULT_DOMAIN_SECTIONS,
+  DEFAULT_INFRA_SECTIONS,
+} from './guards/index.js'