feat(release): ship an OpenAPI fragment, a frozen manifest and a bundle (phase 3, slice 5) #6
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: RunicGateway/Module-uo#6
Reference in New Issue
Block a user
No description provided.
Delete Branch "feature/close-phase3"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
The three artifacts that make this module installable and checkable, closing phase 3's extraction. Nothing about what the module serves changes — the same 72 URLs, the same behaviour.
Pairs with website#141 (core's half: the request-time merge into
/api/docs.json, and the last of core's UO copy) and docs#140. Merge this one first.The OpenAPI fragment was never built, on either side
MODULE_API.md§2.8 and §6.1a say every module shipsswagger-fragment.jsonand core merges started modules' fragments into/api/docs.json. Neither half existed. The 417#swaggerannotations came across in slice 1 and went nowhere, andsrc/app.jsserved the committed spec flat — so every route this module serves was in no OpenAPI spec at all. That is core's standing rule ("never ship a route that isn't in the spec") being broken by the extraction rather than by a route, and it is why it is fixed here rather than left to phase 4.server/scripts/swaggerFragment.jsgenerates it, and the prefixes are derived: the script runs the module's ownregister()against a recordingapiand asksrequire.cachewhich file each router object came from. A mount prefix therefore exists in one place —server/index.js— and not in a table beside it.The 31 schemas moved here from core's
swagger/swagger.js, namespacedUo…because core wins every key collision in the merge and two games' modules must be able to describe the same idea.ErrorandValidationErrorstay referenced by core's names and are not redefined — they resolve in the merged document, which is the point of a fragment.The frozen manifest is derived by subtraction
MODULE_API.md§5.3. Thefrozen-manifestjob clones core at the ref pinned inci/core-ref.json, generates its route manifest without this module and then with it, and takes the difference.Taking the difference rather than filtering by prefix buys the half of §5.3 that matters most for free: a module that shadowed or displaced one of core's routes shows up as a removal, not merely as an addition somewhere else. That is the frozen-URL promise §1.2 makes to the shipped Android app and the Discord bot.
The same job is where the fragment meets ground truth — a real core reporting the URLs it actually serves. Every route must have an operation, and every operation must be a route. It is the only check in this repo that can tell whether "the prefix I register" and "the path I document" name the same URL; everything else here compares two strings in the same repo.
Releases
A merge to
mainthat leavesmodule.jsonat a version with no release yet publishesmodule-uo-<version>.tar.gzplusmodule-uo-<version>.jsoncarrying itssha256.linkandinstaller.module.json's version is what core records ininstalled_modules; two sources for one number is how they drift.mainneeds no push exception. That is the installer's model, adopted for the reason it was adopted there.Five annotation defects, inherited and invisible until now
Nothing had ever generated a spec from these files, so nothing had ever read their annotations:
requestBodyliterals a brace short — the route documented with an empty body;"and a backtick to'before evaluating, so either inside a single-quoted description ends the string early.itemIdlost its type, itsrequiredand its description and was silently re-inferred as an untyped string.It reports each one and then prints
Successin green. The generator now captures its diagnostics and makes them fatal — the same class as every other failure in this seam, except that here the tool did say something and nothing was listening.The fifth needed a browser. Nineteen descriptions carried
\'— correct JavaScript, and wrong here, because swagger-autogen does not evaluate the annotation as JS. The backslash survived into the fragment and Swagger UI rendered "the shard\'s published ruleset" to a reader. The fragment was valid JSON, the paths were right, every test passed. Only opening the page found it.Also found while writing it: passing one shared
docto swagger-autogen six times. It renderscomponents.schemasfrom an example object and writes the result back into what it was handed, so each pass re-wrapped the last — the fragment came out at 484 MB.Verification
check:importscleanswagger-fragment.json— 69 paths covering all 72 routes, 0 undocumented, 0 unservedroutes.manifest.json— 72 routes; 0 of core's own routes removed or changed/api/docs: the module's operations render under their own tags, no dangling$refs, zero console errorsAI-assisted contribution. Written with Claude Code (Claude Opus). Commits carry
Co-Authored-By: Claude <noreply@anthropic.com>.🤖 Generated with Claude Code
The three artifacts that make this module installable and checkable, closing phase 3's extraction. Nothing about what the module serves changes: the same 72 URLs, the same behaviour. **The OpenAPI fragment (MODULE_API.md §2.8, §6.1a) was never built, on either side.** The 417 `#swagger` annotations came across in slice 1 and went nowhere, and core's /api/docs.json merged nothing — so every route this module serves was in no spec at all, which is core's standing rule ("never ship a route that isn't in the spec") being broken by the extraction rather than by a route. `server/scripts/swaggerFragment.js` generates it. The prefixes are DERIVED: the script runs the module's own `register()` against a recording api and asks `require.cache` which file each router came from, so a mount prefix exists in one place — `server/index.js` — and not in a table beside it. The 31 schemas moved here from core's swagger.js, namespaced `Uo…` because core wins every key collision in the merge; `Error` and `ValidationError` stay referenced by core's names, since they resolve in the merged document. **The frozen route manifest (§5.3)** is derived too, and by subtraction: CI clones core at the ref pinned in ci/core-ref.json, generates its manifest without this module and then with it, and the difference is what this module serves. That buys the half of §5.3 that matters most for free — a module that shadowed or displaced one of core's routes shows up as a REMOVAL, not merely as an addition elsewhere. The same job checks the fragment against ground truth: every route must have an operation and every operation must be a route. **The release workflow** publishes `module-uo-<version>.tar.gz` plus a manifest carrying its sha256. The version is declared in module.json rather than computed from commit subjects, and the workflow never writes to a branch — it tags and publishes — so `main` needs no push exception. The bundle is assembled from an include list, because an exclude list ships whatever it forgot. Four annotation defects, inherited from core and never visible until something generated a spec from these files: two `requestBody` literals a brace short (the route documented with an empty body), and two descriptions whose inner quoting swagger-autogen cannot survive — it re-quotes `"` and a backtick to `'` before evaluating, so either inside a single-quoted description ends the string early and the annotation is dropped. It reports each one and then prints Success in green, so the generator now captures its diagnostics and makes them fatal. Also fixed while writing it: passing one shared `doc` to swagger-autogen six times. It renders components.schemas from an EXAMPLE object and writes the result back into what it was handed, so each pass re-wrapped the last and the fragment came out at 484 MB. - 409 server tests (+21), 40 client tests unchanged - swagger-fragment.json: 69 paths covering all 72 routes - routes.manifest.json: 72 routes; core's own surface unchanged, 0 removals - verified end to end by assembling the bundle exactly as CI will, unpacking it into a real core and regenerating the manifest Refs: docs/website/MODULE_SYSTEM.md §2.7.1, MODULE_API.md §2.8, §5.3, §6.1a Co-Authored-By: Claude <noreply@anthropic.com>