@jhlagado/azm 0.1.1 → 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}/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,14 +68,10 @@ 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.
@@ -170,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.
  */
@@ -209,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/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/{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,9 +13,9 @@ 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.
@@ -42,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;

package/dist/legacy-root-azm/src/z80/effects.js

@@ -0,0 +1,516 @@
+import { expandCarrier } from '../registerCare/carriers.js';
+const FLAG_WRITES = ['sign', 'zero', 'halfCarry', 'parity', 'carry'];
+const INC_DEC_FLAG_WRITES = ['sign', 'zero', 'halfCarry', 'parity'];
+const ROTATE_SHIFT_FLAG_WRITES = [
+    'sign',
+    'zero',
+    'halfCarry',
+    'parity',
+    'carry',
+];
+const BIT_FLAG_WRITES = ['sign', 'zero', 'halfCarry', 'parity'];
+const STACK_POINTER_UNITS = ['SPH', 'SPL'];
+const UNKNOWN_UNITS = [
+    'A',
+    'B',
+    'C',
+    'D',
+    'E',
+    'H',
+    'L',
+    'IXH',
+    'IXL',
+    'IYH',
+    'IYL',
+    'SPH',
+    'SPL',
+    'carry',
+    'zero',
+    'sign',
+    'parity',
+    'halfCarry',
+];
+function baseEffect() {
+    return {
+        reads: [],
+        writes: [],
+        stack: { kind: 'none' },
+        control: { kind: 'fallthrough' },
+    };
+}
+function unknownEffect() {
+    return {
+        reads: UNKNOWN_UNITS,
+        writes: UNKNOWN_UNITS,
+        stack: { kind: 'unknown' },
+        control: { kind: 'unknown' },
+    };
+}
+function appendUnique(out, units) {
+    for (const unit of units) {
+        if (!out.includes(unit))
+            out.push(unit);
+    }
+}
+function concatUnique(...groups) {
+    const out = [];
+    for (const group of groups)
+        appendUnique(out, group);
+    return out;
+}
+function registerUnits(op) {
+    if (!op || op.kind !== 'Reg')
+        return undefined;
+    return expandCarrier(op.name);
+}
+function immName(op) {
+    return op?.kind === 'Imm' && op.expr.kind === 'ImmName' ? op.expr.name : undefined;
+}
+function immLiteral(op) {
+    return op?.kind === 'Imm' && op.expr.kind === 'ImmLiteral' ? op.expr.value : undefined;
+}
+function operandTokenName(op) {
+    if (op?.kind === 'Reg')
+        return op.name.toUpperCase();
+    if (op?.kind === 'Imm' && op.expr.kind === 'ImmName')
+        return op.expr.name.toUpperCase();
+    return undefined;
+}
+function conditionFlagRead(op) {
+    switch (operandTokenName(op)) {
+        case 'Z':
+        case 'NZ':
+            return ['zero'];
+        case 'C':
+        case 'NC':
+            return ['carry'];
+        case 'M':
+        case 'P':
+            return ['sign'];
+        case 'PE':
+        case 'PO':
+            return ['parity'];
+        default:
+            return undefined;
+    }
+}
+function eaReads(ea) {
+    switch (ea.kind) {
+        case 'EaName':
+            return expandCarrier(ea.name) ?? [];
+        case 'EaImm':
+            return [];
+        case 'EaLayoutCast':
+        case 'EaField':
+            return eaReads(ea.base);
+        case 'EaAdd':
+        case 'EaSub':
+            return eaReads(ea.base);
+        case 'EaIndex': {
+            const base = eaReads(ea.base);
+            const index = indexReads(ea.index);
+            if (!base || !index)
+                return undefined;
+            return concatUnique(base, index);
+        }
+        default:
+            return undefined;
+    }
+}
+function indexReads(index) {
+    switch (index.kind) {
+        case 'IndexImm':
+            return [];
+        case 'IndexReg8':
+        case 'IndexReg16':
+            return expandCarrier(index.reg);
+        case 'IndexMemHL':
+            return expandCarrier('HL');
+        case 'IndexMemIxIy':
+            return expandCarrier(index.base);
+        case 'IndexEa':
+            return eaReads(index.expr);
+        default:
+            return undefined;
+    }
+}
+function operandReads(op) {
+    if (!op)
+        return undefined;
+    switch (op.kind) {
+        case 'Reg':
+            return expandCarrier(op.name);
+        case 'Imm':
+            return immReads(op.expr);
+        case 'Ea':
+        case 'Mem':
+            return eaReads(op.expr);
+        case 'PortC':
+            return expandCarrier('C');
+        case 'PortImm8':
+            return immReads(op.expr);
+        default:
+            return undefined;
+    }
+}
+function immReads(expr) {
+    switch (expr.kind) {
+        case 'ImmBinary':
+            return concatUnique(immReads(expr.left), immReads(expr.right));
+        case 'ImmUnary':
+            return immReads(expr.expr);
+        default:
+            return [];
+    }
+}
+function targetName(operands) {
+    if (operands.length === 0)
+        return undefined;
+    return immName(operands[operands.length - 1]);
+}
+function callControl(target, conditional) {
+    return target === undefined
+        ? { kind: 'call', conditional }
+        : { kind: 'call', target, conditional };
+}
+function rstControl(vector) {
+    return vector === undefined ? { kind: 'rst' } : { kind: 'rst', vector };
+}
+function jumpControl(target, conditional) {
+    return target === undefined
+        ? { kind: 'jump', conditional }
+        : { kind: 'jump', target, conditional };
+}
+function isConditionalControl(operands) {
+    return operands.length > 1;
+}
+function ldEffect(inst) {
+    if (inst.operands.length !== 2)
+        return unknownEffect();
+    const dst = inst.operands[0];
+    const src = inst.operands[1];
+    if (!dst || !src)
+        return unknownEffect();
+    const effect = baseEffect();
+    const srcReads = operandReads(src);
+    if (!srcReads)
+        return unknownEffect();
+    if (dst.kind === 'Reg') {
+        const dstWrites = expandCarrier(dst.name);
+        if (!dstWrites)
+            return unknownEffect();
+        effect.reads = srcReads;
+        effect.writes = dstWrites;
+        return effect;
+    }
+    if (dst.kind === 'Mem') {
+        const dstReads = operandReads(dst);
+        if (!dstReads)
+            return unknownEffect();
+        effect.reads = concatUnique(dstReads, srcReads);
+        return effect;
+    }
+    return unknownEffect();
+}
+function unaryOperandEffect(inst, flagWrites) {
+    if (inst.operands.length !== 1)
+        return unknownEffect();
+    const op = inst.operands[0];
+    if (!op)
+        return unknownEffect();
+    const reads = operandReads(op);
+    if (!reads)
+        return unknownEffect();
+    const writes = op.kind === 'Reg' ? registerUnits(op) : [];
+    if (!writes)
+        return unknownEffect();
+    return {
+        ...baseEffect(),
+        reads,
+        writes: concatUnique(writes, flagWrites),
+    };
+}
+function incDecEffect(inst) {
+    return unaryOperandEffect(inst, INC_DEC_FLAG_WRITES);
+}
+function aluEffect(inst) {
+    if (inst.operands.length < 1 || inst.operands.length > 2)
+        return unknownEffect();
+    const first = inst.operands[0];
+    const second = inst.operands[1];
+    const xorSelfZero = inst.head === 'xor' &&
+        second === undefined &&
+        first?.kind === 'Reg' &&
+        first.name.toUpperCase() === 'A';
+    const firstReads = operandReads(first);
+    if (!firstReads)
+        return unknownEffect();
+    let reads;
+    let writes = [];
+    if (second) {
+        const secondReads = operandReads(second);
+        if (!secondReads)
+            return unknownEffect();
+        reads = concatUnique(firstReads, secondReads);
+        if (inst.head !== 'cp' && first?.kind === 'Reg') {
+            const firstWrites = registerUnits(first);
+            if (!firstWrites)
+                return unknownEffect();
+            writes = firstWrites;
+        }
+    }
+    else {
+        const aReads = expandCarrier('A');
+        if (!aReads)
+            return unknownEffect();
+        reads = xorSelfZero ? [] : concatUnique(aReads, firstReads);
+        if (inst.head !== 'cp')
+            writes = aReads;
+    }
+    const carryReads = inst.head === 'adc' || inst.head === 'sbc' ? ['carry'] : [];
+    return {
+        ...baseEffect(),
+        reads: concatUnique(reads, carryReads),
+        writes: concatUnique(writes, FLAG_WRITES),
+    };
+}
+function pushEffect(inst) {
+    if (inst.operands.length !== 1)
+        return unknownEffect();
+    const units = registerUnits(inst.operands[0]);
+    if (!units)
+        return unknownEffect();
+    return {
+        ...baseEffect(),
+        reads: units,
+        writes: STACK_POINTER_UNITS,
+        stack: { kind: 'push', units },
+    };
+}
+function popEffect(inst) {
+    if (inst.operands.length !== 1)
+        return unknownEffect();
+    const units = registerUnits(inst.operands[0]);
+    if (!units)
+        return unknownEffect();
+    return {
+        ...baseEffect(),
+        writes: concatUnique(units, STACK_POINTER_UNITS),
+        stack: { kind: 'pop', units },
+    };
+}
+function controlEffect(control, reads = []) {
+    return {
+        ...baseEffect(),
+        reads,
+        control,
+    };
+}
+function stackControlEffect(control, reads = []) {
+    return {
+        ...controlEffect(control, reads),
+        writes: STACK_POINTER_UNITS,
+        stack: { kind: 'unknown' },
+    };
+}
+function jumpEffect(inst) {
+    const conditional = isConditionalControl(inst.operands);
+    const reads = conditional
+        ? conditionFlagRead(inst.operands[0])
+        : operandReads(inst.operands[inst.operands.length - 1]);
+    if (!reads)
+        return unknownEffect();
+    const effect = controlEffect(jumpControl(targetName(inst.operands), conditional));
+    effect.reads = reads;
+    return effect;
+}
+function callEffect(inst) {
+    const conditional = isConditionalControl(inst.operands);
+    const reads = conditional ? conditionFlagRead(inst.operands[0]) : [];
+    if (!reads)
+        return unknownEffect();
+    return stackControlEffect(callControl(targetName(inst.operands), conditional), reads);
+}
+function retEffect(inst) {
+    const reads = inst.operands.length > 0 ? conditionFlagRead(inst.operands[0]) : [];
+    if (!reads)
+        return unknownEffect();
+    return stackControlEffect({ kind: 'return' }, reads);
+}
+function djnzEffect(inst) {
+    return {
+        ...baseEffect(),
+        reads: ['B'],
+        writes: ['B'],
+        control: jumpControl(targetName(inst.operands), true),
+    };
+}
+function rotateShiftEffect(inst) {
+    return unaryOperandEffect(inst, ROTATE_SHIFT_FLAG_WRITES);
+}
+function accumulatorRotateEffect(head) {
+    const reads = head === 'rla' || head === 'rra' ? ['A', 'carry'] : ['A'];
+    return {
+        ...baseEffect(),
+        reads,
+        writes: ['A', 'carry', 'halfCarry'],
+    };
+}
+function bitEffect(inst) {
+    if (inst.operands.length !== 2)
+        return unknownEffect();
+    const target = inst.operands[1];
+    if (!target)
+        return unknownEffect();
+    const reads = operandReads(target);
+    if (!reads)
+        return unknownEffect();
+    return {
+        ...baseEffect(),
+        reads,
+        writes: BIT_FLAG_WRITES,
+    };
+}
+function outEffect(inst) {
+    if (inst.operands.length !== 2)
+        return unknownEffect();
+    const portReads = operandReads(inst.operands[0]);
+    const valueReads = operandReads(inst.operands[1]);
+    if (!portReads || !valueReads)
+        return unknownEffect();
+    return {
+        ...baseEffect(),
+        reads: concatUnique(portReads, valueReads),
+    };
+}
+function inEffect(inst) {
+    if (inst.operands.length !== 2)
+        return unknownEffect();
+    const target = inst.operands[0];
+    const port = inst.operands[1];
+    if (target?.kind !== 'Reg')
+        return unknownEffect();
+    const writes = registerUnits(target);
+    if (!writes)
+        return unknownEffect();
+    if (port?.kind === 'PortImm8') {
+        return {
+            ...baseEffect(),
+            reads: concatUnique(['A'], operandReads(port) ?? []),
+            writes,
+        };
+    }
+    if (port?.kind === 'PortC') {
+        return {
+            ...baseEffect(),
+            reads: ['C'],
+            writes: concatUnique(writes, BIT_FLAG_WRITES),
+        };
+    }
+    return unknownEffect();
+}
+function blockTransferEffect(inst) {
+    if (inst.operands.length !== 0)
+        return unknownEffect();
+    return {
+        ...baseEffect(),
+        reads: ['H', 'L', 'D', 'E', 'B', 'C'],
+        writes: ['H', 'L', 'D', 'E', 'B', 'C', 'halfCarry', 'parity'],
+    };
+}
+function exEffect(inst) {
+    if (inst.operands.length !== 2)
+        return unknownEffect();
+    const left = inst.operands[0];
+    const right = inst.operands[1];
+    const leftUnits = registerUnits(left);
+    const rightUnits = registerUnits(right);
+    if (!leftUnits || !rightUnits)
+        return unknownEffect();
+    const leftName = left?.kind === 'Reg' ? left.name.toUpperCase() : '';
+    const rightName = right?.kind === 'Reg' ? right.name.toUpperCase() : '';
+    const isDeHl = (leftName === 'DE' && rightName === 'HL') || (leftName === 'HL' && rightName === 'DE');
+    if (!isDeHl)
+        return unknownEffect();
+    return {
+        ...baseEffect(),
+        reads: concatUnique(leftUnits, rightUnits),
+        writes: concatUnique(leftUnits, rightUnits),
+    };
+}
+export function getZ80InstructionEffect(inst) {
+    switch (inst.head.toLowerCase()) {
+        case 'nop':
+        case 'halt':
+        case 'di':
+        case 'ei':
+            return baseEffect();
+        case 'ld':
+            return ldEffect(inst);
+        case 'inc':
+        case 'dec':
+            return incDecEffect(inst);
+        case 'add':
+        case 'adc':
+        case 'sbc':
+        case 'sub':
+        case 'and':
+        case 'or':
+        case 'xor':
+        case 'cp':
+            return aluEffect(inst);
+        case 'push':
+            return pushEffect(inst);
+        case 'pop':
+            return popEffect(inst);
+        case 'call':
+            return callEffect(inst);
+        case 'rst':
+            return stackControlEffect(rstControl(immLiteral(inst.operands[0])));
+        case 'ret':
+        case 'retn':
+        case 'reti':
+            return retEffect(inst);
+        case 'jp':
+        case 'jr':
+            return jumpEffect(inst);
+        case 'djnz':
+            return djnzEffect(inst);
+        case 'rlc':
+        case 'rrc':
+        case 'rl':
+        case 'rr':
+        case 'sla':
+        case 'sra':
+        case 'srl':
+            return rotateShiftEffect(inst);
+        case 'rlca':
+        case 'rrca':
+        case 'rla':
+        case 'rra':
+            return accumulatorRotateEffect(inst.head.toLowerCase());
+        case 'bit':
+            return bitEffect(inst);
+        case 'scf':
+            return { ...baseEffect(), writes: ['carry', 'halfCarry'] };
+        case 'ccf':
+            return { ...baseEffect(), reads: ['carry'], writes: ['carry', 'halfCarry'] };
+        case 'cpl':
+            return { ...baseEffect(), reads: ['A'], writes: ['A', 'halfCarry'] };
+        case 'neg':
+            return { ...baseEffect(), reads: ['A'], writes: concatUnique(['A'], FLAG_WRITES) };
+        case 'out':
+            return outEffect(inst);
+        case 'in':
+            return inEffect(inst);
+        case 'ldi':
+        case 'ldir':
+        case 'ldd':
+        case 'lddr':
+            return blockTransferEffect(inst);
+        case 'ex':
+            return exEffect(inst);
+        default:
+            return unknownEffect();
+    }
+}