pi-python-helper 0.1.1 → 0.3.0

package/extensions/tools/environment.ts

@@ -4,9 +4,17 @@ import { result, failure } from '../../src/core/result.ts';
 import { detectPythonEnvironment } from '../../src/environment/discovery.ts';
 import { inspectProject } from '../../src/project/inspect.ts';
 import { readInstalledDistributions } from '../../src/project/installed.ts';
-import { isGitIgnored } from '../../src/project/root.ts';
+import { detectPytestConfiguration } from '../../src/project/pytest-config.ts';
+import { findTestDirectories, isGitIgnored } from '../../src/project/root.ts';
 import { runScanProject } from '../../src/project/scanner.ts';
-import { hasDirectory, messageOf, resolveProjectRoot, text, type Pi } from '../shared.ts';
+import {
+  hasDirectory,
+  messageOf,
+  readPytestIniFiles,
+  resolveProjectRoot,
+  text,
+  type Pi,
+} from '../shared.ts';
 
 export function registerEnvironmentTools(pi: Pi): void {
   pi.registerTool({
@@ -110,14 +118,21 @@ export function registerEnvironmentTools(pi: Pi): void {
         const venvPath = join(root, '.venv');
         const venvDir = (await hasDirectory(venvPath)) ? venvPath : undefined;
         const venvIgnored = venvDir ? await isGitIgnored(root, '.venv') : undefined;
-        const hasTestsDirectory =
-          (await hasDirectory(join(root, 'tests'))) || (await hasDirectory(join(root, 'test')));
+        // Tests frequently live inside the package they cover, so the whole tree
+        // is searched instead of only `./tests`.
+        const testDirectories = await findTestDirectories(root);
+        const pytestConfiguration = detectPytestConfiguration({
+          pyprojectConfigured: scan.payload.manifest?.toolConfiguration?.pytest === true,
+          iniFiles: await readPytestIniFiles(root),
+        });
         const installed = venvDir ? await readInstalledDistributions(venvDir) : undefined;
         const inspection = inspectProject({
           payload: scan.payload,
           venvDir,
           venvIgnored,
-          hasTestsDirectory,
+          hasTestsDirectory: testDirectories.length > 0,
+          testDirectories,
+          pytestConfiguration,
           installed,
         });
 

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

@@ -1,12 +1,14 @@
 import { Type } from 'typebox';
+import { basename } from 'node:path';
 import { failure, result } from '../../src/core/result.ts';
 import { runCommand } from '../../src/core/runner.ts';
 import { pytestCommand } from '../../src/build/commands.ts';
 import { changedPaths, listTestFiles } from '../../src/build/discover.ts';
 import { diagnoseFailure, refineWithDeclarations } from '../../src/build/failure.ts';
 import { parsePytestOutput } from '../../src/build/pytest.ts';
-import { selectTests } from '../../src/build/selection.ts';
+import { selectTests, type TestImportMap } from '../../src/build/selection.ts';
 import { buildDeclaredIndex } from '../../src/dependencies/plan.ts';
+import { isRunnableTestFile } from '../../src/project/paths.ts';
 import { runScanProject } from '../../src/project/scanner.ts';
 import { messageOf, resolveProjectRoot, text, type Pi } from '../shared.ts';
 
@@ -33,6 +35,30 @@ async function refine(
   return refineWithDeclarations(diagnosis, { declared, localModules });
 }
 
+/**
+ * Map each test file to the dotted modules it imports.
+ *
+ * A test named `test_db_session.py` gives no naming hint that it covers
+ * `db/database.py`; the fact that it imports `pkg.db.database` does. The scanner
+ * supplies this because only a real parser may be trusted with Python source.
+ */
+async function collectTestImports(
+  root: string,
+  cwd: string,
+  signal: AbortSignal | undefined,
+): Promise<TestImportMap | undefined> {
+  const scan = await runScanProject(cwd, { root, mode: 'imports' }, signal);
+  const files = scan.payload?.imports?.files;
+  if (!scan.ok || !files) return undefined;
+  const map: TestImportMap = {};
+  for (const entry of files) {
+    if (!isRunnableTestFile(entry.path) && basename(entry.path) !== 'conftest.py') continue;
+    if (!entry.importModules?.length) continue;
+    map[entry.path] = entry.importModules;
+  }
+  return map;
+}
+
 export function registerTestingTools(pi: Pi): void {
   pi.registerTool({
     name: 'py_test_select',
@@ -68,21 +94,41 @@ export function registerTestingTools(pi: Pi): void {
           changedSource = discovered.source === 'git' ? 'git' : (discovered.error ?? 'none');
         }
         const testFiles = params.testFiles ?? (await listTestFiles(root));
-        const selection = selectTests(changed, testFiles);
+        const testImports = params.testFiles
+          ? 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
+          .filter(
+            (entry) => isRunnableTestFile(entry.path) || basename(entry.path) === 'conftest.py',
+          )
+          .map((entry) => entry.path);
         const command = pytestCommand(ctx.cwd, {
-          targets: selection.fellBackToAll ? [] : selection.selected.map((entry) => entry.path),
+          targets: selection.fellBackToAll ? [] : targets,
         });
 
         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}).` +
               (selection.fellBackToAll
                 ? ' No match was found, so the full suite is in scope.'
-                : ''),
-            data: { ...selection, pytestTargets: selection.selected.map((entry) => entry.path) },
+                : selection.narrowed
+                  ? ''
+                  : ' Every candidate matched, so nothing was narrowed.'),
+            data: {
+              ...selection,
+              pytestTargets: targets,
+              noNarrowing: !selection.fellBackToAll && !selection.narrowed,
+            },
             evidence: [
               {
                 kind: 'test_selection',
@@ -90,10 +136,22 @@ export function registerTestingTools(pi: Pi): void {
                 changedTestFiles: selection.changedTestFiles,
                 selected: selection.selected,
                 fellBackToAll: selection.fellBackToAll,
+                narrowed: selection.narrowed,
+                importEvidenceUsed: selection.importEvidenceUsed,
               },
             ],
-            warnings:
-              testFiles.length === 0
+            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
                 ? [
                     {
                       code: 'NO_TEST_FILES',
@@ -102,7 +160,27 @@ export function registerTestingTools(pi: Pi): void {
                       severity: 'warning' as const,
                     },
                   ]
-                : [],
+                : []),
+              ...(!selection.fellBackToAll && !selection.narrowed && selection.selected.length > 0
+                ? [
+                    {
+                      code: 'NO_NARROWING',
+                      message: `${selection.selected.length} of ${testFiles.length} test file(s) matched, so this selection is the whole suite rather than a focused target.`,
+                      severity: 'warning' as const,
+                    },
+                  ]
+                : []),
+              ...(selection.fellBackToAll || (!selection.importEvidenceUsed && changed.length > 0)
+                ? [
+                    {
+                      code: 'SELECTION_WITHOUT_IMPORT_EVIDENCE',
+                      message:
+                        'No candidate was matched by an actual import of a changed module, so this selection rests on file naming alone. Run the full suite or py_test with lastFailed=true when the change is broad.',
+                      severity: 'warning' as const,
+                    },
+                  ]
+                : []),
+            ],
             errors: [],
             suggestions: selection.selected.length
               ? [
@@ -131,6 +209,7 @@ export function registerTestingTools(pi: Pi): void {
     promptGuidelines: [
       'Use py_test with execute=false first; a preview is never a passing test run.',
       'Use py_test after changing Python sources; it does not rebuild anything, so run py_sync first when dependencies changed.',
+      'Use py_test with extraArgs to run project-standard pytest flags such as coverage options that the tool does not model directly.',
     ],
     parameters: Type.Object({
       targets: Type.Optional(Type.Array(Type.String())),
@@ -138,6 +217,12 @@ export function registerTestingTools(pi: Pi): void {
         Type.Boolean({ description: 'Rerun only tests that failed last time (--lf).' }),
       ),
       keyword: Type.Optional(Type.String({ description: 'pytest -k expression.' })),
+      extraArgs: Type.Optional(
+        Type.Array(Type.String(), {
+          description:
+            'Extra pytest arguments passed verbatim as an argument array, e.g. ["--cov=my_pkg", "--cov-branch"] or ["-m", "unit"].',
+        }),
+      ),
       maxFail: Type.Optional(Type.Integer({ minimum: 1, maximum: 1000 })),
       execute: Type.Optional(Type.Boolean()),
       timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1, maximum: 3600 })),
@@ -151,6 +236,7 @@ export function registerTestingTools(pi: Pi): void {
           targets: params.targets,
           lastFailed: params.lastFailed,
           keyword: params.keyword,
+          extraArgs: params.extraArgs,
           maxFail: params.maxFail,
         });
         if (!params.execute) {