pi-python-helper 0.1.1 → 0.2.0

package/src/environment/discovery.ts

@@ -4,13 +4,19 @@ import { findProjectRoot, findVenvDir, isFile } from '../project/root.ts';
 import {
   type EnvironmentSection,
   type LockPackage,
-  resolveInterpreter,
+  resolveProjectInterpreter,
   runScanProject,
 } from '../project/scanner.ts';
 import { inspectTools, type ToolAvailability } from './tools.ts';
 
 export interface PythonEnvironment {
   interpreter?: string;
+  /**
+   * Whether the analysed interpreter belongs to the project environment or was
+   * taken from PATH. Analysis facts such as `site-packages` contents and the
+   * reported version are only the project's when this is `venv`.
+   */
+  interpreterOrigin?: 'venv' | 'path';
   python?: EnvironmentSection;
   projectRoot?: string;
   venvDir?: string;
@@ -57,12 +63,13 @@ export async function detectPythonEnvironment(
 ): Promise<PythonEnvironment> {
   const warnings: Diagnostic[] = [];
   const suggestions: string[] = [];
-  const interpreter = await resolveInterpreter(cwd, signal);
   const projectRoot = await findProjectRoot(cwd);
   const scanRoot = projectRoot ?? cwd;
 
   let python: EnvironmentSection | undefined;
   let lockPackages: LockPackage[] = [];
+  const resolved = await resolveProjectInterpreter(scanRoot, cwd, signal);
+  const interpreter = resolved.interpreter;
   if (interpreter) {
     const scan = await runScanProject(
       cwd,
@@ -79,7 +86,7 @@ export async function detectPythonEnvironment(
     warnings.push(
       warn(
         'PYTHON_NOT_FOUND',
-        'No Python 3 interpreter was found on PATH; every analysis tool degrades to static inspection only.',
+        'No Python 3 interpreter was found in the project environment or on PATH; every analysis tool degrades to static inspection only.',
       ),
     );
     suggestions.push('Install Python 3.11 or newer so pyproject.toml and uv.lock can be parsed.');
@@ -101,6 +108,25 @@ export async function detectPythonEnvironment(
   const lockPresent = projectRoot ? await isFile(`${projectRoot}/uv.lock`) : false;
   const tools = await inspectTools({ venvDir, lockPackages });
 
+  // A distribution recorded in the lockfile is installable, not installed. When
+  // the project environment exists but a declared tool has no console script,
+  // the environment was synced without it and every later step that needs it
+  // will fail, so this is reported rather than left to be discovered later.
+  const missingDeclaredTools = venvDir ? tools.filter((tool) => tool.installable) : [];
+  if (missingDeclaredTools.length > 0) {
+    const names = missingDeclaredTools.map((tool) => tool.name).join(', ');
+    warnings.push(
+      warn(
+        'TOOL_NOT_INSTALLED',
+        `${names} ${missingDeclaredTools.length === 1 ? 'is' : 'are'} recorded in uv.lock but has no executable in .venv, so it cannot be run right now.`,
+        venvDir,
+      ),
+    );
+    suggestions.push(
+      'Run uv sync --frozen --all-groups --all-extras: a plain uv sync removes extras declared in [project.optional-dependencies].',
+    );
+  }
+
   const uvVersion = await toolVersion(cwd, 'uv', signal);
   if (!uvVersion) {
     warnings.push(
@@ -155,6 +181,7 @@ export async function detectPythonEnvironment(
 
   return {
     interpreter,
+    interpreterOrigin: resolved.origin,
     python,
     projectRoot,
     venvDir,

package/src/environment/tools.ts

@@ -22,10 +22,20 @@ export type ToolVersionSource = 'lock' | 'cli' | 'unknown';
 
 export interface ToolAvailability {
   name: string;
-  /** True when the tool is runnable, either locally or through `uv run`. */
+  /**
+   * True only when a runnable executable was found right now.
+   *
+   * A distribution recorded in `uv.lock` is *installable*, not available: the
+   * environment may have had it removed. Reporting it as available made a
+   * broken virtual environment look healthy.
+   */
   available: boolean;
   /** True when `uv.lock` records the distribution, so `uv sync` can install it. */
   declared: boolean;
+  /** True when `uv sync` would provide the tool that is not runnable yet. */
+  installable: boolean;
+  /** True when the console script was found inside the project environment. */
+  installed: boolean;
   /** Absolute path when an executable was found. */
   executable?: string;
   /** Where the executable was found: the project environment or the host PATH. */
@@ -128,8 +138,10 @@ export async function inspectTools(input: ToolProbeInput = {}): Promise<ToolAvai
 
       return {
         name,
-        available: Boolean(executable) || lockVersion !== undefined,
+        available: Boolean(executable),
         declared: lockVersion !== undefined,
+        installable: lockVersion !== undefined && !executable,
+        installed: venvScript !== undefined,
         executable,
         origin,
         version: lockVersion,
@@ -139,3 +151,30 @@ export async function inspectTools(input: ToolProbeInput = {}): Promise<ToolAvai
     }),
   );
 }
+
+export interface RequiredToolCheck {
+  /** False when there was no project environment to inspect at all. */
+  checked: boolean;
+  venvDir?: string;
+  /** Names with no console script in the project environment. */
+  missing: string[];
+}
+
+/**
+ * Confirm that the tools a later step depends on are runnable *now*.
+ *
+ * `uv sync` can legitimately finish with exit code 0 while removing the very
+ * tools the next step needs, so the environment is re-checked between the two
+ * instead of trusting the exit code.
+ */
+export async function checkRequiredTools(
+  venvDir: string | undefined,
+  names: readonly string[],
+): Promise<RequiredToolCheck> {
+  if (!venvDir) return { checked: false, missing: [] };
+  const missing: string[] = [];
+  for (const name of names) {
+    if (!(await findVenvScript(venvDir, name))) missing.push(name);
+  }
+  return { checked: true, venvDir, missing };
+}

package/src/project/conformance.ts

@@ -50,6 +50,12 @@ export interface ConformanceReport {
     installedScanned: boolean;
     projectInstalled: boolean | null;
     projectEditable: boolean | null;
+    /**
+     * False when the root project is a `virtual` lock source, which uv creates
+     * for a project without a `[build-system]` table. Such a project is never
+     * installed into `.venv`, so its absence is expected rather than drift.
+     */
+    projectInstallable: boolean | null;
   };
   counts: {
     lockPackages: number;
@@ -59,6 +65,11 @@ export interface ConformanceReport {
     /** Locked entries that are conditional for this platform and correctly absent. */
     conditional: number;
     untracked: number;
+    /**
+     * Normalized names that uv.lock pins more than once (a marker split, such as
+     * `argon2-cffi-bindings` at 21.2.0 for Python 3.14 and 25.1.0 below it).
+     */
+    markerSplitNames: number;
   };
   findings: ConformanceFinding[];
   warnings: Diagnostic[];
@@ -147,6 +158,7 @@ export function compareInstalledConformance(input: ConformanceInput): Conformanc
     installedScanned: venvPresent,
     projectInstalled: null as boolean | null,
     projectEditable: null as boolean | null,
+    projectInstallable: null as boolean | null,
   };
   const counts = {
     lockPackages: lock?.packages.length ?? 0,
@@ -155,6 +167,7 @@ export function compareInstalledConformance(input: ConformanceInput): Conformanc
     missing: 0,
     conditional: 0,
     untracked: 0,
+    markerSplitNames: 0,
   };
 
   for (const message of installed?.warnings ?? []) {
@@ -189,51 +202,83 @@ export function compareInstalledConformance(input: ConformanceInput): Conformanc
   const lockByNormalized = new Map(lock.packages.map((entry) => [entry.normalized, entry]));
   const required = requiredInstalledNames(lock, new Set(installedByNormalized.keys()), input);
   const conditionalAbsent: string[] = [];
+  const markerSplitNames: string[] = [];
+  const virtualRoots: string[] = [];
 
+  // uv writes one lock entry per marker branch, so a name can appear several
+  // times with different versions. Comparing a single arbitrary entry reported a
+  // version mismatch on a correctly synced environment (21.2.0 is locked for
+  // Python 3.14 while a 3.12 environment rightly has 25.1.0).
+  const variantsByNormalized = new Map<string, LockPackage[]>();
   for (const entry of lock.packages) {
-    const actual = installedByNormalized.get(entry.normalized);
-    const localProject = isLocalProjectEntry(entry);
-    const rootProject = isRootProjectEntry(entry, projectName);
+    const variants = variantsByNormalized.get(entry.normalized);
+    if (variants) variants.push(entry);
+    else variantsByNormalized.set(entry.normalized, [entry]);
+  }
+
+  for (const [normalized, variants] of variantsByNormalized) {
+    const primary = variants[0];
+    const actual = installedByNormalized.get(normalized);
+    const localProject = variants.some((variant) => isLocalProjectEntry(variant));
+    const rootProject = variants.some((variant) => isRootProjectEntry(variant, projectName));
+    if (variants.length > 1) {
+      counts.markerSplitNames += 1;
+      markerSplitNames.push(primary.name);
+    }
 
     if (!actual) {
       if (localProject) {
+        if (rootProject && variants.some((variant) => variant.source === 'virtual')) {
+          // Without a [build-system] uv records the project as a virtual source
+          // and never installs it; its absence from .venv is not drift.
+          checks.projectInstalled = false;
+          checks.projectInstallable = false;
+          virtualRoots.push(primary.name);
+          continue;
+        }
         counts.missing += 1;
         if (rootProject) checks.projectInstalled = false;
         findings.push({
           code: 'PROJECT_NOT_INSTALLED',
-          name: entry.name,
-          expected: entry.version ?? undefined,
+          name: primary.name,
+          expected: primary.version ?? undefined,
           message: rootProject
-            ? `uv.lock records "${entry.name}" as an editable install, but it is absent from .venv. The project is not importable and no test can exercise it.`
-            : `uv.lock records the local project "${entry.name}" as an editable install, but it is absent from .venv.`,
+            ? `uv.lock records "${primary.name}" as an editable install, but it is absent from .venv. The project is not importable and no test can exercise it.`
+            : `uv.lock records the local project "${primary.name}" as an editable install, but it is absent from .venv.`,
         });
-      } else if (required.has(entry.normalized)) {
+      } else if (required.has(normalized)) {
         counts.missing += 1;
         findings.push({
           code: 'INSTALLED_PACKAGE_MISSING',
-          name: entry.name,
-          expected: entry.version ?? undefined,
-          message: `"${entry.name}" is locked and required unconditionally, but it is not installed in .venv.`,
+          name: primary.name,
+          expected: primary.version ?? undefined,
+          message: `"${primary.name}" is locked and required unconditionally, but it is not installed in .venv.`,
         });
       } else {
         // Guarded by a platform or version marker, so this platform rightly omits it.
-        counts.conditional += 1;
-        conditionalAbsent.push(`${entry.name}@${entry.version ?? '?'}`);
+        counts.conditional += variants.length;
+        for (const variant of variants) {
+          const label = `${primary.name}@${variant.version ?? '?'}`;
+          if (!conditionalAbsent.includes(label)) conditionalAbsent.push(label);
+        }
       }
       continue;
     }
 
     if (localProject) {
-      if (rootProject) checks.projectInstalled = true;
+      if (rootProject) {
+        checks.projectInstalled = true;
+        checks.projectInstallable = true;
+      }
       if (actual.source !== 'editable') {
         if (rootProject) checks.projectEditable = false;
         findings.push({
           code: 'PROJECT_INSTALLED_NOT_EDITABLE',
-          name: entry.name,
+          name: primary.name,
           actual: actual.version,
           message: rootProject
-            ? `"${entry.name}" is installed from a materialised copy instead of an editable link, so tests would import a stale snapshot of the sources.`
-            : `The local project "${entry.name}" is installed from a materialised copy instead of an editable link.`,
+            ? `"${primary.name}" is installed from a materialised copy instead of an editable link, so tests would import a stale snapshot of the sources.`
+            : `The local project "${primary.name}" is installed from a materialised copy instead of an editable link.`,
         });
       } else if (rootProject) {
         checks.projectEditable = true;
@@ -243,16 +288,31 @@ export function compareInstalledConformance(input: ConformanceInput): Conformanc
       continue;
     }
 
-    if (entry.version && actual.version !== entry.version) {
-      counts.mismatched += 1;
-      findings.push({
-        code: 'INSTALLED_VERSION_MISMATCH',
-        name: entry.name,
-        expected: entry.version,
-        actual: actual.version,
-        message: `"${entry.name}" is locked at ${entry.version} but ${actual.version} is installed in .venv.`,
+    // Matching any locked variant is positive proof the environment agrees with
+    // the lockfile for the markers that apply here.
+    if (variants.some((variant) => variant.version === actual.version)) continue;
+
+    const versions = variants.map((variant) => variant.version).filter((value) => value !== null);
+    if (versions.length === 0) {
+      notes.push({
+        code: 'LOCKED_VERSION_UNKNOWN',
+        message: `uv.lock records "${primary.name}" without a version, so the installed ${actual.version} could not be compared.`,
+        severity: 'info',
       });
+      continue;
     }
+
+    counts.mismatched += 1;
+    findings.push({
+      code: 'INSTALLED_VERSION_MISMATCH',
+      name: primary.name,
+      expected: versions.join(' | '),
+      actual: actual.version,
+      message:
+        versions.length > 1
+          ? `"${primary.name}" is locked at ${versions.join(' or ')} (marker-dependent) but ${actual.version} is installed in .venv, which matches none of them.`
+          : `"${primary.name}" is locked at ${versions[0]} but ${actual.version} is installed in .venv.`,
+    });
   }
 
   const untrackedCandidates = (installed?.distributions ?? []).filter(
@@ -284,6 +344,22 @@ export function compareInstalledConformance(input: ConformanceInput): Conformanc
     }
   }
 
+  if (markerSplitNames.length > 0) {
+    notes.push({
+      code: 'MARKER_SPLIT_LOCK_ENTRIES',
+      message: `${markerSplitNames.length} distribution(s) are locked more than once because uv splits them by marker (${markerSplitNames.slice(0, 5).join(', ')}${markerSplitNames.length > 5 ? ', …' : ''}); the installed version is compared against every variant and matches when it equals any one of them.`,
+      severity: 'info',
+    });
+  }
+
+  if (virtualRoots.length > 0) {
+    notes.push({
+      code: 'PROJECT_VIRTUAL_SOURCE',
+      message: `uv.lock records "${virtualRoots[0]}" with source = { virtual = "." }, which uv writes for a project without a [build-system] table. It is intentionally never installed into .venv, and imports still resolve from the working directory.`,
+      severity: 'info',
+    });
+  }
+
   if (conditionalAbsent.length > 0) {
     notes.push({
       code: 'CONDITIONAL_PACKAGES_ABSENT',

package/src/project/inspect.ts

@@ -5,6 +5,7 @@ import {
   type ConformanceReport,
 } from './conformance.ts';
 import type { InstalledEnvironment } from './installed.ts';
+import type { PytestConfiguration } from './pytest-config.ts';
 import type { LockComparison, LockSection, ManifestSection, ScanPayload } from './scanner.ts';
 
 export interface ProjectInspection {
@@ -44,6 +45,13 @@ export interface InspectInput {
   /** `undefined` when no .gitignore exists, so the check stays honest. */
   venvIgnored?: boolean;
   hasTestsDirectory: boolean;
+  /** Test directories found relative to the root; names them in the diagnostic. */
+  testDirectories?: string[];
+  /**
+   * Where pytest configuration was found. The scanner only reads
+   * `pyproject.toml`, so INI files are decided by the caller.
+   */
+  pytestConfiguration?: PytestConfiguration;
   /** Distributions read from `.venv`; omit to skip the conformance comparison. */
   installed?: InstalledEnvironment;
 }
@@ -220,6 +228,8 @@ function collectEnvironmentDiagnostics(
   venvDir: string | undefined,
   venvIgnored: boolean | undefined,
   hasTestsDirectory: boolean,
+  testDirectories: string[] | undefined,
+  pytestConfiguration: PytestConfiguration | undefined,
   collector: DiagnosticCollector,
 ): void {
   if (!venvDir) {
@@ -246,15 +256,27 @@ function collectEnvironmentDiagnostics(
     collector.notes.push({
       code: 'TESTS_DIRECTORY_MISSING',
       message:
-        'No tests/ directory was found; test selection and TDD gates cannot match changed sources.',
+        'No tests directory was found in the project root or inside a top-level package, so test selection and TDD gates cannot match changed sources.',
+      severity: 'info',
+    });
+  } else if (testDirectories && testDirectories.length > 0) {
+    collector.notes.push({
+      code: 'TESTS_DIRECTORY_FOUND',
+      message: `Tests live in ${testDirectories.slice(0, 4).join(', ')}${testDirectories.length > 4 ? `, … (+${testDirectories.length - 4})` : ''}. Confirm testpaths covers them when running pytest without a target.`,
       severity: 'info',
     });
   }
 
-  if (manifest?.pyprojectPath && manifest.toolConfiguration && !manifest.toolConfiguration.pytest) {
+  // pytest can be configured from pytest.ini, tox.ini, or setup.cfg, not only
+  // from pyproject.toml; checking one file reported "not configured" for most
+  // projects that use pytest's own configuration file.
+  const pytestConfigured =
+    pytestConfiguration?.configured ?? manifest?.toolConfiguration?.pytest === true;
+  if (manifest?.pyprojectPath && !pytestConfigured) {
     collector.notes.push({
       code: 'PYTEST_NOT_CONFIGURED',
-      message: 'pyproject.toml has no [tool.pytest.ini_options] table.',
+      message:
+        'No pytest configuration was found in pyproject.toml, pytest.ini, tox.ini, or setup.cfg.',
       severity: 'info',
     });
   }
@@ -283,7 +305,15 @@ function collectEnvironmentDiagnostics(
  * whole diagnostic surface is unit-testable without touching a filesystem.
  */
 export function inspectProject(input: InspectInput): ProjectInspection {
-  const { payload, venvDir, venvIgnored, hasTestsDirectory, installed } = input;
+  const {
+    payload,
+    venvDir,
+    venvIgnored,
+    hasTestsDirectory,
+    testDirectories,
+    pytestConfiguration,
+    installed,
+  } = input;
   const manifest = payload.manifest;
   const lock = payload.lock;
   const comparison = payload.lockComparison;
@@ -292,7 +322,16 @@ export function inspectProject(input: InspectInput): ProjectInspection {
   const collector: DiagnosticCollector = { warnings: [], notes: [], suggestions: [] };
   collectManifestDiagnostics(manifest, root, collector);
   collectLockDiagnostics(lock, comparison, collector);
-  collectEnvironmentDiagnostics(root, manifest, venvDir, venvIgnored, hasTestsDirectory, collector);
+  collectEnvironmentDiagnostics(
+    root,
+    manifest,
+    venvDir,
+    venvIgnored,
+    hasTestsDirectory,
+    testDirectories,
+    pytestConfiguration,
+    collector,
+  );
 
   const { warnings, notes, suggestions } = collector;
 
@@ -311,7 +350,7 @@ export function inspectProject(input: InspectInput): ProjectInspection {
     if (conformance.findings.some((finding) => finding.code === 'PROJECT_NOT_INSTALLED')) {
       suggestions.push({
         message:
-          'The project is not installed in .venv. Run uv sync; if that fails, the build backend could not find the package (check that the module directory name matches [project] name).',
+          'The project is recorded as an editable install but is missing from .venv. Run uv sync; if that fails, the build backend could not find the package (check that the module directory name matches [project] name).',
         confidence: 'high',
         command: 'uv sync',
       });

package/src/project/paths.ts

@@ -21,6 +21,21 @@ export function isTestFile(path: string): boolean {
   return TEST_DIRECTORY.test(posix) || TEST_FILENAME.test(posix);
 }
 
+const RUNNABLE_TEST_FILENAME = /^test_.*\.[a-z]+$/i;
+const RUNNABLE_TEST_SUFFIX = /_test\.[a-z]+$/i;
+
+/**
+ * A file pytest actually collects tests from.
+ *
+ * Living under `tests/` is not enough: `tests/__init__.py`, `tests/conftest.py`,
+ * and `tests/utils.py` are test *infrastructure*, and naming them as pytest
+ * targets overstates what the selection covers.
+ */
+export function isRunnableTestFile(path: string): boolean {
+  const name = basename(toPosix(path));
+  return RUNNABLE_TEST_FILENAME.test(name) || RUNNABLE_TEST_SUFFIX.test(name);
+}
+
 export function isSourceFile(path: string): boolean {
   return isPythonFile(path) && !isTestFile(path);
 }

package/src/project/pytest-config.ts

@@ -0,0 +1,45 @@
+/**
+ * Where pytest configuration can live. `pyproject.toml` is read by the scanner
+ * (tomllib) and passed in already-decided; the INI files have to be inspected
+ * here because only `pytest.ini` is unambiguously a pytest file.
+ */
+export interface PytestConfiguration {
+  configured: boolean;
+  /** Files that define pytest configuration, in the order they were checked. */
+  sources: string[];
+}
+
+export interface PytestConfigurationInput {
+  /** True when pyproject.toml has a `[tool.pytest.ini_options]` table. */
+  pyprojectConfigured: boolean;
+  /**
+   * Raw contents of `pytest.ini`, `tox.ini`, and `setup.cfg`, keyed by file
+   * name. A missing key means the file does not exist.
+   */
+  iniFiles: Record<string, string | undefined>;
+}
+
+/** `[pytest]` (pytest.ini) and `[tool:pytest]` (setup.cfg / tox.ini). */
+const PYTEST_SECTION = /^\s*\[(?:tool:)?pytest\]\s*$/m;
+
+/**
+ * Deciding whether pytest is configured used to look at `pyproject.toml`
+ * alone, which reports "not configured" for every project that keeps
+ * `pytest.ini` — the file pytest itself recommends.
+ *
+ * `pytest.ini` counts on existence because it has no other purpose. `tox.ini`
+ * and `setup.cfg` are shared files, so they only count when they actually carry
+ * a pytest section.
+ */
+export function detectPytestConfiguration(input: PytestConfigurationInput): PytestConfiguration {
+  const sources: string[] = [];
+  if (input.pyprojectConfigured) sources.push('pyproject.toml');
+
+  for (const name of ['pytest.ini', 'tox.ini', 'setup.cfg']) {
+    const content = input.iniFiles[name];
+    if (content === undefined) continue;
+    if (name === 'pytest.ini' || PYTEST_SECTION.test(content)) sources.push(name);
+  }
+
+  return { configured: sources.length > 0, sources };
+}

package/src/project/root.ts

@@ -1,4 +1,5 @@
-import { access, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { access, readdir, stat } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 
 /** Files that mark the root of a uv-managed Python project. */
@@ -56,6 +57,89 @@ export async function findVenvDir(root: string): Promise<string | undefined> {
   return (await isDirectory(candidate)) ? candidate : undefined;
 }
 
+const TEST_DIRECTORY_NAMES = new Set(['test', 'tests', 'testing']);
+
+/** Directories that can never contain the project's own tests. */
+const UNSCANNABLE_DIRECTORIES = new Set([
+  '.git',
+  '.venv',
+  'venv',
+  '.tox',
+  '.nox',
+  '__pycache__',
+  'node_modules',
+  'build',
+  'dist',
+  '.eggs',
+  '.mypy_cache',
+  '.ruff_cache',
+  '.pytest_cache',
+]);
+
+/**
+ * Find the directories that hold tests, relative to the project root.
+ *
+ * Looking only for `./tests` misses the common layout where the suite lives
+ * inside the package it tests (`<package>/tests/`), which made the tool claim a
+ * project with hundreds of tests had none.
+ */
+export async function findTestDirectories(root: string, maxDepth = 3): Promise<string[]> {
+  const found: string[] = [];
+  const walk = async (directory: string, relative: string, depth: number): Promise<void> => {
+    let entries;
+    try {
+      entries = await readdir(directory, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+      if (!entry.isDirectory()) continue;
+      const name = entry.name;
+      if (name.startsWith('.')) continue;
+      const childRelative = relative ? `${relative}/${name}` : name;
+      if (TEST_DIRECTORY_NAMES.has(name)) {
+        found.push(childRelative);
+        continue;
+      }
+      if (UNSCANNABLE_DIRECTORIES.has(name)) continue;
+      if (depth < maxDepth) await walk(join(directory, name), childRelative, depth + 1);
+    }
+  };
+  await walk(root, '', 1);
+  return found;
+}
+
+const WINDOWS = process.platform === 'win32';
+
+/**
+ * Locate the interpreter inside a project virtual environment.
+ *
+ * The interpreter that runs the read-only scanner decides which
+ * `site-packages` it can see: a host `python3` maps four modules while the
+ * project's own interpreter maps the whole environment, so asking the wrong one
+ * makes every import name look like it has no providing distribution.
+ */
+export async function findVenvInterpreter(venvDir: string): Promise<string | undefined> {
+  const directories = WINDOWS
+    ? [join(venvDir, 'Scripts'), join(venvDir, 'bin')]
+    : [join(venvDir, 'bin'), join(venvDir, 'Scripts')];
+  const names = WINDOWS ? ['python.exe', 'python'] : ['python', 'python3'];
+  for (const directory of directories) {
+    for (const name of names) {
+      const candidate = join(directory, name);
+      try {
+        const info = await stat(candidate);
+        if (!info.isFile()) continue;
+        if (!WINDOWS) await access(candidate, constants.X_OK);
+        return candidate;
+      } catch {
+        continue;
+      }
+    }
+  }
+  return undefined;
+}
+
 export async function isGitIgnored(root: string, entry: string): Promise<boolean | undefined> {
   const gitignore = join(root, '.gitignore');
   try {