@preventive/triage 1.0.0-alpha.37 → 1.0.0-alpha.39

package/risk/files/stamps.js

@@ -0,0 +1,46 @@
+// A file's stamps: what risk reads of one file (the readers beside this), and
+// what of it calls for a look, as a list of files tags it and orders it by:
+// each `{ name, severity }`, its tag's text and how severe it is (SEVERITIES).
+import { READABILITY, npmFileReadability, npmLabelMark, npmLargeCode, npmReadabilityLabels, npmTaggedCategory } from './readability.js'
+import { npmExfiltration, npmHostSeverity, npmHostTags, npmHosts } from './hosts.js'
+import { npmRunsCode, npmRunsCodeFlags } from './runs-code.js'
+
+// How severe a stamp or a finding is, the most first: `critical` red,
+// `high` a warning's orange, `moderate` yellow, `low`, and a `notice`, under
+// a low one.
+export const SEVERITIES = ['critical', 'high', 'moderate', 'low', 'notice']
+
+// A label's mark (readability.js READABILITY) as a severity: a warning's
+// orange, or a notice.
+const severityOf = mark => mark === 'warn' ? 'high' : 'notice'
+
+// A file's stamps, from what was read of it: what its code does beyond
+// itself (runs-code.js npmRunsCodeFlags), a warning's or, for the whole
+// environment read out and publishing, critical; the services it names
+// (hosts.js), a stamp a tag, at the tag's severity (Exfiltration critical,
+// Remote high, IP lookup moderate); a large code file, a notice; an
+// obfuscator's fingerprint, a warning's; and its control characters, long
+// lines and category, by their marks, but for what reads as most files do
+// (UTF-8, ASCII) and a source map.
+function npmStampsOf({ path, bytes, readability, runsCode, exfiltration }) {
+  const category = npmTaggedCategory(readability)
+  const listed = category !== 'ascii' && category !== 'map' && READABILITY.get(category).mark
+  return [...npmRunsCodeFlags(runsCode),
+    ...npmHostTags(exfiltration).map(([tag, services]) => ({ name: tag, severity: npmHostSeverity(tag, services) })),
+    ...npmLargeCode(path, bytes) ? [{ name: 'Large', severity: 'notice' }] : [],
+    ...readability.obfuscation ? [{ name: 'Obfuscated', severity: 'high' }] : [],
+    ...npmReadabilityLabels(readability).filter(label => label === 'controls' || label === 'long')
+      .map(label => ({ name: READABILITY.get(label).tag, severity: severityOf(npmLabelMark(readability, label)) })),
+    ...listed ? [{ name: READABILITY.get(category).tag, severity: severityOf(listed) }] : []]
+}
+
+// Everything risk reads of a file (`path`, its `text`, null for one that
+// isn't, and its size in `bytes`): how it reads (npmFileReadability), what
+// its code does beyond itself (npmRunsCode), the services it names under the
+// hosts' tags (npmExfiltration) and the hosts its code names (npmHosts), and its
+// `stamps` (npmStampsOf).
+export function npmFileRisk(path, text, bytes) {
+  const readability = npmFileReadability(path, text)
+  const exfiltration = npmExfiltration(path, text), runsCode = npmRunsCode(path, text)
+  return { readability, runsCode, exfiltration, hosts: npmHosts(path, text), stamps: npmStampsOf({ path, bytes, readability, runsCode, exfiltration }) }
+}

package/risk/index.d.ts

@@ -0,0 +1,142 @@
+// Hand-written against index.js; a change to either belongs with the other.
+import type { CacheStore } from '@preventive/upstream/npm.js'
+
+// How severe a stamp or a finding is, the most first: `critical` red, `high`
+// a warning's orange, `moderate` yellow, `low`, and a `notice`.
+export type Severity = 'critical' | 'high' | 'moderate' | 'low' | 'notice'
+
+// The severities, the most severe first.
+export const SEVERITIES: readonly Severity[]
+
+// How old a version must be to be trusted unless said: two weeks, in ms.
+export const DEFAULT_MINIMUM_RELEASE_AGE: number
+
+// npm has no such package or version (`package-not-found`,
+// `version-not-found`), a tarball unpacks past risk's bounds
+// (`package-too-large`), npm asked to be asked later (`upstream-busy`, a 429,
+// for a caller to wait on and ask again), or npm couldn't be asked
+// (`upstream-unavailable`), answered past them (`upstream-too-large`) or
+// answered what can't be read (`upstream-invalid`). `message` tells which
+// request and why.
+export class NpmRiskError extends Error {
+  code: string
+}
+
+export interface AssessNpmOptions {
+  // The version to compare with; true for the one of the package's versions
+  // most likely free of what an attack injects, as risk picks it by npm's
+  // document (risk/npm/old-version.js), none where none is below it; without
+  // one, everything of the version is new.
+  oldVersion?: string | true | null
+  // Compare all files with an empty package, for an initial dependency review.
+  fromEmpty?: boolean
+  // Younger than this, in ms, a version is `too-new`; 0 for none, as a
+  // caller's own scopes take. Two weeks unless given.
+  minimumReleaseAge?: number
+  // Whether the package is flagged as few download it (`popularity`); false
+  // for none, as a caller's own scopes take, its downloads then not asked.
+  // True unless given.
+  popularity?: boolean
+  // Where what is read is kept, by type (risk/npm/registry.js and assess.js
+  // name each): `npm/tarballs`, `risk/npm/versions`, `risk/npm/packages`,
+  // `risk/npm/old-versions`, `risk/npm/public`, `risk/npm/downloads`,
+  // `risk/npm/advisories` and `risk/npm/assessments`.
+  cache?: CacheStore | false
+  // Asks for a package's whole document in risk's stead, as the managed
+  // server does within its bounds: null where npm has none for this asker.
+  // `authorized` whether it may be asked with the caller's npm token: the
+  // package assessed, not its dependencies.
+  packument?: (name: string, options: { authorized: boolean; signal: AbortSignal | undefined }) => Promise<Record<string, unknown> | null>
+  // Reads a version's tarball, gzipped, in place of upstream's getTarball, as
+  // the managed server does within its bounds: `version` the one assessed or
+  // `oldVersion`, that one only where its files could change what is found.
+  // What it throws is thrown as it is.
+  tarball?: (name: string, version: string, options: { signal: AbortSignal | undefined }) => Promise<Uint8Array>
+  now?: number
+  signal?: AbortSignal
+  // Whether npm's downloads are asked for: the package's popularity, and its
+  // new dependencies' tiers and ages. True unless given.
+  downloads?: boolean
+  // Whether its new dependencies' tiers and ages are asked for, a request or
+  // two of npm each, where `downloads` is. True unless given.
+  dependencies?: boolean
+  // Whether npm's advisories of the version are asked for, an advisory of
+  // malware naming it a `malware` finding, as its package taken down by npm
+  // is. True unless given.
+  advisories?: boolean
+  // Whether OSV's records of malware in the version are asked for too, where
+  // `advisories` are: false for a private package, whose name OSV is never
+  // to be sent. True unless given.
+  osv?: boolean
+  // Whether a package is the caller's own, as its own scopes take: a new
+  // dependency on one is told no tier nor age, nor is npm asked of it. None
+  // unless given.
+  owned?: (name: string) => boolean | Promise<boolean>
+}
+
+// What calls for a look, by `id`, with what it found beside.
+export interface Finding {
+  id: string
+  severity: Severity
+  [found: string]: unknown
+}
+
+// A stamp on a file, as a list of files tags it.
+export interface Stamp {
+  name: string
+  severity: Severity
+}
+
+export interface FileRisk {
+  stamps: Stamp[]
+  readability: Record<string, unknown>
+  runsCode: Record<string, number[]> | null
+  exfiltration: Record<string, number[]> | null
+  hosts: Record<string, number> | null
+}
+
+export interface DependencyRisk {
+  key: string
+  name: string
+  kind: 'peer' | 'optional' | null
+  range?: string
+  from?: string
+  to?: string
+  opens: string | null
+  flags: { check: string; label: string; tooltip: string }[]
+  tier?: number | null
+  level?: string
+  // Its last whole month's downloads, by what its tier goes by: none where
+  // npm counts none of them.
+  month?: { total: number; from: string }
+  // Whether npm counts none of its downloads, as of a package published
+  // the day before; unpopular all the same.
+  uncounted?: true
+  created?: string
+  gap?: number
+}
+
+export interface NpmAssessment {
+  name: string
+  version: string
+  // The version compared with, as given or as risk picked it; null for none.
+  oldVersion: string | null
+  published: string | null
+  // A version npm removed, as it removes every one it finds malware in, told
+  // of by its `malware` finding alone, with no files nor dependencies.
+  removed?: true
+  findings: Finding[]
+  files: Record<string, FileRisk>
+  // Against `oldVersion`, each it holds too, flagged against none (`held`).
+  dependencies: { added: DependencyRisk[]; changed: DependencyRisk[]; held?: DependencyRisk[] }
+}
+
+export function assessNpm(name: string, version: string, options?: AssessNpmOptions): Promise<NpmAssessment>
+
+// Whether an advisory is of malware rather than a vulnerability: OSV's of a
+// malicious package (`MAL-…`), or one such a record names (its `aliases`),
+// CWE-506, embedded malicious code, whatever its title, or a title naming
+// malware.
+export function npmMalwareAdvisory(advisory: { id?: string | undefined; aliases?: readonly string[] | undefined; cwe?: readonly string[] | undefined; title?: string | undefined }): boolean
+
+export function npmFileRisk(path: string, text: string | null, bytes?: number): unknown

package/risk/index.js

@@ -0,0 +1,7 @@
+// What calls for a look at a package version, for a reviewer: risk's
+// heuristics, apart from any view of them. See README.md.
+export { assessNpm } from './npm/assess.js'
+export { npmMalwareAdvisory } from './npm/malware.js'
+export { DEFAULT_MINIMUM_RELEASE_AGE } from './npm/release.js'
+export { NpmRiskError } from './npm/registry.js'
+export { SEVERITIES, npmFileRisk } from './files/stamps.js'

package/risk/npm/assess.js

@@ -0,0 +1,219 @@
+// A package version's risk, as the managed server asks it: what calls for a
+// look at it, against the version before it where one is given or risk picks
+// one (old-version.js), each file's stamps, and its dependencies', from npm's
+// registry, kept in the caller's cache (registry.js) as it goes.
+import { npmBaseFilesTell, npmCompareFindings } from './compare.js'
+import { npmCombinedFindings, npmHeldDependencyFindings } from './combined.js'
+import { npmHeldFindings, npmVersionFindings } from './held.js'
+import { npmVersionFileRisk } from './files.js'
+import { npmDependencyChanges, npmFlagDependencyChanges } from './dependencies.js'
+import { npmDownloadMonths, npmSettledDownloads, npmTierLevel } from './downloads.js'
+import { NpmRiskError, npmDownloads, npmPackageFacts, npmPackageReleases, npmPublicFacts, npmVersionAdvisories, npmVersionFiles } from './registry.js'
+import { npmMalwareFinding } from './malware.js'
+import { npmKnownScope } from './manifest.js'
+import { DEFAULT_MINIMUM_RELEASE_AGE, npmAccountStanding } from './release.js'
+import { npmAddedDependency } from './new-dependency.js'
+
+// Which reading of a version an assessment kept (`risk/npm/assessments`) is:
+// one more whenever a heuristic changes what it finds, so one kept by an
+// older reading is read anew.
+const RISK_VERSION = 12
+
+// How long an assessment kept may be as JSON, and what risk reads of either
+// version's files: a package past it, whose files name thousands of hosts or
+// do what they run on thousands of lines each, is refused as too large as its
+// files are read, before more of them is held (filesRisk), and the assessment
+// once told, rather than kept and answered. A package's files tell a few
+// hundred characters each, a few MiB for the most files npm's viewer reads.
+const MAX_ASSESSMENT_LENGTH = 16 * 1024 * 1024
+const tooLarge = what => new NpmRiskError('package-too-large', `what risk tells of ${what} is past ${MAX_ASSESSMENT_LENGTH} characters`)
+
+// A value as JSON holds it: a Map as an object, its keys as strings.
+const plain = value => value instanceof Map ? Object.fromEntries([...value].map(([key, item]) => [key, plain(item)]))
+  : Array.isArray(value) ? value.map(plain)
+  : value && typeof value === 'object' ? Object.fromEntries(Object.entries(value).map(([key, item]) => [key, plain(item)])) : value
+
+// A tier among npm's packages as an assessment says it: `{ tier, level }`, the
+// rank a package is among (null past the last, unpopular) and its tint
+// (downloads.js npmTierLevel).
+const tierOf = tier => ({ tier: Number.isFinite(tier) ? tier : null, level: npmTierLevel(tier) })
+
+// Each of a version's files' stamps and what risk read of it (stamps.js
+// npmFileRisk), by path, as JSON holds them: read a file at a time and given
+// up on, as too large, once they are past MAX_ASSESSMENT_LENGTH as JSON
+// altogether, so that no more of them is held than that.
+function filesRisk(version, what) {
+  let length = 0
+  return Object.fromEntries(version.json.sources.map(path => {
+    const { readability, runsCode, exfiltration, hosts, stamps } = npmVersionFileRisk(version, path)
+    const risk = plain({ stamps, readability, runsCode, exfiltration, hosts })
+    length += path.length + JSON.stringify(risk).length
+    if (length > MAX_ASSESSMENT_LENGTH) throw tooLarge(what)
+    return [path, risk]
+  }))
+}
+
+// What of an assessment holds whatever the time, of the open version
+// (`other`) against the one compared with (`base`), or alone without one,
+// each as compare.js takes a version, as JSON holds it: what it holds,
+// always (held.js npmHeldFindings, and its dependencies against none,
+// combined.js npmHeldDependencyFindings), and against `base` what its files,
+// dependencies, install scripts, publisher and provenance call for anew
+// (compare.js npmCompareFindings), folded into what it holds, never lowering
+// it (combined.js npmCombinedFindings); each file's stamps and what risk read
+// of it (filesRisk); and its dependencies added and changed, each with its
+// flags (dependencies.js), against `base` each it holds too (`held`). Its own findings are told fresh
+// (npmAssessmentOf). The managed server's assessments keep it (`lasting`),
+// and a test can tell what one says of versions it holds. Each publisher's
+// standing on the package is told where `standing` is given (release.js
+// npmAccountStanding, of the open version).
+export const npmLastingRisk = (other, base = null, standing = null) => lastingOf(other, base, filesRisk(other, `${other.npm.name}@${other.npm.version}`), standing)
+
+// npmLastingRisk's, the open version's files read within bounds (`files`,
+// filesRisk's), as the one compared with's are where `base` has them, before
+// the findings read them all.
+function lastingOf(other, base, files, standing) {
+  if (base?.json) filesRisk(base, `${base.npm.name}@${base.npm.version}`)
+  const all = npmFlagDependencyChanges(npmDependencyChanges(undefined, other.npm.manifest), null, other)
+  const held = [...npmHeldFindings(other), ...npmHeldDependencyFindings(all)]
+  const { added, changed } = base ? npmFlagDependencyChanges(npmDependencyChanges(base.npm.manifest, other.npm.manifest), base, other) : all
+  const findings = base ? npmCombinedFindings(held, npmCompareFindings(base, other, { added, changed }, standing)) : held
+  const kept = { findings: plain(findings), files, dependencies: plain({ added, changed, ...base ? { held: all.added } : {} }) }
+  if (JSON.stringify(kept).length > MAX_ASSESSMENT_LENGTH) throw tooLarge(`${other.npm.name}@${other.npm.version}`)
+  return kept
+}
+
+// What of an assessment holds whatever the time (npmLastingRisk), kept once a
+// reading and pair, its versions' files read from npm only where it isn't:
+// the open version's first, then the one compared with's only where they
+// could change what is found (compare.js npmBaseFilesTell), that one else
+// told by what npm's document of it says alone; and where another account
+// published it, each one's standing on the package (release.js
+// npmAccountStanding), by its versions as `facts` read them, or as its
+// document is read again where they were kept. A standing changes as npm
+// removes a version, its publisher then unknown, and never else, so such a
+// pair is kept by how many npm has removed (`~<removals>`), read anew as it
+// removes another.
+async function lasting(name, version, oldVersion, facts, context, fromEmpty) {
+  const old = oldVersion === null ? null : facts.versions.get(oldVersion)
+  const publishers = [old, facts.versions.get(version)].map(fact => fact?.manifest.publisher)
+  const changed = publishers.every(Boolean) && publishers[0] !== publishers[1]
+  const key = `${RISK_VERSION}/${name}@${version}${fromEmpty ? '..(empty)' : oldVersion === null ? '' : `..${oldVersion}`}${changed ? `~${facts.removals}` : ''}`
+  const hit = context.cache ? await context.cache.read('risk/npm/assessments', key) : null
+  if (hit) return hit
+  const other = await npmVersionFiles(name, version, facts.versions.get(version), context)
+  const files = filesRisk(other, `${name}@${version}`)
+  const base = fromEmpty ? { npm: { name, version: '', manifest: {} }, json: { sources: [], sourcesContent: [] } } : old === null ? null : npmBaseFilesTell(other, old.manifest) ? await npmVersionFiles(name, oldVersion, old, context)
+    : { npm: { name, version: oldVersion, manifest: old.manifest, published: old.published }, json: null }
+  const standing = changed ? npmAccountStanding(facts.releases ?? await npmPackageReleases(name, context), other.npm.published) : null
+  const kept = lastingOf(other, base, files, standing)
+  if (context.cache) await context.cache.write('risk/npm/assessments', key, kept)
+  return kept
+}
+
+// How many dependencies added are told of at most, however many a version
+// adds, as each costs npm a request or two: the rest are left as they are,
+// their packages unknown.
+const MAX_TOLD_DEPENDENCIES = 100
+
+// Each dependency `added` that npm installs from its registry, up to
+// MAX_TOLD_DEPENDENCIES of them, but for the caller's own packages (`owned`,
+// as its own scopes take, few downloading them, as new as its releases),
+// with what risk tells of its package
+// (new-dependency.js npmAddedDependency): its tier, its last whole month's
+// downloads by what its tier goes by where it has one (`month`, `{ total,
+// from }`), `uncounted` where npm counts none of them, and `created` and `gap`
+// where it is new since the version compared with (`published`, when that
+// and the open version were); four asked at a time, whether each is the
+// caller's own among them, none more once one fails or MAX_TOLD_DEPENDENCIES
+// not the caller's own were taken, however many a version adds.
+async function addedDependencies(added, published, context, owned) {
+  const told = [...added]
+  const asked = told.flatMap((row, at) => row.opens ? [at] : [])
+  let next = 0, taken = 0
+  const tell = async row => {
+    const downloads = await npmDownloads(row.opens, context)
+    let facts = npmAddedDependency({ downloads, published }, context.now)
+    if (facts.wanted) {
+      const listed = await npmPublicFacts(row.opens, context)
+      facts = npmAddedDependency({ downloads, listed: listed && { ...listed, private: false }, published }, context.now)
+    }
+    const settled = npmSettledDownloads(downloads, context.now)
+    const month = npmDownloadMonths(settled).at(-1)
+    return { ...row, ...facts.tier === null ? {} : { ...tierOf(facts.tier), ...settled ? month && { month: { total: month.total, from: month.from.toISOString().slice(0, 10) } } : { uncounted: true } },
+      ...facts.created ? { created: facts.created, gap: facts.gap } : {} }
+  }
+  await Promise.all(Array.from({ length: 4 }, async () => {
+    while (next < asked.length && taken < MAX_TOLD_DEPENDENCIES) {
+      const at = asked[next++]
+      try {
+        if (await owned(told[at].opens)) continue
+        if (taken >= MAX_TOLD_DEPENDENCIES) break
+        taken++
+        told[at] = await tell(told[at])
+      } catch (error) { next = asked.length; throw error }
+    }
+  }))
+  return told
+}
+
+// What calls for a look at `version` of package `name`, as JSON holds it:
+// malware first (malware.js npmMalwareFinding: its package taken down by
+// npm, and npm's advisories of malware naming it where `advisories`, true
+// unless given false, has them asked, OSV's too where `osv` is, true unless
+// given false, as a private package's name is never sent it); against `oldVersion` where given,
+// true for the one of its versions most likely free of what an attack
+// injects, as risk picks it by npm's document (old-version.js npmOldVersion;
+// none where none is below it), the one it picked said as `oldVersion`
+// (compare.js npmCompareFindings's order), else what it holds (held.js
+// npmHeldFindings), a deprecation first, and last
+// one younger than `minimumReleaseAge` (two weeks unless given; 0 for none, as
+// a caller's own scopes take), and the package's tier past the top 20,000
+// (`popularity`, held.js npmVersionFindings, unless `popularity` is given
+// false, as a caller's own scopes take); `files`, each file's stamps and what risk read of it; and
+// `dependencies`, those added and changed against it, each with its flags,
+// an added one with its package's tier and age where `downloads` (true unless
+// given false) has them asked, and `dependencies` (true unless given false)
+// too, but where `owned` says its package is the caller's own, as its own scopes
+// take (none unless given). `cache` keeps what is read (registry.js),
+// `packument` asks for a package's whole document and `tarball` for a
+// version's tarball in risk's stead (registry.js), `now` is when it is asked, `signal` gives up on what is
+// still asked of npm. A version npm removed, as it removes every one it finds
+// malware in, is told of by its malware alone (`removed`), nothing of it left
+// to read. Throws an NpmRiskError (registry.js), its `code` saying why, where
+// npm has no such package or version (nor malware explaining one removed),
+// answers past risk's bounds, or can't be asked.
+export async function assessNpm(name, version, { oldVersion = null, fromEmpty = false, minimumReleaseAge = DEFAULT_MINIMUM_RELEASE_AGE, popularity = true, cache, packument, tarball, now = Date.now(), signal, downloads = true, dependencies = true, advisories = true, osv = true, owned = () => false } = {}) {
+  const context = { cache, packument, tarball, now, signal }
+  const facts = await npmPackageFacts(name, version, oldVersion, context)
+  const old = facts.oldVersion
+  if (old !== null && !facts.versions.has(old)) throw new NpmRiskError('version-not-found', `npm has no ${name}@${old}`)
+  const malware = npmMalwareFinding({ takenDown: facts.takenDown, advisories: advisories ? await npmVersionAdvisories(name, version, osv, context) : [] })
+  if (!facts.versions.has(version)) {
+    if (!malware) throw new NpmRiskError('version-not-found', `npm has no ${name}@${version}`)
+    return { name, version, oldVersion: null, published: facts.removed.get(version), removed: true, findings: [malware], files: {}, dependencies: { added: [], changed: [] } }
+  }
+  const { published, manifest } = facts.versions.get(version)
+  const kept = await lasting(name, version, old, facts, context, fromEmpty)
+  const own = npmVersionFindings({ deprecated: facts.deprecated[version], published, minimumReleaseAge, now, known: Boolean(manifest.knownAccounts), scope: npmKnownScope(name),
+    provenance: Boolean(manifest.provenance), downloads: downloads && popularity ? await npmDownloads(name, context) : null })
+  const was = old === null ? null : facts.versions.get(old).published
+  const added = downloads && dependencies ? await addedDependencies(kept.dependencies.added, [was, published], context, owned) : kept.dependencies.added
+  return { name, version, oldVersion: old, published, ...npmAssessmentOf(kept, malware ? [malware, ...own] : own, added) }
+}
+
+// An assessment of what of it holds whatever the time (`kept`,
+// npmLastingRisk's) and what is told fresh: the open version's own findings
+// (`own`, held.js npmVersionFindings, and its malware), its malware and
+// deprecation first and the rest last, its tier as JSON holds it (tierOf),
+// and its dependencies `added`, as addedDependencies tells them. The managed
+// server's (assessNpm), and a test's of versions it holds.
+const FIRST = new Set(['malware', 'deprecated'])
+export function npmAssessmentOf(kept, own, added = kept.dependencies.added) {
+  return {
+    findings: [...own.filter(({ id }) => FIRST.has(id)), ...kept.findings,
+      ...own.filter(({ id }) => !FIRST.has(id)).map(finding => finding.id === 'popularity' ? { ...finding, ...tierOf(finding.tier) } : finding)],
+    files: kept.files,
+    dependencies: { ...kept.dependencies, added },
+  }
+}

package/risk/npm/combined.js

@@ -0,0 +1,65 @@
+// What calls for a look at a version against the one compared with, as one
+// list: what it holds, always (held.js npmHeldFindings, and its dependencies
+// against none, npmHeldDependencyFindings), as no change hides any of it; and
+// what changed (compare.js npmCompareFindings), each change to what it holds
+// folded into its held finding, never lowering it: its severity the higher of
+// the two, the files, scripts or dependencies the change brought marked
+// (`added`); the rest (a publisher changed, provenance lost, large code
+// added, a file become unreadable, hosts named anew) as they are.
+import { SEVERITIES } from '../files/stamps.js'
+import { HOST_TAGS } from '../files/hosts.js'
+import { npmDependencyFindings } from './compare.js'
+import { npmHostFinding } from './held.js'
+
+// A version's dependencies that call for a look whatever came before it
+// (compare.js npmDependencyFindings against none, `dependencies` flagged
+// against none): `held-non-registry-deps` and `held-unused-deps`.
+export const npmHeldDependencyFindings = dependencies => npmDependencyFindings(dependencies, null).map(finding => ({ ...finding, id: `held-${finding.id}` }))
+
+// The more severe of two severities (stamps.js SEVERITIES).
+const higher = (a, b) => SEVERITIES[Math.min(SEVERITIES.indexOf(a), SEVERITIES.indexOf(b))]
+
+// What a change to what a version holds marks of its held finding's rows,
+// by the change's id: a file's what it runs, the services it names under a
+// hosts' tag, and an obfuscator's fingerprint new to it (`added`); the
+// scripts added or changed and what each version ran (`flagged`, `was`); a
+// dependency taken from elsewhere than npm's registry anew, its spec before
+// (`was`), or added that nothing imports (`added`). Code kept running beyond
+// itself (`kept-runs-code`) marks nothing, its files held already.
+const byPath = (rows, key) => new Map(rows.map(row => [row.path, row[key]]))
+const marked = (held, rows) => ({ ...held, files: held.files.map(row => rows.has(row.path) ? { ...row, added: rows.get(row.path) } : row) })
+const FOLDS = {
+  'runs-code': ['held-runs-code', (held, change) => marked(held, byPath(change.files, 'added'))],
+  'kept-runs-code': ['held-runs-code', held => held],
+  obfuscated: ['held-obfuscated', (held, change) => marked(held, byPath(change.files, 'obfuscation'))],
+  'install-scripts': ['held-install-scripts', (held, change) => ({ ...held, flagged: change.flagged, was: [...change.was] })],
+  'non-registry-deps': ['held-non-registry-deps', (held, change) => {
+    const was = new Map(change.dependencies.map(row => [row.name, row.was]))
+    return { ...held, dependencies: held.dependencies.map(row => was.has(row.name) ? { ...row, was: was.get(row.name), added: true } : row) }
+  }],
+  'unused-deps': ['held-unused-deps', (held, change) => {
+    const added = new Set(change.dependencies.map(row => `${row.kind ?? ''}\0${row.name}`))
+    return { ...held, dependencies: held.dependencies.map(row => added.has(`${row.kind ?? ''}\0${row.name}`) ? { ...row, added: true } : row) }
+  }],
+  ...Object.fromEntries([...HOST_TAGS.keys()].map(npmHostFinding).map(id => [id, [`held-${id}`, (held, change) => marked(held, byPath(change.files, 'added'))]])),
+}
+
+// Who published the open version and how, ahead of what it holds, as a
+// reviewer reads them; what else changed after it.
+const FIRST = new Set(['publisher', 'provenance-lost'])
+
+// What a version holds (`held`) with what changed against the one compared
+// with (`changed`) folded in, as one list in the order a reviewer reads it: a
+// publisher changed and provenance lost, what it holds, then the rest of what
+// changed. A change whose held finding is missing is kept as it is.
+export function npmCombinedFindings(held, changed) {
+  const combined = new Map(held.map(finding => [finding.id, finding]))
+  const rest = []
+  for (const change of changed) {
+    const [id, fold] = FOLDS[change.id] ?? []
+    const into = id && combined.get(id)
+    if (into) combined.set(id, { ...fold(into, change), severity: higher(into.severity, change.severity) })
+    else rest.push(change)
+  }
+  return [...rest.filter(({ id }) => FIRST.has(id)), ...combined.values(), ...rest.filter(({ id }) => !FIRST.has(id))]
+}