@jhlagado/azm 0.2.7 → 0.2.9

package/README.md

@@ -4,10 +4,12 @@ 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.
 
-This README is the condensed manual. The full AZM book is on the Debug80
-documentation site:
+This README is the condensed manual. The Debug80 website contains the detailed
+AZM manual and broader Debug80 documentation:
 
-[AZM Assembler Manual](https://jhlagado.github.io/debug80-docs/azm-book/book4/)
+- [Debug80 documentation](https://debug80.com/)
+- [AZM Book 0 — Assembler Manual](https://debug80.com/azm-book/book0/)
+- [AZM Book 4](https://jhlagado.github.io/debug80-docs/azm-book/book4/)
 
 ## Install
 
@@ -43,13 +45,13 @@ 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
+`@Start:` is an address label and also a public routine entry for register contracts
 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
+data definitions, layout declarations, register contract comments and optional
 inline `op` definitions.
 
 Canonical AZM directives are lowercase and dotted:
@@ -89,16 +91,102 @@ 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:
+### Style Guide
+
+AZM is stricter than many older Z80 assemblers. It accepts compatibility aliases
+so existing source can be assembled, but source that you control should use the
+canonical syntax below. These rules are intended to make AZM source predictable
+for people and coding agents.
+
+Use lowercase dotted directives, not legacy aliases:
 
 ```asm
-SCREEN_WIDTH .equ 32
+        .org     0x4000
+        .include "../shared/constants.asm"
 
-DrawSprite:
-        ret
+MOVE_PERIOD     .equ     128
+
+Message:
+        .db      "READY",0
+
+StatePtr:
+        .dw      0
+
+Buffer:
+        .ds      32
+```
+
+Use `@Name:` for callable routine entries. The `@` marks a register contracts
+routine boundary; call sites still write the symbol name without `@`:
+
+```asm
+;!      in        A
+;!      out       A
+;!      clobbers  BC
+@MxMask:
+        LD      C,A
+        OR      A
+        LD      A,0x80
+        JR      Z,MxMaskDone
+MxMaskLp:
+        SRL     A
+        DJNZ    MxMaskLp
+MxMaskDone:
+        RET
+```
+
+Use plain labels for data and internal branch targets. Plain labels are global,
+so give branch labels names that stay unique across the whole include tree.
+Prefer descriptive labels such as `MxMaskLoop`, `MxMaskDone`, `SpawnFailed` and
+`HeldDirRateSet` rather than generic names such as `Loop` or `Done`.
+
+Use uppercase with underscores for constants, following the usual C-style
+convention. Group related constants with clear prefixes:
+
+```asm
+PORT_DIGITS     .equ     0x01
+PORT_LCD_DATA   .equ     0x84
+
+API_SCAN_KEYS   .equ     16
+KEY_LEFT        .equ     0x11
+KEY_RIGHT       .equ     0x10
+
+COLOR_RED       .equ     0x01
+COLOR_GREEN     .equ     0x02
+COLOR_YELLOW    .equ     COLOR_RED + COLOR_GREEN
+```
+
+Use PascalCase for routine entries, branch labels, data labels, type names and
+enum names. Use lower camel case for fields and enum members when that makes
+layout expressions easier to read. The assembler enforces uniqueness, not style,
+but symbols are case-sensitive: `ColorRed`, `COLOR_RED` and `colorRed` are
+different names.
+
+Put declaration names on the left and do not use a colon for constants, enums,
+types or type aliases:
+
+```asm
+MOVE_PERIOD     .equ     128
+Colour          .enum    Red, Green, Blue
+SpriteArray     .typealias Sprite[16]
+
+Sprite          .type
+x               .field   byte
+y               .field   byte
+tile            .field   byte
+flags           .field   byte
+                .endtype
 ```
 
+Use a colon only for address labels. `COUNT .equ 8` declares a constant;
+`Count:` declares an address label. Do not write `COUNT: .equ 8` in canonical
+AZM.
+
+Use indentation to make columns easy to scan. Put labels at the left margin,
+indent instructions and standalone directives, and align operands enough to keep
+dense assembly readable. Exact tab width is less important than keeping one
+source file internally consistent.
+
 ## Literals
 
 AZM accepts the usual Z80 numeric forms:
@@ -247,12 +335,74 @@ azm -I include -I vendor program.asm
 Included source contributes labels, constants, enums, types, ops and routines to
 the same assembly.
 
-## Register Care
+## Imports
 
-Register care checks whether subroutines preserve the register values that their
+`.import` is AZM's module-style source composition directive:
+
+```asm
+; main.asm
+        .import "keyboard.asm"
+
+@Start:
+        call    ReadKey
+        ret
+```
+
+```asm
+; keyboard.asm
+@ReadKey:
+        call    ScanMatrix
+        ret
+
+ScanMatrix:
+        xor     a
+        ret
+```
+
+Imported source assembles at the point where `.import` appears, so native
+`.bin`, `.hex` and `.d8.json` output contain the imported bytes as part of the
+same program. Paths resolve like includes: relative to the importing file first,
+then through `-I` include directories.
+
+The difference is visibility. In an imported file, labels written with `@` are
+public exports. Code outside `keyboard.asm` can call `ReadKey`, using the name
+without `@`. Plain labels in an imported file, such as `ScanMatrix`, are private
+to that imported file or import unit. The imported file may call its own private
+helpers, but outside references fail with a direct visibility diagnostic.
+
+`.include` remains textual. Included text belongs to the including source unit
+and is intended for shared constants, declarations and compatibility source.
+Use `.import` when a source file should behave like a module with public `@`
+entry points and private implementation labels.
+
+Repeated imports of the same resolved file are idempotent: the first import
+loads and emits the module, later imports of that same file are skipped.
+Repeated includes are still textual and repeat every time. Recursive includes or
+imports are rejected with source diagnostics.
+
+Register contracts use the same `@` routine boundaries across imported files.
+Imported public routines are analyzed as internal routines under `--rc strict`,
+and private helpers called inside an imported public routine are summarized as
+part of the same program analysis.
+
+ASM80-compatible lowered `.z80` output does not yet support imported source
+units. If `--asm80` is requested for a program that uses `.import`, AZM reports
+an explicit `AZMN_ASM80` diagnostic instead of silently flattening the module
+boundary. Use native `.bin`, `.hex` and `.d8.json` output for imported programs.
+
+## Register Contracts
+
+Register contracts check whether subroutines preserve the register values that their
 callers still need. It is designed to catch register collisions, a common source
 of assembly bugs.
 
+The benefit is practical: AZM can stop a plausible-looking routine at compile
+time when it reads a register after calling code that may clobber it. In larger
+Z80 projects this encourages smaller routines, clearer `@` boundaries, explicit
+helper outputs, and proof or test harnesses that stay honest under
+`--rc strict`. The friction is intentional: strict contracts make hidden
+register and stack assumptions visible before they become debugger sessions.
+
 Routine entry labels start with `@`:
 
 ```asm
@@ -272,7 +422,7 @@ name:
         call    CheckTile
 ```
 
-AZMDoc register-care comments use `;!` and may record inputs, outputs,
+AZMDoc register contract 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.
@@ -280,13 +430,24 @@ when the routine returns.
 Run the analysis with:
 
 ```sh
-azm --rc audit --reg-report program.asm
+azm --rc audit program.asm
+azm --rc warn program.asm
 azm --rc error --interface monitor.asmi program.asm
+azm --rc strict 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.
+The main modes are `audit`, `warn`, `error` and `strict`. Use `audit` for a
+non-blocking check, `warn` for visible diagnostics with a successful compile,
+`error` to fail on proven caller/callee register conflicts, and `strict` to fail
+on any register contracts issue AZM cannot prove safe, including unknown call
+boundaries and unbalanced or unknown stack effects.
+
+The normal register contracts interface is compiler diagnostics plus source
+contracts. Use `--contracts` or `--fix` when you want AZM to update compact
+AZMDoc contract comments in source. Use `.asmi` files for externally assembled
+routines or monitor/system APIs. Text report files are available with
+`--reg-report`, but they are an explicit debug/export option and are not part of
+the normal workflow.
 
 ## Ops and Aliases
 
@@ -316,7 +477,7 @@ 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
+External register contract interfaces use `.asmi` and are loaded with
 `--interface`.
 
 Basic use writes the default artifact set next to the source file:
@@ -364,55 +525,57 @@ Generate ASM80-compatible lowered source:
 azm --asm80 program.asm
 ```
 
-Run register-care analysis:
+Run register contracts analysis:
 
 ```sh
-azm --rc audit --reg-report program.asm
+azm --rc audit program.asm
+azm --rc warn program.asm
 azm --rc error --interface monitor.asmi program.asm
+azm --rc strict 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.
+| 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-contracts <mode>`           | Register contracts mode: `off`, `audit`, `warn`, `error`, `strict`. |
+| `--reg-report, --emit-register-report`        | Opt-in debug report: write `.regcontracts.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 contract source fixes.                  |
+| `--accept-out <routine:carrier>`              | Promote an inferred output candidate while annotating.              |
+| `--interface <file>`                          | Load external register contracts from `.asmi`.                      |
+| `--reg-profile, --register-profile <profile>` | Register contracts 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 the [AZM Engineering Manual](docs/codebase/) for the maintained codebase,
+CLI and package-interface reference.
 
 ## Output Artifacts
 
 By default, AZM writes the requested primary output plus useful side artifacts
 using the same base path.
 
-| Extension      | Contents                                      |
-| -------------- | --------------------------------------------- |
-| `.hex`         | Intel HEX                                     |
-| `.bin`         | flat binary                                   |
-| `.d8.json`     | Debug80 map                                   |
-| `.z80`         | ASM80-compatible lowered source when enabled  |
-| `.regcare.txt` | register-care report when enabled             |
-| `.asmi`        | register-care interface when enabled          |
+| Extension           | Contents                                     |
+| ------------------- | -------------------------------------------- |
+| `.hex`              | Intel HEX                                    |
+| `.bin`              | flat binary                                  |
+| `.d8.json`          | Debug80 map                                  |
+| `.z80`              | ASM80-compatible lowered source when enabled |
+| `.regcontracts.txt` | opt-in register contracts debug report       |
+| `.asmi`             | register contracts interface when enabled    |
 
 ## Programmatic API
 
@@ -430,13 +593,13 @@ npm install @jhlagado/azm
 ```
 
 Use `@jhlagado/azm/tooling` when an editor, linter or debugger integration
-needs parsing, diagnostics, symbols, semantic checks or register-care facts in
+needs parsing, diagnostics, symbols, semantic checks or register contract facts in
 memory:
 
 ```ts
 import {
   analyzeProgram,
-  analyzeRegisterCareForTools,
+  analyzeRegisterContractsForTools,
   loadProgram,
 } from '@jhlagado/azm/tooling';
 
@@ -451,13 +614,13 @@ if (loaded.loadedProgram) {
     requireMain: false,
   });
 
-  const registerCare = analyzeRegisterCareForTools(loaded.loadedProgram, {
+  const registerContracts = analyzeRegisterContractsForTools(loaded.loadedProgram, {
     mode: 'audit',
-    registerCareProfile: 'mon3',
+    registerContractsProfile: 'mon3',
   });
 
   console.log(analysis.diagnostics);
-  console.log(registerCare.candidateDiagnostics);
+  console.log(registerContracts.candidateDiagnostics);
 }
 ```
 
@@ -483,8 +646,8 @@ const result = await compile(
       hex: '/abs/path/to/project/build/main.hex',
       bin: '/abs/path/to/project/build/main.bin',
     },
-    registerCare: 'audit',
-    registerCareInterfaces: ['/abs/path/to/monitor.asmi'],
+    registerContracts: 'audit',
+    registerContractsInterfaces: ['/abs/path/to/monitor.asmi'],
   },
   { formats: defaultFormatWriters },
 );
@@ -501,24 +664,24 @@ 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.                          |
+| 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.                          |
+| `registerContracts`             | Register contracts mode.                                  |
+| `registerContractsInterfaces`   | External `.asmi` contract files.                          |
 
 Public tooling types include `Diagnostic`, `LoadedProgram`,
-`AnalyzeProgramResult`, `LoadProgramResult`, `RegisterCareCandidateDiagnostic`
+`AnalyzeProgramResult`, `LoadProgramResult`, `RegisterContractsCandidateDiagnostic`
 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.
+See the [public surface reference](docs/codebase/appendices/c-public-surface-reference.md)
+for current API notes.
 
 ## Development
 
@@ -533,8 +696,8 @@ npm run test:azm:corpus
 npm test
 ```
 
-The live source map is maintained in
-[docs/reference/source-overview.md](docs/reference/source-overview.md).
+The live source map is maintained in the
+[AZM Engineering Manual](docs/codebase/).
 
 ## License
 

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

@@ -0,0 +1,20 @@
+import type { Diagnostic } from './model/diagnostic.js';
+import type { SourceItem } from './model/source-item.js';
+import type { Artifact, EmittedByteMap, FormatWriters } from './outputs/types.js';
+import type { CompileNextFunctionOptions } from './api-compile.js';
+interface EmitAssemblyArtifactsOptions {
+    readonly entryFile: string;
+    readonly options: CompileNextFunctionOptions;
+    readonly formats: FormatWriters;
+    readonly program: readonly SourceItem[];
+    readonly bytes: Uint8Array;
+    readonly origin: number;
+    readonly sourceSegments: EmittedByteMap['sourceSegments'];
+    readonly initializedAddresses: readonly number[];
+    readonly symbols: Readonly<Record<string, number>>;
+}
+export declare function emitAssemblyArtifacts(input: EmitAssemblyArtifactsOptions): Promise<{
+    readonly artifacts: readonly Artifact[];
+    readonly diagnostics: readonly Diagnostic[];
+}>;
+export {};

package/dist/src/api-artifacts.js

@@ -0,0 +1,165 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, normalize } from 'node:path';
+import { UnsupportedAsm80LoweringError } from './outputs/write-asm80.js';
+let cachedPackageVersion;
+export async function emitAssemblyArtifacts(input) {
+    const artifacts = [];
+    const diagnostics = [];
+    const map = assembledImageToMap(input.bytes, input.origin, input.sourceSegments);
+    const hexMap = assembledInitializedImageToMap(input.bytes, input.origin, input.initializedAddresses);
+    const sidecarMap = assembledInitializedImageToMap(input.bytes, input.origin, input.initializedAddresses, input.sourceSegments);
+    const symbols = collectSymbolEntries(input.program, input.symbols);
+    const emit = compileArtifactDefaults(input.options);
+    const d8Root = input.options.sourceRoot ?? dirname(input.entryFile);
+    if (emit.emitBin) {
+        artifacts.push(input.formats.writeBin(map, symbols));
+    }
+    if (emit.emitHex) {
+        artifacts.push(input.formats.writeHex(hexMap, symbols));
+    }
+    if (emit.emitD8m) {
+        artifacts.push(input.formats.writeD8m(sidecarMap, symbols, await buildD8mOptions(input.entryFile, d8Root, input.options, symbols)));
+    }
+    if (emit.emitAsm80 && input.formats.writeAsm80 !== undefined) {
+        try {
+            artifacts.push(input.formats.writeAsm80(input.program, symbols));
+        }
+        catch (error) {
+            if (error instanceof UnsupportedAsm80LoweringError) {
+                diagnostics.push({
+                    severity: 'error',
+                    code: 'AZMN_ASM80',
+                    message: error.message,
+                    sourceName: error.item.span.sourceName,
+                    line: error.item.span.line,
+                    column: error.item.span.column,
+                });
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    return { artifacts, diagnostics };
+}
+function compileArtifactDefaults(options) {
+    const anyPrimary = [options.emitBin, options.emitHex, options.emitD8m].some((value) => value !== undefined);
+    const emitBin = anyPrimary ? (options.emitBin ?? false) : true;
+    const emitHex = anyPrimary ? (options.emitHex ?? false) : true;
+    const emitD8m = anyPrimary ? (options.emitD8m ?? false) : true;
+    const emitAsm80 = options.emitAsm80 ?? false;
+    return { emitBin, emitHex, emitD8m, emitAsm80 };
+}
+function assembledImageToMap(bytes, origin, sourceSegments = []) {
+    const map = new Map();
+    for (let offset = 0; offset < bytes.length; offset += 1) {
+        map.set(origin + offset, bytes[offset] ?? 0);
+    }
+    const writtenRange = {
+        start: origin,
+        end: origin + bytes.length,
+    };
+    return { bytes: map, writtenRange, sourceSegments };
+}
+function assembledInitializedImageToMap(bytes, origin, initializedAddresses, sourceSegments = []) {
+    const map = new Map();
+    for (const address of initializedAddresses) {
+        const offset = address - origin;
+        if (offset >= 0 && offset < bytes.length) {
+            map.set(address, bytes[offset] ?? 0);
+        }
+    }
+    return { bytes: map, sourceSegments };
+}
+function collectSymbolEntries(items, resolvedSymbols) {
+    const map = new Map();
+    for (const item of items) {
+        appendSymbolEntry(map, item, resolvedSymbols);
+    }
+    return [...map.values()];
+}
+function appendSymbolEntry(map, item, resolvedSymbols) {
+    if (item.kind === 'equ') {
+        const value = resolvedSymbols[item.name];
+        if (value !== undefined) {
+            map.set(item.name, {
+                kind: 'constant',
+                name: item.name,
+                value,
+                file: item.span.sourceName,
+                line: item.span.line,
+                scope: 'global',
+            });
+        }
+        return;
+    }
+    if (item.kind === 'label') {
+        const address = resolvedSymbols[item.name];
+        if (address !== undefined) {
+            map.set(item.name, {
+                kind: 'label',
+                name: item.name,
+                address,
+                file: item.span.sourceName,
+                line: item.span.line,
+                scope: 'global',
+            });
+        }
+        return;
+    }
+    if (item.kind === 'enum') {
+        for (const member of item.members) {
+            const fullName = `${item.name}.${member}`;
+            const value = resolvedSymbols[fullName];
+            if (value !== undefined) {
+                map.set(fullName, {
+                    kind: 'constant',
+                    name: fullName,
+                    value,
+                    file: item.span.sourceName,
+                    line: item.span.line,
+                    scope: 'global',
+                });
+            }
+        }
+    }
+}
+async function buildD8mOptions(entryFile, d8Root, options, symbols) {
+    const main = symbols.find((symbol) => symbol.kind === 'label' && symbol.name.toLowerCase() === 'main');
+    return {
+        rootDir: normalize(d8Root),
+        packageVersion: await readPackageVersion(),
+        inputs: {
+            entry: entryFile,
+            ...(options.d8mInputs?.hex !== undefined ? { hex: options.d8mInputs.hex } : {}),
+            ...(options.d8mInputs?.bin !== undefined ? { bin: options.d8mInputs.bin } : {}),
+        },
+        ...(main !== undefined ? { entrySymbol: main.name } : {}),
+        ...(main !== undefined ? { entryAddress: main.kind === 'constant' ? main.value : main.address } : {}),
+    };
+}
+async function readPackageVersion() {
+    if (cachedPackageVersion !== undefined) {
+        return cachedPackageVersion;
+    }
+    const packageJsonCandidates = [
+        new URL('../package.json', import.meta.url),
+        new URL('../../package.json', import.meta.url),
+        new URL('../../../package.json', import.meta.url),
+    ];
+    for (const candidate of packageJsonCandidates) {
+        try {
+            const raw = await readFile(candidate, 'utf8');
+            const json = JSON.parse(raw);
+            if (json.version !== undefined) {
+                cachedPackageVersion = json.version;
+                return cachedPackageVersion;
+            }
+        }
+        catch {
+            // Continue searching candidates.
+        }
+    }
+    cachedPackageVersion = '0.0.0';
+    return cachedPackageVersion;
+}

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

@@ -3,7 +3,7 @@ import { writeHex } from './outputs/write-hex.js';
 import type { AddressRange, Artifact, D8mArtifact, D8mFileEntry, D8mFileSymbol, D8mGenerator, D8mJson, D8mSegment, D8mSymbol, EmittedByteMap, FormatWriters, SymbolEntry, WriteD8mOptions } from './outputs/types.js';
 import type { Diagnostic } from './model/diagnostic.js';
 import type { CaseStyleMode } from './tooling/case-style.js';
-import type { RegisterCareMode } from './register-care/types.js';
+import type { RegisterContractsMode } from './register-contracts/types.js';
 export { writeHex, defaultFormatWriters };
 export type { AddressRange, Artifact, D8mArtifact, D8mFileEntry, D8mFileSymbol, D8mGenerator, D8mJson, D8mSegment, D8mSymbol, EmittedByteMap, FormatWriters, SymbolEntry, WriteD8mOptions, };
 export type CompileDependencies = CompileNextDependencies;
@@ -27,13 +27,19 @@ export interface CompileNextFunctionOptions {
     readonly emitHex?: boolean;
     readonly emitD8m?: boolean;
     readonly emitAsm80?: boolean;
-    readonly registerCare?: RegisterCareMode;
+    readonly registerContracts?: RegisterContractsMode;
+    /** @deprecated Use registerContracts. */
+    readonly registerCare?: RegisterContractsMode;
     readonly emitRegisterReport?: boolean;
     readonly emitRegisterInterface?: boolean;
     readonly emitRegisterAnnotations?: boolean;
     readonly fixRegisterContracts?: boolean;
     readonly acceptRegisterOutputCandidates?: string[];
+    readonly registerContractsProfile?: 'mon3';
+    /** @deprecated Use registerContractsProfile. */
     readonly registerCareProfile?: 'mon3';
+    readonly registerContractsInterfaces?: string[];
+    /** @deprecated Use registerContractsInterfaces. */
     readonly registerCareInterfaces?: string[];
     readonly skipAssembly?: boolean;
 }