@debugai/mcp 2.4.2 → 2.5.0

package/dist/workspaceFacts.d.ts

@@ -0,0 +1,336 @@
+/**
+ * What the editor can SEE about this workspace, sent as facts the engine reads.
+ *
+ * ## The hole this fills
+ *
+ * Every wrong answer in the 2026-09-10 production read needed one fact that is
+ * not in the traceback and never can be, because it is a property of the
+ * machine rather than of the error:
+ *
+ *     No module named 'ip_connection_monitor'  ->  "pip install ip_connection_monitor"
+ *          the fact:  that name is a .py file sitting in their own project
+ *
+ *     No module named 'numpy'  x3, one user, three days  ->  "pip install numpy"
+ *          the fact:  numpy was installed the whole time, under another interpreter
+ *
+ *     import Flask, jsonify, ...  ->  "pip install Flask"
+ *          the fact:  flask is declared in their own requirements.txt
+ *
+ * The engine is server-side and will never touch a user's disk. The extension
+ * is already ON that disk — and has been reading `package.json`,
+ * `requirements.txt` and `pyproject.toml` since v2.1, at
+ * `detectWorkspaceFramework()`, purely to guess a one-word framework label. It
+ * has been reading the right files for the smallest possible purpose.
+ *
+ * Nothing here executes anything. Every field is a file read or a read-only
+ * VS Code API call, which is what an editor extension already is, so there is
+ * no new permission, no consent prompt and no new execution path. Running a
+ * command is a separate decision with a separate threat model (see the note on
+ * Tier 2 at the bottom) and deliberately not this module.
+ *
+ * ## The one law: observations, never classifications
+ *
+ * This module reports what is on disk. It never concludes what it means.
+ * "`ip_connection_monitor` is one of your files" and "install it" are both
+ * decisions, and decisions live in the engine — beside the error pattern that
+ * raised the question, in one place, where they already are.
+ *
+ * That is not style. It is the same law as Critical Rule 10 (the waitlist never
+ * trusts a client-computed privilege field) and the attribution rule (the client
+ * reports src and referrer, the SERVER computes `medium`). Applied here it also
+ * buys something concrete: the name normalisation that decides whether
+ * `python-dotenv` matches `python_dotenv` exists in exactly one file, so there
+ * is no cross-boundary copy to drift and no parity test to keep (Rule 15b).
+ *
+ * ## The other law: a capped list cannot prove an absence
+ *
+ * `local_modules` and `declared_deps` are capped, because a monorepo has
+ * thousands of files and this rides on a request a user is waiting for. A cap
+ * is the difference between "numpy is not one of your files" and "numpy is not
+ * in the first 600 of your files", and answering the first when you only know
+ * the second is how a confident wrong answer gets built.
+ *
+ * So every list that might be short names itself in `incomplete`, and the
+ * engine may draw a POSITIVE conclusion from any list (the name is there, so it
+ * exists) but a NEGATIVE one only from a list that is not listed there. Same
+ * judgement as MIN_SAMPLE in scanFindings and MIN_COHORT in attribution: an
+ * instrument that cannot say "I do not know" will say something false instead.
+ *
+ * Pure: no `vscode` import, no I/O. The caller supplies the file contents and
+ * the directory listings, which is what makes the whole thing testable with no
+ * editor — same split as `scanCandidates.ts` and `errorPaths.ts`.
+ *
+ * ## MIRRORED, byte for byte, in two other places
+ *
+ *     packages/mcp/src/workspaceFacts.ts          (published to npm, standalone)
+ *     apps/extension/src/mcp/workspaceFacts.ts    (bundled MCP server)
+ *
+ * This file has ZERO imports, which is what makes a byte-identical copy the
+ * whole of the solution rather than the start of a divergence. `npm publish`
+ * cannot reach into `apps/`, so the copies are not optional (Rule 15b).
+ *
+ * Do not edit a copy. Edit THIS file and re-copy:
+ *
+ *     cp apps/extension/src/workspaceFacts.ts packages/mcp/src/workspaceFacts.ts
+ *     cp apps/extension/src/workspaceFacts.ts apps/extension/src/mcp/workspaceFacts.ts
+ *
+ * `mcp/drift.test.ts` compares all three as text and fails on any difference,
+ * headers included - deliberately stricter than the other mirrored modules,
+ * because this one has no import line to anchor a partial comparison to.
+ */
+/** A list whose absence-of-a-name means nothing. See the module docstring. */
+export type IncompleteList = 'declared_deps' | 'local_modules';
+export interface WorkspaceFacts {
+    /**
+     * Dependency names exactly as the manifests spell them — `python-dotenv`,
+     * `@babel/core`, `Flask`. NOT normalised: normalising is comparing, and
+     * comparing is the engine's job (see the law above).
+     */
+    declared_deps: string[];
+    /**
+     * Version as the manifest SPELLS it, keyed by the same raw name:
+     * `{"Yarp.ReverseProxy": "2.3.0", "react": "^18.2.0", "flask": ">=3"}`.
+     *
+     * Not resolved, and that is the point. `2.3.0` is a fact about what is
+     * installed; `^18.2.0` is a fact about what is ALLOWED, and the difference
+     * is information the engine needs - on 2026-09-12 we told a user to call
+     * `.AddPassiveHealthCheckPolicies()` on YARP at confidence 92 and the
+     * method does not exist in the 2.3.0 their own .csproj declares. An exact
+     * pin can settle that question; a range cannot, and the engine must be able
+     * to tell which one it has.
+     *
+     * A name declared in two manifests with two versions keeps the first seen.
+     * The alternative is a list per name, which costs the whole shape for a
+     * case (one package, two versions, one workspace) that is itself a bug.
+     */
+    declared_versions: Record<string, string>;
+    /**
+     * Which manifest files those names came from, relative to the root. Load
+     * bearing: an empty `declared_deps` means "declares nothing" when a
+     * manifest was read and "we found no manifest" when this is empty, and
+     * those support opposite conclusions.
+     */
+    manifests: string[];
+    /**
+     * Every name in this workspace that Python could import as a top-level
+     * module: `foo.py` -> `foo`, `foo/__init__.py` -> `foo`. Deduped across
+     * directories, because `sys.path[0]` is the running script's own directory
+     * and a sibling module is importable from there without being at the root.
+     */
+    local_modules: string[];
+    /** Root directories that look like a virtualenv: `.venv`, `venv`, `env`. */
+    venv_dirs: string[];
+    /** A `node_modules` directory exists at the workspace root. */
+    has_node_modules: boolean;
+    /**
+     * The interpreter VS Code currently has selected, from the Python
+     * extension's read-only environments API. `null` when the Python extension
+     * is not installed, not activated, or has no selection — three states that
+     * mean "we do not know", never "there isn't one".
+     */
+    python_interpreter: string | null;
+    /** Lists that may be missing entries. Absence from one of these proves nothing. */
+    incomplete: IncompleteList[];
+}
+/**
+ * Caps. Chosen so an ordinary project is never truncated and a monorepo is
+ * truncated honestly rather than slowly. `findFiles` is given `cap + 1` so the
+ * overflow is detected exactly rather than guessed at the boundary.
+ */
+export declare const MAX_DECLARED_DEPS = 400;
+/** Versions are only kept for names that survived the dep cap. */
+export declare const MAX_VERSION_LENGTH = 60;
+export declare const MAX_LOCAL_MODULES = 600;
+/**
+ * Dependency names declared in a `package.json`, across all four dependency
+ * fields.
+ *
+ * `peerDependencies` and `optionalDependencies` are included on purpose: a
+ * `Cannot find module` for a peer dep is a real and common shape (the package
+ * is declared, expects you to install it, and nothing did), and leaving them
+ * out would make the engine conclude "not declared" about a name that is.
+ *
+ * Never throws. A malformed `package.json` is itself a plausible thing to be
+ * debugging, and losing the whole fact set to it would be absurd.
+ */
+export declare function depsFromPackageJson(text: string): string[];
+/**
+ * Package names from a `requirements.txt`.
+ *
+ * A requirements line carries far more than a name — version specifiers,
+ * extras, environment markers, hashes, editable installs, includes, direct
+ * URLs — and every one of those forms appears in real projects. The name is
+ * whatever survives stripping them, and a line with no name left (a bare `-r
+ * base.txt`, a comment, a flag) contributes nothing rather than contributing
+ * garbage.
+ *
+ * `-r other.txt` is NOT followed. Following it would need another file read
+ * driven by content we just parsed, and the honest alternative is cheaper: the
+ * caller marks `declared_deps` incomplete, so a name missing from the list
+ * proves nothing, which is exactly the truth about a split requirements file.
+ */
+export declare function depsFromRequirements(text: string): {
+    deps: string[];
+    sawInclude: boolean;
+};
+/**
+ * Package names from a `pyproject.toml`, without a TOML parser.
+ *
+ * Bundling one would be the honest engineering answer if the names had to be
+ * exact. They do not: a name that survives this is real (a positive conclusion,
+ * always safe), and a name this misses is covered by the caller marking the
+ * list incomplete (so no negative conclusion is drawn from it). That trade buys
+ * out a dependency in a bundle that ships to 652 installs.
+ *
+ * Two shapes, which between them cover almost every real file:
+ *
+ *     [project]                      PEP 621, the modern default
+ *     dependencies = ["flask>=3", "python-dotenv"]
+ *
+ *     [tool.poetry.dependencies]     poetry, still very common
+ *     flask = "^3.0"
+ *
+ * `found` is false when the file exists but neither shape was recognised —
+ * pdm, hatch's dynamic metadata, a dependency-groups-only file. The caller
+ * needs that to be a different state from "no pyproject at all", because one
+ * means "we could not read the declarations" and the other means "there are
+ * none to read".
+ */
+export declare function depsFromPyproject(text: string): {
+    deps: string[];
+    found: boolean;
+};
+/**
+ * Versions from a `package.json`, keyed by dependency name.
+ *
+ * A SEPARATE pass rather than a change to `depsFromPackageJson`, on purpose.
+ * That function's contract and its tests are shipped and correct; widening a
+ * return type to carry a new field is how a working parser acquires a
+ * regression. These files are small and already capped, so the second pass
+ * costs nothing measurable.
+ */
+export declare function versionsFromPackageJson(text: string): Record<string, string>;
+/**
+ * Versions from a `requirements.txt`, keyed by package name.
+ *
+ * Keeps the whole specifier as written - `==3.0.0`, `>=2,<3`, `~=1.4` - because
+ * `==` is a fact about what IS installed and `>=` is a fact about what is
+ * allowed, and collapsing them would throw away the distinction the engine
+ * needs most.
+ *
+ * A line with no specifier contributes a NAME (via `depsFromRequirements`) and
+ * no version, which is honest: `flask` on its own line pins nothing.
+ *
+ * Never reads an `--index-url`. Those carry credentials in real projects
+ * (`https://user:token@pypi.internal/simple`) and a package's version is never
+ * on that line anyway.
+ */
+export declare function versionsFromRequirements(text: string): Record<string, string>;
+/**
+ * Versions from a `pyproject.toml`, keyed by package name.
+ *
+ * Same two shapes `depsFromPyproject` recognises, and the same trade: a version
+ * this finds is real, and one it misses simply is not reported. `declared_deps`
+ * already carries `incomplete` for the negative case, and a missing VERSION is
+ * never read as "no version constraint" - only as "we did not see one".
+ */
+export declare function versionsFromPyproject(text: string): Record<string, string>;
+/**
+ * Package names and versions from a .NET project file (`.csproj` / `.fsproj`).
+ *
+ * The manifest that would have prevented 2026-09-12. Four consecutive answers
+ * guessed at `Elastic.Clients.Elasticsearch` constructor signatures and a fifth
+ * invented `.AddPassiveHealthCheckPolicies()` on YARP - while the user's own
+ * project file said `Version="2.3.0"` the entire time, and their error text
+ * even quoted it back to us.
+ *
+ * .NET pins are usually EXACT, which makes this the highest-value manifest in
+ * the set: `<PackageReference Include="X" Version="2.3.0" />` settles "does
+ * this method exist" in a way `^18.2.0` never can.
+ *
+ * Two spellings, both common and both emitted by `dotnet add package`:
+ *
+ *     <PackageReference Include="X" Version="2.3.0" />
+ *     <PackageReference Include="X"><Version>2.3.0</Version></PackageReference>
+ *
+ * Regex rather than an XML parser, for the same reason `depsFromPyproject`
+ * avoids a TOML parser: a name this finds is real, a name it misses is covered
+ * by `incomplete`, and neither justifies a dependency in a bundle that ships to
+ * every install. Attribute order is not assumed - `Version` before `Include`
+ * is legal and real.
+ */
+export declare function depsFromCsproj(text: string): {
+    deps: string[];
+    versions: Record<string, string>;
+};
+/**
+ * The top-level module name a Python file would be imported by, or null.
+ *
+ * `a/b/foo.py` -> `foo`, `a/b/foo/__init__.py` -> `foo`. A dunder file other
+ * than `__init__` (`__main__.py`, `__about__.py`) names no importable module
+ * and is dropped, so it cannot be mistaken for one.
+ */
+export declare function moduleNameForPath(relPath: string): string | null;
+/** Raw inputs, exactly as the editor hands them over. Every field optional. */
+export interface FactInputs {
+    packageJson?: string | null;
+    requirementsTxt?: string | null;
+    pyprojectToml?: string | null;
+    /**
+     * Contents of every .NET project file found, newest-irrelevant order. A
+     * list because a solution has one per project and the error can come from
+     * any of them - salman's repo had six.
+     */
+    csprojFiles?: string[];
+    /** True when the caller stopped looking for .csproj files before exhausting them. */
+    csprojTruncated?: boolean;
+    /** Workspace-relative paths of every `.py` file the caller found. */
+    pythonFiles?: string[];
+    /** True when the caller's file search hit its own limit. */
+    pythonFilesTruncated?: boolean;
+    /** Root directory names the caller saw. */
+    rootDirs?: string[];
+    /** From the Python extension's environments API. */
+    pythonInterpreter?: string | null;
+}
+/**
+ * Assemble the facts. Total function: any subset of inputs, no throw.
+ *
+ * Every list is deduped and sorted before capping, so what survives a cap is
+ * stable across requests rather than dependent on filesystem walk order — a
+ * cache key reads this, and a set that reshuffles per request would miss the
+ * cache every time on exactly the large workspaces where a miss costs most.
+ */
+export declare function buildWorkspaceFacts(input: FactInputs): WorkspaceFacts;
+/**
+ * True when these facts carry nothing the engine could act on.
+ *
+ * An empty fact set is not neutral: it costs bytes on every request, and — far
+ * worse — it takes part in the response cache key, so sending an all-empty
+ * object from a window with no folder open would split the cache between
+ * "no facts" and "no facts, spelled out" for no gain. Send nothing instead.
+ */
+export declare function factsAreEmpty(f: WorkspaceFacts): boolean;
+/**
+ * NOT IN THIS MODULE, on purpose: anything that runs.
+ *
+ * `python -c "import sys; print(sys.executable)"` settles the wrong-interpreter
+ * case outright, and `python_interpreter` above only reports what VS Code has
+ * SELECTED — which is the right answer for a Run button and not necessarily the
+ * interpreter that produced a traceback pasted from an external terminal.
+ *
+ * Closing that gap means executing something, and the 2026 record of agentic
+ * tools is unambiguous about how that goes wrong: every published incident is a
+ * variant of one mistake, treating a command STRING as data. Aider ran a
+ * repo-supplied `test-cmd` at startup (#5254). Claude Code's allowlist admitted
+ * `man --html="touch ..."` (CVE-2025-66032). Cursor's approval dialog showed a
+ * workspace path while the write followed a symlink to `~/.ssh/authorized_keys`
+ * (CVE-2026-50549).
+ *
+ * So when Tier 2 lands, the server names a PROBE and its parameters from a
+ * catalog this client owns — `{probe: "interpreter"}`, never a command string —
+ * the client maps that to argv it wrote itself, and an unknown probe name is
+ * refused rather than passed through. That is the difference between MCP
+ * elicitation and every incident above, and it is a different module with a
+ * consent gate, not a quiet extension of this one.
+ */