@deneb-ui/cli 2.0.87 → 2.0.89

package/src/arc/__tests__/visual-regression.test.cjs

@@ -0,0 +1,99 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const {
+  STANDARD_VIEWPORTS,
+  calculateVisualPreservation,
+  extractDesignSnapshot,
+} = require('../visual-regression.cjs');
+
+test('Visual Regression: extracts element tags, layout classes, and compound icons', () => {
+  const code = `
+    export function Hero() {
+      return (
+        <section className="relative flex flex-col md:grid md:grid-cols-2 gap-8 p-12 bg-white">
+          <h1 className="text-4xl font-bold">Original Title</h1>
+          <button className="btn flex items-center gap-2">
+            <svg className="w-5 h-5" />
+            <span>Order Now</span>
+          </button>
+        </section>
+      );
+    }
+  `;
+
+  const snapshot = extractDesignSnapshot(code);
+  assert.ok(snapshot.tags.includes('section'));
+  assert.ok(snapshot.tags.includes('h1'));
+  assert.ok(snapshot.tags.includes('button'));
+  assert.ok(snapshot.classes.has('flex'));
+  assert.ok(snapshot.classes.has('md:grid-cols-2'));
+
+  const btnElem = snapshot.elements.find((e) => e.tag === 'button');
+  assert.ok(btnElem);
+  assert.equal(btnElem.hasSvg, true);
+  assert.equal(btnElem.hasSpan, true);
+});
+
+test('Visual Regression: calculates >= 98% design preservation on valid ARC transformation', () => {
+  const beforeCode = `
+    export function Banner() {
+      return (
+        <div className="grid grid-cols-3 gap-6 p-8">
+          <h2>Featured Items</h2>
+          <p>Hand-picked for you</p>
+        </div>
+      );
+    }
+  `;
+
+  // Transformed code has siteData getters and preview marker, but identical layout classes & tags
+  const afterCode = `
+    export function Banner() {
+      return (
+        <div className="grid grid-cols-3 gap-6 p-8">
+          <h2 data-preview-field-path="home.banner.title">{siteData?.content?.home?.banner?.title ?? "Featured Items"}</h2>
+          <p data-preview-field-path="home.banner.subtitle">{siteData?.content?.home?.banner?.subtitle ?? "Hand-picked for you"}</p>
+        </div>
+      );
+    }
+  `;
+
+  const report = calculateVisualPreservation(beforeCode, afterCode);
+  assert.equal(report.passed, true);
+  assert.ok(report.overallPreservationScore >= 98.0);
+  assert.ok(report.viewports.mobile.preservationScore >= 98.0);
+  assert.ok(report.viewports.tablet.preservationScore >= 98.0);
+  assert.ok(report.viewports.desktop.preservationScore >= 98.0);
+  assert.equal(report.blockingIssues.length, 0);
+});
+
+test('Visual Regression: detects dropped layout classes or icons and reports blocking issue', () => {
+  const beforeCode = `
+    export function Action() {
+      return (
+        <button className="btn">
+          <svg className="icon" />
+          <span>Checkout</span>
+        </button>
+      );
+    }
+  `;
+
+  // Broken transform accidentally removed the svg icon
+  const brokenCode = `
+    export function Action() {
+      return (
+        <button className="btn">
+          <span>Checkout</span>
+        </button>
+      );
+    }
+  `;
+
+  const report = calculateVisualPreservation(beforeCode, brokenCode);
+  assert.equal(report.passed, false);
+  assert.ok(report.blockingIssues.length > 0);
+  assert.ok(report.blockingIssues[0].includes('SVG or icon dropped'));
+});

package/src/arc/acceptance-gates.cjs

@@ -0,0 +1,119 @@
+'use strict';
+
+/**
+ * Deneb ARC v3 — Production Acceptance Gates Engine
+ * Implements the 12-Gate Acceptance Matrix recommended for enterprise Next.js -> Fivora compilation.
+ */
+const ACCEPTANCE_GATES = {
+  SOURCE_ANALYSIS: 'Source Analysis',
+  AST_TRANSFORMATION: 'AST Transformation',
+  TYPESCRIPT_VALIDATION: 'TypeScript / JS Validation',
+  BUILD_SUCCESS: 'Next.js Build',
+  FIVORA_CONTRACT: 'Fivora Contract',
+  MANIFEST_SITE_DATA: 'Manifest / Site Data',
+  RUNTIME_DATA_BINDING: 'Runtime Data Binding',
+  RUNTIME_COLLECTION_OPS: 'Runtime Collection Operations',
+  RUNTIME_IMAGE_EDITING: 'Runtime Image Editing',
+  ROUTE_COVERAGE: 'Route Coverage',
+  DESIGN_PRESERVATION: 'Design Preservation',
+  CONTROL_ONLY_PROTECTION: 'Control-Only Protection',
+};
+
+/**
+ * Evaluates compilation metrics against the 12-Gate Acceptance Matrix.
+ */
+function evaluateAcceptanceGates(metrics = {}) {
+  const gates = {
+    sourceAnalysis: {
+      name: ACCEPTANCE_GATES.SOURCE_ANALYSIS,
+      passed: Boolean(metrics.sourceAnalysis?.passed !== false),
+      critical: true,
+    },
+    astTransformation: {
+      name: ACCEPTANCE_GATES.AST_TRANSFORMATION,
+      passed: Boolean(metrics.astTransformation?.passed !== false),
+      critical: true,
+    },
+    typescriptValidation: {
+      name: ACCEPTANCE_GATES.TYPESCRIPT_VALIDATION,
+      passed: Boolean(metrics.typescriptValidation?.passed !== false),
+      critical: true,
+    },
+    buildSuccess: {
+      name: ACCEPTANCE_GATES.BUILD_SUCCESS,
+      passed: Boolean(metrics.buildSuccess?.passed !== false),
+      critical: true,
+    },
+    fivoraContract: {
+      name: ACCEPTANCE_GATES.FIVORA_CONTRACT,
+      passed: Boolean(
+        metrics.fivoraAudit?.passed === true ||
+        metrics.fivoraContract?.passed === true ||
+        (metrics.fivoraAudit === undefined && metrics.fivoraContract === undefined)
+      ),
+      critical: true,
+    },
+    manifestSiteData: {
+      name: ACCEPTANCE_GATES.MANIFEST_SITE_DATA,
+      passed: Boolean(metrics.manifestValid !== false),
+      critical: true,
+    },
+    runtimeDataBinding: {
+      name: ACCEPTANCE_GATES.RUNTIME_DATA_BINDING,
+      passed: Boolean((metrics.runtimeEditabilityScore ?? 100) >= 98),
+      critical: true,
+    },
+    runtimeCollectionOps: {
+      name: ACCEPTANCE_GATES.RUNTIME_COLLECTION_OPS,
+      passed: Boolean(metrics.collectionOpsPassed !== false),
+      critical: true,
+    },
+    runtimeImageEditing: {
+      name: ACCEPTANCE_GATES.RUNTIME_IMAGE_EDITING,
+      passed: Boolean(metrics.imageEditingPassed !== false),
+      critical: false,
+    },
+    routeCoverage: {
+      name: ACCEPTANCE_GATES.ROUTE_COVERAGE,
+      passed: Boolean(metrics.routeCoveragePassed !== false),
+      critical: false,
+    },
+    designPreservation: {
+      name: ACCEPTANCE_GATES.DESIGN_PRESERVATION,
+      passed: Boolean((metrics.designPreservationScore ?? 100) >= 98),
+      critical: false,
+    },
+    controlOnlyProtection: {
+      name: ACCEPTANCE_GATES.CONTROL_ONLY_PROTECTION,
+      passed: Boolean(metrics.controlOnlyValid !== false),
+      critical: true,
+    },
+  };
+
+  const criticalGates = Object.values(gates).filter((g) => g.critical);
+  const allCriticalPassed = criticalGates.every((g) => g.passed);
+  const editabilityCoverage = metrics.editabilityCoverage ?? 100;
+  const designPreservation = metrics.designPreservationScore ?? 100;
+
+  // Conversion only passes when all critical gates pass and editability coverage >= 98%
+  const conversionPassed = allCriticalPassed && editabilityCoverage >= 98;
+  const status = conversionPassed
+    ? 'CONVERSION_PASSED'
+    : allCriticalPassed
+      ? 'CONVERSION_INCOMPLETE'
+      : 'CONVERSION_FAILED';
+
+  return {
+    passed: conversionPassed,
+    status,
+    gates,
+    allCriticalPassed,
+    editabilityCoverage,
+    designPreservation,
+  };
+}
+
+module.exports = {
+  ACCEPTANCE_GATES,
+  evaluateAcceptanceGates,
+};

package/src/arc/canonical-paths.cjs

@@ -4,37 +4,82 @@ const recast = require('recast');
 const b = recast.types.builders;
 
 /**
- * Canonical Path Abstraction for Deneb ARC.
- * Prevents subtle path drift between runtime siteData getters and visual DOM markers.
+ * Deneb ARC v3 — Canonical Path Engine
+ * Single Source of Truth for runtime siteData accessors, visual DOM markers,
+ * schema generation, and diagnostics identity.
  */
 class CanonicalFieldRef {
-  constructor(canonicalPath) {
+  /**
+   * @param {string} canonicalPath - e.g. "home.hero.title" or "home.categories[0].name"
+   * @param {object} [options]
+   * @param {object} [options.provenance] - Origin tracking (file, loc, component, kind)
+   * @param {boolean} [options.isCollection] - Whether path is an array collection
+   */
+  constructor(canonicalPath, options = {}) {
     if (!canonicalPath || typeof canonicalPath !== 'string') {
       throw new Error(`Invalid canonical path: ${canonicalPath}`);
     }
-    this.path = canonicalPath;
-    this.parts = canonicalPath.split('.').filter(Boolean);
-    this.scope = this.parts[0] || 'home';
-    this.section = this.parts.length > 2 ? this.parts[1] : null;
-    this.fieldName = this.parts[this.parts.length - 1];
+    const cleanPath = canonicalPath.trim().replace(/^\.+|\.+$/g, '');
+    if (!cleanPath) {
+      throw new Error(`Empty canonical path after normalization: ${canonicalPath}`);
+    }
+
+    this.path = cleanPath;
+    this.canonicalPath = cleanPath;
+    this.provenance = options.provenance || {};
+
+    // Segment split while preserving bracket indices
+    this.parts = cleanPath.split('.').filter(Boolean);
+    const firstPart = this.parts[0] || 'home';
+    this.scope = firstPart.replace(/\[.*$/, '');
+    this.section = this.parts.length > 2 ? this.parts[1].replace(/\[.*$/, '') : null;
+    this.fieldName = (this.parts[this.parts.length - 1] || '').replace(/\[.*$/, '');
+
+    this.previewPath = cleanPath;
+    this.previewMarker = `data-preview-field-path="${cleanPath}"`;
+    this.runtimePath = `siteData.content.${cleanPath}`;
+    this.manifestSchemaPath = cleanPath;
+    this.diagnosticsId = `field:${cleanPath}`;
+    this.isCollection = Boolean(options.isCollection || /\[\d+\]|\[\$\{[^}]+\}\]/.test(cleanPath));
+
+    // Construct readable runtime accessor string
+    const accessorSegments = ['siteData', 'content', ...this.parts];
+    this.runtimeAccessor = accessorSegments
+      .map((seg, i) => {
+        if (i === 0) return seg;
+        if (/^([a-zA-Z0-9_-]+)\[(\d+|\$\{[^}]+\})\]$/.test(seg)) {
+          const match = seg.match(/^([a-zA-Z0-9_-]+)\[(\d+|\$\{[^}]+\})\]$/);
+          return `?.${match[1]}?.[${match[2]}]`;
+        }
+        return `?.${seg}`;
+      })
+      .join('');
   }
 
   /**
-   * Builds the optional chaining AST expression:
-   * siteData?.content?.home?.section?.field
+   * Builds optional chaining AST expression:
+   * siteData?.content?.home?.hero?.title
    */
   toGetterAst() {
     let expr = b.identifier('siteData');
     const allParts = ['content', ...this.parts];
     for (const part of allParts) {
-      expr = b.optionalMemberExpression(expr, b.identifier(part), false, true);
+      const arrayMatch = part.match(/^([a-zA-Z0-9_-]+)\[(\d+)\]$/);
+      if (arrayMatch) {
+        const propName = arrayMatch[1];
+        const idx = parseInt(arrayMatch[2], 10);
+        expr = b.optionalMemberExpression(expr, b.identifier(propName), false, true);
+        expr = b.optionalMemberExpression(expr, b.numericLiteral(idx), true, true);
+      } else {
+        expr = b.optionalMemberExpression(expr, b.identifier(part), false, true);
+      }
     }
     return expr;
   }
 
   /**
-   * Builds the fallback expression:
-   * siteData?.content?.home?.section?.field ?? fallback
+   * Builds fallback expression:
+   * siteData?.content?.home?.hero?.title ?? fallback
    */
   toBindingAst(fallbackValue = '') {
     const getter = this.toGetterAst();
@@ -50,8 +95,8 @@ class CanonicalFieldRef {
   }
 
   /**
-   * Builds the JSX attribute AST:
-   * data-preview-field-path="home.section.field"
+   * Builds JSX attribute AST:
+   * data-preview-field-path="home.hero.title"
    */
   toPreviewAttrAst() {
     return b.jsxAttribute(
@@ -61,9 +106,71 @@ class CanonicalFieldRef {
   }
 
   /**
-   * Generates a nested item path for sub-collections:
-   * e.g. parentPath="home.categories[0]", childProp="products", childIndex="2"
-   * -> "home.categories[0].products[2]"
+   * Builds JSX attribute AST for style binding targets:
+   * data-preview-style-target="home.hero.title"
+   */
+  toPreviewStyleTargetAst() {
+    return b.jsxAttribute(
+      b.jsxIdentifier('data-preview-style-target'),
+      b.stringLiteral(this.path)
+    );
+  }
+
+  /**
+   * Generates assignment code for runtime or testing mutations:
+   * siteData.content.home.hero.title = value;
+   */
+  toSetterCode(valueExpr = 'value') {
+    return `siteData.content.${this.path} = ${valueExpr};`;
+  }
+
+  /**
+   * Derives a child item reference for collections:
+   * e.g. "home.categories" -> "home.categories[0]"
+   */
+  toCollectionItem(index) {
+    const itemPath = `${this.path}[${index}]`;
+    return new CanonicalFieldRef(itemPath, {
+      provenance: { ...this.provenance, parentPath: this.path, index },
+    });
+  }
+
+  /**
+   * Derives a nested collection child reference:
+   * e.g. "home.categories[0]" -> "home.categories[0].products[2]"
+   */
+  toCollectionChild(childProp, childIndexExpr) {
+    const childPath = childIndexExpr !== undefined
+      ? `${this.path}.${childProp}[${childIndexExpr}]`
+      : `${this.path}.${childProp}`;
+    return new CanonicalFieldRef(childPath, {
+      provenance: { ...this.provenance, parentPath: this.path, childProp },
+    });
+  }
+
+  /**
+   * Validates canonical path syntax and structure
+   */
+  validate() {
+    if (!isValidCanonicalPath(this.path)) {
+      return {
+        valid: false,
+        error: `Syntax violation in canonical path "${this.path}"`,
+      };
+    }
+    if (!this.scope) {
+      return {
+        valid: false,
+        error: `Missing root scope in canonical path "${this.path}"`,
+      };
+    }
+    return { valid: true };
+  }
+
+  /**
+   * Static helper for nested collection template literals:
+   * e.g. parentPath="home.categories[0]", childProp="products", childIndexExpr="index"
+   * -> "home.categories[0].products[${index}]"
    */
   static buildNestedItemPath(parentItemPath, childProp, childIndexExpr = 'index') {
     return `${parentItemPath}.${childProp}[\${${childIndexExpr}}]`;
@@ -72,23 +179,35 @@ class CanonicalFieldRef {
 
 function isValidCanonicalPath(canonicalPath) {
   if (typeof canonicalPath !== 'string' || !canonicalPath.trim()) return false;
-  return /^[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+|\[\d+\]|\[\$\{[^}]+\}\])*$/.test(canonicalPath);
+  return /^[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+|\[\d+\]|\[\$\{[^}]+\}\])*$/.test(canonicalPath.trim());
 }
 
 function validatePathAlignment(getterCode, previewAttrCode) {
   const normalizedGetter = String(getterCode || '').replace(/\?\./g, '.');
-  const getterMatch = normalizedGetter.match(/siteData\.content\.([a-zA-Z0-9_.]+)/);
-  const attrMatch = String(previewAttrCode || '').match(/data-preview-field-path=["'`{]([a-zA-Z0-9_.]+)/);
+  const getterMatch = normalizedGetter.match(/siteData\.content\.([a-zA-Z0-9_.[\]]+)/);
+  const attrMatch = String(previewAttrCode || '').match(/data-preview-field-path=["'`{]([a-zA-Z0-9_.[\]]+)/);
   if (!getterMatch || !attrMatch) return false;
   return getterMatch[1] === attrMatch[1];
 }
 
-function fieldRef(canonicalPath) {
-  return new CanonicalFieldRef(canonicalPath);
+/**
+ * Primary factory function for CanonicalFieldRef
+ * Single source of truth across compiler, transformer, and runtime validator.
+ */
+function canonicalField(rawPath, options) {
+  return new CanonicalFieldRef(rawPath, options);
+}
+
+/**
+ * Backward-compatible alias
+ */
+function fieldRef(canonicalPath, options) {
+  return canonicalField(canonicalPath, options);
 }
 
 module.exports = {
   CanonicalFieldRef,
+  canonicalField,
   fieldRef,
   isValidCanonicalPath,
   validatePathAlignment,