@jhlagado/azm 0.2.0 → 0.2.2

package/README.md

@@ -1,47 +1,63 @@
 # AZM
 
-AZM is a Z80 assembler in the ASM80 tradition: plain assembly input, predictable
-object output, and modern safety tooling for projects that still want to see the
-machine.
-
-The project goal is a good assembler, not a high-level language. AZM keeps
-labels, directives, instructions, branches, data bytes, register effects, and
-generated metadata visible in source and artifacts.
-
-## Product boundary
-
-AZM keeps:
-
-- ASM80-style `.asm` / `.z80` source as the input baseline
-- `.asmi` external interface files for register-care contracts
+AZM is the Z80 assembler used by the Debug80 toolchain. It assembles plain
+`.asm` and `.z80` source into machine-code artifacts for hardware, emulators,
+and Debug80: Intel HEX, flat binary, Debug80 maps, and optional
+ASM80-compatible lowered source.
+
+The user manual is the AZM book in the Debug80 documentation site:
+
+[AZM Assembler Manual](https://jhlagado.github.io/debug80-docs/azm-book/book4/)
+
+## What AZM Is
+
+AZM is an assembler, not a high-level language or macro preprocessor. Source is
+intended to stay close to the machine: labels, directives, instructions, data,
+register contracts, and generated artifacts remain visible.
+
+AZM keeps the parts of the original assembler that matter for real Z80 work:
+
+- Z80 instructions with case-insensitive mnemonics and registers
+- case-sensitive labels and symbols
+- global labels, with `@NAME:` labels marking routine entries for register-care
+  analysis
+- canonical dotted directives such as `.org`, `.equ`, `.db`, `.dw`, and `.ds`
+- exact compatibility spelling for common undotted directive heads such as
+  `ORG`, `EQU`, `DB`, `DW`, and `DS`
+- lowercase, case-sensitive canonical dotted directives; compatibility spellings
+  are handled as directive aliases, not as canonical AZM style
+- colon labels are address labels only; declarations use name-left forms such as
+  `Name .equ`, `Name .enum`, `Name .type`, `Name .union`, and
+  `Name .typealias`
 - textual `.include`
-- directive aliases for importing common assembler spellings
-- register-care analysis, compact AZMDoc comments, and `.asmi` external
-  contracts
-- AST-level `op` extensions
-- enums as constant namespaces
-- `.type` / `.union` layout metadata
+- conditional source inclusion with lowercase `.if`, `.else`, and `.endif`
+- register-care contracts, AZMDoc comments, and `.asmi` external interfaces
+- `op` definitions for structured inline instruction idioms
+- enums and qualified enum constants
+- `.type` / `.union` layout metadata and `Name .typealias TypeExpr` layout aliases
 - compile-time layout constants such as `sizeof(...)`, `offset(...)`, scalar
-  layout sizes, and constant-only layout casts
-- assembler data directives including `.db`, `.dw`, `.ds`, `.cstr`, `.pstr`,
-  and `.istr`
-
-AZM `.asm` and `.z80` source rejects old ZAX high-level features such as
-modules/imports, `func`, formal arguments, locals, typed assignment/storage
-lowering, structured control, generated frames, typed storage blocks, and named
-section blocks. Those inherited paths are removal work, not product
-compatibility.
+  layout sizes, constant-only layout casts, `LSB(...)`, and `MSB(...)`
+- case-sensitive AZM function names with documented spelling, such as
+  `sizeof(...)`, `offset(...)`, `LSB(...)`, and `MSB(...)`
+- data directives including `.db`, `.dw`, `.ds`, `.cstr`, `.pstr`, and `.istr`
+- single quotes are character literals; double quotes are strings
+
+AZM does not implement text macros, local labels, modules/imports, `func`,
+formal arguments, generated stack frames, runtime structured control flow, typed
+assignment lowering, hidden typed load/store lowering, or named section blocks.
+Those features belong to older high-level ZAX-era code paths, not current AZM
+source.
 
 ## Install
 
-Requires Node.js 20+.
+AZM requires Node.js 20 or newer.
 
 ```sh
 npm install -g @jhlagado/azm
-azm path/to/program.z80
+azm path/to/program.asm
 ```
 
-From a checkout, use the local CLI after building:
+From a checkout, build first and then use the local CLI:
 
 ```sh
 npm ci
@@ -49,56 +65,69 @@ npm run build
 npm run azm -- examples/hello.asm
 ```
 
-Output files for each compiled source:
+## Command Line
 
-| Extension  | Contents                  |
-| ---------- | ------------------------- |
-| `.hex`     | Intel HEX                 |
-| `.bin`     | Flat binary               |
-| `.lst`     | Byte dump plus symbols    |
-| `.z80`     | Plain Z80 source emission |
-| `.d8.json` | Debug80 map               |
+Basic use writes the default artifact set next to the source file:
 
-Small input example:
+```sh
+azm program.asm
+```
 
-```asm
-        ORG 0100H
-START:
-        LD A,42
-        RET
+Write a specific primary output:
+
+```sh
+azm --type bin --output build/program.bin program.asm
+azm --type hex --output build/program.hex program.asm
 ```
 
-Compile a binary and listing:
+Add include search paths:
 
 ```sh
-azm --type bin --output build/start.bin start.asm
+azm -I include -I vendor program.asm
 ```
 
-```text
-azm [options] <entry.asm|entry.z80>
-
-Options:
-  -o, --output <file>   Primary output path (must match --type extension)
-  -t, --type <type>     Primary output type: hex|bin (default: hex)
-  -n, --nolist          Suppress .lst
-      --nobin           Suppress .bin
-      --nohex           Suppress .hex
-      --nod8m           Suppress .d8.json
-      --asm80           Emit assembler-valid lowered source (.z80)
-      --source-root <d> Normalize D8 source paths relative to this directory
-      --case-style <m>  Case-style lint mode: off|upper|lower|consistent
-      --rc <m>            Register-care mode: off|audit|warn|error|strict
-      --reg-report       Emit .regcare.txt report
-      --reg-interface    Emit inferred register-care interface (.asmi)
-      --fix             Apply conservative register-care source fixes
-      --contracts       Update source AZM contract blocks in place
-      --accept-out <r:c> Promote inferred output candidate while annotating
-      --interface <file> Load register-care interface contracts
-      --reg-profile <p> Register-care profile: mon3
-      --aliases <file>  Load project directive alias JSON (repeatable)
-  -I, --include <dir>   Add include search path (repeatable)
-  -V, --version         Print version
-  -h, --help            Show help
+Run register-care analysis:
+
+```sh
+azm --rc audit --reg-report program.asm
+azm --rc error --interface monitor.asmi program.asm
+```
+
+See [docs/reference/cli.md](docs/reference/cli.md) for the complete option
+reference.
+
+## Output Artifacts
+
+By default, AZM writes the requested primary output plus useful side artifacts
+using the same base path.
+
+| Extension      | Contents                                      |
+| -------------- | --------------------------------------------- |
+| `.hex`         | Intel HEX                                     |
+| `.bin`         | flat binary                                   |
+| `.d8.json`     | Debug80 map                                   |
+| `.z80`         | ASM80-compatible lowered source when enabled  |
+| `.regcare.txt` | register-care report when enabled             |
+| `.asmi`        | inferred register-care interface when enabled |
+
+The `.z80` output is a generated compatibility artifact for ASM80-style
+workflows and comparison tooling. BIN, HEX, Debug80 maps, and
+register-care reports are the normal production outputs.
+
+## Small Example
+
+```asm
+        .org 0100H
+
+@START:
+        ld      a,42
+        ret
+```
+
+Compile it:
+
+```sh
+azm --type bin --output build/start.bin start.asm
 ```
 
 ## Programmatic API
@@ -121,7 +150,6 @@ const result = await compile(
     sourceRoot: '/abs/path/to/project',
     d8mInputs: {
       hex: '/abs/path/to/project/build/main.hex',
-      listing: '/abs/path/to/project/build/main.lst',
     },
   },
   { formats: defaultFormatWriters },
@@ -130,21 +158,25 @@ const result = await compile(
 console.log(result.diagnostics);
 ```
 
-See [docs/reference/cli.md](docs/reference/cli.md) for the full CLI reference
-and [docs/reference/tooling-api.md](docs/reference/tooling-api.md) for the
-current API notes.
+See [docs/reference/tooling-api.md](docs/reference/tooling-api.md) for current
+API notes.
 
-## Verification
+## Development
 
 Useful local verification lanes:
 
 ```sh
 npm run build
+npm run typecheck
+npm run lint
 npm run test:azm:alpha
 npm run test:azm:corpus
 npm test
 ```
 
+The live source map is maintained in
+[docs/reference/source-overview.md](docs/reference/source-overview.md).
+
 ## License
 
 GPL-3.0-only. See [LICENSE](LICENSE).

package/dist/src/api-compile.d.ts

@@ -20,14 +20,12 @@ export interface CompileNextFunctionOptions {
     readonly outputType?: 'bin' | 'hex';
     readonly sourceRoot?: string;
     readonly d8mInputs?: {
-        readonly listing?: string;
         readonly hex?: string;
         readonly bin?: string;
     };
     readonly emitBin?: boolean;
     readonly emitHex?: boolean;
     readonly emitD8m?: boolean;
-    readonly emitListing?: boolean;
     readonly emitAsm80?: boolean;
     readonly registerCare?: RegisterCareMode;
     readonly emitRegisterReport?: boolean;

package/dist/src/api-compile.js

@@ -152,7 +152,6 @@ export async function compile(entryFile, options = {}, deps = { formats: default
             packageVersion: await readPackageVersion(),
             inputs: {
                 entry: normalizedEntry,
-                ...(options.d8mInputs?.listing !== undefined ? { listing: options.d8mInputs.listing } : {}),
                 ...(options.d8mInputs?.hex !== undefined ? { hex: options.d8mInputs.hex } : {}),
                 ...(options.d8mInputs?.bin !== undefined ? { bin: options.d8mInputs.bin } : {}),
             },
@@ -163,11 +162,6 @@ export async function compile(entryFile, options = {}, deps = { formats: default
         };
         artifacts.push(deps.formats.writeD8m(sidecarMap, symbols, d8mOpts));
     }
-    if (emit.emitListing) {
-        if (deps.formats.writeListing !== undefined) {
-            artifacts.push(deps.formats.writeListing(sidecarMap, symbols));
-        }
-    }
     if (emit.emitAsm80) {
         if (deps.formats.writeAsm80 !== undefined) {
             try {
@@ -183,7 +177,7 @@ export async function compile(entryFile, options = {}, deps = { formats: default
                         line: error.item.span.line,
                         column: error.item.span.column,
                     });
-                    return { diagnostics, artifacts: [] };
+                    return { diagnostics, artifacts };
                 }
                 throw error;
             }
@@ -196,9 +190,8 @@ function compileArtifactDefaults(options) {
     const emitBin = anyPrimary ? (options.emitBin ?? false) : true;
     const emitHex = anyPrimary ? (options.emitHex ?? false) : true;
     const emitD8m = anyPrimary ? (options.emitD8m ?? false) : true;
-    const emitListing = options.emitListing ?? true;
     const emitAsm80 = options.emitAsm80 ?? false;
-    return { emitBin, emitHex, emitD8m, emitListing, emitAsm80 };
+    return { emitBin, emitHex, emitD8m, emitAsm80 };
 }
 function assembledImageToMap(bytes, origin, sourceSegments = []) {
     const map = new Map();

package/dist/src/assembly/address-planning.js

@@ -52,12 +52,17 @@ function buildAddressStateOnce(items, diagnostics, previous, reportUnknown) {
             case 'type':
                 defineLayout(layouts, labels, equates, enumNamesLower, item.name, item.layoutKind, item.fields, item.span, diagnostics);
                 break;
+            case 'type-alias':
+                defineTypeAlias(layouts, labels, equates, enumNamesLower, item.name, item.typeExpr, item.span, diagnostics);
+                break;
             case 'equ':
                 defineEquate(equates, labels, layouts, enumNames, enumNamesLower, item.name, item.expression, item.span, placementAddress(placement), diagnostics, item.stringValue);
                 break;
             case 'enum':
                 defineEnumMembers(equates, labels, layouts, enumNames, enumNamesLower, item.name, item.members, item.span, diagnostics);
                 break;
+            case 'comment':
+                break;
             case 'label':
                 defineLabel(labels, equates, layouts, enumNamesLower, item.name, placementAddress(placement), item.span, diagnostics);
                 break;
@@ -154,7 +159,11 @@ function addressStateSignature(state) {
     return JSON.stringify({
         labels: state.labels,
         equates: [...state.equates].map(([name, record]) => [name, record.currentLocation]),
-        layouts: [...state.layouts].map(([name, record]) => [name, record.kind, record.fields]),
+        layouts: [...state.layouts].map(([name, record]) => [
+            name,
+            record.kind,
+            record.kind === 'alias' ? record.typeExpr : record.fields,
+        ]),
         origin: state.origin,
     });
 }
@@ -178,6 +187,17 @@ function defineLayout(layouts, labels, equates, enumNamesLower, name, layoutKind
     }
     layouts.set(name, { kind: layoutKind, fields, span });
 }
+function defineTypeAlias(layouts, labels, equates, enumNamesLower, name, typeExpr, span, diagnostics) {
+    const lowerName = name.toLowerCase();
+    if (hasCaseInsensitiveMapKey(layouts, lowerName) ||
+        hasCaseInsensitiveKey(labels, lowerName) ||
+        hasCaseInsensitiveMapKey(equates, lowerName) ||
+        enumNamesLower.has(lowerName)) {
+        diagnostics.push(diagnostic(span, `duplicate type name: ${name}`));
+        return;
+    }
+    layouts.set(name, { kind: 'alias', typeExpr, span });
+}
 function defineLabel(labels, equates, layouts, enumNamesLower, name, address, span, diagnostics) {
     if (labels[name] !== undefined ||
         equates.has(name) ||

package/dist/src/assembly/program-emission.js

@@ -117,6 +117,7 @@ export function emitProgramImage(items, addressState, symbols, diagnostics) {
                 }
                 break;
             }
+            case 'comment':
             case 'equ':
             case 'label':
             case 'enum':

package/dist/src/cli/parse-args.d.ts

@@ -11,7 +11,6 @@ export type CliOptions = {
     emitBin: boolean;
     emitHex: boolean;
     emitD8m: boolean;
-    emitListing: boolean;
     emitAsm80: boolean;
     caseStyle: CaseStyleMode;
     registerCare: RegisterCareMode;

package/dist/src/cli/parse-args.js

@@ -7,7 +7,6 @@ export function cliUsage() {
         'Options:',
         '  -o, --output <file>   Primary output path (must match --type extension)',
         '  -t, --type <type>     Primary output type: hex|bin (default: hex)',
-        '  -n, --nolist          Suppress .lst',
         '      --nobin           Suppress .bin',
         '      --nohex           Suppress .hex',
         '      --nod8m           Suppress .d8.json',
@@ -44,7 +43,6 @@ function createDefaultCliState() {
         emitBin: true,
         emitHex: true,
         emitD8m: true,
-        emitListing: true,
         emitAsm80: false,
         caseStyle: 'off',
         registerCare: 'off',
@@ -249,7 +247,6 @@ function finalizeCliOptions(state) {
         emitBin: state.emitBin,
         emitHex: state.emitHex,
         emitD8m: state.emitD8m,
-        emitListing: state.emitListing,
         emitAsm80: state.emitAsm80,
         caseStyle: state.caseStyle,
         registerCare: state.registerCare,
@@ -278,10 +275,6 @@ export function parseCliArgs(argv) {
             continue;
         if (parseOutputTypeArg(arg, argv, indexRef, state))
             continue;
-        if (arg === '-n' || arg === '--nolist') {
-            state.emitListing = false;
-            continue;
-        }
         if (arg === '--nobin') {
             state.emitBin = false;
             continue;

package/dist/src/cli/write-artifacts.js

@@ -52,7 +52,6 @@ export async function writeArtifacts(base, artifacts, outputType) {
     const hexPath = `${base}.hex`;
     const binPath = `${base}.bin`;
     const d8mPath = `${base}.d8.json`;
-    const lstPath = `${base}.lst`;
     const asm80Path = `${base}.z80`;
     const registerCareReportPath = `${base}.regcare.txt`;
     const registerCareInterfacePath = `${base}.asmi`;
@@ -90,13 +89,6 @@ export async function writeArtifacts(base, artifacts, outputType) {
             await writeFile(d8mPath, `${text}\n`, 'utf8');
         })());
     }
-    const lst = byKind.get('lst');
-    if (lst && lst.kind === 'lst') {
-        writes.push((async () => {
-            await ensureDir(lstPath);
-            await writeFile(lstPath, lst.text, 'utf8');
-        })());
-    }
     const asm80 = byKind.get('asm80');
     if (asm80 && asm80.kind === 'asm80') {
         writes.push((async () => {
@@ -141,14 +133,12 @@ export async function writeArtifacts(base, artifacts, outputType) {
 export function buildCompileOptions(parsed, base) {
     const hexPath = `${base}.hex`;
     const binPath = `${base}.bin`;
-    const lstPath = `${base}.lst`;
     return {
         includeDirs: parsed.includeDirs,
         directiveAliasFiles: parsed.directiveAliasFiles,
         emitBin: parsed.emitBin,
         emitHex: parsed.emitHex,
         emitD8m: parsed.emitD8m,
-        emitListing: parsed.emitListing,
         emitAsm80: parsed.emitAsm80,
         caseStyle: parsed.caseStyle,
         registerCare: parsed.registerCare,
@@ -165,7 +155,6 @@ export function buildCompileOptions(parsed, base) {
         ...(parsed.sourceRoot !== undefined
             ? {
                 d8mInputs: {
-                    ...(parsed.emitListing ? { listing: lstPath } : {}),
                     ...(parsed.emitHex ? { hex: hexPath } : {}),
                     ...(parsed.emitBin ? { bin: binPath } : {}),
                 },