@zebralabs/context-cli 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zebralabs/context-cli",
-    "version": "0.1.3",
+    "version": "0.1.4",
     "description": "Context-as-Code CLI (help/list/compile/validate)",
     "license": "MIT",
     "type": "module",

package/src/application/compile/compile-context.js

@@ -0,0 +1,119 @@
+import { Stage1Discovery } from "./stage1-discovery.js";
+import { Stage2Extraction } from "./stage2-extraction.js";
+import { Stage4Consolidation } from "./stage4-consolidation.js";
+import { Stage5Assets } from "./stage5-assets.js";
+import { Stage6Validation } from "./stage6-validation.js";
+import YAML from "yaml";
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Main compilation orchestrator
+ * Coordinates all compilation stages
+ */
+export class CompileContext {
+  constructor() {
+    this.stage1 = new Stage1Discovery();
+    this.stage2 = new Stage2Extraction();
+    this.stage4 = new Stage4Consolidation();
+    this.stage5 = new Stage5Assets();
+    this.stage6 = new Stage6Validation();
+  }
+
+  /**
+   * Compile context for a specific pack
+   * @param {string} repoRoot - Repository root
+   * @param {string} packId - Pack ID to compile
+   * @param {string} outputPath - Output path (defaults to pack directory)
+   * @returns {Object} Compilation result
+   */
+  async compilePack(repoRoot, packId, outputPath = null) {
+    // Try both locations for context.yaml
+    const installedPath = path.join(repoRoot, "docs", "practices-and-standards", "context.yaml");
+    const sourcePath = path.join(repoRoot, "practices-and-standards", "context.yaml");
+    
+    let contextPath;
+    if (fs.existsSync(installedPath)) {
+      contextPath = installedPath;
+    } else if (fs.existsSync(sourcePath)) {
+      contextPath = sourcePath;
+    } else {
+      throw new Error(`context.yaml not found. Checked:\n  - ${installedPath}\n  - ${sourcePath}`);
+    }
+
+    const contextYaml = YAML.parse(fs.readFileSync(contextPath, "utf8"));
+
+    // Find the pack in installed packs
+    const pack = (contextYaml.installed_packs || []).find(p => p.id === packId);
+    if (!pack) {
+      throw new Error(`Pack ${packId} not found in context.yaml`);
+    }
+
+    // Determine output path
+    if (!outputPath) {
+      // Output to pack directory
+      const packDir = path.dirname(path.join(repoRoot, pack.manifest));
+      outputPath = packDir;
+    }
+
+    const stageReports = {};
+
+    // Stage 1: Discovery
+    console.log("Stage 1: Discovery & Collection...");
+    const discovery = this.stage1.execute(repoRoot, contextYaml);
+    
+    // Filter to only files from the specified pack
+    const packSourceFiles = discovery.sourceFiles.filter(f => f.packId === packId);
+    
+    console.log(`  Found ${packSourceFiles.length} source files`);
+    stageReports.stage1 = discovery;
+
+    // Stage 2: Extraction
+    console.log("Stage 2: Rule Extraction & Parsing...");
+    const extraction = this.stage2.execute(packSourceFiles);
+    
+    console.log(`  Extracted ${extraction.report.rulesExtracted} rules`);
+    console.log(`  Extracted ${extraction.report.preferencesExtracted} preferences`);
+    console.log(`  Extracted ${extraction.report.scopesExtracted} scopes`);
+
+    if (extraction.report.errors.length > 0) {
+      console.warn(`  Errors: ${extraction.report.errors.length}`);
+      extraction.report.errors.forEach(e => {
+        console.warn(`    - ${e.file}: ${e.error}`);
+      });
+    }
+    stageReports.stage2 = extraction.report;
+
+    // Stage 4: Consolidation
+    console.log("Stage 4: Consolidation & Standard Generation...");
+    const consolidation = this.stage4.execute(extraction.compilation, outputPath);
+    console.log(`  Generated ${consolidation.filesGenerated.length} consolidated files`);
+
+    // Stage 5: Asset Generation
+    console.log("Stage 5: Integration Asset Generation...");
+    const assets = await this.stage5.execute(extraction.compilation, packSourceFiles, outputPath);
+    console.log(`  Generated Cursor rules: ${assets.results.cursorRules.filesGenerated.length} files`);
+    if (assets.skillsExtracted > 0) {
+      console.log(`  Generated Cursor skills: ${assets.results.cursorSkills.filesGenerated.length} files`);
+    }
+    console.log(`  Generated Claude.md`);
+
+    // Stage 6: Validation & Reporting
+    console.log("Stage 6: Validation & Reporting...");
+    const validation = this.stage6.execute(extraction.compilation, stageReports, outputPath);
+    console.log(`  Validation: ${validation.validation.rulesValid ? "✅ Passed" : "❌ Failed"}`);
+    console.log(`  Generated ${validation.reportsGenerated.length} reports`);
+
+    return {
+      compilation: extraction.compilation,
+      outputPath,
+      stageReports: {
+        ...stageReports,
+        stage4: consolidation,
+        stage5: assets,
+        stage6: validation
+      }
+    };
+  }
+}
+

package/src/application/compile/stage1-discovery.js

@@ -0,0 +1,125 @@
+import path from "node:path";
+import fs from "node:fs";
+import YAML from "yaml";
+import { FileReader } from "../../infrastructure/file-system/file-reader.js";
+
+/**
+ * Stage 1: Discovery & Collection
+ * Gathers all sources of knowledge (packs + custom docs)
+ */
+export class Stage1Discovery {
+  constructor() {
+    this.fileReader = new FileReader();
+  }
+
+  /**
+   * Discover and collect source files
+   * @param {string} repoRoot - Repository root directory
+   * @param {Object} contextYaml - Parsed context.yaml
+   * @returns {Object} Discovery result with source files and metadata
+   */
+  execute(repoRoot, contextYaml) {
+    const sourceFiles = [];
+    const packs = [];
+    const precedence = contextYaml.precedence || [];
+    
+    // Order packs by precedence
+    const installedPacks = this.orderPacksByPrecedence(
+      contextYaml.installed_packs || [],
+      precedence
+    );
+
+    // Process each pack
+    for (let i = 0; i < installedPacks.length; i++) {
+      const pack = installedPacks[i];
+      const precedenceIndex = precedence.indexOf(pack.id);
+      const finalPrecedence = precedenceIndex !== -1 ? precedenceIndex : 1000 + i;
+
+      // Load pack manifest
+      const manifestPath = path.join(repoRoot, pack.manifest);
+      if (!this.fileReader.exists(manifestPath)) {
+        console.warn(`Pack manifest not found: ${manifestPath}`);
+        continue;
+      }
+
+      // Parse pack.yaml to get contributes.roots
+      const packManifest = YAML.parse(fs.readFileSync(manifestPath, "utf8"));
+      const packId = pack.id;
+      const packVersion = pack.version;
+      const roots = packManifest?.contributes?.roots || [];
+
+      packs.push({
+        id: packId,
+        version: packVersion,
+        precedence: finalPrecedence
+      });
+
+      // Collect markdown files from each root
+      for (const root of roots) {
+        // Try installed location first (docs/practices-and-standards/...)
+        let rootPath = path.join(repoRoot, root);
+        
+        // If not found and root starts with "docs/", try source location
+        if (!this.fileReader.exists(rootPath) && root.startsWith("docs/")) {
+          const sourceRoot = root.replace(/^docs\//, "");
+          rootPath = path.join(repoRoot, sourceRoot);
+        }
+        
+        if (!this.fileReader.exists(rootPath)) {
+          console.warn(`Pack ${packId} root not found: ${root} (tried: ${path.join(repoRoot, root)} and ${rootPath})`);
+          continue;
+        }
+
+        const markdownFiles = this.fileReader.listMarkdownFiles(rootPath);
+
+        for (const filePath of markdownFiles) {
+          const relativePath = path.relative(repoRoot, filePath).replace(/\\/g, "/");
+          
+          sourceFiles.push({
+            path: relativePath,
+            absolutePath: filePath,
+            packId: packId,
+            packVersion: packVersion,
+            precedence: finalPrecedence,
+            isCustom: false
+          });
+        }
+      }
+    }
+
+    return {
+      sourceFiles,
+      packs,
+      precedenceOrder: precedence
+    };
+  }
+
+  /**
+   * Order packs by precedence
+   * @param {Object[]} installedPacks - Installed packs
+   * @param {string[]} precedence - Precedence order
+   * @returns {Object[]} Ordered packs
+   */
+  orderPacksByPrecedence(installedPacks, precedence) {
+    const ordered = [];
+    const unordered = [];
+
+    // Add packs in precedence order
+    for (const packId of precedence) {
+      const pack = installedPacks.find(p => p.id === packId);
+      if (pack) {
+        ordered.push(pack);
+      }
+    }
+
+    // Add remaining packs
+    for (const pack of installedPacks) {
+      if (!precedence.includes(pack.id)) {
+        unordered.push(pack);
+      }
+    }
+
+    return [...ordered, ...unordered];
+  }
+}
+

package/src/application/compile/stage2-extraction.js

@@ -0,0 +1,97 @@
+import { FileReader } from "../../infrastructure/file-system/file-reader.js";
+import { RuleExtractor } from "../../infrastructure/parsing/rule-extractor.js";
+import { Compilation } from "../../domain/compilation.js";
+
+/**
+ * Stage 2: Rule Extraction & Parsing
+ * Extracts structured rules from markdown documents
+ */
+export class Stage2Extraction {
+  constructor() {
+    this.fileReader = new FileReader();
+    this.ruleExtractor = new RuleExtractor();
+  }
+
+  /**
+   * Extract rules from source files
+   * @param {Object[]} sourceFiles - Array of source file metadata
+   * @returns {Object} Extraction result with compilation and report
+   */
+  execute(sourceFiles) {
+    const compilation = new Compilation();
+    const report = {
+      filesProcessed: 0,
+      rulesExtracted: 0,
+      preferencesExtracted: 0,
+      scopesExtracted: 0,
+      errors: [],
+      warnings: []
+    };
+
+    for (const sourceFile of sourceFiles) {
+      try {
+        report.filesProcessed++;
+
+        const content = this.fileReader.readFile(sourceFile.absolutePath);
+        
+        // Extract rules
+        const rules = this.ruleExtractor.extractRules(content, {
+          pack: sourceFile.packId,
+          packVersion: sourceFile.packVersion,
+          file: sourceFile.path,
+          precedence: sourceFile.precedence
+        });
+
+        for (const rule of rules) {
+          try {
+            compilation.addRule(rule);
+            report.rulesExtracted++;
+          } catch (error) {
+            report.errors.push({
+              file: sourceFile.path,
+              error: error.message
+            });
+          }
+        }
+
+        // Extract preferences
+        const preferences = this.ruleExtractor.extractPreferences(content, {
+          pack: sourceFile.packId,
+          packVersion: sourceFile.packVersion,
+          file: sourceFile.path,
+          precedence: sourceFile.precedence
+        });
+
+        for (const preference of preferences) {
+          compilation.addPreference(preference);
+          report.preferencesExtracted++;
+        }
+
+        // Extract scope
+        const scope = this.ruleExtractor.extractScope(content, {
+          pack: sourceFile.packId,
+          packVersion: sourceFile.packVersion,
+          file: sourceFile.path,
+          precedence: sourceFile.precedence
+        });
+
+        if (scope) {
+          compilation.addScope(scope);
+          report.scopesExtracted++;
+        }
+
+      } catch (error) {
+        report.errors.push({
+          file: sourceFile.path,
+          error: error.message
+        });
+      }
+    }
+
+    return {
+      compilation,
+      report
+    };
+  }
+}
+

package/src/application/compile/stage4-consolidation.js

@@ -0,0 +1,235 @@
+import { FileWriter } from "../../infrastructure/file-system/file-writer.js";
+import path from "node:path";
+
+/**
+ * Stage 4: Consolidation & Standard Generation
+ * Creates a single, coherent, human-readable standard document
+ */
+export class Stage4Consolidation {
+  constructor() {
+    this.fileWriter = new FileWriter();
+  }
+
+  /**
+   * Generate consolidated outputs
+   * @param {Compilation} compilation - The compilation with extracted rules
+   * @param {string} outputDir - Output directory
+   * @returns {Object} Consolidation result
+   */
+  execute(compilation, outputDir) {
+    const consolidatedDir = outputDir;
+
+    // Generate consolidated standard
+    const consolidatedStandard = this.generateConsolidatedStandard(compilation);
+    this.fileWriter.writeFile(
+      path.join(consolidatedDir, "CONSOLIDATED-STANDARDS.md"),
+      consolidatedStandard
+    );
+
+    // Generate rule index
+    const rulesIndex = this.generateRulesIndex(compilation);
+    this.fileWriter.writeFile(
+      path.join(consolidatedDir, "RULES-INDEX.md"),
+      rulesIndex
+    );
+
+    // Generate rules by scope
+    const rulesByScope = this.generateRulesByScope(compilation);
+    this.fileWriter.writeFile(
+      path.join(consolidatedDir, "RULES-BY-SCOPE.md"),
+      rulesByScope
+    );
+
+    // Generate JSON outputs
+    this.fileWriter.writeJson(
+      path.join(consolidatedDir, "rules.json"),
+      compilation.rules.map(r => ({
+        id: r.id,
+        level: r.level,
+        category: r.category,
+        appliesTo: r.appliesTo,
+        rule: r.rule,
+        rationale: r.rationale,
+        source: r.source
+      }))
+    );
+
+    this.fileWriter.writeJson(
+      path.join(consolidatedDir, "preferences.json"),
+      compilation.preferences.map(p => ({
+        name: p.name,
+        description: p.description,
+        source: p.source
+      }))
+    );
+
+    this.fileWriter.writeJson(
+      path.join(consolidatedDir, "metadata.json"),
+      {
+        ...compilation.metadata,
+        rulesCount: compilation.rules.length,
+        preferencesCount: compilation.preferences.length,
+        scopesCount: compilation.scopes.length,
+        categories: compilation.getCategories()
+      }
+    );
+
+    return {
+      outputDir: consolidatedDir,
+      filesGenerated: [
+        "CONSOLIDATED-STANDARDS.md",
+        "RULES-INDEX.md",
+        "RULES-BY-SCOPE.md",
+        "rules.json",
+        "preferences.json",
+        "metadata.json"
+      ]
+    };
+  }
+
+  /**
+   * Generate consolidated standard markdown
+   * @param {Compilation} compilation - Compilation object
+   * @returns {string} Markdown content
+   */
+  generateConsolidatedStandard(compilation) {
+    const lines = [];
+    lines.push("# Consolidated Standards");
+    lines.push("");
+    lines.push(`Generated: ${compilation.metadata.timestamp}`);
+    lines.push(`Total Rules: ${compilation.rules.length}`);
+    lines.push(`Total Preferences: ${compilation.preferences.length}`);
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+
+    // Group by category
+    const categories = compilation.getCategories();
+    for (const category of categories) {
+      lines.push(`## ${category}`);
+      lines.push("");
+
+      const rules = compilation.getRulesByCategory(category);
+      // Sort by level, then by ID
+      const levelOrder = { must: 0, should: 1, prefer: 2, avoid: 3 };
+      rules.sort((a, b) => {
+        const levelDiff = levelOrder[a.level] - levelOrder[b.level];
+        if (levelDiff !== 0) return levelDiff;
+        return a.id.localeCompare(b.id);
+      });
+
+      for (const rule of rules) {
+        lines.push(`### ${rule.id}: ${this.extractTitle(rule.rule)}`);
+        lines.push("");
+        lines.push(`- **Level:** ${rule.level}`);
+        lines.push(`- **Applies to:** ${rule.appliesTo.join(", ")}`);
+        lines.push(`- **Rule:** ${rule.rule}`);
+        if (rule.rationale) {
+          lines.push(`- **Rationale:** ${rule.rationale}`);
+        }
+        lines.push(`- **Source:** [${rule.source.pack}@${rule.source.packVersion}](${rule.source.file})`);
+        lines.push("");
+      }
+    }
+
+    // Add preferences section
+    if (compilation.preferences.length > 0) {
+      lines.push("---");
+      lines.push("");
+      lines.push("## Preferences");
+      lines.push("");
+
+      for (const pref of compilation.preferences) {
+        lines.push(`- **${pref.name}**`);
+        if (pref.description) {
+          lines.push(`  - ${pref.description}`);
+        }
+        lines.push(`  - Source: [${pref.source.pack}@${pref.source.packVersion}](${pref.source.file})`);
+        lines.push("");
+      }
+    }
+
+    return lines.join("\n");
+  }
+
+  /**
+   * Generate rules index
+   * @param {Compilation} compilation - Compilation object
+   * @returns {string} Markdown content
+   */
+  generateRulesIndex(compilation) {
+    const lines = [];
+    lines.push("# Rules Index");
+    lines.push("");
+    lines.push("Quick reference of all rules.");
+    lines.push("");
+    lines.push("| ID | Level | Category | Applies To |");
+    lines.push("|----|-------|----------|------------|");
+
+    const allRules = [...compilation.rules].sort((a, b) => a.id.localeCompare(b.id));
+    for (const rule of allRules) {
+      lines.push(`| ${rule.id} | ${rule.level} | ${rule.category} | ${rule.appliesTo.join(", ")} |`);
+    }
+
+    return lines.join("\n");
+  }
+
+  /**
+   * Generate rules by scope
+   * @param {Compilation} compilation - Compilation object
+   * @returns {string} Markdown content
+   */
+  generateRulesByScope(compilation) {
+    const lines = [];
+    lines.push("# Rules by Scope");
+    lines.push("");
+    lines.push("Rules organized by what they apply to.");
+    lines.push("");
+
+    // Collect all unique scopes
+    const scopes = new Set();
+    for (const rule of compilation.rules) {
+      if (rule.appliesTo.includes("all")) {
+        scopes.add("all");
+      } else {
+        rule.appliesTo.forEach(s => scopes.add(s));
+      }
+    }
+
+    const sortedScopes = Array.from(scopes).sort();
+
+    for (const scope of sortedScopes) {
+      lines.push(`## ${scope}`);
+      lines.push("");
+
+      const applicableRules = compilation.rules.filter(r => r.appliesToScope(scope));
+      const levelOrder = { must: 0, should: 1, prefer: 2, avoid: 3 };
+      applicableRules.sort((a, b) => {
+        const levelDiff = levelOrder[a.level] - levelOrder[b.level];
+        if (levelDiff !== 0) return levelDiff;
+        return a.id.localeCompare(b.id);
+      });
+
+      for (const rule of applicableRules) {
+        lines.push(`- **${rule.id}** (${rule.level}): ${this.extractTitle(rule.rule)}`);
+      }
+
+      lines.push("");
+    }
+
+    return lines.join("\n");
+  }
+
+  /**
+   * Extract a short title from a rule statement
+   * @param {string} rule - Rule statement
+   * @returns {string} Short title
+   */
+  extractTitle(rule) {
+    // Take first sentence or first 80 characters
+    const firstSentence = rule.split(/[.!?]/)[0];
+    if (firstSentence.length <= 80) return firstSentence;
+    return rule.substring(0, 77) + "...";
+  }
+}
+

package/src/application/compile/stage5-assets.js

@@ -0,0 +1,61 @@
+import { CursorRulesGenerator } from "../../infrastructure/assets/cursor/cursor-rules-generator.js";
+import { CursorSkillsGenerator } from "../../infrastructure/assets/cursor/cursor-skills-generator.js";
+import { ClaudeGenerator } from "../../infrastructure/assets/claude/claude-generator.js";
+import { SkillExtractor } from "../../infrastructure/parsing/skill-extractor.js";
+import { FileReader } from "../../infrastructure/file-system/file-reader.js";
+
+/**
+ * Stage 5: Integration Asset Generation
+ * Generates tool-specific assets from consolidated standard
+ */
+export class Stage5Assets {
+  constructor() {
+    this.cursorRulesGenerator = new CursorRulesGenerator();
+    this.cursorSkillsGenerator = new CursorSkillsGenerator();
+    this.claudeGenerator = new ClaudeGenerator();
+    this.skillExtractor = new SkillExtractor();
+    this.fileReader = new FileReader();
+  }
+
+  /**
+   * Generate integration assets
+   * @param {Compilation} compilation - The compilation with extracted rules
+   * @param {Object[]} sourceFiles - Source files (for skill extraction)
+   * @param {string} outputPath - Output directory
+   * @returns {Object} Asset generation result
+   */
+  async execute(compilation, sourceFiles, outputPath) {
+    const results = {};
+
+    // Extract skills from source files
+    const skills = [];
+    for (const sourceFile of sourceFiles) {
+      const content = this.fileReader.readFile(sourceFile.absolutePath);
+      const extractedSkills = this.skillExtractor.extractSkills(content, {
+        pack: sourceFile.packId,
+        packVersion: sourceFile.packVersion,
+        file: sourceFile.path
+      });
+      skills.push(...extractedSkills);
+    }
+
+    // Generate Cursor rules
+    results.cursorRules = await this.cursorRulesGenerator.generate(compilation, outputPath);
+
+    // Generate Cursor skills
+    if (skills.length > 0) {
+      results.cursorSkills = await this.cursorSkillsGenerator.generate(compilation, outputPath, skills);
+    } else {
+      results.cursorSkills = { filesGenerated: [], outputDir: null };
+    }
+
+    // Generate Claude.md
+    results.claude = await this.claudeGenerator.generate(compilation, outputPath);
+
+    return {
+      results,
+      skillsExtracted: skills.length
+    };
+  }
+}
+