aios-core 2.1.0

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

@@ -0,0 +1,375 @@
+#!/usr/bin/env node
+/**
+ * Source-Tree Guardian - Main Entry Point
+ *
+ * CLI tool and module exports for source-tree validation.
+ *
+ * @module source-tree-guardian
+ * @version 1.0.0
+ * @story 6.8
+ */
+
+const path = require('path');
+const fs = require('fs').promises;
+
+// Import core modules
+const {
+  SourceTreeValidator,
+  normalizePath,
+  validateNamingConvention,
+  matchesPattern,
+  loadRules,
+  shouldExclude,
+  validateFilePlacement,
+  getStagedFiles,
+  Severity,
+} = require('./validator');
+
+const {
+  ManifestGenerator,
+  generateTree,
+  countFilesByCategory,
+  getFileStats,
+  FILE_CATEGORIES,
+  DEFAULT_EXCLUSIONS,
+} = require('./manifest-generator');
+
+/**
+ * CLI argument parser
+ * @param {string[]} args - Command line arguments
+ * @returns {Object} Parsed options
+ */
+function parseArgs(args) {
+  const options = {
+    help: false,
+    version: false,
+    files: null,
+    stagedOnly: false,
+    generateManifest: false,
+    diff: false,
+    fix: false,
+    json: false,
+    verbose: false,
+    force: false,
+    reason: null,
+    config: null,
+    check: null,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    switch (arg) {
+      case '-h':
+      case '--help':
+        options.help = true;
+        break;
+      case '-v':
+      case '--version':
+        options.version = true;
+        break;
+      case '--files':
+        options.files = args[++i];
+        break;
+      case '--staged-only':
+        options.stagedOnly = true;
+        break;
+      case '--generate-manifest':
+        options.generateManifest = true;
+        break;
+      case '--diff':
+        options.diff = true;
+        break;
+      case '--fix':
+        options.fix = true;
+        break;
+      case '--json':
+        options.json = true;
+        break;
+      case '--verbose':
+        options.verbose = true;
+        break;
+      case '--force':
+        options.force = true;
+        break;
+      case '--reason':
+        options.reason = args[++i];
+        break;
+      case '--config':
+        options.config = args[++i];
+        break;
+      case '--check':
+        options.check = args[++i];
+        break;
+      default:
+        if (!arg.startsWith('-')) {
+          options.files = arg;
+        }
+    }
+  }
+
+  return options;
+}
+
+/**
+ * Prints help message
+ */
+function printHelp() {
+  console.log(`
+Source-Tree Guardian - Structure Validation System
+Version: 1.0.0 | Story: 6.8
+
+USAGE:
+  node index.js [options]
+  npm run validate:structure [-- options]
+
+OPTIONS:
+  -h, --help              Show this help message
+  -v, --version           Show version information
+  --files <glob>          Validate specific files (glob pattern)
+  --staged-only           Only validate git staged files
+  --generate-manifest     Generate source-tree-manifest.json
+  --diff                  Show drift from previous manifest
+  --fix                   Show auto-fix suggestions
+  --json                  Output in JSON format
+  --verbose               Enable verbose output
+  --force                 Bypass validation (requires --reason)
+  --reason <text>         Justification for --force (logged)
+  --config <path>         Custom rules file location
+  --check <path>          Check a single file
+
+EXAMPLES:
+  # Validate all files
+  npm run validate:structure
+
+  # Validate specific files
+  npm run validate:structure -- --files "src/**/*.js"
+
+  # Validate staged files only (pre-commit)
+  npm run validate:structure -- --staged-only
+
+  # Generate manifest
+  npm run validate:structure -- --generate-manifest
+
+  # Show drift from previous manifest
+  npm run validate:structure -- --diff
+
+  # JSON output for CI
+  npm run validate:structure -- --json
+
+  # Force bypass with reason
+  npm run validate:structure -- --force --reason "Hotfix deployment"
+`);
+}
+
+/**
+ * Prints version information
+ */
+function printVersion() {
+  console.log('Source-Tree Guardian v1.0.0');
+  console.log('Story: 6.8 - Source-Tree Guardian - Structure Validation System');
+}
+
+/**
+ * Logs force bypass with reason
+ * @param {string} reason - Justification for bypass
+ * @param {string} projectRoot - Project root directory
+ */
+async function logForceBypass(reason, projectRoot) {
+  const logDir = path.join(projectRoot, '.ai');
+  const logFile = path.join(logDir, 'force-bypass-log.md');
+
+  await fs.mkdir(logDir, { recursive: true });
+
+  const entry = `\n## Force Bypass - ${new Date().toISOString()}\n\n**Reason:** ${reason}\n\n---\n`;
+
+  try {
+    await fs.appendFile(logFile, entry);
+    console.log(`⚠️  Force bypass logged to ${logFile}`);
+  } catch (error) {
+    console.warn(`Warning: Could not log force bypass: ${error.message}`);
+  }
+}
+
+/**
+ * Main CLI entry point
+ * @param {string[]} args - Command line arguments
+ * @returns {Promise<number>} Exit code
+ */
+async function main(args = process.argv.slice(2)) {
+  const options = parseArgs(args);
+  const projectRoot = process.cwd();
+
+  // Handle help and version
+  if (options.help) {
+    printHelp();
+    return 0;
+  }
+
+  if (options.version) {
+    printVersion();
+    return 0;
+  }
+
+  // Handle force bypass
+  if (options.force) {
+    if (!options.reason) {
+      console.error('❌ --force requires --reason to be specified');
+      return 1;
+    }
+    await logForceBypass(options.reason, projectRoot);
+    console.log('✅ Validation bypassed');
+    return 0;
+  }
+
+  // Handle manifest generation
+  if (options.generateManifest) {
+    const generator = new ManifestGenerator({ projectRoot });
+    console.log('📊 Generating source-tree manifest...');
+
+    const manifest = await generator.generate();
+    const outputPath = await generator.save(manifest);
+
+    if (options.json) {
+      console.log(JSON.stringify(manifest, null, 2));
+    } else {
+      console.log(`✅ Manifest generated: ${outputPath}`);
+      console.log(`   Files: ${manifest.summary.totalFiles}`);
+      console.log(`   Directories: ${manifest.summary.totalDirectories}`);
+      console.log(`   Duration: ${manifest.duration}ms`);
+    }
+    return 0;
+  }
+
+  // Handle diff
+  if (options.diff) {
+    const generator = new ManifestGenerator({ projectRoot });
+    console.log('📊 Comparing with previous manifest...');
+
+    try {
+      const oldManifest = await generator.load();
+      const newManifest = await generator.generate();
+      const diff = generator.compare(oldManifest, newManifest);
+
+      if (options.json) {
+        console.log(JSON.stringify(diff, null, 2));
+      } else {
+        console.log(generator.formatDiffReport(diff));
+      }
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        console.log('⚠️  No previous manifest found. Generate one first with --generate-manifest');
+        return 1;
+      }
+      throw error;
+    }
+    return 0;
+  }
+
+  // Handle single file check
+  if (options.check) {
+    const validator = new SourceTreeValidator({
+      projectRoot,
+      rulesPath: options.config,
+      verbose: options.verbose,
+    });
+
+    const result = await validator.validateFile(options.check);
+
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      if (result.isValid) {
+        console.log(`✅ ${options.check}: Valid placement`);
+      } else {
+        console.log(`❌ ${options.check}: Invalid placement`);
+        for (const v of result.violations) {
+          console.log(`   ${v.message}`);
+          if (v.suggestedLocation) {
+            console.log(`   Suggested: ${v.suggestedLocation}`);
+          }
+        }
+      }
+    }
+
+    return result.isValid ? 0 : 1;
+  }
+
+  // Main validation
+  const validator = new SourceTreeValidator({
+    projectRoot,
+    rulesPath: options.config,
+    verbose: options.verbose,
+  });
+
+  console.log('🔍 Validating source-tree structure...');
+
+  const report = await validator.validate({
+    files: options.files,
+    stagedOnly: options.stagedOnly,
+  });
+
+  // Output report
+  if (options.json) {
+    console.log(validator.formatJsonReport(report));
+  } else {
+    console.log(validator.formatReport(report, { showFixHint: !options.fix }));
+  }
+
+  // Show fix suggestions if requested
+  if (options.fix && report.violations.length > 0) {
+    console.log('\n📋 FIX SUGGESTIONS:\n');
+    const suggestions = validator.generateFixSuggestions(report.violations);
+    for (const suggestion of suggestions) {
+      console.log(`File: ${suggestion.file}`);
+      console.log(`  Current: ${suggestion.currentLocation}`);
+      console.log(`  Suggested: ${suggestion.suggestedLocation}`);
+      if (suggestion.command) {
+        console.log(`  Command: ${suggestion.command}`);
+      }
+      console.log('');
+    }
+  }
+
+  // Return exit code based on errors
+  return report.summary.errors > 0 ? 1 : 0;
+}
+
+// Export modules
+module.exports = {
+  // Validator exports
+  SourceTreeValidator,
+  normalizePath,
+  validateNamingConvention,
+  matchesPattern,
+  loadRules,
+  shouldExclude,
+  validateFilePlacement,
+  getStagedFiles,
+  Severity,
+  // Manifest exports
+  ManifestGenerator,
+  generateTree,
+  countFilesByCategory,
+  getFileStats,
+  FILE_CATEGORIES,
+  DEFAULT_EXCLUSIONS,
+  // CLI exports
+  main,
+  parseArgs,
+};
+
+// Run CLI if executed directly
+if (require.main === module) {
+  main()
+    .then((exitCode) => {
+      process.exit(exitCode);
+    })
+    .catch((error) => {
+      console.error('❌ Error:', error.message);
+      if (process.env.DEBUG) {
+        console.error(error.stack);
+      }
+      process.exit(1);
+    });
+}