pi-python-helper 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -7,6 +7,24 @@ does not guarantee a stable public tool schema.
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-09-21
+
+### Changed
+
+- `src/core/safety.ts` now delegates to `pi-helper-core`'s classifier and supplies only the Python package-manager, environment, and migration rules; the segment-splitting, safe-override precedence, and compound-merge logic is no longer duplicated. Requires `pi-helper-core` 0.1.2, which stops treating `--frozen`/`--locked`/`--list` as read-only flags so `uv sync --frozen` is classified as mutating again.
+
+## [0.4.0] - 2026-09-21
+
+### Changed
+
+- Adopt `pi-helper-core` (`^0.1.1`) for the shared response envelope, bounded command runner, TDD checkpoint, validation-bundle gate, completion evidence, artifact staleness, and test selection. `src/core/result.ts` and `src/core/runner.ts` are now thin shims, and `src/validation/` and `src/build/` supply only Python signals, labels, and rules.
+- **Breaking:** tool metadata no longer carries `pythonVersion`; the interpreter version now lives in the ecosystem-neutral `metadata.toolchain` (`{ kind: 'python', version }`).
+- Validation and completion messages now use the shared core wording (`uv lock --check`/`uv sync` labels); the drift check reports a mismatch against "the lockfile" generically.
+
+### Added
+
+- `test/core-dependency.test.ts` pins the `pi-helper-core` dependency and the shared behaviours the Python tools delegate to.
+
 ## [0.3.0] - 2026-09-21
 
 ### Added

package/docs/tools.md

@@ -30,12 +30,13 @@
   - `cwd`: string
   - `durationMs`: number
   - `projectRoot` (optional): string
-  - `pythonVersion` (optional): string
   - `toolVersion`: string
+  - `toolchain` (optional): object
+    - `kind`: string
+    - `source`: string
+    - `version`: string
   - `truncated`: boolean
 - `ok`: boolean
-- `projectRoot` (optional): string
-- `pythonVersion` (optional): string
 - `suggestions`: array of
   - `command` (optional): string
   - `confidence`: string

package/extensions/tools/dependencies.ts

@@ -72,7 +72,7 @@ export function registerDependencyTools(pi: Pi): void {
             errors: [],
             suggestions: plan.suggestions,
             projectRoot: root,
-            pythonVersion: scan.payload.pythonVersion,
+            toolchain: { kind: 'python', version: scan.payload.pythonVersion, source: 'project' },
           }),
         );
       } catch (error) {

package/extensions/tools/environment.ts

@@ -67,7 +67,11 @@ export function registerEnvironmentTools(pi: Pi): void {
               confidence: 'medium' as const,
             })),
             projectRoot: environment.projectRoot,
-            pythonVersion: python?.version,
+            toolchain: {
+              kind: 'python',
+              version: python?.version,
+              source: environment.projectRoot ? 'project' : 'path',
+            },
           }),
         );
       } catch (error) {
@@ -175,7 +179,7 @@ export function registerEnvironmentTools(pi: Pi): void {
             errors: [],
             suggestions: inspection.suggestions,
             projectRoot: inspection.root,
-            pythonVersion: scan.payload.pythonVersion,
+            toolchain: { kind: 'python', version: scan.payload.pythonVersion, source: 'project' },
           }),
         );
       } catch (error) {

package/extensions/tools/test-config.ts

@@ -137,7 +137,7 @@ export function registerTestConfigTools(pi: Pi): void {
                 confidence: 'high' as const,
               })),
             projectRoot: root,
-            pythonVersion: scan.payload.pythonVersion,
+            toolchain: { kind: 'python', version: scan.payload.pythonVersion, source: 'project' },
           }),
         );
       } catch (error) {

package/extensions/tools/validation.ts

@@ -590,7 +590,11 @@ export function registerValidationTools(pi: Pi): void {
                 ],
             commands,
             projectRoot: root,
-            pythonVersion: scan.payload?.pythonVersion,
+            toolchain: {
+              kind: 'python',
+              version: scan.payload?.pythonVersion,
+              source: 'project',
+            },
           }),
         );
       } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-python-helper",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Python (uv) development tools for the pi coding agent",
   "type": "module",
   "keywords": [
@@ -69,5 +69,8 @@
     "prettier": "^3.9.8",
     "tsx": "^4.23.13",
     "typescript": "^7.0.2"
+  },
+  "dependencies": {
+    "pi-helper-core": "^0.1.2"
   }
 }

package/src/build/selection.ts

@@ -1,75 +1,26 @@
-import { basename, dirname, join } from 'node:path';
+/**
+ * Python's test-selection signals over the shared ranking algorithm.
+ *
+ * The ranking (pytest naming conventions first, fuzzy token overlap second,
+ * ubiquitous signals discarded) lives in `pi-helper-core`. This module answers
+ * only the Python questions: what is a source/test file, what module a path
+ * becomes, and what counts as shared test infrastructure.
+ */
+import { selectTests as coreSelectTests, type SelectionSignals } from 'pi-helper-core';
 import {
   isPythonFile,
   isRunnableTestFile,
   isTestFile,
-  parentDir,
   pathTokens,
   toPosix,
 } from '../project/paths.ts';
 
-export interface TestSelection {
-  path: string;
-  score: number;
-  reason: string;
-}
-
-export interface SelectionResult {
-  selected: TestSelection[];
-  /** True when no changed file could be mapped and every test file is returned. */
-  fellBackToAll: boolean;
-  /**
-   * False when the selection covers every considered test file, so the
-   * candidate list was not narrowed at all. Reported so a caller does not read
-   * "30 of 30 selected" as a focused run.
-   */
-  narrowed: boolean;
-  changedSourceFiles: string[];
-  changedTestFiles: string[];
-  consideredTestFiles: string[];
-  /** Files under a test directory that pytest does not collect tests from. */
-  supportFiles: string[];
-  /**
-   * True when at least one candidate was matched by an actual import of a
-   * changed module, which is the strongest available signal. False means the
-   * selection rests on naming conventions alone.
-   */
-  importEvidenceUsed: boolean;
-}
-
-/**
- * Dotted module names imported by each test file, keyed by test path.
- * Supplied by the scanner because a test named `test_db_session.py` gives no
- * naming hint that it covers `db/database.py`; its imports do.
- */
-export type TestImportMap = Record<string, string[]>;
-
-export interface SelectionOptions {
-  testImports?: TestImportMap;
-}
-
-const SCORE = {
-  changedTestItself: 100,
-  /** Importing the changed module is stronger than any name coincidence. */
-  importsChangedModule: 90,
-  sameStemSameDir: 80,
-  sameStem: 60,
-  sameDirectory: 40,
-  sharedToken: 20,
-  sharedModule: 30,
-};
-
-function stem(path: string): string {
-  return basename(toPosix(path)).replace(/\.py$/i, '');
-}
-
-/** Strip the pytest prefix/suffix so `test_parser.py` and `parser.py` compare equal. */
-function normalizedStem(path: string): string {
-  return stem(path)
-    .replace(/^test_/, '')
-    .replace(/_test$/, '')
-    .toLowerCase();
-}
+export type {
+  SelectionOptions,
+  SelectionResult,
+  TestImportMap,
+  TestSelection,
+} from 'pi-helper-core';
 
 function firstImportableSegment(path: string): string {
   const segments = toPosix(path)
@@ -106,200 +57,21 @@ export function modulePathsFromFile(path: string): string[] {
   return [...new Set(candidates)];
 }
 
-/** True when a test imports the module, or a parent package of it. */
-function importsModule(imported: string[], modules: string[]): string | undefined {
-  let best: string | undefined;
-  for (const candidate of modules) {
-    for (const entry of imported) {
-      const matches =
-        entry === candidate ||
-        entry.startsWith(`${candidate}.`) ||
-        candidate.startsWith(`${entry}.`);
-      if (!matches) continue;
-      // Report the most specific import: naming `pkg` when the file actually
-      // imports `pkg.routes.admin` overstates how broadly the test is coupled.
-      if (!best || entry.length > best.length) best = entry;
-    }
-  }
-  return best;
-}
-
-/**
- * Values that appear in at least this share of the candidates carry no
- * information about *which* candidate to run: in a project whose tests all live
- * inside the package under test, the package name matches every file.
- */
-const UBIQUITOUS_SHARE = 0.5;
-
-function ubiquitousValues(documents: string[][]): Set<string> {
-  const counts = new Map<string, number>();
-  for (const values of documents) {
-    for (const value of new Set(values)) {
-      if (value.length === 0) continue;
-      counts.set(value, (counts.get(value) ?? 0) + 1);
-    }
-  }
-  const threshold = Math.max(2, documents.length * UBIQUITOUS_SHARE);
-  const ubiquitous = new Set<string>();
-  for (const [value, count] of counts) {
-    if (count >= threshold) ubiquitous.add(value);
-  }
-  return ubiquitous;
-}
+const PYTHON_SIGNALS: SelectionSignals = {
+  isSourceFile: isPythonFile,
+  isTestFile,
+  isRunnableTestFile,
+  pathTokens,
+  moduleNamesForFile: modulePathsFromFile,
+  packageName: firstImportableSegment,
+  supportFileNames: new Set(['conftest.py']),
+  testNameAffixes: { prefixes: ['test_'], suffixes: ['_test'] },
+};
 
-/**
- * Rank test files against changed paths using pytest conventions first and
- * token overlap second. The convention signals are strong enough in Python that
- * a name match should always outrank a fuzzy token match.
- *
- * Signals shared by every candidate are discarded rather than scored. Without
- * that step a package-rooted test tree (`<package>/tests/`) matches its own
- * package on every file and the selection degenerates into the full suite.
- */
 export function selectTests(
   changedPaths: string[],
   testFiles: string[],
-  options: SelectionOptions = {},
-): SelectionResult {
-  const changed = changedPaths.map(toPosix).filter(isPythonFile);
-  const changedSourceFiles = changed.filter((path) => !isTestFile(path));
-  const changedTestFiles = changed.filter(isTestFile);
-  const considered = [...new Set(testFiles.map(toPosix).filter(isPythonFile))].sort();
-  const supportFiles = considered.filter((path) => !isRunnableTestFile(path));
-  const testImports = options.testImports ?? {};
-
-  if (!changed.length) {
-    return {
-      selected: [],
-      fellBackToAll: false,
-      narrowed: false,
-      changedSourceFiles,
-      changedTestFiles,
-      consideredTestFiles: considered,
-      supportFiles,
-      importEvidenceUsed: false,
-    };
-  }
-
-  const sourceTokens = new Set(changedSourceFiles.flatMap(pathTokens));
-  const sourceModules = new Set(changedSourceFiles.map(firstImportableSegment));
-  const sourceStems = new Set(changedSourceFiles.map(normalizedStem));
-  const sourceModulePaths = changedSourceFiles.map((path) => modulePathsFromFile(path));
-
-  const ubiquitousTokens = ubiquitousValues(considered.map((path) => pathTokens(path)));
-  const ubiquitousModules = ubiquitousValues(
-    considered.map((path) => [firstImportableSegment(path)]),
-  );
-  // A source directory that contains every test file (the package root) cannot
-  // distinguish candidates, so it does not score.
-  const sourceDirs = new Set(
-    [...new Set(changedSourceFiles.map(parentDir))].filter(
-      (directory) =>
-        directory === '' || !considered.every((path) => path.startsWith(`${directory}/`)),
-    ),
-  );
-
-  let importEvidenceUsed = false;
-  const selections: TestSelection[] = [];
-  for (const testFile of considered) {
-    // Test infrastructure is not a target, but it can still affect the run, so it
-    // is reported separately instead of being scored as a test file.
-    if (!isRunnableTestFile(testFile)) continue;
-
-    const reasons: string[] = [];
-    let score = 0;
-
-    if (changedTestFiles.includes(testFile)) {
-      score += SCORE.changedTestItself;
-      reasons.push('the test file itself changed');
-    }
-
-    const imported = testImports[testFile];
-    if (imported && imported.length > 0) {
-      const matched = sourceModulePaths
-        .map((modules) => importsModule(imported, modules))
-        .find((value) => value !== undefined);
-      if (matched) {
-        score += SCORE.importsChangedModule;
-        importEvidenceUsed = true;
-        reasons.push(`imports the changed module "${matched}"`);
-      }
-    }
-
-    const testStem = normalizedStem(testFile);
-    const testDir = parentDir(testFile);
-    if (sourceStems.has(testStem)) {
-      score += SCORE.sameStem;
-      reasons.push(`module name matches "${testStem}"`);
-      if (sourceDirs.has(testDir)) {
-        score += SCORE.sameStemSameDir - SCORE.sameStem;
-        reasons.push('same directory as the changed module');
-      }
-    } else if (sourceDirs.has(testDir)) {
-      score += SCORE.sameDirectory;
-      reasons.push('same directory as a changed module');
-    } else if (sourceDirs.has(dirname(testDir)) || sourceDirs.has(join(dirname(testDir), ''))) {
-      score += SCORE.sameDirectory - 10;
-      reasons.push('nested under a changed directory');
-    }
-
-    const module = firstImportableSegment(testFile);
-    if (module && sourceModules.has(module) && !ubiquitousModules.has(module)) {
-      score += SCORE.sharedModule;
-      reasons.push(`covers module "${module}"`);
-    }
-
-    const tokens = pathTokens(testFile);
-    const shared = tokens.filter(
-      (token) => sourceTokens.has(token) && !ubiquitousTokens.has(token),
-    );
-    if (shared.length) {
-      score += SCORE.sharedToken * Math.min(shared.length, 2);
-      reasons.push(`shares token(s): ${shared.slice(0, 4).join(', ')}`);
-    }
-
-    if (score > 0) {
-      selections.push({ path: testFile, score, reason: reasons.join('; ') });
-    }
-  }
-
-  selections.sort((left, right) => right.score - left.score || left.path.localeCompare(right.path));
-
-  // A conftest can affect every test, so it is always in scope once tests run.
-  for (const testFile of considered) {
-    if (basename(testFile) === 'conftest.py' && !selections.some((s) => s.path === testFile)) {
-      selections.push({ path: testFile, score: 1, reason: 'shared conftest fixture scope' });
-    }
-  }
-
-  const runnableConsidered = considered.filter(isRunnableTestFile);
-  const selectedRunnable = selections.filter((entry) => isRunnableTestFile(entry.path));
-  const fellBackToAll = selections.length === 0 && considered.length > 0;
-  if (fellBackToAll) {
-    return {
-      selected: considered.map((path) => ({
-        path,
-        score: 0,
-        reason: 'no match; running the full suite',
-      })),
-      fellBackToAll: true,
-      narrowed: false,
-      changedSourceFiles,
-      changedTestFiles,
-      consideredTestFiles: considered,
-      supportFiles,
-      importEvidenceUsed,
-    };
-  }
-
-  return {
-    selected: selections,
-    fellBackToAll: false,
-    narrowed: selectedRunnable.length < runnableConsidered.length,
-    changedSourceFiles,
-    changedTestFiles,
-    consideredTestFiles: considered,
-    supportFiles,
-    importEvidenceUsed,
-  };
+  options: import('pi-helper-core').SelectionOptions = {},
+): import('pi-helper-core').SelectionResult {
+  return coreSelectTests(changedPaths, testFiles, PYTHON_SIGNALS, options);
 }

package/src/build/staleness.ts

@@ -1,13 +1,18 @@
-import { readdir, stat } from 'node:fs/promises';
-import { join } from 'node:path';
+/**
+ * Python's staleness spec over the shared `detectStaleArtifacts` walker.
+ *
+ * Python invalidates bytecode automatically and pytest installs nothing, so a
+ * stale coverage report is the one artifact that can make a passing run
+ * describe the wrong code. The walk and mtime comparison live in
+ * `pi-helper-core`; this module names the sources and artifacts.
+ */
+import {
+  detectStaleArtifacts as coreDetectStaleArtifacts,
+  type StaleArtifact,
+  type StalenessSpec,
+} from 'pi-helper-core';
 
-export interface StaleArtifact {
-  code: 'STALE_COVERAGE_DATA';
-  message: string;
-  path: string;
-  artifactMtimeMs?: number;
-  newestSource?: { path: string; mtimeMs: number };
-}
+export type { StaleArtifact };
 
 export interface PythonStalenessReport {
   stale: boolean;
@@ -16,102 +21,21 @@ export interface PythonStalenessReport {
   incompleteReason?: string;
 }
 
-const IGNORED_DIRECTORIES = new Set([
-  '.git',
-  '.venv',
-  'venv',
-  '.tox',
-  '.nox',
-  '__pycache__',
-  '.mypy_cache',
-  '.ruff_cache',
-  '.pytest_cache',
-  'node_modules',
-  'build',
-  'dist',
-  '.eggs',
-]);
-
-const MAX_WALKED_FILES = 5000;
-
-async function mtimeMs(path: string): Promise<number | undefined> {
-  try {
-    return (await stat(path)).mtimeMs;
-  } catch {
-    return undefined;
-  }
-}
-
-async function newestPythonSource(
-  root: string,
-): Promise<{ path: string; mtimeMs: number } | undefined> {
-  let newest: { path: string; mtimeMs: number } | undefined;
-  let visited = 0;
-  const stack = [root];
-  while (stack.length > 0) {
-    const directory = stack.pop() as string;
-    let entries;
-    try {
-      entries = await readdir(directory, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-    for (const entry of entries) {
-      if (visited > MAX_WALKED_FILES) return newest;
-      const path = join(directory, entry.name);
-      if (entry.isDirectory()) {
-        if (IGNORED_DIRECTORIES.has(entry.name)) continue;
-        stack.push(path);
-      } else if (entry.isFile() && entry.name.endsWith('.py')) {
-        visited += 1;
-        const modified = await mtimeMs(path);
-        if (modified === undefined) continue;
-        if (!newest || modified > newest.mtimeMs) newest = { path, mtimeMs: modified };
-      }
-    }
-  }
-  return newest;
-}
+const PYTHON_SPEC: StalenessSpec = {
+  sourceExtensions: ['.py'],
+  artifacts: [
+    { name: '.coverage', code: 'STALE_COVERAGE_DATA', describe: 'coverage results' },
+    { name: 'coverage.xml', code: 'STALE_COVERAGE_DATA', describe: 'coverage results' },
+  ],
+  // `.venv`/`venv` are not in the core's universal ignore list because they are
+  // Python-specific; caches and build trees already are.
+  ignoredDirectories: new Set(['.venv', 'venv']),
+};
 
-/**
- * Detect a coverage report that predates the sources it claims to describe.
- *
- * Python invalidates bytecode automatically and pytest installs nothing, so a
- * stale report is the one artifact that can make a passing run describe the
- * wrong code. Whether the project itself is installed as a stale copy is a
- * structural question and is answered by the environment conformance check
- * rather than by comparing mtimes here.
- */
 export async function detectStaleArtifacts(root: string): Promise<PythonStalenessReport> {
-  const artifacts: StaleArtifact[] = [];
-  let newestSource: { path: string; mtimeMs: number } | undefined;
-  try {
-    newestSource = await newestPythonSource(root);
-  } catch (error) {
-    return {
-      stale: false,
-      artifacts,
-      incompleteReason: `Source scan failed: ${error instanceof Error ? error.message : String(error)}`,
-    };
-  }
-  if (!newestSource) {
-    return { stale: false, artifacts, incompleteReason: 'No Python source files were found.' };
+  const report = await coreDetectStaleArtifacts(root, PYTHON_SPEC);
+  if (report.incompleteReason?.startsWith('No source file')) {
+    return { ...report, incompleteReason: 'No Python source files were found.' };
   }
-
-  for (const name of ['.coverage', 'coverage.xml']) {
-    const path = join(root, name);
-    const modified = await mtimeMs(path);
-    if (modified === undefined) continue;
-    if (modified < newestSource.mtimeMs) {
-      artifacts.push({
-        code: 'STALE_COVERAGE_DATA',
-        message: `${name} was written before ${newestSource.path} changed; coverage results do not describe the current sources.`,
-        path,
-        artifactMtimeMs: modified,
-        newestSource,
-      });
-    }
-  }
-
-  return { stale: artifacts.length > 0, artifacts };
+  return report;
 }