For agents: start with the agent guide. Every page is Markdown by default; add Accept: text/html for HTML.

Code snippets quote a pinned source

Design brief; shipped at a646f7ffd00273d85fbe1d905d9cdb194fdc0f60.¶

@rat-stack/code-snippets gives an excerpt its exact source, checks its metadata, and builds both reader views from one model. See Write a wiki page for authoring steps and exact repair messages.¶

Lore explains design choices. Systems documents shipped behavior, as set out in the project vision.¶

The problem

A copied excerpt can stop matching its source. A reader needs the exact revision, file, and selected lines. An author needs errors that explain how to repair a broken reference.¶

The package reads pinned sources⁹ during content generation. It produces one snippet model for both renderers⁸. It reports changed selected lines as warnings without replacing the pinned text.¶

The authoring syntax

A Markdown code fence³⁹ is a block delimited by backticks. It differs from rat-stack’s enforcement fence.¶

Code fences are the only authoring syntax. Authors do not write <Code> elements. The internal component renderer remains an implementation detail.¶

Fence metadata means options on the opening line of a Markdown code block. It has these parts:¶

• An optional language token.¶
• Whitespace-separated key=value pairs.¶
• At most one highlight set, such as {3,5-7}.¶
• Unquoted or double-quoted values.¶

The accepted keys are repo, path, at, lines, and title. Unknown keys, duplicate keys, and malformed metadata are errors.¶

The shipped request records content, selection, and source repository, commit, file, and line numbers:¶

export class CodeRequest extends Schema.Class<CodeRequest>("CodeRequest")({
  body: Schema.String,
  commit: Schema.String,
  configured: Schema.Boolean,
  highlights: Schema.Array(RangeSchema),
  language: Schema.String,
  line: Schema.Int,
  path: Schema.String,
  rangeText: Schema.String,
  ranges: Schema.Array(RangeSchema),
  reference: Schema.Boolean,
  repo: Schema.String,
  sourcePath: Schema.String,
  title: Schema.String,
}) {}

configured distinguishes metadata fences from ordinary fences. ranges carries decoded selections.¶

A source reference has an empty body. These selected lines enforce the pin and path rules:¶

const validCommit = (value: string) => {
  for (let index = 0; index < value.length; index += 1) {
    const char = value.charAt(index);

    if (!(char >= "0" && char <= "9") && !(char >= "a" && char <= "f")) {
      return false;
    }
  }

  return value.length === 40;
};
const validPath = (value: string) =>
  !value.startsWith("/") &&
  !value.includes(":") &&
  !value
    .split("/")
    .some((part) => part === ".." || part === "" || part === ".");

Paths reject traversal, empty segments, dots, and colons.¶

For a source reference:¶

• repo identifies a configured repository. It defaults to rat-stack.¶
• path names a relative file path.¶
• at pins a full 40-character lowercase commit SHA, never a branch or tag.¶
• lines selects positive, ordered, non-overlapping inclusive ranges.¶
• Highlights use original source line numbers and stay inside visible ranges.¶
• Configured fences show at most 25 source lines. Collapsed gaps do not count.¶

The cap also covers inline fences with metadata. Ordinary fences without metadata keep their renderer and are not capped by this rule.¶

A path reference with body text fails with CodeBodyWithReference.¶

An explicit language wins. An unknown explicit language is an error. Without a language, a source reference infers it from the file extension.¶

An unmapped extension or an unlabelled inline fence uses markdown. The adapter maps svx to Markdown and txt to text; it accepts javascript explicitly.¶

Schema decoding¹⁷ parses unknown metadata into a CodeRequest at the boundary. Later stages receive decoded values.¶

The pipeline

Preflight⁹ checks every independent snippet job before any generated output is written.¶

fence nodes
    │ collect and decode
    ▼
CodeRequest
    │ resolve pinned Git object
    ▼
ResolvedCode
    │ tokenize the whole file
    ▼
HighlightedFile
    │ select lines, highlights, and gaps
    ▼
CodeSnippet
    │ all jobs pass preflight
    ├──────────────────────┐
    ▼                      ▼
HTML                   agent Markdown

Each stage adds facts. Both renderers use the same final model.¶

Whole-file tokenization⁷ comes before range selection. This preserves the preceding source context for multiline comments and strings.¶

Ports and adapters

A port is an application-owned interface. An adapter implements that interface for a provider. The package follows ports and adapters¹⁹.¶

Its core owns stage schemas, errors, and selection rules. Core imports neither Git nor Shiki.¶

SourceRepository resolves repository id, commit, and path through a decoded registry. Each entry contains id, adapter, and location. Optional fields are linkTemplate and the bootstrap remote.¶

The /git adapter reads any configured local Git repository. Mischief configures rat-stack to the clone used for generation. Link templates substitute {sha}, {path}, {start}, and {end}. A GitHub, GitLab, Forgejo, or link-free entry needs no core change.¶

The highlighter port⁷ exposes:¶

• Per-line tokens containing text, role, and fontStyle.¶
• Language, alias, and theme catalogues.¶
• An engine fingerprint: an identifier for the highlighter, version, and settings used in cache keys.¶

The /shiki adapter uses the existing build-only Shiki 3.23.0 pin. Shiki token types stay inside that adapter. A /plain adapter supplies uncoloured tokens for core tests.¶

A service is a named interface. A Layer describes how to build a service and supply its dependencies. A Scope²⁰ owns resource cleanup.¶

Layers¹² provide the adapters. Shiki acquisition and disposal stay inside a scoped Layer.¶

Mischief collects Markdown syntax-tree nodes, chooses component renderers, and owns markup, CSS, and reporting. Syntax styles obey the fence³⁹, including the existing accent rule.¶

Cache boundaries

During one build, caches reuse successful results whose inputs cannot change:¶

• Blob cache: repository, commit, and path.¶
• Whole-file token cache: content key and engine settings.¶
• Render cache: the canonical snippet content key.¶

Snippet decoration also depends on ranges and highlights. HEAD, diagnostics, and failures do not enter the immutable cache. There is no persistent cache initially. Content-addressed output and Turbo provide reuse between builds.¶

Errors as interface

Errors are part of the interface⁸. Each typed error keeps the source location, request context, and a repair instruction⁸. Range errors include requested ranges and actual file length when available. Invalid metadata retains raw values because no decoded request exists.¶

The report-level CodeBuildFailed holds collected failures. Error accumulation⁹ uses Effect.validate. validateAll is not the operation used here.¶

A dependent stage stops on failure. Unrelated jobs still run. No asset writer runs before successful preflight.¶

Source drift⁹ produces diagnostics while allowing the build to continue. The error model³⁶ separates expected failures from defects.¶

The testing approach

The package ships property tests¹⁸ for these rules. Mischief also tests the renderer integration.¶

Use a small plain-array reference model for visible line numbers, gaps, and highlights. Do not copy production selection logic into the model. See model-based testing¹⁴ and tests that earn their place²².¶

A changed key need not change output bytes. An engine version change can preserve token output.¶

Use property-based testing and shrinking¹⁸. Effect 4 exposes Arbitrary.schema through effect/Arbitrary. it.prop and it.effect.prop accept Schema or Arbitrary inputs.¶

The package uses 40 runs per property. P5 exercises Shiki. Other core properties use the plain adapter.¶

The test suite also checks:¶

• One exact-message example per error tag at the interface that reports errors.¶
• Byte comparisons for ordinary fences under the decided default language rule.¶
• A planted range or slicing bug that makes its property fail.¶
• Startup bundle checks for the build-only boundary.¶

Use tests that earn their place²² for planted-bug checks. Agents explore, tests remember⁷ connects exploration with repeatable behavior checks.¶

Prior art and where we differ

The scanner accepts only the grammar documented above, a stricter subset than the general MetaOptions parser.¶

Build-only limits

There is no remote source adapter, mirror synchronization, or persistent snippet cache in this design. A shallow clone must already contain the pinned commit and file-content Git object. Generation performs no checkout and no network fetch.¶

Run pnpm sources:fetch explicitly before generation when pinned objects are missing. It uses the configured bootstrap remote and verifies the requested commits.¶

Build-time work stays out of requests⁷. The Worker receives static assets. Git access, Shiki, and the snippet package stay in the build.¶

There is no state machine yet. This is one scoped Effect over immutable local objects. It has no retry policy, resumable acquisition, or externally driven state transitions. A machine would repeat the stage call graph without owning a lifecycle.¶

Lifecycles are machines²⁰ applies when remote acquisition adds retries, cancellation, or resumability. That future adapter must use declared Effect actors rather than inline side effects.¶

See the glossary for fence metadata and the linked concepts.¶

Last changed 2026-10-10 in 978dccc. Source on GitHub. Change log.