@celox-sim/celox 0.1.14 → 0.1.16

package/src/e2e.test.ts

@@ -400,7 +400,7 @@ describe("E2E: Simulator.create (backward compat)", () => {
 			{
 				__celox_module: true,
 				name: "Adder",
-				source: ADDER_SOURCE,
+				sources: [{ path: "", content: ADDER_SOURCE }],
 				ports: {
 					clk: { direction: "input", type: "clock", width: 1 },
 					rst: { direction: "input", type: "reset", width: 1 },
@@ -499,9 +499,13 @@ module InitTest (
     b: input bit<8>,
 ) {}
 `;
-		raw = new addon.NativeSimulatorHandle(source, "InitTest", {
-			fourState: true,
-		});
+		raw = new addon.NativeSimulatorHandle(
+			[{ content: source, path: "" }],
+			"InitTest",
+			{
+				fourState: true,
+			},
+		);
 		const layout = parseNapiLayout(raw.layoutJson);
 		const buf = raw.sharedMemory().buffer;
 
@@ -536,9 +540,13 @@ module InitTest (
 	});
 
 	test("AND: 0 & X = 0 (dominant zero)", () => {
-		raw = new addon.NativeSimulatorHandle(AND_OR_SOURCE, "AndOr", {
-			fourState: true,
-		});
+		raw = new addon.NativeSimulatorHandle(
+			[{ content: AND_OR_SOURCE, path: "" }],
+			"AndOr",
+			{
+				fourState: true,
+			},
+		);
 		const layout = parseNapiLayout(raw.layoutJson);
 		const buf = raw.sharedMemory().buffer;
 		const view = new DataView(buf);
@@ -571,9 +579,13 @@ module InitTest (
 	});
 
 	test("OR: 1 | X = 1 (dominant one)", () => {
-		raw = new addon.NativeSimulatorHandle(AND_OR_SOURCE, "AndOr", {
-			fourState: true,
-		});
+		raw = new addon.NativeSimulatorHandle(
+			[{ content: AND_OR_SOURCE, path: "" }],
+			"AndOr",
+			{
+				fourState: true,
+			},
+		);
 		const layout = parseNapiLayout(raw.layoutJson);
 		const buf = raw.sharedMemory().buffer;
 		const view = new DataView(buf);
@@ -599,9 +611,13 @@ module InitTest (
 	});
 
 	test("logic-to-bit assignment strips X mask", () => {
-		raw = new addon.NativeSimulatorHandle(LOGIC_BIT_MIX_SOURCE, "LogicBitMix", {
-			fourState: true,
-		});
+		raw = new addon.NativeSimulatorHandle(
+			[{ content: LOGIC_BIT_MIX_SOURCE, path: "" }],
+			"LogicBitMix",
+			{
+				fourState: true,
+			},
+		);
 		const layout = parseNapiLayout(raw.layoutJson);
 		const buf = raw.sharedMemory().buffer;
 		const view = new DataView(buf);
@@ -620,9 +636,13 @@ module InitTest (
 	});
 
 	test("bit-to-logic assignment has no X", () => {
-		raw = new addon.NativeSimulatorHandle(LOGIC_BIT_MIX_SOURCE, "LogicBitMix", {
-			fourState: true,
-		});
+		raw = new addon.NativeSimulatorHandle(
+			[{ content: LOGIC_BIT_MIX_SOURCE, path: "" }],
+			"LogicBitMix",
+			{
+				fourState: true,
+			},
+		);
 		const layout = parseNapiLayout(raw.layoutJson);
 		const buf = raw.sharedMemory().buffer;
 		const view = new DataView(buf);
@@ -642,9 +662,13 @@ module InitTest (
 	});
 
 	test("arithmetic with X produces all-X output", () => {
-		raw = new addon.NativeSimulatorHandle(ADDER_4STATE_SOURCE, "Adder4S", {
-			fourState: true,
-		});
+		raw = new addon.NativeSimulatorHandle(
+			[{ content: ADDER_4STATE_SOURCE, path: "" }],
+			"Adder4S",
+			{
+				fourState: true,
+			},
+		);
 		const layout = parseNapiLayout(raw.layoutJson);
 		const buf = raw.sharedMemory().buffer;
 		const view = new DataView(buf);
@@ -668,9 +692,13 @@ module InitTest (
 	});
 
 	test("defined inputs in 4-state mode behave like 2-state", () => {
-		raw = new addon.NativeSimulatorHandle(ADDER_4STATE_SOURCE, "Adder4S", {
-			fourState: true,
-		});
+		raw = new addon.NativeSimulatorHandle(
+			[{ content: ADDER_4STATE_SOURCE, path: "" }],
+			"Adder4S",
+			{
+				fourState: true,
+			},
+		);
 		const layout = parseNapiLayout(raw.layoutJson);
 		const buf = raw.sharedMemory().buffer;
 		const view = new DataView(buf);
@@ -694,7 +722,11 @@ module InitTest (
 	});
 
 	test("FF captures X from input, reset clears X", () => {
-		raw = new addon.NativeSimulatorHandle(FF_SOURCE, "FF", { fourState: true });
+		raw = new addon.NativeSimulatorHandle(
+			[{ content: FF_SOURCE, path: "" }],
+			"FF",
+			{ fourState: true },
+		);
 		const layout = parseNapiLayout(raw.layoutJson);
 		const buf = raw.sharedMemory().buffer;
 		const view = new DataView(buf);
@@ -744,9 +776,13 @@ module InitTest (
 	});
 
 	test("FourState write through DUT sets value and mask", () => {
-		raw = new addon.NativeSimulatorHandle(ADDER_4STATE_SOURCE, "Adder4S", {
-			fourState: true,
-		});
+		raw = new addon.NativeSimulatorHandle(
+			[{ content: ADDER_4STATE_SOURCE, path: "" }],
+			"Adder4S",
+			{
+				fourState: true,
+			},
+		);
 		const layout = parseNapiLayout(raw.layoutJson);
 		const buf = raw.sharedMemory().buffer;
 		const view = new DataView(buf);
@@ -764,9 +800,13 @@ module InitTest (
 	});
 
 	test("setting defined value clears X mask", () => {
-		raw = new addon.NativeSimulatorHandle(ADDER_4STATE_SOURCE, "Adder4S", {
-			fourState: true,
-		});
+		raw = new addon.NativeSimulatorHandle(
+			[{ content: ADDER_4STATE_SOURCE, path: "" }],
+			"Adder4S",
+			{
+				fourState: true,
+			},
+		);
 		const layout = parseNapiLayout(raw.layoutJson);
 		const buf = raw.sharedMemory().buffer;
 		const view = new DataView(buf);
@@ -866,9 +906,13 @@ describe("E2E: 4-state high-level DUT API", () => {
 
 	test("multiplexer with X selector produces X output", () => {
 		const addon = loadNativeAddon();
-		const raw = new addon.NativeSimulatorHandle(MULTIPLEXER_SOURCE, "Mux4", {
-			fourState: true,
-		});
+		const raw = new addon.NativeSimulatorHandle(
+			[{ content: MULTIPLEXER_SOURCE, path: "" }],
+			"Mux4",
+			{
+				fourState: true,
+			},
+		);
 		const layout = parseNapiLayout(raw.layoutJson);
 		const buf = raw.sharedMemory().buffer;
 		const view = new DataView(buf);
@@ -1676,7 +1720,7 @@ describe("E2E: parameter override — DUT correctness", () => {
 			{
 				__celox_module: true,
 				name: "ParamWidth",
-				source: PARAM_WIDTH_SOURCE,
+				sources: [{ path: "", content: PARAM_WIDTH_SOURCE }],
 				ports: {
 					// STALE: these say width=8, but we'll override to 16
 					a: { direction: "input", type: "logic", width: 8 },
@@ -2345,3 +2389,168 @@ describe("E2E: deadStorePolicy option", () => {
 		sim.dispose();
 	});
 });
+
+// ---------------------------------------------------------------------------
+// E2E: Proto package ordering (issue #22)
+// ---------------------------------------------------------------------------
+
+const PROTO_PKG_SOURCE = `
+pub proto package ItemProto {
+    type Item;
+}
+
+pub package ItemPlain::<WIDTH: u32 = 16> for ItemProto {
+    type Item = logic<WIDTH>;
+}
+`;
+
+const GENERIC_MODULE_SOURCE = `
+pub module GenericModule::<PKG: ItemProto> #(
+    param DEPTH: u32 = 4,
+) (
+    clk  : input  clock     ,
+    rst  : input  reset     ,
+    d_in : input  PKG::Item ,
+    d_out: output PKG::Item ,
+) {
+    var store: PKG::Item;
+    always_ff (clk, rst) {
+        if_reset { store = '0; }
+        else     { store = d_in; }
+    }
+    assign d_out = store;
+}
+
+pub module ConcreteModule #(
+    param DEPTH: u32 = 4,
+) (
+    clk  : input  clock     ,
+    rst  : input  reset     ,
+    d_in : input  logic<16> ,
+    d_out: output logic<16> ,
+) {
+    inst u_inner: GenericModule::<ItemPlain::<16>> #(DEPTH: DEPTH) (
+        clk, rst, d_in, d_out,
+    );
+}
+`;
+
+const UNRELATED_MODULE_SOURCE = `
+pub module UnrelatedModule (
+    clk  : input  clock    ,
+    rst  : input  reset    ,
+    d_in : input  logic<8> ,
+    d_out: output logic<8> ,
+) {
+    var data_r: logic<8>;
+    always_ff (clk, rst) {
+        if_reset { data_r = 0; }
+        else     { data_r = d_in; }
+    }
+    assign d_out = data_r;
+}
+`;
+
+describe("E2E: Proto package ordering (issue #22)", () => {
+	test("single-file source fails when project has proto packages in wrong order", () => {
+		// Reproduce the original bug: when proto_pkg definitions come after
+		// the code that references them (as a single concatenated source),
+		// the analyzer fails with "referred before it is defined".
+		expect(() =>
+			Simulator.fromSource(
+				GENERIC_MODULE_SOURCE + PROTO_PKG_SOURCE + UNRELATED_MODULE_SOURCE,
+				"ConcreteModule",
+			),
+		).toThrow();
+	});
+
+	test("multi-source: unrelated module compiles with proto packages in project", () => {
+		// New behavior: all source files are passed as separate entries.
+		// The Rust from_sources() handles dependency ordering correctly.
+		const sim = Simulator.fromSource<{
+			d_in: bigint;
+			readonly d_out: bigint;
+		}>(
+			PROTO_PKG_SOURCE + GENERIC_MODULE_SOURCE + UNRELATED_MODULE_SOURCE,
+			"UnrelatedModule",
+		);
+
+		// Reset sequence
+		sim.dut.rst = 0n;
+		sim.tick();
+		sim.tick();
+		sim.dut.rst = 1n;
+
+		sim.dut.d_in = 42n;
+		sim.tick();
+		sim.tick();
+
+		expect(sim.dut.d_out).toBe(42n);
+		sim.dispose();
+	});
+
+	test("multi-source: ConcreteModule using proto package works", () => {
+		// The concrete module that actually uses the proto package should
+		// also compile and simulate correctly.
+		const sim = Simulator.fromSource<{
+			d_in: bigint;
+			readonly d_out: bigint;
+		}>(
+			PROTO_PKG_SOURCE + GENERIC_MODULE_SOURCE + UNRELATED_MODULE_SOURCE,
+			"ConcreteModule",
+		);
+
+		// Reset sequence
+		sim.dut.rst = 0n;
+		sim.tick();
+		sim.tick();
+		sim.dut.rst = 1n;
+
+		sim.dut.d_in = 0xabcdn;
+		sim.tick();
+		sim.tick();
+
+		expect(sim.dut.d_out).toBe(0xabcdn);
+		sim.dispose();
+	});
+
+	test("Simulator.create() with multi-source ModuleDefinition", () => {
+		// Simulates what celox-ts-gen now generates: a ModuleDefinition with
+		// sources[] containing all project files.
+		const addon = loadNativeAddon();
+		const nativeCreate = createSimulatorBridge(addon);
+
+		const sim = Simulator.create(
+			{
+				__celox_module: true,
+				name: "UnrelatedModule",
+				sources: [
+					{ path: "proto_pkg.veryl", content: PROTO_PKG_SOURCE },
+					{ path: "generic_module.veryl", content: GENERIC_MODULE_SOURCE },
+					{ path: "unrelated_module.veryl", content: UNRELATED_MODULE_SOURCE },
+				],
+				ports: {
+					clk: { direction: "input", type: "clock", width: 1 },
+					rst: { direction: "input", type: "reset", width: 1 },
+					d_in: { direction: "input", type: "logic", width: 8 },
+					d_out: { direction: "output", type: "logic", width: 8 },
+				},
+				events: ["clk"],
+			},
+			{ __nativeCreate: nativeCreate },
+		);
+
+		// Reset sequence
+		sim.dut.rst = 0n;
+		sim.tick();
+		sim.tick();
+		sim.dut.rst = 1n;
+
+		sim.dut.d_in = 99n;
+		sim.tick();
+		sim.tick();
+
+		expect(sim.dut.d_out).toBe(99n);
+		sim.dispose();
+	});
+});

package/src/index.ts

@@ -51,6 +51,7 @@ export type {
 	PortInfo,
 	SignalLayout,
 	SimulatorOptions,
+	SourceFile,
 	TrueLoopSpec,
 } from "./types.js";
 // 4-state helpers

package/src/napi-helpers.ts

@@ -19,6 +19,7 @@ import type {
 	PortInfo,
 	SignalLayout,
 	SimulatorOptions,
+	SourceFile,
 	TrueLoopSpec,
 } from "./types.js";
 
@@ -30,6 +31,7 @@ export interface RawNapiSimulatorHandle {
 	readonly layoutJson: string;
 	readonly eventsJson: string;
 	readonly hierarchyJson: string;
+	readonly warningsJson: string;
 	readonly stableSize: number;
 	readonly totalSize: number;
 	tick(eventId: number): void;
@@ -44,6 +46,7 @@ export interface RawNapiSimulationHandle {
 	readonly layoutJson: string;
 	readonly eventsJson: string;
 	readonly hierarchyJson: string;
+	readonly warningsJson: string;
 	readonly stableSize: number;
 	readonly totalSize: number;
 	readonly defaultMaxSteps: number | null;
@@ -98,10 +101,15 @@ export interface NapiOptions {
 	deadStorePolicy?: string;
 }
 
+export interface NapiSourceFile {
+	content: string;
+	path: string;
+}
+
 export interface RawNapiAddon {
 	NativeSimulatorHandle: {
 		new (
-			code: string,
+			sources: NapiSourceFile[],
 			top: string,
 			options?: NapiOptions,
 		): RawNapiSimulatorHandle;
@@ -113,7 +121,7 @@ export interface RawNapiAddon {
 	};
 	NativeSimulationHandle: {
 		new (
-			code: string,
+			sources: NapiSourceFile[],
 			top: string,
 			options?: NapiOptions,
 		): RawNapiSimulationHandle;
@@ -265,7 +273,8 @@ export function buildNapiOpts(
 			preserveTopPorts: "preserve_top_ports",
 			preserveAllPorts: "preserve_all_ports",
 		};
-		napiOpts.deadStorePolicy = map[options.deadStorePolicy] ?? options.deadStorePolicy;
+		napiOpts.deadStorePolicy =
+			map[options.deadStorePolicy] ?? options.deadStorePolicy;
 		hasOpt = true;
 	}
 
@@ -611,12 +620,20 @@ function parseLegacyLayout(json: string): Record<string, SignalLayout> {
  */
 export function createSimulatorBridge(addon: RawNapiAddon): NativeCreateFn {
 	return (
-		source: string,
+		sources: ReadonlyArray<SourceFile>,
 		moduleName: string,
 		options: SimulatorOptions,
 	): CreateResult<NativeSimulatorHandle> => {
 		const napiOpts = buildNapiOpts(options);
-		const raw = new addon.NativeSimulatorHandle(source, moduleName, napiOpts);
+		const napiSources = sources.map((s) => ({
+			content: s.content,
+			path: s.path,
+		}));
+		const raw = new addon.NativeSimulatorHandle(
+			napiSources,
+			moduleName,
+			napiOpts,
+		);
 
 		const layout = parseLegacyLayout(raw.layoutJson);
 		const events: Record<string, number> = JSON.parse(raw.eventsJson);
@@ -625,7 +642,9 @@ export function createSimulatorBridge(addon: RawNapiAddon): NativeCreateFn {
 		const buf = raw.sharedMemory().buffer;
 		const handle = wrapDirectSimulatorHandle(raw);
 
-		return { buffer: buf, layout, events, handle, hierarchy };
+		const warnings: string[] = JSON.parse(raw.warningsJson ?? "[]");
+
+		return { buffer: buf, layout, events, handle, hierarchy, warnings };
 	};
 }
 
@@ -637,12 +656,20 @@ export function createSimulationBridge(
 	addon: RawNapiAddon,
 ): NativeCreateSimulationFn {
 	return (
-		source: string,
+		sources: ReadonlyArray<SourceFile>,
 		moduleName: string,
 		options: SimulatorOptions,
 	): CreateResult<NativeSimulationHandle> => {
 		const napiOpts = buildNapiOpts(options);
-		const raw = new addon.NativeSimulationHandle(source, moduleName, napiOpts);
+		const napiSources = sources.map((s) => ({
+			content: s.content,
+			path: s.path,
+		}));
+		const raw = new addon.NativeSimulationHandle(
+			napiSources,
+			moduleName,
+			napiOpts,
+		);
 
 		const layout = parseLegacyLayout(raw.layoutJson);
 		const events: Record<string, number> = JSON.parse(raw.eventsJson);
@@ -650,7 +677,8 @@ export function createSimulationBridge(
 
 		const buf = raw.sharedMemory().buffer;
 		const handle = wrapDirectSimulationHandle(raw);
+		const warnings: string[] = JSON.parse(raw.warningsJson ?? "[]");
 
-		return { buffer: buf, layout, events, handle, hierarchy };
+		return { buffer: buf, layout, events, handle, hierarchy, warnings };
 	};
 }

package/src/simulation.test.ts

@@ -20,7 +20,7 @@ interface TopPorts {
 const TopModule: ModuleDefinition<TopPorts> = {
 	__celox_module: true,
 	name: "Top",
-	source: "module Top ...",
+	sources: [{ path: "", content: "module Top ..." }],
 	ports: {
 		clk: { direction: "input", type: "clock", width: 1 },
 		rst: { direction: "input", type: "reset", width: 1 },

package/src/simulation.ts

@@ -22,6 +22,7 @@ import type {
 	NativeSimulationHandle,
 	SignalLayout,
 	SimulatorOptions,
+	SourceFile,
 } from "./types.js";
 import { SimulationTimeoutError } from "./types.js";
 
@@ -31,7 +32,7 @@ import { SimulationTimeoutError } from "./types.js";
  * @internal
  */
 export type NativeCreateSimulationFn = (
-	source: string,
+	sources: ReadonlyArray<SourceFile>,
 	moduleName: string,
 	options: SimulatorOptions,
 ) => CreateResult<NativeSimulationHandle>;
@@ -65,6 +66,7 @@ export class Simulation<P = Record<string, unknown>> {
 		{ period: number; eventId: number }
 	>();
 	private readonly _defaultMaxSteps: number | undefined;
+	private readonly _warnings: readonly string[];
 	private _disposed = false;
 
 	private constructor(
@@ -77,6 +79,7 @@ export class Simulation<P = Record<string, unknown>> {
 			string,
 			SignalLayout & { typeKind?: string; associatedClock?: string }
 		>,
+		warnings: string[],
 		defaultMaxSteps?: number,
 	) {
 		this._handle = handle;
@@ -85,6 +88,7 @@ export class Simulation<P = Record<string, unknown>> {
 		this._state = state;
 		this._buffer = buffer;
 		this._layout = layout;
+		this._warnings = warnings;
 		this._defaultMaxSteps = defaultMaxSteps;
 	}
 
@@ -107,11 +111,7 @@ export class Simulation<P = Record<string, unknown>> {
 
 		// When the module was produced by the Vite plugin, delegate to fromProject()
 		if (module.projectPath && !merged?.__nativeCreate) {
-			return Simulation.fromProject<P>(
-				module.projectPath,
-				module.name,
-				merged,
-			);
+			return Simulation.fromProject<P>(module.projectPath, module.name, merged);
 		}
 
 		const createFn = merged?.__nativeCreate ?? _nativeCreate;
@@ -133,7 +133,7 @@ export class Simulation<P = Record<string, unknown>> {
 			parameters,
 			deadStorePolicy,
 		} = merged ?? {};
-		const result = createFn(module.source, module.name, {
+		const result = createFn(module.sources, module.name, {
 			fourState,
 			vcd,
 			optimize,
@@ -167,6 +167,7 @@ export class Simulation<P = Record<string, unknown>> {
 			state,
 			result.buffer,
 			result.layout,
+			result.warnings ?? [],
 		);
 	}
 
@@ -189,12 +190,19 @@ export class Simulation<P = Record<string, unknown>> {
 	): Simulation<P> {
 		const addon = loadNativeAddon(options?.nativeAddonPath);
 		const napiOpts = buildNapiOpts(options);
-		const raw = new addon.NativeSimulationHandle(source, top, napiOpts);
+		const raw = new addon.NativeSimulationHandle(
+			[{ content: source, path: "" }],
+			top,
+			napiOpts,
+		);
 
 		const layout = parseNapiLayout(raw.layoutJson);
 		const events: Record<string, number> = JSON.parse(raw.eventsJson);
 		const rawHierarchy = parseHierarchyLayout(raw.hierarchyJson, events);
-		const hierarchy = filterHierarchyForDse(rawHierarchy, options?.deadStorePolicy);
+		const hierarchy = filterHierarchyForDse(
+			rawHierarchy,
+			options?.deadStorePolicy,
+		);
 
 		const ports = buildPortsFromLayout(hierarchy.signals, events);
 
@@ -211,7 +219,17 @@ export class Simulation<P = Record<string, unknown>> {
 			hierarchy,
 		);
 
-		return new Simulation<P>(handle, dut, events, state, buf, layout.signals);
+		const warnings: string[] = JSON.parse(raw.warningsJson ?? "[]");
+
+		return new Simulation<P>(
+			handle,
+			dut,
+			events,
+			state,
+			buf,
+			layout.signals,
+			warnings,
+		);
 	}
 
 	/**
@@ -242,7 +260,10 @@ export class Simulation<P = Record<string, unknown>> {
 		const layout = parseNapiLayout(raw.layoutJson);
 		const events: Record<string, number> = JSON.parse(raw.eventsJson);
 		const rawHierarchy = parseHierarchyLayout(raw.hierarchyJson, events);
-		const hierarchy = filterHierarchyForDse(rawHierarchy, options?.deadStorePolicy);
+		const hierarchy = filterHierarchyForDse(
+			rawHierarchy,
+			options?.deadStorePolicy,
+		);
 
 		const ports = buildPortsFromLayout(hierarchy.signals, events);
 
@@ -260,6 +281,8 @@ export class Simulation<P = Record<string, unknown>> {
 			hierarchy,
 		);
 
+		const warnings: string[] = JSON.parse(raw.warningsJson ?? "[]");
+
 		return new Simulation<P>(
 			handle,
 			dut,
@@ -267,6 +290,7 @@ export class Simulation<P = Record<string, unknown>> {
 			state,
 			buf,
 			layout.signals,
+			warnings,
 			defaultMaxSteps,
 		);
 	}
@@ -276,6 +300,11 @@ export class Simulation<P = Record<string, unknown>> {
 		return this._dut;
 	}
 
+	/** Analyzer warnings emitted during compilation. */
+	get warnings(): readonly string[] {
+		return this._warnings;
+	}
+
 	/**
 	 * Register a periodic clock.
 	 *

package/src/simulator.test.ts

@@ -20,7 +20,7 @@ interface AdderPorts {
 const AdderModule: ModuleDefinition<AdderPorts> = {
 	__celox_module: true,
 	name: "Adder",
-	source: "module Adder ...",
+	sources: [{ path: "", content: "module Adder ..." }],
 	ports: {
 		clk: { direction: "input", type: "clock", width: 1 },
 		rst: { direction: "input", type: "reset", width: 1 },