@opum-ai/lore 0.1.0 → 0.2.0

package/src/core/validate.ts

@@ -1,517 +0,0 @@
-/**
- * validate.ts — the **pure**, aggregating engine behind `lore validate`.
- *
- * Where {@link tryParseConcept}/{@link validateFrontmatter} are *fail-fast* (they throw the
- * first error-tier problem they hit, which is right for the write path — lore must never
- * emit bytes it would refuse to read back), `lore validate` is a **reporter**: it surfaces
- * *every file's* findings in one pass — fail-fast aborts the whole run on the first bad file;
- * this never does — so an author or a pre-commit hook sees the whole bundle's picture at once
- * (cli-surface §validate, ADR-0007). Within a single file the frontmatter tier still
- * short-circuits: a parse failure yields the one frontmatter error (plus the raw-text
- * quote-safety scan), and the per-type section checks — which presuppose a parsed type/body —
- * run only once the frontmatter parses. This module turns the fail-fast machinery into an
- * aggregator: it runs the existing frontmatter engine per file, collects what it throws or
- * warns as {@link Finding}s, and layers the two checks ADR-0007 adds on top — **per-type
- * required sections** and **frontmatter quote-safety**.
- *
- * It stays within the core contract (lore-design §2.1): pure, filesystem-free, no printing
- * or `process.exit`. The command layer (`commands/validate.ts`) owns file discovery and I/O
- * and hands raw text here; this module owns the *judgement* and returns structured data.
- *
- * The tiers (ADR-0007 "How lore checks conformance"):
- *
- * - **Tier 1 — OKF §9 (error):** frontmatter parses and `type` is present/non-empty. Reuses
- *   {@link tryParseConcept}, whose thrown `validation` {@link LoreError} becomes one finding.
- * - **Tier 2 — per-type shape (error):** a *known* type's strict Zod schema (surfaced through
- *   the same {@link tryParseConcept} throw) **plus** its {@link requiredSectionsFor required
- *   body sections} (this module).
- * - **Tier 3 — extensions (warning):** an unknown `type`, an extra key on a known type, or a
- *   missing/over-long `summary` — collected from the {@link WarningCollector}.
- * - **Cross-cutting — quote-safety:** unquoted frontmatter scalars that a YAML-1.1 consumer
- *   would coerce to a non-string (or that carry a YAML indicator), so the value is
- *   parser-dependent across the bundle's target renderers ({@link quoteSafetyFindings}).
- *
- * A file that is **not a concept** (no frontmatter, an empty/`null` fence, or a bare
- * scalar/list — e.g. a hand-written `index.md`/`log.md`) is **skipped**, not failed: exactly
- * the {@link tryParseConcept} distinction {@link loadBundle} draws, so a pre-commit hook that
- * globs `*.md` does not trip over a non-concept file.
- */
-
-import { fromMarkdown } from "mdast-util-from-markdown";
-import { LoreError, singleLine, stripAnsiAndControls, WarningCollector } from "../errors";
-import { effectiveProfileFor, nodeText } from "./bundle";
-import { type Concept, tryParseConcept } from "./concept";
-import type { Finding as BaseFinding, Severity } from "./finding";
-import { decodeTarget } from "./links";
-import { defaultProfile, type Profile } from "./profile";
-import { ROOT_INDEX_PATH } from "./scaffold";
-import { requiredSectionsFor } from "./schema";
-import { expectedResource } from "./template";
-
-export type { Severity };
-
-/** Which check produced a {@link Finding}, for machine consumers and grouped display. */
-export type FindingRule = "frontmatter" | "required-section" | "quote-safety" | "resource";
-
-/** One tiered problem found in a single file — the shared {@link BaseFinding} narrowed to `validate`'s rules. */
-export type Finding = BaseFinding<FindingRule>;
-
-/** The validation outcome for one file. */
-export interface FileReport {
-  /** The file's repo-relative POSIX path, as given to {@link validateConceptText}. */
-  readonly path: string;
-  /** The resolved concept `type`, or `undefined` for a skipped non-concept or an unparseable file. */
-  readonly type?: string;
-  /** Every finding for this file, in tier order (frontmatter → sections → quote-safety). */
-  readonly findings: readonly Finding[];
-  /** `true` when the file is not a concept and was not validated (no findings contributed). */
-  readonly skipped: boolean;
-  /** `true` when the file carries no error-severity finding (a warning-only or clean/skipped file). */
-  readonly ok: boolean;
-}
-
-/** The aggregate report across every validated file — the `validate.report` payload. */
-export interface ValidateReport {
-  /** Per-file reports, in the order the files were supplied. */
-  readonly files: readonly FileReport[];
-  /** Total error-severity findings across all files. */
-  readonly errorCount: number;
-  /** Total warning-severity findings across all files. */
-  readonly warningCount: number;
-  /** Files skipped as non-concepts. */
-  readonly skippedCount: number;
-}
-
-/**
- * Validate one file's raw bytes into a {@link FileReport}, never throwing for a *content*
- * problem — every tier is collected as a {@link Finding}.
- *
- * The frontmatter tiers reuse {@link parseConcept}: a thrown `validation` {@link LoreError}
- * (missing/invalid `type`, a mistyped known field, unparseable YAML) becomes one error
- * finding; the {@link WarningCollector} it fills (unknown type/key, summary) becomes warning
- * findings. A non-concept (no usable frontmatter) is **skipped** via {@link tryParseConcept}.
- * On a clean parse the two ADR-0007 additions run: {@link requiredSectionFindings} and
- * {@link quoteSafetyFindings}.
- *
- * `path` is resolved to its **judging profile** via {@link import("./bundle").effectiveProfileFor}
- * before any of that runs: the bundle-root {@link ROOT_INDEX_PATH} (this module's repo-relative
- * spelling) is always judged against the built-in {@link defaultProfile}, never `profile`
- * (LORE-144) — see that helper for why, and for why it lives in `bundle.ts` rather than here
- * (LORE-192: this module already imports {@link nodeText} from `bundle.ts`, so the reverse import
- * would cycle).
- *
- * A non-{@link LoreError} (a genuine bug) is *not* swallowed — it propagates, so a crash is
- * never silently dressed up as a validation finding.
- */
-export function validateConceptText(path: string, raw: string, profile: Profile = defaultProfile()): FileReport {
-  const effective = effectiveProfileFor(path, ROOT_INDEX_PATH, profile);
-  // Parse exactly once. tryParseConcept fills the collector with tier-3 warnings, returns null for
-  // a non-concept (skip), and throws a `validation` LoreError for a real-but-malformed concept —
-  // so a single call draws every distinction the reporter needs without re-parsing the same bytes.
-  const warnings = new WarningCollector();
-  let concept: Concept | null;
-  try {
-    concept = tryParseConcept(path, raw, { warnings, profile: effective });
-  } catch (err) {
-    // A genuine bug (a non-LoreError) must never be dressed up as a validation finding — propagate
-    // it (the invariant this module states). A malformed concept becomes one error finding; its
-    // `type` is recovered best-effort from the raw frontmatter so a `--type` run still attributes
-    // (and so never silently drops) a known-type-but-invalid file — the gate it exists to enforce.
-    if (!(err instanceof LoreError)) {
-      throw err;
-    }
-    const findings: Finding[] = [{ severity: "error", rule: "frontmatter", message: err.message }];
-    // Quote-safety is a raw-text scan needing no parsed concept, so it still runs and the author
-    // sees YAML hazards in the same pass; per-type section checks presuppose a parsed type/body
-    // and are deferred until the frontmatter parses.
-    findings.push(...quoteSafetyFindings(raw));
-    return { path, type: recoverType(raw), findings, skipped: false, ok: false };
-  }
-  if (concept === null) {
-    return { path, findings: [], skipped: true, ok: true };
-  }
-
-  const findings: Finding[] = [];
-  for (const message of warnings.list()) {
-    findings.push({ severity: "warning", rule: "frontmatter", message });
-  }
-  findings.push(...requiredSectionFindings(concept.type, concept.body, effective));
-  findings.push(...resourceDriftFindings(path, concept, effective));
-  findings.push(...quoteSafetyFindings(raw));
-
-  return finalize(path, concept.type, findings);
-}
-
-/**
- * Validate a list of `{ path, raw }` files into one aggregate {@link ValidateReport}, optionally
- * narrowed to a single `type`. Pure over its inputs (the command layer does the reading), so the
- * aggregation and the `--type` filter are testable without the filesystem.
- *
- * `type` (the `--type <T>` flag, already canonicalized by the caller) narrows the report to one
- * concept type — but **never** at the cost of hiding a broken file from the gate: see
- * {@link keepForType}.
- */
-export function validateFiles(
-  files: readonly { path: string; raw: string }[],
-  type?: string,
-  profile: Profile = defaultProfile(),
-): ValidateReport {
-  const wanted = type?.toLowerCase();
-  const reports: FileReport[] = [];
-  for (const file of files) {
-    const report = validateConceptText(file.path, file.raw, profile);
-    if (wanted !== undefined && !keepForType(report, wanted)) {
-      continue;
-    }
-    reports.push(report);
-  }
-  return summarize(reports);
-}
-
-/**
- * Whether a per-file report belongs in a `--type <wanted>` run. An **error** file is **always
- * kept**: silently dropping a broken file would turn the very gate `--type` scopes green over a
- * malformed concept, and a malformed file's true type can never be trusted to be *not* `wanted`
- * (its frontmatter did not parse). A clean concept is kept only when its type matches; a skipped
- * non-concept is dropped (it is genuinely not `wanted`). The error file's {@link recoverType}d
- * type is for display only — never a reason to filter it out.
- */
-function keepForType(report: FileReport, wanted: string): boolean {
-  if (!report.ok && !report.skipped) {
-    return true;
-  }
-  return report.type?.toLowerCase() === wanted;
-}
-
-/** Tally per-file reports into the aggregate counts (errors, warnings, skips). */
-export function summarize(files: readonly FileReport[]): ValidateReport {
-  let errorCount = 0;
-  let warningCount = 0;
-  let skippedCount = 0;
-  for (const file of files) {
-    if (file.skipped) {
-      skippedCount++;
-    }
-    for (const finding of file.findings) {
-      if (finding.severity === "error") {
-        errorCount++;
-      } else {
-        warningCount++;
-      }
-    }
-  }
-  return { files, errorCount, warningCount, skippedCount };
-}
-
-/**
- * Assemble a non-skipped {@link FileReport}, deriving `ok` from the absence of any error-severity
- * finding (a warning-only file is still `ok` — warnings never fail a file, cli-contract §4.1).
- */
-function finalize(path: string, type: string, findings: readonly Finding[]): FileReport {
-  const ok = !findings.some((finding) => finding.severity === "error");
-  return { path, type, findings, skipped: false, ok };
-}
-
-/**
- * A best-effort `type` read from the raw frontmatter of a file that failed to parse, so a `--type`
- * run can attribute (and therefore never silently drop) a known-type-but-invalid concept. Scans the
- * fenced block for a top-level `type:` line, stripping a trailing comment and surrounding quotes;
- * returns `undefined` when no `type` is recoverable (unparseable YAML, or a missing `type`). The
- * value is raw (not canonicalized) — it is matched case-insensitively, only for filtering/display.
- */
-function recoverType(raw: string): string | undefined {
-  const block = frontmatterBlock(raw);
-  if (block === null) {
-    return undefined;
-  }
-  for (const line of block.split("\n")) {
-    const match = /^type:[ \t]+(.*)$/.exec(line);
-    if (match === null) {
-      continue;
-    }
-    const value = unquoteScalar(stripInlineComment((match[1] ?? "").trim()));
-    return value === "" ? undefined : value;
-  }
-  return undefined;
-}
-
-/** Strip a trailing YAML comment (` #…`, the `#` preceded by whitespace) from a raw scalar value. */
-function stripInlineComment(value: string): string {
-  return value.replace(/\s+#.*$/, "").trimEnd();
-}
-
-/** Remove a matching pair of surrounding quotes from a scalar value, else return it unchanged. */
-function unquoteScalar(value: string): string {
-  const quote = value[0];
-  if (value.length >= 2 && (quote === '"' || quote === "'") && value.endsWith(quote)) {
-    return value.slice(1, -1);
-  }
-  return value;
-}
-
-// ── Tier 2: required body sections ─────────────────────────────────────────────—
-
-/**
- * The required-section findings for a concept body: one **error** per
- * {@link requiredSectionsFor required `##` heading} the body does not carry. Matching is on
- * {@link normalizeHeading normalized} heading text (trimmed, interior whitespace collapsed,
- * lower-cased), so `## status` and `## Acceptance  criteria` (a double space that renders
- * identically) both satisfy their requirement. A type with no required sections (every unknown
- * type, and Epic/Spec/Runbook/Reference under the minimal policy) yields nothing.
- */
-function requiredSectionFindings(type: string, body: string, profile: Profile): Finding[] {
-  const required = requiredSectionsFor(type, profile);
-  if (required.length === 0) {
-    return [];
-  }
-  const present = new Set(h2Headings(body).map(normalizeHeading));
-  const findings: Finding[] = [];
-  for (const section of required) {
-    if (!present.has(normalizeHeading(section))) {
-      findings.push({
-        severity: "error",
-        rule: "required-section",
-        message: `${type} is missing the required "## ${section}" section`,
-      });
-    }
-  }
-  return findings;
-}
-
-// ── Cross-cutting: resource drift ──────────────────────────────────────────────—
-
-/**
- * The resource-drift finding for a concept whose stamped `resource` no longer matches what its
- * path + the profile's `resource_base` would produce (LORE-47 / AC#4) — one **warning** when a
- * **present** string `resource` differs from {@link expectedResource}. Unlike `index.md`/`log.md`,
- * a stamped `resource` is not regenerated, so a later rename or `resource_base` change silently
- * leaves a stale URL; this surfaces that drift in the same pass.
- *
- * It judges only what lore itself would stamp: a file with no `resource`, a non-string `resource`,
- * or one where lore would stamp nothing here ({@link expectedResource} `undefined` — no
- * `resource_base`, an index file, or a type that owns its own `resource` field) yields nothing, so
- * an author-owned `resource` is never second-guessed. Advisory tier (`resource` is advisory
- * metadata, not a shape constraint), so it reports the staleness without failing the file.
- */
-function resourceDriftFindings(path: string, concept: Concept, profile: Profile): Finding[] {
-  const actual = concept.frontmatter.resource;
-  if (typeof actual !== "string") {
-    return [];
-  }
-  const expected = expectedResource(concept.type, path, profile);
-  if (expected === undefined || actual === expected) {
-    return [];
-  }
-  // Compare decode-tolerantly: the shared segment encoder (links.ts `encodePathSegment`) escapes the
-  // markdown-significant `! ' ( ) *` that `encodeURIComponent` leaves raw, so a `resource` stamped
-  // before LORE-28 (or hand-authored with those chars literal) differs from the freshly-encoded
-  // `expected` only in percent-encoding — an equivalent URL, not drift. Decoding both collapses that
-  // difference while a real path/`resource_base` change still decodes to a different string.
-  if (decodeTarget(actual) === decodeTarget(expected)) {
-    return [];
-  }
-  return [
-    {
-      severity: "warning",
-      rule: "resource",
-      // `actual` is sanitized here, not above: the drift comparisons must judge the *raw*
-      // bundle-authored value (sanitizing first could mask real drift or falsely collapse two
-      // distinct URLs into one), but `Finding.message` is documented as "a single-line, actionable
-      // description" and every other finding builder only ever interpolates lore-computed values
-      // (`type`, `expected`) — `resource` is the one message that embeds an author-controlled raw
-      // string straight from frontmatter. Sanitizing once here, at the only place that string
-      // reaches a message, keeps that contract for every consumer (CLI text, `--json`, a future
-      // renderer) instead of trusting each print site to re-derive the same defense (LORE-161).
-      message: `resource "${sanitizeForMessage(actual)}" is stale; this path under the profile's resource_base is "${expected}" — update it or remove the \`resource\` key`,
-    },
-  ];
-}
-
-/**
- * Collapse an author-controlled frontmatter string to a single line with no ANSI escape sequences
- * or other control bytes, for safe embedding into a {@link Finding} `message`. {@link singleLine}
- * (cli-contract §5.2's own single-line discipline) only folds line *terminators* (CR/LF/U+2028/
- * U+2029); a YAML double-quoted scalar can also smuggle an ESC-led ANSI sequence or another C0/C1/
- * DEL control byte (e.g. `resource: "…\x1b[31m…"`), which `singleLine` leaves untouched. Runs
- * `singleLine` first, then strips what it leaves via the shared {@link stripAnsiAndControls}
- * (LORE-181) — the single home for that two-pass strip, also used by `output.ts`,
- * `commands/query.ts`, and `core/links.ts` — imported from `errors.ts` rather than `output.ts`:
- * this module must stay filesystem/output-layer-free (module doc above), and `errors.ts` is
- * layer-neutral.
- */
-function sanitizeForMessage(text: string): string {
-  return stripAnsiAndControls(singleLine(text));
-}
-
-/** Normalize a heading or section name for comparison: trim, collapse interior whitespace, lower-case. */
-function normalizeHeading(text: string): string {
-  return text.trim().replace(/\s+/g, " ").toLowerCase();
-}
-
-/**
- * The text of every depth-2 (`##`) heading that is a **direct, top-level child of the document
- * root** — i.e. a genuine section heading, not one nested inside a blockquote or list item —
- * in document order. Extraction defers to a CommonMark parser (`mdast-util-from-markdown`) so a
- * `## ` that appears inside a fenced/indented code block is **not** mistaken for a heading —
- * matching how {@link loadBundle} extracts links. Unlike {@link nodeText}'s own traversal (which
- * still walks a matched heading's inline children to assemble its text), this only iterates the
- * root's immediate `children` — it does not recurse into container nodes — so `> ## Status`
- * (inside a blockquote) or a `## `-looking line inside a list item never counts as a top-level
- * section, even though both nest a real `heading` node somewhere in the tree.
- */
-function h2Headings(body: string): string[] {
-  const headings: string[] = [];
-  for (const node of fromMarkdown(body).children) {
-    if (node.type === "heading" && node.depth === 2) {
-      headings.push(nodeText(node));
-    }
-  }
-  return headings;
-}
-
-// ── Cross-cutting: frontmatter quote-safety ────────────────────────────────────—
-
-/** YAML indicator characters that make an unquoted scalar parser-dependent or reserved. */
-const INDICATOR_CHARS: ReadonlySet<string> = new Set(["@", "`", "!", "&", "*", "|", ">", ":"]);
-
-/** A bare YAML-1.1 boolean alias a non-1.2 consumer coerces away from a string. */
-const YAML11_BOOLEAN = /^(yes|no|on|off|y|n)$/i;
-
-/** A `|`/`>` block-scalar **header** (optional indent digit + chomping indicator), authored on purpose. */
-const BLOCK_SCALAR_HEADER = /^[|>][1-9]?[+-]?$/;
-
-/** A bare `YYYY-MM-DD` date a YAML-1.1 consumer parses as a timestamp. */
-const BARE_DATE = /^\d{4}-\d{2}-\d{2}$/;
-
-/**
- * The quote-safety findings for a file's raw frontmatter (ADR-0007 "frontmatter quote-safety").
- * lore's *own* output is already safe — it serializes structurally and js-yaml quotes whatever
- * needs it ([ADR-0011](../../docs/adr/0011-frontmatter-serialization-stability.md)) — so this
- * check exists for **author-written** frontmatter, whose ambiguous scalars round-trip
- * differently across the bundle's target consumers (GitHub, Obsidian, MkDocs, Docusaurus), some
- * of which still parse YAML 1.1.
- *
- * It is a deliberately **best-effort line scan** over the raw fenced block, not a re-parse: by
- * the time js-yaml has parsed the value, the ambiguity is already resolved, so the raw token is
- * the only place the hazard is visible. To stay false-positive-free on real bundles it inspects
- * only **simple top-level `key: value` lines** with a single-line unquoted scalar value;
- * quoted values, block scalars (`|`/`>`), flow collections (`[`/`{`), list items, nested
- * (indented) lines, and empty values are left alone (a documented limitation — nested/list
- * scalars are not analyzed). Returns `[]` for a file with no frontmatter fence.
- */
-export function quoteSafetyFindings(raw: string): Finding[] {
-  const findings: Finding[] = [];
-  for (const value of topLevelScalarValues(raw)) {
-    const finding = quoteSafetyForValue(value);
-    if (finding !== null) {
-      findings.push(finding);
-    }
-  }
-  return findings;
-}
-
-/** Judge one unquoted scalar value, or `null` when it is quote-safe. */
-function quoteSafetyForValue(value: string): Finding | null {
-  const first = value[0] ?? "";
-  // An intentional block-scalar header (`|`, `>-`, `|2`, …) is safe; only `>foo`/`|foo` with
-  // content abutting the indicator is suspect (it is not a valid header), so it falls through.
-  if ((first === "|" || first === ">") && BLOCK_SCALAR_HEADER.test(value)) {
-    return null;
-  }
-  if (INDICATOR_CHARS.has(first)) {
-    return error(
-      `unquoted value starts with the YAML indicator "${first}" ("${value}"); quote it so every consumer reads a string`,
-    );
-  }
-  if (YAML11_BOOLEAN.test(value)) {
-    return error(`unquoted "${value}" is a boolean to YAML 1.1 consumers; quote it to keep the string "${value}"`);
-  }
-  if (value.includes(": ")) {
-    return error(
-      `unquoted value contains a colon ("${value}"); YAML reads "key: a: b" as a nested mapping — quote the value`,
-    );
-  }
-  if (BARE_DATE.test(value)) {
-    return warning(`unquoted "${value}" parses as a date to YAML 1.1 consumers; quote it to keep it a string`);
-  }
-  return null;
-}
-
-/** Build an error-severity quote-safety {@link Finding}. */
-function error(message: string): Finding {
-  return { severity: "error", rule: "quote-safety", message };
-}
-
-/** Build a warning-severity quote-safety {@link Finding}. */
-function warning(message: string): Finding {
-  return { severity: "warning", rule: "quote-safety", message };
-}
-
-/**
- * The unquoted single-line scalar values of the top-level `key: value` lines in a file's raw
- * frontmatter fence, in order. Returns `[]` when the file has no leading `---` fence. Only the
- * lines this scan can judge safely are returned; everything else (see
- * {@link quoteSafetyFindings}) is skipped.
- */
-function topLevelScalarValues(raw: string): string[] {
-  const block = frontmatterBlock(raw);
-  if (block === null) {
-    return [];
-  }
-  const values: string[] = [];
-  for (const line of block.split("\n")) {
-    // Top-level only: a leading space/tab means a nested or list value, which this scan does
-    // not analyze. A blank line or a YAML comment carries no scalar.
-    if (line === "" || /^\s/.test(line) || line.startsWith("#")) {
-      continue;
-    }
-    const match = /^[A-Za-z0-9_][\w.-]*:(?:[ \t]+(.*))?$/.exec(line);
-    if (match === null) {
-      continue; // not a simple `key:`/`key: value` line (e.g. a `- item`, or `?`-complex key)
-    }
-    let value = (match[1] ?? "").trim();
-    // An empty value (`key:`) or a comment-only value (`key: # note`, which YAML reads as null)
-    // carries no scalar to judge.
-    if (value === "" || value.startsWith("#")) {
-      continue;
-    }
-    const quote = value[0];
-    if (quote === '"' || quote === "'") {
-      continue; // already quoted — explicitly a string, safe
-    }
-    if (value.startsWith("[") || value.startsWith("{")) {
-      continue; // flow collection — a structured list/map, not a scalar string
-    }
-    // Strip a trailing YAML comment only now, on a known-unquoted scalar: a `#` with no leading
-    // space (a URL fragment `a#b`) is part of the value and must survive, while ` # note` is a
-    // comment YAML discards — analyzing it would be a false positive (a colon there is not a hazard).
-    value = stripInlineComment(value);
-    if (value !== "") {
-      values.push(value);
-    }
-  }
-  return values;
-}
-
-/**
- * Extract the raw text **between** the opening and closing `---` fences, or `null` when the file
- * does not open with a frontmatter fence. Applies the same leading normalization
- * {@link parseConcept} does (strip BOM(s), CRLF/CR → LF, drop leading whitespace) so a
- * BOM/Windows/whitespace-padded concept is analyzed identically to how it is parsed, then takes
- * the lines up to the next line that is exactly `---`.
- */
-function frontmatterBlock(raw: string): string | null {
-  const normalized = raw
-    .replace(/^\uFEFF+/, "")
-    .replace(/\r\n?/g, "\n")
-    .replace(/^\s+/, "");
-  if (!normalized.startsWith("---\n")) {
-    return null;
-  }
-  const rest = normalized.slice(4);
-  const end = rest.indexOf("\n---");
-  if (end === -1) {
-    return null; // no closing fence — not a well-formed concept; parse-tier handles it
-  }
-  return rest.slice(0, end);
-}