@sledorze/cairn 0.1.0 → 0.3.0

package/dist/core/{MarkdownLinks.bench.js → links/MarkdownLinks.bench.js}

@@ -1,5 +1,5 @@
 import { bench, describe } from 'vitest';
-import { buildBasenameIndex, checkContent, extractLinkDefinitions, extractLinks, stripCode } from "./MarkdownLinks.js";
+import { buildBasenameIndex, checkContent, extractLinkDefinitions, extractLinks, stripCode } from './MarkdownLinks.js';
 const makeDoc = (linkCount) => {
     const lines = [];
     for (let i = 0; i < linkCount; i++) {

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

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

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

@@ -0,0 +1,121 @@
+export interface MarkdownLink {
+    readonly target: string;
+    readonly text: string;
+}
+export interface MarkdownLinkDef {
+    readonly label: string;
+    readonly target: string;
+}
+/** Why a link was reported broken — additive on `BrokenLink` (issue #39):
+ * `'path'` the target itself doesn't resolve (the original, only check);
+ * `'anchor'` the target resolves but its `#heading` fragment doesn't;
+ * `'line'` the target resolves but its `#L10`/`#L10-L20` fragment is out of range. */
+export type BrokenReason = 'anchor' | 'line' | 'path';
+export interface BrokenLink {
+    /** Short, human-readable elaboration — what's actually there instead, so
+     * fixing this doesn't require opening the target file first. E.g. for
+     * `reason: 'anchor'`, the target's real headings; for `reason: 'line'`,
+     * the target's real line count. */
+    readonly detail?: string;
+    readonly reason?: BrokenReason;
+    readonly suggestion?: string;
+    readonly target: string;
+    readonly text: string;
+}
+export interface SuggestFixArgs {
+    readonly fromDir: string;
+    readonly index: ReadonlyMap<string, readonly string[]>;
+    readonly target: string;
+}
+/**
+ * A checkable link whose target's existence and/or `#fragment` couldn't be
+ * decided without IO — either the target resolves outside the eagerly-listed
+ * `roots` (its existence itself is unknown), or it carries an anchor (its
+ * validity needs the target's real content, which `checkContent` — pure and
+ * IO-free — never reads for a file other than the one it's scanning). The
+ * caller (../program/CheckLinks.ts) resolves these, bounded by `base`.
+ */
+export interface PendingCheck {
+    /** `null` when the target itself has no `#fragment` — only existence (out of `roots`) is unresolved. */
+    readonly anchor: string | null;
+    readonly fromDir: string;
+    readonly target: string;
+    readonly targetAbs: string;
+    readonly text: string;
+}
+export interface CheckContentResult {
+    readonly broken: readonly BrokenLink[];
+    readonly pending: readonly PendingCheck[];
+}
+export interface CheckContentArgs {
+    readonly content: string;
+    readonly existsAbs: (absPath: string) => boolean;
+    readonly fileAbs: string;
+    readonly index?: ReadonlyMap<string, readonly string[]>;
+    /** True for any absolute path inside the eagerly-listed `roots` (regardless
+     * of whether it exists there) — lets `checkContent` tell "genuinely absent,
+     * in-root" (resolvable now, no IO) apart from "outside `roots` entirely"
+     * (existence itself unknown, deferred to `pending`). Defaults to "everything
+     * is in-root", matching this function's original, `roots`-only behaviour. */
+    readonly inRoots?: (absPath: string) => boolean;
+}
+/**
+ * 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 declare const stripCode: (content: string) => string;
+/** Extract inline Markdown links/images as `{ target, text }`. */
+export declare const extractLinks: (content: string) => MarkdownLink[];
+/** Extract reference-style link definitions (`[label]: ./path "title"`). */
+export declare const extractLinkDefinitions: (content: string) => MarkdownLinkDef[];
+/** 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 declare const isCheckableTarget: (target: string) => boolean;
+export interface ParsedTarget {
+    /** The raw text after `#`, or `null` if the target carries no fragment. */
+    readonly anchor: string | null;
+    /** The target with `#anchor`/`?query` removed; `''` for a bare `#anchor`
+     * (same-page fragment — the "path" is the current file itself). */
+    readonly path: string;
+}
+/** 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 declare const parseTarget: (target: string) => ParsedTarget;
+/** Drop `#anchor` and `?query` from a target. */
+export declare const stripAnchor: (target: string) => string;
+export interface Reference {
+    readonly anchor: string | null;
+    readonly target: string;
+}
+/**
+ * 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 declare const extractReferences: (content: string) => Reference[];
+/** Map basename -> list of absolute paths, for ambiguity-aware fixing. */
+export declare const buildBasenameIndex: (absPaths: readonly string[]) => Map<string, string[]>;
+/**
+ * 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 declare const suggestFix: ({ fromDir, index, target }: SuggestFixArgs) => string | null;
+/**
+ * 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 declare const checkContent: ({ content, existsAbs, fileAbs, index, inRoots, }: CheckContentArgs) => CheckContentResult;
+//# sourceMappingURL=MarkdownLinks.d.ts.map

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

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

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,GAAI,GAAG,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"}