Repository navigation
Self-projections of the authoring surface: files, rules language, CLI and SDK - #12
Open
agorischek wants to merge 2 commits into
Open
agorischek wants to merge 2 commits into
agorischek wants to merge 2 commits into
Conversation
…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
force-pushed
the
agorischek/authoring-api-projection
branch
from
November 17, 2026 18:58
a73f019 to
d3235fc
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
apirenderer with the default comparator: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$defstype and one per field, nested (Definition.execution.timeoutMs). Signatures are TypeScript-like with constraints, for exampletimeoutMs?: integer (≥ 1, ≤ 300000).packages/comparators/rules/language.json: library functions, macros, the protocol types CEL expressions read (with their fields in the signature), and the budget.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,prandlicensesare left out (definitioninputs.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) withnode --testtests. Reusable: the JSON Schema →api/v0part 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/projectionsTypeScript API (built-ins only, no--trust)This uses the built-in
typescript-public-apiover the package's entry points, with a tsconfig whosepathsmap the workspace packages to their sources. Changes are classified by theapi-compatibilitycomparator file. It has 1,620 declarations../testingis left out becausetypescript-public-apioverflows the TypeScript checker's stack on its Playwright fixture types (RangeError: Maximum call stack size exceededingetConditionalTypeInstantiation). That is an extractor bug worth an issue.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-revisionreplays Let bookmark run compare bookmarks saved before their projection #7:bookmark run --definition-revisionis added, and--definitionloses its literal default (= base).projections bookmark run --trustpasses.node --test .github/projections/self-authoring-api/andprojections check -p self-authoring-api -p self-authoring-sdk --trust.Screenshots
#7 in Diff (light, dark):
Current state (dark), and the definition's fields (light):
The SDK projection on a demo edit (not committed): additive changes classified and listed first among 1,621 declarations (light, dark).
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 20api-compatibilitycomparator test casesprojections bookmark run --trustnode --test .github/projections/self-authoring-api/and the API renderer'snpm testandtypechecknpm run docs:check,format:check,check:boundaries,check:portability,check:casing,check:links,check:readmes, Considered, and eslint on the changed pathsThis is rebased onto #11. The bookmark entry is added to its
.projections-bookmarks.json.