Changelog

Surface follows semantic versioning. This page mirrors releases of the surf CLI. While Surface is pre-1.0 (v0.x), minor versions may include breaking changes.

v0.3.2

Documentation.

• The docs site (surface.gradientdev.xyz) is now generated from this repo on release: each v* tag regenerates the Starlight site’s pages and changelog from docs/ and CHANGELOG.md and opens a sync PR, so the site no longer drifts from canonical docs.
• docs/reference/commands.md is now governed by surf check itself — a hub anchored to the clap command/flag surface blocks the gate when the CLI and its reference drift.
• Pinned Connorrmcd6/surface@vX.Y.Z Action refs in the README and docs are now derived from Cargo.toml at release, and the Examples page description is quoted so it parses under the site’s strict YAML.

v0.3.1

Documentation.

• Reposition around documentation governed like code for fast-moving codebases, led by the context-rot story (a context file that’s accurate when written and rots as the code moves because nobody knows it exists or where to find it). Dropped the older accusatory framing.
• Slim the README to a pitch + compact quickstart that links out; the full reference now lives in docs/. Restructured docs/ into a site-ready tree (getting-started/, reference/, guides/) with title/description frontmatter, mirroring the docs site (surface.gradientdev.xyz); this repo’s docs/ is the source of truth.
• Bring the docs current with 0.3.0: the versioned --format json envelope, the per-claim ignore_literals option, Python non-callable anchors, file-rename --follow, and decorators in the hashed span.

v0.3.0

Added.

• Python: at: now resolves non-callable symbols — module-level constants and type aliases (X = …, X: T = …, PEP 695 type X = …) and class-level attributes (Class > attr, including annotation-only). Previously only functions, methods, and classes resolved.
• Per-claim ignore_literals: true frontmatter option — excludes string-literal content from a claim’s hash so a copy edit inside the anchored span no longer re-opens the gate. Logic edits (operators, numbers, structure) are still caught. The stored hash is computed in this mode, so it travels with the claim rather than a CLI flag.
• surf verify --follow and surf lint now follow file renames via git rename detection: a moved file makes lint warn (and point at --follow) instead of hard-blocking, and --follow rewrites the anchor’s path — only when the code is otherwise unchanged. Best-effort and git-dependent; the deterministic surf check verdict never depends on it.

Changed.

• Python decorators are now part of an anchored function/class’s hashed span, and a decorator’s name is kept verbatim (not alpha-renamed) — so adding/removing a decorator, changing its arguments, or swapping it (@cache → @lru_cache, @staticmethod → @classmethod) trips the gate. Previously decorators were excluded from the span entirely.
• Breaking (JSON): surf check --format json now emits a versioned envelope { "version": 1, "divergences": [...] } instead of a bare array. The contract is additive-only within a major version; a breaking change bumps version. Consumers should read .divergences and tolerate unknown fields.

v0.2.1

Documentation.

• Precisely scope “cosmetic”: a literal value is part of the hashed AST, so editing a string literal — including user-facing copy — inside an anchored span trips the gate. “Cosmetic” means only whitespace, comments, and consistent renames. Added a FAQ entry and a note to anchor the narrowest symbol so unrelated literal edits don’t re-open a claim.

v0.2.0

Added.

• surf check scoping: --files <globs> evaluates only claims whose anchored file(s) match, and an explicit --base <ref> diff-scopes the gate to claims whose files changed since the merge base. Omitting --base keeps a full check (enrichment falls back to HEAD).
• --format json for surf lint and surf verify, mirroring surf check. lint emits structured findings; verify emits per-anchor outcomes (stamped/followed/unchanged/skipped) plus counts.
• Advisory surf lint granularity warnings (never blocking): a near-whole-file anchor span, a hub with too many anchors, and public functions in an anchored file that no claim covers.
• surf lint enforces the AGENTS.md pointer block: when AGENTS.md carries a <!-- surf:hubs --> block, it must link the hubs directory (and that directory must exist) so agents are pointed at the hubs to search — never duplicating or enumerating them. Opt-in; blocks on a missing/dangling pointer.
• surf suggest <globs> — scans source for top-level public functions that no hub anchors yet and prints a copy-pasteable starter hub. Suggestions only: never writes a file or stamps a hash.
• surf_core::public_fns — enumerates a file’s top-level public functions (backs the under-coverage warning and surf suggest).

Changed.

• An explicit surf check --base <ref> now diff-scopes the gate to claims whose files changed, in addition to feeding advisory old_code/magnitude. Previously --base only fed enrichment and every claim was still checked. CI that passes --base explicitly will now check fewer claims; omit --base for a full check.

v0.1.1

Fixed.

• resolve: resolve const-bound call-expression functions (TS/JS).
• verify: skip unchanged anchors instead of re-stamping, so a no-op verify leaves hub files byte-identical.

Changed.

• Releases: dropped Intel macOS (x86_64-apple-darwin); prebuilt binaries cover macOS (Apple Silicon) and Linux (x86_64). Other targets build from source.

v0.1.0

Initial release — the MVP gate that surfaces docs↔code divergence.

Added.

• AST-canonical hashing via bundled, version-pinned tree-sitter grammars: quiet on cosmetics (formatting, comments, consistent renames), loud on logic. Advisory tree-edit magnitude.
• Anchor resolution: the file > A > B path grammar with @N disambiguation; scope-set resolution so Type > method resolves uniquely.
• Hub format (markdown frontmatter), surf.toml workspace discovery, and per-claim combined hashing across multi-site at: lists.
• Commands: surf lint, surf check (the gate), surf verify (re-seal, with --follow for renames), plus surf init and surf new for authoring ergonomics.
• Language support: TypeScript/TSX, JavaScript/JSX, Rust, Python, and Go.
• Distribution: GitHub Action, pre-commit hook, and install.sh; Apache-2.0 license.