@uknows/setup 0.0.0-stage → 0.2.0

package/lib/stacks/python-lock.mjs

@@ -0,0 +1,105 @@
+/*
+ * The lock refresh of uv and Poetry projects (uv lock in the workspace root, poetry lock), shared by the Python and
+ * the Azure Monitor appliers. The tool on this computer writes the lock, and the image reads it, so the run stops
+ * with a required step when:
+ *   - the lock is above the --path folder (the command would write outside it),
+ *   - the tool is missing (the engine probed it: ctx.tools[tool] === null),
+ *   - it does not meet [tool.uv] required-version (or uv.toml), [tool.poetry] requires-poetry, or the version that
+ *     the Dockerfile pins (COPY --from=ghcr.io/astral-sh/uv:0.11.29, pip install uv==X, the astral.sh/uv/<version>/install.sh
+ *     installer with ENV UV_VERSION, POETRY_VERSION).
+ * After the run, the engine rolls back when the lockfile format line changed (keep): version = N in uv.lock,
+ * lock-version in poetry.lock. An older tool in the image cannot read a newer format.
+ */
+import { posix } from 'node:path'
+import { RESOLVE } from '../contract.mjs'
+import { parseDockerfile } from '../dockerfile.mjs'
+import { tomlString, tomlTable } from '../toml.mjs'
+import { satisfies } from '../versions.mjs'
+
+/** Lockfile name -> tool. PDM has no automatic refresh. */
+export const LOCK_TOOLS = { 'uv.lock': 'uv', 'poetry.lock': 'poetry' }
+const KEEP = { 'uv.lock': '^version = \\d+$', 'poetry.lock': '^lock-version = "[^"]*"$' }
+const fill = (text, values) => text.replace(/\{(\w+)\}/g, (m, key) => (key in values ? String(values[key]) : m))
+const read = (view, path) => { try { return view.read(path) } catch { return null } }
+const at = (dir, name) => (dir === '.' ? name : `${dir}/${name}`)
+
+/**
+ * The lock command for lockFile, or the required step that replaces it.
+ * @param {{view: any, lockFile: string, tools?: Record<string, string|null>, dockerfile?: string|null, docker?: string|null, packages: string}} opts
+ *   packages: what the lock adds, for the required step ('the OpenTelemetry packages').
+ * @returns {{command: import('../types.mjs').Command}|{block: import('../types.mjs').Block}|null}  null for a lockfile with no tool (pdm.lock).
+ */
+export function lockStep({ view, lockFile, tools, dockerfile = null, docker = null, packages }) {
+  const name = posix.basename(lockFile), tool = LOCK_TOOLS[name]
+  if (!tool) return null
+  const dir = posix.dirname(lockFile)
+  const version = tools && Object.prototype.hasOwnProperty.call(tools, tool) ? tools[tool] : undefined
+  const poetry1 = tool === 'poetry' && /^1\./.test(version ?? '')
+  const args = poetry1 ? ['lock', '--no-update'] : ['lock']
+  const command = [tool, ...args].join(' ')
+  if (lockFile.startsWith('../')) {
+    return { block: { title: RESOLVE.outside.title, lines: RESOLVE.outside.lines.map((l) => fill(l, { lock: lockFile, command, dir })) } }
+  }
+  const needs = toolNeeds(view, dir, tool, dockerfile, docker)
+  const pinned = needs.find((n) => n.exact)
+  const block = (reason) => ({ title: fill(RESOLVE.tool.title, { tool, version: pinned ? ` ${pinned.version}` : '' }),
+    lines: [fill(RESOLVE.tool.why, { lock: lockFile, tool, packages }), reason,
+      fill(RESOLVE.tool.install, { tool, version: pinned ? ` ${pinned.version}` : '' }), RESOLVE.again] })
+  if (version === null) return { block: block(fill(RESOLVE.tool.missing, { tool })) }
+  if (version) {
+    const unmet = needs.find((n) => !satisfies(version, n.spec))
+    if (unmet) {
+      return { block: block(fill(unmet.line ? RESOLVE.tool.image : RESOLVE.tool.version,
+        { file: unmet.file, line: unmet.line, tool, need: unmet.version ?? unmet.spec, have: version })) }
+    }
+  }
+  return { command: { cwd: dir, cmd: tool, args, touches: [lockFile], added: [], kind: 'lock', undo: null,
+    keep: [{ file: lockFile, pattern: KEEP[name] }], why: fill(RESOLVE.update, { lock: name, command }) } }
+}
+
+/**
+ * The versions of the tool that the project asks for: required-version (uv) or requires-poetry in the pyproject.toml
+ * next to the lock, uv.toml, and the version the Dockerfile installs. exact: a pinned image or package version.
+ * @returns {{spec: string, version?: string, file: string, line?: number, exact: boolean}[]}
+ */
+export function toolNeeds(view, dir, tool, dockerfile, docker) {
+  const out = []
+  const pyproject = read(view, at(dir, 'pyproject.toml'))
+  if (tool === 'uv') {
+    const spec = tomlString(tomlTable(pyproject ?? '', 'tool.uv'), 'required-version')
+    if (spec) out.push({ spec, file: at(dir, 'pyproject.toml'), exact: false })
+    const own = tomlString(read(view, at(dir, 'uv.toml')) ?? '', 'required-version')
+    if (own) out.push({ spec: own, file: at(dir, 'uv.toml'), exact: false })
+  } else {
+    const spec = tomlString(tomlTable(pyproject ?? '', 'tool.poetry'), 'requires-poetry')
+    if (spec) out.push({ spec, file: at(dir, 'pyproject.toml'), exact: false })
+  }
+  if (docker && dockerfile) {
+    const image = tool === 'uv' ? /\bghcr\.io\/astral-sh\/uv:(\d+(?:\.\d+){0,2})(?=[\s@-]|$)/ : null
+    const pip = new RegExp(`\\bpip3?\\s+install\\b[^\\n&|;]*?["']?\\b${tool}==(\\d+(?:\\.\\d+){1,2})\\b`)
+    const env = tool === 'poetry' ? /\bPOETRY_VERSION=["']?(\d+(?:\.\d+){1,2})\b/ : null
+    // The versioned installer script: astral.sh/uv/0.11.29/install.sh, or astral.sh/uv/${UV_VERSION}/install.sh with an
+    // ENV or ARG UV_VERSION line before it.
+    const script = tool === 'uv' ? /astral\.sh\/uv\/(?:\$\{?UV_VERSION\}?|(\d+(?:\.\d+){1,2}))\/install\.sh/ : null
+    const instructions = parseDockerfile(docker).instructions
+    const uvVersion = (upTo) => instructions.slice(0, upTo).filter((y) => y.keyword === 'ENV' || y.keyword === 'ARG')
+      .map((y) => ({ y, m: /\bUV_VERSION=["']?(\d+(?:\.\d+){1,2})\b/.exec(y.args) })).filter((e) => e.m).at(-1) ?? null
+    for (const [k, x] of instructions.entries()) {
+      const text = x.argv ? x.argv.join(' ') : x.args
+      let m = (image && (x.keyword === 'FROM' || x.keyword === 'COPY') && image.exec(text)) || (x.keyword === 'RUN' && pip.exec(text))
+        || (env && (x.keyword === 'ENV' || x.keyword === 'ARG') && env.exec(text))
+      let at = x
+      const run = !m && script && x.keyword === 'RUN' ? script.exec(text) : null
+      if (run) {
+        const found = run[1] ? null : uvVersion(k)
+        m = run[1] ? run : found?.m ?? null
+        at = found?.y ?? x
+      }
+      if (!m) continue
+      const v = m[1]
+      out.push({ spec: v.split('.').length < 3 ? `==${v}.*` : `==${v}`, version: v, file: dockerfile, line: at.start + 1, exact: true })
+      break
+    }
+  }
+  return out
+}

package/lib/stacks/python-sets.mjs

@@ -0,0 +1,143 @@
+/*
+ * Which OpenTelemetry set (PINS.python.sets, newest first) a Python app gets. The first set that fits the direct
+ * limits of the app (protobuf and opentelemetry-* in its dependency files) and its Python version wins. pip apps get
+ * exact pins from that set. uv and Poetry apps get floors, and the set only decides which instrumentation packages
+ * exist for them (bootstrap SINCE). The plan says why when it is not the newest set.
+ */
+import { PINS, RESOLVE } from '../contract.mjs'
+import { tomlArray, tomlEntries, tomlTable } from '../toml.mjs'
+import { clauses, compareVersion, lowestRelease, overlaps, satisfies } from '../versions.mjs'
+import { normalize } from './python-bootstrap.mjs'
+
+/** opentelemetry-* packages on the core release line (1.x), and on the contrib line (0.xb). Other names are ignored. */
+const CORE = /^opentelemetry-(?:api|sdk|proto|exporter-otlp(?:-proto-(?:http|grpc|common))?)$/
+const CONTRIB = /^opentelemetry-(?:distro|instrumentation(?:-[\w-]+)?|semantic-conventions|util-http)$/
+const fill = (text, values) => text.replace(/\{(\w+)\}/g, (m, key) => (key in values ? String(values[key]) : m))
+const read = (ws, path) => { try { return ws.read(path) } catch { return null } }
+
+/**
+ * @typedef {{name: string, spec: string, style: 'python'|'poetry', file: string, line: number, value: string}} Limit
+ */
+
+/**
+ * The direct limits that decide the set: protobuf and opentelemetry-* entries with a version limit, in requirements
+ * files (1 level of -r), [project] dependencies and [tool.poetry.dependencies] of these pyproject.toml files.
+ * @param {any} ws
+ * @param {string[]} files  dependency files: requirements*.txt or pyproject.toml
+ * @returns {Limit[]}
+ */
+export function directLimits(ws, files) {
+  const out = []
+  const relevant = (name) => name === 'protobuf' || CORE.test(name) || CONTRIB.test(name)
+  const seen = new Set()
+  const fromRequirements = (file, depth) => {
+    if (seen.has(file)) return
+    seen.add(file)
+    const text = read(ws, file)
+    if (text === null) return
+    text.split(/\r?\n/).forEach((raw, i) => {
+      const line = raw.replace(/(^|\s)#.*$/, '').trim()
+      const include = /^(?:-r|--requirement)(?:\s+|=)(\S+)/.exec(line)
+      if (include && depth === 0) return fromRequirements(join(dirOf(file), include[1]), 1)
+      const m = /^([A-Za-z0-9][A-Za-z0-9._-]*)(?:\[[^\]]*\])?\s*([<>=!~][^;]*)?/.exec(line)
+      if (m?.[2] && relevant(normalize(m[1]))) out.push({ name: normalize(m[1]), spec: m[2].trim(), style: 'python', file, line: i + 1, value: line.split(';')[0].trim() })
+    })
+  }
+  for (const file of files) {
+    if (/\.txt$/.test(file)) { fromRequirements(file, 0); continue }
+    const text = read(ws, file)
+    if (text === null) continue
+    const lines = text.split(/\r?\n/)
+    for (const req of tomlArray(tomlTable(text, 'project'), 'dependencies')) {
+      const m = /^\s*([A-Za-z0-9][A-Za-z0-9._-]*)(?:\[[^\]]*\])?\s*([<>=!~][^;]*)?/.exec(req)
+      if (!m?.[2] || !relevant(normalize(m[1]))) continue
+      const line = lines.findIndex((l) => l.includes(req)) + 1
+      out.push({ name: normalize(m[1]), spec: m[2].trim(), style: 'python', file, line, value: req.split(';')[0].trim() })
+    }
+    for (const { key, value, line } of tomlEntries(text, 'tool.poetry.dependencies')) {
+      const name = normalize(key)
+      const spec = /^["']([^"']*)["']/.exec(value)?.[1] ?? /\bversion\s*=\s*["']([^"']*)["']/.exec(value)?.[1]
+      if (spec && spec !== '*' && relevant(name)) out.push({ name, spec, style: 'poetry', file, line, value: `${key} = ${value}` })
+    }
+  }
+  return out
+}
+
+/** The Python versions a uv or Poetry project must support: the lowest of requires-python, or python in Poetry. */
+export function projectPython(ws, files) {
+  for (const file of files.filter((f) => /pyproject\.toml$/.test(f))) {
+    const text = read(ws, file) ?? ''
+    const requires = /^\s*requires-python\s*=\s*["']([^"']+)["']/m.exec(tomlTable(text, 'project'))?.[1]
+    const low = requires ? lowestRelease(requires) : null
+    if (low) return low
+    const poetry = tomlEntries(text, 'tool.poetry.dependencies').find((e) => e.key === 'python')
+    const spec = poetry && /^["']([^"']*)["']/.exec(poetry.value)?.[1]
+    const lowPoetry = spec ? lowestRelease(spec, 'poetry') : null
+    if (lowPoetry) return lowPoetry
+  }
+  return null
+}
+
+/** True when the set allows the limit. */
+function fits(set, limit) {
+  if (limit.name === 'protobuf') return overlaps(limit.spec, set.protobuf, limit.style)
+  if (CORE.test(limit.name)) return satisfies(set.core, limit.spec, limit.style)
+  if (CONTRIB.test(limit.name)) return satisfies(set.contrib, limit.spec, limit.style)
+  return true
+}
+
+/**
+ * The first set that fits. why: the plan sentence when it is not the newest set. When none fits: the required step.
+ * @param {{limits: Limit[], python: [number, number]|null, tool?: string|null}} opts  tool: uv or poetry for floors, else pins.
+ * @returns {{set: typeof PINS.python.sets[number], why: string|null}|{block: import('../types.mjs').Block}}
+ */
+export function pickSet({ limits, python, tool = null }) {
+  const sets = PINS.python.sets
+  const pyOk = (set) => !python || python[0] * 1000 + python[1] >= set.minPython[0] * 1000 + set.minPython[1]
+  const index = sets.findIndex((set) => pyOk(set) && limits.every((l) => fits(set, l)))
+  if (index < 0) {
+    const limit = limits.find((l) => sets.filter(pyOk).every((set) => !fits(set, l)))
+    if (!limit) return { block: oldPython(python) }
+    return { block: { title: RESOLVE.python.noSet.title, lines: RESOLVE.python.noSet.lines.map((l) => fill(l, limit)) } }
+  }
+  const set = sets[index]
+  if (index === 0) return { set, why: null }
+  const newest = sets[0]
+  const limit = limits.find((l) => !fits(newest, l))
+  const values = { ...limit, python: python?.join('.'), newest: newest.core, need: newest.minPython.join('.'), core: set.core, contrib: set.contrib, tool }
+  const text = limit ? (tool ? RESOLVE.python.floorLimit : RESOLVE.python.olderLimit) : tool ? RESOLVE.python.floorPython : RESOLVE.python.olderPython
+  return { set, why: fill(text, values) }
+}
+
+/** The step for a Python version below every set. */
+function oldPython(python) {
+  const oldest = PINS.python.sets.at(-1)
+  const need = oldest.minPython.join('.')
+  return { title: `Use Python ${need} or later`, lines: [`This app uses Python ${python.join('.')}.`,
+    `opentelemetry-distro ${oldest.contrib} needs Python ${need} or later.`, 'Update the Python version of the app. Then run npx @uknows/setup again.'] }
+}
+
+/** Requirement text of 1 package: name==version or name>=floor. */
+export const requirement = (name, version, floor = null) => (floor ? `${name}>=${floor}` : `${name}==${version}`)
+
+/** The package name of a requirement text. */
+export const requirementName = (req) => normalize(/^[A-Za-z0-9][A-Za-z0-9._-]*/.exec(req)?.[0] ?? req)
+
+/** The lowest protobuf release a lock has, as a limit, so the set fits a lock that keeps protobuf below 5. */
+export function lockedLimit(installed, name) {
+  const item = installed?.packages?.get(name)
+  if (!item?.version || !clauses(`==${item.version}`).length) return null
+  return { name, spec: `==${item.version}`, style: 'python', file: item.file, line: item.line ?? 0, value: `${item.name} ${item.version}` }
+}
+
+export { compareVersion }
+
+const dirOf = (path) => (path.includes('/') ? path.slice(0, path.lastIndexOf('/')) : '.')
+function join(dir, rel) {
+  const parts = dir === '.' ? [] : dir.split('/')
+  for (const part of rel.split('/')) {
+    if (part === '..') parts.pop()
+    else if (part && part !== '.') parts.push(part)
+  }
+  return parts.join('/') || '.'
+}