feat(engine): Perl language extractor (.pl/.pm/.t files)

Adds tree-sitter-perl grammar (tree-sitter-perl/tree-sitter-perl v1.0.2)
wired through the standard LanguageExtractor pattern. Extracts named
subroutines, function calls, package declarations, and use/require
imports.

Author: Broccolito

engine/PATCHES.md

@@ -37,6 +37,22 @@ Perl — each documented as a numbered entry below when it lands.
   - `macro_definition` has the same structure as `function_definition`
   - Call edges work via the standard `call_expression` in `callTypes`; `visitFunctionBody` recursively finds them
 
+### Perl (added 2026-05-30)
+- WASM grammar: `engine/src/extraction/wasm/tree-sitter-perl.wasm` from tree-sitter-perl/tree-sitter-perl v1.0.2
+- Extension map: `.pl`, `.pm`, `.t` → `perl`
+- Extractor: `engine/src/extraction/languages/perl.ts`
+- Tests: added `Perl Extraction` describe block in `engine/__tests__/extraction.test.ts` (10 tests)
+- Notes: Perl grammar (tree-sitter-perl v1.0.2) key AST facts confirmed empirically:
+  - `subroutine_declaration_statement`: namedChild[0]=`bareword` (name), namedChild[1]=`block` (body); no named fields
+  - `function_call_expression`: child[0] has type `function` (callee); no named fields
+  - `ambiguous_function_call_expression`: like function_call_expression but wraps e.g. `print foo()`; child[0] type=`function`
+  - `method_call_expression`: `$obj->method()` or `Class->method()`; child[2] type=`method` (method name)
+  - `use_statement`: namedChild[0] is a `package` node holding the module name
+  - `require_expression`: namedChild[0] is a `bareword` holding the module name
+  - `package_statement`: namedChild[0] is a `package` node holding the package name (re-uses `package` type for both the keyword and the identifier)
+  - The grammar does NOT use named fields (childForFieldName returns null); all extraction uses `namedChild(i)` or `child(i)` by index
+  - `resolveName` hook is used to extract callee names from all three call node types
+
 ### MATLAB (added 2026-05-30)
 - WASM grammar: `engine/src/extraction/wasm/tree-sitter-matlab.wasm` built locally from acristoffers/tree-sitter-matlab (upstream ships only Python wheels)
 - Extension map: `.m` is shared with Objective-C; disambiguated by `detectLanguage(filePath, content)` content heuristic that checks for ObjC markers (`@interface`, `@implementation`, `#import`, `#include`) in the first 4 KB. `EXTENSION_MAP` still maps `.m` → `objc` as the default; the heuristic overrides to `matlab` only when no ObjC markers are found.

engine/__tests__/extraction.test.ts

@@ -4729,3 +4729,205 @@ y = 42;
     expect(names).toContain('y');
   });
 });
+
+describe('Perl Extraction', () => {
+  // ── Language detection ────────────────────────────────────────────────────
+  it('should detect Perl files by extension', () => {
+    expect(detectLanguage('script.pl')).toBe('perl');
+    expect(detectLanguage('MyModule.pm')).toBe('perl');
+    expect(detectLanguage('foo.t')).toBe('perl');
+    expect(detectLanguage('src/lib/Utils.pm')).toBe('perl');
+  });
+
+  it('should report Perl as supported', () => {
+    expect(isLanguageSupported('perl')).toBe(true);
+    expect(getSupportedLanguages()).toContain('perl');
+  });
+
+  // ── File node ─────────────────────────────────────────────────────────────
+  it('should create a file node for Perl files', () => {
+    const code = `
+package MyPackage;
+
+sub hello {
+    my ($name) = @_;
+    return "Hello";
+}
+
+1;
+`;
+    const result = extractFromSource('MyPackage.pm', code);
+
+    const fileNode = result.nodes.find((n) => n.kind === 'file');
+    expect(fileNode).toBeDefined();
+    expect(fileNode?.name).toBe('MyPackage.pm');
+    expect(fileNode?.language).toBe('perl');
+  });
+
+  // ── Function (sub) extraction ─────────────────────────────────────────────
+  it('should extract named subroutines', () => {
+    const code = `
+package MyPackage;
+
+sub hello {
+    my ($name) = @_;
+    return "Hello";
+}
+
+sub greet {
+    return hello("world");
+}
+
+sub main {
+    print greet();
+}
+
+1;
+`;
+    const result = extractFromSource('script.pl', code);
+
+    const functions = result.nodes.filter((n) => n.kind === 'function');
+    const names = functions.map((f) => f.name).sort();
+    expect(names).toContain('hello');
+    expect(names).toContain('greet');
+    expect(names).toContain('main');
+    expect(functions[0].language).toBe('perl');
+  });
+
+  it('should include sub name in function signature', () => {
+    const code = `
+sub hello {
+    return "hi";
+}
+`;
+    const result = extractFromSource('hello.pl', code);
+
+    const funcNode = result.nodes.find((n) => n.kind === 'function');
+    expect(funcNode).toBeDefined();
+    expect(funcNode?.name).toBe('hello');
+    expect(funcNode?.signature).toContain('hello');
+  });
+
+  // ── Call edges ────────────────────────────────────────────────────────────
+  it('should extract function call edges', () => {
+    const code = `
+sub hello {
+    return "Hello";
+}
+
+sub greet {
+    return hello("world");
+}
+
+sub main {
+    print greet();
+}
+`;
+    const result = extractFromSource('calls.pl', code);
+
+    const calls = result.unresolvedReferences.filter((r) => r.referenceKind === 'calls');
+    const callNames = calls.map((c) => c.referenceName);
+    expect(callNames).toContain('hello');
+    expect(callNames).toContain('greet');
+  });
+
+  // ── Package declaration ───────────────────────────────────────────────────
+  it('should extract package declaration as a module node', () => {
+    const code = `
+package MyPackage;
+
+sub hello { return "hi"; }
+
+1;
+`;
+    const result = extractFromSource('MyPackage.pm', code);
+
+    const modules = result.nodes.filter((n) => n.kind === 'module');
+    expect(modules).toHaveLength(1);
+    expect(modules[0].name).toBe('MyPackage');
+    expect(modules[0].language).toBe('perl');
+  });
+
+  // ── use/require imports ───────────────────────────────────────────────────
+  it('should extract use statements as import nodes', () => {
+    const code = `
+use strict;
+use warnings;
+use MyModule qw(foo bar);
+`;
+    const result = extractFromSource('script.pl', code);
+
+    const imports = result.nodes.filter((n) => n.kind === 'import');
+    const names = imports.map((i) => i.name);
+    expect(names).toContain('strict');
+    expect(names).toContain('warnings');
+    expect(names).toContain('MyModule');
+  });
+
+  it('should extract require expressions as import nodes', () => {
+    const code = `
+require AnotherModule;
+require 'some_file.pl';
+`;
+    const result = extractFromSource('script.pl', code);
+
+    const imports = result.nodes.filter((n) => n.kind === 'import');
+    const names = imports.map((i) => i.name);
+    expect(names).toContain('AnotherModule');
+  });
+
+  // ── Full file extraction ──────────────────────────────────────────────────
+  it('should extract a complete Perl module correctly', () => {
+    const code = `
+package MyPackage;
+
+use strict;
+use warnings;
+use MyModule qw(foo bar);
+require AnotherModule;
+
+sub hello {
+    my ($name) = @_;
+    return "Hello";
+}
+
+sub greet {
+    return hello("world");
+}
+
+sub main {
+    print greet();
+}
+
+1;
+`;
+    const result = extractFromSource('MyPackage.pm', code);
+
+    // File node
+    expect(result.nodes.find((n) => n.kind === 'file')).toBeDefined();
+
+    // Package → module node
+    const modules = result.nodes.filter((n) => n.kind === 'module');
+    expect(modules.map((m) => m.name)).toContain('MyPackage');
+
+    // Subs → function nodes
+    const functions = result.nodes.filter((n) => n.kind === 'function');
+    const funcNames = functions.map((f) => f.name);
+    expect(funcNames).toContain('hello');
+    expect(funcNames).toContain('greet');
+    expect(funcNames).toContain('main');
+
+    // use/require → import nodes
+    const imports = result.nodes.filter((n) => n.kind === 'import');
+    const importNames = imports.map((i) => i.name);
+    expect(importNames).toContain('strict');
+    expect(importNames).toContain('MyModule');
+    expect(importNames).toContain('AnotherModule');
+
+    // Call edges
+    const calls = result.unresolvedReferences.filter((r) => r.referenceKind === 'calls');
+    const callNames = calls.map((c) => c.referenceName);
+    expect(callNames).toContain('hello');
+    expect(callNames).toContain('greet');
+  });
+});

engine/src/extraction/grammars.ts

@@ -41,6 +41,7 @@ const WASM_GRAMMAR_FILES: Record<GrammarLanguage, string> = {
   r: 'tree-sitter-r.wasm',
   julia: 'tree-sitter-julia.wasm',
   matlab: 'tree-sitter-matlab.wasm',
+  perl: 'tree-sitter-perl.wasm',
 };
 
 /**
@@ -101,6 +102,9 @@ export const EXTENSION_MAP: Record<string, Language> = {
   '.R': 'r',
   '.r': 'r',
   '.jl': 'julia',
+  '.pl': 'perl',
+  '.pm': 'perl',
+  '.t': 'perl',
   // XML: file-level tracking; the MyBatis extractor matches `<mapper namespace="...">`
   // shape and emits SQL-statement nodes (other XML returns empty).
   '.xml': 'xml',
@@ -185,7 +189,7 @@ export async function loadGrammarsForLanguages(languages: Language[]): Promise<v
       // ABI-13 build that corrupts the shared WASM heap under web-tree-sitter
       // 0.25 (drops nested calls/imports on every file after the first); we
       // vendor the upstream ABI-15 wasm instead.
-      const wasmPath = (lang === 'pascal' || lang === 'scala' || lang === 'lua' || lang === 'luau' || lang === 'r' || lang === 'julia' || lang === 'matlab')
+      const wasmPath = (lang === 'pascal' || lang === 'scala' || lang === 'lua' || lang === 'luau' || lang === 'r' || lang === 'julia' || lang === 'matlab' || lang === 'perl')
         ? path.join(__dirname, 'wasm', wasmFile)
         : require.resolve(`tree-sitter-wasms/out/${wasmFile}`);
       const language = await WasmLanguage.load(wasmPath);
@@ -399,6 +403,7 @@ export function getLanguageDisplayName(language: Language): string {
     r: 'R',
     julia: 'Julia',
     matlab: 'MATLAB',
+    perl: 'Perl',
     yaml: 'YAML',
     twig: 'Twig',
     xml: 'XML',

engine/src/extraction/languages/index.ts

@@ -29,6 +29,7 @@ import { objcExtractor } from './objc';
 import { rExtractor } from './r';
 import { juliaExtractor } from './julia';
 import { matlabExtractor } from './matlab';
+import { perlExtractor } from './perl';
 
 export const EXTRACTORS: Partial<Record<Language, LanguageExtractor>> = {
   typescript: typescriptExtractor,
@@ -55,4 +56,5 @@ export const EXTRACTORS: Partial<Record<Language, LanguageExtractor>> = {
   r: rExtractor,
   julia: juliaExtractor,
   matlab: matlabExtractor,
+  perl: perlExtractor,
 };