@jhlagado/azm 0.1.0 → 0.2.0

package/README.md

@@ -85,6 +85,7 @@ Options:
       --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
@@ -115,7 +116,14 @@ import { compile, defaultFormatWriters } from '@jhlagado/azm/compile';
 
 const result = await compile(
   '/abs/path/to/main.asm',
-  { outputType: 'hex' },
+  {
+    outputType: 'hex',
+    sourceRoot: '/abs/path/to/project',
+    d8mInputs: {
+      hex: '/abs/path/to/project/build/main.hex',
+      listing: '/abs/path/to/project/build/main.lst',
+    },
+  },
   { formats: defaultFormatWriters },
 );
 

package/dist/{src → legacy-root-azm/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 → legacy-root-azm/src}/formats/index.d.ts

@@ -1,6 +1,6 @@
 import type { FormatWriters } from './types.js';
 /**
- * Default in-memory artifact writers for PR1.
+ * Default in-memory artifact writers.
  *
  * These writers implement the `FormatWriters` contract and return artifacts without writing to disk.
  */

package/dist/{src → legacy-root-azm/src}/formats/index.js

@@ -4,7 +4,7 @@ import { writeHex } from './writeHex.js';
 import { writeListing } from './writeListing.js';
 import { writeAsm80 } from './writeAsm80.js';
 /**
- * Default in-memory artifact writers for PR1.
+ * Default in-memory artifact writers.
  *
  * These writers implement the `FormatWriters` contract and return artifacts without writing to disk.
  */

package/dist/{src → legacy-root-azm/src}/formats/types.d.ts

@@ -68,20 +68,31 @@ export interface WriteHexOptions {
      */
     lineEnding?: '\n' | '\r\n';
 }
-/**
- * Options for BIN writing (reserved for future options).
- */
+/** Options for BIN writing. */
 export interface WriteBinOptions {
 }
-/**
- * Options for D8M writing (reserved for future options).
- */
+/** Options for D8M writing. */
 export interface WriteD8mOptions {
     /**
      * Base directory used to normalize file paths in D8M symbol entries.
      * 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.
      */
@@ -155,6 +166,64 @@ export interface D8mArtifact {
     path?: string;
     json: D8mJson;
 }
+export type D8mSegmentKind = 'code' | 'data' | 'directive' | 'label' | 'macro' | 'unknown';
+export type D8mSegmentConfidence = 'high' | 'medium' | 'low';
+export interface D8mSegment {
+    start: number;
+    end: number;
+    lstLine: number;
+    /** 1-based original source line when known. */
+    line?: number;
+    kind: D8mSegmentKind;
+    confidence: D8mSegmentConfidence;
+}
+export type D8mSymbol = {
+    name: string;
+    kind: 'constant';
+    value: number;
+    file?: string;
+    line?: number;
+    scope?: 'global' | 'local';
+} | {
+    name: string;
+    kind: 'label' | 'data' | 'unknown';
+    address: number;
+    file?: string;
+    line?: number;
+    scope?: 'global' | 'local';
+    size?: number;
+};
+export type D8mFileSymbol = {
+    name: string;
+    kind: 'constant';
+    value: number;
+    line?: number;
+    scope?: 'global' | 'local';
+} | {
+    name: string;
+    kind: 'label' | 'data' | 'unknown';
+    address: number;
+    line?: number;
+    scope?: 'global' | 'local';
+    size?: number;
+};
+export interface D8mFileEntry {
+    segments?: D8mSegment[];
+    symbols?: D8mFileSymbol[];
+}
+export interface D8mGenerator {
+    name: 'azm';
+    tool: 'azm';
+    version?: string;
+    inputs?: {
+        entry?: string;
+        listing?: string;
+        hex?: string;
+        bin?: string;
+    };
+    entrySymbol?: string;
+    entryAddress?: number;
+}
 /**
  * In-memory register-care audit report artifact.
  */
@@ -194,7 +263,13 @@ export type D8mJson = {
     format: 'd8-debug-map';
     version: 1;
     arch: 'z80';
-    [key: string]: unknown;
+    addressWidth: 16;
+    endianness: 'little';
+    files: Record<string, D8mFileEntry>;
+    segments: AddressRange[];
+    fileList?: string[];
+    symbols: D8mSymbol[];
+    generator: D8mGenerator;
 };
 /**
  * Format writers used by the pipeline to turn emitted bytes/symbols into artifacts.

package/dist/{src → legacy-root-azm/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 → legacy-root-azm/src}/formats/writeHex.d.ts

@@ -2,7 +2,6 @@ import type { EmittedByteMap, HexArtifact, SymbolEntry, WriteHexOptions } from '
 /**
  * Create an Intel HEX artifact from an emitted address->byte map.
  *
- * PR1 implementation note:
  * - Emits only type-00 data records and a type-01 EOF record.
  * - Does not emit extended address records (assumes 16-bit address space).
  */

package/dist/{src → legacy-root-azm/src}/formats/writeHex.js

@@ -9,7 +9,6 @@ function checksum(bytes) {
 /**
  * Create an Intel HEX artifact from an emitted address->byte map.
  *
- * PR1 implementation note:
  * - Emits only type-00 data records and a type-01 EOF record.
  * - Does not emit extended address records (assumes 16-bit address space).
  */

package/dist/legacy-root-azm/src/packageInfo.d.ts

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

package/dist/legacy-root-azm/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 → legacy-root-azm/src}/pipeline.d.ts

@@ -4,8 +4,6 @@ import type { RegisterCareMode } from './registerCare/types.js';
 export type CaseStyleMode = 'off' | 'upper' | 'lower' | 'consistent';
 /**
  * Options that influence compilation behavior and which artifacts are produced.
- *
- * PR1 implementation note: most options are accepted but only a subset is currently honored.
  */
 export interface CompilerOptions {
     /**
@@ -15,10 +13,25 @@ export interface CompilerOptions {
      * importing source file.
      */
     includeDirs?: string[];
-    /** Primary output path used to derive sibling artifacts (future). */
+    /** Primary output path supplied by wrappers that derive sibling artifacts. */
     outputPath?: string;
-    /** Primary output type (future). */
+    /** Primary output type selected by wrappers such as the CLI. */
     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`). */
@@ -27,7 +40,7 @@ export interface CompilerOptions {
     emitD8m?: boolean;
     /** Emit listing (`.lst`). */
     emitListing?: boolean;
-    /** Emit ASM80-compatible lowered source (`.asm`). */
+    /** Emit ASM80-compatible lowered source (`.z80`). */
     emitAsm80?: boolean;
     /** Optional case-style lint mode for asm keywords/register tokens. */
     caseStyle?: CaseStyleMode;

package/dist/legacy-root-azm/src/z80/effects.d.ts

@@ -0,0 +1,3 @@
+import type { AsmInstructionNode } from '../frontend/ast.js';
+import type { InstructionEffect } from '../registerCare/types.js';
+export declare function getZ80InstructionEffect(inst: AsmInstructionNode): InstructionEffect;