living-codebase-ast-graph

living-codebase-ast-graph — vibes-plug Skill

English | Bahasa Indonesia

---

English

Orchestration & Integration

• Upstream & Orchestration: zero-to-prod-orchestrator (Phase 2 foundation & Phase 6 QA), brainstorming, session-memory-manager.
• AST Manipulation & Type Systems: typescript-expert (TS compiler API & symbol binding), autonomous-api-drift-healer (API contract drift blast radius).
• Architecture & Refactoring: scalability-clean-code (Clean Architecture boundary enforcement), legacy-code-translator (strangler migration AST mapping), monorepo-architect (cross-package dependency graphs).
• Code Health & Debt Auditing: zero-tech-debt-auditor (dead symbol & unreachable code eradication), anti-slop (AST anti-slop verification).

Description

Production guide for constructing and querying in-memory Abstract Syntax Tree (AST) knowledge graphs across multi-file and monorepo codebases. Enables autonomous agents to navigate complex symbol relationships, calculate refactoring blast radii, eliminate circular dependencies, determine optimal topological generation sequences, and prune unreachable code without relying on fuzzy string matching.

Trigger Conditions

Activate this skill when:

• Executing large-scale codebase refactoring or renaming symbols across multiple packages.
• Analyzing architectural blast radius before making breaking changes to data models or API signatures.
• Detecting and resolving circular dependencies in TypeScript, JavaScript, Python, or Go codebases.
• Ordering code generation tasks topologically so underlying dependencies are created before dependent modules.
• Identifying dead exports, unreferenced functions, and ghost imports with absolute precision.

---

Core Concepts & Patterns

1. In-Memory AST Dependency Extractor (TypeScript Compiler API)

import ts from 'typescript';
import fs from 'fs';
import path from 'path';

export interface SymbolNode {
  filePath: string;
  name: string;
  kind: 'function' | 'class' | 'interface' | 'variable' | 'type';
  dependencies: string[];
}

export interface CodebaseGraph {
  nodes: Map<string, SymbolNode>;
  edges: Map<string, Set<string>>;
}

export class LivingCodebaseASTGraph {
  private program: ts.Program;
  private checker: ts.TypeChecker;
  private graph: CodebaseGraph;

  constructor(rootFiles: string[], options: ts.CompilerOptions = {}) {
    this.program = ts.createProgram(rootFiles, {
      target: ts.ScriptTarget.ES2022,
      module: ts.ModuleKind.NodeNext,
      ...options
    });
    this.checker = this.program.getTypeChecker();
    this.graph = {
      nodes: new Map(),
      edges: new Map()
    };
    this.buildGraph();
  }

  private buildGraph(): void {
    for (const sourceFile of this.program.getSourceFiles()) {
      if (sourceFile.isDeclarationFile || sourceFile.fileName.includes('node_modules')) {
        continue;
      }
      this.analyzeSourceFile(sourceFile);
    }
  }

  private analyzeSourceFile(sourceFile: ts.SourceFile): void {
    const filePath = path.resolve(sourceFile.fileName);

    ts.forEachChild(sourceFile, (node) => {
      if (ts.isFunctionDeclaration(node) && node.name) {
        this.registerSymbol(filePath, node.name.text, 'function', node);
      } else if (ts.isClassDeclaration(node) && node.name) {
        this.registerSymbol(filePath, node.name.text, 'class', node);
      } else if (ts.isInterfaceDeclaration(node) && node.name) {
        this.registerSymbol(filePath, node.name.text, 'interface', node);
      }
    });
  }

  private registerSymbol(
    filePath: string,
    name: string,
    kind: SymbolNode['kind'],
    node: ts.Node
  ): void {
    const symbolKey = `${filePath}#${name}`;
    const dependencies: string[] = [];

    const visit = (child: ts.Node) => {
      if (ts.isIdentifier(child)) {
        const symbol = this.checker.getSymbolAtLocation(child);
        if (symbol && symbol.declarations && symbol.declarations.length > 0) {
          const declFile = symbol.declarations[0].getSourceFile().fileName;
          if (!declFile.includes('node_modules') && !declFile.endsWith('.d.ts')) {
            const targetKey = `${path.resolve(declFile)}#${symbol.getName()}`;
            if (targetKey !== symbolKey) {
              dependencies.push(targetKey);
            }
          }
        }
      }
      ts.forEachChild(child, visit);
    };

    visit(node);

    this.graph.nodes.set(symbolKey, { filePath, name, kind, dependencies });
    if (!this.graph.edges.has(symbolKey)) {
      this.graph.edges.set(symbolKey, new Set(dependencies));
    }
  }

  public calculateBlastRadius(symbolKey: string): string[] {
    const affected = new Set<string>();
    const queue = [symbolKey];

    while (queue.length > 0) {
      const current = queue.shift()!;
      for (const [nodeKey, deps] of this.graph.edges.entries()) {
        if (deps.has(current) && !affected.has(nodeKey)) {
          affected.add(nodeKey);
          queue.push(nodeKey);
        }
      }
    }
    return Array.from(affected);
  }
}