Merge pull request giancarloerra#67 from SIRTHEO/feat/lua-symbol-graph

feat(graph): Lua symbol/call extraction + fix file discovery for whitelist .gitignore

Author: giancarloerra

package-lock.json

@@ -70,6 +70,7 @@
     "@ast-grep/lang-go": "^0.0.5",
     "@ast-grep/lang-java": "^0.0.6",
     "@ast-grep/lang-kotlin": "^0.0.6",
+    "@ast-grep/lang-lua": "^0.0.7",
     "@ast-grep/lang-php": "^0.0.6",
     "@ast-grep/lang-python": "^0.0.5",
     "@ast-grep/lang-ruby": "^0.0.6",

package.json

@@ -492,6 +492,7 @@ export function ensureDynamicLanguages(): void {
       ["scala",   "@ast-grep/lang-scala"],
       ["bash",    "@ast-grep/lang-bash"],
       ["php",     "@ast-grep/lang-php"],
+      ["lua",     "@ast-grep/lang-lua"],
     ];
 
     for (const [name, pkg] of langPackages) {
@@ -578,7 +579,7 @@ export function getAstGrepLang(ext: string): Lang | string | null {
  * Get all source files in a project for graph analysis.
  * Includes files with known AST grammars and any extra extensions.
  */
-async function getGraphableFiles(
+export async function getGraphableFiles(
   projectPath: string,
   extraExts?: Set<string>,
 ): Promise<string[]> {
@@ -598,7 +599,7 @@ async function getGraphableFiles(
       const fullPath = path.join(dir, entry.name);
       const relPath = toForwardSlash(path.relative(projectPath, fullPath));
 
-      if (shouldIgnore(ig, relPath)) continue;
+      if (shouldIgnore(ig, entry.isDirectory() ? `${relPath}/` : relPath)) continue;
 
       if (entry.isDirectory()) {
         await walk(fullPath);

src/services/code-graph.ts

@@ -142,7 +142,10 @@ export function extractSymbolsAndCalls(
     if (langKey === "bash") {
       return extractFromBash(source, relativePath, language, moduleSymbol);
     }
-    // Dart, Lua, Svelte, Vue and others fall through to the regex fallback.
+    if (langKey === "lua") {
+      return extractFromLua(source, relativePath, language, moduleSymbol);
+    }
+    // Dart, Svelte, Vue and others fall through to the regex fallback.
     return extractFromRegex(source, relativePath, language, moduleSymbol);
   } catch (err) {
     if (!symbolExtractionWarned.has(langKey)) {
@@ -160,6 +163,119 @@ export function extractSymbolsAndCalls(
   }
 }
 
+// ── Lua (namespace tables: function T.f(), local function f(), T.f = function()) ──
+
+/**
+ * Lua has no node-kind-specific extractor upstream and previously fell through
+ * to the regex fallback, which records `Mod` for `function Mod.parse()`.
+ * This walks the ast-grep Lua tree so namespace-table style (`Table.method`,
+ * the common Lua module/OOP idiom) resolves to precise qualified symbols plus
+ * their call sites.
+ */
+function extractFromLua(
+  source: string,
+  file: string,
+  language: string,
+  moduleSym: SymbolNode,
+): ExtractedSymbols {
+  const root = parse("lua" as unknown as Lang, source).root();
+  const symbols: SymbolNode[] = [moduleSym];
+  const scopes: ScopeFrame[] = [];
+  const NAME = new Set(["dot_index_expression", "method_index_expression", "identifier"]);
+  const KW = new Set([
+    "if", "for", "while", "return", "function", "local", "then", "do", "end",
+    "and", "or", "not", "elseif", "else", "in", "repeat", "until", "nil", "true", "false",
+  ]);
+  // biome-ignore lint/suspicious/noExplicitAny: ast-grep node type leaks through
+  const kidsOf = (n: any): any[] => {
+    try {
+      return n.children();
+    } catch {
+      return [];
+    }
+  };
+  const shortName = (qn: string): string => {
+    const parts = qn.split(/[.:]/);
+    return parts[parts.length - 1];
+  };
+  // biome-ignore lint/suspicious/noExplicitAny: ast-grep node type leaks through
+  const addSym = (nameNode: any, rangeNode: any): void => {
+    const qn = nameNode.text().replace(/\s+/g, "");
+    if (!/^[A-Za-z_][\w]*([.:][A-Za-z_][\w]*)*$/.test(qn)) return;
+    const range = rangeNode.range();
+    const startLine = range.start.line + 1;
+    const endLine = range.end.line + 1;
+    const sym: SymbolNode = {
+      id: makeId(file, qn, startLine),
+      name: shortName(qn),
+      qualifiedName: qn,
+      kind: /[.:]/.test(qn) ? "method" : "function",
+      file,
+      line: startLine,
+      endLine,
+      language,
+    };
+    symbols.push(sym);
+    scopes.push({ name: qn, startLine, endLine, symbolId: sym.id });
+  };
+
+  // `function T.f()`, `function T:m()`, `function f()`, `local function f()` —
+  // the name is the DIRECT child before `parameters`, not a body expression.
+  for (const fn of safeFindAll(root, "function_declaration")) {
+    const kids = kidsOf(fn);
+    // biome-ignore lint/suspicious/noExplicitAny: ast-grep node type leaks through
+    const pIdx = kids.findIndex((c: any) => c.kind() === "parameters");
+    const limit = pIdx < 0 ? kids.length : pIdx;
+    // biome-ignore lint/suspicious/noExplicitAny: ast-grep node type leaks through
+    let nameNode: any = null;
+    for (let i = 0; i < limit; i++) {
+      if (NAME.has(kids[i].kind())) {
+        nameNode = kids[i];
+        break;
+      }
+    }
+    if (nameNode) addSym(nameNode, fn);
+  }
+
+  // `T.f = function() … end` / `local f = function() … end` — the RHS must be
+  // DIRECTLY a function_definition (don't match nested anonymous functions).
+  for (const assign of safeFindAll(root, "assignment_statement")) {
+    const kids = kidsOf(assign);
+    // biome-ignore lint/suspicious/noExplicitAny: ast-grep node type leaks through
+    const rhs = kids.find((c: any) => c.kind() === "expression_list");
+    if (!rhs) continue;
+    const rhs0 = kidsOf(rhs)[0];
+    if (!rhs0 || rhs0.kind() !== "function_definition") continue;
+    // biome-ignore lint/suspicious/noExplicitAny: ast-grep node type leaks through
+    const vl = kids.find((c: any) => c.kind() === "variable_list");
+    const nameNode = vl ? kidsOf(vl)[0] : null;
+    if (nameNode && NAME.has(nameNode.kind())) addSym(nameNode, assign);
+  }
+
+  // Calls — attribute each to its enclosing function scope (or <module>).
+  const rawCalls: ExtractedSymbols["rawCalls"] = [];
+  for (const call of safeFindAll(root, "function_call")) {
+    const fnExpr = kidsOf(call)[0];
+    if (!fnExpr) continue;
+    const ids = safeFindAll(fnExpr, "identifier");
+    const callee =
+      ids.length > 0
+        ? ids[ids.length - 1].text()
+        : fnExpr.kind() === "identifier"
+          ? fnExpr.text()
+          : null;
+    if (!callee || KW.has(callee)) continue;
+    const line = call.range().start.line + 1;
+    rawCalls.push({
+      callerId: findCallerId(scopes, line, moduleSym.id),
+      calleeName: callee,
+      callSite: { file, line },
+    });
+  }
+
+  return { symbols, rawCalls };
+}
+
 // ── JS / TS / TSX ────────────────────────────────────────────────────────
 
 function extractFromTsLike(

src/services/graph-symbols.ts

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Giancarlo Erra - Altaire Limited
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { ensureDynamicLanguages, getGraphableFiles } from "../../src/services/code-graph.js";
+
+// Regression for the whitelist .gitignore discovery fix: a `/*` then `!/src/`
+// pattern ignores everything at the root but re-includes `src/`. The old walk
+// passed `src` (no trailing slash) to shouldIgnore, which `/*` matched, so the
+// walk bailed and produced an empty graph. Passing `src/` lets it descend and
+// the files under the re-included directory are actually picked up.
+describe("getGraphableFiles — whitelist .gitignore", () => {
+  let root: string;
+
+  beforeAll(() => {
+    ensureDynamicLanguages();
+    root = fs.mkdtempSync(path.join(os.tmpdir(), "socraticode-discovery-"));
+    fs.mkdirSync(path.join(root, "src"), { recursive: true });
+    fs.writeFileSync(path.join(root, ".gitignore"), "/*\n!/src/\n");
+    fs.writeFileSync(
+      path.join(root, "src", "mod.lua"),
+      "local function f()\n  return 1\nend\nreturn f\n",
+    );
+    // A root-level file the `/*` pattern should keep ignored.
+    fs.writeFileSync(path.join(root, "ignored.lua"), "return 1\n");
+  });
+
+  afterAll(() => {
+    try {
+      fs.rmSync(root, { recursive: true, force: true });
+    } catch {
+      // ignore cleanup errors
+    }
+  });
+
+  it("descends into re-included src/ and discovers its files", async () => {
+    const files = await getGraphableFiles(root);
+    expect(files).toContain("src/mod.lua");
+    // The `/*` pattern still ignores top-level entries that are not re-included.
+    expect(files).not.toContain("ignored.lua");
+  });
+});

tests/unit/graph-discovery.test.ts

@@ -370,26 +370,48 @@ main() {
     });
   });
 
-  describe("Regex fallback (Dart, Lua, Svelte, Vue, unknown)", () => {
-    it("handles Dart via regex fallback", () => {
+  describe("Lua", () => {
+    it("extracts namespace-table, method, local, and assignment function forms", () => {
       const src = `
-String greet(String name) {
-  return 'Hi $name';
-}
+local T = {}
 
-class Foo {
-  int bar() => 1;
-}
+function T.method(a)
+  return a
+end
+
+function T:m()
+  return self
+end
+
+local function helper()
+  return 1
+end
+
+T.f = function()
+  return 2
+end
+
+return T
 `;
-      const out = extractSymbolsAndCalls(src, "dart" as unknown as Lang, ".dart", "main.dart");
-      // regex fallback should at least produce <module> and not throw
-      expect(out.symbols.some((s) => s.name === "<module>")).toBe(true);
+      const out = extractSymbolsAndCalls(src, "lua" as unknown as Lang, ".lua", "init.lua");
       const names = out.symbols.map((s) => s.name);
-      // best-effort detection: should find at least one named symbol
-      expect(names.length).toBeGreaterThanOrEqual(1);
+      const qnames = out.symbols.map((s) => s.qualifiedName);
+      expect(names).toContain("<module>");
+      // qualified Table.method / T:m() forms resolve to precise method symbols
+      expect(qnames).toContain("T.method");
+      expect(qnames).toContain("T:m");
+      // `local function` keeps its bare name
+      expect(names).toContain("helper");
+      // `T.f = function() … end` assignment form
+      expect(qnames).toContain("T.f");
+      const kinds = out.symbols.filter((s) => s.qualifiedName === "T.method").map((s) => s.kind);
+      expect(kinds).toContain("method");
+      // colon-call form is also a method; the plain local function is not
+      expect(out.symbols.find((s) => s.qualifiedName === "T:m")?.kind).toBe("method");
+      expect(out.symbols.find((s) => s.qualifiedName === "helper")?.kind).toBe("function");
     });
 
-    it("handles Lua via regex fallback", () => {
+    it("attributes calls to the enclosing function", () => {
       const src = `
 function greet(name)
   return "hi " .. name
@@ -401,6 +423,72 @@ end
 `;
       const out = extractSymbolsAndCalls(src, "lua" as unknown as Lang, ".lua", "init.lua");
       expect(out.symbols.some((s) => s.name === "<module>")).toBe(true);
+      const greetCall = out.rawCalls.find((c) => c.calleeName === "greet");
+      expect(greetCall).toBeDefined();
+      expect(greetCall?.callerId).toContain("::helper#");
+    });
+
+    it("extracts the `local f = function() … end` assignment form", () => {
+      const src = `
+local f = function()
+  return 1
+end
+
+local g = function()
+  return f()
+end
+`;
+      const out = extractSymbolsAndCalls(src, "lua" as unknown as Lang, ".lua", "init.lua");
+      const names = out.symbols.map((s) => s.name);
+      expect(names).toContain("f");
+      expect(names).toContain("g");
+      expect(out.symbols.find((s) => s.qualifiedName === "f")?.kind).toBe("function");
+      // call to `f` lives inside `g`, so it is attributed to `g`
+      const fCall = out.rawCalls.find((c) => c.calleeName === "f");
+      expect(fCall?.callerId).toContain("::g#");
+    });
+
+    it("attributes top-level calls to <module> and resolves dotted callees", () => {
+      const src = `
+local M = require("mod")
+
+M.setup()
+
+local function run()
+  M.start()
+end
+`;
+      const out = extractSymbolsAndCalls(src, "lua" as unknown as Lang, ".lua", "init.lua");
+      // calls outside any function fall back to the synthetic <module> scope
+      const requireCall = out.rawCalls.find((c) => c.calleeName === "require");
+      expect(requireCall?.callerId).toContain("::<module>#");
+      // dotted callee `M.setup` resolves to the trailing identifier
+      const setupCall = out.rawCalls.find((c) => c.calleeName === "setup");
+      expect(setupCall).toBeDefined();
+      expect(setupCall?.callerId).toContain("::<module>#");
+      // `M.start()` lives inside `run`, so it is attributed there
+      const startCall = out.rawCalls.find((c) => c.calleeName === "start");
+      expect(startCall?.callerId).toContain("::run#");
+    });
+  });
+
+  describe("Regex fallback (Dart, Svelte, Vue, unknown)", () => {
+    it("handles Dart via regex fallback", () => {
+      const src = `
+String greet(String name) {
+  return 'Hi $name';
+}
+
+class Foo {
+  int bar() => 1;
+}
+`;
+      const out = extractSymbolsAndCalls(src, "dart" as unknown as Lang, ".dart", "main.dart");
+      // regex fallback should at least produce <module> and not throw
+      expect(out.symbols.some((s) => s.name === "<module>")).toBe(true);
+      const names = out.symbols.map((s) => s.name);
+      // best-effort detection: should find at least one named symbol
+      expect(names.length).toBeGreaterThanOrEqual(1);
     });
 
     it("handles unknown language without throwing", () => {