pi-python-helper 0.1.0 → 0.2.0

package/extensions/tools/dependencies.ts

@@ -1,9 +1,6 @@
 import { Type } from 'typebox';
 import { failure, result } from '../../src/core/result.ts';
-import { runCommand } from '../../src/core/runner.ts';
 import { planDependencies } from '../../src/dependencies/plan.ts';
-import { buildCompletionEvidence } from '../../src/validation/evidence.ts';
-import { checkTdd } from '../../src/validation/tdd.ts';
 import { messageOf, resolveProjectRoot, text, type Pi } from '../shared.ts';
 import { runScanProject } from '../../src/project/scanner.ts';
 
@@ -83,121 +80,4 @@ export function registerDependencyTools(pi: Pi): void {
       }
     },
   });
-
-  pi.registerTool({
-    name: 'py_tdd_checkpoint',
-    label: 'Python TDD Checkpoint',
-    description:
-      'Check whether production Python changes have related test changes before implementation is considered complete. Read-only.',
-    promptSnippet: 'Check the Python TDD checkpoint for changed files',
-    promptGuidelines: [
-      'Use py_tdd_checkpoint before reporting Python implementation work as complete.',
-    ],
-    parameters: Type.Object({
-      changedPaths: Type.Optional(Type.Array(Type.String(), { maxItems: 500 })),
-      testChangedPaths: Type.Optional(Type.Array(Type.String(), { maxItems: 500 })),
-    }),
-    async execute(_id, params, signal, _update, ctx) {
-      const started = Date.now();
-      let changedPaths = params.changedPaths ?? [];
-      let source = 'argument';
-      if (!changedPaths.length) {
-        const diff = await runCommand('git', ['diff', '--name-only', 'HEAD'], {
-          cwd: ctx.cwd,
-          signal,
-          timeoutMs: 10000,
-          maxBytes: 100_000,
-        });
-        changedPaths = diff.stdout
-          .split(/\r?\n/)
-          .map((line) => line.trim())
-          .filter(Boolean);
-        source = 'git diff';
-      }
-      const checkpoint = checkTdd(changedPaths, params.testChangedPaths ?? changedPaths);
-      return text(
-        result(ctx.cwd, started, {
-          ok: checkpoint.ok,
-          summary: checkpoint.ok
-            ? `TDD checkpoint passed across ${changedPaths.length} changed path(s) from ${source}.`
-            : 'TDD checkpoint found production changes without a related test change.',
-          data: { ...checkpoint, changedPaths, source },
-          evidence: checkpoint.reasons.map((message) => ({ kind: 'tdd_blocker', message })),
-          warnings: checkpoint.reasons.map((message) => ({
-            code: 'TDD_CHECKPOINT',
-            message,
-            severity: 'warning' as const,
-          })),
-          errors: [],
-          suggestions: checkpoint.ok
-            ? []
-            : [
-                {
-                  message:
-                    'Add the smallest focused test for the changed behaviour, or explain why the change needs no test.',
-                  confidence: 'high' as const,
-                },
-              ],
-        }),
-      );
-    },
-  });
-
-  pi.registerTool({
-    name: 'py_completion_evidence',
-    label: 'Python Completion Evidence',
-    description:
-      'Build a conservative completion report from environment sync and test execution results. Read-only.',
-    promptSnippet: 'Create evidence for a Python completion report',
-    promptGuidelines: [
-      'Use py_completion_evidence before claiming Python work is complete; a partial run is not evidence.',
-    ],
-    parameters: Type.Object({
-      syncExecuted: Type.Boolean({
-        description: 'Whether uv lock --check / uv sync actually ran.',
-      }),
-      syncOk: Type.Boolean(),
-      testExecuted: Type.Boolean({ description: 'Whether pytest actually ran.' }),
-      testOk: Type.Boolean(),
-      stale: Type.Boolean({ description: 'Whether stale artifacts were detected.' }),
-      changedPaths: Type.Array(Type.String(), { maxItems: 500 }),
-    }),
-    async execute(_id, params, _signal, _update, ctx) {
-      const started = Date.now();
-      const evidence = buildCompletionEvidence(params);
-      return text(
-        result(ctx.cwd, started, {
-          ok: evidence.ok,
-          summary: evidence.ok
-            ? 'Completion evidence is sufficient for the supplied checks.'
-            : 'Completion evidence is incomplete or contains failing checks.',
-          data: evidence,
-          evidence: evidence.blockers.map((message) => ({ kind: 'completion_blocker', message })),
-          warnings: evidence.blockers.map((message) => ({
-            code: 'INCOMPLETE_EVIDENCE',
-            message,
-            severity: 'warning' as const,
-          })),
-          errors: evidence.ok
-            ? []
-            : [
-                {
-                  code: 'COMPLETION_NOT_PROVEN',
-                  message: 'The supplied evidence does not prove completion.',
-                  severity: 'error' as const,
-                },
-              ],
-          suggestions: evidence.ok
-            ? []
-            : [
-                {
-                  message:
-                    'Run py_validation_bundle and address every blocker before reporting completion.',
-                  confidence: 'high' as const,
-                },
-              ],
-        }),
-      );
-    },
-  });
 }

package/extensions/tools/environment.ts

@@ -4,9 +4,27 @@ 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,
+  readTextIfExists,
+  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({
@@ -110,14 +128,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/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,9 +94,19 @@ 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 });
+        // 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(
@@ -81,8 +117,14 @@ export function registerTestingTools(pi: Pi): void {
               `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 +132,12 @@ 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: [
+              ...(testFiles.length === 0
                 ? [
                     {
                       code: 'NO_TEST_FILES',
@@ -102,7 +146,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 +195,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 +203,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 +222,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) {