@gjsify/cli 0.36.0 → 0.38.0

package/lib/utils/dep-aggregation.js

@@ -1,16 +1,8 @@
-// Workspace-aware dependency aggregation for `gjsify upgrade`.
-//
-// Given a flat list of per-workspace dependency declarations, group them by
-// package name and surface inconsistencies (the same package declared at
-// different version ranges across workspaces). Used by:
-//
-//   - `gjsify upgrade` interactive table — shows fan-out (count of workspaces
-//     declaring the dep) and flags inconsistent declarations with `⚠`.
-//   - `gjsify upgrade --align` — offline mode that detects inconsistencies
-//     and proposes a single range (the highest semver-satisfying one) without
-//     hitting the registry.
-//   - `gjsify upgrade --check` — CI gate that exits non-zero when any
-//     inconsistency exists.
+// Workspace-aware dependency aggregation for `gjsify upgrade`: group per-workspace
+// declarations by package name and surface inconsistencies — the same package
+// declared at different ranges across workspaces. Drives the interactive table's
+// fan-out column, `--align` (propose one range offline, no registry hit) and
+// `--check` (CI gate, non-zero on any inconsistency).
 import { compare, parse } from '@gjsify/semver';
 /** Local `gt` shim: `@gjsify/semver` exports `compare` returning -1|0|1. */
 function semverGt(a, b) {
@@ -22,9 +14,8 @@ function semverGt(a, b) {
     }
 }
 /**
- * Group a flat list of `DepDeclaration`s by dep name. Each group has the full
- * occurrence list plus pre-computed aggregates (consensus range, highest
- * declared version) so callers don't have to re-scan.
+ * Group a flat list of `DepDeclaration`s by dep name, pre-computing the aggregates
+ * so no caller has to re-scan the occurrences.
  */
 export function groupByDependency(decls) {
     const map = new Map();
@@ -48,8 +39,7 @@ export function groupByDependency(decls) {
             }
         }
     }
-    // Second pass: dominantRange = the range with the most occurrences;
-    // ties resolve by highest semver, then by lexicographic order.
+    // dominantRange = most occurrences; ties break on highest semver, then lexically.
     for (const g of map.values()) {
         const counts = new Map();
         for (const occ of g.occurrences) {
@@ -77,10 +67,7 @@ export function groupByDependency(decls) {
 export function isInconsistent(group) {
     return group.declaredRanges.size > 1;
 }
-/**
- * Filter to just the inconsistent groups (>1 distinct range across workspaces).
- * Convenience wrapper for `--align` and `--check` modes.
- */
+/** The inconsistent groups only — what `--align` and `--check` operate on. */
 export function findInconsistencies(groups) {
     return groups.filter(isInconsistent);
 }

package/lib/utils/detect-native-packages.d.ts

@@ -6,38 +6,32 @@ export interface NativePackage {
     prebuildsDir: string;
 }
 /**
- * Which C library an artifact is built against. npm's own `libc` manifest field
- * uses exactly these two tokens, and it is LINUX-ONLY there — every other OS has
- * one C library, so the axis does not exist off Linux and is `null` there rather
- * than defaulted to something.
+ * Which C library an artifact is built against. npm's own `libc` manifest field uses
+ * exactly these two tokens and is LINUX-ONLY — every other OS has one C library, so
+ * the axis is `null` off Linux rather than defaulted to something.
  */
 export type HostLibc = 'glibc' | 'musl';
 /** The host target a resolution is performed for. Defaults to the running process. */
 export interface HostTarget {
-    /** `process.platform` value — `linux` | `darwin` | `win32` | … */
     platform?: string;
-    /** `process.arch` value — `x64` | `arm64` | `ppc64` | `s390x` | `riscv64` | … */
     arch?: string;
     /**
-     * Host C library, or `undefined`/`null` when the axis does not apply (any
-     * non-Linux OS) or could not be determined. Both non-values mean the same
-     * thing to the resolver: behave exactly as before the libc axis existed —
-     * never offer a `-musl` directory. That is deliberately the conservative
-     * direction: an unsuffixed directory is the DEFAULT build, so a host we
-     * cannot classify still resolves what it always did.
+     * Host C library, or `undefined`/`null` when the axis does not apply (non-Linux)
+     * or could not be determined. Both non-values mean the same thing: never offer a
+     * `-musl` directory, exactly as before the axis existed. Conservative on purpose —
+     * an unsuffixed directory is the DEFAULT build, so an unclassifiable host still
+     * resolves what it always did.
      */
     libc?: HostLibc | null;
 }
 /**
- * Environment a GJS process needs so `gi://Gjsify…` imports resolve against
- * the detected prebuilds. `GI_TYPELIB_PATH` is universal (girepository reads
- * it on every OS); the *library* search path is whatever the host's dynamic
- * loader actually consults, which is a different variable per OS — see
+ * Environment a GJS process needs so `gi://Gjsify…` imports resolve against the
+ * detected prebuilds. `GI_TYPELIB_PATH` is universal (girepository reads it on every
+ * OS); the *library* search path is a different variable per OS — see
  * {@link buildNativeEnv}.
  *
- * The index signature exists for the Windows case, where the key is the host's
- * own `PATH` spelling (`Path` on a stock Windows env block) rather than a
- * fixed literal.
+ * The index signature exists for Windows, where the key is the host's own `PATH`
+ * spelling (`Path` on a stock env block) rather than a fixed literal.
  */
 export interface NativeEnv {
     GI_TYPELIB_PATH: string;
@@ -55,35 +49,27 @@ export interface NativeEnv {
     [key: string]: string | undefined;
 }
 /**
- * Split a prebuild target into its three axes.
- *
- * TOKEN GRAMMAR: `<os>-<arch>[-musl]`.
- *
- * An UNSUFFIXED token means "the default build". Note what it does NOT mean: it
- * is not a synonym for glibc. For an artifact that links `libc.so.6` the default
- * build IS glibc; for one that links only GLib/GObject/GIO (plus GnuTLS resp.
- * GStreamer) it is libc-AGNOSTIC and loads against whatever libc the host's GLib
- * was built for. The directory name cannot express that difference and does not
- * need to: the package's own `libc` field answers it at install time, and the
- * `prebuild-libc` conformance rule verifies that field against the binaries
- * (`readElfNeeded` — the DT_NEEDED list is where the answer actually lives).
- *
- * DELIBERATELY NOT CHOSEN: renaming every existing `linux-<arch>` directory to
- * `linux-<arch>-gnu`, which is what a symmetric grammar would demand. It would
- * rename ~60 COMMITTED directories, and — per `status/open-todos.md`'s
- * "Nine fixtures re-implement the prebuild-target name instead of importing it"
- * — nine e2e fixtures COMPOSE the token themselves instead of importing it, so
- * the rename would have to be swept by hand in two shapes (the literal path and
- * the computed one), which is exactly how the last vocabulary change missed
- * `tests/e2e/self-host/run.mjs`. The asymmetric grammar buys the same
- * expressiveness for zero renames, and the cost — that "unsuffixed" is not
- * self-describing — is paid by a field that is machine-checked anyway.
- *
- * A `-musl` suffix is only meaningful when the OS half is `linux`: musl targets
- * no other kernel, and npm's own `libc` field is documented as Linux-only. A
- * `darwin-arm64-musl` token is therefore not a target with an odd name, it is a
- * malformed one, and this returns `libc: null` for it so callers report the
- * token rather than half-honouring it.
+ * Split a prebuild target into its three axes. TOKEN GRAMMAR: `<os>-<arch>[-musl]`.
+ *
+ * An UNSUFFIXED token means "the default build", NOT a synonym for glibc. For an
+ * artifact linking `libc.so.6` the default build IS glibc; for one linking only
+ * GLib/GObject/GIO it is libc-AGNOSTIC and loads against whatever libc the host's GLib
+ * was built for. The directory name cannot express that and does not need to — the
+ * package's own `libc` field answers it at install time, verified against the binaries'
+ * DT_NEEDED list by the `prebuild-libc` conformance rule.
+ *
+ * DELIBERATELY NOT CHOSEN: the symmetric grammar, renaming every `linux-<arch>` to
+ * `linux-<arch>-gnu`. That is ~60 committed directories plus nine e2e fixtures that
+ * COMPOSE the token instead of importing it (open-todos: "Nine fixtures re-implement
+ * the prebuild-target name instead of importing it"), so the sweep would have to be
+ * done by hand in two shapes — the literal path and the computed one — which is
+ * exactly how the last vocabulary change missed `tests/e2e/self-host/run.mjs`. The
+ * asymmetric grammar is equally expressive for zero renames.
+ *
+ * A `-musl` suffix is only meaningful when the OS half is `linux`: musl targets no
+ * other kernel and npm's `libc` field is documented Linux-only. `darwin-arm64-musl` is
+ * therefore malformed rather than oddly named, and this returns `libc: null` for it so
+ * callers report the token instead of half-honouring it.
  */
 export declare function parsePlatformToken(token: string): {
     os: string;
@@ -91,83 +77,64 @@ export declare function parsePlatformToken(token: string): {
     libc: HostLibc | null;
 };
 /**
- * Canonical `<os>-<arch>[-musl]` form — the node spelling — so `linux-x86_64`
- * and `linux-x64` compare equal. Only the *arch* half is normalised: the OS half
- * is always a `process.platform` token (`linux`/`darwin`/`win32`), which has no
- * competing spelling, and the libc half has exactly one spelling by
- * construction.
- *
- * A `-musl` suffix on a non-Linux token is preserved verbatim rather than
- * dropped. Silently canonicalising `darwin-arm64-musl` to `darwin-arm64` would
- * make a malformed declaration compare EQUAL to a valid one, so the audit that
- * rejects it would never see it — the same class of bug as folding the legacy
- * uname spelling on a WRITE path.
+ * Canonical `<os>-<arch>[-musl]` (node spelling) so `linux-x86_64` and `linux-x64`
+ * compare equal. Only the *arch* half is normalised — the OS half is always a
+ * `process.platform` token with no competing spelling, and the libc half has exactly
+ * one spelling by construction.
+ *
+ * A `-musl` suffix on a non-Linux token is preserved rather than dropped: silently
+ * canonicalising `darwin-arm64-musl` to `darwin-arm64` would make a malformed
+ * declaration compare EQUAL to a valid one, so the audit that rejects it would never
+ * see it.
  */
 export declare function canonicalPlatformToken(token: string): string;
 /**
- * The target tokens that describe THIS host, most-specific first — the WRITE-side
- * vocabulary.
- *
- * This is the single definition of the musl preference order, and three callers
- * share it so it cannot drift: the directory probe ({@link prebuildDirCandidates}),
- * the per-platform sibling package probe ({@link platformPackageName}), and
- * `scripts/stage-prebuild.mjs`, which must stage a musl build into
- * `linux-x64-musl/` and never into `linux-x64/`.
- *
- * On a musl host the suffixed token comes FIRST and the unsuffixed one stays as a
- * fallback: an unsuffixed directory is the default build, which for the
- * libc-agnostic bridges (they record no `libc.so.6` at all) genuinely does load
- * on musl. On glibc the `-musl` token is not offered at all — a musl artifact
- * cannot load against glibc, so probing for it could only ever produce a
- * false positive.
- *
- * @param platform `process.platform` value.
- * @param arch `process.arch` value.
- * @param libc host C library; `undefined`/`null` behaves as glibc (see
- *   {@link HostTarget.libc} for why that is the safe default).
+ * The target tokens describing THIS host, most-specific first — the WRITE-side
+ * vocabulary, and the SINGLE definition of the musl preference order. Three callers
+ * share it so it cannot drift: the directory probe ({@link prebuildDirCandidates}), the
+ * companion-package probe ({@link platformPackageName}), and `scripts/stage-prebuild.mjs`,
+ * which must stage a musl build into `linux-x64-musl/` and never into `linux-x64/`.
+ *
+ * On a musl host the suffixed token comes FIRST with the unsuffixed one as fallback,
+ * because an unsuffixed directory is the default build and the libc-agnostic bridges
+ * (no `libc.so.6` recorded at all) genuinely do load on musl. On glibc the `-musl`
+ * token is not offered at all — a musl artifact cannot load against glibc, so probing
+ * for it could only produce a false positive.
+ *
+ * @param libc `undefined`/`null` behaves as glibc — see {@link HostTarget.libc}.
  */
 export declare function hostPlatformTokens(platform: string, arch: string, libc?: HostLibc | null): string[];
 /**
  * The prebuild directory names to probe for a host, most-specific first.
  *
- * The canonical name is `${process.platform}-${process.arch}` — `linux-x64`,
- * `linux-arm64`, `darwin-arm64`, `win32-x64`. Every package in the release
- * train declares it (`gjsify.platforms`), `scripts/stage-prebuild.mjs` is the
- * only thing that creates it, and `scripts/audit-runtimes.mjs --check` rejects
- * any other spelling, so the three can no longer drift.
- *
- * Two probes remain BEHIND that canonical name, and both are backward
- * compatibility with tarballs already on npm — not a second convention:
- *
- *   1. **The package's own declared spelling.** A tarball published before the
- *      rename declares (and ships) `linux-x86_64`; probing its declaration
- *      first loads it without the CLI having to guess. This is also what makes
- *      the rename work in the OTHER direction — an older CLI resolving a newer
- *      package — because `canonicalPlatformToken` folds both spellings onto
- *      one form at both ends.
- *   2. **The legacy uname spelling.** Only reachable for a package that ships
- *      a prebuild dir and declares NO `gjsify.platforms` at all — i.e. a
- *      tarball predating the OS-axis audit, or a third-party package using
- *      `gjsify.prebuilds` without the declaration. Inside this repo the audit
- *      makes that state impossible.
- *
- * Both are pure array entries matched against an already-read directory
- * listing — no extra I/O — so tolerance on the READ side costs nothing, while
- * the single spelling is enforced everywhere a name is WRITTEN.
- *
- * The LIBC AXIS rides in front of all of that: on a musl host the
- * `<os>-<arch>-musl` token is preferred over `<os>-<arch>`, and on glibc the
- * suffixed token is NEVER offered (a musl artifact cannot load against glibc, so
- * a probe for it can only produce a false positive). The `libc` value is a
- * PARAMETER rather than a `process` read for the same reason `platform` and
- * `arch` are: it is the only way the musl branch gets exercised at all, since CI
- * and every developer machine here run glibc.
- *
- * @param platform `process.platform` value.
- * @param arch `process.arch` value.
+ * The canonical name is `${process.platform}-${process.arch}`. Every package in the
+ * release train declares it (`gjsify.platforms`), `scripts/stage-prebuild.mjs` is the
+ * only thing that creates it, and `scripts/audit-runtimes.mjs --check` rejects any
+ * other spelling, so the three cannot drift.
+ *
+ * Two probes sit BEHIND it, both backward compatibility with tarballs already on npm
+ * rather than a second convention:
+ *
+ *   1. **The package's own declared spelling.** A pre-rename tarball declares and
+ *      ships `linux-x86_64`, so probing its declaration first loads it without
+ *      guessing. This is also what makes the rename work in the OTHER direction (an
+ *      older CLI, a newer package), since `canonicalPlatformToken` folds both
+ *      spellings onto one form at both ends.
+ *   2. **The legacy uname spelling.** Only reachable for a package that ships a
+ *      prebuild dir and declares NO `gjsify.platforms` — a tarball predating the
+ *      OS-axis audit, or a third-party package. The audit makes that state impossible
+ *      inside this repo.
+ *
+ * Both are array entries matched against an already-read directory listing, so
+ * tolerance on the READ side costs no I/O while the single spelling stays enforced
+ * everywhere a name is WRITTEN.
+ *
+ * The LIBC AXIS rides in front of all of it (see {@link hostPlatformTokens}). `libc` is
+ * a PARAMETER rather than a `process` read for the same reason `platform` and `arch`
+ * are: it is the only way the musl branch is exercised at all, since CI and every
+ * developer machine here run glibc.
+ *
  * @param declaredPlatforms `package.json#gjsify.platforms`, when present.
- * @param libc host C library; `undefined`/`null` = behave as before the axis
- *   existed.
  */
 export declare function prebuildDirCandidates(platform: string, arch: string, declaredPlatforms?: readonly string[] | undefined, libc?: HostLibc | null): string[];
 /**
@@ -318,12 +285,12 @@ export declare function libraryPathVar(platform: string): {
  *      exactly the "nothing else found it" case. Consequence, and it is the
  *      intended precedence: gjsify's own prebuilds keep priority through the
  *      override variable, the system stack fills in behind it.
- *   2. **Our dirs go FIRST, an inherited fallback is kept BEHIND them, and
- *      `/usr/lib` is appended when there is none.** Setting the variable
- *      REPLACES dyld's own default fallback list, so writing only our dirs would
- *      silently remove `/usr/lib` from the search — a host that exported the
- *      variable itself already carries whatever tail it wants. Same composition
- *      as node-gi's re-exec.
+ *   2. **Our dirs go FIRST, an inherited fallback behind them, and dyld's own
+ *      default list behind that** — `composeDyldFallback()`, the same
+ *      composition node-gi's re-exec uses. Setting the variable REPLACES that
+ *      default list rather than extending it, so any composition that does not
+ *      carry it hands the child a SMALLER search path than it would have had
+ *      with the variable unset.
  *
  * Emitted even when `packages` is empty: the gap is in the host's loader, not in
  * a gjsify prebuild, so a plain `gjsify run script.gjs.js` that touches GTK needs