How to Extend Egonex Plugins with Custom Framework Support

To extend Egonex plugins with custom framework support, implement a parser for the new file type, create an extractor to harvest symbols from the AST, and register both in the central plugin registry at packages/core/src/plugins/registry.ts.

The Egonex-AI/Understand-Anything repository provides a modular architecture that makes it straightforward to extend Egonex plugins with custom framework support. By implementing parsers and extractors in the packages/core/src/plugins/ directory, you can teach the system to analyze proprietary DSLs, internal libraries, or niche build tools. This guide demonstrates the exact file paths and function signatures required to integrate a new framework into the knowledge graph.

Understanding the Plugin Architecture

The Egonex plugin system relies on two core abstractions: parsers that produce tree-sitter-compatible ASTs from source files, and extractors that traverse these trees to emit standardized Symbol objects. The registry.ts file maps file extensions to specific parser-extractor pairs, enabling the core to automatically route files to the correct handlers without modifying downstream agents.

Step 1 – Create a Parser for the New Framework

Implement the Parser Module

Create a new parser file under packages/core/src/plugins/parsers/. This module must initialize the tree-sitter parser with the custom grammar and return a configured Parser instance.

// packages/core/src/plugins/parsers/myf-parser.ts
import { Parser } from 'web-tree-sitter';

export async function initMyfParser(): Promise<Parser> {
  const parser = new Parser();
  // Assume we have a compiled MyFramework grammar at ./myf.wasm
  const Lang = await import('./myf.wasm');
  await parser.setLanguage(Lang);
  return parser;
}

Export the Parser

Update the parsers/index.ts barrel file to expose the new parser to the core.

// packages/core/src/plugins/parsers/index.ts
export * from './myf-parser';

Step 2 – Build the Symbol Extractor

Write the Extractor Logic

Implement an extractor in packages/core/src/plugins/extractors/ that converts AST nodes into the internal Symbol type defined in the core types.

// packages/core/src/plugins/extractors/myf-extractor.ts
import type { Node } from 'web-tree-sitter';
import { Symbol } from '../../types';

export function extractMyfSymbols(root: Node): Symbol[] {
  const symbols: Symbol[] = [];

  // Traverse the tree and capture component declarations
  root.walk((node) => {
    if (node.type === 'component_declaration') {
      const name = node.namedChild(0)!.text;
      symbols.push({
        name,
        kind: 'Component',
        location: node.startPosition,
        // Framework-specific metadata can be added here
        meta: { framework: 'MyFramework' },
      });
    }
  });

  return symbols;
}

Register the Extractor

Add the export to the extractors index file so the registry can import it.

// packages/core/src/plugins/extractors/index.ts
export * from './myf-extractor';

Step 3 – Register the Framework in the Plugin Registry

Open packages/core/src/plugins/registry.ts and append a new entry to the languageRegistry array. This binds the file extension to the parser initializer and extractor function.

// packages/core/src/plugins/registry.ts
import { initMyfParser } from '../parsers/myf-parser';
import { extractMyfSymbols } from '../extractors/myf-extractor';

export const languageRegistry = [
  // Existing entries …
  {
    languageId: 'myf',
    extensions: ['.myf'],
    parserInit: initMyfParser,
    extractor: extractMyfSymbols,
  },
];

Step 4 – Validate with Integration Tests

Create a test file under packages/core/src/__tests__/ to verify the parser and extractor integration. The existing framework-registry.test.ts suite validates that the core discovers new frameworks automatically, but you should add specific tests for your logic.

// packages/core/src/__tests__/myf-integration.test.ts
import { parseAndExtract } from '../../src/plugins/registry';
import { readFileSync } from 'fs';
import { join } from 'path';

test('MyFramework parser & extractor', async () => {
  const src = readFileSync(join(__dirname, 'fixtures/sample.myf'), 'utf8');
  const symbols = await parseAndExtract('myf', src);
  expect(symbols).toContainEqual(
    expect.objectContaining({ name: 'MyButton', kind: 'Component' })
  );
});

Run the core test suite to confirm the integration:

pnpm --filter @understand-anything/core test

Summary

• Implement a parser in packages/core/src/plugins/parsers/ that returns a tree-sitter-compatible AST for your framework's file types.
• Create an extractor in packages/core/src/plugins/extractors/ that walks the AST and yields standardized Symbol objects.
• Register the pair in packages/core/src/plugins/registry.ts by mapping file extensions to the parserInit initializer and extractor function.
• Validate the integration using the test suite in packages/core/src/__tests__/ to ensure the framework is discovered and processed correctly by the knowledge graph.

Frequently Asked Questions

What file types can I add support for when I extend Egonex plugins?

The plugin system accepts any file type that can be parsed into a tree-sitter-compatible AST. You must provide a compiled grammar (.wasm) and an initialization function in packages/core/src/plugins/parsers/ that returns a configured Parser instance.

Do I need to modify the core agents to recognize new symbols?

No. Once registered in registry.ts, the higher-level agents such as the graph-builder and tour-generator automatically ingest symbols from your extractor. The agents consume the standardized Symbol type regardless of the original framework, so no agent-side changes are required.

How does the registry map files to my custom parser?

The languageRegistry array in registry.ts matches file extensions against the extensions property. When a file with a registered extension is encountered, the core invokes the associated parserInit function and passes the resulting AST to your extractor function.

Can I add framework-specific metadata to extracted symbols?

Yes. The Symbol type accepts a meta object where you can store custom fields. In your extractor, populate this object with framework-specific details such as component hierarchies, version tags, or proprietary attributes that downstream tools can utilize.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}