pi-python-helper 0.1.1 → 0.3.0

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 {

package/src/project/scanner.ts

@@ -1,4 +1,5 @@
 import { runCommand } from '../core/runner.ts';
+import { findVenvDir, findVenvInterpreter } from './root.ts';
 
 export const HELPER_URL = new URL('../../helpers/scan_project.py', import.meta.url);
 
@@ -13,7 +14,7 @@ export type ScanMode =
   | 'manifest,imports';
 
 /** Bumped by the scanner when the request or result document changes shape. */
-export const SUPPORTED_SCANNER_VERSION = 1;
+export const SUPPORTED_SCANNER_VERSION = 3;
 
 export interface DeclaredDependency {
   raw: string;
@@ -39,6 +40,12 @@ export interface ManifestSection {
   buildRequires: string[];
   entryPoints: string[];
   toolConfiguration: Record<string, boolean>;
+  /**
+   * `[tool.pytest.ini_options]` as written, or null when the table is absent.
+   * Left untyped because pytest accepts options this package does not model;
+   * only the audited keys are read.
+   */
+  pytestOptions?: Record<string, unknown> | null;
   layout: 'src' | 'flat';
   modules: string[];
   legacySetupPy: boolean;
@@ -88,7 +95,20 @@ export interface ImportSection {
   stdlibAvailable: boolean;
   layout: 'src' | 'flat';
   localModules: string[];
-  files: { path: string; imports: string[]; typeCheckingImports: string[] }[];
+  files: {
+    path: string;
+    imports: string[];
+    /**
+     * Full dotted module names the file references, so a test file can be
+     * matched to the module it imports rather than only by file name.
+     */
+    importModules?: string[];
+    typeCheckingImports: string[];
+    /** `async def test_*` names in this file. */
+    asyncTests?: string[];
+    /** The subset of `asyncTests` that carries an async plugin marker. */
+    asyncioMarkedTests?: string[];
+  }[];
   thirdParty: {
     import: string;
     files: string[];
@@ -137,6 +157,8 @@ export interface ScanPayload {
 export interface ScanOutcome {
   ok: boolean;
   interpreter?: string;
+  /** Whether the interpreter came from the project environment or from PATH. */
+  interpreterOrigin?: 'venv' | 'path';
   payload?: ScanPayload;
   /** Diagnostic code the caller can surface verbatim when `ok` is false. */
   code?:
@@ -145,17 +167,23 @@ export interface ScanOutcome {
   stderr?: string;
 }
 
-let interpreterPromise: Promise<string | undefined> | undefined;
+const interpreterPromises = new Map<string, Promise<string | undefined>>();
 
 /**
  * Pick the interpreter used for read-only analysis. `python3` is preferred so a
  * `python` that points at a legacy Python 2 install is never selected.
+ *
+ * Results are cached per key so repeated tool calls in one session do not probe
+ * PATH again.
  */
 export async function resolveInterpreter(
   cwd: string,
   signal?: AbortSignal,
+  cacheKey = 'path',
 ): Promise<string | undefined> {
-  interpreterPromise ??= (async () => {
+  const cached = interpreterPromises.get(cacheKey);
+  if (cached) return cached;
+  const pending = (async () => {
     for (const candidate of ['python3', 'python']) {
       const probe = await runCommand(candidate, ['-c', 'import sys; print(sys.version_info[0])'], {
         cwd,
@@ -167,7 +195,29 @@ export async function resolveInterpreter(
     }
     return undefined;
   })();
-  return interpreterPromise;
+  interpreterPromises.set(cacheKey, pending);
+  return pending;
+}
+
+/**
+ * Resolve the interpreter whose `site-packages` describe this project.
+ *
+ * The scanner answers "which distribution provides this import?" by asking the
+ * interpreter it runs under. A host `python3` sees only its own site-packages,
+ * so every project dependency looks unowned; the project's own interpreter sees
+ * the environment that `uv sync` actually built.
+ */
+export async function resolveProjectInterpreter(
+  root: string,
+  cwd: string,
+  signal?: AbortSignal,
+): Promise<{ interpreter?: string; origin: 'venv' | 'path' }> {
+  const venvDir = await findVenvDir(root);
+  if (venvDir) {
+    const venvInterpreter = await findVenvInterpreter(venvDir);
+    if (venvInterpreter) return { interpreter: venvInterpreter, origin: 'venv' };
+  }
+  return { interpreter: await resolveInterpreter(cwd, signal), origin: 'path' };
 }
 
 /**
@@ -180,12 +230,14 @@ export async function runScanProject(
   request: { root: string; mode: ScanMode; maxFiles?: number },
   signal?: AbortSignal,
 ): Promise<ScanOutcome> {
-  const interpreter = await resolveInterpreter(cwd, signal);
+  const resolved = await resolveProjectInterpreter(request.root, cwd, signal);
+  const interpreter = resolved.interpreter;
+  const origin = resolved.origin;
   if (!interpreter) {
     return {
       ok: false,
       code: 'PYTHON_NOT_FOUND',
-      message: 'No Python 3 interpreter was found on PATH.',
+      message: 'No Python 3 interpreter was found in the project environment or on PATH.',
     };
   }
   const helper = HELPER_URL.pathname;
@@ -200,6 +252,7 @@ export async function runScanProject(
     return {
       ok: false,
       interpreter,
+      interpreterOrigin: origin,
       code: 'SCANNER_FAILED',
       message: 'The project scanner timed out.',
     };
@@ -208,6 +261,7 @@ export async function runScanProject(
     return {
       ok: false,
       interpreter,
+      interpreterOrigin: origin,
       code: 'SCANNER_FAILED',
       message: 'The project scanner exited with an error.',
       stderr: run.stderr.trim() || undefined,
@@ -216,7 +270,13 @@ export async function runScanProject(
   try {
     const payload = JSON.parse(run.stdout) as ScanPayload;
     if (payload.error) {
-      return { ok: false, interpreter, code: 'SCANNER_FAILED', message: payload.error };
+      return {
+        ok: false,
+        interpreter,
+        interpreterOrigin: origin,
+        code: 'SCANNER_FAILED',
+        message: payload.error,
+      };
     }
     // Refuse to interpret a document whose shape may have changed.
     if (
@@ -226,15 +286,17 @@ export async function runScanProject(
       return {
         ok: false,
         interpreter,
+        interpreterOrigin: origin,
         code: 'SCANNER_VERSION_MISMATCH',
         message: `The scanner reported protocol version ${payload.scannerVersion}, but this extension understands version ${SUPPORTED_SCANNER_VERSION}.`,
       };
     }
-    return { ok: true, interpreter, payload };
+    return { ok: true, interpreter, interpreterOrigin: origin, payload };
   } catch {
     return {
       ok: false,
       interpreter,
+      interpreterOrigin: origin,
       code: 'SCANNER_INVALID_OUTPUT',
       message: 'The project scanner did not return valid JSON.',
       stderr: run.stdout.slice(0, 2000),