@pantheon-systems/p1-content-validator 2.3.0 → 2.5.0

package/dist/authority-enforcement.js

@@ -1,5 +1,6 @@
 import { isAuthority, resolveSlotAuthority, ROOT_SLOT_ID } from './localization.js';
 import { isPlainObject, resolvePropPath } from './guards.js';
+import { mapToWrittenPaths, positionalOps } from './block-paths.js';
 function resolveSlot(path, snapshot) {
     const parts = path.split('.');
     if (parts[0] === 'root' && parts.lastIndexOf('props') === 1) {
@@ -15,16 +16,19 @@ function isContentProp(propName) {
     return propName !== 'id' && !propName.startsWith('_');
 }
 export function validateTranslationAuthority(input) {
-    const { operations, currentSnapshot, templateSnapshot, authorityOverrides = {}, slotAuthority = {}, severity = 'warning', } = input;
+    const { operations, currentSnapshot, templateSnapshot, authorityOverrides = {}, slotAuthority = {}, translatable = {}, severity = 'warning', } = input;
     const diagnostics = [];
     const overrides = new Map(Object.entries(authorityOverrides).map(([slotId, props]) => [
         slotId,
         new Map(Object.entries(props).filter(([, value]) => isAuthority(value))),
     ]));
     const slotDefaults = new Map(Object.entries(slotAuthority).filter((entry) => isAuthority(entry[1])));
+    const translatableFlags = new Map(Object.entries(translatable).map(([slotId, props]) => [slotId, new Map(Object.entries(props))]));
     const effectiveAuthority = (slotId, propName) => overrides.get(slotId)?.get(propName) ??
         slotDefaults.get(slotId) ??
         resolveSlotAuthority(templateSnapshot, slotId);
+    const isInheritedNonTranslatable = (slotId, propName) => effectiveAuthority(slotId, propName) === 'canonical' &&
+        translatableFlags.get(slotId)?.get(propName) === false;
     const flag = (opIndex, path, slotId, propName) => {
         diagnostics.push({
             opIndex,
@@ -38,7 +42,10 @@ export function validateTranslationAuthority(input) {
                 `This prop is owned by the canonical; edit it there and let sync propagate the value.`,
         });
     };
-    operations.forEach((op, opIndex) => {
+    const { ops: positional } = positionalOps(operations, currentSnapshot);
+    positional.forEach((op, opIndex) => {
+        if (op === null)
+            return;
         if (op.type !== 'add' && op.type !== 'replace')
             return;
         if (op.content === undefined)
@@ -53,7 +60,7 @@ export function validateTranslationAuthority(input) {
             for (const propName of Object.keys(op.content)) {
                 if (!isContentProp(propName))
                     continue;
-                if (effectiveAuthority(slotId, propName) === 'canonical') {
+                if (isInheritedNonTranslatable(slotId, propName)) {
                     flag(opIndex, `${op.path}.${propName}`, slotId, propName);
                 }
             }
@@ -62,9 +69,10 @@ export function validateTranslationAuthority(input) {
         const propName = parts[propsIdx + 1];
         if (!isContentProp(propName))
             return;
-        if (effectiveAuthority(slotId, propName) === 'canonical') {
+        if (isInheritedNonTranslatable(slotId, propName)) {
             flag(opIndex, op.path, slotId, propName);
         }
     });
+    mapToWrittenPaths(diagnostics, operations, positional);
     return { diagnostics };
 }

package/dist/block-paths.d.ts

@@ -0,0 +1,43 @@
+/** Where a path points on a page, or why that can't be said. */
+export type BlockPathResult = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** One op whose path could not be resolved, with the reason and its index in the input array. */
+export type BlockPathFailure = {
+    opIndex: number;
+    path: string;
+    reason: string;
+};
+/**
+ * Rewrites a path that starts at a block's id (`#<id>`, `#<id>.props.title`) to that block's
+ * position on `page`, however deep it sits. A positional path comes back unchanged.
+ */
+export declare function resolveBlockPath(page: unknown, path: string): BlockPathResult;
+/**
+ * Rewrites each report's path, and the block's position in its message (e.g. "content.0"), back to
+ * the block id the caller wrote.
+ */
+export declare function mapToWrittenPaths(reports: {
+    opIndex: number;
+    path: string;
+    message: string;
+}[], written: readonly {
+    path: string;
+}[], resolved: readonly ({
+    path: string;
+} | null)[]): void;
+/**
+ * Each op with a block-id path rewritten to its position on `page`, the page as read before the
+ * edit. `null` stands in for an op whose path can't be resolved, with the reason in `failures`.
+ * Without a page every op comes back as written.
+ */
+export declare function positionalOps<T extends {
+    path: string;
+}>(ops: readonly T[], page: unknown): {
+    ops: (T | null)[];
+    failures: BlockPathFailure[];
+};

package/dist/block-paths.js

@@ -0,0 +1,90 @@
+import { isComponentShape, isPlainObject } from './guards.js';
+export function resolveBlockPath(page, path) {
+    const segments = path.split('.');
+    const later = segments.findIndex((segment, i) => i > 0 && segment.startsWith('#'));
+    if (later !== -1) {
+        return { ok: false, reason: `Start the path at the block: ${segments.slice(later).join('.')}` };
+    }
+    const [first = '', ...rest] = segments;
+    if (!first.startsWith('#'))
+        return { ok: true, path };
+    const id = first.slice(1);
+    if (id === '')
+        return { ok: false, reason: 'Path names no block id' };
+    const found = pathsOfBlock(page, id);
+    if (found.length === 0)
+        return { ok: false, reason: `No block #${id} on this page` };
+    if (found.length > 1) {
+        return { ok: false, reason: `#${id} names ${String(found.length)} blocks on this page; name it by position` };
+    }
+    return { ok: true, path: [found[0], ...rest].join('.') };
+}
+function pathsOfBlock(value, id, at = [], found = []) {
+    if (Array.isArray(value)) {
+        value.forEach((item, i) => pathsOfBlock(item, id, [...at, String(i)], found));
+    }
+    else if (isPlainObject(value)) {
+        if (isComponentShape(value) && value.props.id === id)
+            found.push(at.join('.'));
+        for (const [key, child] of Object.entries(value))
+            pathsOfBlock(child, id, [...at, key], found);
+    }
+    return found;
+}
+export function mapToWrittenPaths(reports, written, resolved) {
+    for (const report of reports) {
+        const resolvedOp = resolved[report.opIndex];
+        const writtenOp = written[report.opIndex];
+        if (!resolvedOp || !writtenOp)
+            continue;
+        const from = resolvedOp.path;
+        const to = writtenOp.path;
+        if (from === to || !to.startsWith('#'))
+            continue;
+        const dotIdx = to.indexOf('.');
+        const tail = dotIdx === -1 ? '' : to.slice(dotIdx);
+        if (tail !== '' && !from.endsWith(tail))
+            continue;
+        const head = from.slice(0, from.length - tail.length);
+        const blockRef = dotIdx === -1 ? to : to.slice(0, dotIdx);
+        if (report.path === head || (report.path.startsWith(head) && report.path[head.length] === '.')) {
+            report.path = blockRef + report.path.slice(head.length);
+        }
+        report.message = replaceStandalone(report.message, head, blockRef);
+    }
+}
+function replaceStandalone(text, path, by) {
+    if (path === '')
+        return text;
+    let out = '';
+    let from = 0;
+    let at = text.indexOf(path);
+    while (at !== -1) {
+        const before = at > 0 ? text.charAt(at - 1) : '';
+        const after = text.charAt(at + path.length);
+        if (!/[A-Za-z0-9_.]/.test(before) && (after === '' || /[."\s,:]/.test(after))) {
+            out += text.slice(from, at) + by;
+            from = at + path.length;
+            at = text.indexOf(path, from);
+        }
+        else {
+            at = text.indexOf(path, at + 1);
+        }
+    }
+    return out + text.slice(from);
+}
+export function positionalOps(ops, page) {
+    const failures = [];
+    if (page == null)
+        return { ops: [...ops], failures };
+    const resolved = ops.map((op, opIndex) => {
+        if (!op.path.includes('#'))
+            return op;
+        const result = resolveBlockPath(page, op.path);
+        if (result.ok)
+            return { ...op, path: result.path };
+        failures.push({ opIndex, path: op.path, reason: result.reason });
+        return null;
+    });
+    return { ops: resolved, failures };
+}

package/dist/index.d.ts

@@ -4,5 +4,7 @@ export { hashDescriptor } from './component-descriptor.js';
 export type { ComponentDescriptor, ComponentProvenance, FieldAiMeta, RegistryIndex, SerializedField, } from './component-descriptor.js';
 export { validateDocumentStructure } from './structure-validator.js';
 export { validateTranslationAuthority } from './authority-enforcement.js';
-export { resolveTranslatable, resolveSlotAuthority, resolveSlotAuthorityMap, isAuthority, AUTHORITIES, DEFAULT_AUTHORITY, ROOT_SLOT_ID, } from './localization.js';
-export type { EditOperation, Authority, ComponentSchema, ComponentField, FieldOption, ValidationError, ValidateInput, FetchRegistryOpts, TemplateComponent, TemplateSnapshot, StructuralConformanceError, ValidateStructureInput, AuthoritySeverity, AuthorityOverrideMap, AuthorityDiagnostic, ValidateTranslationAuthorityInput, } from './types.js';
+export { resolveBlockPath, positionalOps } from './block-paths.js';
+export type { BlockPathResult, BlockPathFailure } from './block-paths.js';
+export { resolveTranslatable, resolveTranslatableMap, resolveSlotAuthority, resolveSlotAuthorityMap, isAuthority, AUTHORITIES, DEFAULT_AUTHORITY, ROOT_SLOT_ID, } from './localization.js';
+export type { EditOperation, Authority, ComponentSchema, ComponentField, FieldOption, ValidationError, ValidateInput, FetchRegistryOpts, TemplateComponent, TemplateSnapshot, StructuralConformanceError, ValidateStructureInput, AuthoritySeverity, AuthorityOverrideMap, TranslatableMap, AuthorityDiagnostic, ValidateTranslationAuthorityInput, } from './types.js';

package/dist/index.js

@@ -3,4 +3,5 @@ export { fetchRegistry, listRegistryVersions, snapshotToComponentSchema, registr
 export { hashDescriptor } from './component-descriptor.js';
 export { validateDocumentStructure } from './structure-validator.js';
 export { validateTranslationAuthority } from './authority-enforcement.js';
-export { resolveTranslatable, resolveSlotAuthority, resolveSlotAuthorityMap, isAuthority, AUTHORITIES, DEFAULT_AUTHORITY, ROOT_SLOT_ID, } from './localization.js';
+export { resolveBlockPath, positionalOps } from './block-paths.js';
+export { resolveTranslatable, resolveTranslatableMap, resolveSlotAuthority, resolveSlotAuthorityMap, isAuthority, AUTHORITIES, DEFAULT_AUTHORITY, ROOT_SLOT_ID, } from './localization.js';

package/dist/localization.d.ts

@@ -1,4 +1,4 @@
-import type { Authority } from './types.js';
+import type { Authority, TranslatableMap } from './types.js';
 /**
  * Localization resolvers — the single source of truth for two independent
  * properties of the localization model:
@@ -31,6 +31,13 @@ export declare function isAuthority(value: unknown): value is Authority;
  * true.
  */
 export declare function resolveTranslatable(snapshot: unknown, slotId: string, propName: string): boolean;
+/**
+ * Resolves a canonical page snapshot's whole `root.props._localeTranslatable` map,
+ * keyed by slot id then prop name. Only boolean entries are kept, so a prop absent
+ * from the result is translatable, matching `resolveTranslatable`. Absent maps,
+ * malformed snapshots and non-object slot entries resolve to no entries.
+ */
+export declare function resolveTranslatableMap(snapshot: unknown): TranslatableMap;
 /**
  * Resolves the per-slot authority default from a template snapshot's
  * `root.props._localeAuthority` map, keyed by slot id. Slots with no declared

package/dist/localization.js

@@ -23,6 +23,13 @@ export function resolveTranslatable(snapshot, slotId, propName) {
     }
     return slot[propName] !== false;
 }
+export function resolveTranslatableMap(snapshot) {
+    const slots = Object.entries(localeConfigMap(snapshot, '_localeTranslatable')).filter((entry) => isPlainObject(entry[1]));
+    return Object.fromEntries(slots.map(([slotId, props]) => [
+        slotId,
+        Object.fromEntries(Object.entries(props).filter((entry) => typeof entry[1] === 'boolean')),
+    ]));
+}
 export function resolveSlotAuthority(templateSnapshot, slotId) {
     const value = localeConfigMap(templateSnapshot, '_localeAuthority')[slotId];
     return isAuthority(value) ? value : DEFAULT_AUTHORITY;

package/dist/types.d.ts

@@ -32,7 +32,7 @@ export interface ComponentSchema {
 export interface ValidationError {
     opIndex: number;
     path: string;
-    code: 'unknown_component_type' | 'component_type_case_mismatch' | 'invalid_prop_key' | 'invalid_prop_value' | 'missing_required_prop' | 'invalid_readonly_key' | 'deprecated_zones_usage';
+    code: 'unknown_component_type' | 'component_type_case_mismatch' | 'invalid_prop_key' | 'invalid_prop_value' | 'missing_required_prop' | 'invalid_readonly_key' | 'deprecated_zones_usage' | 'unresolved_block';
     message: string;
 }
 export interface FetchRegistryOpts {
@@ -95,6 +95,12 @@ export type AuthoritySeverity = 'warning' | 'error';
  * slot's template default.
  */
 export type AuthorityOverrideMap = Record<string, Record<string, Authority>>;
+/**
+ * Per-prop translatable flags from a canonical page's `_localeTranslatable` map,
+ * nested by slot id then prop name. A prop is translatable unless its entry is
+ * `false`.
+ */
+export type TranslatableMap = Record<string, Record<string, boolean>>;
 /**
  * A diagnostic raised when a write targets a prop whose effective authority is
  * `canonical` — a prop the translation does not own. `authority` carries that
@@ -123,6 +129,12 @@ export interface ValidateTranslationAuthorityInput {
     slotAuthority?: Record<string, Authority>;
     /** Per-prop overrides from the localization edge; absent props follow the default. */
     authorityOverrides?: AuthorityOverrideMap;
+    /**
+     * The canonical's translatable flags. A translatable prop is not judged, since
+     * the translation holds its own wording of it; an absent map or entry reads as
+     * translatable.
+     */
+    translatable?: TranslatableMap;
     /** Severity to stamp on emitted diagnostics. Defaults to `warning`. */
     severity?: AuthoritySeverity;
 }

package/dist/validator.js

@@ -1,5 +1,6 @@
 import { registryComponentKey } from './registry.js';
 import { getAtPath, isComponentShape, isPlainObject, resolvePropPath } from './guards.js';
+import { mapToWrittenPaths, positionalOps } from './block-paths.js';
 const UUID_V4_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const PREFIXED_UUID_RE = /^[A-Za-z][A-Za-z0-9]*-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const ULID_RE = /^[0-9A-HJKMNP-TV-Z]{26}$/;
@@ -247,8 +248,14 @@ export function validateOps(input) {
     const zonesKey = config.zonesKey ?? 'zones';
     const warnOnZonesUsage = config.warnOnZonesUsage ?? true;
     const errors = [];
+    const { ops: positional, failures } = positionalOps(operations, currentSnapshot);
+    for (const failure of failures) {
+        errors.push({ opIndex: failure.opIndex, path: failure.path, code: 'unresolved_block', message: failure.reason });
+    }
     for (let opIndex = 0; opIndex < operations.length; opIndex++) {
-        const op = operations[opIndex];
+        const op = positional[opIndex];
+        if (op === null || op === undefined)
+            continue;
         if (op.type !== 'add' && op.type !== 'replace')
             continue;
         if (op.content === undefined)
@@ -276,5 +283,6 @@ export function validateOps(input) {
         }
         validateContent(op.content, normalizedRegistry, opIndex, op.path, errors, zonesKey, warnOnZonesUsage, existingIds);
     }
+    mapToWrittenPaths(errors, operations, positional);
     return { errors };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pantheon-systems/p1-content-validator",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Validates Puck component edit operations against the P1 component registry",
   "repository": {
     "type": "git",