@really-knows-ai/foundry 3.3.8 → 3.4.0

package/dist/scripts/appraise-module.js

@@ -0,0 +1,452 @@
+/**
+ * Appraise module — gathers context for parallel appraiser dispatch and
+ * consolidates results after all appraisers have run.
+ *
+ * Gather phase: reads artefacts, laws, and appraiser personalities, builds
+ * subagent prompts, and returns a dispatch_multi action so the orchestrator's
+ * LLM dispatches appraisers in parallel.
+ *
+ * Consolidate phase: receives lastResults from the orchestrator, unions and
+ * de-duplicates appraiser issues, posts feedback, and finalises the stage
+ * so the orchestrator can re-sort and determine the next action.
+ */
+
+import { getArtefactsForCycle } from './lib/artefacts.js';
+import { selectAppraisers, getLaws } from './lib/config.js';
+
+// ---------------------------------------------------------------------------
+// Public API — gather
+// ---------------------------------------------------------------------------
+
+/**
+ * Gather appraise context: read draft artefacts, select appraisers, read laws
+ * and artefact content, then build a dispatch_multi action with one task per
+ * (artefact, appraiser) pair.
+ *
+ * @param {object} ctx
+ * @param {string} ctx.cycleId
+ * @param {object} ctx.io
+ * @param {string} ctx.foundryDir
+ * @param {string} [ctx.defaultModel] - Fallback model when an appraiser has no
+ *   explicit model.
+ * @returns {Promise<{action: string, tasks: Array, stage: string, cycle: string}>}
+ */
+export async function gatherAppraiseContext(ctx) {
+  if (!ctx.cycleId) {
+    return violation('cycleId is required', []);
+  }
+
+  const artefacts = getArtefactsForCycle(ctx.cycleId, ctx.io);
+  if (artefacts.length === 0) {
+    return emptyDispatch(ctx.cycleId);
+  }
+
+  const tasks = await collectTasks(artefacts, ctx);
+
+  return {
+    action: 'dispatch_multi',
+    tasks,
+    stage: `appraise:${ctx.cycleId}`,
+    cycle: ctx.cycleId,
+  };
+}
+
+/**
+ * Build all appraiser tasks across artefacts, caching per type.
+ */
+async function collectTasks(artefacts, ctx) {
+  const tasks = [];
+  const typeCache = new Map();
+
+  for (const artefact of artefacts) {
+    const entry = await resolveTypeEntry(artefact.type, typeCache, ctx);
+    if (!entry) continue;
+
+    addTasksForArtefact(tasks, artefact, entry, ctx);
+  }
+
+  return tasks;
+}
+
+/**
+ * Get or create a cached (appraisers, laws) entry for an artefact type.
+ * Returns null when no appraisers are available for the type.
+ */
+async function resolveTypeEntry(typeId, cache, ctx) {
+  if (cache.has(typeId)) {
+    return cache.get(typeId);
+  }
+
+  const [appraisers, laws] = await Promise.all([
+    selectAppraisers(ctx.foundryDir, typeId, { io: ctx.io }),
+    getLaws(ctx.foundryDir, ctx.io, { typeId }),
+  ]);
+
+  const entry = appraisers.length === 0 ? null : { appraisers, laws };
+  cache.set(typeId, entry);
+  return entry;
+}
+
+/**
+ * Build and append appraiser tasks for a single artefact.
+ */
+function addTasksForArtefact(tasks, artefact, entry, ctx) {
+  const content = ctx.io.readFile(artefact.file);
+
+  for (const appraiser of entry.appraisers) {
+    const prompt = buildAppraiserPrompt({
+      appraiser,
+      artefact: { file: artefact.file, content },
+      laws: entry.laws,
+    });
+
+    tasks.push({
+      subagent_type: resolveSubagentType(appraiser, ctx),
+      prompt,
+    });
+  }
+}
+
+/**
+ * Map an appraiser's model to a subagent type string.
+ */
+function resolveSubagentType(appraiser, ctx) {
+  const name = appraiser.model || ctx.defaultModel || 'general';
+  if (name === 'general') return 'general';
+
+  return `foundry-${name.replace(/[/.]/g, '-')}`;
+}
+
+/**
+ * Empty dispatch response when there is nothing to appraise.
+ */
+function emptyDispatch(cycleId) {
+  return {
+    action: 'dispatch_multi',
+    tasks: [],
+    stage: `appraise:${cycleId}`,
+    cycle: cycleId,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public API — consolidate
+// ---------------------------------------------------------------------------
+
+/**
+ * Consolidate appraiser results after all subagents have run.
+ *
+ * Parses each successful output for structured issues, unions across
+ * appraisers, de-duplicates by (file, law-id, issue text), posts feedback,
+ * resolves stale prior appraise feedback, and finalises the stage.
+ *
+ * @param {object} ctx
+ * @param {Array<{ok: boolean, output?: string, error?: string}>} lastResults
+ * @returns {Promise<{ok: boolean, summary?: string}|violation>}
+ */
+export async function consolidateAppraise(ctx, lastResults) {
+  const baseSha = ctx.activeStage?.baseSha;
+  if (!baseSha) {
+    return violation('No active stage found', []);
+  }
+
+  const results = arrayFrom(lastResults);
+  const successful = results.filter(r => r.ok === true);
+
+  if (allAppraisersFailed(results, successful)) {
+    return violation('All appraisers failed to evaluate the artefact', []);
+  }
+
+  const consolidated = parseConsolidated(successful);
+  const stageId = `appraise:${ctx.cycleId}`;
+
+  postConsolidatedFeedback(ctx, consolidated);
+  resolvePriorAppraise(ctx, consolidated, stageId);
+
+  const summary = buildConsolidateSummary(consolidated.length);
+
+  await ctx.finalize({
+    lastStage: { stage: stageId, summary, baseSha },
+    activeStage: ctx.activeStage,
+  });
+
+  return { ok: true, summary };
+}
+
+/**
+ * Parse all successful appraiser outputs and de-duplicate the combined issue
+ * list by (file, law-id, issue text).
+ */
+function parseConsolidated(successful) {
+  const all = [];
+
+  for (const result of successful) {
+    const issues = parseAppraiserOutput(result.output || '');
+    all.push(...issues);
+  }
+
+  return deduplicateIssues(all);
+}
+
+/**
+ * De-duplicate an issue array by (file, law, issue text).
+ */
+function deduplicateIssues(issues) {
+  const seen = new Set();
+  const result = [];
+
+  for (const issue of issues) {
+    const key = `${issue.file}:${issue.law}:${issue.issue}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      result.push(issue);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Post one feedback item per consolidated issue.
+ */
+function postConsolidatedFeedback(ctx, consolidated) {
+  for (const issue of consolidated) {
+    ctx.feedback.add({
+      file: issue.file,
+      text: issue.issue,
+      tag: `law:${issue.law}`,
+    });
+  }
+}
+
+/**
+ * Resolve prior appraise feedback: items still present stay rejected, stale
+ * items are approved.
+ */
+function resolvePriorAppraise(ctx, consolidated, stageId) {
+  const current = new Set(
+    consolidated.map(i => `${i.file}:law:${i.law}`)
+  );
+
+  const priorItems = ctx.feedback.list({ source: stageId });
+
+  for (const prior of priorItems) {
+    if (prior.state === 'resolved') continue;
+    const sig = `${prior.file}:${prior.tag}`;
+    const decision = current.has(sig) ? 'rejected' : 'approved';
+    ctx.feedback.resolve(prior.id, decision);
+  }
+}
+
+/**
+ * Build the summary string for consolidation.
+ */
+function buildConsolidateSummary(count) {
+  if (count === 0) return 'No issues found by appraisers';
+
+  return `${count} issue(s) found by appraisers`;
+}
+
+// ---------------------------------------------------------------------------
+// Prompt builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a subagent prompt for a single (appraiser, artefact) pair.
+ *
+ * Follows the template from the appraise skill (src/skills/appraise/SKILL.md)
+ * extended to include the file path for deterministic result parsing.
+ */
+function buildAppraiserPrompt({ appraiser, artefact, laws }) {
+  const lawSections = laws
+    .map(law => `## ${law.id}\n\n${law.text}`)
+    .join('\n\n');
+
+  const lines = [
+    'You are an appraiser. Your personality:',
+    '',
+    appraiser.personality,
+    '',
+    'Evaluate the following artefact against each law below. For each law,',
+    'either:',
+    '- Note no issues (pass)',
+    '- Describe the issue, quoting evidence from the artefact',
+    '',
+    '## Artefact',
+    '',
+    artefact.content,
+    '',
+    '## Laws',
+    '',
+    lawSections,
+    '',
+    '## Output',
+    '',
+    'Return a list of issues. For each issue:',
+    `- file: ${artefact.file}`,
+    '- law: <law-id>',
+    '- issue: <description>',
+    '- evidence: <quote from artefact>',
+    '',
+    'If there are no issues, return an empty list.',
+  ];
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Output parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a structured issue list from an appraiser subagent output.
+ *
+ * Expected per-issue format (YAML list):
+ *   - file: <path>
+ *     law: <law-id>
+ *     issue: <description>
+ *     evidence: <quote>
+ *
+ * Returns an array of { file, law, issue, evidence } objects. Entries that
+ * lack a file, law, or issue field are silently skipped.
+ */
+function parseAppraiserOutput(output) {
+  // Split output into entries on boundaries where a new line starts a
+  // list entry ("- ").  Avoids regex to prevent sonarjs/slow-regex.
+  const entries = [];
+  let buffer = '';
+
+  for (const line of output.split('\n')) {
+    if (buffer && isListEntryStart(line)) {
+      entries.push(buffer);
+      buffer = line;
+      continue;
+    }
+
+    buffer = concatLine(buffer, line);
+  }
+
+  if (buffer) entries.push(buffer);
+
+  return entries
+    .map(parseRawEntry)
+    .filter(e => e !== null);
+}
+
+/**
+ * Append a line to the current buffer string.
+ */
+function concatLine(buffer, line) {
+  if (!buffer) return line;
+  return `${buffer}\n${line}`;
+}
+
+/**
+ * True when a line marks the start of a new YAML list entry (starts with
+ * "- " after optional whitespace).
+ */
+function isListEntryStart(line) {
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === ' ' || ch === '\t') continue;
+    return ch === '-' && line[i + 1] === ' ';
+  }
+  return false;
+}
+
+/**
+ * Parse a single raw entry block into an issue object, or null when
+ * required fields are missing.
+ */
+function parseRawEntry(raw) {
+  const block = raw.trim();
+
+  const file = extractField(block, 'file');
+  const law = extractField(block, 'law');
+  const issue = extractField(block, 'issue');
+  const evidence = extractField(block, 'evidence');
+
+  if (!file || !law || !issue) return null;
+
+  return { file, law, issue, evidence: evidence || '' };
+}
+
+/**
+ * Extract a YAML list item field value.
+ *
+ * Matches lines like:
+ *   - file: value
+ *     law: value
+ *
+ * The field name may be preceded by optional whitespace and/or a "- " list
+ * marker. Returns the value portion, trimmed.
+ */
+function extractField(text, key) {
+  // Walk lines to find "key: value" preceded only by whitespace or a "- "
+  // list marker.  Avoids regex quantifiers that trigger sonarjs/slow-regex.
+
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    const value = tryExtractKey(trimmed, key);
+    if (value !== null) return value;
+  }
+
+  return null;
+}
+
+/**
+ * Given a single trimmed line, try to extract the value for key.
+ * Returns null if the pattern is not found.
+ */
+function tryExtractKey(line, key) {
+  const needle = `${key}:`;
+  const idx = line.indexOf(needle);
+  if (idx < 0) return null;
+
+  const before = line.slice(0, idx);
+  if (before.length > 0 && !isLegalPrefix(before)) return null;
+
+  const value = line.slice(idx + needle.length).trim();
+  return value || null;
+}
+
+/**
+ * True when the text before a key: on a line is either all whitespace or
+ * the "- " list marker.
+ */
+function isLegalPrefix(before) {
+  if (before === '- ') return true;
+
+  for (let i = 0; i < before.length; i++) {
+    if (before[i] !== ' ' && before[i] !== '\t') return false;
+  }
+
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+
+function violation(details, affectedFiles) {
+  return {
+    action: 'violation',
+    details,
+    recoverable: false,
+    affected_files: affectedFiles,
+  };
+}
+
+/**
+ * Safely coerce a value to an array, defaulting to empty array.
+ */
+function arrayFrom(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+/**
+ * True when there were results but none succeeded.
+ */
+function allAppraisersFailed(results, successful) {
+  return results.length > 0 && successful.length === 0;
+}

package/dist/scripts/lib/artefacts.js

@@ -149,3 +149,15 @@ export function setArtefactStatus(text, file, newStatus) {
 
   throw new Error(`File not found in artefacts table: ${file}`);
 }
+
+/**
+ * Get draft artefacts for a specific cycle from the artefacts table.
+ * @param {string} cycleId - Cycle ID to filter by
+ * @param {object} io - IO interface
+ * @returns {Array<{file: string, type: string, cycle: string, status: string}>}
+ */
+export function getArtefactsForCycle(cycleId, io) {
+  const text = io.readFile('WORK.md');
+  const artefacts = parseArtefactsTable(text);
+  return artefacts.filter(a => a.cycle === cycleId && a.status === 'draft');
+}

package/dist/scripts/lib/validation.js

@@ -0,0 +1,230 @@
+/**
+ * Shared validation utilities extracted from the plugin's validate-tools.
+ *
+ * These functions run deterministic validator commands (no LLM involvement)
+ * and return structured results consumed by the quench module and the
+ * plugin's `foundry_validate_run` tool.
+ */
+
+import { execSync } from 'child_process';
+import { readdir } from 'fs/promises';
+import { join, relative, dirname, sep } from 'path';
+import { minimatch } from 'minimatch';
+import { getLawsForQuench, getArtefactType } from './config.js';
+import { parseValidatorJsonl } from './validator-jsonl.js';
+
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+
+function shellQuote(value) {
+  return "'" + String(value).replace(/'/g, "'\\''") + "'";
+}
+
+function validatePatterns(patterns, typeId) {
+  if (!Array.isArray(patterns) || patterns.length === 0) {
+    return { ok: false, error: `Artefact type ${typeId} has no file-patterns` };
+  }
+  return null;
+}
+
+const SKIP_DIRS = new Set(['node_modules', '.git']);
+
+function toPosix(p) {
+  return sep === '/' ? p : p.split(sep).join('/');
+}
+
+async function readdirSafe(dir) {
+  try {
+    return await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+async function* walkFiles(root, dir) {
+  for (const entry of await readdirSafe(dir)) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory() && !SKIP_DIRS.has(entry.name)) {
+      yield* walkFiles(root, full);
+    } else if (entry.isFile()) {
+      yield toPosix(relative(root, full));
+    }
+  }
+}
+
+function fileMatchesAnyPattern(rel, patterns) {
+  for (const pattern of patterns) {
+    if (minimatch(rel, pattern)) return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Exported functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Read file-patterns for an artefact type from its definition.
+ */
+export async function getValidationPatterns(foundryDir, typeId, io) {
+  const artType = await getArtefactType(foundryDir, typeId, io);
+  return artType.frontmatter['file-patterns'] || [];
+}
+
+/**
+ * Run validation commands for an artefact type deterministically.
+ *
+ * Accepts an IO interface and foundryDir directly (no plugin context
+ * dependency). Returns a plain result object.
+ *
+ * @param {{ typeId: string, io: object, foundryDir: string }} params
+ * @returns {Promise<{ ok: boolean, validatorsRun: number, items: Array, errors: Array }>}
+ */
+export async function performValidation({ typeId, io, foundryDir }) {
+  let patterns;
+  try {
+    patterns = await getValidationPatterns(foundryDir, typeId, io);
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+
+  const validationErr = validatePatterns(patterns, typeId);
+  if (validationErr) return validationErr;
+
+  const laws = await getLawsForQuench(foundryDir, io, { typeId });
+  if (!laws?.length) {
+    return { ok: true, validatorsRun: 0, items: [], errors: [] };
+  }
+  return runValidatorsAndReport(laws, patterns, foundryDir);
+}
+
+/**
+ * Run validators for a set of laws and build the aggregated result.
+ */
+export async function runValidatorsAndReport(laws, patterns, foundryDir) {
+  const worktree = dirname(foundryDir);
+  const expandedFiles = await expandPatterns(patterns, worktree);
+  const substitutions = {
+    pattern: patterns.map(shellQuote).join(' '),
+    files: expandedFiles.map(shellQuote).join(' '),
+  };
+  const results = await runValidators(laws, patterns, substitutions, worktree);
+
+  return {
+    ok: results.errors.length === 0,
+    validatorsRun: results.validatorsRun,
+    items: results.items,
+    errors: results.errors,
+  };
+}
+
+/**
+ * Expand glob patterns to actual file paths in the worktree.
+ *
+ * Uses readdir + minimatch for Node 20 compatibility (glob added in Node 22).
+ */
+export async function expandPatterns(patterns, worktree) {
+  const files = new Set();
+  for await (const rel of walkFiles(worktree, worktree)) {
+    if (fileMatchesAnyPattern(rel, patterns)) {
+      files.add(rel);
+    }
+  }
+  return Array.from(files).sort();
+}
+
+/**
+ * Run all validators across a list of laws and collect results.
+ */
+export async function runValidators(laws, patterns, substitutions, worktree) {
+  const results = {
+    validatorsRun: 0,
+    items: [],
+    errors: [],
+  };
+
+  for (const law of laws) {
+    if (!law.validators || law.validators.length === 0) continue;
+    await runLawValidators(law, patterns, substitutions, worktree, results);
+  }
+
+  return results;
+}
+
+/**
+ * Run validators for a single law.
+ */
+export async function runLawValidators(law, patterns, substitutions, worktree, results) {
+  for (const validator of law.validators) {
+    // Skip commands that require {files} when there are no matching files
+    if (substitutions.files === '' && /(?:^|\s)\{files\}(?=\s|$)/.test(validator.command)) {
+      continue;
+    }
+    results.validatorsRun++;
+    const expanded = expandValidatorCommand(validator.command, substitutions);
+    const parseResult = await executeValidator(expanded, worktree, patterns);
+    collectValidatorResult(parseResult, law.id, validator.id, results);
+  }
+}
+
+/**
+ * Fold a single validator's parse result into the aggregate results.
+ */
+export function collectValidatorResult(parseResult, lawId, validatorId, results) {
+  for (const item of parseResult.items) {
+    results.items.push({ lawId, validatorId, ...item });
+  }
+  for (const message of parseResult.parseErrors) {
+    results.errors.push({ lawId, validatorId, type: 'parse', message });
+  }
+  for (const message of parseResult.patternErrors) {
+    results.errors.push({ lawId, validatorId, type: 'pattern-mismatch', message });
+  }
+}
+
+/**
+ * Execute a validator command and parse its JSONL output.
+ */
+export async function executeValidator(expanded, worktree, patterns) {
+  try {
+    const output = execSync(expanded, {
+      cwd: worktree,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const { Readable } = await import('stream');
+    const stream = Readable.from([output]);
+    return await parseValidatorJsonl(stream, patterns);
+  } catch (err) {
+    // Validator command failed — prefer stdout for JSONL
+    // (tools like rg exit 1 with results on stdout)
+    const output = (err.stdout || err.stderr || err.message || '').trim();
+    const { Readable } = await import('stream');
+    const stream = Readable.from([output]);
+    return await parseValidatorJsonl(stream, patterns);
+  }
+}
+
+/**
+ * Expand validator command placeholders {pattern} and {files}.
+ *
+ * Both placeholders are recognised only as standalone tokens bounded by
+ * whitespace or start/end of string. Surrounding single or double quotes
+ * around the placeholder are stripped first.
+ */
+export function expandValidatorCommand(command, { pattern, files }) {
+  let cmd = command
+    .replace(/"\{pattern\}"/g, '{pattern}')
+    .replace(/'\{pattern\}'/g, '{pattern}')
+    .replace(/"\{files\}"/g, '{files}')
+    .replace(/'\{files\}'/g, '{files}');
+
+  cmd = cmd.replace(/(?:^|\s)\{pattern\}(?=\s|$)/g, (match) =>
+    match.startsWith('{') ? pattern : ' ' + pattern);
+
+  cmd = cmd.replace(/(?:^|\s)\{files\}(?=\s|$)/g, (match) =>
+    match.startsWith('{') ? files : ' ' + files);
+
+  return cmd;
+}