@exodus/stasis 1.0.0-beta.2 → 1.0.0-beta.5

package/src/cmd/diff.js

@@ -4,25 +4,8 @@ import { sha512integrity } from '@exodus/stasis-core/state-util'
 import { parseFileWithKind } from '../parse.js'
 import { diffArtifacts, formatDiffStat, hasDifferences } from '../diff.js'
 
-// Run the `stasis diff` CLI command end-to-end: read the two given
-// lockfiles/bundles from disk (this is the layer that pulls in brotli, via
-// `parseFileWithKind`), diff them through the file-free `@exodus/stasis/diff`
-// API, and print the requested view. `left` is the baseline ("from"), `right`
-// the comparison ("to"). Today only the `--stat` summary is implemented, so
-// `stat` is required; the report goes to `out` (stdout by default). With
-// `imports: true` (the `--imports` flag) the report also diffs the resolution
-// graphs — which import edges were added, removed, or redirected.
-//
-// This layer owns the canonical hash: the file-free diff API doesn't pull in
-// `node:crypto`, so we inject `sha512integrity` (the same digest `stasis run`
-// records) for it to re-hash bundle bytes with.
-//
-// Either side may be a lockfile or a bundle, in any combination: a bundle's
-// recorded bytes are re-hashed into the SRI digests a lockfile records, so a
-// lockfile and a bundle compare in the same digest space (see src/diff.js).
-//
-// Returns `{ diff, differences }` so the caller can set the process exit code
-// (non-zero when the artifacts differ, like `diff(1)`).
+// Run `stasis diff`: read both lockfiles/bundles from disk and diff them through
+// the file-free diff API. Returns { diff, differences } for the caller's exit code.
 export function diffCommand({ cwd = process.cwd(), left, right, stat, imports = false, out = process.stdout } = {}) {
   if (!left || !right) throw new Error('diff: two files (lockfile or bundle) are required')
   if (!stat) throw new Error('diff: only --stat is implemented; pass stat: true')

package/src/cmd/github-bundle.js

@@ -0,0 +1,39 @@
+import { createHash } from 'node:crypto'
+import { resolve } from 'node:path'
+
+import { createClient } from '@preventive/upstream/github.js'
+import { buildGitHubBundle } from '../vfs-bundle/github.js'
+import { bundledSummary, writeBundle, writeFile } from './output.js'
+
+// The longest file name ext4, APFS and NTFS take: 255 bytes, or characters, ours being ASCII.
+const NAME_MAX = 255
+// Each character outside the portable filename set [A-Za-z0-9._-] made `_`.
+const portable = (s) => s.replaceAll(/[^\w.-]/gu, '_')
+
+// The default output of `stasis github-bundle`: `owner-name.<commit's first 7>.stasis.code.br` of
+// the repo, or `owner-name.<directory, its / made ->.<commit's first 7>.stasis.code.br` of a
+// directory in it, portable. A directory too deep for that to fit in NAME_MAX keeps what fits of
+// its start, and `_` and the first 8 of its sha256 after it; a valid `github` (at most 140
+// characters) leaves at least 91 for it.
+export function githubBundleFile({ github, directory, commit }) {
+  const repo = portable(github.replace('/', '-'))
+  const tail = `.${portable(commit.slice(0, 7))}.stasis.code.br`
+  if (!directory) return `${repo}${tail}`
+  const room = NAME_MAX - `${repo}.${tail}`.length
+  let dir = portable(directory.replaceAll('/', '-'))
+  if (dir.length > room) dir = `${dir.slice(0, room - 9)}_${createHash('sha256').update(directory).digest('hex').slice(0, 8)}`
+  return `${repo}.${dir}${tail}`
+}
+
+// Run `stasis github-bundle`: the bundle of a GitHub repo at a commit, or the one a tag names (the
+// default branch's head without either), as buildGitHubBundle builds it from `options`, written
+// brotli-compressed to `output` (githubBundleFile's name for it by default, `-` for stdout), and a
+// JS bundle's lockfile to `lockfile` where given.
+// The tree is fetched with GITHUB_TOKEN from `env` where it is set; nothing else of `env` is read.
+export async function githubBundleCommand({ cwd = process.cwd(), env = process.env, output, lockfile, brotliQuality, client, ...options } = {}) {
+  const built = await buildGitHubBundle({ ...options, lockfile, client: client ?? createClient({ token: env.GITHUB_TOKEN || null }) })
+  const dest = writeBundle(cwd, output ?? githubBundleFile({ github: options.github, directory: options.directory, commit: built.bundle.repo.commit }), built.bundle.serialize(), brotliQuality)
+  if (lockfile !== undefined) writeFile(resolve(cwd, lockfile), built.lockfile.serialize())
+  const from = `${options.github}@${built.bundle.repo.commit}${options.directory ? `/${options.directory}` : ''}`
+  console.warn(bundledSummary(built.bundle.sources.size, built.bundle.modules, from, dest))
+}

package/src/cmd/output.js

@@ -0,0 +1,36 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { brotliCompressSync } from 'node:zlib'
+
+import { brotliOptions } from '@exodus/stasis-core/brotli'
+
+// Default bundle output: stasis.code.br, the same name `stasis run --bundle=load` discovers, so the two round-trip with no flags.
+export const DEFAULT_BUNDLE_FILE = 'stasis.code.br'
+
+// Write `data` to the absolute path `abs`, creating its directory.
+export function writeFile(abs, data) {
+  mkdirSync(dirname(abs), { recursive: true })
+  writeFileSync(abs, data)
+}
+
+// Write `data` to `target` (resolved against `cwd`), or to stdout for `-`. -> where it went, for the summary
+export function writeOutput(cwd, target, data) {
+  if (target === '-') {
+    process.stdout.write(data)
+    return '<stdout>'
+  }
+  writeFile(resolve(cwd, target), data)
+  return target
+}
+
+// Write a bundle's `serialized` text brotli-compressed (at `brotliQuality`) as writeOutput does. -> where it went
+export const writeBundle = (cwd, target, serialized, brotliQuality) => writeOutput(cwd, target, brotliCompressSync(serialized, brotliOptions(brotliQuality)))
+
+// `N package(s)`: every non-empty bucket of a bundle's `modules` (the "." workspace bucket counts as one).
+export function packagesLabel(modules) {
+  const packages = [...modules.values()].filter((m) => Object.keys(m.files).length > 0).length
+  return `${packages} package${packages === 1 ? '' : 's'}`
+}
+
+// The summary of a bundle of `count` files in `modules` written from `from` to `dest`.
+export const bundledSummary = (count, modules, from, dest) => `[stasis] Bundled ${count} files in ${packagesLabel(modules)} from ${from} to ${dest}`

package/src/cmd/sbom.js

@@ -1,16 +1,10 @@
-import { mkdirSync, writeFileSync } from 'node:fs'
-import { dirname, resolve } from 'node:path'
+import { resolve } from 'node:path'
 
 import { parseFile } from '../parse.js'
 import { collectComponents, generateSbom } from '../sbom.js'
+import { writeOutput } from './output.js'
 
-// Run the `stasis sbom` CLI command end-to-end: read the given lockfiles/bundles
-// from disk (this is the layer that pulls in brotli, via `parseFile`), build an
-// SBOM in the requested `format` (spdx | cyclonedx) through the file-free
-// `@exodus/stasis/sbom` API, and write the pretty-printed JSON to `output` (a
-// file, or stdout when `output` is `-` or unset). The one-line summary goes to
-// stderr so it never corrupts a document streamed to stdout. `now`/`uuid` are
-// injectable for deterministic output.
+// The one-line summary goes to stderr so it never corrupts an SBOM streamed to stdout.
 export function sbomCommand({ cwd = process.cwd(), files, format, output, now, uuid } = {}) {
   if (!Array.isArray(files) || files.length === 0) {
     throw new Error('sbom: at least one lockfile or bundle is required')
@@ -20,15 +14,7 @@ export function sbomCommand({ cwd = process.cwd(), files, format, output, now, u
   const doc = generateSbom(format, components, { now, uuid })
   const text = JSON.stringify(doc, undefined, 2) + '\n'
 
-  const target = output ?? '-'
-  if (target === '-') {
-    process.stdout.write(text)
-  } else {
-    const outAbs = resolve(cwd, target)
-    mkdirSync(dirname(outAbs), { recursive: true })
-    writeFileSync(outAbs, text)
-  }
-  const dest = target === '-' ? '<stdout>' : target
+  const dest = writeOutput(cwd, output ?? '-', text)
   const n = components.length
   console.warn(`[stasis] Wrote ${format} SBOM with ${n} component${n === 1 ? '' : 's'} to ${dest}`)
   return { components, doc }

package/src/diff.js

@@ -1,34 +1,15 @@
 import { sortPaths } from '@exodus/stasis-core/util'
 
-// `@exodus/stasis/diff` — compare two already-parsed stasis artifacts
-// (`Bundle`/`Lockfile` instances) and report what changed, at both the module
-// (package) and the file level. Like `@exodus/stasis/sbom`, it never reads disk
-// and pulls in no brotli (`node:zlib`) or crypto (`node:crypto`): the caller
-// reads/decompresses the artifacts, hands over parsed instances, and — to
-// compare a bundle's bytes against a lockfile's digests — supplies the hash
-// function (see `hash` below). The CLI glue that reads files off disk and wires
-// in `sha512integrity` lives in `src/cmd/diff.js`.
-//
-// The key to comparing across kinds — diffing a lockfile against a bundle — is
-// that every artifact reduces to the same "digest space". A lockfile already
-// records each file as an SRI digest (`sha512-…`); a bundle records the file's
-// bytes, so we re-hash those bytes (via the injected `hash`) into the very
-// digest a lockfile would have recorded. A bundle stores code and 'resource'
-// files as UTF-8 text and 'resource:base64' files as base64 blobs, so the
-// hashing path is decided PER FILE from the bundle's `formats` map -- not
-// from a whole-bundle kind.
+// `@exodus/stasis/diff` — compare two parsed stasis artifacts (Bundle/Lockfile) at the module and
+// file level. Never reads disk. Comparing across kinds works by reducing every file to the same
+// digest space: a lockfile already holds SRI digests; a bundle holds bytes, re-hashed via the
+// injected `hash` — so a `hash` function is required whenever a bundle is an operand. Per-file
+// encoding (resource:base64 vs text) is read from the bundle's `formats` map.
 
 const KINDS = new Set(['lockfile', 'bundle'])
 
-// Reduce one file's recorded value to the SRI digest a lockfile records for it.
-// 'lockfile' values are already digests; a bundle's values are file bytes that
-// must be re-hashed. The encoding is now per-file (one bundle holds both code and
-// resources): a 'resource:base64' file is a base64 blob decoded back to raw bytes
-// first, while code files and raw-UTF-8 'resource' files hash as their string. This
-// is the "rehash the bundle" step that lets a bundle and a lockfile be compared,
-// and the reason a `hash` function is required whenever a bundle is involved.
-// `hash` takes a string or Buffer and returns the SRI digest (e.g. the
-// `sha512integrity` the CLI injects); a lockfile needs none.
+// Reduce one file's recorded value to an SRI digest: lockfile values already are digests; a
+// bundle's are re-hashed, with a `resource:base64` file decoded to bytes first (others hash as text).
 function digestOf(kind, format, value, hash) {
   if (kind === 'lockfile') return value
   if (typeof hash !== 'function') {
@@ -38,12 +19,10 @@ function digestOf(kind, format, value, hash) {
   return hash(value)
 }
 
-// Project an artifact onto a uniform shape for diffing: its scope, plus a map of
-// package dir -> { name, version, ecosystem, files: Map<rel, digest> }. `input`
-// is `{ artifact, kind }` where `artifact` is a parsed Bundle/Lockfile and `kind`
-// is 'lockfile' | 'bundle' (see parseFileWithKind). `hash` is the digest function
-// used to re-hash a bundle's bytes; it is only consulted for bundles (a lockfile
-// already holds digests). Per-file encoding is read from the bundle's `formats`.
+const projectPath = (dir, rel) => (dir === '.' ? rel : `${dir}/${rel}`)
+
+// Project an artifact onto a uniform shape: scope + Map<dir, { name, version, ecosystem,
+// files: Map<rel, digest> }>. `input` is { artifact, kind }; `hash` re-hashes bundle bytes only.
 export function normalizeArtifact(input, { hash } = {}) {
   const { artifact, kind } = input ?? {}
   if (!artifact || !KINDS.has(kind)) {
@@ -54,47 +33,21 @@ export function normalizeArtifact(input, { hash } = {}) {
   for (const [dir, { name, version, ecosystem, files }] of artifact.modules) {
     const digests = new Map()
     for (const [rel, value] of Object.entries(files)) {
-      const full = dir === '.' ? rel : `${dir}/${rel}`
-      digests.set(rel, digestOf(kind, formats.get(full), value, hash))
+      digests.set(rel, digestOf(kind, formats.get(projectPath(dir, rel)), value, hash))
     }
-    // v0 bundles record no name/version (null); normalize undefined to null too
-    // so module-metadata comparisons have a single "unknown" sentinel.
+    // v0 bundles record no name/version; normalize undefined -> null for a single "unknown" sentinel.
     modules.set(dir, { name: name ?? null, version: version ?? null, ecosystem: ecosystem ?? null, files: digests })
   }
-  return { scope: artifact.config?.scope ?? 'full', modules }
+  // `executable` decides which files `stasis extract` chmods +x, so a change to it changes the tree
+  // an artifact produces even when every digest matches -- it has to be part of "did these differ?".
+  return { scope: artifact.config?.scope ?? 'full', modules, executable: artifact.executable ?? new Set() }
 }
 
-const projectPath = (dir, rel) => (dir === '.' ? rel : `${dir}/${rel}`)
-
-// Diff two artifacts. `left`/`right` are each `{ artifact, kind }`; `left` is the
-// baseline ("from"), `right` the comparison ("to"). Returns a structured report:
-//
-//   {
-//     scope: { left, right },
-//     modules: {
-//       added:   [{ dir, name, version, ecosystem, files }],  // only in right
-//       removed: [{ dir, name, version, ecosystem, files }],  // only in left
-//       changed: [{ dir, name, versionChange?, nameChange? }] // in both, metadata differs
-//     },
-//     files: { added: [path], removed: [path], differing: [path] },
-//     imports?: { attested: { left, right }, added, removed, changed }  // only with { imports: true }
-//   }
-//
-// Modules are compared whole-package; files are compared within packages present
-// on BOTH sides. A package that exists on only one side is reported once as an
-// added/removed module (carrying its file count) rather than re-listing each of
-// its files — so the two levels are complementary, not redundant. A module's
-// `version`/`name` change is only reported when both sides record a (non-null)
-// value, since a v0 bundle records neither.
-//
-// With `{ imports: true }` the diff also compares the artifacts' resolution
-// graphs (the `imports` edges both lockfiles and bundles carry) and reports
-// which edges were added, removed, or redirected — see `diffImports`. It is
-// opt-in because the edge graph is verbose and not always attested.
-//
-// `hash` is the digest function used to re-hash bundle bytes (the CLI passes
-// `sha512integrity`); it is required only when a bundle is one of
-// the operands — a lockfile↔lockfile diff needs none.
+// Diff two `{ artifact, kind }` operands (`left` = baseline/"from", `right` = "to"). Modules are
+// compared whole-package; files only within packages present on BOTH sides (a one-sided package is
+// reported once as an added/removed module, not per-file). A version/name change is reported only
+// when both sides record a non-null value. `{ imports: true }` also diffs the resolution graphs
+// (opt-in; verbose). `hash` is required only when a bundle is an operand.
 export function diffArtifacts(left, right, { imports = false, hash } = {}) {
   const L = normalizeArtifact(left, { hash })
   const R = normalizeArtifact(right, { hash })
@@ -106,20 +59,20 @@ export function diffArtifacts(left, right, { imports = false, hash } = {}) {
   const filesRemoved = []
   const filesDiffering = []
 
+  const summary = (dir, m) => ({ dir, name: m.name, version: m.version, ecosystem: m.ecosystem, files: m.files.size })
   const dirs = new Set([...L.modules.keys(), ...R.modules.keys()])
   for (const dir of dirs) {
     const l = L.modules.get(dir)
     const r = R.modules.get(dir)
     if (l && !r) {
-      modulesRemoved.push({ dir, name: l.name, version: l.version, ecosystem: l.ecosystem, files: l.files.size })
+      modulesRemoved.push(summary(dir, l))
       continue
     }
     if (!l && r) {
-      modulesAdded.push({ dir, name: r.name, version: r.version, ecosystem: r.ecosystem, files: r.files.size })
+      modulesAdded.push(summary(dir, r))
       continue
     }
 
-    // Present on both sides: compare package metadata, then files within.
     const change = { dir, name: r.name ?? l.name }
     if (l.version !== null && r.version !== null && l.version !== r.version) {
       change.versionChange = { from: l.version, to: r.version }
@@ -148,35 +101,32 @@ export function diffArtifacts(left, right, { imports = false, hash } = {}) {
   filesRemoved.sort(sortPaths)
   filesDiffering.sort(sortPaths)
 
+  // Execute-bit changes, reported for every path either side marks (not just files in shared
+  // modules): gaining or losing +x is a real change to the extracted tree, whatever bucket it sits in.
+  const onlyIn = (a, b) => [...a].filter((file) => !b.has(file)).toSorted(sortPaths)
+  const executableAdded = onlyIn(R.executable, L.executable)
+  const executableRemoved = onlyIn(L.executable, R.executable)
+
   const result = {
     scope: { left: L.scope, right: R.scope },
     modules: { added: modulesAdded, removed: modulesRemoved, changed: modulesChanged },
     files: { added: filesAdded, removed: filesRemoved, differing: filesDiffering },
+    executable: { added: executableAdded, removed: executableRemoved },
   }
   if (imports) result.imports = diffImports(left, right)
   return result
 }
 
-// The resolution graph an artifact attests, or null when it attests none. A
-// unified bundle always carries a (possibly empty) `imports` Map, so it attests
-// its resolution set -- empty for a resources-only bundle. A lockfile predating
-// resolution attestation records `imports === null` and attests none.
+// The resolution graph an artifact attests, or null when it attests none (a legacy lockfile
+// predating attestation); a bundle always carries a possibly-empty map.
 function attestedImports({ artifact }) {
   return artifact.imports ?? null
 }
 
-// Collapse an imports map (conditions -> parent -> specifier -> target) to a map
-// of (parent, specifier) -> Set<target>, unioning over every conditions key.
-// We diff at this *resolution* level — "what does this import resolve to?" —
-// rather than at the raw (conditions, parent, specifier) edge key, because the
-// two sides label conditions differently: a statically built bundle records
-// every edge under the wildcard "*", while a runtime lockfile records precise
-// condition sets like "node, import". Keying on conditions would then report a
-// byte-identical resolution as removed (the "*" edge) + added (the precise
-// edge); folding conditions away makes them compare equal. This mirrors how the
-// loader reconciles "*" against precise sets when verifying a resolution
-// (state.js #assertAttestedResolution): the final target is what matters, not
-// how the edge is keyed.
+// Collapse an imports map (conditions -> parent -> specifier -> target) to (parent, specifier) ->
+// Set<target>, unioning over conditions: a static bundle keys every edge under "*" while a runtime
+// lockfile uses precise sets, so keying on conditions would report identical resolutions as
+// removed+added. Folding conditions away makes them compare equal.
 function resolutionsOf(imports) {
   const byPair = new Map()
   for (const [, byParent] of imports) {
@@ -185,9 +135,7 @@ function resolutionsOf(imports) {
         const key = JSON.stringify([parent, specifier])
         let entry = byPair.get(key)
         if (!entry) byPair.set(key, (entry = { parent, specifier, targets: new Set() }))
-        // A `--metro` edge target may be a { platform: file } map; fold each
-        // platform's file into the target set, so a redirect is compared at the
-        // "what files does this resolve to" level regardless of platform keying.
+        // A `--metro` edge target may be a { platform: file } map; fold each platform's file into the set.
         if (target instanceof Map) for (const f of target.values()) entry.targets.add(f)
         else entry.targets.add(target)
       }
@@ -201,17 +149,10 @@ const cmpPair = (a, b) => sortPaths(a.parent, b.parent) || cmpStr(a.specifier, b
 const sortedTargets = (set) => [...set].toSorted(sortPaths)
 const sameTargets = (a, b) => a.size === b.size && [...a].every((t) => b.has(t))
 
-// Diff the resolution graphs at the (parent, specifier) level (see
-// `resolutionsOf` for why conditions are folded away). Each side maps a
-// (parent, specifier) to the set of files it resolves to (usually one). Reports:
-//   added   — a (parent, specifier) only the right artifact resolves
-//   removed — a (parent, specifier) only the left artifact resolves
-//   changed — resolved on both sides, but to a different set of targets (a
-//             redirect — the kind of change a byte/format diff can't see)
-// `from`/`to` are sorted arrays of target files. When either side does not
-// attest imports at all (a legacy lockfile predating `imports`), the
-// comparison is skipped and `attested` flags why, rather than reporting one
-// side's whole graph as added/removed.
+// Diff resolution graphs at the (parent, specifier) level (conditions folded away — see
+// resolutionsOf). Reports added/removed and changed (resolved on both sides to different targets —
+// a redirect a byte diff can't see). When either side doesn't attest imports, the diff is skipped
+// and `attested` flags why, rather than reporting one whole graph as added/removed.
 export function diffImports(left, right) {
   const li = attestedImports(left)
   const ri = attestedImports(right)
@@ -238,16 +179,17 @@ export function diffImports(left, right) {
   return { attested, added, removed, changed }
 }
 
-// True when the diff records any module-, file-, or (when present) import-level
-// change. Scope alone is informational (a scope difference shows up as the
-// modules/files only one side records) and does not, on its own, count as a
-// difference. Imports that can't be compared (one side doesn't attest them)
-// contribute nothing — their add/remove/change lists are empty.
+// True when the diff records any module-, file-, or import-level change. Scope alone is
+// informational and doesn't count (unattested imports contribute empty lists).
 export function hasDifferences(diff) {
-  const { modules, files, imports } = diff
+  // `executable` is unguarded like modules/files -- diffArtifacts always sets it, and a shape guard
+  // here would make a renamed facet read as "no differences" and quietly pass a review gate.
+  // `imports` is genuinely opt-in (the `imports` option), so it keeps its guard.
+  const { modules, files, executable, imports } = diff
   let n =
     modules.added.length + modules.removed.length + modules.changed.length +
-    files.added.length + files.removed.length + files.differing.length
+    files.added.length + files.removed.length + files.differing.length +
+    executable.added.length + executable.removed.length
   if (imports) n += imports.added.length + imports.removed.length + imports.changed.length
   return n > 0
 }
@@ -256,8 +198,7 @@ const KIND_LABEL = { lockfile: 'lockfile', bundle: 'bundle' }
 const plural = (n) => (n === 1 ? '' : 's')
 const ident = ({ name, version }) => (name ? (version ? `${name}@${version}` : name) : '')
 
-// Diff markers. `~` reads too close to `-` in a terminal, so a changed/redirected
-// entry is marked `*` (distinct from `-` removed / `+` added).
+// Diff markers: `*` (changed) — `~` reads too close to `-` in a terminal.
 const REMOVED = '-'
 const ADDED = '+'
 const CHANGED = '*'
@@ -274,20 +215,15 @@ const moduleLine = (mark, x) => {
   return `  ${mark} ${x.dir}${id ? `  ${id}` : ''} (${x.files} file${plural(x.files)})`
 }
 
-// `parent  'specifier'` — conditions are folded away (see resolutionsOf), so an
-// edge is identified by the importing file and the specifier it resolved.
+// `parent  'specifier'` — an edge is identified by importer + specifier (conditions folded away).
 const edgeLabel = (e) => `${e.parent}  '${e.specifier}'`
 const targetList = (files) => files.join(', ')
 
-// Render the `--stat` summary of a diff (module + file change lists with
-// counts, plus the import-edge changes when the diff carries them), in the
-// spirit of `git diff --stat`: it reports *what* changed, not the differing
-// text itself, and the whole report — including the trailing differ/no-differ
-// line — goes to stdout. `labels` is `{ left, right, leftKind, rightKind }` for
-// the header. Lines use `-` (only in left / baseline), `+` (only in right),
-// `*` (changed in place). Returns a string ending in a newline.
+// Render the `--stat` summary (module + file change lists with counts, plus import-edge changes
+// when present); reports what changed, not the text. `labels` is { left, right, leftKind, rightKind }.
+// Returns a string ending in a newline.
 export function formatDiffStat(diff, { left = '(left)', right = '(right)', leftKind, rightKind } = {}) {
-  const { modules: m, files: f, imports: im, scope } = diff
+  const { modules: m, files: f, executable: ex, imports: im, scope } = diff
   const lines = ['stasis diff --stat']
   const label = (kind) => (kind ? `${KIND_LABEL[kind]}, ` : '')
   lines.push(`  ${REMOVED} ${left} (${label(leftKind)}scope=${scope.left})`)
@@ -303,15 +239,22 @@ export function formatDiffStat(diff, { left = '(left)', right = '(right)', leftK
   for (const x of m.changed) lines.push(`  ${CHANGED} ${x.dir}  ${describeModuleChange(x)}`)
 
   lines.push('')
-  // Counts cover files *within modules present on both sides*; files inside a
-  // wholly added/removed module are summarized by its module entry above (with
-  // a file count), not re-counted here — so name the scope to avoid misreading
-  // "0 removed" when a whole package vanished.
+  // Counts cover only files within modules present on both sides; a wholly added/removed module's
+  // files are summarized by its module entry above — hence the "within shared modules" label.
   lines.push(`Files (within shared modules): ${f.added.length} added, ${f.removed.length} removed, ${f.differing.length} differing`)
   for (const p of f.removed) lines.push(`  ${REMOVED} ${p}`)
   for (const p of f.added) lines.push(`  ${ADDED} ${p}`)
   for (const p of f.differing) lines.push(`  ${CHANGED} ${p}`)
 
+  // Only rendered when something changed: an unchanged execute-bit set is the overwhelming norm,
+  // and a permanent "0 added, 0 removed" line would be noise in every diff.
+  if (ex.added.length > 0 || ex.removed.length > 0) {
+    lines.push('')
+    lines.push(`Executable: ${ex.added.length} added, ${ex.removed.length} removed`)
+    for (const p of ex.removed) lines.push(`  ${REMOVED} ${p}`)
+    for (const p of ex.added) lines.push(`  ${ADDED} ${p}`)
+  }
+
   if (im) {
     lines.push('')
     if (!im.attested.left || !im.attested.right) {