@byline/core 4.3.0 → 4.4.1

package/dist/paths/paths.test.node.js

@@ -0,0 +1,339 @@
+/**
+ * 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 { validateAdminConfigs } from '../config/validate-admin-configs.js';
+import { formatDeclarationPath, formatInstancePath, parseDeclarationPath, parseInstancePath, resolveDeclarationPath, toDeclarationSegments, walkFieldDeclarations, } from './index.js';
+// The same structural shape the characterization suite uses: array→group
+// nesting, a blocks field, an array inside a block, and two block types that
+// each declare `alt` — the collision an unqualified path cannot resolve.
+const fields = [
+    { name: 'title', label: 'Title', type: 'text' },
+    {
+        name: 'files',
+        label: 'Files',
+        type: 'array',
+        fields: [
+            {
+                name: 'filesGroup',
+                type: 'group',
+                fields: [{ name: 'caption', label: 'Caption', type: 'text' }],
+            },
+        ],
+    },
+    {
+        name: 'content',
+        label: 'Content',
+        type: 'blocks',
+        blocks: [
+            {
+                blockType: 'photoBlock',
+                fields: [
+                    {
+                        name: 'gallery',
+                        label: 'Gallery',
+                        type: 'array',
+                        fields: [{ name: 'alt', label: 'Alt', type: 'text' }],
+                    },
+                ],
+            },
+            { blockType: 'videoBlock', fields: [{ name: 'alt', label: 'Alt', type: 'text' }] },
+        ],
+    },
+];
+describe('parseDeclarationPath', () => {
+    it('splits a dotted path into field segments', () => {
+        expect(parseDeclarationPath('files.filesGroup.caption')).toEqual({
+            ok: true,
+            segments: [
+                { kind: 'field', name: 'files' },
+                { kind: 'field', name: 'filesGroup' },
+                { kind: 'field', name: 'caption' },
+            ],
+        });
+    });
+    it('cannot classify a block type on its own — that needs the schema', () => {
+        // `photoBlock` comes back as a field segment. Only resolution against a
+        // field set can tell it apart from a field of the same name.
+        const parsed = parseDeclarationPath('content.photoBlock.gallery.alt');
+        expect(parsed.ok && parsed.segments.every((s) => s.kind === 'field')).toBe(true);
+    });
+    it('rejects item indices rather than silently dropping them', () => {
+        expect(parseDeclarationPath('files[0].filesGroup.caption')).toEqual({
+            ok: false,
+            reason: 'index',
+        });
+    });
+    it('distinguishes a stray bracket from a wrong-dialect index', () => {
+        // `index` steers the author from instance notation to declaration
+        // notation; that advice is misleading for what is only a typo.
+        expect(parseDeclarationPath('files].caption')).toEqual({ ok: false, reason: 'malformed' });
+    });
+    it('rejects empty paths and empty segments', () => {
+        expect(parseDeclarationPath('')).toEqual({ ok: false, reason: 'empty' });
+        expect(parseDeclarationPath('   ')).toEqual({ ok: false, reason: 'empty' });
+        expect(parseDeclarationPath('a..b')).toEqual({ ok: false, reason: 'emptySegment' });
+        expect(parseDeclarationPath('.a')).toEqual({ ok: false, reason: 'emptySegment' });
+        expect(parseDeclarationPath('a.')).toEqual({ ok: false, reason: 'emptySegment' });
+    });
+});
+describe('parseInstancePath', () => {
+    it('reads positional item selectors', () => {
+        expect(parseInstancePath('content[0].gallery[1].alt')).toEqual({
+            ok: true,
+            segments: [
+                { kind: 'field', name: 'content' },
+                { kind: 'index', index: 0 },
+                { kind: 'field', name: 'gallery' },
+                { kind: 'index', index: 1 },
+                { kind: 'field', name: 'alt' },
+            ],
+        });
+    });
+    it('reads stable-id item selectors', () => {
+        expect(parseInstancePath('content[id=abc].alt')).toEqual({
+            ok: true,
+            segments: [
+                { kind: 'field', name: 'content' },
+                { kind: 'id', id: 'abc' },
+                { kind: 'field', name: 'alt' },
+            ],
+        });
+    });
+    it('rejects malformed bracket syntax instead of truncating', () => {
+        for (const bad of ['a[', 'a[]', 'a[x]', 'a]b']) {
+            expect(parseInstancePath(bad).ok).toBe(false);
+        }
+    });
+    it('rejects an id containing a closing bracket rather than truncating it', () => {
+        // Ids are UUIDv7 today, so this is unreachable in practice. Pinned because
+        // the id token is scanned to the first `]`: the guarantee worth holding is
+        // that an id which somehow contains one is rejected outright, never
+        // silently shortened into a different — and possibly valid — id.
+        expect(parseInstancePath('gallery[id=a]b].alt').ok).toBe(false);
+    });
+});
+describe('formatting', () => {
+    it('round-trips a declaration path', () => {
+        const parsed = parseDeclarationPath('files.filesGroup.caption');
+        expect(parsed.ok && formatDeclarationPath(parsed.segments)).toBe('files.filesGroup.caption');
+    });
+    it('round-trips an instance path', () => {
+        const parsed = parseInstancePath('content[0].gallery[1].alt');
+        expect(parsed.ok && formatInstancePath(parsed.segments)).toBe('content[0].gallery[1].alt');
+    });
+    it('renders a block type in declaration form and omits it in instance form', () => {
+        const segments = [
+            { kind: 'field', name: 'content' },
+            { kind: 'blockType', blockType: 'photoBlock' },
+            { kind: 'field', name: 'alt' },
+        ];
+        expect(formatDeclarationPath(segments)).toBe('content.photoBlock.alt');
+        expect(formatInstancePath(segments)).toBe('content.alt');
+    });
+});
+describe('toDeclarationSegments', () => {
+    it('drops item selectors and keeps the block type', () => {
+        const parsed = parseInstancePath('content[0].gallery[1].alt');
+        expect(parsed.ok && formatDeclarationPath(toDeclarationSegments(parsed.segments))).toBe('content.gallery.alt');
+    });
+    it('preserves a field whose name is numeric', () => {
+        // The regex-over-text approach each call site hand-rolls today deletes
+        // this segment. Working over typed segments cannot: `0` here is a field.
+        const parsed = parseInstancePath('weird.0.value');
+        expect(parsed.ok && formatDeclarationPath(toDeclarationSegments(parsed.segments))).toBe('weird.0.value');
+    });
+});
+describe('walkFieldDeclarations', () => {
+    const collect = () => {
+        const out = [];
+        walkFieldDeclarations(fields, (_field, segments) => {
+            out.push(formatDeclarationPath(segments));
+        });
+        return out;
+    };
+    it('qualifies paths through a blocks field with the block type', () => {
+        expect(collect()).toEqual(expect.arrayContaining([
+            'title',
+            'files.filesGroup.caption',
+            'content.photoBlock.gallery.alt',
+            'content.videoBlock.alt',
+        ]));
+    });
+    it('keeps same-named fields in different blocks distinct', () => {
+        // The defect this walk exists to prevent: without the block type both of
+        // these collapse to `content.alt` and become unidentifiable.
+        const alts = collect().filter((p) => p.endsWith('.alt'));
+        expect(new Set(alts).size).toBe(alts.length);
+    });
+    it('visits structure fields themselves, not only leaves', () => {
+        expect(collect()).toEqual(expect.arrayContaining(['files', 'files.filesGroup', 'content']));
+    });
+    it('reports every block through onBlock, addressed by its own path', () => {
+        const blocks = [];
+        walkFieldDeclarations(fields, () => { }, {
+            onBlock: (block, segments) => {
+                blocks.push(`${formatDeclarationPath(segments)} (${block.blockType})`);
+            },
+        });
+        expect(blocks).toEqual(['content.photoBlock (photoBlock)', 'content.videoBlock (videoBlock)']);
+    });
+    it('reports blocks nested inside other blocks', () => {
+        // `validateBlockAdminConfigs` collects every declaration site of a block
+        // type, and a block may be declared inside another block. The walk has to
+        // recurse through block fields, not just collection fields.
+        const nested = [
+            {
+                name: 'content',
+                label: 'C',
+                type: 'blocks',
+                blocks: [
+                    {
+                        blockType: 'outerBlock',
+                        fields: [
+                            {
+                                name: 'inner',
+                                label: 'I',
+                                type: 'blocks',
+                                blocks: [{ blockType: 'deepBlock', fields: [{ name: 'deep', type: 'text' }] }],
+                            },
+                        ],
+                    },
+                ],
+            },
+        ];
+        const seen = [];
+        walkFieldDeclarations(nested, () => { }, {
+            onBlock: (_block, segments) => seen.push(formatDeclarationPath(segments)),
+        });
+        expect(seen).toEqual(['content.outerBlock', 'content.outerBlock.inner.deepBlock']);
+    });
+    it('reports a block declaring no fields, which the field visitor cannot see', () => {
+        // Validation that must inspect every block — the dot-free check on block
+        // types, for one — would silently stop covering empty blocks if blocks
+        // were inferred from the segments of the fields inside them.
+        const withEmpty = [
+            {
+                name: 'content',
+                label: 'C',
+                type: 'blocks',
+                blocks: [{ blockType: 'emptyBlock', fields: [] }],
+            },
+        ];
+        const visited = [];
+        const blocks = [];
+        walkFieldDeclarations(withEmpty, (_field, segments) => visited.push(formatDeclarationPath(segments)), { onBlock: (block) => blocks.push(block.blockType) });
+        expect(visited).toEqual(['content']);
+        expect(blocks).toEqual(['emptyBlock']);
+    });
+    it('reports each block before the fields inside it', () => {
+        const events = [];
+        walkFieldDeclarations(fields, (_field, segments) => events.push(`field:${formatDeclarationPath(segments)}`), {
+            onBlock: (_block, segments) => events.push(`block:${formatDeclarationPath(segments)}`),
+        });
+        expect(events.indexOf('block:content.photoBlock')).toBeLessThan(events.indexOf('field:content.photoBlock.gallery'));
+    });
+});
+describe('resolveDeclarationPath', () => {
+    it('resolves a path through array and group structure', () => {
+        const result = resolveDeclarationPath(fields, 'files.filesGroup.caption');
+        expect(result.status).toBe('ok');
+        expect(result.status === 'ok' && result.field.name).toBe('caption');
+    });
+    it('reclassifies a block-type segment the parser could not identify', () => {
+        const result = resolveDeclarationPath(fields, 'content.photoBlock.gallery.alt');
+        expect(result.status).toBe('ok');
+        expect(result.status === 'ok' && result.segments[1]).toEqual({
+            kind: 'blockType',
+            blockType: 'photoBlock',
+        });
+    });
+    it('distinguishes same-named fields in different blocks', () => {
+        const photo = resolveDeclarationPath(fields, 'content.photoBlock.gallery.alt');
+        const video = resolveDeclarationPath(fields, 'content.videoBlock.alt');
+        expect(photo.status).toBe('ok');
+        expect(video.status).toBe('ok');
+    });
+    it('reports `blocks` rather than `unresolved` when traversal is barred', () => {
+        const result = resolveDeclarationPath(fields, 'content.photoBlock.gallery.alt', {
+            blocks: 'forbidden',
+        });
+        expect(result).toEqual({ status: 'blocks', at: 0 });
+    });
+    it('reports `blocks` even for an unqualified path into a block', () => {
+        expect(resolveDeclarationPath(fields, 'content.alt', { blocks: 'forbidden' }).status).toBe('blocks');
+    });
+    it('resolves the blocks field itself under `forbidden`', () => {
+        // `forbidden` bars *traversal* into a block, not addressing the blocks
+        // field. A blocks field carries a label like any other, so an admin
+        // `fields{}` key naming it is a legitimate override target — what the
+        // narrowing rules out is reaching past it to the fields inside.
+        const result = resolveDeclarationPath(fields, 'content', { blocks: 'forbidden' });
+        expect(result.status).toBe('ok');
+        expect(result.status === 'ok' && result.field.type).toBe('blocks');
+    });
+    it('rejects an unknown block type', () => {
+        expect(resolveDeclarationPath(fields, 'content.audioBlock.alt').status).toBe('unresolved');
+    });
+    it('rejects a path that stops on the block type', () => {
+        // Addresses a block, not a field declaration.
+        expect(resolveDeclarationPath(fields, 'content.photoBlock').status).toBe('unresolved');
+    });
+    it('rejects a path walking through a value field', () => {
+        expect(resolveDeclarationPath(fields, 'title.anything').status).toBe('unresolved');
+    });
+    it('rejects instance segments passed where a declaration is required', () => {
+        expect(resolveDeclarationPath(fields, 'files[0].filesGroup.caption').status).toBe('unresolved');
+    });
+    it('resolves a structure field addressed on its own', () => {
+        expect(resolveDeclarationPath(fields, 'files').status).toBe('ok');
+    });
+});
+// ---------------------------------------------------------------------------
+// Equivalence with the validator this module will replace.
+//
+// Phase 2c swaps `validate-admin-configs`' private `resolveSchemaPath` for
+// `resolveDeclarationPath({ blocks: 'forbidden' })`. That is only safe if the
+// two agree on every key today, so assert it directly rather than assuming.
+// ---------------------------------------------------------------------------
+describe('resolveDeclarationPath — agreement with the admin fields{} validator', () => {
+    const collection = {
+        path: 'pages',
+        labels: { singular: 'Page', plural: 'Pages' },
+        useAsTitle: 'title',
+        fields,
+    };
+    const validatorAccepts = (key) => {
+        try {
+            validateAdminConfigs([{ slug: 'pages', fields: { [key]: {} } }], [collection]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const resolverAccepts = (key) => resolveDeclarationPath(fields, key, { blocks: 'forbidden' }).status === 'ok';
+    const keys = [
+        'title',
+        'files',
+        'files.filesGroup',
+        'files.filesGroup.caption',
+        'files.filesGroup.missing',
+        'files[0].filesGroup.caption',
+        'title.anything',
+        'content',
+        'content.alt',
+        'content.photoBlock.gallery.alt',
+        'missing',
+        '',
+    ];
+    for (const key of keys) {
+        it(`agrees on ${key === '' ? '<empty>' : key}`, () => {
+            expect(resolverAccepts(key)).toBe(validatorAccepts(key));
+        });
+    }
+});

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

@@ -0,0 +1,47 @@
+/**
+ * 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 { Block, Field } from '../@types/index.js';
+import type { PathResolution, PathSegment, ResolveOptions } from './path-types.js';
+export interface WalkOptions {
+    /**
+     * Called for every block declaration encountered, immediately before its
+     * fields are visited, with the segments addressing the block itself
+     * (`content.photoBlock`).
+     *
+     * Blocks are declaration sites in their own right, and a block with no
+     * fields is invisible to `visit` — so validation that must see every block
+     * regardless of its contents needs this rather than inferring blocks from
+     * the segments of the fields inside them.
+     */
+    readonly onBlock?: (block: Block, segments: readonly PathSegment[]) => void;
+}
+/**
+ * Visit every field declaration in a field set, depth first, handing each one
+ * the segments that address it.
+ *
+ * Structure fields are visited themselves and then descended into. A `blocks`
+ * field contributes two segments per hop — its own name and the block type —
+ * which is what keeps two blocks declaring the same field name apart.
+ *
+ * This is the single canonical walk. Producers of declaration paths (the
+ * upload hook registry, boot-validation error messages) should use it rather
+ * than re-implementing the descent, which is how they drifted apart.
+ */
+export declare function walkFieldDeclarations(fields: readonly Field[], visit: (field: Field, segments: readonly PathSegment[]) => void, options?: WalkOptions): void;
+/**
+ * Resolve a declaration path against a field set.
+ *
+ * Accepts either a path string or pre-parsed segments. Segments arriving as
+ * `kind: 'field'` where the schema expects a block type are reclassified in
+ * the returned `segments`, so callers get a correctly typed path back even
+ * though the parser could not have known.
+ *
+ * Item selectors are rejected: a declaration path addresses a declaration, so
+ * an index is a category error rather than something to ignore.
+ */
+export declare function resolveDeclarationPath(fields: readonly Field[], path: string | readonly PathSegment[], options?: ResolveOptions): PathResolution;

package/dist/paths/resolve-path.js

@@ -0,0 +1,120 @@
+/**
+ * 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 { parseDeclarationPath } from './parse-path.js';
+/**
+ * Visit every field declaration in a field set, depth first, handing each one
+ * the segments that address it.
+ *
+ * Structure fields are visited themselves and then descended into. A `blocks`
+ * field contributes two segments per hop — its own name and the block type —
+ * which is what keeps two blocks declaring the same field name apart.
+ *
+ * This is the single canonical walk. Producers of declaration paths (the
+ * upload hook registry, boot-validation error messages) should use it rather
+ * than re-implementing the descent, which is how they drifted apart.
+ */
+export function walkFieldDeclarations(fields, visit, options = {}) {
+    const walk = (current, prefix) => {
+        for (const field of current) {
+            const segments = [...prefix, { kind: 'field', name: field.name }];
+            visit(field, segments);
+            if (field.type === 'group' || field.type === 'array') {
+                walk(field.fields, segments);
+            }
+            else if (field.type === 'blocks') {
+                for (const block of field.blocks) {
+                    const blockSegments = [
+                        ...segments,
+                        { kind: 'blockType', blockType: block.blockType },
+                    ];
+                    options.onBlock?.(block, blockSegments);
+                    walk(block.fields, blockSegments);
+                }
+            }
+        }
+    };
+    walk(fields, []);
+}
+/**
+ * Resolve a declaration path against a field set.
+ *
+ * Accepts either a path string or pre-parsed segments. Segments arriving as
+ * `kind: 'field'` where the schema expects a block type are reclassified in
+ * the returned `segments`, so callers get a correctly typed path back even
+ * though the parser could not have known.
+ *
+ * Item selectors are rejected: a declaration path addresses a declaration, so
+ * an index is a category error rather than something to ignore.
+ */
+export function resolveDeclarationPath(fields, path, options = {}) {
+    const allowBlocks = (options.blocks ?? 'qualified') === 'qualified';
+    let input;
+    if (typeof path === 'string') {
+        const parsed = parseDeclarationPath(path);
+        if (!parsed.ok)
+            return { status: 'unresolved', at: 0 };
+        input = parsed.segments;
+    }
+    else {
+        input = path;
+    }
+    if (input.length === 0)
+        return { status: 'unresolved', at: 0 };
+    const resolved = [];
+    let current = fields;
+    let i = 0;
+    while (i < input.length) {
+        const segment = input[i];
+        // Declaration paths carry names only. Anything else is a caller passing
+        // instance segments where a declaration was required.
+        if (segment == null || (segment.kind !== 'field' && segment.kind !== 'blockType')) {
+            return { status: 'unresolved', at: i };
+        }
+        const name = segment.kind === 'field' ? segment.name : segment.blockType;
+        const field = current.find((candidate) => candidate.name === name);
+        if (field == null)
+            return { status: 'unresolved', at: i };
+        resolved.push({ kind: 'field', name: field.name });
+        // Deliberately ahead of the `blocks: 'forbidden'` check below: that policy
+        // bars *traversal* into a block, so a path ending on the blocks field
+        // resolves normally. The field carries a label like any other and is a
+        // legitimate admin override target.
+        const isLast = i === input.length - 1;
+        if (isLast)
+            return { status: 'ok', field, segments: resolved };
+        if (field.type === 'group' || field.type === 'array') {
+            current = field.fields;
+            i += 1;
+            continue;
+        }
+        if (field.type === 'blocks') {
+            if (!allowBlocks)
+                return { status: 'blocks', at: i };
+            // The next segment names the block type — the discriminator that makes
+            // the rest of the path unambiguous.
+            const next = input[i + 1];
+            if (next == null || (next.kind !== 'field' && next.kind !== 'blockType')) {
+                return { status: 'unresolved', at: i + 1 };
+            }
+            const blockType = next.kind === 'field' ? next.name : next.blockType;
+            const block = field.blocks.find((candidate) => candidate.blockType === blockType);
+            if (block == null)
+                return { status: 'unresolved', at: i + 1 };
+            resolved.push({ kind: 'blockType', blockType: block.blockType });
+            // A path ending on the block type addresses the block, not a field.
+            if (i + 1 === input.length - 1)
+                return { status: 'unresolved', at: i + 1 };
+            current = block.fields;
+            i += 2;
+            continue;
+        }
+        // A value field with path left to walk.
+        return { status: 'unresolved', at: i };
+    }
+    return { status: 'unresolved', at: input.length - 1 };
+}

package/dist/services/assign-counter-values.js

@@ -46,9 +46,15 @@ function* walkCounterSites(fields, data, pathPrefix = '') {
     }
 }
 /**
- * Resolve a counter value already present in `previousData` at the
- * same dotted path as the site. Returns `undefined` if the value is
- * missing or not a finite number.
+ * Resolve a counter value already present in `previousData` at the same
+ * dotted path as the site. Returns `undefined` if the value is missing or
+ * not a finite number.
+ *
+ * `path` is a plain object accessor, **not** a field path in the sense of
+ * `@byline/core` `paths/` — it walks data, never the schema, and stops at
+ * any array because counters may not be declared inside `array` / `blocks`
+ * (see `walkCounterSites`). It therefore needs no item selectors and no
+ * block-type segments, which is why it does not use the shared grammar.
  */
 function readPreviousValue(previousData, path) {
     const segments = path.split('.');

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "4.3.0",
+  "version": "4.4.1",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -81,7 +81,7 @@
     "pino": "^10.3.1",
     "sharp": "^0.35.3",
     "zod": "^4.4.3",
-    "@byline/auth": "4.3.0"
+    "@byline/auth": "4.4.1"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.4",