@dogfood-lab/findings 1.2.1

package/derive/dedupe.js

@@ -0,0 +1,107 @@
+/**
+ * Deduplication logic for derived candidate findings.
+ *
+ * Dedupe law:
+ *  - Same record re-derived → same ID → skip if identical candidate exists
+ *  - Same ID with non-candidate status → collision, not overwrite
+ *  - Multiple evidence points in one record that map to one lesson → one finding
+ */
+
+import { computeDedupeKey } from './ids.js';
+
+/**
+ * Deduplicate a list of raw derived candidates.
+ * Returns unique candidates with collision info.
+ *
+ * @param {Array} candidates - Raw derived candidates from rules.
+ * @returns {{ unique: Array, skipped: number }}
+ */
+export function dedupeWithinBatch(candidates) {
+  const seen = new Map();
+  const unique = [];
+  let skipped = 0;
+
+  for (const c of candidates) {
+    const key = computeDedupeKey({
+      repo: c.repo,
+      issue_kind: c.issue_kind,
+      root_cause_kind: c.root_cause_kind,
+      journey_stage: c.journey_stage,
+      slug: c.finding_id
+    });
+
+    if (seen.has(key)) {
+      skipped++;
+      continue;
+    }
+    seen.set(key, true);
+    unique.push(c);
+  }
+
+  return { unique, skipped };
+}
+
+/**
+ * Check existing findings on disk for collisions.
+ *
+ * @param {Array} candidates - Candidate findings to check.
+ * @param {Array<{ data: object }>} existingFindings - Already-loaded findings from disk.
+ * @returns {{ toWrite: Array, skippedUnchanged: number, collisions: Array<{ findingId: string, existingStatus: string }> }}
+ */
+export function dedupeAgainstExisting(candidates, existingFindings) {
+  const existingById = new Map();
+  for (const f of existingFindings) {
+    if (f.data?.finding_id) {
+      existingById.set(f.data.finding_id, f.data);
+    }
+  }
+
+  const toWrite = [];
+  let skippedUnchanged = 0;
+  const collisions = [];
+
+  for (const c of candidates) {
+    const existing = existingById.get(c.finding_id);
+
+    if (!existing) {
+      toWrite.push(c);
+      continue;
+    }
+
+    // Same ID exists — check status
+    if (existing.status !== 'candidate') {
+      // Non-candidate status: collision, don't overwrite
+      collisions.push({
+        findingId: c.finding_id,
+        existingStatus: existing.status
+      });
+      continue;
+    }
+
+    // Same ID, still candidate — skip if unchanged
+    if (isSameCandidate(c, existing)) {
+      skippedUnchanged++;
+      continue;
+    }
+
+    // Same ID, still candidate, but content changed — refresh
+    toWrite.push(c);
+  }
+
+  return { toWrite, skippedUnchanged, collisions };
+}
+
+/**
+ * Check if two findings are substantively identical.
+ * Ignores timestamps and derivation metadata.
+ */
+function isSameCandidate(a, b) {
+  return (
+    a.issue_kind === b.issue_kind &&
+    a.root_cause_kind === b.root_cause_kind &&
+    a.remediation_kind === b.remediation_kind &&
+    a.transfer_scope === b.transfer_scope &&
+    a.summary === b.summary &&
+    a.title === b.title
+  );
+}

package/derive/derive-findings.js

@@ -0,0 +1,187 @@
+/**
+ * Main derivation engine.
+ * Takes verified dogfood records and deterministically emits candidate findings.
+ *
+ * Usage:
+ *   deriveFromRecord(record, { rejected }) → CandidateFinding[]
+ *   deriveFromRecords(records) → { candidates, stats }
+ */
+
+import { RULES } from './rules.js';
+import { generateFindingId } from './ids.js';
+import { dedupeWithinBatch } from './dedupe.js';
+
+/**
+ * Derive candidate findings from a single verified record.
+ *
+ * Returns a plain array of candidates for back-compat. To get per-rule errors,
+ * use `deriveFromRecordWithErrors` which returns `{ candidates, ruleErrors }`.
+ *
+ * @param {object} record - Full persisted dogfood record.
+ * @param {{ rejected?: boolean }} opts
+ * @returns {Array} - Zero or more schema-valid candidate finding objects.
+ */
+export function deriveFromRecord(record, opts = {}) {
+  return deriveFromRecordWithErrors(record, opts).candidates;
+}
+
+/**
+ * Derive candidate findings from a single verified record, exposing per-rule errors.
+ *
+ * Each rule's `applies` and `derive` runs in isolation. A rule that throws does
+ * NOT crash the engine, but the error IS recorded in `ruleErrors` and ALSO
+ * logged to stderr so operators see it in CI logs. Callers MUST treat a non-empty
+ * ruleErrors as a partial failure — the engine "succeeded" only if `ruleErrors`
+ * is empty.
+ *
+ * @param {object} record
+ * @param {{ rejected?: boolean }} opts
+ * @returns {{ candidates: Array, ruleErrors: Array<{ ruleId: string, runId: string, message: string }> }}
+ */
+export function deriveFromRecordWithErrors(record, opts = {}) {
+  const rejected = opts.rejected ?? false;
+  const repo = record.repo || '';
+  const repoSlug = repo.split('/').pop() || 'unknown';
+  const runId = record.run_id || 'unknown';
+  const now = new Date().toISOString();
+
+  const raw = [];
+  const ruleErrors = [];
+
+  // Iterate per-scenario so multi-scenario records emit findings tied to the
+  // RIGHT scenario — not just scenario_results[0]. The scenario-aware helpers
+  // in rules.js (scenarioSurface, scenarioMode, scenarioId, failedSteps,
+  // scenarioVerdict) all read index 0; instead of touching every rule, we
+  // present each rule a per-scenario VIEW of the record where scenario_results
+  // contains only that one scenario. The finding's execution_mode and
+  // scenario_ids in assembleFinding then come from the right scenario.
+  //
+  // Backward compat: a single-scenario record runs one iteration with the
+  // same scenario at index 0 → byte-identical output to the old code path.
+  // Rules that already iterated all scenarios internally (rule-blocked-scenario,
+  // rule-execution-mode-gap) emit per-iteration findings; dedupeWithinBatch
+  // collapses any duplicates by dedupe key.
+  const scenarios = Array.isArray(record.scenario_results) && record.scenario_results.length > 0
+    ? record.scenario_results
+    : [null];
+
+  for (const scenario of scenarios) {
+    const scenarioView = scenario === null
+      ? record
+      : { ...record, scenario_results: [scenario] };
+    const ctx = { record: scenarioView, rejected, repoSlug };
+
+    for (const rule of RULES) {
+      try {
+        if (rule.applies(ctx)) {
+          const emitted = rule.derive(ctx);
+          for (const e of emitted) {
+            raw.push(assembleFinding(e, scenarioView, rule, repoSlug, now));
+          }
+        }
+      } catch (err) {
+        const message = err && err.message ? err.message : String(err);
+        const entry = { ruleId: rule.ruleId, runId, message };
+        ruleErrors.push(entry);
+        // Surface the failure on stderr so operators see it in CI logs.
+        // Do NOT crash the engine — other rules still get a chance to run.
+        console.error(
+          `[derive] rule '${rule.ruleId}' threw on run_id=${runId}: ${message}`
+        );
+      }
+    }
+  }
+
+  // Dedupe within this record's batch
+  const { unique } = dedupeWithinBatch(raw);
+  return { candidates: unique, ruleErrors };
+}
+
+/**
+ * Derive candidate findings from multiple records.
+ *
+ * The returned `ruleErrors` collects every per-rule throw across every record.
+ * `stats.ruleErrors` is the count for quick scoreboarding. Callers MUST treat a
+ * non-zero ruleErrors count as a partial failure — derivation did NOT fully
+ * succeed if any rule threw.
+ *
+ * @param {Array<{ record: object, rejected: boolean }>} entries
+ * @returns {{ candidates: Array, ruleErrors: Array<{ ruleId: string, runId: string, message: string }>, stats: { recordsProcessed: number, rulesEvaluated: number, candidatesEmitted: number, deduped: number, ruleErrors: number } }}
+ */
+export function deriveFromRecords(entries) {
+  const allCandidates = [];
+  const allRuleErrors = [];
+  let rulesEvaluated = 0;
+
+  for (const entry of entries) {
+    rulesEvaluated += RULES.length;
+    const { candidates, ruleErrors } = deriveFromRecordWithErrors(
+      entry.record,
+      { rejected: entry.rejected }
+    );
+    allCandidates.push(...candidates);
+    allRuleErrors.push(...ruleErrors);
+  }
+
+  const { unique, skipped } = dedupeWithinBatch(allCandidates);
+
+  return {
+    candidates: unique,
+    ruleErrors: allRuleErrors,
+    stats: {
+      recordsProcessed: entries.length,
+      rulesEvaluated,
+      candidatesEmitted: unique.length,
+      deduped: skipped,
+      ruleErrors: allRuleErrors.length
+    }
+  };
+}
+
+/**
+ * Assemble a full schema-valid finding object from rule output.
+ */
+function assembleFinding(raw, record, rule, repoSlug, now) {
+  const findingId = generateFindingId(repoSlug, raw.slug);
+
+  return {
+    schema_version: '1.0.0',
+    finding_id: findingId,
+    title: raw.title,
+    status: 'candidate',
+    repo: record.repo,
+    product_surface: raw.product_surface,
+    execution_mode: record.scenario_results?.[0]?.execution_mode,
+    journey_stage: raw.journey_stage,
+    issue_kind: raw.issue_kind,
+    root_cause_kind: raw.root_cause_kind,
+    remediation_kind: raw.remediation_kind,
+    transfer_scope: raw.transfer_scope,
+    summary: raw.summary,
+    source_record_ids: [record.run_id],
+    scenario_ids: record.scenario_results
+      ?.map(s => s.scenario_id)
+      .filter(Boolean) || [],
+    evidence: raw.evidence,
+    derived: {
+      method: 'deterministic_rule',
+      rule_id: rule.ruleId,
+      derived_at: now,
+      rationale: raw.rationale
+    },
+    created_at: now,
+    updated_at: now
+  };
+}
+
+/**
+ * Get the rule inventory (for explain/list).
+ */
+export function getRuleInventory() {
+  return RULES.map(r => ({
+    ruleId: r.ruleId,
+    description: r.description
+  }));
+}
+
+export { RULES };

package/derive/ids.js

@@ -0,0 +1,48 @@
+/**
+ * Stable ID generation and dedupe key computation for derived findings.
+ *
+ * ID law: same record + same rule + same lesson slug = same finding ID.
+ * No timestamp noise in IDs.
+ */
+
+/**
+ * Generate a stable finding ID from derivation context.
+ * Format: dfind-<repo-slug>-<lesson-slug>
+ *
+ * @param {string} repoSlug - e.g. "repo-crawler-mcp"
+ * @param {string} lessonSlug - e.g. "surface-misclassification"
+ * @returns {string}
+ */
+export function generateFindingId(repoSlug, lessonSlug) {
+  const normalized = `dfind-${sanitize(repoSlug)}-${sanitize(lessonSlug)}`;
+  return normalized;
+}
+
+/**
+ * Compute a dedupe key for collision detection.
+ * Two findings with the same dedupe key are considered the same lesson.
+ *
+ * @param {{ repo: string, issue_kind: string, root_cause_kind: string, journey_stage: string, slug: string }} fields
+ * @returns {string}
+ */
+export function computeDedupeKey(fields) {
+  return [
+    fields.repo,
+    fields.issue_kind,
+    fields.root_cause_kind,
+    fields.journey_stage,
+    fields.slug
+  ].join('::');
+}
+
+/**
+ * Sanitize a string for use in finding IDs.
+ * Lowercase, replace non-alphanumeric with hyphens, collapse runs, trim.
+ */
+function sanitize(s) {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}

package/derive/index.js

@@ -0,0 +1,9 @@
+/**
+ * Derivation engine exports.
+ */
+export { deriveFromRecord, deriveFromRecordWithErrors, deriveFromRecords, getRuleInventory, RULES } from './derive-findings.js';
+export { generateFindingId, computeDedupeKey } from './ids.js';
+export { dedupeWithinBatch, dedupeAgainstExisting } from './dedupe.js';
+export { loadRecordsForRepo, loadRecordById, loadAllRecords } from './load-records.js';
+export { writeFinding, writeFindings } from './write-findings.js';
+export { getRuleById } from './rules.js';

package/derive/load-records.js

@@ -0,0 +1,153 @@
+/**
+ * Record loader for the derivation engine.
+ * Discovers and loads verified dogfood records from the filesystem.
+ */
+
+import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { resolve, join, extname } from 'node:path';
+
+import { isUnsafeSegment } from '@dogfood-lab/ingest/lib/unsafe-segment.js';
+
+/**
+ * Load all records for a specific repo.
+ *
+ * @param {string} rootDir - dogfood-labs repo root.
+ * @param {string} repoKey - Full org/repo key (e.g. "mcp-tool-shop-org/repo-crawler-mcp").
+ * @returns {Array<{ record: object, rejected: boolean, path: string }>}
+ */
+export function loadRecordsForRepo(rootDir, repoKey) {
+  const [org, repo] = repoKey.split('/');
+  // Path-traversal guard: F-916867-005. Mirrors persist.js + load-context.js
+  // via the central helper at @dogfood-lab/ingest/lib/unsafe-segment.js.
+  // A malformed repoKey (`..` or path-separator) would otherwise resolve
+  // outside the records tree and silently load (or skip) unrelated files.
+  if (!org || !repo || isUnsafeSegment(org) || isUnsafeSegment(repo)) {
+    return [];
+  }
+  const results = [];
+
+  // Accepted records
+  const acceptedDir = resolve(rootDir, 'records', org, repo);
+  results.push(...walkRecords(acceptedDir, false));
+
+  // Rejected records
+  const rejectedDir = resolve(rootDir, 'records', '_rejected', org, repo);
+  results.push(...walkRecords(rejectedDir, true));
+
+  return results;
+}
+
+/**
+ * Load a single record by run_id.
+ *
+ * @param {string} rootDir - dogfood-labs repo root.
+ * @param {string} runId - The run_id to find.
+ * @returns {{ record: object, rejected: boolean, path: string } | null}
+ */
+export function loadRecordById(rootDir, runId) {
+  // Search accepted records
+  const acceptedRoot = resolve(rootDir, 'records');
+  const found = findRecordFile(acceptedRoot, runId, false);
+  if (found) return found;
+
+  // Search rejected records
+  const rejectedRoot = resolve(rootDir, 'records', '_rejected');
+  return findRecordFile(rejectedRoot, runId, true);
+}
+
+/**
+ * Load all records across all repos.
+ *
+ * @param {string} rootDir - dogfood-labs repo root.
+ * @returns {Array<{ record: object, rejected: boolean, path: string }>}
+ */
+export function loadAllRecords(rootDir) {
+  const results = [];
+
+  // Accepted records
+  const recordsDir = resolve(rootDir, 'records');
+  if (existsSync(recordsDir)) {
+    for (const org of listDirs(recordsDir)) {
+      if (org === '_rejected') continue;
+      const orgDir = join(recordsDir, org);
+      for (const repo of listDirs(orgDir)) {
+        const repoDir = join(orgDir, repo);
+        results.push(...walkRecords(repoDir, false));
+      }
+    }
+  }
+
+  // Rejected records
+  const rejectedDir = resolve(rootDir, 'records', '_rejected');
+  if (existsSync(rejectedDir)) {
+    for (const org of listDirs(rejectedDir)) {
+      const orgDir = join(rejectedDir, org);
+      for (const repo of listDirs(orgDir)) {
+        const repoDir = join(orgDir, repo);
+        results.push(...walkRecords(repoDir, true));
+      }
+    }
+  }
+
+  return results;
+}
+
+/** Walk a record directory tree and load all .json files. */
+function walkRecords(dir, rejected) {
+  if (!existsSync(dir)) return [];
+  const results = [];
+
+  function walk(d) {
+    for (const entry of readdirSync(d)) {
+      const full = join(d, entry);
+      try {
+        if (statSync(full).isDirectory()) {
+          walk(full);
+        } else if (extname(entry) === '.json') {
+          const data = JSON.parse(readFileSync(full, 'utf-8'));
+          results.push({ record: data, rejected, path: full });
+        }
+      } catch {
+        // Skip unreadable files
+      }
+    }
+  }
+
+  walk(dir);
+  return results;
+}
+
+/** Find a specific record file by run_id pattern. */
+function findRecordFile(rootDir, runId, rejected) {
+  if (!existsSync(rootDir)) return null;
+
+  function search(dir) {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      try {
+        if (statSync(full).isDirectory()) {
+          const found = search(full);
+          if (found) return found;
+        } else if (extname(entry) === '.json' && entry.includes(runId)) {
+          const data = JSON.parse(readFileSync(full, 'utf-8'));
+          if (data.run_id === runId) {
+            return { record: data, rejected, path: full };
+          }
+        }
+      } catch {
+        // Skip
+      }
+    }
+    return null;
+  }
+
+  return search(rootDir);
+}
+
+function listDirs(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter(name => {
+    try { return statSync(join(dir, name)).isDirectory(); }
+    catch { return false; }
+  });
+}