pumuki 6.3.7

package/integrations/evidence/buildEvidence.ts

@@ -0,0 +1,350 @@
+import type { Finding } from '../../core/gate/Finding';
+import type { GateOutcome } from '../../core/gate/GateOutcome';
+import type { GateStage } from '../../core/gate/GateStage';
+import type { Severity } from '../../core/rules/Severity';
+import type {
+  AiEvidenceV2_1,
+  ConsolidationSuppressedFinding,
+  CompatibilityViolation,
+  EvidenceLines,
+  HumanIntentState,
+  LedgerEntry,
+  PlatformState,
+  RulesetState,
+  SnapshotFinding,
+} from './schema';
+import { resolveHumanIntent } from './humanIntent';
+
+type BuildFindingInput = Finding & {
+  file?: string;
+  lines?: EvidenceLines;
+};
+
+export type BuildEvidenceParams = {
+  stage: GateStage;
+  findings: ReadonlyArray<BuildFindingInput>;
+  gateOutcome?: GateOutcome;
+  previousEvidence?: AiEvidenceV2_1;
+  humanIntent?: HumanIntentState | null;
+  detectedPlatforms: Record<string, PlatformState>;
+  loadedRulesets: ReadonlyArray<RulesetState>;
+};
+
+const normalizeLines = (lines?: EvidenceLines): EvidenceLines | undefined => {
+  if (typeof lines === 'undefined') {
+    return undefined;
+  }
+  if (typeof lines === 'string') {
+    const trimmed = lines.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  }
+  if (typeof lines === 'number') {
+    return Number.isFinite(lines) ? Math.trunc(lines) : undefined;
+  }
+
+  const normalized = Array.from(
+    new Set(lines.filter((line) => Number.isFinite(line)).map((line) => Math.trunc(line)))
+  ).sort((a, b) => a - b);
+
+  return normalized.length > 0 ? normalized : undefined;
+};
+
+const linesKey = (lines?: EvidenceLines): string => {
+  if (typeof lines === 'undefined') {
+    return '';
+  }
+  if (typeof lines === 'string' || typeof lines === 'number') {
+    return String(lines);
+  }
+  return lines.join(',');
+};
+
+const findingKey = (finding: Pick<SnapshotFinding, 'ruleId' | 'file' | 'lines'>): string => {
+  return `${finding.ruleId}::${finding.file}::${linesKey(finding.lines)}`;
+};
+
+const compareFindingEntries = (
+  left: Pick<SnapshotFinding, 'ruleId' | 'file' | 'lines'>,
+  right: Pick<SnapshotFinding, 'ruleId' | 'file' | 'lines'>
+): number => {
+  return findingKey(left).localeCompare(findingKey(right), undefined, { numeric: true });
+};
+
+const ledgerKey = (entry: Pick<LedgerEntry, 'ruleId' | 'file' | 'lines'>): string => {
+  return `${entry.ruleId}::${entry.file}::${linesKey(entry.lines)}`;
+};
+
+const normalizeFinding = (finding: BuildFindingInput): SnapshotFinding => {
+  const file = (finding.filePath ?? finding.file ?? 'unknown').replace(/\\/g, '/');
+  return {
+    ruleId: finding.ruleId,
+    severity: finding.severity,
+    code: finding.code,
+    message: finding.message,
+    file,
+    lines: normalizeLines(finding.lines),
+  };
+};
+
+const severityRank: Record<Severity, number> = {
+  INFO: 0,
+  WARN: 1,
+  ERROR: 2,
+  CRITICAL: 3,
+};
+
+const equivalentRuleFamilies: ReadonlyArray<ReadonlyArray<string>> = [
+  ['ios.no-force-unwrap', 'heuristics.ios.force-unwrap.ast'],
+  ['ios.no-anyview', 'heuristics.ios.anyview.ast'],
+  ['ios.no-completion-handlers-outside-bridges', 'heuristics.ios.callback-style.ast'],
+  ['backend.no-console-log', 'frontend.no-console-log', 'heuristics.ts.console-log.ast'],
+  ['backend.avoid-explicit-any', 'heuristics.ts.explicit-any.ast'],
+  ['backend.no-empty-catch', 'heuristics.ts.empty-catch.ast'],
+];
+
+const ruleFamilyIndex = new Map<string, number>();
+equivalentRuleFamilies.forEach((family, familyIndex) => {
+  family.forEach((ruleId) => {
+    ruleFamilyIndex.set(ruleId, familyIndex);
+  });
+});
+
+const isHeuristicRuleId = (ruleId: string): boolean => {
+  return ruleId.startsWith('heuristics.');
+};
+
+const preferFinding = (
+  current: SnapshotFinding,
+  candidate: SnapshotFinding
+): SnapshotFinding => {
+  const bySeverity = severityRank[candidate.severity] - severityRank[current.severity];
+  if (bySeverity > 0) {
+    return candidate;
+  }
+  if (bySeverity < 0) {
+    return current;
+  }
+
+  const currentIsHeuristic = isHeuristicRuleId(current.ruleId);
+  const candidateIsHeuristic = isHeuristicRuleId(candidate.ruleId);
+  if (currentIsHeuristic !== candidateIsHeuristic) {
+    return currentIsHeuristic ? candidate : current;
+  }
+
+  return candidate.ruleId.localeCompare(current.ruleId) < 0 ? candidate : current;
+};
+
+const consolidateEquivalentFindings = (
+  findings: ReadonlyArray<SnapshotFinding>
+): { findings: SnapshotFinding[]; suppressed: ConsolidationSuppressedFinding[] } => {
+  const selectedByFileFamily = new Map<string, SnapshotFinding>();
+  for (const finding of findings) {
+    const familyIndex = ruleFamilyIndex.get(finding.ruleId);
+    if (typeof familyIndex === 'undefined') {
+      continue;
+    }
+    const key = `${finding.file}::${familyIndex}`;
+    const current = selectedByFileFamily.get(key);
+    if (!current) {
+      selectedByFileFamily.set(key, finding);
+      continue;
+    }
+    selectedByFileFamily.set(key, preferFinding(current, finding));
+  }
+
+  const suppressed: ConsolidationSuppressedFinding[] = [];
+
+  const filtered = findings.filter((finding) => {
+    const familyIndex = ruleFamilyIndex.get(finding.ruleId);
+    if (typeof familyIndex === 'undefined') {
+      return true;
+    }
+    const selected = selectedByFileFamily.get(`${finding.file}::${familyIndex}`);
+    if (!selected) {
+      return true;
+    }
+    const keep = findingKey(selected) === findingKey(finding);
+    if (!keep) {
+      suppressed.push({
+        ruleId: finding.ruleId,
+        file: finding.file,
+        lines: finding.lines,
+        replacedByRuleId: selected.ruleId,
+        reason: 'semantic-family-precedence',
+      });
+    }
+    return keep;
+  });
+
+  suppressed.sort((left, right) => {
+    const byFile = left.file.localeCompare(right.file);
+    if (byFile !== 0) {
+      return byFile;
+    }
+    const byRule = left.ruleId.localeCompare(right.ruleId);
+    if (byRule !== 0) {
+      return byRule;
+    }
+    return left.replacedByRuleId.localeCompare(right.replacedByRuleId);
+  });
+
+  return {
+    findings: filtered,
+    suppressed,
+  };
+};
+
+const normalizeAndDedupeFindings = (
+  findings: ReadonlyArray<BuildFindingInput>
+): { findings: SnapshotFinding[]; suppressed: ConsolidationSuppressedFinding[] } => {
+  const unique = new Map<string, SnapshotFinding>();
+  for (const finding of findings) {
+    const normalized = normalizeFinding(finding);
+    const key = findingKey(normalized);
+    if (!unique.has(key)) {
+      unique.set(key, normalized);
+    }
+  }
+  const deduped = Array.from(unique.values()).sort(compareFindingEntries);
+  const consolidated = consolidateEquivalentFindings(deduped);
+  return {
+    findings: consolidated.findings.sort(compareFindingEntries),
+    suppressed: consolidated.suppressed,
+  };
+};
+
+const toGateOutcome = (findings: ReadonlyArray<SnapshotFinding>): GateOutcome => {
+  if (findings.some((finding) => finding.severity === 'CRITICAL')) {
+    return 'BLOCK';
+  }
+  return findings.length > 0 ? 'WARN' : 'PASS';
+};
+
+const bySeverity = (findings: ReadonlyArray<SnapshotFinding>): Record<Severity, number> => {
+  const counts: Record<Severity, number> = {
+    INFO: 0,
+    WARN: 0,
+    ERROR: 0,
+    CRITICAL: 0,
+  };
+  for (const finding of findings) {
+    counts[finding.severity] += 1;
+  }
+  return counts;
+};
+
+const toCompatibilityViolations = (
+  findings: ReadonlyArray<SnapshotFinding>
+): CompatibilityViolation[] => {
+  return findings.map((finding) => ({
+    ruleId: finding.ruleId,
+    level: finding.severity,
+    code: finding.code,
+    message: finding.message,
+    file: finding.file,
+    lines: finding.lines,
+  }));
+};
+
+const updateLedger = (params: {
+  findings: ReadonlyArray<SnapshotFinding>;
+  previousEvidence?: AiEvidenceV2_1;
+  now: string;
+}): LedgerEntry[] => {
+  const previous = new Map<string, LedgerEntry>();
+  for (const entry of params.previousEvidence?.ledger ?? []) {
+    previous.set(ledgerKey(entry), entry);
+  }
+
+  const activeLedger = params.findings.map<LedgerEntry>((finding) => {
+    const key = findingKey(finding);
+    const prior = previous.get(key);
+    return {
+      ruleId: finding.ruleId,
+      file: finding.file,
+      lines: finding.lines,
+      firstSeen: prior?.firstSeen ?? params.now,
+      lastSeen: params.now,
+    };
+  });
+
+  return activeLedger.sort((left, right) => ledgerKey(left).localeCompare(ledgerKey(right)));
+};
+
+const normalizePlatforms = (
+  platforms: Record<string, PlatformState>
+): Record<string, PlatformState> => {
+  const ordered: Record<string, PlatformState> = {};
+  for (const platform of Object.keys(platforms).sort()) {
+    ordered[platform] = {
+      detected: platforms[platform].detected,
+      confidence: platforms[platform].confidence,
+    };
+  }
+  return ordered;
+};
+
+const normalizeRulesets = (rulesets: ReadonlyArray<RulesetState>): RulesetState[] => {
+  const unique = new Map<string, RulesetState>();
+  for (const ruleset of rulesets) {
+    const key = `${ruleset.platform}::${ruleset.bundle}`;
+    if (!unique.has(key)) {
+      unique.set(key, {
+        platform: ruleset.platform,
+        bundle: ruleset.bundle,
+        hash: ruleset.hash,
+      });
+    }
+  }
+
+  return Array.from(unique.values()).sort((left, right) => {
+    const byPlatform = left.platform.localeCompare(right.platform);
+    return byPlatform !== 0 ? byPlatform : left.bundle.localeCompare(right.bundle);
+  });
+};
+
+export function buildEvidence(params: BuildEvidenceParams): AiEvidenceV2_1 {
+  const now = new Date().toISOString();
+  const consolidatedFindings = normalizeAndDedupeFindings(params.findings);
+  const normalizedFindings = consolidatedFindings.findings;
+  const outcome = params.gateOutcome ?? toGateOutcome(normalizedFindings);
+  const gateStatus = outcome === 'BLOCK' ? 'BLOCKED' : 'ALLOWED';
+  const severity = bySeverity(normalizedFindings);
+  const humanIntent = resolveHumanIntent({
+    now,
+    inputIntent: params.humanIntent,
+    previousEvidence: params.previousEvidence,
+  });
+
+  return {
+    version: '2.1',
+    timestamp: now,
+    snapshot: {
+      stage: params.stage,
+      outcome,
+      findings: normalizedFindings,
+    },
+    ledger: updateLedger({
+      findings: normalizedFindings,
+      previousEvidence: params.previousEvidence,
+      now,
+    }),
+    platforms: normalizePlatforms(params.detectedPlatforms),
+    rulesets: normalizeRulesets(params.loadedRulesets),
+    human_intent: humanIntent,
+    ai_gate: {
+      status: gateStatus,
+      violations: toCompatibilityViolations(normalizedFindings),
+      human_intent: humanIntent,
+    },
+    severity_metrics: {
+      gate_status: gateStatus,
+      total_violations: normalizedFindings.length,
+      by_severity: severity,
+    },
+    consolidation:
+      consolidatedFindings.suppressed.length > 0
+        ? { suppressed: consolidatedFindings.suppressed }
+        : undefined,
+  };
+}

package/integrations/evidence/generateEvidence.ts

@@ -0,0 +1,14 @@
+import { buildEvidence, type BuildEvidenceParams } from './buildEvidence';
+import type { AiEvidenceV2_1 } from './schema';
+import { writeEvidence, type WriteEvidenceResult } from './writeEvidence';
+
+export type GenerateEvidenceResult = {
+  evidence: AiEvidenceV2_1;
+  write: WriteEvidenceResult;
+};
+
+export const generateEvidence = (params: BuildEvidenceParams): GenerateEvidenceResult => {
+  const evidence = buildEvidence(params);
+  const write = writeEvidence(evidence);
+  return { evidence, write };
+};

package/integrations/evidence/humanIntent.ts

@@ -0,0 +1,115 @@
+import type { AiEvidenceV2_1, HumanIntentConfidence, HumanIntentState } from './schema';
+
+const normalizeText = (value: unknown): string | null => {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+};
+
+const normalizeTextList = (value: unknown): string[] => {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const result: string[] = [];
+  const seen = new Set<string>();
+  for (const item of value) {
+    const text = normalizeText(item);
+    if (!text || seen.has(text)) {
+      continue;
+    }
+    seen.add(text);
+    result.push(text);
+  }
+  return result;
+};
+
+const normalizeDateIso = (value: unknown): string | null => {
+  const normalized = normalizeText(value);
+  if (!normalized) {
+    return null;
+  }
+  const date = Date.parse(normalized);
+  if (!Number.isFinite(date)) {
+    return null;
+  }
+  return new Date(date).toISOString();
+};
+
+const normalizeConfidence = (value: unknown): HumanIntentConfidence => {
+  if (value === 'high' || value === 'medium' || value === 'low' || value === 'unset') {
+    return value;
+  }
+  return 'unset';
+};
+
+export const normalizeHumanIntent = (
+  value: HumanIntentState | null | undefined
+): HumanIntentState | null => {
+  if (!value) {
+    return null;
+  }
+
+  const preservedAt = normalizeDateIso(value.preserved_at);
+  if (!preservedAt) {
+    return null;
+  }
+  const hint = normalizeText(value._hint);
+
+  return {
+    primary_goal: normalizeText(value.primary_goal),
+    secondary_goals: normalizeTextList(value.secondary_goals),
+    non_goals: normalizeTextList(value.non_goals),
+    constraints: normalizeTextList(value.constraints),
+    confidence_level: normalizeConfidence(value.confidence_level),
+    set_by: normalizeText(value.set_by),
+    set_at: normalizeDateIso(value.set_at),
+    expires_at: normalizeDateIso(value.expires_at),
+    preserved_at: preservedAt,
+    preservation_count:
+      Number.isFinite(value.preservation_count) && value.preservation_count >= 0
+        ? Math.trunc(value.preservation_count)
+        : 0,
+    ...(hint ? { _hint: hint } : {}),
+  };
+};
+
+export const isHumanIntentExpired = (
+  intent: HumanIntentState,
+  now: string
+): boolean => {
+  if (!intent.expires_at) {
+    return false;
+  }
+  const expiresAt = Date.parse(intent.expires_at);
+  const nowTime = Date.parse(now);
+  if (!Number.isFinite(expiresAt) || !Number.isFinite(nowTime)) {
+    return true;
+  }
+  return expiresAt <= nowTime;
+};
+
+export const resolveHumanIntent = (params: {
+  now: string;
+  inputIntent?: HumanIntentState | null;
+  previousEvidence?: Pick<AiEvidenceV2_1, 'human_intent'>;
+}): HumanIntentState | null => {
+  const candidate = normalizeHumanIntent(
+    params.inputIntent ?? params.previousEvidence?.human_intent ?? null
+  );
+  if (!candidate || isHumanIntentExpired(candidate, params.now)) {
+    return null;
+  }
+
+  const isExplicitInput = typeof params.inputIntent !== 'undefined';
+  const nextCount = isExplicitInput
+    ? candidate.preservation_count
+    : candidate.preservation_count + 1;
+
+  return {
+    ...candidate,
+    preserved_at: params.now,
+    preservation_count: nextCount,
+  };
+};

package/integrations/evidence/readEvidence.ts

@@ -0,0 +1,47 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { AiEvidenceV2_1 } from './schema';
+
+export type EvidenceReadResult =
+  | { kind: 'missing' }
+  | { kind: 'invalid'; version?: string }
+  | { kind: 'valid'; evidence: AiEvidenceV2_1 };
+
+export const readEvidenceResult = (repoRoot: string): EvidenceReadResult => {
+  const evidencePath = resolve(repoRoot, '.ai_evidence.json');
+  if (!existsSync(evidencePath)) {
+    return { kind: 'missing' };
+  }
+
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(evidencePath, 'utf8'));
+    if (
+      typeof parsed === 'object' &&
+      parsed !== null &&
+      'version' in parsed &&
+      (parsed as { version?: unknown }).version === '2.1'
+    ) {
+      return {
+        kind: 'valid',
+        evidence: parsed as AiEvidenceV2_1,
+      };
+    }
+    const versionCandidate =
+      typeof parsed === 'object' && parsed !== null && 'version' in parsed
+        ? (parsed as { version?: unknown }).version
+        : undefined;
+    return {
+      kind: 'invalid',
+      version: typeof versionCandidate === 'string' ? versionCandidate : undefined,
+    };
+  } catch {
+    return {
+      kind: 'invalid',
+    };
+  }
+};
+
+export const readEvidence = (repoRoot: string): AiEvidenceV2_1 | undefined => {
+  const result = readEvidenceResult(repoRoot);
+  return result.kind === 'valid' ? result.evidence : undefined;
+};

package/integrations/evidence/schema.ts

@@ -0,0 +1,97 @@
+import type { GateOutcome } from '../../core/gate/GateOutcome';
+import type { GateStage } from '../../core/gate/GateStage';
+import type { Severity } from '../../core/rules/Severity';
+
+export type EvidenceLines = string | number | readonly number[];
+
+export type SnapshotFinding = {
+  ruleId: string;
+  severity: Severity;
+  code: string;
+  message: string;
+  file: string;
+  lines?: EvidenceLines;
+};
+
+export type Snapshot = {
+  stage: GateStage;
+  outcome: GateOutcome;
+  findings: SnapshotFinding[];
+};
+
+export type LedgerEntry = {
+  ruleId: string;
+  file: string;
+  lines?: EvidenceLines;
+  firstSeen: string;
+  lastSeen: string;
+};
+
+export type PlatformState = {
+  detected: boolean;
+  confidence: 'HIGH' | 'MEDIUM' | 'LOW';
+};
+
+export type RulesetState = {
+  platform: string;
+  bundle: string;
+  hash: string;
+};
+
+export type HumanIntentConfidence = 'high' | 'medium' | 'low' | 'unset';
+
+export type HumanIntentState = {
+  primary_goal: string | null;
+  secondary_goals: string[];
+  non_goals: string[];
+  constraints: string[];
+  confidence_level: HumanIntentConfidence;
+  set_by: string | null;
+  set_at: string | null;
+  expires_at: string | null;
+  preserved_at: string;
+  preservation_count: number;
+  _hint?: string;
+};
+
+export type CompatibilityViolation = {
+  ruleId: string;
+  level: Severity;
+  code: string;
+  message: string;
+  file: string;
+  lines?: EvidenceLines;
+};
+
+export type ConsolidationSuppressedFinding = {
+  ruleId: string;
+  file: string;
+  lines?: EvidenceLines;
+  replacedByRuleId: string;
+  replacementRuleId?: string | null;
+  platform?: string;
+  reason: string;
+};
+
+export type AiEvidenceV2_1 = {
+  version: '2.1';
+  timestamp: string;
+  snapshot: Snapshot;
+  ledger: LedgerEntry[];
+  platforms: Record<string, PlatformState>;
+  rulesets: RulesetState[];
+  human_intent: HumanIntentState | null;
+  ai_gate: {
+    status: 'ALLOWED' | 'BLOCKED';
+    violations: CompatibilityViolation[];
+    human_intent: HumanIntentState | null;
+  };
+  severity_metrics: {
+    gate_status: 'ALLOWED' | 'BLOCKED';
+    total_violations: number;
+    by_severity: Record<Severity, number>;
+  };
+  consolidation?: {
+    suppressed: ConsolidationSuppressedFinding[];
+  };
+};