@dogfood-lab/findings 1.2.2 → 1.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogfood-lab/findings",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "type": "module",
   "description": "Finding contract spine for testing-os. Validates, reads, lists, and queries evidence-bound findings — the fourth contract alongside record, scenario, and policy.",
   "main": "index.js",
@@ -46,7 +46,7 @@
     "js-yaml": "^4.1.0"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "author": "mcp-tool-shop",
   "license": "MIT",

package/reader.js

@@ -1,156 +1,156 @@
-/**
- * Finding reader/lister.
- * Discovers findings from the filesystem, supports filtering and lookup.
- */
-
-import { readdirSync, existsSync, statSync } from 'node:fs';
-import { resolve, join, basename, extname } from 'node:path';
-import { parseFinding, validateFinding } from './validate.js';
-
-/**
- * Discover all .yaml finding files under a root directory.
- * Walks findings/<org>/<repo>/*.yaml
- *
- * @param {string} rootDir - The dogfood-labs repo root.
- * @returns {string[]} Array of absolute paths to finding files.
- */
-export function discoverFindings(rootDir) {
-  const findingsDir = resolve(rootDir, 'findings');
-  if (!existsSync(findingsDir)) return [];
-
-  const paths = [];
-
-  // Walk: findings/<org>/<repo>/*.yaml
-  for (const org of listDirs(findingsDir)) {
-    const orgDir = join(findingsDir, org);
-    for (const repo of listDirs(orgDir)) {
-      const repoDir = join(orgDir, repo);
-      for (const file of readdirSync(repoDir)) {
-        if (extname(file) === '.yaml') {
-          paths.push(resolve(repoDir, file));
-        }
-      }
-    }
-  }
-
-  return paths.sort();
-}
-
-/**
- * Discover finding files from fixtures directory.
- * @param {string} rootDir - The dogfood-labs repo root.
- * @param {'valid' | 'invalid'} kind - Which fixture set.
- * @returns {string[]} Array of absolute paths.
- */
-export function discoverFixtures(rootDir, kind) {
-  const dir = resolve(rootDir, 'fixtures', 'findings', kind);
-  if (!existsSync(dir)) return [];
-
-  return readdirSync(dir)
-    .filter(f => extname(f) === '.yaml')
-    .map(f => resolve(dir, f))
-    .sort();
-}
-
-/**
- * Load all findings from disk (real or fixtures).
- * Returns parsed + validated findings.
- *
- * @param {string} rootDir - The dogfood-labs repo root.
- * @param {{ fixtures?: boolean, fixtureKind?: 'valid' | 'invalid' }} opts
- * @returns {Array<{ path: string, data: object | null, valid: boolean, errors: Array }>}
- */
-export function loadFindings(rootDir, opts = {}) {
-  const paths = opts.fixtures
-    ? discoverFixtures(rootDir, opts.fixtureKind || 'valid')
-    : discoverFindings(rootDir);
-
-  return paths.map(filePath => {
-    const { data, error } = parseFinding(filePath);
-    if (error) {
-      return { path: filePath, data: null, valid: false, errors: [{ path: '/', message: error }] };
-    }
-    const result = validateFinding(data);
-    return { path: filePath, data, ...result };
-  });
-}
-
-/**
- * Find a single finding by its finding_id.
- * Searches real findings first, then fixtures.
- *
- * @param {string} rootDir - The dogfood-labs repo root.
- * @param {string} findingId - The finding_id to look up.
- * @returns {{ path: string, data: object, valid: boolean, errors: Array } | null}
- */
-export function findById(rootDir, findingId) {
-  // Search real findings
-  for (const filePath of discoverFindings(rootDir)) {
-    const { data } = parseFinding(filePath);
-    if (data && data.finding_id === findingId) {
-      const result = validateFinding(data);
-      return { path: filePath, data, ...result };
-    }
-  }
-
-  // Search valid fixtures
-  for (const filePath of discoverFixtures(rootDir, 'valid')) {
-    const { data } = parseFinding(filePath);
-    if (data && data.finding_id === findingId) {
-      const result = validateFinding(data);
-      return { path: filePath, data, ...result };
-    }
-  }
-
-  return null;
-}
-
-/**
- * Filter a list of loaded findings.
- *
- * @param {Array<{ data: object }>} findings - Loaded findings.
- * @param {{ repo?: string, status?: string, surface?: string, issueKind?: string, transferScope?: string }} filters
- * @returns {Array}
- */
-export function filterFindings(findings, filters = {}) {
-  return findings.filter(f => {
-    if (!f.data) return false;
-    if (filters.repo && f.data.repo !== filters.repo) return false;
-    if (filters.status && f.data.status !== filters.status) return false;
-    if (filters.surface && f.data.product_surface !== filters.surface) return false;
-    if (filters.issueKind && f.data.issue_kind !== filters.issueKind) return false;
-    if (filters.transferScope && f.data.transfer_scope !== filters.transferScope) return false;
-    return true;
-  });
-}
-
-/**
- * Check for duplicate finding_ids across all findings.
- * @param {Array<{ data: object, path: string }>} findings
- * @returns {Array<{ findingId: string, paths: string[] }>}
- */
-export function findDuplicates(findings) {
-  const seen = new Map();
-  for (const f of findings) {
-    if (!f.data || !f.data.finding_id) continue;
-    const id = f.data.finding_id;
-    if (!seen.has(id)) seen.set(id, []);
-    seen.get(id).push(f.path);
-  }
-
-  return Array.from(seen.entries())
-    .filter(([, paths]) => paths.length > 1)
-    .map(([findingId, paths]) => ({ findingId, paths }));
-}
-
-/** List subdirectories of a directory. */
-function listDirs(dir) {
-  if (!existsSync(dir)) return [];
-  return readdirSync(dir).filter(name => {
-    try {
-      return statSync(join(dir, name)).isDirectory();
-    } catch {
-      return false;
-    }
-  });
-}
+/**
+ * Finding reader/lister.
+ * Discovers findings from the filesystem, supports filtering and lookup.
+ */
+
+import { readdirSync, existsSync, statSync } from 'node:fs';
+import { resolve, join, basename, extname } from 'node:path';
+import { parseFinding, validateFinding } from './validate.js';
+
+/**
+ * Discover all .yaml finding files under a root directory.
+ * Walks findings/<org>/<repo>/*.yaml
+ *
+ * @param {string} rootDir - The dogfood-labs repo root.
+ * @returns {string[]} Array of absolute paths to finding files.
+ */
+export function discoverFindings(rootDir) {
+  const findingsDir = resolve(rootDir, 'findings');
+  if (!existsSync(findingsDir)) return [];
+
+  const paths = [];
+
+  // Walk: findings/<org>/<repo>/*.yaml
+  for (const org of listDirs(findingsDir)) {
+    const orgDir = join(findingsDir, org);
+    for (const repo of listDirs(orgDir)) {
+      const repoDir = join(orgDir, repo);
+      for (const file of readdirSync(repoDir)) {
+        if (extname(file) === '.yaml') {
+          paths.push(resolve(repoDir, file));
+        }
+      }
+    }
+  }
+
+  return paths.sort();
+}
+
+/**
+ * Discover finding files from fixtures directory.
+ * @param {string} rootDir - The dogfood-labs repo root.
+ * @param {'valid' | 'invalid'} kind - Which fixture set.
+ * @returns {string[]} Array of absolute paths.
+ */
+export function discoverFixtures(rootDir, kind) {
+  const dir = resolve(rootDir, 'fixtures', 'findings', kind);
+  if (!existsSync(dir)) return [];
+
+  return readdirSync(dir)
+    .filter(f => extname(f) === '.yaml')
+    .map(f => resolve(dir, f))
+    .sort();
+}
+
+/**
+ * Load all findings from disk (real or fixtures).
+ * Returns parsed + validated findings.
+ *
+ * @param {string} rootDir - The dogfood-labs repo root.
+ * @param {{ fixtures?: boolean, fixtureKind?: 'valid' | 'invalid' }} opts
+ * @returns {Array<{ path: string, data: object | null, valid: boolean, errors: Array }>}
+ */
+export function loadFindings(rootDir, opts = {}) {
+  const paths = opts.fixtures
+    ? discoverFixtures(rootDir, opts.fixtureKind || 'valid')
+    : discoverFindings(rootDir);
+
+  return paths.map(filePath => {
+    const { data, error } = parseFinding(filePath);
+    if (error) {
+      return { path: filePath, data: null, valid: false, errors: [{ path: '/', message: error }] };
+    }
+    const result = validateFinding(data);
+    return { path: filePath, data, ...result };
+  });
+}
+
+/**
+ * Find a single finding by its finding_id.
+ * Searches real findings first, then fixtures.
+ *
+ * @param {string} rootDir - The dogfood-labs repo root.
+ * @param {string} findingId - The finding_id to look up.
+ * @returns {{ path: string, data: object, valid: boolean, errors: Array } | null}
+ */
+export function findById(rootDir, findingId) {
+  // Search real findings
+  for (const filePath of discoverFindings(rootDir)) {
+    const { data } = parseFinding(filePath);
+    if (data && data.finding_id === findingId) {
+      const result = validateFinding(data);
+      return { path: filePath, data, ...result };
+    }
+  }
+
+  // Search valid fixtures
+  for (const filePath of discoverFixtures(rootDir, 'valid')) {
+    const { data } = parseFinding(filePath);
+    if (data && data.finding_id === findingId) {
+      const result = validateFinding(data);
+      return { path: filePath, data, ...result };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Filter a list of loaded findings.
+ *
+ * @param {Array<{ data: object }>} findings - Loaded findings.
+ * @param {{ repo?: string, status?: string, surface?: string, issueKind?: string, transferScope?: string }} filters
+ * @returns {Array}
+ */
+export function filterFindings(findings, filters = {}) {
+  return findings.filter(f => {
+    if (!f.data) return false;
+    if (filters.repo && f.data.repo !== filters.repo) return false;
+    if (filters.status && f.data.status !== filters.status) return false;
+    if (filters.surface && f.data.product_surface !== filters.surface) return false;
+    if (filters.issueKind && f.data.issue_kind !== filters.issueKind) return false;
+    if (filters.transferScope && f.data.transfer_scope !== filters.transferScope) return false;
+    return true;
+  });
+}
+
+/**
+ * Check for duplicate finding_ids across all findings.
+ * @param {Array<{ data: object, path: string }>} findings
+ * @returns {Array<{ findingId: string, paths: string[] }>}
+ */
+export function findDuplicates(findings) {
+  const seen = new Map();
+  for (const f of findings) {
+    if (!f.data || !f.data.finding_id) continue;
+    const id = f.data.finding_id;
+    if (!seen.has(id)) seen.set(id, []);
+    seen.get(id).push(f.path);
+  }
+
+  return Array.from(seen.entries())
+    .filter(([, paths]) => paths.length > 1)
+    .map(([findingId, paths]) => ({ findingId, paths }));
+}
+
+/** List subdirectories of a directory. */
+function listDirs(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter(name => {
+    try {
+      return statSync(join(dir, name)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+}

package/review/index.js

@@ -1,6 +1,6 @@
-/**
- * Review system exports.
- */
-export { isLawfulTransition, validateTransition, ACTION_TARGET_STATUS, REASON_REQUIRED } from './transitions.js';
-export { createEvent, appendEvent, getEventsForFinding, getAllEvents, getLogPath, generateEventId } from './event-log.js';
-export { performAction, performMerge, getReviewQueue } from './review-engine.js';
+/**
+ * Review system exports.
+ */
+export { isLawfulTransition, validateTransition, ACTION_TARGET_STATUS, REASON_REQUIRED } from './transitions.js';
+export { createEvent, appendEvent, getEventsForFinding, getAllEvents, getLogPath, generateEventId } from './event-log.js';
+export { performAction, performMerge, getReviewQueue } from './review-engine.js';

package/review/transitions.js

@@ -1,79 +1,79 @@
-/**
- * Status transition law for findings.
- *
- * Lawful transitions:
- *   candidate -> reviewed, accepted, rejected
- *   reviewed  -> accepted, rejected
- *   accepted  -> reviewed (via reopen/invalidate only)
- *   accepted  -> rejected (via invalidation/reversal only)
- *   rejected  -> reviewed (via reopen only)
- *
- * Forbidden:
- *   rejected -> candidate (no rewinding to machine output)
- *   any status -> candidate (except initial creation)
- */
-
-const TRANSITIONS = {
-  candidate: new Set(['reviewed', 'accepted', 'rejected']),
-  reviewed:  new Set(['accepted', 'rejected']),
-  accepted:  new Set(['reviewed', 'rejected']),
-  rejected:  new Set(['reviewed'])
-};
-
-/**
- * Check if a status transition is lawful.
- * @param {string} from - Current status.
- * @param {string} to - Desired status.
- * @returns {boolean}
- */
-export function isLawfulTransition(from, to) {
-  const allowed = TRANSITIONS[from];
-  if (!allowed) return false;
-  return allowed.has(to);
-}
-
-/**
- * Validate a transition and return error if invalid.
- * @param {string} from
- * @param {string} to
- * @returns {{ valid: boolean, error?: string }}
- */
-export function validateTransition(from, to) {
-  if (!TRANSITIONS[from]) {
-    return { valid: false, error: `Unknown status: "${from}"` };
-  }
-  if (!isLawfulTransition(from, to)) {
-    const allowed = [...TRANSITIONS[from]].join(', ');
-    return { valid: false, error: `Cannot transition from "${from}" to "${to}". Allowed: ${allowed}` };
-  }
-  return { valid: true };
-}
-
-/**
- * Map review actions to their target statuses.
- */
-export const ACTION_TARGET_STATUS = {
-  review: 'reviewed',
-  accept: 'accepted',
-  reject: 'rejected',
-  edit: null,        // edit preserves current status
-  merge: 'rejected', // merged sources become rejected (merged_into_canonical)
-  reopen: 'reviewed',
-  invalidate: 'reviewed', // invalidated accepted → back to reviewed with invalidation metadata
-  supersede: 'rejected'   // superseded finding becomes rejected
-};
-
-/**
- * Actions that require a reason.
- */
-export const REASON_REQUIRED = new Set(['reject', 'invalidate', 'merge', 'supersede']);
-
-/**
- * Actions that require from_status to be accepted.
- */
-export const REQUIRES_ACCEPTED = new Set(['invalidate']);
-
-/**
- * Actions that require from_status to be accepted or rejected.
- */
-export const REQUIRES_CLOSED = new Set(['reopen']);
+/**
+ * Status transition law for findings.
+ *
+ * Lawful transitions:
+ *   candidate -> reviewed, accepted, rejected
+ *   reviewed  -> accepted, rejected
+ *   accepted  -> reviewed (via reopen/invalidate only)
+ *   accepted  -> rejected (via invalidation/reversal only)
+ *   rejected  -> reviewed (via reopen only)
+ *
+ * Forbidden:
+ *   rejected -> candidate (no rewinding to machine output)
+ *   any status -> candidate (except initial creation)
+ */
+
+const TRANSITIONS = {
+  candidate: new Set(['reviewed', 'accepted', 'rejected']),
+  reviewed:  new Set(['accepted', 'rejected']),
+  accepted:  new Set(['reviewed', 'rejected']),
+  rejected:  new Set(['reviewed'])
+};
+
+/**
+ * Check if a status transition is lawful.
+ * @param {string} from - Current status.
+ * @param {string} to - Desired status.
+ * @returns {boolean}
+ */
+export function isLawfulTransition(from, to) {
+  const allowed = TRANSITIONS[from];
+  if (!allowed) return false;
+  return allowed.has(to);
+}
+
+/**
+ * Validate a transition and return error if invalid.
+ * @param {string} from
+ * @param {string} to
+ * @returns {{ valid: boolean, error?: string }}
+ */
+export function validateTransition(from, to) {
+  if (!TRANSITIONS[from]) {
+    return { valid: false, error: `Unknown status: "${from}"` };
+  }
+  if (!isLawfulTransition(from, to)) {
+    const allowed = [...TRANSITIONS[from]].join(', ');
+    return { valid: false, error: `Cannot transition from "${from}" to "${to}". Allowed: ${allowed}` };
+  }
+  return { valid: true };
+}
+
+/**
+ * Map review actions to their target statuses.
+ */
+export const ACTION_TARGET_STATUS = {
+  review: 'reviewed',
+  accept: 'accepted',
+  reject: 'rejected',
+  edit: null,        // edit preserves current status
+  merge: 'rejected', // merged sources become rejected (merged_into_canonical)
+  reopen: 'reviewed',
+  invalidate: 'reviewed', // invalidated accepted → back to reviewed with invalidation metadata
+  supersede: 'rejected'   // superseded finding becomes rejected
+};
+
+/**
+ * Actions that require a reason.
+ */
+export const REASON_REQUIRED = new Set(['reject', 'invalidate', 'merge', 'supersede']);
+
+/**
+ * Actions that require from_status to be accepted.
+ */
+export const REQUIRES_ACCEPTED = new Set(['invalidate']);
+
+/**
+ * Actions that require from_status to be accepted or rejected.
+ */
+export const REQUIRES_CLOSED = new Set(['reopen']);