aios-core 2.1.0

package/.aios-core/infrastructure/scripts/source-tree-guardian/manifest-generator.js

@@ -0,0 +1,410 @@
+/**
+ * Source-Tree Guardian - Manifest Generator
+ *
+ * Generates a JSON manifest of the current codebase structure
+ * and compares it against the official source-tree.md.
+ *
+ * @module source-tree-guardian/manifest-generator
+ * @version 1.0.0
+ * @story 6.8
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const { glob } = require('glob');
+
+/**
+ * Default exclusion patterns for scanning
+ */
+const DEFAULT_EXCLUSIONS = [
+  'node_modules/**',
+  '.git/**',
+  'dist/**',
+  'build/**',
+  'coverage/**',
+  '.cache/**',
+  '*.log',
+  '*.tmp',
+  '.DS_Store',
+  'Thumbs.db',
+  'outputs/**',
+  '.ai/**',
+];
+
+/**
+ * File category definitions
+ */
+const FILE_CATEGORIES = {
+  agent: {
+    pattern: '.aios-core/development/agents/**/*.md',
+    description: 'Agent definitions',
+  },
+  task: {
+    pattern: '.aios-core/development/tasks/**/*.md',
+    description: 'Task workflows',
+  },
+  template: {
+    pattern: '.aios-core/product/templates/**/*',
+    description: 'Document templates',
+  },
+  checklist: {
+    pattern: '.aios-core/product/checklists/**/*.md',
+    description: 'Validation checklists',
+  },
+  script: {
+    pattern: '.aios-core/infrastructure/scripts/**/*.js',
+    description: 'Infrastructure scripts',
+  },
+  tool: {
+    pattern: '.aios-core/infrastructure/tools/**/*.yaml',
+    description: 'Tool integrations',
+  },
+  utility: {
+    pattern: '.aios-core/core/utils/**/*.js',
+    description: 'Utility functions',
+  },
+  story: {
+    pattern: 'docs/stories/**/*.md',
+    description: 'Development stories',
+  },
+  guide: {
+    pattern: 'docs/guides/**/*.md',
+    description: 'User guides',
+  },
+  architecture: {
+    pattern: 'docs/architecture/**/*.md',
+    description: 'Architecture documentation',
+  },
+  test: {
+    pattern: 'tests/**/*.test.js',
+    description: 'Test files',
+  },
+};
+
+/**
+ * Generates a file structure tree
+ * @param {string} dir - Directory to scan
+ * @param {string} projectRoot - Project root for relative paths
+ * @param {number} depth - Current depth level
+ * @param {number} maxDepth - Maximum depth to scan
+ * @returns {Promise<Object>} Directory tree structure
+ */
+async function generateTree(dir, projectRoot, depth = 0, maxDepth = 10) {
+  if (depth > maxDepth) {
+    return { truncated: true };
+  }
+
+  const result = {
+    name: path.basename(dir),
+    type: 'directory',
+    path: path.relative(projectRoot, dir).replace(/\\/g, '/') || '.',
+    children: [],
+  };
+
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      // Skip excluded directories
+      if (DEFAULT_EXCLUSIONS.some((ex) => entry.name === ex.split('/')[0])) {
+        continue;
+      }
+
+      const entryPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        const subtree = await generateTree(entryPath, projectRoot, depth + 1, maxDepth);
+        result.children.push(subtree);
+      } else if (entry.isFile()) {
+        result.children.push({
+          name: entry.name,
+          type: 'file',
+          path: path.relative(projectRoot, entryPath).replace(/\\/g, '/'),
+          extension: path.extname(entry.name),
+        });
+      }
+    }
+
+    // Sort: directories first, then files, alphabetically
+    result.children.sort((a, b) => {
+      if (a.type !== b.type) {
+        return a.type === 'directory' ? -1 : 1;
+      }
+      return a.name.localeCompare(b.name);
+    });
+  } catch (error) {
+    result.error = error.message;
+  }
+
+  return result;
+}
+
+/**
+ * Counts files by category
+ * @param {string} projectRoot - Project root directory
+ * @returns {Promise<Object>} File counts by category
+ */
+async function countFilesByCategory(projectRoot) {
+  const counts = {};
+
+  for (const [category, config] of Object.entries(FILE_CATEGORIES)) {
+    try {
+      const files = await glob(config.pattern, {
+        cwd: projectRoot,
+        nodir: true,
+      });
+      counts[category] = {
+        count: files.length,
+        description: config.description,
+        files: files.slice(0, 10), // Sample of first 10 files
+      };
+    } catch (error) {
+      counts[category] = {
+        count: 0,
+        description: config.description,
+        error: error.message,
+      };
+    }
+  }
+
+  return counts;
+}
+
+/**
+ * Gets file statistics
+ * @param {string} filePath - Path to the file
+ * @returns {Promise<Object>} File statistics
+ */
+async function getFileStats(filePath) {
+  try {
+    const stats = await fs.stat(filePath);
+    return {
+      size: stats.size,
+      created: stats.birthtime.toISOString(),
+      modified: stats.mtime.toISOString(),
+    };
+  } catch (error) {
+    return { error: error.message };
+  }
+}
+
+/**
+ * Main ManifestGenerator class
+ */
+class ManifestGenerator {
+  /**
+   * Creates a new ManifestGenerator instance
+   * @param {Object} options - Generator options
+   * @param {string} options.projectRoot - Project root directory
+   * @param {string} options.outputPath - Path for manifest output
+   * @param {number} options.maxDepth - Maximum tree depth
+   */
+  constructor(options = {}) {
+    this.projectRoot = options.projectRoot || process.cwd();
+    this.outputPath = options.outputPath || path.join(
+      this.projectRoot,
+      'docs',
+      'architecture',
+      'source-tree-manifest.json'
+    );
+    this.maxDepth = options.maxDepth || 10;
+  }
+
+  /**
+   * Generates the complete manifest
+   * @returns {Promise<Object>} Generated manifest
+   */
+  async generate() {
+    const startTime = Date.now();
+
+    const manifest = {
+      version: '1.0.0',
+      generated: new Date().toISOString(),
+      generator: 'source-tree-guardian',
+      story: '6.8',
+      projectRoot: this.projectRoot,
+      summary: {
+        totalFiles: 0,
+        totalDirectories: 0,
+        categories: {},
+      },
+      tree: null,
+      categories: {},
+      duration: 0,
+    };
+
+    // Generate tree structure
+    manifest.tree = await generateTree(this.projectRoot, this.projectRoot, 0, this.maxDepth);
+
+    // Count total files and directories
+    const countItems = (node) => {
+      if (node.type === 'directory') {
+        manifest.summary.totalDirectories++;
+        if (node.children) {
+          node.children.forEach(countItems);
+        }
+      } else if (node.type === 'file') {
+        manifest.summary.totalFiles++;
+      }
+    };
+    countItems(manifest.tree);
+
+    // Count by category
+    manifest.categories = await countFilesByCategory(this.projectRoot);
+    manifest.summary.categories = Object.fromEntries(
+      Object.entries(manifest.categories).map(([k, v]) => [k, v.count])
+    );
+
+    manifest.duration = Date.now() - startTime;
+
+    return manifest;
+  }
+
+  /**
+   * Saves the manifest to a file
+   * @param {Object} manifest - The manifest to save
+   * @returns {Promise<string>} Path to saved manifest
+   */
+  async save(manifest) {
+    const dir = path.dirname(this.outputPath);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(this.outputPath, JSON.stringify(manifest, null, 2));
+    return this.outputPath;
+  }
+
+  /**
+   * Loads an existing manifest
+   * @param {string} manifestPath - Path to the manifest file
+   * @returns {Promise<Object>} Loaded manifest
+   */
+  async load(manifestPath) {
+    const content = await fs.readFile(manifestPath || this.outputPath, 'utf8');
+    return JSON.parse(content);
+  }
+
+  /**
+   * Compares two manifests and returns differences
+   * @param {Object} oldManifest - Previous manifest
+   * @param {Object} newManifest - Current manifest
+   * @returns {Object} Comparison results
+   */
+  compare(oldManifest, newManifest) {
+    const diff = {
+      added: [],
+      removed: [],
+      modified: [],
+      summary: {
+        filesAdded: 0,
+        filesRemoved: 0,
+        categoriesChanged: {},
+      },
+    };
+
+    // Extract all file paths from tree
+    const extractPaths = (node, paths = new Set()) => {
+      if (node.type === 'file') {
+        paths.add(node.path);
+      } else if (node.children) {
+        node.children.forEach((child) => extractPaths(child, paths));
+      }
+      return paths;
+    };
+
+    const oldPaths = extractPaths(oldManifest.tree);
+    const newPaths = extractPaths(newManifest.tree);
+
+    // Find added files
+    for (const p of newPaths) {
+      if (!oldPaths.has(p)) {
+        diff.added.push(p);
+        diff.summary.filesAdded++;
+      }
+    }
+
+    // Find removed files
+    for (const p of oldPaths) {
+      if (!newPaths.has(p)) {
+        diff.removed.push(p);
+        diff.summary.filesRemoved++;
+      }
+    }
+
+    // Compare categories
+    for (const [category, oldData] of Object.entries(oldManifest.categories)) {
+      const newData = newManifest.categories[category];
+      if (newData && newData.count !== oldData.count) {
+        diff.summary.categoriesChanged[category] = {
+          old: oldData.count,
+          new: newData.count,
+          delta: newData.count - oldData.count,
+        };
+      }
+    }
+
+    return diff;
+  }
+
+  /**
+   * Formats a diff report for console output
+   * @param {Object} diff - Comparison diff
+   * @returns {string} Formatted report
+   */
+  formatDiffReport(diff) {
+    const lines = [];
+
+    lines.push('╔═══════════════════════════════════════════════════════════════════════╗');
+    lines.push('║               SOURCE-TREE MANIFEST COMPARISON                         ║');
+    lines.push('╠═══════════════════════════════════════════════════════════════════════╣');
+    lines.push(`║  Files Added: ${String(diff.summary.filesAdded).padEnd(58)}║`);
+    lines.push(`║  Files Removed: ${String(diff.summary.filesRemoved).padEnd(56)}║`);
+    lines.push('║                                                                       ║');
+
+    if (diff.added.length > 0) {
+      lines.push('╠═══════════════════════════════════════════════════════════════════════╣');
+      lines.push('║  ADDED FILES                                                          ║');
+      lines.push('╠═══════════════════════════════════════════════════════════════════════╣');
+      for (const file of diff.added.slice(0, 20)) {
+        lines.push(`║  + ${file.substring(0, 69).padEnd(69)}║`);
+      }
+      if (diff.added.length > 20) {
+        lines.push(`║  ... and ${diff.added.length - 20} more files                                          ║`);
+      }
+    }
+
+    if (diff.removed.length > 0) {
+      lines.push('╠═══════════════════════════════════════════════════════════════════════╣');
+      lines.push('║  REMOVED FILES                                                        ║');
+      lines.push('╠═══════════════════════════════════════════════════════════════════════╣');
+      for (const file of diff.removed.slice(0, 20)) {
+        lines.push(`║  - ${file.substring(0, 69).padEnd(69)}║`);
+      }
+      if (diff.removed.length > 20) {
+        lines.push(`║  ... and ${diff.removed.length - 20} more files                                          ║`);
+      }
+    }
+
+    if (Object.keys(diff.summary.categoriesChanged).length > 0) {
+      lines.push('╠═══════════════════════════════════════════════════════════════════════╣');
+      lines.push('║  CATEGORY CHANGES                                                     ║');
+      lines.push('╠═══════════════════════════════════════════════════════════════════════╣');
+      for (const [category, change] of Object.entries(diff.summary.categoriesChanged)) {
+        const delta = change.delta > 0 ? `+${change.delta}` : String(change.delta);
+        lines.push(`║  ${category}: ${change.old} → ${change.new} (${delta})`.padEnd(72) + '║');
+      }
+    }
+
+    lines.push('╚═══════════════════════════════════════════════════════════════════════╝');
+
+    return lines.join('\n');
+  }
+}
+
+// Export for use as module
+module.exports = {
+  ManifestGenerator,
+  generateTree,
+  countFilesByCategory,
+  getFileStats,
+  FILE_CATEGORIES,
+  DEFAULT_EXCLUSIONS,
+};

package/.aios-core/infrastructure/scripts/source-tree-guardian/rules/naming-rules.yaml

@@ -0,0 +1,285 @@
+# Naming Convention Rules for AIOS Source Tree
+# Version: 1.0.0
+# Last Updated: 2025-12-14
+# Story: 6.8 - Source-Tree Guardian
+
+version: "1.0"
+last_updated: "2025-12-14"
+
+# =============================================================================
+# NAMING CONVENTIONS
+# Defines how files and directories should be named
+# =============================================================================
+
+conventions:
+  # ---------------------------------------------------------------------------
+  # KEBAB-CASE (default for most files)
+  # ---------------------------------------------------------------------------
+  kebab-case:
+    pattern: "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
+    description: "Lowercase letters separated by hyphens"
+    examples:
+      valid:
+        - "agent-executor"
+        - "task-runner"
+        - "greeting-builder"
+        - "source-tree-guardian"
+      invalid:
+        - "AgentExecutor"
+        - "task_runner"
+        - "greetingBuilder"
+        - "SOURCE-TREE"
+
+  # ---------------------------------------------------------------------------
+  # CAMEL-CASE (for variables/functions in code)
+  # ---------------------------------------------------------------------------
+  camelCase:
+    pattern: "^[a-z][a-zA-Z0-9]*$"
+    description: "First letter lowercase, subsequent words capitalized"
+    examples:
+      valid:
+        - "agentExecutor"
+        - "taskRunner"
+        - "greetingBuilder"
+      invalid:
+        - "AgentExecutor"
+        - "agent-executor"
+        - "agent_executor"
+
+  # ---------------------------------------------------------------------------
+  # PASCAL-CASE (for classes)
+  # ---------------------------------------------------------------------------
+  PascalCase:
+    pattern: "^[A-Z][a-zA-Z0-9]*$"
+    description: "Each word starts with uppercase"
+    examples:
+      valid:
+        - "AgentExecutor"
+        - "TaskRunner"
+        - "GreetingBuilder"
+      invalid:
+        - "agentExecutor"
+        - "agent-executor"
+        - "AGENT_EXECUTOR"
+
+  # ---------------------------------------------------------------------------
+  # SCREAMING-SNAKE-CASE (for constants)
+  # ---------------------------------------------------------------------------
+  SCREAMING_SNAKE_CASE:
+    pattern: "^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$"
+    description: "Uppercase letters separated by underscores"
+    examples:
+      valid:
+        - "MAX_RETRIES"
+        - "DEFAULT_TIMEOUT"
+        - "API_BASE_URL"
+      invalid:
+        - "maxRetries"
+        - "default-timeout"
+        - "ApiBaseUrl"
+
+# =============================================================================
+# FILE TYPE RULES
+# Maps file types to their required naming conventions
+# =============================================================================
+
+file_rules:
+  # JavaScript files
+  - extension: ".js"
+    convention: kebab-case
+    exceptions:
+      - pattern: "*.config.js"
+        allowed: true
+      - pattern: "*.test.js"
+        allowed: true
+      - pattern: "index.js"
+        allowed: true
+
+  # TypeScript files
+  - extension: ".ts"
+    convention: kebab-case
+    exceptions:
+      - pattern: "*.config.ts"
+        allowed: true
+      - pattern: "*.test.ts"
+        allowed: true
+      - pattern: "*.d.ts"
+        allowed: true
+      - pattern: "index.ts"
+        allowed: true
+
+  # Markdown files
+  - extension: ".md"
+    convention: kebab-case
+    exceptions:
+      - pattern: "README.md"
+        allowed: true
+      - pattern: "CHANGELOG.md"
+        allowed: true
+      - pattern: "CLAUDE.md"
+        allowed: true
+      - pattern: "LICENSE.md"
+        allowed: true
+      - pattern: "CONTRIBUTING.md"
+        allowed: true
+      - pattern: "STORY-BACKLOG.md"
+        allowed: true
+
+  # YAML files
+  - extension: ".yaml"
+    convention: kebab-case
+    exceptions:
+      - pattern: "*.config.yaml"
+        allowed: true
+
+  - extension: ".yml"
+    convention: kebab-case
+
+  # JSON files
+  - extension: ".json"
+    convention: kebab-case
+    exceptions:
+      - pattern: "package.json"
+        allowed: true
+      - pattern: "package-lock.json"
+        allowed: true
+      - pattern: "tsconfig.json"
+        allowed: true
+      - pattern: ".eslintrc.json"
+        allowed: true
+
+# =============================================================================
+# DIRECTORY RULES
+# Naming conventions for directories
+# =============================================================================
+
+directory_rules:
+  - convention: kebab-case
+    exceptions:
+      - pattern: ".aios-core"
+        allowed: true
+        reason: "Framework standard directory"
+      - pattern: ".claude"
+        allowed: true
+        reason: "IDE configuration directory"
+      - pattern: ".cursor"
+        allowed: true
+        reason: "IDE configuration directory"
+      - pattern: ".vscode"
+        allowed: true
+        reason: "IDE configuration directory"
+      - pattern: ".husky"
+        allowed: true
+        reason: "Git hooks directory"
+      - pattern: ".git"
+        allowed: true
+        reason: "Git repository directory"
+      - pattern: ".ai"
+        allowed: true
+        reason: "AI artifacts directory"
+      - pattern: "node_modules"
+        allowed: true
+        reason: "npm packages directory"
+
+# =============================================================================
+# SPECIAL PATTERNS
+# Files that follow specific naming patterns
+# =============================================================================
+
+special_patterns:
+  # Story files
+  - name: story
+    pattern: "^story-[0-9]+\\.[0-9]+(\\.[0-9]+)*(-[a-z-]+)?\\.md$"
+    description: "Story files follow story-{id}.md or story-{id}-{slug}.md pattern"
+    examples:
+      valid:
+        - "story-6.8.md"
+        - "story-6.8-source-tree-guardian.md"
+        - "story-6.1.2.5.md"
+      invalid:
+        - "Story-6.8.md"
+        - "story_6.8.md"
+        - "6.8-story.md"
+
+  # Epic files
+  - name: epic
+    pattern: "^epic-[0-9]+(\\.[0-9]+)*-[a-z-]+\\.md$"
+    description: "Epic files follow epic-{number}-{name}.md pattern"
+    examples:
+      valid:
+        - "epic-6.1-agent-identity-system.md"
+        - "epic-7-deployment-automation.md"
+      invalid:
+        - "Epic-6.1.md"
+        - "epic_6.1.md"
+
+  # Decision files (ADRs)
+  - name: decision
+    pattern: "^decision-[0-9]+-[a-z-]+(-FINAL)?\\.md$"
+    description: "Decision files follow decision-{number}-{name}.md pattern"
+    examples:
+      valid:
+        - "decision-005-repository-restructuring.md"
+        - "decision-005-repository-restructuring-FINAL.md"
+      invalid:
+        - "Decision-005.md"
+        - "decision_005.md"
+
+  # Template files
+  - name: template
+    pattern: "^[a-z-]+-tmpl\\.(yaml|md)$"
+    description: "Template files follow {name}-tmpl.{ext} pattern"
+    examples:
+      valid:
+        - "story-tmpl.yaml"
+        - "prd-tmpl.yaml"
+        - "epic-tmpl.md"
+      invalid:
+        - "story-template.yaml"
+        - "Story-tmpl.yaml"
+
+  # Checklist files
+  - name: checklist
+    pattern: "^[a-z-]+-checklist\\.md$"
+    description: "Checklist files follow {name}-checklist.md pattern"
+    examples:
+      valid:
+        - "po-master-checklist.md"
+        - "story-draft-checklist.md"
+      invalid:
+        - "po-master.checklist.md"
+        - "POChecklist.md"
+
+  # Test files
+  - name: test
+    pattern: "^[a-z-]+\\.test\\.(js|ts)$"
+    description: "Test files follow {name}.test.{ext} pattern"
+    examples:
+      valid:
+        - "validator.test.js"
+        - "manifest-generator.test.js"
+      invalid:
+        - "ValidatorTest.js"
+        - "validator_test.js"
+
+# =============================================================================
+# VALIDATION SETTINGS
+# =============================================================================
+
+validation:
+  strict_mode: false  # If true, all files must match a rule
+  case_sensitive: true  # Enforce exact case matching
+  allow_numbers: true  # Allow numbers in names (after first character)
+  max_length: 100  # Maximum filename length (excluding extension)
+  min_length: 2  # Minimum filename length (excluding extension)
+
+# =============================================================================
+# SEVERITY LEVELS
+# =============================================================================
+
+severity:
+  wrong_convention: warning
+  invalid_characters: error
+  too_long: warning
+  too_short: error
+  special_pattern_mismatch: error