@preventive/triage 1.0.0-alpha.43 → 1.0.0-alpha.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preventive/triage",
-  "version": "1.0.0-alpha.43",
+  "version": "1.0.0-alpha.45",
   "description": "Client & relay server for triaging of automated reports",
   "license": "MIT OR Apache-2.0",
   "author": {
@@ -89,6 +89,9 @@
     "server-e2e/ws-server.ts",
     "server-e2e/config.example.json",
     "server-managed/activity.ts",
+    "server-managed/agent-merges.ts",
+    "server-managed/release-commits.ts",
+    "server-managed/app-agents.ts",
     "server-managed/avatar-store.ts",
     "server-managed/blob-store.ts",
     "server-managed/brotli.ts",
@@ -108,6 +111,8 @@
     "server-managed/cache-storage.ts",
     "server-managed/cli.js",
     "server-managed/combined.ts",
+    "server-managed/commit-coauthors.ts",
+    "server-managed/comparison.ts",
     "server-managed/comments.ts",
     "server-managed/config.ts",
     "server-managed/content-access.ts",
@@ -117,13 +122,21 @@
     "server-managed/db-schema.ts",
     "server-managed/db-table-names.ts",
     "server-managed/db.ts",
+    "server-managed/dependabot-access.ts",
+    "server-managed/dependabot-alerts.ts",
+    "server-managed/dependency-review-comments.ts",
     "server-managed/dependency-reviews.ts",
+    "server-managed/github-accounts.ts",
+    "server-managed/github-actions.ts",
     "server-managed/github-app.ts",
     "server-managed/github-errors.ts",
     "server-managed/github-metadata.ts",
     "server-managed/github-issue-oauth.ts",
     "server-managed/github-issues.ts",
     "server-managed/github-issue-links.ts",
+    "server-managed/github-link-oauth.ts",
+    "server-managed/github-links.ts",
+    "server-managed/github-users.ts",
     "server-managed/github-oauth.ts",
     "server-managed/github-pulls.ts",
     "server-managed/http-response.ts",
@@ -145,13 +158,21 @@
     "server-managed/kept.ts",
     "server-managed/npm-kept.ts",
     "server-managed/npm-loads.ts",
+    "server-managed/npm-delta.ts",
+    "server-managed/npm-delta-worker.js",
+    "server-managed/lockfile-scope.ts",
     "server-managed/npm-manifest.ts",
     "server-managed/npm-packages.ts",
     "server-managed/package-entry-points.ts",
     "server-managed/pretty-print.ts",
+    "server-managed/pull-reviews.ts",
     "server-managed/rename-diff.ts",
     "server-managed/rename-diff-worker.js",
     "server-managed/public-workspace.ts",
+    "server-managed/pull-dependencies.ts",
+    "server-managed/pull-dependency-reviews.ts",
+    "server-managed/pull-comment-reviews.ts",
+    "server-managed/commit-lockfiles.ts",
     "server-managed/queue.ts",
     "server-managed/repo-path.ts",
     "server-managed/report-migration.ts",
@@ -161,12 +182,22 @@
     "server-managed/report-sources.ts",
     "server-managed/revisions.ts",
     "server-managed/repository-browser.ts",
+    "server-managed/repository-changes.ts",
+    "server-managed/repository-code.ts",
+    "server-managed/repository-dependency-reviews.ts",
+    "server-managed/reviewed-dependencies.ts",
+    "server-managed/repository-agents.ts",
+    "server-managed/repository-history.ts",
+    "server-managed/repository-issues.ts",
+    "server-managed/repository-pulse.ts",
     "server-managed/repository-aliases.ts",
     "server-managed/repository-discovery.ts",
     "server-managed/repository-policy.ts",
+    "server-managed/repository-actions.ts",
     "server-managed/repository-risk.ts",
     "server-managed/repository-risk-assess.ts",
     "server-managed/repository-risk-audit.ts",
+    "server-managed/repository-risk-read.ts",
     "server-managed/scan-downloads.ts",
     "server-managed/session.ts",
     "server-managed/slugs.ts",
@@ -206,6 +237,9 @@
     "common/bundle-commit.d.ts",
     "common/bundle-commit.js",
     "common/bundle-compare-diff.js",
+    "common/bundle-compare-versions.js",
+    "common/bundle-comparison.d.ts",
+    "common/bundle-comparison.js",
     "common/bundle-compare-diff.d.ts",
     "common/bundle-compare-inputs.d.ts",
     "common/bundle-compare-inputs.js",
@@ -239,7 +273,10 @@
     "common/line-diff.d.ts",
     "common/line-diff.js",
     "common/linked-workspace-groups.js",
+    "common/managed/agent-tasks.ts",
     "common/managed/comments.ts",
+    "common/managed/github-agents.ts",
+    "common/managed/github-logins.ts",
     "common/managed/npm-packages.d.ts",
     "common/managed/npm-packages.js",
     "common/managed/permissions.ts",
@@ -291,6 +328,14 @@
     "risk/npm/score.js",
     "risk/npm/specs.js",
     "risk/npm/tarball.js",
+    "risk/actions/findings.js",
+    "risk/actions/resolve.js",
+    "risk/actions/uses.js",
+    "risk/actions/workflow.js",
+    "risk/actions/scripts/commands.js",
+    "risk/actions/scripts/grade.js",
+    "risk/actions/scripts/packages.js",
+    "risk/actions/scripts/shell.js",
     "client/dependency-paths.d.ts",
     "client/dependency-paths.js",
     "client/finding-link.js",
@@ -301,6 +346,8 @@
     "out/client-managed.js",
     "out/client-managed-import.js",
     "out/client-sync.js",
+    "out/compare.js",
+    "out/dialogs.js",
     "out/graph.js",
     "out/github-issue-authorized.html",
     "out/github-issue-authorized.js",
@@ -309,6 +356,7 @@
     "out/index.html",
     "out/manifest.webmanifest",
     "out/prism.js",
+    "out/scan.js",
     "out/stasis.svg",
     "out/terminal.js",
     "out/view.css",
@@ -352,13 +400,14 @@
   "dependencies": {
     "@exodus/stasis": "1.0.0-beta.9",
     "@exodus/stasis-core": "1.0.0-beta.9",
-    "@preventive/compare": "^1.2.8",
-    "@preventive/diff": "^1.0.2",
-    "@preventive/lockfile": "1.1.0",
+    "@preventive/archive": "^1.1.0",
+    "@preventive/compare": "^1.2.11",
+    "@preventive/diff": "^1.1.0",
+    "@preventive/lockfile": "^1.2.0",
     "@preventive/publishers": "^1.1.0",
-    "@preventive/report": "1.0.0-alpha.9",
+    "@preventive/report": "^1.0.0",
     "@preventive/sourcemap": "1.0.0-alpha.1",
-    "@preventive/upstream": "1.1.0",
+    "@preventive/upstream": "^1.2.0",
     "css-tree": "^3.2.1",
     "oxc-minify": "^0.152.0",
     "oxc-parser": "^0.152.0",

package/risk/actions/findings.js

@@ -0,0 +1,156 @@
+// What a workflow, or an action's metadata, calls for by its own text (README.md).
+import { YamlError } from '@preventive/lockfile/yaml.js'
+import { readWorkflow } from './workflow.js'
+import { installsOf } from './scripts/commands.js'
+import { dotted, imageFinding, lockedName, namesPullHead, scriptFindings, scriptInjections, within } from './scripts/grade.js'
+import { ownerKind, usesKey } from './uses.js'
+import { resolved } from '../npm/files.js'
+
+// What a `uses:` calls for by its pin, a reference's with its `key`.
+function usesFinding(uses, owner) {
+  if (uses.kind === 'invalid') return { id: 'invalid-uses', severity: 'low', uses: uses.uses }
+  if (uses.kind === 'docker') return uses.digest ? null : imageFinding(uses.uses, uses)
+  if ((uses.kind !== 'action' && uses.kind !== 'workflow') || uses.pin === 'sha') return null
+  const at = { uses: uses.uses, key: usesKey(uses) }
+  return uses.pin === 'short-sha' ? { id: 'short-sha', severity: 'high', ...at } : { id: 'unpinned', severity: ownerKind(uses.repo, owner) === 'third-party' ? 'high' : 'moderate', ...at, ref: uses.ref }
+}
+
+// An action that installs a project's npm packages, by its name: npm's,
+// Yarn's, pnpm's or Bun's install of dependencies (`bahmutov/npm-install`),
+// not another tool's (`cachix/install-nix-action`).
+const INSTALLER = /(?:npm|yarn|pnpm|bun|node[-_]?modules)[-_]?(?:ci|install)|install[-_]?(?:npm|yarn|pnpm|bun|node[-_]?modules|dep(?:endencie)?s|packages)/iu
+
+// Where a step installs a project's packages, each `{ at, prod }`: a
+// script's install's directory or the one it names, and whether it leaves
+// devDependencies out; an action of its own's, by its metadata (ScanOptions
+// `actions`), anywhere (null) where none is told; and anywhere for an action
+// that installs them (cypress-io/github-action's unless `install: false`,
+// pnpm/action-setup's with `run_install`).
+const ANYWHERE = [{ at: null, prod: false }]
+function installs(step, actions, seen = new Set()) {
+  if (step.uses?.kind === 'local') return actions ? ownInstalls(actions, step.uses.path, seen) : ANYWHERE
+  const repo = step.uses?.repo?.toLowerCase()
+  if (repo && (INSTALLER.test(repo) || (repo === 'cypress-io/github-action' && String(step.with?.install) !== 'false'))) return ANYWHERE
+  if (repo === 'pnpm/action-setup' && /^(?:true|\[|\{|-)/u.test(String(step.with?.run_install ?? '').trim())) return ANYWHERE
+  return step.run ? installsOf(step.run.script, step.run.production).map(({ into, prod }) => ({ at: directoryOf(step.run.workingDirectory, into), prod })) : []
+}
+
+// Where the repository's own action at `dir` installs, by its steps, each
+// action of its own once.
+function ownInstalls(actions, dir, seen) {
+  const read = actions.has(dir) && !seen.has(dir) && seen.add(dir) ? readWorkflow('action', actions.get(dir)) : null
+  return read && !(read instanceof YamlError) ? read.jobs.flatMap(job => job.steps.flatMap(step => installs(step, actions, seen))) : []
+}
+
+// A step's directory, and a path from it (`into`), from the repository's
+// root, '' for it; as written where an expression or a variable names it, or
+// it is out of the repository, so that it is within the same alone.
+function directoryOf(workingDirectory, into = null) {
+  const path = into?.startsWith('/') ? into : [workingDirectory, into].filter(Boolean).join('/')
+  return /\$|^\//u.test(path) ? path : resolved([], path)?.join('/') ?? path
+}
+
+// Whether the nearest lockfiles at or above `directory`, its project's, lock
+// what npx runs by `name`: `dev` where only devDependencies need it in each
+// that does.
+const lockDir = path => path.includes('/') ? path.slice(0, path.lastIndexOf('/')) : ''
+function lockedIn(lockfiles, directory, name) {
+  const above = lockfiles.filter(({ path }) => within(lockDir(path), directory))
+  const nearest = Math.max(...above.map(({ path }) => lockDir(path).length))
+  const locking = above.filter(({ path, names }) => lockDir(path).length === nearest && lockedName(names, name))
+  return locking.length > 0 && (locking.every(({ dev }) => dev && lockedName(dev, name)) ? 'dev' : true)
+}
+
+// The inputs a text names (`${{ inputs.title }}`).
+const inputsIn = text => typeof text === 'string' ? [...dotted(text).matchAll(/\$\{\{[^}]*?\binputs\s*\.\s*([\w-]+)/gu)].map(match => match[1]) : []
+
+// The inputs a step's action writes into a script: github-script's
+// `script`, and those an action of the repository's own (ScanOptions
+// `actions`) names in its `run:`s or hands to such an input of a step's.
+function scriptInputs(step, actions, seen = new Set()) {
+  if (step.uses?.repo?.toLowerCase() === 'actions/github-script') return ['script']
+  const dir = step.uses?.kind === 'local' && actions?.has(step.uses.path) && !seen.has(step.uses.path) ? step.uses.path : null
+  const read = dir === null ? null : readWorkflow('action', actions.get(dir))
+  if (!read || read instanceof YamlError) return []
+  return [...new Set(read.jobs.flatMap(job => job.steps.flatMap(each => [...inputsIn(each.run?.script),
+    ...scriptInputs(each, actions, new Set(seen).add(dir)).flatMap(input => inputsIn(each.with?.[input]))])))]
+}
+
+// Injections through the inputs an action writes into its scripts, and a
+// fork's code or artifacts taken where the workflow runs with its secrets.
+function stepFindings(step, triggers, actions) {
+  const repo = step.uses?.repo?.toLowerCase()
+  const found = scriptInputs(step, actions).flatMap(input => scriptInjections(step.with?.[input], triggers).map(({ index: _index, ...finding }) => ({ ...finding, line: step.withLines[input] })))
+  const forks = ['pull_request_target', 'workflow_run', 'issue_comment'].some(event => triggers.includes(event))
+  if (forks && repo === 'actions/checkout' && (namesPullHead(step.with?.ref) || namesPullHead(step.with?.repository))) {
+    found.push({ id: 'pwn-request', severity: 'critical', ref: String(step.with.ref ?? step.with.repository), line: step.withLines.ref ?? step.withLines.repository ?? step.line })
+  }
+  if (forks && step.run && /\bgh\s+pr\s+checkout\b/u.test(step.run.script)) found.push({ id: 'pwn-request', severity: 'critical', ref: 'gh pr checkout', line: step.run.line })
+  if (triggers.includes('workflow_run') && ((repo === 'actions/download-artifact' && (step.with?.['run-id'] !== undefined || step.with?.['github-token'] !== undefined))
+    || repo === 'dawidd6/action-download-artifact' || /\bgh\s+run\s+download\b/u.test(step.run?.script ?? ''))) found.push({ id: 'untrusted-artifact', severity: 'high', line: step.uses?.line ?? step.run.line })
+  return found
+}
+
+// A job's findings, each script graded by the installs before it and its lockfiles.
+function jobFindings(job, triggers, { owner, lockfiles, external, actions }) {
+  const found = []
+  if (job.uses) {
+    const finding = usesFinding(job.uses, owner)
+    if (finding) found.push({ ...finding, line: job.uses.line })
+    if (job.secrets === 'inherit' && job.uses.repo && ownerKind(job.uses.repo, owner) === 'third-party') found.push({ id: 'secrets-inherited', severity: 'high', uses: job.uses.uses, key: usesKey(job.uses), line: job.uses.line })
+    // An input of a reusable workflow, which one writes into its scripts.
+    for (const [input, value] of Object.entries(job.with ?? {})) for (const { index: _index, ...injected } of scriptInjections(value, triggers)) found.push({ ...injected, line: job.withLines[input] })
+  }
+  for (const image of job.images) {
+    if (!image.read?.digest && !image.text.includes('${{')) found.push({ ...imageFinding(image.text, image.read), line: image.line })
+    for (const { index: _index, ...injected } of scriptInjections(image.text, triggers)) found.push({ ...injected, line: image.line })
+  }
+  const installed = []
+  for (const step of job.steps) {
+    const finding = step.uses && usesFinding(step.uses, owner)
+    if (finding) found.push({ ...finding, line: step.uses.line })
+    if (step.run) {
+      const directory = dir => directoryOf(step.run.workingDirectory, dir)
+      const locked = (name, dir) => !external && lockedIn(lockfiles, directory(dir), name)
+      const before = (dev, dir) => installed.some(({ at, prod }) => within(at, directory(dir)) && !(prod && dev))
+      found.push(...scriptFindings(step.run, { locked, installed: before, external, triggers }))
+    }
+    found.push(...stepFindings(step, triggers, actions))
+    installed.push(...installs(step, actions))
+  }
+  return found
+}
+
+// Every finding of a workflow read (readWorkflow), in its lines' order, by
+// index.d.ts ScanOptions.
+export function workflowFindings(read, { owner = null, lockfiles = [], external = false, actions = null } = {}) {
+  const found = read.jobs.flatMap(job => jobFindings(job, read.triggers, { owner, lockfiles, external, actions }))
+  if (/^node(?:12|16)$/u.test(read.using ?? '')) found.push({ id: 'deprecated-runtime', severity: 'low', using: read.using, line: read.usingLine })
+  return found.toSorted((a, b) => (a.line ?? 0) - (b.line ?? 0))
+}
+
+// The references a workflow read makes: of GitHub's, each with its `key`, and
+// of its own (`local`).
+export function workflowUses(read) {
+  return read.jobs.flatMap(job => [job.uses, ...job.steps.map(step => step.uses)]).flatMap(uses => {
+    if (uses?.kind === 'local') return [uses]
+    return uses?.kind === 'action' || uses?.kind === 'workflow' ? [{ ...uses, key: usesKey(uses) }] : []
+  })
+}
+
+// The actions of the repository's own a workflow or an action uses, by
+// their directories, and a Docker action's Dockerfile; none for one GitHub
+// can't run.
+export function ownFilesOf(kind, text) {
+  const read = readWorkflow(kind, text)
+  if (read instanceof YamlError) return { actions: [], dockerfile: null }
+  return { actions: workflowUses(read).flatMap(uses => uses.kind === 'local' && !uses.job ? [uses.path] : []), dockerfile: read.dockerfile?.path ?? null }
+}
+
+// A workflow's or an action's metadata's (`kind`) references and findings;
+// why not (`workflow-unreadable`) for one GitHub can't run.
+export function scanWorkflow(kind, text, options = {}) {
+  const read = readWorkflow(kind, text)
+  if (read instanceof YamlError) return { error: 'workflow-unreadable', detail: read.message.slice(0, 500) }
+  return { uses: workflowUses(read), findings: workflowFindings(read, options) }
+}

package/risk/actions/resolve.js

@@ -0,0 +1,219 @@
+// A reference resolved on GitHub (`source`, index.d.ts ActionsSource): its
+// repository, its ref's commit and its own code's findings (README.md).
+import { YamlError } from '@preventive/lockfile/yaml.js'
+import { readWorkflow } from './workflow.js'
+import { workflowFindings, workflowUses } from './findings.js'
+import { imageFinding, scriptFindings } from './scripts/grade.js'
+import { isWorkflowPath, ownerKind, readImage, readUses, usesKey } from './uses.js'
+
+// An action's tags as versions: a release's (`v4.2.1`), and a major (`v4`) or
+// minor one (`v4.2`) moved to its line's latest. `[major, minor, patch]`,
+// null for a part a tag hasn't; null for no version.
+export function tagVersion(tag) {
+  const m = typeof tag === 'string' ? /^v?(\d{1,9})(?:\.(\d{1,9}))?(?:\.(\d{1,9}))?$/u.exec(tag) : null
+  return m && [Number(m[1]), m[2] === undefined ? null : Number(m[2]), m[3] === undefined ? null : Number(m[3])]
+}
+
+const isRelease = version => version !== null && version[2] !== null
+
+const byVersion = (a, b) => (b[0] - a[0]) || ((b[1] ?? -1) - (a[1] ?? -1)) || ((b[2] ?? -1) - (a[2] ?? -1))
+
+// Whether a release is of a major or minor tag's line: `v4`'s `4.x.y`.
+const ofLine = (version, other) => isRelease(other) && other[0] === version[0] && (version[1] === null || other[1] === version[1])
+
+// The versions of `tags` (`{ tag, oid }` each), the highest first.
+const versionsOf = tags => tags.flatMap(({ tag, oid }) => { const version = tagVersion(tag); return version ? [{ tag, oid, version }] : [] })
+  .toSorted((a, b) => byVersion(a.version, b.version))
+
+// The latest release's tag of `tags`, else the highest version's; null where
+// none is one.
+export function latestOf(tags) {
+  const versions = versionsOf(tags)
+  return (versions.find(({ version }) => isRelease(version)) ?? versions[0])?.tag ?? null
+}
+
+// The highest release of each major line, the latest line first: where a
+// commit is most likely in a release's history.
+export function newestOfLines(tags) {
+  const seen = new Set()
+  return versionsOf(tags).filter(({ version }) => isRelease(version) && !seen.has(version[0]) && seen.add(version[0]))
+}
+
+// An instruction's lines, its continuations (`\` at a line's end) joined,
+// and each heredoc's (`<<EOF`) through its delimiter, as BuildKit reads one.
+function instructions(text) {
+  const lines = text.split('\n').map(line => line.replace(/\r$/u, ''))
+  const found = []
+  for (let at = 0; at < lines.length; at++) {
+    const start = at
+    while (lines[at].endsWith('\\') && at + 1 < lines.length) at++
+    for (const { 2: quoted, 3: bare } of lines.slice(start, at + 1).join('\n').matchAll(/(?<!<)<<-?\s*(?:(["'])(.+?)\1|([^\s"'<>|&;()]+))/gu)) {
+      do at++
+      while (at < lines.length - 1 && lines[at].trim() !== (quoted ?? bare))
+    }
+    found.push({ start, lines: lines.slice(start, Math.min(at, lines.length - 1) + 1) })
+    at = Math.min(at, lines.length - 1)
+  }
+  return found
+}
+
+// A `RUN`'s command, its exec form (`RUN ["sh", "-c", "…"]`) as words.
+function runCommand(text) {
+  if (!text.trimStart().startsWith('[')) return text
+  try {
+    const words = JSON.parse(text)
+    return Array.isArray(words) ? words.map(word => /[\s'"]/u.test(String(word)) ? `'${String(word).replaceAll("'", "'\\''")}'` : String(word)).join(' ') : text
+  } catch { return text }
+}
+
+// A Docker action's Dockerfile: each `FROM` by a tag, a build argument's
+// yellow, and each `RUN` read as a script's (scripts/grade.js).
+export function dockerfileFindings(text) {
+  const findings = [], script = [], stages = new Set()
+  for (const { start, lines } of instructions(text)) {
+    const first = /^\s*(FROM|RUN)\s+(.*)$/iu.exec(lines[0])
+    // A RUN's options (`--mount=…`, `--network=…`) aren't its command.
+    if (first?.[1].toUpperCase() === 'RUN') { script.push(runCommand(first[2].replace(/^(?:--[a-z-]+(?:=\S*)?\s+)*/iu, '')), ...lines.slice(1)); continue }
+    script.push(...lines.map(() => ''))
+    if (!first) continue
+    const words = lines.join(' ').replaceAll('\\', ' ').trim().split(/\s+/u).slice(1).filter(word => !word.startsWith('--'))
+    const [image, as, stage] = words
+    const built = image && stages.has(image.toLowerCase())
+    if (as?.toLowerCase() === 'as' && stage) stages.add(stage.toLowerCase())
+    if (!image || image === 'scratch' || built) continue
+    const read = readImage(image)
+    if (image.includes('$')) findings.push({ id: 'unpinned-image', severity: 'moderate', image, line: start + 1 })
+    else if (!read?.digest) findings.push({ ...imageFinding(image, read), line: start + 1 })
+  }
+  const run = { script: script.join('\n'), line: 1, start: 1 }
+  findings.push(...scriptFindings(run, { locked: () => false, installed: () => false, external: true, triggers: [] }))
+  return findings.toSorted((a, b) => a.line - b.line)
+}
+
+// How many major lines' releases a commit is looked for in.
+const MAX_LINES = 10
+
+async function repositoryOf(uses, source, owner) {
+  const info = await source.repo(uses.repo)
+  if (!info) return { info: null, findings: [{ id: 'repo-missing', severity: ownerKind(uses.repo, owner) === 'own' ? 'moderate' : 'critical' }] }
+  const findings = []
+  if (info.fullName.toLowerCase() !== uses.repo.toLowerCase()) findings.push({ id: 'repo-moved', severity: 'high', to: info.fullName })
+  if (info.fork) findings.push({ id: 'repo-fork', severity: 'low', parent: info.fork })
+  if (info.archived) findings.push({ id: 'repo-archived', severity: 'low' })
+  return { info, findings }
+}
+
+// Where `sha` is in the history (`default`, `release`, `branch`), `none`,
+// `unknown` where not all could be looked in, or `missing`: each branch and
+// release looked in once, from its commit.
+async function reachable(source, info, sha, tags) {
+  const name = info.fullName, releases = newestOfLines(tags ?? []).slice(0, MAX_LINES)
+  if (releases.some(({ oid }) => oid === sha)) return 'release'
+  const head = await source.branch(name, info.defaultBranch)
+  const onDefault = await source.contains(name, head ?? info.defaultBranch, sha)
+  if (onDefault === null) return 'missing'
+  if (onDefault) return 'default'
+  const looked = new Set([head])
+  const contains = oid => !looked.has(oid) && looked.add(oid) && source.contains(name, oid, sha)
+  for (const { oid } of releases) if (await contains(oid)) return 'release'
+  const { branches, complete } = await source.branches(name)
+  for (const { oid } of branches) if (oid === sha || await contains(oid)) return 'branch'
+  return complete && tags !== null ? 'none' : 'unknown'
+}
+
+const tagsOn = (tags, commit) => tags?.filter(({ oid }) => oid === commit).map(({ tag }) => tag) ?? []
+
+function tagFindings(ref, commit, tags) {
+  const version = tagVersion(ref)
+  if (!version) return [{ id: 'not-version', severity: 'moderate' }]
+  if (!tags) return []
+  const findings = []
+  const releases = versionsOf(tags).filter(other => ofLine(version, other.version))
+  if (version[2] === null && releases.length > 0 && !releases.some(({ oid }) => oid === commit)) findings.push({ id: 'tag-off-release', severity: 'high', release: releases[0].tag })
+  const latest = latestOf(tags)
+  if (latest && tagVersion(latest)[0] > version[0]) findings.push({ id: 'outdated', severity: 'low', latest })
+  return findings
+}
+
+// A ref not a commit, resolved as GitHub resolves it, a tag before a branch.
+async function refOf(uses, info, source, tags) {
+  const name = info.fullName
+  const [tagged, branched] = await Promise.all([tags ? tags.find(({ tag }) => tag === uses.ref)?.oid ?? null : source.tag(name, uses.ref), source.branch(name, uses.ref)])
+  if (!tagged && !branched) return { commit: null, at: null, findings: [{ id: 'ref-missing', severity: 'moderate' }] }
+  if (!tagged) return { commit: branched, at: 'branch', findings: [{ id: 'branch-ref', severity: 'high' }] }
+  const findings = branched ? [{ id: 'ambiguous-ref', severity: 'high', branch: branched }] : []
+  findings.push(...tagFindings(uses.ref, tagged, tags))
+  const where = await reachable(source, info, tagged, tags)
+  if (where === 'none') findings.push({ id: 'tag-off-branch', severity: 'low' })
+  return { commit: tagged, at: 'tag', findings }
+}
+
+// Whether a version a comment names is a tag on the commit, or one's line.
+function commentHolds(comment, named) {
+  const version = tagVersion(comment)
+  return named.some(tag => tag === comment || tag.replace(/^v/u, '') === comment.replace(/^v/u, '') || (version && version[2] === null && ofLine(version, tagVersion(tag))))
+}
+
+// A commit, looked for in the history where no tag names it, held to its comment.
+async function pinnedOf(uses, info, source, tags) {
+  const commit = uses.ref
+  let named = tagsOn(tags, commit)
+  if (!tags && uses.comment && await source.tag(info.fullName, uses.comment) === commit) named = [uses.comment]
+  const findings = []
+  if (named.length === 0) {
+    const where = await reachable(source, info, commit, tags)
+    if (where === 'missing') findings.push({ id: 'commit-missing', severity: 'high' })
+    else if (where === 'none') findings.push({ id: 'imposter-commit', severity: 'critical' })
+    else if (where === 'unknown') findings.push({ id: 'unverified-commit', severity: 'high' })
+    else if (tags) findings.push({ id: 'untagged-commit', severity: 'moderate', on: where })
+  }
+  if (uses.comment && !commentHolds(uses.comment, named)) findings.push({ id: 'comment-mismatch', severity: 'high', comment: uses.comment, tags: named })
+  return { commit, at: 'sha', findings }
+}
+
+// A `$/path` (the repository's own at the commit running) as a reference.
+const selfRef = (uses, info, commit) => readUses(`${info.fullName}/${uses.path}@${commit}`, { job: isWorkflowPath(uses.path) })
+
+// What a reference runs at `commit` (action.yml, a reusable workflow, a
+// Dockerfile): its findings, each with its file, and the references it makes.
+async function codeOf(uses, info, commit, source) {
+  const dir = uses.path ? `${uses.path}/` : '', name = info.fullName
+  const candidates = uses.kind === 'workflow' ? [uses.path] : [`${dir}action.yml`, `${dir}action.yaml`]
+  let file = null, text = null
+  for (const path of candidates) {
+    text = await source.file(name, path, commit)
+    if (text !== null) { file = path; break }
+  }
+  if (text === null) return { findings: [{ id: 'action-missing', severity: 'moderate' }], uses: [] }
+  const read = readWorkflow(uses.kind === 'workflow' ? 'workflow' : 'action', text)
+  if (read instanceof YamlError) return { findings: [{ id: 'unreadable', severity: 'moderate', file, detail: read.message }], uses: [] }
+  const findings = workflowFindings(read, { owner: name.split('/')[0], external: true }).map(finding => ({ ...finding, file }))
+  const dockerfile = read.dockerfile && `${dir}${read.dockerfile.path}`
+  const docker = dockerfile && !dockerfile.split('/').includes('..') ? await source.file(name, dockerfile, commit) : null
+  if (docker !== null) findings.push(...dockerfileFindings(docker).map(finding => ({ ...finding, file: dockerfile })))
+  const nested = workflowUses(read).map(each => each.kind === 'local' ? (each.self || each.job) && selfRef(each, info, commit) : each)
+  return { findings, uses: nested.filter(each => each?.kind === 'action' || each?.kind === 'workflow').map(usesKey) }
+}
+
+// A reference resolved (index.d.ts ResolvedAction); `owner`, whose workflow names it.
+export async function resolveAction(uses, source, { owner = null } = {}) {
+  const at = { key: usesKey(uses), kind: uses.kind, repo: uses.repo, path: uses.path, ref: uses.ref }
+  const { info, findings } = await repositoryOf(uses, source, owner)
+  if (!info) return { ...at, repository: null, commit: null, at: null, tags: [], findings, uses: [] }
+  const tags = await source.tags(info.fullName)
+  const ref = uses.pin === 'sha' ? await pinnedOf(uses, info, source, tags) : await refOf(uses, info, source, tags)
+  const code = ref.commit && !ref.findings.some(({ id }) => id === 'commit-missing') ? await codeOf(uses, info, ref.commit, source) : null
+  return { ...at, repository: { fullName: info.fullName, private: Boolean(info.private) }, commit: ref.commit, at: ref.at, tags: tagsOn(tags, ref.commit),
+    findings: [...findings, ...ref.findings, ...code?.findings ?? []], uses: code?.uses ?? [] }
+}
+
+// `source` with its answers kept, by what was asked, while held: a scan's.
+export function keptSource(source) {
+  const kept = new Map()
+  const keep = method => (...args) => {
+    const key = `${method}\0${JSON.stringify(args)}`
+    if (!kept.has(key)) kept.set(key, source[method](...args).catch(error => { kept.delete(key); throw error }))
+    return kept.get(key)
+  }
+  return Object.fromEntries(['repo', 'tags', 'tag', 'branch', 'branches', 'contains', 'file'].map(method => [method, keep(method)]))
+}