Ascribe 0.2.0

This release adds review: reading a pull request as readers will see it, page by page, with the changed blocks marked and the pull request's review comments beside them. It works in VS Code's page preview, in your site's own pages under astro dev, and as an HTML report CI can attach to every pull request. Comments are ordinary GitHub review comments, so there's nothing to set up or host. See Review.

The language

• @snippet puts a code example from a file in the page as a fenced code block: @snippet: code:examples/quill/ascribe.toml#dimensions. The file is read on every check, build, and diff, so the example changes when the code does. A region is marked in the code with Bluehawk's tags (:snippet-start:, :snippet-end:, :remove:). ascribe check reports a missing address, file, or region, and tags that don't balance (snippet-address and five more). See @snippet and Drift.
• [sources.<name>] in ascribe.toml names a folder of code outside the content that snippets may read, with include and ignore patterns. It's the only way a page reads outside its project's folder, and the folder must be in the project's git repository. See [sources.<name>].
• A source in another repository: git (and branch) in place of path. The files snippets use are copied into sources/<name>/ and pinned to a commit in ascribe.lock. Both are committed with the docs, so checking, building, diffing, and drift never reach the other repository. ascribe check reports copies that don't match the lock or the snippets (lock-invalid, source-copy-changed, and three more). See a source in another repository and Docs kept apart from the code.
• A table row can have an availability: an attribute block at the end of its first cell, | `stream` {available="self-managed preview 3.4"} | … |. A badge build marks the row, and a filter build removes it where it isn't available. The spec is checked as an @available line's is, within the table's own availability. Behavior change: a {key=value} that ends a body row's first cell was text and is now an attribute block, so a key other than available is an error (attribute-unknown-key). See table rows.
• A page title can show code. inline = "code" on a content type's string field reads code spans in it: title = { type = "string", inline = "code" } lets a page be titled "`ascribe.toml` reference". The site output writes the field as plain text, for <title> and search, and as HTML under the new key formatted (entry.data.formatted.title in an Astro layout). The JSON output has formatted too. Behavior changes: a type can no longer declare a field named formatted (model-field-reserved), and in a field that turns inline on, a backslash before punctuation is an escape and is removed, as in Markdown. See code in a field.
• A link can name a heading from a fragment the page includes: setup.md#prerequisites works when prerequisites comes from a fragment setup.md includes. It was an error (link-id-in-fragment, now retired). See @include.

The ascribe command

• ascribe diff shows what changed between a git revision and the working tree, as readers will see it: each build's changed pages, and the blocks added, removed, changed, or moved on them, with the words that changed. It compares resolved pages, so a page that changed only through a fragment, a phrase, or a build's settings is listed with the cause, and reformatting is no change. The default base is the merge base with the default branch, as in a pull request. --format json adds each block's source lines, for tools. It needs only git. It also says how many errors the working tree has, as do the HTML report and both previews, so a broken render isn't read as the change. See ascribe diff.
• ascribe diff --format html writes the changes as one self-contained HTML file: every changed page rendered with its changes marked, and the page as it will be and as it was a click away. It makes no network requests and runs nothing from the pages, so CI can attach it to a pull request. See the HTML report and the report in CI.
• ascribe drift lists the pages whose code examples changed between a git revision and the working tree: first those whose own text didn't change, so the words around the code may be out of date, then those that changed with their examples, then those whose examples no longer resolve. A region is compared as text, so an edit elsewhere in its file isn't a change. --format summary writes Markdown for a CI job's summary, --format json is for tools, and --exit-code exits 1 when an example broke, or changed while its page didn't. See ascribe drift and Drift.
• ascribe build --emit site --anchors marks each block of the site output with its source file and lines (data-ascribe-source, and data-ascribe-via for a block from a fragment). Without the flag, the output is unchanged. See the site-render contract.
• ascribe sources fetch makes the copies of sources in other repositories match ascribe.lock. ascribe sources update moves a source's pin to the head of its branch (or --to), copies again, and reports the commits, the copies, and the pages whose examples changed, as text, JSON, or Markdown for a pull request. ascribe sources status shows each pin and copy, offline. fetch and update run git with its own credentials, and are the only commands that reach the network. See ascribe sources.
• Each command's --help describes its options in the words of the command reference, whose option lists are generated from it, and ends with a link to its section on the docs site, https://ascribed-dev.com. -h shows the first paragraph of each.
• Fixed: the plain-markdown output (--emit plain) writes an inline <br> as a line break, or as ; in a table cell or heading. It was dropped, so code spans on either side ran together.

The editor

• Review in the preview. Ascribe: Start Review compares the active page's project with a base: the base of the branch's pull request, the default branch, or a revision you type. The preview marks what changed on the page and follows your edits. Its header shows the base and the page's changes, switches between Changes / As it will be / As it was, and steps through the changes and the changed pages. Ascribe: Changed Pages lists the pages the change touches, and a status bar item shows whether review is on and starts it. See Review in the preview.
• Comments in the preview. When the branch has an open pull request, the preview shows its review threads beside their blocks. You can reply, resolve, comment on any block, and submit or discard your review. New comments are visible only to you until you submit. Ascribe: Refresh Comments reads the threads again. Threads also show on their source lines, unless the GitHub Pull Requests extension shows them already (the new setting ascribe.review.sourceComments). Comments use VS Code's GitHub sign-in or the GitHub CLI's. Without either, review shows the changes only. See Comments in the preview.
• The site preview. Ascribe: Open Site Preview opens the active page on its project's dev server, in the browser, at the heading the editor shows. The preview panel's Page | Site switch shows it in the panel, following the active file. See Site preview.
• Ascribe: Open Preview to the Side is now Ascribe: Open Page Preview to the Side (the command id is unchanged). The new Ascribe: Open Page Preview opens the preview in place of the editor.
• The preview and the editor scroll together by block instead of by heading, in both directions, and double-clicking a block puts the cursor on its source line. ascribe.preview.scrollPreviewWithEditor and ascribe.preview.scrollEditorWithPreview turn each direction off.
• The preview takes scripts, event handlers, and javascript: URLs out of a page's HTML before showing it, as the review report does.
• The Settings editor describes each setting in the words of the editor guide, whose settings table is generated from it.

Astro

• Review in the site preview. In astro dev, an Ascribe review app in Astro's dev toolbar marks a change's blocks on the real page, in your site's layout, and shows the pull request's review threads beside them. Commenting goes through the GitHub CLI, which the dev server runs. It stays off when the dev server listens on the network, or when the Vite config lets other pages reach it. The review option (on by default) turns the app off. astro build output has no anchors, overlay, or review code. See Review in the site preview.
• astro dev writes its address to .ascribe/dev.json in the project, for the editor's site preview, and removes it when it stops.
• The anchors option turns source anchors on: "dev" in astro dev only, true always.
• A code block's title, such as a @snippet's, shows above it, in a <figure class="code-title"> with a <figcaption>. The codeTitles option turns it off. See code block titles.
• @ascribed/astro/Availability.astro renders a page's available frontmatter as the element library's badge: <Availability available={entry.data.available} />.
• The integration copies the generated schema into .astro/integrations/_ascribed_astro/schema.ts after each build. A site whose Ascribe project is outside the Astro root imports that copy, so type-checking finds astro/zod. See define the collection.
• A clean build's check summary (checked 14 files: 0 errors, 0 warnings) is logged as info, not as a warning.
• The npm packages' source maps include their sources, so Vite no longer warns that they point to missing files.

The language server

• It answers ascribe/review/setBase and ascribe/review/changes, and ascribe/preview with review: true adds the page's changes, for editors other than VS Code. See crates/tessera-lsp/README.md.

Installing

• The Linux binaries run on glibc 2.28 or later, instead of 2.39, so @ascribed/cli installs and runs in the build images of Vercel, AWS Amplify, and Cloudflare Pages as well as Netlify's.
• A canary of the npm packages, built from main, is published every night under the next tag: npm install @ascribed/cli@next @ascribed/astro@next. It comes with no promise of stability, and its ascribe --version names the commit it was built from. Releases still publish under latest.

@ascribed/review

• A new package, for hosts that show review. Its Node part finds the open pull request for a checkout's branch, reads its review threads, places each on its rendered block, and posts comments and replies into the reviewer's pending review. It talks to GitHub through the GitHub CLI or a token its host supplies, and stores no token. Its browser part marks a rendered page's changed blocks and draws the threads beside them. Comment bodies render from a safe subset of Markdown, with no raw HTML, and no image loads without a click. See packages/review.