feat(engine): MATLAB extractor with .m disambiguation from ObjC

MATLAB shares .m with Objective-C. detectLanguage() now sniffs the first
4KB of file content: ObjC markers (@interface/@implementation/#import/
#include) → objc; otherwise MATLAB. EXTENSION_MAP still maps .m → objc
as the default; the heuristic only overrides when no ObjC markers exist.

Vendored grammar: acristoffers/tree-sitter-matlab (built locally via
tree-sitter-cli; upstream ships only Python wheels).

Author: Broccolito

engine/PATCHES.md

@@ -36,3 +36,15 @@ Perl — each documented as a numbered entry below when it lands.
   - `const_statement` wraps an inner `assignment` node
   - `macro_definition` has the same structure as `function_definition`
   - Call edges work via the standard `call_expression` in `callTypes`; `visitFunctionBody` recursively finds them
+
+### 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.
+- Extractor: `engine/src/extraction/languages/matlab.ts`
+- Tests: extraction + disambiguation tests in `engine/__tests__/extraction.test.ts` (`MATLAB Extraction` describe block; 14 tests total)
+- Notes: MATLAB grammar (acristoffers/tree-sitter-matlab) key AST facts confirmed empirically:
+  - `function_definition`: field `'name'` → function identifier; `function_output` optional named child for return values; `function_arguments` named child for params; `block` named child for body
+  - Three function forms: `function greet()`, `function result = hello(name)`, `function [a,b] = swap(x,y)` — all produce `function_definition` nodes with the same structure
+  - `function_call`: field `'name'` → callee identifier; used for call edges via `callTypes: ['function_call']`
+  - `assignment`: fields `'left'` and `'right'`; top-level identifier-lhs assignments → variable nodes
+  - Grammar does NOT use `call_expression` (unlike most other languages); uses `function_call` instead

engine/__tests__/extraction.test.ts

@@ -4571,3 +4571,161 @@ const MAX_SIZE = 1000
     expect(names).toContain('MAX_SIZE');
   });
 });
+
+describe('MATLAB Extraction', () => {
+  // ── Language detection ────────────────────────────────────────────────────
+  it('should detect MATLAB files via content heuristic (no ObjC markers)', () => {
+    // .m with MATLAB content → matlab
+    const matlabContent = `function result = hello(name)\n    result = name;\nend\n`;
+    expect(detectLanguage('hello.m', matlabContent)).toBe('matlab');
+  });
+
+  it('should detect ObjC .m files that have @interface', () => {
+    const objcContent = `@interface Foo : NSObject\n- (void)bar;\n@end\n`;
+    expect(detectLanguage('Foo.m', objcContent)).toBe('objc');
+  });
+
+  it('should detect ObjC .m files that have @implementation', () => {
+    const objcContent = `@implementation Foo\n- (void)bar {}\n@end\n`;
+    expect(detectLanguage('Foo.m', objcContent)).toBe('objc');
+  });
+
+  it('should detect ObjC .m files that have #import', () => {
+    const objcContent = `#import <Foundation/Foundation.h>\n\n@implementation Foo\n@end\n`;
+    expect(detectLanguage('Foo.m', objcContent)).toBe('objc');
+  });
+
+  it('should default to matlab for .m with no ObjC markers (just comments)', () => {
+    const commentOnly = `% This is a MATLAB comment\n% No function defined yet\n`;
+    expect(detectLanguage('script.m', commentOnly)).toBe('matlab');
+  });
+
+  it('should fall back to objc for .m with no content provided', () => {
+    // When source is omitted, EXTENSION_MAP default (objc) is returned
+    expect(detectLanguage('unknown.m')).toBe('objc');
+  });
+
+  it('should report MATLAB as supported', () => {
+    expect(isLanguageSupported('matlab')).toBe(true);
+    expect(getSupportedLanguages()).toContain('matlab');
+  });
+
+  // ── File node ─────────────────────────────────────────────────────────────
+  it('should create a file node for MATLAB files', () => {
+    const code = `
+function result = hello(name)
+    result = ['Hello, ', name];
+end
+`;
+    const result = extractFromSource('hello.m', code);
+
+    const fileNode = result.nodes.find((n) => n.kind === 'file');
+    expect(fileNode).toBeDefined();
+    expect(fileNode?.name).toBe('hello.m');
+    expect(fileNode?.language).toBe('matlab');
+  });
+
+  // ── Function extraction ───────────────────────────────────────────────────
+  it('should extract a simple void function (no output)', () => {
+    const code = `
+function greet()
+    disp('hello');
+end
+`;
+    const result = extractFromSource('greet.m', code);
+
+    const functions = result.nodes.filter((n) => n.kind === 'function');
+    expect(functions).toHaveLength(1);
+    expect(functions[0].name).toBe('greet');
+    expect(functions[0].language).toBe('matlab');
+  });
+
+  it('should extract a function with a single return value', () => {
+    const code = `
+function result = hello(name)
+    result = ['Hello, ', name];
+end
+`;
+    const result = extractFromSource('hello.m', code);
+
+    const funcNode = result.nodes.find((n) => n.kind === 'function');
+    expect(funcNode).toBeDefined();
+    expect(funcNode?.name).toBe('hello');
+    expect(funcNode?.signature).toContain('hello');
+  });
+
+  it('should extract a function with multiple return values', () => {
+    const code = `
+function [a, b] = swap(x, y)
+    a = y;
+    b = x;
+end
+`;
+    const result = extractFromSource('swap.m', code);
+
+    const funcNode = result.nodes.find((n) => n.kind === 'function');
+    expect(funcNode).toBeDefined();
+    expect(funcNode?.name).toBe('swap');
+  });
+
+  it('should extract multiple function definitions', () => {
+    const code = `
+function result = hello(name)
+    result = ['Hello, ', name];
+end
+
+function greet()
+    hello('world');
+end
+
+function main()
+    greet();
+end
+`;
+    const result = extractFromSource('funcs.m', 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');
+  });
+
+  // ── Call edges ────────────────────────────────────────────────────────────
+  it('should extract call edges from function bodies', () => {
+    const code = `
+function result = hello(name)
+    result = ['Hello, ', name];
+end
+
+function greet()
+    hello('world');
+end
+
+function main()
+    greet();
+end
+`;
+    const result = extractFromSource('calls.m', 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');
+  });
+
+  // ── Variable extraction ───────────────────────────────────────────────────
+  it('should extract top-level variable assignments', () => {
+    const code = `
+x = hello('test');
+y = 42;
+`;
+    const result = extractFromSource('script.m', code);
+
+    const variables = result.nodes.filter((n) => n.kind === 'variable');
+    const names = variables.map((v) => v.name);
+    expect(names).toContain('x');
+    expect(names).toContain('y');
+  });
+});

engine/src/extraction/grammars.ts

@@ -40,6 +40,7 @@ const WASM_GRAMMAR_FILES: Record<GrammarLanguage, string> = {
   objc: 'tree-sitter-objc.wasm',
   r: 'tree-sitter-r.wasm',
   julia: 'tree-sitter-julia.wasm',
+  matlab: 'tree-sitter-matlab.wasm',
 };
 
 /**
@@ -184,7 +185,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')
+      const wasmPath = (lang === 'pascal' || lang === 'scala' || lang === 'lua' || lang === 'luau' || lang === 'r' || lang === 'julia' || lang === 'matlab')
         ? path.join(__dirname, 'wasm', wasmFile)
         : require.resolve(`tree-sitter-wasms/out/${wasmFile}`);
       const language = await WasmLanguage.load(wasmPath);
@@ -234,7 +235,15 @@ export function getParser(language: Language): Parser | null {
 }
 
 /**
- * Detect language from file extension
+ * Detect language from file extension, with content-based disambiguation
+ * for ambiguous extensions.
+ *
+ * Currently disambiguates:
+ *   .h  — C vs C++ vs Objective-C (existing behaviour)
+ *   .m  — Objective-C vs MATLAB: ObjC has distinctive top-of-file markers
+ *          (@interface, @implementation, #import, #include). MATLAB has none.
+ *          If any ObjC marker appears in the first ~4 KB, treat as ObjC;
+ *          otherwise MATLAB.
  */
 export function detectLanguage(filePath: string, source?: string): Language {
   // Play `conf/routes` has no grammar — route through the no-symbol path; the
@@ -249,6 +258,13 @@ export function detectLanguage(filePath: string, source?: string): Language {
     if (looksLikeObjc(source)) return 'objc';
   }
 
+  // .m files could be Objective-C or MATLAB — check source content
+  // EXTENSION_MAP maps .m → objc as the safe default; override to matlab
+  // only when no ObjC markers are present.
+  if (lang === 'objc' && ext === '.m' && source) {
+    if (!looksLikeObjc4kb(source)) return 'matlab';
+  }
+
   return lang;
 }
 
@@ -269,6 +285,16 @@ function looksLikeObjc(source: string): boolean {
   return /@(?:interface|implementation|protocol|synthesize)\b/.test(sample);
 }
 
+/**
+ * Heuristic: does a .m file look like Objective-C (vs MATLAB)?
+ * Checks the first ~4 KB for ObjC-specific top-of-file markers.
+ * MATLAB files never start with @interface/@implementation or #import/#include.
+ */
+function looksLikeObjc4kb(source: string): boolean {
+  const sample = source.slice(0, 4096);
+  return /^\s*(@interface\b|@implementation\b|#import\b|#include\b)/m.test(sample);
+}
+
 /**
  * Check if a language is supported (has a grammar defined).
  * Returns true if the grammar exists, even if not yet loaded.
@@ -372,6 +398,7 @@ export function getLanguageDisplayName(language: Language): string {
     objc: 'Objective-C',
     r: 'R',
     julia: 'Julia',
+    matlab: 'MATLAB',
     yaml: 'YAML',
     twig: 'Twig',
     xml: 'XML',

engine/src/extraction/languages/index.ts

@@ -28,6 +28,7 @@ import { luauExtractor } from './luau';
 import { objcExtractor } from './objc';
 import { rExtractor } from './r';
 import { juliaExtractor } from './julia';
+import { matlabExtractor } from './matlab';
 
 export const EXTRACTORS: Partial<Record<Language, LanguageExtractor>> = {
   typescript: typescriptExtractor,
@@ -53,4 +54,5 @@ export const EXTRACTORS: Partial<Record<Language, LanguageExtractor>> = {
   objc: objcExtractor,
   r: rExtractor,
   julia: juliaExtractor,
+  matlab: matlabExtractor,
 };

engine/src/extraction/languages/matlab.ts

@@ -0,0 +1,133 @@
+import { getNodeText, getChildByField } from '../tree-sitter-helpers';
+import type { LanguageExtractor, ExtractorContext } from '../tree-sitter-types';
+import type { Node as SyntaxNode } from 'web-tree-sitter';
+
+/**
+ * MATLAB Language Extractor
+ *
+ * MATLAB function syntax:
+ *   function greet()                       — no output
+ *   function result = hello(name)          — single output
+ *   function [a, b] = swap(x, y)           — multiple outputs
+ *
+ * Grammar used: acristoffers/tree-sitter-matlab (vendored WASM)
+ *
+ * Key node kinds confirmed by AST inspection:
+ *   function_definition — function definitions (all three forms above)
+ *     field 'name': identifier — the function name
+ *     field 'function_arguments': argument list node
+ *     function_output (optional named child): single or multi-return marker
+ *     block: function body
+ *
+ *   function_call — foo(args)
+ *     field 'name': identifier — callee name
+ *
+ *   assignment — x = expr
+ *     field 'left': lhs (identifier or complex expression)
+ *     field 'right': rhs
+ *
+ * MATLAB has no class or import syntax in the file-based sense (classdef
+ * exists but is handled separately; scripts have no module imports). We
+ * focus on functions, calls, and top-level variable assignments.
+ */
+
+export const matlabExtractor: LanguageExtractor = {
+  // All interesting patterns handled by visitNode
+  functionTypes: [],
+  classTypes: [],
+  methodTypes: [],
+  interfaceTypes: [],
+  structTypes: [],
+  enumTypes: [],
+  typeAliasTypes: [],
+  importTypes: [],
+  callTypes: ['function_call'],
+  variableTypes: [],
+
+  // Field names — used as fallbacks; primary extraction is in visitNode
+  nameField: 'name',
+  bodyField: 'body',
+  paramsField: 'function_arguments',
+  returnField: undefined,
+
+  isAsync: () => false,
+  isStatic: () => false,
+
+  extractImport: () => null,
+
+  /**
+   * Custom visitor for MATLAB's AST.
+   *
+   * Handles:
+   *   function_definition  → 'function' node (all return forms)
+   *   assignment with identifier lhs → 'variable' node (top-level only)
+   */
+  visitNode: (node: SyntaxNode, ctx: ExtractorContext): boolean => {
+    const type = node.type;
+
+    // ── function_definition ────────────────────────────────────────────────
+    if (type === 'function_definition') {
+      // The 'name' field always holds the function identifier
+      const nameNode = getChildByField(node, 'name');
+      if (!nameNode) return false;
+      const name = getNodeText(nameNode, ctx.source);
+
+      // Build signature string: [outputs] = name(params)
+      // Find function_output (optional) and function_arguments among named children
+      let outputText = '';
+      let paramsText = '';
+      let bodyNode: SyntaxNode | null = null;
+
+      for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (!child || !child.isNamed) continue;
+        if (child.type === 'function_output') {
+          outputText = getNodeText(child, ctx.source); // e.g. "result =" or "[a, b] ="
+        } else if (child.type === 'function_arguments') {
+          paramsText = getNodeText(child, ctx.source); // e.g. "(name)" or "()"
+        } else if (child.type === 'block') {
+          bodyNode = child;
+        }
+      }
+
+      const signature = outputText
+        ? `${outputText} ${name}${paramsText}`
+        : `${name}${paramsText}`;
+
+      const funcNode = ctx.createNode('function', name, node, {
+        signature,
+        isAsync: false,
+        isStatic: false,
+      });
+      if (funcNode && bodyNode) {
+        ctx.pushScope(funcNode.id);
+        ctx.visitFunctionBody(bodyNode, funcNode.id);
+        ctx.popScope();
+      }
+      return true;
+    }
+
+    // ── assignment ─────────────────────────────────────────────────────────
+    if (type === 'assignment') {
+      const lhsNode = getChildByField(node, 'left');
+      const rhsNode = getChildByField(node, 'right');
+      if (!lhsNode || !rhsNode) return false;
+
+      // Only extract simple identifier assignments at script scope
+      if (lhsNode.type !== 'identifier') return false;
+
+      const name = getNodeText(lhsNode, ctx.source);
+      const initValue = getNodeText(rhsNode, ctx.source).slice(0, 100);
+      const initSignature = initValue
+        ? `= ${initValue}${initValue.length >= 100 ? '...' : ''}`
+        : undefined;
+
+      ctx.createNode('variable', name, node, { signature: initSignature });
+      // Visit rhs to capture any calls in the initializer
+      ctx.visitNode(rhsNode);
+      return true;
+    }
+
+    return false;
+  },
+};