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

English | Bahasa Indonesia

---

<a name="english"></a>

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);
  }
}

2. Topological Code Generation Sorter

Autonomous swarms must construct files in strict topological order to avoid compiling against non-existent types:

[Core Domain Types / Schemas]
             │
             ▼
[Persistence Layer & ORM Repositories]
             │
             ▼
[Business Services & Interactors]
             │
             ▼
[API Handlers / Controllers]
             │
             ▼
[Client SDKs & Frontend Hooks]

---

Best Practices

1. Reject String RegEx for Semantic Audits: Never use regex or text matching to find symbol usages; use static AST symbol declarations.
2. Compute Blast Radius Before Refactoring: When a core database model or API payload changes, compute all affected frontend and backend nodes first.
3. Fail Builds on Circular Dependencies: Integrate AST cycle checks directly into continuous integration pipelines to prevent runtime initialization deadlocks.
4. Order Swarm Generation Topologically: Feed code generation tasks to subagents according to dependency levels so downstream callers always receive complete interfaces.

---

Common Pitfalls to Avoid

Anti-Pattern	Blast Consequence	Correct AST Engineering
Global find-and-replace for variable renaming	Corrupts unrelated variables sharing identical names	Use AST symbol binding via ts.TypeChecker
Parallel multi-file generation without topological sort	Subagent attempts to import interfaces that do not exist	Sequence subagents using Directed Acyclic Graph (DAG) levels
Ignoring circular module references	Silent runtime initialization undefined bugs	Traverse graph using Tarjan's SCC algorithm

---

<a name="bahasa-indonesia"></a>

Bahasa Indonesia

Integrasi Orkestrasi

• Hulu & Orkestrasi: zero-to-prod-orchestrator (Pondasi Fase 2 & QA Fase 6), brainstorming, session-memory-manager.
• Manipulasi AST & Sistem Tipe: typescript-expert (compiler API TS & binding simbol), autonomous-api-drift-healer (radius dampak drift kontrak API).
• Arsitektur & Refaktor: scalability-clean-code (penegakan batas Clean Architecture), legacy-code-translator (pemetaan AST migrasi strangler), monorepo-architect (graf dependensi lintas paket).
• Kesehatan Kode & Audit Utang: zero-tech-debt-auditor (pembersihan simbol mati & kode tak terjangkau), anti-slop (verifikasi anti-slop AST).

Deskripsi

Panduan produksi untuk membangun dan menavigasi graf pengetahuan Abstract Syntax Tree (AST) in-memory pada proyek perangkat lunak berskala besar dan monorepo. Memungkinkan agen otonom untuk memahami relasi simbolik, menghitung radius dampak (blast radius) sebelum refaktor, mendeteksi dependensi melingkar (circular dependency), menentukan urutan pembuatan kode secara topologis, dan membersihkan kode mati tanpa mengandalkan pencarian teks biasa.

Kondisi Pemicu

Aktifkan skill ini ketika:

• Menjalankan refaktor skala besar atau mengganti nama simbol di banyak file/paket.
• Menganalisis radius dampak arsitektur sebelum mengubah skema database atau kontrak API.
• Mendeteksi dan memecahkan dependensi melingkar (circular dependency).
• Menentukan urutan pembuatan kode bagi sub-agen secara topologis agar dependensi dasar dibuat terlebih dahulu.
• Mengidentifikasi export yang tidak lagi dipakai (dead code) dan impor phantom.

---

Konsep Inti & Pola Praktik

1. Kalkulasi Radius Dampak (Blast Radius)

Saat mengubah suatu fungsi inti atau tipe data:

1. Identifikasi Simbol: Dapatkan simpul AST target menggunakan ts.TypeChecker.
2. Penelusuran Graf Terbalik: Telusuri semua simpul yang mengimpor atau memanggil simbol tersebut secara rekursif.
3. Pemberian Skor Risiko: Klasifikasikan file yang terdampak ke dalam tingkat risiko (Tinggi untuk API publik, Sedang untuk modul internal).

2. Urutan Pembangunan Topologis untuk Swarm

Pastikan sub-agen AI membangun file berdasarkan tingkatan hierarki DAG:

• Tingkat 0: Skema Database & Tipe Inti
• Tingkat 1: Repositori Data & ORM
• Tingkat 2: Layanan Logika Bisnis (Services)
• Tingkat 3: Endpoint Controller & API Route
• Tingkat 4: Hooks Frontend & Komponen UI

---

Praktik Terbaik

1. Gunakan AST Bukan Regex: Hindari pencarian teks biasa (find-and-replace) yang dapat merusak variabel bernama serupa di berkas lain.
2. Hitung Radius Dampak Sebelum Memulai: Sebelum sub-agen menulis ulang kode, dapatkan daftar lengkap berkas yang bergantung padanya.
3. Cegah Dependensi Melingkar: Jalankan algoritma Tarjan atau DFS untuk memastikan tidak ada siklus dependensi yang menyebabkan nilai undefined saat runtime.
4. Hapus Kode Mati Secara Otomatis: Padukan dengan zero-tech-debt-auditor untuk membersihkan fungsi dan tipe yang tidak memiliki referensi masuk (inbound edges).

---

Jebakan Umum yang Harus Dihindari

Praktik Buruk	Dampak Buruk	Solusi Rekayasa
Mengganti nama fungsi dengan string replace biasa	Merusak properti objek atau komentar yang kebetulan memiliki nama yang sama	Gunakan binding simbol AST dari TypeScript Compiler API
Memerintahkan sub-agen membuat UI sebelum tipe data siap	Muncul error tipe hilang dan kompilasi gagal	Susun urutan pembuatan secara topologis (Topological Sort)
Membiarkan import melingkar (circular imports)	Bug runtime sulit dilacak saat aplikasi diinisialisasi	Lakukan pengecekan siklus AST pada CI pipeline