@company-semantics/contracts 0.18.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -46,6 +46,7 @@
     "guard:version-tag:json": "npx tsx scripts/ci/version-tag-guard.ts --json",
     "guard:test": "vitest run scripts/ci/__tests__",
     "release": "npx tsx scripts/release.ts",
+    "prepublishOnly": "pnpm guard:version-tag",
     "test": "vitest run scripts/ci/__tests__"
   },
   "packageManager": "pnpm@10.25.0",

package/src/guards/config.ts

@@ -281,6 +281,26 @@ export interface EvolutionBaselines {
    * @see ADR-2025-12-014
    */
   contractsFreshness?: ContractsFreshnessBaseline;
+
+  /**
+   * Coverage drift check configuration.
+   * CI injects checkCoverageDrift based on this config.
+   * Errors when coverage drops below baseline (enforced).
+   */
+  coverage?: CoverageBaseline;
+}
+
+/**
+ * Coverage baseline configuration.
+ * Used by CI orchestrator to inject coverage drift guard.
+ */
+export interface CoverageBaseline {
+  /** Path to coverage-summary.json (default: 'coverage/coverage-summary.json') */
+  coverageFile?: string;
+  /** Baseline coverage percentage (lines) */
+  baseline: number;
+  /** Allowed drop threshold before error (default: 0 = any drop errors) */
+  dropThreshold?: number;
 }
 
 /**

package/src/guards/index.ts

@@ -18,10 +18,23 @@ export type {
   GuardOutput,
   KnownVulnerability,
   VulnerabilityConfig,
+  // SOC 2 Compliance types
+  Soc2ControlArea,
+  Soc2ControlStatus,
+  Soc2ControlResult,
+  Soc2ComplianceOutput,
 } from './types.js';
 
 // Constants (these are type-level, not runtime)
-export { GUARD_SCHEMA_VERSION, GUARD_TIERS } from './types.js';
+export {
+  GUARD_SCHEMA_VERSION,
+  GUARD_TIERS,
+  // SOC 2 Compliance constants
+  SOC2_CONTROL_NAMES,
+  REQUIRED_SOC2_CONTROLS,
+  BLOCKING_SOC2_CONTROLS,
+  SOC2_SCHEMA_VERSION,
+} from './types.js';
 
 // Config types
 export type {
@@ -36,6 +49,7 @@ export type {
   VulnerabilitiesBaseline,
   EvolutionBaselines,
   ContractsFreshnessBaseline,
+  CoverageBaseline,
   MetaBaselines,
 } from './config.js';
 

package/src/guards/types.ts

@@ -158,3 +158,114 @@ export interface VulnerabilityConfig {
   /** Baseline of known/accepted vulnerabilities (grandfathered) */
   knownVulnerabilities?: KnownVulnerability[];
 }
+
+// =============================================================================
+// SOC 2 Compliance Types
+// =============================================================================
+
+/**
+ * SOC 2 control area identifiers.
+ * - CM: Change Management
+ * - AC: Access Control
+ * - LM: Logging & Monitoring
+ * - SD: Secure SDLC
+ * - BR: Backup & Recovery
+ */
+export type Soc2ControlArea = 'CM' | 'AC' | 'LM' | 'SD' | 'BR';
+
+/**
+ * Control status semantics:
+ * - PASS: Control asserted and within bounds
+ * - WARN: Control exists but has drift/open findings
+ * - FAIL: Control invariant broken
+ * - SKIP: Control explicitly out-of-scope for this repo (requires evidence)
+ *
+ * SKIP rules:
+ * - Must include an evidence string explaining why out-of-scope
+ * - Is never blocking
+ * - Must be explicit (configured in soc2Baselines), not implicit
+ */
+export type Soc2ControlStatus = 'PASS' | 'WARN' | 'FAIL' | 'SKIP';
+
+/**
+ * Human-readable names for SOC 2 control areas.
+ */
+export const SOC2_CONTROL_NAMES: Record<Soc2ControlArea, string> = {
+  CM: 'Change Management',
+  AC: 'Access Control',
+  LM: 'Logging & Monitoring',
+  SD: 'Secure SDLC',
+  BR: 'Backup & Recovery',
+} as const;
+
+/**
+ * All required SOC 2 controls.
+ * Aggregator fails if any control is missing from the output.
+ */
+export const REQUIRED_SOC2_CONTROLS: readonly Soc2ControlArea[] = [
+  'CM',
+  'AC',
+  'LM',
+  'SD',
+  'BR',
+] as const;
+
+/**
+ * Controls that block CI when status is FAIL.
+ * Non-blocking controls report FAIL but don't set exit code to 1.
+ */
+export const BLOCKING_SOC2_CONTROLS: readonly Soc2ControlArea[] = ['CM', 'AC'] as const;
+
+/**
+ * A single SOC 2 control assertion result.
+ */
+export interface Soc2ControlResult {
+  /** Control area code (e.g., 'CM', 'AC') */
+  area: Soc2ControlArea;
+  /** Human-readable control name (e.g., 'Change Management') */
+  name: string;
+  /** Control status */
+  status: Soc2ControlStatus;
+  /**
+   * Evidence describes PROCESS or EXISTENCE, not outcomes.
+   * Good: "PR reviews enforced on main", "Backup config present"
+   * Bad: "Secure", "Compliant", "Safe"
+   */
+  evidence: string;
+  /** Whether this control blocks CI when status is FAIL */
+  blocking: boolean;
+  /**
+   * Control version for SOC 2 Type II audit trail.
+   * Increment when control definition changes materially.
+   */
+  controlVersion: number;
+  /** Underlying guard messages that contributed to this status (if any) */
+  messages?: GuardMessage[];
+}
+
+/**
+ * SOC 2 compliance snapshot output.
+ * This is the top-level structure emitted when --soc2 flag is used.
+ */
+export interface Soc2ComplianceOutput {
+  /** ISO 8601 timestamp of when the compliance check ran */
+  timestamp: string;
+  /** Repository name */
+  repository: string;
+  /** Git commit SHA */
+  commitSha: string;
+  /** CI run ID (if available) */
+  ciRunId?: string;
+  /** CI run URL (if available) */
+  ciRunUrl?: string;
+  /** All control results (must include all REQUIRED_SOC2_CONTROLS) */
+  controls: Soc2ControlResult[];
+  /** Overall pass/fail based on blocking controls only */
+  overallStatus: 'PASS' | 'FAIL';
+}
+
+/**
+ * Current SOC 2 compliance schema version.
+ * Bump on breaking schema changes.
+ */
+export const SOC2_SCHEMA_VERSION = '1.0.0';

package/src/index.ts

@@ -30,16 +30,23 @@ export type {
   SystemCapability,
   SystemLayer,
   SystemCapabilityManifest,
-  // Graph-based diagram spec (v0.18.0)
+  // Graph-based diagram spec (v0.19.0)
   DiagramNodeKind,
   DiagramEdgeRelation,
   EdgeDirection,
   FlowStage,
+  PipelinePhase,
   DiagramMode,
   DiagramNode,
   DiagramEdge,
   DiagramSpec,
   DiagramSnapshot,
+  // Repository capability types (v0.20.0)
+  RepoId,
+  CapabilityInvariants,
+  RepoCapability,
+  CapabilityManifest,
+  AggregatedCapabilities,
 } from './system/index.js'
 
 // Guard types (CI guard vocabulary)
@@ -61,6 +68,7 @@ export type {
   ScriptsDepsBaseline,
   EvolutionBaselines,
   ContractsFreshnessBaseline,
+  CoverageBaseline,
   MetaBaselines,
 } from './guards/index.js'
 

package/src/system/capabilities.ts

@@ -0,0 +1,139 @@
+/**
+ * Repository Capability Types
+ *
+ * Types for cross-repo capability registration and aggregation.
+ * Used by the system diagram to render repo-level features.
+ *
+ * Promoted from company-semantics-control/system-diagram/contracts/
+ *
+ * INVARIANTS:
+ * - RepoCapability is a strict superset of DiagramNode
+ * - Aggregation transforms RepoCapability → DiagramNode (validate + normalize only)
+ * - No semantic changes during aggregation
+ * - flowStage is required on repo-level nodes (primary organizing axis)
+ *
+ * @see ADR-CONTRACTS-NNN in DECISIONS.md
+ */
+
+import type { DiagramNode, FlowStage, FeatureStatus } from './index.js'
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Valid repository identifiers.
+ * Add new repos here as the system grows.
+ */
+export type RepoId =
+  | 'backend'
+  | 'edge'
+  | 'app'
+  | 'site'
+  | 'ci'
+  | 'contracts'
+  | 'control'
+
+/**
+ * Semantic invariants for a capability.
+ * Used for CI drift detection and diagram styling.
+ */
+export interface CapabilityInvariants {
+  /** Does this capability invoke LLM/AI APIs? */
+  llmCalls: boolean
+
+  /** Is this an authority boundary (trust/gateway)? */
+  authority: boolean
+
+  /** Can this capability write to strategy/goals? */
+  writesStrategy: boolean
+}
+
+/**
+ * Repository Capability
+ *
+ * Extends DiagramNode with repo-specific fields.
+ * This is what each repo declares in their capabilities.ts.
+ *
+ * CRITICAL: This extends DiagramNode — do NOT add fields that duplicate
+ * or conflict with DiagramNode fields.
+ */
+export interface RepoCapability extends DiagramNode {
+  /**
+   * Which repository owns this capability.
+   * Used for aggregation grouping and validation.
+   */
+  repo: RepoId
+
+  /**
+   * Whether this capability should appear in public diagrams.
+   * - true: visible on marketing site, docs
+   * - false: internal only, visible in app
+   */
+  public: boolean
+
+  /**
+   * Architecture layer for horizontal organization.
+   * Required for repo-level nodes. The primary organizing axis.
+   * Children inherit unless explicitly overridden.
+   */
+  flowStage?: FlowStage
+
+  /**
+   * Stage-level edges for flow projection.
+   * References other capability IDs in format: `repo:domain:capability`
+   *
+   * Example: ['backend:semantic:processing', 'backend:graph:storage']
+   */
+  flowsTo?: string[]
+
+  /**
+   * Whether this capability is exported at the architecture level.
+   * Exported capabilities represent repo boundaries and API surfaces.
+   * Visible in 'architecture' mode.
+   */
+  exported?: boolean
+
+  /**
+   * Semantic invariants for CI validation.
+   * Optional - defaults applied per-repo during aggregation.
+   */
+  invariants?: Partial<CapabilityInvariants>
+}
+
+/**
+ * Manifest of capabilities from a single repository.
+ *
+ * NOTE: No version field — add when actually needed for:
+ * - CI compatibility checks
+ * - Schema evolution
+ * - Breaking capability changes
+ */
+export interface CapabilityManifest {
+  /** Which repository this manifest is from */
+  repo: RepoId
+
+  /** All capabilities declared by this repo */
+  capabilities: RepoCapability[]
+}
+
+/**
+ * Aggregated capabilities from all repositories.
+ * Output of the aggregation step.
+ */
+export interface AggregatedCapabilities {
+  /** All capabilities from all repos, validated */
+  capabilities: RepoCapability[]
+
+  /** Which repos contributed to this aggregation */
+  repos: RepoId[]
+
+  /** ISO timestamp of aggregation */
+  aggregatedAt: string
+}
+
+// =============================================================================
+// Re-exports for convenience
+// =============================================================================
+
+export type { FeatureStatus, FlowStage }

package/src/system/diagram.ts

@@ -88,6 +88,20 @@ export type FlowStage =
   | 'evaluation'  // EVALUATION, GUIDANCE, & AGENTS (MCP)
   | 'governance'  // CI / GOVERNANCE
 
+/**
+ * Data lifecycle phase for coloring/filtering.
+ * Secondary annotation — does not affect layout.
+ *
+ * v0.19.0: New type for pipeline visualization
+ */
+export type PipelinePhase =
+  | 'source'     // External data origin
+  | 'ingest'     // Data collection and intake
+  | 'normalize'  // Schema alignment and transformation
+  | 'evaluate'   // Analysis and decision-making
+  | 'store'      // Persistence and retrieval
+  | 'surface'    // Presentation and delivery
+
 /**
  * Diagram projection modes.
  * One graph, filtered by mode.

package/src/system/index.ts

@@ -1,5 +1,5 @@
 /**
- * System Diagram Types (v0.18.0)
+ * System Diagram Types (v0.19.0)
  *
  * Schema for the system diagram feature.
  * These types define the contract between:
@@ -11,6 +11,7 @@
  *   - Site displays interactive React Flow diagram
  *   - Snapshots pushed via CI automation
  *
+ * v0.19.0: PipelinePhase annotation for data lifecycle visualization
  * v0.18.0: Semantic architecture diagram transformation
  *   - Edge semantics (invokes, emits, authorizes, reads)
  *   - FlowStage for architecture layers
@@ -72,9 +73,19 @@ export type {
   DiagramEdgeRelation,
   EdgeDirection,
   FlowStage,
+  PipelinePhase,
   DiagramMode,
   DiagramNode,
   DiagramEdge,
   DiagramSpec,
   DiagramSnapshot,
 } from './diagram.js'
+
+// Repository capability types
+export type {
+  RepoId,
+  CapabilityInvariants,
+  RepoCapability,
+  CapabilityManifest,
+  AggregatedCapabilities,
+} from './capabilities.js'