pi-python-helper 0.1.1 → 0.3.0

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