pi-python-helper 0.1.1 → 0.3.0

package/package.json

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

package/skills/python-development/SKILL.md

@@ -10,32 +10,40 @@ 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`을 미리보기/실행하세요.
-9. 재현이 어려운 실패는 `py_test`의 `lastFailed=true`(`--lf`)로 직전 실패만 다시 실행하세요.
-10. 작업 완료를 보고하기 전에 `py_validation_bundle`(lock 검사 → sync → pytest → 환경 정합성 → 오래된 아티팩트 검사)을 실행하고, `py_completion_evidence`로 근거가 충분한지 확인하세요. 정합성이 `drifted`나 `unverifiable`이면 테스트가 통과했어도 게이트는 실패합니다.
-11. `py_tdd_checkpoint`로 프로덕션 변경에 대응하는 테스트 변경이 있는지 확인하세요.
+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_test_config`로 pytest 설정을 검증하세요. `ASYNC_TESTS_WITHOUT_PLUGIN`/`ASYNC_TESTS_REQUIRE_MARKER`는 async 테스트가 **수집만 되고 실행되지 않는** 상태(플러그인 미선언 또는 `asyncio_mode` 미설정 + 마커 없음)를 뜻하며, `COVERAGE_OPTION_WITHOUT_PLUGIN`과 `ASYNCIO_MODE_WITHOUT_PLUGIN`은 실행 전에 pytest가 오류로 중단되는 설정입니다. `TESTPATH_MISSING`은 `testpaths`가 존재하지 않는 디렉터리를 가리킨다는 경고입니다.
+8. 실패 출력이 있을 때는 `py_failure_diagnose`를 사용하세요. `site-packages` 내부 프레임은 원인이 아니며, 도구는 첫 번째 프로젝트 프레임을 지목합니다. 실행 파일을 찾지 못해 명령이 시작되지 못한 경우(`Failed to spawn`, `command not found`)는 `tool_not_installed`로 분류됩니다.
+9. 의존성이 바뀌었거나 `.venv`가 오래된 경우 `py_sync`로 `uv lock --check` 또는 `uv sync --frozen`을 미리보기/실행하세요. sync는 `[project.optional-dependencies]`의 extra를 함께 요청하므로 dev 도구가 extra로 선언된 프로젝트에서도 삭제되지 않습니다. `SYNC_REMOVED_PACKAGES`가 보이면 그것이 이후 "command not found"의 원인입니다.
+10. 재현이 어려운 실패는 `py_test`의 `lastFailed=true`(`--lf`)로 직전 실패만 다시 실행하세요.
+11. 작업 완료를 보고하기 전에 `py_validation_bundle`(lock 검사 → sync → pytest → 환경 정합성 → 오래된 아티팩트 검사)을 실행하고, `py_completion_evidence`로 근거가 충분한지 확인하세요. 정합성이 `drifted`나 `unverifiable`이면 테스트가 통과했어도 게이트는 실패합니다. 각 응답에서 조치 필요 여부는 `attention`으로 판단하세요.
+12. `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` 수정은 항상 명시적인 편집 도구로 수행하세요.
 
 ## 해석 규칙 (Interpretation rules)
 
+- `ok`는 도구의 **판정**이며 "도구가 실행됐다"는 뜻이 아닙니다. 검사 도구는 문제를 찾으면 도구 자체가 실패하지 않았어도 `ok: false`를 반환합니다. 조치가 필요한지는 `attention`을 읽으세요: `ok: false`이거나 경고·오류가 하나라도 있으면 `true`입니다.
+- `ok: false`에는 항상 그것을 설명하는 진단(`warnings` 또는 `errors`)이 함께 옵니다. 설명 없는 `ok: false`를 보면 도구 결함이므로 그대로 보고하세요. 게이트 도구는 판정을 `data.ok`(`checkpoint.ok`, `evidence.ok`, `summary.ok`)에도 노출합니다.
 - `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,8 @@
 import type { Suggestion } from '../core/result.ts';
+import { importAliasCandidates } from '../dependencies/aliases.ts';
 
 export type FailureKind =
+  | 'tool_not_installed'
   | 'module_not_found'
   | 'environment_not_synced'
   | 'import_error'
@@ -33,6 +35,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 +128,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 +196,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,8 +213,34 @@ 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];
+    // The traceback names an import, not a distribution. `uv add <import name>`
+    // installs a different package or nothing at all when the two disagree, so a
+    // command is emitted only when the alias table yields exactly one provider.
+    const providers = importAliasCandidates(module);
+    const resolveSuggestion: Suggestion =
+      providers.length === 1
+        ? {
+            message: `Declare the distribution providing "${module}" with uv add ${providers[0]} if it is third-party. Import names often differ from distribution names (PIL/pillow, yaml/PyYAML).`,
+            confidence: 'medium',
+            command: `uv add ${providers[0]}`,
+          }
+        : {
+            message:
+              providers.length > 1
+                ? `"${module}" is provided by more than one distribution (${providers.join(', ')}). Verify which one the project needs before adding it.`
+                : `The distribution providing "${module}" is unknown. Verify the distribution name before adding it; import names often differ from distribution names (PIL/pillow, yaml/PyYAML).`,
+            confidence: 'medium',
+          };
     return {
       kind: 'module_not_found',
       summary: `Import failed because the module "${module}" could not be found.`,
@@ -175,11 +250,7 @@ export function diagnoseFailure(output: string): FailureDiagnosis {
       firstUserFrame: userFrame,
       evidence: [{ message: missing[0].trim(), file: userFrame?.path, line: userFrame?.line }],
       suggestions: [
-        {
-          message: `Declare the distribution that provides "${module}" with uv add ${module} if it is third-party. Import names often differ from distribution names (PIL/pillow, yaml/PyYAML).`,
-          confidence: 'medium',
-          command: `uv add ${module}`,
-        },
+        resolveSuggestion,
         {
           message:
             'If the module is project code, run uv sync so the project package is installed in editable mode.',
@@ -348,7 +419,6 @@ export function refineWithDeclarations(
   const module = diagnosis.missingModule;
   if (!module) return diagnosis;
   const normalized = module.replace(/[-_.]+/g, '-').toLowerCase();
-  const suggestions: Suggestion[] = [];
 
   if (input.localModules.has(module)) {
     return {
@@ -391,14 +461,9 @@ export function refineWithDeclarations(
     };
   }
 
-  suggestions.push({
-    message: `Declare the distribution providing "${module}" with uv add ${module}, or verify the import name.`,
-    confidence: 'medium',
-    command: `uv add ${module}`,
-  });
-  suggestions.push({
-    message: 'Import names can differ from distribution names (PIL/pillow, yaml/PyYAML).',
-    confidence: 'medium',
-  });
-  return { ...diagnosis, suggestions: [...diagnosis.suggestions, ...suggestions] };
+  // The module is neither project code nor declared, so this refinement adds no
+  // new information: `diagnoseFailure` already reported the unknown provider.
+  // Appending here duplicated those suggestions, so the diagnosis is returned
+  // unchanged.
+  return diagnosis;
 }

package/src/build/pytest-audit.ts

@@ -0,0 +1,226 @@
+import { normalizeName } from '../dependencies/plan.ts';
+
+/**
+ * The pytest options this audit reasons about. Only options whose absence
+ * changes whether tests *run* are read, so an unknown option can never be
+ * misreported: pytest silently ignores a key it does not know, and so does this.
+ */
+export interface PytestOptions {
+  asyncioMode?: string;
+  addopts?: string;
+  testpaths: string[];
+  markers: string[];
+}
+
+export interface PytestConfigResolution {
+  /** The configuration file pytest will actually use, when one exists. */
+  sources: string[];
+  options: PytestOptions;
+}
+
+/**
+ * pytest uses the first configuration file it finds, in this order, and ignores
+ * the rest. Merging them would invent options the run never sees.
+ */
+export const PYTEST_CONFIG_PRECEDENCE = [
+  'pytest.ini',
+  'pyproject.toml',
+  'tox.ini',
+  'setup.cfg',
+] as const;
+
+const INI_SECTION_RE = /^\s*\[(?:tool:)?pytest\]\s*$/m;
+
+function emptyOptions(): PytestOptions {
+  return { testpaths: [], markers: [] };
+}
+
+function stringOption(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function stringList(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value.filter((entry): entry is string => typeof entry === 'string');
+  }
+  if (typeof value === 'string') {
+    return value.split(/\s+/).filter((entry) => entry.length > 0);
+  }
+  return [];
+}
+
+/**
+ * Read the `[pytest]` / `[tool:pytest]` section of one INI file.
+ *
+ * `undefined` means "this file does not configure pytest". A file that has the
+ * section but none of the options still counts as configured, so the caller can
+ * distinguish "no configuration" from "configuration with defaults".
+ */
+export function parseIniPytestOptions(content: string | undefined): PytestOptions | undefined {
+  if (content === undefined) return undefined;
+  const header = INI_SECTION_RE.exec(content);
+  if (!header) return undefined;
+  const rest = content.slice(header.index + header[0].length);
+  const nextSection = rest.search(/^\s*\[/m);
+  const body = nextSection === -1 ? rest : rest.slice(0, nextSection);
+  const read = (key: string): string | undefined => {
+    const found = new RegExp(`^[ \\t]*${key}[ \\t]*=[ \\t]*(.*)$`, 'm').exec(body);
+    const raw = found?.[1]?.trim();
+    return raw ? raw : undefined;
+  };
+
+  const asyncioMode = read('asyncio_mode');
+  const addopts = read('addopts');
+  const testpaths = read('testpaths');
+  return {
+    ...(asyncioMode ? { asyncioMode } : {}),
+    ...(addopts ? { addopts } : {}),
+    testpaths: testpaths ? testpaths.split(/\s+/).filter((entry) => entry.length > 0) : [],
+    markers: [],
+  };
+}
+
+/**
+ * Resolve the options pytest will use, honouring its first-file-wins rule.
+ *
+ * `pytest.ini` counts when it merely exists: unlike `tox.ini`/`setup.cfg` it has
+ * no other purpose, so an empty file still sets the rootdir configuration.
+ */
+export function resolvePytestOptions(input: {
+  pyprojectOptions?: Record<string, unknown> | null;
+  iniFiles: Record<string, string | undefined>;
+}): PytestConfigResolution {
+  const raw = input.pyprojectOptions;
+  const fromPyproject: PytestOptions | undefined = raw
+    ? {
+        ...(stringOption(raw['asyncio_mode'])
+          ? { asyncioMode: stringOption(raw['asyncio_mode']) }
+          : {}),
+        ...(stringOption(raw['addopts']) ? { addopts: stringOption(raw['addopts']) } : {}),
+        testpaths: stringList(raw['testpaths']),
+        markers: stringList(raw['markers']),
+      }
+    : undefined;
+
+  const pytestIni = input.iniFiles['pytest.ini'];
+  const candidates: Record<string, PytestOptions | undefined> = {
+    'pytest.ini':
+      pytestIni === undefined ? undefined : (parseIniPytestOptions(pytestIni) ?? emptyOptions()),
+    'pyproject.toml': fromPyproject,
+    'tox.ini': parseIniPytestOptions(input.iniFiles['tox.ini']),
+    'setup.cfg': parseIniPytestOptions(input.iniFiles['setup.cfg']),
+  };
+
+  for (const name of PYTEST_CONFIG_PRECEDENCE) {
+    const options = candidates[name];
+    if (options) return { sources: [name], options };
+  }
+  return { sources: [], options: emptyOptions() };
+}
+
+export interface AsyncTestFile {
+  path: string;
+  /** Async test names in this file that carry no async plugin marker. */
+  tests: string[];
+}
+
+export interface PytestAuditInput {
+  sources: string[];
+  options: PytestOptions;
+  declared: Set<string>;
+  /** Async tests that no marker covers, per file. */
+  unmarkedAsyncTests: AsyncTestFile[];
+  /** Configured `testpaths` entries that do not exist on disk. */
+  missingTestPaths: string[];
+  hasTestFiles: boolean;
+}
+
+export interface PytestFinding {
+  code: string;
+  severity: 'info' | 'warning' | 'error';
+  message: string;
+  suggestion?: string;
+}
+
+/** Plugins that make pytest run a coroutine test function at all. */
+const ASYNC_PLUGINS = ['pytest-asyncio', 'pytest-anyio', 'anyio', 'pytest-trio'];
+
+function declares(declared: Set<string>, names: string[]): boolean {
+  return names.some((name) => declared.has(normalizeName(name)));
+}
+
+/**
+ * Report the pytest configuration problems that make tests pass without running.
+ *
+ * Only two things are asserted: coroutine tests that no plugin and no marker
+ * will execute, and options that point at a plugin the project does not declare.
+ * Anything less certain is reported as `info` so a false alarm cannot erode the
+ * tool's credibility.
+ */
+export function auditPytestConfiguration(input: PytestAuditInput): PytestFinding[] {
+  const findings: PytestFinding[] = [];
+  const { options, declared } = input;
+  const unmarkedFiles = input.unmarkedAsyncTests.filter((entry) => entry.tests.length > 0);
+  const unmarkedCount = unmarkedFiles.reduce((total, entry) => total + entry.tests.length, 0);
+  const asyncPluginDeclared = declares(declared, ASYNC_PLUGINS);
+  const mode = (options.asyncioMode ?? '').trim().toLowerCase();
+
+  if (unmarkedCount > 0 && !asyncPluginDeclared) {
+    findings.push({
+      code: 'ASYNC_TESTS_WITHOUT_PLUGIN',
+      severity: 'error',
+      message: `${unmarkedCount} async test function(s) in ${unmarkedFiles.length} file(s) will not run: no pytest async plugin is declared.`,
+      suggestion:
+        'Declare pytest-asyncio with uv add --dev pytest-asyncio and mark the tests, or add pytest-asyncio and set asyncio_mode = "auto".',
+    });
+  } else if (unmarkedCount > 0 && mode !== 'auto') {
+    findings.push({
+      code: 'ASYNC_TESTS_REQUIRE_MARKER',
+      severity: 'error',
+      message: `${unmarkedCount} async test function(s) in ${unmarkedFiles.length} file(s) carry no async marker and asyncio_mode is not "auto", so pytest-asyncio's strict default will skip them.`,
+      suggestion:
+        'Set asyncio_mode = "auto" in [tool.pytest.ini_options], or add @pytest.mark.asyncio to each async test.',
+    });
+  }
+
+  if (mode.length > 0 && !declares(declared, ['pytest-asyncio'])) {
+    findings.push({
+      code: 'ASYNCIO_MODE_WITHOUT_PLUGIN',
+      severity: 'error',
+      message: `asyncio_mode is set to "${options.asyncioMode}" but pytest-asyncio is not declared, so pytest errors with an unknown option before collecting anything.`,
+      suggestion:
+        'Declare pytest-asyncio with uv add --dev pytest-asyncio, or remove asyncio_mode from the pytest configuration.',
+    });
+  }
+
+  const addopts = options.addopts ?? '';
+  if (/(^|\s)--cov(=|\s|$)/.test(addopts) && !declares(declared, ['pytest-cov'])) {
+    findings.push({
+      code: 'COVERAGE_OPTION_WITHOUT_PLUGIN',
+      severity: 'error',
+      message:
+        'addopts passes --cov but pytest-cov is not declared, so every run fails with an unrecognized argument.',
+      suggestion: 'Declare pytest-cov with uv add --dev pytest-cov, or remove --cov from addopts.',
+    });
+  }
+
+  for (const path of input.missingTestPaths) {
+    findings.push({
+      code: 'TESTPATH_MISSING',
+      severity: 'warning',
+      message: `testpaths lists "${path}", which does not exist, so a bare pytest run collects nothing from it.`,
+      suggestion: `Create ${path} or correct testpaths in ${input.sources[0] ?? 'the pytest configuration'}.`,
+    });
+  }
+
+  if (input.sources.length === 0 && input.hasTestFiles) {
+    findings.push({
+      code: 'PYTEST_NOT_CONFIGURED',
+      severity: 'info',
+      message:
+        'No pytest configuration was found: pytest runs with defaults, so testpaths and plugin options are not pinned anywhere.',
+    });
+  }
+
+  return findings;
+}

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