pi-python-helper 0.1.1 → 0.3.0

package/src/build/selection.ts

@@ -1,5 +1,12 @@
 import { basename, dirname, join } from 'node:path';
-import { isPythonFile, isTestFile, parentDir, pathTokens, toPosix } from '../project/paths.ts';
+import {
+  isPythonFile,
+  isRunnableTestFile,
+  isTestFile,
+  parentDir,
+  pathTokens,
+  toPosix,
+} from '../project/paths.ts';
 
 export interface TestSelection {
   path: string;
@@ -11,13 +18,40 @@ export interface SelectionResult {
   selected: TestSelection[];
   /** True when no changed file could be mapped and every test file is returned. */
   fellBackToAll: boolean;
+  /**
+   * False when the selection covers every considered test file, so the
+   * candidate list was not narrowed at all. Reported so a caller does not read
+   * "30 of 30 selected" as a focused run.
+   */
+  narrowed: boolean;
   changedSourceFiles: string[];
   changedTestFiles: string[];
   consideredTestFiles: string[];
+  /** Files under a test directory that pytest does not collect tests from. */
+  supportFiles: string[];
+  /**
+   * True when at least one candidate was matched by an actual import of a
+   * changed module, which is the strongest available signal. False means the
+   * selection rests on naming conventions alone.
+   */
+  importEvidenceUsed: boolean;
+}
+
+/**
+ * Dotted module names imported by each test file, keyed by test path.
+ * Supplied by the scanner because a test named `test_db_session.py` gives no
+ * naming hint that it covers `db/database.py`; its imports do.
+ */
+export type TestImportMap = Record<string, string[]>;
+
+export interface SelectionOptions {
+  testImports?: TestImportMap;
 }
 
 const SCORE = {
   changedTestItself: 100,
+  /** Importing the changed module is stronger than any name coincidence. */
+  importsChangedModule: 90,
   sameStemSameDir: 80,
   sameStem: 60,
   sameDirectory: 40,
@@ -46,34 +80,132 @@ function firstImportableSegment(path: string): string {
   return (segments[start] ?? '').replace(/\.py$/i, '').toLowerCase();
 }
 
+/**
+ * Dotted module names a source path could be imported as.
+ *
+ * `src/pkg/db/database.py` is imported as `pkg.db.database`, and an
+ * `__init__.py` is the package itself, so both forms are produced with and
+ * without the `src/` prefix.
+ */
+export function modulePathsFromFile(path: string): string[] {
+  const posix = toPosix(path);
+  if (!isPythonFile(posix)) return [];
+  const segments = posix.split('/').filter((segment) => segment.length > 0);
+  const srcIndex = segments.lastIndexOf('src');
+  const trimmed = (srcIndex === -1 ? segments : segments.slice(srcIndex + 1)).map((segment) =>
+    segment.replace(/\.py$/i, ''),
+  );
+  if (trimmed.length === 0) return [];
+  if (trimmed.at(-1) === '__init__') trimmed.pop();
+  if (trimmed.length === 0) return [];
+  const dotted = trimmed.join('.');
+  const withoutRoot = trimmed.slice(1).join('.');
+  const candidates = [dotted];
+  if (srcIndex !== -1) candidates.push(segments.slice(srcIndex).join('.').replace(/\.py$/i, ''));
+  if (withoutRoot.length > 0) candidates.push(withoutRoot);
+  return [...new Set(candidates)];
+}
+
+/** True when a test imports the module, or a parent package of it. */
+function importsModule(imported: string[], modules: string[]): string | undefined {
+  let best: string | undefined;
+  for (const candidate of modules) {
+    for (const entry of imported) {
+      const matches =
+        entry === candidate ||
+        entry.startsWith(`${candidate}.`) ||
+        candidate.startsWith(`${entry}.`);
+      if (!matches) continue;
+      // Report the most specific import: naming `pkg` when the file actually
+      // imports `pkg.routes.admin` overstates how broadly the test is coupled.
+      if (!best || entry.length > best.length) best = entry;
+    }
+  }
+  return best;
+}
+
+/**
+ * Values that appear in at least this share of the candidates carry no
+ * information about *which* candidate to run: in a project whose tests all live
+ * inside the package under test, the package name matches every file.
+ */
+const UBIQUITOUS_SHARE = 0.5;
+
+function ubiquitousValues(documents: string[][]): Set<string> {
+  const counts = new Map<string, number>();
+  for (const values of documents) {
+    for (const value of new Set(values)) {
+      if (value.length === 0) continue;
+      counts.set(value, (counts.get(value) ?? 0) + 1);
+    }
+  }
+  const threshold = Math.max(2, documents.length * UBIQUITOUS_SHARE);
+  const ubiquitous = new Set<string>();
+  for (const [value, count] of counts) {
+    if (count >= threshold) ubiquitous.add(value);
+  }
+  return ubiquitous;
+}
+
 /**
  * Rank test files against changed paths using pytest conventions first and
  * token overlap second. The convention signals are strong enough in Python that
  * a name match should always outrank a fuzzy token match.
+ *
+ * Signals shared by every candidate are discarded rather than scored. Without
+ * that step a package-rooted test tree (`<package>/tests/`) matches its own
+ * package on every file and the selection degenerates into the full suite.
  */
-export function selectTests(changedPaths: string[], testFiles: string[]): SelectionResult {
+export function selectTests(
+  changedPaths: string[],
+  testFiles: string[],
+  options: SelectionOptions = {},
+): SelectionResult {
   const changed = changedPaths.map(toPosix).filter(isPythonFile);
   const changedSourceFiles = changed.filter((path) => !isTestFile(path));
   const changedTestFiles = changed.filter(isTestFile);
   const considered = [...new Set(testFiles.map(toPosix).filter(isPythonFile))].sort();
+  const supportFiles = considered.filter((path) => !isRunnableTestFile(path));
+  const testImports = options.testImports ?? {};
 
   if (!changed.length) {
     return {
       selected: [],
       fellBackToAll: false,
+      narrowed: false,
       changedSourceFiles,
       changedTestFiles,
       consideredTestFiles: considered,
+      supportFiles,
+      importEvidenceUsed: false,
     };
   }
 
   const sourceTokens = new Set(changedSourceFiles.flatMap(pathTokens));
   const sourceModules = new Set(changedSourceFiles.map(firstImportableSegment));
-  const sourceDirs = new Set(changedSourceFiles.map(parentDir));
   const sourceStems = new Set(changedSourceFiles.map(normalizedStem));
+  const sourceModulePaths = changedSourceFiles.map((path) => modulePathsFromFile(path));
+
+  const ubiquitousTokens = ubiquitousValues(considered.map((path) => pathTokens(path)));
+  const ubiquitousModules = ubiquitousValues(
+    considered.map((path) => [firstImportableSegment(path)]),
+  );
+  // A source directory that contains every test file (the package root) cannot
+  // distinguish candidates, so it does not score.
+  const sourceDirs = new Set(
+    [...new Set(changedSourceFiles.map(parentDir))].filter(
+      (directory) =>
+        directory === '' || !considered.every((path) => path.startsWith(`${directory}/`)),
+    ),
+  );
 
+  let importEvidenceUsed = false;
   const selections: TestSelection[] = [];
   for (const testFile of considered) {
+    // Test infrastructure is not a target, but it can still affect the run, so it
+    // is reported separately instead of being scored as a test file.
+    if (!isRunnableTestFile(testFile)) continue;
+
     const reasons: string[] = [];
     let score = 0;
 
@@ -81,6 +213,19 @@ export function selectTests(changedPaths: string[], testFiles: string[]): Select
       score += SCORE.changedTestItself;
       reasons.push('the test file itself changed');
     }
+
+    const imported = testImports[testFile];
+    if (imported && imported.length > 0) {
+      const matched = sourceModulePaths
+        .map((modules) => importsModule(imported, modules))
+        .find((value) => value !== undefined);
+      if (matched) {
+        score += SCORE.importsChangedModule;
+        importEvidenceUsed = true;
+        reasons.push(`imports the changed module "${matched}"`);
+      }
+    }
+
     const testStem = normalizedStem(testFile);
     const testDir = parentDir(testFile);
     if (sourceStems.has(testStem)) {
@@ -99,13 +244,15 @@ export function selectTests(changedPaths: string[], testFiles: string[]): Select
     }
 
     const module = firstImportableSegment(testFile);
-    if (module && sourceModules.has(module)) {
+    if (module && sourceModules.has(module) && !ubiquitousModules.has(module)) {
       score += SCORE.sharedModule;
       reasons.push(`covers module "${module}"`);
     }
 
     const tokens = pathTokens(testFile);
-    const shared = tokens.filter((token) => sourceTokens.has(token));
+    const shared = tokens.filter(
+      (token) => sourceTokens.has(token) && !ubiquitousTokens.has(token),
+    );
     if (shared.length) {
       score += SCORE.sharedToken * Math.min(shared.length, 2);
       reasons.push(`shares token(s): ${shared.slice(0, 4).join(', ')}`);
@@ -125,14 +272,34 @@ export function selectTests(changedPaths: string[], testFiles: string[]): Select
     }
   }
 
+  const runnableConsidered = considered.filter(isRunnableTestFile);
+  const selectedRunnable = selections.filter((entry) => isRunnableTestFile(entry.path));
   const fellBackToAll = selections.length === 0 && considered.length > 0;
+  if (fellBackToAll) {
+    return {
+      selected: considered.map((path) => ({
+        path,
+        score: 0,
+        reason: 'no match; running the full suite',
+      })),
+      fellBackToAll: true,
+      narrowed: false,
+      changedSourceFiles,
+      changedTestFiles,
+      consideredTestFiles: considered,
+      supportFiles,
+      importEvidenceUsed,
+    };
+  }
+
   return {
-    selected: fellBackToAll
-      ? considered.map((path) => ({ path, score: 0, reason: 'no match; running the full suite' }))
-      : selections,
-    fellBackToAll,
+    selected: selections,
+    fellBackToAll: false,
+    narrowed: selectedRunnable.length < runnableConsidered.length,
     changedSourceFiles,
     changedTestFiles,
     consideredTestFiles: considered,
+    supportFiles,
+    importEvidenceUsed,
   };
 }

package/src/build/sync.ts

@@ -0,0 +1,70 @@
+/**
+ * uv prints a per-package inventory when `uv sync` changes the environment:
+ *
+ * ```text
+ * Uninstalled 10 packages in 305ms
+ *  - coverage==7.15.4
+ *  - pytest==9.0.3
+ *  + ruff==0.15.5
+ * ```
+ *
+ * Removals matter because a sync that silently drops the project's own dev
+ * tooling leaves every later step unable to run, so the inventory is parsed
+ * rather than discarded.
+ */
+export interface SyncInventory {
+  installed: string[];
+  uninstalled: string[];
+  /** One of `uv`'s summary lines, e.g. `Audited 78 packages in 3ms`. */
+  summaryLines: string[];
+}
+
+const COUNT_LINE = /^(Installed|Uninstalled|Prepared|Audited|Resolved)\b/;
+const PACKAGE_LINE = /^\s*([+-])\s*([A-Za-z0-9._-]+)(?:==(\S+))?\s*$/;
+
+function stripVersion(name: string): string {
+  return name.trim();
+}
+
+/**
+ * Read the installed/uninstalled inventory out of uv's stdout. Anything that
+ * does not match the documented layout is ignored rather than guessed at, so a
+ * future uv output change degrades to "no inventory" instead of a wrong one.
+ */
+export function parseSyncOutput(stdout: string, stderr = ''): SyncInventory {
+  const installed: string[] = [];
+  const uninstalled: string[] = [];
+  const summaryLines: string[] = [];
+  let section: 'installed' | 'uninstalled' | null = null;
+
+  for (const rawLine of `${stdout}\n${stderr}`.split(/\r?\n/)) {
+    const line = rawLine.trimEnd();
+    if (COUNT_LINE.test(line.trim())) {
+      summaryLines.push(line.trim());
+      if (/^Uninstalled\b/.test(line.trim())) section = 'uninstalled';
+      else if (/^Installed\b/.test(line.trim())) section = 'installed';
+      else section = null;
+      continue;
+    }
+    const match = line.match(PACKAGE_LINE);
+    if (!match || !section) continue;
+    const name = stripVersion(match[2]);
+    if (match[1] === '-' && section === 'uninstalled') uninstalled.push(name);
+    else if (match[1] === '+' && section === 'installed') installed.push(name);
+  }
+
+  return { installed, uninstalled, summaryLines };
+}
+
+/**
+ * A sync that removes distributions is worth reporting even when it exits zero:
+ * on its own it is not a failure, but it explains every later "command not
+ * found" failure in the same run.
+ */
+export function describeRemovals(inventory: SyncInventory): string | undefined {
+  if (inventory.uninstalled.length === 0) return undefined;
+  const shown = inventory.uninstalled.slice(0, 12).join(', ');
+  const rest =
+    inventory.uninstalled.length > 12 ? `, … (+${inventory.uninstalled.length - 12})` : '';
+  return `uv sync removed ${inventory.uninstalled.length} distribution(s) from .venv: ${shown}${rest}.`;
+}

package/src/core/result.ts

@@ -45,7 +45,23 @@ export interface ToolMetadata {
  * `data`; everything the agent must reason about lives in the typed sections.
  */
 export interface PyToolResult<T = unknown> {
+  /**
+   * The tool's own verdict, not "the tool ran". `true` means the question this
+   * tool asks was answered affirmatively: the project state is acceptable, the
+   * command succeeded, or the gate may proceed. A diagnostic tool that finds a
+   * problem therefore returns `ok: false` without the tool itself having
+   * failed. Read `attention` for "must the caller act".
+   */
   ok: boolean;
+  /**
+   * `true` when the caller must act before proceeding: the tool failed, or it
+   * emitted a warning or an error. An `info` diagnostic is informational by
+   * definition and does not set this. Derived from `ok`, `warnings`, and
+   * `errors` unless a tool sets it explicitly, so `ok: false` always implies
+   * `attention: true` and no diagnostic is silently dropped. This is the field
+   * to read when the question is "do I need to do something".
+   */
+  attention: boolean;
   summary: string;
   data?: T;
   evidence: Evidence[];
@@ -56,10 +72,20 @@ export interface PyToolResult<T = unknown> {
   metadata: ToolMetadata;
 }
 
+/**
+ * An `info` diagnostic records a fact; only a warning or an error asks the
+ * caller to do something. Keeping them apart stops a purely informational note
+ * from raising `attention`.
+ */
+function isActionable(value: { warnings: Diagnostic[]; errors: Diagnostic[] }): boolean {
+  return [...value.warnings, ...value.errors].some((entry) => entry.severity !== 'info');
+}
+
 export function result<T>(
   cwd: string,
   startedAt: number,
-  value: Omit<PyToolResult<T>, 'metadata'> & {
+  value: Omit<PyToolResult<T>, 'metadata' | 'attention'> & {
+    attention?: boolean;
     truncated?: boolean;
     projectRoot?: string;
     pythonVersion?: string;
@@ -67,6 +93,7 @@ export function result<T>(
 ): PyToolResult<T> {
   return {
     ...value,
+    attention: value.attention ?? (!value.ok || isActionable(value)),
     metadata: {
       toolVersion: TOOL_VERSION,
       cwd,

package/src/dependencies/aliases.ts

@@ -65,6 +65,27 @@ export const IMPORT_ALIASES: Record<string, string[]> = {
   tqdm: ['tqdm'],
 };
 
+const NORMALIZE_RE = /[-_.]+/g;
+
+/**
+ * Distribution candidates for an import name, from the static alias table only.
+ *
+ * Used where the scanner cannot supply the authoritative provider mapping (a
+ * traceback names an import, not an installed distribution). Ordering is
+ * preserved so a caller can name every candidate when an import maps to more
+ * than one distribution: `cv2` is either `opencv-python` or
+ * `opencv-python-headless`, and picking one silently would install the wrong
+ * variant. An empty result means the provider is unknown, and no `uv add`
+ * command may be fabricated from the import name.
+ */
+export function importAliasCandidates(importName: string): string[] {
+  const normalized = importName.replace(NORMALIZE_RE, '-').trim().toLowerCase();
+  const candidates = new Set<string>();
+  for (const alias of IMPORT_ALIASES[importName] ?? []) candidates.add(alias);
+  for (const alias of IMPORT_ALIASES[normalized] ?? []) candidates.add(alias);
+  return [...candidates];
+}
+
 /** Distributions that are normally invoked as a console script, not imported. */
 export const CONSOLE_ONLY: Set<string> = new Set([
   'ruff',

package/src/dependencies/plan.ts

@@ -63,7 +63,16 @@ export interface UndeclaredImport {
   files: string[];
   fileCount: number;
   providers: string[];
-  suggestedDistribution: string;
+  /**
+   * The distribution to declare, when the analysing interpreter could determine
+   * it. Absent otherwise: `uv add <import name>` would then install a different
+   * package, or nothing at all, because import names and distribution names
+   * frequently disagree (`wconfig` ships inside `wpyconf`, `yaml` inside
+   * `PyYAML`).
+   */
+  suggestedDistribution?: string;
+  /** True when the suggestion comes from installed metadata rather than a guess. */
+  providerKnown: boolean;
   typeCheckingOnly: boolean;
   reason: string;
 }
@@ -95,6 +104,12 @@ export interface DependencyPlan {
     requiresPythonMismatch: { manifest: string; lock: string } | null;
   };
   providerMappingReliable: boolean;
+  /**
+   * Third-party imports the analysing interpreter could not map to an installed
+   * distribution. A high count means the interpreter is not the project's own,
+   * so "undeclared" may really be "import name differs from distribution name".
+   */
+  unmappedImports: number;
   unparsable: { path: string; error: string }[];
   warnings: Diagnostic[];
   notes: Diagnostic[];
@@ -147,13 +162,19 @@ export function planDependencies(
     const runtimeRelevant = !entry.typeCheckingOnly && runtimeFiles.length > 0;
 
     if (matched.length === 0) {
+      // Prefer the distribution that actually owns the module. The static alias
+      // table is a fallback for checkouts where nothing is installed.
+      const suggested =
+        entry.providers[0] ??
+        IMPORT_ALIASES[entry.import]?.[0] ??
+        IMPORT_ALIASES[normalizeName(entry.import)]?.[0];
       undeclared.push({
         import: entry.import,
         files: entry.files,
         fileCount: entry.fileCount,
         providers: entry.providers,
-        suggestedDistribution:
-          entry.providers[0] ?? IMPORT_ALIASES[entry.import]?.[0] ?? entry.import,
+        suggestedDistribution: suggested,
+        providerKnown: suggested !== undefined,
         typeCheckingOnly: entry.typeCheckingOnly,
         reason: entry.typeCheckingOnly
           ? 'imported only under TYPE_CHECKING and declared in neither [project] tables nor uv.lock'
@@ -199,11 +220,21 @@ export function planDependencies(
         entry.files[0],
       ),
     );
-    suggestions.push({
-      message: `Declare ${entry.suggestedDistribution} with uv add${entry.typeCheckingOnly ? ' --dev' : ''} ${entry.suggestedDistribution}.`,
-      confidence: entry.providers.length ? 'high' : 'medium',
-      command: `uv add${entry.typeCheckingOnly ? ' --dev' : ''} ${entry.suggestedDistribution}`,
-    });
+    const distribution = entry.suggestedDistribution;
+    if (distribution) {
+      const flag = entry.typeCheckingOnly ? ' --dev' : '';
+      suggestions.push({
+        message: `Declare ${distribution} with uv add${flag} ${distribution}.`,
+        confidence: entry.providers.length ? 'high' : 'medium',
+        command: `uv add${flag} ${distribution}`,
+      });
+    } else {
+      // Fabricating a command here would install the wrong package or fail.
+      suggestions.push({
+        message: `Look up the distribution that provides "${entry.import}" and declare that name: import names and distribution names frequently disagree, and the analysing interpreter could not map this one.`,
+        confidence: 'low',
+      });
+    }
   }
 
   for (const entry of misplaced) {
@@ -252,6 +283,11 @@ export function planDependencies(
     });
   }
 
+  const thirdPartyCount = imports?.thirdParty.length ?? 0;
+  const unmappedImports = (imports?.thirdParty ?? []).filter(
+    (entry) => entry.providers.length === 0,
+  ).length;
+
   if (imports?.providersUnavailable) {
     notes.push({
       code: 'PROVIDER_MAPPING_HEURISTIC',
@@ -259,6 +295,12 @@ export function planDependencies(
         'No installed distributions were visible to the analysing interpreter, so import-to-distribution mapping relied on a static alias table.',
       severity: 'info',
     });
+  } else if (unmappedImports > 0) {
+    notes.push({
+      code: 'UNMAPPED_IMPORTS',
+      message: `${unmappedImports} of ${thirdPartyCount} third-party import(s) could not be mapped to an installed distribution, so their distribution names are unknown rather than merely undeclared.`,
+      severity: 'info',
+    });
   }
   if (imports && !imports.stdlibAvailable) {
     notes.push({
@@ -288,7 +330,14 @@ export function planDependencies(
     misplaced,
     unused,
     drift,
-    providerMappingReliable: !(imports?.providersUnavailable ?? true),
+    // A partial mapping is disclosed through `unmappedImports`; the claim here is
+    // only that the interpreter could see an installed environment at all. When
+    // it could see one yet owned none of the project's imports, it is not the
+    // project's interpreter and nothing it reports should be trusted.
+    providerMappingReliable:
+      !(imports?.providersUnavailable ?? true) &&
+      !(thirdPartyCount > 0 && unmappedImports === thirdPartyCount),
+    unmappedImports,
     unparsable: imports?.unparsable ?? [],
     warnings,
     notes,

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 };
+}