artifact-chain-assistant 0.8.0

package/adapters/codex/scripts/batch-split.mjs

@@ -0,0 +1,184 @@
+// @feature ACA16 @scenario S-49
+// Deterministic batch splitting for artifact review workflows.
+
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+
+/**
+ * Recursively collect all .md files under a directory.
+ */
+async function collectMarkdownFiles(dir, base) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      // Skip hidden directories and node_modules
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      files.push(...await collectMarkdownFiles(fullPath, base));
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      const relativePath = relative(base, fullPath);
+      const content = await readFile(fullPath, 'utf8');
+      files.push({
+        path: relativePath,
+        chars: content.length,
+        content,
+        // For grouping: detect part-*.md files that belong to a batch-*.md
+        groupKey: extractGroupKey(entry.name, relativePath),
+      });
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Extract a group key for related-file co-location.
+ * Files like batch-001-part-1.md, batch-001-part-2.md share the key "batch-001".
+ * Standalone files get a unique key based on their path.
+ */
+function extractGroupKey(fileName, relativePath) {
+  // Match batch-*.md pattern for grouping parts
+  const batchMatch = fileName.match(/^(batch-[^/]+?)(?:-part-\d+)?\.md$/);
+  if (batchMatch) {
+    return `batch:${batchMatch[1]}`;
+  }
+  // Each standalone file is its own group
+  return `file:${relativePath}`;
+}
+
+/**
+ * Sort files deterministically by path.
+ */
+function sortFiles(files) {
+  return files.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/**
+ * Build batches from sorted files.
+ *
+ * Strategy:
+ * 1. Group files by groupKey to keep related files together.
+ * 2. For each group, if adding the group to the current batch exceeds batch-size,
+ *    and the current batch is non-empty, flush it and start a new one.
+ * 3. If a single group exceeds batch-size, it gets its own batch.
+ * 4. Sort groups by their first file's path for determinism.
+ */
+function buildBatches(files, batchSize) {
+  // Group files by groupKey
+  const groups = new Map();
+  for (const file of files) {
+    if (!groups.has(file.groupKey)) {
+      groups.set(file.groupKey, []);
+    }
+    groups.get(file.groupKey).push(file);
+  }
+
+  // Sort groups by their first file's path for determinism
+  const sortedGroups = [...groups.entries()].sort(([, a], [, b]) =>
+    a[0].path.localeCompare(b[0].path)
+  );
+
+  const batches = [];
+  let currentBatchFiles = [];
+  let currentBatchChars = 0;
+
+  for (const [, groupFiles] of sortedGroups) {
+    const groupChars = groupFiles.reduce((sum, f) => sum + f.chars, 0);
+
+    // If the group alone exceeds batch-size, it gets its own batch
+    if (groupChars >= batchSize) {
+      // Flush current batch if non-empty
+      if (currentBatchFiles.length > 0) {
+        batches.push(currentBatchFiles);
+        currentBatchFiles = [];
+        currentBatchChars = 0;
+      }
+      // This group is its own batch
+      batches.push(groupFiles);
+      continue;
+    }
+
+    // If adding this group would exceed batch-size, flush current batch
+    if (currentBatchChars + groupChars > batchSize && currentBatchFiles.length > 0) {
+      batches.push(currentBatchFiles);
+      currentBatchFiles = [];
+      currentBatchChars = 0;
+    }
+
+    // Add group to current batch
+    currentBatchFiles.push(...groupFiles);
+    currentBatchChars += groupChars;
+  }
+
+  // Flush remaining files
+  if (currentBatchFiles.length > 0) {
+    batches.push(currentBatchFiles);
+  }
+
+  return batches;
+}
+
+/**
+ * Deterministic batch splitting.
+ *
+ * @param {string} targetDir - Directory to scan for .md files
+ * @param {object} options
+ * @param {number} [options.batchSize=40000] - Maximum characters per batch
+ * @returns {Promise<Array<{id: string, files: string[], chars: number}>>}
+ */
+export async function batchSplit(targetDir, options = {}) {
+  const { batchSize = 40000 } = options;
+  const base = resolve(targetDir);
+
+  // Verify target directory exists
+  const targetStat = await stat(base).catch(() => null);
+  if (!targetStat || !targetStat.isDirectory()) {
+    return [];
+  }
+
+  // Collect and sort files
+  const rawFiles = await collectMarkdownFiles(base, base);
+  const files = sortFiles(rawFiles);
+
+  // Build batches
+  const batchArrays = buildBatches(files, batchSize);
+
+  // Format output
+  return batchArrays.map((batchFiles, index) => ({
+    id: `batch-${String(index + 1).padStart(3, '0')}`,
+    files: batchFiles.map(f => f.path),
+    chars: batchFiles.reduce((sum, f) => sum + f.chars, 0),
+  }));
+}
+
+// CLI entry point
+const isMain = import.meta.url === `file://${process.argv[1]}`;
+if (isMain) {
+  const args = process.argv.slice(2);
+  const targetDir = args[0];
+
+  if (!targetDir) {
+    console.error('Usage: node batch-split.mjs <target-dir> [--batch-size N]');
+    process.exit(1);
+  }
+
+  let batchSize = 40000;
+  const sizeIdx = args.indexOf('--batch-size');
+  if (sizeIdx !== -1 && args[sizeIdx + 1]) {
+    batchSize = parseInt(args[sizeIdx + 1], 10);
+    if (isNaN(batchSize) || batchSize <= 0) {
+      console.error('Error: --batch-size must be a positive integer');
+      process.exit(1);
+    }
+  }
+
+  try {
+    const batches = await batchSplit(targetDir, { batchSize });
+    console.log(JSON.stringify(batches, null, 2));
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+}

package/adapters/codex/scripts/check-workflow-profile.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// @feature ACA17
+// @scenario S-51
+// @scenario S-53
+// @scenario S-54
+// @decision D-ACA-17
+// Thin CLI wrapper. scripts/lib/workflow-profile.mjs is the single resolver.
+import { resolve } from 'node:path';
+import { buildCheckerOutput } from './lib/workflow-profile.mjs';
+
+export async function checkWorkflowProfile({ root = process.cwd(), action = 'review', domain, profilePath, target } = {}) {
+  const projectRoot = resolve(root);
+  const checker = await buildCheckerOutput({ root: projectRoot, profilePath, intent: action, domain, target });
+  return {
+    ...checker,
+    root: projectRoot,
+    action,
+    domain,
+    profile: checker.profile_path,
+    worker: checker.worker_path ? checker.worker_path.split('/').slice(-2, -1)[0] : null,
+    dry_run: true,
+  };
+}
+
+const isMain = import.meta.url === `file://${process.argv[1]}`;
+if (isMain) {
+  const args = process.argv.slice(2);
+  const value = flag => {
+    const index = args.indexOf(flag);
+    return index >= 0 ? args[index + 1] : undefined;
+  };
+  if (args.includes('--help')) {
+    console.log('Usage: node check-workflow-profile.mjs --root <path> --action <generate|review|repair|audit|batch> --domain <type> [--profile <json|yaml>] [--target <path>] [--format json|text]');
+    process.exit(0);
+  }
+  let result;
+  try {
+    result = await checkWorkflowProfile({
+      root: value('--root') ?? process.cwd(),
+      action: value('--action') ?? 'review',
+      domain: value('--domain'),
+      profilePath: value('--profile'),
+      target: value('--target'),
+    });
+  } catch (error) {
+    result = {
+      status: 'BLOCKED', schema: null, profile_path: null, execution_mode: null,
+      worker_path: null, checklist_paths: [], validators: [], template_paths: [],
+      diagnostics: [`Checker failed closed: ${error.message}`],
+      next: 'Fix the malformed or unsafe profile and run this check again.',
+      root: resolve(value('--root') ?? process.cwd()),
+      action: value('--action') ?? 'review', domain: value('--domain'), profile: null,
+      worker: null, dry_run: true,
+    };
+  }
+  if ((value('--format') ?? 'json') === 'text') {
+    console.log(`${result.status}: ${result.action}/${result.domain ?? '(missing)'}`);
+    for (const item of result.diagnostics) console.log(`- ${item}`);
+    console.log(`Next: ${result.next}`);
+  } else {
+    console.log(JSON.stringify(result, null, 2));
+  }
+  process.exit(result.status === 'OK' ? 0 : 2);
+}

package/adapters/codex/scripts/doctor.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// @scenario S-06 @feature ACA3
+// @scenario S-44 @feature ACA13
+// @decision D-ACA-15
+import { spawnSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { inspectArtifactGraphRuntime } from './lib/artifact-graph-runtime.mjs';
+
+// Parse --root from args (same as artifact-graph CLI convention)
+const args = process.argv.slice(2);
+let projectRoot = process.cwd();
+const rootIdx = args.indexOf('--root');
+if (rootIdx !== -1 && args[rootIdx + 1]) {
+  projectRoot = resolve(args[rootIdx + 1]);
+}
+
+const runtime = await inspectArtifactGraphRuntime({ projectRoot });
+
+if (!runtime.ok) {
+  const lines = [
+    `artifact-chain-assistant: doctor pre-check failed`,
+    `  reason: ${runtime.reason}`,
+  ];
+  if (runtime.cliPath) lines.push(`  cli: ${runtime.cliPath}`);
+  if (runtime.packagePath) lines.push(`  package: ${runtime.packagePath}`);
+  if (runtime.actualVersion != null) lines.push(`  actual version: ${runtime.actualVersion}`);
+  if (runtime.expectedVersion != null) lines.push(`  expected version: ${runtime.expectedVersion}`);
+  if (runtime.remediation) lines.push(`  fix: ${runtime.remediation}`);
+  process.stderr.write(lines.join('\n') + '\n');
+  process.exitCode = 1;
+} else {
+  // Forward all args to the real artifact-graph doctor
+  const result = spawnSync(runtime.cliPath, ['doctor', ...args], {
+    cwd: process.cwd(),
+    stdio: 'inherit',
+  });
+
+  if (result.error) {
+    process.stderr.write(`artifact-chain-assistant: failed to run artifact-graph doctor: ${result.error.message}\n`);
+    process.exitCode = 127;
+  } else {
+    process.exitCode = result.status ?? 1;
+  }
+}

package/adapters/codex/scripts/lib/artifact-graph-runtime.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+// @scenario S-44 @feature ACA13 @feature ACA3
+// @decision D-ACA-15
+import { access, readFile, realpath } from 'node:fs/promises';
+import { delimiter, join, dirname, resolve } from 'node:path';
+import { loadCompatibilityPolicy } from './compatibility-policy.mjs';
+
+/**
+ * Locate the artifact-graph CLI in a target project, resolve its package version,
+ * and compare against the plugin's compatibility policy.
+ *
+ * Resolution order:
+ *   1. <projectRoot>/node_modules/.bin/artifact-graph
+ *   2. PATH lookup for artifact-graph
+ *   3. ARTIFACT_GRAPH_LEGACY_CLI env var (explicit fallback)
+ *
+ * For the resolved CLI, look up its owning package.json (name === "artifact-graph")
+ * and compare the version field against policy.artifactGraph.verifiedVersion.
+ *
+ * @param {{ projectRoot: string, env?: Record<string,string> }} opts
+ * @returns {Promise<{ok: boolean, cliPath?: string, packagePath?: string, actualVersion?: string, expectedVersion?: string, reason?: string, remediation?: string}>}
+ */
+export async function inspectArtifactGraphRuntime({ projectRoot, env }) {
+  const pluginRoot = resolve(import.meta.dirname, '..', '..');
+  let policy;
+  try {
+    policy = await loadCompatibilityPolicy(pluginRoot);
+  } catch (error) {
+    return {
+      ok: false,
+      reason: 'policy_load_failed',
+      remediation: `Failed to load compatibility policy: ${error.message}`,
+      expectedVersion: null,
+    };
+  }
+
+  const expectedVersion = policy.artifactGraph.verifiedVersion;
+  const installSpec = policy.artifactGraph.installSpec;
+
+  // 1. Try project-local CLI first
+  const localBin = join(projectRoot, 'node_modules', '.bin', 'artifact-graph');
+  let cliPath = await resolveIfExecutable(localBin);
+
+  // 2. Try PATH
+  if (!cliPath) {
+    cliPath = await findOnPath(env ?? process.env);
+  }
+
+  // 3. Try explicit legacy CLI override
+  if (!cliPath) {
+    const legacy = (env ?? process.env).ARTIFACT_GRAPH_LEGACY_CLI;
+    if (legacy) {
+      cliPath = await resolveIfExecutable(legacy);
+    }
+  }
+
+  if (!cliPath) {
+    return {
+      ok: false,
+      reason: 'cli_not_found',
+      expectedVersion,
+      remediation: `artifact-graph CLI not found. Run: pnpm add -D ${installSpec}`,
+    };
+  }
+
+  // 4. Resolve the owning package.json
+  const { packagePath, version } = await resolvePackageVersion(cliPath);
+
+  if (!version) {
+    return {
+      ok: false,
+      cliPath,
+      packagePath,
+      reason: 'version_unresolved',
+      expectedVersion,
+      remediation: `Could not determine artifact-graph version from ${packagePath || cliPath}. Run: pnpm add -D ${installSpec}`,
+    };
+  }
+
+  if (version !== expectedVersion) {
+    return {
+      ok: false,
+      cliPath,
+      packagePath,
+      actualVersion: version,
+      expectedVersion,
+      reason: 'version_mismatch',
+      remediation: `artifact-graph version is ${version}, expected ${expectedVersion}. Run: pnpm add -D ${installSpec}`,
+    };
+  }
+
+  return {
+    ok: true,
+    cliPath,
+    packagePath,
+    actualVersion: version,
+    expectedVersion,
+  };
+}
+
+/**
+ * Resolve a path to its realpath if it exists and is executable (X_OK).
+ */
+async function resolveIfExecutable(path) {
+  try {
+    const real = await realpath(path);
+    await access(real, 1); // X_OK = 1
+    return real;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Search PATH for artifact-graph binary.
+ * Does NOT check ARTIFACT_GRAPH_LEGACY_CLI — that's the caller's fallback.
+ */
+export async function findOnPath(env) {
+  const pathEnv = env.PATH || '';
+  const pathDirs = pathEnv.split(delimiter);
+
+  for (const dir of pathDirs) {
+    if (!dir) continue;
+    const candidate = join(dir, 'artifact-graph');
+    const resolved = await resolveIfExecutable(candidate);
+    if (resolved) return resolved;
+  }
+
+  return null;
+}
+
+/**
+ * Given a CLI path, find the owning artifact-graph package.json and its version.
+ *
+ * Strategy:
+ * 1. Walk up from the CLI directory looking for package.json with name === "artifact-graph".
+ * 2. If CLI is under .bin/, also try walking up from the sibling artifact-graph/ package directory.
+ *
+ * Returns { packagePath, version } or { packagePath: null, version: null }.
+ */
+export async function resolvePackageVersion(cliPath) {
+  // Strategy 1: walk up from CLI location
+  const result = await walkUpForPackage(dirname(cliPath));
+  if (result.packagePath) return result;
+
+  // Strategy 2: if CLI is under a .bin/ directory, check sibling package directories
+  const dir = dirname(cliPath);
+  const parentDir = dirname(dir);
+  if (dir.endsWith('.bin') || dir.endsWith('.bin/')) {
+    // Check parentDir/artifact-graph/package.json directly
+    const siblingPkg = join(parentDir, 'artifact-graph', 'package.json');
+    try {
+      const raw = await readFile(siblingPkg, 'utf8');
+      const pkg = JSON.parse(raw);
+      if (pkg.name === 'artifact-graph') {
+        return { packagePath: siblingPkg, version: pkg.version || null };
+      }
+    } catch {
+      // No sibling package found
+    }
+  }
+
+  return { packagePath: null, version: null };
+}
+
+async function walkUpForPackage(startDir) {
+  let dir = startDir;
+  const seen = new Set();
+
+  while (dir && !seen.has(dir)) {
+    seen.add(dir);
+    const pkgPath = join(dir, 'package.json');
+    try {
+      const raw = await readFile(pkgPath, 'utf8');
+      const pkg = JSON.parse(raw);
+      if (pkg.name === 'artifact-graph') {
+        return { packagePath: pkgPath, version: pkg.version || null };
+      }
+    } catch {
+      // No package.json at this level, or not valid JSON
+    }
+
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return { packagePath: null, version: null };
+}