pi-python-helper 0.2.0 → 0.4.0

package/src/core/result.ts

@@ -1,102 +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> {
-  ok: 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';
+
+export const { result, failure } = createResultFactory(TOOL_VERSION);
 
-export function result<T>(
-  cwd: string,
-  startedAt: number,
-  value: Omit<PyToolResult<T>, 'metadata'> & {
-    truncated?: boolean;
-    projectRoot?: string;
-    pythonVersion?: string;
-  },
-): PyToolResult<T> {
-  return {
-    ...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/dependencies/aliases.ts

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

package/src/project/scanner.ts

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

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