@forumulate/cli 0.9.0 → 0.10.0

package/dist/check/command.js

@@ -0,0 +1,256 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHECK_HELP = exports.CHECK_VALUE_FLAGS = void 0;
+exports.runCheck = runCheck;
+exports.folderReport = folderReport;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const manifest_1 = require("../publish/manifest");
+const names_1 = require("../publish/names");
+const scan_1 = require("../publish/scan");
+const exit_codes_1 = require("../exit-codes");
+const external_1 = require("./external");
+const markdown_links_1 = require("./markdown-links");
+exports.CHECK_VALUE_FLAGS = ['--allow-redirect', '--ignore'];
+exports.CHECK_HELP = `forumulate check links [folder] [flags]
+forumulate check links --space <id|slug> [--org <id|slug>] [flags]
+
+Find broken links before readers do (FMU-F05).
+
+On a folder (the default, "."): reads it the way \`publish\` does — forumulate.yaml
+and every space in it — and checks, without a token and without publishing:
+  internal links   ./other.md, ../guide/setup.md, /slug, ./slug — the page must exist
+  anchors          #section and page#section — the heading (or {#id}, or id="…") must exist,
+                   with the product's own anchor rule (duplicates get -2, -3)
+  pictures         a local image or file the page points at must be on disk
+  external links   with --external: a 2xx passes; a redirect passes only to a host
+                   --allow-redirect allows (default same-host); never followed
+On a published space (--space): asks the API for the same report, which adds
+reference-page operation anchors (#operationId and #get-v1-x) and uploads.
+
+Flags:
+  --external              also check outside links (slow; paced per host; cached a day)
+  --allow-redirect <list> hosts a redirect may land on: same-host, docs.x.com, *.x.com
+                          (space mode: the space/org key links.check_allowed_redirect_hosts)
+  --ignore <pattern>      skip links containing this text (repeatable)
+  --no-cache              ask every outside link again
+  --json                  the report as JSON on stdout
+
+Exit status: 0 nothing broken, 1 something broken, 2 usage, 3 auth, 4 not found.`;
+const flagValues = (argv, name) => argv.flatMap((a, i) => a.startsWith(`${name}=`) ? [a.slice(name.length + 1)] : a === name ? [argv[i + 1] ?? ''] : []);
+/** `forumulate check …` — only `links` today; the noun leaves room for the next check. */
+async function runCheck(argv, rest, deps) {
+    const [what, folder] = rest;
+    if (what !== 'links' || argv.includes('--help')) {
+        (what === 'links' || argv.includes('--help') ? deps.out : deps.err)(exports.CHECK_HELP);
+        return what === 'links' || argv.includes('--help') ? exit_codes_1.EXIT.OK : exit_codes_1.EXIT.USAGE;
+    }
+    const json = argv.includes('--json');
+    const external = argv.includes('--external');
+    const allow = flagValues(argv, '--allow-redirect').flatMap((v) => v.split(',')).map((v) => v.trim()).filter(Boolean);
+    const ignore = flagValues(argv, '--ignore').filter(Boolean);
+    const space = flagValues(argv, '--space')[0];
+    let report;
+    try {
+        report = space
+            ? await spaceReport(space, flagValues(argv, '--org')[0], external, deps)
+            : folderReport((0, node_path_1.resolve)(folder ?? '.'), deps);
+    }
+    catch (e) {
+        deps.err(`check links: ${e.message}`);
+        // A folder that cannot be read is the command line's fault (2); an API
+        // refusal maps as every command maps it (3 auth, 4 not found, …).
+        return space ? (0, exit_codes_1.exitCodeForError)(e) : exit_codes_1.EXIT.USAGE;
+    }
+    if (!space && external) {
+        const checker = new external_1.ExternalChecker({
+            allowRedirects: allow.length ? allow : ['same-host'],
+            cacheFile: argv.includes('--no-cache') ? null : (0, external_1.defaultCacheFile)(deps.env),
+            fetch: deps.fetch,
+        });
+        const pending = report.external;
+        const verdicts = await checker.checkAll(pending.keys());
+        report.checked.external = pending.size;
+        for (const [url, v] of verdicts) {
+            if (v.ok)
+                continue;
+            for (const at of pending.get(url) ?? [])
+                report.broken.push({
+                    ...at,
+                    url,
+                    reason: v.reason ?? 'external_unreachable',
+                    status: v.status,
+                    ...(v.location ? { location: v.location } : {}),
+                });
+        }
+    }
+    report.broken = report.broken.filter((b) => !ignore.some((p) => b.url.includes(p)));
+    print(report, json, deps);
+    return report.broken.length ? exit_codes_1.EXIT.FAILED : exit_codes_1.EXIT.OK;
+}
+function print(report, json, deps) {
+    const { external: _x, ...plain } = report;
+    if (json) {
+        deps.out(JSON.stringify(plain, null, 2));
+        return;
+    }
+    for (const b of report.broken) {
+        const extra = b.anchor
+            ? `  #${b.anchor} is not on that page`
+            : b.location
+                ? `  → ${b.location} (${b.status})`
+                : b.status
+                    ? `  (${b.status})`
+                    : '';
+        deps.out(`${b.where}${b.line ? `:${b.line}` : ''}  ${b.reason.padEnd(20)} ${b.url}${extra}`);
+    }
+    const c = report.checked;
+    deps.out(`${report.broken.length ? `${report.broken.length} broken` : 'No broken links'} — ` +
+        `${c.links} link(s) on ${c.pages} page(s), ${c.anchors} anchor(s)` +
+        (c.external ? `, ${c.external} outside address(es)` : '') +
+        (c.unchecked ? `; ${c.unchecked} link(s) into other spaces not checked from a folder` : '') +
+        '.');
+}
+async function spaceReport(space, orgFlag, external, deps) {
+    const org = orgFlag ?? deps.env?.FORUMULATE_ORG ?? process.env.FORUMULATE_ORG;
+    if (!org)
+        throw Object.assign(new Error('which organization? Pass --org or set FORUMULATE_ORG.'), { exitCode: exit_codes_1.EXIT.USAGE });
+    if (!deps.request)
+        throw Object.assign(new Error('no API client'), { exitCode: exit_codes_1.EXIT.AUTH });
+    const r = await deps.request('GET', `/orgs/${encodeURIComponent(org)}/spaces/${encodeURIComponent(space)}/docs/broken-links`, {
+        query: { external, refresh: true },
+    });
+    return {
+        mode: 'space',
+        checked: { ...r.checked, unchecked: 0 },
+        broken: r.broken.map(({ pageSlug, ...b }) => ({ where: pageSlug, ...b })),
+    };
+}
+/** Path inside a space folder → the page it is, case-insensitively. */
+function pageIndex(root, scan) {
+    const bySlug = new Map();
+    const byFile = new Map();
+    for (const c of scan.collections)
+        for (const p of c.pages) {
+            if (p.stub)
+                continue;
+            bySlug.set(p.slug, p);
+            // `file` is relative to the publish root; links are relative to the page.
+            byFile.set((0, node_path_1.relative)(scan.absDir, (0, node_path_1.resolve)(root, p.file)).split(node_path_1.sep).join('/').toLowerCase(), p);
+        }
+    return { bySlug, byFile };
+}
+/** The folder half: every space the manifest names, read as `publish` reads it. */
+function folderReport(root, _deps = {}) {
+    if (!(0, node_fs_1.existsSync)(root) || !(0, node_fs_1.statSync)(root).isDirectory())
+        throw new Error(`${root} is not a folder`);
+    const manifest = (0, manifest_1.loadManifest)((0, manifest_1.findManifest)(root));
+    const spaces = manifest.spaces.map((spec) => {
+        const scan = (0, scan_1.scanSpace)(root, spec, 'docs', []);
+        return { key: spec.space ?? spec.path, spec, scan, ...pageIndex(root, scan) };
+    });
+    const byKey = new Map(spaces.map((s) => [s.key ?? '', s]));
+    const anchorsMemo = new Map();
+    const anchorsOf = (p) => {
+        let a = anchorsMemo.get(p);
+        if (!a)
+            anchorsMemo.set(p, (a = (0, markdown_links_1.markdownAnchors)(p.source, p.title)));
+        return a;
+    };
+    const report = {
+        mode: 'folder',
+        checked: { pages: 0, links: 0, anchors: 0, external: 0, unchecked: 0 },
+        broken: [],
+        external: new Map(),
+    };
+    for (const s of spaces) {
+        for (const page of s.bySlug.values()) {
+            report.checked.pages += 1;
+            const fileAbs = (0, node_path_1.resolve)(root, page.file);
+            const inSpace = (0, node_path_1.relative)(s.scan.absDir, fileAbs).split(node_path_1.sep).join('/');
+            for (const link of (0, markdown_links_1.markdownLinks)(page.source)) {
+                const href = link.href.trim();
+                if (!href || /^(mailto|tel|javascript|data):/i.test(href))
+                    continue;
+                report.checked.links += 1;
+                const where = { where: page.file, line: link.line };
+                if (/^https?:\/\//i.test(href)) {
+                    const bare = href.replace(/#.*$/, '');
+                    report.external.set(bare, [...(report.external.get(bare) ?? []), where]);
+                    continue;
+                }
+                if (/^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith('//'))
+                    continue;
+                const hash = href.indexOf('#');
+                const path = (hash >= 0 ? href.slice(0, hash) : href).replace(/\?.*$/, '');
+                let anchor = null;
+                if (hash >= 0 && hash < href.length - 1) {
+                    try {
+                        anchor = decodeURIComponent(href.slice(hash + 1));
+                    }
+                    catch {
+                        anchor = href.slice(hash + 1);
+                    }
+                }
+                let target;
+                if (!path)
+                    target = page;
+                else if (names_1.MD.test(path)) {
+                    let rel;
+                    try {
+                        rel = node_path_1.posix.normalize(node_path_1.posix.join(node_path_1.posix.dirname(inSpace), decodeURI(path))).toLowerCase();
+                    }
+                    catch {
+                        rel = path.toLowerCase();
+                    }
+                    target = s.byFile.get(rel);
+                    if (!target) {
+                        report.broken.push({ ...where, url: href, reason: 'internal_not_found' });
+                        continue;
+                    }
+                }
+                else if (names_1.ASSET.test(path) || link.media) {
+                    // A picture or file next to the page; a root path is the site's to serve.
+                    if (path.startsWith('/'))
+                        continue;
+                    let abs;
+                    try {
+                        abs = (0, node_path_1.join)((0, node_path_1.dirname)(fileAbs), decodeURI(path));
+                    }
+                    catch {
+                        abs = (0, node_path_1.join)((0, node_path_1.dirname)(fileAbs), path);
+                    }
+                    if (!(0, node_fs_1.existsSync)(abs))
+                        report.broken.push({ ...where, url: href, reason: 'asset_missing' });
+                    continue;
+                }
+                else {
+                    const segments = path.split('/').filter((x) => x && x !== '.');
+                    const last = (segments[segments.length - 1] ?? '').replace(/\.md$/i, '');
+                    if (path.startsWith('/') && segments.length > 1) {
+                        const other = byKey.get(segments[0]);
+                        if (!other) {
+                            // Another section of the site we cannot see from this folder.
+                            report.checked.unchecked += 1;
+                            continue;
+                        }
+                        target = other.bySlug.get(last);
+                    }
+                    else
+                        target = s.bySlug.get(last);
+                    if (!target) {
+                        report.broken.push({ ...where, url: href, reason: 'internal_not_found' });
+                        continue;
+                    }
+                }
+                if (anchor && target) {
+                    report.checked.anchors += 1;
+                    if (!anchorsOf(target).has(anchor))
+                        report.broken.push({ ...where, url: href, reason: 'anchor_not_found', anchor });
+                }
+            }
+        }
+    }
+    return report;
+}
+//# sourceMappingURL=command.js.map

package/dist/check/command.js.map

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

package/dist/check/external.d.ts

@@ -0,0 +1,66 @@
+/** One outside link's verdict. */
+export interface Verdict {
+    ok: boolean;
+    status: number;
+    location?: string;
+    reason?: 'external_unreachable' | 'external_redirect';
+    /** When it was asked, ms since the epoch — for the cache. */
+    at: number;
+}
+export type Fetcher = (url: string, init: {
+    method: string;
+    redirect: 'manual';
+    signal: AbortSignal;
+    headers: Record<string, string>;
+}) => Promise<{
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+}>;
+export interface ExternalOptions {
+    /** Hosts a redirect may land on and still pass: `same-host`, `docs.x.com`, `*.x.com`, `*`. */
+    allowRedirects: string[];
+    concurrency?: number;
+    /** Gap between two requests to one host, ms. */
+    perHostGapMs?: number;
+    timeoutMs?: number;
+    /** Where verdicts are kept between runs; null for none. */
+    cacheFile?: string | null;
+    okTtlMs?: number;
+    brokenTtlMs?: number;
+    fetch?: Fetcher;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+/** Where the verdicts live: `$XDG_CACHE_HOME/forumulate/link-check.json`. */
+export declare function defaultCacheFile(env?: NodeJS.ProcessEnv): string;
+/**
+ * Whether a redirect from `from` to `location` is one the caller accepts —
+ * the same rule as the API's `redirectAllowed` (packages/shared docs-workflow),
+ * mirrored because this package ships alone.
+ */
+export declare function redirectAllowed(from: string, location: string, allow: readonly string[]): boolean;
+/**
+ * Outside links, checked the way the API checks them (FMU-F05): no redirect is
+ * followed — a 3xx passes only to an allowed host, else it is
+ * `external_redirect` naming where it goes; `HEAD` first, `GET` when a host
+ * refuses `HEAD`; a few requests at once and a gap between two to the same
+ * host, so a docs folder with 300 links to one site is not a burst; and a
+ * verdict file, so a second run in a minute asks nothing (a day for a working
+ * link, an hour for a broken one).
+ */
+export declare class ExternalChecker {
+    private readonly last;
+    private cache;
+    private readonly o;
+    constructor(opts: ExternalOptions);
+    checkAll(urls: Iterable<string>): Promise<Map<string, Verdict>>;
+    private fresh;
+    check(url: string): Promise<Verdict>;
+    private pace;
+    private request;
+    private ask;
+    private save;
+}
+//# sourceMappingURL=external.d.ts.map

package/dist/check/external.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external.d.ts","sourceRoot":"","sources":["../../src/check/external.ts"],"names":[],"mappings":"AAIA,kCAAkC;AAClC,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,sBAAsB,GAAG,mBAAmB,CAAC;IACtD,6DAA6D;IAC7D,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,MAAM,OAAO,GAAG,CACpB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,KAC/F,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE;QAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;KAAE,CAAA;CAAE,CAAC,CAAC;AAEhF,MAAM,WAAW,eAAe;IAC9B,8FAA8F;IAC9F,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAG7E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAmBjG;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6B;IAClD,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,QAAQ,CAAC,CAAC,CAGhB;gBAEU,IAAI,EAAE,eAAe;IAsB3B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAWrE,OAAO,CAAC,KAAK;IAKP,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;YAQ5B,IAAI;YAaJ,OAAO;YAgBP,GAAG;IAyBjB,OAAO,CAAC,IAAI;CAWb"}

package/dist/check/external.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExternalChecker = void 0;
+exports.defaultCacheFile = defaultCacheFile;
+exports.redirectAllowed = redirectAllowed;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+/** Where the verdicts live: `$XDG_CACHE_HOME/forumulate/link-check.json`. */
+function defaultCacheFile(env = process.env) {
+    const base = env.XDG_CACHE_HOME || (0, node_path_1.join)((0, node_os_1.homedir)(), '.cache');
+    return (0, node_path_1.join)(base, 'forumulate', 'link-check.json');
+}
+/**
+ * Whether a redirect from `from` to `location` is one the caller accepts —
+ * the same rule as the API's `redirectAllowed` (packages/shared docs-workflow),
+ * mirrored because this package ships alone.
+ */
+function redirectAllowed(from, location, allow) {
+    let a;
+    let b;
+    try {
+        a = new URL(from);
+        b = new URL(location, from);
+    }
+    catch {
+        return false;
+    }
+    const host = b.hostname.toLowerCase();
+    for (const raw of allow) {
+        const p = raw.trim().toLowerCase();
+        if (!p)
+            continue;
+        if (p === 'same-host' && host === a.hostname.toLowerCase())
+            return true;
+        if (p === '*')
+            return true;
+        if (p.startsWith('*.') && (host === p.slice(2) || host.endsWith(p.slice(1))))
+            return true;
+        if (host === p)
+            return true;
+    }
+    return false;
+}
+/**
+ * Outside links, checked the way the API checks them (FMU-F05): no redirect is
+ * followed — a 3xx passes only to an allowed host, else it is
+ * `external_redirect` naming where it goes; `HEAD` first, `GET` when a host
+ * refuses `HEAD`; a few requests at once and a gap between two to the same
+ * host, so a docs folder with 300 links to one site is not a burst; and a
+ * verdict file, so a second run in a minute asks nothing (a day for a working
+ * link, an hour for a broken one).
+ */
+class ExternalChecker {
+    last = new Map();
+    cache = {};
+    o;
+    constructor(opts) {
+        this.o = {
+            concurrency: 4,
+            perHostGapMs: 300,
+            timeoutMs: 10_000,
+            okTtlMs: 86_400_000,
+            brokenTtlMs: 3_600_000,
+            sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+            now: () => Date.now(),
+            ...opts,
+            fetch: opts.fetch ?? globalThis.fetch,
+            cacheFile: opts.cacheFile === undefined ? null : opts.cacheFile,
+        };
+        if (this.o.cacheFile && (0, node_fs_1.existsSync)(this.o.cacheFile)) {
+            try {
+                this.cache = JSON.parse((0, node_fs_1.readFileSync)(this.o.cacheFile, 'utf8'));
+            }
+            catch {
+                this.cache = {};
+            }
+        }
+    }
+    async checkAll(urls) {
+        const queue = [...new Set(urls)];
+        const out = new Map();
+        const worker = async () => {
+            for (let u = queue.shift(); u !== undefined; u = queue.shift())
+                out.set(u, await this.check(u));
+        };
+        await Promise.all(Array.from({ length: Math.min(this.o.concurrency, queue.length) }, worker));
+        this.save();
+        return out;
+    }
+    fresh(v) {
+        if (!v)
+            return false;
+        return this.o.now() - v.at < (v.ok ? this.o.okTtlMs : this.o.brokenTtlMs);
+    }
+    async check(url) {
+        const hit = this.cache[url];
+        if (this.fresh(hit))
+            return hit;
+        const v = await this.ask(url);
+        this.cache[url] = v;
+        return v;
+    }
+    async pace(url) {
+        let host = '';
+        try {
+            host = new URL(url).host;
+        }
+        catch {
+            return;
+        }
+        const due = (this.last.get(host) ?? 0) + this.o.perHostGapMs;
+        this.last.set(host, Math.max(this.o.now(), due));
+        const wait = due - this.o.now();
+        if (wait > 0)
+            await this.o.sleep(wait);
+    }
+    async request(url, method) {
+        await this.pace(url);
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), this.o.timeoutMs);
+        try {
+            return await this.o.fetch(url, {
+                method,
+                redirect: 'manual',
+                signal: ctrl.signal,
+                headers: { 'user-agent': 'forumulate-cli link check', accept: 'text/html,*/*;q=0.8' },
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async ask(url) {
+        const at = this.o.now();
+        try {
+            let res = await this.request(url, 'HEAD');
+            if ([403, 405, 501].includes(res.status))
+                res = await this.request(url, 'GET');
+            const status = res.status;
+            if (status >= 200 && status < 300)
+                return { ok: true, status, at };
+            if (status >= 300 && status < 400) {
+                const raw = res.headers.get('location') ?? '';
+                let location = raw;
+                try {
+                    location = new URL(raw, url).toString();
+                }
+                catch {
+                    /* kept as sent */
+                }
+                if (raw && redirectAllowed(url, location, this.o.allowRedirects))
+                    return { ok: true, status, location, at };
+                return { ok: false, status, location, reason: 'external_redirect', at };
+            }
+            return { ok: false, status, reason: 'external_unreachable', at };
+        }
+        catch {
+            return { ok: false, status: 0, reason: 'external_unreachable', at };
+        }
+    }
+    save() {
+        if (!this.o.cacheFile)
+            return;
+        try {
+            (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(this.o.cacheFile), { recursive: true });
+            // Only verdicts still worth keeping, so the file does not grow forever.
+            const keep = Object.fromEntries(Object.entries(this.cache).filter(([, v]) => this.fresh(v)));
+            (0, node_fs_1.writeFileSync)(this.o.cacheFile, JSON.stringify(keep));
+        }
+        catch {
+            /* a cache that cannot be written is only a slower next run */
+        }
+    }
+}
+exports.ExternalChecker = ExternalChecker;
+//# sourceMappingURL=external.js.map

package/dist/check/external.js.map

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

package/dist/check/markdown-links.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Links and anchors in a Markdown file, read the way the product reads them —
+ * for `forumulate check links` on a folder (FMU-F05), before anything is
+ * published.
+ *
+ * This package ships alone (it depends on the SDK and `yaml`, nothing else), so
+ * the heading rule is mirrored here rather than imported, the way `names.ts`
+ * mirrors the slug rule: `headingSlug` below is the docs-schema's
+ * `headingSlug` (packages/docs-schema/src/heading-slug.ts), and
+ * `markdown-links.test.ts` pins the same cases that file's tests do. A checker
+ * whose anchors differ from the renderer's would report working links broken.
+ */
+/** A heading's anchor id from its text — the renderer's rule. */
+export declare function headingSlug(text: string): string;
+/** The id the renderer used before the accent fix, still answered as an alias. */
+export declare function legacyHeadingSlug(text: string): string | null;
+/** A link as written, and the line it is on (1-based, in the file). */
+export interface FoundLink {
+    href: string;
+    line: number;
+    /** An image or embedded file, rather than a link a reader follows. */
+    media: boolean;
+}
+/**
+ * Every `#fragment` the page will answer to: each heading's id (duplicates
+ * suffixed `-2`, `-3`, as the renderer claims them), its pre-fix alias, an
+ * explicit `{#id}` on a heading, and any `id="…"` / `name="…"` in HTML.
+ * `title` drops a leading `# Title` that repeats the page title, which the
+ * renderer does not render as a heading either.
+ */
+export declare function markdownAnchors(text: string, title?: string): Set<string>;
+/**
+ * Every link and picture in the file: `[t](href)`, `![a](src)`, reference
+ * definitions `[id]: href`, and HTML `href=` / `src=` — not inside a code
+ * fence or an inline code span, where a URL is an example, not a link.
+ */
+export declare function markdownLinks(text: string): FoundLink[];
+//# sourceMappingURL=markdown-links.d.ts.map

package/dist/check/markdown-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-links.d.ts","sourceRoot":"","sources":["../../src/check/markdown-links.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAWH,iEAAiE;AACjE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUhD;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS7D;AA4BD,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,KAAK,EAAE,OAAO,CAAC;CAChB;AAwBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAkCzE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,CAgBvD"}