@scalequality/check 0.4.0 → 0.5.1

package/README.md

@@ -21,6 +21,8 @@ and **Turn on continuous measurement**. Store the token as a CI secret named
 | `--host` | `SQ_HOST` | `https://app.scalequality.io` | API host |
 | `--timeout` | — | `600` | Max seconds to wait for the measurement |
 | `--json` | — | off | Print the raw result as JSON |
+| `--exclude <path>` | — | — | Exclude a generated file/directory by literal checkout-relative path; repeatable |
+| `--dry-run` | — | off | Measure locally and validate the package without uploading; no token needed |
 
 Exit codes: `0` passed (or track-only), `1` below the cutoff, `2` error.
 
@@ -62,9 +64,9 @@ Recognised out of the box: JaCoCo (`jacoco.xml`), LCOV (`lcov.info`), Cobertura
 (`coverage.xml`, `coverage.cobertura.xml`), Istanbul (`coverage-summary.json`),
 Clover (`clover.xml`) and Go (`coverage.out`). Multi-module builds are summed.
 
-The reports are copied into a temporary `.sqreports/` folder so they survive the
-archive's build-output exclusions, and that folder is removed before the command
-exits — including when the job is cancelled.
+The reports are copied outside your checkout into temporary staging, then stored
+as `.sqreports/` entries in the upload. Build-output exclusions do not discard
+these measured reports, and your working tree is not modified.
 
 Report somewhere unusual? Point at it in `scalequality.properties` at the repo
 root:
@@ -74,3 +76,95 @@ sq.coverage.reportPaths=ops/reports/jacoco-aggregate.xml
 ```
 
 Full guide: https://scalequality.io/docs/continuous-measurement
+
+## Fixed history window and large repositories (0.5.0)
+
+Durability is calculated **on the CI runner**, against its existing Git history,
+using the same native engine as ScaleQuality: a fixed **90-day** window, with
+**14 days** for introduced code to settle before survival is measured. The source
+engine revision and report time travel with the result. The CLI sends current
+source, coverage, and a bounded durability report (at most 1 MiB); it never uploads
+the raw `.git` object database. Years of old binary history therefore do not add
+to the archive size. It does not truncate or change your repository.
+
+Use a complete checkout for that measurement. Shallow history is reported as
+unavailable; it is not treated as a full 90-day measurement.
+
+```yaml
+# GitHub Actions
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- run: npx @scalequality/check@0.5.1 --project <projectId>
+  env:
+    SQ_TOKEN: ${{ secrets.SQ_TOKEN }}
+```
+
+For GitLab set `GIT_DEPTH: "0"`. For Bitbucket Pipelines set:
+
+```yaml
+clone:
+  depth: full
+```
+
+The current-code scanners still run on the server. Historical secret scanning and
+commit-convention analysis are not included in this report; the result shows those
+limits and identifies durability as reported by CI. CPU, time, malformed Git or
+report-size limits yield unavailable history, never a fabricated clean result.
+
+Version 0.5.0 needs the compatible ScaleQuality server release. The CLI checks the
+server's acknowledgement of this exact report before declaring a passing gate.
+
+The compressed **source-and-reports archive** remains limited to 60 MiB. A time
+window cannot guarantee that arbitrary source assets fit: one current binary can
+exceed the limit. Generated dependency/output directories (`node_modules`,
+`dist`, `build`, `.next`, `out`, `target`, `.venv`, `venv`, `coverage`,
+`.turbo`) are excluded at every depth, while lockfiles are retained.
+Use `--exclude generated/assets` for other generated content. Paths are literal,
+relative to the checkout, and do not use shell wildcards. Do not exclude source
+that you expect to measure.
+
+```bash
+# Local verification; does not need a token and sends nothing to ScaleQuality.
+npx @scalequality/check@0.5.1 --dry-run
+```
+
+The CLI checks compressed size before allocating the upload buffer or sending a
+request. If current source alone cannot fit, it lists the largest included files
+and exits with an actionable error. No oversized upload is sent.
+
+
+## 0.5.1: Composer dependencies and large Git blame output
+
+The CLI recognizes installed Composer dependencies using `composer.json` and a
+valid `composer.lock`. It excludes the default `vendor/`, or a safe relative
+`config.vendor-dir`, while preserving both files for dependency analysis. Nested
+Composer projects are recognized too. A directory named `vendor` alone is not
+sufficient evidence to exclude it. Ambiguous configuration, source paths that
+overlap the dependency directory, and unavailable local package origins keep the
+directory in the archive. The CLI reports which directories it excluded or kept.
+It reads JSON only; it does not run Composer, plugins or scripts.
+
+`node_modules/` and the existing generated-output directories remain excluded.
+Coverage reports from application tests are staged separately before packaging.
+Excluding installed dependencies does not certify that their locked versions are
+free of vulnerabilities.
+
+Git durability reads incremental blame ranges as a stream instead of buffering
+all per-line metadata and source content. This preserves the native calculation,
+90-day window, 14-day settlement and tracked-file selection. It handles large
+blame output without increasing the worker's memory or time budgets.
+
+Archive exclusions, including `--exclude`, do not change Git durability's tracked
+file scope. A tracked dependency can still contribute to the historical metric.
+Changing that methodology requires a separate coordinated version; this patch
+does not silently rewrite prior scores. Missing coverage or history is still
+reported as unavailable.
+
+Track-only completion now says `measurement completed (track only; no cutoff
+configured)`. Its exit code remains zero; completion does not certify that every
+dimension was measured or that a maturity threshold was passed.
+
+The 60 MiB compressed-source limit still applies. A checkout with more than that
+amount of first-party source or ambiguous generated assets is rejected locally;
+this release does not truncate source to force a successful upload.

package/bin/archive.mjs

@@ -0,0 +1,115 @@
+import { spawnSync } from "node:child_process"
+import { mkdtempSync, mkdirSync, readdirSync, lstatSync, existsSync, statSync, writeFileSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join, resolve, posix } from "node:path"
+import { planComposerExclusions } from "./composer-vendor.mjs"
+
+export const ARCHIVE_LIMIT_BYTES = 60 * 1024 * 1024
+const MAX_DURABILITY_REPORT_BYTES = 1024 * 1024
+// Directory names, at every depth. Explicit file manifests avoid GNU/BSD tar
+// differences in matching nested output/dependency directories.
+const SKIP = new Set(["node_modules", "dist", "build", ".next", "out", "target", ".venv", "venv", "coverage", ".turbo"])
+const mib = (bytes) => (bytes / 1024 / 1024).toFixed(1)
+
+export function normalizeExcludes(excludes = []) {
+  return excludes.map((value) => {
+    if (typeof value !== "string" || !value || value.startsWith("-") || value.includes("\0") || value.includes("\\") || /[*?\[\]]/.test(value)) {
+      throw new Error("--exclude needs a literal path relative to the checkout (no wildcards).")
+    }
+    const path = posix.normalize(value.replace(/^\.\//, "")).replace(/\/$/, "")
+    if (!path || path === "." || path.startsWith("/") || path === ".." || path.startsWith("../") || /^[A-Za-z]:/.test(path) || [".git", ".sqreports"].includes(path.split("/")[0])) {
+      throw new Error("--exclude must stay inside the checkout and cannot exclude .git or .sqreports.")
+    }
+    return path
+  })
+}
+
+function inventory(root, { reports = false, excludes = [], log = () => {} } = {}) {
+  const paths = [], largest = []
+  const composerExcluded = reports ? [] : planComposerExclusions(root, excludes, SKIP, log)
+  for (const candidate of composerExcluded) {
+    log(`ScaleQuality: excluding installed Composer dependencies at ${JSON.stringify(candidate.path)}; retaining ${JSON.stringify(candidate.manifest)} and ${JSON.stringify(candidate.lockfile)} for dependency analysis. Git durability scope is unchanged.`)
+  }
+  const walk = (rel) => {
+    const abs = join(root, rel)
+    const st = lstatSync(abs)
+    paths.push(`./${rel}`)
+    if (st.isDirectory()) {
+      for (const entry of readdirSync(abs).sort()) visit(rel ? `${rel}/${entry}` : entry, entry)
+    } else if (st.isFile()) {
+      largest.push({ path: rel, bytes: st.size })
+    }
+  }
+  const visit = (rel, name) => {
+    if (!reports && (name === ".git" || rel === ".sqreports" || [...excludes, ...composerExcluded.map(item => item.path)].some((p) => rel === p || rel.startsWith(`${p}/`)))) return
+    if (!reports && SKIP.has(name) && lstatSync(join(root, rel)).isDirectory()) return
+    walk(rel)
+  }
+  for (const entry of readdirSync(root).sort()) visit(entry, entry)
+  return { paths, largest: largest.sort((a, b) => b.bytes - a.bytes).slice(0, 5), composerExcluded }
+}
+
+/**
+ * Upload current source plus bounded measurement reports, never raw Git objects.
+ * The 90-day durability calculation happens against the original local history;
+ * no shallow clone, artificial root commit or changes to the customer's checkout.
+ */
+export function prepareCheckoutArchive({ root, coverageRoot, durabilityReport, log = () => {}, maxBytes = ARCHIVE_LIMIT_BYTES, excludes = [] }) {
+  root = resolve(root)
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0 || maxBytes > ARCHIVE_LIMIT_BYTES) throw new Error("Invalid archive size limit.")
+  excludes = normalizeExcludes(excludes)
+  const temp = mkdtempSync(join(tmpdir(), "sq-checkout-"))
+  const onExit = () => { try { rmSync(temp, { recursive: true, force: true }) } catch { /* best effort on process exit */ } }
+  process.once("exit", onExit)
+  const cleanup = () => { process.removeListener("exit", onExit); rmSync(temp, { recursive: true, force: true }) }
+  try {
+    const source = inventory(root, { excludes, log })
+    const sourceList = join(temp, "source.list")
+    writeFileSync(sourceList, source.paths.length ? `${source.paths.join("\0")}\0` : "")
+    const metadataRoot = join(temp, "metadata")
+    mkdirSync(join(metadataRoot, ".sqreports"), { recursive: true })
+    const hasGit = existsSync(join(root, ".git"))
+    const history = { mode: hasGit ? "omitted" : "unavailable", reason: durabilityReport ? "ci_report" : hasGit ? "invalid_git" : "missing_git" }
+    writeFileSync(join(metadataRoot, ".sqreports/checkout.json"), JSON.stringify({ version: 1, history, archiveLimitBytes: ARCHIVE_LIMIT_BYTES }))
+    if (source.composerExcluded.length) writeFileSync(join(metadataRoot, ".sqreports/source.json"), JSON.stringify({ version: 1, composerDependencyExclusions: source.composerExcluded }))
+    if (durabilityReport) {
+      const json = JSON.stringify(durabilityReport)
+      if (Buffer.byteLength(json) > MAX_DURABILITY_REPORT_BYTES) throw new Error("Durability report exceeds the 1 MiB report limit. No upload was sent.")
+      writeFileSync(join(metadataRoot, ".sqreports/durability.json"), json)
+    }
+    const metadataList = join(temp, "metadata.list")
+    writeFileSync(metadataList, `${inventory(metadataRoot, { reports: true }).paths.join("\0")}\0`)
+    const tarPath = join(temp, "checkout.tar")
+    const archivePath = `${tarPath}.gz`
+    // BSD tar uses only the last -T list. Build/append one directory and list
+    // per invocation, then stream compression through Node (no extra dependency).
+    const archivePart = (operation, directory, list) => {
+      const tar = spawnSync("tar", [operation, tarPath, "--no-recursion", "--null", "-C", directory, "-T", list], { encoding: "utf8", timeout: 180000, maxBuffer: 1024 * 1024, env: { ...process.env, COPYFILE_DISABLE: "1" } })
+      if (tar.error || tar.status !== 0) throw new Error("Could not archive the checkout. Ensure GNU/BSD tar is installed, files are readable, and the build has finished changing files.")
+    }
+    archivePart("-cf", root, sourceList)
+    if (coverageRoot) {
+      const coverageList = join(temp, "coverage.list")
+      const entries = inventory(coverageRoot, { reports: true }).paths
+      writeFileSync(coverageList, entries.length ? `${entries.join("\0")}\0` : "")
+      if (entries.length) archivePart("-rf", coverageRoot, coverageList)
+    }
+    archivePart("-rf", metadataRoot, metadataList)
+    const compression = spawnSync(process.execPath, ["--input-type=module", "-e", "import {createReadStream,createWriteStream} from 'node:fs';import{createGzip}from'node:zlib';import{pipeline}from'node:stream/promises';await pipeline(createReadStream(process.argv[1]),createGzip(),createWriteStream(process.argv[2]));", tarPath, archivePath], { encoding: "utf8", timeout: 180000, maxBuffer: 1024 * 1024 })
+    // A nonempty file can still be truncated. Never upload an archive produced
+    // by failed tar or a checkout that changed while it was being archived.
+    if (compression.error || compression.status !== 0 || !existsSync(archivePath) || statSync(archivePath).size === 0) {
+      throw new Error("Could not archive the checkout. Ensure GNU/BSD tar is installed, files are readable, and the build has finished changing files.")
+    }
+    const bytes = statSync(archivePath).size
+    if (bytes > maxBytes) {
+      const files = source.largest.map((f) => `${JSON.stringify(f.path)} (${mib(f.bytes)} MiB uncompressed)`).join(", ")
+      throw new Error(`source archive alone is ${mib(bytes)} MiB, above the ${mib(maxBytes)} MiB limit even without Git history. No upload was sent. Exclude generated assets with --exclude <relative-path>. Largest included files: ${files || "none"}`)
+    }
+    log(`ScaleQuality: checkout archive ${mib(bytes)} MiB / ${mib(maxBytes)} MiB; raw Git history stays on this runner.`)
+    return { archivePath, bytes, history, cleanup }
+  } catch (error) {
+    cleanup()
+    throw error
+  }
+}

package/bin/check.mjs

@@ -1,13 +1,15 @@
 #!/usr/bin/env node
 // ScaleQuality continuous check. Uploads THIS CI checkout to ScaleQuality (re-measures
-// the code the runner already has, including .git so durability still runs) and exits
+// the code the runner already has, with a local 90-day durability report) and exits
 // non-zero when maturity is below the configured cutoff, so a CI step can fail the
 // build. Pure Node 18+ (global fetch/FormData/Blob), no npm dependencies.
 
 import { tmpdir } from "node:os"
 import { join, dirname, relative, sep } from "node:path"
 import { spawnSync } from "node:child_process"
-import { readFileSync, writeFileSync, existsSync, statSync, rmSync, readdirSync, mkdirSync, copyFileSync } from "node:fs"
+import { readFileSync, writeFileSync, statSync, rmSync, readdirSync, mkdirSync, mkdtempSync, copyFileSync } from "node:fs"
+import { prepareCheckoutArchive, normalizeExcludes } from "./archive.mjs"
+import { measureDurability } from "./durability.mjs"
 
 const args = process.argv.slice(2)
 const flag = (name) => {
@@ -30,6 +32,8 @@ Options:
                    myapp:\${{ github.sha }}. Needs trivy on PATH; skipped with a
                    note if it is missing, never fails the build for it.
   --timeout <s>    Max seconds to wait for the measurement (default 600)
+  --exclude <p>    Exclude a generated path relative to the checkout; repeatable
+  --dry-run        Measure locally and check the package; do not upload (no token needed)
   --json           Print the raw result as JSON
   -h, --help       Show this help
 
@@ -41,6 +45,7 @@ const token = flag("--token") || process.env.SQ_TOKEN
 const project = flag("--project") || process.env.SQ_PROJECT
 const host = (flag("--host") || process.env.SQ_HOST || "https://app.scalequality.io").replace(/\/+$/, "")
 const jsonOut = has("--json")
+const dryRun = has("--dry-run")
 const image = flag("--image") || process.env.SQ_IMAGE
 const timeoutMs = Math.max(30, Number(flag("--timeout") || 600)) * 1000
 
@@ -49,7 +54,7 @@ const log = (m) => { if (!jsonOut) console.log(m) }
 const fail = (m) => { console.error(`ScaleQuality: ${m}`); process.exit(2) }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
 
-if (!token || !project) {
+if (!dryRun && (!token || !project)) {
   fail("--token and --project are required (or env SQ_TOKEN / SQ_PROJECT). See --help.")
 }
 
@@ -153,13 +158,13 @@ const MAX_REPORTS = 40
 
 function stageCoverageReports() {
   const root = process.cwd()
-  const stage = join(root, COVERAGE_STAGE)
-  rmSync(stage, { recursive: true, force: true })
+  const stagingRoot = mkdtempSync(join(tmpdir(), "sq-coverage-"))
+  const stage = join(stagingRoot, COVERAGE_STAGE)
   // The staged copies must not outlive this process under ANY exit path. A
   // cancelled job or a network failure that left them behind would show up as
   // untracked files in the customer's checkout, and a pipeline that runs
   // `git diff --exit-code` after the gate would fail because of us.
-  const clean = () => { try { rmSync(stage, { recursive: true, force: true }) } catch { /* best effort */ } }
+  const clean = () => { try { rmSync(stagingRoot, { recursive: true, force: true }) } catch { /* best effort */ } }
   process.on("exit", clean)
   for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
     process.on(sig, () => { clean(); process.exit(130) })
@@ -178,6 +183,7 @@ function stageCoverageReports() {
         if (!COVERAGE_SKIP.has(e.name)) walk(abs, depth + 1)
         continue
       }
+      if (!e.isFile()) continue
       const hit = COVERAGE_NAMES.find((c) => c.re.test(e.name))
       if (!hit) continue
       let size = 0
@@ -203,42 +209,38 @@ function stageCoverageReports() {
   } else {
     log("ScaleQuality: no coverage report found in this job. Run your tests with coverage before this step to get a measured %.")
   }
-  return { stage, count: index.length }
+  return { stage, root: stagingRoot, count: index.length, cleanup: clean }
 }
 
 async function main() {
   const auth = { Authorization: `Bearer ${token}` }
+  const excludes = normalizeExcludes(args.flatMap((arg, i) => arg === "--exclude" ? [args[i + 1]] : []))
+  const durabilityReport = await measureDurability({ root: process.cwd(), log: jsonOut ? (message) => console.error(message) : log })
   const coverage = stageCoverageReports()
-
-  // Upload THIS checkout (the runner already has the code) instead of asking the server
-  // to clone the repo from outside — that needed a stored provider credential and failed
-  // with no_repo_reachable on private repos. Keep .git so the durability domain (git blame)
-  // still runs; node_modules + build output are excluded to stay small.
-  const archivePath = join(tmpdir(), `sq-checkout-${process.pid}.tar.gz`)
-  // Portable flags only (GNU/BSD/busybox tar all accept -czf, --exclude, -C). We do NOT
-  // rely on tar's exit code (some tars exit 1 on a benign "file changed as we read it"
-  // during a build); instead we require the archive to exist and be non-empty.
-  const tr = spawnSync("tar", [
-    "-czf", archivePath,
-    "--exclude=./node_modules", "--exclude=./dist", "--exclude=./build",
-    "--exclude=./.next", "--exclude=./out", "--exclude=./target",
-    "--exclude=./.venv", "--exclude=./venv", "--exclude=./coverage", "--exclude=./.turbo",
-    "-C", process.cwd(), ".",
-  ], { encoding: "utf8" })
-  if (!(existsSync(archivePath) && statSync(archivePath).size > 0)) {
-    rmSync(coverage.stage, { recursive: true, force: true })
-    fail(`could not archive the checkout (tar unavailable or failed). ${tr.error?.message || (tr.stderr || "").trim()}`)
+  let packed, buf
+  try {
+    packed = prepareCheckoutArchive({ root: process.cwd(), coverageRoot: coverage.root, durabilityReport, excludes, log })
+    if (durabilityReport) {
+      const head = spawnSync("git", ["--no-optional-locks", "-C", process.cwd(), "rev-parse", "--verify", "HEAD"], { encoding: "utf8", timeout: 10000 })
+      if (head.error || head.status !== 0 || head.stdout.trim() !== durabilityReport.headSha) throw new Error("Git HEAD changed during measurement or packaging. No upload was sent; rerun after the checkout is stable.")
+    }
+    if (!dryRun) buf = readFileSync(packed.archivePath)
+  } finally {
+    packed?.cleanup()
+    coverage.cleanup()
+  }
+  const localCheckout = { version: 1, history: packed.history, archiveBytes: packed.bytes, durability: durabilityReport ? { source: "ci", windowDays: 90, settleDays: 14, headSha: durabilityReport.headSha, measuredAt: durabilityReport.measuredAt, engineCommit: durabilityReport.engineCommit } : undefined }
+  const limitation = "ScaleQuality: historical secret scanning and commit-convention signals are not included in this checkout report."
+  console.error(limitation)
+  if (dryRun) {
+    if (jsonOut) console.log(JSON.stringify({ dryRun: true, checkout: localCheckout, coverageReports: coverage.count }))
+    else log("ScaleQuality: local package verified; no upload sent.")
+    return
   }
-  const buf = readFileSync(archivePath)
-  rmSync(archivePath, { force: true })
-  // The staged copies exist only to ride along in the archive. Leaving them
-  // behind would dirty the working tree of the job that ran us.
-  rmSync(coverage.stage, { recursive: true, force: true })
-  const sizeMB = buf.length / (1024 * 1024)
-  if (sizeMB > 60) fail(`checkout archive too large (${sizeMB.toFixed(0)}MB > 60MB limit). Reduce clone depth or exclude build output.`)
 
   const form = new FormData()
   form.append("project", project)
+  form.append("reportProtocol", "durability-ci-v1")
   form.append("file", new Blob([buf]), "checkout.tar.gz")
   const containerReport = scanImage()
   if (containerReport) form.append("containerReport", containerReport)
@@ -251,7 +253,7 @@ async function main() {
     const body = await r.text().catch(() => "")
     if (r.status === 401) fail("invalid token.")
     if (r.status === 402) fail("continuous measurement needs an active subscription.")
-    if (r.status === 409) fail("continuous is not enabled for this project. Turn it on in ScaleQuality.")
+    if (r.status === 409) fail(body.includes("measurement_already_running") ? "another measurement is already running for this project. Wait for it to finish and rerun this step." : "continuous is not enabled for this project. Turn it on in ScaleQuality.")
     fail(`report failed (${r.status}) ${body}`)
   }
   const { runId } = await r.json()
@@ -285,6 +287,10 @@ async function main() {
 
   if (!last || (last.status !== "COMPLETED" && last.status !== "FAILED")) fail("timed out waiting for the measurement.")
   if (last.status === "FAILED") fail(`measurement failed: ${last.failureReason || "unknown"}`)
+  if (last.checkout?.version !== 1) fail("the server did not confirm the checkout report protocol. No passing gate is claimed; update to the compatible continuous-measurement server release.")
+  if (durabilityReport && (last.checkout?.durability?.source !== "ci" || last.checkout.durability.windowDays !== 90 || last.checkout.durability.settleDays !== 14 || last.checkout.durability.headSha !== durabilityReport.headSha || last.checkout.durability.measuredAt !== durabilityReport.measuredAt || last.checkout.durability.engineCommit !== durabilityReport.engineCommit)) {
+    fail("the server did not confirm this checkout's 90-day durability report. No passing gate is claimed; the server needs the compatible continuous-measurement release.")
+  }
 
   if (jsonOut) {
     console.log(JSON.stringify(last))
@@ -292,6 +298,7 @@ async function main() {
     const cut = last.cutoff != null ? ` (cutoff ${last.cutoff})` : " (track only)"
     log(`ScaleQuality: maturity ${last.maturity ?? "—"}${cut}`)
     if (last.passed === false) console.error("ScaleQuality: below the line — failing the build.")
+    else if (last.cutoff == null) log("ScaleQuality: measurement completed (track only; no cutoff configured).")
     else log("ScaleQuality: passed.")
   }
   process.exit(last.passed === false ? 1 : 0)

package/bin/composer-vendor.mjs

@@ -0,0 +1,198 @@
+import { constants, closeSync, fstatSync, lstatSync, openSync, readSync, readdirSync } from 'node:fs'
+import { join, posix } from 'node:path'
+
+const MAX_JSON_BYTES = 4 * 1024 * 1024
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+const overlaps = (a, b) => a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`) || a === '.' || b === '.'
+
+// Inspect data only. Composer plugins/scripts and customer symlinks are never run/followed.
+function readJson(path) {
+  let fd
+  try {
+    fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+    const stat = fstatSync(fd)
+    if (!stat.isFile() || stat.size > MAX_JSON_BYTES) return null
+    const raw = Buffer.alloc(stat.size + 1)
+    let bytes = 0
+    while (bytes < raw.length) {
+      const count = readSync(fd, raw, bytes, raw.length - bytes, null)
+      if (!count) break
+      bytes += count
+    }
+    if (bytes !== stat.size) return null
+    const value = JSON.parse(raw.subarray(0, bytes).toString('utf8'))
+    return object(value) ? value : null
+  } catch { return null }
+  finally { if (fd !== undefined) closeSync(fd) }
+}
+
+function safeRelative(value) {
+  if (typeof value !== 'string' || !value || /[\\\0*?\[\]$~]/.test(value) || value.startsWith('/') || /^[A-Za-z]:/.test(value)) return null
+  if (value.split('/').includes('..')) return null
+  const path = posix.normalize(value).replace(/\/$/, '')
+  return path === '.' || path.split('/').some(part => ['.git', '.sqreports'].includes(part)) ? null : path
+}
+
+function sourcePath(module, value) {
+  if (typeof value !== 'string' || /[\\\0$~]/.test(value) || value.startsWith('/') || /^[A-Za-z]:/.test(value)) return null
+  // A glob's fixed directory prefix bounds every possible source it might select.
+  const glob = value.search(/[*?\[]/)
+  const prefix = glob < 0 ? value : value.slice(0, glob).replace(/[^/]*$/, '')
+  const path = posix.normalize(posix.join(module || '.', prefix || '.')).replace(/\/$/, '')
+  return path === '..' || path.startsWith('../') ? null : path
+}
+
+function autoloadPaths(value) {
+  if (value === undefined) return []
+  if (!object(value)) return [null]
+  const paths = []
+  for (const key of ['psr-4', 'psr-0', 'classmap', 'files']) {
+    const entry = value[key]
+    if (entry === undefined) continue
+    const values = ['psr-4', 'psr-0'].includes(key) ? object(entry) ? Object.values(entry) : [null] : Array.isArray(entry) ? entry : [null]
+    for (const item of values) paths.push(...(Array.isArray(item) ? item : [item]))
+  }
+  return paths
+}
+
+function regularDirectory(root, path, consume = () => {}) {
+  let current = root
+  for (const part of path.split('/')) {
+    consume()
+    current = join(current, part)
+    try { if (!lstatSync(current).isDirectory()) return false }
+    catch { return false }
+  }
+  return true
+}
+
+/** A transport exclusion, never a change to the native Git durability scope. */
+export function composerVendorDirectory(root, module = '', excludes = [], ignoredDirectories = new Set(), consume = () => {}) {
+  const manifest = readJson(join(root, module, 'composer.json'))
+  if (!manifest) return null
+  const label = posix.join(module, 'composer.json')
+  const keep = reason => ({ kept: true, manifest: label, reason })
+  const lock = readJson(join(root, module, 'composer.lock'))
+  if (!lock || !Array.isArray(lock.packages) || (lock['packages-dev'] !== undefined && !Array.isArray(lock['packages-dev']))) return keep('a valid composer.lock is required')
+  const packages = [...lock.packages, ...(lock['packages-dev'] || [])]
+  if (!packages.length || packages.some(pkg => !object(pkg) || typeof pkg.name !== 'string' || !pkg.name || typeof pkg.version !== 'string' || !pkg.version)) return keep('locked dependency versions could not be confirmed')
+  if (manifest.config !== undefined && !object(manifest.config)) return keep('Composer config is ambiguous')
+  const vendor = safeRelative(manifest.config && Object.hasOwn(manifest.config, 'vendor-dir') ? manifest.config['vendor-dir'] : 'vendor')
+  if (!vendor) return keep('vendor-dir must be a literal directory within the Composer project')
+  const path = posix.join(module, vendor)
+  // If either evidence file is explicitly excluded, do not infer a safe replacement for installed dependencies.
+  if (['composer.json', 'composer.lock'].some(file => excludes.some(ex => overlaps(ex, posix.join(module, file))))) return keep('the manifest or lockfile was explicitly excluded')
+
+  const repositories = manifest.repositories === undefined ? [] : Array.isArray(manifest.repositories) ? manifest.repositories : object(manifest.repositories) ? Object.values(manifest.repositories) : [null]
+  if (repositories.some(repo => repo !== false && !object(repo))) return keep('Composer repositories are ambiguous')
+  const localOrigins = [
+    ...repositories.filter(repo => repo && repo.type === 'path').map(repo => repo.url),
+    ...packages.filter(pkg => pkg.dist?.type === 'path').map(pkg => pkg.dist.url),
+  ]
+  // Resolving Composer's glob rules and each symlink target is outside this transport hotfix.
+  if (localOrigins.some(value => typeof value !== 'string' || /[*?\[]/.test(value))) return keep('local package origins use ambiguous paths or globs')
+  const sources = [...autoloadPaths(manifest.autoload), ...autoloadPaths(manifest['autoload-dev']), ...localOrigins]
+  if (sources.some(value => { consume(); const source = sourcePath(module, value); return source === null || overlaps(path, source) })) return keep('local source paths may overlap installed dependencies or lie outside the checkout')
+  if (localOrigins.some(value => {
+    const source = sourcePath(module, value)
+    consume()
+    return !regularDirectory(root, source, consume) || source.split('/').some(part => ignoredDirectories.has(part) || part === 'vendor') || excludes.some(ex => overlaps(ex, source))
+  })) return keep('a local package origin is missing, linked or excluded from the archive')
+  // A custom vendor-dir can have several components: reject a symlink in ANY component.
+  if (!regularDirectory(root, path, consume)) return null
+  return { path, manifest: label, lockfile: posix.join(module, 'composer.lock') }
+}
+
+function declaredSources(root, module, consume) {
+  const manifest = readJson(join(root, module, 'composer.json'))
+  if (!manifest) return [null]
+  const repositories = manifest.repositories === undefined ? [] : Array.isArray(manifest.repositories) ? manifest.repositories : object(manifest.repositories) ? Object.values(manifest.repositories) : [null]
+  if (repositories.some(repo => repo !== false && !object(repo))) return [null]
+  const lock = readJson(join(root, module, 'composer.lock'))
+  let packages = []
+  try {
+    lstatSync(join(root, module, 'composer.lock'))
+    if (!lock || !Array.isArray(lock.packages) || (lock['packages-dev'] !== undefined && !Array.isArray(lock['packages-dev']))) return [null]
+    packages = [...lock.packages, ...(lock['packages-dev'] || [])]
+    if (packages.some(pkg => !object(pkg))) return [null]
+  } catch (error) { if (error.code !== 'ENOENT') return [null] }
+  return [
+    ...autoloadPaths(manifest.autoload), ...autoloadPaths(manifest['autoload-dev']),
+    ...repositories.filter(repo => repo && repo.type === 'path').map(repo => repo.url),
+    ...packages.filter(pkg => pkg.dist?.type === 'path').map(pkg => pkg.dist.url),
+  ].map(value => {
+    consume()
+    // Resolving a glob or symlink could reveal another project's only source copy.
+    if (typeof value !== 'string' || /[*?\[]/.test(value)) return null
+    const path = sourcePath(module, value)
+    if (path === null) return null
+    let current = root
+    for (const part of path.split('/')) {
+      consume()
+      current = join(current, part)
+      try { if (lstatSync(current).isSymbolicLink()) return null }
+      catch (error) { if (error.code === 'ENOENT') break; return null }
+    }
+    return path
+  })
+}
+
+/** Discover all projects before applying any Composer exclusion. References can cross modules. */
+export function planComposerExclusions(root, excludes = [], ignoredDirectories = new Set(), log = () => {}) {
+  const limit = new Error('Composer discovery resource limit')
+  const deadline = Date.now() + 5_000
+  let work = 0
+  const consume = () => { if (++work > 1_000_000 || Date.now() > deadline) throw limit }
+  try {
+    const projects = []
+    const pending = ['']
+    let visited = 0
+    while (pending.length) {
+      consume()
+      const module = pending.pop()
+      const entries = readdirSync(join(root, module), { withFileTypes: true })
+      visited += entries.length
+      if (visited > 100_000 || projects.length > 5_000) throw limit
+      if (entries.some(entry => entry.name === 'composer.json')) projects.push({
+        module,
+        candidate: composerVendorDirectory(root, module, excludes, ignoredDirectories, consume),
+        sources: declaredSources(root, module, consume),
+      })
+      for (const entry of entries.sort((a, b) => b.name.localeCompare(a.name))) {
+        consume()
+        const path = posix.join(module, entry.name)
+        if (!entry.isDirectory() || entry.name === '.git' || path === '.sqreports' || ignoredDirectories.has(entry.name) || excludes.some(ex => path === ex || path.startsWith(`${ex}/`))) continue
+        pending.push(path)
+      }
+    }
+    const candidates = projects.flatMap(project => project.candidate?.path ? [project.candidate] : [])
+    const protectedPaths = new Set()
+    const isActive = project => !candidates.some(candidate => { consume(); return !protectedPaths.has(candidate.path) && (project.module === candidate.path || project.module.startsWith(`${candidate.path}/`)) })
+    // Dependency package manifests do not veto their containing vendor directory.
+    // Once an external project references it, it is retained and its declarations
+    // become relevant too. Iterate until no newly retained project protects another.
+    let changed
+    do {
+      changed = false
+      const sources = projects.filter(isActive).flatMap(project => project.sources)
+      for (const candidate of candidates) {
+        if (!protectedPaths.has(candidate.path) && sources.some(source => { consume(); return source === null || overlaps(candidate.path, source) })) {
+          protectedPaths.add(candidate.path)
+          changed = true
+        }
+      }
+    } while (changed)
+    for (const project of projects.filter(isActive)) {
+      if (project.candidate?.kept) log(`ScaleQuality: retaining possible Composer dependencies near ${JSON.stringify(project.candidate.manifest)}: ${project.candidate.reason}.`)
+    }
+    for (const candidate of candidates) {
+      if (protectedPaths.has(candidate.path)) log(`ScaleQuality: retaining ${JSON.stringify(candidate.path)}: a project declares source there or its source paths could not be resolved safely.`)
+    }
+    // Nested installed package manifests cannot create independent upload exclusions.
+    return projects.filter(isActive).flatMap(project => project.candidate?.path && !protectedPaths.has(project.candidate.path) ? [project.candidate] : [])
+  } catch (error) {
+    if (error !== limit) throw error
+    log('ScaleQuality: retaining Composer dependency directories: project discovery exceeded its resource limit.')
+    return []
+  }
+}