aios-core 2.1.5 → 2.2.0

package/.aios-core/infrastructure/scripts/documentation-integrity/doc-generator.js

@@ -0,0 +1,331 @@
+/**
+ * Documentation Generator Module
+ *
+ * Generates project-specific documentation from templates.
+ * Supports Node.js, Python, Go, and Rust projects.
+ *
+ * @module documentation-integrity/doc-generator
+ * @version 1.0.0
+ * @story 6.9
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Template directory
+const TEMPLATES_DIR = path.join(__dirname, '..', '..', 'templates', 'project-docs');
+
+/**
+ * Template file names
+ * @enum {string}
+ */
+const TemplateFiles = {
+  SOURCE_TREE: 'source-tree-tmpl.md',
+  CODING_STANDARDS: 'coding-standards-tmpl.md',
+  TECH_STACK: 'tech-stack-tmpl.md',
+};
+
+/**
+ * Output file names
+ * @enum {string}
+ */
+const OutputFiles = {
+  SOURCE_TREE: 'source-tree.md',
+  CODING_STANDARDS: 'coding-standards.md',
+  TECH_STACK: 'tech-stack.md',
+};
+
+/**
+ * Documentation context for template rendering
+ * @typedef {Object} DocContext
+ * @property {string} PROJECT_NAME - Project name
+ * @property {string} GENERATED_DATE - Generation date
+ * @property {string} INSTALLATION_MODE - Installation mode
+ * @property {string} TECH_STACK - Detected tech stack
+ * @property {boolean} IS_NODE - Is Node.js project
+ * @property {boolean} IS_PYTHON - Is Python project
+ * @property {boolean} IS_GO - Is Go project
+ * @property {boolean} IS_RUST - Is Rust project
+ * @property {boolean} IS_TYPESCRIPT - Uses TypeScript
+ */
+
+/**
+ * Builds documentation context from detected markers
+ *
+ * @param {string} projectName - Project name
+ * @param {string} mode - Installation mode
+ * @param {Object} markers - Detected project markers
+ * @param {Object} [overrides] - Optional context overrides
+ * @returns {DocContext} Documentation context
+ */
+function buildDocContext(projectName, mode, markers, overrides = {}) {
+  // Detect tech stack from markers
+  const techStacks = [];
+  if (markers.hasPackageJson) techStacks.push('Node.js');
+  if (markers.hasPythonProject) techStacks.push('Python');
+  if (markers.hasGoMod) techStacks.push('Go');
+  if (markers.hasCargoToml) techStacks.push('Rust');
+
+  // Determine file extension
+  let fileExt = 'js';
+  if (markers.hasTsconfig) fileExt = 'ts';
+
+  // Build context
+  const context = {
+    // Basic info
+    PROJECT_NAME: projectName,
+    GENERATED_DATE: new Date().toISOString().split('T')[0],
+    INSTALLATION_MODE: mode,
+    TECH_STACK: techStacks.join(', ') || 'Unknown',
+
+    // Language flags
+    IS_NODE: markers.hasPackageJson || false,
+    IS_PYTHON: markers.hasPythonProject || false,
+    IS_GO: markers.hasGoMod || false,
+    IS_RUST: markers.hasCargoToml || false,
+    IS_TYPESCRIPT: markers.hasTsconfig || false,
+
+    // Node.js specific
+    FILE_EXT: fileExt,
+    NODE_VERSION: '18+',
+    TYPESCRIPT_VERSION: '5.0+',
+    NPM_VERSION: '9+',
+    SEMICOLONS: 'Required',
+    SEMICOLONS_RULE: 'always',
+    PRETTIER_SEMI: true,
+
+    // Python specific
+    PYTHON_PACKAGE_NAME: projectName.toLowerCase().replace(/[^a-z0-9]/g, '_'),
+    PYTHON_VERSION: '3.11+',
+    PYTHON_SHORT_VERSION: '311',
+    POETRY_VERSION: '1.5+',
+
+    // Go specific
+    GO_VERSION: '1.21+',
+    GO_MODULE: `github.com/user/${projectName}`,
+
+    // Rust specific
+    RUST_VERSION: '1.70+',
+
+    // Deployment
+    DEPLOYMENT_PLATFORM: null,
+    PRODUCTION_BRANCH: 'main',
+    STAGING_BRANCH: 'staging',
+    HAS_STAGING: false,
+
+    // Database
+    DATABASE: null,
+    CACHE: null,
+
+    // Quality gates
+    QUALITY_GATES: ['Lint', 'Type Check', 'Tests'],
+
+    // Dependencies (to be populated by analyzer)
+    DEPENDENCIES: [],
+    DEV_DEPENDENCIES: [],
+    ENV_VARS: [],
+
+    // Apply overrides
+    ...overrides,
+  };
+
+  return context;
+}
+
+/**
+ * Simple template renderer with Handlebars-like syntax
+ * Supports: {{variable}}, {{#if condition}}, {{/if}}, {{#each array}}, {{/each}}
+ *
+ * @param {string} template - Template string
+ * @param {Object} context - Context object
+ * @returns {string} Rendered template
+ */
+function renderTemplate(template, context) {
+  let result = template;
+
+  // Process {{#if}} blocks
+  result = processIfBlocks(result, context);
+
+  // Process {{#each}} blocks
+  result = processEachBlocks(result, context);
+
+  // Replace simple variables {{variable}}
+  result = result.replace(/\{\{([^#/}][^}]*)\}\}/g, (match, key) => {
+    const value = getNestedValue(context, key.trim());
+    return value !== undefined ? String(value) : match;
+  });
+
+  // Clean up empty lines from removed blocks
+  result = result.replace(/\n{3,}/g, '\n\n');
+
+  return result;
+}
+
+/**
+ * Process {{#if condition}}...{{/if}} blocks
+ *
+ * @param {string} template - Template string
+ * @param {Object} context - Context object
+ * @returns {string} Processed template
+ */
+function processIfBlocks(template, context) {
+  // Match if blocks (non-greedy, innermost first)
+  const ifRegex = /\{\{#if\s+(\w+)\}\}([\s\S]*?)\{\{\/if\}\}/g;
+
+  let result = template;
+  let iterations = 0;
+  const maxIterations = 100; // Prevent infinite loops
+
+  while (ifRegex.test(result) && iterations < maxIterations) {
+    result = result.replace(ifRegex, (match, condition, content) => {
+      const value = context[condition];
+      if (value) {
+        return content;
+      }
+      return '';
+    });
+    iterations++;
+  }
+
+  return result;
+}
+
+/**
+ * Process {{#each array}}...{{/each}} blocks
+ *
+ * @param {string} template - Template string
+ * @param {Object} context - Context object
+ * @returns {string} Processed template
+ */
+function processEachBlocks(template, context) {
+  const eachRegex = /\{\{#each\s+(\w+)\}\}([\s\S]*?)\{\{\/each\}\}/g;
+
+  return template.replace(eachRegex, (match, arrayName, content) => {
+    const array = context[arrayName];
+    if (!Array.isArray(array) || array.length === 0) {
+      return '';
+    }
+
+    return array
+      .map((item) => {
+        let itemContent = content;
+        if (typeof item === 'object') {
+          // Replace {{this.property}} with item properties
+          itemContent = itemContent.replace(/\{\{this\.(\w+)\}\}/g, (m, prop) => {
+            return item[prop] !== undefined ? String(item[prop]) : m;
+          });
+        } else {
+          // Replace {{this}} with item value
+          itemContent = itemContent.replace(/\{\{this\}\}/g, String(item));
+        }
+        return itemContent;
+      })
+      .join('');
+  });
+}
+
+/**
+ * Get nested value from object using dot notation
+ *
+ * @param {Object} obj - Object to search
+ * @param {string} path - Dot-notation path
+ * @returns {*} Value at path or undefined
+ */
+function getNestedValue(obj, path) {
+  return path.split('.').reduce((current, key) => {
+    return current && current[key] !== undefined ? current[key] : undefined;
+  }, obj);
+}
+
+/**
+ * Loads a template file
+ *
+ * @param {string} templateName - Template file name
+ * @returns {string} Template content
+ * @throws {Error} If template not found
+ */
+function loadTemplate(templateName) {
+  const templatePath = path.join(TEMPLATES_DIR, templateName);
+
+  if (!fs.existsSync(templatePath)) {
+    throw new Error(`Template not found: ${templatePath}`);
+  }
+
+  return fs.readFileSync(templatePath, 'utf8');
+}
+
+/**
+ * Generates all documentation files for a project
+ *
+ * @param {string} targetDir - Target directory
+ * @param {DocContext} context - Documentation context
+ * @param {Object} [options] - Generation options
+ * @param {boolean} [options.dryRun] - Don't write files, just return content
+ * @returns {Object} Generated files with content
+ */
+function generateDocs(targetDir, context, options = {}) {
+  const docsDir = path.join(targetDir, 'docs', 'architecture');
+  const results = {};
+
+  // Ensure docs directory exists
+  if (!options.dryRun) {
+    fs.mkdirSync(docsDir, { recursive: true });
+  }
+
+  // Generate each doc
+  const templates = [
+    { template: TemplateFiles.SOURCE_TREE, output: OutputFiles.SOURCE_TREE },
+    { template: TemplateFiles.CODING_STANDARDS, output: OutputFiles.CODING_STANDARDS },
+    { template: TemplateFiles.TECH_STACK, output: OutputFiles.TECH_STACK },
+  ];
+
+  for (const { template, output } of templates) {
+    try {
+      const templateContent = loadTemplate(template);
+      const rendered = renderTemplate(templateContent, context);
+      const outputPath = path.join(docsDir, output);
+
+      results[output] = {
+        path: outputPath,
+        content: rendered,
+        success: true,
+      };
+
+      if (!options.dryRun) {
+        fs.writeFileSync(outputPath, rendered, 'utf8');
+      }
+    } catch (error) {
+      results[output] = {
+        path: path.join(docsDir, output),
+        content: null,
+        success: false,
+        error: error.message,
+      };
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Generates a single documentation file
+ *
+ * @param {string} templateName - Template file name
+ * @param {DocContext} context - Documentation context
+ * @returns {string} Rendered content
+ */
+function generateDoc(templateName, context) {
+  const template = loadTemplate(templateName);
+  return renderTemplate(template, context);
+}
+
+module.exports = {
+  buildDocContext,
+  renderTemplate,
+  loadTemplate,
+  generateDocs,
+  generateDoc,
+  TemplateFiles,
+  OutputFiles,
+  TEMPLATES_DIR,
+};

package/.aios-core/infrastructure/scripts/documentation-integrity/gitignore-generator.js

@@ -0,0 +1,312 @@
+/**
+ * Gitignore Generator Module
+ *
+ * Generates .gitignore files based on detected tech stack.
+ * Supports brownfield merge mode to preserve existing ignores.
+ *
+ * @module documentation-integrity/gitignore-generator
+ * @version 1.0.0
+ * @story 6.9
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Template directory
+const TEMPLATES_DIR = path.join(__dirname, '..', '..', 'templates', 'gitignore');
+
+/**
+ * Template file names
+ * @enum {string}
+ */
+const GitignoreTemplates = {
+  AIOS_BASE: 'gitignore-aios-base.tmpl',
+  NODE: 'gitignore-node.tmpl',
+  PYTHON: 'gitignore-python.tmpl',
+  BROWNFIELD_MERGE: 'gitignore-brownfield-merge.tmpl',
+};
+
+/**
+ * Tech stack identifiers
+ * @enum {string}
+ */
+const TechStack = {
+  NODE: 'node',
+  PYTHON: 'python',
+  GO: 'go',
+  RUST: 'rust',
+};
+
+/**
+ * Loads a gitignore template
+ *
+ * @param {string} templateName - Template file name
+ * @returns {string} Template content
+ * @throws {Error} If template not found
+ */
+function loadGitignoreTemplate(templateName) {
+  const templatePath = path.join(TEMPLATES_DIR, templateName);
+
+  if (!fs.existsSync(templatePath)) {
+    throw new Error(`Gitignore template not found: ${templatePath}`);
+  }
+
+  return fs.readFileSync(templatePath, 'utf8');
+}
+
+/**
+ * Detects tech stack from project markers
+ *
+ * @param {Object} markers - Detected project markers
+ * @returns {string[]} List of detected tech stacks
+ */
+function detectTechStacks(markers) {
+  const stacks = [];
+
+  if (markers.hasPackageJson) stacks.push(TechStack.NODE);
+  if (markers.hasPythonProject) stacks.push(TechStack.PYTHON);
+  if (markers.hasGoMod) stacks.push(TechStack.GO);
+  if (markers.hasCargoToml) stacks.push(TechStack.RUST);
+
+  return stacks;
+}
+
+/**
+ * Gets gitignore templates for detected tech stacks
+ *
+ * @param {string[]} techStacks - Detected tech stacks
+ * @returns {string[]} List of template names to use
+ */
+function getTemplatesForStacks(techStacks) {
+  const templates = [GitignoreTemplates.AIOS_BASE];
+
+  for (const stack of techStacks) {
+    switch (stack) {
+      case TechStack.NODE:
+        templates.push(GitignoreTemplates.NODE);
+        break;
+      case TechStack.PYTHON:
+        templates.push(GitignoreTemplates.PYTHON);
+        break;
+      // Go and Rust would have their own templates
+      // Add when implemented
+    }
+  }
+
+  return templates;
+}
+
+/**
+ * Generates a complete .gitignore file
+ *
+ * @param {Object} markers - Detected project markers
+ * @param {Object} [options] - Generation options
+ * @param {string} [options.projectName] - Project name for header
+ * @returns {string} Generated gitignore content
+ */
+function generateGitignore(markers, options = {}) {
+  const techStacks = detectTechStacks(markers);
+  const templates = getTemplatesForStacks(techStacks);
+
+  const sections = [];
+
+  // Add project header
+  const projectName = options.projectName || 'Project';
+  sections.push(`# ${projectName} .gitignore`);
+  sections.push('# Generated by AIOS Documentation Integrity System');
+  sections.push(`# Date: ${new Date().toISOString().split('T')[0]}`);
+  sections.push(`# Tech Stack: ${techStacks.join(', ') || 'Generic'}`);
+  sections.push('');
+
+  // Load and append each template
+  for (const templateName of templates) {
+    try {
+      const content = loadGitignoreTemplate(templateName);
+      sections.push(content);
+      sections.push(''); // Add blank line between sections
+    } catch (error) {
+      console.warn(`Warning: Could not load template ${templateName}: ${error.message}`);
+    }
+  }
+
+  return sections.join('\n').trim() + '\n';
+}
+
+/**
+ * Merges AIOS ignores with existing .gitignore
+ *
+ * @param {string} existingContent - Existing .gitignore content
+ * @param {Object} [options] - Merge options
+ * @returns {string} Merged gitignore content
+ */
+function mergeGitignore(existingContent, _options = {}) {
+  // Check if AIOS section already exists
+  if (existingContent.includes('AIOS Integration Section')) {
+    console.log('AIOS section already exists in .gitignore, skipping merge');
+    return existingContent;
+  }
+
+  // Load merge template
+  let mergeSection;
+  try {
+    mergeSection = loadGitignoreTemplate(GitignoreTemplates.BROWNFIELD_MERGE);
+  } catch {
+    // Fallback to minimal section
+    mergeSection = `
+# ========================================
+# AIOS Integration Section
+# ========================================
+
+# AIOS Local Configuration
+.aios-core/local/
+.aios-core/*.local.yaml
+.aios-core/logs/
+.aios-core/cache/
+
+# ========================================
+# End of AIOS Integration Section
+# ========================================
+`;
+  }
+
+  // Replace date placeholder
+  mergeSection = mergeSection.replace(
+    '{{GENERATED_DATE}}',
+    new Date().toISOString().split('T')[0],
+  );
+
+  // Append to existing content
+  const merged = existingContent.trimEnd() + '\n\n' + mergeSection.trim() + '\n';
+
+  return merged;
+}
+
+/**
+ * Generates or merges .gitignore for a project
+ *
+ * @param {string} targetDir - Target directory
+ * @param {Object} markers - Detected project markers
+ * @param {Object} [options] - Generation options
+ * @param {boolean} [options.dryRun] - Don't write file, just return content
+ * @param {boolean} [options.merge] - Merge with existing instead of replace
+ * @param {string} [options.projectName] - Project name for header
+ * @returns {Object} Generation result
+ */
+function generateGitignoreFile(targetDir, markers, options = {}) {
+  const gitignorePath = path.join(targetDir, '.gitignore');
+  const existingPath = fs.existsSync(gitignorePath);
+
+  let content;
+  let mode;
+
+  if (existingPath && options.merge !== false) {
+    // Brownfield mode - merge with existing
+    const existing = fs.readFileSync(gitignorePath, 'utf8');
+    content = mergeGitignore(existing, options);
+    mode = 'merged';
+  } else {
+    // Greenfield mode - generate new
+    content = generateGitignore(markers, options);
+    mode = existingPath ? 'replaced' : 'created';
+  }
+
+  const result = {
+    success: true,
+    path: gitignorePath,
+    content,
+    mode,
+    techStacks: detectTechStacks(markers),
+  };
+
+  if (!options.dryRun) {
+    try {
+      fs.writeFileSync(gitignorePath, content, 'utf8');
+    } catch (error) {
+      result.success = false;
+      result.error = error.message;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Checks if a .gitignore file has AIOS integration
+ *
+ * @param {string} targetDir - Target directory
+ * @returns {boolean} True if AIOS section exists
+ */
+function hasAiosIntegration(targetDir) {
+  const gitignorePath = path.join(targetDir, '.gitignore');
+
+  if (!fs.existsSync(gitignorePath)) {
+    return false;
+  }
+
+  const content = fs.readFileSync(gitignorePath, 'utf8');
+  return content.includes('AIOS Integration Section') || content.includes('.aios-core/');
+}
+
+/**
+ * Parses an existing .gitignore into sections
+ *
+ * @param {string} content - .gitignore content
+ * @returns {Object} Parsed sections
+ */
+function parseGitignore(content) {
+  const lines = content.split('\n');
+  const sections = {
+    header: [],
+    patterns: [],
+    aiosSection: null,
+    comments: [],
+  };
+
+  let aiosStart = -1;
+  let aiosEnd = -1;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    if (line.includes('AIOS Integration Section')) {
+      if (aiosStart === -1) {
+        aiosStart = i;
+      }
+    }
+
+    if (line.includes('End of AIOS Integration Section')) {
+      aiosEnd = i;
+    }
+
+    if (line.startsWith('#') && !line.includes('AIOS')) {
+      sections.comments.push({ line: i, content: line });
+    }
+
+    if (!line.startsWith('#') && line.trim()) {
+      sections.patterns.push({ line: i, pattern: line.trim() });
+    }
+  }
+
+  if (aiosStart !== -1) {
+    sections.aiosSection = {
+      start: aiosStart,
+      end: aiosEnd !== -1 ? aiosEnd : lines.length - 1,
+    };
+  }
+
+  return sections;
+}
+
+module.exports = {
+  loadGitignoreTemplate,
+  detectTechStacks,
+  getTemplatesForStacks,
+  generateGitignore,
+  mergeGitignore,
+  generateGitignoreFile,
+  hasAiosIntegration,
+  parseGitignore,
+  GitignoreTemplates,
+  TechStack,
+  TEMPLATES_DIR,
+};

package/.aios-core/infrastructure/scripts/documentation-integrity/index.js

@@ -0,0 +1,74 @@
+/**
+ * Documentation Integrity System
+ *
+ * Mode-aware project configuration system for AIOS.
+ * Supports three installation modes: framework-dev, greenfield, brownfield.
+ *
+ * @module documentation-integrity
+ * @version 1.0.0
+ * @story 6.9
+ */
+
+const modeDetector = require('./mode-detector');
+const docGenerator = require('./doc-generator');
+const configGenerator = require('./config-generator');
+const deploymentConfigLoader = require('./deployment-config-loader');
+const gitignoreGenerator = require('./gitignore-generator');
+const brownfieldAnalyzer = require('./brownfield-analyzer');
+
+// Re-export all modules
+module.exports = {
+  // Mode detection
+  detectInstallationMode: modeDetector.detectInstallationMode,
+  collectMarkers: modeDetector.collectMarkers,
+  isAiosCoreRepository: modeDetector.isAiosCoreRepository,
+  mapLegacyTypeToMode: modeDetector.mapLegacyTypeToMode,
+  validateModeSelection: modeDetector.validateModeSelection,
+  getModeOptions: modeDetector.getModeOptions,
+
+  // Mode constants
+  InstallationMode: modeDetector.InstallationMode,
+  LegacyProjectType: modeDetector.LegacyProjectType,
+  ModeDescriptions: modeDetector.ModeDescriptions,
+
+  // Documentation generation (Phase 2)
+  buildDocContext: docGenerator.buildDocContext,
+  generateDocs: docGenerator.generateDocs,
+  generateDoc: docGenerator.generateDoc,
+  TemplateFiles: docGenerator.TemplateFiles,
+  OutputFiles: docGenerator.OutputFiles,
+
+  // Config generation (Phase 3)
+  buildConfigContext: configGenerator.buildConfigContext,
+  generateConfig: configGenerator.generateConfig,
+  buildDeploymentConfig: configGenerator.buildDeploymentConfig,
+  ConfigTemplates: configGenerator.ConfigTemplates,
+  DeploymentWorkflow: configGenerator.DeploymentWorkflow,
+  DeploymentPlatform: configGenerator.DeploymentPlatform,
+
+  // Deployment config loader (shared utility)
+  loadDeploymentConfig: deploymentConfigLoader.loadDeploymentConfig,
+  loadProjectConfig: deploymentConfigLoader.loadProjectConfig,
+  getTargetBranch: deploymentConfigLoader.getTargetBranch,
+  getEnvironmentConfig: deploymentConfigLoader.getEnvironmentConfig,
+  isQualityGateEnabled: deploymentConfigLoader.isQualityGateEnabled,
+  getEnabledQualityGates: deploymentConfigLoader.getEnabledQualityGates,
+  validateDeploymentConfig: deploymentConfigLoader.validateDeploymentConfig,
+
+  // Gitignore generation (Phase 4)
+  generateGitignore: gitignoreGenerator.generateGitignore,
+  mergeGitignore: gitignoreGenerator.mergeGitignore,
+  generateGitignoreFile: gitignoreGenerator.generateGitignoreFile,
+  hasAiosIntegration: gitignoreGenerator.hasAiosIntegration,
+  GitignoreTemplates: gitignoreGenerator.GitignoreTemplates,
+  TechStack: gitignoreGenerator.TechStack,
+
+  // Brownfield analysis (Phase 5)
+  analyzeProject: brownfieldAnalyzer.analyzeProject,
+  analyzeTechStack: brownfieldAnalyzer.analyzeTechStack,
+  analyzeCodeStandards: brownfieldAnalyzer.analyzeCodeStandards,
+  analyzeWorkflows: brownfieldAnalyzer.analyzeWorkflows,
+  analyzeDirectoryStructure: brownfieldAnalyzer.analyzeDirectoryStructure,
+  generateRecommendations: brownfieldAnalyzer.generateRecommendations,
+  formatMigrationReport: brownfieldAnalyzer.formatMigrationReport,
+};