@pantheon-systems/p1-content-validator 1.0.0 → 2.0.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { validateOps } from './validator.js';
 export { fetchRegistry, listRegistryVersions, snapshotToComponentSchema } from './registry.js';
-export type { EditOperation, ComponentSchema, ComponentField, FieldOption, ValidationError, ValidateInput, FetchRegistryOpts, } from './types.js';
+export { validateDocumentStructure } from './structure-validator.js';
+export type { EditOperation, ComponentSchema, ComponentField, FieldOption, ValidationError, ValidateInput, FetchRegistryOpts, TemplateComponent, TemplateSnapshot, StructuralConformanceError, ValidateStructureInput, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAC/F,YAAY,EACV,aAAa,EACb,eAAe,EACf,cAAc,EACd,WAAW,EACX,eAAe,EACf,aAAa,EACb,iBAAiB,GAClB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAC/F,OAAO,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AACrE,YAAY,EACV,aAAa,EACb,eAAe,EACf,cAAc,EACd,WAAW,EACX,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,0BAA0B,EAC1B,sBAAsB,GACvB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,3 @@
 export { validateOps } from './validator.js';
 export { fetchRegistry, listRegistryVersions, snapshotToComponentSchema } from './registry.js';
+export { validateDocumentStructure } from './structure-validator.js';

package/dist/structure-validator.d.ts

@@ -0,0 +1,26 @@
+import type { StructuralConformanceError, ValidateStructureInput } from './types.js';
+/**
+ * Validates that a document snapshot conforms to a template's structural skeleton.
+ *
+ * A template component is pinned when `root.props._pinMap[props.id]` is `true`;
+ * pinned types are checked in template `content` order.
+ *
+ * Conformance rules:
+ * 1. All pinned components must be present in the document
+ * 2. Pinned components must appear in the same relative order as in the template
+ * 3. Non-pinned components are allowed and do not affect conformance
+ *
+ * This implements partial conformance: documents may have additional components
+ * beyond the pinned skeleton without failing validation.
+ *
+ * DEFENSIVE DESIGN: This function is designed to never crash, even with malformed
+ * inputs. All property accesses use optional chaining, and all array operations
+ * verify types before use.
+ *
+ * @param input - Document snapshot and template snapshot to validate against
+ * @returns Object with array of structural conformance errors (empty if valid)
+ */
+export declare function validateDocumentStructure(input: ValidateStructureInput): {
+    errors: StructuralConformanceError[];
+};
+//# sourceMappingURL=structure-validator.d.ts.map

package/dist/structure-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structure-validator.d.ts","sourceRoot":"","sources":["../src/structure-validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAC1B,sBAAsB,EACvB,MAAM,YAAY,CAAC;AASpB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,sBAAsB,GAC5B;IAAE,MAAM,EAAE,0BAA0B,EAAE,CAAA;CAAE,CAoG1C"}

package/dist/structure-validator.js

@@ -0,0 +1,118 @@
+/** Returns the value when it is a plain object, otherwise undefined. */
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/**
+ * Validates that a document snapshot conforms to a template's structural skeleton.
+ *
+ * A template component is pinned when `root.props._pinMap[props.id]` is `true`;
+ * pinned types are checked in template `content` order.
+ *
+ * Conformance rules:
+ * 1. All pinned components must be present in the document
+ * 2. Pinned components must appear in the same relative order as in the template
+ * 3. Non-pinned components are allowed and do not affect conformance
+ *
+ * This implements partial conformance: documents may have additional components
+ * beyond the pinned skeleton without failing validation.
+ *
+ * DEFENSIVE DESIGN: This function is designed to never crash, even with malformed
+ * inputs. All property accesses use optional chaining, and all array operations
+ * verify types before use.
+ *
+ * @param input - Document snapshot and template snapshot to validate against
+ * @returns Object with array of structural conformance errors (empty if valid)
+ */
+export function validateDocumentStructure(input) {
+    const { documentSnapshot, templateSnapshot } = input;
+    const errors = [];
+    // Puck snapshots store the component array at top-level `content`, but some
+    // wrappers nest it under `root.props.content`. Check both, fall back to empty.
+    const topLevelContent = documentSnapshot?.content;
+    const contentRaw = Array.isArray(topLevelContent)
+        ? topLevelContent
+        : asRecord(asRecord(documentSnapshot?.root)?.props)?.content;
+    const content = Array.isArray(contentRaw)
+        ? contentRaw
+        : [];
+    const templateContent = Array.isArray(templateSnapshot?.content)
+        ? templateSnapshot.content
+        : [];
+    // A component is pinned only when root.props._pinMap[props.id] is true.
+    const pinMap = asRecord(asRecord(asRecord(templateSnapshot?.root)?.props)?._pinMap) ?? {};
+    // Pinned component types in template content order.
+    // A component without a string type or string id is never pinned.
+    const pinnedTypes = [];
+    for (const templateComponent of templateContent) {
+        if (!templateComponent || typeof templateComponent.type !== 'string') {
+            continue;
+        }
+        const id = asRecord(templateComponent.props)?.id;
+        if (typeof id === 'string' && pinMap[id] === true) {
+            pinnedTypes.push(templateComponent.type);
+        }
+    }
+    // If template has no pinned components, document always conforms
+    if (pinnedTypes.length === 0) {
+        return { errors };
+    }
+    // Build a map of pinned component types to their indices in the document
+    // Defensively handle components without type field or with non-string types
+    const pinnedIndices = new Map();
+    content.forEach((component, index) => {
+        // Skip components without a valid type field
+        if (!component || typeof component.type !== 'string') {
+            return;
+        }
+        if (pinnedTypes.includes(component.type)) {
+            const indices = pinnedIndices.get(component.type) || [];
+            indices.push(index);
+            pinnedIndices.set(component.type, indices);
+        }
+    });
+    // Track the last index we successfully matched to ensure ordering
+    let lastFoundIndex = -1;
+    // Check each pinned component in template order
+    for (let i = 0; i < pinnedTypes.length; i++) {
+        const expectedType = pinnedTypes[i];
+        const indices = pinnedIndices.get(expectedType) || [];
+        // Find the first occurrence of this component type after lastFoundIndex
+        const foundIndex = indices.find((idx) => idx > lastFoundIndex);
+        if (foundIndex === undefined) {
+            // No unconsumed occurrence appears after the last match. If the document
+            // holds fewer instances of this type than the template pins up to here,
+            // a required instance is absent; otherwise the instances that exist sit
+            // before where this one must appear.
+            let requiredSoFar = 0;
+            for (let j = 0; j <= i; j++) {
+                if (pinnedTypes[j] === expectedType)
+                    requiredSoFar++;
+            }
+            if (indices.length < requiredSoFar) {
+                errors.push({
+                    code: 'missing_pinned_component',
+                    componentType: expectedType,
+                    message: `Required component "${expectedType}" is missing from the document.`,
+                });
+            }
+            else {
+                // Component exists but is out of order (appears before lastFoundIndex)
+                errors.push({
+                    code: 'pinned_component_out_of_order',
+                    componentType: expectedType,
+                    expectedIndex: i,
+                    actualIndex: indices[0],
+                    message: `Pinned component "${expectedType}" appears out of order. ` +
+                        `Expected after index ${lastFoundIndex} but found at index ${indices[0]}.`,
+                });
+            }
+        }
+        else {
+            // Component found in correct relative order
+            lastFoundIndex = foundIndex;
+        }
+    }
+    return { errors };
+}

package/dist/types.d.ts

@@ -44,4 +44,36 @@ export interface ValidateInput {
         warnOnZonesUsage?: boolean;
     };
 }
+export interface TemplateComponent {
+    type: string;
+    /** Component props are the template's default props. `id` keys into `_pinMap`. */
+    props: {
+        id?: string;
+        [key: string]: unknown;
+    };
+}
+/** A template's version snapshot: Puck data, identical in shape to a page. */
+export interface TemplateSnapshot {
+    content: TemplateComponent[];
+    root: {
+        props: {
+            _template?: Record<string, unknown>;
+            /** Component id to pinned flag. A component is pinned only when its entry is `true`. */
+            _pinMap?: Record<string, boolean>;
+            [key: string]: unknown;
+        };
+    };
+    zones?: Record<string, unknown>;
+}
+export interface StructuralConformanceError {
+    code: 'missing_pinned_component' | 'pinned_component_out_of_order' | 'unexpected_component_at_pinned_slot';
+    message: string;
+    componentType: string;
+    expectedIndex?: number;
+    actualIndex?: number;
+}
+export interface ValidateStructureInput {
+    documentSnapshot: Record<string, unknown>;
+    templateSnapshot: TemplateSnapshot;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;IAClC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EACA,wBAAwB,GACxB,kBAAkB,GAClB,oBAAoB,GACpB,uBAAuB,GACvB,sBAAsB,GACtB,wBAAwB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC1C,MAAM,CAAC,EAAE;QACP,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,gBAAgB,CAAC,EAAE,OAAO,CAAC;KAC5B,CAAC;CACH"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pantheon-systems/p1-content-validator",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Validates Puck component edit operations against the CSS component registry",
   "repository": {
     "type": "git",
@@ -28,6 +28,11 @@
   "engines": {
     "node": ">=20.0.0"
   },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": false
+  },
   "license": "MIT",
   "scripts": {
     "build": "tsc",