@tmhs/godot-correctness-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,34 @@
+Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International
+
+Copyright (c) 2026 TM Hospitality Strategies
+
+This work is licensed under the Creative Commons
+Attribution-NonCommercial-NoDerivatives 4.0 International License.
+
+You are free to:
+
+  Share - copy and redistribute the material in any medium or format.
+
+The licensor cannot revoke these freedoms as long as you follow the
+license terms.
+
+Under the following terms:
+
+  Attribution - You must give appropriate credit, provide a link to the
+  license, and indicate if changes were made. You may do so in any
+  reasonable manner, but not in any way that suggests the licensor
+  endorses you or your use.
+
+  NonCommercial - You may not use the material for commercial purposes.
+
+  NoDerivatives - If you remix, transform, or build upon the material,
+  you may not distribute the modified material.
+
+  No additional restrictions - You may not apply legal terms or
+  technological measures that legally restrict others from doing
+  anything the license permits.
+
+Full license text:
+https://creativecommons.org/licenses/by-nc-nd/4.0/legalcode
+
+SPDX-License-Identifier: CC-BY-NC-ND-4.0

package/README.md

@@ -0,0 +1,118 @@
+# godot-correctness-mcp
+
+**Offline static correctness MCP server for Godot 4.x GDScript projects**
+
+![License: CC-BY-NC-ND-4.0](https://img.shields.io/badge/license-CC--BY--NC--ND--4.0-green)
+![Version](https://img.shields.io/badge/version-0.1.0-blue)
+
+---
+
+A Model Context Protocol server (and `gdcorrect` CLI) that statically checks the
+correctness of Godot 4.x GDScript projects. It runs **headless, offline, and in
+CI** — it never launches the editor, never needs a running Godot instance, and
+never touches the network at runtime.
+
+## Three pillars
+
+1. **GDScript linting** — anti-pattern detection via a committed tree-sitter
+   grammar (WASM). Rules like `delta-misuse`, `get-node-in-process`,
+   `missing-onready`, `untyped-declaration`, `await-misuse`, `stringly-nodepath`,
+   `connect-without-disconnect`, `float-grid-equality`. See [docs/lint.md](docs/lint.md).
+2. **Cross-version API lookup & diff** — query classes/methods/properties/signals
+   and diff the API between Godot **4.4** and **4.5**, from committed offline
+   symbol databases. See [docs/symbol-db.md](docs/symbol-db.md).
+3. **Scene / resource / registry analysis** — validate `.tscn`, `.tres`, and
+   `project.godot`, including deep validation of data-driven `.tres` registries
+   (the dangling-path check). See [docs/scenes.md](docs/scenes.md).
+
+## Non-goals
+
+- **No live bridge.** It does not connect to a running editor or game.
+- **No editor plugin.** Nothing to install inside Godot.
+- **No C#.** GDScript only.
+- **Nothing older than Godot 4.4.** Symbol data is pinned to 4.4 and 4.5.
+
+This is deliberately the complement to the live-session Godot MCP tools: it is the
+one you run in CI and headless pipelines.
+
+## Installation
+
+As an MCP server (Claude Desktop / Cursor `mcpServers` config):
+
+```json
+{
+  "mcpServers": {
+    "godot-correctness": {
+      "command": "npx",
+      "args": ["-y", "@tmhs/godot-correctness-mcp"]
+    }
+  }
+}
+```
+
+As a CLI:
+
+```bash
+npx -y @tmhs/godot-correctness-mcp gdcorrect lint . --format json
+```
+
+## MCP surface
+
+**Tools:** `server_info`; `api_symbol_lookup`, `api_class_summary`, `api_diff`;
+`lint_file`, `lint_project`; `validate_scenes`, `validate_project_config`,
+`validate_registries`, `project_report`.
+
+**Resources:** curated GDScript skill snippets under `skill://` (data-driven
+resources, signal hygiene, typed GDScript, preload vs load).
+
+## CLI and CI
+
+`gdcorrect <command> <projectPath> [--format json|pretty]`, where `<command>` is
+`lint`, `validate-scenes`, `validate-project`, `validate-registries`, or `report`.
+JSON is the primary, machine-readable format. Exit codes: **0** clean, **1** on
+any error-severity finding, **2** on tool failure.
+
+```yaml
+# .github/workflows/godot-correctness.yml
+jobs:
+  correctness:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - name: Lint GDScript (fails on error-severity findings)
+        run: npx -y @tmhs/godot-correctness-mcp gdcorrect lint . --format json
+      - name: Validate registries
+        run: npx -y @tmhs/godot-correctness-mcp gdcorrect validate-registries . --format json
+```
+
+## Configuration
+
+Place `godot-correctness.config.json` at your project root (see
+[`godot-correctness.config.example.json`](godot-correctness.config.example.json)):
+enable/disable rules, override severities, set include/exclude globs, and declare
+`registryDirs` / `pathPropertyPatterns` for registry validation. Full reference in
+[docs/lint.md](docs/lint.md#configuration) and [docs/scenes.md](docs/scenes.md#configuration).
+
+## Symbol database regeneration
+
+The API pillar reads committed gzipped symbol DBs generated locally from pinned
+Godot binaries (CI validates them but never runs Godot). Regeneration procedure:
+[docs/symbol-db.md](docs/symbol-db.md).
+
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md) and [BACKLOG.md](BACKLOG.md).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+CC-BY-NC-ND-4.0 -- see [LICENSE](LICENSE) for details.
+
+---
+
+**Built by TMHSDigital**

package/dist/capabilities.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Godot minor versions this server carries symbol data for. Deliberately
+ * narrow: the server targets 4.4 and 4.5 and nothing older. See README non-goals.
+ */
+export declare const PINNED_GODOT_VERSIONS: readonly ["4.4", "4.5"];
+export type GodotVersion = (typeof PINNED_GODOT_VERSIONS)[number];
+/**
+ * The three correctness pillars. A pillar is "available" only when the offline
+ * artifacts it depends on are actually present in the package. Later phases add
+ * those artifacts, which flips the flags without any code change here.
+ */
+export interface PillarAvailability {
+    /** GDScript anti-pattern linting (tree-sitter grammar WASM). Phase 3. */
+    gdscriptLint: boolean;
+    /** Cross-version API symbol lookup/diff (committed symbol databases). Phase 2. */
+    apiSymbols: boolean;
+    /** Static .tscn/.tres/project.godot analysis incl. registry validation. Phase 4. */
+    sceneResourceAnalysis: boolean;
+}
+/** Report which pillars are currently usable based on committed artifacts. */
+export declare function pillarAvailability(): PillarAvailability;

package/dist/capabilities.js

@@ -0,0 +1,24 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Godot minor versions this server carries symbol data for. Deliberately
+ * narrow: the server targets 4.4 and 4.5 and nothing older. See README non-goals.
+ */
+export const PINNED_GODOT_VERSIONS = ["4.4", "4.5"];
+// dist/capabilities.js and src/capabilities.ts both sit one level below the
+// package root, so data/ resolves the same whether running compiled or via tsx.
+const dataDir = join(dirname(fileURLToPath(import.meta.url)), "..", "data");
+/** Report which pillars are currently usable based on committed artifacts. */
+export function pillarAvailability() {
+    const apiSymbols = PINNED_GODOT_VERSIONS.every((v) => existsSync(join(dataDir, `godot-${v}.symbols.json.gz`)));
+    const gdscriptLint = existsSync(join(dataDir, "tree-sitter-gdscript.wasm"));
+    return {
+        gdscriptLint,
+        apiSymbols,
+        // Phase 4 static scene/resource/registry analysis is pure TypeScript with
+        // no external artifact; it is always available once shipped.
+        sceneResourceAnalysis: true,
+    };
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,KAAK,EAAE,KAAK,CAAU,CAAC;AAkB7D,4EAA4E;AAC5E,gFAAgF;AAChF,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AAE5E,8EAA8E;AAC9E,MAAM,UAAU,kBAAkB;IAChC,MAAM,UAAU,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CACnD,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,kBAAkB,CAAC,CAAC,CACxD,CAAC;IACF,MAAM,YAAY,GAAG,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC;IAC5E,OAAO;QACL,YAAY;QACZ,UAAU;QACV,0EAA0E;QAC1E,6DAA6D;QAC7D,qBAAqB,EAAE,IAAI;KAC5B,CAAC;AACJ,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import type { Finding } from "./lint/types.js";
+interface CommandResult {
+    root: string;
+    findings: Finding[];
+    /** Full JSON payload for --format json (already includes findings). */
+    payload: unknown;
+}
+export declare function renderPretty(res: CommandResult): string;
+/** Exit code: 0 clean, 1 on any error-severity finding, 2 on tool failure. */
+export declare function runCli(argv: string[], log?: (s: string) => void, errOut?: (s: string) => void): Promise<number>;
+export {};

package/dist/cli.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import { lintProject } from "./lint/project.js";
+import { projectReport } from "./scenes/report.js";
+import { validateProjectConfig, validateRegistries, validateScenes } from "./scenes/validate.js";
+const COMMANDS = new Set([
+    "lint",
+    "validate-scenes",
+    "validate-project",
+    "validate-registries",
+    "report",
+]);
+async function runCommand(command, root) {
+    switch (command) {
+        case "lint": {
+            const r = await lintProject(root);
+            return { root, findings: r.findings, payload: r };
+        }
+        case "validate-scenes": {
+            const findings = validateScenes(root);
+            return { root, findings, payload: { root, findings, count: findings.length } };
+        }
+        case "validate-project": {
+            const findings = validateProjectConfig(root);
+            return { root, findings, payload: { root, findings, count: findings.length } };
+        }
+        case "validate-registries": {
+            const r = validateRegistries(root);
+            return { root, findings: r.findings, payload: { root, ...r } };
+        }
+        case "report": {
+            const r = await projectReport(root);
+            return {
+                root,
+                findings: [...r.scenes, ...r.project, ...r.registries, ...r.lint],
+                payload: r,
+            };
+        }
+        default:
+            throw new Error(`Unknown command: ${command}`);
+    }
+}
+function countErrors(findings) {
+    return findings.filter((f) => f.severity === "error").length;
+}
+export function renderPretty(res) {
+    const lines = [];
+    let lastFile = "";
+    const sorted = [...res.findings].sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.col - b.col);
+    for (const f of sorted) {
+        if (f.file !== lastFile) {
+            lines.push(`\n${f.file}`);
+            lastFile = f.file;
+        }
+        lines.push(`  ${f.line}:${f.col}  ${f.severity.toUpperCase().padEnd(7)} ${f.ruleId}`);
+        lines.push(`         ${f.message}`);
+    }
+    const e = countErrors(res.findings);
+    const w = res.findings.filter((f) => f.severity === "warning").length;
+    const i = res.findings.filter((f) => f.severity === "info").length;
+    lines.push(`\n${res.findings.length} finding(s): ${e} error(s), ${w} warning(s), ${i} info.`);
+    return lines.join("\n").trimStart();
+}
+function parseArgs(argv) {
+    let format = "json";
+    const positional = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--format" || a === "-f")
+            format = argv[++i] ?? "";
+        else if (a.startsWith("--format="))
+            format = a.slice("--format=".length);
+        else
+            positional.push(a);
+    }
+    return { command: positional[0], root: positional[1], format };
+}
+/** Exit code: 0 clean, 1 on any error-severity finding, 2 on tool failure. */
+export async function runCli(argv, log = console.log, errOut = console.error) {
+    const { command, root, format } = parseArgs(argv);
+    if (!command || !COMMANDS.has(command) || !root) {
+        errOut(`Usage: gdcorrect <${[...COMMANDS].join("|")}> <projectPath> [--format json|pretty]`);
+        return 2;
+    }
+    if (format !== "json" && format !== "pretty") {
+        errOut(`Unknown format: ${format}. Use 'json' or 'pretty'.`);
+        return 2;
+    }
+    try {
+        const res = await runCommand(command, root);
+        log(format === "pretty" ? renderPretty(res) : JSON.stringify(res.payload, null, 2));
+        return countErrors(res.findings) > 0 ? 1 : 0;
+    }
+    catch (err) {
+        errOut(`gdcorrect: ${err instanceof Error ? err.message : String(err)}`);
+        return 2;
+    }
+}
+const invokedDirectly = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) {
+    runCli(process.argv.slice(2))
+        .then((code) => process.exit(code))
+        .catch(() => process.exit(2));
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAWjG,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC;IACvB,MAAM;IACN,iBAAiB;IACjB,kBAAkB;IAClB,qBAAqB;IACrB,QAAQ;CACT,CAAC,CAAC;AAEH,KAAK,UAAU,UAAU,CAAC,OAAe,EAAE,IAAY;IACrD,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,MAAM,CAAC,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC;YAClC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QACpD,CAAC;QACD,KAAK,iBAAiB,CAAC,CAAC,CAAC;YACvB,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;YACtC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;QACjF,CAAC;QACD,KAAK,kBAAkB,CAAC,CAAC,CAAC;YACxB,MAAM,QAAQ,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;YAC7C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;QACjF,CAAC;QACD,KAAK,qBAAqB,CAAC,CAAC,CAAC;YAC3B,MAAM,CAAC,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;YACnC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC;QACjE,CAAC;QACD,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,CAAC,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC;YACpC,OAAO;gBACL,IAAI;gBACJ,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC;gBACjE,OAAO,EAAE,CAAC;aACX,CAAC;QACJ,CAAC;QACD;YACE,MAAM,IAAI,KAAK,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;IACnD,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,QAAmB;IACtC,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,MAAM,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAkB;IAC7C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,QAAQ,GAAG,EAAE,CAAC;IAClB,MAAM,MAAM,GAAG,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CACnC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAC3E,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACxB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YAC1B,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC;QACpB,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QACtF,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IACtC,CAAC;IACD,MAAM,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACpC,MAAM,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,MAAM,CAAC;IACtE,MAAM,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,MAAM,CAAC,CAAC,MAAM,CAAC;IACnE,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,QAAQ,CAAC,MAAM,gBAAgB,CAAC,cAAc,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC9F,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC;AACtC,CAAC;AAED,SAAS,SAAS,CAAC,IAAc;IAC/B,IAAI,MAAM,GAAG,MAAM,CAAC;IACpB,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,KAAK,UAAU,IAAI,CAAC,KAAK,IAAI;YAAE,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;aACxD,IAAI,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC;YAAE,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;;YACpE,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;AACjE,CAAC;AAED,8EAA8E;AAC9E,MAAM,CAAC,KAAK,UAAU,MAAM,CAC1B,IAAc,EACd,MAA2B,OAAO,CAAC,GAAG,EACtC,SAA8B,OAAO,CAAC,KAAK;IAE3C,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAClD,IAAI,CAAC,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAChD,MAAM,CAAC,qBAAqB,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,wCAAwC,CAAC,CAAC;QAC7F,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC7C,MAAM,CAAC,mBAAmB,MAAM,2BAA2B,CAAC,CAAC;QAC7D,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC5C,GAAG,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QACpF,OAAO,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,cAAc,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzE,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC;AAED,MAAM,eAAe,GACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAE3F,IAAI,eAAe,EAAE,CAAC;IACpB,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SAC1B,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;SAClC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAClC,CAAC"}

package/dist/gdscript/ast.d.ts

@@ -0,0 +1,25 @@
+import type { Node } from "web-tree-sitter";
+/** Depth-first walk over all named nodes (inclusive of the start node). */
+export declare function walk(node: Node): Generator<Node>;
+/** Source text covered by a node. */
+export declare function text(node: Node, source: string): string;
+/** All named descendants of a given grammar type. */
+export declare function findAll(root: Node, type: string): Node[];
+/** Text of a named field child, or null. */
+export declare function fieldText(node: Node, field: string, source: string): string | null;
+/** The operator token of a binary/assignment node (read from source between operands). */
+export declare function operatorOf(node: Node, source: string): string | null;
+/** Walk up to the nearest enclosing function_definition, or null. */
+export declare function enclosingFunction(node: Node): Node | null;
+/** Name of the enclosing function_definition, or null if not inside one. */
+export declare function enclosingFunctionName(node: Node, source: string): string | null;
+/**
+ * The identifier being invoked by a call. Handles both free calls
+ * `foo(...)` (a `call` node) and method calls `a.b.foo(...)` (an
+ * `attribute_call` node). Returns the method/function name or null.
+ */
+export declare function calleeName(node: Node, source: string): string | null;
+/** True if the subtree contains an identifier with the given name. */
+export declare function containsIdentifier(node: Node, name: string, source: string): boolean;
+/** True if the function body calls a function/method with the given name. */
+export declare function functionCalls(fn: Node, name: string, source: string): boolean;

package/dist/gdscript/ast.js

@@ -0,0 +1,82 @@
+/** Depth-first walk over all named nodes (inclusive of the start node). */
+export function* walk(node) {
+    yield node;
+    for (const child of node.namedChildren) {
+        if (child)
+            yield* walk(child);
+    }
+}
+/** Source text covered by a node. */
+export function text(node, source) {
+    return source.slice(node.startIndex, node.endIndex);
+}
+/** All named descendants of a given grammar type. */
+export function findAll(root, type) {
+    const out = [];
+    for (const n of walk(root))
+        if (n.type === type)
+            out.push(n);
+    return out;
+}
+/** Text of a named field child, or null. */
+export function fieldText(node, field, source) {
+    const child = node.childForFieldName(field);
+    return child ? text(child, source) : null;
+}
+/** The operator token of a binary/assignment node (read from source between operands). */
+export function operatorOf(node, source) {
+    const left = node.childForFieldName("left");
+    const right = node.childForFieldName("right");
+    if (!left || !right)
+        return null;
+    return source.slice(left.endIndex, right.startIndex).trim();
+}
+/** Walk up to the nearest enclosing function_definition, or null. */
+export function enclosingFunction(node) {
+    let cur = node.parent;
+    while (cur) {
+        if (cur.type === "function_definition")
+            return cur;
+        cur = cur.parent;
+    }
+    return null;
+}
+/** Name of the enclosing function_definition, or null if not inside one. */
+export function enclosingFunctionName(node, source) {
+    const fn = enclosingFunction(node);
+    return fn ? fieldText(fn, "name", source) : null;
+}
+/**
+ * The identifier being invoked by a call. Handles both free calls
+ * `foo(...)` (a `call` node) and method calls `a.b.foo(...)` (an
+ * `attribute_call` node). Returns the method/function name or null.
+ */
+export function calleeName(node, source) {
+    if (node.type === "call") {
+        const fn = node.namedChild(0);
+        return fn && fn.type === "identifier" ? text(fn, source) : null;
+    }
+    if (node.type === "attribute_call") {
+        const id = node.namedChild(0);
+        return id && id.type === "identifier" ? text(id, source) : null;
+    }
+    return null;
+}
+/** True if the subtree contains an identifier with the given name. */
+export function containsIdentifier(node, name, source) {
+    for (const n of walk(node)) {
+        if (n.type === "identifier" && text(n, source) === name)
+            return true;
+    }
+    return false;
+}
+/** True if the function body calls a function/method with the given name. */
+export function functionCalls(fn, name, source) {
+    for (const n of walk(fn)) {
+        if ((n.type === "call" || n.type === "attribute_call") && calleeName(n, source) === name) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=ast.js.map

package/dist/gdscript/ast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.js","sourceRoot":"","sources":["../../src/gdscript/ast.ts"],"names":[],"mappings":"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"}

package/dist/gdscript/parser.d.ts

@@ -0,0 +1,7 @@
+import { Parser, type Tree } from "web-tree-sitter";
+/** Whether the committed GDScript grammar WASM is present. */
+export declare function isGrammarAvailable(): boolean;
+/** Get a shared, initialized GDScript parser (reused across files, sequential). */
+export declare function getParser(): Promise<Parser>;
+/** Parse GDScript source into a concrete syntax tree. */
+export declare function parseGDScript(source: string): Promise<Tree>;

package/dist/gdscript/parser.js

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Language, Parser } from "web-tree-sitter";
+// dist/gdscript/parser.js and src/gdscript/parser.ts both sit two levels below
+// the package root, so the committed grammar resolves the same either way.
+const wasmPath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "data", "tree-sitter-gdscript.wasm");
+/** Whether the committed GDScript grammar WASM is present. */
+export function isGrammarAvailable() {
+    return existsSync(wasmPath);
+}
+let initPromise = null;
+let langPromise = null;
+let parserPromise = null;
+async function getLanguage() {
+    // Parser.init() loads web-tree-sitter's own runtime wasm (auto-located from
+    // node_modules on Node); the grammar is loaded from the committed bytes.
+    if (!initPromise)
+        initPromise = Parser.init();
+    await initPromise;
+    if (!langPromise)
+        langPromise = Language.load(new Uint8Array(readFileSync(wasmPath)));
+    return langPromise;
+}
+/** Get a shared, initialized GDScript parser (reused across files, sequential). */
+export async function getParser() {
+    if (!parserPromise) {
+        parserPromise = getLanguage().then((lang) => {
+            const parser = new Parser();
+            parser.setLanguage(lang);
+            return parser;
+        });
+    }
+    return parserPromise;
+}
+/** Parse GDScript source into a concrete syntax tree. */
+export async function parseGDScript(source) {
+    const parser = await getParser();
+    const tree = parser.parse(source);
+    if (!tree)
+        throw new Error("Failed to parse GDScript source.");
+    return tree;
+}
+//# sourceMappingURL=parser.js.map

package/dist/gdscript/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../src/gdscript/parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAa,MAAM,iBAAiB,CAAC;AAE9D,+EAA+E;AAC/E,2EAA2E;AAC3E,MAAM,QAAQ,GAAG,IAAI,CACnB,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EACvC,IAAI,EACJ,IAAI,EACJ,MAAM,EACN,2BAA2B,CAC5B,CAAC;AAEF,8DAA8D;AAC9D,MAAM,UAAU,kBAAkB;IAChC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC;AAC9B,CAAC;AAED,IAAI,WAAW,GAAyB,IAAI,CAAC;AAC7C,IAAI,WAAW,GAA6B,IAAI,CAAC;AACjD,IAAI,aAAa,GAA2B,IAAI,CAAC;AAEjD,KAAK,UAAU,WAAW;IACxB,4EAA4E;IAC5E,yEAAyE;IACzE,IAAI,CAAC,WAAW;QAAE,WAAW,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC9C,MAAM,WAAW,CAAC;IAClB,IAAI,CAAC,WAAW;QAAE,WAAW,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IACtF,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,mFAAmF;AACnF,MAAM,CAAC,KAAK,UAAU,SAAS;IAC7B,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,aAAa,GAAG,WAAW,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;YAC1C,MAAM,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;YAC5B,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;YACzB,OAAO,MAAM,CAAC;QAChB,CAAC,CAAC,CAAC;IACL,CAAC;IACD,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,yDAAyD;AACzD,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAc;IAChD,MAAM,MAAM,GAAG,MAAM,SAAS,EAAE,CAAC;IACjC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAC/D,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/godot/text-format.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Tolerant parser for Godot 4.x text formats (.tscn, .tres, project.godot).
+ * These are INI-like: bracketed section headers with optional attributes,
+ * followed by `key = value` lines. Values may be strings, numbers, bools, or
+ * constructor literals (ExtResource("id"), Vector2(...), arrays/dicts that can
+ * span lines). Unknown constructs are preserved as opaque `other` values; the
+ * parser never throws.
+ */
+export type GodotValueKind = "string" | "number" | "bool" | "extResource" | "subResource" | "other";
+export interface GodotValue {
+    raw: string;
+    /** 1-based line where the value starts. */
+    line: number;
+    kind: GodotValueKind;
+    /** For kind "string": the unquoted content. */
+    string?: string;
+    /** For kind extResource/subResource: the referenced id. */
+    ref?: string;
+}
+export interface GodotSection {
+    /** Section kind: the first token in the header, e.g. "node", "ext_resource". */
+    kind: string;
+    attributes: Record<string, GodotValue>;
+    properties: Record<string, GodotValue>;
+    /** 1-based line of the section header. */
+    line: number;
+}
+export interface GodotFile {
+    /** The gd_scene / gd_resource header section, or null (e.g. project.godot). */
+    header: GodotSection | null;
+    sections: GodotSection[];
+}
+export declare function parseGodotFile(source: string): GodotFile;
+/** Convenience: all sections of a given kind (e.g. "ext_resource", "node"). */
+export declare function sectionsOfKind(file: GodotFile, kind: string): GodotSection[];

package/dist/godot/text-format.js

@@ -0,0 +1,105 @@
+/**
+ * Tolerant parser for Godot 4.x text formats (.tscn, .tres, project.godot).
+ * These are INI-like: bracketed section headers with optional attributes,
+ * followed by `key = value` lines. Values may be strings, numbers, bools, or
+ * constructor literals (ExtResource("id"), Vector2(...), arrays/dicts that can
+ * span lines). Unknown constructs are preserved as opaque `other` values; the
+ * parser never throws.
+ */
+const HEADER_KINDS = new Set(["gd_scene", "gd_resource"]);
+function classifyValue(raw, line) {
+    const t = raw.trim();
+    let m;
+    if (t.length >= 2 && t.startsWith('"') && t.endsWith('"')) {
+        return { raw: t, line, kind: "string", string: t.slice(1, -1) };
+    }
+    if ((m = /^ExtResource\(\s*"?([^")]*)"?\s*\)$/.exec(t))) {
+        return { raw: t, line, kind: "extResource", ref: m[1] };
+    }
+    if ((m = /^SubResource\(\s*"?([^")]*)"?\s*\)$/.exec(t))) {
+        return { raw: t, line, kind: "subResource", ref: m[1] };
+    }
+    if (/^-?\d+(\.\d+)?$/.test(t))
+        return { raw: t, line, kind: "number" };
+    if (t === "true" || t === "false")
+        return { raw: t, line, kind: "bool" };
+    return { raw: t, line, kind: "other" };
+}
+/** Split `key=value key2="v 2"` attribute text, respecting quotes. */
+function parseAttributes(text, line) {
+    const attrs = {};
+    const re = /(\w[\w./-]*)\s*=\s*("(?:[^"\\]|\\.)*"|[^\s\]]+)/g;
+    let m;
+    while ((m = re.exec(text)))
+        attrs[m[1]] = classifyValue(m[2], line);
+    return attrs;
+}
+/** Whether brackets/braces/parens/quotes in `s` are balanced (string-aware). */
+function isBalanced(s) {
+    let depth = 0;
+    let inStr = false;
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (inStr) {
+            if (c === "\\")
+                i++;
+            else if (c === '"')
+                inStr = false;
+        }
+        else if (c === '"')
+            inStr = true;
+        else if (c === "(" || c === "[" || c === "{")
+            depth++;
+        else if (c === ")" || c === "]" || c === "}")
+            depth--;
+    }
+    return depth <= 0 && !inStr;
+}
+export function parseGodotFile(source) {
+    const lines = source.split(/\r?\n/);
+    const file = { header: null, sections: [] };
+    let current = null;
+    for (let i = 0; i < lines.length; i++) {
+        const rawLine = lines[i];
+        const line = rawLine.trim();
+        if (line === "" || line.startsWith(";"))
+            continue;
+        const headerMatch = /^\[(.+)\]\s*$/.exec(line);
+        if (headerMatch) {
+            const inner = headerMatch[1].trim();
+            const sp = inner.search(/\s/);
+            const kind = sp === -1 ? inner : inner.slice(0, sp);
+            const attrText = sp === -1 ? "" : inner.slice(sp + 1);
+            const section = {
+                kind,
+                attributes: parseAttributes(attrText, i + 1),
+                properties: {},
+                line: i + 1,
+            };
+            if (HEADER_KINDS.has(kind) && !file.header)
+                file.header = section;
+            else
+                file.sections.push(section);
+            current = section;
+            continue;
+        }
+        const propMatch = /^([\w./-]+)\s*=\s*(.*)$/.exec(line);
+        if (propMatch && current) {
+            const key = propMatch[1];
+            let value = propMatch[2];
+            // Continue multi-line values (arrays/dicts/constructors) until balanced.
+            while (!isBalanced(value) && i + 1 < lines.length) {
+                i++;
+                value += `\n${lines[i]}`;
+            }
+            current.properties[key] = classifyValue(value, i + 1);
+        }
+        // Anything else is opaque and intentionally ignored.
+    }
+    return file;
+}
+/** Convenience: all sections of a given kind (e.g. "ext_resource", "node"). */
+export function sectionsOfKind(file, kind) {
+    return file.sections.filter((s) => s.kind === kind);
+}
+//# sourceMappingURL=text-format.js.map