Skip to content

Self-projections of the authoring surface: files, rules language, CLI and SDK - #12

Open
agorischek wants to merge 2 commits into
mainfrom
agorischek/authoring-api-projection
Open

agorischek wants to merge 2 commits into
mainfrom
agorischek/authoring-api-projection

Conversation

@agorischek

@agorischek agorischek commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Two self-projections of the authoring surface, the parts someone writing a projection uses, plus a small fix to the API renderer that large APIs need.

self-authoring-api: files, rules language and CLI (custom extractor, --trust)

479 declarations, drawn by the built-in api renderer with the default comparator:

  • Documents, from their JSON Schemas (packages/schemas/schemas/*/v0.json): the definition, comparator file, comparator tests, extractor request (stdin), extraction (stdout), renderer scenarios and environment file. Each has a row for the document, one per $defs type and one per field, nested (Definition.execution.timeoutMs). Signatures are TypeScript-like with constraints, for example timeoutMs?: integer (≥ 1, ≤ 300000).
  • Comparator rules language, from packages/comparators/rules/language.json: library functions, macros, the protocol types CEL expressions read (with their fields in the signature), and the budget.
  • CLI commands and arguments, from the generated docs/reference/cli.md. CI keeps that page current, so each commit's copy describes that commit's CLI without building it. Signatures keep flags, value names, possible values, literal defaults, and whether an argument is repeatable or required. serve, mcp, view, canvas, pr and licenses are left out (definition inputs.cli.exclude). Those are other surfaces' transports and the agent viewer's commands, which the agent-tools projection covers (Add an agent-tools projection: the tools agents call, on every surface #11), plus review and legal commands. Leaving them out also keeps the projection under the renderer's 500-row limit.

Prose (description, help text) is left out, just as API signatures leave out doc comments.

The extractor is about 300 lines (schemas.mjs, json-lines.mjs, rules.mjs, cli.mjs) with node --test tests. Reusable: the JSON Schema → api/v0 part would make a good built-in (json-schema-api). Any repository with config-file or message schemas could review their surface that way. A clap/CLI-reference reader is the second candidate.

self-authoring-sdk: @githubnext/projections TypeScript API (built-ins only, no --trust)

This uses the built-in typescript-public-api over the package's entry points, with a tsconfig whose paths map the workspace packages to their sources. Changes are classified by the api-compatibility comparator file. It has 1,620 declarations.

API renderer: changes first when a Diff doesn't fit

The renderer lists at most 500 rows in ID order, so a Diff of a large API cut its changes off after the limit. When the rows don't all fit, changed rows now come first (breaking ones first, as before). Rows that fit keep their order. Docs and a test are updated.

Bookmark and CI

  • authoring-definition-revision replays Let bookmark run compare bookmarks saved before their projection #7: bookmark run --definition-revision is added, and --definition loses its literal default (= base). projections bookmark run --trust passes.
  • The CI self-projection step also runs node --test .github/projections/self-authoring-api/ and projections check -p self-authoring-api -p self-authoring-sdk --trust.

Screenshots

#7 in Diff (light, dark):

The bookmark for #7: bookmark run --definition-revision added, --definition modified with its default struck through
The same comparison in the dark theme

Current state (dark), and the definition's fields (light):

The authoring API's current state: global options and commands with their signatures
The definition's execution and extractor fields with their typed signatures

The SDK projection on a demo edit (not committed): additive changes classified and listed first among 1,621 declarations (light, dark).

The SDK projection's Diff: MAX_GENERATED_VALUES added, basisDigest and sha256 modified, each marked Additive, ahead of unchanged rows
The same comparison in the dark theme

Checks run

  • projections check -p self-authoring-api -p self-authoring-sdk --trust: all pass, including renderer checks on the working tree and HEAD → working tree, and the 20 api-compatibility comparator test cases
  • projections bookmark run --trust
  • node --test .github/projections/self-authoring-api/ and the API renderer's npm test and typecheck
  • npm run docs:check, format:check, check:boundaries, check:portability, check:casing, check:links, check:readmes, Considered, and eslint on the changed paths

This is rebased onto #11. The bookmark entry is added to its .projections-bookmarks.json.

@agorischek
agorischek requested a review from a team as a code owner November 17, 2026 17:33
agorischek and others added 2 commits November 17, 2026 10:52
…nges first

The renderer lists at most 500 declarations, in ID order, so a large API's
diff cut its changes off with the unchanged rows after the limit. When a
Diff's rows don't all fit, the changed ones now come first (breaking first,
as before), each group in its own order; rows that fit keep their order.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…f-authoring-sdk

self-authoring-api (api renderer, custom extractor) lists what projection
authors write and run: the fields and types of the definition, comparator
file and tests, extractor request and extraction, renderer scenarios and
environment file (from their JSON Schemas), the comparator rules language
(functions, macros, types, budget, from language.json) and the CLI's
commands and arguments (from the generated CLI reference, without serve,
mcp, view, canvas, pr and licenses). Prose is left out, as API signatures
leave out documentation.

self-authoring-sdk is the built-in typescript-public-api over
@githubnext/projections' entry points, with the api-compatibility
comparator file. ./testing is left out: the extractor overflows the
TypeScript checker's stack on its Playwright fixture types.

A bookmark replays #7, where bookmark run gained --definition-revision and
--definition lost its literal default. CI checks both projections.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@agorischek
agorischek force-pushed the agorischek/authoring-api-projection branch from a73f019 to d3235fc Compare November 17, 2026 18:58

This branch has not been deployed

No deployments
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