@ybotok/loam 0.0.0 → 0.1.0-beta.2

package/dist/core/fleet-context.js

@@ -0,0 +1,225 @@
+/**
+ * Request-scoped read index for commands that walk a whole loam repository.
+ *
+ * The filesystem remains the source of truth.  This class deliberately has no
+ * singleton/global instance: a command creates one after loading loam.json and
+ * drops it when that invocation finishes.  Within that lifetime identical
+ * reads share their in-flight Promise, which removes both duplicate I/O and
+ * duplicate parsing without making a later CLI invocation observe stale data.
+ *
+ * Because every markdown artifact is read HERE, this is also where the two
+ * failures a read must never swallow are answered: bytes that are not UTF-8
+ * (which `readFile(path, "utf8")` silently turns into U+FFFD, so a UTF-16
+ * spec.md parses as zero requirements and grades green), and git conflict
+ * markers left in a living document (which parse as prose, and which the next
+ * `loam archive` rewrites away). One place, so no reader can forget. The
+ * decode itself lives in `document-bytes.ts`, a leaf: the parsers that read a
+ * single file without an index owe the same rule, and must not have to import
+ * this module — and the fleet it pulls in behind it — to obey it.
+ */
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { decodeDocument } from "./document-bytes.js";
+import { loadFile } from "./likec4.js";
+import { readOpenapi, } from "./openapi.js";
+import { featureSpecServices, listFeatures, listServices, } from "./repo.js";
+import { parseRequirements } from "./spec.js";
+function key(path) {
+    return resolve(path);
+}
+/* ------------------------------------------------------------------ */
+/* What a read must never swallow                                      */
+/* ------------------------------------------------------------------ */
+/**
+ * The three-way merge left its markers in the file — 1-based line numbers.
+ *
+ * The rule is `loam doctor`'s, verbatim, and it lives here now because doctor
+ * checked exactly one file (`architecture/landscape.likec4`) from a command
+ * that gates nothing. The same markers in a living `services/<svc>/spec.md`
+ * parse as prose: `loam validate --all` reported `valid: true`, and the next
+ * `loam archive` rewrote the requirements section and dropped the `=======`
+ * line with it, turning a conflict anyone can see into a document nobody can
+ * tell is wrong. For a shared docs repo where a fleet lands through PRs this is
+ * the DEFAULT failure, not an edge.
+ */
+const CONFLICT_MARKERS = ["<<<<<<<", "=======", ">>>>>>>"];
+export function conflictMarkerLines(source) {
+    const out = [];
+    source.split(/\r?\n/).forEach((line, i) => {
+        if (CONFLICT_MARKERS.some((m) => line.startsWith(m)))
+            out.push(i + 1);
+    });
+    return out;
+}
+/** One sentence for the breach, wherever it is found — doctor, validate, either axis. */
+function conflictMessage(label, lines) {
+    return (`${label} still contains git conflict markers (line${lines.length === 1 ? "" : "s"} ${lines.join(", ")}) — ` +
+        `both sides of somebody's merge are in the file, so nothing it says is anyone's text. ` +
+        `Resolve the conflict before anything else: loam rewrites this document on archive, and a rewrite deletes ` +
+        `whichever marker lines fall inside the section it owns — a visible conflict becomes a silently malformed file.`);
+}
+/**
+ * The conflict-marker finding for a requirement document (living spec.md /
+ * arch.spec.md, or a feature's delta of one). Null when the text is clean.
+ *
+ * An error because the document is not valid — nobody wrote what it now says —
+ * and because the merge that would consume it is unsafe. It does not carry
+ * `gates`: that field is coherence's (issue.ts), and the archive gate has to
+ * ask this question itself.
+ */
+export function documentConflictFinding(label, subject, text) {
+    const lines = conflictMarkerLines(text);
+    if (lines.length === 0)
+        return null;
+    return {
+        severity: "error",
+        code: "spec.merge-conflict",
+        subject,
+        message: conflictMessage(label, lines),
+    };
+}
+/** The same breach in the fleet map, where it costs every cross-service check at once. */
+export function landscapeConflictFinding(label, text) {
+    const lines = conflictMarkerLines(text);
+    if (lines.length === 0)
+        return null;
+    return {
+        severity: "error",
+        code: "landscape.merge-conflict",
+        message: conflictMessage(label, lines),
+    };
+}
+/** One coherent filesystem snapshot for one command invocation. */
+export class FleetContext {
+    services = new Map();
+    features = new Map();
+    featureServices = new Map();
+    texts = new Map();
+    requirements = new Map();
+    openapis = new Map();
+    likec4 = new Map();
+    counts = {
+        serviceEnumerations: 0,
+        featureEnumerations: 0,
+        featureServiceEnumerations: 0,
+        textReads: 0,
+        requirementParses: 0,
+        openapiParses: 0,
+        likec4Loads: 0,
+    };
+    /** A copy suitable for diagnostics/tests; callers cannot mutate the counters. */
+    stats() {
+        return { ...this.counts };
+    }
+    listServices(docsDir) {
+        const k = key(docsDir);
+        let pending = this.services.get(k);
+        if (pending === undefined) {
+            this.counts.serviceEnumerations += 1;
+            pending = listServices(docsDir);
+            this.services.set(k, pending);
+        }
+        return pending;
+    }
+    listFeatures(docsDir, opts = {}) {
+        const k = `${key(docsDir)}\0${opts.includeArchived === true ? "all" : "active"}`;
+        let pending = this.features.get(k);
+        if (pending === undefined) {
+            this.counts.featureEnumerations += 1;
+            pending = listFeatures(docsDir, opts).then((entries) => {
+                // listFeatures has already enumerated every feature's specs/ directory;
+                // seed the narrower lookup so validation/coherence do not read it again.
+                for (const entry of entries) {
+                    const featureKey = key(entry.dir);
+                    if (!this.featureServices.has(featureKey)) {
+                        this.featureServices.set(featureKey, Promise.resolve(entry.services));
+                    }
+                }
+                return entries;
+            });
+            this.features.set(k, pending);
+        }
+        return pending;
+    }
+    featureSpecServices(featureDir) {
+        const k = key(featureDir);
+        let pending = this.featureServices.get(k);
+        if (pending === undefined) {
+            this.counts.featureServiceEnumerations += 1;
+            pending = featureSpecServices(featureDir);
+            this.featureServices.set(k, pending);
+        }
+        return pending;
+    }
+    /**
+     * A markdown artifact as text. Bytes in, decoded once, and refused rather
+     * than degraded when they are not UTF-8 — see NotUtf8DocumentError.
+     */
+    readText(path) {
+        const k = key(path);
+        let pending = this.texts.get(k);
+        if (pending === undefined) {
+            this.counts.textReads += 1;
+            pending = readFile(path).then((bytes) => decodeDocument(bytes, path));
+            this.texts.set(k, pending);
+        }
+        return pending;
+    }
+    /**
+     * Git conflict markers in an already-read document, by line. Free for any
+     * caller that was going to read the file anyway — which is every caller,
+     * which is the point: the marker check used to cost a whole extra read of one
+     * hand-picked file, so it was done for one hand-picked file.
+     */
+    async conflictMarkers(path) {
+        return conflictMarkerLines(await this.readText(path));
+    }
+    readRequirements(path) {
+        const k = key(path);
+        let pending = this.requirements.get(k);
+        if (pending === undefined) {
+            this.counts.requirementParses += 1;
+            pending = this.readText(path).then(parseRequirements);
+            this.requirements.set(k, pending);
+        }
+        return pending;
+    }
+    readOpenapi(path) {
+        const k = key(path);
+        let pending = this.openapis.get(k);
+        if (pending === undefined) {
+            this.counts.openapiParses += 1;
+            pending = readOpenapi(path);
+            this.openapis.set(k, pending);
+        }
+        return pending;
+    }
+    async operations(path) {
+        return (await this.readOpenapi(path)).ops;
+    }
+    async operationIds(path) {
+        return (await this.readOpenapi(path)).ops.map((op) => op.id);
+    }
+    /*
+     * Deliberately no `serviceOperationIds` here. The living-plus-feature union is
+     * a RULE — every removal applied before any upsert — not a read, and a second
+     * copy of a rule is a second chance to spell it differently. This one did: it
+     * interleaved removals with upserts, so a relocated operation answered
+     * "defined" through `archive` (no context) and "gone" through `validate` and
+     * `status` (context), or the reverse, depending on the order the feature's
+     * YAML happened to spell the two slots in. `core/openapi.ts` owns the rule and
+     * threads a context through the reads underneath it, which is the only part
+     * this class was ever needed for.
+     */
+    loadLikeC4(path) {
+        const k = key(path);
+        let pending = this.likec4.get(k);
+        if (pending === undefined) {
+            this.counts.likec4Loads += 1;
+            pending = loadFile(path);
+            this.likec4.set(k, pending);
+        }
+        return pending;
+    }
+}
+//# sourceMappingURL=fleet-context.js.map

package/dist/core/fleet-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-context.js","sourceRoot":"","sources":["../../src/core/fleet-context.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Request-scoped read index for commands that walk a whole loam repository.\n *\n * The filesystem remains the source of truth.  This class deliberately has no\n * singleton/global instance: a command creates one after loading loam.json and\n * drops it when that invocation finishes.  Within that lifetime identical\n * reads share their in-flight Promise, which removes both duplicate I/O and\n * duplicate parsing without making a later CLI invocation observe stale data.\n *\n * Because every markdown artifact is read HERE, this is also where the two\n * failures a read must never swallow are answered: bytes that are not UTF-8\n * (which `readFile(path, \"utf8\")` silently turns into U+FFFD, so a UTF-16\n * spec.md parses as zero requirements and grades green), and git conflict\n * markers left in a living document (which parse as prose, and which the next\n * `loam archive` rewrites away). One place, so no reader can forget. The\n * decode itself lives in `document-bytes.ts`, a leaf: the parsers that read a\n * single file without an index owe the same rule, and must not have to import\n * this module — and the fleet it pulls in behind it — to obey it.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { resolve } from \"node:path\";\nimport { decodeDocument } from \"./document-bytes.js\";\nimport { loadFile, type LoadedDoc } from \"./likec4.js\";\nimport type { Finding } from \"./report.js\";\nimport {\n  readOpenapi,\n  type OpenapiDoc,\n  type Operation,\n} from \"./openapi.js\";\nimport {\n  featureSpecServices,\n  listFeatures,\n  listServices,\n  type FeatureEntry,\n  type ServiceEntry,\n} from \"./repo.js\";\nimport { parseRequirements, type Requirement } from \"./spec.js\";\n\nexport interface FleetContextStats {\n  serviceEnumerations: number;\n  featureEnumerations: number;\n  featureServiceEnumerations: number;\n  textReads: number;\n  requirementParses: number;\n  openapiParses: number;\n  likec4Loads: number;\n}\n\nfunction key(path: string): string {\n  return resolve(path);\n}\n\n/* ------------------------------------------------------------------ */\n/* What a read must never swallow                                      */\n/* ------------------------------------------------------------------ */\n\n/**\n * The three-way merge left its markers in the file — 1-based line numbers.\n *\n * The rule is `loam doctor`'s, verbatim, and it lives here now because doctor\n * checked exactly one file (`architecture/landscape.likec4`) from a command\n * that gates nothing. The same markers in a living `services/<svc>/spec.md`\n * parse as prose: `loam validate --all` reported `valid: true`, and the next\n * `loam archive` rewrote the requirements section and dropped the `=======`\n * line with it, turning a conflict anyone can see into a document nobody can\n * tell is wrong. For a shared docs repo where a fleet lands through PRs this is\n * the DEFAULT failure, not an edge.\n */\nconst CONFLICT_MARKERS = [\"<<<<<<<\", \"=======\", \">>>>>>>\"];\n\nexport function conflictMarkerLines(source: string): number[] {\n  const out: number[] = [];\n  source.split(/\\r?\\n/).forEach((line, i) => {\n    if (CONFLICT_MARKERS.some((m) => line.startsWith(m))) out.push(i + 1);\n  });\n  return out;\n}\n\n/** One sentence for the breach, wherever it is found — doctor, validate, either axis. */\nfunction conflictMessage(label: string, lines: number[]): string {\n  return (\n    `${label} still contains git conflict markers (line${lines.length === 1 ? \"\" : \"s\"} ${lines.join(\", \")}) — ` +\n    `both sides of somebody's merge are in the file, so nothing it says is anyone's text. ` +\n    `Resolve the conflict before anything else: loam rewrites this document on archive, and a rewrite deletes ` +\n    `whichever marker lines fall inside the section it owns — a visible conflict becomes a silently malformed file.`\n  );\n}\n\n/**\n * The conflict-marker finding for a requirement document (living spec.md /\n * arch.spec.md, or a feature's delta of one). Null when the text is clean.\n *\n * An error because the document is not valid — nobody wrote what it now says —\n * and because the merge that would consume it is unsafe. It does not carry\n * `gates`: that field is coherence's (issue.ts), and the archive gate has to\n * ask this question itself.\n */\nexport function documentConflictFinding(label: string, subject: string, text: string): Finding | null {\n  const lines = conflictMarkerLines(text);\n  if (lines.length === 0) return null;\n  return {\n    severity: \"error\",\n    code: \"spec.merge-conflict\",\n    subject,\n    message: conflictMessage(label, lines),\n  };\n}\n\n/** The same breach in the fleet map, where it costs every cross-service check at once. */\nexport function landscapeConflictFinding(label: string, text: string): Finding | null {\n  const lines = conflictMarkerLines(text);\n  if (lines.length === 0) return null;\n  return {\n    severity: \"error\",\n    code: \"landscape.merge-conflict\",\n    message: conflictMessage(label, lines),\n  };\n}\n\n/** One coherent filesystem snapshot for one command invocation. */\nexport class FleetContext {\n  private readonly services = new Map<string, Promise<ServiceEntry[]>>();\n  private readonly features = new Map<string, Promise<FeatureEntry[]>>();\n  private readonly featureServices = new Map<string, Promise<string[]>>();\n  private readonly texts = new Map<string, Promise<string>>();\n  private readonly requirements = new Map<string, Promise<Requirement[]>>();\n  private readonly openapis = new Map<string, Promise<OpenapiDoc>>();\n  private readonly likec4 = new Map<string, Promise<LoadedDoc>>();\n\n  private readonly counts: FleetContextStats = {\n    serviceEnumerations: 0,\n    featureEnumerations: 0,\n    featureServiceEnumerations: 0,\n    textReads: 0,\n    requirementParses: 0,\n    openapiParses: 0,\n    likec4Loads: 0,\n  };\n\n  /** A copy suitable for diagnostics/tests; callers cannot mutate the counters. */\n  stats(): Readonly<FleetContextStats> {\n    return { ...this.counts };\n  }\n\n  listServices(docsDir: string): Promise<ServiceEntry[]> {\n    const k = key(docsDir);\n    let pending = this.services.get(k);\n    if (pending === undefined) {\n      this.counts.serviceEnumerations += 1;\n      pending = listServices(docsDir);\n      this.services.set(k, pending);\n    }\n    return pending;\n  }\n\n  listFeatures(docsDir: string, opts: { includeArchived?: boolean } = {}): Promise<FeatureEntry[]> {\n    const k = `${key(docsDir)}\\0${opts.includeArchived === true ? \"all\" : \"active\"}`;\n    let pending = this.features.get(k);\n    if (pending === undefined) {\n      this.counts.featureEnumerations += 1;\n      pending = listFeatures(docsDir, opts).then((entries) => {\n        // listFeatures has already enumerated every feature's specs/ directory;\n        // seed the narrower lookup so validation/coherence do not read it again.\n        for (const entry of entries) {\n          const featureKey = key(entry.dir);\n          if (!this.featureServices.has(featureKey)) {\n            this.featureServices.set(featureKey, Promise.resolve(entry.services));\n          }\n        }\n        return entries;\n      });\n      this.features.set(k, pending);\n    }\n    return pending;\n  }\n\n  featureSpecServices(featureDir: string): Promise<string[]> {\n    const k = key(featureDir);\n    let pending = this.featureServices.get(k);\n    if (pending === undefined) {\n      this.counts.featureServiceEnumerations += 1;\n      pending = featureSpecServices(featureDir);\n      this.featureServices.set(k, pending);\n    }\n    return pending;\n  }\n\n  /**\n   * A markdown artifact as text. Bytes in, decoded once, and refused rather\n   * than degraded when they are not UTF-8 — see NotUtf8DocumentError.\n   */\n  readText(path: string): Promise<string> {\n    const k = key(path);\n    let pending = this.texts.get(k);\n    if (pending === undefined) {\n      this.counts.textReads += 1;\n      pending = readFile(path).then((bytes) => decodeDocument(bytes, path));\n      this.texts.set(k, pending);\n    }\n    return pending;\n  }\n\n  /**\n   * Git conflict markers in an already-read document, by line. Free for any\n   * caller that was going to read the file anyway — which is every caller,\n   * which is the point: the marker check used to cost a whole extra read of one\n   * hand-picked file, so it was done for one hand-picked file.\n   */\n  async conflictMarkers(path: string): Promise<number[]> {\n    return conflictMarkerLines(await this.readText(path));\n  }\n\n  readRequirements(path: string): Promise<Requirement[]> {\n    const k = key(path);\n    let pending = this.requirements.get(k);\n    if (pending === undefined) {\n      this.counts.requirementParses += 1;\n      pending = this.readText(path).then(parseRequirements);\n      this.requirements.set(k, pending);\n    }\n    return pending;\n  }\n\n  readOpenapi(path: string): Promise<OpenapiDoc> {\n    const k = key(path);\n    let pending = this.openapis.get(k);\n    if (pending === undefined) {\n      this.counts.openapiParses += 1;\n      pending = readOpenapi(path);\n      this.openapis.set(k, pending);\n    }\n    return pending;\n  }\n\n  async operations(path: string): Promise<Operation[]> {\n    return (await this.readOpenapi(path)).ops;\n  }\n\n  async operationIds(path: string): Promise<string[]> {\n    return (await this.readOpenapi(path)).ops.map((op) => op.id);\n  }\n\n  /*\n   * Deliberately no `serviceOperationIds` here. The living-plus-feature union is\n   * a RULE — every removal applied before any upsert — not a read, and a second\n   * copy of a rule is a second chance to spell it differently. This one did: it\n   * interleaved removals with upserts, so a relocated operation answered\n   * \"defined\" through `archive` (no context) and \"gone\" through `validate` and\n   * `status` (context), or the reverse, depending on the order the feature's\n   * YAML happened to spell the two slots in. `core/openapi.ts` owns the rule and\n   * threads a context through the reads underneath it, which is the only part\n   * this class was ever needed for.\n   */\n\n  loadLikeC4(path: string): Promise<LoadedDoc> {\n    const k = key(path);\n    let pending = this.likec4.get(k);\n    if (pending === undefined) {\n      this.counts.likec4Loads += 1;\n      pending = loadFile(path);\n      this.likec4.set(k, pending);\n    }\n    return pending;\n  }\n}\n"]}

package/dist/core/frontmatter.js

@@ -0,0 +1,199 @@
+/**
+ * YAML frontmatter — the provenance of an artifact.
+ *
+ * `status` says whether a human has vouched for the document, `sources` says
+ * which code it was written from. When the prose is written by an agent, these
+ * are the only deterministic tie to reality: everything else loam checks is
+ * internal consistency, which a fluent enough fiction satisfies perfectly.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { isMap, parse, parseDocument } from "yaml";
+import { decodeDocument, NotUtf8DocumentError } from "./document-bytes.js";
+/**
+ * Drop a leading byte-order mark.
+ *
+ * With one in front, the opening `---` is no longer at position 0, so the whole
+ * header reads as absent: a documented artifact silently becomes an
+ * undocumented one — no owner, no status, no `sources` — and nothing says why.
+ * The same blindness `spec.ts` had at `^##`.
+ *
+ * Only at position 0: elsewhere U+FEFF is a zero-width no-break space and is the
+ * author's content. Callers strip before measuring, so the offsets `bounds`
+ * returns index the same string the caller then slices.
+ */
+function stripBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+/**
+ * A fence is a LINE of exactly three dashes. Trailing whitespace is tolerated
+ * (`\s` also swallows the CR of a CRLF file), trailing text is not: `--- title`
+ * is prose, `----` is a horizontal rule. Matching the substring `---` instead —
+ * as this used to — made both of those fences, so a stray rule closed the
+ * header early and a `--- note` closer silently ate its own trailing text.
+ */
+const FENCE_RE = /^---\s*$/;
+/**
+ * Locate the frontmatter block. The opener is the very first line, the closer
+ * the first subsequent fence line — a later horizontal rule is body, not a
+ * second fence. No closer means an unterminated opener: not frontmatter at all.
+ *
+ * The reader and the writer both go through this, so they can never disagree
+ * about which bytes are the header — the writer's promise to leave the body
+ * untouched depends on that being one decision, not two.
+ */
+function bounds(md) {
+    const firstNl = md.indexOf("\n");
+    if (!FENCE_RE.test(firstNl === -1 ? md : md.slice(0, firstNl)))
+        return null;
+    // A lone `---` with nothing after it is an unterminated opener.
+    if (firstNl === -1)
+        return null;
+    const start = firstNl + 1;
+    for (let lineStart = start;;) {
+        const nl = md.indexOf("\n", lineStart);
+        const line = nl === -1 ? md.slice(lineStart) : md.slice(lineStart, nl);
+        if (FENCE_RE.test(line)) {
+            // An empty block (`---\n---`) has no text between the fences: start === end.
+            return { start, end: lineStart, bodyStart: nl === -1 ? md.length : nl + 1 };
+        }
+        if (nl === -1)
+            return null;
+        lineStart = nl + 1;
+    }
+}
+/**
+ * Split a markdown document into its frontmatter and body. A document with no
+ * frontmatter is returned whole rather than truncated.
+ */
+export function parseFrontmatter(source) {
+    const md = stripBom(source);
+    const at = bounds(md);
+    if (at === null)
+        return { present: false, malformed: false, data: {}, body: md };
+    const yamlText = md.slice(at.start, at.end);
+    const body = md.slice(at.bodyStart).trimStart();
+    let data = {};
+    let malformed = false;
+    try {
+        const parsed = parse(yamlText);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            data = parsed;
+        }
+        else if (parsed !== null) {
+            // A scalar or sequence header holds no fields to read — as unreadable as
+            // broken YAML. null is the empty block (`---\n---`): legal, and empty.
+            malformed = true;
+        }
+    }
+    catch {
+        // A bad header must not make the document unreadable (the body is still the
+        // body, and never crashes a command) — but the failure travels as a flag,
+        // so the caller can say `frontmatter.malformed` instead of the false
+        // cascade "owner/status missing" the silent {} used to produce.
+        malformed = true;
+    }
+    return { present: true, malformed, data, body };
+}
+/** A field as text. Non-string scalars (a bare date, a number) are stringified. */
+export function stringField(fm, key) {
+    const v = fm.data[key];
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v === "string")
+        return v;
+    if (typeof v === "number" || typeof v === "boolean")
+        return String(v);
+    if (v instanceof Date)
+        return v.toISOString().slice(0, 10);
+    return undefined;
+}
+/** A field as a list. A lone scalar counts as a list of one. */
+export function listField(fm, key) {
+    const v = fm.data[key];
+    if (v === undefined || v === null)
+        return [];
+    if (Array.isArray(v))
+        return v.map((x) => String(x)).filter((s) => s.length > 0);
+    const one = stringField(fm, key);
+    return one === undefined ? [] : [one];
+}
+/**
+ * Return `md` with these frontmatter fields set and everything below the closing
+ * fence byte-identical.
+ *
+ * The header is edited through yaml's document model rather than rebuilt from
+ * the parsed data: keys keep their order and their comments, fields nobody named
+ * are left exactly as they were, and a value that would read back as something
+ * else — a digest of all digits, say — gets quoted for us. Stamping a document
+ * is not a licence to reformat it: the diff a reviewer sees should be the lines
+ * that changed, and nothing else.
+ *
+ * A document with no frontmatter gets one, and the text that was there becomes
+ * the body. A header that does not parse (or is not a mapping) is replaced
+ * rather than merged into — it cannot be edited without guessing what it meant.
+ */
+export function withFrontmatterFields(source, fields) {
+    // Stamping a BOM-prefixed document drops the BOM. It sits above the header, so
+    // the promise about the body still holds — and leaving it would re-break the
+    // file for every parser anchored at position 0, including ours.
+    const md = stripBom(source);
+    const at = bounds(md);
+    const parsed = parseDocument(at === null ? "" : md.slice(at.start, at.end));
+    const editable = parsed.errors.length === 0 && (parsed.contents === null || isMap(parsed.contents));
+    const doc = editable ? parsed : parseDocument("");
+    for (const [key, value] of Object.entries(fields))
+        doc.set(key, value);
+    const yamlText = doc.toString();
+    if (at === null)
+        return `---\n${yamlText}---\n\n${md}`;
+    return md.slice(0, at.start) + yamlText + md.slice(at.end);
+}
+/**
+ * The document's body, byte-exact: everything after the frontmatter block —
+ * the closing `---` line and its newline belong to the HEADER, every byte
+ * after them (blank lines included) is body. A document with no frontmatter is
+ * all body. This is what `content_digest` hashes, and it deliberately does NOT
+ * go through `parseFrontmatter` (whose `body` is trimmed for callers that want
+ * text): the digest's writer and its checker must slice the same bytes, so
+ * both go through here.
+ */
+export function rawBody(source) {
+    const md = stripBom(source);
+    const at = bounds(md);
+    return at === null ? md : md.slice(at.bodyStart);
+}
+/**
+ * Read a markdown file's frontmatter; a missing file reads as absent.
+ *
+ * Bytes in, decoded through `decodeDocument`, because `readFile(path, "utf8")`
+ * turns a UTF-16 spec.md into mojibake whose opening `---` is no longer at
+ * position 0 — so the header reads as ABSENT, and `status`, `owner` and
+ * `sources` all come back missing over a file that spells every one of them.
+ * The same blindness `stripBom` exists to stop, one encoding wider.
+ *
+ * The failure travels as a FLAG rather than an exception, which is how every
+ * reader here degrades (`readOpenapi`'s `unreadable`) and is load-bearing at
+ * exactly this call: this is the read behind the fleet ENUMERATION
+ * (repo.ts `listServices`), so throwing would turn one PowerShell-saved file
+ * into a `loam list` that reports nothing about the other 119 services.
+ * Parsers never diagnose; a checker grades the flag.
+ */
+export async function readFrontmatter(path) {
+    if (!existsSync(path))
+        return { present: false, malformed: false, data: {}, body: "" };
+    let text;
+    try {
+        text = decodeDocument(await readFile(path), path);
+    }
+    catch (err) {
+        if (!(err instanceof NotUtf8DocumentError))
+            throw err;
+        return { present: false, malformed: false, unreadable: err.message, data: {}, body: "" };
+    }
+    return parseFrontmatter(text);
+}
+/** The statuses each kind of artifact may carry. */
+export const SERVICE_STATUSES = ["draft", "verified"];
+export const FEATURE_STATUSES = ["proposed", "in_progress", "built", "done"];
+//# sourceMappingURL=frontmatter.js.map

package/dist/core/frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../src/core/frontmatter.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * YAML frontmatter — the provenance of an artifact.\n *\n * `status` says whether a human has vouched for the document, `sources` says\n * which code it was written from. When the prose is written by an agent, these\n * are the only deterministic tie to reality: everything else loam checks is\n * internal consistency, which a fluent enough fiction satisfies perfectly.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { isMap, parse, parseDocument } from \"yaml\";\nimport { decodeDocument, NotUtf8DocumentError } from \"./document-bytes.js\";\n\nexport interface Frontmatter {\n  /** True when a terminated `---` block was found, even if it was empty. */\n  present: boolean;\n  /**\n   * True when the block was found but its YAML cannot be read as a mapping —\n   * a parse error, or a scalar/sequence document. `data` is then {}, which is\n   * NOT the same fact as an empty header: the fields are unreadable, not\n   * absent, and a checker that grades them \"missing\" sends the author adding\n   * lines to a block YAML refuses to parse. Validate turns this flag into\n   * `frontmatter.malformed`; the writer (withFrontmatterFields) has its own\n   * replace-don't-merge rule for the same state.\n   */\n  malformed: boolean;\n  /**\n   * Why the FILE could not be read as text at all, or absent when it could —\n   * set only by `readFrontmatter`, since a caller that already holds a string\n   * has nothing left to decode.\n   *\n   * A third state, not a shade of the other two: `present: false` here means\n   * nobody could look, where everywhere else it means nobody wrote a header.\n   * A checker must ask this first, or it reports \"owner/status/sources missing\"\n   * over a file whose lines are right there — the same false cascade\n   * `malformed` exists to stop, one layer lower down.\n   */\n  unreadable?: string;\n  /** The parsed mapping, or {} when absent or malformed. */\n  data: Record<string, unknown>;\n  /** The document with the frontmatter removed. */\n  body: string;\n}\n\n/** Where the header sits in the raw text. */\ninterface Bounds {\n  /** First character of the YAML text. */\n  start: number;\n  /** One past its last character — the newline before the closing fence included. */\n  end: number;\n  /** First character of the body. */\n  bodyStart: number;\n}\n\n/**\n * Drop a leading byte-order mark.\n *\n * With one in front, the opening `---` is no longer at position 0, so the whole\n * header reads as absent: a documented artifact silently becomes an\n * undocumented one — no owner, no status, no `sources` — and nothing says why.\n * The same blindness `spec.ts` had at `^##`.\n *\n * Only at position 0: elsewhere U+FEFF is a zero-width no-break space and is the\n * author's content. Callers strip before measuring, so the offsets `bounds`\n * returns index the same string the caller then slices.\n */\nfunction stripBom(text: string): string {\n  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;\n}\n\n/**\n * A fence is a LINE of exactly three dashes. Trailing whitespace is tolerated\n * (`\\s` also swallows the CR of a CRLF file), trailing text is not: `--- title`\n * is prose, `----` is a horizontal rule. Matching the substring `---` instead —\n * as this used to — made both of those fences, so a stray rule closed the\n * header early and a `--- note` closer silently ate its own trailing text.\n */\nconst FENCE_RE = /^---\\s*$/;\n\n/**\n * Locate the frontmatter block. The opener is the very first line, the closer\n * the first subsequent fence line — a later horizontal rule is body, not a\n * second fence. No closer means an unterminated opener: not frontmatter at all.\n *\n * The reader and the writer both go through this, so they can never disagree\n * about which bytes are the header — the writer's promise to leave the body\n * untouched depends on that being one decision, not two.\n */\nfunction bounds(md: string): Bounds | null {\n  const firstNl = md.indexOf(\"\\n\");\n  if (!FENCE_RE.test(firstNl === -1 ? md : md.slice(0, firstNl))) return null;\n  // A lone `---` with nothing after it is an unterminated opener.\n  if (firstNl === -1) return null;\n  const start = firstNl + 1;\n  for (let lineStart = start; ; ) {\n    const nl = md.indexOf(\"\\n\", lineStart);\n    const line = nl === -1 ? md.slice(lineStart) : md.slice(lineStart, nl);\n    if (FENCE_RE.test(line)) {\n      // An empty block (`---\\n---`) has no text between the fences: start === end.\n      return { start, end: lineStart, bodyStart: nl === -1 ? md.length : nl + 1 };\n    }\n    if (nl === -1) return null;\n    lineStart = nl + 1;\n  }\n}\n\n/**\n * Split a markdown document into its frontmatter and body. A document with no\n * frontmatter is returned whole rather than truncated.\n */\nexport function parseFrontmatter(source: string): Frontmatter {\n  const md = stripBom(source);\n  const at = bounds(md);\n  if (at === null) return { present: false, malformed: false, data: {}, body: md };\n\n  const yamlText = md.slice(at.start, at.end);\n  const body = md.slice(at.bodyStart).trimStart();\n\n  let data: Record<string, unknown> = {};\n  let malformed = false;\n  try {\n    const parsed: unknown = parse(yamlText);\n    if (parsed && typeof parsed === \"object\" && !Array.isArray(parsed)) {\n      data = parsed as Record<string, unknown>;\n    } else if (parsed !== null) {\n      // A scalar or sequence header holds no fields to read — as unreadable as\n      // broken YAML. null is the empty block (`---\\n---`): legal, and empty.\n      malformed = true;\n    }\n  } catch {\n    // A bad header must not make the document unreadable (the body is still the\n    // body, and never crashes a command) — but the failure travels as a flag,\n    // so the caller can say `frontmatter.malformed` instead of the false\n    // cascade \"owner/status missing\" the silent {} used to produce.\n    malformed = true;\n  }\n  return { present: true, malformed, data, body };\n}\n\n/** A field as text. Non-string scalars (a bare date, a number) are stringified. */\nexport function stringField(fm: Frontmatter, key: string): string | undefined {\n  const v = fm.data[key];\n  if (v === undefined || v === null) return undefined;\n  if (typeof v === \"string\") return v;\n  if (typeof v === \"number\" || typeof v === \"boolean\") return String(v);\n  if (v instanceof Date) return v.toISOString().slice(0, 10);\n  return undefined;\n}\n\n/** A field as a list. A lone scalar counts as a list of one. */\nexport function listField(fm: Frontmatter, key: string): string[] {\n  const v = fm.data[key];\n  if (v === undefined || v === null) return [];\n  if (Array.isArray(v)) return v.map((x) => String(x)).filter((s) => s.length > 0);\n  const one = stringField(fm, key);\n  return one === undefined ? [] : [one];\n}\n\n/**\n * Return `md` with these frontmatter fields set and everything below the closing\n * fence byte-identical.\n *\n * The header is edited through yaml's document model rather than rebuilt from\n * the parsed data: keys keep their order and their comments, fields nobody named\n * are left exactly as they were, and a value that would read back as something\n * else — a digest of all digits, say — gets quoted for us. Stamping a document\n * is not a licence to reformat it: the diff a reviewer sees should be the lines\n * that changed, and nothing else.\n *\n * A document with no frontmatter gets one, and the text that was there becomes\n * the body. A header that does not parse (or is not a mapping) is replaced\n * rather than merged into — it cannot be edited without guessing what it meant.\n */\nexport function withFrontmatterFields(source: string, fields: Record<string, string>): string {\n  // Stamping a BOM-prefixed document drops the BOM. It sits above the header, so\n  // the promise about the body still holds — and leaving it would re-break the\n  // file for every parser anchored at position 0, including ours.\n  const md = stripBom(source);\n  const at = bounds(md);\n  const parsed = parseDocument(at === null ? \"\" : md.slice(at.start, at.end));\n  const editable = parsed.errors.length === 0 && (parsed.contents === null || isMap(parsed.contents));\n  const doc = editable ? parsed : parseDocument(\"\");\n\n  for (const [key, value] of Object.entries(fields)) doc.set(key, value);\n  const yamlText = doc.toString();\n\n  if (at === null) return `---\\n${yamlText}---\\n\\n${md}`;\n  return md.slice(0, at.start) + yamlText + md.slice(at.end);\n}\n\n/**\n * The document's body, byte-exact: everything after the frontmatter block —\n * the closing `---` line and its newline belong to the HEADER, every byte\n * after them (blank lines included) is body. A document with no frontmatter is\n * all body. This is what `content_digest` hashes, and it deliberately does NOT\n * go through `parseFrontmatter` (whose `body` is trimmed for callers that want\n * text): the digest's writer and its checker must slice the same bytes, so\n * both go through here.\n */\nexport function rawBody(source: string): string {\n  const md = stripBom(source);\n  const at = bounds(md);\n  return at === null ? md : md.slice(at.bodyStart);\n}\n\n/**\n * Read a markdown file's frontmatter; a missing file reads as absent.\n *\n * Bytes in, decoded through `decodeDocument`, because `readFile(path, \"utf8\")`\n * turns a UTF-16 spec.md into mojibake whose opening `---` is no longer at\n * position 0 — so the header reads as ABSENT, and `status`, `owner` and\n * `sources` all come back missing over a file that spells every one of them.\n * The same blindness `stripBom` exists to stop, one encoding wider.\n *\n * The failure travels as a FLAG rather than an exception, which is how every\n * reader here degrades (`readOpenapi`'s `unreadable`) and is load-bearing at\n * exactly this call: this is the read behind the fleet ENUMERATION\n * (repo.ts `listServices`), so throwing would turn one PowerShell-saved file\n * into a `loam list` that reports nothing about the other 119 services.\n * Parsers never diagnose; a checker grades the flag.\n */\nexport async function readFrontmatter(path: string): Promise<Frontmatter> {\n  if (!existsSync(path)) return { present: false, malformed: false, data: {}, body: \"\" };\n  let text: string;\n  try {\n    text = decodeDocument(await readFile(path), path);\n  } catch (err) {\n    if (!(err instanceof NotUtf8DocumentError)) throw err;\n    return { present: false, malformed: false, unreadable: err.message, data: {}, body: \"\" };\n  }\n  return parseFrontmatter(text);\n}\n\n/** The statuses each kind of artifact may carry. */\nexport const SERVICE_STATUSES = [\"draft\", \"verified\"] as const;\nexport const FEATURE_STATUSES = [\"proposed\", \"in_progress\", \"built\", \"done\"] as const;\n"]}