Skip to content

Generate the .idp schema from core's table of config.idp keys - #37

Merged
Kinflou merged 3 commits into
mainfrom
idp-schema-from-core
Nov 15, 2026
Merged

Kinflou merged 3 commits into
mainfrom
idp-schema-from-core

Conversation

@Kinflou

@Kinflou Kinflou commented Nov 15, 2026 •

Copy link
Copy Markdown
Member

Closes #31. Also closes the part of #22 that #31 absorbed.

core#292 is merged: comline.idpSchema.rev pins its merge commit (4d5b19c), and the generated file is the same bytes it was at the PR's head.

Problem

src/idpSchema.ts was a hand-written mirror of core's config.idp reader, and the language server leaves .idp key completion and hover outside settings to the client, so a key missing here was missing in the editor. It had drifted: no id, handshake, settings, unverified, encodings or dependency accept_unverified; wire named datagram@2 the default; specification_version was called a "schema format version".

Fix: the schema is generated from core, not written

Core keeps a table of every key its reader takes (package::config::keys), with types, allowed values, defaults and prose, and commits it as schemas/config-idp.json. Its tests hold the table to the reader in both directions, so a key added to the reader without the table fails there (core#292). The values come from where core declares them (official encodings, comline@2's parameters, the editions, the guarantees), so there is one copy of each.

  • src/idpSchema.generated.json: that file, byte for byte, at the core commit comline.idpSchema.rev pins in package.json, next to comline.languageServer.rev.
  • scripts/sync-idp-schema.mjs: checks the committed copy against the pin (--write refreshes it, --rev tries another commit), as the docs repo does for comline.toml's schema (sync-comline-toml-schema.py). Node built-ins only.
  • CI, Config schema: runs the script, so it fails when the committed copy is not what the pin generates, or the pin is not on GitHub.
  • src/idpSchema.ts: the 200 lines of keys are gone. The engine stays (comment stripping, key path at the cursor, schema walk). It gains the shapes core writes: choice (a string from a closed set, with its default), list, oneOf (handshake and unverified are a name or a dictionary, publish_registries entries a string or a dictionary) and settings, and a required flag. A version it doesn't know is an error, so a bump of the file's shape in core can't be read as the old one.
  • What is still written here: code_generation.languages stays the CLI's live list of targets (ensureTargetsLoaded), because its keys are checked against the generators the configured CLI has; core describes it as a map and the extension replaces it, with one sentence added to core's description saying so. Nothing else.
  • Labels and hover: a choice shows its values ("packed@1" | "json@1" | "msgpack@1"), an either-or shows both ("comline@1" | "comline@2" | "none" | dictionary), and hover on handshake, unverified or an entry lists the dictionary's fields, with required. ahead of the ones a dictionary needs.

#31, item by item

  • specification_version: described as the edition, with the editions core knows.
  • wire: format is packed@1 (default), json@1 or msgpack@1; framing is datagram@3 (default), datagram@2, datagram@1 or jsonrpc@1; a namespaced name declared under encodings is allowed too.
  • handshake: the name (comline@1, comline@2, none) or the dictionary, name and comline@2's four parameters, defaults first: scope protocol | package, newer_consumer degrade | refuse, same_version_differs refuse | warn, exchange offer | symmetric.
  • id, settings, unverified (a reason, or one per guarantee), encodings (kind, profile, map per language with type, package, version).
  • Dependency accept_unverified: protocol names to lists of guarantees.
  • Dependency group: not here; core#284 hasn't landed, and it appears by bumping the pin.
  • The full key list is checked against the reader by core's tests rather than by hand here.

Tests

src/idpSchema.test.ts, in yarn test: the engine against core's shapes (a name or a dictionary, a map's entry names, settings left to the language server, a version it doesn't read), and what #31 found missing, by key. It doesn't list the whole schema, so a bump doesn't break it.

Not here

  • A Renovate manager for comline.idpSchema.rev: a bump needs --write in the same pull request, which Renovate can't do. Instead, an advisory CI step (The pin should be current) warns when core's schemas/config-idp.json on its default branch differs from the pinned copy, like the language-server pin's check.
  • Value completion (wire = { format = | } offering the formats): the schema now has the values, the completion provider still offers keys only.
  • The language server serving .idp itself, which makes this copy unnecessary.

Comment thread src/idpSchema.test.ts Fixed
@Kinflou
Kinflou marked this pull request as ready for review November 15, 2026 22:24
@Kinflou
Kinflou merged commit 33ba3c5 into main Nov 15, 2026
28 checks passed
@Kinflou
Kinflou deleted the idp-schema-from-core branch November 15, 2026 22:40
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.

config.idp schema (idpSchema.ts) has drifted from core's reader

2 participants