ktg-plugin-marketplace/plugins/ultraplan-local/lib/validators/research-validator.mjs

// lib/validators/research-validator.mjs
// Validate research-brief frontmatter + body invariants.

import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
import { join } from 'node:path';
import { parseDocument } from '../util/frontmatter.mjs';
import { issue, fail } from '../util/result.mjs';

export const RESEARCH_REQUIRED_FRONTMATTER = ['type', 'created', 'question'];
export const RESEARCH_BODY_SECTIONS = ['Executive Summary', 'Dimensions'];

export function validateResearchContent(text, opts = {}) {
  const strict = opts.strict !== false;
  const doc = parseDocument(text);
  if (!doc.valid) return doc;

  const fm = doc.parsed.frontmatter || {};
  const body = doc.parsed.body || '';
  const errors = [];
  const warnings = [];

  for (const k of RESEARCH_REQUIRED_FRONTMATTER) {
    if (!(k in fm)) errors.push(issue('RESEARCH_MISSING_FIELD', `Required frontmatter field missing: ${k}`));
  }

  if (fm.type !== undefined && fm.type !== 'ultraresearch-brief') {
    errors.push(issue('RESEARCH_WRONG_TYPE', `frontmatter.type must be "ultraresearch-brief", got "${fm.type}"`));
  }

  if (fm.confidence !== undefined) {
    if (typeof fm.confidence !== 'number' || fm.confidence < 0 || fm.confidence > 1) {
      errors.push(issue('RESEARCH_BAD_CONFIDENCE', `confidence must be number in [0,1], got ${fm.confidence}`));
    }
  } else {
    warnings.push(issue('RESEARCH_NO_CONFIDENCE', 'No confidence field — planner has no signal to weight findings'));
  }

  if (fm.dimensions !== undefined && (typeof fm.dimensions !== 'number' || fm.dimensions < 1)) {
    errors.push(issue('RESEARCH_BAD_DIMENSIONS', `dimensions must be positive integer, got ${fm.dimensions}`));
  }

  for (const section of RESEARCH_BODY_SECTIONS) {
    const re = new RegExp(`^##\\s+${section}\\b`, 'm');
    if (!re.test(body)) {
      const issueObj = issue('RESEARCH_MISSING_SECTION', `Required body section missing: ## ${section}`);
      if (strict) errors.push(issueObj);
      else warnings.push(issueObj);
    }
  }

  return { valid: errors.length === 0, errors, warnings, parsed: { frontmatter: fm, body } };
}

export function validateResearch(filePath, opts = {}) {
  if (!existsSync(filePath)) return fail(issue('RESEARCH_NOT_FOUND', `File not found: ${filePath}`));
  let text;
  try { text = readFileSync(filePath, 'utf-8'); }
  catch (e) { return fail(issue('RESEARCH_READ_ERROR', `Cannot read ${filePath}: ${e.message}`)); }
  const r = validateResearchContent(text, opts);
  return { ...r, parsed: { ...r.parsed, filePath } };
}

export function validateResearchDir(dirPath, opts = {}) {
  if (!existsSync(dirPath) || !statSync(dirPath).isDirectory()) {
    return { valid: true, errors: [], warnings: [], parsed: { files: [] } };
  }
  const files = readdirSync(dirPath).filter(f => f.endsWith('.md')).sort();
  const errors = [];
  const warnings = [];
  const results = [];
  for (const f of files) {
    const r = validateResearch(join(dirPath, f), opts);
    for (const e of r.errors) errors.push(issue(e.code, `${f}: ${e.message}`, e.hint));
    for (const w of r.warnings) warnings.push(issue(w.code, `${f}: ${w.message}`, w.hint));
    results.push({ file: f, valid: r.valid });
  }
  return { valid: errors.length === 0, errors, warnings, parsed: { files: results } };
}

if (import.meta.url === `file://${process.argv[1]}`) {
  const args = process.argv.slice(2);
  const strict = !args.includes('--soft');
  const dirIdx = args.indexOf('--dir');
  if (dirIdx >= 0 && args[dirIdx + 1]) {
    const r = validateResearchDir(args[dirIdx + 1], { strict });
    if (args.includes('--json')) {
      process.stdout.write(JSON.stringify({ valid: r.valid, errors: r.errors, warnings: r.warnings, files: r.parsed.files }, null, 2) + '\n');
    } else {
      process.stdout.write(`research-validator (dir): ${r.valid ? 'PASS' : 'FAIL'} ${args[dirIdx + 1]}\n`);
      for (const e of r.errors) process.stderr.write(`  ERROR  [${e.code}] ${e.message}\n`);
      for (const w of r.warnings) process.stderr.write(`  WARN   [${w.code}] ${w.message}\n`);
    }
    process.exit(r.valid ? 0 : 1);
  }
  const filePath = args.find(a => !a.startsWith('--'));
  if (!filePath) {
    process.stderr.write('Usage: research-validator.mjs [--soft] <file.md>  OR  --dir <research-dir>\n');
    process.exit(2);
  }
  const r = validateResearch(filePath, { strict });
  if (args.includes('--json')) {
    process.stdout.write(JSON.stringify({ valid: r.valid, errors: r.errors, warnings: r.warnings }, null, 2) + '\n');
  } else {
    process.stdout.write(`research-validator: ${r.valid ? 'PASS' : 'FAIL'} ${filePath}\n`);
    for (const e of r.errors) process.stderr.write(`  ERROR  [${e.code}] ${e.message}\n`);
    for (const w of r.warnings) process.stderr.write(`  WARN   [${w.code}] ${w.message}\n`);
  }
  process.exit(r.valid ? 0 : 1);
}