pi-python-helper 0.1.0 → 0.2.0

package/src/project/root.ts

@@ -1,4 +1,5 @@
-import { access, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { access, readdir, stat } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 
 /** Files that mark the root of a uv-managed Python project. */
@@ -56,6 +57,89 @@ export async function findVenvDir(root: string): Promise<string | undefined> {
   return (await isDirectory(candidate)) ? candidate : undefined;
 }
 
+const TEST_DIRECTORY_NAMES = new Set(['test', 'tests', 'testing']);
+
+/** Directories that can never contain the project's own tests. */
+const UNSCANNABLE_DIRECTORIES = new Set([
+  '.git',
+  '.venv',
+  'venv',
+  '.tox',
+  '.nox',
+  '__pycache__',
+  'node_modules',
+  'build',
+  'dist',
+  '.eggs',
+  '.mypy_cache',
+  '.ruff_cache',
+  '.pytest_cache',
+]);
+
+/**
+ * Find the directories that hold tests, relative to the project root.
+ *
+ * Looking only for `./tests` misses the common layout where the suite lives
+ * inside the package it tests (`<package>/tests/`), which made the tool claim a
+ * project with hundreds of tests had none.
+ */
+export async function findTestDirectories(root: string, maxDepth = 3): Promise<string[]> {
+  const found: string[] = [];
+  const walk = async (directory: string, relative: string, depth: number): Promise<void> => {
+    let entries;
+    try {
+      entries = await readdir(directory, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+      if (!entry.isDirectory()) continue;
+      const name = entry.name;
+      if (name.startsWith('.')) continue;
+      const childRelative = relative ? `${relative}/${name}` : name;
+      if (TEST_DIRECTORY_NAMES.has(name)) {
+        found.push(childRelative);
+        continue;
+      }
+      if (UNSCANNABLE_DIRECTORIES.has(name)) continue;
+      if (depth < maxDepth) await walk(join(directory, name), childRelative, depth + 1);
+    }
+  };
+  await walk(root, '', 1);
+  return found;
+}
+
+const WINDOWS = process.platform === 'win32';
+
+/**
+ * Locate the interpreter inside a project virtual environment.
+ *
+ * The interpreter that runs the read-only scanner decides which
+ * `site-packages` it can see: a host `python3` maps four modules while the
+ * project's own interpreter maps the whole environment, so asking the wrong one
+ * makes every import name look like it has no providing distribution.
+ */
+export async function findVenvInterpreter(venvDir: string): Promise<string | undefined> {
+  const directories = WINDOWS
+    ? [join(venvDir, 'Scripts'), join(venvDir, 'bin')]
+    : [join(venvDir, 'bin'), join(venvDir, 'Scripts')];
+  const names = WINDOWS ? ['python.exe', 'python'] : ['python', 'python3'];
+  for (const directory of directories) {
+    for (const name of names) {
+      const candidate = join(directory, name);
+      try {
+        const info = await stat(candidate);
+        if (!info.isFile()) continue;
+        if (!WINDOWS) await access(candidate, constants.X_OK);
+        return candidate;
+      } catch {
+        continue;
+      }
+    }
+  }
+  return undefined;
+}
+
 export async function isGitIgnored(root: string, entry: string): Promise<boolean | undefined> {
   const gitignore = join(root, '.gitignore');
   try {

package/src/project/scanner.ts

@@ -1,4 +1,5 @@
 import { runCommand } from '../core/runner.ts';
+import { findVenvDir, findVenvInterpreter } from './root.ts';
 
 export const HELPER_URL = new URL('../../helpers/scan_project.py', import.meta.url);
 
@@ -13,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 = 1;
+export const SUPPORTED_SCANNER_VERSION = 2;
 
 export interface DeclaredDependency {
   raw: string;
@@ -88,7 +89,16 @@ export interface ImportSection {
   stdlibAvailable: boolean;
   layout: 'src' | 'flat';
   localModules: string[];
-  files: { path: string; imports: string[]; typeCheckingImports: string[] }[];
+  files: {
+    path: string;
+    imports: string[];
+    /**
+     * Full dotted module names the file references, so a test file can be
+     * matched to the module it imports rather than only by file name.
+     */
+    importModules?: string[];
+    typeCheckingImports: string[];
+  }[];
   thirdParty: {
     import: string;
     files: string[];
@@ -137,6 +147,8 @@ export interface ScanPayload {
 export interface ScanOutcome {
   ok: boolean;
   interpreter?: string;
+  /** Whether the interpreter came from the project environment or from PATH. */
+  interpreterOrigin?: 'venv' | 'path';
   payload?: ScanPayload;
   /** Diagnostic code the caller can surface verbatim when `ok` is false. */
   code?:
@@ -145,17 +157,23 @@ export interface ScanOutcome {
   stderr?: string;
 }
 
-let interpreterPromise: Promise<string | undefined> | undefined;
+const interpreterPromises = new Map<string, Promise<string | undefined>>();
 
 /**
  * Pick the interpreter used for read-only analysis. `python3` is preferred so a
  * `python` that points at a legacy Python 2 install is never selected.
+ *
+ * Results are cached per key so repeated tool calls in one session do not probe
+ * PATH again.
  */
 export async function resolveInterpreter(
   cwd: string,
   signal?: AbortSignal,
+  cacheKey = 'path',
 ): Promise<string | undefined> {
-  interpreterPromise ??= (async () => {
+  const cached = interpreterPromises.get(cacheKey);
+  if (cached) return cached;
+  const pending = (async () => {
     for (const candidate of ['python3', 'python']) {
       const probe = await runCommand(candidate, ['-c', 'import sys; print(sys.version_info[0])'], {
         cwd,
@@ -167,7 +185,29 @@ export async function resolveInterpreter(
     }
     return undefined;
   })();
-  return interpreterPromise;
+  interpreterPromises.set(cacheKey, pending);
+  return pending;
+}
+
+/**
+ * Resolve the interpreter whose `site-packages` describe this project.
+ *
+ * The scanner answers "which distribution provides this import?" by asking the
+ * interpreter it runs under. A host `python3` sees only its own site-packages,
+ * so every project dependency looks unowned; the project's own interpreter sees
+ * the environment that `uv sync` actually built.
+ */
+export async function resolveProjectInterpreter(
+  root: string,
+  cwd: string,
+  signal?: AbortSignal,
+): Promise<{ interpreter?: string; origin: 'venv' | 'path' }> {
+  const venvDir = await findVenvDir(root);
+  if (venvDir) {
+    const venvInterpreter = await findVenvInterpreter(venvDir);
+    if (venvInterpreter) return { interpreter: venvInterpreter, origin: 'venv' };
+  }
+  return { interpreter: await resolveInterpreter(cwd, signal), origin: 'path' };
 }
 
 /**
@@ -180,12 +220,14 @@ export async function runScanProject(
   request: { root: string; mode: ScanMode; maxFiles?: number },
   signal?: AbortSignal,
 ): Promise<ScanOutcome> {
-  const interpreter = await resolveInterpreter(cwd, signal);
+  const resolved = await resolveProjectInterpreter(request.root, cwd, signal);
+  const interpreter = resolved.interpreter;
+  const origin = resolved.origin;
   if (!interpreter) {
     return {
       ok: false,
       code: 'PYTHON_NOT_FOUND',
-      message: 'No Python 3 interpreter was found on PATH.',
+      message: 'No Python 3 interpreter was found in the project environment or on PATH.',
     };
   }
   const helper = HELPER_URL.pathname;
@@ -200,6 +242,7 @@ export async function runScanProject(
     return {
       ok: false,
       interpreter,
+      interpreterOrigin: origin,
       code: 'SCANNER_FAILED',
       message: 'The project scanner timed out.',
     };
@@ -208,6 +251,7 @@ export async function runScanProject(
     return {
       ok: false,
       interpreter,
+      interpreterOrigin: origin,
       code: 'SCANNER_FAILED',
       message: 'The project scanner exited with an error.',
       stderr: run.stderr.trim() || undefined,
@@ -216,7 +260,13 @@ export async function runScanProject(
   try {
     const payload = JSON.parse(run.stdout) as ScanPayload;
     if (payload.error) {
-      return { ok: false, interpreter, code: 'SCANNER_FAILED', message: payload.error };
+      return {
+        ok: false,
+        interpreter,
+        interpreterOrigin: origin,
+        code: 'SCANNER_FAILED',
+        message: payload.error,
+      };
     }
     // Refuse to interpret a document whose shape may have changed.
     if (
@@ -226,15 +276,17 @@ export async function runScanProject(
       return {
         ok: false,
         interpreter,
+        interpreterOrigin: origin,
         code: 'SCANNER_VERSION_MISMATCH',
         message: `The scanner reported protocol version ${payload.scannerVersion}, but this extension understands version ${SUPPORTED_SCANNER_VERSION}.`,
       };
     }
-    return { ok: true, interpreter, payload };
+    return { ok: true, interpreter, interpreterOrigin: origin, payload };
   } catch {
     return {
       ok: false,
       interpreter,
+      interpreterOrigin: origin,
       code: 'SCANNER_INVALID_OUTPUT',
       message: 'The project scanner did not return valid JSON.',
       stderr: run.stdout.slice(0, 2000),

package/src/validation/bundle.ts

@@ -1,8 +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;
 }
 
 export interface ValidationSummary {
@@ -13,10 +21,18 @@ 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
@@ -25,27 +41,45 @@ export interface ValidationSummary {
  * 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: {
   lock: ValidationStep;
   sync: ValidationStep;
   test: ValidationStep;
+  /** Declared lint/type commands; omitted when the project declares none. */
+  quality?: ValidationStep[];
   conformance: 'consistent' | 'drifted' | 'unverifiable';
   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.lock.executed || !input.sync.executed || !input.test.executed) {
-    reason = 'Set execute=true to run the validation bundle.';
+  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') {
@@ -54,12 +88,15 @@ export function summarizeValidation(input: {
   } 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.';
   }
   return {
-    ok: lock && sync && test && conformance && !staleArtifacts,
+    ok: lock && sync && test && conformance && quality && !staleArtifacts,
     reason,
-    checks: { lock, sync, test, conformance, staleArtifacts },
+    checks: { lock, sync, test, conformance, quality, staleArtifacts },
   };
 }

package/src/validation/tdd.ts

@@ -1,38 +1,91 @@
 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
-    .toLowerCase()
-    .replace(/\.py$/, '')
-    .split(/[^a-z0-9]+/)
-    .filter((token) => token.length >= MIN_TOKEN_LENGTH);
+    .replace(/\.py$/i, '')
+    .split(/[^A-Za-z0-9]+/)
+    .map((token) => token.toLowerCase())
+    .filter((token) => token.length >= MIN_TOKEN_LENGTH && !PREFIX_TOKENS.has(token));
 }
 
-function related(source: string, test: string): boolean {
-  const testTokens = tokens(test).filter((token) => token !== 'test' && token !== 'tests');
-  return tokens(source).some((sourceToken) =>
-    testTokens.some(
-      (testToken) =>
-        sourceToken === testToken ||
-        sourceToken.startsWith(testToken) ||
-        testToken.startsWith(sourceToken),
-    ),
-  );
+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.
+ *
+ * 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.
+ */
+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)));
 }
 
 /**
  * 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.
+ * 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) =>
@@ -41,15 +94,33 @@ export function checkTdd(changedPaths: string[], testChangedPaths: string[] = []
   const sourceChanges = all.filter((path) => path.endsWith('.py') && !isTestFile(path));
   const testChanges = all.filter((path) => path.endsWith('.py') && isTestFile(path));
 
-  const hasRelatedTest =
-    testChanges.length > 0
-      ? sourceChanges.some((source) => testChanges.some((test) => related(source, test)))
-      : false;
+  // `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 && !hasRelatedTest) {
+  } else if (sourceChanges.length > 0 && associations.length === 0) {
     reasons.push('Changed test files do not appear related to the changed production modules.');
   }
 
@@ -58,5 +129,7 @@ export function checkTdd(changedPaths: string[], testChangedPaths: string[] = []
     reasons,
     sourceChanges,
     testChanges,
+    associations,
+    weakAssociation,
   };
 }