// lib/validators/brief-validator.mjs
// Validate trekbrief frontmatter + body invariants.
//
// Schema is forward-compatible: unknown top-level frontmatter keys are
// tolerated silently. Strict-key checks are intentionally avoided so new
// optional fields (jf. the source_findings precedent on trekreview) can be
// added without a brief_version bump.

import { readFileSync, existsSync } from 'node:fs';
import { parseDocument } from '../util/frontmatter.mjs';
import { issue, ok, fail } from '../util/result.mjs';
import { BASE_ALLOWED_MODELS } from './profile-validator.mjs';

export const BRIEF_REQUIRED_FRONTMATTER = ['type', 'brief_version', 'task', 'slug', 'research_topics', 'research_status'];
export const REVIEW_AS_BRIEF_REQUIRED_FRONTMATTER = ['type', 'task', 'slug', 'project_dir', 'findings'];
export const BRIEF_TYPE_VALUES = Object.freeze(['trekbrief', 'trekreview']);
export const BRIEF_RESEARCH_STATUS_VALUES = ['pending', 'in_progress', 'complete', 'skipped'];
export const BRIEF_BODY_SECTIONS = ['Intent', 'Goal', 'Success Criteria'];
export const PHASE_SIGNAL_PHASES = Object.freeze(['research', 'plan', 'execute', 'review']);
export const EFFORT_LEVELS = Object.freeze(['low', 'standard', 'high']);

function getRequiredFields(type) {
  return type === 'trekreview' ? REVIEW_AS_BRIEF_REQUIRED_FRONTMATTER : BRIEF_REQUIRED_FRONTMATTER;
}

export function validateBriefContent(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 getRequiredFields(fm.type)) {
    if (!(k in fm)) {
      errors.push(issue('BRIEF_MISSING_FIELD', `Required frontmatter field missing: ${k}`));
    }
  }

  // v5.1 — phase_signals (additive optional field) + version-conditional sequencing gate.
  // Composition rule documented in each downstream command's "Composition rule (v5.1)" section.
  const hasSignals = 'phase_signals' in fm;
  const hasPartial = 'phase_signals_partial' in fm;
  if (hasSignals && hasPartial) {
    errors.push(issue(
      'BRIEF_SIGNALS_MUTUALLY_EXCLUSIVE',
      'phase_signals and phase_signals_partial are mutually exclusive — set exactly one',
      'Either commit per-phase signals OR record phase_signals_partial: true (force-stop).',
    ));
  }
  if (hasSignals) {
    if (!Array.isArray(fm.phase_signals)) {
      errors.push(issue(
        'BRIEF_INVALID_PHASE_SIGNALS',
        'phase_signals must be a list of {phase, effort?, model?} entries',
      ));
    } else {
      for (const entry of fm.phase_signals) {
        if (!entry || typeof entry !== 'object' || !('phase' in entry)) {
          errors.push(issue('BRIEF_INVALID_PHASE_SIGNALS', `phase_signals entry must include a "phase" key`));
          continue;
        }
        if (!PHASE_SIGNAL_PHASES.includes(entry.phase)) {
          errors.push(issue(
            'BRIEF_INVALID_PHASE_SIGNAL_PHASE',
            `phase_signals.phase "${entry.phase}" not in [${PHASE_SIGNAL_PHASES.join(', ')}]`,
          ));
        }
        if ('effort' in entry && !EFFORT_LEVELS.includes(entry.effort)) {
          errors.push(issue(
            'BRIEF_INVALID_EFFORT',
            `phase_signals.effort "${entry.effort}" not in [${EFFORT_LEVELS.join(', ')}]`,
          ));
        }
        if ('model' in entry && !BASE_ALLOWED_MODELS.includes(entry.model)) {
          errors.push(issue(
            'BRIEF_INVALID_MODEL',
            `phase_signals.model "${entry.model}" not in [${BASE_ALLOWED_MODELS.join(', ')}]`,
          ));
        }
      }
    }
  }
  // Sequencing gate: brief_version ≥ 2.1 requires phase_signals OR phase_signals_partial.
  if (typeof fm.brief_version === 'string') {
    const vm = fm.brief_version.match(/^(\d+)\.(\d+)$/);
    if (vm) {
      const major = Number(vm[1]);
      const minor = Number(vm[2]);
      const atLeast21 = major > 2 || (major === 2 && minor >= 1);
      if (atLeast21 && !hasSignals && !hasPartial && fm.type !== 'trekreview') {
        errors.push(issue(
          'BRIEF_V51_MISSING_SIGNALS',
          'brief_version ≥ 2.1 requires phase_signals (or phase_signals_partial: true)',
          'Re-run /trekbrief — Phase 3.5 collects per-phase effort + model signals.',
        ));
      }
    }
  }

  if (fm.type !== undefined && !BRIEF_TYPE_VALUES.includes(fm.type)) {
    errors.push(issue(
      'BRIEF_WRONG_TYPE',
      `frontmatter.type must be one of [${BRIEF_TYPE_VALUES.join(', ')}], got "${fm.type}"`,
    ));
  }

  if (fm.type === 'trekreview' && fm.findings !== undefined && !Array.isArray(fm.findings)) {
    errors.push(issue(
      'BRIEF_BAD_FINDINGS_TYPE',
      'Field "findings" must be an array of finding-IDs for type:trekreview',
      'Use block-style YAML: `findings:\\n  - <id1>\\n  - <id2>`',
    ));
  }

  if (fm.research_status !== undefined && !BRIEF_RESEARCH_STATUS_VALUES.includes(fm.research_status)) {
    errors.push(issue(
      'BRIEF_BAD_STATUS',
      `research_status "${fm.research_status}" not in [${BRIEF_RESEARCH_STATUS_VALUES.join(', ')}]`,
    ));
  }

  if (typeof fm.research_topics === 'number' && fm.research_topics > 0 && fm.research_status === 'skipped') {
    if (fm.brief_quality !== 'partial') {
      errors.push(issue(
        'BRIEF_STATE_INCOHERENT',
        `research_topics=${fm.research_topics} but research_status=skipped`,
        'Either set research_status to a real progress value, or mark brief_quality: partial.',
      ));
    } else {
      warnings.push(issue(
        'BRIEF_PARTIAL_SKIPPED',
        `Brief has unresolved research topics (${fm.research_topics}) but is partial`,
      ));
    }
  }

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

  if (typeof fm.brief_version === 'string') {
    const m = fm.brief_version.match(/^(\d+)\.(\d+)$/);
    if (!m) {
      warnings.push(issue('BRIEF_VERSION_FORMAT', `brief_version "${fm.brief_version}" not in N.M form`));
    }
  }

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

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

if (import.meta.url === `file://${process.argv[1]}`) {
  const args = process.argv.slice(2);
  const strict = !args.includes('--soft');
  const filePath = args.find(a => !a.startsWith('--'));
  if (!filePath) {
    process.stderr.write('Usage: brief-validator.mjs [--soft] <brief.md>\n');
    process.exit(2);
  }
  const r = validateBrief(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(`brief-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);
}