quantumcoin 7.0.3 → 7.0.4

package/test/unit/generate-sdk-artifacts-json.test.js

@@ -1,110 +1,113 @@
-/**
- * @testCategory unit
- * @blockchainRequired false
- * @transactional false
- * @description generate-sdk.js artifacts JSON input (multi-contract)
- */
-
-const { describe, it } = require("node:test");
-const assert = require("node:assert/strict");
-const fs = require("node:fs");
-const os = require("node:os");
-const path = require("node:path");
-const { spawnSync } = require("node:child_process");
-
-describe("generate-sdk.js --artifacts-json", () => {
-  it("generates typed files for multiple ABI+BIN pairs (no package scaffold)", () => {
-    const repoRoot = path.resolve(__dirname, "..", "..");
-    const cli = path.join(repoRoot, "generate-sdk.js");
-
-    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "qcgen-artjson-"));
-    const outDir = path.join(tmp, "out");
-
-    const alphaAbi = [
-      { type: "function", name: "get", stateMutability: "view", inputs: [], outputs: [{ name: "", type: "uint256" }] },
-    ];
-    const betaAbi = [
-      { type: "function", name: "set", stateMutability: "nonpayable", inputs: [{ name: "value", type: "uint256" }], outputs: [] },
-    ];
-    const gammaAbi = [
-      { type: "function", name: "ping", stateMutability: "pure", inputs: [], outputs: [{ name: "", type: "bool" }] },
-    ];
-
-    fs.writeFileSync(path.join(tmp, "Alpha.abi.json"), JSON.stringify(alphaAbi, null, 2), "utf8");
-    fs.writeFileSync(path.join(tmp, "Alpha.bin"), "0x6000", "utf8");
-    fs.writeFileSync(path.join(tmp, "Beta.abi.json"), JSON.stringify(betaAbi, null, 2), "utf8");
-    fs.writeFileSync(path.join(tmp, "Beta.bin"), "0x6000", "utf8");
-
-    const artifactsJsonPath = path.join(tmp, "artifacts.json");
-    fs.writeFileSync(
-      artifactsJsonPath,
-      JSON.stringify(
-        [
-          { abi: "./Alpha.abi.json", bin: "./Alpha.bin" },
-          { abi: "./Beta.abi.json", bin: "./Beta.bin" },
-          // Inline string form: abi is a JSON string; bin is inline bytecode (string).
-          { name: "Gamma", abi: JSON.stringify(gammaAbi), bin: "6000" },
-        ],
-        null,
-        2,
-      ),
-      "utf8",
-    );
-
-    const res = spawnSync(
-      process.execPath,
-      [cli, "--artifacts-json", artifactsJsonPath, "--out", outDir, "--non-interactive"],
-      { cwd: repoRoot, encoding: "utf8", stdio: "pipe", shell: false, windowsHide: true },
-    );
-
-    assert.equal(res.status, 0, `generator failed:\n${res.stdout}\n${res.stderr}`);
-
-    assert.ok(fs.existsSync(path.join(outDir, "types.ts")));
-    assert.ok(fs.existsSync(path.join(outDir, "index.ts")));
-    assert.ok(fs.existsSync(path.join(outDir, "Alpha.ts")));
-    assert.ok(fs.existsSync(path.join(outDir, "Alpha__factory.ts")));
-    assert.ok(fs.existsSync(path.join(outDir, "Beta.ts")));
-    assert.ok(fs.existsSync(path.join(outDir, "Beta__factory.ts")));
-    assert.ok(fs.existsSync(path.join(outDir, "Gamma.ts")));
-    assert.ok(fs.existsSync(path.join(outDir, "Gamma__factory.ts")));
-  });
-
-  it("supports --lang js (generates JS source + .d.ts types)", () => {
-    const repoRoot = path.resolve(__dirname, "..", "..");
-    const cli = path.join(repoRoot, "generate-sdk.js");
-
-    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "qcgen-artjson-js-"));
-    const outDir = path.join(tmp, "out");
-
-    const alphaAbi = [
-      { type: "function", name: "get", stateMutability: "view", inputs: [], outputs: [{ name: "", type: "uint256" }] },
-    ];
-    fs.writeFileSync(path.join(tmp, "Alpha.abi.json"), JSON.stringify(alphaAbi, null, 2), "utf8");
-    fs.writeFileSync(path.join(tmp, "Alpha.bin"), "0x6000", "utf8");
-
-    const artifactsJsonPath = path.join(tmp, "artifacts.json");
-    fs.writeFileSync(artifactsJsonPath, JSON.stringify([{ abi: "./Alpha.abi.json", bin: "./Alpha.bin" }], null, 2), "utf8");
-
-    const res = spawnSync(
-      process.execPath,
-      [cli, "--lang", "js", "--artifacts-json", artifactsJsonPath, "--out", outDir, "--non-interactive"],
-      { cwd: repoRoot, encoding: "utf8", stdio: "pipe", shell: false, windowsHide: true },
-    );
-
-    assert.equal(res.status, 0, `generator failed:\n${res.stdout}\n${res.stderr}`);
-
-    assert.ok(fs.existsSync(path.join(outDir, "types.js")));
-    assert.ok(fs.existsSync(path.join(outDir, "types.d.ts")));
-    assert.ok(fs.existsSync(path.join(outDir, "index.js")));
-    assert.ok(fs.existsSync(path.join(outDir, "index.d.ts")));
-    assert.ok(fs.existsSync(path.join(outDir, "Alpha.js")));
-    assert.ok(fs.existsSync(path.join(outDir, "Alpha.d.ts")));
-    assert.ok(fs.existsSync(path.join(outDir, "Alpha__factory.js")));
-    assert.ok(fs.existsSync(path.join(outDir, "Alpha__factory.d.ts")));
-
-    // Ensure generated types re-export core Solidity types (no local re-definition).
-    const typesDts = fs.readFileSync(path.join(outDir, "types.d.ts"), "utf8");
-    assert.ok(typesDts.includes('from "quantumcoin/types"'), "expected generated types.d.ts to reference quantumcoin/types");
-  });
-});
-
+/**
+ * @testCategory unit
+ * @blockchainRequired false
+ * @transactional false
+ * @description generate-sdk.js artifacts JSON input (multi-contract)
+ */
+
+const { describe, it } = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const { logSuite, logTest } = require("../verbose-logger");
+
+describe("generate-sdk.js --artifacts-json", () => {
+  logSuite("generate-sdk.js --artifacts-json");
+  it("generates typed files for multiple ABI+BIN pairs (no package scaffold)", () => {
+    logTest("generates typed files for multiple ABI+BIN pairs (no package scaffold)", {});
+    const repoRoot = path.resolve(__dirname, "..", "..");
+    const cli = path.join(repoRoot, "generate-sdk.js");
+
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "qcgen-artjson-"));
+    const outDir = path.join(tmp, "out");
+
+    const alphaAbi = [
+      { type: "function", name: "get", stateMutability: "view", inputs: [], outputs: [{ name: "", type: "uint256" }] },
+    ];
+    const betaAbi = [
+      { type: "function", name: "set", stateMutability: "nonpayable", inputs: [{ name: "value", type: "uint256" }], outputs: [] },
+    ];
+    const gammaAbi = [
+      { type: "function", name: "ping", stateMutability: "pure", inputs: [], outputs: [{ name: "", type: "bool" }] },
+    ];
+
+    fs.writeFileSync(path.join(tmp, "Alpha.abi.json"), JSON.stringify(alphaAbi, null, 2), "utf8");
+    fs.writeFileSync(path.join(tmp, "Alpha.bin"), "0x6000", "utf8");
+    fs.writeFileSync(path.join(tmp, "Beta.abi.json"), JSON.stringify(betaAbi, null, 2), "utf8");
+    fs.writeFileSync(path.join(tmp, "Beta.bin"), "0x6000", "utf8");
+
+    const artifactsJsonPath = path.join(tmp, "artifacts.json");
+    fs.writeFileSync(
+      artifactsJsonPath,
+      JSON.stringify(
+        [
+          { abi: "./Alpha.abi.json", bin: "./Alpha.bin" },
+          { abi: "./Beta.abi.json", bin: "./Beta.bin" },
+          // Inline string form: abi is a JSON string; bin is inline bytecode (string).
+          { name: "Gamma", abi: JSON.stringify(gammaAbi), bin: "6000" },
+        ],
+        null,
+        2,
+      ),
+      "utf8",
+    );
+
+    const res = spawnSync(
+      process.execPath,
+      [cli, "--artifacts-json", artifactsJsonPath, "--out", outDir, "--non-interactive"],
+      { cwd: repoRoot, encoding: "utf8", stdio: "pipe", shell: false, windowsHide: true },
+    );
+
+    assert.equal(res.status, 0, `generator failed:\n${res.stdout}\n${res.stderr}`);
+
+    assert.ok(fs.existsSync(path.join(outDir, "types.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "index.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Alpha.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Alpha__factory.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Beta.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Beta__factory.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Gamma.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Gamma__factory.ts")));
+  });
+
+  it("supports --lang js (generates JS source + .d.ts types)", () => {
+    const repoRoot = path.resolve(__dirname, "..", "..");
+    const cli = path.join(repoRoot, "generate-sdk.js");
+
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "qcgen-artjson-js-"));
+    const outDir = path.join(tmp, "out");
+
+    const alphaAbi = [
+      { type: "function", name: "get", stateMutability: "view", inputs: [], outputs: [{ name: "", type: "uint256" }] },
+    ];
+    fs.writeFileSync(path.join(tmp, "Alpha.abi.json"), JSON.stringify(alphaAbi, null, 2), "utf8");
+    fs.writeFileSync(path.join(tmp, "Alpha.bin"), "0x6000", "utf8");
+
+    const artifactsJsonPath = path.join(tmp, "artifacts.json");
+    fs.writeFileSync(artifactsJsonPath, JSON.stringify([{ abi: "./Alpha.abi.json", bin: "./Alpha.bin" }], null, 2), "utf8");
+
+    const res = spawnSync(
+      process.execPath,
+      [cli, "--lang", "js", "--artifacts-json", artifactsJsonPath, "--out", outDir, "--non-interactive"],
+      { cwd: repoRoot, encoding: "utf8", stdio: "pipe", shell: false, windowsHide: true },
+    );
+
+    assert.equal(res.status, 0, `generator failed:\n${res.stdout}\n${res.stderr}`);
+
+    assert.ok(fs.existsSync(path.join(outDir, "types.js")));
+    assert.ok(fs.existsSync(path.join(outDir, "types.d.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "index.js")));
+    assert.ok(fs.existsSync(path.join(outDir, "index.d.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Alpha.js")));
+    assert.ok(fs.existsSync(path.join(outDir, "Alpha.d.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Alpha__factory.js")));
+    assert.ok(fs.existsSync(path.join(outDir, "Alpha__factory.d.ts")));
+
+    // Ensure generated types re-export core Solidity types (no local re-definition).
+    const typesDts = fs.readFileSync(path.join(outDir, "types.d.ts"), "utf8");
+    assert.ok(typesDts.includes('from "quantumcoin/types"'), "expected generated types.d.ts to reference quantumcoin/types");
+  });
+});
+

package/test/unit/generate-sdk-artifacts-json.test.ts

@@ -0,0 +1,110 @@
+/**
+ * @testCategory unit
+ * @blockchainRequired false
+ * @transactional false
+ * @description generate-sdk.js artifacts JSON input (multi-contract)
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { logSuite, logTest } from "../verbose-logger";
+
+describe("generate-sdk.js --artifacts-json", () => {
+  logSuite("generate-sdk.js --artifacts-json");
+  it("generates typed files for multiple ABI+BIN pairs (no package scaffold)", () => {
+    logTest("generates typed files for multiple ABI+BIN pairs (no package scaffold)", {});
+    const repoRoot = path.resolve(__dirname, "..", "..");
+    const cli = path.join(repoRoot, "generate-sdk.js");
+
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "qcgen-artjson-"));
+    const outDir = path.join(tmp, "out");
+
+    const alphaAbi = [
+      { type: "function", name: "get", stateMutability: "view", inputs: [], outputs: [{ name: "", type: "uint256" }] },
+    ];
+    const betaAbi = [
+      { type: "function", name: "set", stateMutability: "nonpayable", inputs: [{ name: "value", type: "uint256" }], outputs: [] },
+    ];
+    const gammaAbi = [
+      { type: "function", name: "ping", stateMutability: "pure", inputs: [], outputs: [{ name: "", type: "bool" }] },
+    ];
+
+    fs.writeFileSync(path.join(tmp, "Alpha.abi.json"), JSON.stringify(alphaAbi, null, 2), "utf8");
+    fs.writeFileSync(path.join(tmp, "Alpha.bin"), "0x6000", "utf8");
+    fs.writeFileSync(path.join(tmp, "Beta.abi.json"), JSON.stringify(betaAbi, null, 2), "utf8");
+    fs.writeFileSync(path.join(tmp, "Beta.bin"), "0x6000", "utf8");
+
+    const artifactsJsonPath = path.join(tmp, "artifacts.json");
+    fs.writeFileSync(
+      artifactsJsonPath,
+      JSON.stringify(
+        [
+          { abi: "./Alpha.abi.json", bin: "./Alpha.bin" },
+          { abi: "./Beta.abi.json", bin: "./Beta.bin" },
+          { name: "Gamma", abi: JSON.stringify(gammaAbi), bin: "6000" },
+        ],
+        null,
+        2,
+      ),
+      "utf8",
+    );
+
+    const res = spawnSync(
+      process.execPath,
+      [cli, "--artifacts-json", artifactsJsonPath, "--out", outDir, "--non-interactive"],
+      { cwd: repoRoot, encoding: "utf8", stdio: "pipe", shell: false, windowsHide: true },
+    );
+
+    assert.equal(res.status, 0, `generator failed:\n${res.stdout}\n${res.stderr}`);
+
+    assert.ok(fs.existsSync(path.join(outDir, "types.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "index.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Alpha.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Alpha__factory.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Beta.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Beta__factory.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Gamma.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Gamma__factory.ts")));
+  });
+
+  it("supports --lang js (generates JS source + .d.ts types)", () => {
+    const repoRoot = path.resolve(__dirname, "..", "..");
+    const cli = path.join(repoRoot, "generate-sdk.js");
+
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "qcgen-artjson-js-"));
+    const outDir = path.join(tmp, "out");
+
+    const alphaAbi = [
+      { type: "function", name: "get", stateMutability: "view", inputs: [], outputs: [{ name: "", type: "uint256" }] },
+    ];
+    fs.writeFileSync(path.join(tmp, "Alpha.abi.json"), JSON.stringify(alphaAbi, null, 2), "utf8");
+    fs.writeFileSync(path.join(tmp, "Alpha.bin"), "0x6000", "utf8");
+
+    const artifactsJsonPath = path.join(tmp, "artifacts.json");
+    fs.writeFileSync(artifactsJsonPath, JSON.stringify([{ abi: "./Alpha.abi.json", bin: "./Alpha.bin" }], null, 2), "utf8");
+
+    const res = spawnSync(
+      process.execPath,
+      [cli, "--lang", "js", "--artifacts-json", artifactsJsonPath, "--out", outDir, "--non-interactive"],
+      { cwd: repoRoot, encoding: "utf8", stdio: "pipe", shell: false, windowsHide: true },
+    );
+
+    assert.equal(res.status, 0, `generator failed:\n${res.stdout}\n${res.stderr}`);
+
+    assert.ok(fs.existsSync(path.join(outDir, "types.js")));
+    assert.ok(fs.existsSync(path.join(outDir, "types.d.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "index.js")));
+    assert.ok(fs.existsSync(path.join(outDir, "index.d.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Alpha.js")));
+    assert.ok(fs.existsSync(path.join(outDir, "Alpha.d.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Alpha__factory.js")));
+    assert.ok(fs.existsSync(path.join(outDir, "Alpha__factory.d.ts")));
+
+    const typesDts = fs.readFileSync(path.join(outDir, "types.d.ts"), "utf8");
+    assert.ok(typesDts.includes('from "quantumcoin/types"'), "expected generated types.d.ts to reference quantumcoin/types");
+  });
+});

package/test/unit/generator.test.js

@@ -1,99 +1,102 @@
-/**
- * @testCategory unit
- * @blockchainRequired false
- * @transactional false
- * @description Typed contract generator (file output shape)
- */
-
-const { describe, it } = require("node:test");
-const assert = require("node:assert/strict");
-const fs = require("node:fs");
-const os = require("node:os");
-const path = require("node:path");
-
-const { generate, generateFromArtifacts } = require("../../src/generator");
-
-describe("typed contract generator", () => {
-  it("generates contract + factory + types + index files", () => {
-    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "qcgen-"));
-    const abiPath = path.join(tmp, "Test.abi.json");
-    const binPath = path.join(tmp, "Test.bin");
-    const outDir = path.join(tmp, "out");
-
-    const abi = [
-      {
-        type: "function",
-        name: "balanceOf",
-        stateMutability: "view",
-        inputs: [{ name: "account", type: "address" }],
-        outputs: [{ name: "", type: "uint256" }],
-      },
-      {
-        type: "function",
-        name: "transfer",
-        stateMutability: "nonpayable",
-        inputs: [
-          { name: "to", type: "address" },
-          { name: "amount", type: "uint256" },
-        ],
-        outputs: [{ name: "", type: "bool" }],
-      },
-    ];
-
-    fs.writeFileSync(abiPath, JSON.stringify(abi, null, 2), "utf8");
-    fs.writeFileSync(binPath, "0x6000", "utf8");
-
-    const res = generate({ abiPath, binPath, outDir, contractName: "TestToken" });
-    assert.ok(fs.existsSync(res.contractFile));
-    assert.ok(fs.existsSync(res.factoryFile));
-    assert.ok(fs.existsSync(res.typesFile));
-    assert.ok(fs.existsSync(res.indexFile));
-
-    const contractSrc = fs.readFileSync(res.contractFile, "utf8");
-    assert.ok(contractSrc.includes("export class TestToken"));
-    assert.ok(contractSrc.includes("async balanceOf"));
-    assert.ok(contractSrc.includes("async transfer"));
-    assert.ok(contractSrc.includes("populateTransaction"));
-
-    const factorySrc = fs.readFileSync(res.factoryFile, "utf8");
-    assert.ok(factorySrc.includes("export class TestToken__factory"));
-  });
-
-  it("includes injected docs in generated TypeScript", () => {
-    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "qcgen-docs-"));
-    const outDir = path.join(tmp, "out");
-
-    const abi = [
-      {
-        type: "function",
-        name: "set",
-        stateMutability: "nonpayable",
-        inputs: [{ name: "value", type: "uint256" }],
-        outputs: [],
-      },
-    ];
-
-    const res = generateFromArtifacts({
-      outDir,
-      artifacts: [
-        {
-          contractName: "DocToken",
-          abi,
-          bytecode: "0x6000",
-          docs: {
-            contract: "Example contract doc from Solidity.",
-            functions: {
-              set: "Example function doc from Solidity.",
-            },
-          },
-        },
-      ],
-    });
-
-    const contractFile = res.contracts[0].contractFile;
-    const src = fs.readFileSync(contractFile, "utf8");
-    assert.ok(src.includes("Example contract doc from Solidity."));
-    assert.ok(src.includes("Example function doc from Solidity."));
-  });
-});
-
+/**
+ * @testCategory unit
+ * @blockchainRequired false
+ * @transactional false
+ * @description Typed contract generator (file output shape)
+ */
+
+const { describe, it } = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const { generate, generateFromArtifacts } = require("../../src/generator");
+const { logSuite, logTest } = require("../verbose-logger");
+
+describe("typed contract generator", () => {
+  logSuite("typed contract generator");
+  it("generates contract + factory + types + index files", () => {
+    logTest("generates contract + factory + types + index files", {});
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "qcgen-"));
+    const abiPath = path.join(tmp, "Test.abi.json");
+    const binPath = path.join(tmp, "Test.bin");
+    const outDir = path.join(tmp, "out");
+
+    const abi = [
+      {
+        type: "function",
+        name: "balanceOf",
+        stateMutability: "view",
+        inputs: [{ name: "account", type: "address" }],
+        outputs: [{ name: "", type: "uint256" }],
+      },
+      {
+        type: "function",
+        name: "transfer",
+        stateMutability: "nonpayable",
+        inputs: [
+          { name: "to", type: "address" },
+          { name: "amount", type: "uint256" },
+        ],
+        outputs: [{ name: "", type: "bool" }],
+      },
+    ];
+
+    fs.writeFileSync(abiPath, JSON.stringify(abi, null, 2), "utf8");
+    fs.writeFileSync(binPath, "0x6000", "utf8");
+
+    const res = generate({ abiPath, binPath, outDir, contractName: "TestToken" });
+    assert.ok(fs.existsSync(res.contractFile));
+    assert.ok(fs.existsSync(res.factoryFile));
+    assert.ok(fs.existsSync(res.typesFile));
+    assert.ok(fs.existsSync(res.indexFile));
+
+    const contractSrc = fs.readFileSync(res.contractFile, "utf8");
+    assert.ok(contractSrc.includes("export class TestToken"));
+    assert.ok(contractSrc.includes("async balanceOf"));
+    assert.ok(contractSrc.includes("async transfer"));
+    assert.ok(contractSrc.includes("populateTransaction"));
+
+    const factorySrc = fs.readFileSync(res.factoryFile, "utf8");
+    assert.ok(factorySrc.includes("export class TestToken__factory"));
+  });
+
+  it("includes injected docs in generated TypeScript", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "qcgen-docs-"));
+    const outDir = path.join(tmp, "out");
+
+    const abi = [
+      {
+        type: "function",
+        name: "set",
+        stateMutability: "nonpayable",
+        inputs: [{ name: "value", type: "uint256" }],
+        outputs: [],
+      },
+    ];
+
+    const res = generateFromArtifacts({
+      outDir,
+      artifacts: [
+        {
+          contractName: "DocToken",
+          abi,
+          bytecode: "0x6000",
+          docs: {
+            contract: "Example contract doc from Solidity.",
+            functions: {
+              set: "Example function doc from Solidity.",
+            },
+          },
+        },
+      ],
+    });
+
+    const contractFile = res.contracts[0].contractFile;
+    const src = fs.readFileSync(contractFile, "utf8");
+    assert.ok(src.includes("Example contract doc from Solidity."));
+    assert.ok(src.includes("Example function doc from Solidity."));
+  });
+});
+

package/test/unit/generator.test.ts

@@ -0,0 +1,101 @@
+/**
+ * @testCategory unit
+ * @blockchainRequired false
+ * @transactional false
+ * @description Typed contract generator (file output shape)
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { generate, generateFromArtifacts } from "../../src/generator";
+import { logSuite, logTest } from "../verbose-logger";
+
+describe("typed contract generator", () => {
+  logSuite("typed contract generator");
+  it("generates contract + factory + types + index files", () => {
+    logTest("generates contract + factory + types + index files", {});
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "qcgen-"));
+    const abiPath = path.join(tmp, "Test.abi.json");
+    const binPath = path.join(tmp, "Test.bin");
+    const outDir = path.join(tmp, "out");
+
+    const abi = [
+      {
+        type: "function",
+        name: "balanceOf",
+        stateMutability: "view",
+        inputs: [{ name: "account", type: "address" }],
+        outputs: [{ name: "", type: "uint256" }],
+      },
+      {
+        type: "function",
+        name: "transfer",
+        stateMutability: "nonpayable",
+        inputs: [
+          { name: "to", type: "address" },
+          { name: "amount", type: "uint256" },
+        ],
+        outputs: [{ name: "", type: "bool" }],
+      },
+    ];
+
+    fs.writeFileSync(abiPath, JSON.stringify(abi, null, 2), "utf8");
+    fs.writeFileSync(binPath, "0x6000", "utf8");
+
+    const res = generate({ abiPath, binPath, outDir, contractName: "TestToken" });
+    assert.ok(fs.existsSync(res.contractFile));
+    assert.ok(fs.existsSync(res.factoryFile));
+    assert.ok(fs.existsSync(res.typesFile));
+    assert.ok(fs.existsSync(res.indexFile));
+
+    const contractSrc = fs.readFileSync(res.contractFile, "utf8");
+    assert.ok(contractSrc.includes("export class TestToken"));
+    assert.ok(contractSrc.includes("async balanceOf"));
+    assert.ok(contractSrc.includes("async transfer"));
+    assert.ok(contractSrc.includes("populateTransaction"));
+
+    const factorySrc = fs.readFileSync(res.factoryFile, "utf8");
+    assert.ok(factorySrc.includes("export class TestToken__factory"));
+  });
+
+  it("includes injected docs in generated TypeScript", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "qcgen-docs-"));
+    const outDir = path.join(tmp, "out");
+
+    const abi = [
+      {
+        type: "function",
+        name: "set",
+        stateMutability: "nonpayable",
+        inputs: [{ name: "value", type: "uint256" }],
+        outputs: [],
+      },
+    ];
+
+    const res = generateFromArtifacts({
+      outDir,
+      artifacts: [
+        {
+          contractName: "DocToken",
+          abi,
+          bytecode: "0x6000",
+          docs: {
+            contract: "Example contract doc from Solidity.",
+            functions: {
+              set: "Example function doc from Solidity.",
+            },
+          },
+        },
+      ],
+    });
+
+    const contractFile = res.contracts[0].contractFile;
+    const src = fs.readFileSync(contractFile, "utf8");
+    assert.ok(src.includes("Example contract doc from Solidity."));
+    assert.ok(src.includes("Example function doc from Solidity."));
+  });
+});