@neurcode-ai/governance-runtime 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neurcode-ai/governance-runtime",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Deterministic plan/diff governance runtime shared by CLI, API, and integrations",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/constraints.ts

@@ -7,13 +7,22 @@ export interface DeterministicConstraintRule {
   displayName: string;
   pattern: RegExp;
   matchToken: string;
+  provenance?: DeterministicConstraintProvenance;
   pathIncludePatterns?: string[];
   pathExcludePatterns?: string[];
   pathIncludes?: RegExp[];
   pathExcludes?: RegExp[];
   minMatchesPerFile?: number;
   maxMatchesPerFile?: number;
-  evaluationMode?: 'added_lines' | 'full_file';
+  evaluationMode?: 'added_lines' | 'full_file' | 'signature_delta';
+  evaluationScope?: 'file' | 'repo';
+}
+
+export interface DeterministicConstraintProvenance {
+  why: string;
+  evidence: string[];
+  contributingGraphPaths: string[];
+  trustBoundaries: string[];
 }
 
 export interface DeterministicConstraintCompilation {
@@ -34,6 +43,11 @@ interface ConstraintTemplate {
   matchToken: string;
 }
 
+interface PathScopeMatch {
+  includePatterns: string[];
+  excludePatterns: string[];
+}
+
 const PROHIBITIVE_PATTERN = /\b(no|do not|don't|without|avoid|ban|disallow|never|must not)\b/i;
 
 const CONSTRAINT_TEMPLATES: ConstraintTemplate[] = [
@@ -160,10 +174,7 @@ function compilePathPatterns(patterns: string[]): RegExp[] {
     .filter((item): item is RegExp => item instanceof RegExp);
 }
 
-function parsePathScopes(statement: string): {
-  includePatterns: string[];
-  excludePatterns: string[];
-} {
+function parsePathScopes(statement: string): PathScopeMatch {
   const includePatterns = new Set<string>();
   const excludePatterns = new Set<string>();
 
@@ -189,6 +200,51 @@ function parsePathScopes(statement: string): {
   };
 }
 
+function uniqueSorted(values: string[]): string[] {
+  return [...new Set(values.filter(Boolean))].sort((left, right) => left.localeCompare(right));
+}
+
+function buildProvenance(input: {
+  why: string;
+  evidence: string[];
+  trustBoundaries: string[];
+  pathScopes: PathScopeMatch;
+}): DeterministicConstraintProvenance {
+  const contributingGraphPaths = input.pathScopes.includePatterns.length > 0
+    ? uniqueSorted(input.pathScopes.includePatterns)
+    : ['<repo-scope>'];
+  return {
+    why: input.why,
+    evidence: uniqueSorted(input.evidence),
+    contributingGraphPaths,
+    trustBoundaries: uniqueSorted(input.trustBoundaries),
+  };
+}
+
+function applyPathScopes(
+  rule: Omit<DeterministicConstraintRule, 'pathIncludePatterns' | 'pathExcludePatterns' | 'pathIncludes' | 'pathExcludes'>,
+  pathScopes: PathScopeMatch
+): DeterministicConstraintRule {
+  const includePatterns = [...pathScopes.includePatterns];
+  const excludePatterns = [...pathScopes.excludePatterns];
+
+  return {
+    ...rule,
+    ...(includePatterns.length > 0
+      ? {
+          pathIncludePatterns: includePatterns,
+          pathIncludes: compilePathPatterns(includePatterns),
+        }
+      : {}),
+    ...(excludePatterns.length > 0
+      ? {
+          pathExcludePatterns: excludePatterns,
+          pathExcludes: compilePathPatterns(excludePatterns),
+        }
+      : {}),
+  };
+}
+
 function escapeRegex(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -196,7 +252,7 @@ function escapeRegex(value: string): string {
 function parseInvocationLimitRule(
   statement: string,
   source: DeterministicConstraintSource,
-  pathScopes: { includePatterns: string[]; excludePatterns: string[] }
+  pathScopes: PathScopeMatch
 ): DeterministicConstraintRule | null {
   const normalized = normalizeStatement(statement);
 
@@ -279,8 +335,9 @@ function parseInvocationLimitRule(
     return null;
   }
 
-  const includePatterns = [...pathScopes.includePatterns];
-  const excludePatterns = [...pathScopes.excludePatterns];
+  const repoScopeHint = /\b(across\s+(?:the\s+)?(?:repo|repository|codebase)|globally|in\s+the\s+entire\s+repo)\b/i.test(
+    normalized
+  );
   const displaySuffix =
     comparator === 'exact'
       ? `exactly ${limit}`
@@ -290,29 +347,324 @@ function parseInvocationLimitRule(
   const minMatches = comparator === 'min' || comparator === 'exact' ? limit : undefined;
   const maxMatches = comparator === 'max' || comparator === 'exact' ? limit : undefined;
 
-  return {
-    id: `${source}:${comparator}_invocations_${fnName.toLowerCase()}`,
-    source,
-    statement,
-    displayName: `${fnName}() invocation limit (${displaySuffix})`,
-    pattern: new RegExp(`(?<!function\\s)\\b${escapeRegex(fnName)}\\s*\\(`, 'i'),
-    matchToken: `${fnName}(`,
-    ...(typeof minMatches === 'number' ? { minMatchesPerFile: minMatches } : {}),
-    ...(typeof maxMatches === 'number' ? { maxMatchesPerFile: maxMatches } : {}),
-    evaluationMode: 'full_file',
-    ...(includePatterns.length > 0
-      ? {
-          pathIncludePatterns: includePatterns,
-          pathIncludes: compilePathPatterns(includePatterns),
-        }
-      : {}),
-    ...(excludePatterns.length > 0
-      ? {
-          pathExcludePatterns: excludePatterns,
-          pathExcludes: compilePathPatterns(excludePatterns),
-        }
-      : {}),
-  };
+  return applyPathScopes(
+    {
+      id: `${source}:${comparator}_invocations_${fnName.toLowerCase()}${repoScopeHint ? '_repo' : ''}`,
+      source,
+      statement,
+      displayName: `${fnName}() invocation limit (${displaySuffix}${repoScopeHint ? ', repo-wide' : ''})`,
+      pattern: new RegExp(`(?<!function\\s)\\b${escapeRegex(fnName)}\\s*\\(`, 'i'),
+      matchToken: `${fnName}(`,
+      ...(typeof minMatches === 'number' ? { minMatchesPerFile: minMatches } : {}),
+      ...(typeof maxMatches === 'number' ? { maxMatchesPerFile: maxMatches } : {}),
+      evaluationMode: 'full_file',
+      evaluationScope: repoScopeHint ? 'repo' : 'file',
+      provenance: buildProvenance({
+        why: 'Statement imposes deterministic invocation cardinality limits.',
+        evidence: [fnName, rawLimit, comparator, repoScopeHint ? 'repo-scope' : 'file-scope'],
+        trustBoundaries: repoScopeHint ? ['cross-module'] : ['local-module'],
+        pathScopes,
+      }),
+    },
+    pathScopes
+  );
+}
+
+const EXPORTED_SIGNATURE_PATTERN =
+  /\bexport\s+(?:async\s+)?function\s+[A-Za-z_$][A-Za-z0-9_$]*\s*\(|\bexport\s+const\s+[A-Za-z_$][A-Za-z0-9_$]*\s*=\s*(?:async\s*)?\([^)]*\)\s*=>|\bexport\s+(?:interface|type)\s+[A-Za-z_$][A-Za-z0-9_$]*/i;
+
+function parseSignatureDriftRule(
+  statement: string,
+  source: DeterministicConstraintSource,
+  pathScopes: PathScopeMatch
+): DeterministicConstraintRule | null {
+  const normalized = normalizeStatement(statement);
+  const mentionsSignature =
+    /\b(signature|contract|public api|api surface|exported api)\b/i.test(normalized);
+  const mentionsChange =
+    /\b(change|changed|modify|modified|drift|mutation|alter)\b/i.test(normalized);
+  const prohibitive =
+    PROHIBITIVE_PATTERN.test(normalized)
+    || /\bkeep\b/i.test(normalized)
+    || /\bpreserve\b/i.test(normalized);
+
+  if (!mentionsSignature || !mentionsChange || !prohibitive) {
+    return null;
+  }
+
+  return applyPathScopes(
+    {
+      id: `${source}:no_api_signature_drift`,
+      source,
+      statement,
+      displayName: 'No exported API signature drift',
+      pattern: EXPORTED_SIGNATURE_PATTERN,
+      matchToken: 'api-signature-drift',
+      evaluationMode: 'signature_delta',
+      evaluationScope: 'file',
+      provenance: buildProvenance({
+        why: 'Statement protects external API signature stability.',
+        evidence: ['signature', 'public api', 'change/modify'],
+        trustBoundaries: ['public-api', 'external-consumer'],
+        pathScopes,
+      }),
+    },
+    pathScopes
+  );
+}
+
+function parseBackwardCompatibilityRule(
+  statement: string,
+  source: DeterministicConstraintSource,
+  pathScopes: PathScopeMatch
+): DeterministicConstraintRule | null {
+  const normalized = normalizeStatement(statement);
+  const mentionsCompatibility =
+    /\b(backward compatibility|backwards compatibility|breaking change|non-breaking|existing consumers?)\b/i.test(
+      normalized
+    );
+
+  if (!mentionsCompatibility) {
+    return null;
+  }
+
+  return applyPathScopes(
+    {
+      id: `${source}:backward_compatibility`,
+      source,
+      statement,
+      displayName: 'Backward compatibility guard (public contract drift)',
+      pattern: EXPORTED_SIGNATURE_PATTERN,
+      matchToken: 'backward-compatibility',
+      evaluationMode: 'signature_delta',
+      evaluationScope: 'file',
+      provenance: buildProvenance({
+        why: 'Statement requires non-breaking compatibility guarantees for existing consumers.',
+        evidence: ['backward compatibility', 'breaking change', 'existing consumers'],
+        trustBoundaries: ['public-api', 'external-consumer'],
+        pathScopes,
+      }),
+    },
+    pathScopes
+  );
+}
+
+function parseAsyncOrderingRule(
+  statement: string,
+  source: DeterministicConstraintSource,
+  pathScopes: PathScopeMatch
+): DeterministicConstraintRule | null {
+  const normalized = normalizeStatement(statement);
+  const mentionsOrdering =
+    /\b(async ordering|message ordering|out of order|preserve order|ordered workflow|ordering guarantees?|fifo)\b/i.test(
+      normalized
+    );
+  const mentionsParallelRisk =
+    /\b(parallel|promise\.all|allsettled|race|fan-?out|parallelize)\b/i.test(normalized);
+
+  if (!mentionsOrdering && !mentionsParallelRisk) {
+    return null;
+  }
+
+  return applyPathScopes(
+    {
+      id: `${source}:async_ordering`,
+      source,
+      statement,
+      displayName: 'Async ordering guard (parallelization risk)',
+      pattern: /\bPromise\.(?:all|allSettled|race|any)\s*\(|\bp-?map\s*\(|\bparallel(?:ize|Map)?\s*\(/i,
+      matchToken: 'async-ordering',
+      evaluationMode: 'added_lines',
+      evaluationScope: 'file',
+      provenance: buildProvenance({
+        why: 'Statement flags async ordering sensitivity and blocks risky parallel fan-out patterns.',
+        evidence: ['ordering', 'out of order', 'parallel execution'],
+        trustBoundaries: ['async-workflow', 'downstream-capacity'],
+        pathScopes,
+      }),
+    },
+    pathScopes
+  );
+}
+
+function parseEventSchemaConsistencyRule(
+  statement: string,
+  source: DeterministicConstraintSource,
+  pathScopes: PathScopeMatch
+): DeterministicConstraintRule | null {
+  const normalized = normalizeStatement(statement);
+  const mentionsEventSchema =
+    /\b(event schema|event payload|event contract|subscriber|downstream event|schema evolution|required fields?)\b/i.test(
+      normalized
+    );
+
+  if (!mentionsEventSchema) {
+    return null;
+  }
+
+  return applyPathScopes(
+    {
+      id: `${source}:event_schema_consistency`,
+      source,
+      statement,
+      displayName: 'Event/schema consistency guard',
+      pattern:
+        /\b(?:interface|type)\s+[A-Za-z_$][A-Za-z0-9_$]*(?:Event|Payload|Message|Envelope)\b|\bevent[A-Za-z0-9_$]*\s*:\s*|\bschemaVersion\b/i,
+      matchToken: 'event-schema-drift',
+      evaluationMode: 'signature_delta',
+      evaluationScope: 'file',
+      provenance: buildProvenance({
+        why: 'Statement requires event contract continuity for downstream consumers.',
+        evidence: ['event schema', 'subscriber', 'required fields'],
+        trustBoundaries: ['event-bus', 'external-subscriber'],
+        pathScopes,
+      }),
+    },
+    pathScopes
+  );
+}
+
+function parseMultiTenantIsolationRule(
+  statement: string,
+  source: DeterministicConstraintSource,
+  pathScopes: PathScopeMatch
+): DeterministicConstraintRule | null {
+  const normalized = normalizeStatement(statement);
+  const mentionsTenantIsolation =
+    /\b(multi-tenant|tenant isolation|cross-tenant|tenant boundaries?|tenant_id|tenant guard)\b/i.test(normalized);
+
+  if (!mentionsTenantIsolation) {
+    return null;
+  }
+
+  return applyPathScopes(
+    {
+      id: `${source}:multi_tenant_isolation`,
+      source,
+      statement,
+      displayName: 'Multi-tenant isolation guard',
+      pattern:
+        /\b(?:bypassTenant(?:Guard|Scope)?|ignoreTenant(?:Scope)?|crossTenant|allTenants|tenantScope\s*:\s*false|setTenantContext\s*\(\s*null\s*\)|withoutTenantScope)\b/i,
+      matchToken: 'tenant-isolation',
+      evaluationMode: 'full_file',
+      evaluationScope: 'file',
+      provenance: buildProvenance({
+        why: 'Statement enforces tenant boundary safety and isolation constraints.',
+        evidence: ['multi-tenant', 'tenant_id', 'cross-tenant'],
+        trustBoundaries: ['tenant-boundary', 'data-access-layer'],
+        pathScopes,
+      }),
+    },
+    pathScopes
+  );
+}
+
+function parseCacheInvariantRule(
+  statement: string,
+  source: DeterministicConstraintSource,
+  pathScopes: PathScopeMatch
+): DeterministicConstraintRule | null {
+  const normalized = normalizeStatement(statement);
+  const mentionsCache = /\b(cache invalidation|cache invariant|cache keys?|cache consistency|evict cache|clear(?:ing)? (?:shared )?cache|shared cache|invalidate .*cache)\b/i.test(
+    normalized
+  );
+
+  if (!mentionsCache) {
+    return null;
+  }
+
+  return applyPathScopes(
+    {
+      id: `${source}:cache_invariant`,
+      source,
+      statement,
+      displayName: 'Cache invariant guard (global invalidation risk)',
+      pattern:
+        /\b(?:cache\.(?:clear|reset)\s*\(\s*\)|invalidateAll\s*\(|flushAll\s*\(|redis\.flush(?:all|db)\s*\(|\bFLUSH(?:ALL|DB)\b)\b/i,
+      matchToken: 'cache-invariant',
+      evaluationMode: 'added_lines',
+      evaluationScope: 'file',
+      provenance: buildProvenance({
+        why: 'Statement marks cache behavior as operationally sensitive and blocks global flush patterns.',
+        evidence: ['cache invalidation', 'cache key', 'clear cache'],
+        trustBoundaries: ['cache-layer', 'operational-safety'],
+        pathScopes,
+      }),
+    },
+    pathScopes
+  );
+}
+
+function parseIdempotencyRule(
+  statement: string,
+  source: DeterministicConstraintSource,
+  pathScopes: PathScopeMatch
+): DeterministicConstraintRule | null {
+  const normalized = normalizeStatement(statement);
+  const mentionsIdempotency =
+    /\b(idempotency|idempotent|retryable write|retries|exactly once|at-least-once)\b/i.test(normalized);
+
+  if (!mentionsIdempotency) {
+    return null;
+  }
+
+  return applyPathScopes(
+    {
+      id: `${source}:idempotency`,
+      source,
+      statement,
+      displayName: 'Idempotency expectation guard',
+      pattern: /\b(?:idempotency[-_ ]key|x-idempotency-key|idempotencyKey|dedupe(?:Key|Id)?)\b/i,
+      matchToken: 'idempotency-key',
+      minMatchesPerFile: 1,
+      evaluationMode: 'full_file',
+      evaluationScope: 'repo',
+      provenance: buildProvenance({
+        why: 'Statement requires deterministic retry safety via idempotency markers.',
+        evidence: ['idempotency', 'retryable write', 'exactly once'],
+        trustBoundaries: ['api-edge', 'write-path'],
+        pathScopes,
+      }),
+    },
+    pathScopes
+  );
+}
+
+function parseMigrationSafetyRule(
+  statement: string,
+  source: DeterministicConstraintSource,
+  pathScopes: PathScopeMatch
+): DeterministicConstraintRule | null {
+  const normalized = normalizeStatement(statement);
+  const mentionsMigration =
+    /\b(migration safety|schema migration|destructive migration|drop column|drop table|truncate table|backfill safety)\b/i.test(
+      normalized
+    );
+
+  if (!mentionsMigration) {
+    return null;
+  }
+
+  return applyPathScopes(
+    {
+      id: `${source}:migration_safety`,
+      source,
+      statement,
+      displayName: 'Migration safety guard (destructive operation risk)',
+      pattern:
+        /\b(?:DROP\s+COLUMN|DROP\s+TABLE|TRUNCATE\s+TABLE|ALTER\s+TABLE\s+[A-Za-z0-9_`".]+\s+DROP\s+COLUMN|DELETE\s+FROM\s+[A-Za-z0-9_`".]+\s*;)\b/i,
+      matchToken: 'destructive-migration',
+      evaluationMode: 'added_lines',
+      evaluationScope: 'file',
+      provenance: buildProvenance({
+        why: 'Statement requires non-destructive migration behavior for production safety.',
+        evidence: ['migration safety', 'drop column', 'truncate table'],
+        trustBoundaries: ['data-store', 'migration-pipeline'],
+        pathScopes,
+      }),
+    },
+    pathScopes
+  );
 }
 
 function statementMatchesTemplate(normalizedStatement: string, template: ConstraintTemplate): boolean {
@@ -323,30 +675,25 @@ function createRule(
   template: ConstraintTemplate,
   source: DeterministicConstraintSource,
   statement: string,
-  pathScopes: { includePatterns: string[]; excludePatterns: string[] }
+  pathScopes: PathScopeMatch
 ): DeterministicConstraintRule {
-  const includePatterns = [...pathScopes.includePatterns];
-  const excludePatterns = [...pathScopes.excludePatterns];
-  return {
-    id: `${source}:${template.id}`,
-    source,
-    statement,
-    displayName: template.displayName,
-    pattern: template.pattern,
-    matchToken: template.matchToken,
-    ...(includePatterns.length > 0
-      ? {
-          pathIncludePatterns: includePatterns,
-          pathIncludes: compilePathPatterns(includePatterns),
-        }
-      : {}),
-    ...(excludePatterns.length > 0
-      ? {
-          pathExcludePatterns: excludePatterns,
-          pathExcludes: compilePathPatterns(excludePatterns),
-        }
-      : {}),
-  };
+  return applyPathScopes(
+    {
+      id: `${source}:${template.id}`,
+      source,
+      statement,
+      displayName: template.displayName,
+      pattern: template.pattern,
+      matchToken: template.matchToken,
+      provenance: buildProvenance({
+        why: 'Statement matched deterministic constraint template.',
+        evidence: template.triggerTokens,
+        trustBoundaries: ['code-hygiene'],
+        pathScopes,
+      }),
+    },
+    pathScopes
+  );
 }
 
 function compileStatements(
@@ -368,6 +715,54 @@ function compileStatements(
       continue;
     }
 
+    const signatureDriftRule = parseSignatureDriftRule(rawStatement, source, pathScopes);
+    if (signatureDriftRule) {
+      rules.push(signatureDriftRule);
+      continue;
+    }
+
+    const backwardCompatibilityRule = parseBackwardCompatibilityRule(rawStatement, source, pathScopes);
+    if (backwardCompatibilityRule) {
+      rules.push(backwardCompatibilityRule);
+      continue;
+    }
+
+    const asyncOrderingRule = parseAsyncOrderingRule(rawStatement, source, pathScopes);
+    if (asyncOrderingRule) {
+      rules.push(asyncOrderingRule);
+      continue;
+    }
+
+    const eventSchemaRule = parseEventSchemaConsistencyRule(rawStatement, source, pathScopes);
+    if (eventSchemaRule) {
+      rules.push(eventSchemaRule);
+      continue;
+    }
+
+    const multiTenantRule = parseMultiTenantIsolationRule(rawStatement, source, pathScopes);
+    if (multiTenantRule) {
+      rules.push(multiTenantRule);
+      continue;
+    }
+
+    const cacheInvariantRule = parseCacheInvariantRule(rawStatement, source, pathScopes);
+    if (cacheInvariantRule) {
+      rules.push(cacheInvariantRule);
+      continue;
+    }
+
+    const idempotencyRule = parseIdempotencyRule(rawStatement, source, pathScopes);
+    if (idempotencyRule) {
+      rules.push(idempotencyRule);
+      continue;
+    }
+
+    const migrationSafetyRule = parseMigrationSafetyRule(rawStatement, source, pathScopes);
+    if (migrationSafetyRule) {
+      rules.push(migrationSafetyRule);
+      continue;
+    }
+
     const requiresProhibitiveLanguage = source === 'intent';
     if (requiresProhibitiveLanguage && !PROHIBITIVE_PATTERN.test(normalized)) {
       continue;
@@ -403,6 +798,7 @@ function dedupeRules(rules: DeterministicConstraintRule[]): DeterministicConstra
       typeof rule.minMatchesPerFile === 'number' ? String(rule.minMatchesPerFile) : '',
       typeof rule.maxMatchesPerFile === 'number' ? String(rule.maxMatchesPerFile) : '',
       rule.evaluationMode || '',
+      rule.evaluationScope || '',
     ].join('::');
     if (seen.has(key)) {
       continue;