Add gdscript and godot package definitions

[TeeJS]

Add GDScript and Godot Engine package definitions

Adds two registry definitions built from godotengine/godot-docs:

• registry/gdscript/gdscript.yaml — the GDScript language
• registry/godot/godot.yaml — the Godot engine: full class reference + tutorials

Both use the self-named-directory convention the registry README prescribes for projects
not distributed by a package manager, alongside registry/python/python.yaml and
registry/java/java.yaml.

Build results

Built at godot-docs commit 6d86d7c7f3b8f4f56c71e113022d72fe80b2c84d
(branch stable, 2026-08-05, = Godot 4.7):

definition	docs_path	files	sections	tokens	skipped	size
gdscript/gdscript	tutorials/scripting/gdscript	9	129	60,921	0	0.45 MB
godot/godot	(whole repo)	1,604	14,488	8,136,611	0	48.03 MB

Zero skipped files in both. .rst is already a supported input format, so no new parsing
is required. Both definitions were validated by running the repository's own
loadDefinition() and listDefinitions() — including the whole-tree scan, since one bad
definition fails the nightly publish for every other package.

Why gdscript is scoped narrowly

tutorials/scripting/gdscript yields 129 sections, which is below the README's "a few
hundred" guideline, so it is worth explaining why that is deliberate rather than a
misconfigured docs_path.

The obvious wider path, tutorials/scripting, yields 515 sections — but they break down as:

area	sections
c_sharp/	208 (40%)
gdscript/	129 (25%)
scripting/ root	97
cpp/	41
debug/	40

C# is the largest block in what would ship as a GDScript package, and it wins the most
important queries. Top-5 results from that build, ranked exactly as search.ts ranks them
(bm25(chunks_fts, 5.0, 10.0, 1.0) * -1, ORDER BY score DESC, after buildQuery()):

• signal → c_sharp_signals, how_to_read_the_godot_api, cross_language_scripting, c_sharp_signals, c_sharp_signals — none of the five is GDScript
• await → c_sharp_differences at fix(cli): accept package name with version suffix in remove command #1
• lambda → one GDScript hit, then four C# pages
• export → C# at fix: skip prerelease versions when detecting latest stable tag #2 and docs: update README to reference Next.js 16 #3

Since git sources have no exclude_paths (only zip sources do), the C# and C++ subtrees
cannot be pruned from tutorials/scripting. Narrowing the path is the only way to get a
GDScript package that returns GDScript. The same queries against the narrow build return
gdscript_basics: Signals ×3, gdscript_exports ×4, and static_typing ×4 — every top hit
on target.

One further consequence of the narrow scope, stated plainly because a reviewer will hit it:
when a query matches a built-in function name, the gdscript package returns
lexically-plausible but topically-wrong results rather than nothing, because those words
appear incidentally in tutorial prose.

query	gdscript package returns	actually documented in
preload	gdscript_basics: Keywords, Classes	classes/class_@gdscript.rst
range	gdscript_exports: Limiting editor input ranges	classes/class_@gdscript.rst
push_error	static_typing: How to use static typing	classes/class_@globalscope.rst
get_node	gdscript_styleguide: Static typing	classes/class_node.rst
inst	(no results)	classes/class_@gdscript.rst

All five resolve correctly in the godot package. This is intended routing rather than a
defect — classes/ is unreachable from any tutorial path — but it is why the gdscript
description names the built-ins explicitly and points at the godot package for them,
instead of only mentioning "engine APIs".

Everything the narrow path omits (autoloads, resources, groups, the scene tree,
overridable functions, debugging, multiplayer RPC) is covered by the godot package,
which also carries class_@gdscript.rst and class_@globalscope.rst — the built-in
functions (preload, load, assert, range, str) that live in classes/ and are
unreachable from any tutorial path. Each definition's description points at the other so
an agent can route between them.

Notes for reviewers

• ref: stable — godot-docs has no git tags at all, and no ReadTheDocs htmlzip
  archives are published (all such URLs 404), so neither the tag-pattern nor the
  versioned-by-zip shape applies. The stable branch tracks the current Godot release and
  advances on its own, and source_commit is populated so skip-if-unchanged works.
• Path separators — building on Windows produces doc_path values with backslashes
  (tutorials\scripting\...). That is a local artifact of readLocalDocsFiles on Windows,
  not a problem with these definitions; Linux CI produces forward slashes. Please don't
  "fix" the YAML paths for it.
• Unrelated pre-existing Windows issue (not introduced here, no fix included) — running
  listDefinitions() on Windows throws
  Definition name "@apollo/client" doesn't match filename "@apollo\client.yaml", because
  loadDefinition() compares a relative() path against a /-joined name. It reproduces
  on main with these definitions removed, so it is not caused by this PR and does not
  affect Linux CI. Flagging it rather than fixing it here to keep this PR to one concern; a
  split(sep).join("/") on the derived name would resolve it.
• Size — godot is 48.03 MB, against the client's 512 MB DEFAULT_MAX_DOWNLOAD_BYTES
  and fetched on demand. A classes-only variant was measured (10,960 sections, 38.8 MB);
  it saves 9 MB and loses every tutorial, so it was rejected.

Attribution

godotengine/godot-docs is licensed CC-BY 3.0 Unported (verified from its
LICENSE.txt). Both definitions carry repository: pointing at the upstream repo.

[changeset-bot]

⚠️ No Changeset found

Latest commit: f5cf345

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[moshest]

Thanks for this — the descriptions are unusually careful, and I checked the claims in them rather than taking them at face value. Everything factual holds up:

• ref: stable exists on godotengine/godot-docs.
• docs_path: tutorials/scripting/gdscript exists and contains exactly the 9 files your description advertises (basics, advanced, exports, static typing, style guide, warning system, doc comments, format string).
• The class reference is committed here — classes/ has 1079 .rst files including class_@gdscript.rst and class_@globalscope.rst. Worth stating explicitly because the similar-looking systemd case in #116 fails precisely here (its man pages are generated at build time, not committed), so "official docs repo" doesn't imply the reference is actually in it. Yours is.

I also built both definitions locally, since CI doesn't cover registry YAML:

package	sections	tokens
gdscript	129	60,921
godot	14,488	8,136,608

Both build successfully.

One thing worth changing before merge

godot has no docs_path, so it indexes the whole repository — which includes tutorials/scripting/gdscript/, the entire contents of the gdscript package. The two descriptions tell readers to use one for syntax and the other for engine APIs, but as written godot is a superset and those 9 files get indexed twice.

The schema already supports the fix (registry/java/java.yaml uses exclude_paths):

source:
  type: git
  url: https://github.com/godotengine/godot-docs
  ref: stable
  exclude_paths:
    - "tutorials/scripting/gdscript/**"

That makes the split you describe actually true.

Two notes for the maintainer, not asks of you

• Size. 8.1M tokens is by far the largest definition here — 133× your gdscript package, and ~37× the systemd prototype measured in #116. I found no documented size ceiling in the registry code, so this isn't a rule violation, just worth a deliberate decision rather than an accidental one.
• No CI ran on this PR (zero check runs), and separately ci.yml doesn't validate registry/*.yaml at all — it lints/builds/tests the TS packages only. A definition with a wrong ref or docs_path would pass review and first fail in the 06:00 nightly. That's a gap in our tooling, not in your contribution.

Not approving since the exclude_paths question is the author's call, but the definitions themselves are sound and I'm happy to see them land.

---

Generated by Claude Code

[moshest]

Correcting my review above: the exclude_paths suggestion doesn't work, and you already said so in your description.

I verified it in the code rather than leaving it as competing claims — GitSourceSchema (packages/registry/src/definition.ts:27-39) declares only type, url, ref, docs_path and lang, and both excludePaths call sites in build.ts (lines 100 and 142) sit inside source.type === "zip" branches. exclude_paths is zip-only exactly as you wrote. I generalised from registry/java/java.yaml without checking that it's a zip source. Disregard that part — there's nothing for you to change.

Your routing rationale answers the overlap point too, and with measurements I didn't have: C# taking 40% of tutorials/scripting and winning signal, await and export is a concrete reason to narrow the path, not a stylistic preference. The duplication between the two packages is real but unavoidable without git-source exclude_paths, and the cross-referencing descriptions are the right handling given that.

Adding exclude_paths to git sources looks like a contained change — the schema field plus plumbing it into the git branch alongside the zip one — but that belongs in its own PR, not stacked onto this one.

Two things on CI, since this PR has never had any:

• Workflow runs on it are gated. The Registry Validate run is sitting at action_required, so a maintainer has to approve it before anything executes. That's why you've seen zero checks throughout, and it isn't anything you did.
• I synced your branch with main so it picks up ci: build changed registry definitions on the pull request #134, which builds changed registry definitions on the PR. That's a merge commit, not a rebase, so your local checkout stays valid.

For what it's worth, I built both definitions locally before any of that: gdscript 129 sections / 60,921 tokens and godot 14,488 sections / 8,136,608 tokens, matching your table. The classes/ question I wanted to check — whether the class reference is actually committed rather than generated at build time, which is what sinks the systemd case in #116 — comes out in your favour: 1079 .rst files including class_@gdscript.rst and class_@globalscope.rst.

---

Generated by Claude Code

[moshest]

Follow-up: exclude_paths now works on git sources — #135 is merged into main.

So the suggestion I got wrong earlier is available for real, if you want it. Sync this branch and godot could carry:

source:
  type: git
  url: https://github.com/godotengine/godot-docs
  ref: stable
  exclude_paths:
    - "tutorials/scripting/gdscript/**"

Patterns match relative to docs_path when one is set, or the repo root when it isn't, so the pattern above is right for godot as written.

This isn't a request to change anything. Your analysis is what motivated the feature, and the routing you designed — cross-referencing descriptions, gdscript narrow, godot complete — is defensible exactly as it stands. Keeping the tutorials in godot means someone querying only that package still finds them, which is a real argument against excluding. Your call entirely; the PR is fine either way and I'd merge it as-is.

One thing worth knowing, since it also came out of your description: the wider tutorials/scripting path you rejected is now viable too. With exclude_paths you could prune c_sharp/** and cpp/** and keep scripting/ root and debug/ — the autoloads, resources, groups and node-tree material that the narrow path drops. That wasn't possible when you opened this. Also its own decision, and a bigger change than anything I'd expect you to take on here.

Still gated on a maintainer: workflow runs on this PR sit at action_required, so no CI has executed on it yet. That needs @moshest to approve the run — nothing you can clear from your side.

---

Generated by Claude Code

[moshest]

The Windows listDefinitions() bug you flagged is fixed and merged — #136.

Your diagnosis was exact: loadDefinition compares parsed.name against relative(managerDir, filePath), which returns platform separators, so @apollo\client never matches @apollo/client. Since listDefinitions() loads everything, one scoped package took down every registry command on Windows.

I used .replaceAll("\\", "/") rather than the split(sep).join("/") you suggested, for one reason worth mentioning since yours is the more idiomatic spelling: sep is / on Linux, so split(sep) leaves backslashes untouched and the Windows behaviour becomes a branch that no Linux CI run ever executes. Normalising unconditionally keeps one code path on both platforms.

The regression test reproduces your failure on Linux — a literal backslash in a filename is a single filename here rather than a separator, but the string reaching the comparison is byte-identical to what Windows produces. It fails without the fix with your exact error text.

Thanks for reporting it separately instead of folding it into this PR. It was easy to pick up as its own change precisely because you kept them apart, and a Windows-only failure in a Linux-only CI setup is the kind of thing that would otherwise have sat unnoticed indefinitely.

This PR still needs @moshest to approve its workflow run before any CI can execute on it — unchanged from my last comment, and still not something you can clear.

---

Generated by Claude Code