@design-ai/cli 4.55.0 → 4.56.0

package/cli/lib/site-analysis.mjs

@@ -0,0 +1,297 @@
+// Website Improvement workspace validation and summary helpers.
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+import { normalizeStringArray } from "./site-strings.mjs";
+import {
+  AUDIT_CATEGORIES,
+  CHECKLIST_STATUS_OPTIONS,
+  CMS_OPTIONS,
+  DATABASE_OPTIONS,
+  DEPLOY_OPTIONS,
+  EFFORT_OPTIONS,
+  IMPACT_OPTIONS,
+  MCP_ITEMS,
+  MCP_STATUS_OPTIONS,
+  PRIORITY_OPTIONS,
+  VIEWPORT_OPTIONS,
+} from "./site-options.mjs";
+import {
+  IMPLEMENTATION_EVIDENCE_KEYS,
+  normalizeImplementationEvidence,
+} from "./site-evidence.mjs";
+import {
+  normalizeObject,
+  normalizeSiteWorkspace,
+} from "./site-workspace.mjs";
+
+export function addIssue(issues, level, id, message) {
+  issues.push({ level, id, message });
+}
+
+function assertEnumIssue(issues, value, allowed, id, label) {
+  if (!allowed.includes(value)) {
+    addIssue(issues, "fail", id, `${label} must be one of: ${allowed.join(", ")}`);
+  }
+}
+
+function validateRawWorkspace(raw) {
+  const issues = [];
+  const root = normalizeObject(raw);
+  const profile = normalizeObject(root.siteProfile);
+  const checklist = normalizeObject(root.auditChecklist);
+  const mcpReadiness = normalizeObject(root.mcpReadiness);
+
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    addIssue(issues, "fail", "workspace-object", "Workspace JSON must be an object");
+    return issues;
+  }
+  if (root.version !== 1) {
+    addIssue(issues, "fail", "workspace-version", "Workspace version must be 1");
+  }
+  if (!root.siteProfile || typeof root.siteProfile !== "object" || Array.isArray(root.siteProfile)) {
+    addIssue(issues, "fail", "site-profile", "siteProfile object is required");
+  }
+  if (!root.auditChecklist || typeof root.auditChecklist !== "object" || Array.isArray(root.auditChecklist)) {
+    addIssue(issues, "fail", "audit-checklist", "auditChecklist object is required");
+  }
+  if (!root.mcpReadiness || typeof root.mcpReadiness !== "object" || Array.isArray(root.mcpReadiness)) {
+    addIssue(issues, "fail", "mcp-readiness", "mcpReadiness object is required");
+  }
+  if (!Array.isArray(root.refactorTasks)) {
+    addIssue(issues, "fail", "refactor-tasks", "refactorTasks array is required");
+  }
+  if (root.implementationEvidence !== undefined) {
+    const evidence = normalizeObject(root.implementationEvidence);
+    if (root.implementationEvidence === null || typeof root.implementationEvidence !== "object" || Array.isArray(root.implementationEvidence)) {
+      addIssue(issues, "fail", "implementation-evidence", "implementationEvidence must be an object when provided");
+    } else {
+      for (const key of IMPLEMENTATION_EVIDENCE_KEYS) {
+        if (evidence[key] !== undefined && !Array.isArray(evidence[key])) {
+          addIssue(issues, "fail", `implementation-evidence-${key}`, `implementationEvidence.${key} must be an array`);
+        }
+      }
+    }
+  }
+
+  if (!String(profile.name || "").trim()) {
+    addIssue(issues, "fail", "site-name", "siteProfile.name is required");
+  }
+  if (!String(profile.liveUrl || "").trim()) {
+    addIssue(issues, "fail", "site-live-url", "siteProfile.liveUrl is required");
+  }
+  if (!Array.isArray(profile.pages) || normalizeStringArray(profile.pages).length === 0) {
+    addIssue(issues, "warn", "site-pages", "siteProfile.pages should include at least one priority page");
+  }
+  if (!Array.isArray(profile.userFlows) || normalizeStringArray(profile.userFlows).length === 0) {
+    addIssue(issues, "warn", "site-user-flows", "siteProfile.userFlows should include at least one primary user flow");
+  }
+  if (!Array.isArray(profile.viewports) || normalizeStringArray(profile.viewports).length === 0) {
+    addIssue(issues, "warn", "site-viewports", "siteProfile.viewports should include desktop, tablet, or mobile");
+  } else {
+    for (const viewport of normalizeStringArray(profile.viewports)) {
+      assertEnumIssue(issues, viewport, VIEWPORT_OPTIONS, "site-viewport-value", `Viewport '${viewport}'`);
+    }
+  }
+  if (!String(profile.repoUrl || "").trim() && !String(profile.localPath || "").trim()) {
+    addIssue(issues, "warn", "site-repo-location", "Provide siteProfile.repoUrl or siteProfile.localPath before Codex implementation handoff");
+  }
+  if (profile.deployProvider !== undefined) {
+    assertEnumIssue(issues, profile.deployProvider, DEPLOY_OPTIONS, "deploy-provider", "siteProfile.deployProvider");
+  }
+  if (profile.cms !== undefined) {
+    assertEnumIssue(issues, profile.cms, CMS_OPTIONS, "cms", "siteProfile.cms");
+  }
+  if (profile.database !== undefined) {
+    assertEnumIssue(issues, profile.database, DATABASE_OPTIONS, "database", "siteProfile.database");
+  }
+
+  for (const category of AUDIT_CATEGORIES) {
+    const row = normalizeObject(checklist[category.id]);
+    if (!checklist[category.id]) {
+      addIssue(issues, "warn", `audit-${category.id}`, `${category.label} audit row is missing`);
+      continue;
+    }
+    assertEnumIssue(issues, row.status, CHECKLIST_STATUS_OPTIONS, `audit-${category.id}-status`, `${category.label} status`);
+    if (row.findings !== undefined && !Array.isArray(row.findings)) {
+      addIssue(issues, "fail", `audit-${category.id}-findings`, `${category.label} findings must be an array`);
+    }
+  }
+
+  for (const [key, label] of MCP_ITEMS) {
+    if (mcpReadiness[key] === undefined) {
+      addIssue(issues, "warn", `mcp-${key}`, `${label} MCP readiness status is missing`);
+      continue;
+    }
+    assertEnumIssue(issues, mcpReadiness[key], MCP_STATUS_OPTIONS, `mcp-${key}-status`, `${label} MCP status`);
+  }
+
+  if (Array.isArray(root.refactorTasks)) {
+    for (const [index, task] of root.refactorTasks.entries()) {
+      const item = normalizeObject(task);
+      const label = item.title ? `Task '${item.title}'` : `Task ${index + 1}`;
+      if (!String(item.title || "").trim()) {
+        addIssue(issues, "warn", `task-${index + 1}-title`, `${label} should include a title`);
+      }
+      if (!String(item.problem || "").trim()) {
+        addIssue(issues, "warn", `task-${index + 1}-problem`, `${label} should describe the problem`);
+      }
+      assertEnumIssue(
+        issues,
+        item.category,
+        AUDIT_CATEGORIES.map((category) => category.id),
+        `task-${index + 1}-category`,
+        `${label} category`,
+      );
+      assertEnumIssue(issues, item.impact, IMPACT_OPTIONS, `task-${index + 1}-impact`, `${label} impact`);
+      assertEnumIssue(issues, item.effort, EFFORT_OPTIONS, `task-${index + 1}-effort`, `${label} effort`);
+      assertEnumIssue(issues, item.priority, PRIORITY_OPTIONS, `task-${index + 1}-priority`, `${label} priority`);
+      if (!String(item.codexPrompt || "").trim()) {
+        addIssue(issues, "warn", `task-${index + 1}-codex-prompt`, `${label} should include a Codex implementation prompt`);
+      }
+      if (!Array.isArray(item.verification) || normalizeStringArray(item.verification).length === 0) {
+        addIssue(issues, "warn", `task-${index + 1}-verification`, `${label} should include verification steps`);
+      }
+    }
+  }
+
+  return issues;
+}
+
+function countBy(items, keyFn, allowed = []) {
+  const counts = Object.fromEntries(allowed.map((item) => [item, 0]));
+  for (const item of items) {
+    const key = keyFn(item);
+    counts[key] = (counts[key] || 0) + 1;
+  }
+  return counts;
+}
+
+export function statusFromIssues(issues) {
+  if (issues.some((issue) => issue.level === "fail")) return "fail";
+  if (issues.some((issue) => issue.level === "warn")) return "warn";
+  return "pass";
+}
+
+function summarizeWorkspace(workspace, issues, filePath) {
+  const auditRows = AUDIT_CATEGORIES.map((category) => ({
+    category,
+    row: workspace.auditChecklist[category.id],
+  }));
+  const mcpRows = MCP_ITEMS.map(([key, label]) => ({
+    key,
+    label,
+    status: workspace.mcpReadiness[key],
+  }));
+  const totalFindings = auditRows.reduce((sum, item) => sum + item.row.findings.length, 0);
+  const requiredMcp = mcpRows.filter((item) => item.status === "required").map((item) => item.key);
+  const evidence = normalizeImplementationEvidence(workspace.implementationEvidence);
+  const topTasks = workspace.refactorTasks
+    .slice()
+    .sort((a, b) => PRIORITY_OPTIONS.indexOf(a.priority) - PRIORITY_OPTIONS.indexOf(b.priority))
+    .slice(0, 5)
+    .map((task) => ({
+      id: task.id,
+      title: task.title,
+      priority: task.priority,
+      category: task.category,
+      impact: task.impact,
+      effort: task.effort,
+      pages: task.pages,
+    }));
+
+  return {
+    filePath,
+    valid: statusFromIssues(issues) !== "fail",
+    status: statusFromIssues(issues),
+    site: {
+      id: workspace.siteProfile.id,
+      name: workspace.siteProfile.name,
+      liveUrl: workspace.siteProfile.liveUrl,
+      repoUrl: workspace.siteProfile.repoUrl,
+      localPath: workspace.siteProfile.localPath,
+      deployProvider: workspace.siteProfile.deployProvider,
+      cms: workspace.siteProfile.cms,
+      database: workspace.siteProfile.database,
+      pages: workspace.siteProfile.pages,
+      userFlows: workspace.siteProfile.userFlows,
+      viewports: workspace.siteProfile.viewports,
+    },
+    counts: {
+      pages: workspace.siteProfile.pages.length,
+      userFlows: workspace.siteProfile.userFlows.length,
+      viewports: workspace.siteProfile.viewports.length,
+      auditCategories: AUDIT_CATEGORIES.length,
+      auditFindings: totalFindings,
+      refactorTasks: workspace.refactorTasks.length,
+      executedWork: evidence.executedWork.length,
+      verificationResults: evidence.verificationResults.length,
+      remainingRisks: evidence.remainingRisks.length,
+      nextActions: evidence.nextActions.length,
+      requiredMcp: requiredMcp.length,
+      optionalMcp: mcpRows.filter((item) => item.status === "optional").length,
+      unavailableMcp: mcpRows.filter((item) => item.status === "unavailable").length,
+    },
+    auditStatusCounts: countBy(auditRows, (item) => item.row.status, CHECKLIST_STATUS_OPTIONS),
+    mcpStatusCounts: countBy(mcpRows, (item) => item.status, MCP_STATUS_OPTIONS),
+    taskPriorityCounts: countBy(workspace.refactorTasks, (task) => task.priority, PRIORITY_OPTIONS),
+    requiredMcp,
+    topTasks,
+    issues,
+  };
+}
+
+export function analyzeSiteWorkspace(raw, { filePath = "workspace.json" } = {}) {
+  const issues = validateRawWorkspace(raw);
+  const workspace = normalizeSiteWorkspace(raw);
+  const summary = summarizeWorkspace(workspace, issues, filePath);
+
+  if (summary.status === "pass") {
+    addIssue(summary.issues, "pass", "workspace-ready", "Workspace is ready for report and prompt generation");
+  }
+
+  return {
+    workspace,
+    summary: {
+      ...summary,
+      status: statusFromIssues(summary.issues),
+      valid: statusFromIssues(summary.issues) !== "fail",
+    },
+  };
+}
+
+export function loadSiteWorkspaceInput({
+  target = "",
+  stdin = false,
+  cwd = process.cwd(),
+  readStdin = () => readFileSync(0, "utf8"),
+} = {}) {
+  const filePath = stdin ? "stdin" : path.resolve(cwd, target);
+  const rawText = stdin ? String(readStdin()) : readFileSync(filePath, "utf8");
+  let parsed;
+  try {
+    parsed = JSON.parse(rawText);
+  } catch (error) {
+    throw new Error(`Invalid Website Improvement workspace JSON in ${filePath}: ${error.message}`);
+  }
+  return {
+    filePath,
+    rawText,
+    raw: parsed,
+  };
+}
+
+export function buildSiteReport({
+  target = "",
+  stdin = false,
+  cwd = process.cwd(),
+  readStdin,
+} = {}) {
+  const input = loadSiteWorkspaceInput({ target, stdin, cwd, readStdin });
+  return analyzeSiteWorkspace(input.raw, { filePath: input.filePath });
+}
+
+export function formatSiteJson(report) {
+  return JSON.stringify(report, null, 2);
+}