@preventive/triage 1.0.0-alpha.5 → 1.0.0-alpha.50

package/risk/npm/dependencies.js

@@ -0,0 +1,172 @@
+// What calls for a look among the dependencies a package version names: one
+// npm fetches from elsewhere than its registry, and one nothing of the
+// version imports, which npm installs all the same, running its install
+// scripts, as a dependency added to run them alone would be.
+import { isNpmPackageName } from '../../common/managed/npm-packages.js'
+import { NPM_PROSE } from '../files/readability.js'
+import { npmAlias, npmDependencySource, npmRegistrySpec } from './specs.js'
+import { npmInstallScripts } from './install-scripts.js'
+
+// The kinds of dependency a manifest names, by its field (npmDependencies).
+const NPM_DEPENDENCY_KINDS = [['dependencies', null], ['peerDependencies', 'peer'], ['optionalDependencies', 'optional']]
+
+// A version's dependencies, each `{ name, range, kind, opens }`, in name
+// order: `kind` null for a plain dependency, else 'peer' or 'optional';
+// `opens` the package the viewer opens for it, the one an `npm:` alias
+// names, or null when it names none, or where npm doesn't install it from
+// its registry (specs.js npmRegistrySpec: a path, a repository, a URL),
+// whose package of that name isn't what it installs.
+export function npmDependencies(manifest) {
+  const rows = []
+  for (const [field, kind] of NPM_DEPENDENCY_KINDS) {
+    for (const [name, range] of Object.entries(manifest?.[field] ?? {})) {
+      const opens = npmAlias(range)?.name ?? name
+      rows.push({ name, range, kind, opens: isNpmPackageName(opens) && npmRegistrySpec(range) ? opens : null })
+    }
+  }
+  return rows.toSorted((a, b) => a.name.localeCompare(b.name) || (a.kind ?? '').localeCompare(b.kind ?? ''))
+}
+
+// What two versions' dependencies differ in, by name and kind: those only
+// `base` has, those only `other` has, and those whose range changed.
+export function npmDependencyChanges(base, other) {
+  const index = manifest => new Map(npmDependencies(manifest).map(row => [`${row.kind ?? ''}\0${row.name}`, row]))
+  const after = index(other), before = index(base)
+  const added = [], changed = [], removed = []
+  for (const [key, { name, kind, range, opens }] of before) {
+    const next = after.get(key)
+    if (!next) removed.push({ key, name, kind, range, opens })
+    else if (next.range !== range) changed.push({ key, name, kind, from: range, to: next.range, opens: next.opens })
+  }
+  for (const [key, { name, kind, range, opens }] of after) if (!before.has(key)) added.push({ key, name, kind, range, opens })
+  return { removed, added, changed }
+}
+
+// Files no import is read from: prose, as the Overview tells it
+// (readability.js NPM_PROSE; not code named alike, as
+// `lib/history.js`), but MDX, which imports what it renders; source maps,
+// which quote whatever their sources import, and lockfiles, which name every
+// package installed; nor the package's own package.json, which names them all.
+const MDX = /\.mdx$/iu
+const NO_IMPORTS = /(?:\.map|(?:^|\/)(?:package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml))$/iu
+// A quote, then a run of the characters names and paths are made of (after
+// webpack's `~` too), and what ends it: a quote, escaped too, as a quote in
+// a quoted command is in binding.gyp (`require(\'nan\')`), or a template's `${`.
+const QUOTED = /["'`]~?([\w@./-]+)(\\?["'`]|\$\{)?/gu
+
+// What of a version names a package as an import would, once a version, in
+// one pass over its code files however many names are asked about: `whole`,
+// each name quoted alone or before a path in it (`'name'`, `"name/sub"`);
+// `parts`, each part of a name up to a `-` or `/` that a quote or a
+// template's `${` ends, as a package builds a name from one to pick the
+// build for the platform it runs on (`` `@rollup/rollup-${platform}` ``,
+// `"@typescript/" + name`); and `commands`, the install scripts npm runs.
+const importsByVersion = new WeakMap()
+function importsOf({ json, npm }) {
+  let found = importsByVersion.get(json)
+  if (found) return found
+  const sources = json.sources ?? [], texts = json.sourcesContent ?? []
+  found = { whole: new Set(), parts: new Set(), commands: npmInstallScripts(npm?.manifest, sources).map(([, command]) => command) }
+  for (const [i, path] of sources.entries()) {
+    if (typeof texts[i] !== 'string' || path === 'package.json' || (NPM_PROSE.test(path) && !MDX.test(path)) || NO_IMPORTS.test(path)) continue
+    for (const [, run, end] of texts[i].matchAll(QUOTED)) {
+      if (end && '-/'.includes(run.at(-1))) found.parts.add(run)
+      if (end && end !== '${') found.whole.add(run)
+      for (let at = run.indexOf('/'); at !== -1; at = run.indexOf('/', at + 1)) found.whole.add(run.slice(0, at))
+    }
+  }
+  importsByVersion.set(json, found)
+  return found
+}
+
+// Whether a command names `name`: as a word (`prebuild-install || node-gyp
+// rebuild`), or as the package installed in `node_modules` that a path
+// leads into (`node node_modules/name/setup.js`); not as part of another
+// path (`node scripts/name.js`, `node_modules/@scope/name`).
+function commandNames(command, name) {
+  for (let at = command.indexOf(name); at !== -1; at = command.indexOf(name, at + 1)) {
+    const before = command.slice(0, at)
+    if ((!/[\w@./-]$/u.test(before) || /node_modules\/(?:\.bin\/)?$/u.test(before)) && !/^[\w.-]/u.test(command.slice(at + name.length))) return true
+  }
+  return false
+}
+
+// DefinitelyTyped's stub of a package's types, once the package has types
+// of its own (`@types/mkdirp` 2.0.0), depending on that package, the
+// registry's by its name (`spec`, no `npm:` alias of another, no repository,
+// URL or path): named as DefinitelyTyped publishes the package's types
+// (`@types/name`, a scoped one's `@types/scope__name`), with nothing but
+// prose beside its package.json, no declarations of its own.
+const typesOf = name => `@types/${name.startsWith('@') ? name.slice(1).replace('/', '__') : name}`
+const typesStubOf = ({ json, npm }, name, spec) => npm?.name === typesOf(name) && npmRegistrySpec(spec) && (npmAlias(spec)?.name ?? name) === name
+  && (json.sources ?? []).every(path => path === 'package.json' || (NPM_PROSE.test(path) && !MDX.test(path)))
+
+// Whether nothing of a version (`details`, its files and manifest) imports
+// a dependency it names (`{ name, kind, range }`, or a changed one's `to`,
+// npm-package.js npmDependencies): no code file names it as an import
+// would, whole or by a part of it, nor does an install script npm runs
+// (importsOf); never where its files aren't read. Not a peer dependency,
+// which the package expects whoever installs it to provide, nor types from
+// DefinitelyTyped (`@types/`), imported by another name, where no one else
+// publishes; nor tslib, TypeScript's helpers, which a package compiled
+// with them inlined names all the same, as a third of popular packages
+// naming a dependency nothing imports do; each where npm installs that
+// package from its registry (installsAs), not another under its name
+// (`"tslib": "npm:other@1"`, a repository); nor the package a stub of
+// DefinitelyTyped's types of it depends on (typesStubOf), with no code to
+// import it.
+const installsAs = (name, spec) => npmRegistrySpec(spec) ? npmAlias(spec)?.name ?? name : null
+export function npmDependencyUnimported(details, { name, kind, range, to }) {
+  const installs = installsAs(name, to ?? range)
+  if (!details?.json || kind === 'peer' || (name.startsWith('@types/') && installs?.startsWith('@types/')) || (name === 'tslib' && installs === 'tslib')
+    || typesStubOf(details, name, to ?? range)) return false
+  const { whole, parts, commands } = importsOf(details)
+  return !whole.has(name) && ![...name.slice(1).matchAll(/[-/]/gu)].some(({ index }) => parts.has(name.slice(0, index + 2)))
+    && !commands.some(command => commandNames(command, name))
+}
+
+// Whether a dependency nothing of a version imports (`{ name, range }`,
+// npmDependencyUnimported) counts toward its risk (assess.js): not lodash,
+// which packages keep naming long after their code stopped importing it, nor
+// Babel's own presets (`@babel/preset-*`), which a config names by a string
+// (an ESLint config's parser options); each where npm installs that package
+// from its registry (installsAs), not another under its name.
+export function npmUnusedDependencyCounted({ name, range }) {
+  const installs = installsAs(name, range)
+  return !(name === 'lodash' && installs === 'lodash') && !(name.startsWith('@babel/preset-') && installs?.startsWith('@babel/preset-'))
+}
+
+// Where a source takes a dependency from, in a sentence.
+const SOURCE_NAMES = new Map([['URL', 'a URL'], ['git', 'a git repository']])
+
+// What calls for a look at a dependency a version (`details`) names
+// (`{ name, kind, range }`, or a changed one's `to`), as tags
+// (`{ check, label, tooltip }`): `source` where npm fetches it from
+// elsewhere than its registry (npmDependencySource), its spec in the
+// tooltip, and `unimported` where nothing of the version imports it
+// (npmDependencyUnimported). Against the specs another version named its
+// dependencies by (`was`, npmDependencySpecs), only where it named this one
+// by another spec, or, imported by nothing, not at all.
+export function npmDependencyFlags(details, row, was = null) {
+  const spec = row.to ?? row.range
+  const source = npmDependencySource(spec)
+  return [
+    ...source && was?.get(row.name) !== spec ? [{ check: 'source', label: 'non-registry', tooltip: `From ${SOURCE_NAMES.get(source) ?? source}, not npm's registry: ${spec}` }] : [],
+    ...!was?.has(row.name) && npmDependencyUnimported(details, row) ? [{ check: 'unimported', label: 'unimported',
+      tooltip: `${was ? `New in ${details.npm?.version}, and nothing of it` : `Nothing of ${details.npm?.version}`} imports it: no code file names it as an import would, nor does an install script` }] : [],
+  ]
+}
+
+// The specs a manifest names its dependencies by, by name, whatever their
+// kind.
+export const npmDependencySpecs = manifest => new Map(NPM_DEPENDENCY_KINDS.flatMap(([field]) => Object.entries(manifest?.[field] ?? {})))
+
+// Two versions' dependency changes (npm-package.js npmDependencyChanges),
+// each the open version (`other`) adds or changes with its `flags`
+// (npmDependencyFlags) against the one compared with (`base`), or alone,
+// none given.
+export function npmFlagDependencyChanges({ removed, added, changed }, base, other) {
+  const was = base ? npmDependencySpecs(base.npm?.manifest) : null
+  const flag = row => ({ ...row, flags: npmDependencyFlags(other, row, was) })
+  return { removed, added: added.map(flag), changed: changed.map(flag) }
+}

package/risk/npm/diff.js

@@ -0,0 +1,79 @@
+// How two versions' files differ, as Compare's diff has them
+// (ui/view/bundle-compare-diff.js computeBundleDiff), for risk's findings
+// (compare.js): the files the open version adds, and those it changes, a
+// build's content-hashed file paired with the one it replaces by its name
+// (hashedKey), and a file moved to another path with its old one by content,
+// as git diff -M pairs them (@preventive/compare compareTrees).
+import { compareTrees } from '@preventive/compare'
+import { bundleFilesAsMap } from '../../common/bundle-sources.js'
+
+// git's diff.renameLimit for a package's renames: past this many removed files
+// by added ones, squared, no pair is scored, and only identical content pairs
+// them.
+const RENAME_LIMIT = 250
+
+// Whether two sides hold the same file: text as text, one that isn't by its
+// digest (bundle-compare-diff.js sameContent).
+const same = (a, b) => a === b || (a?.format === 'digest' && b?.format === 'digest' && a.digest === b.digest)
+
+// A file's content as compareTrees reads it to find renames: its text, its
+// digest for one that isn't, or else its place in its list, so that only its
+// path pairs it (bundle-compare-diff.js treeData).
+const treeData = (content, at) => typeof content === 'string' ? `\0text\0${content.toWellFormed()}`
+  : content?.format === 'digest' ? `\0digest\0${content.digest}` : `\0none\0${at}`
+
+// A build's content-hashed file (`assets/index-CyWAfh-p.js`, Vite's and
+// Rollup's `[name]-[hash]`, webpack's `[name].[contenthash].js`) by its name
+// but its hash, `assets/index\0.js`: a release renames it as its content
+// changes, the same file. Null for a name whose last part before its
+// extension is no hash: 8 to 32 of base64url's characters with a letter, and
+// a digit or a capital, as neither a lowercase word (`index-client.js`,
+// `lodash.debounce.js`) nor a number (a date, `migration-20240101.js`) is. Its hash its last 8 or more such characters, so that chunks named
+// after a module (`vendor-react-DQ4mN2sx.js`) pair each with its own; a
+// longer hash holding a `-` (Rollup's `[hash:16]`) is cut there, so that a
+// rebuild pairs by its content alone, as its parts aren't told from a
+// chunk's name's (`vendor-ui-…`) without it.
+const HASHED_NAME = /^(.+)[-.]([\w-]{8,32})((?:\.[A-Za-z\d]+)+)$/u
+function hashedKey(path) {
+  const at = path.lastIndexOf('/') + 1
+  const [, stem, hash, extension] = HASHED_NAME.exec(path.slice(at)) ?? []
+  if (!hash || !/[A-Za-z]/u.test(hash) || !/[\dA-Z]/u.test(hash)) return null
+  return `${path.slice(0, at)}${stem}\0${extension}`
+}
+
+// `onlyOther`, the files the open version (`other`) adds, `{ path }` each, and
+// `changed`, those it changes, `{ path, modified }`, or moves, `{ path,
+// renamedFrom, modified }`, `modified` whether its content changed too; each
+// version as compare.js takes one. A file that isn't text is
+// told by its digest (npmBinaries), as the viewer's Compare tells it.
+export function npmFilesDiff(base, other) {
+  const after = bundleFilesAsMap(other), before = bundleFilesAsMap(base)
+  const changed = [], onlyBase = [], onlyOther = []
+  for (const [path, text] of after) {
+    if (!before.has(path)) onlyOther.push(path)
+    else if (!same(before.get(path), text)) changed.push({ path, modified: true })
+  }
+  for (const path of before.keys()) if (!after.has(path)) onlyBase.push(path)
+  // A content-hashed file added where one by the same name but its hash
+  // (hashedKey) is removed, one each, is that file changed, as a build
+  // renames it: what it runs, how it reads and how large it is told against
+  // it, not all of it new.
+  const hashed = paths => Map.groupBy(paths.filter(hashedKey), hashedKey)
+  const moved = new Set(), removed = hashed(onlyBase)
+  for (const [key, paths] of hashed(onlyOther)) {
+    const was = removed.get(key)
+    if (paths.length !== 1 || was?.length !== 1) continue
+    changed.push({ path: paths[0], renamedFrom: was[0], modified: !same(before.get(was[0]), after.get(paths[0])) })
+    moved.add(paths[0])
+  }
+  // The rest by content, against every file removed: one paired by its name
+  // may be another's too, a build's copy of it elsewhere.
+  const entries = (paths, files, side) => paths.filter(path => path.isWellFormed()).map((path, at) => ({ name: path, data: treeData(files.get(path), `${side}${at}`) }))
+  const renames = compareTrees(entries(onlyBase, before, 'a'), entries(onlyOther.filter(path => !moved.has(path)), after, 'b'), { paths: 'keys', renameLimit: RENAME_LIMIT, lines: false })
+    .filter(change => change.status === 'renamed')
+  for (const change of renames) {
+    changed.push({ path: change.new.path, renamedFrom: change.old.path, modified: change.similarity !== 100 })
+    moved.add(change.new.path)
+  }
+  return { onlyOther: onlyOther.filter(path => !moved.has(path)).map(path => ({ path })), changed }
+}

package/risk/npm/downloads.js

@@ -0,0 +1,84 @@
+// A package's downloads, as npm's downloads API counts them a day
+// (`{ start, end, days }`, the first day's date and a count a day from it):
+// in weeks and months, the tier among npm's packages they put it in, and a
+// dependency's to the day before its latest two weeks.
+
+export const DAY_MS = 24 * 60 * 60_000
+// The date `offset` days past a count's first day (`start`).
+export const dayOf = (start, offset) => new Date(Date.parse(start) + offset * DAY_MS)
+
+// The downloads in 7-day weeks ending on the last day, oldest first, a
+// partial oldest week left out: `{ from, to, total }`, dates as `Date`s.
+export function npmDownloadWeeks(downloads) {
+  const weeks = []
+  if (!downloads?.days) return weeks
+  for (let end = downloads.days.length - 1; end >= 6; end -= 7) {
+    let total = 0
+    for (let day = end - 6; day <= end; day++) total += downloads.days[day]
+    weeks.push({ from: dayOf(downloads.start, end - 6), to: dayOf(downloads.start, end), total })
+  }
+  return weeks.toReversed()
+}
+
+// The downloads in calendar months (UTC), oldest first, the partial months
+// at either end left out: `{ from, to, total }`, as npmDownloadWeeks has them.
+export function npmDownloadMonths(downloads) {
+  const months = []
+  if (!downloads?.days) return months
+  const start = Date.parse(downloads.start)
+  let month = null
+  downloads.days.forEach((count, i) => {
+    const day = new Date(start + i * DAY_MS)
+    if (day.getUTCDate() === 1) {
+      month = { from: day, to: day, total: 0 }
+      months.push(month)
+    }
+    if (month) { month.total += count; month.to = day }
+  })
+  const last = months.at(-1)
+  if (last && new Date(last.to.getTime() + DAY_MS).getUTCDate() !== 1) months.pop()
+  return months
+}
+
+// The weekly downloads from which a package is among npm's top 10, 20, 50,
+// 100, …, 100,000 packages, rounded: download-counts' snapshot of a month's
+// downloads (Jan 30 – Feb 28, 2026), each rank's count grown by the median
+// growth of the packages ranked around it to the 30 days Sep 9 – Oct 8,
+// 2026, as npm counts them, days it failed to count among them, then made a
+// week. An estimate, to be revisited. Below the last, a package is
+// unpopular (Infinity).
+const TIERS = [
+  [10, 550e6], [20, 405e6], [50, 285e6], [100, 225e6], [200, 165e6], [500, 95e6], [1000, 50e6], [2000, 20e6], [5000, 4e6],
+  [10_000, 850e3], [20_000, 155e3], [50_000, 18e3], [100_000, 2e3], [Infinity, 0],
+]
+
+// The tier a package's downloads put it in (TIERS), by the most it had in any
+// of its latest six 7-day weeks (npmDownloadWeeks): a week lower for a day
+// npm failed to count, as it now and then does, or for a holiday, is passed
+// over. Infinity for an unpopular one; null without a week.
+export function npmDownloadTier(downloads) {
+  const latest = npmDownloadWeeks(downloads).slice(-6)
+  if (latest.length === 0) return null
+  const most = Math.max(...latest.map(week => week.total))
+  return TIERS.find(([, from]) => most >= from)[0]
+}
+
+// A tier's name, and its tint: solid green to the top 200, green to the top
+// 5,000, yellow to the top 20,000, orange to the top 100,000, and red for
+// the unpopular, a package few would notice changing.
+export const npmTierLevel = tier => tier <= 200 ? 'is-solid' : tier <= 5000 ? 'is-top' : tier <= 20_000 ? 'is-mid' : tier <= 100_000 ? 'is-low' : 'is-unpopular'
+// A dependency's downloads to the day before its latest two weeks: a
+// package a release just pulled in, as a compromised one depending on it
+// would, could owe those to that release alone. Its own package's tier goes
+// by all of them, its Overview charting them.
+const DEPENDENCY_DAYS_LEFT_OUT = 14
+export function npmSettledDownloads(downloads, now = Date.now()) {
+  if (!downloads) return null
+  const first = Math.floor(Date.parse(downloads.start) / DAY_MS), last = Math.floor(now / DAY_MS) - 1 - DEPENDENCY_DAYS_LEFT_OUT
+  const days = downloads.days.slice(0, Math.max(0, last - first + 1))
+  return { start: downloads.start, end: new Date((first + days.length - 1) * DAY_MS).toISOString().slice(0, 10), days }
+}
+
+// A tier orange or red, past the top 20,000: one few would notice changing,
+// as a release past the top 20,000 is flagged (compare.js).
+export const npmTierLow = tier => tier > 20_000