@jhlagado/azm 0.1.1 → 0.2.1

package/docs/reference/tooling-api.md

@@ -45,7 +45,7 @@ const analysis = analyzeProgram(loaded.loadedProgram, {
 
 const registerCare = analyzeRegisterCareForTools(loaded.loadedProgram, {
   mode: 'audit',
-  profile: 'mon3',
+  registerCareProfile: 'mon3',
 });
 ```
 
@@ -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
@@ -99,6 +101,56 @@ The integration contract is:
 - diagnostics are data objects and should be displayed directly rather than
   parsed from CLI text
 
+## D8 Debug Map Shape
+
+The D8 artifact is typed as `D8mArtifact`, with `json: D8mJson`. Debug80 can
+import these types from `@jhlagado/azm/compile`.
+
+```ts
+import type { D8mArtifact, D8mJson, D8mSymbol } from '@jhlagado/azm/compile';
+```
+
+The top-level map contains:
+
+```ts
+{
+  format: 'd8-debug-map',
+  version: 1,
+  arch: 'z80',
+  addressWidth: 16,
+  endianness: 'little',
+  generator: {
+    name: 'azm',
+    tool: 'azm',
+    version: '0.1.1',
+    inputs: {
+      entry: 'src/pacmo/pacmo.z80',
+      listing: 'build/pacmo.lst',
+      hex: 'build/pacmo.hex',
+      bin: 'build/pacmo.bin',
+    },
+  },
+  files: {
+    'src/pacmo/pacmo.z80': {
+      segments: [],
+      symbols: [],
+    },
+  },
+  segments: [],
+  symbols: [],
+}
+```
+
+Constants and labels intentionally have different shapes:
+
+```ts
+{ name: 'ColorRed', kind: 'constant', value: 1 }
+{ name: 'main', kind: 'label', address: 0x4000 }
+```
+
+A constant value is not a breakpoint address. Debug80 should use labels and
+addressable data symbols as breakpoint anchors.
+
 ## Layer A: Load and Parse
 
 Use `loadProgram()` when you need the same AST, spans, and diagnostics that the compiler uses, but without lowering or writing artifacts.
@@ -168,13 +220,15 @@ if (!loaded.loadedProgram) {
 
 const registerCare = analyzeRegisterCareForTools(loaded.loadedProgram, {
   mode: 'audit',
-  profile: 'mon3',
+  registerCareProfile: 'mon3',
 });
 
 for (const diagnostic of registerCare.candidateDiagnostics) {
   console.log(diagnostic.file, diagnostic.line, diagnostic.message);
   console.log(diagnostic.autoFixable); // true when CLI --fix can safely add the hint
-  console.log(diagnostic.codeAction.edit.text); // "; expects out A\n"
+  if (diagnostic.autoFixable && diagnostic.codeAction) {
+    console.log(diagnostic.codeAction.edit.text); // "; expects out A\n"
+  }
 }
 ```
 
@@ -200,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.
@@ -218,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.1.1",
+  "version": "0.2.1",
   "description": "AZM assembler for the Z80 family (Node.js CLI)",
   "license": "GPL-3.0-only",
   "engines": {
@@ -33,6 +33,7 @@
   },
   "files": [
     "dist/src",
+    "dist/legacy-root-azm",
     "docs/reference/cli.md",
     "docs/reference/tooling-api.md"
   ],
@@ -69,17 +70,34 @@
     "test": "npm run test:azm:alpha",
     "test:all": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "test:ci:slow-reliability": "vitest run --no-file-parallelism --maxWorkers=1 --minWorkers=1 --testTimeout=20000 --hookTimeout=300000 --passWithNoTests 'test/cli_*.test.ts' 'test/cli/**/*.test.ts'",
+    "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": "node scripts/dev/smoke-npm-package.mjs",
+    "test:package": "npm run build && node scripts/dev/smoke-npm-package.mjs",
     "test:asm80:baseline": "node scripts/dev/run-asm80-baseline.mjs",
     "test:asm80:tetro": "AZM_RUN_TETRO_ACCEPTANCE=1 vitest run test/asm80/tetro_acceptance.test.ts",
+    "test:asm80:pacmo": "AZM_RUN_PACMO_ACCEPTANCE=1 vitest run test/asm80/pacmo_acceptance.test.ts",
+    "test:asm80:mon3": "AZM_RUN_MON3_ACCEPTANCE=1 vitest run test/asm80/mon3_acceptance.test.ts",
     "test:watch": "vitest",
+    "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 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",
+    "next:guardrails": "npm run next:guardrails:core && npm run next:guardrails:package && npm run next:guardrails:quality",
     "format": "prettier -w .",
     "format:check": "prettier -c .",
     "check:source-file-sizes": "node scripts/check-source-file-sizes.mjs",
     "check:source-file-sizes:enforce": "node scripts/check-source-file-sizes.mjs --enforce-hard-cap",
+    "next:diff-current": "node scripts/diff-against-current.mjs --fixtures-dir test/differential/fixtures --skip-unsupported",
+    "next:diff-current:root": "node scripts/diff-against-current.mjs --fixtures-dir test/fixtures --skip-unsupported",
+    "next:diff-current:all": "npm run next:diff-current && npm run next:diff-current:root",
     "prepack": "npm run build",
     "prepublishOnly": "npm run build",
     "azm": "npm run build && node dist/src/cli.js"
@@ -91,6 +109,7 @@
     "fallow": "^2.54.2",
     "globals": "^17.4.0",
     "prettier": "^3.5.0",
+    "tsx": "^4.20.5",
     "typescript": "^5.7.3",
     "typescript-eslint": "^8.57.2",
     "vitest": "^2.1.9"