@jhlagado/azm 0.2.0 → 0.2.1

package/docs/reference/tooling-api.md

@@ -89,7 +89,9 @@ The integration contract is:
 - `compile()` returns artifacts in memory; the CLI is only responsible for
   writing those artifacts to disk
 - Debug80 should consume the `d8m` artifact for source/address metadata and the
-  `bin` or `hex` artifact for loadable bytes
+  `bin` artifact for loadable bytes (hex is acceptable when bin is not emitted)
+- Do not rely on lowered `.z80` for Debug80 integration until asm80 coverage is
+  complete; use **bin + d8m** as the supported debugger path
 - pass `sourceRoot` so D8 file keys are stable project-relative source paths
   rather than basename-only paths
 - pass `d8mInputs` when Debug80 knows the intended artifact paths; AZM records
@@ -252,6 +254,12 @@ const result = await compile(
 );
 ```
 
+**`emitAsm80` caveat:** Lowered `.z80` emission is gated but not universal.
+Unsupported instructions or operand forms throw `UnsupportedAsm80LoweringError`,
+surfaced as `AZMN_ASM80`. When assembly already succeeded, `compile()` still
+returns bin/hex/d8/listing artifacts alongside the asm80 error. Run
+`npm run check:asm80-coverage` on your sources before relying on lowered output.
+
 The compiler accepts flat `.asm` / `.z80` source, retained AZM assembler
 features, and the same output writers used by the CLI. External register-care
 interfaces are `.asmi` metadata files, not compile entry files.
@@ -270,20 +278,19 @@ generated frames are outside this API contract for AZM source.
 The public tooling surface includes:
 
 - `Diagnostic`, `DiagnosticIds`, severity/id types
-- `SourcePosition`, `SourceSpan`
-- `ProgramNode`, `SourceFileNode`, `SourceItemNode`
 - `LoadedProgram`
-- `CompileEnv`
+- `AnalyzeProgramResult`, `LoadProgramResult`
 - `RegisterCareCandidateDiagnostic`, `RegisterCareCodeAction`, `RegisterCareOutputCandidate`
 
-In v1, the AST exported from `src/frontend/ast.ts` is part of the public contract. Additive fields are minor-version changes; breaking shape changes are major-version changes.
+The public tooling contract is the package export surface, not deep internal
+paths. Do not document retired internal modules as public API.
 
 ## Syntax Highlighting Example
 
 Syntax colouring is an example consumer of the tooling API:
 
 1. Call `loadProgram()` with the file path and optional unsaved buffer text.
-2. Walk `ProgramNode` and inspect `node.kind` plus `node.span`.
+2. Walk `loadedProgram.program.files[0].items` and inspect each item's `kind` and `span`.
 3. Map those spans to TextMate scopes or semantic token kinds in the editor.
 4. Fall back to regex/TextMate-only colouring if parsing fails or the editor needs a cheaper fast path.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhlagado/azm",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "AZM assembler for the Z80 family (Node.js CLI)",
   "license": "GPL-3.0-only",
   "engines": {
@@ -72,7 +72,9 @@
     "test:coverage": "vitest run --coverage",
     "test:ci:coverage-core": "node scripts/dev/run-coverage-core.mjs",
     "test:ci:slow-reliability": "vitest run --no-file-parallelism --maxWorkers=1 --minWorkers=1 --testTimeout=20000 --hookTimeout=300000 test/cli test/cli_*.test.ts",
+    "test:ci:asm80-parity": "node scripts/ci/run-asm80-parity.mjs",
     "check:fixture-coverage": "node scripts/dev/check-fixture-coverage.mjs",
+    "check:asm80-coverage": "node scripts/dev/check-asm80-lowering-coverage.mjs",
     "test:azm:alpha": "node scripts/dev/run-azm-alpha-guardrails.mjs",
     "test:azm:corpus": "node scripts/dev/run-azm-corpus-guardrails.mjs",
     "test:package": "npm run build && node scripts/dev/smoke-npm-package.mjs",
@@ -84,7 +86,7 @@
     "next:typecheck": "tsc -p tsconfig.json --noEmit",
     "next:test": "vitest run --config vitest.config.ts",
     "next:check": "npm run next:typecheck && npm run next:test",
-    "next:guardrails:core": "npm run next:check && npm run next:diff-current:all",
+    "next:guardrails:core": "npm run next:check && npm run check:asm80-coverage && npm run next:diff-current:all",
     "next:guardrails:package": "npm run test:package || npm run next:guardrails:package:local",
     "next:guardrails:package:local": "npm run build && vitest run -c vitest.config.ts test/integration/stage-16-package-smoke-local.test.ts && vitest run test/public_api_surface.test.ts",
     "next:guardrails:quality": "npm run lint && npm run check:source-file-sizes && node scripts/check-source-file-sizes.mjs",