@sledorze/cairn 0.1.0 → 0.3.0

package/README.md

@@ -16,15 +16,18 @@ compares modification times. But **git does not preserve mtimes**: after a clone
 checkout, every file looks freshly written, so a time-based check silently passes on
 summaries that are actually stale. The bug you meant to catch ships anyway.
 
-`cairn` checks **content**, not clocks. Each summary embeds the SHA-256 of the
-source it summarizes as its first line:
+`cairn` checks **content**, not clocks. The SHA-256 of the source each summary
+summarizes is recorded in a hidden sidecar under `.cairn/`, mirroring your docs tree —
+never inside the summary itself, so the tracking system leaves zero bytes in the docs
+you write:
 
-```markdown
-<!-- source-sha256: 3f9a…(64 hex) -->
+```
+.cairn/docs/guide.summary.md.json  →  {"sha256": "3f9a…(64 hex)", "version": 1}
 ```
 
-The checker recomputes the source hash and compares. Mismatch means stale, missing means
-missing — and it behaves identically on your laptop and in CI, before and after a clone.
+The checker recomputes the source hash and compares it to the sidecar. Mismatch means
+stale, missing means missing — and it behaves identically on your laptop and in CI,
+before and after a clone. Commit `.cairn/` alongside your docs; it isn't gitignored.
 
 ## Install
 
@@ -42,24 +45,72 @@ The round-trip when you touch a doc:
 
 1. **Edit** `docs/guide.md`.
 2. `npx cairn check` **flags it stale** — the source hash no longer matches the
-   stamp in `guide.summary.md`.
+   sidecar recorded for `guide.summary.md`.
 3. **Write** the updated `guide.summary.md` (and update any parent `_SUMMARY.md`).
-4. **Stamp**: `npx cairn check --summaries-only --stamp` rewrites the
-   `source-sha256` lines bottom-up.
+4. **Stamp**: `npx cairn check --summaries-only --stamp` rewrites the `.cairn/`
+   sidecar hashes bottom-up — your summary's content is never touched.
 5. **Check** again — `npx cairn check` exits 0. Green.
 
-You author the prose; the tool verifies and stamps. It never invents content.
+You author the prose; the tool verifies and stamps. It never invents content, and it
+never writes into content either.
 
 ### Commands
 
-| Command                                   | What it does                                             |
-| ----------------------------------------- | -------------------------------------------------------- |
-| `cairn check`                             | Check summaries + links; exit 1 on any problem           |
-| `cairn check --summaries-only`            | Check only summary freshness                             |
-| `cairn check --links-only`                | Check only Markdown links                                |
-| `cairn check --links-only --fix`          | Auto-repair unambiguous dead links                       |
-| `cairn check --summaries-only --stamp`    | Rewrite `source-sha256` of existing summaries, bottom-up |
-| `cairn init --agent claude\|copilot\|all` | Scaffold agent guidance files                            |
+| Command                                   | What it does                                                              |
+| ----------------------------------------- | ------------------------------------------------------------------------- |
+| `cairn check`                             | Check summaries + links; exit 1 on any problem                            |
+| `cairn check --summaries-only`            | Check only summary freshness                                              |
+| `cairn check --links-only`                | Check only Markdown links                                                 |
+| `cairn check --links-only --fix`          | Auto-repair unambiguous dead links                                        |
+| `cairn check --summaries-only --stamp`    | Rewrite the `.cairn/` sidecar hash of existing summaries, bottom-up       |
+| `cairn check --prune`                     | Delete orphan summaries and orphan `.cairn/` sidecars                     |
+| `cairn check --migrate-stamps`            | Optional: same self-healing `--stamp` already does, as its own named step |
+| `cairn check --refs --stamp`              | Opt-in: record each real reference target's content hash                  |
+| `cairn check --refs`                      | Opt-in: report references whose target content has drifted since          |
+| `cairn init --agent claude\|copilot\|all` | Scaffold agent guidance files                                             |
+
+### Link checking
+
+A dead link is only the most obvious way a reference rots. `cairn check` (or
+`--links-only`) verifies, for every relative Markdown link:
+
+- **The path resolves** — including targets _outside_ your configured `roots`, as long as
+  they stay inside the repository checkout (e.g. a doc in `docs/` linking to `../src/foo.ts`).
+  Nothing outside the checkout root is ever touched, even to check existence — this bound is
+  deliberate: CI runs over untrusted PR content, and an unbounded filesystem check would be
+  an existence oracle.
+- **The `#heading` fragment exists** — same-page (`[intro](#getting-started)`) and
+  cross-file (`[intro](./guide.md#getting-started)`), slugged the same way GitHub does.
+- **A `#L10`/`#L10-L20` line-fragment is in range**, for links to source files outside `roots`.
+
+A broken heading or out-of-range line reports with the reason (`path` / `anchor` / `line`)
+and, where possible, what's actually there (the target's real headings, or its real line
+count) — so fixing it doesn't require opening the target file first.
+
+`cairn check --refs` is a separate, **opt-in** signal, off by default and not part of the
+`path`/`anchor`/`line` checks above: it tracks the _content_ of what a link points to, not
+just whether the link resolves. `--refs --stamp` records a hash of every reference target;
+a later `--refs` run reports any that changed since — "this doc's claim about that file may
+be stale," distinct from a broken link (the link still resolves; what it once meant may not
+still hold). Still v1/experimental (whole-file hashing only — a one-line unrelated change to
+a large target file is reported the same as a change to the exact part being referenced).
+
+### Upgrading from an older cairn
+
+**If you're upgrading past `0.3.0`**: link checking got stricter. Anchors and links outside
+`roots` were previously accepted unconditionally, whether or not they actually resolved —
+`cairn` simply never looked. If `cairn check` newly fails after upgrading, the links it's
+flagging were already broken; nothing about your docs changed, only the tool's ability to
+notice did. Fix the flagged link/anchor, or, if a genuine false positive (e.g. a symbol-level
+anchor like `x.ts#someExport` — deliberately never checked, see the source's own scenario
+notes), please open an issue.
+
+Nothing to look up for the summary/stamp side. If a summary still carries the old in-content
+`<!-- source-sha256: ... -->` comment, the ordinary `--stamp` command strips it and
+writes the `.cairn/` sidecar in the same run — automatically, every time. There is no
+separate migration step to discover: whatever `stampCommand` your repo already runs
+already handles it. `--migrate-stamps` exists only as an optional, explicitly-named
+alias for the same behavior, for anyone who wants the cleanup reported as its own step.
 
 ## The two summary kinds