@aifabrix/builder 2.52.1 → 2.53.1

package/scripts/lib/plan-meta.js

@@ -1,104 +0,0 @@
-/**
- * @fileoverview Resolve plan paths and patch YAML frontmatter.
- */
-
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const { REPO_ROOT, PLANS_DIR } = require('./plan-config');
-
-/**
- * @param {string} msg
- * @returns {never}
- */
-function die(msg) {
-  console.error(`Error: ${msg}`);
-  process.exit(1);
-}
-
-/**
- * @param {string} input
- * @returns {string}
- */
-function resolvePlanPath(input) {
-  if (!input) {
-    die('Plan path or id required (e.g. 417.0)');
-  }
-  const resolved = path.resolve(REPO_ROOT, input);
-  if (fs.existsSync(resolved)) {
-    return resolved;
-  }
-  if (!fs.existsSync(PLANS_DIR)) {
-    die(`Plans directory not found: ${PLANS_DIR}`);
-  }
-  /** @param {string} dir */
-  function findIn(dir) {
-    if (!fs.existsSync(dir)) {
-      return null;
-    }
-    for (const name of fs.readdirSync(dir)) {
-      const full = path.join(dir, name);
-      if (fs.statSync(full).isDirectory()) {
-        const found = findIn(full);
-        if (found) {
-          return found;
-        }
-      } else if (name.endsWith('.plan.md')) {
-        const base = name.slice(0, -'.plan.md'.length);
-        if (base === input || base.startsWith(`${input}-`)) {
-          return full;
-        }
-      }
-    }
-    return null;
-  }
-  const exactRoot = path.join(PLANS_DIR, `${input}.plan.md`);
-  if (fs.existsSync(exactRoot)) {
-    return exactRoot;
-  }
-  const plansRoot = fs.readdirSync(PLANS_DIR);
-  const prefixMatch = plansRoot.find((n) => {
-    if (!n.endsWith('.plan.md')) {
-      return false;
-    }
-    const base = n.slice(0, -'.plan.md'.length);
-    return base === input || base.startsWith(`${input}-`);
-  });
-  if (prefixMatch) {
-    return path.join(PLANS_DIR, prefixMatch);
-  }
-  const nested = findIn(PLANS_DIR);
-  if (nested) {
-    return nested;
-  }
-  die(`Plan not found: ${input}`);
-}
-
-/**
- * @param {string} planPath
- * @param {string} key
- * @param {string} value
- */
-function patchPlanMeta(planPath, key, value) {
-  const raw = fs.readFileSync(planPath, 'utf8');
-  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
-  if (!match) {
-    die('Plan has no frontmatter to patch');
-  }
-  let yaml = match[1];
-  const quoted = JSON.stringify(String(value));
-  const re = new RegExp(`^${key}:.*$`, 'm');
-  if (re.test(yaml)) {
-    yaml = yaml.replace(re, `${key}: ${quoted}`);
-  } else {
-    yaml = `${yaml}\n${key}: ${quoted}`;
-  }
-  fs.writeFileSync(planPath, `---\n${yaml}\n---\n${match[2]}`, 'utf8');
-}
-
-module.exports = {
-  die,
-  resolvePlanPath,
-  patchPlanMeta
-};

package/scripts/lib/plan-parse.js

@@ -1,162 +0,0 @@
-/**
- * @fileoverview Parse Cursor plan frontmatter (shared).
- */
-
-'use strict';
-
-const { readFileSync } = require('../../lib/internal/fs-real-sync');
-const { REPO_ROOT, PLANS_DIR } = require('./plan-config');
-
-const TODO_STATUSES = new Set(['pending', 'in_progress', 'completed', 'cancelled']);
-
-/**
- * @param {string} block
- * @returns {Array<{ id: string, content: string, status: string }>}
- */
-function parseTodosBlock(block) {
-  const todos = [];
-  const chunks = block
-    .trim()
-    .split(/(?:^|\n)\s*-\s+id:\s*/)
-    .filter(Boolean);
-  for (const chunk of chunks) {
-    const idLine = chunk.split(/\r?\n/)[0].trim();
-    const contentMatch = chunk.match(/\n\s+content:\s*\|\s*\n([\s\S]*?)(?=\n\s+status:)/);
-    const statusMatch = chunk.match(/\n\s+status:\s*(\w+)/);
-    todos.push({
-      id: idLine,
-      content: contentMatch ? contentMatch[1].replace(/^\s{6}/gm, '').trim() : '',
-      status: statusMatch ? statusMatch[1] : 'pending'
-    });
-  }
-  return todos;
-}
-
-/**
- * @param {string} raw
- * @returns {Record<string, unknown> | null}
- */
-function parseSimpleYaml(raw) {
-  const meta = {};
-  const lines = raw.split(/\r?\n/);
-  let i = 0;
-
-  while (i < lines.length) {
-    const line = lines[i];
-    const keyMatch = line.match(/^([a-zA-Z0-9_]+):\s*(.*)$/);
-    if (!keyMatch) {
-      i += 1;
-      continue;
-    }
-    const key = keyMatch[1];
-    const rest = keyMatch[2].trim();
-
-    if (key === 'todos' && rest === '') {
-      const block = [];
-      i += 1;
-      while (i < lines.length && !/^[a-zA-Z0-9_]+:\s*/.test(lines[i])) {
-        block.push(lines[i]);
-        i += 1;
-      }
-      meta.todos = parseTodosBlock(block.join('\n'));
-      continue;
-    }
-
-    if (rest === '|' || rest === '>') {
-      const block = [];
-      i += 1;
-      while (i < lines.length && /^\s/.test(lines[i])) {
-        block.push(lines[i].replace(/^\s{2}/, ''));
-        i += 1;
-      }
-      meta[key] = block.join('\n').trimEnd();
-      continue;
-    }
-
-    if (rest === '' && i + 1 < lines.length && lines[i + 1].trim().startsWith('- ')) {
-      const items = [];
-      i += 1;
-      while (i < lines.length && lines[i].trim().startsWith('- ')) {
-        items.push(lines[i].trim().slice(2).trim());
-        i += 1;
-      }
-      meta[key] = items;
-      continue;
-    }
-
-    if (rest.startsWith('"') && rest.endsWith('"')) {
-      meta[key] = rest.slice(1, -1).replace(/\\"/g, '"');
-    } else if (rest === 'true' || rest === 'false') {
-      meta[key] = rest === 'true';
-    } else if (/^\d+$/.test(rest)) {
-      meta[key] = Number(rest);
-    } else if (rest) {
-      meta[key] = rest;
-    } else {
-      meta[key] = null;
-    }
-    i += 1;
-  }
-
-  return meta;
-}
-
-/**
- * @param {string} planPath
- * @returns {{ meta: Record<string, unknown>, body: string } | null}
- */
-function loadPlanFile(planPath) {
-  const raw = readFileSync(planPath, 'utf8');
-  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
-  if (!match) {
-    return null;
-  }
-  const meta = parseSimpleYaml(match[1]);
-  if (Array.isArray(meta.todos)) {
-    meta.todos = normalizeTodos(meta.todos);
-  }
-  return { meta, body: match[2] };
-}
-
-/**
- * @param {unknown} todos
- * @returns {Array<{ id: string, content: string, status: string }>}
- */
-function normalizeTodos(todos) {
-  if (!Array.isArray(todos)) {
-    return [];
-  }
-  return todos
-    .filter((t) => t && typeof t === 'object')
-    .map((t) => {
-      const item = /** @type {{ id?: string, content?: string, status?: string }} */ (t);
-      let status = String(item.status || 'pending');
-      if (!TODO_STATUSES.has(status)) {
-        status = 'pending';
-      }
-      return {
-        id: String(item.id || ''),
-        content: String(item.content || ''),
-        status
-      };
-    })
-    .filter((t) => t.id);
-}
-
-/**
- * @param {Record<string, unknown>} meta
- * @param {string} surface
- * @returns {boolean}
- */
-function hasSurface(meta, surface) {
-  const surfaces = meta.surfaces;
-  return Array.isArray(surfaces) && surfaces.includes(surface);
-}
-
-module.exports = {
-  REPO_ROOT,
-  PLANS_DIR,
-  loadPlanFile,
-  normalizeTodos,
-  hasSurface
-};

package/scripts/lib/plan-prevalidate-gates.js

@@ -1,337 +0,0 @@
-/**
- * @fileoverview Pre-implementation plan validation gates (/validate-plan).
- */
-
-/* eslint-disable valid-jsdoc, require-jsdoc */
-
-'use strict';
-
-const {
-  statSync,
-  mkdirSync,
-  writeFileSync
-} = require('../../lib/internal/fs-real-sync');
-const path = require('path');
-const { loadPlanFile, hasSurface } = require('./plan-parse');
-
-const REPO_ROOT = path.resolve(__dirname, '../..');
-const PREVALIDATE_REPORT_DIR = path.join(REPO_ROOT, 'temp/plan-prevalidation');
-
-/**
- * @param {unknown} value
- * @returns {string}
- */
-function escapeMarkdownCell(value) {
-  return String(value ?? '')
-    .replace(/\r?\n+/g, ' ')
-    .replace(/\|/g, '\\|')
-    .trim();
-}
-
-/**
- * @typedef {{ label: string, status: 'pass' | 'fail' | 'warn' | 'skip', detail?: string }} GateResult
- */
-
-/**
- * @param {string} label
- * @param {'pass' | 'fail' | 'warn' | 'skip'} status
- * @param {string} [detail]
- * @returns {GateResult}
- */
-function gate(label, status, detail) {
-  return { label, status, detail };
-}
-
-/**
- * @param {string} body
- * @param {string} heading
- * @returns {boolean}
- */
-function hasHeading(body, heading) {
-  const re = new RegExp(`^## ${heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`, 'm');
-  return re.test(body);
-}
-
-/**
- * @param {string} body
- * @returns {string | null}
- */
-function extractReportStatus(body) {
-  const reportMatch = body.match(/## Plan Validation Report[\s\S]*?\*\*Status\*\*:\s*(.+)/i);
-  if (!reportMatch) {
-    return null;
-  }
-  const line = reportMatch[1].trim();
-  if (/VALIDATED/i.test(line) && !/NEEDS|INCOMPLETE/i.test(line)) {
-    return 'validated';
-  }
-  if (/NEEDS UPDATES/i.test(line)) {
-    return 'needs-updates';
-  }
-  if (/INCOMPLETE/i.test(line)) {
-    return 'incomplete';
-  }
-  return null;
-}
-
-/**
- * @param {string} body
- * @param {string} subsection
- * @returns {boolean}
- */
-function hasReportSubsection(body, subsection) {
-  const reportIdx = body.indexOf('## Plan Validation Report');
-  if (reportIdx < 0) {
-    return false;
-  }
-  const report = body.slice(reportIdx);
-  const re = new RegExp(`^### ${subsection.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'm');
-  return re.test(report);
-}
-
-/**
- * @param {string} planPath
- * @param {string | undefined} lastValidatedAt
- * @returns {boolean}
- */
-function isValidationStale(planPath, lastValidatedAt) {
-  if (!lastValidatedAt) {
-    return false;
-  }
-  const validatedMs = Date.parse(String(lastValidatedAt));
-  if (Number.isNaN(validatedMs)) {
-    return false;
-  }
-  const mtime = statSync(planPath).mtimeMs;
-  return mtime > validatedMs + 86400000;
-}
-
-/**
- * @param {string} body
- * @returns {boolean}
- */
-function needsManualSection(body, meta) {
-  const reportIdx = body.indexOf('## Plan Validation Report');
-  const planBody = reportIdx >= 0 ? body.slice(0, reportIdx) : body;
-  const todos = Array.isArray(meta.todos) ? meta.todos : [];
-  const todoText = todos.map((t) => `${t.content} ${t.id}`).join(' ');
-  const combined = `${planBody}\n${todoText}`;
-  return /manual|pilot|live proof|e2e smoke|container proof|dev-reload/i.test(combined);
-}
-
-/**
- * @param {Record<string, unknown>} meta
- * @returns {boolean}
- */
-function isCodePlan(meta) {
-  return meta.planType === 'code';
-}
-
-/**
- * @param {Record<string, unknown>} meta
- * @returns {boolean}
- */
-function isMetaPlan(meta) {
-  return meta.planType === 'meta';
-}
-
-/**
- * @param {string} planPath
- * @param {{ allowNeedsUpdates?: boolean, repoProfile?: string }} [opts]
- */
-function runPrevalidateGates(planPath, opts = {}) {
-  const loaded = loadPlanFile(planPath);
-  if (!loaded) {
-    return {
-      gates: [gate('plan-parse', 'fail', 'invalid or missing frontmatter')],
-      reportStatus: 'incomplete',
-      planValidatedStatus: 'incomplete',
-      meta: {},
-      body: ''
-    };
-  }
-
-  const { meta, body } = loaded;
-  const gates = [];
-  const code = isCodePlan(meta);
-  const metaPlan = isMetaPlan(meta);
-
-  if (!meta.name && !meta.overview) {
-    gates.push(gate('frontmatter-name', 'fail', 'name or overview required'));
-  } else {
-    gates.push(gate('frontmatter-name', 'pass'));
-  }
-
-  if (!Array.isArray(meta.todos) || meta.todos.length === 0) {
-    gates.push(gate('todos', 'fail', 'frontmatter todos required'));
-  } else {
-    gates.push(gate('todos', 'pass', `${meta.todos.length} todo(s)`));
-  }
-
-  const scopeSections = ['Scope', 'Rules and Standards', 'Before Development', 'Definition of Done'];
-  for (const section of scopeSections) {
-    if (!hasHeading(body, section)) {
-      gates.push(gate(`section-${section}`, 'fail', `missing ## ${section}`));
-    } else {
-      gates.push(gate(`section-${section}`, 'pass'));
-    }
-  }
-
-  if (hasHeading(body, 'Scope')) {
-    const scopeOk =
-      /### In scope/i.test(body) && /### Out of scope/i.test(body);
-    gates.push(
-      scopeOk
-        ? gate('scope-boundaries', 'pass')
-        : gate('scope-boundaries', 'fail', 'Scope needs ### In scope and ### Out of scope')
-    );
-  }
-
-  if (code) {
-    for (const section of ['Architecture alignment', 'Code reuse scan', 'Expected Automated Tests']) {
-      gates.push(
-        hasHeading(body, section)
-          ? gate(`section-${section}`, 'pass')
-          : gate(`section-${section}`, 'fail', `code plan missing ## ${section}`)
-      );
-    }
-    if (!hasHeading(body, 'File Size Reduction Candidates')) {
-      gates.push(gate('file-size-section', 'warn', 'missing ## File Size Reduction Candidates'));
-    } else {
-      gates.push(gate('file-size-section', 'pass'));
-    }
-    if (hasSurface(meta, 'api') && !meta.apiTiers) {
-      gates.push(gate('api-tiers', 'fail', 'api surface requires apiTiers in frontmatter'));
-    } else if (hasSurface(meta, 'api')) {
-      gates.push(gate('api-tiers', 'pass'));
-    } else {
-      gates.push(gate('api-tiers', 'skip', 'no api surface'));
-    }
-  } else if (metaPlan) {
-    gates.push(gate('architecture-section', 'skip', 'meta plan'));
-    gates.push(gate('reuse-section', 'skip', 'meta plan'));
-    gates.push(gate('automated-tests-section', 'skip', 'meta plan'));
-  } else {
-    gates.push(gate('code-sections', 'skip', `planType=${meta.planType || 'unknown'}`));
-  }
-
-  if (code && needsManualSection(body, meta) && !hasHeading(body, 'Manual testing')) {
-    gates.push(gate('manual-testing-section', 'fail', 'manual scope detected — add ## Manual testing'));
-  } else if (metaPlan) {
-    gates.push(gate('manual-testing-section', 'skip', 'meta plan'));
-  } else if (needsManualSection(body, meta)) {
-    gates.push(gate('manual-testing-section', 'pass'));
-  } else {
-    gates.push(gate('manual-testing-section', 'skip', 'no manual scope'));
-  }
-
-  if (!hasHeading(body, 'Plan Validation Report')) {
-    gates.push(gate('validation-report', 'fail', 'missing ## Plan Validation Report'));
-  } else {
-    gates.push(gate('validation-report', 'pass'));
-    const reportStatus = extractReportStatus(body);
-    if (!reportStatus) {
-      gates.push(gate('report-status', 'fail', 'report missing **Status**: VALIDATED line'));
-    } else if (reportStatus === 'validated') {
-      gates.push(gate('report-status', 'pass', 'VALIDATED'));
-    } else if (reportStatus === 'needs-updates') {
-      gates.push(
-        gate('report-status', opts.allowNeedsUpdates ? 'warn' : 'fail', 'NEEDS UPDATES')
-      );
-    } else {
-      gates.push(gate('report-status', 'fail', 'INCOMPLETE'));
-    }
-
-    if (code) {
-      for (const sub of [
-        'Architecture alignment',
-        'Code reuse scan',
-        'Testing strategy',
-        'Manual testing and approval'
-      ]) {
-        gates.push(
-          hasReportSubsection(body, sub)
-            ? gate(`report-${sub}`, 'pass')
-            : gate(`report-${sub}`, 'fail', `report missing ### ${sub}`)
-        );
-      }
-    }
-  }
-
-  if (isValidationStale(planPath, meta.lastValidatedAt)) {
-    gates.push(gate('staleness', 'fail', 'plan modified after lastValidatedAt — re-validate'));
-  } else if (meta.lastValidatedAt) {
-    gates.push(gate('staleness', 'pass'));
-  } else {
-    gates.push(gate('staleness', 'skip', 'not yet validated'));
-  }
-
-  const hasFail = gates.some((g) => g.status === 'fail');
-  const hasWarn = gates.some((g) => g.status === 'warn');
-  let planValidatedStatus = 'validated';
-  if (hasFail) {
-    planValidatedStatus = 'incomplete';
-  } else if (hasWarn) {
-    planValidatedStatus = 'needs-updates';
-  }
-
-  const reportStatus = extractReportStatus(body) || planValidatedStatus;
-  if (reportStatus !== 'validated') {
-    planValidatedStatus = reportStatus === 'needs-updates' ? 'needs-updates' : 'incomplete';
-  }
-  if (hasFail) {
-    planValidatedStatus = 'incomplete';
-  }
-
-  return { gates, reportStatus, planValidatedStatus, meta, body };
-}
-
-/**
- * @param {object} params
- * @returns {string}
- */
-function buildPrevalidateReport(params) {
-  const { planPath, planName, actor, runAt, gates, planValidatedStatus, reportStatus } = params;
-  const lines = [
-    '# Plan pre-validation summary',
-    '',
-    '| Field | Value |',
-    '| --- | --- |',
-    `| **Plan** | \`${planName}\` |`,
-    `| **Stamp status** | \`${planValidatedStatus}\` |`,
-    `| **Report status** | \`${reportStatus || 'unknown'}\` |`,
-    `| **Run at** | ${runAt} |`,
-    `| **Validated by** | ${actor || '_not set_'} |`,
-    `| **Plan file** | \`${path.relative(REPO_ROOT, planPath)}\` |`,
-    '',
-    '## Gates',
-    '',
-    '| Gate | Result | Detail |',
-    '| --- | --- | --- |'
-  ];
-  for (const g of gates) {
-    lines.push(`| ${escapeMarkdownCell(g.label)} | ${escapeMarkdownCell(g.status)} | ${escapeMarkdownCell(g.detail || '')} |`);
-  }
-  return `${lines.join('\n')}\n`;
-}
-
-/**
- * @param {string} content
- * @param {string} planBaseName
- */
-function writePrevalidateReport(content, planBaseName) {
-  mkdirSync(PREVALIDATE_REPORT_DIR, { recursive: true });
-  const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
-  writeFileSync(path.join(PREVALIDATE_REPORT_DIR, `${planBaseName}.${stamp}.md`), content, 'utf8');
-  writeFileSync(path.join(PREVALIDATE_REPORT_DIR, 'LATEST.md'), content, 'utf8');
-}
-
-module.exports = {
-  PREVALIDATE_REPORT_DIR,
-  runPrevalidateGates,
-  buildPrevalidateReport,
-  writePrevalidateReport,
-  hasHeading,
-  extractReportStatus,
-  isValidationStale
-};