@zebralabs/context-cli 0.1.3 → 0.1.5

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
+    };
+  }
+}
+

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");
+  }
+}
+