@gjsify/cli 0.13.2 → 0.15.1

package/lib/commands/workspace.js

@@ -15,8 +15,9 @@
 // failures on uninbuilt workspace deps are the single biggest local-dev
 // pain point in this monorepo.
 import { spawn } from 'node:child_process';
-import { buildDependencyGraph, discoverWorkspaces, topologicalSort, } from '@gjsify/workspace';
+import { buildDependencyGraph, discoverWorkspaces, topologicalSort } from '@gjsify/workspace';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
+import { BuildCacheRunner, buildCacheEnabledByEnv } from '../utils/build-cache.js';
 import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
 export const workspaceCommand = {
     command: 'workspace <name> <script> [args..]',
@@ -41,7 +42,7 @@ export const workspaceCommand = {
         // `-t`/`--topological` is the same flag spelled the way
         // `gjsify foreach` already spells it — kept as an alias so
         // muscle memory transfers.
-        description: 'Pre-build the target workspace\'s transitive workspace dependencies in topological order before running the script in the target. Deps that don\'t declare the script are skipped (--if-present behaviour). Replaces manual `gjsify workspace A build && gjsify workspace B build && …` chains.',
+        description: "Pre-build the target workspace's transitive workspace dependencies in topological order before running the script in the target. Deps that don't declare the script are skipped (--if-present behaviour). Replaces manual `gjsify workspace A build && gjsify workspace B build && …` chains.",
         type: 'boolean',
         alias: ['d', 't', 'topological'],
         default: false,
@@ -61,6 +62,10 @@ export const workspaceCommand = {
         type: 'boolean',
         alias: 'v',
         default: false,
+    })
+        .option('cached', {
+        description: 'Content-hash build cache (ADR 0006): skip the script for a workspace whose inputs (src/**, package.json, tsconfig*.json, transitive workspace deps, toolchain versions) are unchanged and restore its stored outputs instead; on miss run it and store the output dirs it modified. Also applies to the deps run via --with-dependencies. Default from GJSIFY_BUILD_CACHE=1.',
+        type: 'boolean',
     }),
     handler: async (args) => {
         // Walk up to the monorepo root — `gjsify workspace` is often
@@ -97,6 +102,20 @@ export const workspaceCommand = {
         else {
             runList = [target];
         }
+        // Content-hash build cache (ADR 0006 phase 1). Explicit --cached /
+        // --no-cached wins; GJSIFY_BUILD_CACHE=1 is the env default so root
+        // script chains opt in without editing every nested invocation. Keys
+        // are computed against ALL discovered workspaces.
+        const cached = args.cached ?? buildCacheEnabledByEnv();
+        const cache = cached
+            ? new BuildCacheRunner({
+                root,
+                workspaces: allWorkspaces,
+                script: args.script,
+                args: args.args ?? [],
+                targets: runList.map((w) => w.name),
+            })
+            : undefined;
         const failures = [];
         for (const ws of runList) {
             const scripts = ws.manifest.scripts ?? {};
@@ -104,13 +123,14 @@ export const workspaceCommand = {
                 // Skip deps that don't declare the script — mirrors
                 // `gjsify foreach`'s --if-present behaviour. The target
                 // itself was validated above; this branch only filters
-                // intermediate deps.
+                // intermediate deps. A skipped package is also never touched
+                // by the build cache (the no-build-package safety rule).
                 if (verbose)
                     console.error(`[${ws.name}] (no "${args.script}" script — skipping)`);
                 continue;
             }
             try {
-                await runOne(ws, args.script, args.args ?? [], runner, verbose);
+                await runOne(ws, args.script, args.args ?? [], runner, verbose, cache);
             }
             catch (err) {
                 const e = err instanceof Error ? err : new Error(String(err));
@@ -175,7 +195,14 @@ function collectTransitiveClosure(target, allWorkspaces, includeDev) {
     }
     return out;
 }
-async function runOne(ws, script, extraArgs, runner, verbose) {
+async function runOne(ws, script, extraArgs, runner, verbose, cache) {
+    // Build-cache fast path: on a key hit restore the stored outputs and
+    // skip the script; on a miss snapshot the output dirs so only what the
+    // script MODIFIED is stored after success (never a committed no-build
+    // lib/ — see utils/build-cache.ts).
+    if (cache && cache.tryRestore(ws))
+        return;
+    const before = cache?.snapshotOutputs(ws);
     const argv = runner === 'gjsify'
         ? ['run', script, ...extraArgs]
         : ['run', script, ...(extraArgs.length > 0 ? ['--', ...extraArgs] : [])];
@@ -202,6 +229,8 @@ async function runOne(ws, script, extraArgs, runner, verbose) {
         });
         child.on('error', reject);
     });
+    if (cache && before)
+        cache.storeAfterSuccess(ws, before);
 }
 function detectPackageManager() {
     // Under GJS there is no Node, so neither `npm` nor `yarn` can run scripts —

package/lib/utils/build-cache.d.ts

@@ -0,0 +1,157 @@
+import { type Workspace } from '@gjsify/workspace';
+/** Bump to invalidate every existing cache entry (schema/semantic changes). */
+export declare const BUILD_CACHE_LAYOUT_VERSION = "v1";
+/** Conventional per-package build output directories, checked in this order. */
+export declare const OUTPUT_DIR_CANDIDATES: readonly ["lib", "dist", "dist-templates"];
+/** Keep at most this many keys per package; evict the least recently stored/used. */
+export declare const MAX_KEYS_PER_PACKAGE = 2;
+/** Toolchain packages whose resolved versions salt every cache key. */
+export declare const TOOLCHAIN_PACKAGES: readonly ["@gjsify/cli", "@gjsify/tsc", "rolldown", "typescript"];
+export interface BuildCacheManifest {
+    version: 1;
+    layout: string;
+    package: string;
+    script: string;
+    key: string;
+    /** Output dirs (relative to the package dir) the build modified. */
+    dirs: string[];
+    /** Content hash of the stored output dirs (mtime-independent). */
+    outputsHash: string;
+    createdAt: string;
+    usedAt: string;
+}
+/** `true` when GJSIFY_BUILD_CACHE is set to a non-empty, non-"0"/"false" value. */
+export declare function buildCacheEnabledByEnv(env?: Record<string, string | undefined>): boolean;
+/** Cache root for a workspace: `<root>/node_modules/.cache/gjsify/build`. */
+export declare function buildCacheRoot(workspaceRoot: string): string;
+/**
+ * Directory-safe package name. Scoped names collapse (`@gjsify/cli` →
+ * `gjsify-cli`); an 8-hex sha256 suffix of the exact name rules out
+ * collisions between e.g. `@a/b-c` and `@a-b/c`.
+ */
+export declare function sanitizePackageDirName(name: string): string;
+/** Streamed sha256 of one file (bounded memory, real contents). */
+export declare function hashFileStream(path: string): string;
+/**
+ * Content hash of a package's build INPUTS: every file under `src/**`, plus
+ * `package.json`, plus root `tsconfig*.json`. Sorted, content-streamed —
+ * mtimes do not participate, so a `git checkout` with identical contents
+ * hashes identically across machines.
+ */
+export declare function hashPackageInputs(location: string): string;
+/**
+ * Mtime-independent content hash of a set of output dirs — used to skip the
+ * restore copy when the on-disk outputs already match the cached entry, and
+ * as an integrity stamp of what was stored.
+ */
+export declare function hashOutputDirs(location: string, dirs: readonly string[]): string;
+/**
+ * Cheap per-dir change signature (existence + file list + sizes + mtimes).
+ * Taken BEFORE running the script and compared AFTER, to detect which output
+ * dirs the build actually modified. Content hashing is deliberately avoided
+ * here — a build that rewrites identical bytes still bumps mtimes, and that
+ * is exactly the "this dir belongs to the build" signal we want.
+ */
+export declare function snapshotOutputDirs(location: string): Record<string, string | null>;
+/** Output dirs whose signature changed (or that newly appeared) since `before`. */
+export declare function modifiedOutputDirs(location: string, before: Record<string, string | null>): string[];
+export interface ComposeCacheKeyInput {
+    script: string;
+    /** Extra args forwarded to the script invocation (affect the outputs). */
+    args?: readonly string[];
+    /** Toolchain package → resolved version (or 'none'). */
+    toolchain: Record<string, string>;
+    /** The package's own input hash. */
+    ownHash: string;
+    /** dep name → input hash for the FULL transitive workspace-dep closure. */
+    depHashes: ReadonlyMap<string, string> | Record<string, string>;
+}
+/** Deterministic cache key (32 hex chars) from all invalidation ingredients. */
+export declare function composeCacheKey(input: ComposeCacheKeyInput): string;
+/**
+ * Resolve the toolchain versions that salt every key from the workspace's
+ * OWN resolution (`<root>/node_modules/<pkg>/package.json`). In the gjsify
+ * monorepo these are symlinks into the workspace itself, so a CLI/tsc bump
+ * invalidates immediately. A package that isn't resolvable maps to 'none'
+ * (deterministic). `@gjsify/cli` additionally falls back to the RUNNING
+ * CLI's own version so globally-installed CLIs still salt correctly.
+ */
+export declare function resolveToolchainVersions(workspaceRoot: string): Record<string, string>;
+/** Directory of one cache entry: `<cacheRoot>/<pkg-sanitized>/<key>`. */
+export declare function buildCacheEntryDir(cacheRoot: string, pkgName: string, key: string): string;
+/** Read + validate a cache entry's manifest; any mismatch is a MISS (null). */
+export declare function readCacheEntry(cacheRoot: string, pkgName: string, key: string): BuildCacheManifest | null;
+/**
+ * Store the given output dirs of a package under `key`. Atomic: builds a
+ * `.tmp-<pid>` sibling then renames into place, so concurrent readers never
+ * observe a partial entry. Best-effort — failures are swallowed (the build
+ * itself already succeeded).
+ */
+export declare function storeCacheEntry(cacheRoot: string, pkg: {
+    name: string;
+    location: string;
+}, key: string, script: string, dirs: readonly string[]): BuildCacheManifest | null;
+/**
+ * Restore a validated entry into the package. Replaces EXACTLY the dirs the
+ * manifest records (delete-then-copy within the package); skips the copy
+ * when the on-disk outputs already content-match the entry. Returns how the
+ * hit was satisfied, or null when restoration failed (treat as MISS).
+ */
+export declare function restoreCacheEntry(cacheRoot: string, pkg: {
+    name: string;
+    location: string;
+}, manifest: BuildCacheManifest): 'restored' | 'up-to-date' | null;
+/** Evict the oldest entries (by last store/use) beyond `keep` per package. */
+export declare function pruneCacheEntries(cacheRoot: string, pkgName: string, keep?: number): void;
+export interface BuildCacheRunnerOptions {
+    /** Workspace (monorepo) root — owns node_modules/.cache. */
+    root: string;
+    /** ALL discovered workspaces (not just the selected set) for dep closure. */
+    workspaces: readonly Workspace[];
+    /** Script name being run (part of every key). */
+    script: string;
+    /** Extra args forwarded to every invocation (part of every key). */
+    args?: readonly string[];
+    /**
+     * Workspace names that will be run. Their input hashes (plus their
+     * closures') are computed EAGERLY at construction so every key reflects
+     * the tree state at RUN START — a build that mutates its own `src/`
+     * (adwaita-web's generated stylesheet module) must not make a sibling's
+     * key depend on scheduling order within the same run.
+     */
+    targets?: readonly string[];
+    /** Log sink (default: stderr, keeping stdout clean for script output). */
+    log?: (line: string) => void;
+}
+export declare function buildCacheOptedOut(ws: Workspace): boolean;
+/**
+ * Per-run orchestrator used by `gjsify workspace` / `gjsify foreach`:
+ * memoizes input hashes + keys across packages, restores on hit, snapshots +
+ * stores on miss. All entry points are fail-soft — any internal error logs a
+ * warning and reports a MISS so the script runs normally.
+ */
+export declare class BuildCacheRunner {
+    private readonly options;
+    private readonly cacheRoot;
+    private readonly graph;
+    private readonly toolchain;
+    private readonly ownHashes;
+    private readonly closures;
+    private readonly keys;
+    private readonly log;
+    constructor(options: BuildCacheRunnerOptions);
+    private ownHashOf;
+    /** BFS transitive workspace-dep closure (cycle-safe), excluding `name` itself. */
+    private closureOf;
+    /** Content-hash cache key for one workspace (memoized per run). */
+    keyFor(ws: Workspace): string;
+    /**
+     * Try to satisfy the script from the cache. Returns `true` on a hit
+     * (outputs restored / already current — the caller SKIPS the script).
+     */
+    tryRestore(ws: Workspace): boolean;
+    /** Snapshot the candidate output dirs BEFORE running the script. */
+    snapshotOutputs(ws: Workspace): Record<string, string | null>;
+    /** After a SUCCESSFUL script run: store the dirs the build modified. */
+    storeAfterSuccess(ws: Workspace, before: Record<string, string | null>): void;
+}