@zebralabs/context-cli 0.1.3 → 0.1.4

package/src/application/compile/stage6-validation.js

@@ -0,0 +1,133 @@
+import { FileWriter } from "../../infrastructure/file-system/file-writer.js";
+import path from "node:path";
+
+/**
+ * Stage 6: Validation & Reporting
+ * Validates compilation and generates comprehensive reports
+ */
+export class Stage6Validation {
+  constructor() {
+    this.fileWriter = new FileWriter();
+  }
+
+  /**
+   * Validate and generate reports
+   * @param {Compilation} compilation - The compilation
+   * @param {Object} stageReports - Reports from all stages
+   * @param {string} outputDir - Output directory
+   * @returns {Object} Validation result
+   */
+  execute(compilation, stageReports, outputDir) {
+    const reportsDir = path.join(outputDir, "reports");
+    this.fileWriter.ensureDir(reportsDir);
+
+    // Validation checks
+    const validation = {
+      rulesValid: true,
+      noDuplicateIds: true,
+      allRulesHaveIds: true,
+      errors: []
+    };
+
+    // Check for duplicate rule IDs
+    const ruleIds = new Set();
+    for (const rule of compilation.rules) {
+      if (ruleIds.has(rule.id)) {
+        validation.noDuplicateIds = false;
+        validation.errors.push(`Duplicate rule ID: ${rule.id}`);
+      }
+      ruleIds.add(rule.id);
+    }
+
+    // Check all rules have required fields
+    for (const rule of compilation.rules) {
+      if (!rule.id || !rule.level || !rule.rule) {
+        validation.allRulesHaveIds = false;
+        validation.errors.push(`Rule missing required fields: ${rule.id || "unknown"}`);
+      }
+    }
+
+    validation.rulesValid = validation.noDuplicateIds && validation.allRulesHaveIds;
+
+    // Generate compilation report
+    const compilationReport = this.generateCompilationReport(compilation, stageReports, validation);
+    this.fileWriter.writeFile(
+      path.join(reportsDir, "COMPILATION-REPORT.md"),
+      compilationReport
+    );
+
+    return {
+      validation,
+      reportsGenerated: ["COMPILATION-REPORT.md"]
+    };
+  }
+
+  /**
+   * Generate compilation report
+   */
+  generateCompilationReport(compilation, stageReports, validation) {
+    const lines = [];
+    lines.push("# Compilation Report");
+    lines.push("");
+    lines.push(`Generated: ${compilation.metadata.timestamp}`);
+    lines.push("");
+
+    // Summary
+    lines.push("## Summary");
+    lines.push("");
+    lines.push(`- Files Processed: ${stageReports.stage2?.filesProcessed || 0}`);
+    lines.push(`- Rules Extracted: ${compilation.rules.length}`);
+    lines.push(`- Preferences Extracted: ${compilation.preferences.length}`);
+    lines.push(`- Scopes Extracted: ${compilation.scopes.length}`);
+    lines.push(`- Categories: ${compilation.getCategories().length}`);
+    lines.push("");
+
+    // Validation
+    lines.push("## Validation");
+    lines.push("");
+    if (validation.rulesValid) {
+      lines.push("✅ All rules are valid");
+    } else {
+      lines.push("❌ Validation errors found:");
+      for (const error of validation.errors) {
+        lines.push(`  - ${error}`);
+      }
+    }
+    lines.push("");
+
+    // Rules by category
+    lines.push("## Rules by Category");
+    lines.push("");
+    const categories = compilation.getCategories();
+    for (const category of categories) {
+      const rules = compilation.getRulesByCategory(category);
+      lines.push(`- **${category}**: ${rules.length} rules`);
+    }
+    lines.push("");
+
+    // Rules by level
+    lines.push("## Rules by Level");
+    lines.push("");
+    const levels = ["must", "should", "prefer", "avoid"];
+    for (const level of levels) {
+      const rules = compilation.getRulesByLevel(level);
+      if (rules.length > 0) {
+        lines.push(`- **${level}**: ${rules.length} rules`);
+      }
+    }
+    lines.push("");
+
+    // Errors and warnings
+    if (stageReports.stage2?.errors?.length > 0) {
+      lines.push("## Errors");
+      lines.push("");
+      for (const error of stageReports.stage2.errors) {
+        lines.push(`- ${error.file}: ${error.error}`);
+      }
+      lines.push("");
+    }
+
+    return lines.join("\n");
+  }
+}
+

package/src/application/ports/asset-generator.js

@@ -0,0 +1,33 @@
+/**
+ * Asset Generator Port (Interface)
+ * Defines the contract for tool-specific asset generators
+ */
+export class IAssetGenerator {
+  /**
+   * Generate tool-specific assets from consolidated rules
+   * @param {Compilation} compilation - The compiled context
+   * @param {string} outputPath - Where to write assets
+   * @returns {Promise<Object>} Generation result
+   */
+  async generate(compilation, outputPath) {
+    throw new Error("Not implemented");
+  }
+
+  /**
+   * Merge pre-generated assets from packs
+   * @param {Object[]} assets - Assets from packs
+   * @returns {Object[]} Merged assets
+   */
+  merge(assets) {
+    throw new Error("Not implemented");
+  }
+
+  /**
+   * Get the tool name this generator is for
+   * @returns {string} Tool name (e.g., "cursor", "claude")
+   */
+  getToolName() {
+    throw new Error("Not implemented");
+  }
+}
+

package/src/context.js

@@ -17,9 +17,9 @@ Context-as-Code CLI
 
 Usage:
   ctx help
-  ctx list
-  ctx compile
-  ctx validate
+  ctx list [--context-yaml <path>]
+  ctx compile [--pack <packId>] [--context-yaml <path>]
+  ctx validate [--context-yaml <path>]
 
 Pack install:
   ctx pack install <packId> [--repo-root <path>] [--mode SkipExisting|Overwrite]
@@ -32,6 +32,9 @@ Examples (registry download):
   ctx pack install pack-01-documentation-management --registry https://example.com --token YOURTOKEN
   ctx pack install pack-01-documentation-management --registry https://example.com --token YOURTOKEN --version 0.1.0
 
+Examples (compile):
+  ctx compile --pack pack-01-documentation-management
+
 Notes:
 - Zip must contain: practices-and-standards/install.ps1
 - Installer merges into <repo-root>/docs/practices-and-standards/
@@ -41,14 +44,62 @@ Notes:
 function findRepoContextRoot(startDir) {
   let dir = startDir;
   while (true) {
-    const candidate = path.join(dir, "docs", "practices-and-standards", "context.yaml");
-    if (fs.existsSync(candidate)) return dir;
+    // Check installed location
+    const candidate1 = path.join(dir, "docs", "practices-and-standards", "context.yaml");
+    if (fs.existsSync(candidate1)) return dir;
+    
+    // Check source/development location
+    const candidate2 = path.join(dir, "practices-and-standards", "context.yaml");
+    if (fs.existsSync(candidate2)) return dir;
+    
     const parent = path.dirname(dir);
     if (parent === dir) return null;
     dir = parent;
   }
 }
 
+function deriveRepoRootFromContextPath(contextPath) {
+  const normalized = path.normalize(contextPath);
+  
+  // Check if path ends with docs/practices-and-standards/context.yaml
+  const docsSuffix = path.join("docs", "practices-and-standards", "context.yaml");
+  if (normalized.endsWith(docsSuffix)) {
+    return normalized.substring(0, normalized.length - docsSuffix.length);
+  }
+  
+  // Check if path ends with practices-and-standards/context.yaml
+  const psSuffix = path.join("practices-and-standards", "context.yaml");
+  if (normalized.endsWith(psSuffix)) {
+    return normalized.substring(0, normalized.length - psSuffix.length);
+  }
+  
+  // Fallback: go up 3 levels from context.yaml
+  // context.yaml -> practices-and-standards -> (repo root)
+  let current = path.dirname(contextPath);
+  if (path.basename(current) === "practices-and-standards") {
+    return path.dirname(current);
+  }
+  // Or if in docs/practices-and-standards
+  if (path.basename(current) === "practices-and-standards" && path.basename(path.dirname(current)) === "docs") {
+    return path.dirname(path.dirname(current));
+  }
+  
+  // Last resort: assume parent of practices-and-standards or docs
+  return path.dirname(path.dirname(contextPath));
+}
+
+function findContextYamlPath(repoRoot) {
+  // Try installed location first
+  const installedPath = path.join(repoRoot, "docs", "practices-and-standards", "context.yaml");
+  if (fs.existsSync(installedPath)) return installedPath;
+  
+  // Try source location
+  const sourcePath = path.join(repoRoot, "practices-and-standards", "context.yaml");
+  if (fs.existsSync(sourcePath)) return sourcePath;
+  
+  return null;
+}
+
 function readYamlFile(filePath) {
   const raw = fs.readFileSync(filePath, "utf8");
   return YAML.parse(raw);
@@ -197,6 +248,188 @@ function cmdValidate(repoRoot, ctx) {
   process.exit(errors.length > 0 ? 1 : 0);
 }
 
+// Helper function to test Stage5Assets dependencies individually
+async function testStage5Dependencies() {
+  const dependencies = [
+    { name: "CursorRulesGenerator", path: "./infrastructure/assets/cursor/cursor-rules-generator.js" },
+    { name: "CursorSkillsGenerator", path: "./infrastructure/assets/cursor/cursor-skills-generator.js" },
+    { name: "ClaudeGenerator", path: "./infrastructure/assets/claude/claude-generator.js" },
+    { name: "SkillExtractor", path: "./infrastructure/parsing/skill-extractor.js" },
+    { name: "FileReader", path: "./infrastructure/file-system/file-reader.js" },
+    { name: "IAssetGenerator", path: "./application/ports/asset-generator.js" },
+    { name: "FileWriter", path: "./infrastructure/file-system/file-writer.js" },
+    { name: "MarkdownParser", path: "./infrastructure/parsing/markdown-parser.js" },
+  ];
+  
+  console.log("  Testing Stage5Assets dependencies...");
+  for (const dep of dependencies) {
+    try {
+      console.log(`    Testing dependency: ${dep.name} from ${dep.path}`);
+      const module = await import(dep.path);
+      const exportNames = Object.keys(module);
+      console.log(`      ✓ Success - exports: ${exportNames.join(", ")}`);
+      if (!exportNames.includes(dep.name)) {
+        console.warn(`      ⚠ Warning: Expected export '${dep.name}' not found`);
+      }
+    } catch (error) {
+      console.error(`      ✗ FAILED: ${error.message}`);
+      console.error(`        Error type: ${error.constructor.name}`);
+      if (error.code) {
+        console.error(`        Error code: ${error.code}`);
+      }
+      if (error.stack) {
+        const stackLines = error.stack.split("\n").slice(0, 8);
+        console.error(`        Stack trace:\n${stackLines.map(l => `          ${l}`).join("\n")}`);
+      }
+      throw new Error(`Failed to import ${dep.name} from ${dep.path}: ${error.message}`);
+    }
+  }
+  console.log("    ✓ All Stage5Assets dependencies successful");
+}
+
+// Helper function to test imports individually
+async function testImports() {
+  const imports = [
+    { name: "Stage1Discovery", path: "./application/compile/stage1-discovery.js" },
+    { name: "Stage2Extraction", path: "./application/compile/stage2-extraction.js" },
+    { name: "Stage4Consolidation", path: "./application/compile/stage4-consolidation.js" },
+    { name: "Stage5Assets", path: "./application/compile/stage5-assets.js", testDependencies: true },
+    { name: "Stage6Validation", path: "./application/compile/stage6-validation.js" },
+    { name: "CompileContext", path: "./application/compile/compile-context.js" },
+  ];
+  
+  console.log("Testing module imports...");
+  for (const imp of imports) {
+    try {
+      console.log(`  Testing: ${imp.name} from ${imp.path}`);
+      
+      // For Stage5Assets, test dependencies first
+      if (imp.testDependencies) {
+        try {
+          await testStage5Dependencies();
+        } catch (depError) {
+          console.error(`    ✗ Dependency test failed before importing ${imp.name}`);
+          throw depError;
+        }
+      }
+      
+      const module = await import(imp.path);
+      const exportNames = Object.keys(module);
+      console.log(`    ✓ Success - exports: ${exportNames.join(", ")}`);
+      if (!exportNames.includes(imp.name)) {
+        console.warn(`    ⚠ Warning: Expected export '${imp.name}' not found`);
+      }
+    } catch (error) {
+      console.error(`    ✗ FAILED: ${error.message}`);
+      console.error(`      Error type: ${error.constructor.name}`);
+      if (error.code) {
+        console.error(`      Error code: ${error.code}`);
+      }
+      if (error.stack) {
+        const stackLines = error.stack.split("\n").slice(0, 10);
+        console.error(`      Stack trace:\n${stackLines.map(l => `        ${l}`).join("\n")}`);
+      }
+      throw new Error(`Failed to import ${imp.name} from ${imp.path}: ${error.message}`);
+    }
+  }
+  console.log("  ✓ All imports successful\n");
+}
+
+async function cmdCompilePack(repoRoot, packId) {
+  // Test all imports first to isolate the failing module
+  try {
+    await testImports();
+  } catch (error) {
+    console.error("\n❌ Import test failed - this indicates a syntax or module resolution error");
+    die(`Import test failed: ${error.message}`);
+  }
+  
+  // Now try to import the main module with detailed error handling
+  let CompileContext;
+  try {
+    console.log("Loading compilation module...");
+    const modulePath = "./application/compile/compile-context.js";
+    console.log(`  Import path: ${modulePath}`);
+    console.log(`  Current working directory: ${process.cwd()}`);
+    
+    const module = await import(modulePath);
+    CompileContext = module.CompileContext;
+    
+    if (!CompileContext) {
+      const availableExports = Object.keys(module).join(", ");
+      throw new Error(`CompileContext not exported from ${modulePath}. Available exports: ${availableExports || "(none)"}`);
+    }
+    console.log("  ✓ Module loaded successfully");
+  } catch (error) {
+    console.error("\n❌ Failed to load compilation module:");
+    console.error(`  Error type: ${error.constructor.name}`);
+    console.error(`  Error message: ${error.message}`);
+    if (error.code) {
+      console.error(`  Error code: ${error.code}`);
+      if (error.code === "ERR_MODULE_NOT_FOUND") {
+        console.error(`  This indicates the module file was not found at the specified path.`);
+        console.error(`  Check if the file exists and the relative path is correct.`);
+      }
+    }
+    if (error.stack) {
+      const stackLines = error.stack.split("\n").slice(0, 15);
+      console.error(`  Stack trace:\n${stackLines.map(l => `    ${l}`).join("\n")}`);
+    }
+    die(`Failed to load compilation module: ${error.message}`);
+  }
+  
+  // Try to create compiler instance
+  let compiler;
+  try {
+    compiler = new CompileContext();
+    console.log("  ✓ Compiler instance created\n");
+  } catch (error) {
+    console.error("\n❌ Failed to create compiler instance:");
+    console.error(`  Error: ${error.message}`);
+    if (error.stack) {
+      const stackLines = error.stack.split("\n").slice(0, 10);
+      console.error(`  Stack trace:\n${stackLines.map(l => `    ${l}`).join("\n")}`);
+    }
+    die(`Failed to create compiler: ${error.message}`);
+  }
+  
+  // Execute compilation
+  try {
+    const result = await compiler.compilePack(repoRoot, packId);
+    
+    console.log("\n✅ Compilation successful!");
+    console.log(`\nOutput: ${result.outputPath}`);
+    console.log(`\nRules by category:`);
+    const categories = result.compilation.getCategories();
+    for (const category of categories) {
+      const rules = result.compilation.getRulesByCategory(category);
+      console.log(`  ${category}: ${rules.length} rules`);
+    }
+    
+    console.log(`\nTotal: ${result.compilation.rules.length} rules`);
+    console.log(`      ${result.compilation.preferences.length} preferences`);
+    console.log(`      ${result.compilation.scopes.length} scopes`);
+    
+    console.log(`\nGenerated files:`);
+    console.log(`  Consolidated: ${result.stageReports.stage4.filesGenerated.length} files`);
+    console.log(`  Cursor rules: ${result.stageReports.stage5.results.cursorRules.filesGenerated.length} files`);
+    if (result.stageReports.stage5.skillsExtracted > 0) {
+      console.log(`  Cursor skills: ${result.stageReports.stage5.results.cursorSkills.filesGenerated.length} files`);
+    }
+    console.log(`  Claude.md: 1 file`);
+    console.log(`  Reports: ${result.stageReports.stage6.reportsGenerated.length} files`);
+    
+  } catch (error) {
+    console.error("\n❌ Compilation execution failed:");
+    console.error(`  Error: ${error.message}`);
+    if (error.stack) {
+      const stackLines = error.stack.split("\n").slice(0, 15);
+      console.error(`  Stack trace:\n${stackLines.map(l => `    ${l}`).join("\n")}`);
+    }
+    die(error.message);
+  }
+}
+
 function cmdCompile(repoRoot, ctx) {
   const installed = orderInstalledPacks(ctx.installed_packs ?? [], ctx.precedence ?? []);
   const psRoot = path.join(repoRoot, "docs", "practices-and-standards");
@@ -539,7 +772,7 @@ async function main() {
 
   if (cmd === "--version" || cmd === "-v" || cmd === "version") {
     // Make sure package.json has version (or hardcode a constant)
-    console.log("0.1.3");
+    console.log("0.1.4");
     return;
   }
 
@@ -565,10 +798,35 @@ async function main() {
   }
 
   // Existing behavior: these require an existing context.yaml
-  const repoRoot = findRepoContextRoot(process.cwd());
-  if (!repoRoot) die("Could not find docs/practices-and-standards/context.yaml in this directory or any parent.");
+  const contextYamlIndex = process.argv.indexOf("--context-yaml");
+  
+  let repoRoot;
+  let contextPath;
+  
+  if (contextYamlIndex !== -1 && process.argv[contextYamlIndex + 1]) {
+    // Explicit context.yaml path provided
+    contextPath = path.isAbsolute(process.argv[contextYamlIndex + 1])
+      ? process.argv[contextYamlIndex + 1]
+      : path.join(process.cwd(), process.argv[contextYamlIndex + 1]);
+    
+    if (!fs.existsSync(contextPath)) {
+      die(`context.yaml not found at ${contextPath}`);
+    }
+    
+    repoRoot = deriveRepoRootFromContextPath(contextPath);
+  } else {
+    // Auto-detect
+    repoRoot = findRepoContextRoot(process.cwd());
+    if (!repoRoot) {
+      die("Could not find context.yaml. Use --context-yaml to specify the path.");
+    }
+    
+    contextPath = findContextYamlPath(repoRoot);
+    if (!contextPath) {
+      die("Could not find context.yaml in expected locations.");
+    }
+  }
 
-  const contextPath = path.join(repoRoot, "docs", "practices-and-standards", "context.yaml");
   const ctx = readYamlFile(contextPath);
 
   if (!ctx?.schema || ctx.schema !== "context-install/v1") {
@@ -577,7 +835,13 @@ async function main() {
 
   switch (cmd) {
     case "list": return cmdList(repoRoot, ctx);
-    case "compile": return cmdCompile(repoRoot, ctx);
+    case "compile": 
+      // Check for --pack flag
+      const packIndex = process.argv.indexOf("--pack");
+      if (packIndex !== -1 && process.argv[packIndex + 1]) {
+        return cmdCompilePack(repoRoot, process.argv[packIndex + 1]);
+      }
+      return cmdCompile(repoRoot, ctx);
     case "validate": return cmdValidate(repoRoot, ctx);
     default:
       console.log(`Unknown command: ${cmd}\n`);

package/src/domain/compilation.js

@@ -0,0 +1,77 @@
+import { Rule } from "./rule.js";
+import { Preference } from "./preference.js";
+import { Scope } from "./scope.js";
+
+/**
+ * Compilation aggregate root
+ * Orchestrates the compilation process and holds all extracted data
+ */
+export class Compilation {
+  constructor() {
+    this.rules = [];
+    this.preferences = [];
+    this.scopes = [];
+    this.sourceFiles = [];
+    this.packs = [];
+    this.metadata = {
+      timestamp: new Date().toISOString(),
+      version: "1.0.0"
+    };
+  }
+
+  /**
+   * Add a rule to the compilation
+   * @param {Rule} rule - Rule to add
+   */
+  addRule(rule) {
+    // Check for duplicate IDs
+    const existing = this.rules.find(r => r.id === rule.id);
+    if (existing) {
+      throw new Error(`Duplicate rule ID: ${rule.id} in ${rule.source.file} (already exists from ${existing.source.file})`);
+    }
+    this.rules.push(rule);
+  }
+
+  /**
+   * Add a preference to the compilation
+   * @param {Preference} preference - Preference to add
+   */
+  addPreference(preference) {
+    this.preferences.push(preference);
+  }
+
+  /**
+   * Add a scope to the compilation
+   * @param {Scope} scope - Scope to add
+   */
+  addScope(scope) {
+    this.scopes.push(scope);
+  }
+
+  /**
+   * Get rules by category
+   * @param {string} category - Category to filter by
+   * @returns {Rule[]} Rules in that category
+   */
+  getRulesByCategory(category) {
+    return this.rules.filter(r => r.category === category);
+  }
+
+  /**
+   * Get all categories
+   * @returns {string[]} Unique categories
+   */
+  getCategories() {
+    return [...new Set(this.rules.map(r => r.category))].sort();
+  }
+
+  /**
+   * Get rules by level
+   * @param {string} level - Level to filter by
+   * @returns {Rule[]} Rules with that level
+   */
+  getRulesByLevel(level) {
+    return this.rules.filter(r => r.level === level);
+  }
+}
+

package/src/domain/preference.js

@@ -0,0 +1,23 @@
+/**
+ * Preference value object
+ * Represents a preference extracted from documentation
+ */
+export class Preference {
+  /**
+   * @param {Object} data
+   * @param {string} data.name - Preference name
+   * @param {string} [data.description] - Preference description
+   * @param {Object} data.source - Source information
+   * @param {string} data.source.pack - Pack ID
+   * @param {string} data.source.packVersion - Pack version
+   * @param {string} data.source.file - Source file path
+   * @param {number} data.source.line - Line number
+   * @param {number} data.source.precedence - Precedence index
+   */
+  constructor(data) {
+    this.name = data.name;
+    this.description = data.description;
+    this.source = data.source;
+  }
+}
+

package/src/domain/rule.js

@@ -0,0 +1,71 @@
+/**
+ * Rule value object
+ * Represents a single rule extracted from documentation
+ */
+export class Rule {
+  /**
+   * @param {Object} data
+   * @param {string} data.id - Rule ID (e.g., "doc-structure-001")
+   * @param {string} data.level - Rule level: "must" | "should" | "prefer" | "avoid"
+   * @param {string} data.category - Category extracted from rule ID prefix
+   * @param {string[]} data.appliesTo - What this rule applies to
+   * @param {string} data.rule - The rule statement
+   * @param {string} [data.rationale] - Why this rule exists
+   * @param {Object} data.source - Source information
+   * @param {string} data.source.pack - Pack ID
+   * @param {string} data.source.packVersion - Pack version
+   * @param {string} data.source.file - Source file path
+   * @param {number} data.source.line - Line number where rule starts
+   * @param {number} data.source.precedence - Precedence index (lower = higher priority)
+   */
+  constructor(data) {
+    this.id = data.id;
+    this.level = data.level;
+    this.category = data.category;
+    this.appliesTo = data.appliesTo;
+    this.rule = data.rule;
+    this.rationale = data.rationale;
+    this.source = data.source;
+    this.conflicts = []; // Populated during conflict resolution
+  }
+
+  /**
+   * Extract category from rule ID
+   * @param {string} ruleId - Rule ID (e.g., "doc-structure-001")
+   * @returns {string} Category (e.g., "doc-structure")
+   */
+  static extractCategory(ruleId) {
+    const match = ruleId.match(/^([a-z0-9-]+)-\d+$/);
+    return match ? match[1] : "unknown";
+  }
+
+  /**
+   * Validate rule level
+   * @param {string} level - Level to validate
+   * @returns {boolean} True if valid
+   */
+  static isValidLevel(level) {
+    return ["must", "should", "prefer", "avoid"].includes(level);
+  }
+
+  /**
+   * Validate rule ID format
+   * @param {string} ruleId - Rule ID to validate
+   * @returns {boolean} True if valid
+   */
+  static isValidId(ruleId) {
+    return /^[a-z0-9-]+$/.test(ruleId);
+  }
+
+  /**
+   * Check if this rule applies to the given scope
+   * @param {string|string[]} scope - Scope to check
+   * @returns {boolean} True if rule applies
+   */
+  appliesToScope(scope) {
+    if (this.appliesTo.includes("all")) return true;
+    const scopes = Array.isArray(scope) ? scope : [scope];
+    return scopes.some(s => this.appliesTo.includes(s));
+  }
+}
+