jev-agent-tools 0.1.4 → 0.3.0

package/dist/configuration.js

@@ -0,0 +1,267 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, rename, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { privateStorage, } from "./adapters/private-storage.js";
+import { createJevClient } from "./jev/client.js";
+const fields = ["url", "apiKey", "model"];
+const defaults = { url: "", apiKey: "", model: "openjev" };
+const storageError = () => new Error("Cannot read or save Jev configuration. Check that the configuration directory and config.json are owned by you, private, regular storage without symlinks, and contain valid configuration JSON.");
+function nonempty(value) {
+    return value !== undefined && value.trim().length > 0;
+}
+function validate(values) {
+    let validUrl = false;
+    let insecureTransport = false;
+    try {
+        const url = new URL(values.url);
+        const host = url.hostname.toLowerCase();
+        const loopback = host === "127.0.0.1" ||
+            host === "localhost" ||
+            host === "::1" ||
+            host === "[::1]";
+        const wellFormed = /^https?:\/\//i.test(values.url) &&
+            (url.protocol === "http:" || url.protocol === "https:") &&
+            url.hostname !== "" &&
+            url.username === "" &&
+            url.password === "";
+        insecureTransport = wellFormed && url.protocol === "http:" && !loopback;
+        validUrl = wellFormed && (url.protocol === "https:" || loopback);
+    }
+    catch {
+        // Keep user-controlled URL and credentials out of error messages.
+    }
+    if (insecureTransport) {
+        throw new Error("Jev configuration refuses plain http: to a non-loopback host; use https: or an http: loopback URL (127.0.0.1, ::1 or localhost).");
+    }
+    if (!validUrl ||
+        !nonempty(values.apiKey) ||
+        /[^\x20-\x7e\x80-\xff]/.test(values.apiKey) ||
+        !nonempty(values.model)) {
+        throw new Error("Jev configuration requires a full https: URL (or http: to 127.0.0.1, ::1 or localhost) without embedded credentials, a nonempty HTTP-header-compatible API key, and a nonempty model.");
+    }
+}
+/** Effective configuration and its client move together, only after a save succeeds. */
+export class ConfigController {
+    environment = {};
+    flags = {};
+    saved = {};
+    session = {};
+    directory;
+    storage;
+    initialization;
+    currentClient;
+    constructor(options = {}) {
+        const env = options.env ?? process.env;
+        this.storage = options.storage ?? privateStorage();
+        for (const [field, name] of [
+            ["url", "JEV_TOOLS_URL"],
+            ["apiKey", "JEV_TOOLS_API_KEY"],
+            ["model", "JEV_TOOLS_MODEL"],
+        ]) {
+            if (nonempty(env[name]))
+                this.environment[field] = env[name];
+        }
+        const base = nonempty(env.XDG_CONFIG_HOME) && isAbsolute(env.XDG_CONFIG_HOME)
+            ? env.XDG_CONFIG_HOME
+            : join(homedir(), ".config");
+        this.directory = resolve(options.directory ?? join(base, "jev-agent-tools"));
+        if (nonempty(this.environment.url) && nonempty(this.environment.apiKey)) {
+            const effective = this.values();
+            validate(effective);
+            this.currentClient = createJevClient(effective);
+        }
+    }
+    get client() {
+        return this.currentClient;
+    }
+    initialize(flags) {
+        if (this.initialization)
+            return this.initialization;
+        this.initialization = this.load(flags).catch((error) => {
+            this.initialization = undefined;
+            throw error;
+        });
+        return this.initialization;
+    }
+    values() {
+        return {
+            ...defaults,
+            ...this.saved,
+            ...this.session,
+            ...this.flags,
+            ...this.environment,
+        };
+    }
+    locked(field) {
+        return (this.environment[field] !== undefined || this.flags[field] !== undefined);
+    }
+    async apply(values, persist) {
+        if (!this.initialization) {
+            throw new Error("Initialize Jev configuration before applying changes.");
+        }
+        await this.initialization;
+        const session = { ...this.session };
+        for (const field of fields) {
+            if (!this.locked(field))
+                session[field] = values[field];
+        }
+        const effective = {
+            ...defaults,
+            ...this.saved,
+            ...session,
+            ...this.flags,
+            ...this.environment,
+        };
+        validate(effective);
+        const saved = { ...this.saved, ...session };
+        if (persist)
+            await this.save(saved);
+        const previous = this.values();
+        this.session = session;
+        if (persist)
+            this.saved = saved;
+        if (fields.some((field) => previous[field] !== effective[field])) {
+            this.currentClient?.clearCache();
+            this.currentClient = createJevClient(effective);
+        }
+        else {
+            this.currentClient ??= createJevClient(effective);
+        }
+    }
+    async load(flags) {
+        const saved = await this.readSaved();
+        const supplied = {};
+        if (nonempty(flags.url))
+            supplied.url = flags.url;
+        if (nonempty(flags.model))
+            supplied.model = flags.model;
+        const effective = {
+            ...defaults,
+            ...saved,
+            ...supplied,
+            ...this.environment,
+        };
+        if (nonempty(effective.url) && nonempty(effective.apiKey)) {
+            validate(effective);
+            this.currentClient?.clearCache();
+            this.currentClient = createJevClient(effective);
+        }
+        this.saved = saved;
+        this.flags = supplied;
+    }
+    async checkDirectory() {
+        // Check ancestors too: recursive mkdir and path-based reads must not follow symlinks.
+        // Privacy of the directory itself is checked with its file in readSaved,
+        // using the operating system's own permission model.
+        let path = this.directory;
+        let exists = true;
+        while (true) {
+            try {
+                const stat = await lstat(path);
+                if (!stat.isDirectory() || stat.isSymbolicLink())
+                    throw storageError();
+            }
+            catch (error) {
+                if (error?.code !== "ENOENT")
+                    throw storageError();
+                if (path === this.directory)
+                    exists = false;
+            }
+            const parent = dirname(path);
+            if (parent === path)
+                break;
+            path = parent;
+        }
+        return exists;
+    }
+    async readSaved() {
+        try {
+            if (!(await this.checkDirectory()))
+                return {};
+            const directory = {
+                path: this.directory,
+                stat: await lstat(this.directory),
+            };
+            const path = join(this.directory, "config.json");
+            try {
+                const stat = await lstat(path);
+                if (!stat.isFile() || stat.isSymbolicLink())
+                    throw storageError();
+            }
+            catch (error) {
+                if (error?.code === "ENOENT") {
+                    if (!(await this.storage.isPrivate([directory])))
+                        throw storageError();
+                    return {};
+                }
+                throw error;
+            }
+            const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                const stat = await file.stat();
+                if (!stat.isFile() ||
+                    stat.nlink !== 1 ||
+                    !(await this.storage.isPrivate([directory, { path, stat }]))) {
+                    throw storageError();
+                }
+                const value = JSON.parse(await file.readFile("utf8"));
+                if (value === null ||
+                    typeof value !== "object" ||
+                    Array.isArray(value) ||
+                    Object.entries(value).some(([key, entry]) => !fields.some((field) => field === key) ||
+                        typeof entry !== "string")) {
+                    throw storageError();
+                }
+                return value;
+            }
+            finally {
+                await file.close();
+            }
+        }
+        catch {
+            throw storageError();
+        }
+    }
+    async save(values) {
+        let temporary;
+        try {
+            const existed = await this.checkDirectory();
+            if (!existed) {
+                await mkdir(this.directory, { recursive: true, mode: 0o700 });
+            }
+            // Windows ignores mkdir's mode, so restrict the ACL before any secret is
+            // written: always for a new directory, and for an existing one only while
+            // it holds no configuration (e.g. left behind by an earlier failed save).
+            // Existing configuration is never re-permissioned; readSaved refuses it.
+            if (!existed ||
+                !(await lstat(join(this.directory, "config.json")).then(() => true, () => false)))
+                await this.storage.restrictDirectory(this.directory);
+            // Refuse to replace malformed, insecure or newly introduced storage.
+            await this.readSaved();
+            temporary = join(this.directory, `.config-${randomUUID()}.tmp`);
+            const file = await open(temporary, constants.O_WRONLY |
+                constants.O_CREAT |
+                constants.O_EXCL |
+                constants.O_NOFOLLOW, 0o600);
+            try {
+                await file.writeFile(`${JSON.stringify(values, null, 2)}\n`, "utf8");
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            await this.readSaved();
+            await rename(temporary, join(this.directory, "config.json"));
+            temporary = undefined;
+        }
+        catch {
+            throw storageError();
+        }
+        finally {
+            if (temporary)
+                await unlink(temporary).catch(() => { });
+        }
+    }
+}

package/dist/constants.js

@@ -0,0 +1,140 @@
+export const STATE_MAX_CHARS = 80_000;
+export const TEST_SOURCE_MAX_BYTES = STATE_MAX_CHARS * 16;
+export const SELECT_FILE_SHARE = 0.8;
+export const ASK_NOTE_MAX_CHARS = 8_000;
+export const ASK_MAX_FILES = 20;
+export const ASK_TIMEOUT_S = 60;
+export const ASK_TIMEOUT_MAX_S = 300;
+export const PROCESS_KILL_GRACE_MS = 2_000;
+export const PROCESS_PIPE_GRACE_MS = 1_000;
+export const PROCESS_TREE_TIMEOUT_MS = 5_000;
+export const MCP_SHUTDOWN_FLUSH_TIMEOUT_MS = 1_000;
+export const PRIVATE_STORAGE_TIMEOUT_MS = 20_000;
+export const MCP_VALIDATION_MAX_ERRORS = 5;
+export const MCP_PACKAGE_REPLY_TIMEOUT_MS = 20_000;
+export const MCP_PACKAGE_EXIT_TIMEOUT_MS = 10_000;
+export const MCP_PACKAGE_KILL_TIMEOUT_MS = 2_000;
+export const MCP_PACKAGE_INSTALL_TIMEOUT_MS = 300_000;
+export const MCP_PACKAGE_STDERR_MAX_CHARS = 2_000;
+export const OUTPUT_REPEAT_MIN = 5;
+export const OUTPUT_CHUNK_CHARS = 2_500;
+export const OUTPUT_FIND_MAX_CALLS = 40;
+export const OUTPUT_HEAD_SHARE = 0.05;
+export const OUTPUT_TAIL_SHARE = 0.15;
+// Unmeasured admission bound for each command output file; never truncate it silently.
+export const OUTPUT_FILE_MAX_BYTES = 64 * 1024 * 1024;
+export const OUTPUT_LINE_MAX_CHARS = 8_192;
+export const OUTPUT_SHAPE_MAX_COUNT = 2_048;
+export const OUTPUT_FAILURE_WINDOW_LINES = 20;
+export const CHOICE_MAX_OPTIONS = 255;
+export const MAX_FILES = 255;
+export const FILE_MAX_KB = STATE_MAX_CHARS / 1_000;
+export const SCORE_MIN_LEVELS = 2;
+export const SCORE_MAX_LEVELS = 10;
+export const TIMEOUT_MS = 10_000;
+export const UNIT_MAX_CHARS = 6_000;
+export const UNIT_CONTEXT_LINES = 8;
+export const SELECT_MIN = 0.5;
+export const BAND_BOOL_GRAY_A = 0.2;
+export const BAND_BOOL_YES_MIN = 1 - BAND_BOOL_GRAY_A;
+export const ORDER_REVERSE_BELOW = 0.85;
+export const ORDER_DISAGREE_MIN = 0.1;
+export const BAND_CHOICE_VERDICT_MIN = ORDER_REVERSE_BELOW;
+export const CANNOT_TELL_MIN = 0.3;
+export const REQUEST_MAX_TOKENS = 60_000;
+export const RATE_PER_SECOND = 8;
+export const CONCURRENCY = 8;
+export const REQUEST_ATTEMPTS = 3;
+export const RETRY_BASE_MS = 500;
+export const RETRY_MAX_MS = 5_000;
+export const HTTP_ERROR_MAX_CHARS = 300;
+export const QUESTION_TOKENS = 1 / 3.3;
+export const STATE_TOKENS = 0.283;
+export const REQUEST_BASE_TOKENS = 456;
+export const FLAG_MIN = 0.7;
+export const DOCS_CHECK_MIN = 0.2;
+export const DOCS_MAX_SECTIONS = 40;
+export const HOOK_BUDGET_MS = 15_000;
+/** Progressive collection time bound, not a coverage or wall-time guarantee. */
+export const DOCS_COLLECT_BUDGET_MS = 750;
+export const DOCS_NAME_MAX_FILES = 32;
+/** Initial per-anchor traversal bound; shared edge cache remains unbounded. */
+export const DOCS_ANCHOR_MAX_FILES = 32;
+export const WITNESS_LURE_MAX = 0.15;
+/** Small coverage decoys only; risk and large-witness policies remain unchanged. */
+export const COVERAGE_WITNESS_LURE_MAX = 0.2;
+export const WITNESS_LARGE_LURE_MAX = 0.25;
+export const WITNESS_LARGE_CHARS = 13_000;
+export const WITNESS_ETALON_MIN = 0.7;
+export const WITNESS_AUTO_MIN_CELLS = 8;
+export const CLOSURE_MAX_CHARS = 20_000;
+export const CALLER_DISPLAY_MAX_SPANS = 8;
+export const LIMIT_DISPLAY_MAX_PATHS = 4;
+export const DOCS_DISPLAY_MAX_SECTIONS = 5;
+export const FIND_NAME_CANDIDATES = 128;
+export const FIND_NAME_BATCH = 64;
+export const FIND_FILES_READ = 20;
+export const FIND_READ_PER_CALL = 5;
+export const FIND_EXCERPT_CHARS = 3_000;
+export const FIND_POINTER_EXCERPT_CHARS = 1_500;
+export const FIND_POINTER_MAX = 8;
+export const FIND_NAME_GUARD_MIN = 0.9;
+export const FIND_CONFIRM_MIN = 0.8;
+export const FIND_GOAL_MIN_WORDS = 5;
+export const FIND_QUICK_CANDIDATES = 32;
+export const FIND_QUICK_READ = 8;
+export const FIND_THOROUGH_CANDIDATES = 256;
+export const FIND_THOROUGH_READ = 40;
+export const FIND_EXCERPT_HEAD_CHARS = 1_000;
+export const FIND_CONTENT_MIN = 0.5;
+export const FIND_NAME_GUARD_TOP = 3;
+export const FIND_PATH_WEIGHT = 3;
+export const FIND_GREP_PAGE_SIZE = 1024;
+export const FIND_READ_CHUNK_BYTES = 16_384;
+export const LOCATE_MIN_KB = 19;
+export const LOCATE_VERDICT_MIN = 0.7;
+export const LOCATE_GRAY_MIN = 0.4;
+export const LOCATE_SHRINK_TOP = 3;
+export const LOCATE_SECTION_MAX_LINES = 150;
+export const LOCATE_SECTION_MIN_LINES = 8;
+export const LOCATE_WINDOW_LINES = 80;
+export const LOCATE_LABEL_MAX_CHARS = 120;
+export const LOCATE_WHOLE_MAX_CHARS = STATE_MAX_CHARS * 4;
+export const LOCATE_WHOLE_MAX_BYTES = LOCATE_WHOLE_MAX_CHARS * 4;
+export const LOCATE_READ_BUFFER_BYTES = 64 * 1024;
+// Unmeasured engineering bound: leaves room for multi-window refinement and JSON metadata.
+export const LOCATE_WINDOW_MAX_SERIALIZED_CHARS = STATE_MAX_CHARS / 4;
+// Keep SHA-256 IDs plus options below Windows' command-line limit.
+export const GIT_BLOB_BATCH_SIZE = 400;
+export const RUNNER_PACKAGE_MAX_BYTES = 64 * 1024;
+// ADR 0001: allowed local dependencies, including erased type imports.
+export const IMPORT_LAYERS = {
+    core: [
+        "core",
+        "constants.ts",
+        "result.ts",
+        "result-types.ts",
+        "jev/types.ts",
+    ],
+    presets: [
+        "presets",
+        "core",
+        "constants.ts",
+        "result.ts",
+        "result-types.ts",
+        "jev/types.ts",
+    ],
+    adapters: [
+        "adapters",
+        "core",
+        "constants.ts",
+        "result.ts",
+        "result-types.ts",
+        "jev/types.ts",
+    ],
+    jev: ["jev", "core", "constants.ts", "result.ts", "result-types.ts"],
+    texts: ["texts", "constants.ts", "presets"],
+    "constants.ts": [],
+    "result.ts": ["result-types.ts"],
+    "result-types.ts": [],
+};

package/dist/core/ask-closure.js

@@ -0,0 +1,282 @@
+import { posix } from "node:path";
+import { CLOSURE_MAX_CHARS, STATE_MAX_CHARS, UNIT_MAX_CHARS, } from "../constants.js";
+import { truncate } from "./truncate.js";
+export function buildAskClosure({ graph, syntax, paths, intentions, state, }) {
+    const limitations = [];
+    const dependencyLimit = (path, dependency, cause) => {
+        const nonRelative = /^(?:unresolved|ambiguous) import$/.test(cause) &&
+            dependency.length > 0 &&
+            !dependency.startsWith(".") &&
+            !dependency.startsWith("/") &&
+            !dependency.startsWith("sys.path");
+        return {
+            path,
+            dependency,
+            cause: `${cause}${nonRelative ? " (external or standard-library, or unresolved repository alias)" : ""}`,
+            fact: `${path} : ${dependency}, ${cause}${nonRelative ? "; external or standard-library dependency (or unresolved repository alias), not admitted as a repository file" : ""}`,
+            next: nonRelative
+                ? "Provide the dependency contract in state or a repository-local implementation in paths; do not read outside the repository."
+                : "Provide the dependency explicitly in paths.",
+        };
+    };
+    const relevant = new Set(paths);
+    const candidates = new Map();
+    const originalFiles = state.files &&
+        typeof state.files === "object" &&
+        !Array.isArray(state.files)
+        ? state.files
+        : {};
+    const contained = (path) => paths.includes(path) || Object.hasOwn(originalFiles, path);
+    const declarations = (path, name) => syntax.declarations.filter((item) => item.path === path &&
+        (name === "*" ||
+            item.name === name ||
+            item.name.startsWith(`${name}.`)));
+    const mentioned = (name) => intentions.split(/[^\p{L}\p{N}_$.]+/u).includes(name);
+    const add = (declaration, direct, depth, typeOnly = false) => {
+        if (contained(declaration.path))
+            return;
+        const changed = declaration.before !== undefined &&
+            declaration.before !== declaration.text;
+        const priority = mentioned(declaration.name) || direct ? 0 : changed ? 1 : 2;
+        const key = `${declaration.path} (${declaration.name})`;
+        const previous = candidates.get(key);
+        if (!previous ||
+            priority < previous.priority ||
+            (priority === previous.priority &&
+                (Number(typeOnly) < Number(previous.typeOnly) ||
+                    (typeOnly === previous.typeOnly && depth < previous.depth))))
+            candidates.set(key, { declaration, priority, depth, typeOnly });
+    };
+    const target = (binding) => {
+        if (!binding.specifier)
+            return binding.path;
+        const edges = graph.edges.get(binding.path) ?? [];
+        const python = binding.path.endsWith(".py");
+        let base;
+        if (python) {
+            const relative = binding.specifier.match(/^\.+/)?.[0].length ?? 0;
+            base = relative
+                ? posix.join(posix.dirname(binding.path), ...Array.from({ length: relative - 1 }, () => ".."), binding.specifier.slice(relative).replaceAll(".", "/"))
+                : binding.specifier.replaceAll(".", "/");
+        }
+        else
+            base =
+                binding.specifier.startsWith(".") || binding.data
+                    ? posix.join(posix.dirname(binding.path), binding.specifier)
+                    : binding.specifier;
+        base = posix.normalize(base);
+        const alternatives = python
+            ? [
+                base,
+                `${base}.py`,
+                `${base}/__init__.py`,
+                `${base}/${binding.imported}.py`,
+            ]
+            : [
+                base,
+                ...[".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"].map((extension) => base.replace(/\.js$/, "") + extension),
+                ...["ts", "tsx", "js", "jsx"].map((extension) => `${base}/index.${extension}`),
+            ];
+        const matches = edges.filter((edge) => alternatives.some((alternative) => edge === alternative ||
+            (!binding.specifier.startsWith(".") &&
+                edge.endsWith(`/${alternative}`))));
+        if (matches.length === 1)
+            return matches[0];
+        limitations.push(dependencyLimit(binding.path, binding.specifier, matches.length > 1 ? "ambiguous import" : "unresolved import"));
+        return undefined;
+    };
+    const resolve = (path, name, direct, depth, visited, typeOnly = false) => {
+        relevant.add(path);
+        const key = `${path}:${name}`;
+        if (visited.has(key))
+            return;
+        visited.add(key);
+        const found = declarations(path, name);
+        for (const declaration of found)
+            add(declaration, direct, depth, typeOnly);
+        const exports = syntax.bindings.filter((item) => item.path === path &&
+            item.reexport &&
+            (item.local === name || item.local === "*" || name === "*"));
+        if (!found.length && !exports.length && !contained(path))
+            limitations.push({
+                fact: `${path} (${name}) : used declaration not found`,
+                next: "Provide the declaration explicitly in paths.",
+            });
+        for (const binding of exports) {
+            const destination = target(binding);
+            if (destination)
+                resolve(destination, binding.imported === "*" ? name : binding.imported, direct, depth, visited, typeOnly);
+        }
+    };
+    for (const path of paths) {
+        const used = syntax.uses?.get(path) ??
+            syntax.declarations
+                .filter((item) => item.path === path)
+                .flatMap((item) => item.usedNames);
+        for (const binding of syntax.bindings.filter((item) => item.path === path &&
+            (!item.reexport || path.endsWith("__init__.py")) &&
+            (item.used ?? used.includes(item.local)))) {
+            const destination = target(binding);
+            if (!destination)
+                continue;
+            if (binding.data) {
+                relevant.add(destination);
+                const source = syntax.sources?.find((item) => item.path === destination);
+                if (source)
+                    add({
+                        path: destination,
+                        name: "data",
+                        text: source.text,
+                        ...(syntax.before && Object.hasOwn(syntax.before, destination)
+                            ? { before: syntax.before[destination] }
+                            : {}),
+                        usedNames: [],
+                    }, true, 1);
+                else
+                    limitations.push({
+                        fact: `${destination} : data missing from the inventory`,
+                        next: "Provide this file in paths.",
+                    });
+            }
+            else if (binding.imported === "*" && binding.local !== "*") {
+                const members = used.filter((item) => item.startsWith(`${binding.local}.`));
+                for (const name of members)
+                    resolve(destination, name.slice(binding.local.length + 1), true, 1, new Set(), binding.valueMembers
+                        ? !binding.valueMembers.includes(name)
+                        : binding.typeOnly);
+                if (!members.length)
+                    limitations.push({
+                        fact: `${path} : namespace ${binding.local} used without a statically resolved member`,
+                        next: "Provide the namespace declarations explicitly.",
+                    });
+            }
+            else
+                resolve(destination, binding.imported, true, 1, new Set(), binding.typeOnly);
+        }
+        if (path.endsWith(".py") &&
+            /(^|\/)(test[^/]*|[^/]*_test)\.py$/.test(path)) {
+            const fixtures = syntax.declarations.filter((item) => item.fixture &&
+                posix.basename(item.path) === "conftest.py" &&
+                (posix.dirname(item.path) === "." ||
+                    path.startsWith(`${posix.dirname(item.path)}/`)));
+            // Nearest fixture shadows ancestors, as in pytest.
+            fixtures.sort((a, b) => b.path.length - a.path.length);
+            const selected = new Set();
+            for (const fixture of fixtures) {
+                if (selected.has(fixture.name) ||
+                    (!fixture.autouse && !used.includes(fixture.name)))
+                    continue;
+                selected.add(fixture.name);
+                relevant.add(fixture.path);
+                add(fixture, true, 1);
+                for (const name of fixture.usedNames)
+                    for (const helper of declarations(fixture.path, name))
+                        add(helper, false, 1);
+                for (const binding of syntax.bindings.filter((item) => item.path === fixture.path &&
+                    fixture.usedNames.includes(item.local))) {
+                    const destination = target(binding);
+                    if (destination)
+                        resolve(destination, binding.imported, false, 1, new Set());
+                }
+            }
+        }
+    }
+    for (const limit of syntax.limits)
+        if ([...relevant].some((path) => limit.fact.includes(path)))
+            limitations.push(limit);
+    for (const limit of graph.limits)
+        if (relevant.has(limit.path))
+            limitations.push(dependencyLimit(limit.path, limit.specifier, `${limit.kind} import`));
+    const ordered = [...candidates.values()].sort((a, b) => a.priority - b.priority ||
+        Number(a.typeOnly) - Number(b.typeOnly) ||
+        Number(b.declaration.before !== undefined &&
+            b.declaration.before !== b.declaration.text) -
+            Number(a.declaration.before !== undefined &&
+                a.declaration.before !== a.declaration.text) ||
+        a.depth - b.depth ||
+        a.declaration.path.localeCompare(b.declaration.path) ||
+        a.declaration.name.localeCompare(b.declaration.name));
+    const existing = state.closure &&
+        typeof state.closure === "object" &&
+        !Array.isArray(state.closure)
+        ? state.closure
+        : {};
+    const closure = { ...existing };
+    let nextState = state;
+    let budget = JSON.stringify(existing).length - 2;
+    const added = [];
+    const omitted = [];
+    for (const { declaration } of ordered) {
+        const { path, name } = declaration;
+        const key = `${path} (${name})`;
+        const paired = declaration.before !== undefined &&
+            declaration.before !== declaration.text;
+        if (Object.hasOwn(closure, key))
+            continue;
+        const beforeBudget = !paired || declaration.before == null
+            ? 0
+            : declaration.before.length + declaration.text.length > UNIT_MAX_CHARS
+                ? Math.floor(UNIT_MAX_CHARS / 2)
+                : declaration.before.length;
+        const before = !paired
+            ? undefined
+            : declaration.before == null
+                ? declaration.before
+                : truncate(declaration.before, beforeBudget);
+        const after = truncate(declaration.text, UNIT_MAX_CHARS - (before?.length ?? 0));
+        const sliced = after.length < declaration.text.length ||
+            (paired && (before?.length ?? 0) < (declaration.before?.length ?? 0));
+        const value = !paired
+            ? after
+            : { before: before ?? null, after: declaration.deleted ? null : after };
+        const chars = after.length + (before?.length ?? 0);
+        const contribution = JSON.stringify(key).length +
+            1 +
+            JSON.stringify(value).length +
+            (Object.keys(closure).length ? 1 : 0);
+        const candidateState = { ...state, closure: { ...closure, [key]: value } };
+        const reason = budget + contribution > CLOSURE_MAX_CHARS
+            ? "closure budget exceeded"
+            : JSON.stringify(candidateState).length > STATE_MAX_CHARS
+                ? "serialized state limit exceeded"
+                : undefined;
+        if (reason) {
+            omitted.push({ path, name, reason });
+            limitations.push({
+                fact: `${key} : declaration omitted, ${reason}`,
+                next: "Provide this declaration in a smaller call.",
+            });
+            continue;
+        }
+        closure[key] = value;
+        nextState = candidateState;
+        budget += contribution;
+        added.push({ path, name, chars });
+        if (sliced)
+            limitations.push({
+                fact: `${key} : sliced declaration (${chars} characters)`,
+                next: "Read the complete declaration before drawing conclusions about an omitted part.",
+            });
+    }
+    limitations.push({
+        fact: "Import closure only, semantic depth 1; files without an import link are not checked.",
+        next: "Provide configuration, documentation or data dependencies not linked by imports in paths.",
+    });
+    const seen = new Map();
+    for (const limit of limitations) {
+        const key = JSON.stringify(limit.path
+            ? [limit.path, limit.cause, limit.dependency]
+            : [limit.fact, limit.next]);
+        const previous = seen.get(key);
+        if (previous) {
+            if (limit.cause === "dynamic import") {
+                previous.count = (previous.count ?? 1) + 1;
+                previous.fact = `${limit.fact} (${previous.count} occurrences)`;
+            }
+        }
+        else
+            seen.set(key, { ...limit });
+    }
+    const unique = [...seen.values()];
+    return { state: nextState, added, omitted, limitations: unique };
+}

package/dist/core/ask-proof.js

@@ -0,0 +1 @@
+export {};