pi-python-helper 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ does not guarantee a stable public tool schema.
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-21
+
+### Added
+
+- `py_test_config` audits the pytest configuration pytest will actually use against the plugins the project declares and the tests on disk. It reports the cases that make a run look green while tests never execute (`ASYNC_TESTS_WITHOUT_PLUGIN`, `ASYNC_TESTS_REQUIRE_MARKER`), the options pytest rejects before collection (`ASYNCIO_MODE_WITHOUT_PLUGIN`, `COVERAGE_OPTION_WITHOUT_PLUGIN`), and a `testpaths` entry that does not exist (`TESTPATH_MISSING`). Only syntax separates an unmarked coroutine test from a marked one, so the decision is made on the AST rather than by matching text.
+- The scanner reports `[tool.pytest.ini_options]` as `manifest.pytestOptions` and, per scanned file, `asyncTests` and `asyncioMarkedTests` (protocol version 3).
+- Every tool response carries `attention`: `true` whenever the caller must act (`ok: false`, or a warning or error). It is derived centrally in `result()`, so `ok: false` always implies `attention: true` and no diagnostic is silently dropped. `ok` is now documented as the tool's **verdict** — "the project state is acceptable / the command succeeded / the gate may proceed" — rather than "the tool ran", so a check that finds a problem still returns `ok: false` without having failed. An `info` diagnostic is informational and does not raise `attention`.
+
+### Changed
+
+- **Breaking:** scanner protocol `SCANNER_VERSION` is now 3. A scanner reporting version 2 is rejected with `SCANNER_VERSION_MISMATCH`.
+
+### Fixed
+
+- `py_test_select` no longer returns `ok: false` with no diagnostic at all when the change set contains no Python file (or git reports no changes). An empty selection is an answer rather than a failure, so it now returns `ok: true` and explains itself with the `NO_CHANGED_PATHS` warning.
+- `py_failure_diagnose` no longer fabricates `uv add <import name>` for a `ModuleNotFoundError` whose providing distribution is unknown, matching the rule `py_dependency_plan` already follows. The alias table resolves a single provider (`yaml` → `uv add pyyaml`), while an import with several candidates (`cv2`) or none asks the caller to verify the distribution instead of installing the wrong package.
+- `py_failure_diagnose` no longer repeats the same suggestion twice when a missing module is neither project code nor declared. `refineWithDeclarations` appended its generic "verify the distribution" advice on top of what the classifier had already reported, so a single undeclared import produced two suggestions with two duplicates.
+
 ## [0.2.0] - 2026-09-22
 
 ### Fixed

package/docs/tools.md

@@ -12,6 +12,7 @@
 
 모든 도구는 동일한 `PyToolResult` 규격을 반환합니다. 반환 형태는 구조만 기록하며 값·경로·버전·소요시간은 스냅샷에서 제외합니다.
 
+- `attention`: boolean
 - `commands` (optional): array of
   - `args`: array<string>
   - `cwd`: string
@@ -466,6 +467,27 @@ Preview or run pytest through uv run --frozen and summarise failures by test, fi
   - `risk`: string
 - `executed`: boolean
 
+### `py_test_config`
+
+Audit pytest configuration against the declared plugins and the tests on disk, and report options that make tests pass without running. Read-only.
+
+- 시스템 프롬프트 한 줄: `Validate pytest configuration and detect tests that never run`
+- 라벨: Python Test Config
+- 프로젝트 상태 변경: 없음 (읽기 전용)
+
+**파라미터**
+
+| 파라미터 | 타입 | 필수 | 설명 |
+|---|---|---|---|
+| `path` | `string` | 아니오 | Project directory to audit; defaults to the project root. |
+
+**프롬프트 가이드라인**
+
+- Use py_test_config when a test run reports fewer tests than expected, when async tests may be silently skipped, or before trusting a green run.
+- Use py_test_config after changing pyproject.toml, pytest.ini, or the test layout to confirm the configuration still matches the project.
+
+**반환 `data` 형태**: 캡처되지 않음
+
 ### `py_test_select`
 
 Select focused pytest targets from changed files using pytest naming conventions, without running tests. Read-only.

package/extensions/index.ts

@@ -3,12 +3,14 @@ import { detectPythonEnvironment } from '../src/environment/discovery.ts';
 import { registerDependencyTools } from './tools/dependencies.ts';
 import { registerEnvironmentTools } from './tools/environment.ts';
 import { registerTestingTools } from './tools/testing.ts';
+import { registerTestConfigTools } from './tools/test-config.ts';
 import { registerValidationTools } from './tools/validation.ts';
 
 export default function (pi: ExtensionAPI): void {
   registerEnvironmentTools(pi);
   registerDependencyTools(pi);
   registerTestingTools(pi);
+  registerTestConfigTools(pi);
   registerValidationTools(pi);
 
   pi.registerCommand('py-status', {

package/extensions/shared.ts

@@ -1,6 +1,6 @@
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 import { open } from 'node:fs/promises';
-import { basename, dirname, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { findProjectRoot, isDirectory, isFile } from '../src/project/root.ts';
 
 export type Pi = ExtensionAPI;
@@ -70,3 +70,15 @@ export async function readTextIfExists(
 export function messageOf(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
+
+/** INI files that can carry pytest configuration, in the order they are read. */
+export const PYTEST_INI_FILES = ['pytest.ini', 'tox.ini', 'setup.cfg'] as const;
+
+export async function readPytestIniFiles(
+  root: string,
+): Promise<Record<string, string | undefined>> {
+  const entries = await Promise.all(
+    PYTEST_INI_FILES.map(async (name) => [name, await readTextIfExists(join(root, name))] as const),
+  );
+  return Object.fromEntries(entries);
+}

package/extensions/tools/environment.ts

@@ -10,22 +10,12 @@ import { runScanProject } from '../../src/project/scanner.ts';
 import {
   hasDirectory,
   messageOf,
-  readTextIfExists,
+  readPytestIniFiles,
   resolveProjectRoot,
   text,
   type Pi,
 } from '../shared.ts';
 
-/** INI files that can carry pytest configuration, in the order they are read. */
-const PYTEST_INI_FILES = ['pytest.ini', 'tox.ini', 'setup.cfg'];
-
-async function readPytestIniFiles(root: string): Promise<Record<string, string | undefined>> {
-  const entries = await Promise.all(
-    PYTEST_INI_FILES.map(async (name) => [name, await readTextIfExists(join(root, name))] as const),
-  );
-  return Object.fromEntries(entries);
-}
-
 export function registerEnvironmentTools(pi: Pi): void {
   pi.registerTool({
     name: 'py_environment',

package/extensions/tools/test-config.ts

@@ -0,0 +1,148 @@
+import { Type } from 'typebox';
+import { join } from 'node:path';
+import { failure, result, type Diagnostic } from '../../src/core/result.ts';
+import {
+  auditPytestConfiguration,
+  resolvePytestOptions,
+  type AsyncTestFile,
+} from '../../src/build/pytest-audit.ts';
+import { buildDeclaredIndex, normalizeName } from '../../src/dependencies/plan.ts';
+import { isRunnableTestFile } from '../../src/project/paths.ts';
+import { isDirectory } from '../../src/project/root.ts';
+import { runScanProject } from '../../src/project/scanner.ts';
+import { messageOf, readPytestIniFiles, resolveProjectRoot, text, type Pi } from '../shared.ts';
+
+export function registerTestConfigTools(pi: Pi): void {
+  pi.registerTool({
+    name: 'py_test_config',
+    label: 'Python Test Config',
+    description:
+      'Audit pytest configuration against the declared plugins and the tests on disk, and report options that make tests pass without running. Read-only.',
+    promptSnippet: 'Validate pytest configuration and detect tests that never run',
+    promptGuidelines: [
+      'Use py_test_config when a test run reports fewer tests than expected, when async tests may be silently skipped, or before trusting a green run.',
+      'Use py_test_config after changing pyproject.toml, pytest.ini, or the test layout to confirm the configuration still matches the project.',
+    ],
+    parameters: Type.Object({
+      path: Type.Optional(
+        Type.String({ description: 'Project directory to audit; defaults to the project root.' }),
+      ),
+    }),
+    async execute(_id, params, signal, _update, ctx) {
+      const started = Date.now();
+      try {
+        const root = (await resolveProjectRoot(ctx.cwd, params.path)) ?? ctx.cwd;
+        const scan = await runScanProject(ctx.cwd, { root, mode: 'all', maxFiles: 2000 }, signal);
+        if (!scan.ok || !scan.payload) {
+          return text(
+            failure(
+              ctx.cwd,
+              started,
+              scan.message ?? 'The project scanner failed.',
+              scan.code ?? 'SCANNER_FAILED',
+            ),
+          );
+        }
+
+        const manifest = scan.payload.manifest;
+        const declared = new Set(
+          buildDeclaredIndex(
+            manifest ?? {
+              dependencies: [],
+              optionalDependencies: {},
+              dependencyGroups: {},
+            },
+          ).keys(),
+        );
+
+        const resolution = resolvePytestOptions({
+          pyprojectOptions: manifest?.pytestOptions ?? null,
+          iniFiles: await readPytestIniFiles(root),
+        });
+
+        // Only files pytest would actually collect can hide a test, so a script
+        // that happens to define `async def test_*` is not reported.
+        const testFiles = (scan.payload.imports?.files ?? []).filter((file) =>
+          isRunnableTestFile(file.path),
+        );
+        const unmarkedAsyncTests: AsyncTestFile[] = testFiles
+          .map((file) => ({
+            path: file.path,
+            tests: (file.asyncTests ?? []).filter(
+              (name) => !(file.asyncioMarkedTests ?? []).includes(name),
+            ),
+          }))
+          .filter((entry) => entry.tests.length > 0);
+
+        const missingTestPaths: string[] = [];
+        for (const entry of resolution.options.testpaths) {
+          if (!(await isDirectory(join(root, entry)))) missingTestPaths.push(entry);
+        }
+
+        const findings = auditPytestConfiguration({
+          sources: resolution.sources,
+          options: resolution.options,
+          declared,
+          unmarkedAsyncTests,
+          missingTestPaths,
+          hasTestFiles: testFiles.length > 0,
+        });
+
+        const toDiagnostic = (finding: (typeof findings)[number]): Diagnostic => ({
+          code: finding.code,
+          message: finding.suggestion
+            ? `${finding.message} ${finding.suggestion}`
+            : finding.message,
+          severity: finding.severity,
+        });
+        const errors = findings.filter((finding) => finding.severity === 'error');
+        const warnings = findings.filter((finding) => finding.severity !== 'error');
+
+        return text(
+          result(ctx.cwd, started, {
+            ok: errors.length === 0,
+            summary:
+              findings.length === 0
+                ? `pytest configuration is consistent (${resolution.sources[0] ?? 'no configuration file'}, ${testFiles.length} test file(s)).`
+                : `${errors.length} error(s) and ${warnings.length} warning(s) in the pytest configuration.`,
+            data: {
+              sources: resolution.sources,
+              options: resolution.options,
+              findings,
+              unmarkedAsyncTests,
+              missingTestPaths,
+              testFileCount: testFiles.length,
+              declared: {
+                pytestAsyncio: declared.has(normalizeName('pytest-asyncio')),
+                pytestCov: declared.has(normalizeName('pytest-cov')),
+              },
+            },
+            evidence: [
+              {
+                kind: 'pytest_config_audit',
+                sources: resolution.sources,
+                findings: findings.map((finding) => finding.code),
+                unmarkedAsyncTests: unmarkedAsyncTests.reduce(
+                  (total, entry) => total + entry.tests.length,
+                  0,
+                ),
+              },
+            ],
+            warnings: warnings.map(toDiagnostic),
+            errors: errors.map(toDiagnostic),
+            suggestions: findings
+              .filter((finding) => finding.suggestion)
+              .map((finding) => ({
+                message: finding.suggestion as string,
+                confidence: 'high' as const,
+              })),
+            projectRoot: root,
+            pythonVersion: scan.payload.pythonVersion,
+          }),
+        );
+      } catch (error) {
+        return text(failure(ctx.cwd, started, messageOf(error), 'INTERNAL_ERROR'));
+      }
+    },
+  });
+}

package/extensions/tools/testing.ts

@@ -98,6 +98,10 @@ export function registerTestingTools(pi: Pi): void {
           ? undefined
           : await collectTestImports(root, ctx.cwd, signal);
         const selection = selectTests(changed, testFiles, { testImports });
+        // `changed` still holds non-Python paths, so "nothing to select" has to be
+        // decided on what the selector actually matched.
+        const hasPythonChange =
+          selection.changedSourceFiles.length > 0 || selection.changedTestFiles.length > 0;
         // Only files pytest collects tests from become targets; naming
         // `tests/utils.py` as a target overstates the run.
         const targets = selection.selected
@@ -111,7 +115,7 @@ export function registerTestingTools(pi: Pi): void {
 
         return text(
           result(ctx.cwd, started, {
-            ok: selection.selected.length > 0 || testFiles.length === 0,
+            ok: selection.selected.length > 0 || testFiles.length === 0 || !hasPythonChange,
             summary:
               `${selection.selected.length} test file(s) selected from ${testFiles.length} known test file(s) ` +
               `for ${selection.changedSourceFiles.length} changed source file(s) (${changedSource}).` +
@@ -137,6 +141,16 @@ export function registerTestingTools(pi: Pi): void {
               },
             ],
             warnings: [
+              ...(!hasPythonChange
+                ? [
+                    {
+                      code: 'NO_CHANGED_PATHS',
+                      message:
+                        'No changed Python file was found, so nothing could be selected. Pass changedPaths explicitly when the change is not visible to git.',
+                      severity: 'warning' as const,
+                    },
+                  ]
+                : []),
               ...(testFiles.length === 0
                 ? [
                     {

package/helpers/scan_project.py

@@ -37,7 +37,10 @@ from pathlib import Path
 # caller can refuse to interpret a document it does not understand.
 # 2: each scanned file reports `importModules`, the full dotted module names it
 #    references, so test selection can map a test file to the module it imports.
-SCANNER_VERSION = 2
+# 3: the manifest reports `[tool.pytest.ini_options]` as `pytestOptions`, and each
+#    scanned file reports `asyncTests`/`asyncioMarkedTests`, so a configuration
+#    audit can tell an async test that runs from one that is silently skipped.
+SCANNER_VERSION = 3
 
 KNOWN_SECTIONS = ("environment", "manifest", "imports")
 EXIT_OK = 0
@@ -234,6 +237,62 @@ def detect_layout(root: Path) -> tuple[str, list[str]]:
     return layout, sorted(set(modules))
 
 
+def json_safe(value):
+    """Recursively coerce a TOML value into something `json.dumps` accepts.
+
+    `tomllib` can produce datetimes, which are valid TOML but not JSON; a single
+    one would turn the whole document into a scanner crash.
+    """
+    if isinstance(value, dict):
+        return {str(key): json_safe(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [json_safe(item) for item in value]
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    return str(value)
+
+
+ASYNC_MARKERS = {"asyncio", "anyio", "trio"}
+
+
+def _dotted_name(node: ast.AST) -> str:
+    """Rebuild `a.b.c` from an attribute chain, or "" when it is not one."""
+    parts = []
+    current = node
+    while isinstance(current, ast.Attribute):
+        parts.append(current.attr)
+        current = current.value
+    if not isinstance(current, ast.Name):
+        return ""
+    parts.append(current.id)
+    return ".".join(reversed(parts))
+
+
+def async_test_functions(tree: ast.AST) -> tuple:
+    """Async test functions and the subset that carries an async marker.
+
+    pytest-asyncio's default `strict` mode runs a coroutine test only when it is
+    marked, so an unmarked `async def test_*` is collected and then silently
+    skipped. Only the syntax distinguishes the two, so this must be an AST walk
+    rather than a text search.
+    """
+    async_tests: list = []
+    marked: list = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.AsyncFunctionDef):
+            continue
+        if not node.name.startswith("test"):
+            continue
+        async_tests.append(node.name)
+        for decorator in node.decorator_list:
+            target = decorator.func if isinstance(decorator, ast.Call) else decorator
+            dotted = _dotted_name(target)
+            if dotted.rsplit(".", 1)[-1] in ASYNC_MARKERS and ".mark." in f".{dotted}":
+                marked.append(node.name)
+                break
+    return sorted(async_tests), sorted(marked)
+
+
 def scan_manifests(root: Path) -> dict:
     result: dict = {
         "pyprojectPath": None,
@@ -249,6 +308,7 @@ def scan_manifests(root: Path) -> dict:
         "buildRequires": [],
         "entryPoints": [],
         "toolConfiguration": {},
+        "pytestOptions": None,
         "layout": None,
         "modules": [],
         "legacySetupPy": False,
@@ -310,6 +370,9 @@ def scan_manifests(root: Path) -> dict:
                 key: key in tool
                 for key in ("ruff", "mypy", "pytest", "coverage", "pyright", "ty", "hatch")
             }
+            pytest_table = tool.get("pytest") if isinstance(tool.get("pytest"), dict) else {}
+            ini_options = pytest_table.get("ini_options")
+            result["pytestOptions"] = json_safe(ini_options) if isinstance(ini_options, dict) else None
             uv_table = tool.get("uv") if isinstance(tool.get("uv"), dict) else {}
             workspace = uv_table.get("workspace") if isinstance(uv_table.get("workspace"), dict) else {}
             members = workspace.get("members")
@@ -598,12 +661,15 @@ def scan_imports(root: Path, max_files: int) -> dict:
             collector.visit(tree)
             names = collector.all
             names.discard("")
+            async_tests, asyncio_marked = async_test_functions(tree)
             files.append(
                 {
                     "path": relative,
                     "imports": sorted(names),
                     "importModules": sorted(collector.modules),
                     "typeCheckingImports": sorted(collector.type_checking),
+                    "asyncTests": async_tests,
+                    "asyncioMarkedTests": asyncio_marked,
                 }
             )
             for name in names:

package/package.json

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

package/skills/python-development/SKILL.md

@@ -19,11 +19,12 @@ license: Apache-2.0
 4. import 이름과 배포 이름은 다를 수 있습니다(`PIL`/`pillow`, `yaml`/`PyYAML`). `py_dependency_plan`의 제안을 `uv add`로 적용하세요.
 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`로 프로덕션 변경에 대응하는 테스트 변경이 있는지 확인하세요.
+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)
 
@@ -34,6 +35,8 @@ license: Apache-2.0
 
 ## 해석 규칙 (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]` 추가 여부만 검토하세요.

package/src/build/failure.ts

@@ -1,4 +1,5 @@
 import type { Suggestion } from '../core/result.ts';
+import { importAliasCandidates } from '../dependencies/aliases.ts';
 
 export type FailureKind =
   | 'tool_not_installed'
@@ -222,6 +223,24 @@ export function diagnoseFailure(output: string): FailureDiagnosis {
 
   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.`,
@@ -231,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.',
@@ -404,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 {
@@ -447,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/core/result.ts

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

package/src/dependencies/aliases.ts

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

package/src/project/scanner.ts

@@ -14,7 +14,7 @@ export type ScanMode =
   | 'manifest,imports';
 
 /** Bumped by the scanner when the request or result document changes shape. */
-export const SUPPORTED_SCANNER_VERSION = 2;
+export const SUPPORTED_SCANNER_VERSION = 3;
 
 export interface DeclaredDependency {
   raw: string;
@@ -40,6 +40,12 @@ export interface ManifestSection {
   buildRequires: string[];
   entryPoints: string[];
   toolConfiguration: Record<string, boolean>;
+  /**
+   * `[tool.pytest.ini_options]` as written, or null when the table is absent.
+   * Left untyped because pytest accepts options this package does not model;
+   * only the audited keys are read.
+   */
+  pytestOptions?: Record<string, unknown> | null;
   layout: 'src' | 'flat';
   modules: string[];
   legacySetupPy: boolean;
@@ -98,6 +104,10 @@ export interface ImportSection {
      */
     importModules?: string[];
     typeCheckingImports: string[];
+    /** `async def test_*` names in this file. */
+    asyncTests?: string[];
+    /** The subset of `asyncTests` that carries an async plugin marker. */
+    asyncioMarkedTests?: string[];
   }[];
   thirdParty: {
     import: string;