Skip to main content
The AnalyzerPlugin interface defines the contract that all language analysis plugins must satisfy. Plugins are registered with the PluginRegistry and are responsible for parsing source files, resolving imports, and optionally extracting call graphs.

​
AnalyzerPlugin interface

export interface AnalyzerPlugin {
  name: string;
  languages: string[];
  analyzeFile(filePath: string, content: string): StructuralAnalysis;
  resolveImports(filePath: string, content: string): ImportResolution[];
  extractCallGraph?(filePath: string, content: string): CallGraphEntry[];
}
​
name
string
required
Unique identifier for this plugin (e.g. "tree-sitter", "python-ast").
​
languages
string[]
required
List of language identifiers this plugin handles (e.g. ["typescript", "javascript"]). These are matched by the registry’s language map.
​
analyzeFile
(filePath: string, content: string) => StructuralAnalysis
required
Parses content as the given filePath and returns a StructuralAnalysis.
​
resolveImports
(filePath: string, content: string) => ImportResolution[]
required
Parses import statements in content and resolves relative paths to absolute paths. Returns an array of ImportResolution.
​
extractCallGraph
(filePath: string, content: string) => CallGraphEntry[]
Optional. Extracts caller→callee relationships from the file. Returns an array of CallGraphEntry.

​
StructuralAnalysis

The return type of analyzeFile. Contains all structurally interesting declarations found in a source file. 
export interface StructuralAnalysis {
  functions: Array<{
    name: string;
    lineRange: [number, number];
    params: string[];
    returnType?: string;
  }>;
  classes: Array<{
    name: string;
    lineRange: [number, number];
    methods: string[];
    properties: string[];
  }>;
  imports: Array<{
    source: string;
    specifiers: string[];
    lineNumber: number;
  }>;
  exports: Array<{
    name: string;
    lineNumber: number;
  }>;
}
​
functions
Array<...>
required
All function and arrow-function declarations found at the top level or exported.
​
classes
Array<...>
required
All class declarations found in the file.
​
imports
Array<...>
required
All import statements in the file.
​
exports
Array<...>
required
All exported names in the file.

​
ImportResolution

Represents a resolved import statement, returned by resolveImports. 
export interface ImportResolution {
  source: string;
  resolvedPath: string;
  specifiers: string[];
}
​
source
string
required
The module specifier as written in the source file (e.g. "./utils", "react").
​
resolvedPath
string
required
Absolute filesystem path for relative imports, or the original specifier unchanged for package imports (e.g. "/home/user/project/src/utils", "react").
​
specifiers
string[]
required
The imported names, identical to StructuralAnalysis.imports[].specifiers.

​
CallGraphEntry

A single caller→callee relationship, returned by the optional extractCallGraph method. 
export interface CallGraphEntry {
  caller: string;
  callee: string;
  lineNumber: number;
}
​
caller
string
required
Name of the function that contains the call site.
​
callee
string
required
Name (or expression text) of the function being called.
​
lineNumber
number
required
Line number of the call expression (1-indexed).

​
Implementing a custom plugin

To add support for a new language, implement AnalyzerPlugin and register it with the PluginRegistry. 
import type { AnalyzerPlugin, StructuralAnalysis, ImportResolution } from "@understand-anything/core";
import { PluginRegistry } from "@understand-anything/core";

export class PythonPlugin implements AnalyzerPlugin {
  readonly name = "python";
  readonly languages = ["python"];

  analyzeFile(filePath: string, content: string): StructuralAnalysis {
    // Parse the file and return structural info
    return {
      functions: [],
      classes: [],
      imports: [],
      exports: [],
    };
  }

  resolveImports(filePath: string, content: string): ImportResolution[] {
    // Resolve import paths
    return [];
  }

  // extractCallGraph is optional — omit it if not needed
}

// Register the plugin
const registry = new PluginRegistry();
registry.register(new PythonPlugin());
The registry maps the "python" language identifier to this plugin. Any file with a .py extension will automatically be routed to it via getPluginForFile.

Build docs developers (and LLMs) love

Get started for freeTalk to us