pi-python-helper 0.1.0

package/src/build/failure.ts

@@ -0,0 +1,452 @@
+import type { Suggestion } from '../core/result.ts';
+
+export type FailureKind =
+  | 'module_not_found'
+  | 'environment_not_synced'
+  | 'import_error'
+  | 'syntax_error'
+  | 'collection_error'
+  | 'fixture_error'
+  | 'assertion'
+  | 'runtime_error'
+  | 'lockfile_out_of_date'
+  | 'resolution_error'
+  | 'dependency_conflict'
+  | 'timeout'
+  | 'unknown';
+
+export interface TracebackFrame {
+  path: string;
+  line: number;
+  func: string;
+  /** True for site-packages, the standard library, and pytest internals. */
+  library: boolean;
+}
+
+export interface FailureEvidence {
+  file?: string;
+  line?: number;
+  message: string;
+}
+
+export interface FailureDiagnosis {
+  kind: FailureKind;
+  summary: string;
+  missingModule?: string;
+  importTarget?: { name: string; module: string };
+  exceptionType?: string;
+  frames: TracebackFrame[];
+  /** Last frame outside site-packages: the line the user should look at. */
+  firstUserFrame?: TracebackFrame;
+  evidence: FailureEvidence[];
+  suggestions: Suggestion[];
+}
+
+const FRAME_RE = /^\s*File "([^"]+)", line (\d+), in (.+?)\s*$/;
+/**
+ * pytest `--tb=short` replaces the `File "..."` form with `path:line: in func`,
+ * so both notations must be recognised or short tracebacks yield no frame at all.
+ */
+const PYTEST_FRAME_RE = /^\s*([^\s:]+\.py):(\d+): in (.+?)\s*$/;
+
+/**
+ * A frame belongs to library code when it sits in an installed distribution or
+ * in the interpreter's own library tree. Pointing the agent at those frames is
+ * how it ends up editing site-packages instead of the project.
+ */
+export function isLibraryFrame(path: string): boolean {
+  const normalized = path.replace(/\\/g, '/');
+  return (
+    /\/site-packages\//.test(normalized) ||
+    /\/dist-packages\//.test(normalized) ||
+    /\/lib\/python3\.\d+\//.test(normalized) ||
+    /\/python3\.\d+\//.test(normalized) ||
+    /<frozen /.test(normalized) ||
+    /\/_pytest\//.test(normalized) ||
+    /\/pluggy\//.test(normalized)
+  );
+}
+
+export function extractTracebackFrames(output: string): TracebackFrame[] {
+  const frames: TracebackFrame[] = [];
+  for (const line of output.split(/\r?\n/)) {
+    const match = line.match(FRAME_RE) ?? line.match(PYTEST_FRAME_RE);
+    if (!match) continue;
+    const path = match[1];
+    frames.push({
+      path,
+      line: Number.parseInt(match[2], 10),
+      func: match[3].trim(),
+      library: isLibraryFrame(path),
+    });
+  }
+  return frames;
+}
+
+function firstUserFrame(frames: TracebackFrame[]): TracebackFrame | undefined {
+  for (let index = frames.length - 1; index >= 0; index -= 1) {
+    if (!frames[index].library) return frames[index];
+  }
+  return undefined;
+}
+
+function lastMatch(output: string, pattern: RegExp): RegExpMatchArray | undefined {
+  const matches = [...output.matchAll(new RegExp(pattern.source, `${pattern.flags}g`))];
+  return matches.at(-1);
+}
+
+/**
+ * Classify the first actionable cause in bounded command output. The order of
+ * the checks matters: a resolution failure means nothing downstream is
+ * trustworthy, and a missing module explains the traceback that follows it.
+ */
+export function diagnoseFailure(output: string): FailureDiagnosis {
+  const frames = extractTracebackFrames(output);
+  const userFrame = firstUserFrame(frames);
+
+  const lockProblem = lastMatch(
+    output,
+    /(?:lockfile at .*needs to be updated|--locked was provided|lockfile .* is not up to date|`uv lock`)/i,
+  );
+  if (lockProblem) {
+    return {
+      kind: 'lockfile_out_of_date',
+      summary:
+        'uv refused to continue because uv.lock no longer matches pyproject.toml (--locked/--frozen was used).',
+      exceptionType: 'uv',
+      frames,
+      firstUserFrame: userFrame,
+      evidence: [{ message: lockProblem[0].trim() }],
+      suggestions: [
+        {
+          message: 'Run uv lock and commit the refreshed uv.lock before rerunning the command.',
+          confidence: 'high',
+          command: 'uv lock',
+        },
+      ],
+    };
+  }
+
+  const conflict = lastMatch(
+    output,
+    /(?:Because .+ depends on .+|No solution found when resolving dependencies|version solving failed)/,
+  );
+  if (conflict) {
+    return {
+      kind: 'dependency_conflict',
+      summary: 'uv could not find a version set that satisfies every declared constraint.',
+      exceptionType: 'uv',
+      frames,
+      firstUserFrame: userFrame,
+      evidence: [{ message: conflict[0].trim() }],
+      suggestions: [
+        {
+          message:
+            'Inspect the reported conflict chain and relax or pin the offending requirement.',
+          confidence: 'high',
+          command: 'uv lock --verbose',
+        },
+      ],
+    };
+  }
+
+  const resolveFailure = lastMatch(
+    output,
+    /(?:Failed to resolve requirements|error: Failed to download|Could not find a version that satisfies)/,
+  );
+  if (resolveFailure) {
+    return {
+      kind: 'resolution_error',
+      summary: 'uv could not resolve or download a declared requirement.',
+      exceptionType: 'uv',
+      frames,
+      firstUserFrame: userFrame,
+      evidence: [{ message: resolveFailure[0].trim() }],
+      suggestions: [
+        {
+          message:
+            'Check the package name and version constraint, then retry with uv lock --verbose.',
+          confidence: 'medium',
+        },
+      ],
+    };
+  }
+
+  const missing = lastMatch(output, /ModuleNotFoundError: No module named '([^']+)'/);
+  const cannotImport = lastMatch(
+    output,
+    /ImportError: cannot import name '([^']+)' from '([^']+)'/,
+  );
+  const syntax = lastMatch(output, /SyntaxError: (.+)/);
+  const fixture = lastMatch(
+    output,
+    /(?:fixture '[^']+' not found|ERROR at setup of|error in .* fixture)/,
+  );
+  const collection = lastMatch(
+    output,
+    /(?:errors during collection|Interrupted: \d+ error|ERROR collecting)/,
+  );
+  const assertion = lastMatch(output, /^\s*E\s+(AssertionError.*|assert .*)$/m);
+  // pytest prefixes the exception line with `E ` inside a report, so the marker
+  // must be optional here or a plain NameError/ValueError looks unclassified.
+  const genericError = lastMatch(output, /^(?:\s*E\s+)?(?:[A-Za-z_.]*(?:Error|Exception)): (.+)$/m);
+
+  // Pick the cause that appears first in the output. "First actionable" must be
+  // positional: a fixture error printed after a failing assertion is not the
+  // root cause the user needs to read first.
+  const candidates: { kind: FailureKind; index: number }[] = [];
+  const consider = (kind: FailureKind, pattern: RegExp) => {
+    const match = output.match(pattern);
+    if (match?.index !== undefined) candidates.push({ kind, index: match.index });
+  };
+  consider('module_not_found', /ModuleNotFoundError: No module named '([^']+)'/);
+  consider('import_error', /ImportError: cannot import name '([^']+)' from '([^']+)'/);
+  consider('syntax_error', /SyntaxError: (.+)/);
+  consider('fixture_error', /(?:fixture '[^']+' not found|ERROR at setup of|error in .* fixture)/);
+  consider(
+    'collection_error',
+    /(?:errors during collection|Interrupted: \d+ error|ERROR collecting)/,
+  );
+  consider('assertion', /^\s*E\s+(AssertionError.*|assert .*)$/m);
+  consider('runtime_error', /^(?:\s*E\s+)?(?:[A-Za-z_.]*(?:Error|Exception)): (.+)$/m);
+  candidates.sort((left, right) => left.index - right.index);
+  const kind: FailureKind = candidates[0]?.kind ?? 'unknown';
+
+  if (kind === 'module_not_found' && missing) {
+    const module = missing[1].split('.')[0];
+    return {
+      kind: 'module_not_found',
+      summary: `Import failed because the module "${module}" could not be found.`,
+      missingModule: module,
+      exceptionType: 'ModuleNotFoundError',
+      frames,
+      firstUserFrame: userFrame,
+      evidence: [{ message: missing[0].trim(), file: userFrame?.path, line: userFrame?.line }],
+      suggestions: [
+        {
+          message: `Declare the distribution that provides "${module}" with uv add ${module} if it is third-party. Import names often differ from distribution names (PIL/pillow, yaml/PyYAML).`,
+          confidence: 'medium',
+          command: `uv add ${module}`,
+        },
+        {
+          message:
+            'If the module is project code, run uv sync so the project package is installed in editable mode.',
+          confidence: 'medium',
+          command: 'uv sync',
+        },
+      ],
+    };
+  }
+
+  const cannotImportBranch = kind === 'import_error' ? cannotImport : undefined;
+  if (cannotImportBranch) {
+    return {
+      kind: 'import_error',
+      summary: `The name "${cannotImportBranch[1]}" does not exist in module "${cannotImportBranch[2]}".`,
+      importTarget: { name: cannotImportBranch[1], module: cannotImportBranch[2] },
+      exceptionType: 'ImportError',
+      frames,
+      firstUserFrame: userFrame,
+      evidence: [
+        { message: cannotImportBranch[0].trim(), file: userFrame?.path, line: userFrame?.line },
+      ],
+      suggestions: [
+        {
+          message: `Verify the symbol name in "${cannotImportBranch[2]}" and whether the installed version exposes it.`,
+          confidence: 'medium',
+        },
+      ],
+    };
+  }
+
+  if (kind === 'syntax_error' && syntax) {
+    const location = lastMatch(output, /File "([^"]+)", line (\d+)/);
+    return {
+      kind: 'syntax_error',
+      summary: `A file could not be parsed: ${syntax[1].trim()}`,
+      exceptionType: 'SyntaxError',
+      frames,
+      firstUserFrame: userFrame,
+      evidence: [
+        {
+          message: syntax[0].trim(),
+          file: location?.[1],
+          line: location ? Number.parseInt(location[2], 10) : undefined,
+        },
+      ],
+      suggestions: [
+        {
+          message: 'Fix the syntax error at the reported file and line before rerunning.',
+          confidence: 'high',
+        },
+      ],
+    };
+  }
+
+  if (kind === 'fixture_error' && fixture) {
+    return {
+      kind: 'fixture_error',
+      summary: 'A pytest fixture could not be resolved for a test.',
+      exceptionType: 'fixture',
+      frames,
+      firstUserFrame: userFrame,
+      evidence: [{ message: fixture[0].trim(), file: userFrame?.path, line: userFrame?.line }],
+      suggestions: [
+        {
+          message: 'Define the fixture in a conftest.py that is in scope for the failing test.',
+          confidence: 'medium',
+        },
+      ],
+    };
+  }
+
+  if (kind === 'collection_error' && collection) {
+    return {
+      kind: 'collection_error',
+      summary: 'pytest could not collect the test suite, so no test result is trustworthy.',
+      exceptionType: 'pytest',
+      frames,
+      firstUserFrame: userFrame,
+      evidence: [{ message: collection[0].trim(), file: userFrame?.path, line: userFrame?.line }],
+      suggestions: [
+        {
+          message:
+            'Resolve the import or syntax error reported for the collected file, then rerun.',
+          confidence: 'high',
+        },
+      ],
+    };
+  }
+
+  if (kind === 'assertion' && assertion) {
+    return {
+      kind: 'assertion',
+      summary: 'A test assertion failed; the expectation does not match the observed behaviour.',
+      exceptionType: 'AssertionError',
+      frames,
+      firstUserFrame: userFrame,
+      evidence: [
+        {
+          message: assertion[1].trim().slice(0, 500),
+          file: userFrame?.path,
+          line: userFrame?.line,
+        },
+      ],
+      suggestions: [
+        {
+          message:
+            'Inspect the failing expectation and the production code that produced the value.',
+          confidence: 'medium',
+        },
+      ],
+    };
+  }
+
+  if (kind === 'runtime_error' && genericError) {
+    const exceptionType = genericError[0].trim().split(':')[0].trim().replace(/^E\s+/, '');
+    return {
+      kind: 'runtime_error',
+      summary: genericError[0].trim().slice(0, 300),
+      exceptionType,
+      frames,
+      firstUserFrame: userFrame,
+      evidence: [
+        {
+          message: genericError[0].trim().slice(0, 500),
+          file: userFrame?.path,
+          line: userFrame?.line,
+        },
+      ],
+      suggestions: [
+        {
+          message: userFrame
+            ? `Start from ${userFrame.path}:${userFrame.line}; frames inside site-packages are not the cause.`
+            : 'The failure has no project frame; check whether the command ran in the intended environment.',
+          confidence: 'low',
+        },
+      ],
+    };
+  }
+
+  return {
+    kind: 'unknown',
+    summary:
+      'No recognised Python, pytest, or uv failure pattern was found in the captured output.',
+    frames,
+    firstUserFrame: userFrame,
+    evidence: [],
+    suggestions: [
+      {
+        message:
+          'Rerun the command with more verbose output so the first actionable cause is captured.',
+        confidence: 'low',
+      },
+    ],
+  };
+}
+
+/**
+ * Improve a diagnosis using the project model. A module that is declared but
+ * still unimportable is an environment problem, not a missing declaration.
+ */
+export function refineWithDeclarations(
+  diagnosis: FailureDiagnosis,
+  input: { declared: Set<string>; localModules: Set<string> },
+): FailureDiagnosis {
+  const module = diagnosis.missingModule;
+  if (!module) return diagnosis;
+  const normalized = module.replace(/[-_.]+/g, '-').toLowerCase();
+  const suggestions: Suggestion[] = [];
+
+  if (input.localModules.has(module)) {
+    return {
+      ...diagnosis,
+      kind: 'environment_not_synced',
+      summary: `"${module}" is project code but is not importable from the active interpreter.`,
+      suggestions: [
+        {
+          message:
+            'The package is not installed into the environment. Run uv sync so the project is installed in editable mode.',
+          confidence: 'high',
+          command: 'uv sync',
+        },
+        {
+          message: 'Confirm the import path matches the src layout (src/<package>/...).',
+          confidence: 'medium',
+        },
+      ],
+    };
+  }
+
+  if (input.declared.has(normalized)) {
+    return {
+      ...diagnosis,
+      kind: 'environment_not_synced',
+      summary: `"${module}" is declared in pyproject.toml but is missing from the active environment.`,
+      suggestions: [
+        {
+          message: 'The environment is out of sync with the lockfile. Run uv sync --frozen.',
+          confidence: 'high',
+          command: 'uv sync --frozen',
+        },
+        {
+          message:
+            'If the command ran outside the project environment, re-run it through uv run so the correct interpreter is used.',
+          confidence: 'high',
+          command: 'uv run --frozen pytest',
+        },
+      ],
+    };
+  }
+
+  suggestions.push({
+    message: `Declare the distribution providing "${module}" with uv add ${module}, or verify the import name.`,
+    confidence: 'medium',
+    command: `uv add ${module}`,
+  });
+  suggestions.push({
+    message: 'Import names can differ from distribution names (PIL/pillow, yaml/PyYAML).',
+    confidence: 'medium',
+  });
+  return { ...diagnosis, suggestions: [...diagnosis.suggestions, ...suggestions] };
+}

package/src/build/pytest.ts

@@ -0,0 +1,118 @@
+export interface PytestCounts {
+  passed: number;
+  failed: number;
+  errors: number;
+  skipped: number;
+  xfailed: number;
+  xpassed: number;
+  deselected: number;
+  warnings: number;
+}
+
+export interface PytestFailure {
+  /** Full node id, for example `tests/test_api.py::TestApi::test_get`. */
+  test: string;
+  file?: string;
+  message: string;
+  kind: 'FAILED' | 'ERROR';
+}
+
+export interface PytestReport {
+  counts: PytestCounts;
+  failures: PytestFailure[];
+  summaryLine?: string;
+  noTestsRan: boolean;
+  /** Set when pytest never reached its summary, for example on a hard crash. */
+  incomplete: boolean;
+}
+
+const EMPTY_COUNTS: PytestCounts = {
+  passed: 0,
+  failed: 0,
+  errors: 0,
+  skipped: 0,
+  xfailed: 0,
+  xpassed: 0,
+  deselected: 0,
+  warnings: 0,
+};
+
+function countFromLine(line: string, pattern: RegExp): number {
+  const match = line.match(pattern);
+  return match ? Number.parseInt(match[1], 10) : 0;
+}
+
+function isSummaryLine(line: string): boolean {
+  const trimmed = line.trim();
+  if (!trimmed) return false;
+  if (/^=+.*=+$/.test(trimmed)) return true;
+  return /(?:passed|failed|error|no tests ran)/.test(trimmed) && trimmed.length < 200;
+}
+
+/**
+ * Parse `pytest -q --tb=short -rf` output. The final summary line carries the
+ * counts and the short test summary section carries the failing node ids.
+ */
+export function parsePytestOutput(stdout: string, stderr = ''): PytestReport {
+  const text = `${stdout}\n${stderr}`;
+  const lines = text.split(/\r?\n/);
+
+  let summaryLine: string | undefined;
+  for (const line of lines) {
+    if (isSummaryLine(line)) summaryLine = line.trim();
+  }
+
+  const counted = summaryLine ?? '';
+  const counts: PytestCounts = {
+    passed: countFromLine(counted, /(\d+) passed/),
+    failed: countFromLine(counted, /(\d+) failed/),
+    errors: countFromLine(counted, /(\d+) errors?\b/),
+    skipped: countFromLine(counted, /(\d+) skipped/),
+    xfailed: countFromLine(counted, /(\d+) xfailed/),
+    xpassed: countFromLine(counted, /(\d+) xpassed/),
+    deselected: countFromLine(counted, /(\d+) deselected/),
+    warnings: countFromLine(counted, /(\d+) warnings?\b/),
+  };
+
+  const noTestsRan = /no tests ran/.test(counted);
+
+  const failures: PytestFailure[] = [];
+  const seen = new Set<string>();
+  for (const line of lines) {
+    const match = line.match(/^(FAILED|ERROR)\s+(\S+?)(?:\s+-\s+(.*))?$/);
+    if (!match) continue;
+    const [, kind, nodeId, message] = match;
+    if (seen.has(`${kind} ${nodeId}`)) continue;
+    seen.add(`${kind} ${nodeId}`);
+    const fileIndex = nodeId.indexOf('::');
+    failures.push({
+      test: nodeId,
+      file: fileIdToPath(fileIndex === -1 ? nodeId : nodeId.slice(0, fileIndex)),
+      message: (message ?? '').trim(),
+      kind: kind as 'FAILED' | 'ERROR',
+    });
+  }
+
+  const incomplete =
+    counts.passed + counts.failed + counts.errors + counts.skipped === 0 &&
+    !noTestsRan &&
+    !/(?:collected \d+ item|test session starts)/.test(text);
+
+  return { counts, failures, summaryLine, noTestsRan, incomplete };
+}
+
+/** pytest prints collected node ids relative to the invocation root. */
+function fileIdToPath(fileId: string): string | undefined {
+  const trimmed = fileId.trim();
+  return trimmed.endsWith('.py') ? trimmed : undefined;
+}
+
+export function totalTests(counts: PytestCounts): number {
+  return (
+    counts.passed + counts.failed + counts.errors + counts.skipped + counts.xfailed + counts.xpassed
+  );
+}
+
+export function emptyCounts(): PytestCounts {
+  return { ...EMPTY_COUNTS };
+}

package/src/build/selection.ts

@@ -0,0 +1,138 @@
+import { basename, dirname, join } from 'node:path';
+import { isPythonFile, 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;
+  changedSourceFiles: string[];
+  changedTestFiles: string[];
+  consideredTestFiles: string[];
+}
+
+const SCORE = {
+  changedTestItself: 100,
+  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();
+}
+
+function firstImportableSegment(path: string): string {
+  const segments = toPosix(path)
+    .split('/')
+    .filter((segment) => segment.length > 0);
+  const index = segments.lastIndexOf('src');
+  const start = index === -1 ? 0 : index + 1;
+  return (segments[start] ?? '').replace(/\.py$/i, '').toLowerCase();
+}
+
+/**
+ * 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.
+ */
+export function selectTests(changedPaths: string[], testFiles: string[]): 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();
+
+  if (!changed.length) {
+    return {
+      selected: [],
+      fellBackToAll: false,
+      changedSourceFiles,
+      changedTestFiles,
+      consideredTestFiles: considered,
+    };
+  }
+
+  const sourceTokens = new Set(changedSourceFiles.flatMap(pathTokens));
+  const sourceModules = new Set(changedSourceFiles.map(firstImportableSegment));
+  const sourceDirs = new Set(changedSourceFiles.map(parentDir));
+  const sourceStems = new Set(changedSourceFiles.map(normalizedStem));
+
+  const selections: TestSelection[] = [];
+  for (const testFile of considered) {
+    const reasons: string[] = [];
+    let score = 0;
+
+    if (changedTestFiles.includes(testFile)) {
+      score += SCORE.changedTestItself;
+      reasons.push('the test file itself changed');
+    }
+    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)) {
+      score += SCORE.sharedModule;
+      reasons.push(`covers module "${module}"`);
+    }
+
+    const tokens = pathTokens(testFile);
+    const shared = tokens.filter((token) => sourceTokens.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 fellBackToAll = selections.length === 0 && considered.length > 0;
+  return {
+    selected: fellBackToAll
+      ? considered.map((path) => ({ path, score: 0, reason: 'no match; running the full suite' }))
+      : selections,
+    fellBackToAll,
+    changedSourceFiles,
+    changedTestFiles,
+    consideredTestFiles: considered,
+  };
+}