@gjsify/cli 0.14.0 → 0.15.1

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;
+}