canopycms 0.0.63 → 0.0.64

package/dist/utils/url-prefix.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Joining a URL prefix onto a root-relative path, in ONE place.
+ *
+ * Two surfaces need the identical operation and had drifted into two implementations:
+ *
+ * - `static/seo.ts`'s `resolveSeoUrl` puts a site origin in front of an entry's URL path.
+ * - `assets/asset-url.ts`'s `assetUrl` puts an asset-space mount point in front of a stored
+ *   `/assets/…` src.
+ *
+ * The asset copy was the weaker one - it checked neither absoluteness of the path nor the shape
+ * of the prefix - so it silently produced `/prefix/https://cdn.example.com/x.png` for an
+ * off-site src, and a *document-relative* URL for a prefix that had no leading slash. Both bugs
+ * were already solved on the SEO side. Sharing one function is what stops a third caller from
+ * inheriting the weaker half again.
+ *
+ * Dependency-free apart from `./sanitize-href` (itself pure - its only dependency is the global
+ * `URL`), because this is reachable from client bundles via `assets/asset-url.ts`. Do not add a
+ * node built-in here; `pnpm lint:bundle` fails the build if you do.
+ */
+/**
+ * Whether `url` is a DECLARED off-site pointer - a scheme-qualified absolute URL
+ * (`https://example.com/x`) or a literal protocol-relative one (`//cdn.example.com/x`).
+ *
+ * Deliberately narrower than "resolves off-origin": a WHATWG-backslash-equivalent spelling
+ * (`/\evil.com`, `\\evil.com`, `\/evil.com` — see `utils/sanitize-href.ts`'s
+ * `isImplicitlyOffOrigin`) also resolves off-origin in a browser, but is NOT recognized here as
+ * an intentional off-site pointer the way a literal `//cdn…` is. Callers handle that case
+ * separately, by neutralizing (`neutralizeImplicitOffOrigin`) rather than passing through: a
+ * `false` result here isn't a guarantee the value is a safe site-relative path on its own, only
+ * that it isn't a *declared* off-site one.
+ */
+export declare function isAbsoluteUrl(url: string): boolean;
+/**
+ * Strip trailing slashes without a regex.
+ *
+ * The obvious `replace(/\/+$/, '')` is a polynomial-ReDoS shape (CodeQL
+ * `js/polynomial-redos`, flagged high): on a value that is mostly slashes but does not end in
+ * one, the engine retries `\/+` from every position and the match cost is quadratic in the
+ * input length. Both prefixes that reach here - a `siteUrl` and an asset `baseUrl` - are
+ * adopter-supplied and can come from config or an env var, so they count as uncontrolled. A
+ * character scan is linear and needs no reasoning about backtracking.
+ *
+ * Exported (from `canopycms/server`) so adopter code normalizing its own site-origin env var —
+ * e.g. a `SITE_URL` constant built from `NEXT_PUBLIC_SITE_URL` — has a package-provided linear
+ * way to do it instead of reaching for the same regex this function replaced.
+ */
+export declare function stripTrailingSlashes(value: string): string;
+/**
+ * Reduce a URL reference to a value that is safe to emit as a SAME-ORIGIN path.
+ *
+ * `neutralizeImplicitOffOrigin` alone is not sufficient, and this is the subtle part: it returns
+ * `pathname + search + hash`, and a WHATWG `pathname` can ITSELF begin with `//`. `/\evil.com//a`
+ * parses to host `evil.com` with pathname `//a`, so neutralizing yields the string `//a` — which,
+ * re-emitted as a URL reference, reads as protocol-relative all over again and points at a host
+ * literally named `a`. Neutralizing a second time does not help: the value is now indistinguishable
+ * from a caller's legitimate `//cdn.example.com` pointer, so every absolute-URL check downstream
+ * (correctly) passes it straight through, prefix and all.
+ *
+ * The value is same-origin by construction at this point, so collapse the leading slash run to a
+ * single slash. Linear scan rather than a regex, for the reason `stripTrailingSlashes` documents.
+ *
+ * Use this instead of calling `neutralizeImplicitOffOrigin` directly anywhere the result is going
+ * to be prefixed or emitted as a path.
+ */
+export declare function toSameOriginPath(url: string): string;
+/**
+ * Whether `url` is something a prefix cannot meaningfully be put in front of.
+ *
+ * Two kinds: **scheme-bearing** (`data:`, `blob:`, `mailto:`, `https://…`) and **literal
+ * protocol-relative** (`//cdn.example.com/x`). Neither is a site-relative path, so rooting or
+ * prefixing them only corrupts them (`data:image/png;…` → `/data:image/png;…`, a broken
+ * `<img src>`).
+ *
+ * NOTE this is deliberately NOT consulted by `joinUrlPrefix` for the scheme half. A URL-space
+ * mount point (`assetUrl`) wants scheme-bearing values handed back untouched; a site ORIGIN
+ * (`resolveSeoUrl`) does not - it must still produce an absolute URL, because a non-absolute
+ * sitemap `<loc>` invalidates the whole sitemap. Letting the two share one rule silently made
+ * `resolveSeoUrl('mailto:a@b.c', { siteUrl })` return `mailto:a@b.c` and drop the origin. Callers
+ * that want the pass-through opt in by checking this themselves.
+ */
+export declare function isUnprefixablePath(url: string): boolean;
+/**
+ * Make `url` safe to emit AS-IS, changing nothing else.
+ *
+ * For a caller with no mount point to apply, which must hand a value back byte-identical wherever
+ * it legitimately can: an `isUnprefixablePath` value passes straight through, and everything else
+ * goes through `toSameOriginPath`, so a value that merely *reads* as off-origin to a browser (the
+ * backslash spellings) is still neutralized rather than passed along.
+ */
+export declare function sanitizeUnprefixedPath(url: string): string;
+/**
+ * Put `prefix` in front of the root-relative `path`, and return `path` untouched when it is
+ * already a declared off-site URL.
+ *
+ * ORDER MATTERS — the absolute check on `path` runs FIRST. An absolute or protocol-relative
+ * value is a deliberate off-site pointer (syndication, a partner-hosted copy, a CDN image) and
+ * must pass through verbatim; prefixing first turns `https://other.org/page` into
+ * `<prefix>/https://other.org/page`.
+ *
+ * `prefix` normalization, in order:
+ * - Empty/undefined, or nothing but slashes (`'/'`, `'///'`) → no prefix at all, so the result
+ *   stays root-relative. This is what makes an unset option a clean no-op. It also kills a
+ *   `'//'` prefix, which would otherwise concatenate to `//assets/…` — read by browsers as
+ *   protocol-relative, i.e. a request to a host literally named `assets`.
+ * - A declared off-site prefix (`https://cdn.example.com`, `//cdn.example.com`) is used as-is.
+ *   A literal protocol-relative prefix is an intentionally-supported off-site pointer here (see
+ *   `utils/sanitize-href.ts`), so it is NOT collapsed to a path.
+ * - Anything else is a same-origin path prefix and is given a leading slash if it lacks one.
+ *   Without this, a prefix like `preview-123` (the shape an env var often carries) produces a
+ *   *document-relative* URL that resolves to a different place on every page — an intermittent
+ *   failure that is harder to diagnose than the plain 404 it replaced.
+ *
+ * `path` is run through `toSameOriginPath` when it is not a pass-through, so a
+ * backslash-equivalent spelling that `isAbsoluteUrl` correctly declines to call "absolute"
+ * (see its doc) can't still be read by a browser as protocol-relative once emitted. Note this
+ * needs the `//`-pathname collapse, not just neutralization — see `toSameOriginPath`.
+ *
+ * `prefix` is NOT neutralized: it is adopter-supplied configuration rather than content, and
+ * neutralizing it would silently rewrite a legitimate protocol-relative CDN base into a path.
+ */
+export declare function joinUrlPrefix(prefix: string | undefined, path: string): string;

package/dist/utils/url-prefix.js

@@ -0,0 +1,158 @@
+/**
+ * Joining a URL prefix onto a root-relative path, in ONE place.
+ *
+ * Two surfaces need the identical operation and had drifted into two implementations:
+ *
+ * - `static/seo.ts`'s `resolveSeoUrl` puts a site origin in front of an entry's URL path.
+ * - `assets/asset-url.ts`'s `assetUrl` puts an asset-space mount point in front of a stored
+ *   `/assets/…` src.
+ *
+ * The asset copy was the weaker one - it checked neither absoluteness of the path nor the shape
+ * of the prefix - so it silently produced `/prefix/https://cdn.example.com/x.png` for an
+ * off-site src, and a *document-relative* URL for a prefix that had no leading slash. Both bugs
+ * were already solved on the SEO side. Sharing one function is what stops a third caller from
+ * inheriting the weaker half again.
+ *
+ * Dependency-free apart from `./sanitize-href` (itself pure - its only dependency is the global
+ * `URL`), because this is reachable from client bundles via `assets/asset-url.ts`. Do not add a
+ * node built-in here; `pnpm lint:bundle` fails the build if you do.
+ */
+import { declaresScheme, neutralizeImplicitOffOrigin } from './sanitize-href.js';
+/**
+ * Whether `url` is a DECLARED off-site pointer - a scheme-qualified absolute URL
+ * (`https://example.com/x`) or a literal protocol-relative one (`//cdn.example.com/x`).
+ *
+ * Deliberately narrower than "resolves off-origin": a WHATWG-backslash-equivalent spelling
+ * (`/\evil.com`, `\\evil.com`, `\/evil.com` — see `utils/sanitize-href.ts`'s
+ * `isImplicitlyOffOrigin`) also resolves off-origin in a browser, but is NOT recognized here as
+ * an intentional off-site pointer the way a literal `//cdn…` is. Callers handle that case
+ * separately, by neutralizing (`neutralizeImplicitOffOrigin`) rather than passing through: a
+ * `false` result here isn't a guarantee the value is a safe site-relative path on its own, only
+ * that it isn't a *declared* off-site one.
+ */
+export function isAbsoluteUrl(url) {
+    return /^[a-z][a-z0-9+.-]*:\/\//i.test(url) || url.startsWith('//');
+}
+/**
+ * Strip trailing slashes without a regex.
+ *
+ * The obvious `replace(/\/+$/, '')` is a polynomial-ReDoS shape (CodeQL
+ * `js/polynomial-redos`, flagged high): on a value that is mostly slashes but does not end in
+ * one, the engine retries `\/+` from every position and the match cost is quadratic in the
+ * input length. Both prefixes that reach here - a `siteUrl` and an asset `baseUrl` - are
+ * adopter-supplied and can come from config or an env var, so they count as uncontrolled. A
+ * character scan is linear and needs no reasoning about backtracking.
+ *
+ * Exported (from `canopycms/server`) so adopter code normalizing its own site-origin env var —
+ * e.g. a `SITE_URL` constant built from `NEXT_PUBLIC_SITE_URL` — has a package-provided linear
+ * way to do it instead of reaching for the same regex this function replaced.
+ */
+export function stripTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 47 /* '/' */)
+        end--;
+    return value.slice(0, end);
+}
+/**
+ * Reduce a URL reference to a value that is safe to emit as a SAME-ORIGIN path.
+ *
+ * `neutralizeImplicitOffOrigin` alone is not sufficient, and this is the subtle part: it returns
+ * `pathname + search + hash`, and a WHATWG `pathname` can ITSELF begin with `//`. `/\evil.com//a`
+ * parses to host `evil.com` with pathname `//a`, so neutralizing yields the string `//a` — which,
+ * re-emitted as a URL reference, reads as protocol-relative all over again and points at a host
+ * literally named `a`. Neutralizing a second time does not help: the value is now indistinguishable
+ * from a caller's legitimate `//cdn.example.com` pointer, so every absolute-URL check downstream
+ * (correctly) passes it straight through, prefix and all.
+ *
+ * The value is same-origin by construction at this point, so collapse the leading slash run to a
+ * single slash. Linear scan rather than a regex, for the reason `stripTrailingSlashes` documents.
+ *
+ * Use this instead of calling `neutralizeImplicitOffOrigin` directly anywhere the result is going
+ * to be prefixed or emitted as a path.
+ */
+export function toSameOriginPath(url) {
+    const neutralized = neutralizeImplicitOffOrigin(url);
+    let slashes = 0;
+    while (slashes < neutralized.length && neutralized.charCodeAt(slashes) === 47 /* '/' */)
+        slashes++;
+    return slashes > 1 ? `/${neutralized.slice(slashes)}` : neutralized;
+}
+/**
+ * Whether `url` is something a prefix cannot meaningfully be put in front of.
+ *
+ * Two kinds: **scheme-bearing** (`data:`, `blob:`, `mailto:`, `https://…`) and **literal
+ * protocol-relative** (`//cdn.example.com/x`). Neither is a site-relative path, so rooting or
+ * prefixing them only corrupts them (`data:image/png;…` → `/data:image/png;…`, a broken
+ * `<img src>`).
+ *
+ * NOTE this is deliberately NOT consulted by `joinUrlPrefix` for the scheme half. A URL-space
+ * mount point (`assetUrl`) wants scheme-bearing values handed back untouched; a site ORIGIN
+ * (`resolveSeoUrl`) does not - it must still produce an absolute URL, because a non-absolute
+ * sitemap `<loc>` invalidates the whole sitemap. Letting the two share one rule silently made
+ * `resolveSeoUrl('mailto:a@b.c', { siteUrl })` return `mailto:a@b.c` and drop the origin. Callers
+ * that want the pass-through opt in by checking this themselves.
+ */
+export function isUnprefixablePath(url) {
+    return declaresScheme(url) || isAbsoluteUrl(url);
+}
+/**
+ * Make `url` safe to emit AS-IS, changing nothing else.
+ *
+ * For a caller with no mount point to apply, which must hand a value back byte-identical wherever
+ * it legitimately can: an `isUnprefixablePath` value passes straight through, and everything else
+ * goes through `toSameOriginPath`, so a value that merely *reads* as off-origin to a browser (the
+ * backslash spellings) is still neutralized rather than passed along.
+ */
+export function sanitizeUnprefixedPath(url) {
+    if (isUnprefixablePath(url))
+        return url;
+    return toSameOriginPath(url);
+}
+/**
+ * Put `prefix` in front of the root-relative `path`, and return `path` untouched when it is
+ * already a declared off-site URL.
+ *
+ * ORDER MATTERS — the absolute check on `path` runs FIRST. An absolute or protocol-relative
+ * value is a deliberate off-site pointer (syndication, a partner-hosted copy, a CDN image) and
+ * must pass through verbatim; prefixing first turns `https://other.org/page` into
+ * `<prefix>/https://other.org/page`.
+ *
+ * `prefix` normalization, in order:
+ * - Empty/undefined, or nothing but slashes (`'/'`, `'///'`) → no prefix at all, so the result
+ *   stays root-relative. This is what makes an unset option a clean no-op. It also kills a
+ *   `'//'` prefix, which would otherwise concatenate to `//assets/…` — read by browsers as
+ *   protocol-relative, i.e. a request to a host literally named `assets`.
+ * - A declared off-site prefix (`https://cdn.example.com`, `//cdn.example.com`) is used as-is.
+ *   A literal protocol-relative prefix is an intentionally-supported off-site pointer here (see
+ *   `utils/sanitize-href.ts`), so it is NOT collapsed to a path.
+ * - Anything else is a same-origin path prefix and is given a leading slash if it lacks one.
+ *   Without this, a prefix like `preview-123` (the shape an env var often carries) produces a
+ *   *document-relative* URL that resolves to a different place on every page — an intermittent
+ *   failure that is harder to diagnose than the plain 404 it replaced.
+ *
+ * `path` is run through `toSameOriginPath` when it is not a pass-through, so a
+ * backslash-equivalent spelling that `isAbsoluteUrl` correctly declines to call "absolute"
+ * (see its doc) can't still be read by a browser as protocol-relative once emitted. Note this
+ * needs the `//`-pathname collapse, not just neutralization — see `toSameOriginPath`.
+ *
+ * `prefix` is NOT neutralized: it is adopter-supplied configuration rather than content, and
+ * neutralizing it would silently rewrite a legitimate protocol-relative CDN base into a path.
+ */
+export function joinUrlPrefix(prefix, path) {
+    // Only a DECLARED off-site pointer passes through. A scheme-bearing but non-absolute value
+    // (`mailto:x`, `data:…`) is rooted, which is what a site origin needs - see
+    // `isUnprefixablePath` for why this deliberately differs from the asset-mount case.
+    if (isAbsoluteUrl(path))
+        return path;
+    const safePath = toSameOriginPath(path);
+    const normalizedPath = safePath.startsWith('/') ? safePath : `/${safePath}`;
+    if (!prefix)
+        return normalizedPath;
+    const trimmedPrefix = stripTrailingSlashes(prefix);
+    if (!trimmedPrefix)
+        return normalizedPath;
+    const normalizedPrefix = isAbsoluteUrl(trimmedPrefix) || trimmedPrefix.startsWith('/')
+        ? trimmedPrefix
+        : `/${trimmedPrefix}`;
+    return `${normalizedPrefix}${normalizedPath}`;
+}

package/dist/validation/block-structural-keys.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The keys a block item carries that are STRUCTURE rather than content.
+ *
+ * A block on disk is `{ template: 'hero', value: { ...fields } }` — the canonical shape the
+ * editor writes and `ContentStore` persists — or, defensively, the inline `{ _type: 'hero',
+ * ...fields }` shape (see `resolveBlockItem` in `./field-traversal`). Either way the
+ * discriminator names the block's TEMPLATE, which is a category label shared by every block of
+ * that kind, not an identifier for this particular block.
+ *
+ * That distinction matters to two callers for opposite-looking reasons, which is why the list
+ * lives here rather than in either of them:
+ *
+ * - `findUnknownKeys` (./entry-validator) must not report the discriminator as a stale key: it
+ *   is not a schema field, but it is supposed to be there.
+ * - `looksLikeSameItem` (../utils/content-serialize) must not accept the discriminator as
+ *   evidence that two list items are the same item: two `hero` blocks share `template: hero`,
+ *   so counting it migrated an editorial comment off a deleted block onto an unrelated
+ *   survivor.
+ *
+ * A single list keeps those two from drifting apart — a third discriminator added for one of
+ * them but not the other would resurrect exactly one of those bugs.
+ *
+ * Note that two other readers deliberately still spell the keys out themselves, because they
+ * READ the discriminator's value positionally rather than testing membership, and they do not
+ * agree on precedence: `resolveBlockItem` prefers `template`, while `ai/json-to-markdown.ts`
+ * prefers `_type`. Reconciling that is a behaviour question, not a refactor — see
+ * `.claude/future-tasks/block-discriminator-precedence-disagreement.md`.
+ *
+ * Dependency-free on purpose: both importers are reachable from contexts that must not pull in
+ * schema types or node built-ins.
+ */
+/**
+ * The discriminator keys, in the precedence `resolveBlockItem` reads them.
+ *
+ * Ordered (rather than a bare Set) so a caller that needs the VALUE can iterate it, and so the
+ * canonical shape's key stays visibly first.
+ */
+export declare const BLOCK_DISCRIMINATOR_KEYS: readonly ["template", "_type"];
+/** Membership form of {@link BLOCK_DISCRIMINATOR_KEYS}, for the two set-test callers. */
+export declare const BLOCK_STRUCTURAL_KEYS: ReadonlySet<string>;
+/** True for a key that names a block's template rather than holding any of its content. */
+export declare function isBlockStructuralKey(key: string): boolean;

package/dist/validation/block-structural-keys.js

@@ -0,0 +1,44 @@
+/**
+ * The keys a block item carries that are STRUCTURE rather than content.
+ *
+ * A block on disk is `{ template: 'hero', value: { ...fields } }` — the canonical shape the
+ * editor writes and `ContentStore` persists — or, defensively, the inline `{ _type: 'hero',
+ * ...fields }` shape (see `resolveBlockItem` in `./field-traversal`). Either way the
+ * discriminator names the block's TEMPLATE, which is a category label shared by every block of
+ * that kind, not an identifier for this particular block.
+ *
+ * That distinction matters to two callers for opposite-looking reasons, which is why the list
+ * lives here rather than in either of them:
+ *
+ * - `findUnknownKeys` (./entry-validator) must not report the discriminator as a stale key: it
+ *   is not a schema field, but it is supposed to be there.
+ * - `looksLikeSameItem` (../utils/content-serialize) must not accept the discriminator as
+ *   evidence that two list items are the same item: two `hero` blocks share `template: hero`,
+ *   so counting it migrated an editorial comment off a deleted block onto an unrelated
+ *   survivor.
+ *
+ * A single list keeps those two from drifting apart — a third discriminator added for one of
+ * them but not the other would resurrect exactly one of those bugs.
+ *
+ * Note that two other readers deliberately still spell the keys out themselves, because they
+ * READ the discriminator's value positionally rather than testing membership, and they do not
+ * agree on precedence: `resolveBlockItem` prefers `template`, while `ai/json-to-markdown.ts`
+ * prefers `_type`. Reconciling that is a behaviour question, not a refactor — see
+ * `.claude/future-tasks/block-discriminator-precedence-disagreement.md`.
+ *
+ * Dependency-free on purpose: both importers are reachable from contexts that must not pull in
+ * schema types or node built-ins.
+ */
+/**
+ * The discriminator keys, in the precedence `resolveBlockItem` reads them.
+ *
+ * Ordered (rather than a bare Set) so a caller that needs the VALUE can iterate it, and so the
+ * canonical shape's key stays visibly first.
+ */
+export const BLOCK_DISCRIMINATOR_KEYS = ['template', '_type'];
+/** Membership form of {@link BLOCK_DISCRIMINATOR_KEYS}, for the two set-test callers. */
+export const BLOCK_STRUCTURAL_KEYS = new Set(BLOCK_DISCRIMINATOR_KEYS);
+/** True for a key that names a block's template rather than holding any of its content. */
+export function isBlockStructuralKey(key) {
+    return BLOCK_STRUCTURAL_KEYS.has(key);
+}

package/dist/validation/deletion-checker.d.ts

@@ -1,7 +1,7 @@
-import type { ContentStore } from '../content-store';
-import type { ContentIdIndex } from '../content-id-index';
-import type { FieldConfig } from '../config';
-import { type LogicalPath, type Slug } from '../paths';
+import type { ContentStore } from '../content-store.js';
+import type { ContentIdIndex } from '../content-id-index.js';
+import type { FieldConfig } from '../config/index.js';
+import { type LogicalPath, type Slug } from '../paths/index.js';
 export interface ReferenceInfo {
     entryPath: string;
     entryTitle?: string;
@@ -63,4 +63,3 @@ export declare class DeletionChecker {
      */
     private listEntriesInCollection;
 }
-//# sourceMappingURL=deletion-checker.d.ts.map

package/dist/validation/deletion-checker.js

@@ -162,4 +162,3 @@ export class DeletionChecker {
         return entries;
     }
 }
-//# sourceMappingURL=deletion-checker.js.map

package/dist/validation/entry-link-validator.d.ts

@@ -6,8 +6,8 @@
  * This parallels ReferenceValidator but operates on inline links in text content
  * rather than structured reference fields.
  */
-import type { ContentIdIndex } from '../content-id-index';
-import type { FieldConfig } from '../config';
+import type { ContentIdIndex } from '../content-id-index.js';
+import type { FieldConfig } from '../config/index.js';
 export interface EntryLinkWarning {
     field: string;
     fieldPath: string;
@@ -24,4 +24,3 @@ export interface EntryLinkValidationResult {
  * and checks that each referenced ID exists in the content index.
  */
 export declare function validateEntryLinks(data: Record<string, unknown>, schema: readonly FieldConfig[], idIndex: ContentIdIndex, bodyContent?: string): EntryLinkValidationResult;
-//# sourceMappingURL=entry-link-validator.d.ts.map

package/dist/validation/entry-link-validator.js

@@ -46,4 +46,3 @@ function checkText(text, fieldName, fieldPath, idIndex, warnings) {
         }
     }
 }
-//# sourceMappingURL=entry-link-validator.js.map

package/dist/validation/entry-type-reference-validator.d.ts

@@ -13,7 +13,7 @@
  * at entry-schema *registration* (entry-schema-registry.ts), before any branch
  * schema exists, and so cannot perform this check.
  */
-import type { RootCollectionConfig } from '../config';
+import type { RootCollectionConfig } from '../config/index.js';
 /**
  * Collect every entry type name defined anywhere in the schema.
  *
@@ -30,4 +30,3 @@ export declare const collectEntryTypeNames: (schema: RootCollectionConfig) => Se
  * @returns One human-readable message per offending value; empty when valid.
  */
 export declare const validateReferenceEntryTypes: (schema: RootCollectionConfig) => string[];
-//# sourceMappingURL=entry-type-reference-validator.d.ts.map

package/dist/validation/entry-type-reference-validator.js

@@ -107,4 +107,3 @@ export const validateReferenceEntryTypes = (schema) => {
     });
     return issues;
 };
-//# sourceMappingURL=entry-type-reference-validator.js.map

package/dist/validation/entry-validator.d.ts

@@ -21,7 +21,7 @@
  * content ID index (filesystem) and is enforced server-side only, by running
  * `ReferenceValidator` at the write boundary.
  */
-import type { ContentFormat, EntrySchema } from '../config';
+import type { ContentFormat, EntrySchema } from '../config/index.js';
 /**
  * One per-field validation error. `fieldPath` uses the canonical CanopyCMS
  * path format shared with field-traversal and the editor's canopy-path
@@ -56,6 +56,28 @@ export declare function validateEntryData(fields: EntrySchema, data: Record<stri
  * schema's body field before validating so required/type checks see it.
  */
 export declare function validateEntryFormValue(fields: EntrySchema, format: ContentFormat | undefined, value: Record<string, unknown>): EntryFieldError[];
+/**
+ * Find data keys that have no counterpart in the schema, as canonical field paths
+ * (`author.nickname`, `blocks[2].headline`).
+ *
+ * `validateEntryData` iterates the SCHEMA, so it can only ever report fields the schema knows
+ * about. Nothing reported the inverse: rename or reshape a field and the old key persists on
+ * disk forever, because the editor's form state is the whole record verbatim and every save
+ * posts it back. The only symptom is a component quietly receiving `undefined`.
+ *
+ * Pure — safe in the browser. Reports rather than rejects: a save carrying a stale key still
+ * succeeds (and now the write path even preserves the key and its comments), so this feeds the
+ * non-blocking `validationWarnings` channel, not the 422 path.
+ *
+ * Two things it deliberately does not report:
+ *
+ * - **A container with no fields at all.** `api/content.ts` falls back to `[]` for a collection
+ *   with no configured entry type; "no schema" is not "every key is unknown".
+ * - **Anything inside a `reference` value.** Reads resolve references by default, so a reference
+ *   field's value is `{ ...target data, id, slug, collection, urlPath }`. The traversal only
+ *   descends into `object` and `block`, so it never looks inside one.
+ */
+export declare function findUnknownKeys(fields: EntrySchema, data: Record<string, unknown>): string[];
 /**
  * Return a copy of `data` with resolved reference objects (`{ id, ... }`)
  * collapsed back to their id strings, recursing through objects, lists, and
@@ -64,4 +86,3 @@ export declare function validateEntryFormValue(fields: EntrySchema, format: Cont
  * that may still carry resolved objects from a prior read.
  */
 export declare function normalizeReferenceValues(fields: EntrySchema, data: Record<string, unknown>): Record<string, unknown>;
-//# sourceMappingURL=entry-validator.d.ts.map

package/dist/validation/entry-validator.js

@@ -23,8 +23,10 @@
  */
 import { fieldTypes } from '../config/index.js';
 import { isValidCropRect } from '../assets/transform-directives.js';
-import { resolveBlockItem } from './field-traversal.js';
+import { BLOCK_STRUCTURAL_KEYS } from './block-structural-keys.js';
+import { resolveBlockItem, traverseFields } from './field-traversal.js';
 import { findBodyFieldName } from '../utils/body-field.js';
+import { flattenGroupFields } from '../utils/flatten-group-fields.js';
 import { isDataOnlyFormat } from '../utils/format.js';
 const KNOWN_FIELD_TYPES = new Set(fieldTypes);
 /** Field types whose value is a plain string. */
@@ -273,6 +275,37 @@ export function validateEntryFormValue(fields, format, value) {
     }
     return validateEntryData(fields, value);
 }
+/**
+ * Find data keys that have no counterpart in the schema, as canonical field paths
+ * (`author.nickname`, `blocks[2].headline`).
+ *
+ * `validateEntryData` iterates the SCHEMA, so it can only ever report fields the schema knows
+ * about. Nothing reported the inverse: rename or reshape a field and the old key persists on
+ * disk forever, because the editor's form state is the whole record verbatim and every save
+ * posts it back. The only symptom is a component quietly receiving `undefined`.
+ *
+ * Pure — safe in the browser. Reports rather than rejects: a save carrying a stale key still
+ * succeeds (and now the write path even preserves the key and its comments), so this feeds the
+ * non-blocking `validationWarnings` channel, not the 422 path.
+ *
+ * Two things it deliberately does not report:
+ *
+ * - **A container with no fields at all.** `api/content.ts` falls back to `[]` for a collection
+ *   with no configured entry type; "no schema" is not "every key is unknown".
+ * - **Anything inside a `reference` value.** Reads resolve references by default, so a reference
+ *   field's value is `{ ...target data, id, slug, collection, urlPath }`. The traversal only
+ *   descends into `object` and `block`, so it never looks inside one.
+ */
+export function findUnknownKeys(fields, data) {
+    return traverseFields(fields, data, () => [], '', ({ fields: containerFields, data: record, path }) => {
+        if (containerFields.length === 0)
+            return [];
+        const known = new Set(flattenGroupFields(containerFields).map((field) => field.name));
+        return Object.keys(record)
+            .filter((key) => !known.has(key) && !BLOCK_STRUCTURAL_KEYS.has(key))
+            .map((key) => (path ? `${path}.${key}` : key));
+    });
+}
 /**
  * Return a copy of `data` with resolved reference objects (`{ id, ... }`)
  * collapsed back to their id strings, recursing through objects, lists, and
@@ -329,4 +362,3 @@ export function normalizeReferenceValues(fields, data) {
     }
     return result;
 }
-//# sourceMappingURL=entry-validator.js.map

package/dist/validation/field-traversal.d.ts

@@ -5,7 +5,7 @@
  * according to a schema, handling objects, blocks, and arrays with their
  * own schemas.
  */
-import type { FieldConfig, BlockFieldConfig } from '../config';
+import type { FieldConfig, BlockFieldConfig } from '../config/index.js';
 /**
  * Context provided to the visitor function for each field.
  */
@@ -22,6 +22,26 @@ export interface TraversalContext {
  * Return an empty array to skip this field, or return items to collect.
  */
 export type FieldVisitor<T> = (context: TraversalContext) => T[];
+/**
+ * Context for a CONTAINER — one data record together with the field list that governs it.
+ *
+ * The field visitor is driven by the schema, so it can only ever see keys the schema already
+ * knows about. A container visitor sees the record itself, which is what a check on the data's
+ * OWN keys needs (`findUnknownKeys` in entry-validator.ts).
+ */
+export interface ContainerContext {
+    /** The schema fields governing this record. Inline groups are NOT flattened. */
+    fields: readonly FieldConfig[];
+    /** The data record those fields govern. */
+    data: Record<string, unknown>;
+    /** Path to the record itself ('' at the top level, e.g. `blocks[0]` inside a block). */
+    path: string;
+}
+/**
+ * Visitor called once per container, before its fields are walked.
+ * Return an empty array to collect nothing.
+ */
+export type ContainerVisitor<T> = (context: ContainerContext) => T[];
 /**
  * A block item resolved to its template fields and the data record that
  * holds the nested field values.
@@ -58,7 +78,12 @@ export declare function resolveBlockItem(blockField: BlockFieldConfig, item: Rec
  * @param data - The data object to traverse
  * @param visitor - Function called for each field, returns items to collect
  * @param pathPrefix - Current path prefix for nested fields
- * @returns Array of all items returned by the visitor
+ * @param onContainer - Optional, called once per container (this record plus the fields
+ *   governing it) before its fields are walked: the top level, each object value, each
+ *   object-list item, and each block item's resolved data. Inline groups do NOT fire it — a
+ *   group is transparent to the data and shares its parent's record, so its children are already
+ *   covered by the parent's container call.
+ * @returns Array of all items returned by the visitors
  *
  * @example
  * ```ts
@@ -71,7 +96,7 @@ export declare function resolveBlockItem(blockField: BlockFieldConfig, item: Rec
  * })
  * ```
  */
-export declare function traverseFields<T>(fields: readonly FieldConfig[], data: Record<string, unknown>, visitor: FieldVisitor<T>, pathPrefix?: string): T[];
+export declare function traverseFields<T>(fields: readonly FieldConfig[], data: Record<string, unknown>, visitor: FieldVisitor<T>, pathPrefix?: string, onContainer?: ContainerVisitor<T>): T[];
 /**
  * Find all fields of a specific type in the data.
  *
@@ -81,4 +106,3 @@ export declare function traverseFields<T>(fields: readonly FieldConfig[], data:
  * @returns Array of { field, value, path } for matching fields
  */
 export declare function findFieldsByType(fields: readonly FieldConfig[], data: Record<string, unknown>, fieldType: string): TraversalContext[];
-//# sourceMappingURL=field-traversal.d.ts.map