@glw907/cairn-cms 0.68.0 → 0.76.0

package/src/lib/content/media-rewrite.ts

@@ -25,6 +25,13 @@ import type { Image, Root } from 'mdast';
 import type { ContainerDirective } from 'mdast-util-directive';
 import { parseMediaToken } from '../media/reference.js';
 import { escapeLinkText } from './links.js';
+import {
+  type FmLine,
+  splitFrontmatter,
+  fmLines,
+  frontmatterKeyRange,
+  escapeForRegExp,
+} from './frontmatter-region.js';
 
 /** One repointed reference: which surface it lived on, the old token as written, and the new token. */
 export interface RepointPlacement {
@@ -73,18 +80,6 @@ function dropOverlappingEdits<T extends { start: number; end: number }>(edits: T
  */
 const MEDIA_TOKEN_SCAN = /media:[A-Za-z0-9._-]+/g;
 
-/**
- * Split a leading frontmatter block off the markdown. `fmBlock` is the `---` fenced block including
- *  both fences and the trailing newline (empty when there is none); `body` is everything after it.
- *  The block leads the document, so a frontmatter offset is already absolute and a body offset needs
- *  `fmBlock.length` added. Shared by every arm so they agree on the boundary.
- */
-function splitFrontmatter(markdown: string): { fmBlock: string; body: string } {
-  const m = markdown.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
-  const fmBlock = m ? m[0] : '';
-  return { fmBlock, body: markdown.slice(fmBlock.length) };
-}
-
 /**
  * Parse a doc with the figure-aware pipeline, so the body arm agrees with what remarkFigure renders
  *  and can see the enclosing `:::figure` container. Mirrors parseFigureDoc in markdown-format.ts.
@@ -109,66 +104,6 @@ function inFigure(tree: Root, target: Image): boolean {
   return found;
 }
 
-/**
- * The split of fmBlock into its lines, each with its block-relative start and end offsets (the end
- *  is the index of the trailing newline, or the block length for the last line). Block offsets are
- *  already absolute since the frontmatter leads the document.
- */
-interface FmLine {
-  start: number;
-  end: number;
-}
-
-/**
- * Split fmBlock into lines once, so the locator helpers walk a shared structure instead of
- *  re-scanning the block per call.
- */
-function fmLines(fmBlock: string): FmLine[] {
-  const lines: FmLine[] = [];
-  let pos = 0;
-  while (pos <= fmBlock.length) {
-    const nl = fmBlock.indexOf('\n', pos);
-    const end = nl === -1 ? fmBlock.length : nl;
-    lines.push({ start: pos, end });
-    if (nl === -1) break;
-    pos = nl + 1;
-  }
-  return lines;
-}
-
-/**
- * The inclusive line-index range `[lo, hi]` of the block-style mapping a top-level key opens: the
- *  line `^<key>:` at indent 0 through the last line before the next top-level key (or the document
- *  end). A flow-style value (`key: { ... }` all on one line) yields a single-line range. Returns null
- *  when the key has no top-level line, which a malformed or non-canonical block can cause. Scoping the
- *  per-key search to this range is what lets two image fields that share one hash, or an image field
- *  whose hash also appears in a sibling text value, resolve to distinct, correct spans.
- */
-function frontmatterKeyRange(lines: FmLine[], fmBlock: string, key: string): [number, number] | null {
-  const opener = new RegExp(`^${escapeForRegExp(key)}:`);
-  const topLevelKey = /^[^\s#][^:]*:/;
-  const isBoundary = (i: number) => {
-    const text = fmBlock.slice(lines[i].start, lines[i].end);
-    // A new top-level key or the closing `---` fence ends the current key's block.
-    return topLevelKey.test(text) || text === '---';
-  };
-  let lo = -1;
-  for (let i = 1; i < lines.length - 1; i += 1) {
-    // Skip the leading `---` fence (line 0) and the trailing empty line after the closing fence.
-    if (opener.test(fmBlock.slice(lines[i].start, lines[i].end))) {
-      lo = i;
-      break;
-    }
-  }
-  if (lo === -1) return null;
-  let hi = lo;
-  for (let i = lo + 1; i < lines.length - 1; i += 1) {
-    if (isBoundary(i)) break;
-    hi = i;
-  }
-  return [lo, hi];
-}
-
 /**
  * A located `src:` line inside a block-style mapping: the line's start and end, its leading indent,
  *  and the exact `media:` token's block-relative offsets and text.
@@ -470,14 +405,6 @@ function bodyAltEdits(body: string, blockLength: number, hash: string, defaultAl
   return edits;
 }
 
-/**
- * Escape a literal string for safe interpolation into a RegExp source. A key name or an indent is
- *  matched literally, so its characters must not act as metacharacters.
- */
-function escapeForRegExp(literal: string): string {
-  return literal.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
 /**
  * Find a sibling key line (`alt:` or `decorative:`) at exactly `indent` within the inclusive
  *  line-index range `[lo, hi]` of one mapping. The range is the mapping's own block, so the search

package/src/lib/content/reference-index.ts

@@ -0,0 +1,159 @@
+// cairn-cms: the cross-branch reference index, the where-referenced core of the rename and delete
+// gates. It answers "which entries reference this target entry" for every reference edge, keyed by the
+// target's (concept, id) PAIR. The key is the pair and never an id alone (unlike media/usage.ts, which
+// keys on a globally-unique content hash), because an id is unique only within a concept: pages/about
+// and posts/about are distinct targets, and reverse-mapping by id alone would cross that boundary and
+// refuse a rename or delete on a phantom inbound. The map unions two sources: the published corpus on
+// main and every open cairn/* edit branch, so a target referenced only in an unpublished draft still
+// counts as referenced and is not mistaken for safe to delete or freely rename.
+//
+// The main arm reads the content manifest's per-entry references (the edges manifestEntryFromFile
+// records) and builds the reverse map; it never crawls the files, since the manifest already carries
+// the edges. The branch arm cannot use a manifest (the content manifest is never committed to a
+// branch), so it reconstructs each edited entry's path from the branch name, reads that one file, and
+// runs the schema extractor directly.
+import type { ConceptDescriptor } from './types.js';
+import type { Backend } from '../github/backend.js';
+import type { Manifest } from './manifest.js';
+import { PENDING_PREFIX, parsePendingBranch } from './pending.js';
+import { findConcept } from './concepts.js';
+import { isValidId, filenameFromId } from './ids.js';
+import { parseMarkdown } from './frontmatter.js';
+import { extractReferenceEdges } from './references.js';
+
+/**
+ * Where a reference lives: the published corpus on main, or a named open edit branch. Re-declared here
+ *  (rather than imported from media/usage.ts) so the content layer does not depend on the media layer.
+ */
+export type UsageOrigin = { kind: 'published' } | { kind: 'branch'; branch: string };
+
+/** One entry that references a target, in a shape the rename and delete gates name and group by. */
+export interface ReferenceUsageEntry {
+  /** The referencing (source) entry's concept id, e.g. "posts". */
+  concept: string;
+  /** The referencing (source) entry's id (its filename stem). */
+  id: string;
+  /** The referencing entry's title for display, from the manifest (published) or frontmatter (branch). */
+  title: string;
+  /** The referencing entry's public permalink, present for a published entry (carried from the manifest). */
+  permalink?: string;
+  /** The frontmatter field the edge was declared on. */
+  field: string;
+  /** Published vs the cairn/* branch the edit lives on. */
+  origin: UsageOrigin;
+}
+
+/**
+ * The target's `${concept}/${id}` pair to the distinct entries that reference it. A pair with no row is
+ *  not referenced anywhere the index could read (main plus the listed open branches).
+ */
+export type ReferenceIndex = Map<string, ReferenceUsageEntry[]>;
+
+/**
+ * Build options. `branches` lets a caller that already listed the open cairn/* branches pass them in so
+ *  the index does not list them a second time. `strict` flips the per-branch read from degrade-and-skip
+ *  to fail-closed: a delete or rename gate must not treat a transient branch-read failure as an absent
+ *  reference, so it rethrows instead.
+ */
+export interface BuildReferenceOptions {
+  /** The open cairn/* branch names, already listed. When present the index skips its own listing. */
+  branches?: string[];
+  /** When true a branch read that throws rejects the whole build, so the caller can fail closed. */
+  strict?: boolean;
+}
+
+/** Append a row under its target pair key, creating the bucket on first use. */
+function push(index: ReferenceIndex, key: string, entry: ReferenceUsageEntry): void {
+  const rows = index.get(key);
+  if (rows) rows.push(entry);
+  else index.set(key, [entry]);
+}
+
+/**
+ * Build the pair-keyed reference index over main (from the manifest's per-entry references) plus every
+ * open cairn/* branch (parsed from its edited markdown).
+ *
+ * By default a single branch read that throws degrades that one branch and is skipped, the way the
+ * admin loaders degrade a failed read. That tolerance is wrong for the rename and delete gates: a
+ * transient branch-read failure would make a still-referenced target look free. Pass `strict: true` to
+ * rethrow a branch failure so the caller fails closed. Pass `branches` to reuse a branch list the
+ * caller already has rather than listing them a second time.
+ */
+export async function buildReferenceIndex(
+  backend: Backend,
+  concepts: ConceptDescriptor[],
+  manifest: Manifest,
+  opts: BuildReferenceOptions = {},
+): Promise<ReferenceIndex> {
+  const index: ReferenceIndex = new Map();
+
+  // The main arm: the manifest already carries each entry's reference edges, so this is a pure reverse
+  // map with no per-file read. The KEY is the edge's TARGET (concept, id); the ROW is the source entry.
+  for (const entry of manifest.entries) {
+    for (const edge of entry.references ?? []) {
+      push(index, `${edge.concept}/${edge.id}`, {
+        concept: entry.concept,
+        id: entry.id,
+        title: entry.title,
+        permalink: entry.permalink,
+        field: edge.field,
+        origin: { kind: 'published' },
+      });
+    }
+  }
+
+  // The branch arm: read each open cairn/* branch's one edited file. The path is derivable from the
+  // branch name, so no tree-listing is needed. The branch list is reused when the caller passes it.
+  const names = opts.branches ?? (await backend.listBranches(PENDING_PREFIX));
+  // Read the branches in parallel rather than one at a time, so the latency floor is one round trip
+  // instead of N. workerd self-throttles to 6 simultaneous outbound connections, so this batch and
+  // the load path's media-union and linker reads each stay under the limit; do NOT run this fan-out
+  // concurrently with those (a future combined safety gate must not wrap them in one Promise.all),
+  // since the merged fan-out would queue behind that throttle.
+  const perBranch = await Promise.all(
+    names.map(async (name): Promise<{ key: string; entry: ReferenceUsageEntry }[]> => {
+      // Resolve the branch name to a configured entry with the same guard the branch tooling uses: a
+      // malformed name, an id that fails the slug rule (entry paths are built from it, so this is the
+      // path confinement), or a concept this site does not configure is skipped, no read attempted.
+      const ref = parsePendingBranch(name);
+      if (!ref || !isValidId(ref.id)) return [];
+      const concept = findConcept(concepts, ref.concept);
+      if (!concept) return [];
+
+      const path = `${concept.dir}/${filenameFromId(ref.id)}`;
+      try {
+        const raw = await backend.readFile(path, name);
+        if (raw === null) return []; // The file is absent on the branch: nothing to extract.
+        const { frontmatter } = parseMarkdown(raw);
+        const fmTitle = frontmatter.title;
+        const title = typeof fmTitle === 'string' && fmTitle.trim() ? fmTitle : ref.id;
+        const rows: { key: string; entry: ReferenceUsageEntry }[] = [];
+        for (const edge of extractReferenceEdges(frontmatter, concept.fields)) {
+          rows.push({
+            key: `${edge.concept}/${edge.id}`,
+            entry: {
+              concept: concept.id,
+              id: ref.id,
+              title,
+              field: edge.field,
+              origin: { kind: 'branch', branch: name },
+            },
+          });
+        }
+        return rows;
+      } catch (err) {
+        // In strict mode a branch failure fails the whole build so the gate can fail closed; otherwise
+        // degrade this one branch rather than sinking the screen.
+        if (opts.strict) throw err;
+        return [];
+      }
+    }),
+  );
+
+  // Fold the per-branch rows back in, preserving the branch order so the index reads stably.
+  for (const rows of perBranch) {
+    for (const { key, entry } of rows) push(index, key, entry);
+  }
+
+  return index;
+}

package/src/lib/content/standard-schema.ts

@@ -0,0 +1,25 @@
+// cairn-cms: the Standard Schema conformance types, shared by both the v1 schema and the v2
+// fieldset validators. They live here, apart from either validator, so the v2 `fieldset` keeps
+// importing them once the v1 `schema.ts` is removed at the Contract v2 cutover.
+
+/** The validate input the cairn adapter takes: the raw frontmatter and the body. */
+export interface StandardInput {
+  frontmatter: Record<string, unknown>;
+  body: string;
+}
+
+/**
+ * A minimal local copy of the Standard Schema v1 interface (https://standardschema.dev), so the
+ *  schema is a drop-in where the ecosystem accepts a validator, with no runtime dependency.
+ */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly '~standard': {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => StandardResult<Output>;
+    readonly types?: { readonly input: Input; readonly output: Output };
+  };
+}
+type StandardResult<Output> =
+  | { readonly value: Output; readonly issues?: undefined }
+  | { readonly issues: ReadonlyArray<{ readonly message: string; readonly path?: ReadonlyArray<PropertyKey> }> };