@uknows/setup 0.0.0-stage → 0.2.0

package/lib/existing.mjs

@@ -0,0 +1,562 @@
+/*
+ * What 1 service already has for tracing, and the mode that follows from it. It reads the manifests of the
+ * service and of its first-party members (uv workspace members, path sources, file: packages, project
+ * references), the lock closure, the Dockerfile, deploy files, and the source of the service and its members.
+ * Sentry counts only when its tracing is on. Static reading only.
+ *
+ * classify() turns that into 1 mode:
+ *   stop           another APM agent, a classic App Insights SDK, or a package that brings its own OpenTelemetry
+ *   azure-monitor  Azure Monitor OpenTelemetry: keep it, add 1 exporter beside it
+ *   otel           OpenTelemetry SDK packages listed directly: settings only
+ *   standard       nothing yet
+ */
+import { posix } from 'node:path'
+import { AZURE_MONITOR, OTHER_EXPORTERS_NOTE, PHOENIX_KEY_STEP, PHOENIX_STEP, PINS, SETUP_TROUBLESHOOTING, TROUBLESHOOTING } from './contract.mjs'
+import { installedPackages, noPackages, packageKey } from './locks.mjs'
+import { findMembers } from './members.mjs'
+import { pyName } from './toml.mjs'
+
+const at = (dir, name) => (dir === '.' ? name : `${dir}/${name}`)
+const inside = (dir, path) => dir === '.' ? !path.startsWith('../') : path === dir || path.startsWith(`${dir}/`)
+const AGAIN = 'Then run npx @uknows/setup again.'
+const fill = (text, values) => text.replace(/\{(\w+)\}/g, (m, key) => (key in values ? String(values[key]) : m))
+
+/** Manifest name -> ecosystem. */
+const ECOSYSTEM = [
+  [/^package\.json$/, 'node'], [/^(requirements[\w.-]*\.txt|pyproject\.toml|Pipfile)$/, 'python'], [/\.csproj$/, 'dotnet'],
+  [/^(pom\.xml|build\.gradle(\.kts)?)$/, 'java'], [/^go\.mod$/, 'go'], [/^composer\.json$/, 'php'], [/^Gemfile$/, 'ruby'],
+]
+
+/**
+ * Per ecosystem: OpenTelemetry at SDK level (never the API package alone), other APM agents, Sentry, and the
+ * Azure Monitor families: azure (a distro to keep), appInsights (3.x keeps, older stops), classic (stops),
+ * browser (a note only) and tracers (allowed, with advice about the key).
+ */
+const RULES = {
+  node: { otel: /^(@opentelemetry\/(sdk-node|sdk-trace-.+|auto-instrumentations-node|exporter-trace-otlp-.+)|@vercel\/otel)$/,
+    apm: { Datadog: /^dd-trace$/, 'New Relic': /^newrelic$/, 'Elastic APM': /^elastic-apm-node$/, Dynatrace: /^@dynatrace\//, Instana: /^@instana\/collector$/ },
+    sentry: /^@sentry\//, azure: /^@azure\/monitor-opentelemetry$/, appInsights: /^applicationinsights$/, browser: /^@microsoft\/applicationinsights-/,
+    tracers: /^(@arizeai\/.+|langfuse(-.+)?|@langfuse\/.+|@traceloop\/.+|logfire|@pydantic\/logfire.*)$/ },
+  python: { otel: /^opentelemetry-(sdk|distro|instrumentation.*)$/,
+    apm: { Datadog: /^ddtrace$/, 'New Relic': /^newrelic$/, 'Elastic APM': /^elastic-apm$/ },
+    sentry: /^sentry-sdk$/, azure: /^azure-monitor-opentelemetry$/, classic: /^opencensus-ext-azure$/,
+    tracers: /^(arize-phoenix(-otel)?|openinference-.+|langfuse|traceloop-sdk|logfire)$/ },
+  dotnet: { otel: /^OpenTelemetry(\.Extensions\.Hosting|\.AutoInstrumentation|\.Exporter\..+)?$/i,
+    apm: { Datadog: /^Datadog\.Trace/i, 'New Relic': /^NewRelic\./i, 'Elastic APM': /^Elastic\.Apm/i },
+    sentry: /^Sentry(\.|$)/, azure: /^Azure\.Monitor\.OpenTelemetry\.AspNetCore$/i, appInsights: /^Microsoft\.ApplicationInsights\.(AspNetCore|WorkerService)$/i,
+    classic: /^Microsoft\.ApplicationInsights(\.(Web|WindowsServer|DependencyCollector|PerfCounterCollector|EventCounterCollector))?$/i },
+  java: { otel: /^io\.opentelemetry[\w.]*:opentelemetry-[\w-]*(sdk|starter|exporter|javaagent)/,
+    apm: { Datadog: /^com\.datadoghq:dd-/, 'New Relic': /^com\.newrelic\./, 'Elastic APM': /^co\.elastic\.apm:/ },
+    sentry: /^io\.sentry:/, classic: /^(com\.microsoft\.azure:applicationinsights-|com\.azure:azure-monitor-opentelemetry)/ },
+  go: { otel: /^go\.opentelemetry\.io\/otel\/sdk(\/|$)/,
+    apm: { Datadog: /dd-trace-go/, 'New Relic': /^github\.com\/newrelic\/go-agent/, 'Elastic APM': /^go\.elastic\.co\/apm/ },
+    sentry: /^github\.com\/getsentry\/sentry-go/ },
+  php: { otel: /^open-telemetry\/sdk$/,
+    apm: { Datadog: /^datadog\//, 'New Relic': /newrelic/, 'Elastic APM': /^elastic\/apm-agent/ }, sentry: /^sentry\// },
+  ruby: { otel: /^opentelemetry-sdk$/,
+    apm: { Datadog: /^(ddtrace|datadog)$/, 'New Relic': /^newrelic_rpm$/, 'Elastic APM': /^elastic-apm$/,
+      'Scout APM': /^scout_apm$/, Skylight: /^skylight$/ },
+    sentry: /^sentry-(ruby|rails|raven)$/ },
+}
+
+/**
+ * Packages a wrapper may bring OpenTelemetry through without a stop: the Azure Monitor distros, OpenTelemetry
+ * itself and the allowed tracers (Phoenix, openinference, langfuse, traceloop, logfire).
+ */
+const KNOWN = {
+  python: /^(opentelemetry-.+|azure-monitor-opentelemetry(-exporter)?|azure-core-tracing-opentelemetry|arize-phoenix(-otel)?|openinference-.+|langfuse|traceloop-sdk|logfire)$/,
+  dotnet: /^(opentelemetry(\..+)?|azure\.monitor\.opentelemetry(\..+)?|microsoft\.applicationinsights(\..+)?)$/,
+  node: /^(@opentelemetry\/.+|@azure\/monitor-opentelemetry(-exporter)?|applicationinsights|@vercel\/otel|@arizeai\/.+|langfuse(-.+)?|@langfuse\/.+|@traceloop\/.+|logfire)$/,
+}
+/** The Phoenix packages, whose register() falls back to OTEL_EXPORTER_OTLP_ENDPOINT. */
+const PHOENIX = /^(arize-phoenix(-otel)?|@arizeai\/phoenix-otel)$/
+/** Names that say a package is about telemetry. With OpenTelemetry under it, it is a wrapper. */
+const WRAPPER_NAME = /otel|opentelemetry|telemetry|monitoring|tracing|observability/i
+/** Requirements on OpenTelemetry packages, per language. */
+const OTEL_DEP = { python: /^opentelemetry-/, dotnet: /^opentelemetry(\.|$)/i, node: /^@opentelemetry\// }
+const LOCAL_SOURCES = new Set(['path', 'directory', 'file', 'git', 'url', 'link'])
+
+/** Agents that a Dockerfile loads (comment lines are ignored). The App Insights Java agent counts as classic App Insights. */
+const DOCKER_APM = { Datadog: /\bdd-trace\b|\bddtrace(-run)?\b|dd-java-agent|datadog-dotnet-apm|datadog-setup\.php/,
+  'New Relic': /\bnewrelic(-admin|\.jar|-php5?)?\b/i, 'Elastic APM': /elastic-apm-agent|elastic-apm-node|\belasticapm\b/i,
+  'Azure Monitor': /applicationinsights-agent/i, Dynatrace: /\bdynatrace\b|\boneagent\b/i, Instana: /\binstana\b/i }
+const DOCKER_OTEL = /-javaagent:\S*opentelemetry/
+const TRACING = /tracesSampleRate|traces_sample_rate|TracesSampleRate|enableTracing|traces-sample-rate|tracesSampler|traces_sampler/
+const SOURCE = /\.(m?[jt]sx?|c[jt]s|py|cs|rb|go|php|java|kt|properties|ya?ml|json|exs?)$/
+const LOCKS = /(^|\/)(package-lock|npm-shrinkwrap|composer\.lock|packages\.lock|project\.assets)\.json$|(^|\/)(uv|poetry|pdm)\.lock$/
+const CODE = /\.(py|cs|m?[jt]sx?|c[jt]s)$/
+const JS = /\.(m?[jt]sx?|c[jt]s)$/
+const MAX_SCAN = 5000
+const MAX_BYTES = 1_000_000
+
+/**
+ * Lines in source code that matter: where Azure Monitor starts, a tracer provider, OTLP metrics or logs, sampling
+ * arguments and service names. [kind, regex, files]. Each match is 1 anchor.
+ */
+const ANCHORS = [
+  ['azure-call', /\bconfigure_azure_monitor\s*\(/g, /\.py$/],
+  ['azure-call', /\bUseAzureMonitor\s*\(/g, /\.cs$/],
+  ['appinsights-call', /\bAddApplicationInsightsTelemetry(?:WorkerService)?\s*\(/g, /\.cs$/],
+  ['azure-call', /\buseAzureMonitor\s*\(/g, JS],
+  ['appinsights-call', /require\(\s*["']applicationinsights["']\s*\)|from\s+["']applicationinsights["']|import\s+["']applicationinsights["']/g, JS],
+  ['phoenix', /\bphoenix\.otel\b/g, /\.py$/],
+  // Phoenix gets its own address: the setting, or an address passed to register() (endpoint= in Python, url: in JS).
+  ['phoenix-endpoint', /\bPHOENIX_COLLECTOR_ENDPOINT\b|\bregister\s*\([^)]*\bendpoint\s*=/g, /\.py$/],
+  ['phoenix-endpoint', /\bPHOENIX_COLLECTOR_ENDPOINT\b|\bregister\s*\(\s*\{[^}]*\burl\s*:/g, JS],
+  // Phoenix gets its own key: the setting, or headers passed to register(). Else its exporter reads the OTLP headers, the UKNOWS key.
+  ['phoenix-key', /\bPHOENIX_API_KEY\b|\bPHOENIX_CLIENT_HEADERS\b|\bregister\s*\([^)]*\bheaders\s*=/g, /\.py$/],
+  ['phoenix-key', /\bPHOENIX_API_KEY\b|\bPHOENIX_CLIENT_HEADERS\b|\bregister\s*\(\s*\{[^}]*\bheaders\s*:/g, JS],
+  // Python web servers that Azure Monitor does not trace, when the package alone does not show that the app serves HTTP.
+  ['aiohttp-server', /\bfrom\s+aiohttp\s+import\s+[^\n]*\bweb\b|\baiohttp\.web\b/g, /\.py$/],
+  ['mcp-server', /\bFastMCP\s*\(|\bfrom\s+mcp\.server\b/g, /\.py$/],
+  ['provider', /\bset_tracer_provider\s*\(/g, /\.py$/],
+  ['otlp-signal', /\bOTLP(?:Metric|Log)Exporter\b|WriteTo\.OpenTelemetry\s*\(|\.With(?:Metrics|Logging)\s*\([^;]{0,400}?AddOtlpExporter|Logging\.AddOpenTelemetry\s*\([^;]{0,400}?AddOtlpExporter/g, CODE],
+  ['sampling', /\b(?:sampling_ratio|traces_per_second)\s*=\s*[^,)\n]+|\b(?:SamplingRatio|TracesPerSecond)\s*=\s*[^,;}\n]+|\b(?:samplingRatio|tracesPerSecond)\s*:\s*[^,}\n]+/g, CODE],
+  // The app sets the service name in code: it sets OTEL_SERVICE_NAME, or names service.name on a resource. A
+  // resource counts only in a file that also starts the global provider or Azure Monitor (resourceName below), so the
+  // resource of a second, private provider (Phoenix) does not.
+  ['service-name', /\benviron\s*\[\s*["']OTEL_SERVICE_NAME["']\s*\]\s*=(?!=)|\b(?:environ\.setdefault|putenv)\s*\(\s*["']OTEL_SERVICE_NAME["']|\bprocess\.env(?:\.OTEL_SERVICE_NAME|\[\s*["']OTEL_SERVICE_NAME["']\s*\])\s*=(?!=)|\bSetEnvironmentVariable\s*\(\s*"OTEL_SERVICE_NAME"/g, CODE],
+  ['service-resource', /["']service\.name["']|\bSERVICE_NAME\s*:|\.AddService\s*\(/g, CODE],
+  ['connection-string', /\bAPPLICATIONINSIGHTS_CONNECTION_STRING\b/g, CODE],
+  // .NET: AddOtlpExporter() reads only the general OTLP settings. UseOtlpExporter() reads the traces-only ones too.
+  ['add-otlp-exporter', /\.AddOtlpExporter\s*\(/g, /\.cs$/],
+  ['use-otlp-exporter', /\.UseOtlpExporter\s*\(/g, /\.cs$/],
+  ['traces-endpoint', /\bOTEL_EXPORTER_OTLP_TRACES_ENDPOINT\b/g, /\.cs$/],
+  ['traces-headers', /\bOTEL_EXPORTER_OTLP_TRACES_HEADERS\b/g, /\.cs$/],
+]
+/** A file that starts the global tracer provider or Azure Monitor: a service.name on a resource in it names the app. */
+const GLOBAL_PROVIDER = [
+  [/\.py$/, /\bset_tracer_provider\s*\(|\bconfigure_azure_monitor\s*\(/],
+  [/\.cs$/, /\bUseAzureMonitor\s*\(|\bAddOpenTelemetry\s*\(|\bSdk\.CreateTracerProviderBuilder\s*\(/],
+  [JS, /\buseAzureMonitor\s*\(|\bnew\s+NodeSDK\s*\(|\.register\s*\(\s*\)|\btrace\.setGlobalTracerProvider\s*\(/],
+]
+/** Deploy files that can set environment variables of the app. */
+const DEPLOY = /(?:^|\/)(?:Dockerfile(?:\.[^/]+)?|[^/]+\.[Dd]ockerfile|[^/]+\.(?:bicep|tf|ya?ml|env|sh)|\.env[^/]*|[^/]*task[-_.]?def[^/]*\.json)$/
+const ENV_ANCHORS = [
+  ['service-name', /\bOTEL_SERVICE_NAME\b/g],
+  ['connection-string', /\bAPPLICATIONINSIGHTS_CONNECTION_STRING\b/g],
+  ['auto-attach', /\bAZURE_MONITOR_AUTO_ATTACH\b["']?\s*[=:,]?\s*["']?\s*(?:value\s*[:=]\s*["']?)?(true|1)\b/gi],
+  ['sampler-env', /\bOTEL_TRACES_SAMPLER\b["']?\s*[=:]\s*["']?([\w.]+)/g],
+  ['phoenix-endpoint', /\bPHOENIX_COLLECTOR_ENDPOINT\b/g],
+  ['phoenix-key', /\bPHOENIX_API_KEY\b|\bPHOENIX_CLIENT_HEADERS\b/g],
+]
+
+/**
+ * @param {import('./types.mjs').Service} service
+ * @param {import('./workspace.mjs').RepoView|import('./workspace.mjs').Workspace} view  The repo view (ctx.repo). A Workspace works too.
+ * @returns {import('./types.mjs').Existing}
+ */
+export function findExisting(service, view) {
+  const lang = service.lang
+  const found = { otel: [], apm: new Map(), sentry: [], azure: [], classic: [], browser: [], tracers: [] }
+  const add = (vendor, evidence) => {
+    const list = found.apm.get(vendor) ?? found.apm.set(vendor, []).get(vendor)
+    if (!list.some((e) => e.file === evidence.file && e.what === evidence.what)) list.push(evidence)
+  }
+  const { members, local } = lang ? findMembers(service, view) : { members: [], local: [] }
+  const installed = lang ? installedPackages(service, view, members) : noPackages()
+  const version = (eco, name, spec) => installed.packages.get(packageKey(eco, name))?.version ?? specVersion(spec)
+  const manifests = new Set(service.manifests)
+  for (const name of listDir(view, service.dir)) if (ECOSYSTEM.some(([re]) => re.test(name))) manifests.add(at(service.dir, name))
+  for (const m of members) for (const file of m.manifests) manifests.add(file)
+  for (const file of [...manifests].sort()) {
+    const text = read(view, file)
+    const eco = ECOSYSTEM.find(([re]) => re.test(file.split('/').pop()))?.[1]
+    if (text === null || !eco) continue
+    const rules = RULES[eco]
+    for (const { name, line, spec } of dependencies(file, text)) {
+      const evidence = { file, line, what: name }
+      if (rules.otel.test(name)) found.otel.push(evidence)
+      for (const [vendor, re] of Object.entries(rules.apm)) if (re.test(name)) add(vendor, evidence)
+      if (rules.sentry.test(name)) found.sentry.push(evidence)
+      if (rules.azure?.test(name)) found.azure.push({ ...evidence, version: version(eco, name, spec) })
+      if (rules.browser?.test(name)) found.browser.push(evidence)
+      if (rules.tracers?.test(name)) found.tracers.push(evidence)
+      if (rules.appInsights?.test(name) || rules.classic?.test(name)) {
+        const v = version(eco, name, spec)
+        const major = Number(/^\D*(\d+)/.exec(v ?? '')?.[1] ?? NaN)
+        // 3.x of the .NET and Node.js App Insights packages runs on OpenTelemetry: keep it. Older ones, or an unknown
+        // version, stop. The .NET helper packages at 3.x come with Microsoft.ApplicationInsights.AspNetCore 3.x.
+        if (rules.appInsights?.test(name) && major >= 3) found.azure.push({ ...evidence, version: v })
+        else if (!(eco === 'dotnet' && rules.classic?.test(name) && major >= 3)) found.classic.push({ ...evidence, version: v, what: `${name}${v ? ` ${v}` : ''}` })
+      }
+    }
+  }
+  const dockerfile = (service.dockerfile && read(view, service.dockerfile)) || ''
+  dockerfile.split('\n').forEach((text, i) => {
+    const hit = (re) => (/^\s*#/.test(text) || !re.test(text) ? null : { file: service.dockerfile, line: i + 1, what: re.exec(text)[0] })
+    for (const [vendor, re] of Object.entries(DOCKER_APM)) if (hit(re)) (vendor === 'Azure Monitor' ? found.classic.push(hit(re)) : add(vendor, hit(re)))
+    if (hit(DOCKER_OTEL)) found.otel.push(hit(DOCKER_OTEL))
+  })
+  const dirs = [service.dir, ...members.map((m) => m.dir)]
+  let all = []
+  try { all = view.files() } catch { /* unreadable */ }
+  const sources = sourceFiles(view, all, dirs)
+  if (found.sentry.length) {
+    const hit = tracingIn(view, sources)
+    if (hit) for (const evidence of [...found.sentry, hit]) add('Sentry', evidence)
+  }
+  const own = new Set([service.dockerfile, ...(service.k8s ?? []).map((k) => k.file)].filter(Boolean))
+  // A deploy file names the service when it is its Dockerfile or Kubernetes file, or sits in the service folder.
+  const ofService = (a) => a.kind !== 'service-name' || service.dir === '.' || own.has(a.file) || inside(service.dir, a.file)
+  const anchors = [...scan(view, sources, ANCHORS).flatMap((a) => resourceName(view, a)), ...scan(view, deployFiles(view, all, service), ENV_ANCHORS).filter(ofService)]
+  const goLocal = lang === 'go' ? goModules(view, service, sources) : []
+  return { otel: found.otel, apm: [...found.apm].map(([vendor, evidence]) => ({ vendor, evidence })), azure: found.azure, classic: found.classic,
+    browser: found.browser, tracers: found.tracers, anchors, local, members, installed, goLocal }
+}
+
+/** A service.name on a resource counts as the service name only in a file that starts the global provider or Azure Monitor. */
+function resourceName(view, anchor) {
+  if (anchor.kind !== 'service-resource') return [anchor]
+  const rule = GLOBAL_PROVIDER.find(([files]) => files.test(anchor.file))
+  return rule && rule[1].test(read(view, anchor.file) ?? '') ? [{ ...anchor, kind: 'service-name' }] : []
+}
+
+/**
+ * Go: the modules that go.mod replaces with a local folder, and whether that folder's go.mod requires OpenTelemetry.
+ * Such a module is a kit that brings its own OpenTelemetry (the wrapper stop), with the source file that imports it.
+ */
+function goModules(view, service, sources) {
+  const file = at(service.dir, 'go.mod'), text = read(view, file)
+  if (!text) return []
+  const out = []
+  const lines = text.split('\n')
+  let block = false
+  lines.forEach((raw, i) => {
+    const l = raw.replace(/\/\/.*$/, '').trim()
+    if (/^replace\s*\($/.test(l)) { block = true; return }
+    if (block && l === ')') { block = false; return }
+    const m = /^(?:replace\s+)?(\S+)(?:\s+v\S+)?\s*=>\s*(\.{1,2}\/\S*)\s*$/.exec(block ? l : /^replace\s/.test(l) ? l : '')
+    if (!m) return
+    const dir = posix.normalize(at(service.dir, m[2])).replace(/\/+$/, '')
+    const mod = read(view, at(dir, 'go.mod')) ?? ''
+    const otel = /^\s*(?:require\s+)?(go\.opentelemetry\.io\/otel\S*)\s+(v\S+)/m.exec(mod)
+    const importer = sources.filter((f) => f.endsWith('.go') && !inside(dir, f)).map((f) => {
+      const code = read(view, f) ?? ''
+      const pos = code.indexOf(`"${m[1]}`)
+      return pos < 0 ? null : { file: f, line: code.slice(0, pos).split('\n').length }
+    }).find(Boolean) ?? null
+    out.push({ module: m[1], path: dir, file, line: i + 1, otel: otel ? { name: otel[1], version: otel[2] } : null, importer })
+  })
+  return out
+}
+
+/**
+ * The mode for 1 service, and why. Stops come first: another APM agent, a classic App Insights SDK (or codeless
+ * attach on App Service), a package that brings its own OpenTelemetry, or a local telemetry package with no lock.
+ * @param {Partial<import('./types.mjs').Existing>} existing
+ * @param {{lang?: string|null, hosts?: import('./types.mjs').Host[]}} [opts]
+ * @returns {import('./types.mjs').Classification}
+ */
+export function classify(existing, { lang = null, hosts = [] } = {}) {
+  if (existing.apm?.length) return { mode: 'stop', reason: 'apm' }
+  const appService = hosts.some((h) => h.id === 'azure-app-service')
+  const attach = (existing.anchors ?? []).filter((a) => a.kind === 'auto-attach')
+  const classic = [...(existing.classic ?? []), ...(appService ? attach.map((a) => ({ ...a, what: 'AZURE_MONITOR_AUTO_ATTACH=true' })) : [])]
+  if (classic.length) return { mode: 'stop', reason: 'classic', classic }
+  // Also when OpenTelemetry is listed directly: a kit beside it can limit its version, or be the only code that starts it.
+  const wrapper = findWrapper(existing, lang)
+  if (wrapper) return { mode: 'stop', reason: 'wrapper', wrapper }
+  const local = suspectLocal(existing, lang)
+  if (local) return { mode: 'stop', reason: 'local', local }
+  if (existing.azure?.length) return { mode: 'azure-monitor', reason: null }
+  if (existing.otel?.length) return { mode: 'otel', reason: null }
+  return { mode: 'standard', reason: null }
+}
+
+/**
+ * The package that brings the OpenTelemetry SDK and is not standard OpenTelemetry: a local package, a telemetry name,
+ * or a version limit below what this tool needs. When the app lists the SDK itself, a package beside it still counts
+ * when it is local and needs OpenTelemetry, or has a telemetry name and needs the SDK itself (a library that only
+ * needs the API, such as Npgsql.OpenTelemetry, traces itself and is fine). Go: a module that go.mod replaces with a
+ * local folder whose go.mod requires OpenTelemetry.
+ */
+function findWrapper(existing, lang) {
+  if (lang === 'go') {
+    const kit = (existing.goLocal ?? []).find((m) => m.otel)
+    return kit ? { package: { name: kit.module, version: null, file: kit.file, line: kit.line }, sdk: kit.otel, limit: null, need: null,
+      local: { path: kit.path, file: kit.file, line: kit.line, replace: `replace ${kit.module} => ./${posix.relative(posix.dirname(kit.file), kit.path) || '.'}` },
+      importer: kit.importer } : null
+  }
+  const sdk = PINS.sdk[lang]
+  const packages = existing.installed?.packages
+  if (!sdk || !packages) return null
+  const sdkKey = packageKey(lang, sdk.package)
+  const item = packages.get(sdkKey)
+  if (!item) return null
+  const installed = (p) => p.direct || p.via.length > 0
+  // Listed directly: in the lock, or in a manifest of the service (a lock can lag behind its manifest).
+  const direct = item.direct || (existing.otel ?? []).length > 0
+  const candidates = direct
+    ? [...packages].filter(([key, p]) => key !== sdkKey && installed(p) && (p.requires ?? []).some((r) => OTEL_DEP[lang].test(r.name))).map(([key]) => key)
+    : item.via
+  for (const via of candidates) {
+    const wrapper = packages.get(via)
+    const name = wrapper?.name ?? via
+    if (KNOWN[lang].test(lang === 'dotnet' ? name.toLowerCase() : lang === 'python' ? pyName(name) : name)) continue
+    const local = (existing.local ?? []).find((l) => packageKey(lang, l.name) === via) ?? null
+    const isLocal = LOCAL_SOURCES.has(wrapper?.source ?? '') || Boolean(local)
+    const limit = (wrapper?.requires ?? []).find((r) => OTEL_DEP[lang].test(r.name) && upperBound(lang, r.spec) !== null) ?? null
+    const below = Boolean(limit && sdk.need && compareVersions(upperBound(lang, limit.spec), sdk.need) <= 0)
+    const needsSdk = (wrapper?.requires ?? []).some((r) => packageKey(lang, r.name) === sdkKey)
+    const hit = direct ? isLocal || (WRAPPER_NAME.test(name) && needsSdk) : isLocal || WRAPPER_NAME.test(name) || below
+    if (hit) return { package: wrapper ?? { name, version: null, file: item.file }, sdk: item, limit, need: below && !direct ? sdk.need : null, local, direct }
+  }
+  return null
+}
+
+/** A local package file with a telemetry name that no lockfile explains. */
+function suspectLocal(existing, lang) {
+  const packages = existing.installed?.packages ?? new Map()
+  return (existing.local ?? []).find((l) => l.kind !== 'source' && l.kind !== 'folder' && /otel|telemetry|monitoring/i.test(l.name)
+    && !packages.has(packageKey(lang ?? '', l.name))) ?? null
+}
+
+/**
+ * The block that says why the run stops for 1 service. reason apm uses explainApm.
+ * @param {import('./types.mjs').Service} service
+ * @param {Partial<import('./types.mjs').Existing>} existing
+ * @param {import('./types.mjs').Classification} cls
+ * @returns {import('./types.mjs').Block}
+ */
+export function explainStop(service, existing, cls) {
+  const who = service.dir === '.' ? 'This app' : service.dir
+  const where = (e) => `${e.file}${e.line ? ` line ${e.line}` : ''}`
+  if (cls.reason === 'apm') return explainApm(service, existing.apm ?? [])
+  if (cls.reason === 'classic') {
+    const entry = SETUP_TROUBLESHOOTING.find((t) => t.id === 'app-insights-classic')
+    return { title: `${who} uses Application Insights in a way UKNOWS cannot join`,
+      lines: [...cls.classic.map((e) => `Found ${e.what} in ${where(e)}.`), entry.cause, ...entry.steps, AGAIN] }
+  }
+  const entry = SETUP_TROUBLESHOOTING.find((t) => t.id === 'otel-wrapper')
+  if (cls.reason === 'local') {
+    const l = cls.local
+    return { title: `Check ${l.name} before you add UKNOWS`, lines: [`${where(l)} uses the local package file ${l.path}.`,
+      'Its name says that it can bring OpenTelemetry. There is no lockfile that shows what it brings.', entry.cause, ...entry.steps, AGAIN] }
+  }
+  const { package: pkg, sdk, limit, need, local, importer, direct } = cls.wrapper
+  const sdkName = PINS.sdk[service.lang]?.package ?? sdk.name
+  const lines = [`${pkg.name}${pkg.version ? ` ${pkg.version}` : ''} brings ${sdkName} ${sdk.version ?? ''}`.trimEnd() + ` (${pkg.file}${pkg.line ? ` line ${pkg.line}` : ''}).`]
+  if (local?.replace) lines.push(`It is a local module: ${local.replace} (${where(local)}).`)
+  else if (local) lines.push(`It is a local package: ${local.path}, named in ${where(local)}.`)
+  if (importer) lines.push(`${where(importer)} imports it.`)
+  if (limit) lines.push(`It needs ${limit.name} ${limit.spec} (${pkg.file}${limit.line ? ` line ${limit.line}` : ''}).`)
+  if (need) lines.push(`This tool's packages need ${sdkName} ${need} or later.`)
+  if (direct) lines.push(`The app also lists ${sdkName} itself. This tool still stops, because ${pkg.name} can limit the OpenTelemetry version and can be the code that starts OpenTelemetry.`)
+  return { title: `${who} gets OpenTelemetry from ${pkg.name}`, lines: [...lines, entry.cause, ...entry.steps, AGAIN] }
+}
+
+/**
+ * Why the run stops for a service with another APM agent, and the options.
+ * @param {import('./types.mjs').Service} service
+ * @param {import('./types.mjs').Apm[]} apm
+ * @returns {import('./types.mjs').Block}
+ */
+export function explainApm(service, apm) {
+  const vendors = [...new Set(apm.map((a) => a.vendor))]
+  const names = vendors.length > 1 ? `${vendors.slice(0, -1).join(', ')} and ${vendors.at(-1)}` : vendors[0]
+  const steps = TROUBLESHOOTING.find((t) => t.id === 'other-apm')?.steps ?? []
+  return {
+    title: `${service.dir === '.' ? 'This app' : service.dir} already uses ${names}`,
+    lines: [...apm.flatMap((a) => a.evidence.map((e) => `Found ${e.what} in ${e.file}${e.line ? ` line ${e.line}` : ''}.`)),
+      ...steps, AGAIN],
+  }
+}
+
+/**
+ * Notes and advice that never stop the run: the browser App Insights SDK, a connection string or codeless attach
+ * with no SDK, and tracers such as Phoenix that also read the key. Phoenix with no address of its own is a required
+ * step: it would send its traces to the UKNOWS address.
+ * @param {Partial<import('./types.mjs').Existing>} existing
+ * @param {{hosts?: import('./types.mjs').Host[], mode?: string}} [opts]
+ * @returns {{notes: string[], advice: import('./types.mjs').Block[]}}
+ */
+export function existingNotes(existing, { hosts = [], mode = 'standard' } = {}) {
+  const notes = [], advice = []
+  const anchors = existing.anchors ?? []
+  for (const e of existing.browser ?? []) notes.push(fill(AZURE_MONITOR.plan.browser, { file: e.file, value: e.what }))
+  const sdk = existing.azure?.length || existing.classic?.length
+  const connection = anchors.find((a) => a.kind === 'connection-string')
+  if (connection && !sdk) notes.push(fill(AZURE_MONITOR.plan.connectionString, { file: connection.file }))
+  const attach = anchors.find((a) => a.kind === 'auto-attach')
+  if (attach && !hosts.some((h) => h.id === 'azure-app-service')) notes.push(fill(AZURE_MONITOR.plan.autoAttach, { file: attach.file }))
+  const tracer = existing.tracers?.[0] ?? anchors.find((a) => a.kind === 'phoenix')
+  const found = (e) => `Found ${e.what} in ${e.file}${e.line ? ` line ${e.line}` : ''}.`
+  // Phoenix with no address of its own sends to OTEL_EXPORTER_OTLP_ENDPOINT, which is UKNOWS after setup: a required step.
+  const phoenix = (existing.tracers ?? []).find((e) => PHOENIX.test(e.what)) ?? anchors.find((a) => a.kind === 'phoenix')
+  if (phoenix && mode !== 'stop' && !anchors.some((a) => a.kind === 'phoenix-endpoint')) {
+    advice.push({ title: PHOENIX_STEP.title, required: true, lines: [found(phoenix), ...PHOENIX_STEP.lines] })
+  }
+  // Phoenix with no key of its own sends the UKNOWS key to the Phoenix server: a required step too.
+  if (phoenix && mode !== 'stop' && !anchors.some((a) => a.kind === 'phoenix-key')) {
+    advice.push({ title: PHOENIX_KEY_STEP.title, required: true, lines: [found(phoenix), ...PHOENIX_KEY_STEP.lines] })
+  }
+  if (tracer && mode !== 'stop') {
+    advice.push({ title: 'Keep your UKNOWS key away from other exporters', required: false, lines: [found(tracer), OTHER_EXPORTERS_NOTE] })
+  }
+  return { notes, advice }
+}
+
+/** Package names a manifest lists, with 1-based lines and the version text (spec) when the manifest has one. */
+export function dependencies(file, text) {
+  const base = file.split('/').pop()
+  const lines = text.split('\n')
+  const lineOf = (needle) => lines.findIndex((l) => l.includes(needle)) + 1 || undefined
+  const out = []
+  const push = (name, line, spec = null) => { if (name && !out.some((d) => d.name === name)) out.push({ name, line, spec }) }
+  if (base === 'package.json' || base === 'composer.json') {
+    let json
+    try { json = JSON.parse(text) } catch { return out }
+    const groups = base === 'package.json' ? ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'] : ['require', 'require-dev']
+    for (const group of groups) {
+      for (const [name, spec] of Object.entries(json?.[group] ?? {})) push(name, lineOf(`${JSON.stringify(name)}`), typeof spec === 'string' ? spec : null)
+    }
+  } else if (/\.csproj$/.test(base)) {
+    for (const m of text.matchAll(/<PackageReference\s[^>]*?Include\s*=\s*"([^"]+)"[^>]*?(?:\/>|>([\s\S]*?)<\/PackageReference>)/gi)) {
+      const spec = /Version\s*=\s*"([^"]+)"/i.exec(m[0])?.[1] ?? /<Version>\s*([^<]+?)\s*</i.exec(m[2] ?? '')?.[1] ?? null
+      push(m[1], lineOf(m[0].split('\n')[0]), spec)
+    }
+  } else if (base === 'pom.xml') {
+    for (const m of text.matchAll(/<dependency>([\s\S]*?)<\/dependency>/g)) {
+      const group = /<groupId>\s*([^<\s]+)/.exec(m[1])?.[1], artifact = /<artifactId>\s*([^<\s]+)/.exec(m[1])?.[1]
+      if (group && artifact) push(`${group}:${artifact}`, lineOf(`<artifactId>${artifact}`), /<version>\s*([^<\s]+)/.exec(m[1])?.[1] ?? null)
+    }
+  } else if (/^build\.gradle/.test(base)) {
+    for (const m of text.matchAll(/['"]([\w.-]+):([\w.-]+)(?::([^'"]*))?['"]/g)) push(`${m[1]}:${m[2]}`, lineOf(m[0]), m[3] ?? null)
+  } else if (base === 'go.mod') {
+    lines.forEach((l, i) => { const m = /^\s*(?:require\s+)?([\w.-]+\.[\w-]+\/\S+)\s+(v\d\S*)/.exec(l); if (m) push(m[1], i + 1, m[2]) })
+  } else if (base === 'Gemfile') {
+    lines.forEach((l, i) => { const m = /^\s*gem\s*\(?\s*["']([^"']+)["'](?:\s*,\s*["']([^"']+)["'])?/.exec(l); if (m) push(m[1], i + 1, m[2] ?? null) })
+  } else if (/\.txt$/.test(base)) {
+    lines.forEach((l, i) => {
+      const m = /^\s*([A-Za-z0-9][A-Za-z0-9._-]*)(?:\[[^\]]*\])?\s*([^;#]*)/.exec(l.replace(/#.*/, ''))
+      if (m) push(pyName(m[1]), i + 1, m[2].trim() || null)
+    })
+  } else {
+    // pyproject.toml and Pipfile: dependency arrays and dependency tables.
+    let table = '', array = false
+    lines.forEach((raw, i) => {
+      const l = raw.replace(/\s#.*$/, '')
+      const closes = () => l.replace(/"[^"]*"|'[^']*'/g, '').includes(']')
+      const quoted = () => {
+        for (const m of l.matchAll(/["']([A-Za-z0-9][A-Za-z0-9._-]*)(?:\[[^\]"']*\])?\s*([^"';]*)[^"']*["']/g)) push(pyName(m[1]), i + 1, m[2].trim() || null)
+      }
+      if (array) { quoted(); array = !closes(); return }
+      const header = /^\s*\[+([^\]]+)\]/.exec(l)
+      if (header) { table = header[1]; return }
+      const kv = /^\s*["']?([A-Za-z0-9_.-]+)["']?\s*=\s*(.*)$/.exec(l)
+      if (!kv) return
+      if (kv[2].startsWith('[')) {
+        if (/dependencies|requires/.test(kv[1]) || /dependencies|dependency-groups/.test(table)) { quoted(); array = !closes() }
+      } else if (/dependencies|packages/.test(table) && kv[1] !== 'python') {
+        push(pyName(kv[1]), i + 1, /^["']([^"']*)["']/.exec(kv[2])?.[1] ?? /version\s*=\s*["']([^"']*)["']/.exec(kv[2])?.[1] ?? null)
+      }
+    })
+  }
+  return out
+}
+
+/** The first version number in a version text: '^3.3.0' -> '3.3.0', '[2.22.0, )' -> '2.22.0'. null when none. */
+export function specVersion(spec) {
+  return /(\d+(?:\.\d+){0,3})/.exec(spec ?? '')?.[1] ?? null
+}
+
+/**
+ * The upper bound of a version limit, or null when there is none.
+ * Python: <1.45.0, <=1.44, ==1.44.0, ~=1.44.0. NuGet: [1.17.0, 1.19.0), [1.18.0]. npm: <2, ^1.25.0, ~1.25.0.
+ */
+export function upperBound(lang, spec) {
+  if (!spec) return null
+  if (lang === 'dotnet') {
+    const range = /^\s*[[(]\s*([^,\])]*)\s*(?:,\s*([^\])]*))?\s*[\])]\s*$/.exec(spec)
+    if (!range) return null
+    return range[2] === undefined ? range[1] || null : range[2].trim() || null
+  }
+  if (lang === 'node') {
+    const caret = /^\s*\^(\d+)(?:\.(\d+))?/.exec(spec)
+    if (caret) return Number(caret[1]) > 0 ? `${Number(caret[1]) + 1}.0.0` : `0.${Number(caret[2] ?? 0) + 1}.0`
+    const tilde = /^\s*~(\d+)\.(\d+)/.exec(spec)
+    if (tilde) return `${tilde[1]}.${Number(tilde[2]) + 1}.0`
+    return /<=?\s*(\d[\w.]*)/.exec(spec)?.[1] ?? null
+  }
+  const lt = /<=?\s*(\d[\w.]*)/.exec(spec)
+  if (lt) return lt[1]
+  const exact = /===?\s*(\d[\w.]*)/.exec(spec)
+  if (exact) return exact[1]
+  const compatible = /~=\s*(\d+(?:\.\d+)*)/.exec(spec)
+  if (compatible) { const parts = compatible[1].split('.'); parts.pop(); parts[parts.length - 1] = String(Number(parts.at(-1)) + 1); return parts.join('.') }
+  return null
+}
+
+/** Compare 2 dotted versions by their numbers. Pre-release tags are ignored. */
+export function compareVersions(a, b) {
+  const pa = String(a).split(/[.+-]/).map((x) => Number.parseInt(x, 10)), pb = String(b).split(/[.+-]/).map((x) => Number.parseInt(x, 10))
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const x = Number.isNaN(pa[i] ?? 0) ? 0 : pa[i] ?? 0, y = Number.isNaN(pb[i] ?? 0) ? 0 : pb[i] ?? 0
+    if (x !== y) return x < y ? -1 : 1
+  }
+  return 0
+}
+
+function read(view, path) {
+  try { return (view.stat?.(path)?.size ?? 0) > MAX_BYTES * 16 ? null : view.read(path) } catch { return null }
+}
+
+function listDir(view, dir) {
+  try {
+    if (typeof view.list === 'function') return view.list(dir)
+    return view.files().filter((f) => posix.dirname(f) === dir).map((f) => posix.basename(f))
+  } catch { return [] }
+}
+
+/** Source files of the service and its members, capped. */
+function sourceFiles(view, all, dirs) {
+  const out = []
+  for (const file of all) {
+    if (out.length >= MAX_SCAN) break
+    if (!SOURCE.test(file) || LOCKS.test(file) || !dirs.some((d) => inside(d, file))) continue
+    if ((view.stat?.(file)?.size ?? 0) > MAX_BYTES) continue
+    out.push(file)
+  }
+  return out
+}
+
+/** Deploy files in the repo that can set the env of this service: its Dockerfile, templates, workflows, compose and .env files. */
+function deployFiles(view, all, service) {
+  const out = service.dockerfile ? [service.dockerfile] : []
+  for (const file of all) {
+    if (out.length >= MAX_SCAN) break
+    if (!DEPLOY.test(file) || LOCKS.test(file) || out.includes(file) || /(?:^|\/)pnpm-lock\.ya?ml$/.test(file)) continue
+    if ((view.stat?.(file)?.size ?? 0) > 262144) continue
+    out.push(file)
+  }
+  return out
+}
+
+/** Every match of the anchor rules in these files, as evidence with a kind. Comment-only lines still count. */
+function scan(view, files, rules) {
+  const out = []
+  for (const file of files) {
+    const applies = rules.filter((r) => !r[2] || r[2].test(file))
+    if (!applies.length) continue
+    const text = read(view, file)
+    if (!text) continue
+    for (const [kind, re] of applies) {
+      for (const m of text.matchAll(new RegExp(re.source, re.flags.includes('g') ? re.flags : `${re.flags}g`))) {
+        const line = text.slice(0, m.index).split('\n').length
+        out.push({ file, line, what: m[0].trim(), kind, ...(m[1] ? { value: m[1] } : {}) })
+      }
+    }
+  }
+  return out
+}
+
+/** The first source line that turns Sentry tracing on, as evidence. */
+function tracingIn(view, files) {
+  for (const file of files) {
+    const text = read(view, file) ?? ''
+    const m = TRACING.exec(text)
+    if (m) return { file, line: text.slice(0, m.index).split('\n').length, what: `Sentry tracing (${m[0]})` }
+  }
+  return null
+}