@macrulez/devtoolz 0.1.0

package/dist/commands/exports-doctor/parse.d.ts

@@ -0,0 +1,20 @@
+export interface DeclaredPath {
+    /** e.g. 'main', 'bin.devtoolz', 'exports["./cdn"].types' */
+    location: string;
+    /** as written in package.json, e.g. './dist/index.js' */
+    path: string;
+    /**
+     * True when this entry came from inside a real conditions object (e.g.
+     * `{ import: ..., require: ... }`), where a missing `types` sibling is a
+     * genuine gap. False for a bare string/array subpath value, where there
+     * are no siblings at all and TypeScript falls back to a colocated
+     * `.d.ts` file instead — flagging those as "types missing" would be a
+     * false positive.
+     */
+    isConditionEntry: boolean;
+}
+export declare function collectDeclaredPaths(pkg: Record<string, unknown>): DeclaredPath[];
+/** `location`s that name a `bin` entry — these additionally need a shebang. */
+export declare function isBinLocation(location: string): boolean;
+/** `location`s that are the `types`/`typings` half of a pair — see core.ts's types-vs-runtime check. */
+export declare function isTypesLocation(location: string): boolean;

package/dist/commands/exports-doctor/parse.js

@@ -0,0 +1,80 @@
+// Enumerates every file path `package.json` declares — main/module/types/
+// typings/bin/exports — each tagged with WHERE it came from (e.g.
+// `exports["./cdn"].types`), so a finding can point at the exact field to
+// fix, not just "package.json is wrong somewhere".
+function isConditionsObject(value) {
+    // An `exports` value is either a subpaths map (every key starts with
+    // '.') or a conditions map for the implicit '.' entry (keys are
+    // condition names like import/require/types/default/node/browser,
+    // none starting with '.') — same heuristic Node/bundlers use.
+    const keys = Object.keys(value);
+    return keys.length > 0 && keys.every((k) => !k.startsWith('.'));
+}
+function walkExportsValue(value, exportsKey, conditionPath, out) {
+    if (typeof value === 'string') {
+        const suffix = conditionPath.length > 0 ? `.${conditionPath.join('.')}` : '';
+        out.push({
+            location: `exports["${exportsKey}"]${suffix}`,
+            path: value,
+            isConditionEntry: conditionPath.length > 0,
+        });
+    }
+    else if (Array.isArray(value)) {
+        // A fallback array — any entry could be the one actually picked at
+        // runtime depending on the consumer's environment, so all are checked.
+        for (const entry of value)
+            walkExportsValue(entry, exportsKey, conditionPath, out);
+    }
+    else if (value && typeof value === 'object') {
+        for (const [key, nested] of Object.entries(value)) {
+            walkExportsValue(nested, exportsKey, [...conditionPath, key], out);
+        }
+    }
+}
+function collectExportsPaths(exportsField) {
+    const out = [];
+    if (typeof exportsField === 'string') {
+        out.push({ location: 'exports', path: exportsField, isConditionEntry: false });
+        return out;
+    }
+    if (!exportsField || typeof exportsField !== 'object')
+        return out;
+    if (isConditionsObject(exportsField)) {
+        walkExportsValue(exportsField, '.', [], out);
+    }
+    else {
+        for (const [subpath, value] of Object.entries(exportsField)) {
+            walkExportsValue(value, subpath, [], out);
+        }
+    }
+    return out;
+}
+function collectBinPaths(binField) {
+    if (typeof binField === 'string')
+        return [{ location: 'bin', path: binField, isConditionEntry: false }];
+    if (binField && typeof binField === 'object') {
+        return Object.entries(binField)
+            .filter((entry) => typeof entry[1] === 'string')
+            .map(([name, path]) => ({ location: `bin.${name}`, path, isConditionEntry: false }));
+    }
+    return [];
+}
+export function collectDeclaredPaths(pkg) {
+    const out = [];
+    for (const field of ['main', 'module', 'types', 'typings']) {
+        if (typeof pkg[field] === 'string')
+            out.push({ location: field, path: pkg[field], isConditionEntry: false });
+    }
+    out.push(...collectBinPaths(pkg.bin));
+    out.push(...collectExportsPaths(pkg.exports));
+    return out;
+}
+/** `location`s that name a `bin` entry — these additionally need a shebang. */
+export function isBinLocation(location) {
+    return location === 'bin' || location.startsWith('bin.');
+}
+/** `location`s that are the `types`/`typings` half of a pair — see core.ts's types-vs-runtime check. */
+export function isTypesLocation(location) {
+    return location === 'types' || location === 'typings' || location.endsWith('.types');
+}
+//# sourceMappingURL=parse.js.map

package/dist/commands/exports-doctor/parse.js.map

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

package/dist/commands/exports-doctor/report.d.ts

@@ -0,0 +1,3 @@
+import { type VibesOptions } from '../../format/vibes.js';
+import type { ExportsDoctorReport } from './run.js';
+export declare function renderExportsDoctorReport(report: ExportsDoctorReport, options?: VibesOptions): string;

package/dist/commands/exports-doctor/report.js

@@ -0,0 +1,36 @@
+import { banner, cleanCelebration } from '../../format/vibes.js';
+import { formatFindingsRows } from '../../format/findings-list.js';
+const KIND_LABEL = {
+    missing: () => 'file does not exist',
+    'case-mismatch': (_path, realPath) => `wrong case — real path is ${realPath}`,
+    'missing-shebang': () => "missing '#!/usr/bin/env node' — won't run as a bin",
+    'types-missing': () => 'runtime resolves fine, but no types declared for this entry at all',
+};
+export function renderExportsDoctorReport(report, options = {}) {
+    if (report.error) {
+        const lines = [];
+        if (!options.quiet && !options.plain)
+            lines.push(banner(), '');
+        lines.push(`Could not read package.json: ${report.error}`);
+        return lines.join('\n');
+    }
+    const isClean = report.findings.length === 0;
+    if (options.quiet && isClean)
+        return '';
+    const lines = [];
+    if (!options.quiet && !options.plain)
+        lines.push(banner(), '');
+    lines.push(`Checked ${report.packageName ?? 'this package'}'s declared exports.`, '');
+    if (isClean) {
+        lines.push(cleanCelebration(options));
+        return lines.join('\n');
+    }
+    lines.push(`${report.findings.length} problem${report.findings.length === 1 ? '' : 's'} found:`);
+    lines.push(...formatFindingsRows(report.findings.map((f) => ({
+        location: f.location,
+        name: f.path,
+        tag: KIND_LABEL[f.kind]?.(f.path, f.realPath) ?? f.kind,
+    })), options));
+    return lines.join('\n');
+}
+//# sourceMappingURL=report.js.map

package/dist/commands/exports-doctor/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../src/commands/exports-doctor/report.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAqB,MAAM,uBAAuB,CAAA;AACnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAA;AAGlE,MAAM,UAAU,GAAgE;IAC9E,OAAO,EAAE,GAAG,EAAE,CAAC,qBAAqB;IACpC,eAAe,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,CAAC,6BAA6B,QAAQ,EAAE;IAC7E,iBAAiB,EAAE,GAAG,EAAE,CAAC,oDAAoD;IAC7E,eAAe,EAAE,GAAG,EAAE,CAAC,oEAAoE;CAC5F,CAAA;AAED,MAAM,UAAU,yBAAyB,CACvC,MAA2B,EAC3B,UAAwB,EAAE;IAE1B,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,MAAM,KAAK,GAAa,EAAE,CAAA;QAC1B,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,KAAK;YAAE,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,CAAC,CAAA;QAC9D,KAAK,CAAC,IAAI,CAAC,gCAAgC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAA;QAC1D,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACzB,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAA;IAC5C,IAAI,OAAO,CAAC,KAAK,IAAI,OAAO;QAAE,OAAO,EAAE,CAAA;IAEvC,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,CAAC,CAAA;IAE9D,KAAK,CAAC,IAAI,CAAC,WAAW,MAAM,CAAC,WAAW,IAAI,cAAc,sBAAsB,EAAE,EAAE,CAAC,CAAA;IAErF,IAAI,OAAO,EAAE,CAAC;QACZ,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAA;QACrC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACzB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,WAAW,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAA;IAChG,KAAK,CAAC,IAAI,CACR,GAAG,kBAAkB,CACnB,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC1B,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI;KACxD,CAAC,CAAC,EACH,OAAO,CACR,CACF,CAAA;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC"}

package/dist/commands/exports-doctor/resolve-path.d.ts

@@ -0,0 +1,10 @@
+export type PathCheckResult = {
+    status: 'ok';
+} | {
+    status: 'missing';
+} | {
+    status: 'case-mismatch';
+    realPath: string;
+};
+export declare function checkDeclaredPath(packageDir: string, declaredPath: string): PathCheckResult;
+export declare function resolveDeclaredPath(packageDir: string, declaredPath: string): string;

package/dist/commands/exports-doctor/resolve-path.js

@@ -0,0 +1,46 @@
+// Checks one declared path against what's REALLY on disk, segment by
+// segment, via `readdirSync` — same discipline as case-check, but here a
+// missing file is the PRIMARY thing being looked for (case-check treats
+// "doesn't resolve at all" as out of scope; here it's the main case),
+// so the result is three-way instead of a plain yes/no.
+import { readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+export function checkDeclaredPath(packageDir, declaredPath) {
+    const segments = declaredPath
+        .replace(/^\.\//, '')
+        .split('/')
+        .filter((s) => s.length > 0);
+    if (segments.length === 0)
+        return { status: 'missing' };
+    let currentDir = packageDir;
+    const corrected = [];
+    let hasMismatch = false;
+    for (const segment of segments) {
+        let entries;
+        try {
+            entries = readdirSync(currentDir);
+        }
+        catch {
+            return { status: 'missing' };
+        }
+        if (entries.includes(segment)) {
+            corrected.push(segment);
+        }
+        else {
+            const lower = segment.toLowerCase();
+            const match = entries.find((e) => e.toLowerCase() === lower);
+            if (!match)
+                return { status: 'missing' };
+            hasMismatch = true;
+            corrected.push(match);
+        }
+        currentDir = join(currentDir, corrected[corrected.length - 1]);
+    }
+    if (hasMismatch)
+        return { status: 'case-mismatch', realPath: `./${corrected.join('/')}` };
+    return { status: 'ok' };
+}
+export function resolveDeclaredPath(packageDir, declaredPath) {
+    return resolve(packageDir, declaredPath);
+}
+//# sourceMappingURL=resolve-path.js.map

package/dist/commands/exports-doctor/resolve-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-path.js","sourceRoot":"","sources":["../../../src/commands/exports-doctor/resolve-path.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,yEAAyE;AACzE,wEAAwE;AACxE,sEAAsE;AACtE,wDAAwD;AAExD,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACrC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAKzC,MAAM,UAAU,iBAAiB,CAAC,UAAkB,EAAE,YAAoB;IACxE,MAAM,QAAQ,GAAG,YAAY;SAC1B,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;SACpB,KAAK,CAAC,GAAG,CAAC;SACV,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC9B,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAA;IAEvD,IAAI,UAAU,GAAG,UAAU,CAAA;IAC3B,MAAM,SAAS,GAAa,EAAE,CAAA;IAC9B,IAAI,WAAW,GAAG,KAAK,CAAA;IAEvB,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAiB,CAAA;QACrB,IAAI,CAAC;YACH,OAAO,GAAG,WAAW,CAAC,UAAU,CAAC,CAAA;QACnC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAA;QAC9B,CAAC;QAED,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9B,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QACzB,CAAC;aAAM,CAAC;YACN,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAA;YACnC,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC,CAAA;YAC5D,IAAI,CAAC,KAAK;gBAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAA;YACxC,WAAW,GAAG,IAAI,CAAA;YAClB,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACvB,CAAC;QACD,UAAU,GAAG,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAW,CAAC,CAAA;IAC1E,CAAC;IAED,IAAI,WAAW;QAAE,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,QAAQ,EAAE,KAAK,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAA;IACzF,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAA;AACzB,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,UAAkB,EAAE,YAAoB;IAC1E,OAAO,OAAO,CAAC,UAAU,EAAE,YAAY,CAAC,CAAA;AAC1C,CAAC"}

package/dist/commands/exports-doctor/run.d.ts

@@ -0,0 +1,13 @@
+import { type ExportsDoctorFinding } from './core.js';
+export interface ExportsDoctorRunOptions {
+    /** package directory to check */
+    dir: string;
+}
+export interface ExportsDoctorReport {
+    packageName: string | null;
+    findings: ExportsDoctorFinding[];
+    /** package.json couldn't be read/parsed at all — a different kind of problem than any single finding */
+    error: string | null;
+    exitCode: number;
+}
+export declare function runExportsDoctor(options: ExportsDoctorRunOptions): ExportsDoctorReport;

package/dist/commands/exports-doctor/run.js

@@ -0,0 +1,25 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { checkPackage } from './core.js';
+export function runExportsDoctor(options) {
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(join(options.dir, 'package.json'), 'utf8'));
+    }
+    catch (err) {
+        return {
+            packageName: null,
+            findings: [],
+            error: err instanceof Error ? err.message : String(err),
+            exitCode: 1,
+        };
+    }
+    const result = checkPackage(pkg, options.dir);
+    return {
+        packageName: result.packageName,
+        findings: result.findings,
+        error: null,
+        exitCode: result.findings.length > 0 ? 1 : 0,
+    };
+}
+//# sourceMappingURL=run.js.map

package/dist/commands/exports-doctor/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../../src/commands/exports-doctor/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,YAAY,EAA6B,MAAM,WAAW,CAAA;AAenE,MAAM,UAAU,gBAAgB,CAAC,OAAgC;IAC/D,IAAI,GAA4B,CAAA;IAChC,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAGvE,CAAA;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,WAAW,EAAE,IAAI;YACjB,QAAQ,EAAE,EAAE;YACZ,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;YACvD,QAAQ,EAAE,CAAC;SACZ,CAAA;IACH,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAA;IAE7C,OAAO;QACL,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,KAAK,EAAE,IAAI;QACX,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KAC7C,CAAA;AACH,CAAC"}

package/dist/commands/readme-check/core.d.ts

@@ -0,0 +1,22 @@
+import type ts from 'typescript';
+export interface ReadmeCheckFinding {
+    file: string;
+    /** 1-based, real line in the markdown file */
+    line: number;
+    /** 1-based column */
+    column: number;
+    message: string;
+    lang: string;
+}
+export interface ReadmeCheckFileResult {
+    file: string;
+    blocksChecked: number;
+    blocksSkipped: number;
+    findings: ReadmeCheckFinding[];
+}
+/**
+ * Each block is typechecked in isolation — never accumulated with other
+ * blocks in the same file. See `isNoise` above for what that isolation
+ * costs and how it's mitigated.
+ */
+export declare function checkMarkdownFile(file: string, markdown: string, packageDir: string, compilerOptions: ts.CompilerOptions, langs: string[]): ReadmeCheckFileResult;

package/dist/commands/readme-check/core.js

@@ -0,0 +1,92 @@
+import { extractCodeBlocks } from './extract.js';
+import { typecheckBlock } from './typecheck.js';
+// "Cannot find name" (2304) and its "did you mean" variant (2552) — a doc
+// snippet is routinely a FRAGMENT that assumes a variable set up in
+// surrounding prose or an earlier, unrelated block ("inside your
+// component:", "given a `router` instance, ..."). Checking each block in
+// isolation (see below) can't tell that apart from a genuinely wrong
+// example, so it doesn't try — these codes are dropped rather than
+// reported as unreliable noise. Concatenating blocks together to give
+// them shared context was tried and reverted: real dogfooding against
+// every README in this workspace showed it trades this false-positive
+// class for a WORSE one (two independent, alternative examples that
+// happen to reuse a name like `toast`/`useForm` read as "Cannot redeclare
+// block-scoped variable" — an alarming false bug report, not an obvious
+// tool limitation the way "Cannot find name" reads).
+//
+// "X is declared but its value is never read" (6133) — a doc snippet
+// routinely defines a handler function that's wired up somewhere NOT
+// shown in the fenced block (a template's `@click`, an event listener
+// registered elsewhere in prose) — real dogfooding hit this exact shape
+// in vue-toast-kit's README (`function deleteFile(id) { ... }`, never
+// called within its own isolated block). Also fires as a pure cascade of
+// an already-suppressed 2304/2307 upstream (an unresolvable import
+// leaves nothing to meaningfully call the declaration "unused" against).
+const SUPPRESSED_CODES = new Set([2304, 2552, 6133]);
+// "Cannot find module './X'" (2307) for a RELATIVE specifier is almost
+// always a hypothetical file in the reader's own project ("your
+// App.vue"), not something that could ever exist in this package — not
+// checkable, so not reported. A BARE specifier (the package's own name,
+// or one of its subpath exports) is kept: that's the one historically
+// valuable case this command exists for (vue-image-kit's /cdn export
+// resolving to nothing at runtime while nobody noticed).
+const MODULE_NOT_FOUND_CODE = 2307;
+const RELATIVE_MODULE_RE = /Cannot find module '(\.\.?\/[^']*)'/;
+// A DIFFERENT code (2792, not 2307) for the case where the package's own
+// dev tsconfig doesn't set `moduleResolution: bundler/node16/nodenext` at
+// all — self-referencing its own name can never resolve there regardless
+// of what the README says, and TypeScript's message says so explicitly
+// ("Did you mean to set the 'moduleResolution' option..."). That's how
+// this is told apart from a genuine bad specifier under a properly
+// bundler-configured tsconfig (plain 2307, no such suffix) — the real
+// vue-state-machine bug this command caught: its README's code examples
+// still imported the unscoped `vue-state-machine` in five places after a
+// scope-prefix fix elsewhere had already landed.
+const UNSUPPORTED_RESOLUTION_CODE = 2792;
+function isNoise(message, code) {
+    if (SUPPRESSED_CODES.has(code))
+        return true;
+    if (code === MODULE_NOT_FOUND_CODE && RELATIVE_MODULE_RE.test(message))
+        return true;
+    if (code === UNSUPPORTED_RESOLUTION_CODE)
+        return true;
+    return false;
+}
+/**
+ * Each block is typechecked in isolation — never accumulated with other
+ * blocks in the same file. See `isNoise` above for what that isolation
+ * costs and how it's mitigated.
+ */
+export function checkMarkdownFile(file, markdown, packageDir, compilerOptions, langs) {
+    const blocks = extractCodeBlocks(markdown);
+    const findings = [];
+    let blocksChecked = 0;
+    let blocksSkipped = 0;
+    for (const block of blocks) {
+        if (block.noCheck || !langs.includes(block.lang)) {
+            blocksSkipped++;
+            continue;
+        }
+        const diagnostics = typecheckBlock(block.code, block.lang, packageDir, compilerOptions);
+        if (diagnostics === null) {
+            blocksSkipped++;
+            continue;
+        }
+        blocksChecked++;
+        for (const d of diagnostics) {
+            if (d.category !== 'error')
+                continue;
+            if (isNoise(d.message, d.code))
+                continue;
+            findings.push({
+                file,
+                line: block.startLine + d.line,
+                column: d.character + 1,
+                message: d.message,
+                lang: block.lang,
+            });
+        }
+    }
+    return { file, blocksChecked, blocksSkipped, findings };
+}
+//# sourceMappingURL=core.js.map

package/dist/commands/readme-check/core.js.map

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

package/dist/commands/readme-check/extract.d.ts

@@ -0,0 +1,9 @@
+export interface CodeBlock {
+    lang: string;
+    /** 1-based line number of the first line of code, in the ORIGINAL markdown file */
+    startLine: number;
+    code: string;
+    /** an explicit `no-check` word in the fence's info string opts a block out */
+    noCheck: boolean;
+}
+export declare function extractCodeBlocks(markdown: string): CodeBlock[];

package/dist/commands/readme-check/extract.js

@@ -0,0 +1,48 @@
+// Extracts fenced code blocks from a markdown file, tracking the block's
+// language tag and the real 1-based line number where its content starts
+// (right after the opening fence), so a typecheck error inside the block
+// can be reported at the exact markdown line, not an offset into a
+// throwaway virtual file.
+const FENCE_START = /^(\s*)([`~]{3,})(.*)$/;
+export function extractCodeBlocks(markdown) {
+    const lines = markdown.split(/\r\n|\r|\n/);
+    const blocks = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        const openMatch = FENCE_START.exec(line);
+        if (!openMatch) {
+            i++;
+            continue;
+        }
+        const fenceChars = openMatch[2];
+        const fenceChar = fenceChars[0];
+        const fenceLen = fenceChars.length;
+        const info = openMatch[3].trim();
+        const infoWords = info.split(/\s+/).filter(Boolean);
+        const lang = (infoWords[0] ?? '').toLowerCase();
+        const noCheck = infoWords.slice(1).includes('no-check');
+        // A closing fence must use the same character and be at least as long
+        // — a shorter run of the same character inside the block is literal
+        // content, not a close (standard GFM fence-length rule).
+        const closeRe = new RegExp(`^\\s*${fenceChar === '`' ? '`' : '~'}{${fenceLen},}\\s*$`);
+        let j = i + 1;
+        while (j < lines.length && !closeRe.test(lines[j]))
+            j++;
+        if (j >= lines.length) {
+            // Unterminated fence — malformed markdown, nothing sensible to
+            // extract; stop treating the rest of the file as inside this block.
+            i++;
+            continue;
+        }
+        blocks.push({
+            lang,
+            startLine: i + 2,
+            code: lines.slice(i + 1, j).join('\n'),
+            noCheck,
+        });
+        i = j + 1;
+    }
+    return blocks;
+}
+//# sourceMappingURL=extract.js.map

package/dist/commands/readme-check/extract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.js","sourceRoot":"","sources":["../../../src/commands/readme-check/extract.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,yEAAyE;AACzE,yEAAyE;AACzE,mEAAmE;AACnE,0BAA0B;AAW1B,MAAM,WAAW,GAAG,uBAAuB,CAAA;AAE3C,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC,CAAA;IAC1C,MAAM,MAAM,GAAgB,EAAE,CAAA;IAC9B,IAAI,CAAC,GAAG,CAAC,CAAA;IAET,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAW,CAAA;QAC/B,MAAM,SAAS,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACxC,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,CAAC,EAAE,CAAA;YACH,SAAQ;QACV,CAAC;QAED,MAAM,UAAU,GAAG,SAAS,CAAC,CAAC,CAAW,CAAA;QACzC,MAAM,SAAS,GAAG,UAAU,CAAC,CAAC,CAAW,CAAA;QACzC,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAA;QAClC,MAAM,IAAI,GAAI,SAAS,CAAC,CAAC,CAAY,CAAC,IAAI,EAAE,CAAA;QAC5C,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;QACnD,MAAM,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAA;QAC/C,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAA;QAEvD,sEAAsE;QACtE,oEAAoE;QACpE,yDAAyD;QACzD,MAAM,OAAO,GAAG,IAAI,MAAM,CAAC,QAAQ,SAAS,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,QAAQ,SAAS,CAAC,CAAA;QACtF,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACb,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAW,CAAC;YAAE,CAAC,EAAE,CAAA;QAEjE,IAAI,CAAC,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YACtB,+DAA+D;YAC/D,oEAAoE;YACpE,CAAC,EAAE,CAAA;YACH,SAAQ;QACV,CAAC;QAED,MAAM,CAAC,IAAI,CAAC;YACV,IAAI;YACJ,SAAS,EAAE,CAAC,GAAG,CAAC;YAChB,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;YACtC,OAAO;SACR,CAAC,CAAA;QACF,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACX,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/commands/readme-check/lang.d.ts

@@ -0,0 +1,8 @@
+import ts from 'typescript';
+export interface LangInfo {
+    scriptKind: ts.ScriptKind;
+    extension: string;
+    needsAllowJs: boolean;
+}
+export declare function resolveLangInfo(lang: string): LangInfo | null;
+export declare const DEFAULT_LANGS: string[];

package/dist/commands/readme-check/lang.js

@@ -0,0 +1,21 @@
+import ts from 'typescript';
+const LANG_MAP = {
+    ts: { scriptKind: ts.ScriptKind.TS, extension: '.ts', needsAllowJs: false },
+    typescript: { scriptKind: ts.ScriptKind.TS, extension: '.ts', needsAllowJs: false },
+    tsx: { scriptKind: ts.ScriptKind.TSX, extension: '.tsx', needsAllowJs: false },
+    js: { scriptKind: ts.ScriptKind.JS, extension: '.js', needsAllowJs: true },
+    javascript: { scriptKind: ts.ScriptKind.JS, extension: '.js', needsAllowJs: true },
+    jsx: { scriptKind: ts.ScriptKind.JSX, extension: '.jsx', needsAllowJs: true },
+};
+export function resolveLangInfo(lang) {
+    return LANG_MAP[lang] ?? null;
+}
+// tsx is deliberately NOT in the default set — real-world dogfooding
+// against every package in this workspace showed EVERY tsx block failing
+// universally with "Cannot use JSX unless the '--jsx' flag is provided"
+// (Vue packages don't configure JSX/React types, since the block is
+// illustrative "if you're in a React app" pseudocode, not code this
+// package could ever compile). Opt in explicitly with `--lang ts,tsx` for
+// a package that actually configures JSX in its own tsconfig.
+export const DEFAULT_LANGS = ['ts'];
+//# sourceMappingURL=lang.js.map

package/dist/commands/readme-check/lang.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lang.js","sourceRoot":"","sources":["../../../src/commands/readme-check/lang.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAA;AAQ3B,MAAM,QAAQ,GAA6B;IACzC,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE;IAC3E,UAAU,EAAE,EAAE,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE;IACnF,GAAG,EAAE,EAAE,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE;IAC9E,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE;IAC1E,UAAU,EAAE,EAAE,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE;IAClF,GAAG,EAAE,EAAE,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE;CAC9E,CAAA;AAED,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAA;AAC/B,CAAC;AAED,qEAAqE;AACrE,yEAAyE;AACzE,wEAAwE;AACxE,oEAAoE;AACpE,oEAAoE;AACpE,0EAA0E;AAC1E,8DAA8D;AAC9D,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAI,CAAC,CAAA"}

package/dist/commands/readme-check/report.d.ts

@@ -0,0 +1,3 @@
+import { type VibesOptions } from '../../format/vibes.js';
+import type { ReadmeCheckReport } from './run.js';
+export declare function renderReadmeCheckReport(report: ReadmeCheckReport, options?: VibesOptions): string;

package/dist/commands/readme-check/report.js

@@ -0,0 +1,31 @@
+import { banner, cleanCelebration } from '../../format/vibes.js';
+import { formatFindingsRows } from '../../format/findings-list.js';
+export function renderReadmeCheckReport(report, options = {}) {
+    if (report.error) {
+        const lines = [];
+        if (!options.quiet && !options.plain)
+            lines.push(banner(), '');
+        lines.push(`Could not run readme-check: ${report.error}`);
+        return lines.join('\n');
+    }
+    const blocksChecked = report.fileResults.reduce((sum, f) => sum + f.blocksChecked, 0);
+    const isClean = report.findings.length === 0;
+    if (options.quiet && isClean)
+        return '';
+    const lines = [];
+    if (!options.quiet && !options.plain)
+        lines.push(banner(), '');
+    lines.push(`Typechecked ${blocksChecked} code block${blocksChecked === 1 ? '' : 's'} across ${report.fileResults.length} file${report.fileResults.length === 1 ? '' : 's'}.`, '');
+    if (isClean) {
+        lines.push(cleanCelebration(options));
+        return lines.join('\n');
+    }
+    lines.push(`${report.findings.length} problem${report.findings.length === 1 ? '' : 's'} found:`);
+    lines.push(...formatFindingsRows(report.findings.map((f) => ({
+        location: `${f.file}:${f.line}:${f.column}`,
+        name: f.lang,
+        tag: f.message,
+    })), options));
+    return lines.join('\n');
+}
+//# sourceMappingURL=report.js.map

package/dist/commands/readme-check/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../src/commands/readme-check/report.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAqB,MAAM,uBAAuB,CAAA;AACnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAA;AAGlE,MAAM,UAAU,uBAAuB,CACrC,MAAyB,EACzB,UAAwB,EAAE;IAE1B,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,MAAM,KAAK,GAAa,EAAE,CAAA;QAC1B,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,KAAK;YAAE,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,CAAC,CAAA;QAC9D,KAAK,CAAC,IAAI,CAAC,+BAA+B,MAAM,CAAC,KAAK,EAAE,CAAC,CAAA;QACzD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACzB,CAAC;IAED,MAAM,aAAa,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,CAAA;IACrF,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAA;IAC5C,IAAI,OAAO,CAAC,KAAK,IAAI,OAAO;QAAE,OAAO,EAAE,CAAA;IAEvC,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,CAAC,CAAA;IAE9D,KAAK,CAAC,IAAI,CACR,eAAe,aAAa,cAAc,aAAa,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,WAAW,MAAM,CAAC,WAAW,CAAC,MAAM,QAAQ,MAAM,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,EACjK,EAAE,CACH,CAAA;IAED,IAAI,OAAO,EAAE,CAAC;QACZ,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAA;QACrC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACzB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,WAAW,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAA;IAChG,KAAK,CAAC,IAAI,CACR,GAAG,kBAAkB,CACnB,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC1B,QAAQ,EAAE,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,EAAE;QAC3C,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,GAAG,EAAE,CAAC,CAAC,OAAO;KACf,CAAC,CAAC,EACH,OAAO,CACR,CACF,CAAA;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC"}

package/dist/commands/readme-check/run.d.ts

@@ -0,0 +1,19 @@
+import { type ReadmeCheckFinding, type ReadmeCheckFileResult } from './core.js';
+export interface ReadmeCheckRunOptions {
+    /** package directory to check against */
+    dir: string;
+    /** markdown files to check, relative to `dir` — default: ['README.md'] */
+    files?: string[];
+    /** fenced-block languages to typecheck — default: ['ts', 'tsx'] */
+    langs?: string[];
+    /** tsconfig.json path, relative to `dir` — auto-detected by default */
+    tsconfig?: string;
+}
+export interface ReadmeCheckReport {
+    fileResults: ReadmeCheckFileResult[];
+    findings: ReadmeCheckFinding[];
+    /** couldn't load a tsconfig or read a target file at all — a different kind of problem than any single finding */
+    error: string | null;
+    exitCode: number;
+}
+export declare function runReadmeCheck(options: ReadmeCheckRunOptions): ReadmeCheckReport;

package/dist/commands/readme-check/run.js

@@ -0,0 +1,34 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { checkMarkdownFile } from './core.js';
+import { loadCompilerOptions } from './tsconfig.js';
+import { DEFAULT_LANGS } from './lang.js';
+export function runReadmeCheck(options) {
+    const packageDir = resolve(options.dir);
+    const targetFiles = options.files && options.files.length > 0 ? options.files : ['README.md'];
+    const langs = options.langs && options.langs.length > 0 ? options.langs : DEFAULT_LANGS;
+    const loaded = loadCompilerOptions(packageDir, options.tsconfig);
+    if ('error' in loaded) {
+        return { fileResults: [], findings: [], error: loaded.error, exitCode: 1 };
+    }
+    const fileResults = [];
+    for (const relFile of targetFiles) {
+        const absPath = resolve(packageDir, relFile);
+        let markdown;
+        try {
+            markdown = readFileSync(absPath, 'utf8');
+        }
+        catch (err) {
+            return {
+                fileResults: [],
+                findings: [],
+                error: `could not read ${relFile}: ${err instanceof Error ? err.message : String(err)}`,
+                exitCode: 1,
+            };
+        }
+        fileResults.push(checkMarkdownFile(relFile, markdown, packageDir, loaded.options, langs));
+    }
+    const findings = fileResults.flatMap((f) => f.findings);
+    return { fileResults, findings, error: null, exitCode: findings.length > 0 ? 1 : 0 };
+}
+//# sourceMappingURL=run.js.map

package/dist/commands/readme-check/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../../src/commands/readme-check/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,iBAAiB,EAAuD,MAAM,WAAW,CAAA;AAClG,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAqBzC,MAAM,UAAU,cAAc,CAAC,OAA8B;IAC3D,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IACvC,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAA;IAC7F,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,CAAA;IAEvF,MAAM,MAAM,GAAG,mBAAmB,CAAC,UAAU,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;IAChE,IAAI,OAAO,IAAI,MAAM,EAAE,CAAC;QACtB,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAA;IAC5E,CAAC;IAED,MAAM,WAAW,GAA4B,EAAE,CAAA;IAC/C,KAAK,MAAM,OAAO,IAAI,WAAW,EAAE,CAAC;QAClC,MAAM,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,CAAA;QAC5C,IAAI,QAAgB,CAAA;QACpB,IAAI,CAAC;YACH,QAAQ,GAAG,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;QAC1C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,WAAW,EAAE,EAAE;gBACf,QAAQ,EAAE,EAAE;gBACZ,KAAK,EAAE,kBAAkB,OAAO,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;gBACvF,QAAQ,EAAE,CAAC;aACZ,CAAA;QACH,CAAC;QACD,WAAW,CAAC,IAAI,CAAC,iBAAiB,CAAC,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAA;IAC3F,CAAC;IAED,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;IACvD,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;AACtF,CAAC"}

package/dist/commands/readme-check/tsconfig.d.ts

@@ -0,0 +1,9 @@
+import ts from 'typescript';
+export interface LoadedCompilerOptions {
+    options: ts.CompilerOptions;
+    configPath: string;
+}
+export type LoadCompilerOptionsResult = LoadedCompilerOptions | {
+    error: string;
+};
+export declare function loadCompilerOptions(packageDir: string, tsconfigOverride?: string): LoadCompilerOptionsResult;

package/dist/commands/readme-check/tsconfig.js

@@ -0,0 +1,26 @@
+import ts from 'typescript';
+import { dirname, resolve } from 'node:path';
+export function loadCompilerOptions(packageDir, tsconfigOverride) {
+    const configPath = tsconfigOverride
+        ? resolve(packageDir, tsconfigOverride)
+        : ts.findConfigFile(packageDir, ts.sys.fileExists, 'tsconfig.json');
+    if (!configPath || !ts.sys.fileExists(configPath)) {
+        return {
+            error: `no tsconfig.json found under ${packageDir} — nothing to typecheck README code blocks against`,
+        };
+    }
+    const read = ts.readConfigFile(configPath, ts.sys.readFile);
+    if (read.error) {
+        return { error: ts.flattenDiagnosticMessageText(read.error.messageText, '\n') };
+    }
+    const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, dirname(configPath));
+    if (parsed.errors.length > 0) {
+        return {
+            error: parsed.errors
+                .map((e) => ts.flattenDiagnosticMessageText(e.messageText, '\n'))
+                .join('\n'),
+        };
+    }
+    return { options: parsed.options, configPath };
+}
+//# sourceMappingURL=tsconfig.js.map