pumuki 6.3.7

package/core/gate/Finding.test.ts

@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import type { Finding } from './Finding';
+
+test('Finding conserva campos requeridos y filePath opcional', () => {
+  const findingWithPath: Finding = {
+    ruleId: 'heuristics.ts.console-log.ast',
+    severity: 'WARN',
+    code: 'HEURISTICS_CONSOLE_LOG_AST',
+    message: 'AST heuristic detected console.log usage.',
+    filePath: 'apps/backend/src/main.ts',
+  };
+  const findingWithoutPath: Finding = {
+    ruleId: 'gate.summary',
+    severity: 'INFO',
+    code: 'GATE_SUMMARY',
+    message: 'Gate executed.',
+  };
+
+  assert.equal(findingWithPath.ruleId, 'heuristics.ts.console-log.ast');
+  assert.equal(findingWithPath.severity, 'WARN');
+  assert.equal(findingWithPath.filePath, 'apps/backend/src/main.ts');
+  assert.equal(findingWithoutPath.filePath, undefined);
+});
+
+test('Finding permite representar severidades distintas', () => {
+  const findings: Finding[] = [
+    {
+      ruleId: 'rule.info',
+      severity: 'INFO',
+      code: 'RULE_INFO',
+      message: 'Info finding',
+    },
+    {
+      ruleId: 'rule.error',
+      severity: 'ERROR',
+      code: 'RULE_ERROR',
+      message: 'Error finding',
+    },
+    {
+      ruleId: 'rule.critical',
+      severity: 'CRITICAL',
+      code: 'RULE_CRITICAL',
+      message: 'Critical finding',
+    },
+  ];
+
+  assert.deepEqual(
+    findings.map((finding) => finding.severity),
+    ['INFO', 'ERROR', 'CRITICAL']
+  );
+});

package/core/gate/Finding.ts

@@ -0,0 +1,9 @@
+import type { Severity } from '../rules/Severity';
+
+export type Finding = {
+  ruleId: string;
+  severity: Severity;
+  code: string;
+  message: string;
+  filePath?: string;
+};

package/core/gate/GateOutcome.test.ts

@@ -0,0 +1,20 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import type { GateOutcome } from './GateOutcome';
+
+test('GateOutcome soporta PASS, WARN y BLOCK', () => {
+  const passOutcome: GateOutcome = 'PASS';
+  const warnOutcome: GateOutcome = 'WARN';
+  const blockOutcome: GateOutcome = 'BLOCK';
+
+  assert.equal(passOutcome, 'PASS');
+  assert.equal(warnOutcome, 'WARN');
+  assert.equal(blockOutcome, 'BLOCK');
+});
+
+test('GateOutcome permite colecciones de outcomes tipados', () => {
+  const outcomes: GateOutcome[] = ['PASS', 'WARN', 'BLOCK'];
+
+  assert.equal(outcomes.length, 3);
+  assert.deepEqual(outcomes, ['PASS', 'WARN', 'BLOCK']);
+});

package/core/gate/GateOutcome.ts

@@ -0,0 +1 @@
+export type GateOutcome = 'PASS' | 'WARN' | 'BLOCK';

package/core/gate/GatePolicy.test.ts

@@ -0,0 +1,28 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import type { GatePolicy } from './GatePolicy';
+
+test('GatePolicy conserva stage, blockOnOrAbove y warnOnOrAbove', () => {
+  const policy: GatePolicy = {
+    stage: 'PRE_PUSH',
+    blockOnOrAbove: 'ERROR',
+    warnOnOrAbove: 'WARN',
+  };
+
+  assert.equal(policy.stage, 'PRE_PUSH');
+  assert.equal(policy.blockOnOrAbove, 'ERROR');
+  assert.equal(policy.warnOnOrAbove, 'WARN');
+  assert.equal(policy.defaultSeverity, undefined);
+});
+
+test('GatePolicy permite defaultSeverity opcional', () => {
+  const policy: GatePolicy = {
+    stage: 'CI',
+    blockOnOrAbove: 'ERROR',
+    warnOnOrAbove: 'WARN',
+    defaultSeverity: 'INFO',
+  };
+
+  assert.equal(policy.stage, 'CI');
+  assert.equal(policy.defaultSeverity, 'INFO');
+});

package/core/gate/GatePolicy.ts

@@ -0,0 +1,9 @@
+import type { Severity } from '../rules/Severity';
+import type { GateStage } from './GateStage';
+
+export type GatePolicy = {
+  stage: GateStage;
+  blockOnOrAbove: Severity;
+  warnOnOrAbove: Severity;
+  defaultSeverity?: Severity;
+};

package/core/gate/GateStage.test.ts

@@ -0,0 +1,22 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import type { GateStage } from './GateStage';
+
+test('GateStage soporta STAGED, PRE_COMMIT, PRE_PUSH y CI', () => {
+  const staged: GateStage = 'STAGED';
+  const preCommit: GateStage = 'PRE_COMMIT';
+  const prePush: GateStage = 'PRE_PUSH';
+  const ci: GateStage = 'CI';
+
+  assert.equal(staged, 'STAGED');
+  assert.equal(preCommit, 'PRE_COMMIT');
+  assert.equal(prePush, 'PRE_PUSH');
+  assert.equal(ci, 'CI');
+});
+
+test('GateStage permite colecciones tipadas de stages', () => {
+  const stages: GateStage[] = ['STAGED', 'PRE_COMMIT', 'PRE_PUSH', 'CI'];
+
+  assert.equal(stages.length, 4);
+  assert.deepEqual(stages, ['STAGED', 'PRE_COMMIT', 'PRE_PUSH', 'CI']);
+});

package/core/gate/GateStage.ts

@@ -0,0 +1 @@
+export type GateStage = 'STAGED' | 'PRE_COMMIT' | 'PRE_PUSH' | 'CI';

package/core/gate/conditionMatches.test.ts

@@ -0,0 +1,110 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import type { Condition } from '../rules/Condition';
+import { conditionMatches } from './conditionMatches';
+
+const facts = [
+  {
+    kind: 'FileChange',
+    path: 'apps/backend/src/main.ts',
+    changeType: 'modified',
+    source: 'git',
+  },
+  {
+    kind: 'FileContent',
+    path: 'apps/backend/src/main.ts',
+    content: 'console.log("hello")\nconst token = "abc123";',
+    source: 'repo',
+  },
+  {
+    kind: 'Dependency',
+    from: 'core/gate/evaluateGate',
+    to: 'core/gate/evaluateRules',
+    source: 'depcruise',
+  },
+  {
+    kind: 'Heuristic',
+    ruleId: 'heuristics.ts.console-log.ast',
+    severity: 'WARN',
+    code: 'HEURISTICS_CONSOLE_LOG_AST',
+    message: 'AST heuristic detected console.log usage.',
+    filePath: 'apps/backend/src/main.ts',
+    source: 'heuristics:ast',
+  },
+] as const;
+
+test('conditionMatches evalua FileChange por prefijo y tipo de cambio', () => {
+  const matchingCondition: Condition = {
+    kind: 'FileChange',
+    where: { pathPrefix: 'apps/backend/', changeType: 'modified' },
+  };
+  const nonMatchingCondition: Condition = {
+    kind: 'FileChange',
+    where: { pathPrefix: 'apps/frontend/', changeType: 'modified' },
+  };
+
+  assert.equal(conditionMatches(matchingCondition, facts), true);
+  assert.equal(conditionMatches(nonMatchingCondition, facts), false);
+});
+
+test('conditionMatches evalua FileContent con contains, regex y scope', () => {
+  const condition: Condition = {
+    kind: 'FileContent',
+    contains: ['console.log', 'token'],
+    regex: ['console\\.log\\(', 'token\\s*='],
+  };
+
+  assert.equal(
+    conditionMatches(condition, facts, {
+      include: ['apps/backend/*'],
+      exclude: ['apps/backend/generated/*'],
+    }),
+    true
+  );
+  assert.equal(
+    conditionMatches(condition, facts, {
+      include: ['apps/frontend/*'],
+    }),
+    false
+  );
+});
+
+test('conditionMatches evalua Dependency y Heuristic con where', () => {
+  const dependencyCondition: Condition = {
+    kind: 'Dependency',
+    where: { from: 'core/gate/evaluateGate', to: 'core/gate/evaluateRules' },
+  };
+  const heuristicCondition: Condition = {
+    kind: 'Heuristic',
+    where: {
+      ruleId: 'heuristics.ts.console-log.ast',
+      code: 'HEURISTICS_CONSOLE_LOG_AST',
+      filePathPrefix: 'apps/backend/',
+    },
+  };
+
+  assert.equal(conditionMatches(dependencyCondition, facts), true);
+  assert.equal(conditionMatches(heuristicCondition, facts), true);
+});
+
+test('conditionMatches soporta condiciones compuestas All, Any y Not', () => {
+  const composedCondition: Condition = {
+    kind: 'All',
+    conditions: [
+      { kind: 'FileChange', where: { changeType: 'modified' } },
+      {
+        kind: 'Any',
+        conditions: [
+          { kind: 'Dependency', where: { from: 'missing' } },
+          { kind: 'Heuristic', where: { code: 'HEURISTICS_CONSOLE_LOG_AST' } },
+        ],
+      },
+      {
+        kind: 'Not',
+        condition: { kind: 'FileChange', where: { changeType: 'deleted' } },
+      },
+    ],
+  };
+
+  assert.equal(conditionMatches(composedCondition, facts), true);
+});

package/core/gate/conditionMatches.ts

@@ -0,0 +1,174 @@
+import type { Condition } from '../rules/Condition';
+import type { RuleDefinition } from '../rules/RuleDefinition';
+import type { Fact } from '../facts/Fact';
+import type { DependencyFact } from '../facts/DependencyFact';
+import type { FileChangeFact } from '../facts/FileChangeFact';
+import type { FileContentFact } from '../facts/FileContentFact';
+
+type RuleScope = RuleDefinition['scope'];
+
+type FactInput = Fact | FileChangeFact | FileContentFact;
+
+type FactMatch = {
+  facts: ReadonlyArray<FactInput>;
+  scope?: RuleScope;
+};
+
+const isFileChangeFact = (fact: FactInput): fact is FileChangeFact =>
+  fact.kind === 'FileChange';
+
+const isFileContentFact = (fact: FactInput): fact is FileContentFact =>
+  fact.kind === 'FileContent';
+
+const isDependencyFact = (fact: FactInput): fact is DependencyFact =>
+  fact.kind === 'Dependency';
+
+const isHeuristicFact = (fact: FactInput): fact is Extract<Fact, { kind: 'Heuristic' }> =>
+  fact.kind === 'Heuristic';
+
+const extractPrefix = (pattern: string): string => {
+  const wildcardIndex = pattern.indexOf('*');
+  return wildcardIndex === -1 ? pattern : pattern.slice(0, wildcardIndex);
+};
+
+const matchesAnyPrefix = (path: string, patterns: ReadonlyArray<string>): boolean => {
+  return patterns.some((pattern) => path.startsWith(extractPrefix(pattern)));
+};
+
+const matchesScope = (path: string, scope?: RuleScope): boolean => {
+  const include = scope?.include;
+  const exclude = scope?.exclude;
+  if (exclude && exclude.length > 0 && matchesAnyPrefix(path, exclude)) {
+    return false;
+  }
+  if (!include || include.length === 0) {
+    return true;
+  }
+  return matchesAnyPrefix(path, include);
+};
+
+const matchesFileChange = (
+  condition: Extract<Condition, { kind: 'FileChange' }>,
+  facts: ReadonlyArray<FactInput>
+): boolean => {
+  for (const fact of facts) {
+    if (!isFileChangeFact(fact)) {
+      continue;
+    }
+    if (condition.where?.pathPrefix && !fact.path.startsWith(condition.where.pathPrefix)) {
+      continue;
+    }
+    if (condition.where?.changeType && fact.changeType !== condition.where.changeType) {
+      continue;
+    }
+    return true;
+  }
+  return false;
+};
+
+const matchesDependency = (
+  condition: Extract<Condition, { kind: 'Dependency' }>,
+  facts: ReadonlyArray<FactInput>
+): boolean => {
+  for (const fact of facts) {
+    if (!isDependencyFact(fact)) {
+      continue;
+    }
+    if (condition.where?.from && fact.from !== condition.where.from) {
+      continue;
+    }
+    if (condition.where?.to && fact.to !== condition.where.to) {
+      continue;
+    }
+    return true;
+  }
+  return false;
+};
+
+const matchesFileContent = (
+  condition: Extract<Condition, { kind: 'FileContent' }>,
+  match: FactMatch
+): boolean => {
+  const contains = condition.contains;
+  const regex = condition.regex;
+
+  for (const fact of match.facts) {
+    if (!isFileContentFact(fact)) {
+      continue;
+    }
+    if (!matchesScope(fact.path, match.scope)) {
+      continue;
+    }
+    if (contains && contains.length > 0 && !contains.every((token) => fact.content.includes(token))) {
+      continue;
+    }
+    if (regex && regex.length > 0) {
+      const matchesAll = regex.every((pattern) => new RegExp(pattern).test(fact.content));
+      if (!matchesAll) {
+        continue;
+      }
+    }
+    return true;
+  }
+
+  return false;
+};
+
+const matchesHeuristic = (
+  condition: Extract<Condition, { kind: 'Heuristic' }>,
+  facts: ReadonlyArray<FactInput>
+): boolean => {
+  for (const fact of facts) {
+    if (!isHeuristicFact(fact)) {
+      continue;
+    }
+    if (condition.where?.ruleId && fact.ruleId !== condition.where.ruleId) {
+      continue;
+    }
+    if (condition.where?.code && fact.code !== condition.where.code) {
+      continue;
+    }
+    if (condition.where?.filePathPrefix) {
+      const filePath = fact.filePath ?? '';
+      if (!filePath.startsWith(condition.where.filePathPrefix)) {
+        continue;
+      }
+    }
+    return true;
+  }
+  return false;
+};
+
+export const conditionMatches = (
+  condition: Condition,
+  facts: ReadonlyArray<FactInput>,
+  scope?: RuleScope
+): boolean => {
+  const match: FactMatch = { facts, scope };
+
+  if (condition.kind === 'FileChange') {
+    return matchesFileChange(condition, facts);
+  }
+
+  if (condition.kind === 'FileContent') {
+    return matchesFileContent(condition, match);
+  }
+
+  if (condition.kind === 'Dependency') {
+    return matchesDependency(condition, facts);
+  }
+
+  if (condition.kind === 'Heuristic') {
+    return matchesHeuristic(condition, facts);
+  }
+
+  if (condition.kind === 'All') {
+    return condition.conditions.every((child) => conditionMatches(child, facts, scope));
+  }
+
+  if (condition.kind === 'Any') {
+    return condition.conditions.some((child) => conditionMatches(child, facts, scope));
+  }
+
+  return !conditionMatches(condition.condition, facts, scope);
+};

package/core/gate/evaluateGate.test.ts

@@ -0,0 +1,77 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import type { Finding } from './Finding';
+import type { GatePolicy } from './GatePolicy';
+import { evaluateGate } from './evaluateGate';
+
+const defaultPolicy: GatePolicy = {
+  stage: 'CI',
+  blockOnOrAbove: 'ERROR',
+  warnOnOrAbove: 'WARN',
+};
+
+test('evaluateGate devuelve PASS cuando no hay findings', () => {
+  const result = evaluateGate([], defaultPolicy);
+
+  assert.equal(result.outcome, 'PASS');
+  assert.deepEqual(result.blocking, []);
+  assert.deepEqual(result.warnings, []);
+});
+
+test('evaluateGate devuelve WARN cuando hay warnings sin bloqueantes', () => {
+  const findings: Finding[] = [
+    {
+      ruleId: 'rule.warn',
+      severity: 'WARN',
+      code: 'RULE_WARN',
+      message: 'Warn finding',
+    },
+    {
+      ruleId: 'rule.info',
+      severity: 'INFO',
+      code: 'RULE_INFO',
+      message: 'Info finding',
+    },
+  ];
+
+  const result = evaluateGate(findings, defaultPolicy);
+
+  assert.equal(result.outcome, 'WARN');
+  assert.equal(result.blocking.length, 0);
+  assert.equal(result.warnings.length, 1);
+  assert.equal(result.warnings[0]?.ruleId, 'rule.warn');
+});
+
+test('evaluateGate devuelve BLOCK cuando existe al menos un finding bloqueante', () => {
+  const findings: Finding[] = [
+    {
+      ruleId: 'rule.error',
+      severity: 'ERROR',
+      code: 'RULE_ERROR',
+      message: 'Error finding',
+    },
+    {
+      ruleId: 'rule.critical',
+      severity: 'CRITICAL',
+      code: 'RULE_CRITICAL',
+      message: 'Critical finding',
+    },
+    {
+      ruleId: 'rule.warn',
+      severity: 'WARN',
+      code: 'RULE_WARN',
+      message: 'Warn finding',
+    },
+  ];
+
+  const result = evaluateGate(findings, defaultPolicy);
+
+  assert.equal(result.outcome, 'BLOCK');
+  assert.equal(result.blocking.length, 2);
+  assert.deepEqual(
+    result.blocking.map((finding) => finding.ruleId),
+    ['rule.error', 'rule.critical']
+  );
+  assert.equal(result.warnings.length, 1);
+  assert.equal(result.warnings[0]?.ruleId, 'rule.warn');
+});

package/core/gate/evaluateGate.ts

@@ -0,0 +1,23 @@
+import type { Finding } from './Finding';
+import type { GateOutcome } from './GateOutcome';
+import type { GatePolicy } from './GatePolicy';
+import { isSeverityAtLeast } from '../rules/Severity';
+
+export function evaluateGate(
+  findings: Finding[],
+  policy: GatePolicy
+): { outcome: GateOutcome; blocking: Finding[]; warnings: Finding[] } {
+  const blocking = findings.filter((finding) =>
+    isSeverityAtLeast(finding.severity, policy.blockOnOrAbove)
+  );
+  const warnings = findings.filter(
+    (finding) =>
+      !isSeverityAtLeast(finding.severity, policy.blockOnOrAbove) &&
+      isSeverityAtLeast(finding.severity, policy.warnOnOrAbove)
+  );
+
+  const outcome: GateOutcome =
+    blocking.length > 0 ? 'BLOCK' : warnings.length > 0 ? 'WARN' : 'PASS';
+
+  return { outcome, blocking, warnings };
+}

package/core/gate/evaluateRules.test.ts

@@ -0,0 +1,106 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import type { RuleSet } from '../rules/RuleSet';
+import { evaluateRules } from './evaluateRules';
+
+test('evaluateRules genera finding cuando la condicion coincide y usa code explicito', () => {
+  const rules: RuleSet = [
+    {
+      id: 'rule.explicit.code',
+      description: 'Detecta cambios en backend',
+      severity: 'WARN',
+      when: {
+        kind: 'FileChange',
+        where: { pathPrefix: 'apps/backend/', changeType: 'modified' },
+      },
+      then: {
+        kind: 'Finding',
+        message: 'Backend file modified.',
+        code: 'BACKEND_FILE_MODIFIED',
+      },
+    },
+  ];
+  const facts = [
+    {
+      kind: 'FileChange',
+      path: 'apps/backend/src/main.ts',
+      changeType: 'modified',
+      source: 'git',
+    },
+  ] as const;
+
+  const findings = evaluateRules(rules, facts);
+
+  assert.equal(findings.length, 1);
+  assert.deepEqual(findings[0], {
+    ruleId: 'rule.explicit.code',
+    severity: 'WARN',
+    code: 'BACKEND_FILE_MODIFIED',
+    message: 'Backend file modified.',
+  });
+});
+
+test('evaluateRules usa id de la regla como code cuando no se define en consecuencia', () => {
+  const rules: RuleSet = [
+    {
+      id: 'rule.code.fallback',
+      description: 'Detecta dependencia concreta',
+      severity: 'ERROR',
+      when: {
+        kind: 'Dependency',
+        where: { from: 'core/gate/evaluateGate', to: 'core/gate/evaluateRules' },
+      },
+      then: {
+        kind: 'Finding',
+        message: 'Dependency matched.',
+      },
+    },
+  ];
+  const facts = [
+    {
+      kind: 'Dependency',
+      from: 'core/gate/evaluateGate',
+      to: 'core/gate/evaluateRules',
+      source: 'depcruise',
+    },
+  ] as const;
+
+  const findings = evaluateRules(rules, facts);
+
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0]?.code, 'rule.code.fallback');
+  assert.equal(findings[0]?.severity, 'ERROR');
+});
+
+test('evaluateRules respeta scope y no genera hallazgo cuando no coincide', () => {
+  const rules: RuleSet = [
+    {
+      id: 'rule.scope.filtered',
+      description: 'Busca token en backend',
+      severity: 'WARN',
+      when: {
+        kind: 'FileContent',
+        contains: ['token'],
+      },
+      then: {
+        kind: 'Finding',
+        message: 'Token found.',
+      },
+      scope: {
+        include: ['apps/backend/*'],
+      },
+    },
+  ];
+  const facts = [
+    {
+      kind: 'FileContent',
+      path: 'apps/frontend/src/App.tsx',
+      content: 'const token = "abc";',
+      source: 'repo',
+    },
+  ] as const;
+
+  const findings = evaluateRules(rules, facts);
+
+  assert.deepEqual(findings, []);
+});

package/core/gate/evaluateRules.ts

@@ -0,0 +1,40 @@
+import type { RuleSet } from '../rules/RuleSet';
+import type { RuleDefinition } from '../rules/RuleDefinition';
+import type { Condition } from '../rules/Condition';
+import type { Consequence } from '../rules/Consequence';
+import type { Fact } from '../facts/Fact';
+import type { FileChangeFact } from '../facts/FileChangeFact';
+import type { FileContentFact } from '../facts/FileContentFact';
+import type { Finding } from './Finding';
+import { conditionMatches } from './conditionMatches';
+
+type FactInput = Fact | FileChangeFact | FileContentFact;
+
+const toFinding = (rule: RuleDefinition, consequence: Consequence): Finding => {
+  return {
+    ruleId: rule.id,
+    severity: rule.severity,
+    code: consequence.code ?? rule.id,
+    message: consequence.message,
+  };
+};
+
+export function evaluateRules(
+  rules: RuleSet,
+  facts: ReadonlyArray<FactInput>
+): ReadonlyArray<Finding> {
+  const findings: Finding[] = [];
+
+  for (const rule of rules) {
+    const condition: Condition = rule.when;
+    const consequence: Consequence = rule.then;
+    if (!conditionMatches(condition, facts, rule.scope)) {
+      continue;
+    }
+    if (consequence.kind === 'Finding') {
+      findings.push(toFinding(rule, consequence));
+    }
+  }
+
+  return findings;
+}