@scriptc/compiler 0.0.35 → 0.1.1

package/dist/index.d.ts

@@ -1,33 +1,45 @@
+import { type NativeLinkInfo } from "./backend/native-link-info.js";
 import { type ScrDiagnostic } from "./diagnostics/diagnostic.js";
 import type { CoverageInput } from "./coverage/report.js";
 export declare const VERSION = "0.0.1";
-export { compileC, runtimeSrcDir, warmNativeCaches, type CcOptions, type NativeCacheWarmProfile, type WarmNativeCachesOptions, type WarmNativeCachesResult, } from "./backend/cc.js";
-export { ANDROID_MIN_API, IPHONEOS_MIN_VERSION, isAndroidTarget, isIosTarget, isMobileTarget, mobileLibraryTarget, mobileTargetRefusal } from "./backend/cc.js";
-export { emitModule, type CEmitOptions } from "./backend/emission/emitter.js";
+export { EXTERNAL_OBJECT_ABI_STABILITY, RUNTIME_ABI_MARKER, RUNTIME_ABI_VERSION, } from "./backend/runtime-abi.js";
+export type { NativeLinkInfo, NativeLinkFeatures } from "./backend/native-link-info.js";
+export { InternalCompilerError } from "./errors.js";
+export { compileExternalC as compileC, compileExternalC, runtimeSrcDir, warmNativeCaches, type CcOptions, type NativeCacheWarmProfile, type WarmNativeCachesOptions, type WarmNativeCachesResult, } from "./backend/external-c.js";
+export { ANDROID_MIN_API, IPHONEOS_MIN_VERSION, isAndroidTarget, isIosTarget, isMobileTarget, mobileLibraryTarget, mobileTargetRefusal } from "./backend/external-c.js";
+export { emitCModule, emitCModule as emitModule, type CEmitOptions, } from "./backend/c/c-emitter.js";
 export type { ScrDiagnostic } from "./diagnostics/diagnostic.js";
-export { renderAll, renderDiagnostic } from "./diagnostics/render.js";
+export { renderDiagnostics, renderDiagnostics as renderAll, renderDiagnostic, } from "./diagnostics/render.js";
 export { renderCoverage, type CoverageInput } from "./coverage/report.js";
 export { generateSurfaceManifest, renderSurfaceManifest, MANIFEST_SCHEMA_VERSION, type SurfaceManifest, type SurfaceManifestEntry, } from "./coverage/surface-manifest.js";
 export { NODE24_FETCH_COMPAT_PROFILE, type FetchCompatEvidence, type FetchCompatFacet, type FetchCompatInventory, type FetchCompatInventoryEntry, type FetchCompatInventoryExclusion, type FetchCompatInventoryPlacement, type FetchCompatInventoryStatus, type FetchCompatOperation, type FetchCompatOption, type FetchCompatProfile, } from "./compat/fetch-profile.js";
 export { LIB_FN_SIGS, validateModule } from "./ir/validate.js";
+export { deserializeModule, IR_VERSION, serializeModule } from "./ir/serialize.js";
 export { resolveLibraryFences, type LibraryFenceDecl, type ResolvedLibraryFence } from "./library/fence-eval.js";
-export { loadLibraryProfile, profileTeaching, profileRemediation, LIB_PARAM_CLASSES, LIB_RETURN_CLASSES, type LibraryProfile, type LibraryExportEntry, type LibrarySidecarConfig, type LibParamClass, type LibReturnClass, } from "./library/profile.js";
-export { loadFfiProfile, FFI_CALLBACK_PARAM_CLASSES, FFI_PARAM_CLASSES, FFI_RETURN_CLASSES, type FfiCallbackParam, type FfiCallbackParamClass, type FfiContextParam, type FfiFunction, type FfiParamClass, type FfiProfile, type FfiReturnClass, type FfiValueParamClass, } from "./ffi/profile.js";
+export { loadLibraryProfile, profileTeaching, profileRemediation, LIB_PARAM_CLASSES, LIB_RETURN_CLASSES, type LibraryProfile, type LibraryExportEntry, type LibrarySidecarConfig, type LibParamClass, type LibReturnClass, } from "./library/library-profile.js";
+export { loadFfiProfile, FFI_CALLBACK_PARAM_CLASSES, FFI_PARAM_CLASSES, FFI_RETURN_CLASSES, type FfiCallbackParam, type FfiCallbackParamClass, type FfiContextParam, type FfiFunction, type FfiParamClass, type FfiProfile, type FfiReturnClass, type FfiValueParamClass, } from "./ffi/ffi-manifest.js";
 export { assembleTrapTeaching, TRAP_TEACHING_MARKER, TRAP_TEACHING_SEP, } from "./library/trap-teaching.js";
 export { abiExportSuffixes, buildSidecar, canonicalModuleGraph, canonicalPath, compilerReleaseVersion, libraryIdentityHashes, SIDECAR_FORMAT, type SidecarDoc, type SidecarBuildInput, type SidecarBuildResult, type TypeRef, type PayloadDescriptor, } from "./library/sidecar.js";
 export { validateSidecar } from "./library/sidecar-validate.js";
 export { BUILD_ID_SEED, SOURCE_HASH_SEED, hex16, lengthPrefixedStream, wyhash64 } from "./library/wyhash.js";
-export { ISLAND_SURFACE, type IslandFnEntry } from "./frontend/lowering/surfaces.js";
+export { ISLAND_SURFACE, STATIC_MATH_PROPS, type IslandFnEntry } from "./frontend/lowering/surfaces.js";
 export { ambientDtsPath, isExactExternalTypeSpecifier, overridesDtsPath } from "./frontend/program.js";
 export { resolveProvenanceSources } from "./frontend/provenance.js";
 export { wasiGuestPath, type HostPathFlavor } from "./wasi-paths.js";
 export { setProvenanceSources, type ProvenancePackageSource, type ProvenanceSources, } from "./frontend/provenance-registry.js";
-export * as ir from "./ir/nodes.js";
-export interface CompileOptions {
-    /** Output executable path. Default: <outDir>/<stem>. */
+export * as ir from "./ir/ir.js";
+export type CompileOutputKind = "ir" | "c" | "llvm" | "asm" | "obj" | "exe";
+export interface CompileBaseOptions {
+    /** Primary artifact path. The CLI supplies the output-kind default. */
     outPath: string;
-    /** Where intermediates (program.c, program.ir.json) land. */
+    /** Where generated intermediates and compatibility side artifacts land. */
     outDir: string;
+    /** True only when outPath was selected by scriptc's default-path policy.
+     * This authorizes cleanup of stale generated siblings; explicit paths must
+     * leave neighboring caller-owned files untouched. */
+    defaultOutputPath?: boolean;
+    /** Compatibility-only additive IR side artifact for executable builds.
+     * The CLI's deprecated --emit-ir flag supplies this option. */
     emitIr?: boolean;
     sanitize?: boolean;
     /** Embed the dynamic-island engine (--dynamic). Off = the static default:
@@ -35,9 +47,10 @@ export interface CompileOptions {
      * changes. */
     dynamic?: boolean;
     /** Code generator for the program TU. Unset (the release default): the
-     * LLVM backend emits LLVM IR text (.ll) that rides the SAME clang
-     * command line in the program-TU seat, and a program outside the LLVM
-     * tier falls back to the debugging C backend transparently — the IR is
+     * LLVM backend emits LLVM IR text (.ll). Supported macOS arm64 builds send
+     * it through the bundled helper and link a precompiled runtime pack; other
+     * targets retain their established compiler-driver path. A program outside
+     * the LLVM tier falls back to the debugging C backend transparently — the IR is
      * backend-agnostic, so only the emit retries; CompileResult records the
      * lane (`backend`, plus `llvmRefusal` when the fallback engaged). ONLY a
      * tier refusal (LlvmUnsupportedError) falls back — every real diagnostic
@@ -62,29 +75,93 @@ export interface CompileOptions {
      * the flag. */
     npmStatic?: readonly string[] | "auto";
     /** Outbound native FFI manifest. Its signature-only TypeScript bindings
-     * lower to direct C ABI calls, and its archive/system-library inputs are
-     * appended to the executable link. */
+     * lower to direct C ABI calls. Source outputs retain those declarations;
+     * archive/system-library inputs join only an executable link. */
     ffiProfilePath?: string;
+    /** Attach the machine-readable external link recipe to an object result.
+     * Valid only with outputKind "obj"; it never invokes a linker. */
+    nativeLinkInfo?: boolean;
 }
-export type CompileResult = 
-/** `cPath` is the generated program TU next to the binary: the .ll under
- * the LLVM backend (the default lane), the .c under the C backend (same
- * seat, same lifecycle — --keep-c in the CLI governs both). `backend` is
- * the code generator that ACTUALLY emitted the TU; `llvmRefusal` is
- * present iff the default lane fell back to C, carrying the tier
- * refusal's machine-readable kind tag ("stmt:...", "libCall:...", ...). */
-{
-    ok: true;
-    binaryPath: string;
-    cPath: string;
-    irPath?: string;
+/** Executable compile options. This remains the compatibility type for the
+ * historical compile() API, whose omitted output kind means executable. */
+export interface CompileOptions extends CompileBaseOptions {
+    outputKind?: "exe";
+    /** Internal validation lane retained for helper-object artifact tests.
+     * Supported ordinary LLVM executable builds select this path automatically. */
+    nativeProgramObject?: boolean;
+}
+/** Source-artifact compile options, discriminated by the required kind. */
+export interface CompileSourceOptions extends CompileBaseOptions {
+    outputKind: Exclude<CompileOutputKind, "exe">;
+}
+/** Internal/dynamic request shape for callers that select the kind at runtime.
+ * Statically executable/source callers should prefer the narrower interfaces. */
+export interface CompileRequestOptions extends CompileBaseOptions {
+    outputKind?: CompileOutputKind;
+    /** Internal validation lane for executable requests. */
+    nativeProgramObject?: boolean;
+}
+export type CompileArtifact = {
+    kind: "ir";
+    path: string;
+} | {
+    kind: "c";
+    path: string;
+} | {
+    kind: "llvm";
+    path: string;
+} | {
+    kind: "asm";
+    path: string;
+} | {
+    kind: "obj";
+    path: string;
+    nativeLinkInfo?: NativeLinkInfo;
+} | {
+    kind: "exe";
+    path: string;
+    translationUnitPath: string;
     backend: "c" | "llvm";
     llvmRefusal?: string;
-} | {
+};
+export type CompileFailure = {
     ok: false;
     diagnostics: ScrDiagnostic[];
     sourceTexts: Map<string, string>;
 };
+export type CompileSourceResult = {
+    ok: true;
+    artifact: Extract<CompileArtifact, {
+        kind: "ir" | "c" | "llvm" | "asm" | "obj";
+    }>;
+} | CompileFailure;
+/** Historical executable result shape retained for source compatibility. */
+export type CompileResult = {
+    ok: true;
+    binaryPath: string;
+    cPath: string;
+    irPath?: string;
+    backend: "c" | "llvm";
+    llvmRefusal?: string;
+} | CompileFailure;
+export type CompileExecutableResult = 
+/** `cPath` is the generated program TU next to the binary: the .ll under
+ * the LLVM backend (the default lane), the .c under the C backend (same
+ * seat, same lifecycle — --keep-c in the CLI governs both). `backend` is
+ * the code generator that ACTUALLY emitted the TU; `llvmRefusal` is
+ * present iff the default lane fell back to C, carrying the tier
+ * refusal's machine-readable kind tag ("stmt:...", "libCall:...", ...).
+ * These top-level fields remain as compatibility aliases for callers
+ * written before the discriminated `artifact` result was introduced. */
+(Extract<CompileResult, {
+    ok: true;
+}> & {
+    artifact: Extract<CompileArtifact, {
+        kind: "exe";
+    }>;
+}) | CompileFailure;
+/** Result union for callers that choose outputKind dynamically. */
+export type CompileRequestResult = CompileSourceResult | CompileExecutableResult;
 export interface AnalyzeResult {
     coverage: CoverageInput;
     sourceTexts: Map<string, string>;
@@ -96,6 +173,10 @@ export interface AnalyzeResult {
  * SCRIPTC_CC/SCRIPTC_TARGET combination reports at compileC exactly as
  * before, so analysis falls back to the host here rather than throwing. */
 export declare function buildTargetPlatform(env?: NodeJS.ProcessEnv): string;
+/** Target-platform classification without compiler or SDK discovery. Source
+ * artifacts need target semantics for lowering, but do not need a native
+ * toolchain merely to decide whether that target is Windows, WASI, etc. */
+export declare function sourceTargetPlatform(env?: NodeJS.ProcessEnv): string;
 export interface AnalyzeOptions {
     /** Analyze as a --dynamic build (island constructs lower instead of
      * producing requires-dynamic diagnostics). */
@@ -115,8 +196,9 @@ export interface AnalyzeOptions {
 /** Analysis without codegen: how much of the program compiles statically.
  * Unlike compile(), lowering diagnostics are data here, not failure. */
 export declare function analyze(entryPath: string, opts?: AnalyzeOptions): AnalyzeResult;
-/** The whole pipeline: load → preflight → lower → validate → emit C → clang. */
-export declare function compile(entryPath: string, opts: CompileOptions): Promise<CompileResult>;
+export declare function compile(entryPath: string, opts: CompileSourceOptions): Promise<CompileSourceResult>;
+export declare function compile(entryPath: string, opts: CompileOptions): Promise<CompileExecutableResult>;
+export declare function compile(entryPath: string, opts: CompileRequestOptions): Promise<CompileRequestResult>;
 export interface CompileLibraryOptions {
     profilePath: string;
     /** Where the archive and the kept program TU land. */