Read Python version from .tool-versions (#996)

## Summary
- read the Python version from an explicitly selected `.tool-versions`
file
- preserve `python-version` and existing `UV_PYTHON` precedence
- add parser, input, and workflow coverage and update documentation and
bundled action artifacts

## Validation
- `npm run all`
- `actionlint .github/workflows/test.yml`
- `uvx zizmor .github/workflows/test.yml`

Closes #983

Refs: pi-session 019ff01a-544c-79f3-8f73-a00132af39f5

src/utils/inputs.ts

@@ -1,5 +1,7 @@
+import fs from "node:fs";
 import path from "node:path";
 import * as core from "@actions/core";
+import { getPythonVersionFromToolVersions } from "../version/tool-versions-file";
 import { getConfigValueFromTomlFile } from "./config-file";
 import * as log from "./logging";
 
@@ -51,7 +53,7 @@ export function loadInputs(): SetupInputs {
   const workingDirectory = core.getInput("working-directory");
   const version = core.getInput("version");
   const versionFile = getVersionFile(workingDirectory);
-  const pythonVersion = core.getInput("python-version");
+  const pythonVersion = getPythonVersion(versionFile);
   const activateEnvironment = core.getBooleanInput("activate-environment");
   const noProject = core.getBooleanInput("no-project");
   const venvPath = getVenvPath(workingDirectory, activateEnvironment);
@@ -122,6 +124,28 @@ function getVersionFile(workingDirectory: string): string {
   return versionFileInput;
 }
 
+function getPythonVersion(versionFile: string): string {
+  const pythonVersionInput = core.getInput("python-version");
+  if (pythonVersionInput !== "") {
+    return pythonVersionInput;
+  }
+  if (process.env.UV_PYTHON !== undefined && process.env.UV_PYTHON !== "") {
+    return "";
+  }
+  if (versionFile === "" || !fs.existsSync(versionFile)) {
+    return "";
+  }
+
+  try {
+    return getPythonVersionFromToolVersions(versionFile) ?? "";
+  } catch (err) {
+    log.warning(
+      `Error while parsing Python version from ${versionFile}: ${(err as Error).message}`,
+    );
+    return "";
+  }
+}
+
 function getVenvPath(
   workingDirectory: string,
   activateEnvironment: boolean,

src/version/tool-versions-file.ts

@@ -4,28 +4,72 @@ import * as core from "@actions/core";
 export function getUvVersionFromToolVersions(
   filePath: string,
 ): string | undefined {
+  const versions = getToolVersions(filePath, "uv");
+  if (versions === undefined || versions.length !== 1) {
+    return undefined;
+  }
+
+  const version = stripVersionPrefix(versions[0]);
+  if (version.startsWith("ref")) {
+    core.warning(
+      "The ref syntax of .tool-versions is not supported. Please use a released version instead.",
+    );
+    return undefined;
+  }
+  return version;
+}
+
+export function getPythonVersionFromToolVersions(
+  filePath: string,
+): string | undefined {
+  const versions = getToolVersions(filePath, "python");
+  if (versions === undefined || versions.length === 0) {
+    return undefined;
+  }
+  if (versions.length > 1) {
+    core.warning(
+      "Multiple Python versions in .tool-versions are not supported. The Python entry will be ignored.",
+    );
+    return undefined;
+  }
+
+  const version = stripVersionPrefix(versions[0]);
+  if (
+    version === "system" ||
+    version.startsWith("ref:") ||
+    version.startsWith("path:")
+  ) {
+    core.warning(
+      `The Python version ${versions[0]} in .tool-versions is not supported. The Python entry will be ignored.`,
+    );
+    return undefined;
+  }
+  return version;
+}
+
+function getToolVersions(
+  filePath: string,
+  toolName: string,
+): string[] | undefined {
   if (!filePath.endsWith(".tool-versions")) {
     return undefined;
   }
   const fileContents = fs.readFileSync(filePath, "utf8");
-  const lines = fileContents.split("\n");
 
-  for (const line of lines) {
-    // Skip commented lines
-    if (line.trim().startsWith("#")) {
+  for (const line of fileContents.split("\n")) {
+    const content = line.split("#", 1)[0].trim();
+    if (content === "") {
       continue;
     }
-    const match = line.match(/^\s*uv\s*v?\s*(?<version>[^\s]+)\s*$/);
-    if (match) {
-      const matchedVersion = match.groups?.version.trim();
-      if (matchedVersion?.startsWith("ref")) {
-        core.warning(
-          "The ref syntax of .tool-versions is not supported. Please use a released version instead.",
-        );
-        return undefined;
-      }
-      return matchedVersion;
+
+    const [tool, ...versions] = content.split(/\s+/);
+    if (tool === toolName) {
+      return versions;
     }
   }
   return undefined;
 }
+
+function stripVersionPrefix(version: string): string {
+  return version.startsWith("v") ? version.slice(1) : version;
+}