neuronlayer 0.1.0

package/src/core/living-docs/changelog-generator.ts

@@ -0,0 +1,348 @@
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import type Database from 'better-sqlite3';
+import type {
+  DailyChangelog,
+  ChangeEntry,
+  FileChangeInfo,
+  ChangeMetrics,
+  ChangelogOptions
+} from '../../types/documentation.js';
+
+interface CommitInfo {
+  hash: string;
+  subject: string;
+  author: string;
+  date: Date;
+  files: string[];
+  additions: number;
+  deletions: number;
+}
+
+interface DayGroup {
+  date: Date;
+  commits: CommitInfo[];
+  entries: ChangeEntry[];
+}
+
+export class ChangelogGenerator {
+  private projectPath: string;
+  private db: Database.Database;
+  private isGitRepo: boolean;
+
+  constructor(projectPath: string, db: Database.Database) {
+    this.projectPath = projectPath;
+    this.db = db;
+    this.isGitRepo = existsSync(join(projectPath, '.git'));
+  }
+
+  async generate(options: ChangelogOptions = {}): Promise<DailyChangelog[]> {
+    if (!this.isGitRepo) {
+      return [];
+    }
+
+    const since = this.parseSinceString(options.since || 'this week');
+    const until = options.until || new Date();
+
+    const commits = this.getCommitsInRange(since, until);
+    const grouped = this.groupByDay(commits);
+
+    return grouped.map(day => this.createDailyChangelog(day, options.includeDecisions ?? false));
+  }
+
+  private parseSinceString(since: Date | string): Date {
+    if (since instanceof Date) {
+      return since;
+    }
+
+    const now = new Date();
+    const lower = since.toLowerCase();
+
+    if (lower === 'yesterday') {
+      const yesterday = new Date(now);
+      yesterday.setDate(yesterday.getDate() - 1);
+      yesterday.setHours(0, 0, 0, 0);
+      return yesterday;
+    }
+    if (lower === 'today') {
+      const today = new Date(now);
+      today.setHours(0, 0, 0, 0);
+      return today;
+    }
+    if (lower === 'this week') {
+      const dayOfWeek = now.getDay();
+      const startOfWeek = new Date(now);
+      startOfWeek.setDate(now.getDate() - dayOfWeek);
+      startOfWeek.setHours(0, 0, 0, 0);
+      return startOfWeek;
+    }
+    if (lower === 'this month') {
+      return new Date(now.getFullYear(), now.getMonth(), 1);
+    }
+    if (lower === 'last week') {
+      const dayOfWeek = now.getDay();
+      const startOfLastWeek = new Date(now);
+      startOfLastWeek.setDate(now.getDate() - dayOfWeek - 7);
+      startOfLastWeek.setHours(0, 0, 0, 0);
+      return startOfLastWeek;
+    }
+
+    // Try to parse as date string
+    const parsed = new Date(since);
+    return isNaN(parsed.getTime()) ? new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000) : parsed;
+  }
+
+  private getCommitsInRange(since: Date, until: Date): CommitInfo[] {
+    const commits: CommitInfo[] = [];
+
+    try {
+      const sinceStr = since.toISOString().split('T')[0];
+      const untilStr = until.toISOString().split('T')[0];
+
+      // Get commit list with basic info
+      const output = execSync(
+        `git log --since="${sinceStr}" --until="${untilStr}" --format="%H|%s|%an|%ad" --date=iso-strict`,
+        { cwd: this.projectPath, encoding: 'utf-8', maxBuffer: 5 * 1024 * 1024 }
+      );
+
+      const lines = output.trim().split('\n').filter(Boolean);
+
+      for (const line of lines) {
+        const [hash, subject, author, dateStr] = line.split('|');
+        if (!hash || !subject) continue;
+
+        // Get file stats for this commit
+        const { files, additions, deletions } = this.getCommitStats(hash);
+
+        commits.push({
+          hash: hash.slice(0, 8),
+          subject: subject || '',
+          author: author || 'Unknown',
+          date: new Date(dateStr || Date.now()),
+          files,
+          additions,
+          deletions
+        });
+      }
+    } catch (error) {
+      // Git command failed
+    }
+
+    return commits;
+  }
+
+  private getCommitStats(hash: string): { files: string[]; additions: number; deletions: number } {
+    try {
+      const output = execSync(
+        `git show --stat --format="" "${hash}"`,
+        { cwd: this.projectPath, encoding: 'utf-8', maxBuffer: 1024 * 1024 }
+      );
+
+      const files: string[] = [];
+      let additions = 0;
+      let deletions = 0;
+
+      const lines = output.trim().split('\n');
+      for (const line of lines) {
+        // Match file lines like: src/file.ts | 10 +++++-----
+        const fileMatch = line.match(/^\s*([^\|]+)\s*\|/);
+        if (fileMatch && fileMatch[1]) {
+          files.push(fileMatch[1].trim());
+        }
+
+        // Match insertions/deletions from summary line
+        const insertMatch = line.match(/(\d+)\s+insertion/);
+        const deleteMatch = line.match(/(\d+)\s+deletion/);
+        if (insertMatch) additions = parseInt(insertMatch[1]!, 10);
+        if (deleteMatch) deletions = parseInt(deleteMatch[1]!, 10);
+      }
+
+      return { files, additions, deletions };
+    } catch {
+      return { files: [], additions: 0, deletions: 0 };
+    }
+  }
+
+  private groupByDay(commits: CommitInfo[]): DayGroup[] {
+    const groups = new Map<string, DayGroup>();
+
+    for (const commit of commits) {
+      const dateKey = commit.date.toISOString().split('T')[0]!;
+
+      if (!groups.has(dateKey)) {
+        const dayDate = new Date(dateKey);
+        groups.set(dateKey, {
+          date: dayDate,
+          commits: [],
+          entries: []
+        });
+      }
+
+      const group = groups.get(dateKey)!;
+      group.commits.push(commit);
+      group.entries.push(this.commitToEntry(commit));
+    }
+
+    // Sort by date descending (most recent first)
+    return Array.from(groups.values()).sort((a, b) => b.date.getTime() - a.date.getTime());
+  }
+
+  private commitToEntry(commit: CommitInfo): ChangeEntry {
+    return {
+      type: this.categorizeCommit(commit.subject),
+      description: this.cleanCommitMessage(commit.subject),
+      files: commit.files,
+      commit: commit.hash
+    };
+  }
+
+  private categorizeCommit(subject: string): ChangeEntry['type'] {
+    const lower = subject.toLowerCase();
+
+    // Check conventional commit prefixes
+    if (lower.startsWith('feat') || lower.includes('add ') || lower.includes('implement')) {
+      return 'feature';
+    }
+    if (lower.startsWith('fix') || lower.includes('bug') || lower.includes('resolve')) {
+      return 'fix';
+    }
+    if (lower.startsWith('refactor') || lower.includes('cleanup') || lower.includes('reorganize')) {
+      return 'refactor';
+    }
+    if (lower.startsWith('docs') || lower.includes('documentation') || lower.includes('readme')) {
+      return 'docs';
+    }
+    if (lower.startsWith('test') || lower.includes('spec') || lower.includes('coverage')) {
+      return 'test';
+    }
+
+    return 'chore';
+  }
+
+  private cleanCommitMessage(subject: string): string {
+    // Remove conventional commit prefix
+    return subject
+      .replace(/^(?:feat|fix|refactor|docs|test|chore|perf|build|ci|style)\([^)]*\):\s*/i, '')
+      .replace(/^(?:feat|fix|refactor|docs|test|chore|perf|build|ci|style):\s*/i, '')
+      .trim();
+  }
+
+  private createDailyChangelog(day: DayGroup, includeDecisions: boolean): DailyChangelog {
+    const features = day.entries.filter(e => e.type === 'feature');
+    const fixes = day.entries.filter(e => e.type === 'fix');
+    const refactors = day.entries.filter(e => e.type === 'refactor');
+
+    const filesModified = this.aggregateFileChanges(day.commits);
+    const metrics = this.calculateMetrics(day.commits);
+    const decisions = includeDecisions ? this.getDecisionsForDate(day.date) : [];
+
+    return {
+      date: day.date,
+      summary: this.generateSummary(day.entries, metrics),
+      features,
+      fixes,
+      refactors,
+      filesModified,
+      decisions,
+      metrics
+    };
+  }
+
+  private aggregateFileChanges(commits: CommitInfo[]): FileChangeInfo[] {
+    const fileMap = new Map<string, FileChangeInfo>();
+
+    for (const commit of commits) {
+      for (const file of commit.files) {
+        if (!fileMap.has(file)) {
+          fileMap.set(file, {
+            file,
+            added: 0,
+            removed: 0,
+            type: 'modified'
+          });
+        }
+      }
+    }
+
+    // Distribute additions/deletions proportionally (rough estimate)
+    for (const commit of commits) {
+      const fileCount = commit.files.length || 1;
+      const addPerFile = Math.round(commit.additions / fileCount);
+      const delPerFile = Math.round(commit.deletions / fileCount);
+
+      for (const file of commit.files) {
+        const info = fileMap.get(file);
+        if (info) {
+          info.added += addPerFile;
+          info.removed += delPerFile;
+        }
+      }
+    }
+
+    return Array.from(fileMap.values());
+  }
+
+  private calculateMetrics(commits: CommitInfo[]): ChangeMetrics {
+    const filesSet = new Set<string>();
+    let linesAdded = 0;
+    let linesRemoved = 0;
+
+    for (const commit of commits) {
+      for (const file of commit.files) {
+        filesSet.add(file);
+      }
+      linesAdded += commit.additions;
+      linesRemoved += commit.deletions;
+    }
+
+    return {
+      commits: commits.length,
+      filesChanged: filesSet.size,
+      linesAdded,
+      linesRemoved
+    };
+  }
+
+  private generateSummary(entries: ChangeEntry[], metrics: ChangeMetrics): string {
+    const parts: string[] = [];
+
+    const features = entries.filter(e => e.type === 'feature').length;
+    const fixes = entries.filter(e => e.type === 'fix').length;
+    const refactors = entries.filter(e => e.type === 'refactor').length;
+
+    if (features > 0) {
+      parts.push(`${features} feature${features > 1 ? 's' : ''}`);
+    }
+    if (fixes > 0) {
+      parts.push(`${fixes} fix${fixes > 1 ? 'es' : ''}`);
+    }
+    if (refactors > 0) {
+      parts.push(`${refactors} refactor${refactors > 1 ? 's' : ''}`);
+    }
+
+    if (parts.length === 0) {
+      return `${metrics.commits} commit${metrics.commits !== 1 ? 's' : ''} affecting ${metrics.filesChanged} file${metrics.filesChanged !== 1 ? 's' : ''}`;
+    }
+
+    return `${parts.join(', ')} across ${metrics.filesChanged} file${metrics.filesChanged !== 1 ? 's' : ''}`;
+  }
+
+  private getDecisionsForDate(date: Date): string[] {
+    try {
+      const startOfDay = Math.floor(new Date(date).setHours(0, 0, 0, 0) / 1000);
+      const endOfDay = Math.floor(new Date(date).setHours(23, 59, 59, 999) / 1000);
+
+      const stmt = this.db.prepare(`
+        SELECT title FROM decisions
+        WHERE created_at >= ? AND created_at <= ?
+        ORDER BY created_at
+      `);
+
+      const rows = stmt.all(startOfDay, endOfDay) as Array<{ title: string }>;
+      return rows.map(r => r.title);
+    } catch {
+      return [];
+    }
+  }
+}

package/src/core/living-docs/component-generator.ts

@@ -0,0 +1,230 @@
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { basename, extname, join } from 'path';
+import type { Tier2Storage } from '../../storage/tier2.js';
+import type { CodeSymbol } from '../../types/index.js';
+import type {
+  ComponentDoc,
+  SymbolDoc,
+  DependencyDoc,
+  DependentDoc,
+  ChangeHistoryEntry
+} from '../../types/documentation.js';
+
+export class ComponentGenerator {
+  private projectPath: string;
+  private tier2: Tier2Storage;
+  private isGitRepo: boolean;
+
+  constructor(projectPath: string, tier2: Tier2Storage) {
+    this.projectPath = projectPath;
+    this.tier2 = tier2;
+    this.isGitRepo = existsSync(join(projectPath, '.git'));
+  }
+
+  async generate(filePath: string): Promise<ComponentDoc> {
+    const file = this.tier2.getFile(filePath);
+    if (!file) {
+      throw new Error(`File not found: ${filePath}`);
+    }
+
+    const symbols = this.tier2.getSymbolsByFile(file.id);
+    const imports = this.tier2.getImportsByFile(file.id);
+    const dependents = this.tier2.getFileDependents(filePath);
+    const history = this.getChangeHistory(filePath);
+
+    return {
+      file: filePath,
+      name: basename(filePath, extname(filePath)),
+      purpose: this.inferPurpose(filePath, symbols),
+      lastModified: new Date(file.lastModified * 1000),
+      publicInterface: this.extractPublicInterface(symbols),
+      dependencies: this.formatDependencies(imports),
+      dependents: this.formatDependents(dependents),
+      changeHistory: history,
+      contributors: this.extractContributors(history),
+      complexity: this.calculateComplexity(symbols),
+      documentationScore: this.calculateDocScore(symbols)
+    };
+  }
+
+  private inferPurpose(filePath: string, symbols: CodeSymbol[]): string {
+    const name = basename(filePath, extname(filePath));
+    const parts: string[] = [];
+
+    // Infer from filename
+    if (name.toLowerCase().includes('test')) {
+      return `Test file for ${name.replace(/\.test|\.spec|Test|Spec/gi, '')}`;
+    }
+    if (name.toLowerCase().includes('util') || name.toLowerCase().includes('helper')) {
+      return 'Utility functions and helpers';
+    }
+    if (name === 'index') {
+      return 'Module entry point / barrel export';
+    }
+
+    // Infer from exported symbols
+    const exported = symbols.filter(s => s.exported);
+    const classes = exported.filter(s => s.kind === 'class');
+    const interfaces = exported.filter(s => s.kind === 'interface');
+    const functions = exported.filter(s => s.kind === 'function');
+
+    if (classes.length === 1) {
+      return `Defines the ${classes[0]!.name} class`;
+    }
+    if (interfaces.length > 0 && functions.length === 0) {
+      return `Type definitions: ${interfaces.map(i => i.name).slice(0, 3).join(', ')}`;
+    }
+    if (functions.length > 0) {
+      parts.push(`Functions: ${functions.map(f => f.name).slice(0, 3).join(', ')}`);
+    }
+
+    // Infer from directory
+    const pathParts = filePath.split(/[/\\]/);
+    const parentDir = pathParts[pathParts.length - 2];
+    if (parentDir) {
+      const dirPurposes: Record<string, string> = {
+        'server': 'Server-side code',
+        'api': 'API layer',
+        'core': 'Core business logic',
+        'storage': 'Data storage',
+        'utils': 'Utilities',
+        'types': 'Type definitions',
+        'components': 'UI components',
+        'hooks': 'React hooks',
+        'services': 'Service layer'
+      };
+      if (dirPurposes[parentDir]) {
+        parts.unshift(dirPurposes[parentDir]);
+      }
+    }
+
+    return parts.length > 0 ? parts.join('. ') : `Module: ${name}`;
+  }
+
+  private extractPublicInterface(symbols: CodeSymbol[]): SymbolDoc[] {
+    return symbols
+      .filter(s => s.exported)
+      .map(s => ({
+        name: s.name,
+        kind: s.kind,
+        signature: s.signature,
+        description: s.docstring,
+        lineStart: s.lineStart,
+        lineEnd: s.lineEnd,
+        exported: true
+      }));
+  }
+
+  private formatDependencies(imports: Array<{
+    importedFrom: string;
+    importedSymbols: string[];
+  }>): DependencyDoc[] {
+    return imports.map(i => ({
+      file: i.importedFrom,
+      symbols: i.importedSymbols
+    }));
+  }
+
+  private formatDependents(dependents: Array<{
+    file: string;
+    imports: string[];
+  }>): DependentDoc[] {
+    return dependents.map(d => ({
+      file: d.file,
+      symbols: d.imports
+    }));
+  }
+
+  private getChangeHistory(filePath: string): ChangeHistoryEntry[] {
+    const history: ChangeHistoryEntry[] = [];
+
+    if (!this.isGitRepo) {
+      return history;
+    }
+
+    try {
+      const output = execSync(
+        `git log --oneline -20 --format="%H|%s|%an|%ad" --date=short -- "${filePath}"`,
+        { cwd: this.projectPath, encoding: 'utf-8', maxBuffer: 1024 * 1024 }
+      );
+
+      const lines = output.trim().split('\n').filter(Boolean);
+
+      for (const line of lines) {
+        const [hash, subject, author, dateStr] = line.split('|');
+        if (!hash || !subject) continue;
+
+        const { added, removed } = this.getCommitLineChanges(hash, filePath);
+
+        history.push({
+          date: new Date(dateStr || Date.now()),
+          change: subject,
+          author: author || 'Unknown',
+          commit: hash.slice(0, 8),
+          linesChanged: { added, removed }
+        });
+      }
+    } catch {
+      // Git command failed
+    }
+
+    return history;
+  }
+
+  private getCommitLineChanges(hash: string, filePath: string): { added: number; removed: number } {
+    try {
+      const output = execSync(
+        `git show --numstat --format="" "${hash}" -- "${filePath}"`,
+        { cwd: this.projectPath, encoding: 'utf-8', maxBuffer: 1024 * 1024 }
+      );
+
+      const match = output.trim().match(/^(\d+)\s+(\d+)/);
+      if (match) {
+        return {
+          added: parseInt(match[1]!, 10),
+          removed: parseInt(match[2]!, 10)
+        };
+      }
+    } catch {
+      // Git command failed
+    }
+
+    return { added: 0, removed: 0 };
+  }
+
+  private extractContributors(history: ChangeHistoryEntry[]): string[] {
+    const contributors = new Set<string>();
+    for (const entry of history) {
+      contributors.add(entry.author);
+    }
+    return Array.from(contributors);
+  }
+
+  private calculateComplexity(symbols: CodeSymbol[]): 'low' | 'medium' | 'high' {
+    const totalSymbols = symbols.length;
+    const exportedSymbols = symbols.filter(s => s.exported).length;
+    const avgLineSpan = symbols.length > 0
+      ? symbols.reduce((sum, s) => sum + (s.lineEnd - s.lineStart), 0) / symbols.length
+      : 0;
+
+    // Simple heuristic based on symbol count and size
+    if (totalSymbols > 20 || avgLineSpan > 50) {
+      return 'high';
+    }
+    if (totalSymbols > 8 || avgLineSpan > 25) {
+      return 'medium';
+    }
+    return 'low';
+  }
+
+  private calculateDocScore(symbols: CodeSymbol[]): number {
+    const exported = symbols.filter(s => s.exported);
+    if (exported.length === 0) {
+      return 100; // No public API, considered fully documented
+    }
+
+    const documented = exported.filter(s => s.docstring && s.docstring.length > 0);
+    return Math.round((documented.length / exported.length) * 100);
+  }
+}

package/src/core/living-docs/doc-engine.ts

@@ -0,0 +1,110 @@
+import type Database from 'better-sqlite3';
+import type { Tier2Storage } from '../../storage/tier2.js';
+import { ArchitectureGenerator } from './architecture-generator.js';
+import { ComponentGenerator } from './component-generator.js';
+import { ChangelogGenerator } from './changelog-generator.js';
+import { DocValidator } from './doc-validator.js';
+import { ActivityTracker } from './activity-tracker.js';
+import type {
+  ArchitectureDoc,
+  ComponentDoc,
+  DailyChangelog,
+  ChangelogOptions,
+  ValidationResult,
+  ActivityResult,
+  UndocumentedItem
+} from '../../types/documentation.js';
+
+export class LivingDocumentationEngine {
+  private archGen: ArchitectureGenerator;
+  private compGen: ComponentGenerator;
+  private changeGen: ChangelogGenerator;
+  private validator: DocValidator;
+  private activityTracker: ActivityTracker;
+  private db: Database.Database;
+
+  constructor(
+    projectPath: string,
+    dataDir: string,
+    db: Database.Database,
+    tier2: Tier2Storage
+  ) {
+    this.db = db;
+    this.archGen = new ArchitectureGenerator(projectPath, tier2);
+    this.compGen = new ComponentGenerator(projectPath, tier2);
+    this.changeGen = new ChangelogGenerator(projectPath, db);
+    this.validator = new DocValidator(projectPath, tier2, db);
+    this.activityTracker = new ActivityTracker(projectPath, db, tier2);
+  }
+
+  async generateArchitectureDocs(): Promise<ArchitectureDoc> {
+    const doc = await this.archGen.generate();
+
+    // Log activity
+    this.activityTracker.logActivity(
+      'doc_generation',
+      'Generated architecture documentation',
+      undefined,
+      { type: 'architecture' }
+    );
+
+    return doc;
+  }
+
+  async generateComponentDoc(filePath: string): Promise<ComponentDoc> {
+    const doc = await this.compGen.generate(filePath);
+
+    // Store in documentation table for tracking
+    this.storeDocumentation(filePath, 'component', JSON.stringify(doc));
+
+    // Log activity
+    this.activityTracker.logActivity(
+      'doc_generation',
+      `Generated component documentation for ${filePath}`,
+      filePath,
+      { type: 'component' }
+    );
+
+    return doc;
+  }
+
+  async generateChangelog(options: ChangelogOptions = {}): Promise<DailyChangelog[]> {
+    return this.changeGen.generate(options);
+  }
+
+  async validateDocs(): Promise<ValidationResult> {
+    return this.validator.validate();
+  }
+
+  async whatHappened(since: string, scope?: string): Promise<ActivityResult> {
+    return this.activityTracker.whatHappened(since, scope);
+  }
+
+  async findUndocumented(options?: {
+    importance?: 'low' | 'medium' | 'high' | 'all';
+    type?: 'file' | 'function' | 'class' | 'interface' | 'all';
+  }): Promise<UndocumentedItem[]> {
+    return this.validator.findUndocumented(options);
+  }
+
+  private storeDocumentation(filePath: string, docType: string, content: string): void {
+    try {
+      // Get file ID
+      const fileStmt = this.db.prepare('SELECT id FROM files WHERE path = ?');
+      const fileRow = fileStmt.get(filePath) as { id: number } | undefined;
+
+      if (fileRow) {
+        const stmt = this.db.prepare(`
+          INSERT INTO documentation (file_id, doc_type, content, generated_at)
+          VALUES (?, ?, ?, unixepoch())
+          ON CONFLICT(file_id, doc_type) DO UPDATE SET
+            content = excluded.content,
+            generated_at = unixepoch()
+        `);
+        stmt.run(fileRow.id, docType, content);
+      }
+    } catch {
+      // Ignore storage errors
+    }
+  }
+}