canopycms 0.0.67-int.90 → 0.0.67

package/dist/utils/provisioning-lock.js

@@ -6,19 +6,15 @@ import { canopyLogWarn } from './logger.js';
 /**
  * Shared option set for both provisioning-lock variants.
  *
- * **The lock is anchored on the lock file's own path, not its directory.**
- * proper-lockfile keys its module-level `locks{}` bookkeeping (refresh timer,
- * release fn) by the TARGET path passed to `lock()` — not by `lockfilePath`.
- * Passing the shared branches directory made every branch under one root alias
- * a single registry entry: acquiring `.b.init.lock` overwrote `.a.init.lock`'s
- * entry, so releasing A tore down B's refresh timer, made B's own release fail
- * with `ERELEASED`, and leaked B's lock directory on disk until `stale`
- * expired. The orphaned refresh timer then `stat`ed a path its owner had
- * already deleted, raising `ECOMPROMISED`. Anchoring here makes the registry
- * key identical to the on-disk lock identity, so two live locks can never
- * share a key. `realpath: false` because the anchor path is the lock marker
- * itself and does not exist before we create it (realpath would ENOENT).
- * See docs/concurrency.md ("Anchor path matters").
+ * **The lock is anchored on the lock file's own path, not its directory.** proper-lockfile keys
+ * its module-level `locks{}` bookkeeping (refresh timer, release fn) by the TARGET path passed
+ * to `lock()`, not by `lockfilePath`, so passing a shared parent makes every branch under one
+ * root alias a single registry entry: releasing one tears down the other's refresh timer, fails
+ * its release with `ERELEASED`, leaks its lock directory until `stale` expires, and leaves an
+ * orphaned timer to `stat` a deleted path and raise `ECOMPROMISED`. Anchoring on the marker
+ * makes the registry key identical to the on-disk lock identity, so two live locks can never
+ * share one. `realpath: false` because that anchor path does not exist before we create it
+ * (realpath would ENOENT). See docs/concurrency.md ("Anchor path matters").
  */
 function provisioningLockOptions(lockPath, retries, onCompromised) {
     return {
@@ -26,30 +22,27 @@ function provisioningLockOptions(lockPath, retries, onCompromised) {
         realpath: false,
         retries,
         stale: 30_000,
-        // proper-lockfile invokes this from inside its refresh timer, so ANY throw
-        // escaping here is an uncaught exception that kills the process -- the very
-        // failure the handler exists to prevent. Call sites are told not to throw
-        // (see OnLockCompromised); this makes it structural rather than a
-        // convention, and also covers the LOGGER throwing: under `CI=true`,
-        // vitest's `onConsoleLog` turns any console write into a throw.
+        // proper-lockfile invokes this from inside its refresh timer, so ANY throw escaping here is
+        // an uncaught exception that kills the process. Call sites are told not to throw (see
+        // OnLockCompromised); this makes it structural rather than a convention, and also covers the
+        // LOGGER throwing -- under `CI=true`, vitest's `onConsoleLog` turns a console write into a
+        // throw.
         onCompromised: (err) => {
             try {
                 if (onCompromised) {
                     onCompromised(err);
                     return;
                 }
-                // Default: log and let the holder finish. proper-lockfile's own default
-                // rethrows from the refresh timer, which protects nothing -- by the time
-                // a compromise is reported the mutual exclusion is already gone.
-                // `canopyLogWarn` (not the debug logger) because this means "two
-                // holders may now be live": it must be visible without CANOPYCMS_DEBUG.
+                // Default: log and let the holder finish. proper-lockfile's own default rethrows from
+                // the refresh timer, which protects nothing -- by the time a compromise is reported the
+                // mutual exclusion is already gone. `canopyLogWarn`, not the debug logger, because "two
+                // holders may now be live" must be visible without CANOPYCMS_DEBUG.
                 canopyLogWarn(`[canopy] Provisioning lock compromised mid-hold for ${lockPath}:`, getErrorMessage(err));
             }
             catch {
-                // Last resort: a raw stderr write goes around both a replaced logger
-                // and vitest's console interception, so the compromise still leaves a
-                // trace. Guarded in turn, because nothing above this line is allowed
-                // to throw out of a refresh timer.
+                // Last resort: a raw stderr write goes around both a replaced logger and vitest's console
+                // interception, so the compromise still leaves a trace. Guarded in turn, because nothing
+                // here is allowed to throw out of a refresh timer.
                 try {
                     process.stderr.write(`[canopy] lock compromised for ${lockPath}; its handler or logger threw\n`);
                 }
@@ -61,12 +54,11 @@ function provisioningLockOptions(lockPath, retries, onCompromised) {
     };
 }
 /**
- * proper-lockfile's release rejects with `ERELEASED` once the lock has been
- * marked compromised (`setLockAsCompromised` sets `released = true` before the
- * caller ever gets to release). Callers hold this in a `finally`, so letting
- * that escape would convert a COMPLETED operation into a spurious failure.
- * There is nothing left to release in that state, so swallow just that code and
- * let every other release error propagate to the caller that asked for it.
+ * proper-lockfile's release rejects with `ERELEASED` once the lock has been marked compromised
+ * (`setLockAsCompromised` sets `released = true` before the caller gets to release). Callers hold
+ * this in a `finally`, so letting it escape converts a COMPLETED operation into a spurious
+ * failure. Nothing is left to release in that state, so swallow just that code and let every
+ * other release error propagate.
  */
 function releaseIgnoringAlreadyReleased(release, lockPath) {
     return async () => {
@@ -75,9 +67,8 @@ function releaseIgnoringAlreadyReleased(release, lockPath) {
         }
         catch (err) {
             if (isNodeError(err) && err.code === 'ERELEASED') {
-                // Deliberately does not name a cause: ERELEASED is raised both by a
-                // lock compromised mid-hold AND by a plain double-release bug, and
-                // from here the two are indistinguishable.
+                // Deliberately does not name a cause: ERELEASED is raised both by a lock compromised
+                // mid-hold and by a plain double-release bug, indistinguishable from here.
                 canopyLogWarn(`[canopy] Lock at ${lockPath} was already released (compromised mid-hold, or released twice); nothing to release`);
                 return;
             }
@@ -86,51 +77,40 @@ function releaseIgnoringAlreadyReleased(release, lockPath) {
     };
 }
 /**
- * Acquire a cross-process filesystem lock for content provisioning.
+ * Acquire a cross-process filesystem lock for content provisioning. Returns a release function —
+ * always call it in a `finally`.
  *
- * In-memory locks only serialize work within a single process. Build tools such
- * as Next.js static generation provision content from parallel worker
- * *processes*, so two processes can otherwise race while creating the same git
- * workspace (e.g. "cannot mkdir remote.git: File exists" or "destination path
- * already exists"). proper-lockfile uses an atomic on-disk lock that holds across
- * processes, so only one provisions a given resource at a time while the others
- * wait and then find it already done.
+ * In-memory locks serialize only within one process, but build tools such as Next.js static
+ * generation provision content from parallel worker *processes*, which then race while creating
+ * the same git workspace ("cannot mkdir remote.git: File exists", "destination path already
+ * exists"). proper-lockfile's atomic on-disk lock holds across processes, so one provisions while
+ * the others wait and then find it already done.
  *
- * Returns a release function — always call it in a `finally`.
- *
- * @param lockTargetDir directory the lock marker lives in (created if missing)
- * @param lockName name of the on-disk lock marker, created inside lockTargetDir
  * @param onCompromised see {@link OnLockCompromised}; defaults to log-and-continue
  */
 export async function acquireProvisioningLock(lockTargetDir, lockName, onCompromised) {
     await fs.mkdir(lockTargetDir, { recursive: true });
     const lockPath = path.join(lockTargetDir, lockName);
-    // Generous, jittered retries: several processes may contend for one workspace
-    // (e.g. Lambda containers cold-starting together against one EFS root), and
-    // the holder can take several seconds to init + clone/push. `randomize` de-syncs the herd so a waiter isn't
-    // perpetually colliding on the same tick. `stale` stays modest because proper-
-    // lockfile auto-refreshes a live holder's lock, so it only expires when a
-    // process actually dies.
+    // Generous, jittered retries: several processes may contend for one workspace (Lambda
+    // containers cold-starting together against one EFS root), and the holder can take seconds to
+    // init plus clone/push. `randomize` de-syncs the herd so a waiter is not perpetually colliding
+    // on the same tick. `stale` stays modest because proper-lockfile auto-refreshes a live holder's
+    // lock, so it expires only when a process actually dies.
     const release = await lockfile.lock(lockPath, provisioningLockOptions(lockPath, { retries: 600, factor: 1, minTimeout: 300, maxTimeout: 800, randomize: true }, onCompromised));
     return releaseIgnoringAlreadyReleased(release, lockPath);
 }
 /**
- * Zero-retry variant of {@link acquireProvisioningLock}, for admin actions
- * running inside a synchronous request/response cycle (e.g. a Lambda-backed
- * API handler). `acquireProvisioningLock`'s ~600-retry budget waits minutes
- * for a live provisioner to finish; an admin request must fail fast on
- * contention instead (409 immediately) rather than hang the request for that
- * long.
+ * Zero-retry variant of {@link acquireProvisioningLock}, for admin actions inside a synchronous
+ * request/response cycle (a Lambda-backed API handler). `acquireProvisioningLock`'s ~600-retry
+ * budget waits minutes for a live provisioner; an admin request must fail fast instead.
  *
- * `stale: 30_000` is unchanged from the patient variant: a genuinely stale
- * lock (holder crashed more than 30s ago) is still taken over normally --
- * this only removes the RETRY loop for live contention, not the staleness
- * recovery a caller depends on (see branch-health.ts's [H1] freshness rail,
- * which reads this same lock's mtime to decide whether it is fresh or
- * stale before an admin purge/repair proceeds).
+ * `stale: 30_000` is unchanged from the patient variant: a genuinely stale lock (holder crashed
+ * more than 30s ago) is still taken over normally. Only the RETRY loop for live contention is
+ * removed, not the staleness recovery a caller depends on -- see branch-health.ts's [H1]
+ * freshness rail, which reads this lock's mtime before an admin purge/repair proceeds.
  *
- * Throws with `err.code === 'ELOCKED'` on contention (a live, non-stale
- * holder) -- callers should translate that into a 409.
+ * Throws with `err.code === 'ELOCKED'` on contention (a live, non-stale holder) -- callers
+ * translate that into a 409.
  */
 export async function tryAcquireProvisioningLock(lockTargetDir, lockName, onCompromised) {
     await fs.mkdir(lockTargetDir, { recursive: true });

package/dist/utils/sanitize-href.d.ts

@@ -14,9 +14,8 @@ export declare function declaresScheme(url: string): boolean;
  * Whether `url`, resolved as a URL reference against a fixed sentinel origin, lands on a
  * DIFFERENT origin than the sentinel WITHOUT itself declaring a scheme.
  *
- * True for a literal protocol-relative reference (`//host`) and for every WHATWG
- * backslash-equivalent spelling that a browser resolves the same way (`/\host`, `\\host`,
- * `\/host`, and combinations with stripped whitespace/control characters) -- these all read as
+ * True for a literal protocol-relative reference (`//host`) and for every backslash-equivalent
+ * spelling a browser resolves the same way (see `declaresScheme`) -- these all read as
  * "site-relative" to a naive string check but actually redefine the authority. False for a
  * normal site-relative path (`/about`, `docs/guide`) and for a scheme-qualified absolute URL
  * (`declaresScheme` already identifies those as intentionally off-site on their own).
@@ -25,6 +24,7 @@ export declare function declaresScheme(url: string): boolean;
  * (e.g. `utils/url-prefix.ts`'s `isAbsoluteUrl`, for a CDN-hosted `ogImage`) should check that
  * separately and only fall back to this function to catch the spellings that slip past a
  * `startsWith('//')` check.
+ * @internal Exported for tests.
  */
 export declare function isImplicitlyOffOrigin(url: string): boolean;
 /**
@@ -36,7 +36,7 @@ export declare function isImplicitlyOffOrigin(url: string): boolean;
  * slash/backslash characters: WHATWG URL also strips tabs, newlines, and carriage returns during
  * parsing (wherever they appear, not just at the edges), so `/\t/evil.com` is exactly as
  * off-origin as `/\evil.com` despite having no leading backslash-or-slash run for a regex to
- * find. Re-parsing gets this right for free instead of re-deriving the quirk a second time.
+ * find.
  *
  * Useful for a caller that wants to keep emitting SOME value for an implicitly-off-origin input
  * rather than rejecting it outright (`sanitizeHref` rejects to a fallback instead; see
@@ -102,12 +102,7 @@ export declare function isHttpUrlOrSameOriginPath(value: string, opts?: {
  *   likely to be a paste error or an injection attempt than an intentional
  *   protocol-relative link, so we don't let it through as an absolute
  *   off-site URL. This is enforced by checking whether the input DECLARES a
- *   scheme, not by matching a `//` prefix: WHATWG URL treats backslash as
- *   equivalent to slash for special schemes, so `/\evil.com`, `\\evil.com`
- *   and `\/evil.com` are all protocol-relative in effect. An earlier version
- *   of this function checked `startsWith('//')` and let all three through as
- *   `https://evil.com/` -- an open redirect out of the one function whose
- *   job is to prevent exactly that.
+ *   scheme, not by matching a `//` prefix -- see `declaresScheme`.
  * - Fragment-only (`#section`) and query-only (`?q=1`) input resolves
  *   against the sentinel with pathname `/`; we strip that synthetic leading
  *   slash so the result stays a same-page reference (`#section`) instead of

package/dist/utils/sanitize-href.js

@@ -35,9 +35,8 @@ export function declaresScheme(url) {
  * Whether `url`, resolved as a URL reference against a fixed sentinel origin, lands on a
  * DIFFERENT origin than the sentinel WITHOUT itself declaring a scheme.
  *
- * True for a literal protocol-relative reference (`//host`) and for every WHATWG
- * backslash-equivalent spelling that a browser resolves the same way (`/\host`, `\\host`,
- * `\/host`, and combinations with stripped whitespace/control characters) -- these all read as
+ * True for a literal protocol-relative reference (`//host`) and for every backslash-equivalent
+ * spelling a browser resolves the same way (see `declaresScheme`) -- these all read as
  * "site-relative" to a naive string check but actually redefine the authority. False for a
  * normal site-relative path (`/about`, `docs/guide`) and for a scheme-qualified absolute URL
  * (`declaresScheme` already identifies those as intentionally off-site on their own).
@@ -46,6 +45,7 @@ export function declaresScheme(url) {
  * (e.g. `utils/url-prefix.ts`'s `isAbsoluteUrl`, for a CDN-hosted `ogImage`) should check that
  * separately and only fall back to this function to catch the spellings that slip past a
  * `startsWith('//')` check.
+ * @internal Exported for tests.
  */
 export function isImplicitlyOffOrigin(url) {
     if (declaresScheme(url))
@@ -66,7 +66,7 @@ export function isImplicitlyOffOrigin(url) {
  * slash/backslash characters: WHATWG URL also strips tabs, newlines, and carriage returns during
  * parsing (wherever they appear, not just at the edges), so `/\t/evil.com` is exactly as
  * off-origin as `/\evil.com` despite having no leading backslash-or-slash run for a regex to
- * find. Re-parsing gets this right for free instead of re-deriving the quirk a second time.
+ * find.
  *
  * Useful for a caller that wants to keep emitting SOME value for an implicitly-off-origin input
  * rather than rejecting it outright (`sanitizeHref` rejects to a fallback instead; see
@@ -197,12 +197,7 @@ export function isHttpUrlOrSameOriginPath(value, opts = {}) {
  *   likely to be a paste error or an injection attempt than an intentional
  *   protocol-relative link, so we don't let it through as an absolute
  *   off-site URL. This is enforced by checking whether the input DECLARES a
- *   scheme, not by matching a `//` prefix: WHATWG URL treats backslash as
- *   equivalent to slash for special schemes, so `/\evil.com`, `\\evil.com`
- *   and `\/evil.com` are all protocol-relative in effect. An earlier version
- *   of this function checked `startsWith('//')` and let all three through as
- *   `https://evil.com/` -- an open redirect out of the one function whose
- *   job is to prevent exactly that.
+ *   scheme, not by matching a `//` prefix -- see `declaresScheme`.
  * - Fragment-only (`#section`) and query-only (`?q=1`) input resolves
  *   against the sentinel with pathname `/`; we strip that synthetic leading
  *   slash so the result stays a same-page reference (`#section`) instead of
@@ -232,14 +227,9 @@ export function sanitizeHref(url, fallback = '#') {
             return fallback;
         }
         // Reject protocol-relative references in EVERY spelling, by testing the
-        // property we actually care about rather than by enumerating syntax.
-        //
-        // A string-prefix check on '//' is not sufficient: WHATWG URL treats a
-        // backslash as equivalent to a forward slash for special schemes, so
-        // '/\evil.com', '\\evil.com' and '\/evil.com' are all protocol-relative
-        // in effect and each resolved to https://evil.com/ while sailing past a
-        // startsWith('//') guard. Tabs and newlines are stripped during parsing
-        // too, so the set of spellings is not one you can enumerate confidently.
+        // property we actually care about rather than by enumerating syntax (see
+        // `declaresScheme`: a startsWith('//') guard misses the backslash
+        // spellings, and stripped tabs/newlines make the set unenumerable).
         //
         // The property that actually distinguishes "the author asked for another
         // origin" from "the parser inferred one" is whether the input DECLARES a

package/dist/utils/title-field.d.ts

@@ -1,19 +1,21 @@
 import type { FieldConfig } from '../config/index.js';
 /**
- * Find the field marked `isTitle: true` in a schema and extract its value from data.
- * Recurses into object fields to support nested title fields (e.g., hero.title).
- * Returns the string value or undefined if not found or not a string.
+ * Value of the field marked `isTitle: true`, or undefined when there is none or it is not a
+ * string. Recurses into object fields, so a nested title (`hero.title`) is found.
+ * @internal Exported for tests.
  */
 export declare function extractTitleFromSchema(fields: readonly FieldConfig[], data: Record<string, unknown>): string | undefined;
-/** Convert a slug like "my-cool-page" to "My Cool Page". */
+/**
+ * Convert a slug like "my-cool-page" to "My Cool Page".
+ * @internal Exported for tests.
+ */
 export declare function humanizeSlug(slug: string): string;
 /**
- * Resolve a display title for an entry using the full fallback chain:
- * 1. Schema-marked isTitle field (if schema provided)
- * 2. Convention: data.title or data.name
- * 3. Entry type label (if provided)
- * 4. Humanized slug (if provided)
- * 5. "Untitled"
+ * Display title for an entry, by fallback chain: schema-marked isTitle field, then `data.title`
+ * or `data.name`, then the entry type label, then the humanized slug, then "Untitled".
+ *
+ * Client-safe — its only dependency on `../config` is type-only — and re-exported from both
+ * `canopycms/server` and the root `canopycms` entry, so adopter client code can import it.
  */
 export declare function resolveEntryTitle(data: Record<string, unknown>, options?: {
     schema?: readonly FieldConfig[];
@@ -21,19 +23,14 @@ export declare function resolveEntryTitle(data: Record<string, unknown>, options
     slug?: string;
 }): string;
 /**
- * Count the number of fields marked `isTitle: true` in a schema, recursing into objects.
- * Skips `list: true` objects since runtime title extraction cannot resolve array values.
- * Used for validation — at most one field per schema should be marked.
+ * Count fields marked `isTitle: true`, recursing into objects but skipping `list: true` ones,
+ * whose array values runtime title extraction cannot resolve. Validation allows at most one.
  */
 export declare function countTitleFields(fields: readonly FieldConfig[]): number;
 /**
- * Validate that all isTitle fields in a schema are string type.
- * Skips `list: true` objects (those are caught by findTitleFieldsInLists).
- * Returns an array of field names that have isTitle on a non-string type.
+ * Dotted paths of isTitle fields whose type is not `string`. Skips `list: true` objects —
+ * `findTitleFieldsInLists` catches those.
  */
 export declare function findInvalidTitleFields(fields: readonly FieldConfig[], parentPath?: string): string[];
-/**
- * Find isTitle fields inside `list: true` object fields, where they can never resolve.
- * Returns dotted paths of such fields.
- */
+/** Dotted paths of isTitle fields inside `list: true` objects, where they can never resolve. */
 export declare function findTitleFieldsInLists(fields: readonly FieldConfig[], parentPath?: string): string[];

package/dist/utils/title-field.js

@@ -1,11 +1,10 @@
-/** Type guard: true if field is an inline group (type === 'group'). */
 function isGroupField(field) {
     return field.type === 'group';
 }
 /**
- * Find the field marked `isTitle: true` in a schema and extract its value from data.
- * Recurses into object fields to support nested title fields (e.g., hero.title).
- * Returns the string value or undefined if not found or not a string.
+ * Value of the field marked `isTitle: true`, or undefined when there is none or it is not a
+ * string. Recurses into object fields, so a nested title (`hero.title`) is found.
+ * @internal Exported for tests.
  */
 export function extractTitleFromSchema(fields, data) {
     return findTitleValue(fields, data);
@@ -34,7 +33,10 @@ function findTitleValue(fields, data) {
     }
     return undefined;
 }
-/** Convert a slug like "my-cool-page" to "My Cool Page". */
+/**
+ * Convert a slug like "my-cool-page" to "My Cool Page".
+ * @internal Exported for tests.
+ */
 export function humanizeSlug(slug) {
     return slug
         .replace(/[-_]/g, ' ')
@@ -42,34 +44,28 @@ export function humanizeSlug(slug) {
         .trim();
 }
 /**
- * Resolve a display title for an entry using the full fallback chain:
- * 1. Schema-marked isTitle field (if schema provided)
- * 2. Convention: data.title or data.name
- * 3. Entry type label (if provided)
- * 4. Humanized slug (if provided)
- * 5. "Untitled"
+ * Display title for an entry, by fallback chain: schema-marked isTitle field, then `data.title`
+ * or `data.name`, then the entry type label, then the humanized slug, then "Untitled".
+ *
+ * Client-safe — its only dependency on `../config` is type-only — and re-exported from both
+ * `canopycms/server` and the root `canopycms` entry, so adopter client code can import it.
  */
 export function resolveEntryTitle(data, options) {
-    // 1. Schema-marked isTitle field
     if (options?.schema) {
         const schemaTitle = extractTitleFromSchema(options.schema, data);
         if (schemaTitle)
             return schemaTitle;
     }
-    // 2. Convention: data.title or data.name
     const title = data.title ?? data.name;
     if (typeof title === 'string')
         return title;
-    // 3. Entry type label
     if (options?.entryTypeLabel)
         return options.entryTypeLabel;
-    // 4. Humanized slug
     return options?.slug ? humanizeSlug(options.slug) : 'Untitled';
 }
 /**
- * Count the number of fields marked `isTitle: true` in a schema, recursing into objects.
- * Skips `list: true` objects since runtime title extraction cannot resolve array values.
- * Used for validation — at most one field per schema should be marked.
+ * Count fields marked `isTitle: true`, recursing into objects but skipping `list: true` ones,
+ * whose array values runtime title extraction cannot resolve. Validation allows at most one.
  */
 export function countTitleFields(fields) {
     let count = 0;
@@ -88,9 +84,8 @@ export function countTitleFields(fields) {
     return count;
 }
 /**
- * Validate that all isTitle fields in a schema are string type.
- * Skips `list: true` objects (those are caught by findTitleFieldsInLists).
- * Returns an array of field names that have isTitle on a non-string type.
+ * Dotted paths of isTitle fields whose type is not `string`. Skips `list: true` objects —
+ * `findTitleFieldsInLists` catches those.
  */
 export function findInvalidTitleFields(fields, parentPath) {
     const invalid = [];
@@ -110,10 +105,7 @@ export function findInvalidTitleFields(fields, parentPath) {
     }
     return invalid;
 }
-/**
- * Find isTitle fields inside `list: true` object fields, where they can never resolve.
- * Returns dotted paths of such fields.
- */
+/** Dotted paths of isTitle fields inside `list: true` objects, where they can never resolve. */
 export function findTitleFieldsInLists(fields, parentPath) {
     const found = [];
     for (const field of fields) {
@@ -124,7 +116,6 @@ export function findTitleFieldsInLists(fields, parentPath) {
             const fieldPath = parentPath ? `${parentPath}.${field.name}` : field.name;
             if (field.type === 'object' && 'fields' in field && field.fields) {
                 if (field.list) {
-                    // Any isTitle inside a list object is invalid — collect them
                     found.push(...collectAllTitleFields(field.fields, fieldPath));
                 }
                 else {
@@ -135,7 +126,7 @@ export function findTitleFieldsInLists(fields, parentPath) {
     }
     return found;
 }
-/** Collect all isTitle fields recursively (used inside list context). */
+/** Every isTitle field below this point, for the list context where all of them are invalid. */
 function collectAllTitleFields(fields, parentPath) {
     const found = [];
     for (const field of fields) {

package/dist/utils/typed-filename.d.ts

@@ -3,56 +3,28 @@ import type { ContentId, Slug } from '../paths/types.js';
 /**
  * Parse a Canopy content filename into its `{type}.{slug}.{id}.{ext}` parts.
  *
- * ## Filename grammar
+ * The slug may itself contain dots (`getting.started.guide`), so type and ID anchor the split:
+ * the ID is the second-to-last dot-separated segment, the slug is everything between the type and
+ * it (lowercased), and the extension is stripped. The ID is a 12-character Base58 content ID, and
+ * a would-be ID segment that fails `isValidId` rejects the whole parse.
  *
- * Every entry file on disk is named `{type}.{slug}.{id}.{ext}`:
- * - `type` — the entry type name (a key in the collection's `entries` config).
- * - `slug` — the entry's URL slug. May itself contain dots (e.g. a slug of
- *   `getting.started.guide`), so the type and ID anchor the split: the ID is
- *   always the second-to-last dot-separated segment, and the slug is
- *   everything between the type and the ID. The returned `slug` is
- *   lowercased.
- * - `id` — a 12-character Base58 content ID (`generateId()`/`isValidId()`).
- *   Base58 excludes the ambiguous characters `0`, `O`, `I`, `l` so IDs are
- *   unambiguous when read aloud or hand-transcribed. A filename whose
- *   would-be ID segment doesn't pass `isValidId` is rejected — the whole
- *   parse returns `null`, even if the rest of the shape looks right.
- * - `ext` — the format extension (`.md`, `.mdx`, `.json`, `.yaml`), stripped
- *   before parsing and not part of the returned result.
+ * `filename` must be a bare filename, and **that precondition is not enforced**: the parser splits
+ * purely on `.`, so a `/` or `\` is neither rejected nor treated as special and becomes part of
+ * whichever segment it falls in (`'foo/bar.slug.<validId>.md'` gives `type: 'foo/bar'`). Strip the
+ * directory component yourself (`path.basename`) — every internal caller does. A leading-dot
+ * filename is always rejected, matching `extractEntryTypeFromFilename` in `content-id-index.ts`.
  *
- * @param filename - The bare filename (no directory component). **This precondition is
- *   not enforced.** The parser splits purely on `.`, so a `/` or `\` you pass in is not
- *   rejected and is not treated as special — it becomes part of whichever segment it
- *   falls in, most often the `type` segment (e.g. `'foo/bar.slug.<validId>.md'` parses
- *   to `type: 'foo/bar'`). Strip any directory component yourself (e.g.
- *   `path.basename(filePath)`) before calling this — every internal caller already does.
- * @param entryTypes - When provided, the parsed `type` segment must match one
- *   of these entry types by name, or the parse is rejected (this is how
- *   `listCollectionEntries` filters out files that don't belong to the
- *   collection's configured entry types). Omit this argument to parse
- *   structurally without validating the type against a known list — useful
- *   for adopter code that needs to recover `{type, slug, id}` from a
- *   filename without having a schema/entry-types list on hand (e.g. a
- *   filesystem walk over content for tooling or diagnostics). Even without
- *   `entryTypes`, a leading-dot filename (dotfile, editor swap/backup file)
- *   is always rejected — an empty string is never a legal type, matching the
- *   `filename.startsWith('.')` guard `extractEntryTypeFromFilename` in
- *   `content-id-index.ts` already applies.
- * @returns `{ type, slug, id }`, or `null` if `filename` doesn't match the
- *   `{type}.{slug}.{id}.{ext}` shape (too few segments, no extension, a
- *   leading dot, an invalid ID, or — when `entryTypes` is given — an
- *   unrecognized type). `id` is validated (`isValidId`) and safe to trust. **`slug` is
- *   not** — it is the raw dot-joined middle segment(s), lowercased, cast to the branded
- *   `Slug` type without running `parseSlug`'s validation. A filename with an
- *   unconventional slug segment (e.g. containing a space, or a dot) still parses and still
- *   receives the `Slug` brand. Callers that need a validated slug must run the result
- *   through `parseSlug` themselves; this function's contract is "split the filename
- *   grammar apart," not "validate every part." `listCollectionEntries` (content-listing.ts)
- *   is exactly such a caller that does NOT re-validate — it lists the file and computes a
- *   `urlPath` for it regardless — so a dotted slug listed this way builds and gets
- *   advertised (sitemap, `generateStaticParams`) but can never be read back through
- *   `readByUrlPath`, which does run every URL-resolution candidate through `parseSlug`.
- *   `static/index.ts`'s `assertRoutableSlugs` is the build-time guard that catches this.
+ * `entryTypes`, when given, restricts the `type` segment to those entry types — how
+ * `listCollectionEntries` filters out files that do not belong to the collection. Omit it to
+ * parse structurally, for adopter code recovering `{type, slug, id}` with no schema on hand.
+ *
+ * `id` is validated and safe to trust. **`slug` is not** — it is the raw dot-joined middle,
+ * lowercased and cast to the branded `Slug` without `parseSlug`'s validation, so a slug holding a
+ * space or a dot still parses and still carries the brand. Callers needing a validated slug run
+ * `parseSlug` themselves. `listCollectionEntries` does NOT, so a dotted slug is listed and
+ * advertised (sitemap, `generateStaticParams`) yet can never be read back through `readByUrlPath`,
+ * which runs every candidate through `parseSlug`; `static/index.ts`'s `assertRoutableSlugs` is the
+ * build-time guard for that.
  */
 export declare const parseTypedFilename: (filename: string, entryTypes?: readonly EntryTypeConfig[]) => {
     type: string;