@neurcode-ai/governance-runtime 0.1.1 → 0.1.3

package/src/index.test.ts

@@ -157,6 +157,16 @@ test('compileDeterministicConstraints builds rules from intent and policy text',
   assert.ok(ruleIds.includes('policy:no_process_env'));
 });
 
+test('compileDeterministicConstraints supports path-scoped rules', () => {
+  const compiled = compileDeterministicConstraints({
+    policyRules: ['No console.log in src/server/** except src/server/tests/**'],
+  });
+  const scopedRule = compiled.rules.find((rule) => rule.id === 'policy:no_console_log');
+  assert.ok(scopedRule, 'expected path-scoped console.log rule');
+  assert.deepEqual(scopedRule?.pathIncludePatterns, ['src/server/**']);
+  assert.deepEqual(scopedRule?.pathExcludePatterns, ['src/server/tests/**']);
+});
+
 test('evaluatePlanVerification enforces compiled policy rules deterministically', () => {
   const result = evaluatePlanVerification({
     planFiles: SAMPLE_PLAN,
@@ -190,6 +200,294 @@ test('evaluatePlanVerification enforces compiled policy rules deterministically'
   assert.match(result.constraintViolations[0], /console\.log/i);
 });
 
+test('evaluatePlanVerification enforces path-scoped exclusions to reduce false positives', () => {
+  const result = evaluatePlanVerification({
+    planFiles: SAMPLE_PLAN,
+    changedFiles: [
+      {
+        path: 'src/server/app.ts',
+        changeType: 'modify',
+        added: 1,
+        removed: 0,
+        hunks: [
+          {
+            oldStart: 1,
+            oldLines: 0,
+            newStart: 1,
+            newLines: 1,
+            lines: [
+              {
+                type: 'added',
+                content: 'console.log("server");',
+              },
+            ],
+          },
+        ],
+      },
+      {
+        path: 'src/server/tests/app.test.ts',
+        changeType: 'modify',
+        added: 1,
+        removed: 0,
+        hunks: [
+          {
+            oldStart: 1,
+            oldLines: 0,
+            newStart: 1,
+            newLines: 1,
+            lines: [
+              {
+                type: 'added',
+                content: 'console.log("test");',
+              },
+            ],
+          },
+        ],
+      },
+    ],
+    policyRules: ['No console.log in src/server/** except src/server/tests/**'],
+  });
+
+  assert.equal(result.constraintViolations.length, 1);
+  assert.match(result.constraintViolations[0], /src\/server\/app\.ts/i);
+});
+
+test('evaluatePlanVerification supports deterministic invocation limits with full-file context', () => {
+  const result = evaluatePlanVerification({
+    planFiles: SAMPLE_PLAN,
+    changedFiles: [
+      {
+        path: 'src/a.ts',
+        changeType: 'modify',
+        added: 1,
+        removed: 0,
+        hunks: [
+          {
+            oldStart: 1,
+            oldLines: 0,
+            newStart: 1,
+            newLines: 1,
+            lines: [
+              {
+                type: 'added',
+                content: 'const marker = true;',
+              },
+            ],
+          },
+        ],
+      },
+    ],
+    intentConstraints: 'foo invoked only 1 times in src/a.ts',
+    fileContents: {
+      'src/a.ts': 'foo();\nfoo();\n',
+    },
+  });
+
+  assert.equal(result.verdict, 'FAIL');
+  assert.equal(result.constraintViolations.length, 1);
+  assert.match(result.constraintViolations[0], /limit 1/i);
+});
+
+test('evaluatePlanVerification supports at-least invocation constraints', () => {
+  const result = evaluatePlanVerification({
+    planFiles: SAMPLE_PLAN,
+    changedFiles: [
+      {
+        path: 'src/a.ts',
+        changeType: 'modify',
+        added: 1,
+        removed: 0,
+        hunks: [
+          {
+            oldStart: 1,
+            oldLines: 0,
+            newStart: 1,
+            newLines: 1,
+            lines: [
+              {
+                type: 'added',
+                content: 'const marker = true;',
+              },
+            ],
+          },
+        ],
+      },
+    ],
+    intentConstraints: 'foo should be called at least 2 times in src/a.ts',
+    fileContents: {
+      'src/a.ts': 'foo();\n',
+    },
+  });
+
+  assert.equal(result.verdict, 'FAIL');
+  assert.equal(result.constraintViolations.length, 1);
+  assert.match(result.constraintViolations[0], /minimum 2/i);
+});
+
+test('compileDeterministicConstraints supports exact invocation constraints', () => {
+  const compiled = compileDeterministicConstraints({
+    intentConstraints: 'bar should be called exactly 3 times in src/a.ts',
+  });
+
+  const rule = compiled.rules.find((item) => item.id.includes('exact_invocations_bar'));
+  assert.ok(rule, 'expected exact invocation rule');
+  assert.equal(rule?.minMatchesPerFile, 3);
+  assert.equal(rule?.maxMatchesPerFile, 3);
+});
+
+test('compileDeterministicConstraints supports repo-scoped invocation constraints', () => {
+  const compiled = compileDeterministicConstraints({
+    intentConstraints: 'foo should be called at most 2 times across repository',
+  });
+
+  const rule = compiled.rules.find((item) => item.id.includes('invocations_foo_repo'));
+  assert.ok(rule, 'expected repo-scoped invocation rule');
+  assert.equal(rule?.evaluationScope, 'repo');
+  assert.equal(rule?.maxMatchesPerFile, 2);
+});
+
+test('evaluatePlanVerification enforces repo-scoped invocation constraints', () => {
+  const result = evaluatePlanVerification({
+    planFiles: SAMPLE_PLAN,
+    changedFiles: [
+      {
+        path: 'src/a.ts',
+        changeType: 'modify',
+        added: 1,
+        removed: 0,
+        hunks: [
+          {
+            oldStart: 1,
+            oldLines: 0,
+            newStart: 1,
+            newLines: 1,
+            lines: [
+              {
+                type: 'added',
+                content: 'const marker = true;',
+              },
+            ],
+          },
+        ],
+      },
+    ],
+    intentConstraints: 'foo called at most 1 times across repository',
+    fileContents: {
+      'src/a.ts': 'foo();\n',
+      'src/b.ts': 'foo();\n',
+    },
+  });
+
+  assert.equal(result.verdict, 'FAIL');
+  assert.ok(result.constraintViolations.some((item) => /across repository scope/i.test(item)));
+});
+
+test('evaluatePlanVerification detects exported API signature drift constraints', () => {
+  const result = evaluatePlanVerification({
+    planFiles: SAMPLE_PLAN,
+    changedFiles: [
+      {
+        path: 'src/api.ts',
+        changeType: 'modify',
+        added: 1,
+        removed: 1,
+        hunks: [
+          {
+            oldStart: 1,
+            oldLines: 1,
+            newStart: 1,
+            newLines: 1,
+            lines: [
+              {
+                type: 'removed',
+                content: 'export function createUser(name: string): User {',
+              },
+              {
+                type: 'added',
+                content: 'export function createUser(name: string, email: string): User {',
+              },
+            ],
+          },
+        ],
+      },
+    ],
+    intentConstraints: 'Do not change public API signatures',
+  });
+
+  assert.equal(result.verdict, 'FAIL');
+  assert.ok(result.constraintViolations.some((item) => /signature delta/i.test(item)));
+});
+
+test('evaluatePlanVerification detects network-call invariants deterministically', () => {
+  const result = evaluatePlanVerification({
+    planFiles: SAMPLE_PLAN,
+    changedFiles: [
+      {
+        path: 'src/a.ts',
+        changeType: 'modify',
+        added: 1,
+        removed: 0,
+        hunks: [
+          {
+            oldStart: 1,
+            oldLines: 0,
+            newStart: 1,
+            newLines: 1,
+            lines: [
+              {
+                type: 'added',
+                content: 'await fetch("https://api.example.com");',
+              },
+            ],
+          },
+        ],
+      },
+    ],
+    policyRules: ['No network calls in committed code'],
+  });
+
+  assert.equal(result.verdict, 'FAIL');
+  assert.equal(result.constraintViolations.length, 1);
+  assert.match(result.constraintViolations[0], /network-call/i);
+});
+
+test('compileDeterministicConstraints expands advanced architectural invariants', () => {
+  const compiled = compileDeterministicConstraints({
+    intentConstraints: [
+      'Preserve backward compatibility for public endpoints',
+      'Maintain async event ordering and do not process messages out of order',
+      'Do not remove required fields from event payload schema',
+      'Enforce multi-tenant isolation and avoid cross-tenant access',
+      'Do not invalidate global cache keys',
+      'Preserve idempotency guarantees for retryable writes',
+      'Avoid destructive schema migrations such as DROP COLUMN',
+    ].join('; '),
+  });
+
+  const ruleIds = compiled.rules.map((rule) => rule.id);
+  assert.ok(ruleIds.includes('intent:backward_compatibility'));
+  assert.ok(ruleIds.includes('intent:async_ordering'));
+  assert.ok(ruleIds.includes('intent:event_schema_consistency'));
+  assert.ok(ruleIds.includes('intent:multi_tenant_isolation'));
+  assert.ok(ruleIds.includes('intent:cache_invariant'));
+  assert.ok(ruleIds.includes('intent:idempotency'));
+  assert.ok(ruleIds.includes('intent:migration_safety'));
+});
+
+test('compileDeterministicConstraints attaches provenance metadata', () => {
+  const compiled = compileDeterministicConstraints({
+    intentConstraints: 'Preserve backward compatibility for public endpoints in src/api/**',
+  });
+
+  const rule = compiled.rules.find((item) => item.id === 'intent:backward_compatibility');
+  assert.ok(rule, 'expected backward compatibility rule');
+  assert.ok(rule?.provenance, 'expected provenance metadata');
+  assert.equal(rule?.provenance?.why.length ? true : false, true);
+  assert.ok((rule?.provenance?.evidence || []).length > 0);
+  assert.ok((rule?.provenance?.trustBoundaries || []).includes('public-api'));
+  assert.ok((rule?.provenance?.contributingGraphPaths || []).includes('src/api/**'));
+});
+
 test('buildPlanVerificationMessage handles incomplete 0/0 plans', () => {
   const message = buildPlanVerificationMessage({
     constraintViolations: [],

package/src/index.ts

@@ -49,6 +49,7 @@ export interface PlanVerificationInput {
   intentConstraints?: string;
   policyRules?: string[];
   extraConstraintRules?: DeterministicConstraintRule[];
+  fileContents?: Record<string, string>;
 }
 
 export interface PlanDiffSummary {
@@ -105,7 +106,8 @@ function detectConstraintViolations(
   intentConstraints: string | undefined,
   policyRules: string[] | undefined,
   extraConstraintRules: DeterministicConstraintRule[] | undefined,
-  changedFiles: PlanDiffFile[]
+  changedFiles: PlanDiffFile[],
+  fileContents?: Record<string, string>
 ): string[] {
   const compiled = compileDeterministicConstraints({
     intentConstraints,
@@ -123,18 +125,187 @@ function detectConstraintViolations(
 
   const violations: string[] = [];
   const seenViolations = new Set<string>();
+  const normalizedFileContents: Record<string, string> = {};
+  for (const [path, content] of Object.entries(fileContents || {})) {
+    normalizedFileContents[normalizeRepoPath(path)] = content;
+  }
+
+  const pathMatchesRule = (rule: DeterministicConstraintRule, filePath: string): boolean => {
+    const include = rule.pathIncludes || [];
+    const exclude = rule.pathExcludes || [];
+    if (include.length > 0 && !include.some((pattern) => pattern.test(filePath))) {
+      return false;
+    }
+    if (exclude.length > 0 && exclude.some((pattern) => pattern.test(filePath))) {
+      return false;
+    }
+    return true;
+  };
+
+  const countMatches = (pattern: RegExp, input: string): number => {
+    if (!input) return 0;
+    const flags = pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`;
+    const re = new RegExp(pattern.source, flags);
+    let total = 0;
+    for (const _match of input.matchAll(re)) {
+      total += 1;
+    }
+    return total;
+  };
+
+  const addedLinesByPath = new Map<string, string>();
+  for (const file of changedFiles) {
+    const addedLines = (file.hunks || []).flatMap((hunk) =>
+      hunk.lines
+        .filter((line) => line.type === 'added')
+        .map((line) => line.content)
+    );
+    addedLinesByPath.set(file.path, addedLines.join('\n'));
+  }
+
+  const candidateRepoPaths = new Set<string>([
+    ...changedFiles.map((file) => file.path),
+    ...Object.keys(normalizedFileContents),
+  ]);
 
   for (const rule of rules) {
+    if (rule.evaluationMode === 'signature_delta') {
+      for (const file of changedFiles) {
+        if (!pathMatchesRule(rule, file.path)) {
+          continue;
+        }
+        const addedSignatureLines = (file.hunks || []).flatMap((hunk) =>
+          hunk.lines
+            .filter((line) => line.type === 'added' && new RegExp(rule.pattern.source, rule.pattern.flags).test(line.content))
+            .map((line) => line.content)
+        );
+        const removedSignatureLines = (file.hunks || []).flatMap((hunk) =>
+          hunk.lines
+            .filter((line) => line.type === 'removed' && new RegExp(rule.pattern.source, rule.pattern.flags).test(line.content))
+            .map((line) => line.content)
+        );
+        const deltaCount = addedSignatureLines.length + removedSignatureLines.length;
+        if (deltaCount === 0) {
+          continue;
+        }
+        const violation =
+          `Exported API signature delta detected in ${file.path} ` +
+          `(added ${addedSignatureLines.length}, removed ${removedSignatureLines.length}, violates constraint: "${rule.displayName}")`;
+        if (!seenViolations.has(violation)) {
+          seenViolations.add(violation);
+          violations.push(violation);
+        }
+      }
+      continue;
+    }
+
+    const hasMatchBounds =
+      (typeof rule.maxMatchesPerFile === 'number' && Number.isFinite(rule.maxMatchesPerFile))
+      || (typeof rule.minMatchesPerFile === 'number' && Number.isFinite(rule.minMatchesPerFile));
+
+    if (rule.evaluationScope === 'repo' && hasMatchBounds) {
+      let repoMatchCount = 0;
+      let scannedPaths = 0;
+      for (const filePath of candidateRepoPaths) {
+        if (!pathMatchesRule(rule, filePath)) {
+          continue;
+        }
+        const fullContent = normalizedFileContents[filePath];
+        const addedFallback = addedLinesByPath.get(filePath) || '';
+        const haystack =
+          rule.evaluationMode === 'full_file' && typeof fullContent === 'string'
+            ? fullContent
+            : addedFallback;
+        if (!haystack) {
+          continue;
+        }
+        scannedPaths += 1;
+        repoMatchCount += countMatches(rule.pattern, haystack);
+      }
+
+      if (
+        typeof rule.maxMatchesPerFile === 'number'
+        && Number.isFinite(rule.maxMatchesPerFile)
+        && repoMatchCount > rule.maxMatchesPerFile
+      ) {
+        const violation =
+          `${rule.matchToken} matched ${repoMatchCount} times across repository scope ` +
+          `(limit ${rule.maxMatchesPerFile}, scanned ${scannedPaths} file(s), violates constraint: "${rule.displayName}")`;
+        if (!seenViolations.has(violation)) {
+          seenViolations.add(violation);
+          violations.push(violation);
+        }
+      }
+
+      if (
+        typeof rule.minMatchesPerFile === 'number'
+        && Number.isFinite(rule.minMatchesPerFile)
+        && repoMatchCount < rule.minMatchesPerFile
+      ) {
+        const violation =
+          `${rule.matchToken} matched ${repoMatchCount} times across repository scope ` +
+          `(minimum ${rule.minMatchesPerFile}, scanned ${scannedPaths} file(s), violates constraint: "${rule.displayName}")`;
+        if (!seenViolations.has(violation)) {
+          seenViolations.add(violation);
+          violations.push(violation);
+        }
+      }
+      continue;
+    }
+
     for (const file of changedFiles) {
+      if (!pathMatchesRule(rule, file.path)) {
+        continue;
+      }
       if (!file.hunks || file.hunks.length === 0) {
         continue;
       }
+
+      const addedLines = addedLinesByPath.get(file.path) || '';
+
+      if (hasMatchBounds) {
+        const fullContent = normalizedFileContents[file.path];
+        const haystack =
+          rule.evaluationMode === 'full_file' && typeof fullContent === 'string'
+            ? fullContent
+            : addedLines;
+        const matchCount = countMatches(rule.pattern, haystack);
+        if (
+          typeof rule.maxMatchesPerFile === 'number'
+          && Number.isFinite(rule.maxMatchesPerFile)
+          && matchCount > rule.maxMatchesPerFile
+        ) {
+          const violation =
+            `${rule.matchToken} matched ${matchCount} times in ${file.path} ` +
+            `(limit ${rule.maxMatchesPerFile}, violates constraint: "${rule.displayName}")`;
+          if (!seenViolations.has(violation)) {
+            seenViolations.add(violation);
+            violations.push(violation);
+          }
+        }
+        if (
+          typeof rule.minMatchesPerFile === 'number'
+          && Number.isFinite(rule.minMatchesPerFile)
+          && matchCount < rule.minMatchesPerFile
+        ) {
+          const violation =
+            `${rule.matchToken} matched ${matchCount} times in ${file.path} ` +
+            `(minimum ${rule.minMatchesPerFile}, violates constraint: "${rule.displayName}")`;
+          if (!seenViolations.has(violation)) {
+            seenViolations.add(violation);
+            violations.push(violation);
+          }
+        }
+        continue;
+      }
+
       for (const hunk of file.hunks) {
         for (const line of hunk.lines) {
           if (line.type !== 'added') {
             continue;
           }
-          if (!rule.pattern.test(line.content)) {
+          const pattern = new RegExp(rule.pattern.source, rule.pattern.flags);
+          if (!pattern.test(line.content)) {
             continue;
           }
           const violation = `${rule.matchToken} found in ${file.path} (violates constraint: \"${rule.displayName}\")`;
@@ -234,7 +405,8 @@ export function evaluatePlanVerification(input: PlanVerificationInput): PlanVeri
     input.intentConstraints,
     input.policyRules,
     input.extraConstraintRules,
-    normalizedChangedFiles
+    normalizedChangedFiles,
+    input.fileContents
   );
   const verdict = resolvePlanVerdict({
     bloatCount,