@akinon/pz-theme 2.0.43-rc.0 → 2.0.44

package/src/blocks/__tests__/checkout-hosted-parts.test.ts

@@ -0,0 +1,203 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * The checkout outlet blocks style parts they do not render: the code-owned
+ * checkout teleports its markup into them, and each outlet declares the parts
+ * it HOSTS via an exported `HOSTED_PARTS` literal that the editor's
+ * descriptor conformance also reads. A manifest nobody stamps would put dead
+ * entries in the editor panel; a stamp nobody declares would be unstylable —
+ * this suite keeps declaration and reality pointing at each other:
+ *
+ * - every manifest name is stamped (`partAttrs('…')`) somewhere in the app's
+ *   checkout views;
+ * - every stamped name is declared by at least one outlet manifest
+ *   (`summary-*` legitimately by two: the mobile summary sheet re-renders the
+ *   summary inside the flow subtree, and part rules are block-scoped);
+ * - the full vocabulary is pinned inline, so a rename fails loudly here
+ *   before it silently orphans published compositions;
+ * - stamps are INERT (I4): `partAttrs` is the only stamping route, and no
+ *   live runtime — app or pz-theme outside designer-only modules — queries
+ *   `[data-part` from the DOM.
+ */
+
+const repoRoot = path.resolve(__dirname, '../../../../..');
+const blocksDir = path.resolve(__dirname, '..');
+const pzThemeSrcDir = path.resolve(__dirname, '../..');
+const appSrcDir = path.join(repoRoot, 'apps', 'projectzeronext', 'src');
+const appCheckoutDir = path.join(appSrcDir, 'views', 'checkout');
+
+const OUTLET_MANIFEST_FILES = [
+  'checkout-flow-outlet-block.tsx',
+  'checkout-steps-outlet-block.tsx',
+  'checkout-summary-outlet-block.tsx'
+];
+
+/**
+ * The reserved checkout part vocabulary. Changing it is a contract change:
+ * update the outlet manifests, the app stamps, the editor part groups AND
+ * this pin together — published compositions reference these names.
+ */
+const RESERVED_PART_NAMES = [
+  'agreement',
+  'continue-button',
+  'edit-button',
+  'payment-option',
+  'payment-option-icon',
+  'payment-options',
+  'payment-panel',
+  'place-order-button',
+  'section',
+  'section-header',
+  'section-number',
+  'section-title',
+  'step',
+  'step-icon',
+  'step-label',
+  'step-number',
+  'steps',
+  'summary',
+  'summary-edit',
+  'summary-header',
+  'summary-item',
+  'summary-row',
+  'summary-row-label',
+  'summary-row-value',
+  'summary-title',
+  'summary-total',
+  'summary-total-label',
+  'summary-total-value'
+];
+
+const PART_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+const readManifest = (fileName: string): string[] => {
+  const source = fs.readFileSync(path.join(blocksDir, fileName), 'utf8');
+  const hosted = /HOSTED_PARTS\s*(?::[^=]*)?=\s*\[([\s\S]*?)\]/.exec(source);
+  if (!hosted) return [];
+
+  return Array.from(hosted[1].matchAll(/'([^']+)'/g), (match) => match[1]);
+};
+
+const walkSources = (dir: string): string[] => {
+  const files: string[] = [];
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules') continue;
+      files.push(...walkSources(full));
+    } else if (/\.(ts|tsx)$/.test(entry.name)) {
+      files.push(full);
+    }
+  }
+
+  return files;
+};
+
+const isTestFile = (file: string): boolean =>
+  /__tests__/.test(file) || /\.test\.(ts|tsx)$/.test(file);
+
+const manifests = Object.fromEntries(
+  OUTLET_MANIFEST_FILES.map((file) => [file, readManifest(file)])
+) as Record<string, string[]>;
+
+const manifestNames = new Set(Object.values(manifests).flat());
+
+// Runtime sources only. A test may legitimately write a part name into a
+// string template or assert on a raw attribute; what this suite pins is what
+// the SHIPPED checkout markup stamps.
+const checkoutSources = walkSources(appCheckoutDir)
+  .filter((file) => !isTestFile(file))
+  .map((file) => ({
+    file: path.relative(repoRoot, file),
+    source: fs.readFileSync(file, 'utf8')
+  }));
+
+const stampedNames = new Set(
+  checkoutSources.flatMap(({ source }) =>
+    Array.from(source.matchAll(/partAttrs\(\s*'([^']+)'/g), (m) => m[1])
+  )
+);
+
+describe('checkout hosted-parts manifests', () => {
+  it('finds a non-empty HOSTED_PARTS literal in each outlet block', () => {
+    for (const file of OUTLET_MANIFEST_FILES) {
+      expect(manifests[file].length).toBeGreaterThan(0);
+    }
+  });
+
+  it('uses only well-formed kebab-case part names, everywhere', () => {
+    for (const name of [
+      ...Array.from(manifestNames),
+      ...Array.from(stampedNames)
+    ]) {
+      expect(name).toMatch(PART_NAME_PATTERN);
+    }
+  });
+
+  it('pins the full reserved vocabulary — renames fail loudly', () => {
+    expect(Array.from(manifestNames).sort()).toEqual(RESERVED_PART_NAMES);
+  });
+
+  it('declares every stamped part in at least one outlet manifest', () => {
+    const undeclared = Array.from(stampedNames).filter(
+      (name) => !manifestNames.has(name)
+    );
+
+    expect(undeclared).toEqual([]);
+  });
+
+  it('stamps every declared part at least once in the checkout views', () => {
+    const unstamped = Array.from(manifestNames).filter(
+      (name) => !stampedNames.has(name)
+    );
+
+    expect(unstamped).toEqual([]);
+  });
+});
+
+describe('checkout part stamps are inert (I4)', () => {
+  it('routes every app stamp through partAttrs — no raw data-part attribute', () => {
+    const offenders = checkoutSources
+      .filter(({ source }) => source.includes('data-part='))
+      .map(({ file }) => file);
+
+    expect(offenders).toEqual([]);
+  });
+
+  // The attributes are a styling contract, not a runtime signal: nothing on
+  // the live path may branch on them. Designer-only modules (the queries are
+  // gated behind the editor-proven designer flag) are the sole exemption.
+  const DESIGNER_ONLY_PZ_THEME_FILES = [
+    path.join('hooks', 'use-designer-features.tsx'),
+    path.join('components', 'part-state-preview.tsx'),
+    path.join('blocks', 'checkout-outlet-base.tsx')
+  ];
+
+  const PART_QUERY_PATTERN =
+    /(?:querySelectorAll|querySelector|closest|matches)\s*(?:<[^>\n]*>)?\s*\(\s*[`'"]\[data-part/;
+
+  it('never queries [data-part from the app runtime', () => {
+    const offenders = walkSources(appSrcDir)
+      .filter((file) => !isTestFile(file))
+      .filter((file) => PART_QUERY_PATTERN.test(fs.readFileSync(file, 'utf8')))
+      .map((file) => path.relative(repoRoot, file));
+
+    expect(offenders).toEqual([]);
+  });
+
+  it('never queries [data-part from pz-theme outside designer-only modules', () => {
+    const offenders = walkSources(pzThemeSrcDir)
+      .filter((file) => !isTestFile(file))
+      .filter((file) => {
+        const relative = path.relative(pzThemeSrcDir, file);
+        return !DESIGNER_ONLY_PZ_THEME_FILES.includes(relative);
+      })
+      .filter((file) => PART_QUERY_PATTERN.test(fs.readFileSync(file, 'utf8')))
+      .map((file) => path.relative(repoRoot, file));
+
+    expect(offenders).toEqual([]);
+  });
+});