@jhlagado/azm 0.1.0 → 0.2.0

package/docs/reference/cli.md

@@ -40,6 +40,12 @@ Load project directive aliases:
 azm --aliases azm.aliases.json program.asm
 ```
 
+Normalize Debug80 map source paths against the project root:
+
+```sh
+azm --source-root . --output build/program.hex src/program.asm
+```
+
 ## Output Artifacts
 
 By default AZM writes the primary output plus useful side artifacts using the
@@ -73,6 +79,7 @@ azm --nobin --nohex --reg-report --rc audit program.asm
 | `--nohex`                                     | Do not write `.hex`.                                                 |
 | `--nod8m`                                     | Do not write `.d8.json`.                                             |
 | `--asm80`                                     | Write lowered assembler source as `.z80`.                            |
+| `--source-root <dir>`                         | Emit project-relative source paths in `.d8.json`.                    |
 | `--case-style <mode>`                         | Lint opcode/register case: `off`, `upper`, `lower`, or `consistent`. |
 | `--rc, --register-care <mode>`                | Register-care mode: `off`, `audit`, `warn`, `error`, or `strict`.    |
 | `--reg-report, --emit-register-report`        | Write `.regcare.txt`.                                                |
@@ -87,6 +94,14 @@ azm --nobin --nohex --reg-report --rc audit program.asm
 | `-V, --version`                               | Print package version.                                               |
 | `-h, --help`                                  | Print CLI help.                                                      |
 
+## Debug80 Maps
+
+The `.d8.json` artifact records AZM as the generator, the package version, and
+the input/output paths used for the map. When `--source-root` is supplied, file
+keys and generator input paths are written relative to that directory with `/`
+separators. Constants are emitted as `value` metadata without fake addresses;
+labels and addressable data carry `address`.
+
 ## Register-Care Examples
 
 Audit inferred contracts without failing the build:

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',
 });
 ```
 
@@ -58,6 +58,12 @@ const result = await compile(
   '/abs/path/to/main.asm',
   {
     includeDirs: ['/abs/path/to/includes'],
+    sourceRoot: '/abs/path/to/project',
+    d8mInputs: {
+      listing: '/abs/path/to/project/build/main.lst',
+      hex: '/abs/path/to/project/build/main.hex',
+      bin: '/abs/path/to/project/build/main.bin',
+    },
     outputType: 'hex',
     emitBin: true,
     emitHex: true,
@@ -84,9 +90,65 @@ The integration contract is:
   writing those artifacts to disk
 - Debug80 should consume the `d8m` artifact for source/address metadata and the
   `bin` or `hex` artifact for loadable bytes
+- 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
+  those under `generator.inputs`
+- D8 constants use `value` without `address`; only labels and addressable data
+  are breakpoint anchors
 - 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.
@@ -156,13 +218,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"
+  }
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhlagado/azm",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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,32 @@
     "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",
+    "check:fixture-coverage": "node scripts/dev/check-fixture-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 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 +107,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"