@warpgogol/forge 2.8.0 → 2.8.2

package/os/rfc/handlers/validate.ts

@@ -0,0 +1,166 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC validation handler — V-01..V-22 frontmatter, section, and referential integrity checks.</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0303: extracted validate handler from handlers.ts into handlers/validate.ts.</item>
+  <item>Post-refactor hardening: targeted validation resolves RFC ids inside archive subdirectories.</item>
+</CHANGE_SUMMARY>
+*/
+
+import path from "node:path";
+
+import {
+  listRfcFiles,
+  readAndParseRfc,
+  rfcFileMatchesId,
+  type ParsedRfc,
+} from "../frontmatter-io.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import type { RfcValidationViolation, RfcValidationResult, Marker } from "../types.ts";
+import { RFC_DIR, RFC_KNOWN_KEYS } from "../types.ts";
+import { DNA_DOCS, AP_DOCS, loadInvariantIds } from "./shared.ts";
+import { collectRfcCommandLifecycleViolations } from "./lifecycle.ts";
+import { validateSingleRfc, checkFrontmatterYamlParse } from "./validate-rules.ts";
+
+export async function runRfcValidate(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<RfcValidationResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const rfcDirPath = path.join(workspaceRoot, RFC_DIR);
+
+  const targetId = input.flags["id"] as string | undefined;
+
+  const allFiles = await listRfcFiles(rfcDirPath);
+  const filesToValidate = targetId
+    ? allFiles.filter((f) => rfcFileMatchesId(f, targetId))
+    : allFiles;
+
+  if (filesToValidate.length === 0) {
+    if (targetId) {
+      throw new Error(`No RFC file found for id ${targetId} in ${RFC_DIR}/`);
+    }
+    logger.info("No RFC files found to validate.");
+    return {
+      data: { command: "rfc.validate", status: "pass", count: 0, violations: [], markers: [] },
+      summary: "No RFC files found to validate",
+    };
+  }
+
+  const allParsed: Map<string, { fileName: string; parsed: ParsedRfc }> = new Map();
+  const allParsedByFile: Map<string, { fileName: string; parsed: ParsedRfc }> = new Map();
+
+  const violations: RfcValidationViolation[] = [];
+  const allMarkers: Marker[] = [];
+
+  function addViolation(
+    rfcId: string,
+    file: string,
+    rule: string,
+    message: string,
+    severity: "error" | "warning" = "error",
+  ): void {
+    violations.push({ rfcId, file, rule, message, severity });
+  }
+
+  for (const f of allFiles) {
+    const result = await readAndParseRfc(rfcDirPath, f);
+    if (result) {
+      if ("error" in result) {
+        checkFrontmatterYamlParse(f, result, addViolation);
+        continue;
+      }
+      const id = String(result.parsed.frontmatter["id"] ?? "");
+      allParsed.set(id, { fileName: f, parsed: result.parsed });
+      allParsedByFile.set(f, { fileName: f, parsed: result.parsed });
+    }
+  }
+
+  const validDnaIds = await loadInvariantIds(workspaceRoot, DNA_DOCS, "DNA");
+  const validApIds = await loadInvariantIds(workspaceRoot, AP_DOCS, "AP");
+  const knownKeys = new Set<string>(RFC_KNOWN_KEYS);
+
+  const seenIds = new Map<string, string>();
+  const seenFilenameNumbers = new Map<number, string>();
+
+  for (const fileName of filesToValidate) {
+    const result = allParsedByFile.get(fileName);
+    if (!result) continue;
+
+    const markers = await validateSingleRfc(
+      fileName,
+      result.parsed,
+      allParsed,
+      seenIds,
+      validDnaIds,
+      validApIds,
+      knownKeys,
+      workspaceRoot,
+      addViolation,
+      seenFilenameNumbers,
+    );
+    allMarkers.push(...markers);
+  }
+
+  const lifecycle = await collectRfcCommandLifecycleViolations(
+    workspaceRoot,
+    filesToValidate,
+    allParsedByFile,
+    context.commandRegistry,
+  );
+  for (const violation of lifecycle.violations) {
+    addViolation(
+      violation.rfcId,
+      violation.file,
+      violation.rule,
+      violation.message,
+      violation.severity,
+    );
+  }
+
+  const hasErrors = violations.some((v) => v.severity === "error");
+  const resultStatus = hasErrors ? "fail" : "pass";
+
+  if (outputFormat === "pretty") {
+    if (violations.length === 0) {
+      logger.success(`All ${filesToValidate.length} RFC(s) passed validation.`);
+    } else {
+      logger.section(`RFC Validation (${filesToValidate.length} file(s))`);
+      for (const v of violations) {
+        const prefix = v.severity === "error" ? "ERROR" : "WARN";
+        logger[v.severity === "error" ? "error" : "warn"](
+          `[${prefix}] ${v.rfcId} ${v.rule}: ${v.message}`,
+        );
+      }
+      const errorCount = violations.filter((v) => v.severity === "error").length;
+      const warnCount = violations.filter((v) => v.severity === "warning").length;
+      if (errorCount > 0) {
+        logger.error(`${errorCount} error(s), ${warnCount} warning(s)`);
+      } else {
+        logger.warn(`${warnCount} warning(s), 0 errors — passed`);
+      }
+    }
+  }
+
+  return {
+    data: {
+      command: "rfc.validate",
+      status: resultStatus,
+      count: filesToValidate.length,
+      violations,
+      markers: allMarkers,
+    },
+    exitCode: hasErrors ? 1 : 0,
+    summary: hasErrors
+      ? `${violations.filter((v) => v.severity === "error").length} error(s) found`
+      : `All ${filesToValidate.length} RFC(s) passed validation`,
+  };
+}

package/os/rfc/handlers.ts

@@ -0,0 +1,19 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Thin re-export shim for RFC handlers split into handlers/ (RFC-0303).</purpose>
+<non-goals>
+  <item>Do not implement command logic here; implementations live in handlers/*.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0153: remove the C:/Temp debug write + debug-keys leak; make V-12 bidirectional; add V-16 (status/date coupling), V-17 (strict supersededBy), V-18 (related referential integrity vs DNA/AP/RFC); rfc.check skips glob/placeholder/prose paths.</item>
+  <item>RFC-0303: split handlers.ts (1447 lines) into handlers/{shared,lifecycle,list-create,validate,check,index-graph}.ts.</item>
+</CHANGE_SUMMARY>
+*/
+
+export { runRfcList, runRfcCreate, runRfcNextId } from "./handlers/list-create.ts";
+export { runRfcValidate } from "./handlers/validate.ts";
+export { runRfcCommandLifecycleValidate } from "./handlers/lifecycle.ts";
+export { runRfcCheck } from "./handlers/check.ts";
+export { runRfcIndexGenerate, runRfcIndexValidate, runRfcGraph } from "./handlers/index-graph.ts";
+export { runRfcImplementStamp } from "./handlers/implement-stamp.ts";

package/os/rfc/index.ts

@@ -0,0 +1,97 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Barrel export for the rfc domain — types, constants, module, and handlers.</purpose>
+<non-goals>
+  <item>Do not implement RFC logic here; delegate to handlers.js and rfc.module.js.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Backfilled complete Compass header (MODULE_MAP, CHANGE_SUMMARY) for compliance.</item>
+</CHANGE_SUMMARY>
+*/
+
+export { forgeRfcModule } from "./rfc.module.ts";
+export {
+  listRfcFiles,
+  parseRfcFile,
+  readAndParseRfc,
+  rfcFileMatchesId,
+  getRfcStatusById,
+  loadRfcStatusMap,
+  type ParsedRfc,
+  type ReadAndParseRfcResult,
+} from "./frontmatter-io.ts";
+export {
+  runRfcList,
+  runRfcCreate,
+  runRfcValidate,
+  runRfcCommandLifecycleValidate,
+  runRfcCheck,
+} from "./handlers.ts";
+export { runRfcImplementStamp } from "./handlers/implement-stamp.ts";
+export { runRfcAcceptanceRun, runProbe, validateAcceptanceShape } from "./acceptance.ts";
+export { runRfcVerificationEmit, buildEvidenceEnvelope } from "./verification-evidence.ts";
+export { runRfcDnaTraceValidate, runRfcDnaTraceGenerate, buildDnaTrace } from "./dna-trace.ts";
+export type { DnaTraceEntry, DnaTraceResult } from "./dna-trace.ts";
+export { collectDecisionLog, scoreDecisions, runRfcDecisionLogGenerate } from "./decision-log.ts";
+export { runRfcSupersedePropose } from "./handlers/supersede-propose.ts";
+export { runRfcArchive } from "./handlers/archive.ts";
+export {
+  evaluateAcceptanceCriteria,
+  extractAcceptanceCriteriaSection,
+  collectMarkers,
+  checkFrontmatterYamlParse,
+  type AcceptanceCriteriaEvaluation,
+} from "./handlers/validate-rules.ts";
+export type {
+  RfcArchiveResult,
+  ArchiveMove as RfcArchiveMove,
+  ArchiveSkip as RfcArchiveSkip,
+} from "./handlers/archive.ts";
+export type {
+  DecisionLogEntry,
+  DecisionLogEntryKind,
+  DecisionLogResult,
+  ConsultedDecision,
+  RfcSupersedeProposeResult,
+} from "./types.ts";
+export type {
+  RfcImplementStampData,
+  RfcImplementStampRule,
+  RfcImplementStampViolation,
+  RfcImplementStampResult,
+} from "./types.ts";
+export type {
+  RfcStatus,
+  RfcKind,
+  RfcScope,
+  RfcCommands,
+  RfcFrontmatter,
+  RfcListEntry,
+  RfcListResult,
+  RfcCreateResult,
+  RfcValidationViolation,
+  RfcValidationResult,
+  Marker,
+  RfcCommandLifecycleViolation,
+  RfcCommandLifecycleValidationResult,
+  RfcCheckViolation,
+  RfcCheckResult,
+  AcceptanceProbe,
+  ProbeResult,
+  RfcAcceptanceRunResult,
+  VerificationEvidence,
+  VerificationEvidenceProbeRecord,
+  RfcVerificationEmitResult,
+} from "./types.ts";
+export {
+  RFC_STATUSES,
+  RFC_KINDS,
+  RFC_SCOPES,
+  RFC_DIR,
+  RFC_TEMPLATE_FILE,
+  RFC_TEMPLATE_FALLBACK_FILE,
+  RFC_ID_PATTERN,
+  RFC_FULL_REQUIRED_SECTIONS,
+  RFC_METADATA_CUTOFF,
+} from "./types.ts";