pi-python-helper 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ does not guarantee a stable public tool schema.
 
 ## [Unreleased]
 
+## [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.0",
   "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.1"
   }
 }

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

package/src/core/result.ts

@@ -1,129 +1,29 @@
-import { TOOL_VERSION } from './version.ts';
-
-export type DiagnosticSeverity = 'info' | 'warning' | 'error';
-
-export interface Diagnostic {
-  code?: string;
-  message: string;
-  severity: DiagnosticSeverity;
-  path?: string;
-  line?: number;
-}
-
-export interface Evidence {
-  kind: string;
-  message?: string;
-  [key: string]: unknown;
-}
-
-export interface Suggestion {
-  message: string;
-  confidence?: 'low' | 'medium' | 'high';
-  command?: string;
-}
-
-export interface CommandPreview {
-  executable: string;
-  args: string[];
-  cwd?: string;
-  /** Risk classification for the command; `read` commands never change project state. */
-  risk?: 'read' | 'mutating' | 'irreversible';
-}
-
-export interface ToolMetadata {
-  toolVersion: string;
-  cwd: string;
-  durationMs: number;
-  truncated: boolean;
-  projectRoot?: string;
-  pythonVersion?: string;
-}
-
 /**
- * Every tool in this package returns this shape so the agent can rely on a
- * single contract regardless of which diagnostic ran. Domain fields live in
- * `data`; everything the agent must reason about lives in the typed sections.
+ * Local shim over the shared `pi-helper-core` envelope.
+ *
+ * Every tool imports `result`/`failure` and the shared types from here, so the
+ * envelope is defined in exactly one place (`pi-helper-core`) while call sites
+ * stay unaware of that. `pythonVersion` moved into the ecosystem-neutral
+ * `metadata.toolchain` field.
  */
-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[];
-  warnings: Diagnostic[];
-  errors: Diagnostic[];
-  suggestions: Suggestion[];
-  commands?: CommandPreview[];
-  metadata: ToolMetadata;
-}
+import { createResultFactory } from 'pi-helper-core';
+import { TOOL_VERSION } from './version.ts';
 
-/**
- * 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 const { result, failure } = createResultFactory(TOOL_VERSION);
 
-export function result<T>(
-  cwd: string,
-  startedAt: number,
-  value: Omit<PyToolResult<T>, 'metadata' | 'attention'> & {
-    attention?: boolean;
-    truncated?: boolean;
-    projectRoot?: string;
-    pythonVersion?: string;
-  },
-): PyToolResult<T> {
-  return {
-    ...value,
-    attention: value.attention ?? (!value.ok || isActionable(value)),
-    metadata: {
-      toolVersion: TOOL_VERSION,
-      cwd,
-      durationMs: Date.now() - startedAt,
-      truncated: value.truncated ?? false,
-      projectRoot: value.projectRoot,
-      pythonVersion: value.pythonVersion,
-    },
-  };
-}
+export { CORE_SCHEMA_VERSION, isActionable, note, warn } from 'pi-helper-core';
 
-export function failure(
-  cwd: string,
-  startedAt: number,
-  message: string,
-  code: string,
-  details?: Partial<PyToolResult>,
-): PyToolResult {
-  return result(cwd, startedAt, {
-    ok: false,
-    summary: message,
-    evidence: [],
-    warnings: [],
-    errors: [{ code, message, severity: 'error' }],
-    suggestions: [],
-    ...details,
-  });
-}
+export type {
+  CommandPreview,
+  CommandRisk,
+  Diagnostic,
+  Evidence,
+  Severity,
+  Suggestion,
+  ToolchainInfo,
+  ToolResult,
+} from 'pi-helper-core';
 
-/** Shared helper so diagnostics never lose their code when built inline. */
-export function warn(code: string, message: string, path?: string, line?: number): Diagnostic {
-  return { code, message, severity: 'warning', path, line };
-}
+/** The Python tools' view of the shared envelope. */
+export type PyToolResult<T = unknown> = import('pi-helper-core').ToolResult<T>;
+export type DiagnosticSeverity = import('pi-helper-core').Severity;

package/src/core/runner.ts

@@ -1,96 +1,5 @@
-import { spawn } from 'node:child_process';
-
-export interface RunOptions {
-  cwd: string;
-  env?: NodeJS.ProcessEnv;
-  timeoutMs?: number;
-  signal?: AbortSignal;
-  maxBytes?: number;
-  stdin?: string;
-}
-
-export interface RunResult {
-  code: number | null;
-  stdout: string;
-  stderr: string;
-  timedOut: boolean;
-  cancelled: boolean;
-  truncated: boolean;
-}
-
-function appendLimited(current: string, chunk: string, maxBytes: number): [string, boolean] {
-  const next = current + chunk;
-  if (Buffer.byteLength(next, 'utf8') <= maxBytes) return [next, false];
-  return [Buffer.from(next, 'utf8').subarray(0, maxBytes).toString('utf8'), true];
-}
-
 /**
- * Single bounded subprocess entry point. User-supplied paths and package names
- * must always reach the process through `args`, never through a shell string,
- * and every call must stay inside a timeout and an output cap.
+ * The bounded subprocess runner now lives in `pi-helper-core`; this module
+ * keeps the local import path so no call site has to change.
  */
-export async function runCommand(
-  executable: string,
-  args: string[],
-  options: RunOptions,
-): Promise<RunResult> {
-  const maxBytes = options.maxBytes ?? 100 * 1024;
-  const child = spawn(executable, args, {
-    cwd: options.cwd,
-    env: { ...process.env, ...options.env },
-    detached: process.platform !== 'win32',
-    stdio: ['pipe', 'pipe', 'pipe'],
-  });
-
-  if (options.stdin !== undefined) child.stdin.write(options.stdin);
-  child.stdin.end();
-
-  let stdout = '';
-  let stderr = '';
-  let truncated = false;
-  let timedOut = false;
-  let cancelled = false;
-  let spawnError: Error | undefined;
-  const onAbort = () => {
-    cancelled = true;
-    terminate(child);
-  };
-  options.signal?.addEventListener('abort', onAbort, { once: true });
-  const timeout = options.timeoutMs
-    ? setTimeout(() => {
-        timedOut = true;
-        terminate(child);
-      }, options.timeoutMs)
-    : undefined;
-
-  child.on('error', (error) => {
-    spawnError = error;
-  });
-  child.stdout.on('data', (chunk: Buffer) => {
-    const [next, wasTruncated] = appendLimited(stdout, chunk.toString(), maxBytes);
-    stdout = next;
-    truncated ||= wasTruncated;
-  });
-  child.stderr.on('data', (chunk: Buffer) => {
-    const [next, wasTruncated] = appendLimited(stderr, chunk.toString(), maxBytes);
-    stderr = next;
-    truncated ||= wasTruncated;
-  });
-  const [code] = await new Promise<[number | null]>((resolve) => {
-    child.once('close', (exitCode) => resolve([exitCode]));
-  });
-  if (timeout) clearTimeout(timeout);
-  options.signal?.removeEventListener('abort', onAbort);
-  if (spawnError) stderr = `${stderr}${stderr ? '\n' : ''}${spawnError.message}`;
-  return { code, stdout, stderr, timedOut, cancelled, truncated };
-}
-
-function terminate(child: ReturnType<typeof spawn>): void {
-  if (child.pid === undefined) return;
-  try {
-    if (process.platform !== 'win32') process.kill(-child.pid, 'SIGTERM');
-    else child.kill('SIGTERM');
-  } catch {
-    child.kill('SIGTERM');
-  }
-}
+export { isSpawnFailure, runCommand, type RunOptions, type RunResult } from 'pi-helper-core';

package/src/validation/bundle.ts

@@ -1,17 +1,16 @@
-export interface ValidationStep {
-  /** Step label, used for the quality checks (`ruff`, `pyright`). */
-  name?: string;
-  executed: boolean;
-  ok: boolean;
-  exitCode?: number | null;
-  failures?: number;
-  /**
-   * Why a step was not executed. A step that was skipped deliberately (the
-   * environment is missing the tool it needs) must say so, otherwise the run
-   * looks like an unexplained test failure.
-   */
-  skippedReason?: string;
-}
+/**
+ * Python's view of the shared validation-bundle gate.
+ *
+ * `pi-helper-core` owns the lock → preparation → test → quality → conformance
+ * sequence; this module names the Python steps (`uv lock --check`, `uv sync`)
+ * and preserves the local `sync` field name in the returned `checks` map.
+ */
+import {
+  summarizeValidation as coreSummarizeValidation,
+  type ValidationStep,
+} from 'pi-helper-core';
+
+export type { ValidationStep };
 
 export interface ValidationSummary {
   ok: boolean;
@@ -21,32 +20,12 @@ export interface ValidationSummary {
     sync: boolean;
     test: boolean;
     conformance: boolean;
-    /**
-     * True when every configured quality command passed. Vacuously true when the
-     * project declares none, so a project without lint/type tooling is not
-     * penalised.
-     */
     quality: boolean;
     staleArtifacts: boolean;
   };
 }
 
-const PREVIEW_REASON = 'Set execute=true to run the validation bundle.';
-
-/**
- * The bundle runs `uv lock --check`, then `uv sync --frozen`, then pytest, then
- * verifies that the resulting environment actually matches the lockfile and that
- * no stale coverage report is being quoted.
- *
- * Conformance must be proven, not merely not-failed: a test run that passed
- * against versions the lockfile does not describe is not evidence, so an
- * `unverifiable` verdict fails the gate exactly like drift does.
- *
- * A test step that was never executed is also not evidence, and when the reason
- * is known (the environment no longer provides pytest) that reason is reported
- * instead of a generic failure.
- */
-export function summarizeValidation(input: {
+export interface ValidationInput {
   lock: ValidationStep;
   sync: ValidationStep;
   test: ValidationStep;
@@ -56,47 +35,33 @@ export function summarizeValidation(input: {
   stale: boolean;
   /** True when nothing was executed because the caller only asked for a preview. */
   preview?: boolean;
-}): ValidationSummary {
-  const lock = input.lock.executed && input.lock.ok;
-  const sync = input.sync.executed && input.sync.ok;
-  const test = input.test.executed && input.test.ok && (input.test.failures ?? 0) === 0;
-  const qualitySteps = input.quality ?? [];
-  const quality = qualitySteps.every((step) => step.executed && step.ok);
-  const failedQuality = qualitySteps.filter((step) => !step.executed || !step.ok);
-  const conformance = input.conformance === 'consistent';
-  const staleArtifacts = input.stale;
+}
 
-  let reason = 'Lockfile, environment, tests, and installed versions all agree.';
-  if (input.preview) {
-    reason = PREVIEW_REASON;
-  } else if (!input.lock.executed || !input.sync.executed) {
-    reason = !input.lock.executed
-      ? 'uv lock --check was not executed, so lockfile agreement is unproven.'
-      : 'uv sync was not executed, so the environment the tests ran in is unknown.';
-  } else if (!lock) {
-    reason = 'uv.lock is out of date; run uv lock before trusting any test result.';
-  } else if (!sync) {
-    reason = 'The environment could not be synchronised from the lockfile.';
-  } else if (!input.test.executed) {
-    reason =
-      input.test.skippedReason ?? 'Tests were not executed, so no test result exists to report.';
-  } else if (!test) {
-    reason = 'Tests failed; inspect the first failing case and its project frame.';
-  } else if (input.conformance === 'drifted') {
-    reason =
-      'Tests passed, but the installed versions do not match uv.lock, so the run does not describe the locked environment.';
-  } else if (input.conformance === 'unverifiable') {
-    reason =
-      'The installed environment could not be compared with uv.lock, so the passing test run is not proven to be on the locked versions.';
-  } else if (failedQuality.length > 0) {
-    const names = failedQuality.map((step) => step.name ?? 'quality check').join(', ');
-    reason = `Tests passed, but the declared quality check(s) failed: ${names}.`;
-  } else if (staleArtifacts) {
-    reason = 'Tests passed, but a stale coverage report was detected; refresh it and rerun.';
-  }
+export function summarizeValidation(input: ValidationInput): ValidationSummary {
+  const summary = coreSummarizeValidation({
+    lock: input.lock,
+    preparation: input.sync,
+    test: input.test,
+    quality: input.quality,
+    conformance: input.conformance,
+    stale: input.stale,
+    preview: input.preview,
+    labels: {
+      lock: 'uv lock --check',
+      preparation: 'uv sync',
+      stale: 'a stale coverage report',
+    },
+  });
   return {
-    ok: lock && sync && test && conformance && quality && !staleArtifacts,
-    reason,
-    checks: { lock, sync, test, conformance, quality, staleArtifacts },
+    ok: summary.ok,
+    reason: summary.reason,
+    checks: {
+      lock: summary.checks.lock,
+      sync: summary.checks.preparation,
+      test: summary.checks.test,
+      conformance: summary.checks.conformance,
+      quality: summary.checks.quality,
+      staleArtifacts: summary.checks.staleArtifacts,
+    },
   };
 }

package/src/validation/evidence.ts

@@ -1,3 +1,15 @@
+/**
+ * Python's view of the shared completion-evidence gate.
+ *
+ * The gate itself lives in `pi-helper-core`; this module maps the Python
+ * wording ("environment sync") onto the core's preparation stage so call sites
+ * keep their existing input shape.
+ */
+import {
+  buildCompletionEvidence as coreBuildCompletionEvidence,
+  type CompletionEvidence,
+} from 'pi-helper-core';
+
 export interface CompletionEvidenceInput {
   syncExecuted: boolean;
   syncOk: boolean;
@@ -7,27 +19,19 @@ export interface CompletionEvidenceInput {
   changedPaths: string[];
 }
 
-export interface CompletionEvidence {
-  ok: boolean;
-  blockers: string[];
-  changedPaths: string[];
-}
+export type { CompletionEvidence };
 
-/**
- * Completion is only proven when the environment was synchronised and the tests
- * actually ran. Declaring completion on a partial run is treated as a blocker,
- * never as a warning.
- */
 export function buildCompletionEvidence(input: CompletionEvidenceInput): CompletionEvidence {
-  const blockers: string[] = [];
-  if (!input.syncExecuted)
-    blockers.push('The environment sync (uv sync/lock check) was not executed.');
-  else if (!input.syncOk) blockers.push('The environment sync did not pass.');
-  if (!input.testExecuted) blockers.push('Tests were not executed.');
-  else if (!input.testOk) blockers.push('Tests did not pass.');
-  if (input.stale)
-    blockers.push(
-      'Stale artifacts were detected, so the test result does not describe the current sources.',
-    );
-  return { ok: blockers.length === 0, blockers, changedPaths: input.changedPaths };
+  return coreBuildCompletionEvidence({
+    preparation: {
+      name: 'sync',
+      label: 'environment sync (uv sync/lock check)',
+      executed: input.syncExecuted,
+      ok: input.syncOk,
+    },
+    testExecuted: input.testExecuted,
+    testOk: input.testOk,
+    stale: input.stale,
+    changedPaths: input.changedPaths,
+  });
 }

package/src/validation/tdd.ts

@@ -1,135 +1,26 @@
-import { isTestFile } from '../project/paths.ts';
-
-/** A production file and a test file that were matched to each other. */
-export interface TddAssociation {
-  source: string;
-  test: string;
-  /** Tokens both paths share, so the caller can judge the match. */
-  sharedTokens: string[];
-  /**
-   * `module` when the match goes beyond the path prefix every file shares,
-   * `package` when only the common package prefix matched. A package-level match
-   * still passes the checkpoint, but it is weak evidence and is disclosed.
-   */
-  strength: 'module' | 'package';
-}
-
-export interface TddCheckpoint {
-  ok: boolean;
-  reasons: string[];
-  sourceChanges: string[];
-  testChanges: string[];
-  associations: TddAssociation[];
-  /** True when a match rested only on the shared package prefix. */
-  weakAssociation: boolean;
-}
-
-/** Tokens shorter than this cannot distinguish two module names. */
-const MIN_TOKEN_LENGTH = 4;
-
-/** Tokens that appear in the prefix of every file and so carry no meaning. */
-const PREFIX_TOKENS = new Set(['test', 'tests', 'testing', 'src', 'lib']);
-
-function tokens(path: string): string[] {
-  return path
-    .replace(/\.py$/i, '')
-    .split(/[^A-Za-z0-9]+/)
-    .map((token) => token.toLowerCase())
-    .filter((token) => token.length >= MIN_TOKEN_LENGTH && !PREFIX_TOKENS.has(token));
-}
-
-function sharedTokens(source: string, test: string): string[] {
-  const testTokens = tokens(test);
-  const shared: string[] = [];
-  for (const sourceToken of new Set(tokens(source))) {
-    if (
-      testTokens.some(
-        (testToken) =>
-          sourceToken === testToken ||
-          sourceToken.startsWith(testToken) ||
-          testToken.startsWith(sourceToken),
-      )
-    ) {
-      shared.push(sourceToken);
-    }
-  }
-  return shared;
-}
-
 /**
- * Tokens contributed by the directory prefix every changed path shares.
+ * Python's view of the shared TDD checkpoint.
  *
- * In a project whose tests live inside the package under test, every path starts
- * with the package name, so those tokens say nothing about whether a specific
- * test covers a specific module. A common prefix of nothing (no shared
- * directory) yields no exclusions, so an exact name match is never downgraded.
+ * The ordering and token-overlap logic live in `pi-helper-core`; this module
+ * only supplies which files count as production code or tests in a Python
+ * project, so call sites keep their two-argument signature.
  */
-function commonPrefixTokens(paths: string[]): Set<string> {
-  if (paths.length < 2) return new Set();
-  const directories = paths.map((path) => path.replace(/\\/g, '/').split('/').slice(0, -1));
-  const [first, ...rest] = directories;
-  const common: string[] = [];
-  for (let index = 0; index < first.length; index += 1) {
-    const segment = first[index];
-    if (rest.every((entry) => entry[index] === segment)) common.push(segment);
-    else break;
-  }
-  return new Set(common.flatMap((segment) => tokens(segment)));
+import { checkTdd as coreCheckTdd, type TddSignals } from 'pi-helper-core';
+import { isPythonFile, isTestFile } from '../project/paths.ts';
+
+/** Tokens that appear in the prefix of most paths and so cannot distinguish modules. */
+const PYTHON_TDD_SIGNALS: TddSignals = {
+  isSourceFile: isPythonFile,
+  isTestFile,
+  prefixTokens: new Set(['test', 'tests', 'testing', 'src', 'lib']),
+  minTokenLength: 4,
+};
+
+export function checkTdd(
+  changedPaths: string[],
+  testChangedPaths: string[] = [],
+): import('pi-helper-core').TddCheckpoint {
+  return coreCheckTdd(changedPaths, testChangedPaths, PYTHON_TDD_SIGNALS);
 }
 
-/**
- * Check that production changes are accompanied by a plausibly related test
- * change.
- *
- * Matching is name-based on purpose: it is cheap, deterministic, and only used
- * to decide whether to run the heavier verification bundle. Because it is only
- * name-based, it also reports *why* each pair matched and downgrades a match
- * that rests solely on the package prefix instead of silently counting it as
- * strong evidence.
- */
-export function checkTdd(changedPaths: string[], testChangedPaths: string[] = []): TddCheckpoint {
-  const all = [...new Set([...changedPaths, ...testChangedPaths])].map((path) =>
-    path.replace(/\\/g, '/'),
-  );
-  const sourceChanges = all.filter((path) => path.endsWith('.py') && !isTestFile(path));
-  const testChanges = all.filter((path) => path.endsWith('.py') && isTestFile(path));
-
-  // `fastapi_server/db/database.py` and `fastapi_server/tests/unit/test_db.py`
-  // share `fastapi` and `server` with every other file in the project, so those
-  // tokens must not be treated as evidence of a real relationship.
-  const ubiquitous = commonPrefixTokens([...sourceChanges, ...testChanges]);
-
-  const associations: TddAssociation[] = [];
-  for (const source of sourceChanges) {
-    for (const test of testChanges) {
-      const shared = sharedTokens(source, test);
-      if (shared.length === 0) continue;
-      const discriminating = shared.filter((token) => !ubiquitous.has(token));
-      associations.push({
-        source,
-        test,
-        sharedTokens: shared,
-        strength: discriminating.length > 0 ? 'module' : 'package',
-      });
-    }
-  }
-
-  const strong = associations.some((entry) => entry.strength === 'module');
-  const weakAssociation = associations.length > 0 && !strong;
-
-  const reasons: string[] = [];
-  if (sourceChanges.length > 0 && testChanges.length === 0) {
-    reasons.push('Production Python files changed without any test file change.');
-  } else if (sourceChanges.length > 0 && associations.length === 0) {
-    reasons.push('Changed test files do not appear related to the changed production modules.');
-  }
-
-  return {
-    ok: reasons.length === 0,
-    reasons,
-    sourceChanges,
-    testChanges,
-    associations,
-    weakAssociation,
-  };
-}
+export type { TddAssociation, TddCheckpoint } from 'pi-helper-core';