@jhlagado/azm 0.1.0

package/dist/src/sourceLoader.d.ts

@@ -0,0 +1,15 @@
+import type { Diagnostic } from './diagnosticTypes.js';
+import type { ProgramNode } from './frontend/ast.js';
+import type { DirectiveAliasPolicy } from './frontend/directiveAliases.js';
+import type { CompilerOptions } from './pipeline.js';
+export type LoadedProgram = {
+    program: ProgramNode;
+    sourceTexts: Map<string, string>;
+    sourceLineComments: Map<string, Map<number, string>>;
+};
+export interface LoadProgramOptions extends Pick<CompilerOptions, 'includeDirs'> {
+    directiveAliasPolicy?: DirectiveAliasPolicy;
+    preloadedText?: string;
+    signal?: AbortSignal;
+}
+export declare function loadProgram(entryFile: string, diagnostics: Diagnostic[], options: LoadProgramOptions): Promise<LoadedProgram | undefined>;

package/dist/src/sourceLoader.js

@@ -0,0 +1,118 @@
+import { readFile } from 'node:fs/promises';
+import { hasErrors, normalizePath } from './compileShared.js';
+import { DiagnosticIds } from './diagnosticTypes.js';
+import { buildDirectiveAliasPolicy, defaultDirectiveAliasProfileName, } from './frontend/directiveAliases.js';
+import { parseSourceFile } from './frontend/parser.js';
+import { makeSourceFile } from './frontend/source.js';
+import { isSupportedSourcePath } from './frontend/sourceExtensions.js';
+import { expandTextIncludesForFile } from './sourceIncludeExpansion.js';
+function throwIfAborted(signal) {
+    signal?.throwIfAborted();
+}
+async function readSourceFileText(sourcePath, diagnostics, importer, preloadedText, signal) {
+    throwIfAborted(signal);
+    try {
+        return preloadedText ?? (await readFile(sourcePath, 'utf8'));
+    }
+    catch (err) {
+        diagnostics.push({
+            id: DiagnosticIds.IoReadFailed,
+            severity: 'error',
+            message: importer
+                ? `Failed to read included source file "${sourcePath}" (included by "${importer}"): ${String(err)}`
+                : `Failed to read entry file: ${String(err)}`,
+            file: importer ?? sourcePath,
+        });
+        return undefined;
+    }
+}
+function recordSourceLineComments(sourceLineComments, expanded) {
+    const lines = expanded.text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        const semi = line.indexOf(';');
+        if (semi < 0)
+            continue;
+        const commentText = line.slice(semi + 1).trim();
+        if (!commentText)
+            continue;
+        const fileRaw = expanded.lineFiles[i];
+        if (!fileRaw)
+            continue;
+        const file = normalizePath(fileRaw);
+        const lineNo = expanded.lineBaseLines[i] ?? i + 1;
+        let lineMap = sourceLineComments.get(file);
+        if (!lineMap) {
+            lineMap = new Map();
+            sourceLineComments.set(file, lineMap);
+        }
+        lineMap.set(lineNo, commentText);
+    }
+}
+function parseExpandedSourceFile(sourcePath, expanded, diagnostics, aliasPolicy) {
+    try {
+        const sourceFile = makeSourceFile(sourcePath, expanded.text);
+        sourceFile.lineFiles = expanded.lineFiles;
+        sourceFile.lineBaseLines = expanded.lineBaseLines;
+        return parseSourceFile(sourcePath, expanded.text, diagnostics, sourceFile, aliasPolicy);
+    }
+    catch (err) {
+        diagnostics.push({
+            id: DiagnosticIds.InternalParseError,
+            severity: 'error',
+            message: `Internal error during parse: ${String(err)}`,
+            file: sourcePath,
+        });
+        return undefined;
+    }
+}
+export async function loadProgram(entryFile, diagnostics, options) {
+    const entryPath = normalizePath(entryFile);
+    const sourceTexts = new Map();
+    const sourceLineComments = new Map();
+    const includeDirs = (options.includeDirs ?? []).map(normalizePath);
+    const aliasPolicy = options.directiveAliasPolicy ?? buildDirectiveAliasPolicy(defaultDirectiveAliasProfileName());
+    const signal = options.signal;
+    throwIfAborted(signal);
+    const sourceText = await readSourceFileText(entryPath, diagnostics, undefined, options.preloadedText, signal);
+    if (sourceText === undefined)
+        return undefined;
+    sourceTexts.set(entryPath, sourceText);
+    if (!isSupportedSourcePath(entryPath)) {
+        diagnostics.push({
+            id: DiagnosticIds.Unknown,
+            severity: 'error',
+            message: 'Unsupported source file extension (expected .asm or .z80)',
+            file: entryPath,
+        });
+        return undefined;
+    }
+    const expanded = await expandTextIncludesForFile({
+        sourcePath: entryPath,
+        sourceText,
+        includeDirs,
+        diagnostics,
+        sourceTexts,
+        includeStack: [entryPath],
+        ...(aliasPolicy ? { aliasPolicy } : {}),
+        ...(signal ? { signal } : {}),
+    });
+    if (expanded === undefined)
+        return undefined;
+    if (hasErrors(diagnostics))
+        return undefined;
+    const entrySource = parseExpandedSourceFile(entryPath, expanded, diagnostics, aliasPolicy);
+    if (!entrySource)
+        return undefined;
+    recordSourceLineComments(sourceLineComments, expanded);
+    return {
+        program: {
+            kind: 'Program',
+            span: entrySource.span,
+            entryFile: entryPath,
+            files: [entrySource],
+        },
+        sourceTexts,
+        sourceLineComments,
+    };
+}

package/dist/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/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();
+    }
+}

package/dist/src/z80/encode.d.ts

@@ -0,0 +1,10 @@
+import type { Diagnostic } from '../diagnosticTypes.js';
+import type { AsmInstructionNode } from '../frontend/ast.js';
+import type { CompileEnv } from '../semantics/env.js';
+/**
+ * Encode a single `asm` instruction node into Z80 machine-code bytes.
+ *
+ * - Immediate operands may be `imm` expressions (const/enum names and operators), evaluated via the env.
+ * - Unsupported forms append an error diagnostic and return `undefined`.
+ */
+export declare function encodeInstruction(node: AsmInstructionNode, env: CompileEnv, diagnostics: Diagnostic[]): Uint8Array | undefined;