@sledorze/cairn 0.2.0 → 0.3.0

package/dist/core/links/MarkdownLinks.js

@@ -0,0 +1,228 @@
+// Pure, IO-free helpers to find and auto-repair relative Markdown links.
+// All functions here are deterministic and unit-tested in MarkdownLinks.unit.test.ts.
+// The Effect program that touches the filesystem lives in ../program/CheckLinks.ts.
+import * as nodePath from 'node:path';
+import { describeAnchors, extractAnchors } from './Anchors.js';
+import { maskFencedCode } from './markdownFences.js';
+// Reason in POSIX so link resolution is identical on every OS (inputs are
+// normalised to `/` at the IO boundary).
+const path = nodePath.posix;
+const LINK_RE = /!?\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+const INLINE_CODE_RE = /`[^`\n]*`/g;
+/**
+ * Blank out fenced (``` / ~~~, via `maskFencedCode`) and inline (`code`)
+ * spans so links that only appear inside code examples are NOT treated as
+ * real links. Newlines are kept so line-based reasoning is unaffected; other
+ * characters become spaces.
+ */
+export const stripCode = (content) => maskFencedCode(content).replaceAll(INLINE_CODE_RE, (block) => ' '.repeat(block.length));
+const LINK_DEF_RE = /^[ \t]*\[([^\]]+)\]:[ \t]*<?([^>\s]+)>?/gm;
+/** Extract inline Markdown links/images as `{ target, text }`. */
+export const extractLinks = (content) => {
+    const links = [];
+    for (const match of content.matchAll(LINK_RE)) {
+        links.push({ target: match[2] ?? '', text: match[1] ?? '' });
+    }
+    return links;
+};
+/** Extract reference-style link definitions (`[label]: ./path "title"`). */
+export const extractLinkDefinitions = (content) => {
+    const defs = [];
+    for (const match of content.matchAll(LINK_DEF_RE)) {
+        defs.push({ label: match[1] ?? '', target: match[2] ?? '' });
+    }
+    return defs;
+};
+/** Start offset of a regex match's first capture group, given the group's
+ * own text starts right after the FIRST `[` in the whole match (true for
+ * both `LINK_RE`'s text group and `LINK_DEF_RE`'s label group). */
+const captureGroupStart = (match) => (match.index ?? 0) + match[0].indexOf('[') + 1;
+/**
+ * Like `extractLinks`, but matches against `masked` (to keep the existing
+ * "a link written inside a code example isn't a real link" exclusion,
+ * unchanged) while reading the TEXT back from `original` at that same
+ * position. Without this, a link whose own visible text is itself
+ * backtick-styled (e.g. `` [`glob.ts`](../glob.ts) ``) reports as blank —
+ * `stripCode`'s inline-code masking blanks that backtick span before
+ * extraction ever sees it, since it can't distinguish "styling inside a
+ * link's text" from "a link written inside a code example." Errors need the
+ * real text to be actionable, so this is a position-preserving re-read, not a
+ * masking change (masking's own exclusion behaviour must stay exactly as-is).
+ */
+const extractLinksPreservingText = (original, masked) => {
+    const links = [];
+    for (const match of masked.matchAll(LINK_RE)) {
+        const textStart = captureGroupStart(match);
+        const textLength = match[1]?.length ?? 0;
+        links.push({ target: match[2] ?? '', text: original.slice(textStart, textStart + textLength) });
+    }
+    return links;
+};
+/** The `extractLinkDefinitions` counterpart of `extractLinksPreservingText`. */
+const extractLinkDefinitionsPreservingLabel = (original, masked) => {
+    const defs = [];
+    for (const match of masked.matchAll(LINK_DEF_RE)) {
+        const labelStart = captureGroupStart(match);
+        const labelLength = match[1]?.length ?? 0;
+        defs.push({ label: original.slice(labelStart, labelStart + labelLength), target: match[2] ?? '' });
+    }
+    return defs;
+};
+/** True only for relative paths we can resolve on disk — INCLUDING a bare
+ * `#heading` (same-page anchor), now checkable against the file's own
+ * headings (issue #39, scenario C); previously always skipped. */
+export const isCheckableTarget = (target) => {
+    if (!target) {
+        return false;
+    }
+    if (target.startsWith('//')) {
+        return false;
+    } // protocol-relative URL
+    if (/^[a-z][a-z0-9+.-]*:/i.test(target)) {
+        return false;
+    } // http:, mailto:, etc.
+    return true;
+};
+/** Split a link target into its path and (optional) `#anchor`, dropping any
+ * `?query` — plain `indexOf`/`slice`, not a regex (CodeQL flagged the
+ * previous `/\?.*$/` form as a polynomial-ReDoS risk on library input). */
+export const parseTarget = (target) => {
+    const hashIdx = target.indexOf('#');
+    const rawPath = hashIdx === -1 ? target : target.slice(0, hashIdx);
+    const queryIdx = rawPath.indexOf('?');
+    return {
+        anchor: hashIdx === -1 ? null : target.slice(hashIdx + 1),
+        path: queryIdx === -1 ? rawPath : rawPath.slice(0, queryIdx),
+    };
+};
+/** Drop `#anchor` and `?query` from a target. */
+export const stripAnchor = (target) => parseTarget(target).path;
+/**
+ * Every real (checkable, cross-file) reference a doc makes — deduped by
+ * `(target, anchor)` — for issue #39 Scenario I's content-hash drift
+ * tracking (`../program/CheckRefs.ts`). Same-page anchors (`path === ''`)
+ * are excluded: a same-page fragment isn't a reference to another file's
+ * content, it's a position within this one — `checkContent`'s own anchor
+ * check already covers whether it resolves.
+ */
+export const extractReferences = (content) => {
+    const masked = stripCode(content);
+    const candidates = [
+        ...extractLinks(masked),
+        ...extractLinkDefinitions(masked).map((def) => ({ target: def.target, text: '' })),
+    ];
+    const seen = new Set();
+    const refs = [];
+    for (const link of candidates) {
+        if (!isCheckableTarget(link.target)) {
+            continue;
+        }
+        const { anchor, path: target } = parseTarget(link.target);
+        if (target === '') {
+            continue;
+        }
+        const key = `${target}#${anchor ?? ''}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        refs.push({ anchor, target });
+    }
+    return refs;
+};
+/** Map basename -> list of absolute paths, for ambiguity-aware fixing. */
+export const buildBasenameIndex = (absPaths) => {
+    const index = new Map();
+    for (const abs of absPaths) {
+        const base = path.basename(abs);
+        const bucket = index.get(base);
+        if (bucket) {
+            bucket.push(abs);
+        }
+        else {
+            index.set(base, [abs]);
+        }
+    }
+    return index;
+};
+const toRelative = (fromDir, toAbs) => {
+    const rel = path.relative(fromDir, toAbs).split(path.sep).join('/');
+    return rel.startsWith('.') ? rel : `./${rel}`;
+};
+/**
+ * Suggest a repaired relative path for a broken target. Returns a path only
+ * when exactly one indexed file matches the basename (no ambiguity); else null.
+ */
+export const suggestFix = ({ fromDir, index, target }) => {
+    const base = path.basename(stripAnchor(target));
+    const candidates = index.get(base);
+    if (!candidates || candidates.length !== 1) {
+        return null;
+    }
+    return toRelative(fromDir, candidates[0] ?? '');
+};
+/**
+ * Check one file's content for broken relative links, path existence and
+ * `#fragment` validity. Resolves everything decidable without IO — an
+ * in-`roots` path's existence (`existsAbs`, unchanged fast path) and a
+ * same-page `#anchor` (the file's own content is already in hand, no IO
+ * needed — issue #39 scenario C) — synchronously into `broken`. Anything
+ * needing another file's content (a cross-file anchor, or a target outside
+ * `roots` whose existence isn't yet known) is deferred into `pending` for the
+ * caller (../program/CheckLinks.ts) to resolve with real, `base`-bounded IO.
+ */
+export const checkContent = ({ content, existsAbs, fileAbs, index, inRoots = () => true, }) => {
+    const fromDir = path.dirname(fileAbs);
+    const broken = [];
+    const pending = [];
+    const masked = stripCode(content);
+    const candidates = [
+        ...extractLinksPreservingText(content, masked),
+        // Reference-style definitions are checked by their target too.
+        ...extractLinkDefinitionsPreservingLabel(content, masked).map((def) => ({
+            target: def.target,
+            text: `[${def.label}]`,
+        })),
+    ];
+    let sourceAnchors = null;
+    const getSourceAnchors = () => (sourceAnchors ??= extractAnchors(content));
+    for (const link of candidates) {
+        if (!isCheckableTarget(link.target)) {
+            continue;
+        }
+        const { anchor, path: rel } = parseTarget(link.target);
+        if (rel === '') {
+            // Same-page anchor: no other file to read, resolve now.
+            if (anchor !== null && !getSourceAnchors().has(anchor)) {
+                broken.push({
+                    detail: describeAnchors(getSourceAnchors()),
+                    reason: 'anchor',
+                    target: link.target,
+                    text: link.text,
+                });
+            }
+            continue;
+        }
+        const abs = path.resolve(fromDir, rel);
+        if (existsAbs(abs)) {
+            if (anchor !== null) {
+                pending.push({ anchor, fromDir, target: link.target, targetAbs: abs, text: link.text });
+            }
+            continue;
+        }
+        if (!inRoots(abs)) {
+            // Outside the eagerly-listed universe: existence itself is unknown —
+            // never assume broken (issue #39 scenario E), defer to real IO.
+            pending.push({ anchor, fromDir, target: link.target, targetAbs: abs, text: link.text });
+            continue;
+        }
+        // In `roots` and genuinely absent — `existsAbs` already covers the
+        // complete in-root existence universe, no IO needed to know this.
+        const suggestion = index ? suggestFix({ fromDir, index, target: link.target }) : null;
+        broken.push(suggestion
+            ? { reason: 'path', suggestion, target: link.target, text: link.text }
+            : { reason: 'path', target: link.target, text: link.text });
+    }
+    return { broken, pending };
+};
+//# sourceMappingURL=MarkdownLinks.js.map

package/dist/core/links/MarkdownLinks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MarkdownLinks.js","sourceRoot":"","sources":["../../../src/core/links/MarkdownLinks.ts"],"names":[],"mappings":"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"}

package/dist/core/links/RefStore.d.ts

@@ -0,0 +1,32 @@
+import type { MetaLayout } from '../sidecar.ts';
+/** The subdirectory, under `metaRoot`, every reference sidecar lives under —
+ * disjoint from the summary-freshness sidecars living directly under
+ * `metaRoot` (see module header: this is load-bearing, not stylistic). */
+export declare const REFS_DIR = "refs";
+export interface RefRecord {
+    readonly anchor?: string;
+    readonly hash: string;
+    readonly target: string;
+}
+export interface RefsRecord {
+    readonly refs: readonly RefRecord[];
+}
+/** Bumped only if this shape changes incompatibly (never for adding an
+ * optional field — the codec already tolerates unknown keys). */
+export declare const REFS_VERSION = 1;
+/** The sidecar's on-disk JSON form. Trailing newline for a clean git diff. */
+export declare const serializeRefs: (record: RefsRecord) => string;
+/**
+ * Read a sidecar's `RefsRecord` back, or `null` if it's missing/corrupt/
+ * malformed/hand-edited/merge-conflicted — this must NEVER throw, mirroring
+ * `StampStore.ts`'s `parseStamp`: an untrustworthy record reads as no
+ * recorded references at all, not a crash.
+ */
+export declare const parseRefs: (content: string) => RefsRecord | null;
+/**
+ * `<base>/docs/architecture.md` -> `<metaRoot>/refs/docs/architecture.md.json`.
+ * Throws if `docAtPath` isn't under `base`, mirroring `sidecarPathFor`'s own
+ * rule (a caller bug, not a runtime data condition).
+ */
+export declare const refsSidecarPathFor: (docAtPath: string, layout: MetaLayout) => string;
+//# sourceMappingURL=RefStore.d.ts.map

package/dist/core/links/RefStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RefStore.d.ts","sourceRoot":"","sources":["../../../src/core/links/RefStore.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAG/C;;0EAE0E;AAC1E,eAAO,MAAM,QAAQ,SAAS,CAAA;AAE9B,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,CAAA;CACpC;AAED;iEACiE;AACjE,eAAO,MAAM,YAAY,IAAI,CAAA;AAc7B,8EAA8E;AAC9E,eAAO,MAAM,aAAa,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,MAA4B,CAAA;AAEhF;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,UAAU,GAAG,IAAsB,CAAA;AAEhF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,cAAe,MAAM,UAAU,UAAU,KAAG,MAC9B,CAAA"}

package/dist/core/links/RefStore.js

@@ -0,0 +1,60 @@
+// Sidecar tracking for issue #39 Scenario I ("this doc's claim about a
+// referenced target may be stale, even though the link isn't broken"):
+// records the content hash of each real reference (a cross-file/cross-
+// hierarchy link target) a doc makes, at stamp time, so a LATER change to
+// the target's content — the target still exists, the link still resolves —
+// can be surfaced as drift, distinct from `MarkdownLinks.ts`'s "broken."
+//
+// Own path namespace, `.cairn/refs/**`, via `../sidecar.ts`'s `namespace`
+// parameter — NOT the raw doc path directly under `.cairn/`. That was the
+// first design (reasoning: `docs/architecture.md` never had a sidecar of its
+// own, so `.cairn/docs/architecture.md.json` looked free) — wrong in
+// general and caught by construction while dogfooding: `docs/_SUMMARY.md`
+// is ALSO a real `.md` file `stampRefs` scans (it links to every child doc,
+// including `architecture.md`), and its OWN freshness sidecar already lives
+// at exactly `.cairn/docs/_SUMMARY.md.json` — writing a refs record there
+// silently clobbered it. Every summary-tree node (`X.summary.md`,
+// `_SUMMARY.md`) is simultaneously a scannable doc, so the two concerns need
+// genuinely disjoint path spaces, not "usually disjoint."
+//
+// Deliberately a SEPARATE record shape from `StampStore.ts`'s `StampRecord`,
+// not a shared one: a source doc's sidecar has no summary-freshness hash to
+// carry, and a summary's sidecar (today) carries no references — forcing
+// one schema to serve both would leave one half always meaningless for any
+// given sidecar. Same lenient-decode philosophy as `StampStore.ts` (both
+// build on `../sidecar.ts`'s codec): unknown keys are ignored, and a
+// corrupt/hand-edited sidecar reads as absent, never throws.
+import { Schema } from 'effect';
+import { makeSidecarCodec, sidecarPathFor } from '../sidecar.js';
+/** The subdirectory, under `metaRoot`, every reference sidecar lives under —
+ * disjoint from the summary-freshness sidecars living directly under
+ * `metaRoot` (see module header: this is load-bearing, not stylistic). */
+export const REFS_DIR = 'refs';
+/** Bumped only if this shape changes incompatibly (never for adding an
+ * optional field — the codec already tolerates unknown keys). */
+export const REFS_VERSION = 1;
+const RefRecordSchema = Schema.Struct({
+    anchor: Schema.optionalKey(Schema.String),
+    hash: Schema.String,
+    target: Schema.String,
+});
+const RefsRecordSchema = Schema.Struct({
+    refs: Schema.Array(RefRecordSchema),
+});
+const refsCodec = makeSidecarCodec(RefsRecordSchema);
+/** The sidecar's on-disk JSON form. Trailing newline for a clean git diff. */
+export const serializeRefs = refsCodec.serialize;
+/**
+ * Read a sidecar's `RefsRecord` back, or `null` if it's missing/corrupt/
+ * malformed/hand-edited/merge-conflicted — this must NEVER throw, mirroring
+ * `StampStore.ts`'s `parseStamp`: an untrustworthy record reads as no
+ * recorded references at all, not a crash.
+ */
+export const parseRefs = refsCodec.parse;
+/**
+ * `<base>/docs/architecture.md` -> `<metaRoot>/refs/docs/architecture.md.json`.
+ * Throws if `docAtPath` isn't under `base`, mirroring `sidecarPathFor`'s own
+ * rule (a caller bug, not a runtime data condition).
+ */
+export const refsSidecarPathFor = (docAtPath, layout) => sidecarPathFor(docAtPath, layout, REFS_DIR);
+//# sourceMappingURL=RefStore.js.map

package/dist/core/links/RefStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RefStore.js","sourceRoot":"","sources":["../../../src/core/links/RefStore.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,uEAAuE;AACvE,uEAAuE;AACvE,0EAA0E;AAC1E,4EAA4E;AAC5E,yEAAyE;AACzE,EAAE;AACF,0EAA0E;AAC1E,0EAA0E;AAC1E,6EAA6E;AAC7E,qEAAqE;AACrE,0EAA0E;AAC1E,4EAA4E;AAC5E,4EAA4E;AAC5E,0EAA0E;AAC1E,kEAAkE;AAClE,6EAA6E;AAC7E,0DAA0D;AAC1D,EAAE;AACF,6EAA6E;AAC7E,4EAA4E;AAC5E,yEAAyE;AACzE,2EAA2E;AAC3E,yEAAyE;AACzE,qEAAqE;AACrE,6DAA6D;AAE7D,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAG/B,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAEhE;;0EAE0E;AAC1E,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAA;AAY9B;iEACiE;AACjE,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAA;AAE7B,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC;IACzC,IAAI,EAAE,MAAM,CAAC,MAAM;IACnB,MAAM,EAAE,MAAM,CAAC,MAAM;CACtB,CAAC,CAAA;AAEF,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC;CACpC,CAAC,CAAA;AAEF,MAAM,SAAS,GAAG,gBAAgB,CAAC,gBAAgB,CAAC,CAAA;AAEpD,8EAA8E;AAC9E,MAAM,CAAC,MAAM,aAAa,GAAmC,SAAS,CAAC,SAAS,CAAA;AAEhF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAA2C,SAAS,CAAC,KAAK,CAAA;AAEhF;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,SAAiB,EAAE,MAAkB,EAAU,EAAE,CAClF,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAA"}

package/dist/core/links/markdownFences.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Replace every character of each fenced code block — opening and closing
+ * marker lines included — with a space, keeping line count/newlines intact.
+ * An unclosed fence masks to end of document (matches the prior regex's own
+ * behaviour, which also never matched — and so never masked — an unclosed
+ * fence... this instead fails safe: unterminated is treated as "still in
+ * code," not leaking a stray marker line as real content).
+ */
+export declare const maskFencedCode: (content: string) => string;
+//# sourceMappingURL=markdownFences.d.ts.map

package/dist/core/links/markdownFences.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdownFences.d.ts","sourceRoot":"","sources":["../../../src/core/links/markdownFences.ts"],"names":[],"mappings":"AAwBA;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,YAAa,MAAM,KAAG,MAoBhD,CAAA"}

package/dist/core/links/markdownFences.js

@@ -0,0 +1,51 @@
+// Fenced (``` / ~~~) code block masking — a provably linear line scan, not a
+// single regex. The prior single-regex form
+// (`/(^|\n)[ \t]*(```|~~~)[\s\S]*?\n[ \t]*\2[ \t]*(?=\n|$)/g`) is a genuine
+// CodeQL js/polynomial-redos finding: a lazy `[\s\S]*?` hunting for a
+// backreferenced closing marker is O(n^2) on adversarial input (many
+// unclosed or repeated fence markers) — exactly the kind of untrusted
+// document content `cairn check` runs over in CI. Shared by
+// MarkdownLinks.ts (stripCode) and Anchors.ts (heading extraction must not
+// misparse a heading-shaped line inside a fence).
+const fenceOpenMarker = (line) => {
+    const trimmed = line.trimStart();
+    if (trimmed.startsWith('```')) {
+        return '```';
+    }
+    if (trimmed.startsWith('~~~')) {
+        return '~~~';
+    }
+    return null;
+};
+/** A closing fence line is the marker alone, with only surrounding whitespace. */
+const isFenceClose = (line, marker) => line.trim() === marker;
+/**
+ * Replace every character of each fenced code block — opening and closing
+ * marker lines included — with a space, keeping line count/newlines intact.
+ * An unclosed fence masks to end of document (matches the prior regex's own
+ * behaviour, which also never matched — and so never masked — an unclosed
+ * fence... this instead fails safe: unterminated is treated as "still in
+ * code," not leaking a stray marker line as real content).
+ */
+export const maskFencedCode = (content) => {
+    const lines = content.split('\n');
+    let i = 0;
+    while (i < lines.length) {
+        const marker = fenceOpenMarker(lines[i] ?? '');
+        if (marker === null) {
+            i += 1;
+            continue;
+        }
+        let j = i + 1;
+        while (j < lines.length && !isFenceClose(lines[j] ?? '', marker)) {
+            j += 1;
+        }
+        const end = j < lines.length ? j : lines.length - 1;
+        for (let k = i; k <= end; k += 1) {
+            lines[k] = ' '.repeat((lines[k] ?? '').length);
+        }
+        i = end + 1;
+    }
+    return lines.join('\n');
+};
+//# sourceMappingURL=markdownFences.js.map

package/dist/core/links/markdownFences.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdownFences.js","sourceRoot":"","sources":["../../../src/core/links/markdownFences.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,4CAA4C;AAC5C,4EAA4E;AAC5E,sEAAsE;AACtE,qEAAqE;AACrE,sEAAsE;AACtE,4DAA4D;AAC5D,2EAA2E;AAC3E,kDAAkD;AAElD,MAAM,eAAe,GAAG,CAAC,IAAY,EAAwB,EAAE;IAC7D,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,EAAE,CAAA;IAChC,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAA;IACd,CAAC;IACD,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAA;IACd,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC,CAAA;AAED,kFAAkF;AAClF,MAAM,YAAY,GAAG,CAAC,IAAY,EAAE,MAAc,EAAW,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,MAAM,CAAA;AAEtF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAAe,EAAU,EAAE;IACxD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACjC,IAAI,CAAC,GAAG,CAAC,CAAA;IACT,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QACxB,MAAM,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAA;QAC9C,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,CAAC,IAAI,CAAC,CAAA;YACN,SAAQ;QACV,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACb,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC;YACjE,CAAC,IAAI,CAAC,CAAA;QACR,CAAC;QACD,MAAM,GAAG,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAA;QACnD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YACjC,KAAK,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAA;QAChD,CAAC;QACD,CAAC,GAAG,GAAG,GAAG,CAAC,CAAA;IACb,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC,CAAA"}

package/dist/core/paths.d.ts

@@ -1,3 +1,11 @@
 /** Convert an OS path to POSIX form (`\` -> `/`). */
 export declare const toPosix: (p: string) => string;
+/**
+ * True when `candidate` resolves inside `base` (or equals it). The same
+ * containment check `sidecar.ts`'s `sidecarPathFor`/`nodePathForSidecar`
+ * use for sidecar paths — non-throwing here since callers (link-checking's
+ * out-of-hierarchy targets, issue #39) need a boolean to decide "cannot
+ * verify" from, not a programming-error signal.
+ */
+export declare const isWithinBase: (candidate: string, base: string) => boolean;
 //# sourceMappingURL=paths.d.ts.map

package/dist/core/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/core/paths.ts"],"names":[],"mappings":"AAIA,qDAAqD;AACrD,eAAO,MAAM,OAAO,MAAO,MAAM,KAAG,MAAiC,CAAA"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/core/paths.ts"],"names":[],"mappings":"AAQA,qDAAqD;AACrD,eAAO,MAAM,OAAO,MAAO,MAAM,KAAG,MAAiC,CAAA;AAErE;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,cAAe,MAAM,QAAQ,MAAM,KAAG,OAG9D,CAAA"}

package/dist/core/paths.js

@@ -1,6 +1,19 @@
 // Path normalisation. The pure planners reason in POSIX (`/`) paths so behaviour
 // is identical on every OS; the IO layer normalises real filesystem paths (which
 // may use `\` on Windows) to POSIX before they reach the core.
+import * as nodePath from 'node:path';
+const path = nodePath.posix;
 /** Convert an OS path to POSIX form (`\` -> `/`). */
 export const toPosix = (p) => p.replaceAll('\\', '/');
+/**
+ * True when `candidate` resolves inside `base` (or equals it). The same
+ * containment check `sidecar.ts`'s `sidecarPathFor`/`nodePathForSidecar`
+ * use for sidecar paths — non-throwing here since callers (link-checking's
+ * out-of-hierarchy targets, issue #39) need a boolean to decide "cannot
+ * verify" from, not a programming-error signal.
+ */
+export const isWithinBase = (candidate, base) => {
+    const rel = path.relative(base, candidate);
+    return !rel.startsWith('..') && !path.isAbsolute(rel);
+};
 //# sourceMappingURL=paths.js.map

package/dist/core/paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/core/paths.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,iFAAiF;AACjF,+DAA+D;AAE/D,qDAAqD;AACrD,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA"}
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/core/paths.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,iFAAiF;AACjF,+DAA+D;AAE/D,OAAO,KAAK,QAAQ,MAAM,WAAW,CAAA;AAErC,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAA;AAE3B,qDAAqD;AACrD,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;AAErE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,SAAiB,EAAE,IAAY,EAAW,EAAE;IACvE,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CAAA;IAC1C,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAA;AACvD,CAAC,CAAA"}

package/dist/core/sidecar.d.ts

@@ -0,0 +1,45 @@
+import { Schema } from 'effect';
+/** The hidden directory name every metadata tree lives under, relative to `base`. */
+export declare const META_DIR = ".cairn";
+export interface MetaLayout {
+    /** The project root every node path and every sidecar is resolved under. */
+    readonly base: string;
+    /** `join(base, META_DIR)` — passed explicitly (not recomputed) so callers who
+     * already have it (e.g. after listing `.cairn/**`) don't rederive it. */
+    readonly metaRoot: string;
+}
+export declare const metaRootFor: (base: string) => string;
+/** True for any path inside the hidden metadata tree — used to keep `.cairn/**`
+ * out of the set of markdown source files a plan considers. */
+export declare const isSidecarPath: (candidate: string, metaRoot: string) => boolean;
+/**
+ * `<base>/docs/a.summary.md` -> `<metaRoot>/docs/a.summary.md.json`, or, with
+ * a `namespace` (e.g. `'refs'`), `<metaRoot>/refs/docs/a.summary.md.json` —
+ * the mechanism that keeps two DIFFERENT sidecar kinds for the SAME doc path
+ * from colliding (a doc's own freshness stamp vs its reference hashes; see
+ * `links/RefStore.ts`'s header for the real collision this closes). Throws
+ * if `nodeAtPath` isn't under `base`: every real node path is (roots are
+ * always resolved under the project root before a plan ever runs), so this
+ * signals a caller bug, not a runtime data condition to recover from.
+ */
+export declare const sidecarPathFor: (nodeAtPath: string, layout: MetaLayout, namespace?: string) => string;
+/**
+ * The inverse of `sidecarPathFor` (namespace-free form): given a sidecar's
+ * own path (e.g. found by listing `.cairn/**`), recover the node path it
+ * mirrors. Returns `null` for a path that isn't a well-formed sidecar under
+ * `metaRoot` (not `.json`, or outside the tree) rather than throwing —
+ * unlike `sidecarPathFor`, this reads data that could plausibly be malformed
+ * (a stray non-JSON file dropped into `.cairn/` by hand), so `null` is the
+ * right "not a sidecar" signal, not a crash.
+ */
+export declare const nodePathForSidecar: (sidecarPath: string, layout: MetaLayout) => string | null;
+export interface SidecarCodec<A> {
+    /** Read a sidecar's record back, or `null` if missing/corrupt/malformed —
+     * NEVER throws (see module header). */
+    readonly parse: (content: string) => A | null;
+    /** The sidecar's on-disk JSON form. Trailing newline for a clean git diff. */
+    readonly serialize: (record: A) => string;
+}
+/** Build a lenient JSON codec for one sidecar record shape from its `Schema`. */
+export declare const makeSidecarCodec: <S extends Parameters<typeof Schema.decodeUnknownResult>[0]>(schema: S) => SidecarCodec<S['Type']>;
+//# sourceMappingURL=sidecar.d.ts.map

package/dist/core/sidecar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar.d.ts","sourceRoot":"","sources":["../../src/core/sidecar.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAU,MAAM,EAAE,MAAM,QAAQ,CAAA;AAKvC,qFAAqF;AACrF,eAAO,MAAM,QAAQ,WAAW,CAAA;AAEhC,MAAM,WAAW,UAAU;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;6EACyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,eAAO,MAAM,WAAW,SAAU,MAAM,KAAG,MAAmC,CAAA;AAE9E;+DAC+D;AAC/D,eAAO,MAAM,aAAa,cAAe,MAAM,YAAY,MAAM,KAAG,OACJ,CAAA;AAEhE;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,eAAgB,MAAM,UAAU,UAAU,cAAc,MAAM,KAAG,MAO3F,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,gBAAiB,MAAM,UAAU,UAAU,KAAG,MAAM,GAAG,IASrF,CAAA;AAED,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B;2CACuC;IACvC,QAAQ,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,CAAC,GAAG,IAAI,CAAA;IAC7C,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAA;CAC1C;AAED,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,UAAU,CAAC,OAAO,MAAM,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,UACjF,CAAC,KACR,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAexB,CAAA"}

package/dist/core/sidecar.js

@@ -0,0 +1,83 @@
+// The shared low-level primitive under every hidden `.cairn/**` metadata
+// sidecar: path mapping (a node's real path -> its sidecar's path, and back)
+// and a lenient JSON codec factory. Used by BOTH `summaries/StampStore.ts`
+// (doc-freshness records) and `links/RefStore.ts` (reference content-hash
+// records) — genuinely shared mechanics, kept deliberately separate from
+// either domain's own record shape (`StampRecord` vs `RefsRecord`), which
+// stay domain-owned: forcing one schema to serve two different sidecar
+// kinds would leave one half always meaningless for any given sidecar.
+//
+// Two invariants this module enforces:
+//  - every node path handed to `sidecarPathFor` must live under `base` (real
+//    usage: `base` is the project root, every root/node resolved under it) —
+//    violating this is a programming error, not a data error, so it throws;
+//  - a codec's `parse` decodes LENIENTLY: unknown keys are ignored rather
+//    than rejected (forward-compatible), and a corrupt/hand-edited/merge-
+//    conflicted sidecar reads as `null` — exactly equivalent to no record at
+//    all, never a crash.
+import * as nodePath from 'node:path';
+import { Result, Schema } from 'effect';
+// POSIX path semantics so sidecar paths are identical on every OS.
+const path = nodePath.posix;
+/** The hidden directory name every metadata tree lives under, relative to `base`. */
+export const META_DIR = '.cairn';
+export const metaRootFor = (base) => path.join(base, META_DIR);
+/** True for any path inside the hidden metadata tree — used to keep `.cairn/**`
+ * out of the set of markdown source files a plan considers. */
+export const isSidecarPath = (candidate, metaRoot) => candidate === metaRoot || candidate.startsWith(`${metaRoot}/`);
+/**
+ * `<base>/docs/a.summary.md` -> `<metaRoot>/docs/a.summary.md.json`, or, with
+ * a `namespace` (e.g. `'refs'`), `<metaRoot>/refs/docs/a.summary.md.json` —
+ * the mechanism that keeps two DIFFERENT sidecar kinds for the SAME doc path
+ * from colliding (a doc's own freshness stamp vs its reference hashes; see
+ * `links/RefStore.ts`'s header for the real collision this closes). Throws
+ * if `nodeAtPath` isn't under `base`: every real node path is (roots are
+ * always resolved under the project root before a plan ever runs), so this
+ * signals a caller bug, not a runtime data condition to recover from.
+ */
+export const sidecarPathFor = (nodeAtPath, layout, namespace) => {
+    const rel = path.relative(layout.base, nodeAtPath);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+        throw new Error(`sidecarPathFor: "${nodeAtPath}" is not under base "${layout.base}"`);
+    }
+    const root = namespace === undefined ? layout.metaRoot : path.join(layout.metaRoot, namespace);
+    return `${path.join(root, rel)}.json`;
+};
+/**
+ * The inverse of `sidecarPathFor` (namespace-free form): given a sidecar's
+ * own path (e.g. found by listing `.cairn/**`), recover the node path it
+ * mirrors. Returns `null` for a path that isn't a well-formed sidecar under
+ * `metaRoot` (not `.json`, or outside the tree) rather than throwing —
+ * unlike `sidecarPathFor`, this reads data that could plausibly be malformed
+ * (a stray non-JSON file dropped into `.cairn/` by hand), so `null` is the
+ * right "not a sidecar" signal, not a crash.
+ */
+export const nodePathForSidecar = (sidecarPath, layout) => {
+    if (!isSidecarPath(sidecarPath, layout.metaRoot) || !sidecarPath.endsWith('.json')) {
+        return null;
+    }
+    const rel = path.relative(layout.metaRoot, sidecarPath);
+    if (rel.startsWith('..')) {
+        return null;
+    }
+    return path.join(layout.base, rel.slice(0, -'.json'.length));
+};
+/** Build a lenient JSON codec for one sidecar record shape from its `Schema`. */
+export const makeSidecarCodec = (schema) => {
+    const decode = Schema.decodeUnknownResult(schema);
+    return {
+        parse: (content) => {
+            let json;
+            try {
+                json = JSON.parse(content);
+            }
+            catch {
+                return null;
+            }
+            const decoded = decode(json);
+            return Result.isSuccess(decoded) ? decoded.success : null;
+        },
+        serialize: (record) => `${JSON.stringify(record, null, 2)}\n`,
+    };
+};
+//# sourceMappingURL=sidecar.js.map

package/dist/core/sidecar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar.js","sourceRoot":"","sources":["../../src/core/sidecar.ts"],"names":[],"mappings":"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"}

package/dist/core/{DocSummaries.d.ts → summaries/DocSummaries.d.ts}

@@ -29,8 +29,6 @@ export declare const isSummaryFile: (path: string, naming?: Naming) => boolean;
 export declare const summaryPathFor: (path: string, naming?: Naming) => string;
 /** A non-summary Markdown file longer than the threshold must have a summary. */
 export declare const needsSummary: ({ lineCount, naming, path, thresholdLines, }: NeedsSummaryArgs) => boolean;
-/** Deterministic content hash used to stamp and verify summaries. */
-export declare const hashContent: (content: string) => string;
 /** The HTML-comment stamp a summary must carry to declare which source it reflects. */
 export declare const sourceHashTag: (hash: string) => string;
 /** Read back the source hash recorded in a summary, or null if absent. */

package/dist/core/summaries/DocSummaries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocSummaries.d.ts","sourceRoot":"","sources":["../../../src/core/summaries/DocSummaries.ts"],"names":[],"mappings":"AAyBA,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAAA;AAEtD,qDAAqD;AACrD,MAAM,WAAW,MAAM;IACrB,yDAAyD;IACzD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,sFAAsF;IACtF,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;CACnC;AAED,4DAA4D;AAC5D,eAAO,MAAM,cAAc,EAAE,MAG5B,CAAA;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAChC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;CAChC;AAED,sEAAsE;AACtE,eAAO,MAAM,uBAAuB,KAAK,CAAA;AAIzC,uDAAuD;AACvD,eAAO,MAAM,UAAU,YAAa,MAAM,KAAG,MAM5C,CAAA;AAED,uDAAuD;AACvD,eAAO,MAAM,aAAa,SAAU,MAAM,WAAU,MAAM,KAAoB,OACrC,CAAA;AAEzC,wEAAwE;AACxE,eAAO,MAAM,cAAc,SAAU,MAAM,WAAU,MAAM,KAAoB,MAC9B,CAAA;AAEjD,iFAAiF;AACjF,eAAO,MAAM,YAAY,iDAKtB,gBAAgB,KAAG,OAQrB,CAAA;AAED,uFAAuF;AACvF,eAAO,MAAM,aAAa,SAAU,MAAM,KAAG,MAA2C,CAAA;AAExF,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,mBAAoB,MAAM,KAAG,MAAM,GAAG,IAAiD,CAAA;AAErH;;;;0DAI0D;AAC1D,eAAO,MAAM,cAAc,mBAAoB,MAAM,QAAQ,MAAM,KAAG,MAMrE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,mBAAoB,MAAM,KAAG,MAKxD,CAAA;AAED,4EAA4E;AAC5E,eAAO,MAAM,eAAe,gDAAiD,YAAY,KAAG,aAQ3F,CAAA"}