From 8c0d08c9d6b1acab05b6bc7f85a2268d2edf8ca7 Mon Sep 17 00:00:00 2001 From: Connor McDonald Date: Sun, 7 Jun 2026 10:03:04 +0200 Subject: [PATCH] docs: precisely scope "cosmetic"; string literals trip the gate (#21) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Release 0.2.1 (docs-only). The README framed Surface as ignoring "cosmetic" changes, which led users to expect string/copy edits to be ignored — they are not, since a literal value is part of the hashed AST. Clarify that "cosmetic" means only whitespace, comments, and consistent renames, add a FAQ entry, and point at narrower anchoring so copy churn doesn't re-open a claim. The magnitude-aware policy / --ignore-literals knob (the feature half of #21) remains tracked for 0.3.0; refs #21. Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 11 ++++++++++- Cargo.lock | 4 ++-- Cargo.toml | 2 +- README.md | 9 +++++++++ 4 files changed, 22 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8b3db89..79e9571 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,14 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] +## [0.2.1] - 2026-06-07 + +### Documentation +- Precisely scope "cosmetic" (#21): 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. + ## [0.2.0] - 2026-06-07 ### Added @@ -60,7 +68,8 @@ Initial release — the MVP gate that surfaces docs↔code divergence. - Language support: TypeScript/TSX, JavaScript/JSX, Rust, Python, and Go. - Distribution: GitHub Action, pre-commit hook, and `install.sh`; Apache-2.0 license. -[Unreleased]: https://github.com/Connorrmcd6/surface/compare/v0.2.0...HEAD +[Unreleased]: https://github.com/Connorrmcd6/surface/compare/v0.2.1...HEAD +[0.2.1]: https://github.com/Connorrmcd6/surface/compare/v0.2.0...v0.2.1 [0.2.0]: https://github.com/Connorrmcd6/surface/compare/v0.1.1...v0.2.0 [0.1.1]: https://github.com/Connorrmcd6/surface/compare/v0.1.0...v0.1.1 [0.1.0]: https://github.com/Connorrmcd6/surface/releases/tag/v0.1.0 diff --git a/Cargo.lock b/Cargo.lock index 0cded54..1094867 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -519,7 +519,7 @@ checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f" [[package]] name = "surf-cli" -version = "0.2.0" +version = "0.2.1" dependencies = [ "anyhow", "clap", @@ -533,7 +533,7 @@ dependencies = [ [[package]] name = "surf-core" -version = "0.2.0" +version = "0.2.1" dependencies = [ "serde", "serde_yaml", diff --git a/Cargo.toml b/Cargo.toml index de2bbaf..176f6f3 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ members = ["surf-core", "surf-cli"] resolver = "2" [workspace.package] -version = "0.2.0" +version = "0.2.1" edition = "2021" license = "Apache-2.0" repository = "https://github.com/Connorrmcd6/surface" diff --git a/README.md b/README.md index 09da4e7..f9ea366 100644 --- a/README.md +++ b/README.md @@ -80,6 +80,8 @@ The clever part is what counts as "meaningfully change." Surface compares the *c Quiet on cosmetics, loud on logic. That's the entire reason this beats grepping diffs or eyeballing it in review. +"Cosmetic" is precise, and narrower than it sounds: it means *things that aren't in the syntax tree or are normalized out of it* — whitespace, comments, and consistent identifier renames. It does **not** mean "changes that look unimportant." A **literal value is part of the logic**, so editing a string literal — even user-facing copy — inside an anchored span changes the hash and trips the gate. That's deliberate (a string can carry behavior), but on a large anchor a one-word copy tweak re-opens the whole claim. Anchor the *smallest* symbol the sentence is about so an unrelated literal edit doesn't force a re-read (see [authoring hubs](docs/guides/authoring-hubs.md)). + ## What Surface does NOT do Read this part. It's the difference between a tool you trust and one that burns you. @@ -310,6 +312,13 @@ is what's enforced in CI. **Does it slow CI down?** No. It parses and hashes a handful of spans — I/O-bound, not compute-bound. No model, no network, no API key. +**Will editing a string literal trip the gate?** Yes. Literal *values* are part of the hashed +logic, so changing a string — even user-facing copy — inside an anchored span fires a +divergence. "Cosmetic" means whitespace, comments, and consistent renames, not "edits that feel +unimportant." If copy churn re-opens a claim too often, that's a sign the anchor is too coarse — +anchor a narrower symbol. (A magnitude-aware policy / `--ignore-literals` knob is tracked for a +future release.) + **What languages?** TypeScript, JavaScript/JSX, Rust, Python, and Go today, via bundled tree-sitter grammars. More are a build-time addition to the binary, never a runtime dependency.