miniread 1.0.0

package/dist/scripts/evaluate/transform-manifest.js

@@ -0,0 +1,102 @@
+import * as fs from "node:fs/promises";
+import { haveSameIds, normalizeTransformIds, uniqueIds, } from "./transform-id-set.js";
+import { parseTransformManifest } from "./parse-transform-manifest.js";
+import { writeJsonFileAtomic } from "./write-text-file-atomic.js";
+const average = (values) => {
+    if (values.length === 0)
+        return 0;
+    let total = 0;
+    for (const value of values) {
+        total += value;
+    }
+    return total / values.length;
+};
+export const updateTransformManifestFromEvaluation = async (options) => {
+    const { manifestPath, baselineTransforms, testTransforms, reductionRatios, transformRegistry, } = options;
+    try {
+        await fs.access(manifestPath);
+    }
+    catch {
+        return {
+            updated: false,
+            message: `Skipped updating transform-manifest.json (not found at ${manifestPath})`,
+        };
+    }
+    const manifest = parseTransformManifest(await fs.readFile(manifestPath, "utf8"));
+    const existingIds = new Set(manifest.transforms.map((t) => t.id));
+    const baselineIds = normalizeTransformIds(baselineTransforms);
+    const testIds = normalizeTransformIds(testTransforms);
+    const idsToEnsure = new Set([...baselineIds, ...testIds]);
+    idsToEnsure.delete("none");
+    let maxIteration = 0;
+    for (const entry of manifest.transforms) {
+        maxIteration = Math.max(maxIteration, entry.iteration);
+    }
+    let nextIteration = maxIteration + 1;
+    let updated = false;
+    for (const transformId of idsToEnsure) {
+        if (existingIds.has(transformId))
+            continue;
+        const transform = transformRegistry[transformId];
+        const description = transform?.description ?? `Auto-added by evaluation: ${transformId}`;
+        const scope = transform?.scope ?? "file";
+        const parallelizable = transform?.parallelizable ?? true;
+        manifest.transforms.push({
+            id: transformId,
+            description,
+            iteration: nextIteration++,
+            scope,
+            parallelizable,
+            diffReductionImpact: 0,
+            enabledByDefault: false,
+            notes: "Auto-added by evaluation script.",
+        });
+        existingIds.add(transformId);
+        updated = true;
+    }
+    const isBaselineNone = baselineIds.length === 0 ||
+        (baselineTransforms.length === 1 && baselineTransforms[0] === "none");
+    if (isBaselineNone && testIds.length === 1) {
+        const transformId = testIds[0];
+        if (transformId) {
+            const measuredImpact = average(reductionRatios);
+            const entry = manifest.transforms.find((t) => t.id === transformId);
+            if (entry && entry.diffReductionImpact !== measuredImpact) {
+                entry.diffReductionImpact = measuredImpact;
+                const measurementNote = `Measured with baseline none: ${(measuredImpact * 100).toFixed(2)}%.`;
+                entry.notes = entry.notes
+                    ? `${entry.notes} ${measurementNote}`
+                    : measurementNote;
+                updated = true;
+            }
+        }
+    }
+    if (isBaselineNone) {
+        const recommendedIds = manifest.transforms
+            .filter((entry) => entry.enabledByDefault)
+            .map((entry) => entry.id);
+        const testUniqueIds = uniqueIds(testIds);
+        const recommendedUniqueIds = uniqueIds(recommendedIds);
+        if (testUniqueIds.length > 0 &&
+            haveSameIds(testUniqueIds, recommendedUniqueIds)) {
+            const measuredImpact = average(reductionRatios);
+            manifest.presetStats ??= {};
+            const existing = manifest.presetStats.recommended;
+            if (existing?.diffReductionImpact !== measuredImpact) {
+                manifest.presetStats.recommended = {
+                    diffReductionImpact: measuredImpact,
+                    notes: `Measured with baseline none: ${(measuredImpact * 100).toFixed(2)}%.`,
+                };
+                updated = true;
+            }
+        }
+    }
+    if (!updated) {
+        return {
+            updated: false,
+            message: "transform-manifest.json already up to date",
+        };
+    }
+    await writeJsonFileAtomic(manifestPath, manifest, { overwrite: true });
+    return { updated: true, message: "Updated transform-manifest.json" };
+};

package/dist/scripts/evaluate/write-evaluation-stdout.d.ts

@@ -0,0 +1,7 @@
+import type { OutputFormat } from "./create-evaluate-command.js";
+import type { EvaluationOutcome, EvaluationReport } from "./evaluation-report.js";
+export declare const writeEvaluationStdout: (options: {
+    format: OutputFormat;
+    report: EvaluationReport;
+    outcomes: EvaluationOutcome[];
+}) => void;

package/dist/scripts/evaluate/write-evaluation-stdout.js

@@ -0,0 +1,20 @@
+import { sanitizeTsvField } from "./sanitize.js";
+export const writeEvaluationStdout = (options) => {
+    const { format, report, outcomes } = options;
+    if (format === "json") {
+        process.stdout.write(JSON.stringify(report, undefined, 2) + "\n");
+        return;
+    }
+    process.stdout.write("FROM\tTO\tBASELINE_CHANGED_LINES\tTEST_CHANGED_LINES\tREDUCTION_RATIO\tSTATUS\tERROR\n");
+    for (const outcome of outcomes) {
+        if (!outcome.ok) {
+            process.stdout.write(`${outcome.pair.from}\t${outcome.pair.to}\t\t\t\tERROR\t${sanitizeTsvField(outcome.error)}\n`);
+            continue;
+        }
+        const baselineChangedLines = outcome.result.baselineDiff.addedLines +
+            outcome.result.baselineDiff.removedLines;
+        const testChangedLines = outcome.result.testDiff.addedLines + outcome.result.testDiff.removedLines;
+        const status = outcome.result.reductionRatio >= 0 ? "GOOD" : "BAD";
+        process.stdout.write(`${outcome.pair.from}\t${outcome.pair.to}\t${baselineChangedLines}\t${testChangedLines}\t${outcome.result.reductionRatio}\t${status}\t\n`);
+    }
+};

package/dist/scripts/evaluate/write-text-file-atomic.d.ts

@@ -0,0 +1,5 @@
+type WriteOutputOptions = {
+    overwrite: boolean;
+};
+export declare const writeJsonFileAtomic: (outputPath: string, value: unknown, options: WriteOutputOptions) => Promise<void>;
+export {};

package/dist/scripts/evaluate/write-text-file-atomic.js

@@ -0,0 +1,47 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs/promises";
+import path from "node:path";
+const isErrnoException = (error) => {
+    return error instanceof Error;
+};
+const commitTemporaryFile = async (temporaryPath, outputPath, options) => {
+    if (options.overwrite) {
+        try {
+            await fs.rename(temporaryPath, outputPath);
+            return;
+        }
+        catch (error) {
+            if (!isErrnoException(error))
+                throw error;
+            if (process.platform !== "win32")
+                throw error;
+            if (error.code !== "EEXIST" && error.code !== "EPERM")
+                throw error;
+            await fs.unlink(outputPath);
+            await fs.rename(temporaryPath, outputPath);
+            return;
+        }
+    }
+    if (process.platform === "win32") {
+        await fs.rename(temporaryPath, outputPath);
+        return;
+    }
+    await fs.link(temporaryPath, outputPath);
+    await fs.unlink(temporaryPath);
+};
+const writeTextFileAtomic = async (outputPath, content, options) => {
+    const outputDirectory = path.dirname(outputPath);
+    await fs.mkdir(outputDirectory, { recursive: true });
+    const temporaryPath = path.join(outputDirectory, `.miniread-evaluate-tmp-${randomUUID()}`);
+    await fs.writeFile(temporaryPath, content, { encoding: "utf8", flag: "wx" });
+    try {
+        await commitTemporaryFile(temporaryPath, outputPath, options);
+    }
+    catch (error) {
+        await fs.unlink(temporaryPath).catch(() => { });
+        throw error;
+    }
+};
+export const writeJsonFileAtomic = async (outputPath, value, options) => {
+    await writeTextFileAtomic(outputPath, JSON.stringify(value, undefined, 2) + "\n", options);
+};

package/dist/scripts/evaluate.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/scripts/evaluate.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { runEvaluateCli } from "./evaluate/run-evaluate-cli.js";
+try {
+    const exitCode = await runEvaluateCli(process.argv);
+    if (exitCode !== 0) {
+        process.exitCode = exitCode;
+    }
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Error: ${message}`);
+    process.exitCode = 1;
+}

package/dist/scripts/sample/choose-line-window.d.ts

@@ -0,0 +1,11 @@
+export declare const chooseLineWindow: (options: {
+    totalLines: number;
+    startLine: number;
+    endLine: number;
+    contextLines: number;
+    maxLines: number;
+}) => {
+    windowStartLine: number;
+    windowEndLine: number;
+    truncatedByLines: boolean;
+};

package/dist/scripts/sample/choose-line-window.js

@@ -0,0 +1,19 @@
+export const chooseLineWindow = (options) => {
+    const { totalLines, startLine, endLine, contextLines, maxLines } = options;
+    const candidateLines = endLine - startLine + 1;
+    if (candidateLines > maxLines) {
+        return {
+            windowStartLine: startLine,
+            windowEndLine: Math.min(totalLines, startLine + maxLines - 1),
+            truncatedByLines: true,
+        };
+    }
+    const extraLinesAvailable = maxLines - candidateLines;
+    const before = Math.min(contextLines, Math.floor(extraLinesAvailable / 2));
+    const after = Math.min(contextLines, extraLinesAvailable - before);
+    return {
+        windowStartLine: Math.max(1, startLine - before),
+        windowEndLine: Math.min(totalLines, endLine + after),
+        truncatedByLines: false,
+    };
+};

package/dist/scripts/sample/clip-text-around-core.d.ts

@@ -0,0 +1,12 @@
+export declare const clipTextAroundCore: (options: {
+    text: string;
+    coreStart: number;
+    coreEnd: number;
+    contextChars: number;
+    maxChars: number;
+}) => {
+    excerptStart: number;
+    excerptEnd: number;
+    code: string;
+    truncatedByChars: boolean;
+};

package/dist/scripts/sample/clip-text-around-core.js

@@ -0,0 +1,61 @@
+export const clipTextAroundCore = (options) => {
+    const { text, coreStart, coreEnd, contextChars, maxChars } = options;
+    if (text.length <= maxChars) {
+        return {
+            excerptStart: 0,
+            excerptEnd: text.length,
+            code: text,
+            truncatedByChars: false,
+        };
+    }
+    const normalizedCoreStart = Math.max(0, Math.min(coreStart, text.length));
+    const normalizedCoreEnd = Math.max(normalizedCoreStart, Math.min(coreEnd, text.length));
+    const coreLength = normalizedCoreEnd - normalizedCoreStart;
+    const marker = "\n/* … truncated … */\n";
+    if (coreLength > maxChars) {
+        const available = maxChars - marker.length;
+        const headLength = Math.max(1, Math.floor(available / 2));
+        const tailLength = Math.max(1, available - headLength);
+        const head = text.slice(normalizedCoreStart, normalizedCoreStart + headLength);
+        const tail = text.slice(normalizedCoreEnd - tailLength, normalizedCoreEnd);
+        return {
+            excerptStart: normalizedCoreStart,
+            excerptEnd: normalizedCoreEnd,
+            code: `${head}${marker}${tail}`,
+            truncatedByChars: true,
+        };
+    }
+    const desiredStart = Math.max(0, normalizedCoreStart - contextChars);
+    const desiredEnd = Math.min(text.length, normalizedCoreEnd + contextChars);
+    const desiredLength = desiredEnd - desiredStart;
+    if (desiredLength > maxChars) {
+        const budget = maxChars - coreLength;
+        const availableBefore = Math.max(0, normalizedCoreStart - desiredStart);
+        const availableAfter = Math.max(0, desiredEnd - normalizedCoreEnd);
+        let before = Math.min(availableBefore, Math.floor(budget / 2));
+        const after = Math.min(availableAfter, budget - before);
+        before = Math.min(availableBefore, budget - after);
+        const excerptStart = Math.max(0, normalizedCoreStart - before);
+        const excerptEnd = Math.min(text.length, normalizedCoreEnd + after);
+        return {
+            excerptStart,
+            excerptEnd,
+            code: text.slice(excerptStart, excerptEnd),
+            truncatedByChars: true,
+        };
+    }
+    const leftover = maxChars - desiredLength;
+    const availableBefore = desiredStart;
+    const availableAfter = text.length - desiredEnd;
+    let before = Math.min(availableBefore, Math.floor(leftover / 2));
+    const after = Math.min(availableAfter, leftover - before);
+    before = Math.min(availableBefore, leftover - after);
+    const excerptStart = Math.max(0, desiredStart - before);
+    const excerptEnd = Math.min(text.length, desiredEnd + after);
+    return {
+        excerptStart,
+        excerptEnd,
+        code: text.slice(excerptStart, excerptEnd),
+        truncatedByChars: true,
+    };
+};

package/dist/scripts/sample/collect-function-candidates.d.ts

@@ -0,0 +1,20 @@
+export type FunctionCandidate = {
+    nodeType: string;
+    name: string | undefined;
+    startLine: number;
+    endLine: number;
+    startColumn: number;
+    endColumn: number;
+    startOffset: number;
+    endOffset: number;
+};
+export declare const collectFileFunctionCandidates: (options: {
+    filePath: string;
+    content: string;
+}) => {
+    ok: true;
+    candidates: FunctionCandidate[];
+} | {
+    ok: false;
+    error: string;
+};

package/dist/scripts/sample/collect-function-candidates.js

@@ -0,0 +1,82 @@
+import { createRequire } from "node:module";
+import { parse } from "@babel/parser";
+import * as t from "@babel/types";
+const require = createRequire(import.meta.url);
+// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+const traverse = require("@babel/traverse").default;
+const getPlugins = (filePath) => {
+    const plugins = [];
+    if (filePath.endsWith(".ts") || filePath.endsWith(".tsx")) {
+        plugins.push("typescript");
+    }
+    if (filePath.endsWith(".jsx") || filePath.endsWith(".tsx")) {
+        plugins.push("jsx");
+    }
+    return plugins;
+};
+const inferFunctionName = (path) => {
+    const idNode = path.node.id;
+    if (idNode && t.isIdentifier(idNode))
+        return idNode.name;
+    const parent = path.parentPath;
+    // const foo = function() {} / const foo = () => {}
+    if (parent.isVariableDeclarator()) {
+        const { id } = parent.node;
+        if (id && t.isIdentifier(id))
+            return id.name;
+    }
+    // foo = function() {} / foo = () => {}
+    if (parent.isAssignmentExpression()) {
+        const { left } = parent.node;
+        if (left && t.isIdentifier(left))
+            return left.name;
+    }
+    // { foo: function() {} } / { foo() {} }
+    if (parent.isObjectProperty() || parent.isObjectMethod()) {
+        const { key } = parent.node;
+        if (key && t.isIdentifier(key))
+            return key.name;
+        if (key && t.isStringLiteral(key))
+            return key.value;
+    }
+    return undefined;
+};
+const collectFunctionCandidates = (ast) => {
+    const candidates = [];
+    traverse(ast, {
+        Function(path) {
+            const loc = path.node.loc;
+            const start = path.node.start;
+            const end = path.node.end;
+            if (!loc || typeof start !== "number" || typeof end !== "number")
+                return;
+            candidates.push({
+                nodeType: path.node.type,
+                name: inferFunctionName(path),
+                startLine: loc.start.line,
+                endLine: loc.end.line,
+                startColumn: loc.start.column,
+                endColumn: loc.end.column,
+                startOffset: start,
+                endOffset: end,
+            });
+        },
+    });
+    return candidates;
+};
+export const collectFileFunctionCandidates = (options) => {
+    const { filePath, content } = options;
+    let ast;
+    try {
+        ast = parse(content, {
+            sourceType: "unambiguous",
+            plugins: getPlugins(filePath),
+            sourceFilename: filePath,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, error: `Failed to parse ${filePath}: ${message}` };
+    }
+    return { ok: true, candidates: collectFunctionCandidates(ast) };
+};

package/dist/scripts/sample/create-function-excerpt.d.ts

@@ -0,0 +1,20 @@
+export declare const createFunctionExcerpt: (options: {
+    content: string;
+    lineStartOffsets: number[];
+    totalLines: number;
+    startLine: number;
+    endLine: number;
+    startOffset: number;
+    endOffset: number;
+    contextLines: number;
+    contextChars: number;
+    maxLines: number;
+    maxChars: number;
+}) => {
+    excerptStartLine: number;
+    excerptEndLine: number;
+    excerptStartOffset: number;
+    excerptEndOffset: number;
+    truncated: boolean;
+    code: string;
+};

package/dist/scripts/sample/create-function-excerpt.js

@@ -0,0 +1,37 @@
+import { getLineEndOffset, getLineStartOffset, offsetToLineNumber, } from "./line-offsets.js";
+import { clipTextAroundCore } from "./clip-text-around-core.js";
+import { chooseLineWindow } from "./choose-line-window.js";
+export const createFunctionExcerpt = (options) => {
+    const { content, lineStartOffsets, totalLines, startLine, endLine, startOffset, endOffset, contextLines, contextChars, maxLines, maxChars, } = options;
+    const { windowStartLine, windowEndLine, truncatedByLines } = chooseLineWindow({
+        totalLines,
+        startLine,
+        endLine,
+        contextLines,
+        maxLines,
+    });
+    const windowStartOffset = getLineStartOffset(lineStartOffsets, windowStartLine);
+    const windowEndOffset = getLineEndOffset(lineStartOffsets, windowEndLine, content.length);
+    const windowText = content.slice(windowStartOffset, windowEndOffset);
+    const coreStart = Math.max(0, startOffset - windowStartOffset);
+    const coreEnd = Math.min(windowText.length, endOffset - windowStartOffset);
+    const clipped = clipTextAroundCore({
+        text: windowText,
+        coreStart,
+        coreEnd,
+        contextChars,
+        maxChars,
+    });
+    const excerptStartOffset = windowStartOffset + clipped.excerptStart;
+    const excerptEndOffset = windowStartOffset + clipped.excerptEnd;
+    const excerptStartLine = offsetToLineNumber(lineStartOffsets, excerptStartOffset);
+    const excerptEndLine = offsetToLineNumber(lineStartOffsets, Math.max(excerptStartOffset, excerptEndOffset - 1));
+    return {
+        excerptStartLine,
+        excerptEndLine,
+        excerptStartOffset,
+        excerptEndOffset,
+        truncated: truncatedByLines || clipped.truncatedByChars,
+        code: clipped.code,
+    };
+};

package/dist/scripts/sample/create-sample-command.d.ts

@@ -0,0 +1,17 @@
+import { Command } from "@commander-js/extra-typings";
+export type SampleOutputFormat = "markdown" | "json";
+export type SampleCliRawOptions = {
+    input: string;
+    snippets: number;
+    maxFiles: number;
+    minLines: number;
+    maxLines: number;
+    maxChars: number;
+    contextLines: number;
+    contextChars: number;
+    seed?: string;
+    format: SampleOutputFormat;
+};
+export declare const createSampleCommand: (options: {
+    version: string;
+}) => Command;

package/dist/scripts/sample/create-sample-command.js

@@ -0,0 +1,50 @@
+import { Command, InvalidArgumentError } from "@commander-js/extra-typings";
+const parsePositiveInt = (rawValue) => {
+    const value = Number(rawValue);
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new InvalidArgumentError(`invalid value '${rawValue}' (expected a positive integer)`);
+    }
+    return value;
+};
+const parseNonNegativeInt = (rawValue) => {
+    const value = Number(rawValue);
+    if (!Number.isInteger(value) || value < 0) {
+        throw new InvalidArgumentError(`invalid value '${rawValue}' (expected a non-negative integer)`);
+    }
+    return value;
+};
+const parseOutputFormat = (rawValue) => {
+    if (rawValue === "markdown" || rawValue === "json")
+        return rawValue;
+    throw new InvalidArgumentError(`invalid value '${rawValue}' (expected: markdown, json)`);
+};
+export const createSampleCommand = (options) => {
+    const program = new Command()
+        .name("miniread-sample")
+        .description("Generate random code samples from a source tree so an agent cannot choose the samples itself.")
+        .version(options.version)
+        .showHelpAfterError("(add --help for additional information)")
+        .showSuggestionAfterError()
+        .requiredOption("-i, --input <path>", "File or directory to sample from (e.g. sources/claude-code-2.1.11)")
+        .option("--snippets <count>", "How many random snippets to sample (total across all files under --input)", parsePositiveInt, 5)
+        .option("--max-files <count>", "Limit how many files are scanned when --input is a directory (0 = all files)", parseNonNegativeInt, 0)
+        .option("--min-lines <count>", "Minimum snippet size in lines (shorter function bodies are skipped when possible)", parsePositiveInt, 5)
+        .option("--max-lines <count>", "Maximum snippet size in lines (clips larger function bodies)", parsePositiveInt, 80)
+        .option("--max-chars <count>", "Maximum excerpt size in characters (clips very long lines/functions)", parsePositiveInt, 4000)
+        .option("--context-lines <count>", "Extra lines of context around each snippet (best-effort, may be reduced to fit --max-lines)", parseNonNegativeInt, 2)
+        .option("--context-chars <count>", "Extra characters of context around each snippet (best-effort, may be reduced to fit --max-chars)", parseNonNegativeInt, 200)
+        .option("--seed <value>", "Seed for deterministic sampling (optional)")
+        .option("--format <format>", "Output format: markdown, json", parseOutputFormat, "markdown");
+    program.addHelpText("after", `
+Examples:
+  # Sample 5 random functions from a minified source directory
+  pnpm run miniread-sample -- --input sources/claude-code-2.1.11
+
+  # Sample from a single file
+  pnpm run miniread-sample -- --input sources/claude-code-2.1.11/cli.js --snippets 10
+
+  # Deterministic output (share the same samples with someone else)
+  pnpm run miniread-sample -- --input sources/claude-code-2.1.11 --seed 2026-01-21
+`);
+    return program;
+};

package/dist/scripts/sample/extract-function-samples.d.ts

@@ -0,0 +1,31 @@
+import type { RandomNumberGenerator } from "./random.js";
+export type FunctionSample = {
+    filePath: string;
+    filePathRelative: string;
+    nodeType: string;
+    name: string | undefined;
+    startLine: number;
+    endLine: number;
+    startColumn: number;
+    endColumn: number;
+    startOffset: number;
+    endOffset: number;
+    excerptStartLine: number;
+    excerptEndLine: number;
+    excerptStartOffset: number;
+    excerptEndOffset: number;
+    truncated: boolean;
+    code: string;
+};
+export declare const extractFunctionSamples: (options: {
+    filePaths: string[];
+    rootDirectory: string;
+    maxFiles: number;
+    snippets: number;
+    minLines: number;
+    maxLines: number;
+    contextLines: number;
+    contextChars: number;
+    maxChars: number;
+    rng: RandomNumberGenerator;
+}) => Promise<FunctionSample[]>;