@scriptc/compiler 0.0.34 → 0.0.36

package/dist/backend/native-link-info.test.js

@@ -0,0 +1,134 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { loadFfiProfile } from "../ffi/ffi-manifest.js";
+import { createNativeLinkInfo } from "./native-link-info.js";
+import { MACOS_ARM64_TARGET } from "./targets.js";
+const BASE = {
+    dynamic: false,
+    regex: false,
+    copying: false,
+    textDecoderLegacy: false,
+    fileHandle: false,
+    fetch: false,
+    netIsland: false,
+    zlib: false,
+    assert: false,
+    inspect: false,
+    dynInvoke: false,
+    dc: false,
+    dynAsync: false,
+    events: false,
+    emitter: false,
+    symbol: false,
+    searchParams: false,
+    qs: false,
+    parseArgs: false,
+    stream: false,
+    net: false,
+    http: false,
+    http2: false,
+    dgram: false,
+    watch: false,
+    foreignFfi: false,
+    nodeTest: false,
+    tls: false,
+    tlsCa: false,
+};
+describe("native link info recipes", () => {
+    test("feature source sets reproduce runtime and vendor gates", async () => {
+        const info = await createNativeLinkInfo({
+            programObject: "/out/app.o",
+            target: MACOS_ARM64_TARGET,
+            features: {
+                ...BASE,
+                dynamic: true,
+                regex: true,
+                inspect: true,
+                zlib: true,
+                tls: true,
+            },
+            ffi: null,
+        });
+        const runtime = info.runtime_pack.source_sets.find((set) => set.name === "runtime");
+        expect(runtime.sources).toEqual(expect.arrayContaining([
+            "src/scr_regex.c",
+            "src/scr_assert.c",
+            "src/scr_inspect.c",
+            "src/scr_zlib.c",
+            "src/scr_zlib_island.c",
+            "src/scr_tls.c",
+            "src/scr_tls_ca.c",
+            "src/scr_island.c",
+            "src/scr_web.c",
+            "src/scr_inspect_island.c",
+        ]));
+        expect(info.runtime_pack.source_sets.map((set) => set.name)).toEqual([
+            "runtime", "quickjs", "mbedtls",
+        ]);
+        expect(info.runtime_pack.source_sets.find((set) => set.name === "mbedtls").sources.length)
+            .toBeGreaterThan(100);
+        expect(info.link.system_libraries).toEqual(["System", "z", "m"]);
+    });
+    test("dev object recipes keep runtime optimization in lockstep", async () => {
+        const info = await createNativeLinkInfo({
+            programObject: "/out/app.o",
+            target: MACOS_ARM64_TARGET,
+            features: BASE,
+            ffi: null,
+            optimization: "dev",
+        });
+        expect(info.runtime_pack.source_sets[0]?.c_flags).toContain("-O0");
+        expect(info.runtime_pack.source_sets[0]?.c_flags).not.toContain("-O2");
+        // External objects are compiled separately and the driver recipe is an
+        // executable link. The two halves must not leak into each other's recipe.
+        expect(info.runtime_pack.source_sets[0]?.c_flags).not.toContain("-Wl,-dead_strip");
+        expect(info.link.driver_flags).toContain("-Wl,-dead_strip");
+    });
+    test("static external-object links dead-strip just like dynamic links", async () => {
+        const info = await createNativeLinkInfo({
+            programObject: "/out/app.o",
+            target: MACOS_ARM64_TARGET,
+            features: BASE,
+            ffi: null,
+        });
+        expect(info.link.driver_flags).toContain("-Wl,-dead_strip");
+    });
+    test("FFI symbols and resolved inputs remain ordered before the runtime", async () => {
+        const dir = await mkdtemp(join(tmpdir(), "scriptc-native-link-info-unit-"));
+        const library = join(dir, "native.o");
+        const manifest = join(dir, "ffi.json");
+        await writeFile(library, "fixture");
+        await writeFile(manifest, JSON.stringify({
+            ffi_format: 1,
+            functions: [{
+                    name: "nativeScale",
+                    symbol: "native_scale",
+                    params: ["f64"],
+                    returns: "f64",
+                }],
+            libraries: ["./native.o"],
+            system_libraries: ["sqlite3"],
+        }));
+        const loaded = loadFfiProfile(manifest);
+        if (!loaded.ok)
+            throw new Error(loaded.diagnostics[0]?.message);
+        const info = await createNativeLinkInfo({
+            programObject: "/out/app.o",
+            target: MACOS_ARM64_TARGET,
+            features: BASE,
+            ffi: loaded.profile,
+        });
+        expect(info.ffi).toEqual({
+            format: 1,
+            symbols: ["native_scale"],
+            libraries: [library],
+        });
+        expect(info.link.input_order.slice(0, 3)).toEqual([
+            "/out/app.o", library, "runtime/*.o",
+        ]);
+        expect(info.link.system_libraries).toEqual(["sqlite3", "System"]);
+    });
+});
+//# sourceMappingURL=native-link-info.test.js.map

package/dist/backend/native-link-info.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-link-info.test.js","sourceRoot":"","sources":["../../src/backend/native-link-info.test.ts"],"names":[],"mappings":"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"}

package/dist/backend/{cc.d.ts → native-toolchain.d.ts}

@@ -1,9 +1,30 @@
+export { buildCacheRoot, prepareBuildCacheRoot, pruneBuildCache, resolveBuildCacheRoot, } from "./build-cache.js";
+export declare const EXECUTABLE_RUNTIME_SOURCES: readonly ["scr_number.c", "scr_string.c", "scr_array.c", "scr_bytes.c", "scr_bytes_io.c", "scr_map.c", "scr_closure.c", "scr_ffi.c", "scr_object.c", "scr_union.c", "scr_exception.c", "scr_error.c", "scr_console.c", "scr_lib.c", "scr_path.c", "scr_url.c", "scr_json.c", "scr_async.c", "scr_child.c", "scr_cycle.c"];
+/**
+ * Per-executable section-elimination recipe. This belongs beside the native
+ * driver rather than a particular build path: one-shot compilation, cached
+ * runtime objects, external object recipes, and runtime packs must all agree
+ * on what their final executable linker is allowed to discard.
+ *
+ * Archives and compile-only object/library recipes deliberately do not use
+ * the link half. In particular, `--lib` preserves its established object and
+ * archive contract; section GC is an executable-link optimization only.
+ */
+export declare function executableSectionEliminationFlags(platform: string): {
+    compile: string[];
+    link: string[];
+};
 export interface ToolchainEnvironmentCachePolicy {
     completeArtifacts: boolean;
     runtimeObjects: boolean;
 }
 export declare function toolchainEnvironmentCachePolicy(env?: NodeJS.ProcessEnv): ToolchainEnvironmentCachePolicy;
 export declare function toolchainEnvironmentFingerprint(env?: NodeJS.ProcessEnv): string;
+/** Inputs that can change which native tool/runtime implementation an
+ * executable build selects before compileC has a chance to rediscover it.
+ * The early whole-program cache keys this exact posture before restoring a
+ * final binary; compileC retains its deeper inode/content validation. */
+export declare function executableNativeEnvironmentFingerprint(env?: NodeJS.ProcessEnv): Promise<string>;
 export interface CcOptions {
     /** Path of the generated (or hand-written) program TU: a .c file, or the
      * LLVM backend's .ll — clang compiles IR text natively on the same
@@ -18,6 +39,19 @@ export interface CcOptions {
      * top-level bytes alone can safely represent. scriptc's frontend supplies
      * this for its generated C/LLVM IR; `--from-c` deliberately does not. */
     cacheIdentity?: string;
+    /** Native optimization posture. Release preserves the historical -O2
+     * executable lane; dev selects -O0 and may compile a caller-provided LLVM
+     * shard set into independently cached objects before the final link. */
+    optimization?: "release" | "dev";
+    /** Optional equivalent LLVM modules for dev compilation. Unsupported
+     * targets or merge failures fall back to the canonical cPath TU. */
+    programShards?: readonly {
+        name: string;
+        source: string;
+    }[];
+    /** Canonical externally visible definitions retained while shard merging
+     * demotes generated cross-shard linkage back to local symbols. */
+    programPublicSymbols?: readonly string[];
     /** Build with ASan + the runtime RC audit (test/debug lane). */
     sanitize?: boolean;
     /** Additional native archives/objects, appended after the generated
@@ -32,15 +66,17 @@ export interface CcOptions {
      * cached runtime objects. */
     systemLibraries?: readonly string[];
     /** Embed the dynamic-island engine (--dynamic): compiles scr_island.c,
-     * defines SCR_DYNAMIC, and links the cached libqjs.a. Off = the static
-     * default, byte-identical to builds predating the flag. */
+     * defines SCR_DYNAMIC, and links the cached libqjs.a. Off retains the
+     * static runtime selection; executable section GC may still remove
+     * unreachable static-runtime code. */
     dynamic?: boolean;
     /** The program contains a regex construct (index.ts detects it on the
      * IR): compiles scr_regex.c and links the vendored libregexp — as cached
      * standalone objects in static builds, from the engine archive under
      * --dynamic (one libregexp per binary; its host hooks want the island's
      * JSContext there). Off = regex-free: the command line is exactly the
-     * historical one, so regex-free binaries cannot change by a byte. */
+     * historical runtime selection; executable section GC may remove unrelated
+     * unreachable code. */
     regex?: boolean;
     /** The program uses one of the copying/typed-array bridge intrinsics
      * implemented in scr_copying.c (index.ts detects them on the IR).
@@ -77,10 +113,11 @@ export interface CcOptions {
     netIsland?: boolean;
     /** The program uses zlib (index.ts detects zlib.* libCalls on the IR):
      * compiles scr_zlib.c — the regex/curl gating precedent, so zlib-free
-     * binaries keep their exact link line. Host builds link the SYSTEM libz
-     * (macOS ships it), byte-identical to the historical line; cross targets
-     * compile the vendored zlib per target instead (ensureZlibObjects — zig
-     * has no libz in its sysroots). Compressed bytes may differ between the
+     * binaries keep their exact link line. The default host-clang build links
+     * the SYSTEM libz (macOS ships it), byte-identical to the historical line;
+     * every Zig build compiles the vendored zlib with the selected driver instead
+     * (ensureZlibObjects — zig has no libz in its sysroots). Compressed bytes may
+     * differ between the
      * system and vendored libraries, which is why the corpus only ever
      * compares round-trips and fixed-blob inflation, never raw deflate
      * output. */
@@ -196,6 +233,17 @@ export interface CcOptions {
      * The unit also compiles whenever `tls` does — scr_tls.c consults its
      * default-set override and shared Windows-certificate enumerator. */
     tlsCa?: boolean;
+    /** Internal compiler hook: called only after a strict native artifact hit
+     * or a successful stable build has installed `outPath`. The executable
+     * frontend cache uses it to publish its stamp after native dependencies
+     * have validated; arbitrary compileC callers leave it unset. */
+    onArtifactReady?: (artifact: ValidatedNativeArtifact) => Promise<void>;
+}
+/** Native dependency proof attached to an executable frontend-cache entry.
+ * compileC produces this only after its strict local/CAS validation succeeds;
+ * the early reader replays it before restoring the final executable. */
+export interface ValidatedNativeArtifact {
+    dependencies: NativeArtifactDependency[];
 }
 /** Structured compiler-driver failure. Most callers still let this surface
  * as an internal build error; the TypeScript compiler pipeline recognizes it
@@ -229,6 +277,10 @@ export interface CcDriver {
     /** Platform libraries appended after every object/archive input. */
     linkArgs: string[];
 }
+/** Whether the selected compiler driver is Zig. This is deliberately based on
+ * the executable prefix rather than target presence: targetless Zig is still
+ * a Zig build, while target presence is only the platform/target contract. */
+export declare function isZigDriver(driver: Pick<CcDriver, "argv">): boolean;
 export declare const IPHONEOS_MIN_VERSION = "15.0";
 export declare const ANDROID_MIN_API = 26;
 export declare function isIosTarget(target: string | null): boolean;
@@ -244,30 +296,19 @@ export declare function mobileLibraryTarget(env?: NodeJS.ProcessEnv): string | n
  * inspection — no discovery, no subprocess. */
 export declare function mobileTargetRefusal(target: string, hostPlatform?: NodeJS.Platform): string | null;
 export declare function resolveCc(env?: NodeJS.ProcessEnv, hostPlatform?: NodeJS.Platform): CcDriver;
-/** Musl intentionally has no predefined libc macro. The explicit Zig target
- * is therefore the source of truth for selecting its small runtime shim. */
-export declare function isMuslTarget(driver: Pick<CcDriver, "target">): boolean;
 /** The OS the produced binary runs on: the triple's OS under SCRIPTC_TARGET,
  * the host's otherwise — so platform-conditional link flags follow the
  * TARGET, not the machine running the compiler. Exported for compile()/
  * analyze(): the FRONTEND consults it too (path.sep / os.EOL literals and
  * the path-module binding follow the target — a win32 triple compiles
  * Node-on-Windows semantics, path.win32 backing the bare module). */
+export declare function configuredTargetPlatform(env?: NodeJS.ProcessEnv, hostPlatform?: NodeJS.Platform): string;
 export declare function targetPlatform(driver: CcDriver): string;
 /** Architecture identity for host-native cache entries. Explicit cross targets
  * already name their complete target triple; native builds need the process
  * architecture too because one per-user cache can serve both native and
  * emulated processes (arm64 and Rosetta on macOS, for example). */
 export declare function cacheTargetIdentity(driver: Pick<CcDriver, "target">, hostPlatform?: NodeJS.Platform, hostArch?: string): string;
-/** Cross targets already carry their architecture in the explicit triple.
- * Host-native prerequisites need the same separation: a checkout/package can
- * be used by both arm64 Node and Rosetta/x64 Node on macOS. */
-export declare function vendorCacheTargetFlavor(driver: Pick<CcDriver, "target">, hostPlatform?: NodeJS.Platform, hostArch?: string): string;
-/** Vendor prerequisites live outside the content-addressed build root, so
- * their directory name must carry the same environment and resolved compiler
- * identity as the artifacts that consume them. The short digest keeps the
- * package-local path readable while preventing build-order contamination. */
-export declare function vendorCacheBuildIdentity(environmentFingerprint: string, compilerIdentity: string): string;
 export interface LibArchiveOptions {
     /** The program TU (.c or .ll — clang compiles either with -c). */
     cPath: string;
@@ -275,6 +316,17 @@ export interface LibArchiveOptions {
      * spelling. Library assembly uses this for the identity-free projection of
      * a complete caller-visible TU; its bytes drive every native cache key. */
     programSource?: string;
+    /** Optional equivalent LLVM modules for native compilation. The public
+     * `programSource` remains the canonical TU/cache identity; these stable
+     * shards compile independently and are relocatably merged into one program
+     * object before archive assembly. */
+    programShards?: readonly {
+        name: string;
+        source: string;
+    }[];
+    /** Canonical externally visible definitions retained while the shard merge
+     * demotes generated cross-shard linkage back to local symbols. */
+    programPublicSymbols?: readonly string[];
     /** Tiny generated C source carrying volatile library identity getters.
      * Its bytes join the complete archive key, but the source itself exists
      * only in the invocation-private build directory and the large program-
@@ -324,20 +376,14 @@ export interface LibArchiveOptions {
     textDecoderLegacy?: boolean;
 }
 export declare function compileLibArchive(opts: LibArchiveOptions): Promise<void>;
-/** Resolve the build cache without touching the filesystem. Exported from this
- * internal module so its platform and override behavior can be pinned directly. */
-export declare function resolveBuildCacheRoot(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, userHome?: string): string | null;
-/** Shared persistent-cache root for compiler-level tiers.  The early library
- * cache deliberately follows the native cache's activation and hard-disable
- * contract, while native compilation retains ownership of toolchain safety. */
-export declare function buildCacheRoot(): string | null;
-/** Harden/create a compiler-level cache root using the same privacy policy as
- * the artifact caches.  Failure disables only the optional caller's tier. */
-export declare function prepareBuildCacheRoot(root: string | null): Promise<string | null>;
-/** Register a successful compiler-level cache write with the shared bounded
- * LRU policy. */
-export declare function pruneBuildCache(root: string | null): Promise<void>;
-export declare function ccVersionOnce(argv: string[], environmentFingerprint?: string, fresh?: boolean): Promise<string>;
+/** Persistent caches require an inspectable compiler driver. A general
+ * wrapper can branch on the real source/object paths or argument topology and
+ * inject inputs only into the final invocation; no synthetic metadata probe
+ * can safely represent that behavior. Accept direct Clang/Zig drivers (plus
+ * Apple's system shim) and conservatively keep wrapper-driven builds on the
+ * uncached path. */
+export declare function compilerDriverSupportsPersistentCache(driver: Pick<CcDriver, "argv" | "targetArgs" | "target">, environmentFingerprint: string): Promise<boolean>;
+export declare function ccVersion(argv: string[], environmentFingerprint?: string, fresh?: boolean): Promise<string>;
 /** Every system-header spelling consumed by a source tree scriptc owns. The
  * dependency probe preprocesses these spellings with the selected driver and
  * hashes the resolved files. Runtime-local and vendored source/header bytes
@@ -346,25 +392,71 @@ export declare function ccVersionOnce(argv: string[], environmentFingerprint?: s
  * libregexp, mbedTLS, zlib, curl, and Ryū translation units. */
 export declare function implicitDependencyProbeIncludes(rtDir: string): Promise<string[]>;
 export declare function parseLinkTraceFiles(output: string, cwd: string, excludedRoot: string, driverDryRun?: boolean): Promise<string[]>;
+/** Resolve the exact files consumed by one compiler-driver link invocation.
+ * Runtime packs reuse the native toolchain's strict dry-run plus real linker
+ * trace so a PATH-selected Clang carries its own linker, SDK, compiler
+ * runtime, and injected inputs into the executable cache proof. */
+export declare function nativeLinkerDependencyPaths(linker: string, linkArgs: readonly string[]): Promise<string[]>;
+/** Reset process observations whose validity is bounded to one public native
+ * build. A long-lived caller may change PATH or install/remove ccache between
+ * invocations; the next build must probe that environment again. */
+export declare function clearCcCaches(): void;
 export declare function runtimeFingerprint(rtDir: string): Promise<string>;
+declare const vendorCacheTargetFlavor: (driver: Pick<CcDriver, "target">, hostPlatform?: NodeJS.Platform, hostArch?: string) => string, vendorCacheBuildIdentity: (environmentFingerprint: string, compilerIdentity: string, nativeSourceIdentity: string) => string;
+export { vendorCacheBuildIdentity, vendorCacheTargetFlavor };
+export interface NativeArtifactDependency {
+    path: string;
+    kind: "file" | "directory" | "symlink";
+    dev: number;
+    ino: number;
+    size: number;
+    mtimeMs: number;
+    ctimeMs: number;
+    /** Symlinks are identity-bearing paths whose target bytes also matter. */
+    targetPath?: string;
+    targetKind?: "file" | "directory";
+    targetDev?: number;
+    targetIno?: number;
+    targetSize?: number;
+    targetMtimeMs?: number;
+    targetCtimeMs?: number;
+    /** A directory's recursive namespace. This detects a new nested candidate
+     * that can begin shadowing an existing system/header dependency. */
+    treeDigest?: string;
+    treeExclusions?: string[];
+}
+/** Capture exact filesystem identities for inputs produced outside the C
+ * toolchain but consumed by its cache proofs. Callers carry this snapshot
+ * forward so later stages can prove the same inputs remained installed. */
+export declare function snapshotNativeArtifactDependencies(dependencyPaths: readonly string[]): Promise<NativeArtifactDependency[]>;
+export declare function nativeArtifactDependenciesStillMatch(dependencies: readonly NativeArtifactDependency[]): Promise<boolean>;
 /** Give one active link/archive operation private names for its cached
  * runtime objects. A hard link keeps the inode alive if another process's LRU
  * sweep unlinks the cache entry; filesystems that cannot hard-link across the
  * cache/tmp boundary fall back to a copy. If eviction wins before staging,
  * the caller catches the read failure and performs a fully fresh compile. */
 export declare function stageRuntimeObjects(objects: ReadonlyMap<string, string>, stageDir: string): Promise<Map<string, string>>;
-/** Compiles one C program together with the runtime sources.
- * With caching disabled, the runtime (a dozen small files) is recompiled on
- * every build in one historical clang invocation — no cached-archive
- * staleness bugs. --dynamic additionally compiles
- * scr_island.c under SCR_DYNAMIC and links the cached engine archive (built
- * lazily, see above); regex-using programs additionally compile scr_regex.c
- * and link libregexp (the cached objects, or the archive's own copy under
- * --dynamic). Without either, the command line is exactly the historical
- * one — regex-free static builds must stay byte-identical.
- *
- * With a caller-supplied dependency identity and an enabled cache root,
- * unchanged programs skip payload code generation/linking via the binary
- * cache after lightweight metadata probes, and misses link the program's own
- * TU against cached per-flavor runtime objects. */
 export declare function compileC(opts: CcOptions): Promise<void>;
+export type NativeCacheWarmProfile = "runtime" | "tls" | "dynamic";
+export interface WarmNativeCachesOptions {
+    /** Native object posture to seed. Defaults to the shipped release/-O2 lane. */
+    optimization?: "release" | "dev";
+    /** Seed ASan + RC-audit objects instead of the ordinary lane. */
+    sanitize?: boolean;
+    /** Feature families to seed. Defaults to every expensive native family. */
+    profiles?: readonly NativeCacheWarmProfile[];
+}
+export interface WarmNativeCachesResult {
+    cacheRoot: string;
+    profiles: {
+        profile: NativeCacheWarmProfile;
+        elapsedMs: number;
+    }[];
+}
+export declare function supportedNativeCacheWarmProfiles(driver: CcDriver): readonly NativeCacheWarmProfile[];
+/** Populate expensive native prerequisites against the current compiler,
+ * target, SDK, and environment. The resulting entries use the exact same
+ * identities and validators as ordinary builds; this merely pays their cost
+ * before a developer's first program asks for them. Synthetic link products
+ * are discarded and never enter the complete-executable cache. */
+export declare function warmNativeCaches(options?: WarmNativeCachesOptions): Promise<WarmNativeCachesResult>;