@deneb-ui/cli 2.0.84 → 2.0.86

package/src/arc/adapters.cjs

@@ -1,14 +1,17 @@
 'use strict';
 
-const { getJsxName, getJsxAttributeLiteral, hasJsxAttribute, collectJsxText } = require('./ast.cjs');
-
-function createAdapter(id, impl) {
-  return { id, ...impl };
-}
-
-function detectFromProfile(profile, id) {
-  return (profile.componentLibraries || []).includes(id) || profile[id] === true;
-}
+const { collectJsxText, getJsxAttributeLiteral } = require('./ast.cjs');
+const {
+  AdapterRegistry,
+  defaultRegistry,
+  BUILTIN_ADAPTERS,
+  registerAdapter,
+  getAdapter,
+  getAllAdapters,
+  activeAdapters,
+  recognizeWithAdapters,
+  resolveActionWithAdapters,
+} = require('./adapters/registry.cjs');
 
 const ICON_NAME_RE = /^(Icon|[A-Z][A-Za-z0-9]*(Icon|Logo)|Lucide[A-Z]|HiOutline|HiSolid|Fa[A-Z]|Md[A-Z]|Io[A-Z])/;
 const DECORATIVE_TAGS = new Set([
@@ -22,151 +25,11 @@ const SKIP_TAGS = new Set([
 const HEADING_TAGS = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'Heading', 'Title', 'CardTitle', 'ModalHeader', 'DialogTitle']);
 const TEXT_TAGS = new Set(['p', 'span', 'li', 'blockquote', 'figcaption', 'label', 'CardDescription', 'Description', 'Subtitle', 'Typography', 'Text', 'Badge', 'badge']);
 const ACTION_TAGS = new Set(['a', 'Link', 'NavLink', 'Button', 'button', 'IconButton', 'NavbarBrand']);
-const IMAGE_TAGS = new Set(['img', 'Image', 'Img', 'BackgroundImage']);
+const IMAGE_TAGS = new Set(['img', 'Image', 'Img', 'BackgroundImage', 'picture']);
 const FORM_INPUT_TAGS = new Set(['input', 'Input', 'textarea', 'Textarea', 'select', 'Select']);
 const FORM_CONTAINER_TAGS = new Set(['form', 'Form']);
 
-const shadcn = createAdapter('shadcn', {
-  detect: (project) => detectFromProfile(project, 'shadcn') || project.shadcn,
-  recognizeNode(node, ctx) {
-    const name = getJsxName(node);
-    if (name === 'Button') {
-      return { library: 'shadcn', kind: 'button', asChild: hasJsxAttribute(node, 'asChild') };
-    }
-    if (name === 'CardTitle' || name === 'CardDescription' || name === 'Badge') {
-      return { library: 'shadcn', kind: 'text', tag: name };
-    }
-    return null;
-  },
-  resolveAction(node) {
-    const name = getJsxName(node);
-    if (name === 'Button' && hasJsxAttribute(node, 'asChild')) {
-      const child = (node.children || []).find((c) => c && c.type === 'JSXElement');
-      if (child && ACTION_TAGS.has(getJsxName(child))) return child;
-    }
-    return null;
-  },
-});
-
-const heroui = createAdapter('heroui', {
-  detect: (project) => detectFromProfile(project, 'heroui') || project.heroui,
-  recognizeNode(node) {
-    const name = getJsxName(node);
-    if (['Button', 'Link', 'Navbar', 'NavbarBrand', 'NavbarItem', 'NavbarContent'].includes(name)) {
-      return { library: 'heroui', kind: name === 'Button' || name === 'Link' ? 'action' : 'structure', tag: name };
-    }
-    return null;
-  },
-  resolveAction(node) {
-    const name = getJsxName(node);
-    if (name === 'Button' && (hasJsxAttribute(node, 'href') || hasJsxAttribute(node, 'as'))) return node;
-    if (name === 'Link') return node;
-    return null;
-  },
-});
-
-const nextjs = createAdapter('nextjs', {
-  detect: (project) => project.framework === 'nextjs',
-  recognizeNode(node) {
-    const name = getJsxName(node);
-    if (name === 'Link') return { library: 'nextjs', kind: 'action', tag: 'Link' };
-    if (name === 'Image') return { library: 'nextjs', kind: 'image', tag: 'Image' };
-    return null;
-  },
-  resolveAction(node) {
-    return getJsxName(node) === 'Link' ? node : null;
-  },
-});
-
-const framer = createAdapter('framer-motion', {
-  detect: (project) => (project.animationLibraries || []).includes('framer-motion'),
-  recognizeNode(node) {
-    const name = getJsxName(node);
-    if (name.startsWith('motion.')) {
-      const tag = name.slice('motion.'.length);
-      return { library: 'framer-motion', kind: HEADING_TAGS.has(tag) || TEXT_TAGS.has(tag) ? 'text' : 'structure', tag };
-    }
-    return null;
-  },
-});
-
-const reactBits = createAdapter('react-bits', {
-  detect: (project) => project.reactBits,
-  recognizeNode(node) {
-    const name = getJsxName(node);
-    if (/SplitText|BlurText|GradientText|ShinyText|CountUp|RotatingText/.test(name)) {
-      return { library: 'react-bits', kind: 'text', tag: name };
-    }
-    return null;
-  },
-});
-
-const deneb = createAdapter('deneb', {
-  detect: (project) =>
-    (project.componentLibraries || []).includes('@deneb-ui/ui') ||
-    project['@deneb-ui/ui'] === true ||
-    Boolean(project.dependencies && project.dependencies['@deneb-ui/ui']),
-  recognizeNode(node) {
-    const name = getJsxName(node);
-    if (['EditableContactForm', 'ContactForm'].includes(name)) {
-      return { library: 'deneb', kind: 'form', tag: name };
-    }
-    if (['EditableGoogleFeedback', 'EditableCustomerReviews', 'CustomerReviews', 'GoogleFeedback'].includes(name)) {
-      return { library: 'deneb', kind: 'feedback', tag: name };
-    }
-    if (['EditableTestimonialSection', 'EditableTestimonialCard', 'TestimonialSection', 'Testimonials'].includes(name)) {
-      return { library: 'deneb', kind: 'testimonial', tag: name };
-    }
-    if (name === 'EditableMap' || name === 'Map') {
-      return { library: 'deneb', kind: 'map', tag: name };
-    }
-    if (['EditableImage', 'EditableText', 'EditableCard', 'EditableProductCard', 'Image', 'Text', 'Card'].includes(name)) {
-      return { library: 'deneb', kind: 'editable-primitive', tag: name };
-    }
-    return null;
-  },
-});
-
-const radix = createAdapter('radix', {
-  detect: (project) => (project.componentLibraries || []).includes('radix'),
-  recognizeNode(node) {
-    const name = getJsxName(node);
-    if (name === 'Slot' || name.endsWith('.Root') || name.endsWith('.Trigger')) {
-      return { library: 'radix', kind: 'structure', tag: name };
-    }
-    return null;
-  },
-});
-
-const ADAPTERS = [nextjs, deneb, shadcn, heroui, framer, reactBits, radix];
-
-function activeAdapters(profile) {
-  return ADAPTERS.filter((adapter) => {
-    try {
-      return adapter.detect(profile);
-    } catch {
-      return false;
-    }
-  });
-}
-
-function recognizeWithAdapters(node, ctx, adapters) {
-  for (const adapter of adapters) {
-    if (!adapter.recognizeNode) continue;
-    const result = adapter.recognizeNode(node, ctx);
-    if (result) return { ...result, adapterId: adapter.id };
-  }
-  return null;
-}
-
-function resolveActionWithAdapters(node, adapters) {
-  for (const adapter of adapters) {
-    if (!adapter.resolveAction) continue;
-    const result = adapter.resolveAction(node);
-    if (result) return result;
-  }
-  return null;
-}
+const ADAPTERS = BUILTIN_ADAPTERS;
 
 function isIconComponent(name, importSource) {
   if (!name) return false;
@@ -283,6 +146,12 @@ function classifyActionIntent(text, href) {
 }
 
 module.exports = {
+  AdapterRegistry,
+  defaultRegistry,
+  BUILTIN_ADAPTERS,
+  registerAdapter,
+  getAdapter,
+  getAllAdapters,
   ADAPTERS,
   activeAdapters,
   recognizeWithAdapters,

package/src/arc/canonical-paths.cjs

@@ -0,0 +1,95 @@
+'use strict';
+
+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.
+ */
+class CanonicalFieldRef {
+  constructor(canonicalPath) {
+    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];
+  }
+
+  /**
+   * Builds the optional chaining AST expression:
+   * siteData?.content?.home?.section?.field
+   */
+  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);
+    }
+    return expr;
+  }
+
+  /**
+   * Builds the fallback expression:
+   * siteData?.content?.home?.section?.field ?? fallback
+   */
+  toBindingAst(fallbackValue = '') {
+    const getter = this.toGetterAst();
+    let fallbackAst;
+    if (typeof fallbackValue === 'number') {
+      fallbackAst = b.literal(fallbackValue);
+    } else if (typeof fallbackValue === 'boolean') {
+      fallbackAst = b.literal(fallbackValue);
+    } else {
+      fallbackAst = b.stringLiteral(String(fallbackValue));
+    }
+    return b.logicalExpression('??', getter, fallbackAst);
+  }
+
+  /**
+   * Builds the JSX attribute AST:
+   * data-preview-field-path="home.section.field"
+   */
+  toPreviewAttrAst() {
+    return b.jsxAttribute(
+      b.jsxIdentifier('data-preview-field-path'),
+      b.stringLiteral(this.path)
+    );
+  }
+
+  /**
+   * Generates a nested item path for sub-collections:
+   * e.g. parentPath="home.categories[0]", childProp="products", childIndex="2"
+   * -> "home.categories[0].products[2]"
+   */
+  static buildNestedItemPath(parentItemPath, childProp, childIndexExpr = 'index') {
+    return `${parentItemPath}.${childProp}[\${${childIndexExpr}}]`;
+  }
+}
+
+function isValidCanonicalPath(canonicalPath) {
+  if (typeof canonicalPath !== 'string' || !canonicalPath.trim()) return false;
+  return /^[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+|\[\d+\]|\[\$\{[^}]+\}\])*$/.test(canonicalPath);
+}
+
+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_.]+)/);
+  if (!getterMatch || !attrMatch) return false;
+  return getterMatch[1] === attrMatch[1];
+}
+
+function fieldRef(canonicalPath) {
+  return new CanonicalFieldRef(canonicalPath);
+}
+
+module.exports = {
+  CanonicalFieldRef,
+  fieldRef,
+  isValidCanonicalPath,
+  validatePathAlignment,
+};

package/src/arc/data-flow.cjs

@@ -0,0 +1,158 @@
+'use strict';
+
+const { unwrapExpr } = require('./ast.cjs');
+
+/**
+ * Array pipeline methods commonly used before .map()
+ */
+const ARRAY_TRANSFORM_METHODS = new Set([
+  'filter',
+  'slice',
+  'sort',
+  'concat',
+  'reverse',
+  'flatMap',
+  'take',
+  'splice',
+]);
+
+/**
+ * Unrolls a chained array expression to its root data source identifier.
+ * e.g.:
+ *   products.slice(0, 4) -> 'products'
+ *   products.filter(p => p.featured).slice(0, 4) -> 'products'
+ *   Object.values(products) -> 'products'
+ *   [...featured, ...newItems] -> ['featured', 'newItems']
+ */
+function unrollCollectionSource(exprNode, aliasMap = new Map()) {
+  if (!exprNode) return null;
+  let curr = unwrapExpr(exprNode);
+
+  // Direct identifier: products
+  if (curr.type === 'Identifier') {
+    const name = curr.name;
+    if (aliasMap.has(name)) {
+      return aliasMap.get(name);
+    }
+    return { rootName: name, chain: [], kind: 'identifier' };
+  }
+
+  // Method call: products.slice(0, 4) or products.filter(...).slice(...)
+  if (curr.type === 'CallExpression') {
+    const callee = curr.callee;
+
+    // Object.values(products) or Object.entries(products)
+    if (
+      callee?.type === 'MemberExpression' &&
+      callee.object?.type === 'Identifier' &&
+      callee.object.name === 'Object' &&
+      callee.property?.type === 'Identifier' &&
+      (callee.property.name === 'values' || callee.property.name === 'entries')
+    ) {
+      const arg = curr.arguments?.[0];
+      if (arg?.type === 'Identifier') {
+        const root = unrollCollectionSource(arg, aliasMap);
+        return {
+          rootName: root?.rootName || arg.name,
+          chain: ['Object.' + callee.property.name, ...(root?.chain || [])],
+          kind: 'object-values',
+        };
+      }
+    }
+
+    // array.method(...)
+    if (callee?.type === 'MemberExpression' && !callee.computed && callee.property?.type === 'Identifier') {
+      const methodName = callee.property.name;
+      if (ARRAY_TRANSFORM_METHODS.has(methodName) || methodName === 'map') {
+        const sub = unrollCollectionSource(callee.object, aliasMap);
+        if (sub) {
+          return {
+            rootName: sub.rootName,
+            chain: [methodName, ...sub.chain],
+            kind: 'pipeline',
+          };
+        }
+      }
+    }
+  }
+
+  // Array spread literal: [...featured, ...newItems]
+  if (curr.type === 'ArrayExpression') {
+    const roots = [];
+    for (const el of curr.elements || []) {
+      if (el?.type === 'SpreadElement' && el.argument?.type === 'Identifier') {
+        const sub = unrollCollectionSource(el.argument, aliasMap);
+        roots.push(sub?.rootName || el.argument.name);
+      } else if (el?.type === 'Identifier') {
+        const sub = unrollCollectionSource(el, aliasMap);
+        roots.push(sub?.rootName || el.name);
+      }
+    }
+    if (roots.length > 0) {
+      return {
+        rootName: roots[0],
+        additionalRoots: roots.slice(1),
+        chain: ['spread-merge'],
+        kind: 'spread',
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Collects variable aliases inside an AST that point to arrays.
+ * e.g. `const featuredProducts = products.slice(0, 4);`
+ */
+function collectVariableAliases(ast) {
+  const aliases = new Map();
+  if (!ast) return aliases;
+
+  const recast = require('recast');
+  recast.types.visit(ast, {
+    visitVariableDeclarator(pathNode) {
+      const node = pathNode.node;
+      if (node.id?.type === 'Identifier' && node.init) {
+        const varName = node.id.name;
+        const resolved = unrollCollectionSource(node.init, aliases);
+        if (resolved && (resolved.rootName || resolved.rootIdentifier)) {
+          aliases.set(varName, {
+            ...resolved,
+            rootIdentifier: resolved.rootIdentifier || resolved.rootName,
+            transformMethod: resolved.chain?.[0] || 'slice',
+          });
+        }
+      }
+      this.traverse(pathNode);
+    },
+  });
+
+  return aliases;
+}
+
+module.exports = {
+  ARRAY_TRANSFORM_METHODS,
+  unrollCollectionSource,
+  unrollCollectionPipelines: (ast) => {
+    const pipelines = [];
+    const recast = require('recast');
+    recast.types.visit(ast, {
+      visitCallExpression(pathNode) {
+        if (pathNode.node.callee?.property?.name === 'map') {
+          const res = unrollCollectionSource(pathNode.node.callee.object);
+          if (res && res.chain && res.chain.length > 0) {
+            pipelines.push({
+              rootIdentifier: res.rootName || res.rootIdentifier,
+              pipelineChain: [...res.chain].reverse(),
+            });
+          }
+        }
+        this.traverse(pathNode);
+      },
+    });
+    return pipelines;
+  },
+  collectVariableAliases,
+  resolveVariableAliases: collectVariableAliases,
+};

package/src/arc/diff.cjs

@@ -0,0 +1,136 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { scanProject } = require('./scanner.cjs');
+const { buildProjectIR } = require('./ir-builder.cjs');
+const { analyzeFile } = require('./semantic.cjs');
+const { planTransformations } = require('./planner.cjs');
+const { applyFilePlan } = require('./transformer.cjs');
+
+/**
+ * Computes a unified diff string between original and transformed code.
+ */
+function createUnifiedDiff(filename, oldCode, newCode) {
+  const oldLines = oldCode.split('\n');
+  const newLines = newCode.split('\n');
+  const diffLines = [];
+
+  diffLines.push(`--- a/${filename}`);
+  diffLines.push(`+++ b/${filename}`);
+
+  let additions = 0;
+  let deletions = 0;
+
+  // Simple chunk comparison for clear visual inspection
+  const max = Math.max(oldLines.length, newLines.length);
+  for (let i = 0; i < max; i++) {
+    const oldLine = oldLines[i];
+    const newLine = newLines[i];
+
+    if (oldLine === newLine) {
+      continue;
+    }
+
+    if (oldLine !== undefined && (newLine === undefined || oldLine.trim() !== newLine.trim())) {
+      diffLines.push(`- ${oldLine}`);
+      deletions++;
+    }
+    if (newLine !== undefined && (oldLine === undefined || oldLine.trim() !== newLine.trim())) {
+      diffLines.push(`+ ${newLine}`);
+      additions++;
+    }
+  }
+
+  return {
+    filename,
+    diff: diffLines.join('\n'),
+    additions,
+    deletions,
+  };
+}
+
+/**
+ * Simulates ARC conversion and generates unified diffs for all modified files.
+ * Zero files are written to disk.
+ *
+ * @param {string} targetDirInput - Target project directory.
+ * @param {object} options - Options including profile overrides.
+ * @returns {Array} Array of file diff objects.
+ */
+function generateArcDiff(targetDirInput = '.', options = {}) {
+  const projectDir = path.resolve(targetDirInput);
+  const profile = scanProject(projectDir);
+  const ir = buildProjectIR(projectDir, profile);
+
+  const analyses = (profile.jsxFiles || []).map((relativeFile) => {
+    const absPath = path.join(projectDir, relativeFile);
+    if (!fs.existsSync(absPath)) return null;
+    const code = fs.readFileSync(absPath, 'utf8');
+    return analyzeFile({
+      code,
+      relativeFile,
+      profile,
+      ir,
+    });
+  }).filter(Boolean);
+
+  const plan = planTransformations({
+    profile,
+    analyses,
+    ir,
+  });
+
+  const fileDiffs = [];
+
+  for (const filePlan of plan.files || []) {
+    if (!filePlan.transformations?.length || filePlan.skippedFile) continue;
+    let result;
+    try {
+      result = applyFilePlan(filePlan, profile);
+    } catch {
+      continue;
+    }
+
+    if (result && result.changed && result.code !== filePlan.originalCode) {
+      const fileDiff = createUnifiedDiff(filePlan.file, filePlan.originalCode, result.code);
+      fileDiffs.push(fileDiff);
+    }
+  }
+
+  return fileDiffs;
+}
+
+/**
+ * Pretty-prints file diffs to stdout.
+ */
+function printDiff(fileDiffs) {
+  console.log(`\n\x1b[1m\x1b[36mDENEB ARC DIFF\x1b[0m \x1b[90m— Simulated Transformation Diff\x1b[0m`);
+  if (!fileDiffs.length) {
+    console.log(`\x1b[32m✔ No changes planned or all files already editable.\x1b[0m\n`);
+    return;
+  }
+
+  for (const fd of fileDiffs) {
+    console.log(`\n\x1b[1m\x1b[34mDiff: ${fd.filename}\x1b[0m \x1b[90m(+${fd.additions} -${fd.deletions})\x1b[0m`);
+    const lines = fd.diff.split('\n');
+    for (const line of lines) {
+      if (line.startsWith('---') || line.startsWith('+++')) {
+        console.log(`\x1b[1m${line}\x1b[0m`);
+      } else if (line.startsWith('+')) {
+        console.log(`\x1b[32m${line}\x1b[0m`);
+      } else if (line.startsWith('-')) {
+        console.log(`\x1b[31m${line}\x1b[0m`);
+      } else {
+        console.log(`\x1b[90m${line}\x1b[0m`);
+      }
+    }
+  }
+  console.log('');
+}
+
+module.exports = {
+  createUnifiedDiff,
+  generateArcDiff,
+  printDiff,
+};

package/src/arc/explain.cjs

@@ -0,0 +1,113 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { analyzeFile } = require('./semantic.cjs');
+const { scanProject } = require('./scanner.cjs');
+const { buildProjectIR } = require('./ir-builder.cjs');
+
+/**
+ * Explains how Deneb ARC analyzes and intends to refactor a specific component file.
+ *
+ * @param {string} fileInput - Path to the file to explain.
+ * @param {object} options - Options including root project directory and json format flag.
+ * @returns {object} Analysis explanation summary.
+ */
+function explainFile(fileInput, options = {}) {
+  const absPath = path.resolve(options.root || '.', fileInput);
+  if (!fs.existsSync(absPath)) {
+    throw new Error(`File not found: ${fileInput} (resolved to ${absPath})`);
+  }
+
+  const code = fs.readFileSync(absPath, 'utf8');
+  const projectDir = options.root ? path.resolve(options.root) : path.dirname(absPath);
+  const relativeFile = path.relative(projectDir, absPath).replace(/\\/g, '/');
+
+  let profile = options.profile;
+  let ir = options.ir;
+  if (!profile) {
+    try {
+      profile = scanProject(projectDir);
+      ir = buildProjectIR(projectDir, profile);
+    } catch {
+      profile = { framework: 'nextjs', root: projectDir };
+      ir = null;
+    }
+  }
+
+  const analysis = analyzeFile({
+    code,
+    relativeFile,
+    profile,
+    ir,
+  });
+
+  const candidates = analysis.candidates || [];
+  const editable = candidates.filter((c) => !c.skip);
+  const skipped = candidates.filter((c) => c.skip);
+
+  const explanation = {
+    file: relativeFile,
+    absolutePath: absPath,
+    isTypeScript: /\.(tsx|ts)$/.test(relativeFile),
+    alreadyEditable: analysis.alreadyEditable,
+    importsCount: Object.keys(analysis.imports || {}).length,
+    imports: analysis.imports || {},
+    totalCandidates: candidates.length,
+    editableCount: editable.length,
+    skippedCount: skipped.length,
+    editableElements: editable.map((c) => ({
+      tag: c.tag,
+      kind: c.kind,
+      operation: c.operation,
+      loc: c.loc,
+      value: c.value,
+      confidence: c.confidence,
+      reason: c.reason,
+      proposedField: c.field || `home.${c.kind || 'field'}`,
+    })),
+    skippedElements: skipped.map((c) => ({
+      tag: c.tag,
+      kind: c.kind,
+      loc: c.loc,
+      reason: c.reason,
+      confidence: c.confidence,
+    })),
+  };
+
+  return explanation;
+}
+
+/**
+ * Pretty-prints the explanation to stdout.
+ */
+function printExplanation(explanation) {
+  console.log(`\n\x1b[1m\x1b[36mDENEB ARC EXPLAIN\x1b[0m \x1b[90m— Component Analysis\x1b[0m`);
+  console.log(`\x1b[1mFile:\x1b[0m ${explanation.file}`);
+  console.log(`\x1b[90mFormat: ${explanation.isTypeScript ? 'TypeScript (TSX)' : 'JavaScript (JSX)'} | Editable: ${explanation.alreadyEditable ? 'Yes' : 'Pending'}\x1b[0m\n`);
+
+  console.log(`\x1b[1mDiscovered Elements (${explanation.totalCandidates} total, ${explanation.editableCount} editable):\x1b[0m`);
+  for (const el of explanation.editableElements) {
+    const kindTag = `\x1b[32m[${el.kind.toUpperCase()}]\x1b[0m`;
+    const locTag = `\x1b[90m(${el.loc})\x1b[0m`;
+    const val = typeof el.value === 'string' ? `"${el.value.slice(0, 40)}${el.value.length > 40 ? '...' : ''}"` : '';
+    console.log(`  ${kindTag} <${el.tag}> ${locTag} ${val}`);
+    console.log(`    \x1b[90m↳ Proposed path:\x1b[0m \x1b[33m${el.proposedField}\x1b[0m \x1b[90m(confidence: ${Math.round((el.confidence || 0.8) * 100)}%)\x1b[0m`);
+  }
+
+  if (explanation.skippedElements.length > 0) {
+    console.log(`\n\x1b[1mPreserved / Skipped Elements (${explanation.skippedElements.length}):\x1b[0m`);
+    for (const el of explanation.skippedElements.slice(0, 10)) {
+      console.log(`  \x1b[90m[PRESERVED] <${el.tag}> (${el.loc}) — reason: ${el.reason}\x1b[0m`);
+    }
+    if (explanation.skippedElements.length > 10) {
+      console.log(`  \x1b[90m... and ${explanation.skippedElements.length - 10} more\x1b[0m`);
+    }
+  }
+  console.log('');
+}
+
+module.exports = {
+  explainFile,
+  printExplanation,
+};