feat: implement scanForPythonVersions function and tests for discovering Python version matches across various files

Author: CasperKristiansson

docs/tasks.md

@@ -117,7 +117,7 @@ Use Context7 MCP for up to date documentation.
         Patterns for workflows, Dockerfiles, `.python-version`, `.tool-versions`, `runtime.txt`, `tox.ini`, `pyproject.toml`, `Pipfile`, `environment.yml`.
         Verify: Positive/negative unit tests per pattern.
 
-12. [ ] **Scanner module**
+12. [x] **Scanner module**
         Collect matches with file, position, `X.Y.Z`, `X.Y`.
         Verify: Snapshot test over fixture repo.
 

src/scanning/index.ts

@@ -1,3 +1,6 @@
 export { discoverFiles } from './glob-discovery';
 export { findPythonVersionMatches, pythonVersionPatterns } from './patterns/python-version';
 export type { VersionMatch } from './patterns/python-version';
+
+export { scanForPythonVersions } from './scanner';
+export type { ScanOptions, ScanResult } from './scanner';

src/scanning/patterns/python-version.ts

@@ -27,7 +27,9 @@ export const pythonVersionPatterns: PatternDefinition[] = [
       const isYaml = normalized.endsWith('.yml') || normalized.endsWith('.yaml');
       return isWorkflowFile && isYaml;
     },
-    regexes: [new RegExp(`python-version\\s*:\\s*["]?(?<version>${VERSION_PATTERN})["]?`, 'gi')],
+    regexes: [
+      new RegExp(String.raw`python-version\s*:\s*['"]?(?<version>${VERSION_PATTERN})['"]?`, 'gi'),
+    ],
   },
   {
     id: 'dockerfile-from',
@@ -36,7 +38,7 @@ export const pythonVersionPatterns: PatternDefinition[] = [
     regexes: [
       new RegExp(`FROM\\s+[^\\s]*python[^\\s:]*:(?<version>${VERSION_PATTERN})`, 'gi'),
       new RegExp(
-        `\\b(?:ARG|ENV)\\s+PYTHON[_-]?VERSION\\s*=\\s*["]?(?<version>${VERSION_PATTERN})["]?`,
+        String.raw`\b(?:ARG|ENV)\s+PYTHON[_-]?VERSION\s*=\s*['"]?(?<version>${VERSION_PATTERN})['"]?`,
         'gi',
       ),
     ],

src/scanning/scanner.ts

@@ -0,0 +1,79 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { discoverFiles } from './glob-discovery';
+import { findPythonVersionMatches, type VersionMatch } from './patterns/python-version';
+
+export interface ScanOptions {
+  /** Absolute root directory to scan. */
+  root: string;
+  /** Glob patterns to include relative to the root. */
+  patterns: string[];
+  /** Additional ignore patterns. */
+  ignore?: string[];
+  /** Follow symbolic links. Defaults to false. */
+  followSymbolicLinks?: boolean;
+}
+
+export interface ScanResult {
+  filesScanned: number;
+  matches: VersionMatch[];
+}
+
+async function readFileSafe(filePath: string): Promise<string | null> {
+  try {
+    return await readFile(filePath, 'utf8');
+  } catch (error) {
+    const err = error as { code?: string };
+    if (err && err.code === 'ENOENT') {
+      return null;
+    }
+    throw error;
+  }
+}
+
+export async function scanForPythonVersions(options: ScanOptions): Promise<ScanResult> {
+  const { root, patterns, ignore, followSymbolicLinks } = options;
+  const relativeFiles = await discoverFiles({
+    root,
+    patterns,
+    ignore,
+    followSymbolicLinks,
+  });
+
+  const matches: VersionMatch[] = [];
+  let filesScanned = 0;
+
+  for (const relative of relativeFiles) {
+    const absolute = path.join(root, relative);
+    const content = await readFileSafe(absolute);
+    if (content === null) {
+      continue;
+    }
+
+    filesScanned += 1;
+    const fileMatches = findPythonVersionMatches(relative, content);
+    matches.push(
+      ...fileMatches.map((match) => ({
+        ...match,
+        file: relative,
+      })),
+    );
+  }
+
+  matches.sort((a, b) => {
+    const fileCompare = a.file.localeCompare(b.file);
+    if (fileCompare !== 0) {
+      return fileCompare;
+    }
+    if (a.line !== b.line) {
+      return a.line - b.line;
+    }
+    if (a.column !== b.column) {
+      return a.column - b.column;
+    }
+    return 0;
+  });
+
+  return { filesScanned, matches };
+}

tests/fixtures/scanner/.github/workflows/ci.yml

@@ -0,0 +1,6 @@
+jobs:
+  test:
+    steps:
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.12.2'

tests/fixtures/scanner/.python-version

@@ -0,0 +1 @@
+3.10.12

tests/fixtures/scanner/.tool-versions

@@ -0,0 +1,2 @@
+python 3.9.18
+nodejs 20.12.2

tests/fixtures/scanner/Dockerfile

@@ -0,0 +1,2 @@
+FROM python:3.13.4-slim
+ARG PYTHON_VERSION="3.8.19"

tests/fixtures/scanner/environment.yml

@@ -0,0 +1,2 @@
+dependencies:
+  - python=3.12.1

tests/fixtures/scanner/pyproject.toml

@@ -0,0 +1,5 @@
+requires-python = ">=3.7"
+python = "==3.7.17"
+
+[tool.pyright]
+pythonVersion = "3.7.17"