neuronlayer 0.1.0 → 1.1.0

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

@@ -1,348 +0,0 @@
-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

@@ -1,230 +0,0 @@
-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

@@ -1,110 +0,0 @@
-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
-    }
-  }
-}