pi-python-helper 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -7,6 +7,15 @@ does not guarantee a stable public tool schema.
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-09-21
+
+### Changed
+
+- Refactored `src/dependencies/plan.ts` by extracting static import aliases and console-only distribution tables into `src/dependencies/aliases.ts`.
+- Refactored `src/build/failure.ts` by extracting Python and pytest traceback frame parsing and library frame detection into `src/build/traceback.ts`.
+- Decomposed monolithic `inspectProject` in `src/project/inspect.ts` into focused diagnostic collectors for manifest, lockfile, and environment rules.
+- Moved `py_tdd_checkpoint` and `py_completion_evidence` tools from `extensions/tools/dependencies.ts` to `extensions/tools/validation.ts` to align tool registration with module responsibilities.
+
 ## [0.1.0] - 2026-09-21
 
 ### Added

package/extensions/tools/dependencies.ts

@@ -1,9 +1,6 @@
 import { Type } from 'typebox';
 import { failure, result } from '../../src/core/result.ts';
-import { runCommand } from '../../src/core/runner.ts';
 import { planDependencies } from '../../src/dependencies/plan.ts';
-import { buildCompletionEvidence } from '../../src/validation/evidence.ts';
-import { checkTdd } from '../../src/validation/tdd.ts';
 import { messageOf, resolveProjectRoot, text, type Pi } from '../shared.ts';
 import { runScanProject } from '../../src/project/scanner.ts';
 
@@ -83,121 +80,4 @@ export function registerDependencyTools(pi: Pi): void {
       }
     },
   });
-
-  pi.registerTool({
-    name: 'py_tdd_checkpoint',
-    label: 'Python TDD Checkpoint',
-    description:
-      'Check whether production Python changes have related test changes before implementation is considered complete. Read-only.',
-    promptSnippet: 'Check the Python TDD checkpoint for changed files',
-    promptGuidelines: [
-      'Use py_tdd_checkpoint before reporting Python implementation work as complete.',
-    ],
-    parameters: Type.Object({
-      changedPaths: Type.Optional(Type.Array(Type.String(), { maxItems: 500 })),
-      testChangedPaths: Type.Optional(Type.Array(Type.String(), { maxItems: 500 })),
-    }),
-    async execute(_id, params, signal, _update, ctx) {
-      const started = Date.now();
-      let changedPaths = params.changedPaths ?? [];
-      let source = 'argument';
-      if (!changedPaths.length) {
-        const diff = await runCommand('git', ['diff', '--name-only', 'HEAD'], {
-          cwd: ctx.cwd,
-          signal,
-          timeoutMs: 10000,
-          maxBytes: 100_000,
-        });
-        changedPaths = diff.stdout
-          .split(/\r?\n/)
-          .map((line) => line.trim())
-          .filter(Boolean);
-        source = 'git diff';
-      }
-      const checkpoint = checkTdd(changedPaths, params.testChangedPaths ?? changedPaths);
-      return text(
-        result(ctx.cwd, started, {
-          ok: checkpoint.ok,
-          summary: checkpoint.ok
-            ? `TDD checkpoint passed across ${changedPaths.length} changed path(s) from ${source}.`
-            : 'TDD checkpoint found production changes without a related test change.',
-          data: { ...checkpoint, changedPaths, source },
-          evidence: checkpoint.reasons.map((message) => ({ kind: 'tdd_blocker', message })),
-          warnings: checkpoint.reasons.map((message) => ({
-            code: 'TDD_CHECKPOINT',
-            message,
-            severity: 'warning' as const,
-          })),
-          errors: [],
-          suggestions: checkpoint.ok
-            ? []
-            : [
-                {
-                  message:
-                    'Add the smallest focused test for the changed behaviour, or explain why the change needs no test.',
-                  confidence: 'high' as const,
-                },
-              ],
-        }),
-      );
-    },
-  });
-
-  pi.registerTool({
-    name: 'py_completion_evidence',
-    label: 'Python Completion Evidence',
-    description:
-      'Build a conservative completion report from environment sync and test execution results. Read-only.',
-    promptSnippet: 'Create evidence for a Python completion report',
-    promptGuidelines: [
-      'Use py_completion_evidence before claiming Python work is complete; a partial run is not evidence.',
-    ],
-    parameters: Type.Object({
-      syncExecuted: Type.Boolean({
-        description: 'Whether uv lock --check / uv sync actually ran.',
-      }),
-      syncOk: Type.Boolean(),
-      testExecuted: Type.Boolean({ description: 'Whether pytest actually ran.' }),
-      testOk: Type.Boolean(),
-      stale: Type.Boolean({ description: 'Whether stale artifacts were detected.' }),
-      changedPaths: Type.Array(Type.String(), { maxItems: 500 }),
-    }),
-    async execute(_id, params, _signal, _update, ctx) {
-      const started = Date.now();
-      const evidence = buildCompletionEvidence(params);
-      return text(
-        result(ctx.cwd, started, {
-          ok: evidence.ok,
-          summary: evidence.ok
-            ? 'Completion evidence is sufficient for the supplied checks.'
-            : 'Completion evidence is incomplete or contains failing checks.',
-          data: evidence,
-          evidence: evidence.blockers.map((message) => ({ kind: 'completion_blocker', message })),
-          warnings: evidence.blockers.map((message) => ({
-            code: 'INCOMPLETE_EVIDENCE',
-            message,
-            severity: 'warning' as const,
-          })),
-          errors: evidence.ok
-            ? []
-            : [
-                {
-                  code: 'COMPLETION_NOT_PROVEN',
-                  message: 'The supplied evidence does not prove completion.',
-                  severity: 'error' as const,
-                },
-              ],
-          suggestions: evidence.ok
-            ? []
-            : [
-                {
-                  message:
-                    'Run py_validation_bundle and address every blocker before reporting completion.',
-                  confidence: 'high' as const,
-                },
-              ],
-        }),
-      );
-    },
-  });
 }

package/extensions/tools/validation.ts

@@ -11,6 +11,8 @@ import {
 } from '../../src/project/conformance.ts';
 import { readInstalledDistributions } from '../../src/project/installed.ts';
 import { summarizeValidation, type ValidationStep } from '../../src/validation/bundle.ts';
+import { buildCompletionEvidence } from '../../src/validation/evidence.ts';
+import { checkTdd } from '../../src/validation/tdd.ts';
 import { join } from 'node:path';
 import { isFile } from '../../src/project/root.ts';
 import { runScanProject } from '../../src/project/scanner.ts';
@@ -341,4 +343,121 @@ export function registerValidationTools(pi: Pi): void {
       }
     },
   });
+
+  pi.registerTool({
+    name: 'py_tdd_checkpoint',
+    label: 'Python TDD Checkpoint',
+    description:
+      'Check whether production Python changes have related test changes before implementation is considered complete. Read-only.',
+    promptSnippet: 'Check the Python TDD checkpoint for changed files',
+    promptGuidelines: [
+      'Use py_tdd_checkpoint before reporting Python implementation work as complete.',
+    ],
+    parameters: Type.Object({
+      changedPaths: Type.Optional(Type.Array(Type.String(), { maxItems: 500 })),
+      testChangedPaths: Type.Optional(Type.Array(Type.String(), { maxItems: 500 })),
+    }),
+    async execute(_id, params, signal, _update, ctx) {
+      const started = Date.now();
+      let changedPaths = params.changedPaths ?? [];
+      let source = 'argument';
+      if (!changedPaths.length) {
+        const diff = await runCommand('git', ['diff', '--name-only', 'HEAD'], {
+          cwd: ctx.cwd,
+          signal,
+          timeoutMs: 10000,
+          maxBytes: 100_000,
+        });
+        changedPaths = diff.stdout
+          .split(/\r?\n/)
+          .map((line) => line.trim())
+          .filter(Boolean);
+        source = 'git diff';
+      }
+      const checkpoint = checkTdd(changedPaths, params.testChangedPaths ?? changedPaths);
+      return text(
+        result(ctx.cwd, started, {
+          ok: checkpoint.ok,
+          summary: checkpoint.ok
+            ? `TDD checkpoint passed across ${changedPaths.length} changed path(s) from ${source}.`
+            : 'TDD checkpoint found production changes without a related test change.',
+          data: { ...checkpoint, changedPaths, source },
+          evidence: checkpoint.reasons.map((message) => ({ kind: 'tdd_blocker', message })),
+          warnings: checkpoint.reasons.map((message) => ({
+            code: 'TDD_CHECKPOINT',
+            message,
+            severity: 'warning' as const,
+          })),
+          errors: [],
+          suggestions: checkpoint.ok
+            ? []
+            : [
+                {
+                  message:
+                    'Add the smallest focused test for the changed behaviour, or explain why the change needs no test.',
+                  confidence: 'high' as const,
+                },
+              ],
+        }),
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: 'py_completion_evidence',
+    label: 'Python Completion Evidence',
+    description:
+      'Build a conservative completion report from environment sync and test execution results. Read-only.',
+    promptSnippet: 'Create evidence for a Python completion report',
+    promptGuidelines: [
+      'Use py_completion_evidence before claiming Python work is complete; a partial run is not evidence.',
+    ],
+    parameters: Type.Object({
+      syncExecuted: Type.Boolean({
+        description: 'Whether uv lock --check / uv sync actually ran.',
+      }),
+      syncOk: Type.Boolean(),
+      testExecuted: Type.Boolean({ description: 'Whether pytest actually ran.' }),
+      testOk: Type.Boolean(),
+      stale: Type.Boolean({ description: 'Whether stale artifacts were detected.' }),
+      changedPaths: Type.Array(Type.String(), { maxItems: 500 }),
+    }),
+    async execute(_id, params, _signal, _update, ctx) {
+      const started = Date.now();
+      const evidence = buildCompletionEvidence(params);
+      return text(
+        result(ctx.cwd, started, {
+          ok: evidence.ok,
+          summary: evidence.ok
+            ? 'Completion evidence is sufficient for the supplied checks.'
+            : 'Completion evidence is incomplete or contains failing checks.',
+          data: evidence,
+          evidence: evidence.blockers.map((message) => ({ kind: 'completion_blocker', message })),
+          warnings: evidence.blockers.map((message) => ({
+            code: 'INCOMPLETE_EVIDENCE',
+            message,
+            severity: 'warning' as const,
+          })),
+          errors: evidence.ok
+            ? []
+            : [
+                {
+                  code: 'COMPLETION_NOT_PROVEN',
+                  message: 'The supplied evidence does not prove completion.',
+                  severity: 'error' as const,
+                },
+              ],
+          suggestions: evidence.ok
+            ? []
+            : [
+                {
+                  message:
+                    'Run py_validation_bundle and address every blocker before reporting completion.',
+                  confidence: 'high' as const,
+                },
+              ],
+        }),
+      );
+    },
+  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-python-helper",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Python (uv) development tools for the pi coding agent",
   "type": "module",
   "keywords": [

package/src/build/failure.ts

@@ -15,13 +15,13 @@ export type FailureKind =
   | 'timeout'
   | 'unknown';
 
-export interface TracebackFrame {
-  path: string;
-  line: number;
-  func: string;
-  /** True for site-packages, the standard library, and pytest internals. */
-  library: boolean;
-}
+import {
+  extractTracebackFrames,
+  firstUserFrame,
+  isLibraryFrame,
+  type TracebackFrame,
+} from './traceback.ts';
+export { extractTracebackFrames, firstUserFrame, isLibraryFrame, type TracebackFrame };
 
 export interface FailureEvidence {
   file?: string;
@@ -42,54 +42,6 @@ export interface FailureDiagnosis {
   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);

package/src/build/traceback.ts

@@ -0,0 +1,55 @@
+export interface TracebackFrame {
+  path: string;
+  line: number;
+  func: string;
+  /** True for site-packages, the standard library, and pytest internals. */
+  library: boolean;
+}
+
+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;
+}
+
+export 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;
+}

package/src/dependencies/aliases.ts

@@ -0,0 +1,101 @@
+/**
+ * Import name and distribution name frequently disagree. The scanner supplies
+ * the authoritative mapping when the analysing interpreter has the package
+ * installed; this table covers the cases where it does not, so an uninstalled
+ * checkout is still analysed correctly.
+ */
+export const IMPORT_ALIASES: Record<string, string[]> = {
+  PIL: ['pillow'],
+  yaml: ['pyyaml'],
+  dateutil: ['python-dateutil'],
+  bs4: ['beautifulsoup4'],
+  cv2: ['opencv-python', 'opencv-python-headless'],
+  sklearn: ['scikit-learn'],
+  skimage: ['scikit-image'],
+  dotenv: ['python-dotenv'],
+  attr: ['attrs'],
+  attrs: ['attrs'],
+  jwt: ['pyjwt'],
+  jose: ['python-jose'],
+  serial: ['pyserial'],
+  OpenSSL: ['pyopenssl'],
+  Crypto: ['pycryptodome'],
+  pkg_resources: ['setuptools'],
+  MySQLdb: ['mysqlclient'],
+  googleapiclient: ['google-api-python-client'],
+  github: ['PyGithub'],
+  pytest_cov: ['pytest-cov'],
+  _pytest: ['pytest'],
+  pytest_asyncio: ['pytest-asyncio'],
+  psycopg: ['psycopg', 'psycopg-binary'],
+  psycopg2: ['psycopg2', 'psycopg2-binary'],
+  prometheus_client: ['prometheus-client'],
+  grpc: ['grpcio'],
+  kafka: ['kafka-python'],
+  docker: ['docker'],
+  numpy: ['numpy'],
+  pandas: ['pandas'],
+  ruamel: ['ruamel.yaml'],
+  setuptools: ['setuptools'],
+  mako: ['Mako'],
+  pytz: ['pytz'],
+  tzlocal: ['tzlocal'],
+  win32com: ['pywin32'],
+  lxml: ['lxml'],
+  matplotlib: ['matplotlib'],
+  seaborn: ['seaborn'],
+  sqlalchemy: ['sqlalchemy', 'SQLAlchemy'],
+  pydantic: ['pydantic'],
+  fastapi: ['fastapi'],
+  starlette: ['starlette'],
+  uvicorn: ['uvicorn'],
+  celery: ['celery'],
+  redis: ['redis'],
+  boto3: ['boto3'],
+  botocore: ['botocore'],
+  httpx: ['httpx'],
+  aiohttp: ['aiohttp'],
+  werkzeug: ['werkzeug'],
+  flask: ['flask'],
+  django: ['django'],
+  jinja2: ['jinja2'],
+  typer: ['typer'],
+  click: ['click'],
+  rich: ['rich'],
+  tqdm: ['tqdm'],
+};
+
+/** Distributions that are normally invoked as a console script, not imported. */
+export const CONSOLE_ONLY: Set<string> = new Set([
+  'ruff',
+  'mypy',
+  'pyright',
+  'ty',
+  'pytest',
+  'pytest-cov',
+  'coverage',
+  'pre-commit',
+  'tox',
+  'nox',
+  'hatch',
+  'hatchling',
+  'build',
+  'twine',
+  'black',
+  'isort',
+  'flake8',
+  'pylint',
+  'sphinx',
+  'mkdocs',
+  'uvicorn',
+  'gunicorn',
+  'alembic',
+  'celery',
+  'honcho',
+  'maturin',
+  'setuptools-scm',
+  'pip-audit',
+  'bandit',
+  'commitizen',
+  'towncrier',
+]);

package/src/dependencies/plan.ts

@@ -3,109 +3,8 @@ import { warn } from '../core/result.ts';
 import { isTestFile } from '../project/paths.ts';
 import type { DeclaredDependency, ScanPayload } from '../project/scanner.ts';
 
-/**
- * Import name and distribution name frequently disagree. The scanner supplies
- * the authoritative mapping when the analysing interpreter has the package
- * installed; this table covers the cases where it does not, so an uninstalled
- * checkout is still analysed correctly.
- */
-export const IMPORT_ALIASES: Record<string, string[]> = {
-  PIL: ['pillow'],
-  yaml: ['pyyaml'],
-  dateutil: ['python-dateutil'],
-  bs4: ['beautifulsoup4'],
-  cv2: ['opencv-python', 'opencv-python-headless'],
-  sklearn: ['scikit-learn'],
-  skimage: ['scikit-image'],
-  dotenv: ['python-dotenv'],
-  attr: ['attrs'],
-  attrs: ['attrs'],
-  jwt: ['pyjwt'],
-  jose: ['python-jose'],
-  serial: ['pyserial'],
-  OpenSSL: ['pyopenssl'],
-  Crypto: ['pycryptodome'],
-  pkg_resources: ['setuptools'],
-  MySQLdb: ['mysqlclient'],
-  googleapiclient: ['google-api-python-client'],
-  github: ['PyGithub'],
-  pytest_cov: ['pytest-cov'],
-  _pytest: ['pytest'],
-  pytest_asyncio: ['pytest-asyncio'],
-  psycopg: ['psycopg', 'psycopg-binary'],
-  psycopg2: ['psycopg2', 'psycopg2-binary'],
-  prometheus_client: ['prometheus-client'],
-  grpc: ['grpcio'],
-  kafka: ['kafka-python'],
-  docker: ['docker'],
-  numpy: ['numpy'],
-  pandas: ['pandas'],
-  ruamel: ['ruamel.yaml'],
-  setuptools: ['setuptools'],
-  mako: ['Mako'],
-  pytz: ['pytz'],
-  tzlocal: ['tzlocal'],
-  win32com: ['pywin32'],
-  lxml: ['lxml'],
-  matplotlib: ['matplotlib'],
-  seaborn: ['seaborn'],
-  sqlalchemy: ['sqlalchemy', 'SQLAlchemy'],
-  pydantic: ['pydantic'],
-  fastapi: ['fastapi'],
-  starlette: ['starlette'],
-  uvicorn: ['uvicorn'],
-  celery: ['celery'],
-  redis: ['redis'],
-  boto3: ['boto3'],
-  botocore: ['botocore'],
-  httpx: ['httpx'],
-  aiohttp: ['aiohttp'],
-  werkzeug: ['werkzeug'],
-  flask: ['flask'],
-  django: ['django'],
-  jinja2: ['jinja2'],
-  typer: ['typer'],
-  click: ['click'],
-  rich: ['rich'],
-  tqdm: ['tqdm'],
-};
-
-/** Distributions that are normally invoked as a console script, not imported. */
-const CONSOLE_ONLY = new Set(
-  [
-    'ruff',
-    'mypy',
-    'pyright',
-    'ty',
-    'pytest',
-    'pytest-cov',
-    'coverage',
-    'pre-commit',
-    'tox',
-    'nox',
-    'hatch',
-    'hatchling',
-    'build',
-    'twine',
-    'black',
-    'isort',
-    'flake8',
-    'pylint',
-    'sphinx',
-    'mkdocs',
-    'uvicorn',
-    'gunicorn',
-    'alembic',
-    'celery',
-    'honcho',
-    'maturin',
-    'setuptools-scm',
-    'pip-audit',
-    'bandit',
-    'commitizen',
-    'towncrier',
-  ].map((name) => name),
-);
+import { CONSOLE_ONLY, IMPORT_ALIASES } from './aliases.ts';
+export { CONSOLE_ONLY, IMPORT_ALIASES };
 
 const NORMALIZE_RE = /[-_.]+/g;
 

package/src/project/inspect.ts

@@ -5,7 +5,7 @@ import {
   type ConformanceReport,
 } from './conformance.ts';
 import type { InstalledEnvironment } from './installed.ts';
-import type { ScanPayload } from './scanner.ts';
+import type { LockComparison, LockSection, ManifestSection, ScanPayload } from './scanner.ts';
 
 export interface ProjectInspection {
   root: string;
@@ -48,60 +48,56 @@ export interface InspectInput {
   installed?: InstalledEnvironment;
 }
 
-/**
- * Turn a scanner payload into a project model plus diagnostics. Pure so the
- * whole diagnostic surface is unit-testable without touching a filesystem.
- */
-export function inspectProject(input: InspectInput): ProjectInspection {
-  const { payload, venvDir, venvIgnored, hasTestsDirectory, installed } = input;
-  const manifest = payload.manifest;
-  const lock = payload.lock;
-  const comparison = payload.lockComparison;
-  const warnings: Diagnostic[] = [];
-  const notes: Diagnostic[] = [];
-  const suggestions: Suggestion[] = [];
+interface DiagnosticCollector {
+  warnings: Diagnostic[];
+  notes: Diagnostic[];
+  suggestions: Suggestion[];
+}
 
-  const root = payload.root;
+function collectManifestDiagnostics(
+  manifest: ManifestSection | null | undefined,
+  root: string,
+  collector: DiagnosticCollector,
+): void {
   if (manifest?.tomlError) {
-    warnings.push(
+    collector.warnings.push(
       warn('TOML_PARSE_ERROR', manifest.tomlError, manifest.pyprojectPath ?? undefined),
     );
   }
   for (const message of manifest?.warnings ?? []) {
-    warnings.push(warn('MANIFEST_WARNING', message, manifest?.pyprojectPath ?? undefined));
-  }
-  for (const message of lock?.warnings ?? []) {
-    notes.push({ code: 'LOCKFILE_NOTE', message, severity: 'info' });
+    collector.warnings.push(
+      warn('MANIFEST_WARNING', message, manifest?.pyprojectPath ?? undefined),
+    );
   }
 
   if (!manifest?.pyprojectPath) {
-    warnings.push(
+    collector.warnings.push(
       warn(
         'PYPROJECT_MISSING',
         'pyproject.toml was not found; dependencies, layout, and tool configuration cannot be verified.',
       ),
     );
-    suggestions.push({
+    collector.suggestions.push({
       message: 'Run uv init to create a pyproject.toml, then uv add the runtime dependencies.',
       confidence: 'high',
       command: 'uv init',
     });
   } else if (!manifest.name) {
-    warnings.push(
+    collector.warnings.push(
       warn(
         'PROJECT_NAME_MISSING',
         'pyproject.toml has no [project] name, so the installed distribution name is unknown.',
         manifest.pyprojectPath ?? undefined,
       ),
     );
-    suggestions.push({
+    collector.suggestions.push({
       message: 'Add a [project] table with name and version to pyproject.toml.',
       confidence: 'high',
     });
   }
 
   if (manifest?.legacySetupPy || manifest?.legacySetupCfg) {
-    warnings.push(
+    collector.warnings.push(
       warn(
         'LEGACY_PACKAGING',
         `The project still uses ${[
@@ -113,14 +109,14 @@ export function inspectProject(input: InspectInput): ProjectInspection {
         root,
       ),
     );
-    suggestions.push({
+    collector.suggestions.push({
       message: 'Move dependency metadata from setup.py/setup.cfg into [project] in pyproject.toml.',
       confidence: 'medium',
     });
   }
 
   if (manifest?.requirementsFiles.length && manifest.pyprojectPath) {
-    warnings.push(
+    collector.warnings.push(
       warn(
         'DUPLICATE_DEPENDENCY_SOURCE',
         `${manifest.requirementsFiles.join(', ')} also declares dependencies; uv resolves from pyproject.toml and uv.lock only.`,
@@ -129,14 +125,31 @@ export function inspectProject(input: InspectInput): ProjectInspection {
     );
   }
 
+  if (manifest?.legacySetupPy && manifest.buildBackend === null && !manifest.pyprojectPath) {
+    collector.suggestions.push({
+      message: 'uv manages dependencies from pyproject.toml; migrate before running uv sync.',
+      confidence: 'medium',
+    });
+  }
+}
+
+function collectLockDiagnostics(
+  lock: LockSection | null | undefined,
+  comparison: LockComparison | null | undefined,
+  collector: DiagnosticCollector,
+): void {
+  for (const message of lock?.warnings ?? []) {
+    collector.notes.push({ code: 'LOCKFILE_NOTE', message, severity: 'info' });
+  }
+
   if (!lock?.present) {
-    notes.push({
+    collector.notes.push({
       code: 'LOCKFILE_MISSING',
       message:
         'uv.lock was not found, so dependency drift and exact resolved versions cannot be verified.',
       severity: 'info',
     });
-    suggestions.push({
+    collector.suggestions.push({
       message: 'Run uv lock to record resolved versions in uv.lock.',
       confidence: 'high',
       command: 'uv lock',
@@ -144,14 +157,14 @@ export function inspectProject(input: InspectInput): ProjectInspection {
   }
 
   if (comparison?.requiresPythonMismatch) {
-    warnings.push(
+    collector.warnings.push(
       warn(
         'REQUIRES_PYTHON_MISMATCH',
         `pyproject.toml requires-python is "${comparison.requiresPythonMismatch.manifest}" but uv.lock records "${comparison.requiresPythonMismatch.lock}".`,
         lock?.path ?? undefined,
       ),
     );
-    suggestions.push({
+    collector.suggestions.push({
       message: 'Run uv lock so the lockfile reflects the current requires-python constraint.',
       confidence: 'high',
       command: 'uv lock',
@@ -159,7 +172,7 @@ export function inspectProject(input: InspectInput): ProjectInspection {
   }
 
   for (const name of comparison?.missingFromLock ?? []) {
-    warnings.push(
+    collector.warnings.push(
       warn(
         'LOCKFILE_MISSING_DEPENDENCY',
         `"${name}" is declared in pyproject.toml but absent from uv.lock.`,
@@ -168,7 +181,7 @@ export function inspectProject(input: InspectInput): ProjectInspection {
     );
   }
   if (comparison?.missingFromLock.length) {
-    suggestions.push({
+    collector.suggestions.push({
       message: 'Run uv lock to add the missing declarations to the lockfile.',
       confidence: 'high',
       command: 'uv lock',
@@ -176,7 +189,7 @@ export function inspectProject(input: InspectInput): ProjectInspection {
   }
 
   for (const entry of comparison?.unsatisfiedInLock ?? []) {
-    warnings.push(
+    collector.warnings.push(
       warn(
         'LOCKFILE_UNSATISFIED_DEPENDENCY',
         `"${entry.name}" is locked at ${entry.locked} which does not satisfy "${entry.specifier}".`,
@@ -186,42 +199,51 @@ export function inspectProject(input: InspectInput): ProjectInspection {
   }
 
   if (lock?.present && comparison && !comparison.specifierCheckAvailable) {
-    notes.push({
+    collector.notes.push({
       code: 'SPECIFIER_CHECK_UNAVAILABLE',
       message:
         'The packaging library was unavailable, so only declared-versus-locked names were compared, not version constraints.',
       severity: 'info',
     });
-    suggestions.push({
+    collector.suggestions.push({
       message:
         'Install the packaging library in the analysing interpreter to compare declared version constraints against uv.lock.',
       confidence: 'medium',
       command: 'python3 -m pip install packaging',
     });
   }
+}
 
+function collectEnvironmentDiagnostics(
+  root: string,
+  manifest: ManifestSection | null | undefined,
+  venvDir: string | undefined,
+  venvIgnored: boolean | undefined,
+  hasTestsDirectory: boolean,
+  collector: DiagnosticCollector,
+): void {
   if (!venvDir) {
-    notes.push({
+    collector.notes.push({
       code: 'VENV_MISSING',
       message: 'No .venv directory exists at the project root; run uv sync before running tests.',
       severity: 'info',
     });
   } else if (venvIgnored === false) {
-    warnings.push(
+    collector.warnings.push(
       warn(
         'VENV_NOT_IGNORED',
         '.venv exists but is not listed in .gitignore.',
         `${root}/.gitignore`,
       ),
     );
-    suggestions.push({
+    collector.suggestions.push({
       message: 'Add .venv/ to .gitignore so the environment is never committed.',
       confidence: 'high',
     });
   }
 
   if (!hasTestsDirectory) {
-    notes.push({
+    collector.notes.push({
       code: 'TESTS_DIRECTORY_MISSING',
       message:
         'No tests/ directory was found; test selection and TDD gates cannot match changed sources.',
@@ -230,7 +252,7 @@ export function inspectProject(input: InspectInput): ProjectInspection {
   }
 
   if (manifest?.pyprojectPath && manifest.toolConfiguration && !manifest.toolConfiguration.pytest) {
-    notes.push({
+    collector.notes.push({
       code: 'PYTEST_NOT_CONFIGURED',
       message: 'pyproject.toml has no [tool.pytest.ini_options] table.',
       severity: 'info',
@@ -238,7 +260,7 @@ export function inspectProject(input: InspectInput): ProjectInspection {
   }
 
   if (manifest?.layout === 'src' && manifest.modules.length === 0) {
-    warnings.push(
+    collector.warnings.push(
       warn(
         'EMPTY_SRC_LAYOUT',
         'The src/ directory exists but contains no importable module directories or modules.',
@@ -247,20 +269,32 @@ export function inspectProject(input: InspectInput): ProjectInspection {
     );
   }
 
-  if (manifest?.legacySetupPy && manifest.buildBackend === null && !manifest.pyprojectPath) {
-    suggestions.push({
-      message: 'uv manages dependencies from pyproject.toml; migrate before running uv sync.',
-      confidence: 'medium',
-    });
-  }
-
   if (manifest?.uvWorkspaceMembers.length) {
-    notes.push({
+    collector.notes.push({
       code: 'UV_WORKSPACE',
       message: `This is a uv workspace with ${manifest.uvWorkspaceMembers.length} member(s); scope build and test tools per member.`,
       severity: 'info',
     });
   }
+}
+
+/**
+ * Turn a scanner payload into a project model plus diagnostics. Pure so the
+ * whole diagnostic surface is unit-testable without touching a filesystem.
+ */
+export function inspectProject(input: InspectInput): ProjectInspection {
+  const { payload, venvDir, venvIgnored, hasTestsDirectory, installed } = input;
+  const manifest = payload.manifest;
+  const lock = payload.lock;
+  const comparison = payload.lockComparison;
+  const root = payload.root;
+
+  const collector: DiagnosticCollector = { warnings: [], notes: [], suggestions: [] };
+  collectManifestDiagnostics(manifest, root, collector);
+  collectLockDiagnostics(lock, comparison, collector);
+  collectEnvironmentDiagnostics(root, manifest, venvDir, venvIgnored, hasTestsDirectory, collector);
+
+  const { warnings, notes, suggestions } = collector;
 
   const conformance =
     installed !== undefined