Add satisfies command

Author: edvilme

src/common/inlineScript/metadata.ts

@@ -5,7 +5,7 @@ import * as tomljs from '@iarna/toml';
 import * as fs from 'fs/promises';
 import { Uri } from 'vscode';
 import { traceVerbose, traceWarn } from '../logging';
-import { compareReleaseSegments, parseReleaseSegments } from '../utils/pep440Release';
+import { PythonVersion } from '../pythonVersion';
 
 /**
  * Parsed and validated PEP 723 `script` metadata block.
@@ -304,101 +304,15 @@ export function matchesPythonVersion(requiresPython: string, version: string): b
     if (!requiresPython || !version) {
         return false;
     }
-    const clauses = requiresPython
-        .split(',')
-        .map((c) => c.trim())
-        .filter((c) => c.length > 0);
-    if (clauses.length === 0) {
+    const parsedVersion = PythonVersion.tryParse(version);
+    if (!parsedVersion) {
+        traceWarn(`inline script metadata: cannot parse Python version: ${JSON.stringify(version)}`);
         return false;
     }
-    for (const clause of clauses) {
-        if (!matchSingleClause(clause, version)) {
-            return false;
-        }
-    }
-    return true;
-}
-
-// Longest-match-first order matters: `===` must beat `==`, `~=` and
-// `>=` / `<=` / `!=` must beat the single-char operators.
-const SPECIFIER_RE = /^(===|~=|==|!=|>=|<=|>|<)\s*(.+)$/;
-
-function matchSingleClause(clause: string, version: string): boolean {
-    const m = clause.match(SPECIFIER_RE);
-    if (!m) {
-        traceWarn(`inline script metadata: unrecognized requires-python clause: ${JSON.stringify(clause)}`);
-        return false;
-    }
-    const op = m[1];
-    const specVersion = m[2].trim();
-
-    if (op === '===') {
-        // Arbitrary-equality: exact string comparison after stripping
-        // a leading 'v' (which PEP 440 permits).
-        const normSpec = specVersion.replace(/^v/i, '');
-        const normVer = version.replace(/^v/i, '');
-        return normSpec === normVer;
-    }
-
-    if (specVersion.endsWith('.*')) {
-        if (op !== '==' && op !== '!=') {
-            traceWarn(
-                `inline script metadata: wildcard versions are only valid with '==' or '!=': ${JSON.stringify(clause)}`,
-            );
-            return false;
-        }
-        const prefix = parseReleaseSegments(specVersion.slice(0, -2));
-        const ver = parseReleaseSegments(version);
-        if (prefix === undefined || ver === undefined) {
-            traceWarn(`inline script metadata: cannot parse version for clause ${JSON.stringify(clause)}`);
-            return false;
-        }
-        const isPrefixMatch = ver.length >= prefix.length && prefix.every((seg, i) => ver[i] === seg);
-        return op === '==' ? isPrefixMatch : !isPrefixMatch;
-    }
-
-    const specSegs = parseReleaseSegments(specVersion);
-    const verSegs = parseReleaseSegments(version);
-    if (specSegs === undefined || verSegs === undefined) {
-        traceWarn(`inline script metadata: cannot parse version for clause ${JSON.stringify(clause)}`);
+    const result = parsedVersion.matchSpecifier(requiresPython);
+    if (result === undefined) {
+        traceWarn(`inline script metadata: invalid requires-python specifier: ${JSON.stringify(requiresPython)}`);
         return false;
     }
-
-    const cmp = compareReleaseSegments(verSegs, specSegs);
-    switch (op) {
-        case '==':
-            return cmp === 0;
-        case '!=':
-            return cmp !== 0;
-        case '>=':
-            return cmp >= 0;
-        case '<=':
-            return cmp <= 0;
-        case '>':
-            return cmp > 0;
-        case '<':
-            return cmp < 0;
-        case '~=': {
-            // Compatible release. `~=X.Y` is equivalent to
-            // `>= X.Y, == X.*`; `~=X.Y.Z` is `>= X.Y.Z, == X.Y.*`.
-            // PEP 440 requires at least two release segments here.
-            if (specSegs.length < 2) {
-                traceWarn(
-                    `inline script metadata: '~=' requires at least two release segments: ${JSON.stringify(clause)}`,
-                );
-                return false;
-            }
-            if (cmp < 0) {
-                return false;
-            }
-            const prefix = specSegs.slice(0, -1);
-            if (verSegs.length < prefix.length) {
-                return false;
-            }
-            return prefix.every((seg, i) => verSegs[i] === seg);
-        }
-        default:
-            // Unreachable — SPECIFIER_RE only matches the operators above.
-            return false;
-    }
+    return result;
 }

src/common/pythonVersion.ts

@@ -1,4 +1,9 @@
 type PythonReleaseLevel = 'alpha' | 'beta' | 'candidate' | 'final';
+type ComparisonOperator = '~=' | '==' | '!=' | '>=' | '<=' | '>' | '<';
+type ParsedClause =
+    | { readonly operator: '==='; readonly expected: string }
+    | { readonly operator: '==' | '!='; readonly wildcard: readonly number[] }
+    | { readonly operator: ComparisonOperator; readonly expected: PythonVersion };
 
 export class PythonVersion {
     private static readonly VERSION_PATTERN =
@@ -43,12 +48,15 @@ export class PythonVersion {
         }
 
         this.original = normalizedVersion;
-    this.releaseComponentCount = match[3] !== undefined ? 3 : match[2] !== undefined ? 2 : 1;
+        this.releaseComponentCount = match[3] !== undefined ? 3 : match[2] !== undefined ? 2 : 1;
         this.major = parseNumericComponent(match[1], version);
         this.minor = parseNumericComponent(match[2], version);
         this.patch = parseNumericComponent(match[3], version);
         this.releaseLevel = PythonVersion.normalizeReleaseLevel(match[4] ?? match[6]);
         this.releaseSerial = parseNumericComponent(match[5] ?? match[7], version);
+        if (this.releaseLevel === 'final' && this.releaseSerial !== 0) {
+            throw new TypeError(`Invalid Python version: ${version}`);
+        }
     }
 
     readonly major: number;
@@ -86,9 +94,7 @@ export class PythonVersion {
      */
     compareTo(other: PythonVersion): number {
         return (
-            compareNumbers(this.major, other.major) ||
-            compareNumbers(this.minor, other.minor) ||
-            compareNumbers(this.patch, other.patch) ||
+            this.compareReleaseTo(other) ||
             compareNumbers(
                 PythonVersion.RELEASE_LEVEL_ORDER[this.releaseLevel],
                 PythonVersion.RELEASE_LEVEL_ORDER[other.releaseLevel],
@@ -120,15 +126,18 @@ export class PythonVersion {
      * @returns `true` when every clause matches; otherwise `false`.
      */
     satisfies(specifier: unknown): boolean {
-        if (typeof specifier !== 'string') {
-            return false;
-        }
+        return this.matchSpecifier(specifier) ?? false;
+    }
 
-        const clauses = specifier
-            .split(',')
-            .map((clause) => clause.trim())
-            .filter((clause) => clause.length > 0);
-        return clauses.length > 0 && clauses.every((clause) => this.satisfiesClause(clause));
+    /**
+     * Evaluates a Python version specifier while distinguishing invalid syntax.
+     *
+     * @param specifier The specifier to evaluate.
+     * @returns Whether this version matches, or `undefined` for an invalid specifier.
+     */
+    matchSpecifier(specifier: unknown): boolean | undefined {
+        const clauses = PythonVersion.parseSpecifier(specifier);
+        return clauses?.every((clause) => this.satisfiesClause(clause));
     }
 
     /** Returns the normalized Python version representation. */
@@ -150,37 +159,57 @@ export class PythonVersion {
         return value ? (PythonVersion.RELEASE_LEVEL_ALIASES[value.toLowerCase()] ?? 'final') : 'final';
     }
 
-    private satisfiesClause(clause: string): boolean {
+    private static parseSpecifier(specifier: unknown): readonly ParsedClause[] | undefined {
+        if (typeof specifier !== 'string') {
+            return undefined;
+        }
+
+        const clauses = specifier
+            .split(',')
+            .map((clause) => clause.trim())
+            .filter((clause) => clause.length > 0);
+        if (clauses.length === 0) {
+            return undefined;
+        }
+
+        const parsed = clauses.map((clause) => PythonVersion.parseClause(clause));
+        return parsed.every((clause): clause is ParsedClause => clause !== undefined) ? parsed : undefined;
+    }
+
+    private static parseClause(clause: string): ParsedClause | undefined {
         const match = PythonVersion.SPECIFIER_PATTERN.exec(clause);
         if (!match) {
-            return false;
+            return undefined;
         }
 
         const operator = match[1];
         const expected = match[2].trim();
         if (operator === '===') {
-            return this.original.replace(/^v/i, '') === expected.replace(/^v/i, '');
+            return expected.length > 0 ? { operator, expected } : undefined;
         }
-
         if (expected.endsWith('.*')) {
-            if (operator !== '==' && operator !== '!=') {
-                return false;
-            }
-            const expectedComponents = PythonVersion.parseWildcard(expected);
-            if (!expectedComponents) {
-                return false;
-            }
-            const matches = this.matchesReleaseComponents(expectedComponents);
-            return operator === '==' ? matches : !matches;
+            const wildcard = PythonVersion.parseWildcard(expected);
+            return (operator === '==' || operator === '!=') && wildcard ? { operator, wildcard } : undefined;
         }
 
         const expectedVersion = PythonVersion.tryParse(expected);
-        if (!expectedVersion) {
-            return false;
+        if (!expectedVersion || (operator === '~=' && expectedVersion.releaseComponentCount < 2)) {
+            return undefined;
+        }
+        return { operator: operator as ComparisonOperator, expected: expectedVersion };
+    }
+
+    private satisfiesClause(clause: ParsedClause): boolean {
+        if (clause.operator === '===') {
+            return this.original.replace(/^v/i, '') === clause.expected.replace(/^v/i, '');
+        }
+        if ('wildcard' in clause) {
+            const matches = this.matchesReleaseComponents(clause.wildcard);
+            return clause.operator === '==' ? matches : !matches;
         }
 
-        const comparison = this.compareReleaseTo(expectedVersion);
-        switch (operator) {
+        const comparison = this.compareReleaseTo(clause.expected);
+        switch (clause.operator) {
             case '==':
                 return comparison === 0;
             case '!=':
@@ -195,10 +224,9 @@ export class PythonVersion {
                 return comparison < 0;
             case '~=':
                 return (
-                    expectedVersion.releaseComponentCount >= 2 &&
                     comparison >= 0 &&
                     this.matchesReleaseComponents(
-                        expectedVersion.releaseComponents.slice(0, expectedVersion.releaseComponentCount - 1),
+                        clause.expected.releaseComponents.slice(0, clause.expected.releaseComponentCount - 1),
                     )
                 );
             default:

src/test/common/inlineScript/metadata.unit.test.ts

@@ -467,6 +467,12 @@ suite('inlineScriptMetadata', () => {
             assert.strictEqual(matchesPythonVersion('>=3.11', '3.10.0rc1'), false);
         });
 
+        test('supports normalized interpreter version formats', () => {
+            assert.strictEqual(matchesPythonVersion('>=3.14', '3.14.3.final.0'), true);
+            assert.strictEqual(matchesPythonVersion('==3.14.*', '3.14.0b1'), true);
+            assert.strictEqual(matchesPythonVersion('<3.14', '3.14.0b1'), false);
+        });
+
         test('invalid specifier returns false and logs warn', () => {
             assert.strictEqual(matchesPythonVersion('weird-thing', '3.11'), false);
             assert.ok(traceWarnStub.called);

src/test/common/pythonVersion.unit.test.ts

@@ -98,8 +98,22 @@ suite('PythonVersion', () => {
         assert.strictEqual(version.satisfies(undefined), false);
     });
 
+    test('distinguishes invalid specifiers from valid non-matches', () => {
+        const version = new PythonVersion('3.12.4');
+
+        assert.strictEqual(version.matchSpecifier('>=3.13'), false);
+        assert.strictEqual(version.matchSpecifier('>=3.12.*'), undefined);
+    });
+
     test('rejects versions that cannot be compared safely', () => {
-        for (const version of ['', '3.', '3.12.1.4', 'Python 3.12', `${Number.MAX_SAFE_INTEGER}0.1.0`]) {
+        for (const version of [
+            '',
+            '3.',
+            '3.12.1.4',
+            '3.12.1.final.1',
+            'Python 3.12',
+            `${Number.MAX_SAFE_INTEGER}0.1.0`,
+        ]) {
             assert.throws(() => new PythonVersion(version), TypeError);
         }
     });