@preventive/upstream 1.0.0 → 1.0.1

package/advisories.d.ts

@@ -1,6 +1,3 @@
-// Hand-written against advisories.js; a change to either belongs with the
-// other.
-
 import type { Client, RepoName } from './github.js'
 import type { CacheStore } from './npm.js'
 

package/cargo.d.ts

@@ -1,5 +1,3 @@
-// Hand-written against cargo.js; a change to either belongs with the other.
-//
 // A name is asserted to be a crate name, a version an exact semver
 // version, and a checksum 64 lowercase hex digits, before any request or
 // cache path. The cache is setCacheDir's (npm.js).

package/git.d.ts

@@ -1,5 +1,3 @@
-// Hand-written against git.js; a change to either belongs with the other.
-
 // The shape getRepo (package.js) answers in, and HEAD's commit. Each
 // field best-effort: left out where it cannot be read.
 export interface GitCheckout {

package/github/write.d.ts

@@ -1,5 +1,4 @@
-// Hand-written against github/write.js; a change to either belongs with
-// the other. Arguments are checked as github.d.ts describes.
+// Arguments are checked as github.d.ts describes.
 
 import type { Client, RepoName } from '../github.js'
 

package/github.d.ts

@@ -1,5 +1,3 @@
-// Hand-written against github.js; a change to either belongs with the other.
-//
 // Every method checks its arguments hard before any request is built: an
 // options object holding only the keys listed here, a repo that is
 // `owner/name` by GitHub's rules, branches and tags that git would take,
@@ -7,11 +5,12 @@
 // component, titles and headlines on one line. A bad one is a rejection
 // naming the method; nothing is sent. Every URL is built from checked,
 // encoded segments and has to come back out of URL parsing unchanged.
-// Redirects are refused, except the tarballs', so an answer is about the
-// repo asked for. A response is read up to a size limit (64 MiB of JSON,
-// 128 MiB of a file, 512 MiB of a tarball) and within a timeout (30
-// seconds, 5 minutes for a tarball), and what it says goes into an error
-// message escaped.
+// Redirects are refused, so an answer is about the repo asked for, except
+// the tarballs' and, where asked, getRepo's for a repo renamed or
+// transferred. A response is read up to a size limit (64 MiB of JSON, 128
+// MiB of a file, 512 MiB of a tarball) and within a timeout (30 seconds, 5
+// minutes for a tarball), and what it says goes into an error message
+// escaped.
 
 // `owner/name`.
 export type RepoName = string
@@ -35,14 +34,62 @@ export interface RepoDirEntry {
   sha: string
 }
 
-// A failed request: `status` is the HTTP status GitHub answered with.
+// A lockfile's format, by the tool that writes it, with the names it
+// writes one under and those of the project files it locks as
+// src/lockfiles.js lists them. Those @preventive/lockfile reads are as it
+// names the modules that do, yarn as yarn1.js, which reads Yarn 1's alone:
+// only the text tells a later Yarn's apart.
+export type LockfileFormat =
+  | 'pnpm' | 'npm' | 'yarn' | 'bun' | 'deno'
+  | 'uv' | 'poetry' | 'pylock' | 'pipenv' | 'pdm' | 'pixi' | 'conda-lock'
+  | 'bundler' | 'composer' | 'cargo' | 'soldeer' | 'foundry'
+  | 'cocoapods' | 'swiftpm' | 'carthage'
+  | 'go' | 'dep' | 'nuget' | 'paket' | 'gradle' | 'pub' | 'mix' | 'rebar' | 'julia'
+  | 'stack' | 'cabal' | 'shards' | 'opam' | 'nix' | 'conan' | 'bazel' | 'helm' | 'renv' | 'terraform'
+
+// A file by a lockfile's name: `path` from the repo's root, as getRepoFile
+// takes it, and `sha` its blob's id.
+export interface RepoLockfile {
+  path: string
+  format: LockfileFormat
+  sha: string
+}
+
+// A file by a project file's name, as RepoLockfile is, and the formats of
+// the lockfiles that may lock its project, in src/lockfiles.js' order:
+// whether one does, and where, is the tool's to say, a workspace's at its
+// root.
+export interface RepoProjectFile {
+  path: string
+  formats: LockfileFormat[]
+  sha: string
+}
+
+// A failed request: `status` is the HTTP status GitHub answered with, and
+// `headers` its response's (a redirect's `location` among them), on every
+// call but a GraphQL one (github/write.js).
 export class HttpError extends Error {
   name: 'HttpError'
   status: number
+  headers?: Headers
 }
 
 // Reads only.
 export interface Client {
+  // Every file by a lockfile's name, and every project file of a tool that
+  // writes one, in the full commit `sha`, or under its `directory`, found as
+  // getRepoTreeId finds it, each list sorted by path; and a project file no
+  // name tells, by a lockfile beside it named after it: a Python script
+  // `uv lock --script` locked, or a Stack or Cabal project file of another
+  // name than stack.yaml or cabal.project. From one listing of the tree
+  // with every tree under it, each hashed back to its id, so none is left
+  // out or changed; where GitHub cuts that short, as it does past 100,000
+  // entries, from the tree's own listing and then each subtree's in turn.
+  // Not looked in: a submodule, which is another repo's commit, or a
+  // `node_modules`, of packages installed. A symlink is no file. Refused
+  // where a path found is one getRepoFile does not take, such as one with a
+  // control character in it.
+  findRepoLockfiles(options: { repo: RepoName; sha: string; directory?: string }): Promise<{ lockfiles: RepoLockfile[]; projects: RepoProjectFile[] }>
   // An advisory by its GHSA id. With `repo`, that repository's published
   // copy: the maintainer's latest text, there before GitHub reviews it,
   // and shaped as a repository advisory (`state`, `patched_versions`, no
@@ -58,7 +105,14 @@ export interface Client {
   // Refused unless GitHub answers with that pull request in that repo.
   getPullRequest(options: { repo: RepoName; number: number }): Promise<{ title: string; status: PullRequestStatus }>
   // GitHub's repository object, refused unless it is the repo asked for.
-  getRepo(options: { repo: RepoName }): Promise<any>
+  // With `followRedirect`, a repository renamed or transferred, which GitHub
+  // answers with a redirect to it by its id
+  // (`https://api.github.com/repositories/<id>`), is asked for there, with
+  // the same token, once: the repository as it is now, refused unless it
+  // has that id and a `full_name` that is `owner/name`, the name to ask its
+  // other calls with. A redirect anywhere else, or a second, is refused as
+  // without it: an HttpError with the redirect's status.
+  getRepo(options: { repo: RepoName; followRedirect?: boolean }): Promise<any>
   // A file's contents as text, at `ref` or the default branch. Refused for
   // a directory, a symlink or a submodule, unless the bytes hash to the
   // blob GitHub names for the path, and unless valid UTF-8.

package/npm.d.ts

@@ -1,5 +1,3 @@
-// Hand-written against npm.js; a change to either belongs with the other.
-//
 // Every call that reaches the registry first asserts that the name is a
 // string of the shape npm takes, and a version a string that npm's
 // semver.valid answers with unchanged; neither goes near a request, or a
@@ -73,10 +71,12 @@ export interface CacheOptions {
 }
 
 // A failed request: `status` is the HTTP status the registry answered
-// with (404 for a package or version it does not have).
+// with (404 for a package or version it does not have), and `headers` its
+// response's.
 export class HttpError extends Error {
   name: 'HttpError'
   status: number
+  headers?: Headers
 }
 
 // A package's GitHub repo as its registry metadata names it -- getRepo

package/package.d.ts

@@ -1,5 +1,3 @@
-// Hand-written against package.js; a change to either belongs with the other.
-
 export interface PackageRepoLink {
   // `owner/name`, by GitHub's own rules.
   github?: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preventive/upstream",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Minimal npm, crates.io and Soldeer registry clients, a GitHub client, and a git checkout reader: the calls we use, nothing more",
   "type": "module",
   "exports": {
@@ -85,6 +85,7 @@
     "src/github/read.js",
     "src/github/write.js",
     "src/http.js",
+    "src/lockfiles.js",
     "src/npm/cacache.js",
     "src/npm/registry.js",
     "src/npm/repos.js",

package/semver.d.ts

@@ -1,5 +1,3 @@
-// Hand-written against semver.js; a change to either belongs with the other.
-
 // npm's own semver, borrowed from the npm beside node and passed through
 // as it is; where there is no npm, the `semver` package, an optional peer
 // dependency. Without either, every call throws, except valid() on a plain

package/soldeer.d.ts

@@ -1,6 +1,3 @@
-// Hand-written against soldeer.js; a change to either belongs with the
-// other.
-//
 // The name is asserted to be one Soldeer takes, the version a string of
 // letters, digits, `.`, `_`, `+` and `-`, and the checksum 64 lowercase hex
 // digits, before any request or cache path. The cache is setCacheDir's

package/src/github/read.js

@@ -1,9 +1,10 @@
 import assert from 'node:assert/strict'
 import { Buffer } from 'node:buffer'
 
-import { assertArgs, assertGhsa, assertLogin, assertNumber, assertPath, assertRef, assertRepo, assertSha, assertTagName, assertTreeId, isSha, isSha1, isTagName, optional, sameName, show } from '../args.js'
+import { assertArgs, assertBoolean, assertGhsa, assertLogin, assertNumber, assertPath, assertRef, assertRepo, assertSha, assertTagName, assertTreeId, isRepo, isSha, isSha1, isTagName, optional, sameName, show } from '../args.js'
 import { verifiedDownload } from '../download.js'
-import { decode, encodeSegment, requestWithHeaders } from '../http.js'
+import { HttpError, decode, encodeSegment, requestWithHeaders } from '../http.js'
+import { FORMATS, lockfileOf, projectFormats } from '../lockfiles.js'
 import { gitTreeOfListing, objectId } from '../tree.js'
 import { api, bindMethods, call, clientHeaders, isGone, repoApi } from './client.js'
 
@@ -48,10 +49,29 @@ async function listUserRepos(headers, options) {
   return await paginate('listUserRepos', headers, (paging) => api(['user', 'repos'], { ...paging, sort: 'full_name' }), options?.maxPages)
 }
 
+// Where GitHub's API sends a repository renamed or transferred: to that
+// repository by its id.
+const REPO_BY_ID = /^https:\/\/api\.github\.com\/repositories\/([1-9]\d{0,14})$/u
+const REDIRECTS = new Set([301, 302, 307, 308])
+
+// With `followRedirect`, GitHub's redirect for a repository renamed or
+// transferred is followed, once, on its API alone, and the answer held to
+// the id it names rather than to the name asked; any other redirect, or a
+// second, is refused as without it.
 async function getRepo(headers, options) {
-  assertArgs('getRepo', options, { repo: assertRepo })
-  const info = await call(headers, repoApi(options.repo))
-  assert.ok(sameName(info?.full_name, options.repo), `getRepo: answered for ${show(info?.full_name)}, not ${options.repo}`)
+  assertArgs('getRepo', options, { repo: assertRepo, followRedirect: optional(assertBoolean) })
+  const { repo, followRedirect } = options
+  let info
+  try {
+    info = await call(headers, repoApi(repo))
+  } catch (err) {
+    const id = followRedirect && err instanceof HttpError && REDIRECTS.has(err.status) ? REPO_BY_ID.exec(err.headers.get('location') ?? '')?.[1] : undefined
+    if (id === undefined) throw err
+    const moved = await call(headers, api(['repositories', id]))
+    assert.ok(moved?.id === Number(id) && isRepo(moved.full_name), `getRepo: ${repo} redirected to repository ${id}, answered for ${show(moved?.id)}, ${show(moved?.full_name)}`)
+    return moved
+  }
+  assert.ok(sameName(info?.full_name, repo), `getRepo: answered for ${show(info?.full_name)}, not ${repo}`)
   return info
 }
 
@@ -175,6 +195,71 @@ async function listRepoDir(headers, options) {
   return await listTree('listRepoDir', headers, options.repo, tree)
 }
 
+// A tree and every tree under it in one listing, their entries by paths
+// from it, or null where GitHub cut it short, as it does past 100,000
+// entries or 7 MB. Each tree in it, the top one too, has to hash from the
+// entries listed in it, so none is left out, changed or added: an entry is
+// filed under the path before its last `/`, a tree's own with a `/` after
+// it, so `/x` or `a//x` is in no tree.
+async function listTreeDeep(method, headers, repo, tree) {
+  const listing = await call(headers, repoApi(repo, ['git', 'trees', tree], { recursive: 1 }))
+  if (listing?.truncated === true) return null
+  const entries = Array.isArray(listing?.tree) && listing.tree.every((entry) => typeof entry?.path === 'string') ? listing.tree : []
+  const dirs = new Map([['', { sha: tree, listed: [] }], ...entries.filter((entry) => entry.type === 'tree').map((entry) => [`${entry.path}/`, { sha: entry.sha, listed: [] }])])
+  const filed = entries.every(({ path, mode, type, sha }) => {
+    const at = path.lastIndexOf('/') + 1
+    const dir = dirs.get(path.slice(0, at))
+    dir?.listed.push({ path: path.slice(at), mode, type, sha })
+    return dir !== undefined
+  })
+  assert.ok(filed && [...dirs.values()].every(({ sha, listed }) => gitTreeOfListing(listed) === sha), `${method}: GitHub's listing of tree ${tree} in ${repo}, with the trees under it, is not that tree`)
+  return entries
+}
+
+// Each file in `tree`, which is at `base` in the repo, by its path, its
+// name and its blob's id: from the tree's listing with every tree under
+// it, or, where GitHub cuts that short, from its own and then each
+// subtree's in turn, as GitHub advises for a large tree. A node_modules,
+// of packages installed, is not the repo's own.
+async function* filesIn(method, headers, repo, tree, base) {
+  const deep = await listTreeDeep(method, headers, repo, tree)
+  for (const { path, mode, type, sha } of deep ?? await listTree(method, headers, repo, tree)) {
+    const names = path.split('/')
+    if (names.includes('node_modules')) continue
+    if (type === 'blob' && mode !== '120000') yield { path: `${base}${path}`, name: names.at(-1), sha }
+    else if (deep === null && type === 'tree') yield* filesIn(method, headers, repo, sha, `${base}${path}/`)
+  }
+}
+
+const byPath = (a, b) => (a.path < b.path ? -1 : 1)
+
+async function findRepoLockfiles(headers, options) {
+  assertArgs('findRepoLockfiles', options, { repo: assertRepo, sha: assertSha, directory: optional(assertPath) })
+  const { repo, sha, directory } = options
+  const tree = await treeAt('findRepoLockfiles', headers, options)
+  const lockfiles = []
+  const projects = new Map()
+  const files = new Map()
+  const locked = []
+  for await (const { path, name, sha: blob } of filesIn('findRepoLockfiles', headers, repo, tree, directory === undefined ? '' : `${directory}/`)) {
+    files.set(path, blob)
+    const lockfile = lockfileOf(name)
+    const formats = projectFormats(name)
+    if (lockfile === undefined && formats.length === 0) continue
+    assertPath('findRepoLockfiles', `${repo}@${sha}'s ${lockfile === undefined ? 'project file' : 'lockfile'}`, path)
+    if (lockfile !== undefined) lockfiles.push({ path, format: lockfile.format, sha: blob })
+    if (lockfile?.locks !== undefined) locked.push({ path: `${path.slice(0, -name.length)}${lockfile.locks}`, format: lockfile.format })
+    if (formats.length > 0) projects.set(path, { path, formats, sha: blob })
+  }
+  // A file a lockfile beside it locks is a project file of that format too.
+  for (const { path, format } of locked) {
+    if (!files.has(path)) continue
+    const formats = projects.get(path)?.formats ?? []
+    projects.set(path, { path, formats: Object.keys(FORMATS).filter((known) => known === format || formats.includes(known)), sha: files.get(path) })
+  }
+  return { lockfiles: lockfiles.toSorted(byPath), projects: [...projects.values()].toSorted(byPath) }
+}
+
 async function getPullRequest(headers, options) {
   assertArgs('getPullRequest', options, { repo: assertRepo, number: assertNumber })
   const { repo, number } = options
@@ -219,5 +304,5 @@ async function listRepoAdvisories(headers, options) {
   return (await Array.fromAsync(cursorPages('listRepoAdvisories', headers, pageUrl))).flat()
 }
 
-export const readMethods = { getCurrentUser, listUserRepos, getRepo, getRepoHead, getRepoTag, listRepoTags, getRepoFile, getRepoTarball, getRepoTreeTarball, getRepoTreeId, listRepoDir, getPullRequest, getCollaboratorPermission, getAdvisory, listRepoAdvisories }
+export const readMethods = { getCurrentUser, listUserRepos, getRepo, getRepoHead, getRepoTag, listRepoTags, getRepoFile, getRepoTarball, getRepoTreeTarball, getRepoTreeId, listRepoDir, findRepoLockfiles, getPullRequest, getCollaboratorPermission, getAdvisory, listRepoAdvisories }
 export const createClient = (options) => bindMethods(clientHeaders('createClient', options, true), readMethods)

package/src/http.js

@@ -32,11 +32,13 @@ const LIMITS = {
 }
 const decoder = new TextDecoder('utf-8', { fatal: true })
 
+// `headers` are the response's, where there was one to read them from.
 export class HttpError extends Error {
-  constructor(status, message) {
+  constructor(status, message, headers) {
     super(message)
     this.name = 'HttpError'
     this.status = status
+    if (headers !== undefined) this.headers = headers
   }
 }
 
@@ -119,7 +121,7 @@ export async function requestWithHeaders(url, options) {
   if (!res.ok) {
     // A stream decode holds back a character cut at the limit rather than refusing it.
     const text = await readBody(res, 4096, { truncate: true }).then((bytes) => new TextDecoder('utf-8', { fatal: true }).decode(bytes, { stream: true })).catch(() => '')
-    throw new HttpError(res.status, `${options.method ?? 'GET'} ${url} ${res.status}: ${printable(text)}`)
+    throw new HttpError(res.status, `${options.method ?? 'GET'} ${url} ${res.status}: ${printable(text)}`, res.headers)
   }
   return { body: parse(await readBody(res, LIMITS[options.as].bytes), url, options.as), headers: res.headers }
 }

package/src/lockfiles.js

@@ -0,0 +1,113 @@
+// Each tool that writes a lockfile, by the format of it: the names it
+// writes one under, and those of the project files it locks, each a name
+// as git has it, `cargo.lock` not Cargo's, or a pattern. A lockfile's
+// pattern names in a `locks` group the file beside it that it locks, where
+// no name of that file's own tells it is one.
+export const FORMATS = {
+  // pnpm-lock.<branch>.yaml with git-branch-lockfile; shrinkwrap.yaml before
+  // pnpm 3. package.yaml and package.json5 in place of package.json, and
+  // .pnpmfile's hooks, which change what is locked.
+  pnpm: {
+    lockfiles: ['pnpm-lock.yaml', /^pnpm-lock\..+\.yaml$/u, 'shrinkwrap.yaml'],
+    projects: ['package.json', 'package.yaml', 'package.json5', 'pnpm-workspace.yaml', '.pnpmfile.cjs', '.pnpmfile.mjs'],
+  },
+  // npm-shrinkwrap.json is npm's own format, which npm reads before a
+  // package-lock.json beside it.
+  npm: { lockfiles: ['package-lock.json', 'npm-shrinkwrap.json'], projects: ['package.json'] },
+  // Of Yarn 1 or a later Yarn, which only the text tells apart. .yarnrc.yml
+  // has Yarn 4's catalogs.
+  yarn: { lockfiles: ['yarn.lock'], projects: ['package.json', '.yarnrc.yml'] },
+  // bun.lockb is Bun's binary one, before Bun 1.2.
+  bun: { lockfiles: ['bun.lock', 'bun.lockb'], projects: ['package.json'] },
+  deno: { lockfiles: ['deno.lock'], projects: ['deno.json', 'deno.jsonc', 'package.json'] },
+  // <script>.py.lock, of `uv lock --script`, which locks the script.
+  uv: { lockfiles: ['uv.lock', /^(?<locks>.+\.py)\.lock$/u], projects: ['pyproject.toml'] },
+  poetry: { lockfiles: ['poetry.lock'], projects: ['pyproject.toml'] },
+  // PEP 751's.
+  pylock: { lockfiles: ['pylock.toml', /^pylock\.[^.]+\.toml$/u], projects: ['pyproject.toml'] },
+  pipenv: { lockfiles: ['Pipfile.lock'], projects: ['Pipfile'] },
+  pdm: { lockfiles: ['pdm.lock'], projects: ['pyproject.toml'] },
+  pixi: { lockfiles: ['pixi.lock'], projects: ['pixi.toml', 'pyproject.toml'] },
+  // A unified lockfile of another name has to end in `.conda-lock.yml`; the
+  // explicit and env ones are conda-<platform>.lock and .lock.yml. A
+  // conda-build recipe, meta.yaml, is a source too.
+  'conda-lock': {
+    lockfiles: ['conda-lock.yml', 'conda-lock.yaml', /^.+\.conda-lock\.yml$/u, /^conda-[\da-z]+-[\da-z]+\.lock(?:\.yml)?$/u],
+    projects: ['environment.yml', 'environment.yaml', 'meta.yaml', 'pyproject.toml'],
+  },
+  // A gemspec, whose dependencies a Gemfile's `gemspec` takes.
+  bundler: { lockfiles: ['Gemfile.lock', 'gems.locked'], projects: ['Gemfile', 'gems.rb', /^.+\.gemspec$/u] },
+  composer: { lockfiles: ['composer.lock'], projects: ['composer.json'] },
+  cargo: { lockfiles: ['Cargo.lock'], projects: ['Cargo.toml'] },
+  soldeer: { lockfiles: ['soldeer.lock'], projects: ['soldeer.toml', 'foundry.toml'] },
+  foundry: { lockfiles: ['foundry.lock'], projects: ['foundry.toml'] },
+  // Each name CocoaPods reads a Podfile under, and a podspec, whose
+  // dependencies a Podfile's `podspec` takes.
+  cocoapods: { lockfiles: ['Podfile.lock'], projects: ['Podfile', 'Podfile.rb', 'CocoaPods.podfile', 'CocoaPods.podfile.yaml', /^.+\.podspec(?:\.json)?$/u] },
+  swiftpm: { lockfiles: ['Package.resolved'], projects: ['Package.swift', /^Package@swift-\d+(?:\.\d+){0,2}\.swift$/u] },
+  carthage: { lockfiles: ['Cartfile.resolved'], projects: ['Cartfile', 'Cartfile.private'] },
+  // go.sum has the checksums; go.mod, the versions, is locked as it is. A
+  // workspace's go.work.sum has those its modules' go.sum do not.
+  go: { lockfiles: ['go.sum', 'go.work.sum'], projects: ['go.mod', 'go.work'] },
+  dep: { lockfiles: ['Gopkg.lock'], projects: ['Gopkg.toml'] },
+  // packages.<project>.lock.json, for one of projects that share a
+  // directory; Directory.Packages.props has the versions of Central
+  // Package Management, which the project files then leave out.
+  nuget: { lockfiles: ['packages.lock.json', /^packages\..+\.lock\.json$/u], projects: [/^.+\.(?:cs|fs|vb)proj$/u, 'Directory.Packages.props'] },
+  paket: { lockfiles: ['paket.lock'], projects: ['paket.dependencies'] },
+  // Any *.lockfile: Gradle's own, the legacy one of each configuration, or
+  // one a build names. Version catalogs, libs.versions.toml and the like.
+  gradle: { lockfiles: [/^.+\.lockfile$/u], projects: ['build.gradle', 'build.gradle.kts', 'settings.gradle', 'settings.gradle.kts', /^.+\.versions\.toml$/u] },
+  // pubspec_overrides.yaml overrides pubspec.yaml's dependency_overrides,
+  // workspace and resolution.
+  pub: { lockfiles: ['pubspec.lock'], projects: ['pubspec.yaml', 'pubspec_overrides.yaml'] },
+  mix: { lockfiles: ['mix.lock'], projects: ['mix.exs'] },
+  // rebar.config.script, where there is one, makes the configuration.
+  rebar: { lockfiles: ['rebar.lock'], projects: ['rebar.config', 'rebar.config.script'] },
+  julia: { lockfiles: ['Manifest.toml', 'JuliaManifest.toml', /^(?:Julia)?Manifest-v\d+\.\d+\.toml$/u], projects: ['Project.toml', 'JuliaProject.toml'] },
+  // Each of a configuration's name, stack.yaml or another, and `.lock`.
+  stack: { lockfiles: [/^(?<locks>.+\.ya?ml)\.lock$/u], projects: ['stack.yaml'] },
+  // Each of a project file's name, cabal.project or another, and `.freeze`.
+  cabal: { lockfiles: [/^(?<locks>.+)\.freeze$/u], projects: ['cabal.project', /^.+\.cabal$/u] },
+  shards: { lockfiles: ['shard.lock'], projects: ['shard.yml', 'shard.override.yml'] },
+  opam: { lockfiles: ['opam.locked', /^.+\.opam\.locked$/u], projects: ['opam', /^.+\.opam$/u] },
+  nix: { lockfiles: ['flake.lock'], projects: ['flake.nix'] },
+  conan: { lockfiles: ['conan.lock'], projects: ['conanfile.txt', 'conanfile.py'] },
+  // <name>.MODULE.bazel, which MODULE.bazel's include() takes.
+  bazel: { lockfiles: ['MODULE.bazel.lock'], projects: ['MODULE.bazel', /^[^.].*\.MODULE\.bazel$/u] },
+  helm: { lockfiles: ['Chart.lock'], projects: ['Chart.yaml'] },
+  // Of no project file, but the library it is made from.
+  renv: { lockfiles: ['renv.lock'], projects: [] },
+  // Of the configuration in the directory, each of its .tf files, a child
+  // module's too, of which there is none; OpenTofu's .tofu files, and a
+  // Stack's components.
+  terraform: { lockfiles: ['.terraform.lock.hcl'], projects: [/^.+\.(?:tf|tofu)(?:\.json)?$/u, /^.+\.tfcomponent\.hcl$/u] },
+}
+
+const TOOLS = Object.entries(FORMATS)
+const KNOWN = TOOLS.flatMap(([, { lockfiles, projects }]) => [...lockfiles, ...projects])
+
+// A name of none of them, as most in a repository are, is passed over at
+// once, by a set of the names and one pattern of all the patterns.
+const NAMES = new Set(KNOWN.filter((known) => typeof known === 'string'))
+const PATTERN = new RegExp(KNOWN.filter((known) => typeof known !== 'string').map(({ source }) => `(?:${source})`).join('|'), 'u')
+const isKnown = (name) => NAMES.has(name) || PATTERN.test(name)
+
+// Whether `name` is one of `names`, each a name or a pattern.
+const isOf = (names, name) => names.some((known) => (typeof known === 'string' ? known === name : known.test(name)))
+
+// The lockfile a file of this name is, `{ format, locks }`, `locks` the name
+// of the file beside it that it locks where its pattern names one; or
+// undefined.
+export function lockfileOf(name) {
+  for (const [format, { lockfiles }] of isKnown(name) ? TOOLS : []) {
+    for (const known of lockfiles) {
+      const match = typeof known === 'string' ? known === name && {} : known.exec(name)
+      if (match) return { format, locks: match.groups?.locks }
+    }
+  }
+}
+
+// The formats of the lockfiles that lock a project of a file of this name,
+// in FORMATS' order, none where it is no project file.
+export const projectFormats = (name) => (isKnown(name) ? TOOLS.filter(([, { projects }]) => isOf(projects, name)).map(([format]) => format) : [])