@xenonbyte/da-vinci-workflow 0.1.13 → 0.1.15

package/lib/audit.js

@@ -0,0 +1,348 @@
+const fs = require("fs");
+const path = require("path");
+
+const IMAGE_EXPORT_PATTERN = /\.(png|jpe?g|webp|pdf)$/i;
+
+function pathExists(targetPath) {
+  return fs.existsSync(targetPath);
+}
+
+function readTextIfExists(targetPath) {
+  if (!pathExists(targetPath)) {
+    return "";
+  }
+  return fs.readFileSync(targetPath, "utf8");
+}
+
+function listFilesRecursive(rootDir) {
+  if (!pathExists(rootDir)) {
+    return [];
+  }
+
+  return fs.readdirSync(rootDir, { withFileTypes: true }).flatMap((entry) => {
+    const fullPath = path.join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      return listFilesRecursive(fullPath);
+    }
+    return [fullPath];
+  });
+}
+
+function listChildDirs(rootDir) {
+  if (!pathExists(rootDir)) {
+    return [];
+  }
+
+  return fs
+    .readdirSync(rootDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(rootDir, entry.name));
+}
+
+function relativeTo(projectRoot, targetPath) {
+  return path.relative(projectRoot, targetPath) || ".";
+}
+
+function collectRegisteredPenPaths(projectRoot, designRegistryPath) {
+  const registryText = readTextIfExists(designRegistryPath);
+  const matches = registryText.match(/\.da-vinci\/designs\/[^\s`]+\.pen/g) || [];
+  return [...new Set(matches)].map((relativePath) => path.join(projectRoot, relativePath));
+}
+
+function getNonEmptyChangeDirs(changesDir) {
+  return listChildDirs(changesDir).filter((changeDir) => listFilesRecursive(changeDir).length > 0);
+}
+
+function getExpectedChangeArtifacts(changeDir) {
+  return [
+    path.join(changeDir, "design-brief.md"),
+    path.join(changeDir, "design.md"),
+    path.join(changeDir, "pencil-design.md"),
+    path.join(changeDir, "pencil-bindings.md")
+  ];
+}
+
+function isAllowedExportPath(projectRoot, targetPath) {
+  const relativePath = relativeTo(projectRoot, targetPath);
+  return /^\.da-vinci\/changes\/[^/]+\/exports\//.test(relativePath);
+}
+
+function resolveScopedChangeDirs(projectRoot, changesDir, options, failures, warnings, notes) {
+  const requestedChangeId = options.changeId;
+  const requestedChangeDir = requestedChangeId ? path.join(changesDir, requestedChangeId) : null;
+
+  if (requestedChangeDir) {
+    if (!pathExists(requestedChangeDir)) {
+      failures.push(
+        `Requested change scope does not exist: ${relativeTo(projectRoot, requestedChangeDir)}`
+      );
+      return [];
+    }
+
+    return [requestedChangeDir];
+  }
+
+  const nonEmptyChangeDirs = getNonEmptyChangeDirs(changesDir);
+  if (nonEmptyChangeDirs.length === 1) {
+    notes.push(
+      `Inferred completion change scope: ${relativeTo(projectRoot, nonEmptyChangeDirs[0])}`
+    );
+    return nonEmptyChangeDirs;
+  }
+
+  if (nonEmptyChangeDirs.length === 0) {
+    failures.push(
+      "Completion audit requires a non-empty `.da-vinci/changes/<change-id>/` directory."
+    );
+    return [];
+  }
+
+  warnings.push(
+    "Multiple non-empty change directories exist. Pass `--change <change-id>` to run a strict completion audit."
+  );
+  failures.push("Completion audit scope is ambiguous without `--change <change-id>`.");
+  return [];
+}
+
+function addMissingArtifacts(projectRoot, artifactPaths, targetList) {
+  for (const artifactPath of artifactPaths) {
+    if (!pathExists(artifactPath)) {
+      targetList.push(`Missing required artifact: ${relativeTo(projectRoot, artifactPath)}`);
+    }
+  }
+}
+
+function auditProject(projectPathInput, options = {}) {
+  const projectRoot = path.resolve(projectPathInput || process.cwd());
+  const mode = options.mode || "integrity";
+  const daVinciDir = path.join(projectRoot, ".da-vinci");
+  const designsDir = path.join(daVinciDir, "designs");
+  const changesDir = path.join(daVinciDir, "changes");
+  const designRegistryPath = path.join(daVinciDir, "design-registry.md");
+
+  const failures = [];
+  const warnings = [];
+  const notes = [];
+
+  if (!["integrity", "completion"].includes(mode)) {
+    failures.push(`Unsupported audit mode: ${mode}`);
+    return {
+      projectRoot,
+      mode,
+      changeId: options.changeId || null,
+      status: "FAIL",
+      failures,
+      warnings,
+      notes
+    };
+  }
+
+  if (!pathExists(projectRoot)) {
+    failures.push(`Project path does not exist: ${projectRoot}`);
+    return {
+      projectRoot,
+      mode,
+      changeId: options.changeId || null,
+      status: "FAIL",
+      failures,
+      warnings,
+      notes
+    };
+  }
+
+  if (!pathExists(daVinciDir)) {
+    failures.push("Missing `.da-vinci/` directory.");
+    return {
+      projectRoot,
+      mode,
+      changeId: options.changeId || null,
+      status: "FAIL",
+      failures,
+      warnings,
+      notes
+    };
+  }
+
+  const integrityRequiredArtifacts = [path.join(projectRoot, "DA-VINCI.md"), designsDir];
+  addMissingArtifacts(projectRoot, integrityRequiredArtifacts, failures);
+
+  const completionRequiredArtifacts = [
+    path.join(projectRoot, "DA-VINCI.md"),
+    path.join(daVinciDir, "project-inventory.md"),
+    path.join(daVinciDir, "page-map.md"),
+    designRegistryPath,
+    designsDir
+  ];
+
+  if (mode === "completion") {
+    addMissingArtifacts(projectRoot, completionRequiredArtifacts, failures);
+  } else {
+    addMissingArtifacts(projectRoot, completionRequiredArtifacts.slice(1, 4), warnings);
+  }
+
+  const daVinciFiles = listFilesRecursive(daVinciDir);
+  const misplacedExports = daVinciFiles.filter(
+    (filePath) => IMAGE_EXPORT_PATTERN.test(filePath) && !isAllowedExportPath(projectRoot, filePath)
+  );
+
+  if (misplacedExports.length > 0) {
+    failures.push(
+      [
+        "Review exports were written outside `.da-vinci/changes/<change-id>/exports/`:",
+        ...misplacedExports.map((filePath) => `  - ${relativeTo(projectRoot, filePath)}`)
+      ].join("\n")
+    );
+  }
+
+  const designFiles = listFilesRecursive(designsDir);
+  const penFiles = designFiles.filter((filePath) => filePath.endsWith(".pen"));
+  const pollutedDesignFiles = designFiles.filter((filePath) => !filePath.endsWith(".pen"));
+
+  if (pollutedDesignFiles.length > 0) {
+    failures.push(
+      [
+        "`.da-vinci/designs/` contains non-`.pen` files:",
+        ...pollutedDesignFiles.map((filePath) => `  - ${relativeTo(projectRoot, filePath)}`)
+      ].join("\n")
+    );
+  }
+
+  if (penFiles.length === 0) {
+    const message = "No shell-visible project-local `.pen` file exists under `.da-vinci/designs/`.";
+    if (mode === "completion") {
+      failures.push(message);
+    } else {
+      warnings.push(message);
+    }
+  } else {
+    notes.push(
+      `Detected project-local .pen source(s): ${penFiles
+        .map((filePath) => relativeTo(projectRoot, filePath))
+        .join(", ")}`
+    );
+  }
+
+  const registeredPenPaths = collectRegisteredPenPaths(projectRoot, designRegistryPath);
+  for (const registeredPenPath of registeredPenPaths) {
+    if (!pathExists(registeredPenPath)) {
+      failures.push(
+        `Registered design source is missing on disk: ${relativeTo(projectRoot, registeredPenPath)}`
+      );
+    }
+  }
+
+  const changeDirs = listChildDirs(changesDir);
+  if (changeDirs.length === 0) {
+    warnings.push("No `.da-vinci/changes/<change-id>/` directory was found.");
+  }
+
+  const scopedChangeDirs =
+    mode === "completion"
+      ? resolveScopedChangeDirs(projectRoot, changesDir, options, failures, warnings, notes)
+      : changeDirs;
+
+  for (const changeDir of changeDirs) {
+    const changeFiles = listFilesRecursive(changeDir);
+    const changeRel = relativeTo(projectRoot, changeDir);
+
+    if (changeFiles.length === 0) {
+      if (mode === "completion" && scopedChangeDirs.includes(changeDir)) {
+        failures.push(`Completion scope is empty: ${changeRel}`);
+      }
+      warnings.push(`Empty change scaffold: ${changeRel}`);
+      continue;
+    }
+
+    const exportsDir = path.join(changeDir, "exports");
+    const exportsFiles = listFilesRecursive(exportsDir);
+    if (exportsFiles.length > 0) {
+      notes.push(`Detected review exports under ${relativeTo(projectRoot, exportsDir)}.`);
+    }
+
+    const expectedChangeArtifacts = getExpectedChangeArtifacts(changeDir);
+    const missingArtifacts = expectedChangeArtifacts.filter((artifactPath) => !pathExists(artifactPath));
+
+    if (mode === "completion" && scopedChangeDirs.includes(changeDir) && missingArtifacts.length > 0) {
+      failures.push(
+        [
+          `Completion scope is missing required change artifacts in ${changeRel}:`,
+          ...missingArtifacts.map((artifactPath) => `  - ${relativeTo(projectRoot, artifactPath)}`)
+        ].join("\n")
+      );
+    } else if (missingArtifacts.length > 0 && missingArtifacts.length < expectedChangeArtifacts.length) {
+      warnings.push(
+        [
+          `Partial change artifact set in ${changeRel}:`,
+          ...missingArtifacts.map((artifactPath) => `  - missing ${relativeTo(projectRoot, artifactPath)}`)
+        ].join("\n")
+      );
+    }
+
+    if (exportsFiles.length > 0 && !pathExists(path.join(changeDir, "pencil-design.md"))) {
+      failures.push(
+        `Exported screenshots exist in ${changeRel} but no pencil-design.md records the design pass.`
+      );
+    }
+
+    const specDirs = listChildDirs(path.join(changeDir, "specs"));
+    for (const specDir of specDirs) {
+      const specFile = path.join(specDir, "spec.md");
+      if (!pathExists(specFile)) {
+        warnings.push(`Spec scaffold exists without spec.md: ${relativeTo(projectRoot, specDir)}`);
+      }
+    }
+  }
+
+  const status = failures.length > 0 ? "FAIL" : warnings.length > 0 ? "WARN" : "PASS";
+
+  return {
+    projectRoot,
+    mode,
+    changeId: options.changeId || null,
+    status,
+    failures,
+    warnings,
+    notes
+  };
+}
+
+function formatAuditReport(result) {
+  const lines = [
+    "Da Vinci audit",
+    `Project: ${result.projectRoot}`,
+    `Mode: ${result.mode}`,
+    `Status: ${result.status}`
+  ];
+
+  if (result.changeId) {
+    lines.splice(3, 0, `Change: ${result.changeId}`);
+  }
+
+  if (result.failures.length > 0) {
+    lines.push("", "Failures:");
+    for (const failure of result.failures) {
+      lines.push(`- ${failure}`);
+    }
+  }
+
+  if (result.warnings.length > 0) {
+    lines.push("", "Warnings:");
+    for (const warning of result.warnings) {
+      lines.push(`- ${warning}`);
+    }
+  }
+
+  if (result.notes.length > 0) {
+    lines.push("", "Notes:");
+    for (const note of result.notes) {
+      lines.push(`- ${note}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+module.exports = {
+  auditProject,
+  formatAuditReport
+};

package/lib/cli.js

@@ -5,6 +5,7 @@ const {
   getStatus,
   validateAssets
 } = require("./install");
+const { auditProject, formatAuditReport } = require("./audit");
 
 function getOption(args, name) {
   const direct = args.find((arg) => arg.startsWith(`${name}=`));
@@ -20,6 +21,31 @@ function getOption(args, name) {
   return undefined;
 }
 
+function getPositionalArgs(args, optionsWithValues = []) {
+  const positional = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (optionsWithValues.includes(arg)) {
+      index += 1;
+      continue;
+    }
+
+    if (optionsWithValues.some((name) => arg.startsWith(`${name}=`))) {
+      continue;
+    }
+
+    if (arg.startsWith("-")) {
+      continue;
+    }
+
+    positional.push(arg);
+  }
+
+  return positional;
+}
+
 function formatStatus(status) {
   return [
     `Da Vinci v${status.version}`,
@@ -40,11 +66,15 @@ function printHelp() {
       "  da-vinci uninstall --platform codex,claude,gemini",
       "  da-vinci status",
       "  da-vinci validate-assets",
+      "  da-vinci audit [project-path]",
       "  da-vinci --version",
       "",
       "Options:",
       "  --platform <value>   codex, claude, gemini, or all",
-      "  --home <path>        override HOME for installation targets"
+      "  --home <path>        override HOME for installation targets",
+      "  --project <path>     override project path for audit",
+      "  --mode <value>       integrity or completion",
+      "  --change <id>        scope completion audit to one change id"
     ].join("\n")
   );
 }
@@ -52,6 +82,7 @@ function printHelp() {
 async function runCli(argv) {
   const [command] = argv;
   const homeDir = getOption(argv, "--home");
+  const positionalArgs = getPositionalArgs(argv.slice(1), ["--home", "--platform", "--project", "--mode", "--change"]);
 
   if (!command || command === "help" || command === "--help" || command === "-h") {
     printHelp();
@@ -92,6 +123,21 @@ async function runCli(argv) {
     return;
   }
 
+  if (command === "audit") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const mode = getOption(argv, "--mode");
+    const changeId = getOption(argv, "--change");
+    const result = auditProject(projectPath, { mode, changeId });
+    const report = formatAuditReport(result);
+
+    if (result.status === "FAIL") {
+      throw new Error(report);
+    }
+
+    console.log(report);
+    return;
+  }
+
   throw new Error(`Unknown command: ${command}`);
 }