feat(parser): macro expansion, conditionals and include splicing with -I

Assisted-by: GLM 5.3 Flash

docs/CLI.md

@@ -141,12 +141,13 @@ gasm lint kernel_amd64.s
 ## asm
 
 ```text
-Usage: gasm asm [--format raw|elf|goobj] [-p pkg] [-GOARCH arch] [-o out] <file>
+Usage: gasm asm [--format raw|elf|goobj] [-I dir] [-p pkg] [-GOARCH arch] [-o out] <file>
 ```
 
 | Flag | Default | Effect |
 |---|---|---|
 | `-format` | `raw` | output format: `raw` (concatenated image), `elf` or `goobj` (Go object) |
+| `-I` | empty | directory to search for `#include` files; may be repeated, searched in order after the source directory |
 | `-p` | empty | package path for `--format goobj`, qualifying the exported symbols |
 | `-GOARCH` | empty | target architecture: `amd64`, `arm64`, `riscv64` or `loong64`; overrides the file-name suffix |
 | `-o` | empty | write the output to this file instead of a hex dump on stdout |
@@ -162,6 +163,13 @@ system toolchain; `goobj` emits the Go toolchain's own object format, which
 installed: the object preamble is captured from `go tool asm` and the format
 version from `go version`. `raw` and `elf` need no toolchain at all.
 
+Assembly preprocessing matches the toolchain's: `#define` macros (object and
+parameterised) expand at the point of use, `#undef`, `#ifdef`, `#ifndef`,
+`#else` and `#endif` behave as in `go tool asm`, `;` separates statements,
+and `#include "file"` splices the named file in, resolved against the source
+directory and then each `-I` directory in order. `textflag.h` is the one
+header that is not spliced: gasm consumes its flag names natively.
+
 ```sh
 gasm asm hello_amd64.s
 ```
@@ -305,12 +313,13 @@ gasm debug --func add --cover hello_amd64.s
 ## diff
 
 ```text
-Usage: gasm diff [-GOARCH arch] <file1.s> <file2.s>
+Usage: gasm diff [-GOARCH arch] [-I dir] <file1.s> <file2.s>
 ```
 
 | Flag | Default | Effect |
 |---|---|---|
 | `-GOARCH` | empty | target architecture for both files, overriding the file-name suffixes |
+| `-I` | empty | directory to search for `#include` files; may be repeated, searched in order after the source directory |
 | `-map` | empty | comma-separated `old=new` pairs to match functions with different names |
 
 Functions are paired by exact name unless `--map` says otherwise, so
@@ -348,7 +357,7 @@ add: 16 bytes, args=24, frame=0 NOSPLIT
 ## audit-instructions
 
 ```text
-Usage: gasm audit-instructions [--corpus [dir]] [amd64|arm64|riscv64|loong64]
+Usage: gasm audit-instructions [--corpus [dir]] [-I dir] [amd64|arm64|riscv64|loong64]
 ```
 
 Compare the gasm encoder for the given architecture (default amd64) against the

docs/man/gasm-asm.1

@@ -2,7 +2,7 @@
 .SH NAME
 gasm-asm \- assemble Plan 9 assembly without the Go toolchain
 .SH SYNOPSIS
-.B gasm asm [\-\-format raw|elf|goobj] [\-p pkg] [\-GOARCH arch] [\-o out] <file>
+.B gasm asm [\-\-format raw|elf|goobj] [\-I dir] [\-p pkg] [\-GOARCH arch] [\-o out] <file>
 .SH DESCRIPTION
 Assemble FILE without the Go toolchain: every TEXT function is encoded
 to machine code and printed as a hex dump.  Supported architectures:
@@ -47,6 +47,10 @@ functions link too.
 .B \-\-format \fIraw|elf|goobj\fR
 Output format; the default is raw.
 .TP
+.B \-I \fIdir\fR
+Directory to search for #include files; may be repeated, searched in
+order after the source directory.
+.TP
 .B \-p \fIpkg\fR
 Package path for --format goobj, qualifying the exported symbols.
 .TP

docs/man/gasm-audit-instructions.1

@@ -2,7 +2,7 @@
 .SH NAME
 gasm-audit-instructions \- diff the encoder against the Go toolchain, or measure a corpus
 .SH SYNOPSIS
-.B gasm audit\-instructions [\-\-corpus [\fIdir\fR]] [amd64|arm64|riscv64|loong64]
+.B gasm audit\-instructions [\-\-corpus [\fIdir\fR]] [\-I dir] [amd64|arm64|riscv64|loong64]
 .SH DESCRIPTION
 Compare the gasm encoder for the given architecture (default amd64)
 against
@@ -38,6 +38,12 @@ second.
 .B \-\-corpus [\fIdir\fR]
 Assemble a corpus of .s files and report pass rates and failure
 reasons.
+.TP
+.B \-I \fIdir\fR
+Directory to search for #include files; may be repeated, searched in
+order after the source directory.  A corpus run whose files include
+toolchain headers (such as GOROOT/pkg/include) needs it, the same -I a
+toolchain comparison takes.
 .SH EXIT STATUS
 The mnemonic-diff mode reports through its output and exits 0; a failed
 probe or an unknown architecture exits non-zero.

docs/man/gasm-diff.1

@@ -2,7 +2,7 @@
 .SH NAME
 gasm-diff \- compare the machine code of two assembly files
 .SH SYNOPSIS
-.B gasm diff [\-GOARCH arch] <file1.s> <file2.s>
+.B gasm diff [\-GOARCH arch] [\-I dir] <file1.s> <file2.s>
 .SH DESCRIPTION
 Compare the machine code produced by assembling two files.  Shows which
 functions differ and the byte-level differences.  Useful for verifying
@@ -20,6 +20,10 @@ pairs two variants regardless of suffix.
 Target architecture for both files: amd64, arm64, riscv64 or loong64;
 overrides the file-name suffixes.
 .TP
+.B \-I \fIdir\fR
+Directory to search for #include files; may be repeated, searched in
+order after the source directory.
+.TP
 .B \-\-map \fIspec\fR
 Comma-separated old=new pairs to match functions with different names.
 .SH EXIT STATUS