@gjsify/cli 0.48.0 → 0.50.0

package/lib/utils/package-inputs.d.ts

@@ -0,0 +1,81 @@
+/** One file the build may read. `link` is set for a symlink (never followed). */
+export interface PackageInputFile {
+    /** Package-relative path, forward slashes. */
+    rel: string;
+    abs: string;
+    /** Raw symlink target, when this entry is a symlink. */
+    link?: string;
+}
+/**
+ * Where the toolchain writes when the package does not say otherwise.
+ *
+ * Used for a package with NO `clear` script (a consumer project we know
+ * nothing about), and unioned onto the declared set for one that has one:
+ * `gjsify test` writes `dist/test.{gjs,node}.mjs` into packages whose `clear`
+ * line predates that command and names only `lib`, and an output left in the
+ * input set makes every run see a newer file than the artifact it is judging.
+ */
+export declare const CONVENTIONAL_OUTPUT_DIRS: readonly ["lib", "dist", "dist-templates"];
+/**
+ * Files whose change means the installed dependency tree may have moved.
+ *
+ * `node_modules` is deliberately not walked — too large to stat per run, and
+ * the reason the old `gjsify test` walk skipped it too — so the lockfile is
+ * the cheap proxy for it. That substitution is not new: `actions/build.ts`
+ * has made it since the plugin bundle cache existed, and this is the list it
+ * uses, kept in one place so a fifth package manager is added once.
+ */
+export declare const DEP_CHANGE_LOCKFILES: readonly ["gjsify-lock.json", "package-lock.json", "yarn.lock", "pnpm-lock.yaml"];
+export interface PackageBuildInputOptions {
+    /** Parsed `package.json`, when the caller already has it. */
+    manifest?: {
+        scripts?: Record<string, string>;
+    } | null;
+    /** Extra package-relative paths to treat as output (e.g. a `--outdir`). */
+    extraOutputs?: readonly string[];
+}
+/**
+ * The paths this package PRODUCES, package-relative — DERIVED from the
+ * package's own `clear` script rather than re-declared, the same move
+ * `utils/dev-plan.ts` makes for build flags.
+ *
+ * Three cases, and the middle one is the one that matters:
+ *   - `clear` is `gjsify clear a b c` → `a b c` plus the conventional dirs.
+ *     127 of 212 workspace packages, naming `tmp`, `build`, `*.tsbuildinfo`,
+ *     `test.gjs.mjs`, and in two of them `src/*.generated.ts` — a generated
+ *     file INSIDE `src/` that the old walk hashed as an input.
+ *   - `clear` is anything else (`echo 'nothing to do'`, 74 packages) →
+ *     NOTHING. The package states it has nothing to delete, so its `lib/` is
+ *     source, not output. Exactly two of the 74 have a conventional output dir
+ *     on disk, `resolve-npm/lib` and `manifest-conformance/lib`, and in both
+ *     it is tracked source — so the script is a trustworthy oracle both ways.
+ *   - no `clear` script (11 packages, and any consumer project) → the
+ *     conventional dirs, the only guess available.
+ */
+export declare function packageOutputPaths(manifest: {
+    scripts?: Record<string, string>;
+} | null): string[];
+/** `package.json` at `pkgRoot`, or `null` when absent/unreadable. */
+export declare function readPackageManifest(pkgRoot: string): {
+    scripts?: Record<string, string>;
+} | null;
+/**
+ * Every file the build of the package at `pkgRoot` may read, sorted by
+ * package-relative path.
+ *
+ * Enumeration only — the caller decides whether to hash contents (build cache)
+ * or take mtimes (`gjsify test` freshness). That split is deliberate: the two
+ * must agree on the SET, and they legitimately differ on what they do with it.
+ */
+export declare function packageBuildInputs(pkgRoot: string, options?: PackageBuildInputOptions): PackageInputFile[];
+/** Newest mtime (ms) among `files`, or 0 for an empty set. */
+export declare function newestInputMtimeMs(files: readonly PackageInputFile[]): number;
+/**
+ * Newest lockfile mtime (ms) at or above `startDir`, or 0 when there is none.
+ *
+ * Walks up because in a monorepo the lockfile that governs a package's
+ * `node_modules` sits at the workspace root, several levels away — and a
+ * dependency bump that rewrites it is precisely the case #1651 was found in
+ * (postbote, gjsify 0.33.0 → 0.49.0, not one source file touched).
+ */
+export declare function newestDepSignalMtimeMs(startDir: string): number;

package/lib/utils/package-inputs.js

@@ -0,0 +1,233 @@
+// SPDX-License-Identifier: MIT
+// ONE answer to "what are this package's build inputs" — read by the build
+// cache (`build-cache.ts`) and by `gjsify test`'s freshness check. Add a
+// fourth READER, never a fourth answer.
+//
+// It was answered three times, each an ALLOW-list over a guessed layout, and
+// each is wrong for a package that already exists here: `src/**` misses
+// `@gjsify/adwaita-fonts` (no `src/` at all) and the tracked source in
+// `resolve-npm/lib` + `manifest-conformance/lib` (#821); `dirname(<test
+// entry>)` missed `src/**` entirely, so `gjsify test` reran the PREVIOUS
+// bundle and reported on it (#1651).
+//
+// So: a DENY-list. An input is any file in the package that is not a
+// dependency, not tool/VCS state, and not something the package produces —
+// which covers a layout nobody anticipated by construction. **In doubt, a
+// file is an input**: a false input costs one rebuild, a false non-input
+// costs a green test run about code that is not in the artifact.
+//
+// The incident, the measurements behind every number below, and the copy
+// still open (CI's `actions/cache` glob): docs/build-artifacts.md.
+import { existsSync, lstatSync, readdirSync, readFileSync, readlinkSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { hasWildcard, segmentToRegExp } from './clear-targets.js';
+import { gjsifyCommandArgv } from './simple-command.js';
+/**
+ * Where the toolchain writes when the package does not say otherwise.
+ *
+ * Used for a package with NO `clear` script (a consumer project we know
+ * nothing about), and unioned onto the declared set for one that has one:
+ * `gjsify test` writes `dist/test.{gjs,node}.mjs` into packages whose `clear`
+ * line predates that command and names only `lib`, and an output left in the
+ * input set makes every run see a newer file than the artifact it is judging.
+ */
+export const CONVENTIONAL_OUTPUT_DIRS = ['lib', 'dist', 'dist-templates'];
+/**
+ * Files whose change means the installed dependency tree may have moved.
+ *
+ * `node_modules` is deliberately not walked — too large to stat per run, and
+ * the reason the old `gjsify test` walk skipped it too — so the lockfile is
+ * the cheap proxy for it. That substitution is not new: `actions/build.ts`
+ * has made it since the plugin bundle cache existed, and this is the list it
+ * uses, kept in one place so a fifth package manager is added once.
+ */
+export const DEP_CHANGE_LOCKFILES = ['gjsify-lock.json', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml'];
+/**
+ * The paths this package PRODUCES, package-relative — DERIVED from the
+ * package's own `clear` script rather than re-declared, the same move
+ * `utils/dev-plan.ts` makes for build flags.
+ *
+ * Three cases, and the middle one is the one that matters:
+ *   - `clear` is `gjsify clear a b c` → `a b c` plus the conventional dirs.
+ *     127 of 212 workspace packages, naming `tmp`, `build`, `*.tsbuildinfo`,
+ *     `test.gjs.mjs`, and in two of them `src/*.generated.ts` — a generated
+ *     file INSIDE `src/` that the old walk hashed as an input.
+ *   - `clear` is anything else (`echo 'nothing to do'`, 74 packages) →
+ *     NOTHING. The package states it has nothing to delete, so its `lib/` is
+ *     source, not output. Exactly two of the 74 have a conventional output dir
+ *     on disk, `resolve-npm/lib` and `manifest-conformance/lib`, and in both
+ *     it is tracked source — so the script is a trustworthy oracle both ways.
+ *   - no `clear` script (11 packages, and any consumer project) → the
+ *     conventional dirs, the only guess available.
+ */
+export function packageOutputPaths(manifest) {
+    const clear = manifest?.scripts?.clear;
+    if (clear === undefined)
+        return [...CONVENTIONAL_OUTPUT_DIRS];
+    // `allowGlobs`: five packages here clear `*.tsbuildinfo`, and the pattern
+    // is what we want — this reads the targets, it does not run them.
+    const argv = gjsifyCommandArgv(clear, { allowGlobs: true });
+    if (argv === null || argv[0] !== 'clear')
+        return [];
+    const targets = argv.slice(1).filter((token) => !token.startsWith('-'));
+    return [...targets, ...CONVENTIONAL_OUTPUT_DIRS];
+}
+/** `package.json` at `pkgRoot`, or `null` when absent/unreadable. */
+export function readPackageManifest(pkgRoot) {
+    try {
+        return JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Match a package-relative path against output targets — the target itself and
+ * everything under it.
+ *
+ * Wildcards are honoured in the LAST segment only, which is `gjsify clear`'s
+ * own rule (`utils/clear-targets.ts`), so the set matched here is the set that
+ * command would delete.
+ */
+function makeOutputMatcher(targets) {
+    const compiled = targets
+        .map((target) => target
+        .split(/[\\/]+/)
+        .filter((segment) => segment !== '' && segment !== '.')
+        .map((segment) => (hasWildcard(segment) ? segmentToRegExp(segment) : segment)))
+        .filter((segments) => segments.length > 0);
+    return (rel) => {
+        const parts = rel.split('/');
+        for (const target of compiled) {
+            if (target.length > parts.length)
+                continue;
+            let matched = true;
+            for (let i = 0; i < target.length; i++) {
+                const segment = target[i];
+                const got = parts[i];
+                if (typeof segment === 'string' ? segment !== got : !segment.test(got)) {
+                    matched = false;
+                    break;
+                }
+            }
+            if (matched)
+                return true;
+        }
+        return false;
+    };
+}
+function walk(dir, prefix, isOutput, out) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    entries.sort();
+    for (const entry of entries) {
+        // `node_modules` is the dependency tree, not this package's source, and
+        // a dot-entry is VCS/editor/cache state — `.git` alone would make the
+        // walk unbounded. Measured across every package here: no file under any
+        // `src/` is dot-prefixed, so nothing the old hash covered is lost.
+        if (entry === 'node_modules' || entry.startsWith('.'))
+            continue;
+        const rel = prefix === '' ? entry : `${prefix}/${entry}`;
+        if (isOutput(rel))
+            continue;
+        const abs = join(dir, entry);
+        let st;
+        try {
+            st = lstatSync(abs);
+        }
+        catch {
+            continue;
+        }
+        if (st.isSymbolicLink()) {
+            // Not followed: a directory symlink can loop, and a workspace
+            // `node_modules` link would drag the whole tree in. The target
+            // string participates instead; file links are read by content where
+            // the consumer asks for content.
+            out.push({ rel, abs, link: readLinkTarget(abs) });
+        }
+        else if (st.isDirectory()) {
+            walk(abs, rel, isOutput, out);
+        }
+        else if (st.isFile()) {
+            out.push({ rel, abs });
+        }
+    }
+}
+function readLinkTarget(abs) {
+    try {
+        return readlinkSync(abs);
+    }
+    catch {
+        // Dropped between lstat and readlink. An empty target still differs
+        // from the file being absent, which is all the hash needs.
+        return '';
+    }
+}
+/**
+ * Every file the build of the package at `pkgRoot` may read, sorted by
+ * package-relative path.
+ *
+ * Enumeration only — the caller decides whether to hash contents (build cache)
+ * or take mtimes (`gjsify test` freshness). That split is deliberate: the two
+ * must agree on the SET, and they legitimately differ on what they do with it.
+ */
+export function packageBuildInputs(pkgRoot, options = {}) {
+    const manifest = options.manifest !== undefined ? options.manifest : readPackageManifest(pkgRoot);
+    const outputs = [...packageOutputPaths(manifest), ...(options.extraOutputs ?? [])];
+    const files = [];
+    walk(pkgRoot, '', makeOutputMatcher(outputs), files);
+    return files;
+}
+/** Newest mtime (ms) among `files`, or 0 for an empty set. */
+export function newestInputMtimeMs(files) {
+    let newest = 0;
+    for (const file of files) {
+        try {
+            const { mtimeMs } = statSync(file.abs);
+            if (mtimeMs > newest)
+                newest = mtimeMs;
+        }
+        catch {
+            // Vanished mid-walk. Treat as a change: an input we cannot read is
+            // not evidence that the artifact is current.
+            return Number.POSITIVE_INFINITY;
+        }
+    }
+    return newest;
+}
+/**
+ * Newest lockfile mtime (ms) at or above `startDir`, or 0 when there is none.
+ *
+ * Walks up because in a monorepo the lockfile that governs a package's
+ * `node_modules` sits at the workspace root, several levels away — and a
+ * dependency bump that rewrites it is precisely the case #1651 was found in
+ * (postbote, gjsify 0.33.0 → 0.49.0, not one source file touched).
+ */
+export function newestDepSignalMtimeMs(startDir) {
+    let newest = 0;
+    let dir = startDir;
+    for (;;) {
+        for (const name of DEP_CHANGE_LOCKFILES) {
+            const candidate = join(dir, name);
+            if (!existsSync(candidate))
+                continue;
+            try {
+                const { mtimeMs } = statSync(candidate);
+                if (mtimeMs > newest)
+                    newest = mtimeMs;
+            }
+            catch {
+                /* raced away — the other lockfiles still answer */
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return newest;
+        dir = parent;
+    }
+}

package/lib/utils/ship/changelog.d.ts

@@ -38,19 +38,20 @@ export declare function changelogEntriesFor(version: string, source: string): st
  * wrong: exactly one leading space, then `--`, one space, the maintainer, and TWO
  * spaces before the date.
  *
- * TWO lintian tags this file still raises, both measured on lintian 2.117 against
- * gjsify's own `.deb` and both left alone deliberately:
- *
- *  - `initial-upload-closes-no-bugs`, because the Debian revision is `-1` and the
- *    entry closes no bug. It is a statement about the Debian ARCHIVE's ITP
- *    workflow — the first upload of a new source package should close its ITP bug
- *    — and a package built by `gjsify ship` is never uploaded there. There is no
- *    bug number that would be true to write, so the tag is inapplicable rather
- *    than unmet.
- *  - `changelog-not-compressed-with-max-compression`. Policy asks for `gzip -9`
- *    and neither `CompressionStream` nor `@gjsify/zlib` takes a level, so
- *    `gzipDeterministic` cannot ask for one. Ledgered in `status/open-todos.md`:
- *    the fix is a capability in the core, and stamping the header's XFL byte to
- *    claim max compression we did not use is not one.
+ * ONE lintian tag this file still raises, measured on lintian 2.117 against
+ * gjsify's own `.deb` and left alone deliberately: `initial-upload-closes-no-bugs`,
+ * because the Debian revision is `-1` and the entry closes no bug. It is a
+ * statement about the Debian ARCHIVE's ITP workflow — the first upload of a new
+ * source package should close its ITP bug — and a package built by `gjsify ship`
+ * is never uploaded there. There is no bug number that would be true to write, so
+ * the tag is inapplicable rather than unmet.
+ *
+ * `changelog-not-compressed-with-max-compression` was a second one, and closing it
+ * was a capability gap in the CORE rather than anything wrong in this file:
+ * neither `CompressionStream` nor `@gjsify/zlib` would take a compression level,
+ * so `gzipDeterministic` had none to pass on. `@gjsify/zlib` honours
+ * `options.level` now and `plan.ts` compresses this file at
+ * `POLICY_MAX_COMPRESSION`. `verify-deb.sh` gates the tag by name, so it cannot
+ * come back quietly.
  */
 export declare function renderDebianChangelog(settings: PackSettings, source: string | undefined, mtime: number): string;

package/lib/utils/ship/changelog.js

@@ -134,20 +134,21 @@ const WIDTH = 80;
  * wrong: exactly one leading space, then `--`, one space, the maintainer, and TWO
  * spaces before the date.
  *
- * TWO lintian tags this file still raises, both measured on lintian 2.117 against
- * gjsify's own `.deb` and both left alone deliberately:
+ * ONE lintian tag this file still raises, measured on lintian 2.117 against
+ * gjsify's own `.deb` and left alone deliberately: `initial-upload-closes-no-bugs`,
+ * because the Debian revision is `-1` and the entry closes no bug. It is a
+ * statement about the Debian ARCHIVE's ITP workflow — the first upload of a new
+ * source package should close its ITP bug — and a package built by `gjsify ship`
+ * is never uploaded there. There is no bug number that would be true to write, so
+ * the tag is inapplicable rather than unmet.
  *
- *  - `initial-upload-closes-no-bugs`, because the Debian revision is `-1` and the
- *    entry closes no bug. It is a statement about the Debian ARCHIVE's ITP
- *    workflow — the first upload of a new source package should close its ITP bug
- *    — and a package built by `gjsify ship` is never uploaded there. There is no
- *    bug number that would be true to write, so the tag is inapplicable rather
- *    than unmet.
- *  - `changelog-not-compressed-with-max-compression`. Policy asks for `gzip -9`
- *    and neither `CompressionStream` nor `@gjsify/zlib` takes a level, so
- *    `gzipDeterministic` cannot ask for one. Ledgered in `status/open-todos.md`:
- *    the fix is a capability in the core, and stamping the header's XFL byte to
- *    claim max compression we did not use is not one.
+ * `changelog-not-compressed-with-max-compression` was a second one, and closing it
+ * was a capability gap in the CORE rather than anything wrong in this file:
+ * neither `CompressionStream` nor `@gjsify/zlib` would take a compression level,
+ * so `gzipDeterministic` had none to pass on. `@gjsify/zlib` honours
+ * `options.level` now and `plan.ts` compresses this file at
+ * `POLICY_MAX_COMPRESSION`. `verify-deb.sh` gates the tag by name, so it cannot
+ * come back quietly.
  */
 export function renderDebianChangelog(settings, source, mtime) {
     const entries = source === undefined ? [] : changelogEntriesFor(settings.version, source);

package/lib/utils/ship/formats.js

@@ -450,7 +450,21 @@ export const FORMATS = {
         // is a download: it lands in a browser's downloads folder beside other
         // files, so it carries the version and the arch, and it avoids the spaces
         // a display name may contain.
-        fileName: (s, archLabel) => `${s.binaryName}-${s.version}-${s.release}.${archLabel}.zip`,
+        //
+        // AND THE OPERATING SYSTEM, which the extension does not name. Every other
+        // row's suffix names exactly one platform — `.deb`, `.rpm`, `.flatpak`,
+        // `.dmg`, `.msi` — and `.zip` names none, so this row and `windows-dir-zip`
+        // are the only two artifacts in the table a user cannot tell apart by
+        // looking at them. Before this token they were separated by nothing but a
+        // coincidence between two unrelated arch tables (`MACOS_ARCH` maps x64 to
+        // `x86_64`, `WINDOWS_ARCH` to `x64`), which put a bare `…-1.arm64.zip` on a
+        // release page beside a Windows zip with no way to choose — and would have
+        // had the two formats silently overwrite each other in `ship/out/` the day
+        // a Windows/arm64 row became possible, an upstream blocker (#1117) being
+        // all that stood in the way. `macos`, not `darwin`, for the same reason
+        // `MACOS_ARCH` writes `x86_64` rather than `x64`: this label is read by
+        // whoever downloads the file, never by `process.platform`.
+        fileName: (s, archLabel) => `${s.binaryName}-${s.version}-${s.release}.macos.${archLabel}.zip`,
         artifactKind: 'file',
     },
     // ── macOS (#1354 M4) ─────────────────────────────────────────────────
@@ -661,7 +675,14 @@ export const FORMATS = {
         // pair splits them: this one is a download that lands in a browser's
         // folder beside other files, so it carries the version and the arch and
         // avoids the spaces a display name may contain.
-        fileName: (s, archLabel) => `${s.binaryName}-${s.version}-${s.release}.${archLabel}.zip`,
+        //
+        // …and the OS, for the reason spelled out on the `macos-app-zip` row it was
+        // copied from: `.zip` is the one container this table puts on more than one
+        // operating system, so it is the one name that has to say which. `windows`
+        // rather than `win32` — the spelling is the user's, like the `x64` this row
+        // keeps because Node's own archives, gvsbuild's assets and the runner label
+        // all use it.
+        fileName: (s, archLabel) => `${s.binaryName}-${s.version}-${s.release}.windows.${archLabel}.zip`,
         artifactKind: 'file',
     },
     // ── The Windows installer (#1354 M5) ─────────────────────────────────

package/lib/utils/ship/gzip.d.ts

@@ -1,2 +1,31 @@
-/** gzip with the header's timestamp zeroed and the OS byte pinned to Unix. */
-export declare function gzipDeterministic(input: Uint8Array): Promise<Uint8Array>;
+/**
+ * gzip with the header's timestamp zeroed and the OS byte pinned to Unix.
+ *
+ * @param level 0-9, or omitted for zlib's default. THE ONLY HONEST WAY TO SET XFL:
+ *   byte 8 of the header records how hard the compressor tried (2 = maximum,
+ *   4 = fastest, 0 = neither), `lintian` reads it to raise
+ *   `changelog-not-compressed-with-max-compression`, and `file` prints it as
+ *   "max compression". Stamping that byte here beside the mtime and OS bytes would
+ *   be a different thing entirely and was rejected for it: mtime and OS are facts
+ *   about the build ENVIRONMENT, which a reproducible build is entitled to
+ *   normalise, while XFL is a statement about the compression actually performed.
+ *   Writing a 2 we had not earned would make the artifact lie to the tool reading
+ *   it. So the level travels down to the compressor instead.
+ *
+ *   AND THE TEMPTATION IS REAL, which is why this is worth writing down: measured
+ *   on gjsify's own `.deb`, the changelog member compressed at the default level
+ *   and at 9 differs in EXACTLY ONE BYTE — position 9, XFL, 0 against 2 — and is
+ *   1152 bytes either way. For this input, stamping the byte would have produced
+ *   the identical artifact. It is identical by coincidence of a small input: over
+ *   this repo's full `CHANGELOG.md` the same two levels differ by thousands of
+ *   bytes. A rule that happens to hold on today's input is not the rule.
+ */
+export declare function gzipDeterministic(input: Uint8Array, level?: number): Promise<Uint8Array>;
+/**
+ * `gzip -9`, the level Debian Policy § 4.4 asks of a packaging changelog.
+ *
+ * Named rather than spelled `9` at the call site so the reason travels with the
+ * number: the `-n` half of Policy's `gzip -9 -n` is what {@link gzipDeterministic}
+ * already does to bytes 4-7.
+ */
+export declare const POLICY_MAX_COMPRESSION = 9;

package/lib/utils/ship/gzip.js

@@ -5,10 +5,54 @@
 // input produce different bytes — which no test notices, because every test
 // compares the DECOMPRESSED content. It is the single most-missed
 // reproducibility bug in package writers, and it costs nothing to close.
+//
+// WHAT "DETERMINISTIC" DOES NOT COVER, measured 2026-09-11 and named here because
+// the function's own name overstates it: the bytes are reproducible for a given
+// HOST, not for a given artifact. `@gjsify/tar`'s gzip runs on the platform's
+// zlib, and the platforms do not ship the same one — Fedora's libz is
+// `zlib-ng-compat` (2.3.3) while Node bundles its own zlib (1.3.2.1-motley). Over
+// this repo's `CHANGELOG.md` (876 192 bytes) at the DEFAULT level they produce
+// 272 003 and 272 000 bytes respectively, so a `.deb` packed under GJS and one
+// packed under Node already differ, today, before any level argument exists.
+// Levels 1-4 differ too, in the other direction (zlib-ng is smaller). Two
+// consequences worth keeping:
+//
+//   * `tests/e2e/ship-from-stage` asserts byte-equality between a direct pack and
+//     a `--from-stage` pack, and it holds because both run on ONE host. It is
+//     structurally blind to this, and a cross-host pack is exactly what
+//     `--from-stage` exists to enable.
+//   * zlib-ng's level 9 is WORSE than its level 8 on large inputs — 277 974 vs
+//     270 255 bytes on the file above, ~2.9 % bigger — which is why `level: 9` is
+//     asked for only where a reader demands it (see below) and not blanket-applied
+//     to the payload tarballs.
+//
+// Ledgered in `status/open-todos.md`; closing it means pinning ONE deflate
+// implementation, which is a larger decision than this file.
 import { gzip } from '@gjsify/tar';
-/** gzip with the header's timestamp zeroed and the OS byte pinned to Unix. */
-export async function gzipDeterministic(input) {
-    const out = await gzip(input);
+/**
+ * gzip with the header's timestamp zeroed and the OS byte pinned to Unix.
+ *
+ * @param level 0-9, or omitted for zlib's default. THE ONLY HONEST WAY TO SET XFL:
+ *   byte 8 of the header records how hard the compressor tried (2 = maximum,
+ *   4 = fastest, 0 = neither), `lintian` reads it to raise
+ *   `changelog-not-compressed-with-max-compression`, and `file` prints it as
+ *   "max compression". Stamping that byte here beside the mtime and OS bytes would
+ *   be a different thing entirely and was rejected for it: mtime and OS are facts
+ *   about the build ENVIRONMENT, which a reproducible build is entitled to
+ *   normalise, while XFL is a statement about the compression actually performed.
+ *   Writing a 2 we had not earned would make the artifact lie to the tool reading
+ *   it. So the level travels down to the compressor instead.
+ *
+ *   AND THE TEMPTATION IS REAL, which is why this is worth writing down: measured
+ *   on gjsify's own `.deb`, the changelog member compressed at the default level
+ *   and at 9 differs in EXACTLY ONE BYTE — position 9, XFL, 0 against 2 — and is
+ *   1152 bytes either way. For this input, stamping the byte would have produced
+ *   the identical artifact. It is identical by coincidence of a small input: over
+ *   this repo's full `CHANGELOG.md` the same two levels differ by thousands of
+ *   bytes. A rule that happens to hold on today's input is not the rule.
+ */
+export async function gzipDeterministic(input, level) {
+    const out = await gzip(input, level === undefined ? undefined : { level });
     if (out.byteLength < 10 || out[0] !== 0x1f || out[1] !== 0x8b) {
         throw new Error('gjsify ship: internal error — gzip did not produce a gzip stream.');
     }
@@ -19,3 +63,11 @@ export async function gzipDeterministic(input) {
     out[9] = 3;
     return out;
 }
+/**
+ * `gzip -9`, the level Debian Policy § 4.4 asks of a packaging changelog.
+ *
+ * Named rather than spelled `9` at the call site so the reason travels with the
+ * number: the `-n` half of Policy's `gzip -9 -n` is what {@link gzipDeterministic}
+ * already does to bytes 4-7.
+ */
+export const POLICY_MAX_COMPRESSION = 9;

package/lib/utils/ship/plan.d.ts

@@ -67,11 +67,39 @@ export declare function planOverlay(settings: ShipSettings, format: FormatDescri
  */
 export declare function assertOverlayIsLicensed(formatId: FormatId, binaryName: string, overlay: readonly StagedFile[]): void;
 /**
- * The hicolor subdirectory for an icon: `scalable` for SVG, otherwise the
- * pixel size read from a `<n>x<n>` path component or a trailing number in the
- * filename.
+ * Whether an icon belongs in the theme's SYMBOLIC context rather than at a size.
+ *
+ * `symbolic` is a directory of its own in a hicolor theme and NOT a size value.
+ * Measured in `refs/adwaita-icon-theme/index.theme`, which lists `symbolic/apps`
+ * in `Directories=` beside `scalable/apps` and `16x16/apps` and gives it its own
+ * section — `Context=Applications`, `Size=16`, `MinSize=8`, `MaxSize=512`,
+ * `Type=Scalable` — against the scalable row's `Size=128`. The freedesktop icon
+ * theme specification has no notion of `symbolic` at all: a theme expresses it by
+ * giving the directory a section, which is exactly why reading the EXTENSION
+ * cannot see it, and why this question has to be asked before the size one.
+ *
+ * TWO SIGNALS, the same pair `iconThemeDir` already reads for a size: the
+ * directory an author put the file in, and the name they gave it. GTK resolves a
+ * symbolic icon by the `-symbolic` name suffix, so an author who wrote the name
+ * has said as much as one who wrote the path.
+ *
+ * SVG ONLY, because the symbolic directory is declared `Type=Scalable`: the
+ * raster form GTK's own `gtk-encode-symbolic-svg` produces
+ * (`<name>-symbolic.symbolic.png`) is installed at a SIZE instead. So a PNG keeps
+ * answering the size question, and one that cannot answer it stays refused rather
+ * than quietly becoming a scalable icon that does not scale.
+ */
+export declare function isSymbolicIcon(iconPath: string): boolean;
+/**
+ * The hicolor subdirectory for an icon: the `symbolic` CONTEXT, else `scalable`
+ * for an SVG, else the pixel size read from a `<n>x<n>` path component or a
+ * trailing number in the filename.
+ *
+ * Named for the theme DIRECTORY rather than a size from the moment the first of
+ * those answers stopped being one: `iconSizeDir` returning `symbolic` would be a
+ * name every caller has to read past.
  */
-export declare function iconSizeDir(iconPath: string): string;
+export declare function iconThemeDir(iconPath: string): string;
 /**
  * A native module inside the payload has to keep its executable bit.
  *