c-next 0.2.17 → 0.2.18

package/src/transpiler/logic/preprocessor/__tests__/CompileCommandsReader.test.ts

@@ -0,0 +1,216 @@
+/**
+ * Unit tests for CompileCommandsReader.
+ *
+ * cnext must resolve external C/C++ headers exactly as the compiler will. Every
+ * build system (CMake, PlatformIO, Meson, Zephyr, bear-wrapped Make) converges
+ * on the same artifact — a `compile_commands.json` compilation database listing,
+ * per translation unit, the compiler binary and its `-I` / `-D` flags. Reading
+ * that database is how clangd/clang-tidy stay build-system-agnostic; cnext reads
+ * it for the same reason. This is the pure parse layer (no filesystem): a DB
+ * string in, `{ includePaths, defines, compiler }` out.
+ */
+import { describe, it, expect } from "vitest";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import CompileCommandsReader from "../CompileCommandsReader";
+
+describe("CompileCommandsReader.parse", () => {
+  it("extracts include paths from -I arguments, resolving relative to the entry directory", () => {
+    const db = JSON.stringify([
+      {
+        directory: "/project/build",
+        file: "/project/src/main.cpp",
+        arguments: [
+          "xtensa-esp32s3-elf-g++",
+          "-I/abs/include",
+          "-I../rel/include",
+          "-c",
+          "/project/src/main.cpp",
+        ],
+      },
+    ]);
+
+    const result = CompileCommandsReader.parse(db);
+
+    // Absolute -I kept verbatim.
+    expect(result.includePaths).toContain("/abs/include");
+    // Relative -I resolved against the entry's `directory` (/project/build).
+    expect(result.includePaths).toContain("/project/rel/include");
+  });
+
+  it("handles space-separated -I and -isystem forms", () => {
+    const db = JSON.stringify([
+      {
+        directory: "/project",
+        file: "/project/src/main.cpp",
+        arguments: [
+          "g++",
+          "-I",
+          "sep/include",
+          "-isystem",
+          "/opt/toolchain/include",
+          "-isystem/attached/system",
+          "-c",
+          "main.cpp",
+        ],
+      },
+    ]);
+
+    const result = CompileCommandsReader.parse(db);
+
+    expect(result.includePaths).toContain("/project/sep/include"); // -I <path>
+    expect(result.includePaths).toContain("/opt/toolchain/include"); // -isystem <path>
+    expect(result.includePaths).toContain("/attached/system"); // -isystem<path>
+  });
+
+  it("extracts defines: KEY=VAL, bare KEY, and space-separated forms", () => {
+    const db = JSON.stringify([
+      {
+        directory: "/project",
+        file: "/project/src/main.cpp",
+        arguments: [
+          "g++",
+          "-DARDUINO=10812",
+          "-DCORE_DEBUG_LEVEL",
+          "-D",
+          "F_CPU=240000000L",
+          "-c",
+          "main.cpp",
+        ],
+      },
+    ]);
+
+    const result = CompileCommandsReader.parse(db);
+
+    expect(result.defines.ARDUINO).toBe("10812"); // -DKEY=VAL
+    expect(result.defines.CORE_DEBUG_LEVEL).toBe(true); // bare -DKEY
+    expect(result.defines.F_CPU).toBe("240000000L"); // -D KEY=VAL (separated)
+  });
+
+  it("parses the `command` string form with POSIX word-splitting", () => {
+    // PlatformIO emits a `command` string (not `arguments`). Word-splitting must
+    // match the shell the compiler was actually invoked through: real quotes are
+    // syntax (consumed), backslash-escaped quotes are literal (kept), and spaces
+    // inside quotes are preserved. The ARDUINO_BOARD case is the real gnarly one
+    // — outer real quotes wrapping backslash-escaped inner quotes, with spaces.
+    const db = JSON.stringify([
+      {
+        directory: "/project",
+        file: "/project/src/main.cpp",
+        command:
+          "xtensa-esp32s3-elf-g++ -Iinclude -I/abs/inc -DARDUINO=10812 " +
+          '-DARDUINO_BOARD="\\"Espressif ESP32-S3 (8 MB QD, No PSRAM)\\"" ' +
+          "'-DSINGLE=a b' -c main.cpp",
+      },
+    ]);
+
+    const result = CompileCommandsReader.parse(db);
+
+    expect(result.compiler).toBe("xtensa-esp32s3-elf-g++"); // argv[0]
+    expect(result.includePaths).toContain("/project/include"); // -Iinclude, rel
+    expect(result.includePaths).toContain("/abs/inc");
+    expect(result.defines.ARDUINO).toBe("10812");
+    // Escaped inner quotes kept, spaces preserved inside the real outer quotes.
+    expect(result.defines.ARDUINO_BOARD).toBe(
+      '"Espressif ESP32-S3 (8 MB QD, No PSRAM)"',
+    );
+    // Single-quoted operand: literal, spaces preserved, quotes consumed.
+    expect(result.defines.SINGLE).toBe("a b");
+  });
+
+  it("matches shlex on double-quote escapes and escaped whitespace", () => {
+    // Verified against `shlex.split`: inside "" only \" and \\ are escapes, so a
+    // backslash is KEPT before other characters (e.g. $); \<space> outside quotes
+    // is a literal space that joins one token.
+    const command = String.raw`cc -DA="x\\y" -DB="p\$q" -DD="lit\z" -DE=v\ w -c f.c`;
+    const db = JSON.stringify([{ directory: "/p", file: "/p/f.c", command }]);
+
+    const result = CompileCommandsReader.parse(db);
+
+    expect(result.defines.A).toBe("x\\y"); // "\\" -> one literal backslash
+    expect(result.defines.B).toBe("p\\$q"); // "\$" -> backslash kept
+    expect(result.defines.D).toBe("lit\\z"); // "\z" -> backslash kept
+    expect(result.defines.E).toBe("v w"); // v\ w -> single token "v w"
+  });
+
+  it("ignores trailing -I / -D flags that have no operand", () => {
+    const dbI = JSON.stringify([
+      { directory: "/p", file: "a.c", arguments: ["cc", "-I"] },
+    ]);
+    const dbD = JSON.stringify([
+      { directory: "/p", file: "a.c", arguments: ["cc", "-D"] },
+    ]);
+
+    expect(CompileCommandsReader.parse(dbI).includePaths).toEqual([]);
+    expect(CompileCommandsReader.parse(dbD).defines).toEqual({});
+  });
+
+  it("drops a trailing backslash without crashing", () => {
+    const db = JSON.stringify([
+      { directory: "/p", file: "/p/f.c", command: "cc -DA=1 -c f.c\\" },
+    ]);
+
+    const result = CompileCommandsReader.parse(db);
+
+    expect(result.defines.A).toBe("1");
+    expect(result.compiler).toBe("cc");
+  });
+
+  it("tolerates an entry with neither command nor arguments", () => {
+    const db = JSON.stringify([{ directory: "/p", file: "/p/a.c" }]);
+
+    const result = CompileCommandsReader.parse(db);
+
+    expect(result.includePaths).toEqual([]);
+    expect(result.defines).toEqual({});
+    expect(result.compiler).toBeNull();
+  });
+});
+
+describe("CompileCommandsReader.load", () => {
+  it("reads and parses a compile_commands.json file from disk", () => {
+    const dir = mkdtempSync(join(tmpdir(), "cnext-cc-"));
+    try {
+      writeFileSync(
+        join(dir, "compile_commands.json"),
+        JSON.stringify([
+          {
+            directory: dir,
+            file: "a.cpp",
+            command: "g++ -I/x/inc -DFOO=1 -c a.cpp",
+          },
+        ]),
+      );
+
+      const result = CompileCommandsReader.load(
+        join(dir, "compile_commands.json"),
+      );
+
+      expect(result).not.toBeNull();
+      expect(result?.includePaths).toContain("/x/inc");
+      expect(result?.defines.FOO).toBe("1");
+      expect(result?.compiler).toBe("g++");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("returns null for a missing file (caller falls back to config)", () => {
+    expect(
+      CompileCommandsReader.load("/no/such/dir/compile_commands.json"),
+    ).toBeNull();
+  });
+
+  it("returns null for malformed JSON rather than throwing", () => {
+    const dir = mkdtempSync(join(tmpdir(), "cnext-cc-"));
+    try {
+      writeFileSync(join(dir, "compile_commands.json"), "{ not valid json ");
+      expect(
+        CompileCommandsReader.load(join(dir, "compile_commands.json")),
+      ).toBeNull();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/transpiler/logic/preprocessor/__tests__/ExternalDeclarationOracle.test.ts

@@ -0,0 +1,153 @@
+/**
+ * Unit tests for ExternalDeclarationOracle.
+ *
+ * cnext collects header symbols by preprocessing each header standalone, which
+ * fails for include-order-dependent framework headers (e.g. FreeRTOS task.h's
+ * `#ifndef INC_FREERTOS_H / #error`). The oracle recovers by preprocessing a
+ * header set AS A TRANSLATION UNIT (in order, keeping `#line` directives), then
+ * splitting the output back into per-file slices (for the caller to parse into
+ * full symbols) plus the names of function-like macros (no declaration to parse).
+ */
+import { describe, it, expect } from "vitest";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import ExternalDeclarationOracle from "../ExternalDeclarationOracle";
+import Preprocessor from "../Preprocessor";
+
+const currentDir = dirname(fileURLToPath(import.meta.url));
+const FIXTURES = join(currentDir, "fixtures", "oracle");
+
+function allContent(perFile: Map<string, string>): string {
+  return [...perFile.values()].join("\n");
+}
+
+describe("ExternalDeclarationOracle", () => {
+  it("recovers a declaration only valid after its predecessor header", async () => {
+    const preprocessor = new Preprocessor();
+    if (!preprocessor.isAvailable()) return; // no toolchain in this env
+
+    const recovery = await ExternalDeclarationOracle.recover(
+      ['"predecessor.h"', '"dependent.h"'],
+      preprocessor,
+      { includePaths: [FIXTURES] },
+    );
+
+    // dependent.h's #error passes only because predecessor.h ran first in the
+    // TU; oracle_fn is emitted (by a predecessor-defined macro) into its slice.
+    expect(recovery).not.toBeNull();
+    expect(allContent(recovery!.perFileContent)).toContain("oracle_fn");
+  });
+
+  it("buckets each header's declarations under its own path", async () => {
+    const preprocessor = new Preprocessor();
+    if (!preprocessor.isAvailable()) return;
+
+    const recovery = await ExternalDeclarationOracle.recover(
+      ['"predecessor.h"', '"dependent.h"'],
+      preprocessor,
+      { includePaths: [FIXTURES] },
+    );
+
+    const dependentKey = [...recovery!.perFileContent.keys()].find((k) =>
+      k.endsWith("dependent.h"),
+    );
+    expect(dependentKey).toBeDefined();
+    expect(recovery!.perFileContent.get(dependentKey!)).toContain("oracle_fn");
+  });
+
+  it("collects function-like macro names consumed by a normal preprocess", async () => {
+    const preprocessor = new Preprocessor();
+    if (!preprocessor.isAvailable()) return;
+
+    const recovery = await ExternalDeclarationOracle.recover(
+      ['"predecessor.h"'],
+      preprocessor,
+      { includePaths: [FIXTURES] },
+    );
+
+    expect(recovery!.macroNames.has("ORACLE_TICKS")).toBe(true);
+  });
+
+  it("does not surface names that are not declared anywhere", async () => {
+    const preprocessor = new Preprocessor();
+    if (!preprocessor.isAvailable()) return;
+
+    const recovery = await ExternalDeclarationOracle.recover(
+      ['"predecessor.h"'],
+      preprocessor,
+      { includePaths: [FIXTURES] },
+    );
+
+    expect(allContent(recovery!.perFileContent)).not.toContain(
+      "totally_undeclared_symbol",
+    );
+    expect(recovery!.macroNames.has("totally_undeclared_symbol")).toBe(false);
+  });
+
+  it("drops a header that cannot preprocess and keeps the rest", async () => {
+    const preprocessor = new Preprocessor();
+    if (!preprocessor.isAvailable()) return;
+
+    const recovery = await ExternalDeclarationOracle.recover(
+      // the middle include does not exist; it must be dropped, not fatal
+      [
+        '"predecessor.h"',
+        "<this_header_does_not_exist_xyzzy.h>",
+        '"dependent.h"',
+      ],
+      preprocessor,
+      { includePaths: [FIXTURES] },
+    );
+
+    expect(allContent(recovery!.perFileContent)).toContain("oracle_fn");
+    expect(recovery!.macroNames.has("ORACLE_TICKS")).toBe(true);
+  });
+
+  it("keeps searching after dropping more than half the includes", async () => {
+    const preprocessor = new Preprocessor();
+    if (!preprocessor.isAvailable()) return;
+
+    // Three of five includes are individually unpreprocessable. Dropping them
+    // one per iteration (>half) must not exhaust the loop before the two good
+    // includes are tried together. Regression for the aliased loop bound that
+    // re-read the shrinking directive count and bailed once >half were dropped.
+    const recovery = await ExternalDeclarationOracle.recover(
+      [
+        "<cnext_no_such_header_a.h>",
+        "<cnext_no_such_header_b.h>",
+        "<cnext_no_such_header_c.h>",
+        '"predecessor.h"',
+        '"dependent.h"',
+      ],
+      preprocessor,
+      { includePaths: [FIXTURES] },
+    );
+
+    expect(recovery).not.toBeNull();
+    expect(allContent(recovery!.perFileContent)).toContain("oracle_fn");
+  });
+
+  it("returns null for no includes", async () => {
+    const preprocessor = new Preprocessor();
+    const recovery = await ExternalDeclarationOracle.recover(
+      [],
+      preprocessor,
+      {},
+    );
+    expect(recovery).toBeNull();
+  });
+
+  it("returns null when no header can preprocess", async () => {
+    const preprocessor = new Preprocessor();
+    if (!preprocessor.isAvailable()) return;
+
+    // The only include does not exist; after it is dropped nothing remains, so
+    // the largest-working-TU search exhausts and recovery yields null.
+    const recovery = await ExternalDeclarationOracle.recover(
+      ["<cnext_no_such_header_xyzzy.h>"],
+      preprocessor,
+      { includePaths: [FIXTURES] },
+    );
+    expect(recovery).toBeNull();
+  });
+});

package/src/transpiler/logic/preprocessor/__tests__/Preprocessor.test.ts

@@ -20,16 +20,21 @@ type ExecCallback = (
   result: { stdout: string; stderr: string },
 ) => void;
 
-// Mock child_process - exec is promisified, so we mock it to work with promisify
+// Mock child_process - execFile is promisified, so we mock it to work with
+// promisify. execFile is called as (file, args, options, callback).
 vi.mock("node:child_process", () => ({
-  exec: (cmd: string, opts: unknown, cb?: ExecCallback) => {
+  execFile: (
+    file: string,
+    args: string[],
+    opts: unknown,
+    cb?: ExecCallback,
+  ) => {
     // promisify converts callback-based to promise-based
-    // We handle both forms (2-arg and 3-arg)
     let callback: ExecCallback | undefined = cb;
     if (typeof opts === "function") {
       callback = opts as ExecCallback;
     }
-    const result = mockExec(cmd, opts);
+    const result = mockExec(file, args, opts);
     if (result instanceof Promise) {
       result
         .then((r: { stdout: string; stderr: string }) => callback?.(null, r))
@@ -170,11 +175,12 @@ describe("Preprocessor", () => {
       await preprocessor.preprocess("/path/to/file.h");
 
       expect(mockExec).toHaveBeenCalled();
-      const command = mockExec.mock.calls[0][0];
-      expect(command).toContain("/usr/bin/gcc");
-      expect(command).toContain("-E");
-      expect(command).toContain("/path/to/file.h");
-      expect(command).toContain("-I/path/to");
+      const file = mockExec.mock.calls[0][0];
+      const args = mockExec.mock.calls[0][1];
+      expect(file).toBe("/usr/bin/gcc");
+      expect(args).toContain("-E");
+      expect(args).toContain("/path/to/file.h");
+      expect(args).toContain("-I/path/to");
     });
 
     it("includes custom include paths", async () => {
@@ -188,9 +194,9 @@ describe("Preprocessor", () => {
         includePaths: ["/custom/include", "/another/path"],
       });
 
-      const command = mockExec.mock.calls[0][0];
-      expect(command).toContain("-I/custom/include");
-      expect(command).toContain("-I/another/path");
+      const args = mockExec.mock.calls[0][1];
+      expect(args).toContain("-I/custom/include");
+      expect(args).toContain("-I/another/path");
     });
 
     it("includes defines", async () => {
@@ -208,10 +214,29 @@ describe("Preprocessor", () => {
         },
       });
 
-      const command = mockExec.mock.calls[0][0];
-      expect(command).toContain("-DDEBUG");
-      expect(command).toContain("-DVERSION=1.0");
-      expect(command).not.toContain("-DDISABLED");
+      const args = mockExec.mock.calls[0][1];
+      expect(args).toContain("-DDEBUG");
+      expect(args).toContain("-DVERSION=1.0");
+      expect(args).not.toContain("-DDISABLED");
+    });
+
+    it("passes defines with shell metacharacters as a single argv element", async () => {
+      mockExec.mockReturnValue({ stdout: "content", stderr: "" });
+
+      const preprocessor = new Preprocessor(mockToolchain);
+      // A board-name macro whose value contains spaces and parentheses — valid
+      // for the compiler, but would break /bin/sh if the command were routed
+      // through a shell (Issue: cnext preprocessor must invoke via argv).
+      await preprocessor.preprocess("/path/to/file.h", {
+        defines: {
+          ARDUINO_BOARD: '"Espressif ESP32-S3 (8 MB QD, No PSRAM)"',
+        },
+      });
+
+      const args = mockExec.mock.calls[0][1];
+      expect(args).toContain(
+        '-DARDUINO_BOARD="Espressif ESP32-S3 (8 MB QD, No PSRAM)"',
+      );
     });
 
     it("returns success result with content", async () => {
@@ -290,8 +315,8 @@ int y = 10;
         keepLineDirectives: false,
       });
 
-      const command = mockExec.mock.calls[0][0];
-      expect(command).toContain("-P");
+      const args = mockExec.mock.calls[0][1];
+      expect(args).toContain("-P");
     });
 
     it("handles preprocessor errors", async () => {

package/src/transpiler/logic/preprocessor/__tests__/ToolchainDetector.crossCompiler.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Unit tests for ToolchainDetector.fromPath and the CNEXT_CROSS_COMPILER override.
+ *
+ * Cross-compilation targets (e.g. ESP32/xtensa) ship framework headers that
+ * only preprocess with the target compiler — host gcc lacks their system
+ * headers and predefined macros. CNEXT_CROSS_COMPILER lets a project point cnext's
+ * preprocessor at that compiler (e.g. xtensa-esp32s3-elf-gcc).
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import ToolchainDetector from "../ToolchainDetector";
+
+vi.mock("node:child_process", () => ({ execSync: vi.fn() }));
+vi.mock("node:fs", () => ({ existsSync: vi.fn() }));
+
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+
+describe("ToolchainDetector.fromPath", () => {
+  beforeEach(() => vi.clearAllMocks());
+  afterEach(() => vi.restoreAllMocks());
+
+  it("builds a cross-compiler toolchain from an executable name on PATH", () => {
+    vi.mocked(execSync).mockImplementation((cmd: string) => {
+      if (cmd === "which xtensa-esp32s3-elf-gcc") {
+        return "/opt/xt/bin/xtensa-esp32s3-elf-gcc\n";
+      }
+      return "xtensa-esp32s3-elf-gcc (crosstool-NG) 12.2.0\n";
+    });
+    vi.mocked(existsSync).mockReturnValue(true);
+
+    const tc = ToolchainDetector.fromPath("xtensa-esp32s3-elf-gcc");
+
+    expect(tc).not.toBeNull();
+    expect(tc!.cpp).toBe("/opt/xt/bin/xtensa-esp32s3-elf-gcc");
+    expect(tc!.name).toBe("xtensa-esp32s3-elf-gcc");
+    expect(tc!.isCrossCompiler).toBe(true);
+  });
+
+  it("accepts an absolute compiler path directly", () => {
+    vi.mocked(existsSync).mockReturnValue(true);
+    vi.mocked(execSync).mockReturnValue("gcc 13\n");
+
+    const tc = ToolchainDetector.fromPath("/usr/bin/xtensa-esp32s3-elf-gcc");
+
+    expect(tc!.cpp).toBe("/usr/bin/xtensa-esp32s3-elf-gcc");
+  });
+
+  it("returns null when the compiler path does not exist", () => {
+    vi.mocked(existsSync).mockReturnValue(false);
+
+    expect(ToolchainDetector.fromPath("/nope/xtensa-gcc")).toBeNull();
+  });
+});
+
+describe("ToolchainDetector.detect with CNEXT_CROSS_COMPILER", () => {
+  const original = process.env.CNEXT_CROSS_COMPILER;
+  beforeEach(() => vi.clearAllMocks());
+  afterEach(() => {
+    vi.restoreAllMocks();
+    if (original === undefined) delete process.env.CNEXT_CROSS_COMPILER;
+    else process.env.CNEXT_CROSS_COMPILER = original;
+  });
+
+  it("prefers CNEXT_CROSS_COMPILER over auto-detected toolchains", () => {
+    process.env.CNEXT_CROSS_COMPILER = "/opt/xt/bin/xtensa-esp32s3-elf-gcc";
+    vi.mocked(existsSync).mockReturnValue(true);
+    vi.mocked(execSync).mockReturnValue("xtensa gcc 12.2\n");
+
+    const tc = ToolchainDetector.detect();
+
+    expect(tc).not.toBeNull();
+    expect(tc!.cpp).toBe("/opt/xt/bin/xtensa-esp32s3-elf-gcc");
+    expect(tc!.isCrossCompiler).toBe(true);
+  });
+});

package/src/transpiler/logic/preprocessor/__tests__/fixtures/oracle/dependent.h

@@ -0,0 +1,7 @@
+/* Dependent header (mirrors FreeRTOS task.h): refuses standalone inclusion and
+ * emits its declaration via a predecessor-defined macro. Only resolves when
+ * predecessor.h is included first in the same translation unit. */
+#ifndef PRED_GUARD
+#error "include predecessor.h before dependent.h"
+#endif
+DECLARE_ORACLE_FN

package/src/transpiler/logic/preprocessor/__tests__/fixtures/oracle/predecessor.h

@@ -0,0 +1,5 @@
+/* Predecessor header (mirrors FreeRTOS.h): defines the guard, a declaration
+ * macro, and a function-like macro that dependent.h / callers rely on. */
+#define PRED_GUARD 1
+#define DECLARE_ORACLE_FN void oracle_fn(int x);
+#define ORACLE_TICKS(ms) ((ms) / 10)

package/src/transpiler/logic/preprocessor/types/ICompileCommandsResult.ts

@@ -0,0 +1,14 @@
+/**
+ * The compiler's own view, derived from a `compile_commands.json` compilation
+ * database: the include search path, preprocessor defines, and compiler binary.
+ */
+interface ICompileCommandsResult {
+  /** Include search paths (absolute), in first-seen order, de-duplicated. */
+  includePaths: string[];
+  /** Preprocessor defines: `-D KEY=VAL` -> `VAL`, bare `-D KEY` -> `true`. */
+  defines: Record<string, string | boolean>;
+  /** The compiler binary (argv[0]) of the entries, or null if none found. */
+  compiler: string | null;
+}
+
+export default ICompileCommandsResult;

package/src/transpiler/logic/preprocessor/types/IPreprocessOptions.ts

@@ -15,6 +15,23 @@ interface IPreprocessOptions {
 
   /** Keep #line directives for source mapping (default: true) */
   keepLineDirectives?: boolean;
+
+  /**
+   * Headers whose macros to import before preprocessing the target file
+   * (gcc/clang `-imacros`), in order. Supplies include-order macro context so a
+   * header that requires a predecessor can preprocess — e.g. FreeRTOS `task.h`
+   * needs `INC_FREERTOS_H` and attribute macros defined by `FreeRTOS.h` first.
+   * Unlike `-include`, `-imacros` keeps only the predecessors' macros, not their
+   * declarations, so the output stays scoped to the target file.
+   */
+  imacros?: string[];
+
+  /**
+   * Dump macro definitions (gcc/clang `-dM`) instead of preprocessed source.
+   * Output is the `#define` list, used to discover function-like macros (e.g.
+   * FreeRTOS `pdMS_TO_TICKS`) that a plain preprocess consumes at use sites.
+   */
+  dumpMacros?: boolean;
 }
 
 export default IPreprocessOptions;

package/src/transpiler/logic/symbols/SymbolTable.ts

@@ -110,6 +110,16 @@ class SymbolTable {
    */
   private readonly needsStructKeyword: Set<string> = new Set();
 
+  /**
+   * Issue #985 recovery: names of external function-like MACROS recovered by
+   * translation-unit preprocessing (ExternalDeclarationOracle) for headers cnext
+   * could not preprocess standalone. Macros have no declaration to parse, so
+   * only their names are known; consulted by the undeclared-`global.`-call check
+   * so it does not false-positive on a real macro (e.g. FreeRTOS pdMS_TO_TICKS).
+   * Recovered FUNCTIONS are registered as full symbols (with signatures) instead.
+   */
+  private readonly externalDeclarationNames: Set<string> = new Set();
+
   /**
    * Issue #958: Immutable struct symbol state — additive only, query-time resolution.
    * Replaces separate opaqueTypes, typedefStructTypes, structTagAliases fields.
@@ -355,6 +365,21 @@ class SymbolTable {
     }
   }
 
+  /**
+   * Register external declaration names recovered via TU preprocessing.
+   * @see externalDeclarationNames
+   */
+  addExternalDeclarationNames(names: ReadonlySet<string>): void {
+    for (const name of names) {
+      this.externalDeclarationNames.add(name);
+    }
+  }
+
+  /** Whether a name was recovered as an external function / function-like macro. */
+  hasExternalDeclaration(name: string): boolean {
+    return this.externalDeclarationNames.has(name);
+  }
+
   /**
    * Get a C symbol by name (returns first match, or undefined)
    */
@@ -1016,6 +1041,26 @@ class SymbolTable {
     });
   }
 
+  /**
+   * Issue #985: Clear a struct tag's recorded body. Used by external-declaration
+   * recovery to undo a PHANTOM body — one fabricated by ANTLR error-recovery when
+   * the normal pass parsed a header's huge preprocessed blob — so a type the
+   * clean per-file re-parse proves opaque (e.g. lvgl `lv_obj_t`) resolves as
+   * opaque again (and codegen uses a pointer).
+   * @param structTag The struct tag name (e.g., "_lv_obj_t")
+   */
+  clearStructTagHasBody(structTag: string): void {
+    if (!this.structState.structTagsWithBodies.has(structTag)) return;
+    this.structState = produce(this.structState, (draft) => {
+      draft.structTagsWithBodies.delete(structTag);
+    });
+  }
+
+  /** Issue #985: The struct tag a typedef aliases, if any (e.g. lv_obj_t -> _lv_obj_t). */
+  getStructTagForTypedef(typedefName: string): string | undefined {
+    return this.structState.typedefToTag.get(typedefName);
+  }
+
   /**
    * Issue #958: Get all struct tags with bodies for cache serialization.
    * @returns Array of struct tag names