@exodus/stasis 1.0.0-beta.3 → 1.0.0-beta.6

package/src/loaders/paths.js

@@ -0,0 +1,33 @@
+// Path checks shared by the source-language loaders.
+
+import { isAbsolute, relative, resolve } from 'node:path'
+
+import { relativeEscapes, toPosix } from '@exodus/stasis-core/util'
+
+// Reject absolute and `..`-escaping paths in a `.<lang>.txt` listing so a malicious or sloppy
+// listing can't read files outside the listing's own directory.
+export function assertWithinBase(baseDir, candidate, label) {
+  if (isAbsolute(candidate)) throw new Error(`${label} must not be absolute: ${candidate}`)
+  const rel = toPosix(relative(baseDir, resolve(baseDir, candidate)))
+  if (relativeEscapes(rel)) {
+    throw new Error(`${label} escapes baseDir: ${candidate}`)
+  }
+}
+
+// Apply `segments` on `fromFile`'s directory, resolving '.'/'..'. Returns a baseDir-relative POSIX
+// path ('' for baseDir itself), or null when traversal escapes the root.
+export function applyToDir(fromFile, segments) {
+  const fromDir = fromFile.includes('/') ? fromFile.slice(0, fromFile.lastIndexOf('/')) : ''
+  const parts = [...(fromDir ? fromDir.split('/') : []), ...segments]
+  const resolved = []
+  for (const part of parts) {
+    if (part === '.' || part === '') continue
+    if (part === '..') {
+      if (resolved.length === 0) return null
+      resolved.pop()
+    } else {
+      resolved.push(part)
+    }
+  }
+  return resolved.join('/')
+}

package/src/loaders/php.js

@@ -3,11 +3,18 @@
 // (unresolved -> `missing`); Composer-autoloaded class refs are best-effort
 // (unresolved -> silently skipped).
 
-import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { isUtf8 } from 'node:buffer'
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import { isDeepStrictEqual } from 'node:util'
 
-import { assertRealPathWithinBase } from '@exodus/stasis-core/util'
+import { assertRealPathWithinBase, isPlainObject, relativeEscapes, toPosix } from '@exodus/stasis-core/util'
+import { LockfileError, parseComposerLock } from '@preventive/lockfile/composer.js'
+import { isDir, isFile } from '../resolve-typescript.js'
+import { applyToDir } from './paths.js'
+import { readUtf8OrNull } from './solidity-ownership.js'
+import { nameErrors } from './toml.js'
 
 // Cap concurrent reads per wave to avoid EMFILE on large directory globs.
 const READ_CONCURRENCY = 64
@@ -120,6 +127,10 @@ function stringLiterals(code) {
   return out
 }
 
+// Whether `pos` is inside one of `strings` (stringLiterals), and the literal starting at `pos`.
+const inString = (strings, pos) => strings.some(({ start, end }) => pos > start && pos < end)
+const stringAt = (strings, pos) => strings.find(({ start }) => start === pos)
+
 // Include keyword. The lookbehind rejects method/scope-resolution calls
 // (`$x->require`, `Foo::include`); the trailing `\b` stops matching inside
 // `requireConfig`. String-literal matches are filtered out by the caller.
@@ -165,13 +176,16 @@ function matchDirAnchor(code, pos) {
   return { end: PHP_DIR_ANCHOR_RE.lastIndex, up }
 }
 
+// A `./`/`../` specifier, as PHP tells one (a `.`-led NAME like `..cache/a.php` is a bare one).
+const isDotRelative = (spec) => spec === '.' || spec === '..' || spec.startsWith('./') || spec.startsWith('../')
+
 // Normalise an include path to a specifier. Dir-relative paths get a `./` prefix
 // with the leading separator stripped; empty means the file's own dir (`.`).
 function normalizeIncludePath(raw, dirRelative) {
   if (!dirRelative) return raw
   const rel = raw.replace(/^\/+/u, '')
   if (rel === '') return '.'
-  return rel.startsWith('.') ? rel : `./${rel}`
+  return isDotRelative(rel) ? rel : `./${rel}`
 }
 
 // Parse an include/path argument at `start`: an optional directory anchor then a
@@ -179,7 +193,6 @@ function normalizeIncludePath(raw, dirRelative) {
 // `dynamic` at the first variable/function/constant/interpolation; `prefix` is
 // the static path up to there. Returns null with neither anchor nor static string.
 function parseArgPath(code, start, strings) {
-  const stringAt = (pos) => strings.find(({ start: s }) => s === pos)
   let i = start
   let dirRelative = false
   let up = 0
@@ -196,7 +209,7 @@ function parseArgPath(code, start, strings) {
   let dynamic = false
   let sawStatic = false
   for (;;) {
-    const lit = stringAt(i)
+    const lit = stringAt(strings, i)
     if (!lit) { dynamic = true; break }
     const interp = lit.quote === '"' ? lit.value.search(PHP_INTERPOLATION_RE) : -1
     if (interp >= 0) { prefix += lit.value.slice(0, interp); sawStatic = true; dynamic = true; break }
@@ -216,11 +229,10 @@ function parseArgPath(code, start, strings) {
 function scanIncludes(content) {
   const code = maskCommentsAndHeredocs(content)
   const strings = stringLiterals(code)
-  const inString = (pos) => strings.some(({ start, end }) => pos > start && pos < end)
 
   const out = []
   for (const m of code.matchAll(PHP_INCLUDE_KEYWORD_RE)) {
-    if (inString(m.index)) continue
+    if (inString(strings, m.index)) continue
     let i = skipWs(code, m.index + m[0].length)
     if (code[i] === '(') i = skipWs(code, i + 1)
     const arg = parseArgPath(code, i, strings)
@@ -247,13 +259,11 @@ function scanIncludes(content) {
 function scanPathLiterals(content) {
   const code = maskCommentsAndHeredocs(content)
   const strings = stringLiterals(code)
-  const inString = (pos) => strings.some(({ start, end }) => pos > start && pos < end)
-  const stringAt = (pos) => strings.find(({ start }) => start === pos)
 
   const out = []
   // Dir-anchored literals: `__DIR__ . '/x.php'` (resolve against the file).
   for (const m of code.matchAll(PHP_DIR_ANCHOR_FIND_RE)) {
-    if (inString(m.index)) continue
+    if (inString(strings, m.index)) continue
     const arg = parseArgPath(code, m.index, strings)
     if (!arg || arg.dynamic || !arg.sawStatic || !arg.dirRelative) continue
     const spec = normalizeIncludePath(arg.prefix, true)
@@ -261,8 +271,8 @@ function scanPathLiterals(content) {
   }
   // Laravel path helpers: `base_path('routes/web.php')` (resolve against project root).
   for (const m of code.matchAll(PHP_PATH_HELPER_FIND_RE)) {
-    if (inString(m.index)) continue
-    const lit = stringAt(skipWs(code, m.index + m[0].length))
+    if (inString(strings, m.index)) continue
+    const lit = stringAt(strings, skipWs(code, m.index + m[0].length))
     if (!lit || (lit.quote === '"' && PHP_INTERPOLATION_RE.test(lit.value))) continue
     const sub = PHP_PATH_HELPERS.get(m[1].toLowerCase())
     const arg = lit.value.replace(/^\/+/u, '')
@@ -272,15 +282,17 @@ function scanPathLiterals(content) {
   return out
 }
 
+const includeSpecs = (includes, kind) => includes.filter((e) => e.kind === kind).map((e) => e.spec)
+
 // Statically-resolvable include specifiers (concrete files). See scanIncludes.
 export function extractPhpImports(content) {
-  return scanIncludes(content).filter((e) => e.kind === 'file').map((e) => e.spec)
+  return includeSpecs(scanIncludes(content), 'file')
 }
 
 // Directory specifiers for dynamic includes; every `.php` file directly inside is
 // a candidate target.
 export function extractPhpImportDirs(content) {
-  return scanIncludes(content).filter((e) => e.kind === 'dir').map((e) => e.spec)
+  return includeSpecs(scanIncludes(content), 'dir')
 }
 
 // `.php` path literals used outside a `require` -- dir-anchored (`anchor: 'file'`)
@@ -295,55 +307,35 @@ export function extractPhpPathRefs(content) {
   })
 }
 
-// Apply `segments` on `fromFile`'s directory, resolving '.'/'..'. Returns a
-// baseDir-relative POSIX path, or null when traversal escapes the root.
-function applyToDir(fromFile, segments) {
-  const fromDir = fromFile.includes('/') ? fromFile.slice(0, fromFile.lastIndexOf('/')) : ''
-  const parts = [...(fromDir ? fromDir.split('/') : []), ...segments]
-  const resolved = []
-  for (const part of parts) {
-    if (part === '.' || part === '') continue
-    if (part === '..') {
-      if (resolved.length === 0) return null
-      resolved.pop()
-    } else {
-      resolved.push(part)
-    }
-  }
-  return resolved.join('/')
-}
+const isFileOnDisk = (baseDir, rel) => isFile(join(baseDir, rel))
+const isDirOnDisk = (baseDir, rel) => isDir(join(baseDir, rel))
 
-function isFileOnDisk(baseDir, rel) {
-  try {
-    return statSync(join(baseDir, rel)).isFile()
-  } catch {
-    return false
-  }
+// Throws on a path holding `\`: no separator to PHP off Windows but part of a name, and stasis
+// refuses such a name rather than resolve it, or take it for another path. `from`: the includer.
+function refuseBackslash(path, from) {
+  if (path.includes('\\')) throw new Error(`[loader.php] path holds a '\\', which stasis refuses: ${path}${from ? ` (from ${from})` : ''}`)
 }
 
-function isDirOnDisk(baseDir, rel) {
-  try {
-    return statSync(join(baseDir, rel)).isDirectory()
-  } catch {
-    return false
-  }
+// `abs` as a baseDir-relative POSIX path ('' for baseDir itself), or null when it escapes the root.
+function projectRel(baseDir, abs) {
+  const rel = toPosix(relative(baseDir, abs))
+  return relativeEscapes(rel) ? null : rel
 }
 
 // Resolve a directory specifier to an existing baseDir-relative dir, or null.
 // `./`/`../` resolve against the including file; a bare spec tries file- then
 // project-relative.
 export function resolvePhpDir(spec, fromFile, baseDir) {
-  if (spec.startsWith('.')) {
+  refuseBackslash(spec, fromFile)
+  if (isDotRelative(spec)) {
     const rel = applyToDir(fromFile, spec.split('/'))
     return rel !== null && isDirOnDisk(baseDir, rel) ? rel : null
   }
   if (baseDir && !isAbsolute(spec)) {
     const fileRel = applyToDir(fromFile, spec.split('/'))
     if (fileRel && isDirOnDisk(baseDir, fileRel)) return fileRel
-    const projRel = relative(baseDir, resolve(baseDir, spec)).split(/[\\/]/u).join('/')
-    if (projRel !== '' && !projRel.startsWith('..') && !isAbsolute(projRel) && isDirOnDisk(baseDir, projRel)) {
-      return projRel
-    }
+    const projRel = projectRel(baseDir, resolve(baseDir, spec))
+    if (projRel && isDirOnDisk(baseDir, projRel)) return projRel
   }
   return null
 }
@@ -363,9 +355,11 @@ function listPhpFiles(baseDir, dir) {
 // Resolve a PHP include specifier to a baseDir-relative POSIX path. `./`/`../`
 // resolve against the including file (escaping the root -> null); a bare specifier
 // tries a file next to the includer, then project-root-relative. Absolute
-// specifiers are rejected. Returns null when nothing resolves.
+// specifiers are rejected. Returns null when nothing resolves. One holding `\` throws
+// (see refuseBackslash).
 export function resolvePhpImport(specifier, fromFile, { baseDir } = {}) {
-  if (specifier.startsWith('.')) {
+  refuseBackslash(specifier, fromFile)
+  if (isDotRelative(specifier)) {
     return applyToDir(fromFile, specifier.split('/'))
   }
 
@@ -373,10 +367,8 @@ export function resolvePhpImport(specifier, fromFile, { baseDir } = {}) {
     const fileRel = applyToDir(fromFile, specifier.split('/'))
     if (fileRel && isFileOnDisk(baseDir, fileRel)) return fileRel
 
-    const projRel = relative(baseDir, resolve(baseDir, specifier)).split(/[\\/]/u).join('/')
-    if (projRel !== '' && !projRel.startsWith('..') && !isAbsolute(projRel) && isFileOnDisk(baseDir, projRel)) {
-      return projRel
-    }
+    const projRel = projectRel(baseDir, resolve(baseDir, specifier))
+    if (projRel && isFileOnDisk(baseDir, projRel)) return projRel
   }
 
   return null
@@ -385,12 +377,11 @@ export function resolvePhpImport(specifier, fromFile, { baseDir } = {}) {
 // Normalise a project-root-relative autoload path to POSIX baseDir-relative, or
 // null when it escapes root. Re-derives via resolve() so interior `..` escapes
 // (`src/foo/../../../secret.php`) are caught -- a leading-`..`/absolute check
-// alone would let files outside the project into the bundle.
+// alone would let files outside the project into the bundle. One holding `\`
+// throws (see refuseBackslash).
 function normalizeProjectRel(baseDir, p) {
-  const rel = relative(baseDir, resolve(baseDir, p.replace(/\\/gu, '/'))).split(/[\\/]/u).join('/')
-  if (rel === '') return ''
-  if (rel.startsWith('..') || isAbsolute(rel)) return null
-  return rel
+  refuseBackslash(p)
+  return projectRel(baseDir, resolve(baseDir, p))
 }
 
 // Evaluate a generated-autoload path expr (`$baseDir . '/src'`, a bare quoted
@@ -453,13 +444,127 @@ function readJsonIfExists(file) {
   }
 }
 
+// The root composer.json (null when absent or unparsable) and its baseDir-relative vendor dir.
+function readComposerJson(baseDir) {
+  const composerJson = readJsonIfExists(join(baseDir, 'composer.json'))
+  const vendorDir = normalizeProjectRel(baseDir, composerJson?.config?.['vendor-dir'] ?? 'vendor') ?? 'vendor'
+  return { composerJson, vendorDir }
+}
+
+// The packages `vendor/composer/installed.json` lists, in the Composer 2 ({ packages }) or
+// Composer 1 (flat array) shape.
+function readInstalledPackages(baseDir, vendorDir) {
+  const json = readJsonIfExists(join(baseDir, vendorDir, 'composer', 'installed.json'))
+  return Array.isArray(json) ? json : (json?.packages ?? [])
+}
+
+// JSON `text` with each integer as PHP holds it: one past ±(2^53 − 1) a BigInt, as
+// @preventive/lockfile reads one, so two values compare equal only where PHP's do.
+const parseJsonExact = (text) => JSON.parse(text, (key, value, { source }) =>
+  (typeof value === 'number' && !Number.isSafeInteger(value) && /^-?\d+$/u.test(source) ? BigInt(source) : value))
+
+// Where installed.json says Composer installed package `p`, baseDir-relative: its install-path,
+// from vendor/composer (null for none, as of a metapackage), or <vendor-dir>/<name> where it gives
+// none (Composer 1's); null outside baseDir.
+function installedDir(baseDir, vendorDir, p) {
+  const path = p['install-path']
+  if (path === undefined) return projectRel(baseDir, resolve(baseDir, vendorDir, p.name))
+  return typeof path === 'string' ? projectRel(baseDir, resolve(baseDir, vendorDir, 'composer', path)) : null
+}
+
+// Where Composer's library installer puts a package of the lockfile, baseDir-relative
+// (LibraryInstaller::getInstallPath): <vendor-dir>/<name>, under its target-dir where it has one; a
+// metapackage nowhere (null). One of a type an installer plugin takes (composer/installers') goes
+// elsewhere, where its own composer.json's name finds it.
+function lockedDir(baseDir, vendorDir, p) {
+  return p.type === 'metapackage' ? null : projectRel(baseDir, resolve(baseDir, vendorDir, p.name, p.targetDir ?? ''))
+}
+
+// What Composer adds to a package of the lockfile as it installs it, in installed.json.
+const INSTALL_FIELDS = new Set(['version_normalized', 'installation-source', 'install-path'])
+
+// That vendor/composer/installed.json (`installedText`, at `installedFile`) is the install of
+// composer.lock (`lockText`, read by @preventive/lockfile already): as Composer 2 writes it,
+// `{ packages, dev, dev-package-names }`; each package of the lockfile's `packages`, and of its
+// `packages-dev` where it was installed with dev, there once and exactly as locked but for
+// INSTALL_FIELDS, and nothing else; and the names of those of `packages-dev`, in lowercase and
+// sorted, as dev-package-names. Throws where not. Returns the installed.json.
+function assertInstalledAsLocked(lockText, installedText, { installedFile, vendorDir }) {
+  const differ = (detail) => new Error(`${installedFile} is not the install of composer.lock: ${detail}${vendorDir ? `; remove ${vendorDir} and run \`composer install\`` : ''}`)
+  let installed
+  try {
+    installed = parseJsonExact(installedText)
+  } catch {
+    throw new Error(`${installedFile}: not JSON`) // without the parser's message, which quotes the text
+  }
+  const shape = ['packages', 'dev', 'dev-package-names']
+  if (!isPlainObject(installed) || Object.keys(installed).length !== shape.length || !shape.every((key) => Object.hasOwn(installed, key)) ||
+    !Array.isArray(installed.packages) || typeof installed.dev !== 'boolean' || !Array.isArray(installed['dev-package-names'])) {
+    throw differ(`it is not as Composer 2 writes one, { ${shape.join(', ')} }`)
+  }
+
+  const lock = parseJsonExact(lockText)
+  const locked = new Map()
+  for (const [key, dev] of [['packages', false], ['packages-dev', true]]) {
+    for (const spec of lock[key]) locked.set(spec.name, { spec, dev })
+  }
+  const seen = new Set()
+  for (const [index, entry] of installed.packages.entries()) {
+    if (!isPlainObject(entry) || typeof entry.name !== 'string') throw differ(`packages[${index}] is not a package`)
+    const { name } = entry
+    const want = locked.get(name)
+    if (want === undefined) throw differ(`${JSON.stringify(name)} is installed, and not locked`)
+    if (seen.has(name)) throw differ(`${name} is installed twice`)
+    seen.add(name)
+    if (want.dev && !installed.dev) throw differ(`${name} is installed, and locked in packages-dev, which an install without dev leaves out`)
+    const spec = Object.fromEntries(Object.entries(entry).filter(([key]) => !INSTALL_FIELDS.has(key)))
+    const key = [...new Set([...Object.keys(spec), ...Object.keys(want.spec)])].find((k) => !isDeepStrictEqual(spec[k], want.spec[k]))
+    if (key === 'version' && typeof spec.version === 'string') throw differ(`${name} is installed at ${JSON.stringify(spec.version)}, and locked at ${want.spec.version}`)
+    // `composer install` takes a package installed at the version and reference locked as it is,
+    // whatever else of it the lockfile changes.
+    if (key !== undefined) throw differ(`${name}'s ${JSON.stringify(key)} is not as locked`)
+  }
+  for (const [name, { dev }] of locked) {
+    if (!seen.has(name) && (installed.dev || !dev)) throw differ(`${name} is locked, and not installed`)
+  }
+  const devNames = [...locked].filter(([, { dev }]) => dev && installed.dev).map(([name]) => name.toLowerCase()).toSorted()
+  if (!isDeepStrictEqual(installed['dev-package-names'], devNames)) throw differ("its dev-package-names are not the names of the lockfile's packages-dev installed")
+  return installed
+}
+
+// The Composer packages of the project at `baseDir`, `[{ name, version, dir, extra }]`, `dir` where
+// the package is installed, baseDir-relative (null for nowhere in baseDir, as a metapackage). Of
+// its composer.lock where there is one, read by @preventive/lockfile beside composer.json as
+// `composer install` reads them -- one it refuses stops the build -- each package where Composer
+// installs it (lockedDir), so no install is needed; else of vendor/composer/installed.json, as
+// it is. Where both are, installed.json must be the lockfile's install (assertInstalledAsLocked):
+// its packages, each where installed.json says.
+export function loadComposerPackages(baseDir) {
+  const { vendorDir } = readComposerJson(baseDir)
+  const lockText = readUtf8OrNull(join(baseDir, 'composer.lock'), 'composer.lock')
+  if (lockText === null) {
+    return readInstalledPackages(baseDir, vendorDir)
+      .filter((p) => p?.name && p.version)
+      .map((p) => ({ name: p.name, version: p.version, dir: installedDir(baseDir, vendorDir, p), extra: p.extra }))
+  }
+
+  const composerJson = readUtf8OrNull(join(baseDir, 'composer.json'), 'composer.json')
+  const lock = nameErrors('composer.lock', () => parseComposerLock(lockText, composerJson === null ? {} : { composerJson }), [LockfileError])
+  const installedFile = toPosix(join(vendorDir, 'composer', 'installed.json'))
+  const installedText = readUtf8OrNull(join(baseDir, installedFile), installedFile)
+  const installed = installedText === null ? null : assertInstalledAsLocked(lockText, installedText, { installedFile, vendorDir })
+  const dirs = installed === null ? null : new Map(installed.packages.map((p) => [p.name, installedDir(baseDir, vendorDir, p)]))
+  return Object.values(lock.packages)
+    .filter((p) => dirs === null || dirs.has(p.name))
+    .map((p) => ({ name: p.name, version: p.version, dir: dirs === null ? lockedDir(baseDir, vendorDir, p) : dirs.get(p.name), extra: p.extra }))
+}
+
 // Build the autoload config for `baseDir`, merging the root composer.json
 // `autoload`(+dev) with the generated `vendor/composer/autoload_*` maps. All
 // paths normalised to POSIX baseDir-relative (escapers dropped). Returns
 // `{ psr4, psr0, classmap, files }`, or null when no Composer config is found.
 export function loadComposerAutoload(baseDir) {
-  const composerJson = readJsonIfExists(join(baseDir, 'composer.json'))
-  const vendorDir = normalizeProjectRel(baseDir, composerJson?.config?.['vendor-dir'] ?? 'vendor') ?? 'vendor'
+  const { composerJson, vendorDir } = readComposerJson(baseDir)
 
   const psr4 = new Map()
   const psr0 = new Map()
@@ -467,6 +572,7 @@ export function loadComposerAutoload(baseDir) {
   const files = new Set()
   let found = false
 
+  const mergeDirs = (map, prefix, dirs) => map.set(prefix, [...new Set([...(map.get(prefix) ?? []), ...dirs])])
   const addPrefixDirs = (map, prefix, paths) => {
     const list = Array.isArray(paths) ? paths : [paths]
     const dirs = []
@@ -474,8 +580,7 @@ export function loadComposerAutoload(baseDir) {
       const rel = normalizeProjectRel(baseDir, String(p))
       if (rel !== null) dirs.push(rel)
     }
-    const prev = map.get(prefix) ?? []
-    map.set(prefix, [...new Set([...prev, ...dirs])])
+    mergeDirs(map, prefix, dirs)
   }
 
   // Root composer.json autoload (+ dev). PSR-4 keys keep their trailing '\'.
@@ -493,37 +598,26 @@ export function loadComposerAutoload(baseDir) {
   // Generated maps. `$vendorDir` = <baseDir>/<vendorDir>, `$baseDir` = <baseDir>.
   const composerGenDir = join(baseDir, vendorDir, 'composer')
   const vars = { baseDir: resolve(baseDir), vendorDir: resolve(baseDir, vendorDir) }
-  const toRel = (abs) => {
-    const rel = relative(baseDir, abs).split(/[\\/]/u).join('/')
-    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel) ? rel : null
-  }
-  const mergePrefixMap = (file, target) => {
-    if (!existsSync(file)) return
+  const toRel = (abs) => projectRel(baseDir, abs) || null
+  // A generated map's entries; none when the file is absent.
+  const generated = (name, multi) => {
+    const file = join(composerGenDir, name)
+    if (!existsSync(file)) return new Map()
     found = true
-    for (const [prefix, dirs] of parseGeneratedMap(readFileSync(file, 'utf8'), vars, true)) {
-      const rels = dirs.map(toRel).filter((d) => d !== null).map((d) => d.replace(/\/+$/u, ''))
-      const prev = target.get(prefix) ?? []
-      target.set(prefix, [...new Set([...prev, ...rels])])
-    }
+    return parseGeneratedMap(readFileSync(file, 'utf8'), vars, multi)
   }
-  mergePrefixMap(join(composerGenDir, 'autoload_psr4.php'), psr4)
-  mergePrefixMap(join(composerGenDir, 'autoload_namespaces.php'), psr0)
-
-  const classmapFile = join(composerGenDir, 'autoload_classmap.php')
-  if (existsSync(classmapFile)) {
-    found = true
-    for (const [fqcn, abs] of parseGeneratedMap(readFileSync(classmapFile, 'utf8'), vars, false)) {
-      const rel = toRel(abs)
-      if (rel) classmap.set(fqcn.replace(/^\\+/u, ''), rel)
+  for (const [name, target] of [['autoload_psr4.php', psr4], ['autoload_namespaces.php', psr0]]) {
+    for (const [prefix, dirs] of generated(name, true)) {
+      mergeDirs(target, prefix, dirs.map(toRel).filter((d) => d !== null).map((d) => d.replace(/\/+$/u, '')))
     }
   }
-  const filesFile = join(composerGenDir, 'autoload_files.php')
-  if (existsSync(filesFile)) {
-    found = true
-    for (const [, abs] of parseGeneratedMap(readFileSync(filesFile, 'utf8'), vars, false)) {
-      const rel = toRel(abs)
-      if (rel) files.add(rel)
-    }
+  for (const [fqcn, abs] of generated('autoload_classmap.php', false)) {
+    const rel = toRel(abs)
+    if (rel) classmap.set(fqcn.replace(/^\\+/u, ''), rel)
+  }
+  for (const [, abs] of generated('autoload_files.php', false)) {
+    const rel = toRel(abs)
+    if (rel) files.add(rel)
   }
 
   if (!found) return null
@@ -573,30 +667,21 @@ function matchingPrefixes(map, name) {
   return [...map].filter(([prefix]) => name.startsWith(prefix)).toSorted((a, b) => b[0].length - a[0].length)
 }
 
-// Read installed-package versions from `vendor/composer/installed.json` (the
-// authoritative source; a package's own composer.json usually omits `version`).
-// Handles the Composer 2 ({ packages }) and Composer 1 (flat array) shapes.
-function loadInstalledVersions(baseDir, vendorDir) {
-  const json = readJsonIfExists(join(baseDir, vendorDir, 'composer', 'installed.json'))
+// The versions of the Composer `packages` (loadComposerPackages: the authoritative source; a
+// package's own composer.json usually omits `version`), by where each is installed and by name.
+function packageVersions(packages) {
   const byDir = new Map()
   const byName = new Map()
-  const packages = Array.isArray(json) ? json : (json?.packages ?? [])
-  for (const p of packages) {
-    if (!p?.name || !p.version) continue
-    byName.set(p.name, p.version)
-    // install-path is relative to vendor/composer; default layout is vendor/<name>.
-    const abs = p['install-path']
-      ? resolve(baseDir, vendorDir, 'composer', p['install-path'])
-      : resolve(baseDir, vendorDir, p.name)
-    const rel = relative(baseDir, abs).split(/[\\/]/u).join('/')
-    if (rel && !rel.startsWith('..') && !isAbsolute(rel)) byDir.set(rel, p.version)
+  for (const { name, version, dir } of packages) {
+    byName.set(name, version)
+    if (dir) byDir.set(dir, version)
   }
   return { byDir, byName }
 }
 
 // Walk up from a bundled file to the nearest named composer.json, returning
-// { pkgDir, name, version } (pkgDir "." for the root; version from installed.json
-// by dir/name, else composer.json `version`, else `fallbackVersion`). Null if none.
+// { pkgDir, name, version } (pkgDir "." for the root; version from composer.lock or
+// installed.json by dir/name, else composer.json `version`, else `fallbackVersion`). Null if none.
 function findComposerPackage(baseDir, fileRelPath, installed, fallbackVersion) {
   let dir = dirname(fileRelPath)
   for (;;) {
@@ -615,11 +700,9 @@ function findComposerPackage(baseDir, fileRelPath, installed, fallbackVersion) {
 // Group bundled PHP sources into per-package buckets keyed by the nearest
 // composer.json's directory (vendor deps get their own; workspace files and
 // orphans -> the root "." bucket with the placeholder identity). Returns a
-// Map<dir, { name, version, files }>.
-export function bucketizePhpSources(baseDir, sources, fallbackName, fallbackVersion) {
-  const composerJson = readJsonIfExists(join(baseDir, 'composer.json'))
-  const vendorDir = normalizeProjectRel(baseDir, composerJson?.config?.['vendor-dir'] ?? 'vendor') ?? 'vendor'
-  const installed = loadInstalledVersions(baseDir, vendorDir)
+// Map<dir, { name, version, files }>. `packages`: loadComposerPackages(baseDir).
+export function bucketizePhpSources(baseDir, sources, fallbackName, fallbackVersion, packages = loadComposerPackages(baseDir)) {
+  const installed = packageVersions(packages)
 
   const modules = new Map()
   const ensureBucket = (dir, name, version, ecosystem) => {
@@ -647,22 +730,19 @@ export function bucketizePhpSources(baseDir, sources, fallbackName, fallbackVers
 }
 
 // Laravel auto-registers service providers nothing references statically. Returns
-// discoverable provider files (from composer.json + installed.json
+// discoverable provider files (from composer.json + the Composer `packages`'
 // `extra.laravel.providers`, autoload-resolved) plus bootstrap/providers.php as
 // extra collection roots. Best-effort: unresolvable classes skipped.
-export function loadLaravelProviderFiles(baseDir, autoload) {
+// `packages`: loadComposerPackages(baseDir).
+export function loadLaravelProviderFiles(baseDir, autoload, packages = loadComposerPackages(baseDir)) {
   const files = new Set()
   if (existsSync(join(baseDir, 'bootstrap', 'providers.php'))) files.add('bootstrap/providers.php')
   if (!autoload) return [...files]
 
-  const composerJson = readJsonIfExists(join(baseDir, 'composer.json'))
-  const vendorDir = normalizeProjectRel(baseDir, composerJson?.config?.['vendor-dir'] ?? 'vendor') ?? 'vendor'
-  const installed = readJsonIfExists(join(baseDir, vendorDir, 'composer', 'installed.json'))
-  const installedPackages = Array.isArray(installed) ? installed : (installed?.packages ?? [])
-
+  const { composerJson } = readComposerJson(baseDir)
   const fqcns = new Set(composerJson?.extra?.laravel?.providers ?? [])
-  for (const pkg of installedPackages) {
-    for (const fqcn of pkg?.extra?.laravel?.providers ?? []) fqcns.add(fqcn)
+  for (const pkg of packages) {
+    for (const fqcn of pkg.extra?.laravel?.providers ?? []) fqcns.add(fqcn)
   }
   for (const fqcn of fqcns) {
     const file = resolveClassFile(fqcn, autoload, baseDir)
@@ -781,9 +861,10 @@ export function phpClassDependencies(content) {
     if (impl) for (const nm of impl[1].split(',')) add(nm)
   }
 
-  // catch (A | B $e): capture the type list up to `$var`. The lazy `[^)]*?` (no
-  // second whitespace quantifier) keeps matching linear on adversarial input.
-  for (const m of stripped.matchAll(/\bcatch\s*\(([^)]*?)\$\w+/giu)) {
+  // catch (A | B $e), or PHP 8's catch (A | B) with no variable: capture the type
+  // list up to `$var` or `)`. One quantifier with nothing after it keeps matching
+  // linear on adversarial input.
+  for (const m of stripped.matchAll(/\bcatch\s*\(([^)$]*)/giu)) {
     for (const nm of m[1].split('|')) add(nm)
   }
 
@@ -852,7 +933,10 @@ export async function collectPhpFilesFromDisk(baseDir, entries, { autoload = nul
   const readOne = async (relPath) => {
     try {
       assertRealPathWithinBase(realBase, baseDir, relPath)
-      return [relPath, await readFile(join(baseDir, relPath), 'utf8')]
+      const bytes = await readFile(join(baseDir, relPath))
+      // One that isn't UTF-8 is refused rather than carried with U+FFFD in it.
+      if (!isUtf8(bytes)) throw new Error(`PHP source is not valid UTF-8: ${relPath}`)
+      return [relPath, bytes.toString('utf8')]
     } catch (err) {
       // ENOENT (no file) / EISDIR (specifier resolved to a directory): not a
       // loadable file -- warn and skip rather than crash (buildPhpTree surfaces
@@ -880,7 +964,8 @@ export async function collectPhpFilesFromDisk(baseDir, entries, { autoload = nul
       if (!entry) continue
       const [relPath, content] = entry
       sources.set(relPath, content)
-      for (const spec of extractPhpImports(content)) {
+      const includes = scanIncludes(content)
+      for (const spec of includeSpecs(includes, 'file')) {
         const resolved = resolvePhpImport(spec, relPath, { baseDir })
         if (resolved) {
           if (!sources.has(resolved)) next.push(resolved)
@@ -890,7 +975,7 @@ export async function collectPhpFilesFromDisk(baseDir, entries, { autoload = nul
       }
       // Dynamic includes with a static dir prefix: the exact file is known only
       // at runtime, so bundle every `.php` file in that directory as a candidate.
-      for (const dirSpec of extractPhpImportDirs(content)) {
+      for (const dirSpec of includeSpecs(includes, 'dir')) {
         const dir = resolvePhpDir(dirSpec, relPath, baseDir)
         if (!dir) continue
         for (const file of listPhpFiles(baseDir, dir)) {