@jhlagado/azm 0.2.2 → 0.2.4

package/README.md

@@ -1,53 +1,14 @@
 # AZM
 
-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.
+AZM is the Z80 assembler used by the Debug80 toolchain. It assembles `.asm`
+and `.z80` source into Intel HEX, flat binary and Debug80 map artifacts for
+hardware, emulators and Debug80.
 
-The user manual is the AZM book in the Debug80 documentation site:
+This README is the condensed manual. The full AZM book is on 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`
-- 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, 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
 
 AZM requires Node.js 20 or newer.
@@ -65,8 +26,299 @@ npm run build
 npm run azm -- examples/hello.asm
 ```
 
+## First Program
+
+```asm
+        .org $0100
+
+@Start:
+        ld      a,42
+        ret
+```
+
+Assemble it:
+
+```sh
+azm start.asm
+```
+
+`.org` means origin. It sets the assembly address for the bytes that follow.
+`@Start:` is an address label and also a public routine entry for register-care
+analysis. The Z80 instructions assemble at `$0100`.
+
+## Source Style
+
+AZM source is built from labels, declarations, directives, Z80 instructions,
+data definitions, layout declarations, register-care comments and optional
+inline `op` definitions.
+
+Canonical AZM directives are lowercase and dotted:
+
+```asm
+.org
+.equ
+.db
+.dw
+.ds
+.field
+.type
+.endtype
+.union
+.endunion
+.typealias
+.enum
+.include
+```
+
+Z80 instruction mnemonics and registers are case-insensitive. Labels, constants,
+enum names, type names and AZM function names are case-sensitive.
+
+Use a colon for address labels:
+
+```asm
+Loop:
+        djnz    Loop
+```
+
+Use name-left declarations for constants, enums, records, unions and type
+aliases:
+
+```asm
+COUNT       .equ 8
+Colour      .enum Red, Green, Blue
+SpriteArray .typealias Sprite[16]
+```
+
+Constants often use upper case with underscores. Labels and routine names are
+clearer in PascalCase or camelCase:
+
+```asm
+SCREEN_WIDTH .equ 32
+
+DrawSprite:
+        ret
+```
+
+## Literals
+
+AZM accepts the usual Z80 numeric forms:
+
+```asm
+$FF         ; hexadecimal
+0FFH        ; hexadecimal with trailing H
+%10101010   ; binary
+42          ; decimal
+'A'         ; character literal
+"HELLO"     ; string literal
+```
+
+A trailing `H` hexadecimal literal must start with a decimal digit, so `0FFH`
+is hexadecimal 255. Double quotes are used for strings. Single quotes are used
+for character literals.
+
+`$` also names the current assembly address when it appears as a bare
+expression term:
+
+```asm
+TableStart:
+        .db 1,2,3,4
+TableEnd:
+TABLE_SIZE .equ $ - TableStart
+```
+
+## Data and Storage
+
+`.db` emits bytes. `.dw` emits 16-bit words in Z80 little-endian order, with the
+least significant byte stored first. `.ds` reserves storage.
+
+```asm
+Message:
+        .db "READY",0
+
+Vector:
+        .dw Handler
+
+Buffer:
+        .ds 32
+```
+
+String directives encode common string layouts:
+
+```asm
+NameC:
+        .cstr "READY"     ; C string, terminated by zero
+
+NameP:
+        .pstr "READY"     ; Pascal string, length byte first
+
+NameI:
+        .istr "READY"     ; high bit set on final character
+```
+
+## Layout Types
+
+AZM has assembler-time layout declarations for records, unions and arrays. They
+describe byte layout so the assembler can calculate sizes, field offsets and
+structured addresses.
+
+Start with explicit fields:
+
+```asm
+Sprite .type
+x      .field byte
+y      .field byte
+tile   .field byte
+flags  .field byte
+       .endtype
+```
+
+Each `.field` receives a layout type expression. `byte` allocates one byte and
+`word` allocates two bytes. Arrays use square brackets:
+
+```asm
+Palette .type
+entries .field byte[16]
+        .endtype
+```
+
+`sizeof` gives the byte size of a type expression. `offset` gives the byte
+offset of a field path:
+
+```asm
+SPRITE_SIZE .equ sizeof(Sprite)
+FLAGS_OFF   .equ offset(Sprite, flags)
+```
+
+Type aliases give a reusable name to a layout expression:
+
+```asm
+SpriteArray .typealias Sprite[16]
+
+Sprites:
+        .ds SpriteArray
+
+SPRITES_SIZE .equ sizeof(SpriteArray)
+```
+
+A type alias is transparent. `SpriteArray` means `Sprite[16]` anywhere a layout
+type expression is valid.
+
+Layout casts apply a type to an address expression so fields can be addressed by
+name:
+
+```asm
+        ld      hl,<SpriteArray>Sprites[3].flags
+        ld      a,(<SpriteArray>Sprites[3].tile)
+```
+
+The cast performs assembler-time address calculation. Runtime indexing still
+uses Z80 instructions.
+
+## Enums
+
+Enums are grouped constants. Members are qualified by the enum name:
+
+```asm
+Colour .enum Red, Green, Blue
+
+        .db Colour.Red
+        .db Colour.Green
+        .db Colour.Blue
+```
+
+In this example `Colour.Red` is `0`, `Colour.Green` is `1` and `Colour.Blue` is
+`2`.
+
+## Includes
+
+`.include` inserts another source file at the current point:
+
+```asm
+        .include "hardware.asm"
+        .include "sprites.asm"
+```
+
+Include search paths are added with `-I`:
+
+```sh
+azm -I include -I vendor program.asm
+```
+
+Included source contributes labels, constants, enums, types, ops and routines to
+the same assembly.
+
+## Register Care
+
+Register care checks whether subroutines preserve the register values that their
+callers still need. It is designed to catch register collisions, a common source
+of assembly bugs.
+
+Routine entry labels start with `@`:
+
+```asm
+;! in A,HL
+;! out carry
+;! clobbers B
+@CheckTile:
+        ld      b,(hl)
+        cp      b
+        ret
+```
+
+The label is written as `@CheckTile:` at the routine entry. Calls use the public
+name:
+
+```asm
+        call    CheckTile
+```
+
+AZMDoc register-care comments use `;!` and may record inputs, outputs,
+clobbered registers and preserved registers. `clobbers B` means the routine may
+change `B`. `preserves B` means the value that enters in `B` is still present
+when the routine returns.
+
+Run the analysis with:
+
+```sh
+azm --rc audit --reg-report program.asm
+azm --rc error --interface monitor.asmi program.asm
+```
+
+The main modes are `audit`, `warn`, `error` and `strict`. AZM can also emit
+register-care reports and `.asmi` interface files for externally assembled
+routines.
+
+## Ops and Aliases
+
+`op` definitions name short inline instruction idioms:
+
+```asm
+op clear_a()
+        xor     a
+end
+
+        clear_a
+```
+
+The operation expands inline at the use site.
+
+AZM also has directive aliases for common legacy source. Native AZM style uses
+lowercase dotted directives such as `.org`, `.equ`, `.db`, `.dw` and `.ds`.
+Legacy source can use familiar undotted directive heads such as `ORG`, `EQU`,
+`DB`, `DW` and `DS`.
+
 ## Command Line
 
+The command form is:
+
+```sh
+azm [options] <entry.asm|entry.z80>
+```
+
+The entry file is the final argument. Source entries use `.asm` or `.z80`.
+External register-care interfaces use `.asmi` and are loaded with
+`--interface`.
+
 Basic use writes the default artifact set next to the source file:
 
 ```sh
@@ -86,13 +338,65 @@ Add include search paths:
 azm -I include -I vendor program.asm
 ```
 
+Normalize Debug80 map source paths against the project root:
+
+```sh
+azm --source-root . --output build/program.hex src/program.asm
+```
+
+Load project directive aliases:
+
+```sh
+azm --aliases azm.aliases.json program.asm
+```
+
+Suppress selected default artifacts:
+
+```sh
+azm --nod8m program.asm
+azm --nobin program.asm
+azm --nohex program.asm
+```
+
+Generate ASM80-compatible lowered source:
+
+```sh
+azm --asm80 program.asm
+```
+
 Run register-care analysis:
 
 ```sh
 azm --rc audit --reg-report program.asm
 azm --rc error --interface monitor.asmi program.asm
+azm --contracts --rc audit program.asm
 ```
 
+The main switches are:
+
+| Option                                        | Meaning                                                       |
+| --------------------------------------------- | ------------------------------------------------------------- |
+| `-o, --output <file>`                         | Primary output path. The extension matches `--type`.          |
+| `-t, --type <hex\|bin>`                       | Primary output type. Default: `hex`.                          |
+| `--nobin`                                     | Skip `.bin` output.                                           |
+| `--nohex`                                     | Skip `.hex` output.                                           |
+| `--nod8m`                                     | Skip `.d8.json` output.                                       |
+| `--asm80`                                     | Write lowered assembler source as `.z80`.                     |
+| `--source-root <dir>`                         | Emit project-relative source paths in `.d8.json`.             |
+| `--case-style <mode>`                         | Lint mnemonic, register and op-head case style.               |
+| `--rc, --register-care <mode>`                | Register-care mode: `off`, `audit`, `warn`, `error`, `strict`. |
+| `--reg-report, --emit-register-report`        | Write `.regcare.txt`.                                         |
+| `--reg-interface, --emit-register-interface`  | Write inferred `.asmi` interface metadata.                    |
+| `--contracts, --annotate-register-contracts`  | Update AZMDoc contract comments in source.                    |
+| `--fix`                                       | Apply conservative register-care source fixes.                |
+| `--accept-out <routine:carrier>`              | Promote an inferred output candidate while annotating.        |
+| `--interface <file>`                          | Load external register-care contracts from `.asmi`.           |
+| `--reg-profile, --register-profile <profile>` | Register-care profile. Currently `mon3`.                      |
+| `--aliases <file>`                            | Load project directive alias JSON.                            |
+| `-I, --include <dir>`                         | Add an include search path.                                   |
+| `-V, --version`                               | Print package version.                                        |
+| `-h, --help`                                  | Print CLI help.                                               |
+
 See [docs/reference/cli.md](docs/reference/cli.md) for the complete option
 reference.
 
@@ -108,37 +412,60 @@ using the same base path.
 | `.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 |
+| `.asmi`        | 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
+## Programmatic API
 
-```asm
-        .org 0100H
+`@jhlagado/azm` exposes stable Node entry points for tools. Import from these
+package paths:
 
-@START:
-        ld      a,42
-        ret
-```
+- `@jhlagado/azm`
+- `@jhlagado/azm/tooling`
+- `@jhlagado/azm/compile`
 
-Compile it:
+Install the package:
 
 ```sh
-azm --type bin --output build/start.bin start.asm
+npm install @jhlagado/azm
 ```
 
-## Programmatic API
+Use `@jhlagado/azm/tooling` when an editor, linter or debugger integration
+needs parsing, diagnostics, symbols, semantic checks or register-care facts in
+memory:
 
-`@jhlagado/azm` exposes Node entry points for tools:
+```ts
+import {
+  analyzeProgram,
+  analyzeRegisterCareForTools,
+  loadProgram,
+} from '@jhlagado/azm/tooling';
+
+const loaded = await loadProgram({
+  entryFile: '/abs/path/to/main.asm',
+  includeDirs: ['/abs/path/to/includes'],
+});
+
+if (loaded.loadedProgram) {
+  const analysis = analyzeProgram(loaded.loadedProgram, {
+    caseStyle: 'consistent',
+    requireMain: false,
+  });
+
+  const registerCare = analyzeRegisterCareForTools(loaded.loadedProgram, {
+    mode: 'audit',
+    registerCareProfile: 'mon3',
+  });
+
+  console.log(analysis.diagnostics);
+  console.log(registerCare.candidateDiagnostics);
+}
+```
 
-- `@jhlagado/azm`
-- `@jhlagado/azm/tooling`
-- `@jhlagado/azm/compile`
+`loadProgram()` also accepts `preloadedText` for an unsaved editor buffer and
+`signal` for cancellation.
 
-Minimal compile example:
+Use `@jhlagado/azm/compile` when a tool needs assembled bytes, Intel HEX,
+Debug80 map data or other artifacts in memory:
 
 ```ts
 import { compile, defaultFormatWriters } from '@jhlagado/azm/compile';
@@ -146,18 +473,50 @@ import { compile, defaultFormatWriters } from '@jhlagado/azm/compile';
 const result = await compile(
   '/abs/path/to/main.asm',
   {
+    includeDirs: ['/abs/path/to/includes'],
     outputType: 'hex',
+    emitBin: true,
+    emitHex: true,
+    emitD8m: true,
     sourceRoot: '/abs/path/to/project',
     d8mInputs: {
       hex: '/abs/path/to/project/build/main.hex',
+      bin: '/abs/path/to/project/build/main.bin',
     },
+    registerCare: 'audit',
+    registerCareInterfaces: ['/abs/path/to/monitor.asmi'],
   },
   { formats: defaultFormatWriters },
 );
 
 console.log(result.diagnostics);
+
+const d8m = result.artifacts.find((artifact) => artifact.kind === 'd8m');
+const binary = result.artifacts.find((artifact) => artifact.kind === 'bin');
+console.log(d8m, binary);
 ```
 
+The compile API returns artifacts in memory. The CLI uses the same writers to
+write those artifacts to disk.
+
+Common programmatic options include:
+
+| Option                       | Use                                                       |
+| ---------------------------- | --------------------------------------------------------- |
+| `includeDirs`                | Include search paths, like repeated `-I`.                 |
+| `directiveAliasFiles`        | Project directive alias JSON files.                       |
+| `sourceRoot`                 | Stable project-relative paths in Debug80 maps.            |
+| `d8mInputs`                  | Intended artifact paths recorded in Debug80 map metadata. |
+| `outputType`                 | Primary output type, `hex` or `bin`.                      |
+| `emitBin`, `emitHex`, `emitD8m` | Select in-memory artifact kinds.                       |
+| `emitAsm80`                  | Request lowered `.z80` artifact.                          |
+| `registerCare`               | Register-care mode.                                       |
+| `registerCareInterfaces`     | External `.asmi` contract files.                          |
+
+Public tooling types include `Diagnostic`, `LoadedProgram`,
+`AnalyzeProgramResult`, `LoadProgramResult`, `RegisterCareCandidateDiagnostic`
+and the Debug80 map artifact types `D8mArtifact`, `D8mJson` and `D8mSymbol`.
+
 See [docs/reference/tooling-api.md](docs/reference/tooling-api.md) for current
 API notes.
 

package/dist/src/core/compile.js

@@ -26,19 +26,7 @@ export function parseNextSourceItems(lines, options = {}) {
         if (afterTopLevelEnd && !isPostEndParseAllowed(line.text)) {
             continue;
         }
-        const colonLayoutHeader = /^([A-Za-z_][A-Za-z0-9_]*):\s*\.(type|union)\s*$/.exec(stripLineComment(line.text).trim());
-        if (colonLayoutHeader) {
-            const directive = colonLayoutHeader[2] ?? 'type';
-            diagnostics.push(parseDiagnostic(line, `Use "${colonLayoutHeader[1] ?? ''} .${directive}" for layouts; colon labels mark addresses.`));
-            const endDirective = directive === 'union' ? '.endunion' : '.endtype';
-            for (index += 1; index < pendingLines.length; index += 1) {
-                if (stripLineComment(pendingLines[index].text).trim() === endDirective) {
-                    break;
-                }
-            }
-            continue;
-        }
-        const nameLeftTypeAlias = /^([A-Za-z_][A-Za-z0-9_]*)\s+\.typealias\s+(.+)$/.exec(stripLineComment(line.text).trim());
+        const nameLeftTypeAlias = /^([A-Za-z_][A-Za-z0-9_]*)(?::\s*|\s+)\.typealias\s+(.+)$/.exec(stripLineComment(line.text).trim());
         if (nameLeftTypeAlias) {
             const typeExprText = nameLeftTypeAlias[2] ?? '';
             const typeExpr = parseTypeExpr(typeExprText);
@@ -60,7 +48,7 @@ export function parseNextSourceItems(lines, options = {}) {
             diagnostics.push(parseDiagnostic(line, `Use "${typeAlias[1] ?? ''} .typealias ..." for type aliases.`));
             continue;
         }
-        const nameLeftLayoutHeader = /^([A-Za-z_][A-Za-z0-9_]*)\s+\.(type|union)\s*$/.exec(stripLineComment(line.text).trim());
+        const nameLeftLayoutHeader = /^([A-Za-z_][A-Za-z0-9_]*)(?::\s*|\s+)\.(type|union)\s*$/.exec(stripLineComment(line.text).trim());
         const prefixLayoutHeader = /^\.(type|union)\s+([A-Za-z_][A-Za-z0-9_]*)\s*$/.exec(stripLineComment(line.text).trim());
         if (prefixLayoutHeader) {
             const directive = prefixLayoutHeader[1] ?? 'type';
@@ -202,11 +190,7 @@ function evaluateConditionalExpression(line, expressionText, equates, locationDe
 }
 function recordConditionalEquate(line, equates, locationDependentEquates, directiveAliasPolicy) {
     const text = normalizeDirectiveAlias(stripLineComment(line.text), directiveAliasPolicy).trim();
-    const statement = /^(@?[A-Za-z_.$?][A-Za-z0-9_.$?]*):\s*(.+)$/.exec(text);
-    if (statement && /^\.equ\b/.test(statement[2] ?? '')) {
-        return;
-    }
-    const equ = /^([A-Za-z_.$?][A-Za-z0-9_.$?]*)\s+\.equ\s+(.+)$/.exec(text);
+    const equ = /^([A-Za-z_.$?][A-Za-z0-9_.$?]*)(?::\s*|\s+)\.equ\s+(.+)$/.exec(text);
     if (!equ) {
         return;
     }

package/dist/src/register-care/analyze.js

@@ -1,7 +1,7 @@
 import { buildRegisterCareProgramModel } from './programModel.js';
 import { buildRoutineContracts, parseSmartComments } from './smartComments.js';
 import { renderRegisterCareInterface, renderRegisterCareReport } from './report.js';
-import { autoFixableCandidateKeys } from './fix.js';
+import { autoFixableCandidateKeys, findExpectOutFixesForCandidates } from './fix.js';
 import { findCallerOutputCandidateObservations, findRegisterCareConflicts, } from './liveness.js';
 import { buildAnnotations } from './annotations.js';
 import { buildOutputCandidateFixability, buildProfileSummaries, buildProfileSummaryLookup, buildSummaries, buildSummaryByName, outputCandidateKey, routineNames, unknownBoundaryDiagnostics, unknownCallList, withAcceptedOutputs, } from './summaries.js';
@@ -27,8 +27,7 @@ export function analyzeRegisterCare(loaded, options) {
     const profileSummaries = buildProfileSummaries(options.registerCareProfile);
     let summaries = buildSummaries(program.routines, contractMap, profileSummaries);
     summaries = withAcceptedOutputs(summaries, options.acceptedOutputCandidates);
-    const allSummaries = [...summaries, ...profileSummaries];
-    const summariesByName = buildSummaryByName(program.routines, summaries, profileSummaries);
+    let summariesByName = buildSummaryByName(program.routines, summaries, profileSummaries);
     const knownRoutines = new Set(routineNames(program.routines));
     for (const [name] of contractMap) {
         knownRoutines.add(name);
@@ -40,14 +39,18 @@ export function analyzeRegisterCare(loaded, options) {
     const shouldBuildOutputCandidates = options.mode !== 'off' ||
         options.emitAnnotations === true ||
         options.fixRegisterContracts === true;
-    const analyzed = shouldBuildOutputCandidates
-        ? {
-            conflicts: program.routines.flatMap((routine) => findRegisterCareConflicts(routine, summariesByName, smartComments)),
-            outputCandidates: findCallerOutputCandidateObservations(program.routines, summariesByName),
-        }
-        : { conflicts: [], outputCandidates: [] };
-    const conflicts = analyzed.conflicts;
-    const outputCandidates = analyzed.outputCandidates;
+    const outputCandidates = shouldBuildOutputCandidates
+        ? findCallerOutputCandidateObservations(program.routines, summariesByName)
+        : [];
+    const autoAcceptedOutputs = autoAcceptedOutputCandidateMap(program.routines, outputCandidates, loaded.sourceTexts);
+    if (autoAcceptedOutputs.size > 0) {
+        summaries = withAcceptedOutputs(summaries, autoAcceptedOutputs);
+        summariesByName = buildSummaryByName(program.routines, summaries, profileSummaries);
+    }
+    const allSummaries = [...summaries, ...profileSummaries];
+    const conflicts = shouldBuildOutputCandidates
+        ? program.routines.flatMap((routine) => findRegisterCareConflicts(routine, summariesByName, smartComments))
+        : [];
     const outputCandidateFixability = buildOutputCandidateFixability(program.routines, outputCandidates, autoFixableCandidateKeys);
     const outputCandidatesWithFixability = outputCandidates.map((candidate) => {
         const autoFixable = outputCandidateFixability.get(outputCandidateKey(candidate.file, candidate.line, candidate.column)) ?? false;
@@ -113,3 +116,51 @@ export function analyzeRegisterCare(loaded, options) {
         ...(reportModel.unknownCalls.length > 0 ? { unknownCalls: reportModel.unknownCalls } : {}),
     };
 }
+function autoAcceptedOutputCandidateMap(routines, outputCandidates, sourceTexts) {
+    const out = new Map();
+    const sourceMaybeOut = sourceMaybeOutByRoutine(routines, sourceTexts);
+    for (const fix of findExpectOutFixesForCandidates([...routines], [...outputCandidates])) {
+        const declaredMaybeOut = sourceMaybeOut.get(fix.routine) ?? [];
+        const eligibleCarriers = fix.carriers.filter((carrier) => declaredMaybeOut.includes(carrier));
+        if (eligibleCarriers.length === 0)
+            continue;
+        const carriers = out.get(fix.routine) ?? [];
+        for (const carrier of eligibleCarriers) {
+            if (!carriers.includes(carrier))
+                carriers.push(carrier);
+        }
+        out.set(fix.routine, carriers);
+    }
+    return out;
+}
+function sourceMaybeOutByRoutine(routines, sourceTexts) {
+    const out = new Map();
+    for (const routine of routines) {
+        const source = sourceTexts.get(routine.span.file);
+        if (source === undefined)
+            continue;
+        const lines = source.split(/\r?\n/);
+        const units = [];
+        for (let index = routine.span.start.line - 2; index >= 0; index -= 1) {
+            const text = lines[index] ?? '';
+            if (!/^\s*;/.test(text))
+                break;
+            const match = /^\s*;\s*!\s*maybe-out\s+(.+)$/i.exec(text);
+            if (!match)
+                continue;
+            for (const token of match[1].split(',')) {
+                const unit = token.trim();
+                if (unit.length > 0 && !units.includes(unit))
+                    units.push(unit);
+            }
+        }
+        if (units.length === 0)
+            continue;
+        out.set(routine.name, units);
+        for (const label of routine.labels)
+            out.set(label, units);
+        for (const label of routine.entryLabels)
+            out.set(label, units);
+    }
+    return out;
+}

package/dist/src/register-care/fix.js

@@ -11,6 +11,50 @@ function isUnconditionalDirectCall(item) {
         effect.control.target !== undefined &&
         !effect.control.conditional);
 }
+function operandReadsUnit(operand, unit) {
+    switch (operand.kind) {
+        case 'reg8':
+            return operand.register?.toLowerCase() === unit.toLowerCase();
+        case 'reg16':
+        case 'reg-index16': {
+            return operand.register !== undefined && registerNameReadsUnit(operand.register, unit);
+        }
+        case 'reg-half-index':
+            return operand.register?.toLowerCase() === unit.toLowerCase();
+        case 'reg-indirect':
+        case 'indexed':
+            return operand.register !== undefined && registerNameReadsUnit(operand.register, unit);
+        default:
+            return false;
+    }
+}
+function registerNameReadsUnit(registerName, unit) {
+    const register = registerName.toLowerCase();
+    return ((register === 'bc' && (unit === 'B' || unit === 'C')) ||
+        (register === 'de' && (unit === 'D' || unit === 'E')) ||
+        (register === 'hl' && (unit === 'H' || unit === 'L')) ||
+        (register === 'ix' && (unit === 'IXH' || unit === 'IXL')) ||
+        (register === 'iy' && (unit === 'IYH' || unit === 'IYL')) ||
+        (register === 'sp' && (unit === 'SPH' || unit === 'SPL')) ||
+        (register === 'af' && unit === 'A'));
+}
+function instructionDataReadsUnit(instruction, unit) {
+    switch (instruction.mnemonic) {
+        case 'ld':
+            return operandReadsUnit(instruction.source, unit);
+        case 'push':
+            return registerNameReadsUnit(instruction.register, unit);
+        case 'out':
+            if (instruction.source.kind === 'zero')
+                return false;
+            return operandReadsUnit(instruction.source, unit);
+        case 'inc':
+        case 'dec':
+            return operandReadsUnit(instruction.operand, unit);
+        default:
+            return false;
+    }
+}
 function continuationReads(routine, callIndex, carriers) {
     const labels = labelIndex(routine);
     const confirmed = new Set();
@@ -37,7 +81,7 @@ function continuationReads(routine, callIndex, carriers) {
         const writes = new Set(effect.writes);
         const remaining = [];
         for (const unit of pending) {
-            if (reads.has(unit)) {
+            if (reads.has(unit) && instructionDataReadsUnit(item.instruction, unit)) {
                 confirmed.add(unit);
                 continue;
             }

package/dist/src/register-care/liveness.js

@@ -88,10 +88,29 @@ function transferLiveBefore(item, effect, boundary, summary, liveAfter, hints) {
         for (const unit of effect.writes)
             live.delete(unit);
     }
-    for (const unit of effect.reads)
+    for (const unit of semanticReadsForLiveness(item, effect, liveAfter))
         live.add(unit);
     return live;
 }
+function semanticReadsForLiveness(item, effect, liveAfter) {
+    if (item.instruction.mnemonic === 'or' &&
+        item.instruction.source.kind === 'reg8' &&
+        item.instruction.source.register === 'a' &&
+        !liveAfter.has('zero') &&
+        !liveAfter.has('sign') &&
+        !liveAfter.has('parity')) {
+        return effect.reads.filter((unit) => unit !== 'A');
+    }
+    if (item.instruction.mnemonic === 'and' &&
+        item.instruction.source.kind === 'reg8' &&
+        item.instruction.source.register === 'a' &&
+        !liveAfter.has('zero') &&
+        !liveAfter.has('sign') &&
+        !liveAfter.has('parity')) {
+        return effect.reads.filter((unit) => unit !== 'A');
+    }
+    return effect.reads;
+}
 function liveSetsForRoutine(routine, summaries, hints = []) {
     const labels = labelIndex(routine);
     const effects = routine.instructions.map((item) => getZ80InstructionEffect(item.instruction));

package/dist/src/syntax/parse-line.js

@@ -14,9 +14,9 @@ export function parseLogicalLine(line, options = {}) {
         const labelName = normalizeEntryLabelName(rawLabel);
         const isEntry = rawLabel.startsWith('@');
         const statementText = labelWithStatement[2] ?? '';
-        const invalidDeclaration = parseColonDeclarationError(labelName, statementText);
-        if (invalidDeclaration) {
-            return { items: [], diagnostics: [parseError(line, invalidDeclaration)] };
+        const declaration = parseColonDeclaration(line, labelName, statementText, span);
+        if (declaration) {
+            return withLineComment(line, declaration);
         }
         const parsedStatement = parseCanonicalStatement(line, statementText, span);
         return withLineComment(line, {
@@ -254,21 +254,14 @@ function parseCanonicalStatement(line, text, span) {
     }
     return { items: [], diagnostics: [parseError(line, `unsupported source line: ${text}`)] };
 }
-function parseColonDeclarationError(name, statementText) {
-    if (/^\.equ\b/.test(statementText)) {
-        return `Use "${name} .equ ..." for constants; colon labels mark addresses.`;
-    }
-    if (/^\.enum\b/.test(statementText)) {
-        return `Use "${name} .enum ..." for enums; colon labels mark addresses.`;
-    }
-    if (/^\.typealias\b/.test(statementText)) {
-        return `Use "${name} .typealias ..." for type aliases; colon labels mark addresses.`;
-    }
-    if (/^\.type\b/.test(statementText)) {
-        return `Use "${name} .type" for layouts; colon labels mark addresses.`;
+function parseColonDeclaration(line, name, statementText, span) {
+    const equ = /^\.equ\s+(.+)$/.exec(statementText);
+    if (equ) {
+        return parseEquItem(line, name, equ[1] ?? '', span);
     }
-    if (/^\.union\b/.test(statementText)) {
-        return `Use "${name} .union" for layouts; colon labels mark addresses.`;
+    const enumDecl = /^\.enum\s+(.+)$/.exec(statementText);
+    if (enumDecl) {
+        return parseEnumItem(line, name, enumDecl[1] ?? '', span);
     }
     return undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhlagado/azm",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "AZM assembler for the Z80 family (Node.js CLI)",
   "license": "GPL-3.0-only",
   "engines": {