@specmarket/cli 0.0.3 → 0.0.5

package/src/commands/validate.ts

@@ -1,189 +1,62 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { readFile, readdir, access, stat } from 'fs/promises';
+import { readFile, readdir, access } from 'fs/promises';
 import { join, resolve, relative, normalize } from 'path';
 import { parse as parseYaml } from 'yaml';
 import {
   specYamlSchema,
+  specmarketSidecarSchema,
   EXIT_CODES,
   REQUIRED_SPEC_FILES,
   REQUIRED_STDLIB_FILES,
+  SIDECAR_FILENAME,
 } from '@specmarket/shared';
 import type { ValidationResult } from '@specmarket/shared';
+import {
+  detectSpecFormat,
+  fileExists,
+  directoryExists,
+  hasStoryFiles,
+  hasMarkdownFiles,
+} from '../lib/format-detection.js';
 
 /**
- * Validates a spec directory for completeness and schema compliance.
- *
- * Checks (errors):
- * - spec.yaml parses and conforms to Zod schema
- * - Required files exist and are non-empty: PROMPT.md, SPEC.md, SUCCESS_CRITERIA.md
- * - stdlib/ directory with STACK.md
- * - SUCCESS_CRITERIA.md has at least one criterion
- * - No circular references between spec files (Markdown link cycles)
- * - Infrastructure block validates (if present)
- *
- * Checks (warnings):
- * - Web-app/api-service/mobile-app with no infrastructure services
- * - Missing setup_time_minutes
- * - Token/cost/time estimates seem unreasonably low or high
- *
- * Exported as a testable function separate from the CLI command wrapper.
+ * Recursively collects file paths relative to baseDir, filtered by extension.
  */
-export async function validateSpec(specPath: string): Promise<ValidationResult> {
-  const dir = resolve(specPath);
-  const errors: string[] = [];
-  const warnings: string[] = [];
-
-  // Check required files exist and are non-empty
-  for (const file of REQUIRED_SPEC_FILES) {
-    const filePath = join(dir, file);
-    try {
-      await access(filePath);
-      const content = await readFile(filePath, 'utf-8');
-      if (content.trim().length === 0) {
-        errors.push(`${file} exists but is empty`);
-      }
-    } catch {
-      errors.push(`Required file missing: ${file}`);
-    }
-  }
-
-  // Check stdlib directory
-  const stdlibDir = join(dir, 'stdlib');
-  for (const file of REQUIRED_STDLIB_FILES) {
-    const filePath = join(stdlibDir, file);
-    try {
-      await access(filePath);
-      const content = await readFile(filePath, 'utf-8');
-      if (content.trim().length === 0) {
-        errors.push(`stdlib/${file} exists but is empty`);
-      }
-    } catch {
-      errors.push(`Required file missing: stdlib/${file}`);
-    }
-  }
-
-  // Parse and validate spec.yaml
-  let specYaml: unknown = null;
-  const specYamlPath = join(dir, 'spec.yaml');
+async function collectFiles(
+  currentDir: string,
+  baseDir: string,
+  extensions: Set<string>
+): Promise<string[]> {
+  const results: string[] = [];
   try {
-    const raw = await readFile(specYamlPath, 'utf-8');
-    specYaml = parseYaml(raw);
-  } catch (err) {
-    errors.push(`spec.yaml: Failed to parse YAML: ${(err as Error).message}`);
-    return { valid: false, errors, warnings };
-  }
-
-  const parseResult = specYamlSchema.safeParse(specYaml);
-  if (!parseResult.success) {
-    for (const issue of parseResult.error.issues) {
-      errors.push(
-        `spec.yaml: ${issue.path.join('.')} — ${issue.message}`
-      );
-    }
-  } else {
-    const parsed = parseResult.data;
-
-    // Check SUCCESS_CRITERIA.md has at least one criterion
-    try {
-      const criteriaContent = await readFile(join(dir, 'SUCCESS_CRITERIA.md'), 'utf-8');
-      const hasCriterion = /^- \[[ x]\]/m.test(criteriaContent);
-      if (!hasCriterion) {
-        errors.push(
-          'SUCCESS_CRITERIA.md: Must contain at least one criterion in format: - [ ] criterion text'
-        );
-      }
-    } catch {
-      // Already caught in required files check
-    }
-
-    // Check for circular references between spec files
-    const cycles = await detectCircularReferences(dir);
-    for (const cycle of cycles) {
-      errors.push(`Circular reference detected: ${cycle}`);
-    }
-
-    // Infrastructure validation warnings
-    if (parsed.infrastructure) {
-      const infra = parsed.infrastructure;
-
-      // Warn if web/api/mobile apps have no services
-      if (
-        ['web-app', 'api-service', 'mobile-app'].includes(parsed.output_type) &&
-        infra.services.length === 0
-      ) {
-        warnings.push(
-          `${parsed.output_type} should typically define infrastructure services (database, auth, etc.)`
-        );
-      }
-
-      if (!infra.setup_time_minutes) {
-        warnings.push('infrastructure.setup_time_minutes is not set');
-      }
-
-      // Validate defaultProvider matches a defined provider name
-      for (const service of infra.services) {
-        if (service.default_provider) {
-          const providerNames = service.providers.map((p) => p.name);
-          if (!providerNames.includes(service.default_provider)) {
-            errors.push(
-              `infrastructure.services[${service.name}].default_provider "${service.default_provider}" ` +
-              `does not match any defined provider (${providerNames.join(', ')})`
-            );
-          }
+    const entries = await readdir(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+        const subFiles = await collectFiles(fullPath, baseDir, extensions);
+        results.push(...subFiles);
+      } else if (entry.isFile()) {
+        const ext = entry.name.includes('.') ? '.' + entry.name.split('.').pop()! : '';
+        if (extensions.has(ext)) {
+          results.push(relative(baseDir, fullPath));
         }
       }
-    } else {
-      if (['web-app', 'api-service', 'mobile-app'].includes(parsed.output_type)) {
-        warnings.push(
-          'No infrastructure block defined. Consider adding infrastructure.services for database, auth, etc.'
-        );
-      }
-    }
-
-    // Estimate sanity checks
-    if (parsed.estimated_tokens < 1000) {
-      warnings.push(
-        `estimated_tokens (${parsed.estimated_tokens}) seems very low. Most specs use 10,000+.`
-      );
-    }
-    if (parsed.estimated_tokens > 10_000_000) {
-      warnings.push(
-        `estimated_tokens (${parsed.estimated_tokens}) seems very high.`
-      );
-    }
-    if (parsed.estimated_cost_usd < 0.01) {
-      warnings.push(
-        `estimated_cost_usd ($${parsed.estimated_cost_usd}) seems very low.`
-      );
-    }
-    if (parsed.estimated_time_minutes < 1) {
-      warnings.push(
-        `estimated_time_minutes (${parsed.estimated_time_minutes}) seems unrealistically low.`
-      );
     }
+  } catch {
+    // Directory unreadable
   }
-
-  return {
-    valid: errors.length === 0,
-    errors,
-    warnings,
-  };
+  return results;
 }
 
 /**
  * Scans all Markdown/YAML files in the spec directory for relative file
  * references (Markdown links) and detects cycles in the reference graph.
- *
- * Returns an array of cycle descriptions (empty if no cycles found).
- * Uses DFS with coloring (white/gray/black) for cycle detection.
  */
 export async function detectCircularReferences(dir: string): Promise<string[]> {
-  // Collect all text files in the spec directory (md, yaml, yml)
   const textExtensions = new Set(['.md', '.yaml', '.yml']);
   const files = await collectFiles(dir, dir, textExtensions);
-
-  // Build adjacency list: file -> files it references via Markdown links
   const graph = new Map<string, Set<string>>();
   const linkPattern = /\[(?:[^\]]*)\]\(([^)]+)\)/g;
 
@@ -194,32 +67,31 @@ export async function detectCircularReferences(dir: string): Promise<string[]> {
       let match: RegExpExecArray | null;
       while ((match = linkPattern.exec(content)) !== null) {
         const target = match[1]!;
-        // Skip external URLs, anchors, and mailto
-        if (target.startsWith('http://') || target.startsWith('https://') ||
-            target.startsWith('#') || target.startsWith('mailto:')) {
+        if (
+          target.startsWith('http://') ||
+          target.startsWith('https://') ||
+          target.startsWith('#') ||
+          target.startsWith('mailto:')
+        ) {
           continue;
         }
-        // Strip anchor fragments (e.g., "./SPEC.md#section" -> "./SPEC.md")
         const targetPath = target.split('#')[0]!;
         if (!targetPath) continue;
-
-        // Resolve relative to the file's directory
         const fileDir = join(dir, file, '..');
         const resolvedTarget = normalize(relative(dir, resolve(fileDir, targetPath)));
-
-        // Only track references to files within the spec directory
         if (!resolvedTarget.startsWith('..') && files.includes(resolvedTarget)) {
           refs.add(resolvedTarget);
         }
       }
     } catch {
-      // File unreadable — skip
+      // skip
     }
     graph.set(file, refs);
   }
 
-  // DFS cycle detection
-  const WHITE = 0, GRAY = 1, BLACK = 2;
+  const WHITE = 0,
+    GRAY = 1,
+    BLACK = 2;
   const color = new Map<string, number>();
   const parent = new Map<string, string | null>();
   const cycles: string[] = [];
@@ -233,7 +105,6 @@ export async function detectCircularReferences(dir: string): Promise<string[]> {
     const neighbors = graph.get(node) ?? new Set();
     for (const neighbor of neighbors) {
       if (color.get(neighbor) === GRAY) {
-        // Found a cycle — reconstruct the path
         const cyclePath: string[] = [neighbor, node];
         let curr = node;
         while (curr !== neighbor) {
@@ -263,44 +134,314 @@ export async function detectCircularReferences(dir: string): Promise<string[]> {
 }
 
 /**
- * Recursively collects file paths relative to baseDir, filtered by extension.
+ * Format-specific validation for specmarket-legacy. Pushes to errors/warnings.
+ * Zero behavior change from original validateSpec for legacy dirs.
  */
-async function collectFiles(
-  currentDir: string,
-  baseDir: string,
-  extensions: Set<string>
-): Promise<string[]> {
-  const results: string[] = [];
+async function validateLegacySpec(
+  dir: string,
+  errors: string[],
+  warnings: string[]
+): Promise<void> {
+  for (const file of REQUIRED_SPEC_FILES) {
+    const filePath = join(dir, file);
+    try {
+      await access(filePath);
+      const content = await readFile(filePath, 'utf-8');
+      if (content.trim().length === 0) {
+        errors.push(`${file} exists but is empty`);
+      }
+    } catch {
+      errors.push(`Required file missing: ${file}`);
+    }
+  }
+
+  const stdlibDir = join(dir, 'stdlib');
+  for (const file of REQUIRED_STDLIB_FILES) {
+    const filePath = join(stdlibDir, file);
+    try {
+      await access(filePath);
+      const content = await readFile(filePath, 'utf-8');
+      if (content.trim().length === 0) {
+        errors.push(`stdlib/${file} exists but is empty`);
+      }
+    } catch {
+      errors.push(`Required file missing: stdlib/${file}`);
+    }
+  }
+
+  let specYaml: unknown = null;
+  const specYamlPath = join(dir, 'spec.yaml');
   try {
-    const entries = await readdir(currentDir, { withFileTypes: true });
-    for (const entry of entries) {
-      const fullPath = join(currentDir, entry.name);
-      if (entry.isDirectory()) {
-        // Skip hidden directories and node_modules
-        if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
-        const subFiles = await collectFiles(fullPath, baseDir, extensions);
-        results.push(...subFiles);
-      } else if (entry.isFile()) {
-        const ext = entry.name.includes('.') ? '.' + entry.name.split('.').pop() : '';
-        if (extensions.has(ext)) {
-          results.push(relative(baseDir, fullPath));
+    const raw = await readFile(specYamlPath, 'utf-8');
+    specYaml = parseYaml(raw);
+  } catch (err) {
+    errors.push(`spec.yaml: Failed to parse YAML: ${(err as Error).message}`);
+    return;
+  }
+
+  const parseResult = specYamlSchema.safeParse(specYaml);
+  if (!parseResult.success) {
+    for (const issue of parseResult.error.issues) {
+      errors.push(`spec.yaml: ${issue.path.join('.')} — ${issue.message}`);
+    }
+    return;
+  }
+
+  const parsed = parseResult.data;
+
+  try {
+    const criteriaContent = await readFile(join(dir, 'SUCCESS_CRITERIA.md'), 'utf-8');
+    const hasCriterion = /^- \[[ x]\]/m.test(criteriaContent);
+    if (!hasCriterion) {
+      errors.push(
+        'SUCCESS_CRITERIA.md: Must contain at least one criterion in format: - [ ] criterion text'
+      );
+    }
+  } catch {
+    // Already caught in required files check
+  }
+
+  const cycles = await detectCircularReferences(dir);
+  for (const cycle of cycles) {
+    errors.push(`Circular reference detected: ${cycle}`);
+  }
+
+  if (parsed.infrastructure) {
+    const infra = parsed.infrastructure;
+    if (
+      ['web-app', 'api-service', 'mobile-app'].includes(parsed.output_type) &&
+      infra.services.length === 0
+    ) {
+      warnings.push(
+        `${parsed.output_type} should typically define infrastructure services (database, auth, etc.)`
+      );
+    }
+    if (!infra.setup_time_minutes) {
+      warnings.push('infrastructure.setup_time_minutes is not set');
+    }
+    for (const service of infra.services) {
+      if (service.default_provider) {
+        const providerNames = service.providers.map((p) => p.name);
+        if (!providerNames.includes(service.default_provider)) {
+          errors.push(
+            `infrastructure.services[${service.name}].default_provider "${service.default_provider}" ` +
+              `does not match any defined provider (${providerNames.join(', ')})`
+          );
         }
       }
     }
+  } else {
+    if (['web-app', 'api-service', 'mobile-app'].includes(parsed.output_type)) {
+      warnings.push(
+        'No infrastructure block defined. Consider adding infrastructure.services for database, auth, etc.'
+      );
+    }
+  }
+
+  if (parsed.estimated_tokens < 1000) {
+    warnings.push(
+      `estimated_tokens (${parsed.estimated_tokens}) seems very low. Most specs use 10,000+.`
+    );
+  }
+  if (parsed.estimated_tokens > 10_000_000) {
+    warnings.push(`estimated_tokens (${parsed.estimated_tokens}) seems very high.`);
+  }
+  if (parsed.estimated_cost_usd < 0.01) {
+    warnings.push(
+      `estimated_cost_usd ($${parsed.estimated_cost_usd}) seems very low.`
+    );
+  }
+  if (parsed.estimated_time_minutes < 1) {
+    warnings.push(
+      `estimated_time_minutes (${parsed.estimated_time_minutes}) seems unrealistically low.`
+    );
+  }
+}
+
+/**
+ * Validates a spec directory. Detects format first, then runs universal checks
+ * and format-specific validation. Returns ValidationResult with format and
+ * formatDetectedBy when detection ran.
+ */
+export async function validateSpec(specPath: string): Promise<ValidationResult> {
+  const dir = resolve(specPath);
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  const detection = await detectSpecFormat(dir);
+
+  // Universal: directory non-empty (at least one readable file)
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const hasAnyFile = entries.some((e) => e.isFile());
+    if (!hasAnyFile) {
+      errors.push('Directory is empty or has no readable files');
+    }
   } catch {
-    // Directory unreadable
+    errors.push('Directory is empty or unreadable');
   }
-  return results;
+
+  // If sidecar exists, validate with specmarketSidecarSchema and sanity-check estimates
+  const sidecarPath = join(dir, SIDECAR_FILENAME);
+  if (await fileExists(sidecarPath)) {
+    try {
+      const raw = await readFile(sidecarPath, 'utf-8');
+      const parsed = parseYaml(raw) as unknown;
+      const sidecarResult = specmarketSidecarSchema.safeParse(parsed);
+      if (!sidecarResult.success) {
+        for (const issue of sidecarResult.error.issues) {
+          errors.push(
+            `${SIDECAR_FILENAME}: ${issue.path.join('.')} — ${issue.message}`
+          );
+        }
+      } else {
+        const sidecar = sidecarResult.data;
+        if (sidecar.estimated_tokens !== undefined) {
+          if (sidecar.estimated_tokens < 1000) {
+            warnings.push(
+              `sidecar estimated_tokens (${sidecar.estimated_tokens}) seems very low.`
+            );
+          }
+          if (sidecar.estimated_tokens > 10_000_000) {
+            warnings.push(
+              `sidecar estimated_tokens (${sidecar.estimated_tokens}) seems very high.`
+            );
+          }
+        }
+        if (
+          sidecar.estimated_cost_usd !== undefined &&
+          sidecar.estimated_cost_usd < 0.01
+        ) {
+          warnings.push(
+            `sidecar estimated_cost_usd ($${sidecar.estimated_cost_usd}) seems very low.`
+          );
+        }
+        if (
+          sidecar.estimated_time_minutes !== undefined &&
+          sidecar.estimated_time_minutes < 1
+        ) {
+          warnings.push(
+            `sidecar estimated_time_minutes (${sidecar.estimated_time_minutes}) seems unrealistically low.`
+          );
+        }
+      }
+    } catch (err) {
+      errors.push(
+        `${SIDECAR_FILENAME}: Failed to read or parse: ${(err as Error).message}`
+      );
+    }
+  }
+
+  // Format-specific validation. Run legacy validation when spec.yaml exists or
+  // when format is legacy (e.g. PROMPT+SUCCESS_CRITERIA but spec.yaml missing).
+  const hasSpecYaml = await fileExists(join(dir, 'spec.yaml'));
+  if (hasSpecYaml || detection.format === 'specmarket-legacy') {
+    await validateLegacySpec(dir, errors, warnings);
+  }
+
+  switch (detection.format) {
+    case 'specmarket-legacy':
+      break;
+    case 'speckit': {
+      const hasSpecMd = await fileExists(join(dir, 'spec.md'));
+      const hasTasksMd = await fileExists(join(dir, 'tasks.md'));
+      const hasPlanMd = await fileExists(join(dir, 'plan.md'));
+      const hasSpecifyDir = await directoryExists(join(dir, '.specify'));
+      if (!hasSpecMd) {
+        errors.push('speckit format requires spec.md');
+      }
+      if (!hasTasksMd && !hasPlanMd) {
+        errors.push('speckit format requires tasks.md or plan.md');
+      }
+      if (!hasSpecifyDir) {
+        warnings.push('speckit format: .specify/ directory is recommended');
+      }
+      break;
+    }
+    case 'bmad': {
+      const hasPrdMd = await fileExists(join(dir, 'prd.md'));
+      const hasStory = await hasStoryFiles(dir);
+      if (!hasPrdMd && !hasStory) {
+        errors.push('bmad format requires prd.md or story-*.md files');
+      }
+      const hasArch = await fileExists(join(dir, 'architecture.md'));
+      if (!hasArch) {
+        warnings.push('bmad format: architecture.md is recommended');
+      }
+      break;
+    }
+    case 'ralph': {
+      const prdPath = join(dir, 'prd.json');
+      if (!(await fileExists(prdPath))) {
+        errors.push('ralph format requires prd.json');
+        break;
+      }
+      try {
+        const raw = await readFile(prdPath, 'utf-8');
+        const data = JSON.parse(raw) as unknown;
+        if (
+          !data ||
+          typeof data !== 'object' ||
+          !('userStories' in data) ||
+          !Array.isArray((data as { userStories: unknown }).userStories)
+        ) {
+          errors.push('ralph format: prd.json must have userStories array');
+        }
+      } catch {
+        errors.push('ralph format: prd.json must be valid JSON with userStories array');
+      }
+      break;
+    }
+    case 'custom':
+    default: {
+      const hasMd = await hasMarkdownFiles(dir);
+      if (!hasMd) {
+        errors.push('custom format requires at least one .md file');
+        break;
+      }
+      // At least one .md file > 100 bytes
+      const textExtensions = new Set(['.md']);
+      const mdFiles = await collectFiles(dir, dir, textExtensions);
+      let hasSubstantialMd = false;
+      for (const f of mdFiles) {
+        try {
+          const content = await readFile(join(dir, f), 'utf-8');
+          if (content.length > 100) {
+            hasSubstantialMd = true;
+            break;
+          }
+        } catch {
+          // skip
+        }
+      }
+      if (!hasSubstantialMd) {
+        errors.push('custom format requires at least one .md file larger than 100 bytes');
+      }
+      break;
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    format: detection.format,
+    formatDetectedBy: detection.detectedBy,
+  };
 }
 
 export function createValidateCommand(): Command {
   return new Command('validate')
     .description('Validate a spec directory for completeness and schema compliance')
-    .argument('<path>', 'Path to the spec directory')
+    .argument('[path]', 'Path to the spec directory (defaults to current directory)', '.')
     .action(async (specPath: string) => {
       try {
         const result = await validateSpec(specPath);
 
+        if (result.format !== undefined) {
+          console.log(chalk.gray(`Detected format: ${result.format}`));
+        }
+
         if (result.warnings.length > 0) {
           console.log(chalk.yellow('\nWarnings:'));
           for (const warning of result.warnings) {