@jhlagado/azm 0.2.8 → 0.2.10

package/dist/src/register-contracts/report.js

@@ -2,6 +2,7 @@ function list(units) {
     return units.length === 0 ? '-' : units.join(',');
 }
 const FLAG_UNITS = new Set(['carry', 'zero', 'sign', 'parity', 'halfCarry']);
+const FLAG_UNIT_LIST = ['carry', 'zero', 'sign', 'parity', 'halfCarry'];
 const CONTRACT_CARRIER_PAIRS = [
     { label: 'BC', hi: 'B', lo: 'C' },
     { label: 'DE', hi: 'D', lo: 'E' },
@@ -32,6 +33,14 @@ export function contractCarrierList(units) {
     }
     return parts.length === 0 ? '-' : parts.join(',');
 }
+function sourceContractCarrierList(units) {
+    const unique = [...new Set(units)];
+    const hasAllFlags = FLAG_UNIT_LIST.every((unit) => unique.includes(unit));
+    const compacted = hasAllFlags
+        ? unique.filter((unit) => !FLAG_UNITS.has(unit)).concat('F')
+        : unique;
+    return contractCarrierList(compacted);
+}
 function relationOutputUnits(relations) {
     return relations.flatMap((rel) => rel.out);
 }
@@ -59,9 +68,9 @@ function sourceContractEntries(summary) {
     const outputUnits = relationOutputUnits(summary.valueRelations);
     if (outputUnits.length > 0)
         out.push({ keyword: 'out', carriers: contractCarrierList(outputUnits) });
-    const clobbers = summary.mayWrite.filter((unit) => !relationOut.has(unit) && !FLAG_UNITS.has(unit));
+    const clobbers = summary.mayWrite.filter((unit) => !relationOut.has(unit));
     if (clobbers.length > 0)
-        out.push({ keyword: 'clobbers', carriers: contractCarrierList(clobbers) });
+        out.push({ keyword: 'clobbers', carriers: sourceContractCarrierList(clobbers) });
     return out;
 }
 function stackStatus(summary) {
@@ -152,5 +161,8 @@ export function renderRegisterContractsInterface(summaries) {
     return `${lines.join('\n')}\n`;
 }
 export function renderRegisterContractsSourceBlock(summary) {
-    return sourceContractEntries(summary).map((entry) => `;!      ${entry.keyword.padEnd(10)}${entry.carriers}`);
+    const entries = sourceContractEntries(summary);
+    if (entries.length === 0)
+        return [];
+    return [`;! ${entries.map((entry) => `${entry.keyword} ${entry.carriers}`).join('; ')}`];
 }

package/dist/src/register-contracts/smartCommentParsing.d.ts

@@ -1,3 +1,4 @@
 import type { SmartComment } from './types.js';
 export declare function parseSmartCommentLine(line: string): SmartComment | undefined;
+export declare function parseSmartCommentLines(line: string): SmartComment[];
 export declare function isCompactSourceCommentLine(line: string): boolean;

package/dist/src/register-contracts/smartCommentParsing.js

@@ -1,5 +1,6 @@
 import { expandCarrierList } from './carriers.js';
 const COMPACT_SOURCE_TAG_RE = /^;?\s*!\s*(in|out|clobbers|preserves)(?:\s+(.+))?$/i;
+const COMPACT_SOURCE_CLAUSE_RE = /^(in|out|clobbers|preserves)(?:\s+(.+))?$/i;
 const COMPACT_SOURCE_LINE_RE = /^\s*;\s*!\s*(?:in|out|maybe-out|clobbers|preserves)(?:\s|$)/i;
 const CARRIER_RE = /^\{([^}]+)\}(?:\s+(.+))?$/;
 const CONTRACT_COMMENT_KINDS = new Set(['in', 'out', 'clobbers', 'preserves']);
@@ -35,17 +36,51 @@ function parseCarrierPayload(rest) {
     return { carriers, ...(name ? { name } : {}) };
 }
 export function parseSmartCommentLine(line) {
+    return parseSmartCommentLines(line)[0];
+}
+export function parseSmartCommentLines(line) {
     const trimmed = line.trim();
     const expectOut = parseExpectOutComment(trimmed);
     if (expectOut !== undefined)
-        return expectOut;
+        return [expectOut];
+    const semicolonSeparated = parseSemicolonSeparatedSourceComments(trimmed);
+    if (semicolonSeparated.length > 0)
+        return semicolonSeparated;
     const match = COMPACT_SOURCE_TAG_RE.exec(trimmed);
-    if (!match)
-        return undefined;
-    const tag = match[1].toLowerCase();
-    if (!CONTRACT_COMMENT_KINDS.has(tag))
-        return undefined;
-    return parseCarrierComment(tag, match[2]?.trim());
+    if (match) {
+        const tag = match[1].toLowerCase();
+        if (!CONTRACT_COMMENT_KINDS.has(tag))
+            return [];
+        const comment = parseCarrierComment(tag, match[2]?.trim());
+        return comment === undefined ? [] : [comment];
+    }
+    return [];
+}
+function parseSemicolonSeparatedSourceComments(trimmed) {
+    const sourcePrefix = /^;?\s*!\s*/.exec(trimmed);
+    if (sourcePrefix === null)
+        return [];
+    const content = trimmed.slice(sourcePrefix[0].length);
+    const parts = content
+        .split(';')
+        .map((part) => part.trim())
+        .filter(Boolean);
+    if (parts.length <= 1)
+        return [];
+    const comments = [];
+    for (const part of parts) {
+        const match = COMPACT_SOURCE_CLAUSE_RE.exec(part);
+        if (!match)
+            return [];
+        const tag = match[1].toLowerCase();
+        if (!CONTRACT_COMMENT_KINDS.has(tag))
+            return [];
+        const comment = parseCarrierComment(tag, match[2]?.trim());
+        if (comment === undefined)
+            return [];
+        comments.push(comment);
+    }
+    return comments;
 }
 function parseExpectOutComment(trimmed) {
     const expectOut = /^;?\s*expects\s+out\s+(.+)$/i.exec(trimmed);

package/dist/src/register-contracts/smartComments.d.ts

@@ -1,5 +1,5 @@
 import type { LocatedSmartComment, RegisterContractsRoutine, RoutineContract } from './types.js';
-import { parseSmartCommentLine } from './smartCommentParsing.js';
-export { parseSmartCommentLine };
+import { parseSmartCommentLine, parseSmartCommentLines } from './smartCommentParsing.js';
+export { parseSmartCommentLine, parseSmartCommentLines };
 export declare function parseSmartComments(sourceLineComments: ReadonlyMap<string, ReadonlyMap<number, string>>): LocatedSmartComment[];
 export declare function buildRoutineContracts(comments: LocatedSmartComment[], routines?: RegisterContractsRoutine[], sourceTexts?: ReadonlyMap<string, string>): Map<string, RoutineContract>;

package/dist/src/register-contracts/smartComments.js

@@ -1,12 +1,11 @@
 import { collectPrecedingCommentBlock } from './smartCommentBlocks.js';
-import { parseSmartCommentLine } from './smartCommentParsing.js';
-export { parseSmartCommentLine };
+import { parseSmartCommentLine, parseSmartCommentLines } from './smartCommentParsing.js';
+export { parseSmartCommentLine, parseSmartCommentLines };
 export function parseSmartComments(sourceLineComments) {
     const out = [];
     for (const [file, comments] of sourceLineComments) {
         for (const [line, text] of comments) {
-            const parsed = parseSmartCommentLine(`;${text}`);
-            if (parsed) {
+            for (const parsed of parseSmartCommentLines(`;${text}`)) {
                 out.push({ file, line, comment: parsed });
             }
         }

package/dist/src/source/logical-lines.d.ts

@@ -3,5 +3,8 @@ export interface LogicalLine {
     readonly sourceName: string;
     readonly line: number;
     readonly text: string;
+    readonly sourceUnit?: string;
+    readonly sourceRelation?: SourceRelation;
 }
+export type SourceRelation = 'entry' | 'include' | 'import';
 export declare function scanLogicalLines(source: SourceFile): LogicalLine[];

package/dist/src/source/source-span.d.ts

@@ -2,4 +2,6 @@ export interface SourceSpan {
     readonly sourceName: string;
     readonly line: number;
     readonly column: number;
+    readonly sourceUnit?: string;
+    readonly sourceRelation?: 'entry' | 'include' | 'import';
 }

package/dist/src/syntax/parse-directive-statement.d.ts

@@ -1,14 +1,9 @@
 import type { LogicalLine } from '../source/logical-lines.js';
+import type { SourceSpan } from '../source/source-span.js';
 import type { ParseLineResult } from './parse-line.js';
-type SourceSpan = {
-    readonly sourceName: string;
-    readonly line: number;
-    readonly column: number;
-};
 export declare function parseDirectiveStatement(line: LogicalLine, text: string, span: SourceSpan): ParseLineResult | undefined;
 export declare function parseColonDeclaration(line: LogicalLine, name: string, statementText: string, span: {
     readonly sourceName: string;
     readonly line: number;
     readonly column: number;
 }): ParseLineResult | undefined;
-export {};

package/dist/src/syntax/parse-directive-statement.js

@@ -144,7 +144,9 @@ function parseDsDirective(line, valueText, span) {
     };
 }
 function validateDsValueList(line, parts) {
-    return parts.length < 1 || parts.length > 2 ? parseError(line, `invalid .ds value list`) : undefined;
+    return parts.length < 1 || parts.length > 2
+        ? parseError(line, `invalid .ds value list`)
+        : undefined;
 }
 function parseDsSize(line, sizeText) {
     const size = parseTypeSizeExpression(sizeText) ?? parseExpression(sizeText);

package/dist/src/syntax/parse-layout-declarations.js

@@ -38,7 +38,7 @@ function parseTypeAlias(line, text) {
                 kind: 'type-alias',
                 name: nameLeftTypeAlias[1] ?? '',
                 typeExpr,
-                span: { sourceName: line.sourceName, line: line.line, column: firstColumn(line.text) },
+                span: spanForLine(line),
             },
             diagnostics: [],
         };
@@ -99,10 +99,19 @@ function parseLayoutBlock(lines, index, header) {
             name: header.name,
             layoutKind,
             fields,
-            span: { sourceName: line.sourceName, line: line.line, column: firstColumn(line.text) },
+            span: spanForLine(line),
         },
     };
 }
+function spanForLine(line) {
+    return {
+        sourceName: line.sourceName,
+        line: line.line,
+        column: firstColumn(line.text),
+        ...(line.sourceUnit !== undefined ? { sourceUnit: line.sourceUnit } : {}),
+        ...(line.sourceRelation !== undefined ? { sourceRelation: line.sourceRelation } : {}),
+    };
+}
 function skipToLayoutEnd(lines, index, directive) {
     const endDirective = directive === 'union' ? '.endunion' : '.endtype';
     for (let next = index + 1; next < lines.length; next += 1) {

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

@@ -7,7 +7,7 @@ export function parseLogicalLine(line, options = {}) {
     if (text.length === 0) {
         return commentOnlyLine(line);
     }
-    const span = { sourceName: line.sourceName, line: line.line, column: firstColumn(line.text) };
+    const span = spanForLine(line);
     const labelWithStatement = /^(@?[A-Za-z_.$?][A-Za-z0-9_.$?]*):\s*(.+)$/.exec(text);
     if (labelWithStatement) {
         const rawLabel = labelWithStatement[1] ?? '';
@@ -20,7 +20,10 @@ export function parseLogicalLine(line, options = {}) {
         }
         const parsedStatement = parseCanonicalStatement(line, statementText, span);
         return withLineComment(line, {
-            items: [{ kind: 'label', name: labelName, ...(isEntry ? { isEntry: true } : {}), span }, ...parsedStatement.items],
+            items: [
+                { kind: 'label', name: labelName, ...(isEntry ? { isEntry: true } : {}), span },
+                ...parsedStatement.items,
+            ],
             diagnostics: parsedStatement.diagnostics,
         });
     }
@@ -56,6 +59,8 @@ function commentOnlyLine(line) {
                     sourceName: line.sourceName,
                     line: line.line,
                     column: firstColumn(line.text),
+                    ...(line.sourceUnit !== undefined ? { sourceUnit: line.sourceUnit } : {}),
+                    ...(line.sourceRelation !== undefined ? { sourceRelation: line.sourceRelation } : {}),
                 },
             },
         ],
@@ -78,6 +83,8 @@ function withLineComment(line, result) {
                     sourceName: line.sourceName,
                     line: line.line,
                     column: firstColumn(line.text),
+                    ...(line.sourceUnit !== undefined ? { sourceUnit: line.sourceUnit } : {}),
+                    ...(line.sourceRelation !== undefined ? { sourceRelation: line.sourceRelation } : {}),
                 },
             },
         ],
@@ -107,6 +114,15 @@ function parseCanonicalStatement(line, text, span) {
     }
     return { items: [], diagnostics: [parseError(line, `unsupported source line: ${text}`)] };
 }
+function spanForLine(line) {
+    return {
+        sourceName: line.sourceName,
+        line: line.line,
+        column: firstColumn(line.text),
+        ...(line.sourceUnit !== undefined ? { sourceUnit: line.sourceUnit } : {}),
+        ...(line.sourceRelation !== undefined ? { sourceRelation: line.sourceRelation } : {}),
+    };
+}
 function normalizeEntryLabelName(raw) {
     return raw.startsWith('@') ? raw.slice(1) : raw;
 }

package/dist/src/tooling/api.js

@@ -34,7 +34,7 @@ export function analyzeProgramNext(loadedProgram, options = {}) {
         mode: options.caseStyle ?? 'off',
     });
     return {
-        diagnostics: caseStyleDiagnostics,
+        diagnostics: [...assembly.diagnostics, ...caseStyleDiagnostics],
         env: { symbols: assembly.symbols },
     };
 }

package/docs/codebase/01-orientation-and-repository-layout.md

@@ -0,0 +1,192 @@
+---
+layout: default
+title: 'Chapter 1 - Orientation and Repository Layout'
+parent: 'AZM Engineering Manual'
+nav_order: 1
+---
+
+[Manual](index.md) | [Source Loading and Parsing ->](02-source-loading-and-parsing.md)
+
+# Chapter 1 - Orientation and Repository Layout
+
+AZM is a Z80 assembler and tooling package. It turns `.asm` and `.z80` source
+files into bytes, Intel HEX, flat binary output, Debug80 maps, lowered ASM80
+source and register contract metadata. The same implementation serves the command
+line, package consumers, Debug80 integration and the test suite.
+
+The codebase follows the same path as an assembly run. A source file is loaded,
+`.include` lines are expanded, source is split into logical lines, logical lines
+become typed source items, visible `op` invocations expand into ordinary
+instructions, assembler-time facts are collected, instructions and data emit
+bytes, symbolic fixups are resolved and output writers serialize the result.
+
+AZM's extensions are assembler-time features. Layout types, enums, type
+aliases, AZMDoc comments and register contracts help the assembler
+calculate addresses, check contracts and produce metadata. Runtime behaviour
+still comes from the Z80 instructions and bytes that AZM emits.
+
+## The Compiler Path
+
+A small source file shows the main pipeline:
+
+```asm
+        .org $0100
+
+LIMIT       .equ 8
+SpriteArray .typealias Sprite[16]
+
+Sprite .type
+x      .field byte
+y      .field byte
+tile   .field byte
+flags  .field byte
+       .endtype
+
+@Start:
+        ld      b,LIMIT
+Loop:
+        djnz    Loop
+
+Sprites:
+        .ds SpriteArray
+```
+
+The loader reads the entry file and expands includes. The logical-line scanner
+records each line with source provenance. The parser emits source items for
+`.org`, `.equ`, `.typealias`, the `Sprite` layout, labels, instructions and
+`.ds`. Address planning assigns `$0100` to `@Start`, assigns the following
+addresses to `Loop` and `Sprites`, records `LIMIT = 8` and records the size of
+`SpriteArray`. The encoder turns `ld b,LIMIT` and `djnz Loop` into fragments.
+Fixup emission resolves `LIMIT` and the relative branch displacement. The
+output writers produce the selected artifacts.
+
+The CLI and package consumers use this same path. AZM has one compiler pipeline
+with several entry points.
+
+## Main Layers
+
+The implementation has six main layers:
+
+1. **Public entry points** in `src/index.ts`, `src/api-compile.ts`,
+   `src/api-artifacts.ts`, `src/api-register-contracts.ts`, `src/api-tooling.ts`
+   and `src/cli.ts`.
+2. **Loading and parsing** in `src/node/`, `src/source/`, `src/syntax/` and
+   `src/core/compile.ts`.
+3. **Assembler-time analysis** in `src/assembly/` and `src/semantics/`.
+4. **Z80 parsing and encoding** in `src/z80/`.
+5. **Language services** in `src/expansion/`, `src/register-contracts/` and
+   `src/tooling/`.
+6. **Artifact writers** in `src/outputs/`.
+
+Each layer passes structured data to the next. Diagnostics are accumulated as
+data objects and formatted at the CLI edge. Editor tooling, tests and package
+consumers share the same diagnostic model.
+
+## Runtime Boundary
+
+AZM computes everything it can at assembly time. `sizeof(Sprite)`,
+`offset(Sprite, flags)` and `<SpriteArray>Sprites[3].tile` fold to numbers while
+the assembler runs. The generated Z80 program receives those numbers in
+instructions and data. At runtime the CPU executes normal Z80 operations:
+loads, stores, branches, calls, returns and port I/O.
+
+This boundary explains where major features live. Layout code belongs to the
+assembler because it calculates byte offsets. Register contracts belong to the
+assembler because it analyses visible calls and register effects. Output writers
+belong at the edge because they serialize already-assembled facts.
+
+## Repository Shape
+
+The AZM repository has a compact top-level structure:
+
+```text
+AZM/
+  src/                 TypeScript implementation
+  test/                unit, integration, CLI, differential and acceptance tests
+  docs/                active contributor references, specs and design notes
+  examples/            small runnable source examples
+  scripts/             CI, guardrail and developer utility scripts
+  dist/                generated package output
+  package.json         package exports, CLI bin, scripts and dependencies
+```
+
+The repository is a Node package. The source is TypeScript ESM. The published
+package exposes the CLI binary `azm` and stable imports for compile and tooling
+consumers.
+
+## Source Directories
+
+`src/` is organised by compiler responsibility:
+
+| Directory             | Responsibility                                                                                                          |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `assembly/`           | Address planning, placement, byte emission and fixups.                                                                  |
+| `cli/`                | Argument parsing, usage text, artifact path calculation and disk artifact writing.                                      |
+| `core/`               | In-memory compile helpers, conditional assembly and source-item parsing orchestration.                                  |
+| `diagnostics/`        | Diagnostic text formatting.                                                                                             |
+| `expansion/`          | Visible `op` collection, operand modelling, overload selection and expansion.                                           |
+| `model/`              | Shared data types used across layers.                                                                                   |
+| `node/`               | File-backed source loading and include expansion.                                                                       |
+| `outputs/`            | BIN, HEX, D8 map, lowered ASM80 and artifact helper writers.                                                            |
+| `register-contracts/` | Register contract routine modelling, instruction shape helpers, liveness, summaries, reports, interfaces and fixes.     |
+| `semantics/`          | Expression evaluation, constant operators, byte functions and layout evaluation.                                        |
+| `source/`             | Source files, spans, logical line scanning, comment scanning and comment stripping.                                     |
+| `syntax/`             | Line parsing, directive parsing, expression tokenizing, token expression parsing, layout parsing and directive aliases. |
+| `tooling/`            | Editor/tooling APIs and source-style checks.                                                                            |
+| `z80/`                | Z80 instruction model, operand splitting, parser families, encoder families and register effects.                       |
+
+The root files expose public entry points. The subdirectories hold the compiler
+pipeline. A change usually belongs to the directory that owns the data it
+changes.
+
+## Tests, Docs and Scripts
+
+The test tree mirrors the implementation boundaries. Unit tests target narrow
+modules. Integration tests cover cross-stage compiler behaviour. CLI tests
+verify argument and artifact contracts. ASM80 and differential tests protect
+compatibility and byte parity. Type tests protect the public TypeScript surface.
+
+The repo-local docs are the active working set for implementation detail:
+
+```text
+docs/
+  codebase/
+```
+
+`docs/codebase/` is the maintained engineering manual for the source tree,
+compile flow, user-facing CLI, package-facing APIs, AZMDoc/register contract
+metadata and verification lanes. Avoid reintroducing parallel reference,
+planning or design trees unless there is a concrete active need.
+
+`scripts/` contains verification and maintenance utilities. The package scripts
+in `package.json` are the normal entry points. Invoke script files directly
+while debugging the script itself.
+
+## Package Exports
+
+`package.json` exposes these public paths:
+
+```text
+@jhlagado/azm
+@jhlagado/azm/compile
+@jhlagado/azm/tooling
+@jhlagado/azm/cli
+@jhlagado/azm/package.json
+```
+
+Public consumers import from those paths. Internal files under `src/` and
+compiled files under `dist/src/` are implementation details.
+
+## Reading the Codebase
+
+Start with the public entry point that matches your task. For a CLI bug, begin
+in `src/cli/run.ts` and follow the option into `api-compile.ts`. For source
+syntax, begin in `parseNextSourceItems()` and `parse-line.ts`. For an encoding
+bug, begin in `parse-instruction.ts`, `instruction.ts` and `encode.ts`. For a
+D8 map issue, begin in `program-emission.ts`, `outputs/types.ts` and
+`write-d8.ts`.
+
+The compiler is small enough that one feature can be followed from front to
+back. `.typealias`, for example, appears in the parser, address planner,
+expression evaluator, tests and manual examples. A feature is complete when
+each boundary that observes it has the right structured fact.