docspack 0.0.1 → 0.1.0

package/dist/discovery.js

@@ -0,0 +1,126 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { DocspackError } from "./errors.js";
+import { isCommunityPackage, isDocsPackage, LLMS_DIR, MANIFEST_FILE, packageId, parseManifest, } from "./spec.js";
+/**
+ * Finds the documentation packages a project depends on: every `@vendor/docspack` or
+ * `@docspack-community/*` entry in `dependencies` or `devDependencies` that is installed and
+ * ships a `.llms/manifest.json`.
+ */
+export async function discoverPackages(cwd) {
+    const root = resolve(cwd);
+    const declared = await declaredDocsPackages(root);
+    const packages = [];
+    const problems = [];
+    for (const name of declared) {
+        const dir = await resolvePackageDir(name, root);
+        if (dir === undefined) {
+            problems.push(`${name} is declared in package.json but is not installed`);
+            continue;
+        }
+        let version;
+        try {
+            version = await installedVersion(name, dir);
+        }
+        catch (error) {
+            problems.push(describe(error));
+            continue;
+        }
+        const llmsDir = join(dir, LLMS_DIR);
+        let manifest;
+        try {
+            const raw = await readFile(join(llmsDir, MANIFEST_FILE), "utf8");
+            manifest = parseManifest(JSON.parse(raw), `${name} ${LLMS_DIR}/${MANIFEST_FILE}`);
+        }
+        catch (error) {
+            problems.push(error.code === "ENOENT"
+                ? `${name} has no ${LLMS_DIR}/${MANIFEST_FILE} and cannot be indexed`
+                : describe(error));
+            continue;
+        }
+        if (manifest.version !== version) {
+            problems.push(`${name}: manifest says version ${manifest.version}, package.json says ${version}; using ${version}`);
+        }
+        packages.push({
+            id: packageId(name, version),
+            name,
+            version,
+            dir,
+            llmsDir,
+            manifest,
+            trusted: !isCommunityPackage(name),
+        });
+    }
+    packages.sort((a, b) => a.name.localeCompare(b.name));
+    return { packages, problems };
+}
+/** Package ids installed in this project, used to scope queries to the versions actually in use. */
+export async function projectPackageIds(cwd) {
+    const { packages } = await discoverPackages(cwd);
+    return packages.map((pkg) => pkg.id);
+}
+async function declaredDocsPackages(cwd) {
+    let raw;
+    try {
+        raw = await readFile(join(cwd, "package.json"), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new DocspackError(`No package.json found in ${cwd}`, {
+                hint: "Run docspack from a project directory, or pass --cwd <dir>.",
+            });
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new DocspackError(`${join(cwd, "package.json")} is not valid JSON`, { cause: error });
+    }
+    const root = parsed;
+    const names = new Set();
+    for (const field of [root.dependencies, root.devDependencies]) {
+        if (typeof field !== "object" || field === null)
+            continue;
+        for (const name of Object.keys(field)) {
+            if (isDocsPackage(name))
+                names.add(name);
+        }
+    }
+    return [...names].sort();
+}
+/**
+ * Walks `node_modules` upwards from the project, which resolves npm, pnpm (through its symlinks)
+ * and workspace layouts without depending on a package's export map.
+ */
+export async function resolvePackageDir(name, cwd) {
+    let dir = cwd;
+    while (true) {
+        const candidate = join(dir, "node_modules", ...name.split("/"));
+        try {
+            await readFile(join(candidate, "package.json"), "utf8");
+            return candidate;
+        }
+        catch {
+            // Not here; keep walking up.
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+async function installedVersion(name, dir) {
+    const parsed = JSON.parse(await readFile(join(dir, "package.json"), "utf8"));
+    const version = parsed.version;
+    if (typeof version !== "string" || version.length === 0) {
+        throw new DocspackError(`${name} has no version in its package.json`);
+    }
+    return version;
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=discovery.js.map

package/dist/discovery.js.map

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

package/dist/doctor.d.ts

@@ -0,0 +1,25 @@
+export type Severity = "error" | "warn" | "info";
+export interface Finding {
+    readonly check: string;
+    readonly severity: Severity;
+    readonly message: string;
+    readonly where?: string;
+    readonly fix?: string;
+}
+export interface DoctorReport {
+    readonly ok: boolean;
+    readonly findings: readonly Finding[];
+    readonly chunks: number;
+    readonly tokens: number;
+}
+export interface DoctorOptions {
+    readonly dir: string;
+    /** Treat warnings as failures. Used by prepublishOnly and CI. */
+    readonly strict?: boolean;
+}
+/**
+ * Checks a documentation package the way the indexer and a reviewer would. A broken docs package
+ * still installs and still indexes, so every problem here is one that would otherwise be silent.
+ */
+export declare function runDoctor(options: DoctorOptions): Promise<DoctorReport>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAqBA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAEjD,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAMD;;;GAGG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAqK7E"}

package/dist/doctor.js

@@ -0,0 +1,276 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { readBuildConfig } from "./config.js";
+import { PLACEHOLDER } from "./init/templates.js";
+import { estimateTokens, LLMS_DIR, MANIFEST_FILE, parseManifest, resolveChunkFile, } from "./spec.js";
+import { contentFingerprint, findFiller, findLongSentences, hasConcreteContent, withoutCode, } from "./style.js";
+/** Over this, a chunk crowds out the response budget; under it, a chunk answers nothing. */
+const MAX_CHUNK_TOKENS = 1500;
+const MIN_CHUNK_TOKENS = 30;
+/**
+ * Checks a documentation package the way the indexer and a reviewer would. A broken docs package
+ * still installs and still indexes, so every problem here is one that would otherwise be silent.
+ */
+export async function runDoctor(options) {
+    const findings = [];
+    const llmsDir = join(options.dir, LLMS_DIR);
+    const pkg = await readJson(join(options.dir, "package.json"));
+    const manifest = await loadManifest(llmsDir, findings);
+    if (manifest === undefined) {
+        return { ok: false, findings, chunks: 0, tokens: 0 };
+    }
+    checkPackageJson(pkg, manifest, findings);
+    let tokens = 0;
+    let newestSource = 0;
+    const seen = new Map();
+    const abstract = [];
+    for (const chunk of manifest.chunks) {
+        let contents;
+        try {
+            contents = await readFile(resolveChunkFile(llmsDir, chunk.file), "utf8");
+        }
+        catch (error) {
+            findings.push({
+                check: /outside of/.test(String(error)) ? "chunk-escapes" : "chunk-missing",
+                severity: "error",
+                message: /outside of/.test(String(error))
+                    ? `chunk "${chunk.id}" points outside ${LLMS_DIR}/`
+                    : `chunk "${chunk.id}" is missing its file`,
+                where: chunk.file,
+                fix: "Rebuild with `docspack build`.",
+            });
+            continue;
+        }
+        const text = contents.trim();
+        if (text.length === 0) {
+            findings.push({
+                check: "chunk-empty",
+                severity: "error",
+                message: `chunk "${chunk.id}" is empty`,
+                where: chunk.file,
+                fix: "Write the section, or remove it from the manifest.",
+            });
+            continue;
+        }
+        const size = chunk.tokens > 0 ? chunk.tokens : estimateTokens(text);
+        tokens += size;
+        if (size > MAX_CHUNK_TOKENS) {
+            findings.push({
+                check: "chunk-too-large",
+                severity: "warn",
+                message: `chunk "${chunk.id}" is ~${size} tokens; it will crowd out a response`,
+                where: chunk.file,
+                fix: "Split the section with more headings, or lower maxChunkTokens.",
+            });
+        }
+        else if (size < MIN_CHUNK_TOKENS) {
+            findings.push({
+                check: "chunk-too-small",
+                severity: "warn",
+                message: `chunk "${chunk.id}" is ~${size} tokens; too small to answer anything`,
+                where: chunk.file,
+                fix: "Merge it into a neighbouring section.",
+            });
+        }
+        if (chunk.tags.length === 0 && chunk.entities.length === 0) {
+            findings.push({
+                check: "untagged",
+                severity: "warn",
+                message: `chunk "${chunk.id}" has no tags or entities; it is findable only by its prose`,
+                where: chunk.file,
+                fix: "Name the API in `inline code`, or add tags to the manifest.",
+            });
+        }
+        // Prose that mentions the marker inside `code` is documenting it, not leaving one behind.
+        if (withoutCode(text).includes(PLACEHOLDER)) {
+            findings.push({
+                check: "placeholder",
+                severity: "warn",
+                message: `chunk "${chunk.id}" still contains ${PLACEHOLDER} markers from the template`,
+                where: chunk.file,
+                fix: "Replace the template text with real documentation.",
+            });
+        }
+        const filler = findFiller(text);
+        if (filler.length > 0) {
+            const listed = filler
+                .slice(0, 3)
+                .map((hit) => `"${hit.phrase}"`)
+                .join(", ");
+            findings.push({
+                check: "filler",
+                severity: "warn",
+                message: `chunk "${chunk.id}" contains narration a model does not need: ${listed}`,
+                where: chunk.file,
+                fix: "Delete it. Nobody searches for these words and they carry no fact.",
+            });
+        }
+        const long = findLongSentences(text);
+        if (long.length > 0) {
+            findings.push({
+                check: "long-sentence",
+                severity: "warn",
+                message: `chunk "${chunk.id}" has ${plural(long.length, "sentence")} over 40 words`,
+                where: chunk.file,
+                fix: "Split them. One claim per sentence retrieves and reads better.",
+            });
+        }
+        if (!hasConcreteContent(text))
+            abstract.push(chunk.id);
+        const fingerprint = contentFingerprint(text);
+        const twin = seen.get(fingerprint);
+        if (twin === undefined)
+            seen.set(fingerprint, chunk.id);
+        else {
+            findings.push({
+                check: "duplicate-chunk",
+                severity: "warn",
+                message: `chunk "${chunk.id}" says the same thing as "${twin}"`,
+                where: chunk.file,
+                fix: "Remove one. Duplicates compete for the same query and waste the response budget.",
+            });
+        }
+    }
+    if (abstract.length > 0) {
+        findings.push({
+            check: "no-example",
+            severity: "info",
+            message: `${plural(abstract.length, "chunk")} of ${manifest.chunks.length} have no code, list or table: ${abstract.slice(0, 3).join(", ")}${abstract.length > 3 ? ", …" : ""}`,
+            fix: "Agents act on concrete text. Add the call, the signature or the values.",
+        });
+    }
+    if (manifest.chunks.every((chunk) => chunk.entities.length === 0)) {
+        findings.push({
+            check: "no-entities",
+            severity: "info",
+            message: "no chunk names an identifier; agents searching for an API name may miss this package",
+            fix: "Put API names in `inline code` in the source documentation.",
+        });
+    }
+    newestSource = await newestSourceMtime(options.dir);
+    const manifestMtime = await mtime(join(llmsDir, MANIFEST_FILE));
+    if (newestSource > 0 && manifestMtime > 0 && newestSource > manifestMtime) {
+        findings.push({
+            check: "payload-stale",
+            severity: "warn",
+            message: "the documentation source is newer than the generated payload",
+            fix: "Run `docspack build`.",
+        });
+    }
+    const failed = findings.some((finding) => finding.severity === "error" || (options.strict === true && finding.severity === "warn"));
+    return { ok: !failed, findings, chunks: manifest.chunks.length, tokens };
+}
+function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+async function loadManifest(llmsDir, findings) {
+    let raw;
+    try {
+        raw = await readFile(join(llmsDir, MANIFEST_FILE), "utf8");
+    }
+    catch {
+        findings.push({
+            check: "manifest-invalid",
+            severity: "error",
+            message: `no ${LLMS_DIR}/${MANIFEST_FILE}`,
+            fix: "Run `docspack build` to generate the payload.",
+        });
+        return undefined;
+    }
+    try {
+        return parseManifest(JSON.parse(raw), `${LLMS_DIR}/${MANIFEST_FILE}`);
+    }
+    catch (error) {
+        findings.push({
+            check: "manifest-invalid",
+            severity: "error",
+            message: error instanceof Error ? error.message : String(error),
+            where: `${LLMS_DIR}/${MANIFEST_FILE}`,
+            fix: "Run `docspack build` to regenerate it.",
+        });
+        return undefined;
+    }
+}
+function checkPackageJson(pkg, manifest, findings) {
+    if (pkg === undefined) {
+        findings.push({
+            check: "manifest-invalid",
+            severity: "error",
+            message: "no package.json next to the payload",
+            fix: "Run `docspack init` or add a package.json.",
+        });
+        return;
+    }
+    if (typeof pkg.version === "string" && pkg.version !== manifest.version) {
+        findings.push({
+            check: "version-mismatch",
+            severity: "error",
+            message: `package.json is ${pkg.version} but the manifest says ${manifest.version}`,
+            fix: "Run `docspack build` after bumping the version.",
+        });
+    }
+    if (typeof pkg.name === "string" && pkg.name !== manifest.name) {
+        findings.push({
+            check: "version-mismatch",
+            severity: "error",
+            message: `package.json is ${pkg.name} but the manifest says ${manifest.name}`,
+            fix: "Run `docspack build` to regenerate the manifest.",
+        });
+    }
+    const files = Array.isArray(pkg.files) ? pkg.files.map(String) : undefined;
+    if (files !== undefined &&
+        !files.some((entry) => entry.replace(/^\.\//, "").startsWith(LLMS_DIR))) {
+        findings.push({
+            check: "files-missing-payload",
+            severity: "error",
+            message: `"files" does not include ${LLMS_DIR}; publishing would ship a package with no documentation`,
+            where: "package.json",
+            fix: `Add "${LLMS_DIR}" to the files array.`,
+        });
+    }
+}
+/** Newest mtime across the configured documentation source, used to spot a stale payload. */
+async function newestSourceMtime(dir) {
+    const config = await readBuildConfig(dir);
+    const source = config.from ?? config.openapi;
+    if (source === undefined)
+        return 0;
+    const target = join(dir, source);
+    const single = await mtime(target);
+    if (single > 0 && config.openapi !== undefined)
+        return single;
+    let found;
+    try {
+        found = await readdir(target, { recursive: true, withFileTypes: true });
+    }
+    catch {
+        return single;
+    }
+    let newest = 0;
+    for (const entry of found) {
+        if (!entry.isFile())
+            continue;
+        newest = Math.max(newest, await mtime(join(entry.parentPath, entry.name)));
+    }
+    return newest;
+}
+async function mtime(path) {
+    try {
+        return (await stat(path)).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+async function readJson(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        return typeof parsed === "object" && parsed !== null
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=doctor.js.map

package/dist/doctor.js.map

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

package/dist/document.d.ts

@@ -0,0 +1,13 @@
+export interface CleanedDocument {
+    readonly text: string;
+    /** Title taken from front matter, when the document declares one. */
+    readonly title?: string;
+    /** Keywords taken from front matter, indexed alongside the prose. */
+    readonly tags: readonly string[];
+}
+/**
+ * Prepares a source document for chunking: lifts front matter into metadata the index can use,
+ * and drops site boilerplate. Prose is left alone — the index matches on it.
+ */
+export declare function cleanDocument(raw: string): CleanedDocument;
+//# sourceMappingURL=document.d.ts.map

package/dist/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAID;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAW1D"}

package/dist/document.js

@@ -0,0 +1,47 @@
+import { stripBoilerplate } from "./style.js";
+const FRONT_MATTER = /^?---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+/**
+ * Prepares a source document for chunking: lifts front matter into metadata the index can use,
+ * and drops site boilerplate. Prose is left alone — the index matches on it.
+ */
+export function cleanDocument(raw) {
+    const match = FRONT_MATTER.exec(raw);
+    const body = stripBoilerplate(match === null ? raw : raw.slice(match[0].length)).trim();
+    if (match?.[1] === undefined)
+        return { text: body, tags: [] };
+    const meta = parseFrontMatter(match[1]);
+    return {
+        text: body,
+        ...(meta.title === undefined ? {} : { title: meta.title }),
+        tags: meta.tags,
+    };
+}
+/**
+ * Reads the two front matter fields worth indexing. This is deliberately not a YAML parser:
+ * anything more complex is not metadata a retrieval index can use.
+ */
+function parseFrontMatter(block) {
+    let title;
+    const tags = [];
+    for (const line of block.split("\n")) {
+        const entry = /^\s*([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(line);
+        if (entry?.[1] === undefined || entry[2] === undefined)
+            continue;
+        const key = entry[1].toLowerCase();
+        const value = entry[2].trim().replace(/^["']|["']$/g, "");
+        if (key === "title" && value.length > 0)
+            title = value;
+        if ((key === "tags" || key === "keywords") && value.startsWith("[")) {
+            tags.push(...splitList(value));
+        }
+    }
+    return { ...(title === undefined ? {} : { title }), tags };
+}
+function splitList(value) {
+    return value
+        .replace(/^\[|\]$/g, "")
+        .split(",")
+        .map((item) => item.trim().replace(/^["']|["']$/g, ""))
+        .filter((item) => item.length > 0);
+}
+//# sourceMappingURL=document.js.map

package/dist/document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.js","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAU9C,MAAM,YAAY,GAAG,qCAAqC,CAAC;AAE3D;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,gBAAgB,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACxF,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IAE9D,MAAM,IAAI,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACxC,OAAO;QACL,IAAI,EAAE,IAAI;QACV,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;QAC1D,IAAI,EAAE,IAAI,CAAC,IAAI;KAChB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,gBAAgB,CAAC,KAAa;IACrC,IAAI,KAAyB,CAAC;IAC9B,MAAM,IAAI,GAAa,EAAE,CAAC;IAE1B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,mCAAmC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7D,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS;YAAE,SAAS;QAEjE,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QACnC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;QAC1D,IAAI,GAAG,KAAK,OAAO,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,KAAK,GAAG,KAAK,CAAC;QACvD,IAAI,CAAC,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,UAAU,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACpE,IAAI,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED,OAAO,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC;AAC7D,CAAC;AAED,SAAS,SAAS,CAAC,KAAa;IAC9B,OAAO,KAAK;SACT,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;SACtD,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACvC,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+/** An error with a message safe to show to the user, plus an optional next step. */
+export declare class DocspackError extends Error {
+    readonly hint: string | undefined;
+    constructor(message: string, options?: {
+        hint?: string;
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAK9E"}

package/dist/errors.js

@@ -0,0 +1,10 @@
+/** An error with a message safe to show to the user, plus an optional next step. */
+export class DocspackError extends Error {
+    hint;
+    constructor(message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "DocspackError";
+        this.hint = options.hint;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,IAAI,CAAqB;IAElC,YAAY,OAAe,EAAE,UAA8C,EAAE;QAC3E,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;CACF"}

package/dist/exports.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The names a package declares, read statically from its type declarations.
+ *
+ * Importing the package and reading its keys would be more accurate and would execute
+ * third-party code, which is not acceptable for a check that runs over every dependency.
+ */
+export interface ExportSurface {
+    readonly name: string;
+    readonly version: string;
+    /** Every identifier declared anywhere in the package's `.d.ts` files. */
+    readonly names: ReadonlySet<string>;
+    readonly files: number;
+}
+/**
+ * Reads every `.d.ts` in an installed package. Reading all of them rather than following the
+ * entry points is deliberate: a wider set of known names means fewer false accusations, which
+ * matters more here than catching every last rename.
+ */
+export declare function readExportSurface(dir: string): Promise<ExportSurface | undefined>;
+//# sourceMappingURL=exports.d.ts.map

package/dist/exports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exports.d.ts","sourceRoot":"","sources":["../src/exports.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAaD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CA4BvF"}