@jhlagado/azm 0.2.8 → 0.2.9

package/docs/codebase/05-interfaces-and-output-artifacts.md

@@ -0,0 +1,253 @@
+---
+layout: default
+title: 'Chapter 5 - Interfaces and Output Artifacts'
+parent: 'AZM Engineering Manual'
+nav_order: 5
+---
+
+[<- Ops and Register Contracts](04-ops-and-register-contracts.md) | [Verification and Maintenance ->](06-verification-and-maintenance.md)
+
+# Chapter 5 - Interfaces and Output Artifacts
+
+AZM has three public entry surfaces: the command-line binary, the compile API
+and the tooling API. They all use the same compiler pipeline. Output writers
+then serialize assembled facts for users, Debug80 and package consumers.
+
+This chapter covers the boundary between the compiler and its callers: package
+exports, CLI flow, public TypeScript APIs and artifact shapes.
+
+## Package Exports
+
+`package.json` exposes:
+
+```text
+@jhlagado/azm
+@jhlagado/azm/compile
+@jhlagado/azm/tooling
+@jhlagado/azm/cli
+@jhlagado/azm/package.json
+```
+
+`src/index.ts` re-exports the stable public surface. `src/api-compile.ts` backs
+`@jhlagado/azm/compile`. `src/api-artifacts.ts` isolates assembly artifact
+creation for the compile API. `src/api-register-contracts.ts` isolates register contract
+analysis, interface loading and register contract artifact creation.
+`src/api-tooling.ts` backs `@jhlagado/azm/tooling`. `src/cli.ts` is the
+executable entry.
+
+The root export gives consumers a broad import. The `/compile` path is the
+build-system path. The `/tooling` path is the editor and analysis path. The
+`/cli` path backs the executable entry. The `/package.json` path exposes package
+metadata for tools that need the installed version.
+
+## CLI Flow
+
+The executable path in `package.json` points to `dist/src/cli.js`, compiled from
+`src/cli.ts`. That file calls `runCli(process.argv.slice(2))` and sets the
+process exit code.
+
+`src/cli/run.ts` owns the CLI control flow:
+
+```text
+runCli(argv)
+  parseCliArgs(argv)
+  artifactBase(entryFile, outputType, outputPath)
+  compile(entryFile, buildCompileOptions(parsed, base))
+  sort and print diagnostics
+  writeArtifacts(base, artifacts, outputType)
+  return exit code
+```
+
+The CLI returns `0` for a successful assembly, `1` when diagnostics include an
+error and `2` for argument or unexpected runtime failures. Diagnostics are
+printed to standard error. The primary output path is printed to standard output
+when artifact writing succeeds.
+
+`src/cli/parse-args.ts` parses switches and validates the command shape.
+`src/cli/usage.ts` owns help text. The parser recognises output selection,
+artifact suppression, include paths, source-root, case-style linting, directive
+aliases and register contract options.
+
+`src/cli/write-artifacts.ts` maps parsed options into
+`CompileNextFunctionOptions` and calculates the output stem.
+`src/cli/artifact-files.ts` writes in-memory artifacts to disk. If the user
+supplies `--output build/program.bin`, the primary artifact is written to that
+path and side artifacts use the same base. If the user supplies only
+`program.asm`, AZM writes outputs next to the entry source using the source
+stem.
+
+## Compile API
+
+`src/api-compile.ts` exports:
+
+```ts
+export async function compile(
+  entryFile: string,
+  options: CompileNextFunctionOptions = {},
+  deps: CompileNextDependencies = { formats: defaultFormatWriters },
+): Promise<CompileNextResult>;
+```
+
+The compile API is file-backed. It reads source from disk, expands includes,
+analyses the program, assembles it and returns artifacts in memory.
+
+Important options include:
+
+| Option                                       | Meaning                                 |
+| -------------------------------------------- | --------------------------------------- |
+| `includeDirs`                                | Include search paths.                   |
+| `directiveAliasFiles`                        | Project alias profile files.            |
+| `caseStyle`                                  | Case-style lint mode.                   |
+| `outputType`                                 | Primary output type, `hex` or `bin`.    |
+| `sourceRoot`                                 | Root used for portable D8 map paths.    |
+| `d8mInputs`                                  | Artifact paths recorded in D8 metadata. |
+| `emitBin`, `emitHex`, `emitD8m`, `emitAsm80` | Artifact selection.                     |
+| `registerContracts`                          | Register contract mode.                 |
+| `emitRegisterReport`                         | Emit `.regcontracts.txt` artifact.      |
+| `emitRegisterInterface`                      | Emit `.asmi` artifact.                  |
+| `emitRegisterAnnotations`                    | Emit source annotation artifact.        |
+| `fixRegisterContracts`                       | Apply conservative source fixes.        |
+| `acceptRegisterOutputCandidates`             | Promote selected output candidates.     |
+| `registerContractsProfile`                   | Built-in external contract profile.     |
+| `registerContractsInterfaces`                | External `.asmi` contract files.        |
+| `skipAssembly`                               | Run loading and analysis only.          |
+
+`compile()` returns:
+
+```ts
+export interface CompileNextResult {
+  readonly diagnostics: readonly Diagnostic[];
+  readonly artifacts: readonly Artifact[];
+}
+```
+
+Diagnostics describe every warning or error observed during loading, analysis,
+register contract analysis, assembly or artifact creation. Artifacts contain the
+in-memory outputs requested by options.
+
+The older option names `registerCare`, `registerCareProfile` and
+`registerCareInterfaces` remain as deprecated aliases for package consumers.
+New callers should use the `registerContracts...` names.
+
+## Tooling API
+
+`src/tooling/api.ts` exports `loadProgramNext()` and `analyzeProgramNext()`.
+`src/api-tooling.ts` re-exports those functions with register contract tooling
+helpers.
+
+`loadProgramNext()` returns a loaded program with source items, source texts and
+source line comments. `analyzeProgramNext()` runs semantic checks and returns
+symbols. `analyzeRegisterContractsForTools()` returns register contract
+diagnostics and code actions in a form suitable for editors.
+
+The tooling loader now recognises both `.include` and `.import`. Both directives
+flatten source into one parse stream. `.import` also marks parsed spans with a
+new source ownership unit, while `.include` keeps the surrounding owner's unit.
+Editor features can use `item.span.sourceUnit` and `item.span.sourceRelation`
+to distinguish module-owned declarations from text included into another unit.
+Diagnostics, symbols and source segments continue to use physical source file
+paths, so imported files appear as their own files in editor and Debug80 map
+metadata.
+
+An editor integration usually starts with:
+
+```ts
+const loaded = await loadProgramNext({
+  entryFile: '/project/src/main.asm',
+  includeDirs: ['/project/include'],
+  preloadedText: editorText,
+});
+```
+
+When `loaded.loadedProgram` is present, the editor can call
+`analyzeProgramNext()` for symbols and case-style diagnostics. It can also call
+`analyzeRegisterContractsForTools()` for register contract candidate diagnostics
+and code actions.
+
+## Artifact Types
+
+The output layer uses structured artifact objects from `src/outputs/types.ts`:
+
+- `BinArtifact`
+- `HexArtifact`
+- `D8mArtifact`
+- `Asm80Artifact`
+- `RegisterContractsReportArtifact`
+- `RegisterContractsInterfaceArtifact`
+- `RegisterContractsAnnotationsArtifact`
+
+Each artifact has a `kind` field. Callers can switch on `kind` to find the
+artifact they need:
+
+```ts
+const d8m = result.artifacts.find((artifact) => artifact.kind === 'd8m');
+const bin = result.artifacts.find((artifact) => artifact.kind === 'bin');
+```
+
+This shape keeps the compile API independent from output paths. A caller can
+write artifacts to disk, keep them in memory, send them to another process or
+compare them in a test.
+
+## Byte Maps, BIN and HEX
+
+Assembly produces an `EmittedByteMap`. It represents sparse output: addresses
+map to byte values and source segments describe where those bytes came from.
+
+`src/outputs/range.ts` provides range helpers. `getWrittenSegments()` identifies
+contiguous written address ranges. `getWrittenRange()` returns the overall
+written span.
+
+`src/outputs/write-bin.ts` writes flat binary. It chooses the written range,
+fills gaps as needed and returns a `Uint8Array` artifact.
+`src/outputs/write-hex.ts` wraps `src/outputs/hex.ts`, which writes Intel HEX
+records and checksums.
+
+## D8 Debug Maps
+
+`src/outputs/write-d8.ts` writes Debug80 metadata. It records generator details,
+input artifact paths, source files, source segments, addressable symbols and
+value-only constants.
+
+The writer normalizes source paths through `sourceRoot` when provided. It also
+coalesces source segments and clips them to written ranges so Debug80 receives a
+clean map of source lines to emitted bytes.
+
+The D8 map distinguishes addressable symbols from constants. Labels and
+addressable data carry addresses. Constants carry values. Debug80 can then use
+addressable symbols for breakpoints and display constants as metadata.
+
+## Lowered ASM80 and Register Contract Artifacts
+
+`src/outputs/write-asm80.ts` serializes accepted AZM source items as
+ASM80-compatible `.z80` text. It lowers supported AZM constructs into forms that
+can be compared against ASM80 output. The writer is larger than the other
+writers because it turns structured items back into source text.
+
+Lowered ASM80 output currently rejects programs that use `.import`. Imported
+source units carry visibility semantics that would be misleading if silently
+flattened into compatibility text. The compile API reports `AZMN_ASM80` for
+this output combination while native BIN, HEX and D8 artifacts remain
+supported.
+
+Register contract report, interface and annotation artifacts are created through
+`runRegisterContracts()` in `src/api-register-contracts.ts` and flow through
+the same compile result and CLI write path. The report is human-readable. The `.asmi`
+interface is metadata that can be loaded by later compile runs through
+`--interface`. Annotation artifacts write source files when `--contracts` or
+`--fix` is used.
+
+## Public API Compatibility
+
+The public API is defined by package exports and exported TypeScript types.
+Major-version planning is the point where these shapes can change:
+
+- exported function names
+- option object property names
+- result object shapes
+- artifact kinds
+- diagnostic object shape
+- D8 map type exports
+- register contract tooling result shapes
+
+The type tests are the safety net for this boundary. When a public type changes,
+the change should be intentional and reflected in package documentation.

package/docs/codebase/06-verification-and-maintenance.md

@@ -0,0 +1,202 @@
+---
+layout: default
+title: 'Chapter 6 - Verification and Maintenance'
+parent: 'AZM Engineering Manual'
+nav_order: 6
+---
+
+[<- Interfaces and Output Artifacts](05-interfaces-and-output-artifacts.md) | [Appendices ->](appendices/)
+
+# Chapter 6 - Verification and Maintenance
+
+AZM's verification suite is organised by compiler boundary. A parser change has
+a parser test. A byte-emission change has an encoder or integration test. A
+public API change has a type-surface test. Reading the tests beside the
+implementation is often the fastest way to understand a subsystem.
+
+## Test Directory Map
+
+```text
+test/
+  unit/
+  integration/
+  cli/
+  asm80/
+  differential/
+  fixtures/
+  helpers/
+  types/
+```
+
+Start with the narrowest useful test, then add the integration or CLI coverage
+that proves the user-facing behaviour.
+
+## Unit and Integration Tests
+
+Unit tests live under `test/unit/` and mirror implementation directories:
+
+| Directory                  | Boundary                                                            |
+| -------------------------- | ------------------------------------------------------------------- |
+| `unit/syntax/`             | Line parsing, expression parsing and directive aliases.             |
+| `unit/source/`             | Logical line and comment handling.                                  |
+| `unit/z80/`                | Instruction parsing, diagnostics and encoding.                      |
+| `unit/outputs/`            | Artifact writer behaviour.                                          |
+| `unit/expansion/`          | Op collection and expansion.                                        |
+| `unit/register-contracts/` | Register contract carriers, summaries, liveness, reports and fixes. |
+
+Unit tests are small and direct. A new indexed operand form belongs in
+`test/unit/z80/` before it appears in a full source fixture. The unit test proves
+the instruction parser and encoder agree on that one form.
+
+Integration tests under `test/integration/` assemble real source snippets
+through multiple compiler stages. Layout features, ops and register contracts
+interactions usually need this level of test because the behaviour exists
+between modules rather than inside one helper.
+
+Source-loading and tooling provenance changes belong here as well. The
+`stage-11-tooling-api.test.ts` integration suite covers include and import
+resolution, recursive load failures and the span ownership metadata that tools
+read from parsed items.
+
+## CLI, ASM80 and Differential Tests
+
+`test/cli/` verifies the command-line contract: options, artifact writing,
+failure modes, determinism, case-style linting and register contract switches.
+Users experience the command-line behaviour through argument parsing,
+diagnostics, output paths and exit status.
+
+CLI tests also protect deterministic output. `compareDiagnosticsForCli()` sorts
+diagnostics by file, line, column, severity, code and message. A CLI test can
+catch changes that leave the compiler correct but make terminal output unstable.
+
+`test/asm80/` and `test/differential/` protect compatibility and byte parity.
+These tests compare AZM behaviour against ASM80 expectations, lowered output and
+real-program fixtures. For an assembler, a one-byte difference is a behavioural
+change.
+
+## Fixtures and Helpers
+
+`test/fixtures/` contains small source programs named after the issue or
+behaviour they cover. A good fixture shows the source shape that matters. It
+includes enough context to assemble and diagnose the behaviour, then stops.
+
+`test/helpers/` contains shared helpers for CLI runs, diagnostics, temporary
+source files and acceptance tests. Use helpers for repetitive setup. Keep test
+expectations close to the test itself so failures stay easy to read.
+
+`test/types/` and `test/public_api_surface.test.ts` protect the package export
+surface. Run them whenever changing `src/index.ts`, `src/api-compile.ts`,
+`src/api-tooling.ts`, `src/outputs/types.ts` or `package.json` exports.
+
+## Guardrails
+
+The main package scripts are:
+
+```sh
+npm run build
+npm run typecheck
+npm run lint
+npm run test:azm:alpha
+npm run test:azm:corpus
+npm run next:guardrails:core
+npm run next:guardrails:package
+npm run next:guardrails:quality
+npm run next:guardrails
+npm test
+```
+
+Additional guardrails live under `scripts/ci/` and `scripts/dev/`. They answer
+larger questions: does the alpha lane still pass, does ASM80 parity still hold,
+does the package work after build output is generated, does lowered ASM80 still
+cover the intended source set, do source files remain within the size budget and
+does the corpus still match the accepted compatibility baseline.
+
+Use this map when choosing a verification lane:
+
+| Change                      | Tests                                                                |
+| --------------------------- | -------------------------------------------------------------------- |
+| Parser or expression syntax | `test/unit/syntax/**`, relevant integration tests.                   |
+| Source loading or tooling provenance | `test/integration/stage-11-tooling-api.test.ts`, relevant unit tests in `test/unit/source/**`. |
+| Z80 instruction support     | `test/unit/z80/**`, diagnostic matrices, ASM80 parity when relevant. |
+| Layout semantics            | layout integration tests and output tests.                           |
+| Ops                         | `test/unit/expansion/**`, op integration tests.                      |
+| Register contracts          | register contract unit, integration and CLI tests.                   |
+| CLI options                 | `test/cli/**`.                                                       |
+| Output artifacts            | `test/unit/outputs/**`, CLI artifact tests.                          |
+| Public API                  | type tests, public API surface tests and tooling API tests.          |
+| ASM80 lowering or parity    | `check:asm80-coverage`, `test:ci:asm80-parity`, corpus guardrails.   |
+| Package export surface      | `test:package`, public API surface tests.                            |
+
+For subtle compiler changes, use a narrow test that names the broken layer and
+a broader test that proves the public behaviour. That combination makes failures
+easy to diagnose.
+
+## Maintenance Boundaries
+
+AZM is stable enough that changes should preserve the existing boundaries. A
+maintainer can usually decide where a change belongs before editing code:
+source loading, parsing, expression evaluation, address planning, Z80 encoding,
+op expansion, register contracts, artifact writing, CLI or public API.
+
+Ask what kind of fact the change affects:
+
+- Text and files belong in `node/` and `source/`.
+- Syntax belongs in `syntax/` or the structural parsing section of
+  `core/compile.ts`.
+- Assembler-time facts belong in `assembly/` and `semantics/`.
+- Instruction forms belong in `z80/`.
+- Inline source generation belongs in `expansion/`.
+- Routine contracts and liveness belong in `register-contracts/`.
+- Artifact shape belongs in `outputs/`.
+- User commands belong in `cli/`.
+- Package consumers belong in `api-compile.ts`, `api-tooling.ts` and
+  `index.ts`.
+
+This boundary choice determines the files to read, the tests to write and the
+documentation to update.
+
+## Structured Data and Compatibility
+
+AZM passes structured data between stages. When a later stage needs more
+information, add it to the earlier structured model and carry it forward.
+Source provenance belongs on logical lines and source items. Syntax shape
+belongs in `SourceItem`. Instruction shape belongs in `Z80Instruction`. Layout
+facts belong in layout records and type expressions. Artifact metadata belongs
+in output types.
+
+Directive aliases and ASM80 lowering serve compatibility. Native AZM syntax
+stays clean inside the compiler model when compatibility forms are converted to
+canonical source items early and compatibility output is serialized late.
+
+## Diagnostics and Manual Updates
+
+Diagnostics should name the source location, the failing construct and the
+reason. Parser diagnostics should recover where possible. Assembly diagnostics
+should be deterministic. CLI output should sort diagnostics consistently.
+
+This book should change when:
+
+- a source directory is added, removed or repurposed
+- the compile flow changes
+- public package exports change
+- CLI option groups change
+- output artifact shapes change
+- a major subsystem gains a new responsibility
+- tests or guardrails are reorganised
+
+Small implementation changes usually need test updates. Structural changes need
+tests and manual updates.
+
+## Suggested Change Workflow
+
+1. Identify the boundary.
+2. Read the relevant chapter and appendix entry.
+3. Add or revise the closest test for the behaviour.
+4. Change the implementation.
+5. Run the focused test.
+6. Run the broader guardrail that matches the public behaviour.
+7. Update docs when the contract or architecture changed.
+
+This workflow leaves evidence at the level where future maintainers will look:
+the affected boundary, the public behaviour and the engineering manual when the
+structure changes.