pi-python-helper 0.1.0

package/src/project/installed.ts

@@ -0,0 +1,225 @@
+import { open, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/** Marker files Python seeds into a fresh virtual environment. */
+const BOOTSTRAP_DISTRIBUTIONS = new Set([
+  'pip',
+  'setuptools',
+  'wheel',
+  'virtualenv',
+  'distribute',
+  'distlib',
+  'filelock',
+  'platformdirs',
+]);
+
+/**
+ * Only the header block of `METADATA` is needed, and some distributions ship a
+ * multi-megabyte body (full README). Reading a bounded prefix keeps the scan
+ * proportional to the number of distributions rather than their size.
+ */
+const METADATA_HEADER_BYTES = 8192;
+const MAX_DISTRIBUTIONS = 5000;
+
+export interface InstalledDistribution {
+  name: string;
+  normalized: string;
+  version: string;
+  /** Directory name such as `httpx-0.28.1.dist-info`. */
+  distInfo: string;
+  /** `editable` when the distribution is a live link into the project tree. */
+  source: 'editable' | 'copy' | 'unknown';
+  /** True for interpreter-seeded packages such as pip, which no lock records. */
+  bootstrap: boolean;
+  /** Set when the version had to be recovered from the directory name. */
+  recoveredFromDirectory?: boolean;
+}
+
+export interface InstalledEnvironment {
+  sitePackages: string;
+  distributions: InstalledDistribution[];
+  count: number;
+  truncated: boolean;
+  warnings: string[];
+}
+
+const NORMALIZE_RE = /[-_.]+/g;
+
+export function normalizeDistributionName(name: string): string {
+  return name.replace(NORMALIZE_RE, '-').trim().toLowerCase();
+}
+
+/**
+ * Locate the `site-packages` directory of a virtual environment. POSIX and
+ * Windows layouts differ, and `lib64` is used on some distributions.
+ */
+export async function findSitePackages(venvDir: string): Promise<string | undefined> {
+  const isDirectory = async (path: string): Promise<boolean> => {
+    try {
+      return (await stat(path)).isDirectory();
+    } catch {
+      return false;
+    }
+  };
+
+  const directCandidates = [join(venvDir, 'Lib', 'site-packages')];
+  for (const candidate of directCandidates) {
+    if (await isDirectory(candidate)) return candidate;
+  }
+
+  for (const base of [join(venvDir, 'lib'), join(venvDir, 'lib64')]) {
+    let entries;
+    try {
+      entries = await readdir(base, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name === 'site-packages') return join(base, entry.name);
+      const candidate = join(base, entry.name, 'site-packages');
+      if (await isDirectory(candidate)) return candidate;
+    }
+  }
+  return undefined;
+}
+
+async function readMetadataHeaders(
+  path: string,
+): Promise<{ name?: string; version?: string } | undefined> {
+  let handle;
+  try {
+    handle = await open(path, 'r');
+    const buffer = Buffer.alloc(METADATA_HEADER_BYTES);
+    const { bytesRead } = await handle.read(buffer, 0, METADATA_HEADER_BYTES, 0);
+    const text = buffer.subarray(0, bytesRead).toString('utf8');
+    const headers: { name?: string; version?: string } = {};
+    for (const line of text.split(/\r?\n/)) {
+      if (line.length === 0) break; // the header block ends at the first blank line
+      const match = line.match(/^([A-Za-z0-9][A-Za-z0-9-]*):\s*(.*)$/);
+      if (!match) continue;
+      const key = match[1].toLowerCase();
+      if (key === 'name') headers.name = match[2].trim();
+      else if (key === 'version') headers.version = match[2].trim();
+      if (headers.name && headers.version) break;
+    }
+    return headers;
+  } catch {
+    return undefined;
+  } finally {
+    await handle?.close().catch(() => undefined);
+  }
+}
+
+/**
+ * Recover name and version from `<name>-<version>.dist-info`. The version is the
+ * final `-`-separated segment that begins with a digit, so names containing
+ * hyphens or underscores still parse.
+ */
+export function parseDistInfoDirectory(
+  directory: string,
+): { name: string; version: string } | undefined {
+  const stem = directory.replace(/\.dist-info$/i, '');
+  const match = stem.match(/^(.+?)-(\d[^-]*)$/);
+  if (!match) return undefined;
+  return { name: match[1], version: match[2] };
+}
+
+async function readDistributionSource(
+  distInfoPath: string,
+): Promise<'editable' | 'copy' | 'unknown'> {
+  let raw: string;
+  try {
+    const handle = await open(join(distInfoPath, 'direct_url.json'), 'r');
+    try {
+      const { size } = await handle.stat();
+      const buffer = Buffer.alloc(Math.min(size, 8192));
+      const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+      raw = buffer.subarray(0, bytesRead).toString('utf8');
+    } finally {
+      await handle.close().catch(() => undefined);
+    }
+  } catch {
+    // No direct_url.json: installed from an index, so it is a materialised copy.
+    return 'copy';
+  }
+  try {
+    const parsed = JSON.parse(raw) as { dir_info?: { editable?: boolean } };
+    return parsed.dir_info?.editable ? 'editable' : 'copy';
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Read the distributions installed in a virtual environment without running
+ * Python. `METADATA` carries the canonical name and version, and the
+ * `dist-info` directory name is used as a fallback so a single damaged
+ * distribution cannot hide the rest of the environment.
+ */
+export async function readInstalledDistributions(
+  venvDir: string,
+  options: { maxDistributions?: number } = {},
+): Promise<InstalledEnvironment | undefined> {
+  const limit = options.maxDistributions ?? MAX_DISTRIBUTIONS;
+  const sitePackages = await findSitePackages(venvDir);
+  if (!sitePackages) return undefined;
+
+  const warnings: string[] = [];
+  let entries;
+  try {
+    entries = await readdir(sitePackages, { withFileTypes: true });
+  } catch (error) {
+    return {
+      sitePackages,
+      distributions: [],
+      count: 0,
+      truncated: false,
+      warnings: [
+        `site-packages could not be read: ${error instanceof Error ? error.message : String(error)}`,
+      ],
+    };
+  }
+
+  const distInfos = entries
+    .filter((entry) => entry.isDirectory() && entry.name.endsWith('.dist-info'))
+    .map((entry) => entry.name)
+    .sort();
+
+  const truncated = distInfos.length > limit;
+  const selected = truncated ? distInfos.slice(0, limit) : distInfos;
+  if (truncated) {
+    warnings.push(`Only the first ${limit} of ${distInfos.length} distributions were inspected.`);
+  }
+
+  const distributions: InstalledDistribution[] = [];
+  for (const directory of selected) {
+    const distInfoPath = join(sitePackages, directory);
+    const headers = await readMetadataHeaders(join(distInfoPath, 'METADATA'));
+    const fallback = parseDistInfoDirectory(directory);
+    const rawName = headers?.name ?? fallback?.name;
+    const rawVersion = headers?.version ?? fallback?.version;
+    if (!rawName) {
+      warnings.push(`${directory} declares no distribution name and was skipped.`);
+      continue;
+    }
+    const normalized = normalizeDistributionName(rawName);
+    distributions.push({
+      name: rawName,
+      normalized,
+      version: rawVersion ?? '0',
+      distInfo: directory,
+      source: await readDistributionSource(distInfoPath),
+      bootstrap: BOOTSTRAP_DISTRIBUTIONS.has(normalized),
+      recoveredFromDirectory: headers?.version === undefined && fallback !== undefined,
+    });
+  }
+
+  return {
+    sitePackages,
+    distributions,
+    count: distributions.length,
+    truncated,
+    warnings,
+  };
+}

package/src/project/paths.ts

@@ -0,0 +1,74 @@
+import { basename } from 'node:path';
+
+export function toPosix(path: string): string {
+  return path.replace(/\\/g, '/');
+}
+
+export function isPythonFile(path: string): boolean {
+  return toPosix(path).endsWith('.py');
+}
+
+const TEST_DIRECTORY = /(^|\/)(tests?|testing)(\/|$)/i;
+const TEST_FILENAME = /(^|\/)(test_[^/]+|[^/]+_test)\.py$/i;
+
+/**
+ * pytest conventions only: a `tests/` directory, a `test_*.py` / `*_test.py`
+ * module, or a conftest. Everything else counts as production code.
+ */
+export function isTestFile(path: string): boolean {
+  const posix = toPosix(path);
+  if (basename(posix) === 'conftest.py') return true;
+  return TEST_DIRECTORY.test(posix) || TEST_FILENAME.test(posix);
+}
+
+export function isSourceFile(path: string): boolean {
+  return isPythonFile(path) && !isTestFile(path);
+}
+
+/** Directory that contains the file, without a trailing slash. */
+export function parentDir(path: string): string {
+  const posix = toPosix(path);
+  const index = posix.lastIndexOf('/');
+  return index === -1 ? '' : posix.slice(0, index);
+}
+
+/**
+ * Meaningful tokens of a path: directory and file stems, split on case
+ * boundaries and punctuation, with generic segments removed.
+ */
+const GENERIC = new Set([
+  'src',
+  'lib',
+  'app',
+  'apps',
+  'pkg',
+  'packages',
+  'python',
+  'test',
+  'tests',
+  'testing',
+  'unit',
+  'integration',
+  'py',
+  'init',
+  'main',
+  'demo',
+]);
+
+export function pathTokens(path: string): string[] {
+  return toPosix(path)
+    .replace(/\.py$/i, '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .split(/[^A-Za-z0-9]+/)
+    .map((token) => token.toLowerCase())
+    .filter((token) => token.length >= 3 && !GENERIC.has(token));
+}
+
+/** Importable top-level module a source path belongs to, when discoverable. */
+export function moduleNameFromPath(path: string): string | undefined {
+  const segments = toPosix(path).split('/');
+  const index = segments.lastIndexOf('src');
+  if (index !== -1 && segments.length > index + 2) return segments[index + 1];
+  if (segments.length > 1 && !isTestFile(path)) return segments[0];
+  return undefined;
+}

package/src/project/root.ts

@@ -0,0 +1,72 @@
+import { access, stat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+
+/** Files that mark the root of a uv-managed Python project. */
+const ROOT_MARKERS = ['pyproject.toml', 'uv.lock', 'setup.py', 'setup.cfg'];
+
+export async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export async function isFile(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve the project root from a directory. `pyproject.toml` and `uv.lock`
+ * win over the legacy markers, so a repository that contains a nested uv
+ * project still resolves to that nested project when the search starts inside
+ * it.
+ */
+export async function findProjectRoot(start: string): Promise<string | undefined> {
+  let current = resolve(start);
+  let fallback: string | undefined;
+  while (true) {
+    if (await isFile(join(current, 'pyproject.toml'))) return current;
+    if (await isFile(join(current, 'uv.lock'))) return current;
+    for (const marker of ROOT_MARKERS) {
+      if (await isFile(join(current, marker))) fallback ??= current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return fallback;
+    current = parent;
+  }
+}
+
+/** Locate the virtual environment uv would create for the project. */
+export async function findVenvDir(root: string): Promise<string | undefined> {
+  const candidate = join(root, '.venv');
+  return (await isDirectory(candidate)) ? candidate : undefined;
+}
+
+export async function isGitIgnored(root: string, entry: string): Promise<boolean | undefined> {
+  const gitignore = join(root, '.gitignore');
+  try {
+    const { readFile } = await import('node:fs/promises');
+    const content = await readFile(gitignore, 'utf8');
+    return content
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0 && !line.startsWith('#'))
+      .some((line) => line.replace(/^\//, '').replace(/\/$/, '') === entry);
+  } catch {
+    return undefined;
+  }
+}

package/src/project/scanner.ts

@@ -0,0 +1,243 @@
+import { runCommand } from '../core/runner.ts';
+
+export const HELPER_URL = new URL('../../helpers/scan_project.py', import.meta.url);
+
+/** Sections the scanner can produce. A comma-separated combination is allowed. */
+export type ScanMode =
+  | 'environment'
+  | 'manifest'
+  | 'imports'
+  | 'all'
+  | 'environment,manifest'
+  | 'environment,imports'
+  | 'manifest,imports';
+
+/** Bumped by the scanner when the request or result document changes shape. */
+export const SUPPORTED_SCANNER_VERSION = 1;
+
+export interface DeclaredDependency {
+  raw: string;
+  name: string;
+  normalized: string;
+  specifier: string;
+  extras: string[];
+  marker: string | null;
+}
+
+export interface ManifestSection {
+  pyprojectPath: string | null;
+  name: string | null;
+  version: string | null;
+  requiresPython: string | null;
+  description: string | null;
+  license: string | null;
+  importName?: string;
+  dependencies: DeclaredDependency[];
+  optionalDependencies: Record<string, DeclaredDependency[]>;
+  dependencyGroups: Record<string, DeclaredDependency[]>;
+  buildBackend: string | null;
+  buildRequires: string[];
+  entryPoints: string[];
+  toolConfiguration: Record<string, boolean>;
+  layout: 'src' | 'flat';
+  modules: string[];
+  legacySetupPy: boolean;
+  legacySetupCfg: boolean;
+  requirementsFiles: string[];
+  uvWorkspaceMembers: string[];
+  uvSources: string[];
+  warnings: string[];
+  tomlError?: string;
+}
+
+export interface LockDependencyEdge {
+  name: string;
+  normalized: string;
+  /** Non-null when uv only includes this dependency under a platform/version condition. */
+  marker: string | null;
+}
+
+export interface LockPackage {
+  name: string;
+  normalized: string;
+  version: string | null;
+  source: string | null;
+  dependencies?: LockDependencyEdge[];
+}
+
+export interface LockSection {
+  path: string | null;
+  present: boolean;
+  version: unknown;
+  revision: unknown;
+  requiresPython: string | null;
+  packages: LockPackage[];
+  warnings: string[];
+}
+
+export interface LockComparison {
+  specifierCheckAvailable: boolean;
+  missingFromLock: string[];
+  unsatisfiedInLock: { name: string; specifier: string; locked: string }[];
+  requiresPythonMismatch: { manifest: string; lock: string } | null;
+  checkedCount: number;
+}
+
+export interface ImportSection {
+  pythonVersion: string;
+  stdlibAvailable: boolean;
+  layout: 'src' | 'flat';
+  localModules: string[];
+  files: { path: string; imports: string[]; typeCheckingImports: string[] }[];
+  thirdParty: {
+    import: string;
+    files: string[];
+    fileCount: number;
+    providers: string[];
+    /** True when every importing file guards the import behind TYPE_CHECKING. */
+    typeCheckingOnly: boolean;
+    typeCheckingFiles: string[];
+  }[];
+  providersUnavailable: boolean;
+  unparsable: { path: string; error: string }[];
+  scannedFiles: number;
+  truncated: boolean;
+}
+
+export interface EnvironmentSection {
+  version: string;
+  versionInfo: number[];
+  executable: string;
+  prefix: string;
+  basePrefix: string;
+  inVirtualEnvironment: boolean;
+  virtualEnv: string | null;
+  condaPrefix: string | null;
+  candidateVenvDir: string | null;
+  implementation: string;
+  platform: string;
+  stdlibModuleNames: boolean;
+  tomlAvailable: boolean;
+}
+
+export interface ScanPayload {
+  scannerVersion?: number;
+  root: string;
+  mode: ScanMode;
+  pythonVersion: string;
+  tomlAvailable: boolean;
+  environment?: EnvironmentSection;
+  manifest?: ManifestSection;
+  lock?: LockSection;
+  lockComparison?: LockComparison;
+  imports?: ImportSection;
+  error?: string;
+}
+
+export interface ScanOutcome {
+  ok: boolean;
+  interpreter?: string;
+  payload?: ScanPayload;
+  /** Diagnostic code the caller can surface verbatim when `ok` is false. */
+  code?:
+    'PYTHON_NOT_FOUND' | 'SCANNER_FAILED' | 'SCANNER_INVALID_OUTPUT' | 'SCANNER_VERSION_MISMATCH';
+  message?: string;
+  stderr?: string;
+}
+
+let interpreterPromise: Promise<string | undefined> | 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.
+ */
+export async function resolveInterpreter(
+  cwd: string,
+  signal?: AbortSignal,
+): Promise<string | undefined> {
+  interpreterPromise ??= (async () => {
+    for (const candidate of ['python3', 'python']) {
+      const probe = await runCommand(candidate, ['-c', 'import sys; print(sys.version_info[0])'], {
+        cwd,
+        signal,
+        timeoutMs: 5000,
+        maxBytes: 2048,
+      });
+      if (probe.code === 0 && probe.stdout.trim() === '3') return candidate;
+    }
+    return undefined;
+  })();
+  return interpreterPromise;
+}
+
+/**
+ * Run the read-only scanner. A missing Python or an older interpreter without
+ * `tomllib` degrades to a structured diagnostic instead of throwing, so static
+ * tools remain usable in environments without Python tooling installed.
+ */
+export async function runScanProject(
+  cwd: string,
+  request: { root: string; mode: ScanMode; maxFiles?: number },
+  signal?: AbortSignal,
+): Promise<ScanOutcome> {
+  const interpreter = await resolveInterpreter(cwd, signal);
+  if (!interpreter) {
+    return {
+      ok: false,
+      code: 'PYTHON_NOT_FOUND',
+      message: 'No Python 3 interpreter was found on PATH.',
+    };
+  }
+  const helper = HELPER_URL.pathname;
+  const run = await runCommand(interpreter, [helper], {
+    cwd,
+    signal,
+    timeoutMs: 30000,
+    maxBytes: 2 * 1024 * 1024,
+    stdin: JSON.stringify(request),
+  });
+  if (run.timedOut) {
+    return {
+      ok: false,
+      interpreter,
+      code: 'SCANNER_FAILED',
+      message: 'The project scanner timed out.',
+    };
+  }
+  if (run.code !== 0) {
+    return {
+      ok: false,
+      interpreter,
+      code: 'SCANNER_FAILED',
+      message: 'The project scanner exited with an error.',
+      stderr: run.stderr.trim() || undefined,
+    };
+  }
+  try {
+    const payload = JSON.parse(run.stdout) as ScanPayload;
+    if (payload.error) {
+      return { ok: false, interpreter, code: 'SCANNER_FAILED', message: payload.error };
+    }
+    // Refuse to interpret a document whose shape may have changed.
+    if (
+      typeof payload.scannerVersion === 'number' &&
+      payload.scannerVersion !== SUPPORTED_SCANNER_VERSION
+    ) {
+      return {
+        ok: false,
+        interpreter,
+        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 };
+  } catch {
+    return {
+      ok: false,
+      interpreter,
+      code: 'SCANNER_INVALID_OUTPUT',
+      message: 'The project scanner did not return valid JSON.',
+      stderr: run.stdout.slice(0, 2000),
+    };
+  }
+}

package/src/validation/bundle.ts

@@ -0,0 +1,65 @@
+export interface ValidationStep {
+  executed: boolean;
+  ok: boolean;
+  exitCode?: number | null;
+  failures?: number;
+}
+
+export interface ValidationSummary {
+  ok: boolean;
+  reason: string;
+  checks: {
+    lock: boolean;
+    sync: boolean;
+    test: boolean;
+    conformance: boolean;
+    staleArtifacts: boolean;
+  };
+}
+
+/**
+ * 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.
+ */
+export function summarizeValidation(input: {
+  lock: ValidationStep;
+  sync: ValidationStep;
+  test: ValidationStep;
+  conformance: 'consistent' | 'drifted' | 'unverifiable';
+  stale: 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 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.';
+  } 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 (!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 (staleArtifacts) {
+    reason = 'Tests passed, but a stale coverage report was detected; refresh it and rerun.';
+  }
+  return {
+    ok: lock && sync && test && conformance && !staleArtifacts,
+    reason,
+    checks: { lock, sync, test, conformance, staleArtifacts },
+  };
+}