@company-semantics/contracts 0.25.1 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.25.1",
+  "version": "0.26.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -53,6 +53,8 @@
     "guard:scripts-deps": "npx tsx scripts/ci/scripts-deps-guard.ts",
     "guard:version-tag": "npx tsx scripts/ci/version-tag-guard.ts",
     "guard:version-tag:json": "npx tsx scripts/ci/version-tag-guard.ts --json",
+    "guard:decisions-deprecation": "npx tsx scripts/ci/decisions-deprecation-guard.ts",
+    "guard:decisions-deprecation:json": "npx tsx scripts/ci/decisions-deprecation-guard.ts --json",
     "guard:test": "vitest run scripts/ci/__tests__",
     "release": "npx tsx scripts/release.ts",
     "prepublishOnly": "echo 'ERROR: Publishing is CI-only via tag push. Use pnpm release instead.' && exit 1",

package/src/guards/config.ts

@@ -8,7 +8,7 @@
  * Each repo provides its own config values; shared guards consume them.
  */
 
-import type { CheckResult } from './types.js';
+import type { CheckResult, Soc2ControlArea } from './types.js';
 
 // =============================================================================
 // Size Limits
@@ -376,6 +376,115 @@ export interface SubdirectoryAffinityBaseline {
   ignoredDirectories?: string[];
 }
 
+// =============================================================================
+// SOC 2 Guard Configuration Types
+// =============================================================================
+
+/**
+ * Configuration for the secrets detection guard.
+ * This is a blocking control for SOC 2 Access Control (AC).
+ */
+export interface SecretsDetectionConfig {
+  /** Source directory to scan (relative to repo root) */
+  srcDir?: string;
+  /** Additional directories to scan */
+  additionalDirs?: string[];
+  /** File patterns to exclude (globs) */
+  excludePatterns?: string[];
+  /** Additional secret patterns to detect (regex strings) */
+  additionalPatterns?: string[];
+}
+
+/**
+ * Configuration for the structured logging guard.
+ * This is a non-blocking control for SOC 2 Logging & Monitoring (LM).
+ */
+export interface StructuredLoggingConfig {
+  /** Entry point files to check (relative to repo root) */
+  entryPoints?: string[];
+  /** Source directory to scan for logging (fallback if no entry points) */
+  srcDir?: string;
+  /** Recognized logging libraries */
+  loggingLibraries?: string[];
+  /** Logger instantiation patterns (regex strings) */
+  instantiationPatterns?: string[];
+}
+
+/**
+ * Configuration for the alerts config guard.
+ * This is a non-blocking control for SOC 2 Logging & Monitoring (LM).
+ */
+export interface AlertsConfigGuardConfig {
+  /**
+   * Files or directories to check for alerting configuration.
+   * Supports both file paths and directory paths.
+   */
+  files?: string[];
+  /**
+   * Whether this check should be skipped.
+   * Use for repos that don't have alerting (e.g., pure libraries).
+   */
+  skip?: boolean;
+  /**
+   * Evidence string when alerting is explicitly skipped.
+   */
+  skipEvidence?: string;
+}
+
+/**
+ * Configuration for the backup config guard.
+ * This is a non-blocking control for SOC 2 Backup & Recovery (BR).
+ */
+export interface BackupConfigGuardConfig {
+  /**
+   * Files or directories to check for backup configuration.
+   */
+  files?: string[];
+  /**
+   * Whether this check should be skipped.
+   * Use for repos that don't manage backups (e.g., frontend-only).
+   */
+  skip?: boolean;
+  /**
+   * Evidence string when backup check is explicitly skipped.
+   */
+  skipEvidence?: string;
+}
+
+/**
+ * SOC 2 compliance baselines.
+ * Configures SOC 2 control guards for a repository.
+ *
+ * Design: Product repos provide data only; CI orchestrator owns guard implementations.
+ */
+export interface Soc2Baselines {
+  /** Enable SOC 2 compliance reporting */
+  enabled?: boolean;
+  /** Advisory mode: all controls become non-blocking for visibility-only rollout */
+  advisoryMode?: boolean;
+  /** Repository name (for evidence) */
+  repository?: string;
+  /** Secrets detection configuration */
+  secretsDetection?: SecretsDetectionConfig;
+  /** Structured logging configuration */
+  structuredLogging?: StructuredLoggingConfig;
+  /** Alerts config configuration */
+  alertsConfig?: AlertsConfigGuardConfig;
+  /** Backup config configuration */
+  backupConfig?: BackupConfigGuardConfig;
+  /** Controls to explicitly skip (with evidence) */
+  skipControls?: {
+    area: Soc2ControlArea;
+    evidence: string;
+  }[];
+  /**
+   * Controls that remain blocking even in advisory mode.
+   * Use to gradually promote controls from advisory to blocking.
+   * Example: ['AC'] to make secrets-detection blocking first.
+   */
+  alwaysBlockingControls?: Soc2ControlArea[];
+}
+
 /**
  * Registry of checks grouped by tier.
  * Each repo exports this from guard-entries.ts for universal orchestration.

package/src/guards/index.ts

@@ -54,6 +54,12 @@ export type {
   FileClusterBaseline,
   SubdirectoryAffinityBaseline,
   MetaBaselines,
+  // SOC 2 Guard Configuration types
+  SecretsDetectionConfig,
+  StructuredLoggingConfig,
+  AlertsConfigGuardConfig,
+  BackupConfigGuardConfig,
+  Soc2Baselines,
 } from './config.js';
 
 // Config constants (type-level defaults)

package/src/index.ts

@@ -70,6 +70,17 @@ export type {
   ContractsFreshnessBaseline,
   CoverageBaseline,
   MetaBaselines,
+  // SOC 2 Compliance types
+  Soc2ControlArea,
+  Soc2ControlStatus,
+  Soc2ControlResult,
+  Soc2ComplianceOutput,
+  // SOC 2 Guard Configuration types
+  SecretsDetectionConfig,
+  StructuredLoggingConfig,
+  AlertsConfigGuardConfig,
+  BackupConfigGuardConfig,
+  Soc2Baselines,
 } from './guards/index.js'
 
 export {
@@ -78,6 +89,11 @@ export {
   DEFAULT_SKIP_DIRECTORIES,
   DEFAULT_DOMAIN_SECTIONS,
   DEFAULT_INFRA_SECTIONS,
+  // SOC 2 Compliance constants
+  SOC2_CONTROL_NAMES,
+  REQUIRED_SOC2_CONTROLS,
+  BLOCKING_SOC2_CONTROLS,
+  SOC2_SCHEMA_VERSION,
 } from './guards/index.js'
 
 // Compatibility manifest (CI guard vocabulary)