canopycms 0.0.67-int.90 → 0.0.67

package/dist/content-listing.js

@@ -1,7 +1,5 @@
 /**
  * Shared content-listing utilities used by both the entries API and the content tree builder.
- *
- * Extracted from api/entries.ts to avoid duplication.
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
@@ -17,10 +15,7 @@ import { createDebugLogger } from './utils/debug.js';
 import { ContentStore, ContentStoreError, createReferenceResolveCache, } from './content-store.js';
 import { isBuildMode } from './build-mode.js';
 const log = createDebugLogger({ prefix: 'ContentListing' });
-/**
- * Validate and normalize a path relative to root.
- * Throws ContentStoreError on traversal attempt.
- */
+/** Validate and normalize `target` under `root`; throws ContentStoreError on a traversal. */
 const normalizePath = (root, target) => {
     const result = validateAndNormalizePath(root, target);
     if (!result.valid) {
@@ -29,13 +24,11 @@ const normalizePath = (root, target) => {
     return result.normalizedPath;
 };
 /**
- * Read entry data from a file.
- * For md/mdx: returns frontmatter fields plus the body content (mapped to the
- * field name specified by `bodyFieldName`, which defaults to `'body'`).
- * For json: returns the parsed JSON object.
- * Returns an empty object on read/parse failure.
+ * Read entry data from a file. For md/mdx: frontmatter fields plus the body content under
+ * `bodyFieldName` (defaults to `'body'`); for json/yaml, the parsed object. Returns an empty
+ * object on read/parse failure.
  */
-export const readEntryData = async (filePath, format, bodyFieldName = 'body') => {
+const readEntryData = async (filePath, format, bodyFieldName = 'body') => {
     try {
         const raw = await fs.readFile(filePath, 'utf8');
         if (format === 'json') {
@@ -51,13 +44,10 @@ export const readEntryData = async (filePath, format, bodyFieldName = 'body') =>
         // Copy before writing the body in. gray-matter keeps a PROCESS-GLOBAL cache keyed by file
         // content and hands every caller the same `data` object instance, so mutating it in place
         // wrote the body into a shared object that later, unrelated `matter()` calls then saw as
-        // frontmatter. Concretely, before this copy: listing a collection that contains an md entry
-        // poisoned the cache, and a subsequent reference resolution to that same entry — which goes
-        // through `ContentStore.read()`, whose md branch calls `matter()` again — returned the body
-        // as a frontmatter field. So a resolved md snippet came back WITH `body` on a whole-site
-        // listing and WITHOUT it on one scoped past its own collection: the same entry, two shapes,
-        // decided by unrelated scoping. Regression coverage lives with the reference-resolution
-        // tests in content-listing.test.ts.
+        // frontmatter: listing a collection containing an md entry poisoned the cache, and a
+        // reference resolution to that same entry (through `ContentStore.read()`, whose md branch
+        // calls `matter()` again) returned the body as a frontmatter field -- one entry with two
+        // shapes, decided by unrelated listing scope.
         const data = { ...(parsed.data ?? {}) };
         if (parsed.content) {
             data[bodyFieldName] = parsed.content;
@@ -71,30 +61,25 @@ export const readEntryData = async (filePath, format, bodyFieldName = 'body') =>
         return {};
     }
 };
-// `parseTypedFilename` now lives in utils/typed-filename.ts so dependency-light modules can
-// use it without importing this one (which pulls in ContentStore). Re-exported here because
-// this is where callers -- and `canopycms/server` -- have always imported it from.
+// `parseTypedFilename` lives in utils/typed-filename.ts so dependency-light modules can use it
+// without importing this one (which pulls in ContentStore). Re-exported here because callers --
+// and `canopycms/server` -- import it from here.
 export { parseTypedFilename } from './utils/typed-filename.js';
 import { parseTypedFilename } from './utils/typed-filename.js';
-// ---------------------------------------------------------------------------
-// Reference resolution for batch listings
-// ---------------------------------------------------------------------------
 /**
  * Build the `ContentStore` + shared cache that a batch listing resolves references through.
  *
  * Unrelated to the `ReferenceResolver` class in reference-resolver.ts despite the adjacent
- * name — that one resolves an id to a human-readable *display label* for the editor UI. This
- * resolves a reference to the referenced entry's *data* for server-side listings.
+ * name — that one resolves an id to a human-readable display label for the editor UI.
  *
- * Constructed lazily by each listing surface, and ONLY when the caller opted in — a store
+ * Constructed lazily by each listing surface, and ONLY when the caller opted in: a store
  * builds a ContentId index on first use, which is a full scan of the content tree, and the
  * default (`resolveReferences` off) must stay a pure filesystem walk with no index at all.
  *
- * One store and one cache per listing call, not per collection: the cache is the reason a
+ * One store and one cache per listing CALL, not per collection: the cache is the reason a
  * shared block referenced from 40 pages costs one read instead of 40, so it has to span the
- * whole batch. Per-call construction is the established shape here — content-reader.ts's
- * `resolveStore` builds a store per read, and content-index-registry.ts holds stores through
- * `WeakRef` + a `FinalizationRegistry` precisely so short-lived instances stay collectable.
+ * whole batch. content-index-registry.ts holds stores through `WeakRef` + a
+ * `FinalizationRegistry`, so these short-lived instances stay collectable.
  */
 export const createReferenceResolver = (branchRoot, flatSchema, contentRootName) => ({
     store: new ContentStore(branchRoot, flatSchema, { contentRootName }),
@@ -118,46 +103,33 @@ export const resolveCollectionItemReferences = async (items, collection, resolve
     };
 }));
 /**
- * List all content entries as a flat array.
+ * List all content entries as a flat array: walks the schema to discover collections, reads
+ * entries from each, and returns a flat list suitable for generateStaticParams, search
+ * indexing, sitemaps, etc.
  *
- * Walks the schema to discover collections, reads entries from each,
- * and returns a flat list suitable for generateStaticParams, search indexing, sitemaps, etc.
+ * Build-time-only failure: a file with a recognized content extension sitting in a collection
+ * directory that *looks like an attempted entry* (see `looksLikeMalformedEntry`) but does not
+ * match `{type}.{slug}.{id}.{ext}` is silently dropped by default. That is exactly the
+ * silent-page-loss static generation must not have -- a schema rename without a matching file
+ * rename, or an entry type declared in one collection but not another, would vanish a page with
+ * zero build output -- so when `isBuildMode()` is true any such file throws instead
+ * (`static/index.ts`'s `assertBuildEntriesValid` is the sibling schema-validity guard).
+ * Outside build mode (admin UI, content tree, `next dev`) it is still skipped, since a fresh
+ * scaffold or mid-rename file legitimately exists there.
  *
- * Build-time-only failure: a file with a recognized content extension (`.md`/`.mdx`/`.json`/
- * `.yaml`) sitting in a collection directory that *looks like an attempted entry* (see
- * `looksLikeMalformedEntry` below) but doesn't match `{type}.{slug}.{id}.{ext}` is, by default,
- * silently dropped (see `listCollectionEntries`'s debug-gated warning). That is exactly the
- * silent-page-loss failure mode static generation must not have — a schema rename without a
- * matching file rename, or an entry type declared in one collection but not another, would
- * otherwise vanish a page with zero build output. So when `isBuildMode()` is true, any such file
- * turns the listing into a thrown error instead (see `findInvalidEntries`/`assertBuildEntriesValid`
- * in `static/index.ts` for the sibling schema-validity guard this mirrors). Outside build mode
- * (admin UI, content tree, `next dev`) the file is still just skipped, since a fresh scaffold or
- * mid-rename file legitimately exists there.
- *
- * A file that was never entry-shaped to begin with — a `README.md`, or a colocated sibling
- * artifact named `{contentId}.suffix.ext` per the `entryTransforms`/`readSibling` convention
- * documented in the README — is not this guard's failure mode and never throws, in or out of
- * build mode. See `looksLikeMalformedEntry` for the exact shape test.
- *
- * @param branchRoot - Absolute path to the branch workspace root
- * @param flatSchema - Flattened schema items (from flattenSchema)
- * @param contentRootName - The content root name (e.g. "content")
- * @param options - Listing options (extract, filter, rootPath, sort, resolveReferences)
- * @param visibility - Internal path-ACL predicate; see `ContentVisibilityOptions`
+ * A file that was never entry-shaped -- a `README.md`, or a colocated sibling artifact named
+ * `{contentId}.suffix.ext` per the `entryTransforms`/`readSibling` convention -- never throws.
  */
 export async function listEntries(branchRoot, flatSchema, contentRootName, options, visibility) {
     const rootPath = options?.rootPath ?? contentRootName;
     const extract = options?.extract;
     const filter = options?.filter;
     const customSort = options?.sort;
-    // Find all collections under rootPath
     const collections = flatSchema.filter((item) => item.type === 'collection' &&
         item.entries !== undefined &&
         (item.logicalPath === rootPath || item.logicalPath.startsWith(`${rootPath}/`)));
-    // List entries from all collections in parallel.
-    // The visibility predicate is applied here, before the map below, so a denied entry's
-    // data never reaches `extract` (let alone the returned items).
+    // List entries from all collections in parallel. The visibility predicate is applied here,
+    // before the map below, so a denied entry's data never reaches `extract`.
     const shouldInclude = visibility?.shouldInclude;
     const skippedFiles = [];
     // One store + cache for the whole call, or nothing at all when the caller did not opt in.
@@ -176,10 +148,9 @@ export async function listEntries(branchRoot, flatSchema, contentRootName, optio
             : visible;
         return resolved.map((entry) => ({ entry, collection }));
     }));
-    // Build-time only: fail loudly rather than silently shipping a build with a page missing. See
-    // the build-time-only-failure note in this function's own doc comment above. Only files that
-    // structurally look like a malformed entry reach `skippedFiles` at all -- see
-    // `looksLikeMalformedEntry` and `listCollectionEntries`.
+    // Build-time only: fail loudly rather than silently shipping a build with a page missing --
+    // see this function's doc comment. Only files that structurally look like a malformed entry
+    // reach `skippedFiles` (see `looksLikeMalformedEntry`).
     if (isBuildMode() && skippedFiles.length > 0) {
         const lines = skippedFiles.map(({ filename, collectionPath }) => `  - ${collectionPath}/${filename}`);
         throw new Error(`CanopyCMS static build: found ${skippedFiles.length} file(s) that look like malformed ` +
@@ -193,26 +164,22 @@ export async function listEntries(branchRoot, flatSchema, contentRootName, optio
             'segments (id.suffix.ext) so it is never mistaken for an entry attempt. Otherwise rename ' +
             'or move the file, or fix the schema, then rebuild.');
     }
-    // Flatten and map to ListEntriesItem
     const contentPrefix = contentRootName ? `${contentRootName}/` : '';
     const items = [];
     for (const results of collectionResults) {
         for (const { entry, collection } of results) {
-            // Compute pathSegments: strip content root prefix, split on /
             const pathWithoutRoot = entry.logicalPath.startsWith(contentPrefix)
                 ? entry.logicalPath.slice(contentPrefix.length)
                 : entry.logicalPath;
             const pathSegments = pathWithoutRoot.split('/').filter(Boolean);
-            // Compute urlPath (collapses an `index` entry to its parent collection path) through
-            // the SHARED rule rather than a local copy of it. A resolved reference now carries a
-            // `urlPath` too, and the whole point of that field is that it addresses the same entry
-            // this listing does, so the two must not be free to drift apart.
+            // Compute urlPath (collapsing an `index` entry to its parent collection path) through
+            // the SHARED rule rather than a local copy: a resolved reference carries a `urlPath`
+            // that must address the same entry this listing does, so the two must not drift apart.
             //
-            // One deliberate copy of this rule remains: `content-tree.ts`'s `defaultBuildPath`,
-            // which is exported for adopters to extend and also handles the collection case
-            // `computeEntryUrl` does not model. It agrees today; folding it in is tracked in
+            // One deliberate copy of the rule remains: `content-tree.ts`'s `defaultBuildPath`,
+            // exported for adopters to extend and also handling the collection case
+            // `computeEntryUrl` does not model. Folding it in is tracked in
             // `.claude/future-tasks/default-build-path-url-rule-copy.md`.
-            // `content-listing.test.ts` pins the listing-vs-resolved-reference agreement.
             const urlPath = computeEntryUrl(entry.collectionPath, entry.slug, contentRootName);
             const raw = entry.data;
             const meta = {
@@ -249,15 +216,9 @@ export async function listEntries(branchRoot, flatSchema, contentRootName, optio
     }
     return items;
 }
-// ---------------------------------------------------------------------------
-// Shared utilities
-// ---------------------------------------------------------------------------
 /**
- * Sort items by a content ID order array.
- * Items in the order array come first (in order), items not in the array come at the end
- * sorted by the provided fallback key.
- *
- * Note: sorts the array in-place and returns it.
+ * Sort items by a content ID order array: items in `order` come first, in that order, then
+ * the rest sorted by `fallbackKey`. Sorts the array in place and returns it.
  */
 export const sortByOrder = (items, order, fallbackKey) => {
     if (!order || order.length === 0) {
@@ -278,32 +239,26 @@ export const sortByOrder = (items, order, fallbackKey) => {
     });
 };
 /**
- * True when a content-extension filename structurally resembles an attempted entry — as opposed
- * to a file that was never entry-shaped to begin with.
+ * True when a content-extension filename structurally resembles an attempted entry — as
+ * opposed to a file that was never entry-shaped to begin with.
  *
- * A successfully-parsed entry always has at least 4 dot-separated segments: `type` (1+),
- * `slug` (1+, since `parseTypedFilename` always takes at least the one segment between type and
- * id), `id` (1), `ext` (1). So a file with 4+ segments that still failed to parse is malformed
- * on its face — a wrong-length or invalid-Base58 ID, most often (`post.hello-world.BADID.md`).
+ * A successfully-parsed entry always has at least 4 dot-separated segments (type, slug, id,
+ * ext), so a 4+-segment file that still failed to parse is malformed on its face -- usually a
+ * wrong-length or invalid-Base58 ID (`post.hello-world.BADID.md`).
  *
- * That segment-count test alone missed the MORE common accident: losing the ID segment
- * entirely. `post.hello-world.md` (3 segments) fails `parseTypedFilename` exactly like the
- * 4-segment case does, but a bare 3-or-fewer-segment cutoff would treat it as never having been
- * entry-shaped and drop it silently — the page just vanishes with a green build. So a 3-segment
- * file whose FIRST segment matches a real entry type name in this collection is ALSO treated as
- * malformed: `parseTypedFilename` requires type+slug+id (3 segments) after stripping the
- * extension, so a 3-total-segment filename already has only 2 left over — it could only have
- * been attempting `type.slug` with no id, or `type.id` with no slug, either way a lost segment,
- * not a coincidence. This still leaves the two motivating "was never an entry" cases alone: a
- * bare `README.md` (2 segments, and "README" is essentially never a configured entry type name)
- * and an entry's colocated sibling artifact named `{contentId}.suffix.ext` per the
- * `entryTransforms`/`readSibling` convention documented in the README (3 segments, e.g.
- * `5NVkkrB1MJUv.profile.json` — a content ID is never itself an entry type name, so the same
- * "first segment matches a known type" test correctly leaves it unflagged).
+ * A 3-segment file whose FIRST segment matches a real entry type name in this collection
+ * counts too, which catches the more common accident of losing the ID segment entirely
+ * (`post.hello-world.md`): `parseTypedFilename` needs type+slug+id after the extension, so 3
+ * total segments leave only 2 -- `type.slug` with no id, or `type.id` with no slug, a lost
+ * segment rather than a coincidence. That leaves the two "never an entry" cases alone: a bare
+ * `README.md` (2 segments, and "README" is essentially never a configured entry type name) and
+ * an entry's colocated sibling artifact `{contentId}.suffix.ext` per the
+ * `entryTransforms`/`readSibling` convention (3 segments, but a content ID is never a type
+ * name).
  *
- * Dot-prefixed (hidden files, editor swap/backup files) and underscore-prefixed (a common
- * adopter convention for "not an entry") names are excluded outright regardless of segment
- * count, matching `parseTypedFilename`'s own dotfile rejection.
+ * Dot-prefixed (hidden files, editor swap/backup files) and underscore-prefixed (an adopter
+ * convention for "not an entry") names are excluded outright at any segment count, matching
+ * `parseTypedFilename`'s own dotfile rejection.
  */
 const looksLikeMalformedEntry = (filename, entryTypes) => {
     if (filename.startsWith('.') || filename.startsWith('_'))
@@ -314,24 +269,20 @@ const looksLikeMalformedEntry = (filename, entryTypes) => {
     return segments.length === 3 && entryTypes.some((e) => e.name === segments[0]);
 };
 /**
- * List all entries in a collection directory.
- * Reads each entry's data (frontmatter or JSON).
+ * List all entries in a collection directory, reading each entry's data.
  *
- * @param onSkip - Called for every file that has a recognized content extension, doesn't match
- *   the `{type}.{slug}.{id}.{ext}` grammar (see `parseTypedFilename`), AND structurally looks
- *   like an attempted entry (see `looksLikeMalformedEntry`). A file that was never entry-shaped
- *   (too few dot-separated segments to ever be a valid entry — a `README.md`, a colocated
- *   sibling artifact) is always silently dropped with a debug-gated `log.warn`, never passed to
- *   `onSkip`. Optional and purely a diagnostic hook — existing callers that omit it keep the
- *   exact prior behavior. `listEntries` below uses this to turn the skip into a hard build-time
- *   failure instead of a silent one.
+ * `onSkip` is called for every file that has a recognized content extension, does NOT match
+ * the `{type}.{slug}.{id}.{ext}` grammar (see `parseTypedFilename`), AND structurally looks
+ * like an attempted entry (see `looksLikeMalformedEntry`). A file that was never entry-shaped
+ * -- a `README.md`, a colocated sibling artifact -- is always dropped with a debug-gated
+ * `log.warn` and never passed to `onSkip`. Optional and purely diagnostic: `listEntries` uses
+ * it to turn the skip into a hard build-time failure instead of a silent one.
  */
 export const listCollectionEntries = async (root, collection, onSkip) => {
     if (collection.type !== 'collection' || !collection.entries) {
         return [];
     }
     const entryTypes = collection.entries;
-    // Build a map of extension to entry types for efficient lookup
     const extToTypes = new Map();
     for (const entryType of entryTypes) {
         const ext = getFormatExtension(entryType.format);
@@ -340,7 +291,6 @@ export const listCollectionEntries = async (root, collection, onSkip) => {
         extToTypes.set(ext, existing);
     }
     const validExts = Array.from(extToTypes.keys());
-    // Resolve the full collection path with embedded IDs
     const collectionRoot = await resolveCollectionPath(root, collection.logicalPath);
     if (!collectionRoot) {
         return [];

package/dist/content-reader.d.ts

@@ -31,18 +31,16 @@ export interface ReadContentInput {
      *
      * 1. `entryPath` must be a COLLECTION. A published URL is `/<collectionSegments>/<slug>` (or
      *    the collapsed collection path, for an index entry), so its non-slug segments are always
-     *    collection names. An `entryPath` that resolves to an entry-TYPE item instead would be
-     *    delegated by `ContentStore.buildPaths` to the parent collection -- answering at
-     *    `/<collection>/<typeName>` and `/<collection>/<typeName>/<slug>`, neither of which any
-     *    forward surface emits.
+     *    collection names. An `entryPath` resolving to an entry-TYPE item would be delegated by
+     *    `ContentStore.buildPaths` to the parent collection, answering at URLs no forward surface
+     *    emits.
      * 2. The resolved entry's type must be one its collection declares, matching the
      *    `parseTypedFilename(filename, collection.entries)` check `listEntries` applies. A legacy
      *    untyped file has no type token to fail on -- see `declaresEntryType`.
      *
-     * Set by `readByUrlPath` and nothing else. Note what it does NOT do: `read({ entryPath:
-     * 'content/home' })` and direct `ContentStore` use keep the entry-type delegation, which is a
-     * supported API and the only way to address a singleton structurally. Misusing this flag can
-     * only make a read stricter, never looser.
+     * Set by `readByUrlPath` and nothing else: `read({ entryPath: 'content/home' })` and direct
+     * `ContentStore` use keep the entry-type delegation, a supported API and the only way to
+     * address a singleton structurally. Misusing this flag can only make a read stricter.
      */
     urlAddressableOnly?: boolean;
 }
@@ -53,35 +51,28 @@ export interface ReadContentInput {
  */
 export interface ContentReadMeta {
     /**
-     * Absolute filesystem path to the resolved entry file. It is **server-only**
-     * -- do not serialize it to the client or embed it in public output, as it
-     * reveals the deployment's filesystem layout (home dir / EFS mount / branch
-     * name).
+     * Absolute filesystem path to the resolved entry file. **Server-only**: do not serialize it
+     * to the client or embed it in public output, as it reveals the deployment's filesystem
+     * layout (home dir / EFS mount / branch name).
      */
     physicalPath: PhysicalPath;
     /**
      * The resolved entry type name, read from the entry's own filename
-     * (`{type}.{slug}.{id}.{ext}`) -- immutable once the file is created, and
-     * NOT re-validated against the collection's current `entries` config on
-     * every read. It is therefore usually, but not guaranteed to be, a key in
-     * the collection's `entries` config: it can diverge if an entry type was
-     * renamed or removed from the schema after files using the old name were
-     * created, or if the file was hand-authored with an unrecognized type
-     * token.
+     * (`{type}.{slug}.{id}.{ext}`) -- immutable once the file is created, and NOT re-validated
+     * against the collection's current `entries` config on every read. So it is usually, but not
+     * guaranteed to be, a key in that config: it diverges when an entry type was renamed or
+     * removed from the schema after files using the old name were created, or when the file was
+     * hand-authored with an unrecognized type token.
      *
-     * For a legacy entry file predating embedded-type filenames (`{slug}.{ext}`),
-     * there is no type recorded on disk at all -- `entryType` silently falls
-     * back to the collection's DEFAULT entry type, which may or may not be what
-     * the file actually is. `entryId` being `undefined` (below) is the signal
-     * that this happened: when `entryId` is `undefined`, `entryType` is
-     * inferred rather than read.
+     * A legacy entry file (`{slug}.{ext}`) records no type at all, so this falls back to the
+     * collection's DEFAULT entry type, which may not be what the file is. `entryId` being
+     * `undefined` is the signal that this happened.
      */
     entryType: string;
     /**
-     * The entry's 12-char Base58 content ID, when the resolved file carries one.
-     * Undefined only for legacy entry files predating embedded-ID filenames
-     * (`{slug}.{ext}` rather than `{type}.{slug}.{id}.{ext}`) -- see the
-     * `entryType` caveat above for what that implies about it.
+     * The entry's 12-char Base58 content ID, when the resolved file carries one. Undefined only
+     * for legacy entry files predating embedded-ID filenames (`{slug}.{ext}` rather than
+     * `{type}.{slug}.{id}.{ext}`) -- see the `entryType` caveat above for what that implies.
      */
     entryId?: ContentId;
 }

package/dist/content-reader.js

@@ -63,7 +63,6 @@ export const createContentReader = (options) => {
     const resolveStore = async (branchName) => {
         const context = await resolveBranchContext(branchName);
         const { branchRoot } = resolveBranchPaths(context, operatingMode, basePathOverride);
-        // Load per-branch schema dynamically
         const branchSchemaCache = services.branchSchemaCache;
         const contentRootName = services.config.contentRoot || 'content';
         const { flatSchema: branchFlatSchema } = await branchSchemaCache.getSchema(branchRoot, services.entrySchemaRegistry, contentRootName);
@@ -86,24 +85,22 @@ export const createContentReader = (options) => {
         .filter(Boolean)
         .map((segment) => encodeURIComponent(segment))
         .join('/');
-    // Build preview paths using simple path construction
     const contentRoot = trimSlashes(services.config.contentRoot ?? 'content');
     // The `val === contentRoot` branch matters as much as the prefix one: a root-level entry's
-    // collectionPath IS the content root, which does not start with `${contentRoot}/`, so without
-    // it the root index reported `path: '/content'` (and a root entry `/content/about`) -- paths
-    // that resolve to nothing. `computeEntryUrl` has always had both branches; this had one.
+    // collectionPath IS the content root, which does not start with `${contentRoot}/`, so
+    // without it the root index reports `path: '/content'` (and a root entry `/content/about`)
+    // -- paths that resolve to nothing.
     //
     // Both branches stay guarded on `contentRoot` so an empty one passes the value through
     // unchanged, exactly as `computeEntryUrl` does. Unreachable today (`contentRootSchema` is
     // `relativePathSchema.default('content')` with `.min(1)`), but a blanket short-circuit would
-    // be the WRONG answer if it ever were reachable -- it would flatten every entry to root.
+    // be the WRONG answer if it ever were reachable: it would flatten every entry to root.
     const stripRoot = (val) => contentRoot && val === contentRoot
         ? ''
         : contentRoot && val.startsWith(`${contentRoot}/`)
             ? val.slice(contentRoot.length + 1)
             : val;
     const buildEntryPath = (opts) => {
-        // Construct preview path from collectionPath
         const stripped = stripRoot(opts.collectionPath);
         const base = stripped ? `/${stripped}` : '/';
         const appendBranch = (url) => opts.branch
@@ -136,21 +133,18 @@ export const createContentReader = (options) => {
         // for server-side colocated-artifact reads (e.g. a sibling profile.json). Already
         // computed here for permission checks; just carried through.
         let physicalPath;
-        // Entry type + content ID are already resolved as part of path resolution
-        // (buildPaths() derives both from the schema item / filename) — surfaced on
-        // read() / readByUrlPath() so callers can route or key by them without a
-        // separate listEntries lookup or filename parse.
+        // Entry type + content ID come out of path resolution (buildPaths() derives both from the
+        // schema item / filename), surfaced on read() / readByUrlPath() so callers can route or
+        // key by them without a separate listEntries lookup or filename parse.
         let entryType;
         let entryId;
         try {
             const resolved = await store.resolveDocumentPath(entryPath, slug ?? '');
             relativePath = resolved.relativePath;
             physicalPath = resolved.absolutePath;
-            // resolveDocumentPath() always sets entryTypeName for a valid schema item
-            // (collection entries fall back to 'entry'; entry-type items delegate to
-            // their parent collection with their own name), so no further fallback
-            // is needed here — id is the one field that can be legitimately absent,
-            // for legacy entry files without an embedded ID (see ContentReadMeta).
+            // resolveDocumentPath() always sets entryTypeName for a valid schema item, so no
+            // further fallback is needed here; `id` is the one field that can be legitimately
+            // absent, for legacy entry files without an embedded ID (see ContentReadMeta).
             entryType = resolved.entryTypeName;
             entryId = resolved.id;
         }
@@ -216,9 +210,7 @@ export const createContentReader = (options) => {
         const rawData = docRecord.data;
         const body = docRecord.body;
         const bodyFieldName = docRecord.bodyFieldName ?? 'body';
-        // Merge body into data first, then resolve entry links across all fields
         let data = (body != null ? { ...rawData, [bodyFieldName]: body } : rawData);
-        // Resolve entry:ID links in all string values (body + nested markdown fields)
         if (input.resolveEntryLinks ?? true) {
             const idIndex = await store.idIndex();
             data = resolveEntryLinksInData(data, idIndex, contentRoot, services.config.entryLinkUrl);