@deneb-ui/cli 2.0.87 → 2.0.89

package/src/arc/explain-blocked.cjs

@@ -0,0 +1,388 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const contract = require('./fivora-contract.cjs');
+const { validateRuntimeEditabilitySync, validateCollectionOperations } = require('./runtime-validator.cjs');
+const { evaluateAcceptanceGates } = require('./acceptance-gates.cjs');
+const { resolveSiteDataFile } = require('./corpus-verifier.cjs');
+
+const IGNORED_SOURCE_DIRS = new Set([
+  'node_modules',
+  'out',
+  'dist',
+  'build',
+  '.next',
+  '.turbo',
+  '.cache',
+]);
+
+function collectSourceFiles(dir) {
+  const sources = [];
+  function walk(current) {
+    if (!fs.existsSync(current)) return;
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const lower = entry.name.toLowerCase();
+      if (IGNORED_SOURCE_DIRS.has(lower) || entry.name.startsWith('.deneb') || entry.name.startsWith('.')) continue;
+      const abs = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        walk(abs);
+      } else if (/\.(tsx|jsx|ts|js)$/.test(entry.name)) {
+        try {
+          sources.push({
+            abs,
+            rel: path.relative(dir, abs).replace(/\\/g, '/'),
+            code: fs.readFileSync(abs, 'utf8'),
+          });
+        } catch {}
+      }
+    }
+  }
+  walk(dir);
+  return sources;
+}
+
+function findLineInCode(code, searchText) {
+  if (!code || !searchText) return 1;
+  const lines = code.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes(searchText)) {
+      return i + 1;
+    }
+  }
+  return 1;
+}
+
+function findBestSourceForPath(sources, fieldPath) {
+  if (!fieldPath) return null;
+  const parts = fieldPath.split('.');
+  const lastPart = parts[parts.length - 1];
+  const sectionPart = parts[1] || parts[0];
+
+  for (const s of sources) {
+    const baseName = path.basename(s.rel).toLowerCase();
+    if (baseName.includes(sectionPart.toLowerCase()) || (lastPart && baseName.includes(lastPart.toLowerCase()))) {
+      return s;
+    }
+    if (s.code.includes(lastPart)) {
+      return s;
+    }
+  }
+  return sources[0] || null;
+}
+
+/**
+ * Analyzes why a project conversion was blocked and compiles structured, actionable findings.
+ */
+function analyzeBlockedProject(targetDir = process.cwd(), options = {}) {
+  const projectDir = path.resolve(targetDir);
+  const projectName = path.basename(projectDir);
+  const findings = [];
+
+  // 1. Inspect recent run artifacts in .deneb/runs/ if present
+  let runReasons = [];
+  const runsDir = path.join(projectDir, '.deneb', 'runs');
+  if (fs.existsSync(runsDir)) {
+    try {
+      const runs = fs.readdirSync(runsDir).sort();
+      const latestRun = runs[runs.length - 1];
+      if (latestRun) {
+        const rollbackFile = path.join(runsDir, latestRun, 'reports', 'rollback-reason.json');
+        if (fs.existsSync(rollbackFile)) {
+          const rollbackData = JSON.parse(fs.readFileSync(rollbackFile, 'utf8'));
+          if (Array.isArray(rollbackData.reasons)) {
+            runReasons = rollbackData.reasons;
+          }
+        }
+      }
+    } catch {}
+  }
+
+  // 2. Inspect fivora-template.json
+  const manifestPath = path.join(projectDir, 'fivora-template.json');
+  let manifest = null;
+  let manifestRaw = '';
+
+  if (!fs.existsSync(manifestPath)) {
+    findings.push({
+      ruleId: 'MISSING_MANIFEST',
+      category: 'FIVORA_CONTRACT',
+      severity: 'BLOCKING',
+      file: 'fivora-template.json',
+      line: 1,
+      message: 'fivora-template.json is missing in project root.',
+      remediation: "Run 'npx @deneb-ui/cli init' to generate the mandatory Fivora template manifest.",
+    });
+  } else {
+    try {
+      manifestRaw = fs.readFileSync(manifestPath, 'utf8');
+      manifest = JSON.parse(manifestRaw);
+    } catch (err) {
+      findings.push({
+        ruleId: 'CORRUPT_MANIFEST_JSON',
+        category: 'FIVORA_CONTRACT',
+        severity: 'BLOCKING',
+        file: 'fivora-template.json',
+        line: 1,
+        message: `Corrupted JSON in fivora-template.json: ${err.message}`,
+        remediation: 'Ensure fivora-template.json is valid JSON with proper quotes and commas.',
+      });
+    }
+  }
+
+  // 3. Inspect editorSchema uniqueness & types using authoritative Fivora contract
+  if (manifest && manifest.editorSchema) {
+    const schemaErrors = contract.auditSchemaUniqueness(manifest.editorSchema);
+    for (const sErr of schemaErrors) {
+      if (sErr.includes('declares unsupported type')) {
+        const typeMatch = sErr.match(/unsupported type "([^"]+)"/);
+        const badType = typeMatch ? typeMatch[1] : 'unknown';
+        const line = findLineInCode(manifestRaw, `"${badType}"`);
+        findings.push({
+          ruleId: 'SCHEMA_UNSUPPORTED_TYPE',
+          category: 'FIVORA_CONTRACT',
+          severity: 'BLOCKING',
+          file: 'fivora-template.json',
+          line,
+          snippet: `"type": "${badType}"`,
+          message: sErr,
+          remediation: `Fivora schema requires primitive types (text, textarea, email, tel, url, image, number, boolean, select). Replace type '${badType}' with 'number' or 'text'.`,
+        });
+      } else {
+        const line = findLineInCode(manifestRaw, 'duplicate');
+        findings.push({
+          ruleId: 'SCHEMA_DUPLICATE_SECTION',
+          category: 'FIVORA_CONTRACT',
+          severity: 'BLOCKING',
+          file: 'fivora-template.json',
+          line,
+          message: sErr,
+          remediation: 'Ensure each section and field in editorSchema.sections has a distinct, unique path identifier.',
+        });
+      }
+    }
+  }
+
+  // 4. Inspect siteDataFile & Content
+  const siteDataPath = resolveSiteDataFile(projectDir, manifest || {});
+  let siteData = {};
+  if (siteDataPath && fs.existsSync(siteDataPath)) {
+    try {
+      siteData = JSON.parse(fs.readFileSync(siteDataPath, 'utf8'));
+    } catch {}
+  }
+
+  // 5. Audit source files, markers, and coverage
+  const sources = collectSourceFiles(projectDir);
+  const allMarkers = [];
+
+  for (const s of sources) {
+    const { markers } = contract.extractMarkers(s.code, s.rel);
+    allMarkers.push(...markers);
+
+    // Audit placement errors
+    const placementErrors = contract.auditMarkerPlacement(s.code, s.rel);
+    for (const err of placementErrors) {
+      findings.push({
+        ruleId: 'MARKER_PLACEMENT_INVALID',
+        category: 'FIVORA_CONTRACT',
+        severity: 'BLOCKING',
+        file: s.rel,
+        line: err.line || findLineInCode(s.code, 'data-preview-field-path'),
+        message: err.message || 'data-preview-field-path placed on invalid container node.',
+        remediation: 'Attach data-preview-field-path to native HTML elements (div, h1, p, button) or thread via previewPath prop.',
+      });
+    }
+
+    // Audit action collisions
+    const collisions = contract.auditActionLabelCollision(s.code, s.rel);
+    for (const col of collisions) {
+      findings.push({
+        ruleId: 'COLLISION_ACTION_LABEL',
+        category: 'FIVORA_CONTRACT',
+        severity: 'BLOCKING',
+        file: s.rel,
+        line: col.line || 1,
+        message: col.message || 'Action href and label collide on the same path.',
+        remediation: 'Split the action contract into separate urlField and labelField bindings.',
+      });
+    }
+  }
+
+  // 6. Path Coverage Audit
+  if (manifest && manifest.editorSchema) {
+    const coverage = contract.auditPathCoverage({
+      content: siteData.content || siteData,
+      editorSchema: manifest.editorSchema,
+      markers: allMarkers,
+      controlOnlyPaths: manifest.visualEditing?.controlOnlyPaths || [],
+    });
+
+    for (const err of coverage.errors) {
+      const match = err.match(/"([^"]+)"/);
+      const unmappedPath = match ? match[1] : null;
+      const matchedSource = findBestSourceForPath(sources, unmappedPath);
+      const file = matchedSource ? matchedSource.rel : 'fivora-template.json';
+      const line = matchedSource ? findLineInCode(matchedSource.code, unmappedPath?.split('.').pop()) : 1;
+
+      findings.push({
+        ruleId: 'FIVORA_UNMAPPED_FIELD',
+        category: 'FIVORA_CONTRACT',
+        severity: 'BLOCKING',
+        file,
+        line,
+        message: err,
+        remediation: unmappedPath
+          ? `Add data-preview-field-path="${unmappedPath}" to the JSX element rendering this content in ${file}, or add "${unmappedPath.split('.').slice(0, 2).join('.')}" to visualEditing.controlOnlyPaths in fivora-template.json.`
+          : 'Ensure all site-data paths have visual editing markers or are registered in controlOnlyPaths.',
+      });
+    }
+  }
+
+  // 7. Route / Page on Disk Audit
+  if (manifest && Array.isArray(manifest.pages)) {
+    const pageCoverage = contract.auditPageCoverage(projectDir, manifest.pages);
+    for (const err of pageCoverage.errors || []) {
+      findings.push({
+        ruleId: 'MISSING_PAGE_ROUTE',
+        category: 'FIVORA_CONTRACT',
+        severity: 'BLOCKING',
+        file: 'fivora-template.json',
+        line: 1,
+        message: err,
+        remediation: 'Ensure every page defined in manifest.pages has a corresponding page.tsx on disk (e.g. src/app/<route>/page.tsx).',
+      });
+    }
+  }
+
+  // 8. Runtime & Collection Evaluations
+  const runtimeReport = validateRuntimeEditabilitySync({
+    projectDir,
+    siteData,
+    manifest,
+  });
+
+  const collectionReport = validateCollectionOperations(siteData);
+
+  const acceptance = evaluateAcceptanceGates({
+    sourceAnalysis: { passed: sources.length > 0 },
+    astTransformation: { passed: true },
+    typescriptValidation: { passed: true },
+    buildSuccess: { passed: true },
+    fivoraAudit: { passed: findings.length === 0 },
+    manifestValid: Boolean(manifest?.framework && manifest?.editorSchema),
+    runtimeEditabilityScore: runtimeReport.runtimeEditabilityScore ?? 100,
+    collectionOpsPassed: collectionReport.passed,
+    imageEditingPassed: true,
+    routeCoveragePassed: true,
+    designPreservationScore: 99.0,
+    controlOnlyValid: true,
+    editabilityCoverage: runtimeReport.runtimeEditabilityScore ?? 100,
+  });
+
+  if (!collectionReport.passed) {
+    findings.push({
+      ruleId: 'RUNTIME_COLLECTION_OPS_FAILED',
+      category: 'ACCEPTANCE_GATE',
+      severity: 'BLOCKING',
+      file: 'src/data/site-data.json',
+      line: 1,
+      message: 'Collection mutation operations (add, remove, reorder) failed runtime simulation.',
+      remediation: 'Ensure array items in site-data.json have unique identifiers (id or slug) and consistent object shapes.',
+    });
+  }
+
+  const blocked = findings.length > 0 || !acceptance.passed;
+
+  return {
+    timestamp: new Date().toISOString(),
+    targetDir: projectDir,
+    projectName,
+    blocked,
+    rollbackOccurred: runReasons.length > 0 || blocked,
+    totalBlockingIssues: findings.length,
+    criticalGatesPassed: acceptance.allCriticalPassed,
+    findings,
+    summary: {
+      contractPassed: findings.length === 0,
+      acceptanceStatus: acceptance.status,
+      runtimeEditabilityScore: runtimeReport.runtimeEditabilityScore,
+    },
+  };
+}
+
+/**
+ * Formats structured explanation report into a terminal UI display.
+ */
+function formatBlockedExplanationTerminal(report) {
+  const red = '\x1b[31m';
+  const green = '\x1b[32m';
+  const yellow = '\x1b[33m';
+  const cyan = '\x1b[36m';
+  const bold = '\x1b[1m';
+  const dim = '\x1b[90m';
+  const reset = '\x1b[0m';
+
+  const lines = [];
+
+  lines.push('');
+  lines.push(`${red}${bold}╔═══════════════════════════════════════════════════════════════════════════════╗${reset}`);
+  lines.push(`${red}${bold}║  ✖ DENEB CONVERSION BLOCKED — WHY IT FAILED & EXACT REMEDIATION STEPS         ║${reset}`);
+  lines.push(`${red}${bold}╚═══════════════════════════════════════════════════════════════════════════════╝${reset}`);
+  lines.push('');
+
+  lines.push(`  ${bold}Project:${reset}       ${report.projectName}`);
+  lines.push(`  ${bold}Directory:${reset}     ${dim}${report.targetDir}${reset}`);
+  lines.push(`  ${bold}Files Intact:${reset}  ${green}YES — Atomic rollback preserved all original files${reset}`);
+  lines.push(`  ${bold}Status:${reset}        ${report.blocked ? `${red}${bold}${report.summary.acceptanceStatus}${reset}` : `${green}${bold}CONVERSION_PASSED${reset}`}`);
+  lines.push(`  ${bold}Blocking Issues:${reset} ${report.totalBlockingIssues > 0 ? `${red}${bold}${report.totalBlockingIssues}${reset}` : `${green}${bold}0${reset}`}`);
+  lines.push('');
+
+  if (report.findings.length === 0) {
+    lines.push(`  ${green}✔ No blocking issues detected. The project satisfies all Fivora contracts!${reset}`);
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  lines.push(`${bold}─────────────────────────────────────────────────────────────────────────────────${reset}`);
+  lines.push(`${bold}DETAILED BLOCKING ISSUES & REMEDIATION:${reset}`);
+  lines.push(`${bold}─────────────────────────────────────────────────────────────────────────────────${reset}`);
+  lines.push('');
+
+  report.findings.forEach((finding, idx) => {
+    const loc = finding.line ? `:${finding.line}` : '';
+    lines.push(`  ${red}${bold}[${idx + 1}] ${finding.ruleId}${reset} ${dim}(${finding.category})${reset}`);
+    lines.push(`      ${bold}Location:${reset}     ${cyan}${finding.file}${loc}${reset}`);
+    if (finding.snippet) {
+      lines.push(`      ${bold}Snippet:${reset}      ${yellow}${finding.snippet}${reset}`);
+    }
+    lines.push(`      ${bold}Problem:${reset}      ${finding.message}`);
+    lines.push(`      ${green}${bold}Fix:${reset}          ${finding.remediation}`);
+    lines.push('');
+  });
+
+  lines.push(`${bold}─────────────────────────────────────────────────────────────────────────────────${reset}`);
+  lines.push(`  ${cyan}${bold}Next Step:${reset} Apply the fixes described above, then rerun:`);
+  lines.push(`            ${bold}npx @deneb-ui/cli init${reset}`);
+  lines.push(`${bold}─────────────────────────────────────────────────────────────────────────────────${reset}`);
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Prints explanation report to console in terminal or JSON format.
+ */
+function printBlockedExplanation(report, options = {}) {
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(formatBlockedExplanationTerminal(report));
+  }
+}
+
+module.exports = {
+  analyzeBlockedProject,
+  formatBlockedExplanationTerminal,
+  printBlockedExplanation,
+};