@possumtech/rummy.repo 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PossumTech Laboratories
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# rummy.repo
+
+Symbol extraction plugin for [Rummy](https://github.com/possumtech/rummy). Turns source files into structured symbol maps using [antlrmap](https://github.com/possumtech/antlrmap) (formal ANTLR4 grammars) with [Universal Ctags](https://ctags.io/) as a fallback.
+
+Antlrmap relies on ANTLR4's Grammar Zoo, mapping the symbol extraction process from formal EBNF grammars. More academically rigorous than tree-sitter heuristics, more accurate than ctags regex patterns, and more amenable to obscure and domain-specific languages. Don't like it? This is why symbol extraction is a plugin -- swap it out in 20 lines.
+
+## What It Does
+
+When files change in a Rummy project, this plugin extracts their symbols (functions, classes, methods, fields) and returns them as structured data. Rummy stores the formatted symbol tree in file entry attributes, giving the model a compact map of the codebase without reading every file.
+
+## Supported Languages
+
+Antlrmap provides grammar-based parsing for 36+ languages: JavaScript, TypeScript, Python, Rust, Go, Java, C, C++, Kotlin, PHP, Lua, SQL, Dart, Scala, Clojure, Elixir, Zig, R, Objective-C, Verilog, VHDL, Terraform, Fortran, Erlang, Thrift, GraphQL, AWK, JSON, TOML, Dockerfile, and more.
+
+Files with unsupported extensions fall back to Universal Ctags (if installed).
+
+## Installation
+
+Drop into your Rummy plugins directory:
+
+```bash
+cd ~/.rummy/plugins
+git clone https://github.com/possumtech/rummy.repo
+cd rummy.repo/main
+npm install
+```
+
+Rummy loads plugins from `~/.rummy/plugins/` on startup. No configuration required.
+
+## Usage
+
+The plugin registers automatically via the standard Rummy plugin contract. No manual setup needed.
+
+```js
+// Rummy's plugin loader calls this automatically:
+import RepoMapPlugin from "@possumtech/rummy.repo";
+RepoMapPlugin.register(hooks);
+```
+
+### formatSymbols
+
+The plugin exposes a `formatSymbols` helper for rendering symbol arrays as indented text:
+
+```js
+import RepoMapPlugin from "@possumtech/rummy.repo";
+
+const text = RepoMapPlugin.formatSymbols(symbols);
+// class MyClass L1
+//   method doThing(a, b) L5
+//   field name L3
+```
+
+## Development
+
+```bash
+npm test          # lint + unit tests (80% coverage threshold)
+npm run lint      # biome check
+```
+
+Requires Node.js >= 25.
+
+## License
+
+MIT -- PossumTech Laboratories

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@possumtech/rummy.repo",
+	"version": "0.0.1",
+	"description": "Rummy plugin for symbol extraction via antlrmap and ctags",
+	"keywords": [
+		"rummy",
+		"repomap",
+		"symbols",
+		"antlrmap",
+		"ctags"
+	],
+	"homepage": "https://github.com/possumtech/rummy.repo#readme",
+	"bugs": {
+		"url": "https://github.com/possumtech/rummy.repo/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/possumtech/rummy.repo.git"
+	},
+	"license": "MIT",
+	"author": "@wikitopian",
+	"engines": {
+		"node": ">=25",
+		"npm": ">=11"
+	},
+	"type": "module",
+	"main": "src/rummy.repo.js",
+	"exports": {
+		".": "./src/rummy.repo.js"
+	},
+	"files": [
+		"src/rummy.repo.js",
+		"src/CtagsExtractor.js",
+		"src/formatSymbols.js"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"lint": "biome check src --fix --unsafe",
+		"test": "npm run lint && npm run test:unit",
+		"test:unit": "node --experimental-test-coverage --test-coverage-lines=80 --test-coverage-branches=80 --test-coverage-functions=80 --test-concurrency=1 --test $(find src -name '*.test.js')"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.6"
+	},
+	"dependencies": {
+		"@possumtech/antlrmap": "^0.0.8"
+	}
+}

package/src/CtagsExtractor.js

@@ -0,0 +1,71 @@
+import { spawnSync as defaultSpawnSync } from "node:child_process";
+
+export default class CtagsExtractor {
+	#root;
+	#spawnSync;
+
+	constructor(root, spawnSync = defaultSpawnSync) {
+		this.#root = root;
+		this.#spawnSync = spawnSync;
+	}
+
+	extract(paths) {
+		const result = this.#spawnSync(
+			"ctags",
+			["--output-format=json", "--fields=+nS", "-f", "-", ...paths],
+			{ cwd: this.#root, encoding: "utf8", maxBuffer: 10 * 1024 * 1024 },
+		);
+
+		if (result.error && result.error.code === "ENOENT") {
+			console.warn("[RUMMY.REPO] skipping ctags: not installed.");
+			return new Map(paths.map((p) => [p, []]));
+		}
+
+		if (result.status !== 0) {
+			console.warn(`[RUMMY.REPO] skipping ctags: failed (${result.stderr})`);
+			return new Map(paths.map((p) => [p, []]));
+		}
+
+		const tags = result.stdout
+			.split("\n")
+			.filter(Boolean)
+			.map((l) => JSON.parse(l));
+
+		const grouped = new Map();
+		for (const path of paths) grouped.set(path, []);
+
+		for (const tag of tags) {
+			const symbols = grouped.get(tag.path);
+			if (symbols) {
+				symbols.push(this.#processTag(tag));
+			}
+		}
+
+		return grouped;
+	}
+
+	#processTag(tag) {
+		let params = tag.signature || null;
+
+		// LUA HACK: ctags doesn't provide signatures for Lua, but they are in the pattern.
+		// Handles both 'function name(params)' and 'name = function(params)'
+		if (!params && tag.path.endsWith(".lua") && tag.pattern && tag.name) {
+			const escapedName = tag.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+			const regex = new RegExp(
+				`${escapedName}\\s*(?:=\\s*function\\s*)?(\\(.*?\\))`,
+			);
+			const match = tag.pattern.match(regex);
+			if (match) {
+				params = match[1];
+			}
+		}
+
+		return {
+			name: tag.name,
+			type: tag.kind,
+			params,
+			line: tag.line,
+			source: "standard",
+		};
+	}
+}

package/src/formatSymbols.js

@@ -0,0 +1,20 @@
+export default function formatSymbols(symbols) {
+	const sorted = symbols.toSorted((a, b) => (a.line || 0) - (b.line || 0));
+	const stack = [];
+	const lines = [];
+
+	for (const s of sorted) {
+		while (stack.length > 0 && s.line > stack.at(-1).endLine) stack.pop();
+		const depth = stack.length;
+		const indent = "  ".repeat(depth);
+		const kind = s.kind ? `${s.kind} ` : "";
+		const line = s.line ? ` L${s.line}` : "";
+		const p = s.params
+			? `(${Array.isArray(s.params) ? s.params.join(", ") : s.params})`
+			: "";
+		lines.push(`${indent}${kind}${s.name}${p}${line}`);
+		if (s.endLine && s.endLine > s.line) stack.push(s);
+	}
+
+	return lines.join("\n");
+}

package/src/rummy.repo.js

@@ -0,0 +1,59 @@
+import { readFileSync } from "node:fs";
+import { extname, join } from "node:path";
+import Antlrmap from "@possumtech/antlrmap";
+import CtagsExtractor from "./CtagsExtractor.js";
+import formatSymbols from "./formatSymbols.js";
+
+const antlrmapSupported = new Set(Object.keys(Antlrmap.extensions));
+
+/**
+ * RepoMapPlugin: symbol extraction via antlrmap (ANTLR4 grammars)
+ * with ctags fallback.
+ *
+ * Filter: hooks.file.symbols
+ * Input:  Map (empty or partially populated)
+ * Context: { paths, projectPath }
+ *   - paths: string[] of relative file paths that changed
+ *   - projectPath: string, absolute project root
+ * Output: Map<string, symbol[]> where symbol = { name, kind?, params?, line?, endLine? }
+ */
+export default class RepoMapPlugin {
+	static register(hooks) {
+		hooks.file.symbols.addFilter(async (symbolMap, { paths, projectPath }) => {
+			const result = symbolMap instanceof Map ? symbolMap : new Map();
+			const antlrmap = new Antlrmap();
+			const ctagsQueue = [];
+
+			for (const relPath of paths) {
+				if (result.has(relPath)) continue;
+				const ext = extname(relPath);
+
+				if (antlrmapSupported.has(ext)) {
+					try {
+						const content = readFileSync(join(projectPath, relPath), "utf8");
+						const symbols = await antlrmap.mapSource(content, ext);
+						if (symbols?.length > 0) {
+							result.set(relPath, symbols);
+							continue;
+						}
+					} catch {
+						// Fall through to ctags
+					}
+				}
+				ctagsQueue.push(relPath);
+			}
+
+			if (ctagsQueue.length > 0) {
+				const extractor = new CtagsExtractor(projectPath);
+				const ctagsResults = extractor.extract(ctagsQueue);
+				for (const [path, symbols] of ctagsResults) {
+					if (symbols.length > 0) result.set(path, symbols);
+				}
+			}
+
+			return result;
+		}, 50);
+	}
+
+	static formatSymbols = formatSymbols;
+}