@jhlagado/azm 0.1.0 → 0.1.1

package/dist/src/cli.d.ts

@@ -8,6 +8,7 @@ type CliOptions = {
     entryFile: string;
     outputPath?: string;
     outputType: 'hex' | 'bin';
+    sourceRoot?: string;
     emitBin: boolean;
     emitHex: boolean;
     emitD8m: boolean;

package/dist/src/cli.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import { mkdir, writeFile } from 'node:fs/promises';
-import { createRequire } from 'node:module';
 import { dirname, extname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { compile } from './compile.js';
 import { isSupportedSourcePath, sourceExtensions } from './frontend/sourceExtensions.js';
 import { defaultFormatWriters } from './formats/index.js';
 import { normalizePathForCompare } from './pathCompare.js';
+import { readPackageVersion } from './packageInfo.js';
 function usage() {
     return [
         'azm [options] <entry.asm|entry.z80>',
@@ -19,6 +19,7 @@ function usage() {
         '      --nohex           Suppress .hex',
         '      --nod8m           Suppress .d8.json',
         '      --asm80           Emit assembler-valid lowered source (.z80)',
+        '      --source-root <d> Normalize D8 source paths relative to this directory',
         '      --case-style <m>  Case-style lint mode: off|upper|lower|consistent',
         '      --rc <m>            Register-care mode: off|audit|warn|error|strict',
         '      --reg-report       Emit .regcare.txt report',
@@ -132,6 +133,13 @@ function parseCaseStyleArg(arg, argv, indexRef, state) {
     state.caseStyle = value;
     return true;
 }
+function parseSourceRootArg(arg, argv, indexRef, state) {
+    const parsed = readMatchedFlagValue(arg, argv, indexRef, ['--source-root', '--map-root']);
+    if (!parsed)
+        return false;
+    state.sourceRoot = parsed.value;
+    return true;
+}
 function parseRegisterCareArg(arg, argv, indexRef, state) {
     const parsed = readMatchedFlagValue(arg, argv, indexRef, ['--register-care', '--rc']);
     if (!parsed)
@@ -199,11 +207,7 @@ function handleCliFastPath(arg) {
         return { code: 0 };
     }
     if (arg === '-V' || arg === '--version') {
-        const require = createRequire(import.meta.url);
-        const here = dirname(fileURLToPath(import.meta.url));
-        const packageJsonPath = resolve(here, '..', '..', 'package.json');
-        const pkg = require(packageJsonPath);
-        process.stdout.write(`${String(pkg.version ?? '0.0.0')}\n`);
+        process.stdout.write(`${readPackageVersion()}\n`);
         return { code: 0 };
     }
     return undefined;
@@ -239,6 +243,7 @@ function finalizeCliOptions(state) {
         entryFile: state.entryFile,
         ...(state.outputPath ? { outputPath: state.outputPath } : {}),
         outputType: state.outputType,
+        ...(state.sourceRoot !== undefined ? { sourceRoot: state.sourceRoot } : {}),
         emitBin: state.emitBin,
         emitHex: state.emitHex,
         emitD8m: state.emitD8m,
@@ -293,6 +298,8 @@ export function parseCliArgs(argv) {
         }
         if (parseCaseStyleArg(arg, argv, indexRef, state))
             continue;
+        if (parseSourceRootArg(arg, argv, indexRef, state))
+            continue;
         if (parseDirectiveAliasFileArg(arg, argv, indexRef, state))
             continue;
         if (parseRegisterCareArg(arg, argv, indexRef, state))
@@ -457,6 +464,9 @@ export async function runCli(argv) {
         if ('code' in parsed)
             return parsed.code;
         const base = artifactBase(parsed.entryFile, parsed.outputType, parsed.outputPath);
+        const hexPath = `${base}.hex`;
+        const binPath = `${base}.bin`;
+        const lstPath = `${base}.lst`;
         const compileOptions = {
             emitBin: parsed.emitBin,
             emitHex: parsed.emitHex,
@@ -466,6 +476,12 @@ export async function runCli(argv) {
             caseStyle: parsed.caseStyle,
             includeDirs: parsed.includeDirs,
             directiveAliasFiles: parsed.directiveAliasFiles,
+            ...(parsed.sourceRoot !== undefined ? { sourceRoot: parsed.sourceRoot } : {}),
+            d8mInputs: {
+                ...(parsed.sourceRoot !== undefined && parsed.emitListing ? { listing: lstPath } : {}),
+                ...(parsed.sourceRoot !== undefined && parsed.emitHex ? { hex: hexPath } : {}),
+                ...(parsed.sourceRoot !== undefined && parsed.emitBin ? { bin: binPath } : {}),
+            },
             requireMain: false,
             defaultCodeBase: 0,
             registerCare: parsed.registerCare,

package/dist/src/compile.js

@@ -9,6 +9,7 @@ import { emitProgram } from './lowering/emit.js';
 import { loadProgram } from './sourceLoader.js';
 import { analyzeRegisterCare } from './registerCare/analyze.js';
 import { parseInterfaceContracts } from './registerCare/smartComments.js';
+import { readPackageVersion } from './packageInfo.js';
 function withDefaults(options) {
     const anyPrimaryEmitSpecified = [options.emitBin, options.emitHex, options.emitD8m].some((v) => v !== undefined);
     const emitBin = anyPrimaryEmitSpecified ? (options.emitBin ?? false) : true;
@@ -135,8 +136,18 @@ export const compile = async (entryFile, options, deps) => {
     }
     if (emit.emitD8m) {
         const mainEntry = symbols.find((s) => s.kind === 'label' && s.name.toLowerCase() === 'main');
+        const d8mRoot = options.sourceRoot ?? dirname(entryPath);
         artifacts.push(deps.formats.writeD8m(map, symbols, {
-            rootDir: dirname(entryPath),
+            rootDir: d8mRoot,
+            packageVersion: readPackageVersion(),
+            inputs: {
+                entry: entryPath,
+                ...(options.d8mInputs?.listing !== undefined
+                    ? { listing: options.d8mInputs.listing }
+                    : {}),
+                ...(options.d8mInputs?.hex !== undefined ? { hex: options.d8mInputs.hex } : {}),
+                ...(options.d8mInputs?.bin !== undefined ? { bin: options.d8mInputs.bin } : {}),
+            },
             ...(mainEntry
                 ? {
                     entrySymbol: mainEntry.name,

package/dist/src/formats/types.d.ts

@@ -82,6 +82,21 @@ export interface WriteD8mOptions {
      * When provided, file paths are made project-relative and use `/` separators.
      */
     rootDir?: string;
+    /**
+     * AZM package version to record in generator metadata.
+     */
+    packageVersion?: string;
+    /**
+     * Source/output paths used to produce this map.
+     *
+     * Paths are normalized with `rootDir` when present.
+     */
+    inputs?: {
+        entry?: string;
+        listing?: string;
+        hex?: string;
+        bin?: string;
+    };
     /**
      * Optional runnable entry symbol metadata for harnesses.
      */

package/dist/src/formats/writeD8m.js

@@ -12,6 +12,14 @@ function normalizeD8mPath(file, rootDir) {
     }
     return rel.replace(/\\/g, '/');
 }
+function normalizeD8mInputs(inputs, rootDir) {
+    if (!inputs)
+        return undefined;
+    const entries = Object.entries(inputs)
+        .filter((entry) => typeof entry[1] === 'string' && entry[1] !== '')
+        .map(([key, value]) => [key, normalizeD8mPath(value, rootDir)]);
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
 function toSerializedSymbol(symbol) {
     if (symbol.kind === 'constant') {
         return {
@@ -213,6 +221,7 @@ export function writeD8m(map, symbols, opts) {
             ...(entry.symbols.length > 0 ? { symbols: entry.symbols } : {}),
         },
     ]));
+    const generatorInputs = normalizeD8mInputs(opts?.inputs, opts?.rootDir);
     const json = {
         format: 'd8-debug-map',
         version: 1,
@@ -223,17 +232,14 @@ export function writeD8m(map, symbols, opts) {
         segments,
         ...(fileList.length > 0 ? { fileList } : {}),
         symbols: serializedSymbols,
-        ...(opts?.entrySymbol !== undefined || opts?.entryAddress !== undefined
-            ? {
-                generator: {
-                    tool: 'azm',
-                    ...(opts.entrySymbol !== undefined ? { entrySymbol: opts.entrySymbol } : {}),
-                    ...(opts.entryAddress !== undefined
-                        ? { entryAddress: opts.entryAddress & 0xffff }
-                        : {}),
-                },
-            }
-            : {}),
+        generator: {
+            name: 'azm',
+            tool: 'azm',
+            ...(opts?.packageVersion !== undefined ? { version: opts.packageVersion } : {}),
+            ...(generatorInputs !== undefined ? { inputs: generatorInputs } : {}),
+            ...(opts?.entrySymbol !== undefined ? { entrySymbol: opts.entrySymbol } : {}),
+            ...(opts?.entryAddress !== undefined ? { entryAddress: opts.entryAddress & 0xffff } : {}),
+        },
     };
     return { kind: 'd8m', json };
 }

package/dist/src/packageInfo.d.ts

@@ -0,0 +1 @@
+export declare function readPackageVersion(): string;

package/dist/src/packageInfo.js

@@ -0,0 +1,15 @@
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export function readPackageVersion() {
+    const require = createRequire(import.meta.url);
+    const here = dirname(fileURLToPath(import.meta.url));
+    let pkg;
+    try {
+        pkg = require(resolve(here, '..', 'package.json'));
+    }
+    catch {
+        pkg = require(resolve(here, '..', '..', 'package.json'));
+    }
+    return String(pkg.version ?? '0.0.0');
+}

package/dist/src/pipeline.d.ts

@@ -19,6 +19,21 @@ export interface CompilerOptions {
     outputPath?: string;
     /** Primary output type (future). */
     outputType?: 'hex' | 'bin';
+    /**
+     * Root used for source paths in debug maps.
+     *
+     * When present, D8 file keys and generator input paths are emitted relative
+     * to this directory with `/` separators.
+     */
+    sourceRoot?: string;
+    /**
+     * Output paths recorded in D8 generator metadata when known by the caller.
+     */
+    d8mInputs?: {
+        listing?: string;
+        hex?: string;
+        bin?: string;
+    };
     /** Emit flat binary (`.bin`). */
     emitBin?: boolean;
     /** Emit Intel HEX (`.hex`). */

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

@@ -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,6 +90,12 @@ 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhlagado/azm",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "AZM assembler for the Z80 family (Node.js CLI)",
   "license": "GPL-3.0-only",
   "engines": {