Skip to content

feat(modules-lib): a description of the types of a module's exports, piloted on rune - #999

Merged
martin-henz merged 2 commits into
masterfrom
module-descriptions-pilot
Nov 9, 2026
Merged

martin-henz merged 2 commits into
masterfrom
module-descriptions-pilot

Conversation

@martin-henz

Copy link
Copy Markdown
Member

First step of #997 (design settled in #996): the format, and a pilot on rune.

What

  • @sourceacademy/modules-lib/description: the format (version 1) as a JSON-serializable TypeScript type: number, integer, string, boolean, void, any, named opaque types (with optional type arguments), type parameters, list, pair, array, function types; functions and opaque types may have type parameters. Builders (opaque, fun, parameter, fn) to write one by hand.
  • validateDescription: what is wrong with a description in itself: a name described twice, an opaque type or type parameter that is not declared (or has the wrong number of arguments), an unknown version, and integer as a result (a module's number comes back as a float; integer is for a parameter that must be whole; a callback turns the direction around).
  • checkDescription(description, exportedSymbols): the above, and that the described names are exactly what the plugin exports. Give it plugin.exports after initialise(), not exportedNames: a plugin can export names when it is loaded.
  • rune: src/description.ts, the 38 functions and 11 shapes, with the Rune opaque type and the callback types written by hand; and description.test.ts, which checks it against the real plugin's exports after initialise(), so that a function that is added to the plugin without a description fails the bundle's tests.

Why this way

Not in this PR (next steps of #997): the build step that publishes description.json next to a bundle's index.js, the generator for the generated part (names and arities from exportedNames and attachModuleMethod signatures, TypeScript declarations), the other bundles, and py-slang fetching the description at run time. The format has no JSON schema file yet.

Tests: 9 for the format, 2 for rune. tsc and lint pass for rune and for the new files of modules-lib (the remaining warnings in modules-lib are in files this PR does not touch). The repo's pre-push hook passes (run as sh .husky/pre-push, about 90 s); the push itself used --no-verify because the SSH connection was closed while the hook ran inside git push.

🤖 Generated with Claude Code

…piloted on rune (#997)

The format (version 1), builders, validateDescription and checkDescription, which checks a
description against what a plugin exports after initialise(). rune describes its exports.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@martin-henz

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-09T03:46:22.801983Z 83d82d7 Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d5bbde6e94

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/bundles/rune/src/description.ts Resolved
…ption

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@martin-henz

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Chef's kiss.

Reviewed commit: 83d82d75fc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@martin-henz
martin-henz merged commit 2a5ee2d into master Nov 9, 2026
44 checks passed
@martin-henz
martin-henz deleted the module-descriptions-pilot branch November 9, 2026 03:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant