pi-python-helper 0.1.0

package/src/dependencies/plan.ts

@@ -0,0 +1,398 @@
+import type { Diagnostic, Suggestion } from '../core/result.ts';
+import { warn } from '../core/result.ts';
+import { isTestFile } from '../project/paths.ts';
+import type { DeclaredDependency, ScanPayload } from '../project/scanner.ts';
+
+/**
+ * Import name and distribution name frequently disagree. The scanner supplies
+ * the authoritative mapping when the analysing interpreter has the package
+ * installed; this table covers the cases where it does not, so an uninstalled
+ * checkout is still analysed correctly.
+ */
+export const IMPORT_ALIASES: Record<string, string[]> = {
+  PIL: ['pillow'],
+  yaml: ['pyyaml'],
+  dateutil: ['python-dateutil'],
+  bs4: ['beautifulsoup4'],
+  cv2: ['opencv-python', 'opencv-python-headless'],
+  sklearn: ['scikit-learn'],
+  skimage: ['scikit-image'],
+  dotenv: ['python-dotenv'],
+  attr: ['attrs'],
+  attrs: ['attrs'],
+  jwt: ['pyjwt'],
+  jose: ['python-jose'],
+  serial: ['pyserial'],
+  OpenSSL: ['pyopenssl'],
+  Crypto: ['pycryptodome'],
+  pkg_resources: ['setuptools'],
+  MySQLdb: ['mysqlclient'],
+  googleapiclient: ['google-api-python-client'],
+  github: ['PyGithub'],
+  pytest_cov: ['pytest-cov'],
+  _pytest: ['pytest'],
+  pytest_asyncio: ['pytest-asyncio'],
+  psycopg: ['psycopg', 'psycopg-binary'],
+  psycopg2: ['psycopg2', 'psycopg2-binary'],
+  prometheus_client: ['prometheus-client'],
+  grpc: ['grpcio'],
+  kafka: ['kafka-python'],
+  docker: ['docker'],
+  numpy: ['numpy'],
+  pandas: ['pandas'],
+  ruamel: ['ruamel.yaml'],
+  setuptools: ['setuptools'],
+  mako: ['Mako'],
+  pytz: ['pytz'],
+  tzlocal: ['tzlocal'],
+  win32com: ['pywin32'],
+  lxml: ['lxml'],
+  matplotlib: ['matplotlib'],
+  seaborn: ['seaborn'],
+  sqlalchemy: ['sqlalchemy', 'SQLAlchemy'],
+  pydantic: ['pydantic'],
+  fastapi: ['fastapi'],
+  starlette: ['starlette'],
+  uvicorn: ['uvicorn'],
+  celery: ['celery'],
+  redis: ['redis'],
+  boto3: ['boto3'],
+  botocore: ['botocore'],
+  httpx: ['httpx'],
+  aiohttp: ['aiohttp'],
+  werkzeug: ['werkzeug'],
+  flask: ['flask'],
+  django: ['django'],
+  jinja2: ['jinja2'],
+  typer: ['typer'],
+  click: ['click'],
+  rich: ['rich'],
+  tqdm: ['tqdm'],
+};
+
+/** Distributions that are normally invoked as a console script, not imported. */
+const CONSOLE_ONLY = new Set(
+  [
+    'ruff',
+    'mypy',
+    'pyright',
+    'ty',
+    'pytest',
+    'pytest-cov',
+    'coverage',
+    'pre-commit',
+    'tox',
+    'nox',
+    'hatch',
+    'hatchling',
+    'build',
+    'twine',
+    'black',
+    'isort',
+    'flake8',
+    'pylint',
+    'sphinx',
+    'mkdocs',
+    'uvicorn',
+    'gunicorn',
+    'alembic',
+    'celery',
+    'honcho',
+    'maturin',
+    'setuptools-scm',
+    'pip-audit',
+    'bandit',
+    'commitizen',
+    'towncrier',
+  ].map((name) => name),
+);
+
+const NORMALIZE_RE = /[-_.]+/g;
+
+/** PEP 503 normalization: case and `-`/`_`/`.` are not significant. */
+export function normalizeName(name: string): string {
+  return name.replace(NORMALIZE_RE, '-').trim().toLowerCase();
+}
+
+export function distributionCandidates(importName: string, providers: string[]): string[] {
+  const normalized = normalizeName(importName);
+  const candidates = new Set<string>();
+  for (const provider of providers) candidates.add(normalizeName(provider));
+  for (const alias of IMPORT_ALIASES[importName] ?? []) candidates.add(normalizeName(alias));
+  for (const alias of IMPORT_ALIASES[normalized] ?? []) candidates.add(normalizeName(alias));
+  candidates.add(normalized);
+  candidates.add(`python-${normalized}`);
+  candidates.add(`${normalized}-python`);
+  return [...candidates].filter((candidate) => candidate.length > 0);
+}
+
+export interface DeclaredEntry {
+  name: string;
+  normalized: string;
+  groups: string[];
+}
+
+export type DependencyGroup = string;
+
+export function buildDeclaredIndex(manifest: {
+  dependencies: DeclaredDependency[];
+  optionalDependencies: Record<string, DeclaredDependency[]>;
+  dependencyGroups: Record<string, DeclaredDependency[]>;
+}): Map<string, DeclaredEntry> {
+  const index = new Map<string, DeclaredEntry>();
+  const add = (dependency: DeclaredDependency, group: DependencyGroup) => {
+    const normalized = normalizeName(dependency.normalized || dependency.name);
+    const existing = index.get(normalized);
+    if (existing) {
+      if (!existing.groups.includes(group)) existing.groups.push(group);
+      return;
+    }
+    index.set(normalized, { name: dependency.name, normalized, groups: [group] });
+  };
+  for (const dependency of manifest.dependencies) add(dependency, 'runtime');
+  for (const [extra, list] of Object.entries(manifest.optionalDependencies)) {
+    for (const dependency of list) add(dependency, `optional:${extra}`);
+  }
+  for (const [group, list] of Object.entries(manifest.dependencyGroups)) {
+    for (const dependency of list) add(dependency, `group:${group}`);
+  }
+  return index;
+}
+
+export interface UndeclaredImport {
+  import: string;
+  files: string[];
+  fileCount: number;
+  providers: string[];
+  suggestedDistribution: string;
+  typeCheckingOnly: boolean;
+  reason: string;
+}
+
+export interface MisplacedDependency {
+  import: string;
+  distribution: string;
+  declaredIn: string[];
+  runtimeFiles: string[];
+}
+
+export interface UnusedDeclaration {
+  name: string;
+  normalized: string;
+  groups: string[];
+}
+
+export interface DependencyPlan {
+  declaredCount: number;
+  declared: DeclaredEntry[];
+  thirdPartyImportCount: number;
+  undeclared: UndeclaredImport[];
+  misplaced: MisplacedDependency[];
+  unused: UnusedDeclaration[];
+  drift: {
+    lockPresent: boolean;
+    missingFromLock: string[];
+    unsatisfiedInLock: { name: string; specifier: string; locked: string }[];
+    requiresPythonMismatch: { manifest: string; lock: string } | null;
+  };
+  providerMappingReliable: boolean;
+  unparsable: { path: string; error: string }[];
+  warnings: Diagnostic[];
+  notes: Diagnostic[];
+  suggestions: Suggestion[];
+}
+
+export interface DependencyPlanOptions {
+  /** Reporting declared-but-unimported packages produces false positives by design. */
+  includeUnused?: boolean;
+}
+
+/**
+ * Compare what the code imports with what the project declares.
+ *
+ * Three questions are answered, in decreasing confidence:
+ * 1. an imported distribution that is declared nowhere,
+ * 2. an imported distribution declared only in a dev group or extra while
+ *    production code imports it, and
+ * 3. an imported distribution missing from `uv.lock` or locked below its
+ *    declared specifier.
+ */
+export function planDependencies(
+  payload: ScanPayload,
+  options: DependencyPlanOptions = {},
+): DependencyPlan {
+  const imports = payload.imports;
+  const manifest = payload.manifest;
+  const comparison = payload.lockComparison;
+  const warnings: Diagnostic[] = [];
+  const notes: Diagnostic[] = [];
+  const suggestions: Suggestion[] = [];
+
+  const declaredIndex = manifest ? buildDeclaredIndex(manifest) : new Map<string, DeclaredEntry>();
+
+  const undeclared: UndeclaredImport[] = [];
+  const misplaced: MisplacedDependency[] = [];
+  const usedNormalized = new Set<string>();
+
+  for (const entry of imports?.thirdParty ?? []) {
+    const candidates = distributionCandidates(entry.import, entry.providers);
+    const matched = candidates
+      .map((candidate) => declaredIndex.get(candidate))
+      .filter((value): value is DeclaredEntry => value !== undefined);
+    for (const declaration of matched) usedNormalized.add(declaration.normalized);
+
+    const typeCheckingFiles = new Set(entry.typeCheckingFiles ?? []);
+    const runtimeFiles = entry.files.filter(
+      (file) => !isTestFile(file) && !typeCheckingFiles.has(file),
+    );
+    const runtimeRelevant = !entry.typeCheckingOnly && runtimeFiles.length > 0;
+
+    if (matched.length === 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,
+        typeCheckingOnly: entry.typeCheckingOnly,
+        reason: entry.typeCheckingOnly
+          ? 'imported only under TYPE_CHECKING and declared in neither [project] tables nor uv.lock'
+          : 'imported by project code but declared in no dependency group',
+      });
+      continue;
+    }
+
+    const hasRuntimeDeclaration = matched.some((declaration) =>
+      declaration.groups.includes('runtime'),
+    );
+    if (runtimeRelevant && !hasRuntimeDeclaration) {
+      const groups = [...new Set(matched.flatMap((declaration) => declaration.groups))];
+      misplaced.push({
+        import: entry.import,
+        distribution: matched[0].name,
+        declaredIn: groups,
+        runtimeFiles,
+      });
+    }
+  }
+
+  const unused: UnusedDeclaration[] = [];
+  if (options.includeUnused) {
+    for (const declaration of declaredIndex.values()) {
+      if (usedNormalized.has(declaration.normalized)) continue;
+      if (CONSOLE_ONLY.has(declaration.normalized)) continue;
+      unused.push({
+        name: declaration.name,
+        normalized: declaration.normalized,
+        groups: declaration.groups,
+      });
+    }
+  }
+
+  for (const entry of undeclared) {
+    warnings.push(
+      warn(
+        entry.typeCheckingOnly ? 'UNDECLARED_TYPE_ONLY_IMPORT' : 'UNDECLARED_IMPORT',
+        `"${entry.import}" is imported${entry.files.length ? ` in ${entry.files[0]}` : ''}${
+          entry.fileCount > 1 ? ` and ${entry.fileCount - 1} other file(s)` : ''
+        } but is declared in no dependency group.`,
+        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}`,
+    });
+  }
+
+  for (const entry of misplaced) {
+    warnings.push(
+      warn(
+        'RUNTIME_DEPENDENCY_IN_DEV_GROUP',
+        `"${entry.import}" is imported by production code (${entry.runtimeFiles[0]}) but "${entry.distribution}" is declared only in ${entry.declaredIn.join(', ')}.`,
+        entry.runtimeFiles[0],
+      ),
+    );
+    suggestions.push({
+      message: `Move ${entry.distribution} from ${entry.declaredIn.join(', ')} into [project] dependencies.`,
+      confidence: 'high',
+      command: `uv add ${entry.distribution}`,
+    });
+  }
+
+  for (const entry of unused) {
+    notes.push({
+      code: 'UNUSED_DECLARATION',
+      message: `"${entry.name}" is declared in ${entry.groups.join(', ')} but no project file imports it (console-only tools are excluded; verify before removing).`,
+      severity: 'info',
+    });
+  }
+
+  const drift = {
+    lockPresent: comparison !== undefined && (payload.lock?.present ?? false),
+    missingFromLock: comparison?.missingFromLock ?? [],
+    unsatisfiedInLock: comparison?.unsatisfiedInLock ?? [],
+    requiresPythonMismatch: comparison?.requiresPythonMismatch ?? null,
+  };
+  if (drift.lockPresent && drift.missingFromLock.length + drift.unsatisfiedInLock.length > 0) {
+    warnings.push(
+      warn(
+        'LOCKFILE_DRIFT',
+        `uv.lock disagrees with pyproject.toml (${drift.missingFromLock.length} missing, ${
+          drift.unsatisfiedInLock.length
+        } unsatisfied). Run uv lock before trusting the environment.`,
+        payload.lock?.path ?? undefined,
+      ),
+    );
+    suggestions.push({
+      message: 'Run uv lock to resynchronise uv.lock.',
+      confidence: 'high',
+      command: 'uv lock',
+    });
+  }
+
+  if (imports?.providersUnavailable) {
+    notes.push({
+      code: 'PROVIDER_MAPPING_HEURISTIC',
+      message:
+        'No installed distributions were visible to the analysing interpreter, so import-to-distribution mapping relied on a static alias table.',
+      severity: 'info',
+    });
+  }
+  if (imports && !imports.stdlibAvailable) {
+    notes.push({
+      code: 'STDLIB_LIST_HEURISTIC',
+      message:
+        'The analysing interpreter predates sys.stdlib_module_names, so standard-library detection used a reduced list and third-party results may over-report.',
+      severity: 'info',
+    });
+  }
+
+  for (const entry of imports?.unparsable ?? []) {
+    notes.push({
+      code: 'UNPARSABLE_FILE',
+      message: `${entry.path} could not be parsed: ${entry.error}`,
+      severity: 'info',
+      path: entry.path,
+    });
+  }
+
+  return {
+    declaredCount: declaredIndex.size,
+    declared: [...declaredIndex.values()].sort((left, right) =>
+      left.normalized.localeCompare(right.normalized),
+    ),
+    thirdPartyImportCount: imports?.thirdParty.length ?? 0,
+    undeclared,
+    misplaced,
+    unused,
+    drift,
+    providerMappingReliable: !(imports?.providersUnavailable ?? true),
+    unparsable: imports?.unparsable ?? [],
+    warnings,
+    notes,
+    suggestions,
+  };
+}

package/src/environment/discovery.ts

@@ -0,0 +1,166 @@
+import { type Diagnostic, warn } from '../core/result.ts';
+import { runCommand } from '../core/runner.ts';
+import { findProjectRoot, findVenvDir, isFile } from '../project/root.ts';
+import {
+  type EnvironmentSection,
+  type LockPackage,
+  resolveInterpreter,
+  runScanProject,
+} from '../project/scanner.ts';
+import { inspectTools, type ToolAvailability } from './tools.ts';
+
+export interface PythonEnvironment {
+  interpreter?: string;
+  python?: EnvironmentSection;
+  projectRoot?: string;
+  venvDir?: string;
+  uv: { available: boolean; version?: string; lockPresent: boolean };
+  tools: ToolAvailability[];
+  warnings: Diagnostic[];
+  suggestions: string[];
+}
+
+function parseVersion(output: string): string | undefined {
+  const match = output.match(/(\d+\.\d+(?:\.\d+)?(?:[-+][\w.]+)?)/);
+  return match?.[1];
+}
+
+/**
+ * Report the version of a host CLI. Reserved for `uv`, which cannot be resolved
+ * from the project lockfile; project tools get their version from `uv.lock`.
+ */
+export async function toolVersion(
+  cwd: string,
+  name: string,
+  signal?: AbortSignal,
+): Promise<string | undefined> {
+  const run = await runCommand(name, ['--version'], {
+    cwd,
+    signal,
+    timeoutMs: 5000,
+    maxBytes: 4096,
+  });
+  if (run.code !== 0) return undefined;
+  return parseVersion(`${run.stdout}\n${run.stderr}`);
+}
+
+/**
+ * Describe the interpreter, project root, environment, and tool availability.
+ *
+ * A single bounded scanner call supplies both the interpreter facts and the
+ * lockfile, so availability is resolved from filesystem probes plus the
+ * lockfile instead of one subprocess per tool.
+ */
+export async function detectPythonEnvironment(
+  cwd: string,
+  signal?: AbortSignal,
+): 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[] = [];
+  if (interpreter) {
+    const scan = await runScanProject(
+      cwd,
+      { root: scanRoot, mode: 'environment,manifest' },
+      signal,
+    );
+    if (scan.ok) {
+      python = scan.payload?.environment;
+      lockPackages = scan.payload?.lock?.packages ?? [];
+    } else if (scan.message) {
+      warnings.push(warn(scan.code ?? 'SCANNER_FAILED', scan.message));
+    }
+  } else {
+    warnings.push(
+      warn(
+        'PYTHON_NOT_FOUND',
+        'No Python 3 interpreter was found 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.');
+  }
+
+  if (!projectRoot) {
+    warnings.push(
+      warn(
+        'PROJECT_NOT_FOUND',
+        'No pyproject.toml, uv.lock, or setup.py was found from this directory.',
+      ),
+    );
+    suggestions.push(
+      'Run uv init to create a uv-managed project, or change to an existing project directory.',
+    );
+  }
+
+  const venvDir = projectRoot ? await findVenvDir(projectRoot) : undefined;
+  const lockPresent = projectRoot ? await isFile(`${projectRoot}/uv.lock`) : false;
+  const tools = await inspectTools({ venvDir, lockPackages });
+
+  const uvVersion = await toolVersion(cwd, 'uv', signal);
+  if (!uvVersion) {
+    warnings.push(
+      warn(
+        'UV_NOT_AVAILABLE',
+        'The uv CLI was not found on PATH; commands cannot be previewed reliably.',
+      ),
+    );
+    suggestions.push('Install uv (https://docs.astral.sh/uv/) before build or test operations.');
+  }
+
+  if (projectRoot && python && !python.inVirtualEnvironment && !venvDir) {
+    warnings.push(
+      warn(
+        'NO_VIRTUAL_ENVIRONMENT',
+        'The resolved interpreter is not inside a virtual environment and no .venv directory exists at the project root.',
+      ),
+    );
+    suggestions.push('Run uv sync to create .venv and install the locked dependencies.');
+  }
+
+  if (projectRoot && python && python.inVirtualEnvironment && venvDir && python.virtualEnv) {
+    const active = python.virtualEnv.replace(/\/+$/, '');
+    if (active !== venvDir) {
+      warnings.push(
+        warn(
+          'VIRTUAL_ENVIRONMENT_MISMATCH',
+          `VIRTUAL_ENV points at ${active} but the project environment is ${venvDir}.`,
+        ),
+      );
+      suggestions.push(
+        'Deactivate the unrelated environment, or run uv sync to refresh the project .venv.',
+      );
+    }
+  }
+
+  if (python && !python.tomlAvailable) {
+    warnings.push(
+      warn(
+        'TOML_PARSER_UNAVAILABLE',
+        `Python ${python.version} has no tomllib; pyproject.toml and uv.lock analysis is degraded.`,
+      ),
+    );
+    suggestions.push(
+      'Use Python 3.11+ (or install tomli in the analysing interpreter) to enable manifest analysis.',
+    );
+  }
+
+  if (projectRoot && !lockPresent) {
+    suggestions.push('Run uv lock to create uv.lock so dependency drift can be detected.');
+  }
+
+  return {
+    interpreter,
+    python,
+    projectRoot,
+    venvDir,
+    uv: { available: uvVersion !== undefined, version: uvVersion, lockPresent },
+    tools,
+    warnings,
+    suggestions,
+  };
+}

package/src/environment/tools.ts

@@ -0,0 +1,141 @@
+import { constants } from 'node:fs';
+import { access, stat } from 'node:fs/promises';
+import { delimiter, join } from 'node:path';
+import { normalizeDistributionName } from '../project/installed.ts';
+import type { LockPackage } from '../project/scanner.ts';
+
+/**
+ * Tools worth reporting to the agent. Lint and type diagnostics are delegated
+ * to other extensions, but the agent still needs to know whether the project
+ * environment provides these executables.
+ */
+export const DEFAULT_PROBED_TOOLS = [
+  'pytest',
+  'ruff',
+  'mypy',
+  'ty',
+  'pyright',
+  'pre-commit',
+] as const;
+
+export type ToolVersionSource = 'lock' | 'cli' | 'unknown';
+
+export interface ToolAvailability {
+  name: string;
+  /** True when the tool is runnable, either locally or through `uv run`. */
+  available: boolean;
+  /** True when `uv.lock` records the distribution, so `uv sync` can install it. */
+  declared: boolean;
+  /** Absolute path when an executable was found. */
+  executable?: string;
+  /** Where the executable was found: the project environment or the host PATH. */
+  origin?: 'venv' | 'path';
+  version?: string;
+  versionSource: ToolVersionSource;
+  preferredInvocation: string;
+}
+
+const WINDOWS = process.platform === 'win32';
+const WINDOWS_EXTENSIONS = ['.exe', '.cmd', '.bat', '.ps1'];
+
+function executableNames(name: string): string[] {
+  return WINDOWS ? WINDOWS_EXTENSIONS.map((extension) => `${name}${extension}`) : [name];
+}
+
+async function isExecutableFile(path: string): Promise<boolean> {
+  try {
+    const info = await stat(path);
+    if (!info.isFile()) return false;
+    if (WINDOWS) return true;
+    await access(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Find a console script inside a virtual environment. uv puts scripts in `bin`
+ * on POSIX and `Scripts` on Windows; both are checked so a project analysed on
+ * either platform reports the same tools.
+ */
+export async function findVenvScript(venvDir: string, name: string): Promise<string | undefined> {
+  const directories = WINDOWS
+    ? [join(venvDir, 'Scripts'), join(venvDir, 'bin')]
+    : [join(venvDir, 'bin'), join(venvDir, 'Scripts')];
+  for (const directory of directories) {
+    for (const candidate of executableNames(name)) {
+      const path = join(directory, candidate);
+      if (await isExecutableFile(path)) return path;
+    }
+  }
+  return undefined;
+}
+
+/** Resolve an executable on PATH without spawning a process. */
+export async function resolveOnPath(
+  name: string,
+  pathValue: string = process.env.PATH ?? '',
+): Promise<string | undefined> {
+  for (const directory of pathValue.split(delimiter)) {
+    if (!directory) continue;
+    for (const candidate of executableNames(name)) {
+      const path = join(directory, candidate);
+      if (await isExecutableFile(path)) return path;
+    }
+  }
+  return undefined;
+}
+
+/** Versions the lockfile pins, keyed by normalized distribution name. */
+export function lockedVersions(lockPackages: LockPackage[] | undefined): Map<string, string> {
+  const versions = new Map<string, string>();
+  for (const entry of lockPackages ?? []) {
+    if (entry.version) versions.set(entry.normalized, entry.version);
+  }
+  return versions;
+}
+
+export interface ToolProbeInput {
+  venvDir?: string;
+  lockPackages?: LockPackage[];
+  names?: readonly string[];
+  pathValue?: string;
+}
+
+/**
+ * Report which tools the project can run, using only filesystem probes and the
+ * already-parsed lockfile.
+ *
+ * Executing `--version` per tool was the single largest cost in
+ * `py_environment` (pytest alone spent 154 ms importing itself), and it reported
+ * the *host* version rather than the one the project will use. The lockfile is
+ * the authoritative source for a project tool, and PATH or `.venv/bin`
+ * presence answers the availability question without a subprocess.
+ */
+export async function inspectTools(input: ToolProbeInput = {}): Promise<ToolAvailability[]> {
+  const names = input.names ?? DEFAULT_PROBED_TOOLS;
+  const locked = lockedVersions(input.lockPackages);
+
+  return Promise.all(
+    names.map(async (name) => {
+      const normalized = normalizeDistributionName(name);
+      const venvScript = input.venvDir ? await findVenvScript(input.venvDir, name) : undefined;
+      const pathScript = venvScript ? undefined : await resolveOnPath(name, input.pathValue);
+      const lockVersion = locked.get(normalized);
+      const executable = venvScript ?? pathScript;
+      const origin = venvScript ? 'venv' : pathScript ? 'path' : undefined;
+
+      return {
+        name,
+        available: Boolean(executable) || lockVersion !== undefined,
+        declared: lockVersion !== undefined,
+        executable,
+        origin,
+        version: lockVersion,
+        versionSource: lockVersion ? 'lock' : 'unknown',
+        preferredInvocation: `uv run --frozen ${name}`,
+      } satisfies ToolAvailability;
+    }),
+  );
+}