@byline/core 4.3.0 → 4.4.0

package/dist/paths/parse-path.js

@@ -0,0 +1,133 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+// ---------------------------------------------------------------------------
+// Parsing and serialising field paths.
+//
+// Parsing is schema-unaware: it recovers structure from text and nothing
+// more. In particular it cannot tell a block type from a field name, since
+// both are bare identifiers — `resolveDeclarationPath` settles that against
+// a field set. Callers that already hold the schema (path *producers*) should
+// build segments directly and use the formatters here.
+// ---------------------------------------------------------------------------
+const INDEX_TOKEN = /^\[(\d+)\]$/;
+const ID_TOKEN = /^\[id=(.+)\]$/;
+/**
+ * Parse a declaration path: dotted, index-free, block types written as plain
+ * segments (`content.photoBlock.gallery.alt`).
+ *
+ * Every segment comes back as `kind: 'field'`. Item indices are a parse
+ * error rather than something silently dropped — a caller writing
+ * `files[0].caption` where a declaration is expected has made a category
+ * mistake, and saying so is more useful than quietly addressing every item.
+ */
+export function parseDeclarationPath(path) {
+    if (path.trim() === '')
+        return { ok: false, reason: 'empty' };
+    if (path.includes('[') || path.includes(']'))
+        return { ok: false, reason: 'index' };
+    const segments = [];
+    for (const part of path.split('.')) {
+        if (part === '')
+            return { ok: false, reason: 'emptySegment' };
+        segments.push({ kind: 'field', name: part });
+    }
+    return { ok: true, segments };
+}
+/**
+ * Parse an instance path: dotted field names with bracket item selectors,
+ * either positional (`gallery[1]`) or by stable id (`gallery[id=abc]`).
+ *
+ * Blocks carry no discriminator here — the addressed item resolves its own
+ * `_type` — so a block hop is just the blocks field name followed by an
+ * item selector.
+ */
+export function parseInstancePath(path) {
+    if (path.trim() === '')
+        return { ok: false, reason: 'empty' };
+    const segments = [];
+    for (const part of path.split('.')) {
+        if (part === '')
+            return { ok: false, reason: 'emptySegment' };
+        const bracket = part.indexOf('[');
+        if (bracket === -1) {
+            if (part.includes(']'))
+                return { ok: false, reason: 'malformed' };
+            segments.push({ kind: 'field', name: part });
+            continue;
+        }
+        const name = part.slice(0, bracket);
+        if (name === '')
+            return { ok: false, reason: 'emptySegment' };
+        segments.push({ kind: 'field', name });
+        // One segment may carry several selectors (`items[0][1]` is not produced
+        // today, but parsing it costs nothing and beats silently truncating).
+        let rest = part.slice(bracket);
+        while (rest !== '') {
+            const close = rest.indexOf(']');
+            if (close === -1)
+                return { ok: false, reason: 'malformed' };
+            const token = rest.slice(0, close + 1);
+            rest = rest.slice(close + 1);
+            const indexMatch = INDEX_TOKEN.exec(token);
+            if (indexMatch?.[1] != null) {
+                segments.push({ kind: 'index', index: Number.parseInt(indexMatch[1], 10) });
+                continue;
+            }
+            const idMatch = ID_TOKEN.exec(token);
+            if (idMatch?.[1] != null) {
+                segments.push({ kind: 'id', id: idMatch[1] });
+                continue;
+            }
+            return { ok: false, reason: 'malformed' };
+        }
+    }
+    return { ok: true, segments };
+}
+/**
+ * Serialise segments as a declaration path. Index and id segments are
+ * dropped, so this doubles as the instance → declaration projection when
+ * applied to instance segments.
+ */
+export function formatDeclarationPath(segments) {
+    return segments
+        .filter((segment) => segment.kind === 'field' || segment.kind === 'blockType')
+        .map((segment) => (segment.kind === 'blockType' ? segment.blockType : segment.name))
+        .join('.');
+}
+/** Serialise segments as an instance path, rendering selectors in brackets. */
+export function formatInstancePath(segments) {
+    let out = '';
+    for (const segment of segments) {
+        switch (segment.kind) {
+            case 'field':
+                out += out === '' ? segment.name : `.${segment.name}`;
+                break;
+            case 'blockType':
+                // Instance paths carry no discriminator; the item knows its own type.
+                break;
+            case 'index':
+                out += `[${segment.index}]`;
+                break;
+            case 'id':
+                out += `[id=${segment.id}]`;
+                break;
+        }
+    }
+    return out;
+}
+/**
+ * Drop the item selectors from a path, leaving the declaration it addresses.
+ *
+ * This is the projection several call sites hand-roll with a regex today.
+ * Doing it over segments rather than raw text is what makes it safe: a field
+ * legitimately named `0` is a `field` segment and survives, where a
+ * string-level `/^\d+$/` filter would silently delete it.
+ */
+export function toDeclarationSegments(segments) {
+    return segments.filter((segment) => segment.kind === 'field' || segment.kind === 'blockType');
+}

package/dist/paths/path-dialects.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/paths/path-dialects.test.node.js

@@ -0,0 +1,267 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { describe, expect, it } from 'vitest';
+import { prepareHookAttachment } from '../config/attach-hooks.js';
+import { validateAdminConfigs, validateBlockAdminConfigs, } from '../config/validate-admin-configs.js';
+import { validateCollections } from '../config/validate-collections.js';
+import { parsePatchPath } from '../patches/apply-patches.js';
+// ---------------------------------------------------------------------------
+// Characterization tests for Byline's field-path notations.
+//
+// Several subsystems address fields by dotted path, and they do NOT all use
+// the same grammar. This file pins the CURRENT behaviour of each so that the
+// reconciliation work (see PATH-GRAMMAR-ANALYSIS-AND-RECONCILIATION.md) either
+// preserves it or changes it visibly and on purpose.
+//
+// The organising model — the two categories these dialects fall into:
+//
+//   * INSTANCE paths address a value in one item of one document. Indices are
+//     required. The block type is redundant: the item carries its own `_type`.
+//   * DECLARATION paths address a field declaration in the schema. There are
+//     no indices. The block type IS required — without it, two blocks in the
+//     same field that declare the same field name are indistinguishable.
+//
+// The dialects do not all agree yet. Where one is deliberately narrower than
+// the grammar (admin `fields{}` barring block traversal) the comment says so;
+// where one is still being brought into line, it cites the phase that moves
+// it. A failure here means a dialect changed — check it was on purpose.
+// ---------------------------------------------------------------------------
+/**
+ * One fixture, exercising every structural combination the dialects differ
+ * over: array→group nesting, a blocks field, an array inside a block, an
+ * upload field inside a block, and — critically — two block types that each
+ * declare a field named `alt`, which is what makes an unqualified path
+ * ambiguous.
+ */
+const fixture = (overrides = {}) => ({
+    path: 'pages',
+    labels: { singular: 'Page', plural: 'Pages' },
+    useAsTitle: 'title',
+    fields: [
+        { name: 'title', label: 'Title', type: 'text' },
+        {
+            name: 'files',
+            label: 'Files',
+            type: 'array',
+            fields: [
+                {
+                    name: 'filesGroup',
+                    type: 'group',
+                    fields: [
+                        { name: 'publicationFile', label: 'File', type: 'file', upload: {} },
+                        { name: 'caption', label: 'Caption', type: 'text' },
+                    ],
+                },
+            ],
+        },
+        {
+            name: 'content',
+            label: 'Content',
+            type: 'blocks',
+            blocks: [
+                {
+                    blockType: 'photoBlock',
+                    fields: [
+                        { name: 'display', label: 'Display', type: 'text' },
+                        {
+                            name: 'gallery',
+                            label: 'Gallery',
+                            type: 'array',
+                            fields: [
+                                {
+                                    name: 'alt',
+                                    label: 'Alt',
+                                    type: 'text',
+                                    ...(overrides.altVirtual === true ? { virtual: true } : {}),
+                                },
+                                { name: 'heroImage', label: 'Hero', type: 'image', upload: {} },
+                            ],
+                        },
+                    ],
+                },
+                // Same leaf name (`alt`) as photoBlock's gallery child. This is the
+                // collision that an unqualified declaration path cannot resolve.
+                {
+                    blockType: 'videoBlock',
+                    fields: [{ name: 'alt', label: 'Alt', type: 'text' }],
+                },
+            ],
+        },
+    ],
+});
+// ---------------------------------------------------------------------------
+// Dialect 1 — upload hook registry keys (DECLARATION paths)
+//
+// Produced by `indexUploadFields` (config/attach-hooks.ts), consumed as the
+// keys of `ServerConfig.hooks.uploads`. Collection-prefixed, index-free, and
+// block types are named explicitly. This is the only dialect that gets
+// declaration paths fully right today.
+// ---------------------------------------------------------------------------
+describe('path dialect — upload hook registry keys', () => {
+    const register = (key) => () => prepareHookAttachment({
+        collections: [fixture()],
+        hooks: { uploads: { [key]: async () => ({}) } },
+    });
+    // Rejections assert on the message, not merely that something threw — a
+    // bare try/catch would let an unrelated failure masquerade as the
+    // path-resolution rejection under test.
+    const unresolved = /references unknown or non-upload field/;
+    it('addresses a nested upload field with a collection-prefixed declaration path', () => {
+        expect(register('pages.files.filesGroup.publicationFile')).not.toThrow();
+    });
+    it('qualifies a path through a blocks field with the block type', () => {
+        // The other half of the elision claim. `storage-paths.test.node.ts` in
+        // @byline/db-postgres derives this exact declaration path from real
+        // flattener output by dropping index segments; here the real registry
+        // accepts it. Neither package can import the other's half, so the two
+        // tests meet at this literal.
+        expect(register('pages.content.photoBlock.gallery.heroImage')).not.toThrow();
+    });
+    it('rejects the same path with the block type omitted', () => {
+        expect(register('pages.content.gallery.heroImage')).toThrow(unresolved);
+    });
+    it('rejects item indices — these address declarations, not instances', () => {
+        expect(register('pages.content.0.photoBlock.gallery.heroImage')).toThrow(unresolved);
+    });
+});
+// ---------------------------------------------------------------------------
+// Dialect 2 — admin `fields{}` override keys (DECLARATION paths, blocks barred)
+//
+// Consumed by `resolveSchemaPath` (config/validate-admin-configs.ts). Same
+// declaration-addressing as the registry, plus one deliberate policy: keys
+// may not traverse a `blocks` field at all, because fields inside a block
+// take their overrides from the blockType-keyed `blockAdmin` registry so that
+// one registration applies wherever the block renders.
+// ---------------------------------------------------------------------------
+describe('path dialect — admin fields{} override keys', () => {
+    const admin = (key) => ({ slug: 'pages', fields: { [key]: {} } });
+    const validate = (key) => () => validateAdminConfigs([admin(key)], [fixture()]);
+    it('accepts a top-level field name', () => {
+        expect(validate('title')).not.toThrow();
+    });
+    it('accepts a declaration path through array and group structure', () => {
+        expect(validate('files.filesGroup.caption')).not.toThrow();
+    });
+    it('rejects an item index, naming the instance-path confusion', () => {
+        expect(validate('files[0].filesGroup.caption')).toThrow(/index-free schema paths/);
+    });
+    it('rejects traversal into a block even when correctly block-qualified', () => {
+        expect(validate('content.photoBlock.alt')).toThrow(/blockAdmin/);
+    });
+    it('rejects traversal into a block when unqualified', () => {
+        expect(validate('content.alt')).toThrow(/blockAdmin/);
+    });
+    it('rejects a path that walks through a value field', () => {
+        expect(validate('title.anything')).toThrow(/does not resolve to a field declaration/);
+    });
+});
+describe('path dialect — block admin fields{} override keys', () => {
+    const validate = (blockType, key) => () => validateBlockAdminConfigs([{ blockType, fields: { [key]: {} } }], [fixture()]);
+    it('accepts a top-level field name of the block', () => {
+        expect(validate('photoBlock', 'display')).not.toThrow();
+    });
+    it('accepts a declaration path through the block’s array structure', () => {
+        expect(validate('photoBlock', 'gallery.alt')).not.toThrow();
+    });
+    it('rejects a key that does not resolve within the block', () => {
+        expect(validate('photoBlock', 'gallery.missing')).toThrow(/does not resolve to a field declaration/);
+    });
+    it('resolves keys relative to the block root, not the collection', () => {
+        // `content.photoBlock.gallery.alt` is the collection-rooted path; from the
+        // block root the same field is just `gallery.alt`.
+        expect(validate('photoBlock', 'content.photoBlock.gallery.alt')).toThrow(/does not resolve to a field declaration/);
+    });
+});
+// ---------------------------------------------------------------------------
+// Dialect 3 — boot-validation error message paths (DECLARATION paths)
+//
+// Produced by `walkFieldsWithPath` (config/validate-collections.ts) and
+// interpolated into user-facing error messages. Now delegates to the shared
+// grammar's `walkFieldDeclarations`, so it agrees with the upload registry.
+// ---------------------------------------------------------------------------
+describe('path dialect — boot-validation error message paths', () => {
+    /** The field path quoted in the virtual-field error, or null. */
+    const pathInError = () => {
+        try {
+            validateCollections([fixture({ altVirtual: true })]);
+            return null;
+        }
+        catch (error) {
+            const match = error.message.match(/virtual field "([^"]+)"/);
+            return match?.[1] ?? null;
+        }
+    };
+    it('qualifies the path with the block type', () => {
+        expect(pathInError()).toBe('content.photoBlock.gallery.alt');
+    });
+    it('identifies which block declaration is at fault', () => {
+        // The fixture declares `alt` in both photoBlock and videoBlock. Before the
+        // block type was carried through, both rendered as `content.alt` and the
+        // message could not say which declaration it meant.
+        expect(pathInError()).toContain('photoBlock');
+    });
+});
+// ---------------------------------------------------------------------------
+// Dialect 4 — patch paths (INSTANCE paths)
+//
+// Parsed by `parsePatchPath` (patches/apply-patches.ts). Bracket indices, or
+// `[id=…]` for stable item identity. Blocks are transparent: no block-type
+// segment, because the addressed item carries its own `_type`.
+// ---------------------------------------------------------------------------
+describe('path dialect — patch paths', () => {
+    it('addresses array items by positional bracket index', () => {
+        expect(parsePatchPath('content[0].gallery[1].alt')).toEqual([
+            { kind: 'field', key: 'content' },
+            { kind: 'index', index: 0 },
+            { kind: 'field', key: 'gallery' },
+            { kind: 'index', index: 1 },
+            { kind: 'field', key: 'alt' },
+        ]);
+    });
+    it('addresses array items by stable id', () => {
+        expect(parsePatchPath('content[id=abc].gallery[id=def].alt')).toEqual([
+            { kind: 'field', key: 'content' },
+            { kind: 'id', id: 'abc' },
+            { kind: 'field', key: 'gallery' },
+            { kind: 'id', id: 'def' },
+            { kind: 'field', key: 'alt' },
+        ]);
+    });
+    it('carries no block-type segment — the item resolves its own type', () => {
+        const segments = parsePatchPath('content[0].alt');
+        expect(segments).not.toContainEqual({ kind: 'field', key: 'photoBlock' });
+    });
+    it('cannot consume a storage path — dotted indices become field names', () => {
+        // Storage emits `content.0.photoBlock.display`. Fed to the patch parser,
+        // the index and block type silently become field keys. Not currently
+        // reachable in product code, but nothing prevents it.
+        expect(parsePatchPath('content.0.photoBlock.display')).toEqual([
+            { kind: 'field', key: 'content' },
+            { kind: 'field', key: '0' },
+            { kind: 'field', key: 'photoBlock' },
+            { kind: 'field', key: 'display' },
+        ]);
+    });
+});
+// ---------------------------------------------------------------------------
+// Cross-dialect — the relationship the reconciliation is built on
+// ---------------------------------------------------------------------------
+describe('path dialects — cross-dialect relationships', () => {
+    it('registry keys and admin keys agree on non-block structure', () => {
+        // The same declaration, addressed by two dialects, differs only by the
+        // collection prefix — no divergence in how group/array nesting is spelled.
+        const registryKey = 'pages.files.filesGroup.publicationFile';
+        const adminKey = 'files.filesGroup.publicationFile';
+        expect(registryKey).toBe(`pages.${adminKey}`);
+        expect(() => prepareHookAttachment({
+            collections: [fixture()],
+            hooks: { uploads: { [registryKey]: async () => ({}) } },
+        })).not.toThrow();
+        expect(() => validateAdminConfigs([{ slug: 'pages', fields: { [adminKey]: {} } }], [fixture()])).not.toThrow();
+    });
+});

package/dist/paths/path-types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { Field } from '../@types/index.js';
+/**
+ * One step along a field path.
+ *
+ * `field` and `blockType` are indistinguishable in source text — both are
+ * bare identifiers. Parsing is schema-unaware and therefore produces only
+ * `field` segments; `resolveDeclarationPath` reclassifies them against a
+ * field set. Producers walking a schema (see `walkFieldDeclarations`) know
+ * the difference and emit the correct kind directly.
+ */
+export type PathSegment = {
+    readonly kind: 'field';
+    readonly name: string;
+} | {
+    readonly kind: 'blockType';
+    readonly blockType: string;
+} | {
+    readonly kind: 'index';
+    readonly index: number;
+} | {
+    readonly kind: 'id';
+    readonly id: string;
+};
+/** Why a path string failed to parse. */
+export type PathParseFailure = 
+/** The whole path was empty or whitespace. */
+'empty'
+/** A segment between dots was empty (`a..b`, `.a`, `a.`). */
+ | 'emptySegment'
+/** A declaration path carried an item index (`files[0].caption`). */
+ | 'index'
+/** Bracket syntax present but unparseable (`a[`, `a[]`, `a[x]`). */
+ | 'malformed';
+export type PathParseResult = {
+    readonly ok: true;
+    readonly segments: readonly PathSegment[];
+} | {
+    readonly ok: false;
+    readonly reason: PathParseFailure;
+};
+/**
+ * Outcome of resolving a declaration path against a field set.
+ *
+ * `blocks` is distinct from `unresolved` because the two warrant different
+ * guidance: a path that correctly names a block type but is used where block
+ * traversal is barred should point the author at the `blockAdmin` registry,
+ * not tell them their path is wrong.
+ */
+export type PathResolution = 
+/** Resolved to a field declaration. `segments` carry block types correctly classified. */
+{
+    readonly status: 'ok';
+    readonly field: Field;
+    readonly segments: readonly PathSegment[];
+}
+/** Traversal reached a `blocks` field while `blocks: 'forbidden'` was in effect. */
+ | {
+    readonly status: 'blocks';
+    readonly at: number;
+}
+/** A segment named nothing, or a value field appeared mid-path. */
+ | {
+    readonly status: 'unresolved';
+    readonly at: number;
+};
+export interface ResolveOptions {
+    /**
+     * How to treat a `blocks` field encountered mid-path.
+     *
+     * - `'qualified'` (default) — descend, consuming the next segment as a
+     *   block type. This is the grammar's normal behaviour, used by the upload
+     *   hook registry.
+     * - `'forbidden'` — stop and report `status: 'blocks'`. Used by the admin
+     *   `fields{}` maps, where per-field overrides inside a block belong to the
+     *   blockType-keyed `blockAdmin` registry so that one registration applies
+     *   wherever the block renders.
+     */
+    readonly blocks?: 'qualified' | 'forbidden';
+}

package/dist/paths/path-types.js

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/paths/paths.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};