pi-python-helper 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-python-helper",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Python (uv) development tools for the pi coding agent",
   "type": "module",
   "keywords": [

package/skills/python-development/SKILL.md

@@ -10,24 +10,24 @@ license: Apache-2.0
 
 ## 조사 및 작업 순서 (Investigation order)
 
-1. 인터프리터나 가상환경 상태가 불확실할 때는 `py_environment`를 실행하세요. 잘못된 Python으로 테스트를 실행하는 것이 가장 흔한 실패 원인입니다.
+1. 인터프리터나 가상환경 상태가 불확실할 때는 `py_environment`를 실행하세요. 잘못된 Python으로 테스트를 실행하는 것이 가장 흔한 실패 원인입니다. `interpreterOrigin: 'venv'`이면 분석이 프로젝트 환경을 봤다는 뜻이고, `'path'`이면 호스트 PATH의 Python을 봤다는 뜻입니다. `available`은 "지금 실행 가능", `installable`은 "uv sync로 설치 가능"(선언되었지만 실행 파일 없음)입니다.
 2. `pyproject.toml`이나 `uv.lock`을 편집하기 전에 `py_project_inspect`로 레이아웃(src/flat), 의존성 그룹, lockfile 드리프트, **환경 정합성**(선언 ↔ lock ↔ 실제 설치본)을 확인하세요. 정합성은 `consistent` / `drifted` / `unverifiable` 중 하나이며, `unverifiable`을 일치로 해석하지 마세요.
 3. 의존성을 추가/이동하기 전에 `py_dependency_plan`을 사용하세요. `ast`로 실제 import를 스캔하여 다음을 구분합니다:
    - 선언되지 않은 import (런타임 오류로 이어짐)
    - `[project] dependencies`가 아니라 dev 그룹/extra에만 선언된 런타임 import
    - `uv.lock`에 없거나 스펙을 만족하지 않는 버전
 4. import 이름과 배포 이름은 다를 수 있습니다(`PIL`/`pillow`, `yaml`/`PyYAML`). `py_dependency_plan`의 제안을 `uv add`로 적용하세요.
-5. 소스 코드를 수정한 후에는 `py_test_select`로 변경 파일과 연관된 테스트를 선별하세요. 매칭이 실패하면 전체 스위트가 범위가 되며, 선택 이유가 함께 반환됩니다.
-6. 테스트 실행은 `py_test`를 사용하세요. `execute=false`로 먼저 미리보기하고, 실제 실행 시에만 `execute=true`를 전달합니다.
-7. 실패 출력이 있을 때는 `py_failure_diagnose`를 사용하세요. `site-packages` 내부 프레임은 원인이 아니며, 도구는 첫 번째 프로젝트 프레임을 지목합니다.
-8. 의존성이 바뀌었거나 `.venv`가 오래된 경우 `py_sync`로 `uv lock --check` 또는 `uv sync --frozen`을 미리보기/실행하세요.
+5. 소스 코드를 수정한 후에는 `py_test_select`로 변경 파일과 연관된 테스트를 선별하세요. 테스트가 변경 모듈을 **실제로 import**하면 가장 강한 근거이며, 이름 규약은 그 다음입니다. `narrowed: false`나 `NO_NARROWING`은 "30개 중 30개 선택"처럼 결과가 좁혀지지 않았다는 뜻이고, `SELECTION_WITHOUT_IMPORT_EVIDENCE`는 근거가 파일 이름뿐이라는 뜻이므로 변경이 넓다면 전체 스위트나 `lastFailed=true`를 사용하세요.
+6. 테스트 실행은 `py_test`를 사용하세요. `execute=false`로 먼저 미리보기하고, 실제 실행 시에만 `execute=true`를 전달합니다. 커버리지 플래그나 `-m` 마커 선택처럼 도구가 모델링하지 않는 프로젝트 표준 옵션은 `extraArgs`로 넘기세요.
+7. 실패 출력이 있을 때는 `py_failure_diagnose`를 사용하세요. `site-packages` 내부 프레임은 원인이 아니며, 도구는 첫 번째 프로젝트 프레임을 지목합니다. 실행 파일을 찾지 못해 명령이 시작되지 못한 경우(`Failed to spawn`, `command not found`)는 `tool_not_installed`로 분류됩니다.
+8. 의존성이 바뀌었거나 `.venv`가 오래된 경우 `py_sync`로 `uv lock --check` 또는 `uv sync --frozen`을 미리보기/실행하세요. sync는 `[project.optional-dependencies]`의 extra를 함께 요청하므로 dev 도구가 extra로 선언된 프로젝트에서도 삭제되지 않습니다. `SYNC_REMOVED_PACKAGES`가 보이면 그것이 이후 "command not found"의 원인입니다.
 9. 재현이 어려운 실패는 `py_test`의 `lastFailed=true`(`--lf`)로 직전 실패만 다시 실행하세요.
 10. 작업 완료를 보고하기 전에 `py_validation_bundle`(lock 검사 → sync → pytest → 환경 정합성 → 오래된 아티팩트 검사)을 실행하고, `py_completion_evidence`로 근거가 충분한지 확인하세요. 정합성이 `drifted`나 `unverifiable`이면 테스트가 통과했어도 게이트는 실패합니다.
 11. `py_tdd_checkpoint`로 프로덕션 변경에 대응하는 테스트 변경이 있는지 확인하세요.
 
 ## 안전 규칙 (Safety)
 
-- `py_sync`와 `py_validation_bundle`은 `execute: true`가 명시적으로 전달되기 전까지 명령을 실행하지 않고 미리보기만 반환합니다. `execute=true`는 `.venv`를 생성/갱신하므로 사용자 확인 없이 반복 실행하지 마세요.
+- `py_sync`와 `py_validation_bundle`은 `execute: true`가 명시적으로 전달되기 전까지 명령을 실행하지 않고 미리보기만 반환합니다. `execute=true`는 `.venv`를 생성/갱신하므로 사용자 확인 없이 반복 실행하지 마세요. `extras: 'none'`은 프로젝트가 요청할 때만 사용하세요: extra로 선언된 dev 도구를 삭제할 수 있습니다.
 - Python에는 ROS의 `cmd_vel`처럼 위험을 결정론적으로 알려주는 이름이 없습니다. 다음은 되돌릴 수 없는 작업으로 취급하세요: `uv publish`/`twine upload`(공개 불가 회수), `git push --force`, `git reset --hard`/`git clean -fd`, `alembic downgrade`, `DROP`/`DELETE`(WHERE 없는), `rm -rf`, `conda env remove`.
 - 가상환경을 파괴하는 명령(`rm -rf .venv`, `uv venv --clear`)이나 전역 Python에 패키지를 설치하는 명령(`pip install` without a venv)을 임의로 실행하지 마세요.
 - 도구는 파일을 쓰지 않습니다. `pyproject.toml`/`uv.lock` 수정은 항상 명시적인 편집 도구로 수행하세요.
@@ -36,6 +36,11 @@ license: Apache-2.0
 
 - `PROJECT_INSTALLED_NOT_EDITABLE`는 프로젝트가 환경에 live link가 아니라 복사본으로 설치되어, 소스 변경이 테스트에 반영되지 않음을 의미합니다. `uv sync`로 해결하세요.
 - `PROJECT_NOT_INSTALLED`는 lock이 editable 설치를 기대하는데 `.venv`에 프로젝트가 없다는 뜻입니다. `uv sync`를 실행하고, 그래도 실패하면 빌드 백엔드가 패키지를 찾지 못한 것입니다(`[project] name`과 모듈 디렉터리 이름이 일치하는지 확인).
+- `PROJECT_VIRTUAL_SOURCE`는 정상입니다. `[build-system]`이 없으면 uv는 프로젝트를 `virtual` 소스로 기록하고 `.venv`에 설치하지 않습니다. 누락(`PROJECT_NOT_INSTALLED`)으로 취급하지 말고 `[build-system]` 추가 여부만 검토하세요.
+- `MARKER_SPLIT_LOCK_ENTRIES`는 정상입니다. uv가 같은 배포판을 마커별로 여러 버전으로 기록한 것이며, 설치 버전이 그중 하나와 일치하면 드리프트가 아닙니다.
+- `TOOL_NOT_INSTALLED`는 lock에는 있지만 `.venv`에 실행 파일이 없다는 뜻입니다. `uv sync` 직후에 발생했다면 sync가 extra를 삭제한 것이므로 `uv sync --frozen --all-groups --all-extras`로 복구하세요.
+- `SYNC_REMOVED_PACKAGES`는 sync가 `.venv`에서 패키지를 제거했음을 뜻하며, 같은 실행에서 이어지는 "command not found"의 원인입니다.
+- `UNMAPPED_IMPORTS`는 분석한 인터프리터가 import를 배포판에 연결하지 못했다는 뜻입니다. 이 상태에서는 `UNDECLARED_IMPORT`가 "선언 누락"이 아니라 "배포 이름 미확인"일 수 있으므로, 제안된 `uv add` 명령이 없으면 배포 이름을 직접 확인하세요.
 - `INSTALLED_VERSION_MISMATCH`는 `uv add`/`uv lock` 후 `uv sync`를 잊은 상태입니다. `uv lock --check`는 이걸 잡지 못하니(락은 최신) 테스트를 신뢰하기 전에 `uv sync --frozen`을 실행하세요.
 - `INSTALLED_PACKAGE_UNTRACKED`는 `.venv`에만 있고 lock에 없는 패키지입니다. 에이전트가 `uv pip install`로 임의 설치했을 가능성을 의심하세요.
 - `CONDITIONAL_PACKAGES_ABSENT`는 정상입니다. `sys_platform == 'win32'`나 `python_version < '3.11'` 같은 마커 때문에 해당 플랫폼에 설치되지 않은 항목이며, 드리프트로 취급하지 마세요.

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'
@@ -15,13 +16,13 @@ export type FailureKind =
   | 'timeout'
   | 'unknown';
 
-export interface TracebackFrame {
-  path: string;
-  line: number;
-  func: string;
-  /** True for site-packages, the standard library, and pytest internals. */
-  library: boolean;
-}
+import {
+  extractTracebackFrames,
+  firstUserFrame,
+  isLibraryFrame,
+  type TracebackFrame,
+} from './traceback.ts';
+export { extractTracebackFrames, firstUserFrame, isLibraryFrame, type TracebackFrame };
 
 export interface FailureEvidence {
   file?: string;
@@ -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[];
@@ -42,54 +45,6 @@ export interface FailureDiagnosis {
   suggestions: Suggestion[];
 }
 
-const FRAME_RE = /^\s*File "([^"]+)", line (\d+), in (.+?)\s*$/;
-/**
- * pytest `--tb=short` replaces the `File "..."` form with `path:line: in func`,
- * so both notations must be recognised or short tracebacks yield no frame at all.
- */
-const PYTEST_FRAME_RE = /^\s*([^\s:]+\.py):(\d+): in (.+?)\s*$/;
-
-/**
- * A frame belongs to library code when it sits in an installed distribution or
- * in the interpreter's own library tree. Pointing the agent at those frames is
- * how it ends up editing site-packages instead of the project.
- */
-export function isLibraryFrame(path: string): boolean {
-  const normalized = path.replace(/\\/g, '/');
-  return (
-    /\/site-packages\//.test(normalized) ||
-    /\/dist-packages\//.test(normalized) ||
-    /\/lib\/python3\.\d+\//.test(normalized) ||
-    /\/python3\.\d+\//.test(normalized) ||
-    /<frozen /.test(normalized) ||
-    /\/_pytest\//.test(normalized) ||
-    /\/pluggy\//.test(normalized)
-  );
-}
-
-export function extractTracebackFrames(output: string): TracebackFrame[] {
-  const frames: TracebackFrame[] = [];
-  for (const line of output.split(/\r?\n/)) {
-    const match = line.match(FRAME_RE) ?? line.match(PYTEST_FRAME_RE);
-    if (!match) continue;
-    const path = match[1];
-    frames.push({
-      path,
-      line: Number.parseInt(match[2], 10),
-      func: match[3].trim(),
-      library: isLibraryFrame(path),
-    });
-  }
-  return frames;
-}
-
-function firstUserFrame(frames: TracebackFrame[]): TracebackFrame | undefined {
-  for (let index = frames.length - 1; index >= 0; index -= 1) {
-    if (!frames[index].library) return frames[index];
-  }
-  return undefined;
-}
-
 function lastMatch(output: string, pattern: RegExp): RegExpMatchArray | undefined {
   const matches = [...output.matchAll(new RegExp(pattern.source, `${pattern.flags}g`))];
   return matches.at(-1);
@@ -172,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,
@@ -200,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)/);
@@ -212,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}.`;
+}