@illuminis/comprism 0.1.0

package/out/executor/paths.js

@@ -0,0 +1,126 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutsideWorkspace = void 0;
+exports.isSecret = isSecret;
+exports.resolveInside = resolveInside;
+/**
+ * The folder boundary, on a real filesystem.
+ *
+ * Specification: docs/modules/CODING_AGENT_BUILD_SPECIFICATION.md §8, register
+ * items F1 (the folder is a boundary) and F2 (shortcuts do not defeat it).
+ *
+ * The browser executor gets this property free: it walks directory handles, and
+ * a handle it was never given simply cannot be reached. A real filesystem has no
+ * such protection, so here it has to be enforced, and enforced in the one order
+ * that works.
+ *
+ * **Resolve first, then compare.** Checking the string somebody sent and then
+ * resolving it is the standard way out: `a/../../etc/passwd` passes a check for
+ * ".." at the start and becomes `/etc/passwd` afterwards. And on a real
+ * filesystem there is a second door the browser does not have, which is a
+ * symbolic link inside the project pointing outside it. `realpath` follows it;
+ * a string comparison does not.
+ *
+ * The server checks this too. Two checks is not belt and braces: the server
+ * cannot see the filesystem, so it can only reason about the path it was given,
+ * and this can see the filesystem but runs on a machine we do not control.
+ * Neither alone is the boundary.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+class OutsideWorkspace extends Error {
+    attempted;
+    constructor(attempted) {
+        super(`Refused: ${attempted} is outside this project. The agent works only ` +
+            `inside the folder that was opened.`);
+        this.attempted = attempted;
+        this.name = "OutsideWorkspace";
+    }
+}
+exports.OutsideWorkspace = OutsideWorkspace;
+/** Files never read, whatever the mode. Mirrors the server's own list. */
+const SECRET = /^(\.env(\..*)?|.*\.pem|.*\.key|.*\.p12|.*\.pfx|id_rsa.*|id_ed25519.*|.*\.keystore|credentials|\.npmrc|\.netrc|\.git-credentials)$/i;
+function isSecret(p) {
+    return SECRET.test(path.basename(p));
+}
+/**
+ * An absolute path inside the workspace, or a refusal.
+ *
+ * `mustExist` is false when the caller is about to CREATE the thing. A file that
+ * does not exist yet cannot be resolved, so the check is applied to the deepest
+ * parent that does exist: creating `src/new/deep/file.ts` is inside the project
+ * exactly when `src` is, and demanding the leaf exist first would make it
+ * impossible to write a new file at all.
+ */
+function resolveInside(root, rel, mustExist = false) {
+    const realRoot = fs.realpathSync(root);
+    const asked = String(rel ?? "");
+    // An ABSOLUTE path is resolved as written, and refused if it lands outside.
+    // It used to have its leading slash stripped and be treated as relative to
+    // the project, which was safe and quietly wrong: asking to write
+    // `/tmp/notes.txt` created `<project>/tmp/notes.txt` and reported the path the
+    // caller gave. Nothing escaped, but the confirmation named a file that did not
+    // exist, so the next read failed and the model spent steps on a mystery. An
+    // absolute path inside the project still works, which is the only case anybody
+    // actually means.
+    const joined = path.isAbsolute(asked)
+        ? path.resolve(asked)
+        : path.resolve(realRoot, asked);
+    let probe = joined;
+    if (!mustExist) {
+        // Walk up to the deepest part that exists, so a path we are about to create
+        // is still checked against where it would actually land.
+        while (!fs.existsSync(probe) && path.dirname(probe) !== probe) {
+            probe = path.dirname(probe);
+        }
+    }
+    let real;
+    try {
+        real = fs.realpathSync(probe);
+    }
+    catch {
+        throw new OutsideWorkspace(rel);
+    }
+    // The comparison, with a separator on the end. Without it `/work/project-two`
+    // passes as being inside `/work/project`, because one string starts with the
+    // other.
+    if (real !== realRoot && !real.startsWith(realRoot + path.sep)) {
+        throw new OutsideWorkspace(rel);
+    }
+    // Return the requested path, not the probe: the caller wants to write to the
+    // file it named, and the probe may be an ancestor of it.
+    return mustExist ? real : joined;
+}

package/out/executor/shell.d.ts

@@ -0,0 +1,41 @@
+export interface RunResult {
+    content: string;
+    isError?: boolean;
+    summary?: string;
+}
+export declare function safeEnvironment(from?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export interface ShellOptions {
+    root: string;
+    cwd?: string;
+    timeoutMs?: number;
+    onOutput?: (chunk: string) => void;
+    /** Extra variables for this one command.
+     *
+     *  Used by hooks, so a project's own script can read which file the agent
+     *  just touched without the agent having to rewrite the script's arguments.
+     *  Still filtered by `safeEnvironment`, so a hook cannot be handed a
+     *  credential this way either. */
+    extraEnv?: Record<string, string>;
+}
+/** Run a command and wait for it.
+ *
+ *  Never throws for an ordinary failure. A command that exits non-zero is a
+ *  RESULT: it is usually the most useful thing that can happen, because it is
+ *  how the agent learns what is wrong.
+ */
+export declare function runCommand(command: string, opts: ShellOptions): Promise<RunResult>;
+export declare function startBackground(command: string, opts: ShellOptions): RunResult;
+export declare function readOutput(id: string): RunResult;
+export declare function stopProcess(id: string): RunResult;
+/** Everything still running, stopped. Called when a session ends, so a job that
+ *  started a dev server does not leave it holding a port after the person has
+ *  closed the terminal. */
+export declare function stopEverything(): void;
+export declare function guessTestCommand(root: string): string | null;
+export declare function runTests(opts: ShellOptions & {
+    command?: string;
+    path?: string;
+}): Promise<RunResult & {
+    passed?: boolean;
+    command?: string;
+}>;

package/out/executor/shell.js

@@ -0,0 +1,336 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeEnvironment = safeEnvironment;
+exports.runCommand = runCommand;
+exports.startBackground = startBackground;
+exports.readOutput = readOutput;
+exports.stopProcess = stopProcess;
+exports.stopEverything = stopEverything;
+exports.guessTestCommand = guessTestCommand;
+exports.runTests = runTests;
+/**
+ * Running things on a real machine.
+ *
+ * Specification: docs/modules/CODING_AGENT_BUILD_SPECIFICATION.md, register
+ * items D17 (run a command), D18 (run the tests), D19 to D21 (long running
+ * processes), D22 (install a dependency) and F12 (a restricted environment).
+ *
+ * ## Why the tests are their own action
+ *
+ * `run_tests` could be a shell command and deliberately is not. Its result is
+ * the grading signal the whole product is built on: it is how a job knows it is
+ * finished, and how the routing engine eventually learns whether a cheaper
+ * model actually finished the work. A result buried inside the output of a
+ * generic command is a result nobody can count.
+ *
+ * ## Why the environment is trimmed
+ *
+ * A command inherits the environment of whatever started it, and on a
+ * developer's machine that includes cloud credentials, deployment tokens and
+ * signing keys. None of that is needed to run a test suite, and all of it is
+ * available to anything the command chooses to run. The agent is not the risk
+ * here; a package in the project's own dependency tree is.
+ */
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const paths_1 = require("./paths");
+/** What a command may print back into the conversation. Beyond this it is cut,
+ *  and the cut is stated: a model that believes it saw the whole output, and
+ *  did not, draws a confident conclusion from half of it. */
+const MAX_OUTPUT_CHARS = 30_000;
+/** Environment variables never passed to a command.
+ *
+ *  Matched by pattern rather than listed by name, because the list is
+ *  unknowable: every cloud provider, CI system and package registry invents its
+ *  own, and a list of the ones we happened to think of is a list that is out of
+ *  date the day it is written. */
+const SECRET_ENV = /(^|_)(KEY|SECRET|TOKEN|PASSWORD|PASSWD|CREDENTIAL|CREDENTIALS|AUTH|PRIVATE|SESSION|COOKIE)(_|$)/i;
+/** Kept regardless, because a command that cannot find its own tools is a
+ *  command that fails for a reason nobody can diagnose. */
+const ALWAYS_KEEP = new Set([
+    "PATH", "HOME", "USER", "SHELL", "LANG", "LC_ALL", "TERM", "TMPDIR", "TZ",
+    "NODE_ENV", "PWD", "PYTHONPATH", "VIRTUAL_ENV", "NVM_DIR", "JAVA_HOME",
+    "GOPATH", "GOROOT", "CARGO_HOME", "RUSTUP_HOME",
+]);
+function safeEnvironment(from = process.env) {
+    const out = {};
+    for (const [k, v] of Object.entries(from)) {
+        if (ALWAYS_KEEP.has(k) || !SECRET_ENV.test(k))
+            out[k] = v;
+    }
+    // Told, not hidden. A command that behaves differently under the agent should
+    // be able to say so, and a person debugging one should be able to see why.
+    out.ILLUMINIS_AGENT = "1";
+    return out;
+}
+function clip(text) {
+    if (text.length <= MAX_OUTPUT_CHARS)
+        return text;
+    const cut = text.length - MAX_OUTPUT_CHARS;
+    return (`${text.slice(0, MAX_OUTPUT_CHARS)}\n\n[... ${cut.toLocaleString()} more ` +
+        `characters. Narrow the command, or write the output to a file and read part of it.]`);
+}
+/** Run a command and wait for it.
+ *
+ *  Never throws for an ordinary failure. A command that exits non-zero is a
+ *  RESULT: it is usually the most useful thing that can happen, because it is
+ *  how the agent learns what is wrong.
+ */
+function runCommand(command, opts) {
+    const cwd = opts.cwd ? (0, paths_1.resolveInside)(opts.root, opts.cwd, true) : fs.realpathSync(opts.root);
+    const timeoutMs = opts.timeoutMs ?? 300_000;
+    return new Promise((resolve) => {
+        let out = "";
+        let done = false;
+        // Through a shell on purpose: pipes, redirection and `&&` are how people
+        // actually write commands, and an agent told it cannot use them writes three
+        // commands where a person would write one.
+        //
+        // Running a command IS this function. It is the agent's shell tool, and a
+        // shell tool that cannot reach a shell is not a tool. What stands between a
+        // command and the machine is the approval list every command is matched
+        // against before it reaches here, plus the working directory being resolved
+        // inside the workspace root. Removing the shell would not add safety; it
+        // would move the same commands somewhere with fewer checks in front of them.
+        // The marker has to be the LAST line before the call, not the first line of
+        // the explanation: semgrep only reads the line immediately above.
+        // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process
+        const child = (0, child_process_1.spawn)(command, {
+            cwd, shell: true,
+            env: { ...safeEnvironment(), ...(opts.extraEnv ?? {}) },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const collect = (chunk) => {
+            const text = chunk.toString();
+            out += text;
+            opts.onOutput?.(text);
+        };
+        child.stdout?.on("data", collect);
+        child.stderr?.on("data", collect);
+        const timer = setTimeout(() => {
+            if (done)
+                return;
+            done = true;
+            // The whole process group, not just the shell. Killing the shell leaves
+            // whatever it started running, which is how a stuck job leaves a server
+            // holding a port after everybody has gone home.
+            try {
+                process.kill(-child.pid, "SIGKILL");
+            }
+            catch {
+                child.kill("SIGKILL");
+            }
+            resolve({
+                isError: true,
+                content: clip(out) +
+                    `\n\n[Stopped after ${Math.round(timeoutMs / 1000)}s. If this command ` +
+                    `waits for input it will never finish; run it in a way that does not.]`,
+                summary: `timed out after ${Math.round(timeoutMs / 1000)}s`,
+            });
+        }, timeoutMs);
+        child.on("error", (err) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            resolve({ isError: true, content: `Could not run it: ${err.message}` });
+        });
+        child.on("close", (code) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            const body = clip(out).trim() || "(no output)";
+            resolve({
+                // Non-zero is not an error in the sense that matters here. It is
+                // information, and it is usually the most useful information available.
+                isError: false,
+                content: `exit ${code}\n\n${body}`,
+                summary: code === 0 ? "exit 0" : `exit ${code}`,
+            });
+        });
+    });
+}
+const running = new Map();
+let counter = 0;
+function startBackground(command, opts) {
+    const cwd = opts.cwd ? (0, paths_1.resolveInside)(opts.root, opts.cwd, true) : fs.realpathSync(opts.root);
+    const id = `p${++counter}`;
+    // The background half of the same shell tool, with the same approval list and
+    // the same workspace root in front of it. See `runCommand` above.
+    // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process
+    const child = (0, child_process_1.spawn)(command, {
+        cwd, shell: true, env: safeEnvironment(), stdio: ["ignore", "pipe", "pipe"],
+    });
+    const entry = { child, buffer: "", read: 0, command };
+    const collect = (chunk) => {
+        entry.buffer += chunk.toString();
+        // Bounded. A watcher left running for an hour would otherwise hold its whole
+        // output in memory, and nobody is going to read the first hour of it.
+        if (entry.buffer.length > MAX_OUTPUT_CHARS * 4) {
+            entry.buffer = entry.buffer.slice(-MAX_OUTPUT_CHARS * 2);
+            entry.read = 0;
+        }
+    };
+    child.stdout?.on("data", collect);
+    child.stderr?.on("data", collect);
+    running.set(id, entry);
+    return {
+        content: `Started as ${id}: ${command}\nUse read_output with ${id} to see what it prints, and stop_process to end it.`,
+        summary: `started ${id}`,
+    };
+}
+function readOutput(id) {
+    const entry = running.get(id);
+    if (!entry)
+        return { isError: true, content: `No process called ${id}.` };
+    const fresh = entry.buffer.slice(entry.read);
+    entry.read = entry.buffer.length;
+    const alive = entry.child.exitCode === null && !entry.child.killed;
+    return {
+        content: (fresh.trim() || "(nothing new)") +
+            `\n\n[${id} is ${alive ? "still running" : `finished, exit ${entry.child.exitCode}`}.]`,
+        summary: alive ? `${id} running` : `${id} exited`,
+    };
+}
+function stopProcess(id) {
+    const entry = running.get(id);
+    if (!entry)
+        return { isError: true, content: `No process called ${id}.` };
+    try {
+        process.kill(-entry.child.pid, "SIGTERM");
+    }
+    catch {
+        entry.child.kill("SIGTERM");
+    }
+    running.delete(id);
+    return { content: `Stopped ${id}.`, summary: `stopped ${id}` };
+}
+/** Everything still running, stopped. Called when a session ends, so a job that
+ *  started a dev server does not leave it holding a port after the person has
+ *  closed the terminal. */
+function stopEverything() {
+    for (const id of Array.from(running.keys()))
+        stopProcess(id);
+}
+// ── the tests ───────────────────────────────────────────────────────────────
+/** How this project runs its tests, worked out from what is in it.
+ *
+ *  Ordered by how specific the evidence is. A `test` script in package.json is
+ *  a statement by the project's own authors; the presence of a pytest.ini is an
+ *  inference. Guessing wrong is cheap here because the result says what it ran.
+ */
+/** Whether this folder holds Python tests, by their conventional names.
+ *
+ *  `test_x.py` and `x_test.py` are the two names pytest collects by default, so
+ *  a folder containing either is a folder pytest can run. Deliberately shallow:
+ *  one directory read, no walk, because this is a guess made before every test
+ *  run and a recursive scan of somebody's repository is not.
+ */
+function looksLikePython(root) {
+    try {
+        return fs.readdirSync(root).some((name) => /^test_.*\.py$/.test(name) || /.*_test\.py$/.test(name));
+    }
+    catch {
+        // An unreadable project directory is a different problem, and it will be
+        // reported by whatever tries to read a file next.
+        return false;
+    }
+}
+function guessTestCommand(root) {
+    const has = (f) => fs.existsSync(path.join(root, f));
+    const pkgPath = path.join(root, "package.json");
+    if (has("package.json")) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+            if (pkg.scripts?.test) {
+                return has("pnpm-lock.yaml") ? "pnpm test"
+                    : has("yarn.lock") ? "yarn test" : "npm test";
+            }
+        }
+        catch { /* a malformed package.json is not our problem to report here */ }
+    }
+    if (has("pytest.ini") || has("pyproject.toml") || has("tests") || has("setup.cfg")) {
+        return "python -m pytest -q";
+    }
+    // A project identified by its TEST FILES rather than by a configuration file.
+    // A plain folder of `test_*.py` with no `pyproject.toml` is an entirely normal
+    // Python project and was not recognized, so `run_tests` refused and the model
+    // had to work out the command itself. It did, and it cost a step and an
+    // approval on a job that was otherwise clean. Found by watching a real run in
+    // the desktop app.
+    //
+    // One shallow directory read, and only when nothing above matched.
+    if (looksLikePython(root))
+        return "python -m pytest -q";
+    if (has("Cargo.toml"))
+        return "cargo test";
+    if (has("go.mod"))
+        return "go test ./...";
+    if (has("Gemfile"))
+        return "bundle exec rspec";
+    if (has("pom.xml"))
+        return "mvn -q test";
+    if (has("build.gradle") || has("build.gradle.kts"))
+        return "gradle test";
+    return null;
+}
+async function runTests(opts) {
+    const root = fs.realpathSync(opts.root);
+    let command = opts.command?.trim() || guessTestCommand(root) || "";
+    if (!command) {
+        return {
+            isError: true,
+            content: "I could not work out how this project runs its tests. Tell me the " +
+                "command and I will use it from now on.",
+        };
+    }
+    if (opts.path)
+        command = `${command} ${(0, paths_1.resolveInside)(root, opts.path, false)}`;
+    const result = await runCommand(command, { ...opts, timeoutMs: opts.timeoutMs ?? 600_000 });
+    const passed = /^exit 0\b/.test(result.content);
+    return {
+        ...result,
+        passed,
+        command,
+        // The verdict first, in words, before the output. This result is read by a
+        // model deciding whether it has finished, and burying "exit 1" under two
+        // hundred lines of test output is how a job declares success on a red suite.
+        content: `${passed ? "TESTS PASSED" : "TESTS FAILED"} (${command})\n\n${result.content}`,
+        summary: `${passed ? "tests passed" : "tests failed"}: ${command}`,
+    };
+}

package/out/graph/build.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Turn a folder of source files into code map facts, on the machine that holds
+ * them.
+ *
+ * Reading is the only part of the map that happens here. The joining, the
+ * storing and the answering all happen in the service, because a client that
+ * joined the map would be a client holding an opinion, and because a map that
+ * lived on one laptop could not be read by the same person's editor an hour
+ * later.
+ */
+import type { FactSet } from "./facts";
+import { IndexedFile } from "./files";
+export interface ReadResult {
+    /** One entry per file successfully read. */
+    facts: Record<string, FactSet>;
+    failures: {
+        file: string;
+        reason: string;
+    }[];
+    /** Files present in the project that no reader on this machine can read. */
+    unread: {
+        python: number;
+        typescript: number;
+    };
+    seconds: number;
+}
+/** What this machine can read at all, said plainly and once. */
+export declare function readers(): {
+    python: boolean;
+    typescript: boolean;
+};
+/** Read the named files. Everything when `rels` is absent. */
+export declare function readFacts(root: string, rels?: string[], knownNames?: string[]): ReadResult;
+export interface ProjectState {
+    files: IndexedFile[];
+    stamps: Record<string, string>;
+    fingerprint: {
+        hash: string;
+        files: number;
+    };
+    commit: string;
+}
+/** What the project looks like right now: which files, and one short string
+ *  that changes the moment any of them does. Costs about ten milliseconds. */
+export declare function projectState(root: string): ProjectState;

package/out/graph/build.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readers = readers;
+exports.readFacts = readFacts;
+exports.projectState = projectState;
+const files_1 = require("./files");
+const read_locales_1 = require("./read-locales");
+const read_python_1 = require("./read-python");
+const read_typescript_1 = require("./read-typescript");
+/** What this machine can read at all, said plainly and once. */
+function readers() {
+    return {
+        python: Boolean(require("./read-python").findPython()),
+        typescript: Boolean((0, read_typescript_1.loadCompiler)()),
+    };
+}
+/**
+ * Drop the calls that could never resolve to anything in this project.
+ *
+ * Two thirds of the raw facts read from a real 1,816 file project were calls to
+ * names the project does not define: `len`, `push`, `map`, and every library
+ * function anybody imported. The service discards every one of them when it
+ * joins the map, so sending and storing them is pure waste, measured at 17.8
+ * megabytes of 26.6.
+ *
+ * `known` is what the project already defines, which the service sends back
+ * with the file stamps, plus whatever the files just read define themselves.
+ * Nothing is dropped that the service would have kept: the join applies the same
+ * rule, only later. Correctness never depends on this, only size.
+ */
+function prune(facts, known) {
+    const droppable = new Set(["calls", "references"]);
+    for (const rel of Object.keys(facts)) {
+        const entry = facts[rel];
+        if (!entry)
+            continue;
+        entry.links = entry.links.filter((link) => {
+            if (!droppable.has(link.kind))
+                return true;
+            const leaf = String(link.to_name ?? "").split(".").pop() ?? "";
+            return known.has(leaf);
+        });
+    }
+}
+/** Read the named files. Everything when `rels` is absent. */
+function readFacts(root, rels, knownNames) {
+    const started = Date.now();
+    const all = (0, files_1.indexedFiles)(root);
+    const wanted = rels ? new Set(rels) : null;
+    const chosen = wanted ? all.filter((f) => wanted.has(f.rel)) : all;
+    const py = chosen.filter((f) => f.lang === "python").map((f) => f.rel);
+    const ts = chosen.filter((f) => f.lang === "typescript").map((f) => f.rel);
+    const locales = chosen.filter((f) => f.lang === "translations").map((f) => f.rel);
+    const fromPython = (0, read_python_1.readPython)(root, py);
+    const fromTs = (0, read_typescript_1.readTypeScript)(root, ts);
+    // Translation files need no compiler and no interpreter, so they are always
+    // read: a machine missing Python still gets its labels mapped.
+    const fromLocales = (0, read_locales_1.readLocales)(root, locales);
+    const facts = { ...fromPython.facts, ...fromTs.facts, ...fromLocales.facts };
+    // Everything the files just read define, plus everything the service already
+    // knows this project defines. A name on neither list cannot resolve.
+    const known = new Set(knownNames ?? []);
+    for (const entry of Object.values(facts)) {
+        for (const object of entry.objects) {
+            if (object.kind === "file" || object.kind === "route" || object.kind === "table")
+                continue;
+            const leaf = String(object.name).split(".").pop();
+            if (leaf)
+                known.add(leaf);
+        }
+    }
+    prune(facts, known);
+    return {
+        facts,
+        failures: [...fromPython.failures, ...fromTs.failures, ...fromLocales.failures],
+        unread: {
+            python: fromPython.available ? 0 : py.length,
+            typescript: fromTs.available ? 0 : ts.length,
+        },
+        seconds: Math.round((Date.now() - started) / 100) / 10,
+    };
+}
+/** What the project looks like right now: which files, and one short string
+ *  that changes the moment any of them does. Costs about ten milliseconds. */
+function projectState(root) {
+    const files = (0, files_1.indexedFiles)(root);
+    const stamps = {};
+    for (const file of files)
+        stamps[file.rel] = (0, files_1.stampOf)(file);
+    return { files, stamps, fingerprint: (0, files_1.fingerprint)(files), commit: (0, files_1.headCommit)(root) };
+}