feat(cmd): GOOS-aware headers, audit battery shapes and semicolon spacing

Assisted-by: GLM 5.3 Flash

docs/CLI.md

@@ -141,7 +141,7 @@ gasm lint kernel_amd64.s
 ## asm
 
 ```text
-Usage: gasm asm [--format raw|elf|goobj] [-I dir] [-p pkg] [-GOARCH arch] [-o out] <file>
+Usage: gasm asm [--format raw|elf|goobj] [-I dir] [-p pkg] [-GOARCH arch] [-GOOS os] [-o out] <file>
 ```
 
 | Flag | Default | Effect |
@@ -150,6 +150,7 @@ Usage: gasm asm [--format raw|elf|goobj] [-I dir] [-p pkg] [-GOARCH arch] [-o ou
 | `-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 |
+| `-GOOS` | empty | operating system for the generated `go_asm.h`: any GOOS `go/build` recognises in file names; default is the host's |
 | `-o` | empty | write the output to this file instead of a hex dump on stdout |
 
 Supported architectures: amd64 (VEX/AVX2 and EVEX/AVX-512 included), arm64,
@@ -163,6 +164,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.
 
+A file that includes `go_asm.h` gets that header generated from the Go
+files beside it, type-checked for the target. `-GOOS` selects the
+type-checking GOOS for that header, because a GOOS-specific file needs its
+platform's defines: `sys_darwin_arm64.s` fails against the ambient GOOS
+(`machTimebaseInfo_numer` is missing from a linux type-check) and assembles
+with `-GOOS darwin`.
+
 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,
@@ -390,7 +398,9 @@ With `--corpus` the audit changes shape: it assembles every `.s` file under
 DIR (default `GOROOT/src`) with the gasm encoder only, no toolchain probing.
 A file whose name carries a recognisable `_arch` suffix is attempted for that
 architecture; a file without one is attempted for all four, exactly as a
-`GOARCH` build would compile it. The report gives the headline number (files
+`GOARCH` build would compile it, and a name that names a GOOS
+(`sys_darwin_arm64.s`) type-checks its generated `go_asm.h` for that GOOS.
+The report gives the headline number (files
 that assemble for every target architecture), the per-architecture pass rates
 and the most common failure reasons with one representative file each, which
 drive the encodability backlog by frequency rather than by table order. A run

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] [\-I dir] [\-p pkg] [\-GOARCH arch] [\-o out] <file>
+.B gasm asm [\-\-format raw|elf|goobj] [\-I dir] [\-p pkg] [\-GOARCH arch] [\-GOOS os] [\-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:
@@ -42,6 +42,15 @@ need no toolchain at all.
 Framed functions receive the stack-split guard and the trailing
 morestack block, byte-identical to the toolchain's output, so split
 functions link too.
+.PP
+A file that includes go_asm.h gets that header generated from the Go
+files beside it, type-checked for the target.
+.B \-GOOS
+selects the type-checking GOOS for that header, because a GOOS-specific
+file needs its platform's defines: sys_darwin_arm64.s fails against the
+ambient GOOS (machTimebaseInfo_numer is missing from a linux type-check)
+and assembles with
+.BR "\-GOOS darwin" .
 .SH OPTIONS
 .TP
 .B \-\-format \fIraw|elf|goobj\fR
@@ -59,6 +68,10 @@ Target architecture: amd64, arm64, riscv64 or loong64; overrides the
 file-name suffix, which is how the suffix-less majority of GOROOT's
 files (cpu_x86.s, stub.s, ...) become assemblable.
 .TP
+.B \-GOOS \fIos\fR
+Operating system for the generated go_asm.h: any GOOS go/build
+recognises in file names; the default is the host's.
+.TP
 .B \-o \fIfile\fR
 Write the output to this file instead of a hex dump on stdout.
 .SH EXIT STATUS