pi-python-helper 0.1.1 → 0.2.0

package/src/build/commands.ts

@@ -19,8 +19,23 @@ export function uvLock(cwd: string): CommandPreview {
   return { executable: 'uv', args: ['lock'], cwd, risk: 'mutating' };
 }
 
-export function uvSyncFrozen(cwd: string): CommandPreview {
-  return { executable: 'uv', args: ['sync', '--frozen', '--all-groups'], cwd, risk: 'mutating' };
+export interface UvSyncOptions {
+  /**
+   * `all` requests every extra declared in `[project.optional-dependencies]`.
+   *
+   * `uv sync --all-groups` covers `[dependency-groups]` only, so a project that
+   * declares pytest/ruff/pyright as an extra has them **removed** by a plain
+   * sync. Installing more than needed is recoverable; deleting the project's
+   * own dev tooling mid-run is not, so extras are requested by default.
+   */
+  extras?: 'all' | 'none';
+}
+
+export function uvSyncFrozen(cwd: string, options: UvSyncOptions = {}): CommandPreview {
+  const extras = options.extras ?? 'all';
+  const args = ['sync', '--frozen', '--all-groups'];
+  if (extras === 'all') args.push('--all-extras');
+  return { executable: 'uv', args, cwd, risk: 'mutating' };
 }
 
 export function uvRun(cwd: string, args: string[]): CommandPreview {

package/src/build/failure.ts

@@ -1,6 +1,7 @@
 import type { Suggestion } from '../core/result.ts';
 
 export type FailureKind =
+  | 'tool_not_installed'
   | 'module_not_found'
   | 'environment_not_synced'
   | 'import_error'
@@ -33,6 +34,8 @@ export interface FailureDiagnosis {
   kind: FailureKind;
   summary: string;
   missingModule?: string;
+  /** Executable the command tried to start but could not find. */
+  missingTool?: string;
   importTarget?: { name: string; module: string };
   exceptionType?: string;
   frames: TracebackFrame[];
@@ -124,6 +127,46 @@ export function diagnoseFailure(output: string): FailureDiagnosis {
     };
   }
 
+  // An environment failure is not a code failure. It appears as a spawn error
+  // rather than a traceback, so it must be classified before the traceback
+  // patterns or the whole run reads as an unclassifiable crash.
+  const spawnFailure = lastMatch(output, /Failed to spawn:?\s*`?([A-Za-z0-9._+-]+)`?/);
+  const commandNotFound = lastMatch(
+    output,
+    /(?:^|\n)\s*(?:sh: |bash: )?([A-Za-z0-9._+-]+): (?:command not found|No such file or directory)/,
+  );
+  const missingExecutable = spawnFailure ?? commandNotFound;
+  const toolNotInstalled = (tool: string, matchedText: string): FailureDiagnosis => {
+    const noEntry = /No such file or directory/.test(output) || /command not found/.test(output);
+    return {
+      kind: 'tool_not_installed',
+      summary: noEntry
+        ? `The command could not start because "${tool}" is not installed in the environment that ran it.`
+        : `The command could not start: ${matchedText}`,
+      missingTool: tool,
+      exceptionType: 'environment',
+      frames,
+      firstUserFrame: userFrame,
+      evidence: [{ message: matchedText }],
+      suggestions: [
+        {
+          message: `Install the project environment so "${tool}" is available, then rerun through uv run.`,
+          confidence: 'high',
+          command: 'uv sync --frozen --all-groups --all-extras',
+        },
+        {
+          message:
+            'A plain uv sync removes extras declared in [project.optional-dependencies], which is the usual reason a declared tool disappears mid-run.',
+          confidence: 'high',
+        },
+        {
+          message: `Run the tool from the project environment with uv run --frozen ${tool}.`,
+          confidence: 'high',
+        },
+      ],
+    };
+  };
+
   const missing = lastMatch(output, /ModuleNotFoundError: No module named '([^']+)'/);
   const cannotImport = lastMatch(
     output,
@@ -152,6 +195,11 @@ export function diagnoseFailure(output: string): FailureDiagnosis {
     if (match?.index !== undefined) candidates.push({ kind, index: match.index });
   };
   consider('module_not_found', /ModuleNotFoundError: No module named '([^']+)'/);
+  consider('tool_not_installed', /Failed to spawn:?\s*`?([A-Za-z0-9._+-]+)`?/);
+  consider(
+    'tool_not_installed',
+    /(?:^|\n)\s*(?:sh: |bash: )?([A-Za-z0-9._+-]+): (?:command not found|No such file or directory)/,
+  );
   consider('import_error', /ImportError: cannot import name '([^']+)' from '([^']+)'/);
   consider('syntax_error', /SyntaxError: (.+)/);
   consider('fixture_error', /(?:fixture '[^']+' not found|ERROR at setup of|error in .* fixture)/);
@@ -164,6 +212,14 @@ export function diagnoseFailure(output: string): FailureDiagnosis {
   candidates.sort((left, right) => left.index - right.index);
   const kind: FailureKind = candidates[0]?.kind ?? 'unknown';
 
+  // Dispatch on the positional winner. `tool_not_installed` can be the earliest
+  // cause even when a traceback follows it, so it is not checked before the
+  // positional comparison.
+  if (kind === 'tool_not_installed') {
+    const match = missingExecutable;
+    if (match) return toolNotInstalled(match[1], match[0].trim());
+  }
+
   if (kind === 'module_not_found' && missing) {
     const module = missing[1].split('.')[0];
     return {

package/src/build/quality.ts

@@ -0,0 +1,49 @@
+import { uvRun } from './commands.ts';
+import type { CommandPreview } from '../core/result.ts';
+
+/**
+ * Quality commands a validation bundle can run without any project-specific
+ * configuration. Every entry is invoked as an argument array through
+ * `uv run --frozen`, so the tool comes from the project environment.
+ */
+export interface QualityRunner {
+  /** Normalized distribution name that must be declared for this to run. */
+  distribution: string;
+  name: string;
+  args: string[];
+  /**
+   * mypy needs a `[tool.mypy]` table: run bare it reports every untyped
+   * third-party call, which is pre-existing noise rather than a regression.
+   */
+  requiresToolSection?: boolean;
+}
+
+export const QUALITY_RUNNERS: QualityRunner[] = [
+  { distribution: 'ruff', name: 'ruff', args: ['ruff', 'check', '.'] },
+  { distribution: 'pyright', name: 'pyright', args: ['pyright'] },
+  { distribution: 'mypy', name: 'mypy', args: ['mypy', '.'], requiresToolSection: true },
+];
+
+/**
+ * Pick the quality gates the project actually declares.
+ *
+ * Gating on the *declaration* rather than on a config file matches what CI
+ * usually runs: a project can run `ruff check .` with no `[tool.ruff]` table at
+ * all, and its absence from the gate would hide a real regression.
+ */
+export function selectQualityRunners(input: {
+  declared: Iterable<string>;
+  toolConfiguration?: Record<string, boolean>;
+}): QualityRunner[] {
+  const declared = new Set(input.declared);
+  const configuration = input.toolConfiguration ?? {};
+  return QUALITY_RUNNERS.filter((runner) => {
+    if (!declared.has(runner.distribution)) return false;
+    if (runner.requiresToolSection && configuration[runner.distribution] !== true) return false;
+    return true;
+  });
+}
+
+export function qualityCommands(cwd: string, runners: QualityRunner[]): CommandPreview[] {
+  return runners.map((runner) => uvRun(cwd, runner.args));
+}

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/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,