docs(python): add comments to marker evaluator and provider integration

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ruromero

src/providers/marker_evaluator.js

@@ -1,3 +1,8 @@
+// PEP 508 environment marker evaluator.
+// Filters Python dependencies by platform/version markers so that e.g.
+// "pywin32 ; sys_platform == 'win32'" is excluded on Linux/macOS.
+// See https://peps.python.org/pep-0508/#environment-markers
+
 import { execSync } from 'node:child_process'
 import os from 'node:os'
 
@@ -15,7 +20,11 @@ function getPythonVersion() {
 	return cachedPythonVersion
 }
 
-/** @returns {Record<string, string>} */
+/**
+ * Maps Node.js/OS values to PEP 508 marker variables.
+ * Example: on Linux, sys_platform='linux', platform_system='Linux', os_name='posix'
+ * @returns {Record<string, string>}
+ */
 export function getEnvironmentMarkers() {
 	let platform = process.platform
 	let systemMap = { win32: 'Windows', linux: 'Linux', darwin: 'Darwin' }
@@ -47,6 +56,9 @@ function compareVersions(left, right) {
 	return 0
 }
 
+// Evaluates a single comparison like sys_platform == 'win32' or python_version >= '3.8'.
+// Version-bearing variables (python_version, python_full_version) use numeric comparison;
+// all others use string equality. Returns false when the env value is missing.
 function evaluateComparison(variable, op, value, env) {
 	let envVal = env[variable]
 	if (envVal === undefined || envVal === '') {
@@ -82,17 +94,26 @@ function evaluateComparison(variable, op, value, env) {
 	}
 }
 
+// Parses a single marker comparison into {variable, op, value}.
+// Handles both normal and reversed forms:
+//   "sys_platform == 'linux'"  → { variable: 'sys_platform', op: '==', value: 'linux' }
+//   "'linux' == sys_platform"  → { variable: 'sys_platform', op: '==', value: 'linux' }
 function parseAtom(expr) {
+	// Normal form: variable op 'value'
 	let m = expr.match(/^\s*([\w.]+)\s*(~=|!=|==|>=|<=|>|<|not\s+in|in)\s*["']([^"']*)["']\s*$/)
 	if (m) { return { variable: m[1], op: m[2].replace(/\s+/g, ' '), value: m[3] } }
 
+	// Reversed form: 'value' op variable
 	let mReverse = expr.match(/^\s*["']([^"']*)['"]\s*(~=|!=|==|>=|<=|>|<|not\s+in|in)\s*([\w.]+)\s*$/)
 	if (mReverse) { return { variable: mReverse[3], op: mReverse[2].replace(/\s+/g, ' '), value: mReverse[1] } }
 
 	return null
 }
 
 /**
+ * Evaluates a full PEP 508 marker expression against the current platform.
+ * Example: "sys_platform == 'win32' and python_version >= '3.8'" → false on Linux
+ * Empty/missing markers return true (unconditional dependency).
  * @param {string} markerExpr
  * @returns {boolean}
  */
@@ -124,6 +145,10 @@ function evaluateExpr(expr, env) {
 	return evaluateComparison(atom.variable, atom.op, atom.value, env)
 }
 
+// Splits an expression by " and " or " or " at the top level, skipping
+// separators inside parentheses or quoted strings.
+// Example: splitLogical("a == 'x' and (b == 'y' or c == 'z')", " and ")
+//        → ["a == 'x'", "(b == 'y' or c == 'z')"]
 function splitLogical(expr, sep) {
 	let parts = []
 	let depth = 0

src/providers/python_poetry.js

@@ -113,6 +113,12 @@ export default class Python_poetry extends Base_pyproject {
 	}
 
 	/**
+	 * Collects PEP 508 marker expressions for direct and transitive deps.
+	 * Direct markers come from pyproject.toml dependency strings, e.g.:
+	 *   "pywin32>=311 ; sys_platform == 'win32'"  → directMarkers['pywin32'] = "sys_platform == 'win32'"
+	 * Transitive markers come from poetry.lock [package.dependencies] entries, e.g.:
+	 *   colorama = {version = "*", markers = "sys_platform == 'win32'"}
+	 *   → transitiveMarkers['click']['colorama'] = "sys_platform == 'win32'"
 	 * @param {string|null} lockDir
 	 * @param {object} parsed - parsed pyproject.toml
 	 * @returns {{directMarkers: Map<string, string>, transitiveMarkers: Map<string, Map<string, string>>}}
@@ -121,6 +127,7 @@ export default class Python_poetry extends Base_pyproject {
 		let directMarkers = new Map()
 		let transitiveMarkers = new Map()
 
+		// Extract markers from PEP 621 dependency strings: "name[extras]>=ver ; marker"
 		let deps = parsed.project?.dependencies || []
 		for (let dep of deps) {
 			let m = dep.match(/^([A-Za-z0-9][A-Za-z0-9._-]*)\s*[^;]*;\s*(.+)$/)

src/providers/python_uv.js

@@ -99,6 +99,7 @@ export default class Python_uv extends Base_pyproject {
 				let nameNode = child.children.find(c => c.type === 'package')
 				if (!nameNode) { continue }
 
+				// Skip packages with non-matching PEP 508 markers, e.g. "pywin32==311 ; sys_platform == 'win32'"
 				let markerNode = child.children.find(c => c.type === 'marker_spec')
 				if (markerNode) {
 					let markerText = markerNode.text.replace(/^\s*;\s*/, '')