@jhlagado/azm 0.2.8 → 0.2.9

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.

package/docs/codebase/02-source-loading-and-parsing.md

@@ -0,0 +1,263 @@
+---
+layout: default
+title: 'Chapter 2 - Source Loading and Parsing'
+parent: 'AZM Engineering Manual'
+nav_order: 2
+---
+
+[<- Orientation and Repository Layout](01-orientation-and-repository-layout.md) | [Assembly and Z80 Emission ->](03-assembly-and-z80-emission.md)
+
+# Chapter 2 - Source Loading and Parsing
+
+Source loading and parsing turn entry files into typed source items. This
+chapter follows the path from a filename to the structured data that assembly,
+tooling and register contracts consume.
+
+The loading boundary lives in `src/node/source-host.ts`. The parser is
+orchestrated by `parseNextSourceItems()` in `src/core/compile.ts`, with
+single-line parsing in `src/syntax/parse-line.ts`. Expression and declaration
+parsing is split across tokenizer, token-expression, directive and layout
+modules in `src/syntax/`.
+
+## Entry Files and Source Text
+
+The public tooling and compile APIs enter loading through `loadProgramNext()` in
+`src/tooling/api.ts`. That function calls `expandSourceForTooling()` and then
+passes the expanded logical lines to `parseNextSourceItems()`.
+
+`expandSourceForTooling()` accepts:
+
+```ts
+export interface LoadProgramNextOptions {
+  readonly entryFile: string;
+  readonly includeDirs?: readonly string[];
+  readonly directiveAliasFiles?: readonly string[];
+  readonly preloadedText?: string;
+  readonly signal?: AbortSignal;
+}
+```
+
+The entry file is normalised and checked for a source extension. AZM source
+entries use `.asm` or `.z80`. `preloadedText` lets editor integrations parse an
+unsaved buffer for the entry file while included files still come from disk.
+`signal` lets an editor cancel stale work when a newer buffer arrives.
+
+The loader keeps the full text of every loaded source file in `sourceTexts`.
+Later stages use parsed source items for compiler logic, but several features
+need original text:
+
+- register contract annotation rewrites exact source lines
+- tooling reads source text for diagnostics and code actions
+- D8 map generation needs file names and line provenance
+- case-style linting inspects original token case
+
+Logical lines drive parsing. Source texts support tools that need to point back
+into the user's files.
+
+## Source Loading Directives
+
+The tooling loader recognises two source-loading directives before parsing:
+`.include` and `.import`.
+
+`.include` is textual inclusion. The loader reads the entry file, scans it into
+logical lines and recursively expands include directives. Include paths resolve
+relative to the including source file first, then through configured include
+directories.
+
+`.import` uses the same path resolution rule, but it starts a new source
+ownership unit for tooling. Parsed items from the imported file still join the
+same flattened logical line stream, though their spans record the imported file
+as the owning unit. This lets tools distinguish entry-owned source, text pulled
+in by `.include` and routines introduced by imported modules.
+
+Repeated imports of the same resolved file are idempotent. The first import
+loads and emits the module at the import point; later imports of that same
+resolved file are skipped. Repeated includes remain textual and repeatable.
+Recursive include or import stacks are diagnosed before parsing, with the
+diagnostic naming the recursive source relation.
+
+Labels in imported source keep their physical source locations. Imported
+`@Name:` labels are public exports visible to outside source as `Name`. Plain
+labels in an imported file are private to that import unit. Text included from
+inside an imported file remains part of that imported unit, so its plain labels
+are private unless they are also public `@` labels.
+
+That rule keeps library files portable. A library can include a sibling file and
+still assemble when the entry file is run from another directory. Include
+directories then act as project-level search paths for shared headers, vendor
+source and imported modules.
+
+The loader returns:
+
+```ts
+export interface ExpandedNextSource {
+  readonly entryFile: string;
+  readonly lines: readonly LogicalLine[];
+  readonly sourceTexts: ReadonlyMap<string, string>;
+  readonly sourceLineComments: ReadonlyMap<string, ReadonlyMap<number, string>>;
+}
+```
+
+`lines` is the flattened source stream for parsing. `sourceTexts` keeps the
+original file text. `sourceLineComments` keeps comments indexed by file and line
+so register contract analysis can reconstruct AZMDoc contract blocks after routines have
+been identified.
+
+## Logical Lines and Comments
+
+`src/source/logical-lines.ts` scans a `SourceFile` into `LogicalLine` objects. A
+logical line records the source name, line number and original text. Tooling
+loads can also attach `sourceUnit` and `sourceRelation`:
+
+- `sourceUnit` is the owning file for the current tooling unit
+- `sourceRelation` is `entry`, `include` or `import`
+
+This thin structure gives every later diagnostic a stable location and enough
+provenance for tooling features that need to reason about module ownership.
+
+The source helpers are small and important:
+
+| File                      | Role                                                   |
+| ------------------------- | ------------------------------------------------------ |
+| `source-file.ts`          | Wraps source text with a source name.                  |
+| `logical-lines.ts`        | Splits text into line records.                         |
+| `source-span.ts`          | Defines the common span shape.                         |
+| `line-comment-scanner.ts` | Finds line comments while respecting quoted text.      |
+| `strip-line-comment.ts`   | Removes semicolon comments through the shared scanner. |
+
+`strip-line-comment.ts` is used by source-loading directive recognition, layout parsing,
+conditional assembly and single-line parsing. Shared comment handling prevents
+each stage from inventing a slightly different rule for semicolons inside
+strings and character literals.
+
+## Directive Aliases
+
+Directive aliases are loaded during `loadProgramNext()`:
+
+```ts
+const directiveAliasProfiles = await Promise.all(
+  (options.directiveAliasFiles ?? []).map((path) => readDirectiveAliasProfile(path)),
+);
+const directiveAliasPolicy = buildDirectiveAliasPolicy(directiveAliasProfiles);
+```
+
+`src/syntax/directive-aliases.ts` owns the alias policy. Built-in aliases and
+project alias files are normalised before line parsing. The parser then
+receives canonical directive forms and emits canonical source items.
+
+Aliases are a syntax boundary. They affect directive recognition before parsing.
+The assembler-time model receives canonical source items.
+
+## Source Items
+
+The parser is the first place where AZM source becomes compiler data. Before
+this point, a line is text with a file name and line number. After this point, a
+line is a label, instruction, directive, layout declaration or comment item.
+
+`src/model/source-item.ts` defines the parser output. The model includes:
+
+- labels
+- `.org`, `.equ`, `.db`, `.dw`, `.ds`, `.align`, string directives and `.end`
+- instructions
+- record and union layout declarations
+- type aliases
+- enums
+- op-expanded items
+- comments
+
+Each item carries a source span where appropriate. Tooling spans now preserve
+optional `sourceUnit` and `sourceRelation` fields when the loader attached them.
+Assembly uses item kind to decide size and emission. Register contract analysis
+uses instruction, label and comment items to build routines. D8 map output uses
+spans to connect emitted bytes back to files and lines.
+
+## Top-Level Parse Order
+
+`parseNextSourceItems()` handles structural forms before ordinary line parsing:
+
+1. `applyConditionalAssembly()` in `src/core/conditional-assembly.ts` filters
+   the logical line stream.
+2. `collectOps()` records top-level `op` definitions and marks their body lines.
+3. Name-left `.typealias` declarations are parsed.
+4. Record and union headers collect `.field` declarations until `.endtype` or
+   `.endunion`.
+5. Visible op invocations expand into ordinary source items.
+6. `parseLogicalLine()` handles single-line labels, directives, data and
+   instructions.
+
+This order matters. Ops must be collected before invocation expansion. Layout
+declarations must collect their body lines as one source item. Ordinary
+instruction parsing should see the lines that remain after those structural
+forms have been handled.
+
+## Layout and Declaration Parsing
+
+Name-left layout syntax is parsed in `parseNextSourceItems()` because a record
+or union body spans multiple lines:
+
+```asm
+Sprite .type
+x      .field byte
+y      .field byte
+tile   .field byte
+flags  .field byte
+       .endtype
+```
+
+Fields are parsed as `LayoutField` values. Each field has a name and a type
+expression. The parser checks declaration shape. `address-planning.ts` later
+checks duplicate field names, layout size and type references.
+
+Type aliases are parsed as named bindings:
+
+```asm
+SpriteArray .typealias Sprite[16]
+```
+
+The parser stores the alias target as a type expression. Assembly resolves the
+target against scalar layout names, record names, union names and other type
+aliases.
+
+The parser also distinguishes address labels from declarations. An address
+label uses a colon and becomes a label item. Name-left declarations become
+equate, enum, type, union or type-alias items.
+
+```asm
+Start:
+        ret
+
+COUNT .equ 8
+```
+
+A label contributes an address based on placement. An equate contributes an
+assembler-time value based on expression evaluation.
+
+## Expressions and Conditionals
+
+`src/syntax/expression-tokenizer.ts` tokenizes expression text.
+`parse-token-expression.ts` builds expression trees from tokens.
+`parse-expression.ts` is the public syntax wrapper used by line parsing.
+`parse-layout-expression.ts` parses layout type expressions used by `.ds`,
+`.field`, `.typealias`, `sizeof(...)`, `offset(...)` and layout casts.
+`parse-directive-statement.ts` parses directive statements that need more than
+single-token recognition.
+
+The parser produces expression trees from `src/model/expression.ts`.
+`src/semantics/expression-evaluation.ts` evaluates those trees when the
+assembler-time environment is available.
+
+Conditional assembly is handled before final line parsing. The conditional pass
+keeps the active lines and removes inactive branches from the stream seen by
+later stages. Ordinary parsing then receives one effective source program.
+
+## Parse Diagnostics
+
+`src/syntax/parse-diagnostics.ts` contains shared helpers for syntax errors.
+Diagnostic IDs come from `src/model/diagnostic.ts`. Use those helpers when
+adding parse failures so source positions, severity and code shape stay
+consistent.
+
+Parser recovery matters for editor tooling. A user may have a half-written line
+while typing. Tooling still needs symbols, diagnostics and register contract hints
+for surrounding source, so parse errors should usually report a diagnostic and
+let parsing continue.