diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b61a229..09cc6f1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -126,6 +126,49 @@ jobs: echo "The pinned server and the CLI both use comline-core ${server_core:0:7}." fi + # The keys of `config.idp` (completion and hover in a `.idp`) are core's: core + # keeps a table of what its reader takes, held to the reader by its tests, and + # `src/idpSchema.generated.json` is that file at the rev `package.json` pins + # (`comline.idpSchema.rev`). Fails when the committed copy is not what the pin + # generates, or the pin is not on GitHub. + idp-schema: + name: Config schema + runs-on: ubuntu-24.04 + timeout-minutes: 10 + + steps: + - name: Harden the runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + + - name: Checkout code + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Setup Node.js + uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 + with: + node-version: 20.20.2 + + - name: The committed schema must be core's at the pinned rev + run: node scripts/sync-idp-schema.mjs + + # Advisory, like the language-server pin's: core changing what + # `config.idp` takes doesn't fail anything here, so say when the pin is + # behind core's default branch. A failed lookup is a warning too. + - name: The pin should be current + run: | + url=https://raw.githubusercontent.com/ComlineProject/core/HEAD/schemas/config-idp.json + if ! curl -fsSL --retry 3 "$url" -o "$RUNNER_TEMP/config-idp.json"; then + echo "::warning::couldn't fetch core's schemas/config-idp.json to check the pin" + elif cmp -s "$RUNNER_TEMP/config-idp.json" src/idpSchema.generated.json; then + echo "The pinned schema is core's current one." + else + echo "::warning file=package.json::core's schemas/config-idp.json has changed since comline.idpSchema.rev: bump the pin and run 'node scripts/sync-idp-schema.mjs --write'" + fi + package-test: name: Package Test runs-on: ubuntu-24.04 diff --git a/CHANGELOG.md b/CHANGELOG.md index 49d7a2e..198978f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,22 @@ All notable changes to the "comline-vscode" extension will be documented in this ## [Unreleased] ### Added +- `.idp` completion and hover know every key core reads (#31). Missing before: + `id`, `handshake` (the name, and the dictionary form with `comline@2`'s + `scope`, `newer_consumer`, `same_version_differs` and `exchange`, each with its + values and its default first), `settings`, `unverified`, `encodings` (with + `kind`, `profile` and the per-language `map`) and a dependency's + `accept_unverified`. `wire` lists the formats and framings core declares and + names `datagram@3` as the default framing, and `specification_version` is + described as the edition. Completion marks a key a dictionary needs as + required. Dependency `group` follows core#284. +- The `.idp` schema is generated, not written: core keeps a table of every key its + reader takes (held to the reader by core's tests) and commits it as + `schemas/config-idp.json`; `src/idpSchema.generated.json` is that file at the + core commit `comline.idpSchema.rev` pins, refreshed by + `node scripts/sync-idp-schema.mjs --write`. CI fails when the committed copy + differs from the pin, so the schema can't drift from core again, and warns + when core's schema has moved past the pin. - The package status bar item's tooltip says which language server and CLI are in use: each one's version with its `comline-core` commit, and its path with how it was found (bundled, PATH, custom path, or on the host). The CLI's diff --git a/RELEASING.md b/RELEASING.md index 856419a..43816ed 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -70,6 +70,13 @@ the CLI's. The server reports its core in `comline-lsp --version`. > the release builds. Committing that lockfile would make releases fully > reproducible. +The keys `.idp` completion and hover offer are core's, too: `src/idpSchema.generated.json` +is core's `schemas/config-idp.json` at the core commit +`comline.idpSchema.rev` pins. To follow core, move the pin and run +`node scripts/sync-idp-schema.mjs --write`; CI fails when the committed file is +not what the pin generates, and warns when core's current schema differs from +the pinned one. + The `comline` CLI is **not** bundled. Build/Check/Generate/Clean need it on `PATH` (see the README's Requirements section). @@ -81,7 +88,8 @@ The `comline` CLI is **not** bundled. Build/Check/Generate/Clean need it on and start a fresh empty `## [Unreleased]` above it. That section becomes the release notes word for word. - optionally move `comline.languageServer.rev` to a newer `language-server` - commit + commit, and `comline.idpSchema.rev` to a newer core commit (then + `node scripts/sync-idp-schema.mjs --write`) Merge it. diff --git a/package.json b/package.json index eb0de6d..48baf04 100644 --- a/package.json +++ b/package.json @@ -16,6 +16,9 @@ "comline": { "languageServer": { "rev": "c56715ab44de036544150151a7eaf440d531c323" + }, + "idpSchema": { + "rev": "4d5b19ca61871ee52423b8284acf20b664c8cf8e" } }, "categories": [ @@ -268,7 +271,7 @@ "compile": "tsc -p ./", "watch": "tsc -watch -p ./", "pretest": "yarn compile", - "test": "node --test out/resolve.test.js out/coreRev.test.js", + "test": "node --test out/resolve.test.js out/coreRev.test.js out/idpSchema.test.js", "lint": "eslint src --ext ts", "package": "bash scripts/package.sh", "link-binary": "bash scripts/link-binary.sh", diff --git a/scripts/sync-idp-schema.mjs b/scripts/sync-idp-schema.mjs new file mode 100644 index 0000000..872befc --- /dev/null +++ b/scripts/sync-idp-schema.mjs @@ -0,0 +1,63 @@ +#!/usr/bin/env node +// Keep `src/idpSchema.generated.json`, the keys of `config.idp`, equal to core's. +// +// node scripts/sync-idp-schema.mjs # check; exit 1 on drift +// node scripts/sync-idp-schema.mjs --write # refresh the committed copy +// node scripts/sync-idp-schema.mjs --rev [--write] +// +// Core keeps a table of every key its `config.idp` reader takes, with types, +// allowed values, defaults and prose (`comline_core::package::config::keys`, +// held to the reader by core's own tests), and commits it as +// `schemas/config-idp.json`. This copies that file at the core commit +// `comline.idpSchema.rev` in package.json pins (`--rev` tries another one), the +// way the docs repo keeps its copy of the `comline.toml` schema. Bump the pin +// when core changes what `config.idp` takes, then `--write`. +// +// Run by CI (`idp-schema` in ci.yml). Node built-ins only, so it runs before +// `yarn install`. + +import { readFileSync, writeFileSync } from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; + +const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); +const copy = path.join(root, "src", "idpSchema.generated.json"); + +const args = process.argv.slice(2); +const write = args.includes("--write"); +const revFlag = args.indexOf("--rev"); +const pinned = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8")).comline?.idpSchema?.rev; +const rev = revFlag >= 0 ? args[revFlag + 1] : pinned; +if (!rev || !/^[0-9a-f]{40}$/.test(rev)) { + console.error("sync-idp-schema: no core rev: set comline.idpSchema.rev in package.json (40 hex digits), or pass --rev"); + process.exit(2); +} + +const url = `https://raw.githubusercontent.com/ComlineProject/core/${rev}/schemas/config-idp.json`; +const response = await fetch(url); +if (!response.ok) { + console.error(`sync-idp-schema: ${url}: ${response.status} ${response.statusText}`); + process.exit(2); +} +const upstream = await response.text(); + +const name = path.relative(root, copy); +if (write) { + writeFileSync(copy, upstream); + console.log(`wrote ${name} from core ${rev.slice(0, 7)}`); + process.exit(0); +} + +let current = ""; +try { + current = readFileSync(copy, "utf8"); +} catch { + // Missing counts as different. +} +if (current === upstream) { + console.log(`${name}: up to date with core ${rev.slice(0, 7)}`); +} else { + console.error(`${name} differs from ${url}`); + console.error("Refresh with:\n node scripts/sync-idp-schema.mjs --write"); + process.exit(1); +} diff --git a/src/extension.ts b/src/extension.ts index 1728e6d..2483bb2 100644 --- a/src/extension.ts +++ b/src/extension.ts @@ -43,6 +43,8 @@ import { resolveSchemaAtPath, resolveFieldByPathAndWord, idpValueKindLabel, + dictionaryFieldsOf, + mapEntryOf, IdpFieldSchema, } from './idpSchema'; import { @@ -787,7 +789,7 @@ class LanguagesCompletionProvider { const item = new CompletionItem(field.key, CompletionItemKind.Field); item.insertText = field.key; item.range = range; - item.detail = idpValueKindLabel(field.value); + item.detail = `${idpValueKindLabel(field.value)}${field.required ? ' (required)' : ''}`; item.documentation = new MarkdownString(field.description); return item; }); @@ -800,7 +802,7 @@ class LanguagesCompletionProvider { function renderFieldsBlock(fields: IdpFieldSchema[]): string { const lines = fields.map((f) => ({ keyType: `${f.key}: ${idpValueKindLabel(f.value)}`, - summary: f.summary, + summary: f.required ? `required. ${f.summary}` : f.summary, })); const width = Math.max(...lines.map((l) => l.keyType.length)); return lines.map((l) => `${l.keyType.padEnd(width)} // ${l.summary}`).join('\n'); @@ -818,13 +820,16 @@ function renderFieldHover(field: IdpFieldSchema): MarkdownString { md.appendMarkdown('---\n\n'); md.appendMarkdown(`${field.description}\n`); - if (field.value.kind === 'dictionary' && field.value.fields.length > 0) { + const fields = dictionaryFieldsOf(field.value); + const entry = mapEntryOf(field.value); + const entryFields = entry ? dictionaryFieldsOf(entry.value) : undefined; + if (fields && fields.length > 0) { md.appendMarkdown('\n---\n\n#### Fields\n\n'); - md.appendCodeblock(renderFieldsBlock(field.value.fields), 'comline-package'); - } else if (field.value.kind === 'map' && field.value.entry.value.kind === 'dictionary') { - md.appendMarkdown(`\n---\n\n#### Each entry (${field.value.entry.key})\n\n`); - md.appendMarkdown(`${field.value.entry.description}\n\n`); - md.appendCodeblock(renderFieldsBlock(field.value.entry.value.fields), 'comline-package'); + md.appendCodeblock(renderFieldsBlock(fields), 'comline-package'); + } else if (entry && entryFields && entryFields.length > 0) { + md.appendMarkdown(`\n---\n\n#### Each entry (${entry.key})\n\n`); + md.appendMarkdown(`${entry.description}\n\n`); + md.appendCodeblock(renderFieldsBlock(entryFields), 'comline-package'); } return md; diff --git a/src/idpSchema.generated.json b/src/idpSchema.generated.json new file mode 100644 index 0000000..3b3547a --- /dev/null +++ b/src/idpSchema.generated.json @@ -0,0 +1,460 @@ +{ + "$comment": "Generated from comline_core::package::config::keys; regenerate with `COMLINE_BLESS=1 cargo test -p comline-core --lib config::keys`.", + "keys": [ + { + "description": "The edition of the schema language this package is written in, as a number; this core knows edition 1. A change that would break schemas already written ships in a new edition, and a package keeps its behaviour until it moves to it. Every package states one.", + "key": "specification_version", + "summary": "The edition of the schema language this package is written in", + "value": { + "kind": "integer", + "values": [ + 1 + ] + } + }, + { + "description": "The package's identity for the compatibility check: 32 lowercase hex digits. `comline new` and `comline build` write one when it's missing. A rename keeps it, a copy must change it, and changing it is a major change.", + "key": "id", + "summary": "The package's identity, written by comline build", + "value": { + "kind": "string" + } + }, + { + "description": "Declares what this package can be compiled to. Its only key is `languages`. Per-target output (directory, layout, package versions) lives in `comline.toml`'s `[generate]` table, not here.", + "key": "code_generation", + "summary": "What this package can be compiled to", + "value": { + "fields": [ + { + "description": "The `language#version` targets this package declares it can generate. Each entry's value must be an empty dict (`lang#ver = {}`: it takes no options). A target is checked against the generators the CLI has when the package is generated, not here.", + "key": "languages", + "summary": "Targets this package can generate, checked by the generators", + "value": { + "entry": { + "description": "A language and the version of its generator, written `rust#1.70.0`. The value is `{}`: a declared target takes no options.", + "key": "#", + "summary": "A target, taking no options", + "value": { + "fields": [], + "kind": "dictionary" + } + }, + "kind": "map" + } + } + ], + "kind": "dictionary" + } + }, + { + "description": "The package's wire defaults, which both ends of a connection must agree on: `wire = { format = \"packed@1\" framing = \"datagram@3\" }`. Leaving out either key gives its default, shown there. A protocol's own `@framing` wins over `framing`.", + "key": "wire", + "summary": "The wire format and framing both ends speak", + "value": { + "fields": [ + { + "description": "How values are encoded, `\"packed@1\"` where left out: fixed-width fields and no tags for `packed@1`, UTF-8 JSON for `json@1`, MessagePack for `msgpack@1`, or a namespaced format the package or a dependency declares under `encodings`. JSON-RPC protocols always speak JSON.", + "key": "format", + "summary": "How values are encoded", + "value": { + "default": "packed@1", + "kind": "choice", + "namespaced": true, + "values": [ + "packed@1", + "json@1", + "msgpack@1" + ] + } + }, + { + "description": "How calls are framed, for every protocol with no `@framing` of its own; `\"datagram@3\"` where left out. The `datagram` framings are Comline's own binary one: `datagram@3` and `datagram@2` are a connection, where either end can call and several protocols share one transport (`datagram@3` addresses a call by its wire number), `datagram@1` is lockstep, one protocol per transport. `jsonrpc@1` is JSON-RPC 2.0. Or a namespaced framing a package declares under `encodings`.", + "key": "framing", + "summary": "How calls are framed", + "value": { + "default": "datagram@3", + "kind": "choice", + "namespaced": true, + "values": [ + "jsonrpc", + "datagram", + "datagram@2", + "datagram@3" + ] + } + } + ], + "kind": "dictionary" + } + }, + { + "description": "The handshake each protocol of the package runs when it names none in `@handshake`: a name, `handshake = \"comline@2\"`, or a dictionary when the handshake takes parameters, `handshake = { name = \"comline@2\" scope = \"package\" }`. Left out, it is `comline@2`, or `comline@1` in a package whose protocols can't all run `comline@2`. A protocol's own `@handshake` replaces the package's whole. Only `comline@2` takes parameters.", + "key": "handshake", + "summary": "The handshake the package's protocols run", + "value": { + "alternatives": [ + { + "kind": "choice", + "namespaced": true, + "values": [ + "comline@1", + "comline@2", + "none" + ] + }, + { + "fields": [ + { + "description": "Which handshake the package's protocols run. The same as the plain form: `handshake = \"comline@2\"` is `{ name = \"comline@2\" }`.", + "key": "name", + "required": true, + "summary": "The handshake", + "value": { + "kind": "choice", + "namespaced": true, + "values": [ + "comline@1", + "comline@2", + "none" + ] + } + }, + { + "description": "Whether a protocol's refusal refuses that protocol alone (`protocol`) or the whole connection (`package`). A parameter of `comline@2`, `protocol` where left out. Each end applies it on its own.", + "key": "scope", + "summary": "Whether a refusal reaches the protocol or the connection", + "value": { + "default": "protocol", + "kind": "choice", + "values": [ + "protocol", + "package" + ] + } + }, + { + "description": "When the consumer has functions the provider lacks: `degrade` connects, and calls to them fail locally; `refuse` refuses the protocol. A parameter of `comline@2`, `degrade` where left out. Each end applies it on its own.", + "key": "newer_consumer", + "summary": "What a consumer with more functions gets", + "value": { + "default": "degrade", + "kind": "choice", + "values": [ + "degrade", + "refuse" + ] + } + }, + { + "description": "When two versions are equal but their shapes differ: `refuse` refuses the protocol, `warn` connects and reports a warning, which gives up version honesty. A parameter of `comline@2`, `refuse` where left out. Each end applies it on its own.", + "key": "same_version_differs", + "summary": "What equal versions with different shapes get", + "value": { + "default": "refuse", + "kind": "choice", + "values": [ + "refuse", + "warn" + ] + } + }, + { + "description": "Who sends what: `offer` is a hello, an answer and a verdict, `symmetric` has each end send a hello and a verdict. A parameter of `comline@2`, `offer` where left out. Both ends must agree on it.", + "key": "exchange", + "summary": "Who sends what in the handshake", + "value": { + "default": "offer", + "kind": "choice", + "values": [ + "offer", + "symmetric" + ] + } + } + ], + "kind": "dictionary" + } + ], + "kind": "oneOf" + } + }, + { + "description": "Acknowledges, for the whole package, the guarantees its protocols give up through the package's handshake, wire or settings: one reason, `unverified = \"the gateway pins schemas by contract\"`, or a reason for each guarantee, `unverified = { schema_agreement = \"...\" }`. A protocol's own `@unverified` wins where both say.", + "key": "unverified", + "summary": "Guarantees the package gives up, with a reason", + "value": { + "alternatives": [ + { + "kind": "string" + }, + { + "fields": [ + { + "description": "The reason the package gives up `schema_agreement`, for the protocols that take it from the package.", + "key": "schema_agreement", + "summary": "Why the package gives this guarantee up", + "value": { + "kind": "string" + } + }, + { + "description": "The reason the package gives up `encoding_agreement`, for the protocols that take it from the package.", + "key": "encoding_agreement", + "summary": "Why the package gives this guarantee up", + "value": { + "kind": "string" + } + }, + { + "description": "The reason the package gives up `encoding_conformance`, for the protocols that take it from the package.", + "key": "encoding_conformance", + "summary": "Why the package gives this guarantee up", + "value": { + "kind": "string" + } + }, + { + "description": "The reason the package gives up `version_honesty`, for the protocols that take it from the package.", + "key": "version_honesty", + "summary": "Why the package gives this guarantee up", + "value": { + "kind": "string" + } + }, + { + "description": "The reason the package gives up `bounded_size`, for the protocols that take it from the package.", + "key": "bounded_size", + "summary": "Why the package gives this guarantee up", + "value": { + "kind": "string" + } + } + ], + "kind": "dictionary" + } + ], + "kind": "oneOf" + } + }, + { + "description": "Package-wide authoring policy, applying to every schema by default: which annotations and validators are allowed, bounds, and diagnostic levels. Its keys are the settings registry's, which the language server completes and explains inside the block. A dictionary, or a reference to another package's named settings schema.", + "key": "settings", + "summary": "Authoring policy for every schema in the package", + "value": { + "kind": "settings" + } + }, + { + "description": "Formats, framings and handshakes beyond the official ones, keyed by a namespaced name (`com.acme.x@1`). Each has a profile, a file in the package that states what it establishes, and may suggest how each language implements it.", + "key": "encodings", + "summary": "Encodings the package declares", + "value": { + "entry": { + "description": "A namespaced name, `com.acme.x@1`, with the kind of encoding and its profile.", + "key": "@", + "summary": "An encoding and its profile", + "value": { + "fields": [ + { + "description": "What the encoding is.", + "key": "kind", + "required": true, + "summary": "format, framing or handshake", + "value": { + "kind": "choice", + "values": [ + "format", + "framing", + "handshake" + ] + } + }, + { + "description": "The path of the encoding's profile (JSON), relative to the package and inside it. Its kind and name must be this entry's. Conformance vectors sit beside it: `profiles/x.json`'s are `profiles/x.vectors.json`.", + "key": "profile", + "required": true, + "summary": "The profile's path, inside the package", + "value": { + "kind": "string" + } + }, + { + "description": "Where each language finds a type implementing the encoding, keyed by language.", + "key": "map", + "summary": "Suggested implementations, by language", + "value": { + "entry": { + "description": "The type that implements the encoding in this language, and optionally the package and version it comes from.", + "key": "", + "summary": "How one language implements the encoding", + "value": { + "fields": [ + { + "description": "The type implementing the encoding.", + "key": "type", + "required": true, + "summary": "The implementing type", + "value": { + "kind": "string" + } + }, + { + "description": "The package the type comes from.", + "key": "package", + "summary": "The package the type comes from", + "value": { + "kind": "string" + } + }, + { + "description": "The version of that package.", + "key": "version", + "summary": "The package's version", + "value": { + "kind": "string" + } + } + ], + "kind": "dictionary" + } + }, + "kind": "map" + } + } + ], + "kind": "dictionary" + } + }, + "kind": "map" + } + }, + { + "description": "Named publish destinations for this package, keyed by a name you choose.", + "key": "publish_registries", + "summary": "Named publish destinations, keyed by name you choose", + "value": { + "entry": { + "description": "A string, identifier, or namespaced reference to a registry, or a dictionary with a `uri`.", + "key": "", + "summary": "A publish registry reference", + "value": { + "alternatives": [ + { + "kind": "string" + }, + { + "fields": [ + { + "description": "The registry URI.", + "key": "uri", + "summary": "The registry URI", + "value": { + "kind": "string" + } + } + ], + "kind": "dictionary" + } + ], + "kind": "oneOf" + } + }, + "kind": "map" + } + }, + { + "description": "This package's dependencies, keyed by a name you choose. It can't be `self`, `parent`, `package` or `std`.", + "key": "dependencies", + "summary": "This package's dependencies, keyed by name you choose", + "value": { + "entry": { + "description": "A Path dependency (`path`), a Git dependency (`version` + `uri` + `commit`), or a Registry dependency (`version` + `uri`): which fields are present determines the kind.", + "key": "", + "summary": "A Path, Git, or Registry dependency", + "value": { + "fields": [ + { + "description": "Local filesystem path to a sibling package, which makes this a Path dependency (no declared version; its version is read from the sibling's own last build).", + "key": "path", + "summary": "Local path, which makes this a Path dependency", + "value": { + "kind": "string" + } + }, + { + "description": "Declared version. Required for Git and Registry dependencies (omit for Path dependencies).", + "key": "version", + "summary": "Declared version (Git and Registry dependencies)", + "value": { + "kind": "string" + } + }, + { + "description": "Source URI. Required for Git and Registry dependencies.", + "key": "uri", + "summary": "Source URI (Git and Registry dependencies)", + "value": { + "kind": "string" + } + }, + { + "description": "Pinned commit hash. Its presence makes this a Git dependency (needs `version` and `uri` too).", + "key": "commit", + "summary": "Pinned commit, which makes this a Git dependency", + "value": { + "kind": "string" + } + }, + { + "description": "Optional integrity hash (e.g. `blake3:...`). Valid on any dependency kind.", + "key": "hash", + "summary": "Optional integrity hash", + "value": { + "kind": "string" + } + }, + { + "description": "Optional signature. Registry dependencies only.", + "key": "signature", + "summary": "Optional signature (Registry dependencies only)", + "value": { + "kind": "string" + } + }, + { + "description": "The dependency's `@unverified` protocols this package accepts, each with the guarantees it was accepted for: `accept_unverified = { Billing = [\"schema_agreement\"] }`. If the dependency gives up more, the build stops until it's accepted again; `comline accept` writes it.", + "key": "accept_unverified", + "summary": "The dependency's unverified protocols this package accepts", + "value": { + "entry": { + "description": "The guarantees accepted for this protocol of the dependency.", + "key": "", + "summary": "The guarantees accepted for one protocol", + "value": { + "item": { + "kind": "choice", + "values": [ + "schema_agreement", + "encoding_agreement", + "encoding_conformance", + "version_honesty", + "bounded_size" + ] + }, + "kind": "list" + } + }, + "kind": "map" + } + } + ], + "kind": "dictionary" + } + }, + "kind": "map" + } + } + ], + "version": 1 +} diff --git a/src/idpSchema.test.ts b/src/idpSchema.test.ts new file mode 100644 index 0000000..ad7bb09 --- /dev/null +++ b/src/idpSchema.test.ts @@ -0,0 +1,170 @@ +// Run with `yarn test` (node's built-in runner, on the compiled output). +// +// The schema's contents are core's (`idpSchema.generated.json`), so these +// don't list its keys: they hold the engine to the shapes core writes, and +// pin what comline-vscode#31 found missing. + +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { + IDP_ROOT_FIELDS, + IdpFieldSchema, + IdpValueKind, + idpValueKindLabel, + keyPathAt, + loadIdpSchema, + resolveFieldByPathAndWord, + resolveSchemaAtPath, + stripNonCode, +} from './idpSchema'; + +const keys = (fields: IdpFieldSchema[]): string[] => fields.map((f) => f.key); + +const fieldsAt = (path: string[]): IdpFieldSchema[] => { + const resolved = resolveSchemaAtPath(path); + assert.ok(resolved && 'fields' in resolved, `fields at ${path.join('.')}`); + return resolved.fields; +}; + +/** The path of the cursor at `|` in `source`. */ +const pathAtBar = (source: string): string[] => { + const offset = source.indexOf('|'); + const text = source.slice(0, offset) + source.slice(offset + 1); + return keyPathAt(stripNonCode(text), offset); +}; + +const walk = (field: IdpFieldSchema, visit: (f: IdpFieldSchema) => void): void => { + visit(field); + const nested = (value: IdpValueKind): void => { + switch (value.kind) { + case 'dictionary': + value.fields.forEach((f) => walk(f, visit)); + break; + case 'map': + walk(value.entry, visit); + break; + case 'oneOf': + value.alternatives.forEach(nested); + break; + case 'list': + nested(value.item); + break; + } + }; + nested(field.value); +}; + +test('every field core describes has a one-line summary and a description', () => { + let seen = 0; + for (const root of IDP_ROOT_FIELDS) { + walk(root, (f) => { + seen++; + assert.ok(f.summary.length > 0 && !f.summary.includes('\n'), `${f.key}: summary`); + assert.ok(f.description.length > 0, `${f.key}: description`); + }); + } + assert.ok(seen > 20, `only ${seen} fields`); +}); + +test('the root keys include what the schema had missed (#31)', () => { + const root = keys(IDP_ROOT_FIELDS); + for (const key of ['specification_version', 'id', 'handshake', 'settings', 'unverified', 'encodings']) { + assert.ok(root.includes(key), `${key} in ${root.join(', ')}`); + } +}); + +test('specification_version is the edition, not a schema format version', () => { + const field = IDP_ROOT_FIELDS.find((f) => f.key === 'specification_version'); + assert.ok(field); + assert.match(field.description, /edition/); + assert.doesNotMatch(field.description, /schema format version/); +}); + +test('wire lists the formats and framings core declares, with their defaults', () => { + const wire = Object.fromEntries(fieldsAt(['wire']).map((f) => [f.key, f.value])); + const format = wire.format; + const framing = wire.framing; + assert.equal(format.kind, 'choice'); + assert.equal(framing.kind, 'choice'); + if (format.kind === 'choice' && framing.kind === 'choice') { + assert.equal(format.default, 'packed@1'); + assert.ok(format.values.includes('json@1') && format.values.includes('msgpack@1')); + assert.equal(framing.default, 'datagram@3'); + assert.ok(framing.values.includes('datagram@2')); + } + const text = IDP_ROOT_FIELDS.find((f) => f.key === 'wire')?.description ?? ''; + assert.doesNotMatch(text, /framing = "datagram@2"/); +}); + +test('handshake is a name or a dictionary of comline@2 parameters, default first', () => { + const handshake = IDP_ROOT_FIELDS.find((f) => f.key === 'handshake'); + assert.ok(handshake); + assert.equal(handshake.value.kind, 'oneOf'); + + const fields = fieldsAt(['handshake']); + assert.deepEqual(keys(fields), ['name', 'scope', 'newer_consumer', 'same_version_differs', 'exchange']); + const values = (key: string): string[] | undefined => { + const value = fields.find((f) => f.key === key)?.value; + return value?.kind === 'choice' ? value.values : undefined; + }; + assert.deepEqual(values('scope'), ['protocol', 'package']); + assert.deepEqual(values('newer_consumer'), ['degrade', 'refuse']); + assert.deepEqual(values('same_version_differs'), ['refuse', 'warn']); + assert.deepEqual(values('exchange'), ['offer', 'symmetric']); + assert.equal(fields.find((f) => f.key === 'name')?.required, true); +}); + +test('a dependency takes accept_unverified', () => { + const dependency = keys(fieldsAt(['dependencies', 'shared'])); + for (const key of ['path', 'version', 'uri', 'commit', 'hash', 'signature', 'accept_unverified']) { + assert.ok(dependency.includes(key), `${key} in ${dependency.join(', ')}`); + } +}); + +test('code_generation.languages is the CLI registry, not core’s entries', () => { + assert.deepEqual(keys(fieldsAt(['code_generation'])), ['languages']); + assert.deepEqual(resolveSchemaAtPath(['code_generation', 'languages']), { isRegistry: true }); + const languages = resolveFieldByPathAndWord(['code_generation'], 'languages'); + assert.equal(languages?.value.kind, 'registry'); + assert.match(languages?.description ?? '', /currently configured/); +}); + +test('the walk follows a name or a dictionary, and a map’s entry names', () => { + assert.deepEqual(keys(fieldsAt(['publish_registries', 'mine'])), ['uri']); + // `encodings = { "com.acme.x@1" = { map = { rust = { | } } } }` + assert.deepEqual(keys(fieldsAt(['encodings', '', 'map', ''])), ['type', 'package', 'version']); + assert.deepEqual(keys(fieldsAt(['encodings', ''])), ['kind', 'profile', 'map']); + // Inside `settings` the language server answers, and the schema says nothing. + assert.deepEqual(fieldsAt(['settings']), []); + assert.equal(resolveSchemaAtPath(['nonsense']), undefined); + // At a map itself the names are the user's. + assert.deepEqual(fieldsAt(['dependencies']), []); +}); + +test('the cursor’s path is found in text', () => { + assert.deepEqual(pathAtBar('handshake = { name = "comline@2" | }'), ['handshake']); + assert.deepEqual(pathAtBar('dependencies = { a = { | } }'), ['dependencies', 'a']); + assert.deepEqual(pathAtBar('/* wire = { */ id = "x"\nwire = { | }'), ['wire']); + assert.deepEqual(pathAtBar('id = "{" |'), []); +}); + +test('hover finds a key by the block it is in', () => { + assert.equal(resolveFieldByPathAndWord(['handshake'], 'exchange')?.key, 'exchange'); + assert.equal(resolveFieldByPathAndWord([], 'handshake')?.key, 'handshake'); + assert.equal(resolveFieldByPathAndWord(['handshake'], 'nope'), undefined); +}); + +test('labels show a choice’s values and an either-or', () => { + assert.equal(idpValueKindLabel({ kind: 'choice', values: ['a', 'b'] }), '"a" | "b"'); + assert.equal(idpValueKindLabel({ kind: 'integer', values: [1] }), '1'); + assert.equal(idpValueKindLabel({ kind: 'integer' }), 'integer'); + assert.equal( + idpValueKindLabel({ kind: 'oneOf', alternatives: [{ kind: 'string' }, { kind: 'dictionary', fields: [] }] }), + 'string | dictionary' + ); + assert.equal(idpValueKindLabel({ kind: 'list', item: { kind: 'string' } }), '[string]'); +}); + +test('a file in a version this extension does not read is refused', () => { + assert.throws(() => loadIdpSchema({ version: 99, keys: [] }), /version 99/); +}); diff --git a/src/idpSchema.ts b/src/idpSchema.ts index fda40f2..1b5b2c4 100644 --- a/src/idpSchema.ts +++ b/src/idpSchema.ts @@ -1,36 +1,49 @@ -// A hand-authored schema for `.idp` ("congregation" package config) plus the -// text-heuristic engine that resolves "what key-path is the cursor inside" -// against it. No `.idp` parser exists client-side (or in the language server -// at all — confirmed, see extension.ts), so this works off plain text -// scanning, in the same spirit as the language server's -// `completion.rs::determine_context` for `.ids`. That function only strips -// `//` line comments, which is correct only for `.ids` — `.idp` has `/* */` -// block comments too (confirmed in +// The schema of `.idp` ("congregation" package config) plus the text-heuristic +// engine that resolves "what key-path is the cursor inside" against it. No +// `.idp` parser exists client-side (or in the language server at all — +// confirmed, see extension.ts), so this works off plain text scanning, in the +// same spirit as the language server's `completion.rs::determine_context` for +// `.ids`. That function only strips `//` line comments, which is correct only +// for `.ids` — `.idp` has `/* */` block comments too (confirmed in // `core/core/src/package/config/idl/grammar.rs`), so this independently // strips both, plus string contents, before any brace-depth counting or key // search runs. // -// The schema itself is authoritative against -// `core/core/src/package/config/ir/interpreter/freezing.rs` and -// `core/core/src/package/config/dependency.rs` — there is no serde/typed -// schema on the Rust side to introspect (it's a hand-written, string-key- -// switching interpreter that `panic!`s on anything it doesn't recognize), so -// this is a manual mirror, kept in sync by hand. `code_generation.languages` -// is the one dynamic exception: its keys are open `name#version` tokens -// validated only at `comline generate` time against the compiled-in -// generator registry — see `comline.cli.*` / `ensureTargetsLoaded` in -// extension.ts for how that list is fetched live instead of guessed here. +// The schema itself is not written here. Core's reader is a hand-written, +// string-key-switching interpreter, so core keeps a table of the keys it reads +// (`comline_core::package::config::keys`, held to the reader by its tests) and +// commits it as `schemas/config-idp.json`. `idpSchema.generated.json` is that +// file at the core commit `comline.idpSchema.rev` in package.json pins, and +// `scripts/sync-idp-schema.mjs` keeps it so (CI fails when it differs): +// a key core reads shows up here by bumping the pin, not by editing this file. +// Only `code_generation.languages` is overridden below: its keys are open +// `name#version` tokens validated at `comline generation` time against the +// generators the CLI has, so the extension offers the CLI's live list (see +// `comline.cli.*` / `ensureTargetsLoaded` in extension.ts) instead of +// guessing. +import generated from './idpSchema.generated.json'; + +/** The shape of a value, as core's table writes it + * (`comline_core::package::config::keys::ConfigShape`). */ export type IdpValueKind = - | { kind: 'integer' } + | { kind: 'integer'; values?: number[] } | { kind: 'string' } + // A string from a closed set; `default` is what applies where it's left out, + // `namespaced` whether a name declared under `encodings` is allowed too. + | { kind: 'choice'; values: string[]; default?: string; namespaced?: boolean } + | { kind: 'list'; item: IdpValueKind } | { kind: 'dictionary'; fields: IdpFieldSchema[] } - // `code_generation.languages` specifically — dynamic `name#version` keys, - // validated live against the configured `comline` CLI, not this schema. - | { kind: 'registry' } // A dictionary whose keys are user-chosen names (a dependency name, a // publish-registry name) — `entry` describes the shape of each value. - | { kind: 'map'; entry: IdpFieldSchema }; + | { kind: 'map'; entry: IdpFieldSchema } + // Any one of these (`handshake`: a name, or a dictionary). + | { kind: 'oneOf'; alternatives: IdpValueKind[] } + // The settings registry's keys, which the language server serves. + | { kind: 'settings' } + // `code_generation.languages` specifically — dynamic `name#version` keys, + // validated live against the configured `comline` CLI, not this schema. + | { kind: 'registry' }; export interface IdpFieldSchema { key: string; @@ -41,167 +54,65 @@ export interface IdpFieldSchema { summary: string; /** The full explanation, shown when this field is hovered directly. */ description: string; + /** Whether the dictionary it is in is wrong without it. */ + required?: boolean; value: IdpValueKind; } -const DEPENDENCY_ENTRY_FIELDS: IdpFieldSchema[] = [ - { - key: 'path', - summary: 'Local path — makes this a Path dependency', - description: - 'Local filesystem path to a sibling package — makes this a Path dependency (no declared ' + - "version; its version is read from the sibling's own last build).", - value: { kind: 'string' }, - }, - { - key: 'version', - summary: 'Declared version (Git/Registry dependencies)', - description: 'Declared version. Required for Git and Registry dependencies (omit for Path dependencies).', - value: { kind: 'string' }, - }, - { - key: 'uri', - summary: 'Source URI (Git/Registry dependencies)', - description: 'Source URI. Required for Git and Registry dependencies.', - value: { kind: 'string' }, - }, - { - key: 'commit', - summary: 'Pinned commit — makes this a Git dependency', - description: - 'Pinned commit hash — presence of this key makes this a Git dependency (needs `version` ' + - 'and `uri` too).', - value: { kind: 'string' }, - }, - { - key: 'hash', - summary: 'Optional integrity hash', - description: 'Optional integrity hash (e.g. `blake3:...`). Valid on any dependency kind.', - value: { kind: 'string' }, - }, - { - key: 'signature', - summary: 'Optional signature (Registry dependencies only)', - description: 'Optional signature. Registry dependencies only.', - value: { kind: 'string' }, - }, -]; - -const PUBLISH_REGISTRY_ENTRY_FIELDS: IdpFieldSchema[] = [ - { - key: 'uri', - summary: 'The registry URI', - description: 'The registry URI.', - value: { kind: 'string' }, - }, -]; - -export const IDP_ROOT_FIELDS: IdpFieldSchema[] = [ - { - key: 'specification_version', - summary: 'The .idp schema format version', - description: 'The `.idp` schema format version this file is written against.', - value: { kind: 'integer' }, - }, - { - key: 'code_generation', - summary: 'What this package can be compiled to', - description: - 'Declares what this package can be compiled to. Its only key is `languages`. ' + - "Per-target output (directory, layout, package versions) lives in `comline.toml`'s " + - '`[generate]` table, not here.', - value: { - kind: 'dictionary', - fields: [ - { - key: 'languages', - summary: 'Targets this package can generate, CLI-validated', - description: - 'The `language#version` targets this package declares it can generate. ' + - "Each entry's value must be an empty dict (`lang#ver = {}` — it takes no options). " + - 'Completion offers targets the *currently configured* `comline` CLI can generate.', - value: { kind: 'registry' }, - }, - ], - }, - }, - { - key: 'wire', - summary: 'The wire format and framing both ends speak', - description: - "The package's wire defaults, which both ends of a connection must agree on: " + - '`wire = { format = "packed@1" framing = "datagram@2" }`. Leaving out either key gives ' + - 'its default, shown there. A protocol\'s own `@framing` wins over `framing`.', - value: { - kind: 'dictionary', - fields: [ - { - key: 'format', - summary: 'packed@1 (default), json@1 or msgpack@1', - description: - 'How values are encoded: `"packed@1"` (the default: fixed-width fields, no tags), ' + - '`"json@1"` or `"msgpack@1"`. JSON-RPC protocols always speak JSON.', - value: { kind: 'string' }, - }, - { - key: 'framing', - summary: 'datagram@2 (default), datagram or jsonrpc', - description: - 'How calls are framed, for every protocol with no `@framing` of its own: ' + - '`"datagram@2"` (the default: a connection, where either end can call and several ' + - 'protocols share one transport), `"datagram"` (lockstep, one protocol per ' + - 'transport) or `"jsonrpc"`.', - value: { kind: 'string' }, - }, - ], - }, - }, - { - key: 'publish_registries', - summary: 'Named publish destinations, keyed by name you choose', - description: 'Named publish destinations for this package, keyed by a name you choose.', - value: { - kind: 'map', - entry: { - key: '', - summary: 'A publish registry reference', - description: - 'A string, identifier, or namespaced reference to a registry, or a dictionary ' + - 'with a `uri`.', - value: { kind: 'dictionary', fields: PUBLISH_REGISTRY_ENTRY_FIELDS }, - }, - }, - }, - { - key: 'dependencies', - summary: "This package's dependencies, keyed by name you choose", - description: "This package's dependencies, keyed by a name you choose.", - value: { - kind: 'map', - entry: { - key: '', - summary: 'A Path, Git, or Registry dependency', - description: - 'A Path dependency (`path`), a Git dependency (`version` + `uri` + `commit`), or a ' + - 'Registry dependency (`version` + `uri`) — which fields are present determines the kind.', - value: { kind: 'dictionary', fields: DEPENDENCY_ENTRY_FIELDS }, - }, - }, - }, -]; +/** The file's own version, which core bumps when it changes the shape. */ +const SUPPORTED_SCHEMA_VERSION = 1; + +const REGISTRY_NOTE = + 'Completion offers the targets the *currently configured* `comline` CLI can generate.'; + +/** `code_generation.languages` as the extension serves it: core's field, its + * entries replaced by the CLI's live list. */ +function withRegistry(fields: IdpFieldSchema[]): IdpFieldSchema[] { + return fields.map((field) => { + if (field.key !== 'code_generation' || field.value.kind !== 'dictionary') { + return field; + } + const languages = field.value.fields.map((f) => + f.key === 'languages' + ? { ...f, description: `${f.description} ${REGISTRY_NOTE}`, value: { kind: 'registry' } as IdpValueKind } + : f + ); + return { ...field, value: { kind: 'dictionary', fields: languages } as IdpValueKind }; + }); +} + +/** The root keys of `config.idp`, from core's table. */ +export function loadIdpSchema(file: { version: number; keys: unknown }): IdpFieldSchema[] { + if (file.version !== SUPPORTED_SCHEMA_VERSION) { + throw new Error( + `idpSchema.generated.json is version ${file.version}, this extension reads ${SUPPORTED_SCHEMA_VERSION}` + ); + } + return withRegistry(file.keys as IdpFieldSchema[]); +} + +export const IDP_ROOT_FIELDS: IdpFieldSchema[] = loadIdpSchema(generated); export function idpValueKindLabel(value: IdpValueKind): string { switch (value.kind) { case 'integer': - return 'integer'; + return value.values && value.values.length > 0 ? value.values.join(' | ') : 'integer'; case 'string': return 'string'; + case 'choice': + return value.values.map((v) => `"${v}"`).join(' | '); + case 'list': + return `[${idpValueKindLabel(value.item)}]`; case 'dictionary': return 'dictionary'; case 'registry': return 'languages registry'; case 'map': return 'dictionary (named entries)'; + case 'oneOf': + return value.alternatives.map(idpValueKindLabel).join(' | '); + case 'settings': + return 'dictionary (settings)'; default: { const exhaustive: never = value; return exhaustive; @@ -209,6 +120,38 @@ export function idpValueKindLabel(value: IdpValueKind): string { } } +/** The fields of the dictionary a value is, or one of its alternatives is. */ +export function dictionaryFieldsOf(value: IdpValueKind): IdpFieldSchema[] | undefined { + if (value.kind === 'dictionary') { + return value.fields; + } + if (value.kind === 'oneOf') { + for (const alternative of value.alternatives) { + const fields = dictionaryFieldsOf(alternative); + if (fields) { + return fields; + } + } + } + return undefined; +} + +/** The entry of the map a value is, or one of its alternatives is. */ +export function mapEntryOf(value: IdpValueKind): IdpFieldSchema | undefined { + if (value.kind === 'map') { + return value.entry; + } + if (value.kind === 'oneOf') { + for (const alternative of value.alternatives) { + const entry = mapEntryOf(alternative); + if (entry) { + return entry; + } + } + } + return undefined; +} + /** * Blanks `//` line comments, `/* *\/` block comments, and `"..."` string * contents to spaces — preserving length, offsets, and newlines — so brace @@ -382,16 +325,25 @@ export type SchemaAtPath = { fields: IdpFieldSchema[] } | { isRegistry: true } | /** Walks the schema along `path` (a `keyPathAt` result) — a path segment at * a `map` node is treated as a user-chosen key (looked up by shape, not by - * name), since dependency/registry names are never fixed. */ + * name), since dependency/registry names are never fixed. A value that is one + * of several (`handshake`: a name or a dictionary) is walked by its + * dictionary. */ export function resolveSchemaAtPath(path: string[]): SchemaAtPath { let fields: IdpFieldSchema[] | undefined = IDP_ROOT_FIELDS; let pendingMapEntry: IdpFieldSchema | undefined; for (const key of path) { if (pendingMapEntry) { - const value = pendingMapEntry.value; + const value: IdpValueKind = pendingMapEntry.value; pendingMapEntry = undefined; - fields = value.kind === 'dictionary' ? value.fields : []; + const entry = mapEntryOf(value); + if (entry) { + // A map of maps: this segment names an entry, the next is inside it. + pendingMapEntry = entry; + fields = undefined; + } else { + fields = dictionaryFieldsOf(value) ?? []; + } continue; } @@ -403,18 +355,15 @@ export function resolveSchemaAtPath(path: string[]): SchemaAtPath { return undefined; } - switch (field.value.kind) { - case 'dictionary': - fields = field.value.fields; - break; - case 'registry': - return { isRegistry: true }; - case 'map': - pendingMapEntry = field; - fields = undefined; - break; - default: - fields = []; + if (field.value.kind === 'registry') { + return { isRegistry: true }; + } + const entry = mapEntryOf(field.value); + if (entry) { + pendingMapEntry = entry; + fields = undefined; + } else { + fields = dictionaryFieldsOf(field.value) ?? []; } }