@jhlagado/azm 0.1.0

package/dist/src/lowering/loweredAsmTypes.d.ts

@@ -0,0 +1,202 @@
+import type { PlacementKind } from './loweringTypes.js';
+export type LoweredAsmStream = {
+    /** Ordered blocks as emitted during lowering (pre-placement). */
+    blocks: LoweredAsmStreamBlock[];
+};
+export type LoweredAsmStreamBlock = {
+    /** Base placement chunk. */
+    kind: 'base';
+    /** Which logical placement this block belongs to. */
+    placement: PlacementKind;
+    /** Lowered items in emission order. */
+    items: LoweredAsmItem[];
+};
+export type LoweredAsmProgram = {
+    /** Blocks with assigned origins after placement. */
+    blocks: LoweredAsmBlock[];
+    /** Optional symbol table snapshot for listings. */
+    symbols?: LoweredAsmSymbol[];
+};
+export type LoweredAsmBlock = {
+    /** Placement-relative block vs absolute-origin blob. */
+    kind: 'placed' | 'absolute';
+    /** Base address for this block’s bytes. */
+    origin: number;
+    /** Code/data placement when `kind === 'placed'`. */
+    placement?: PlacementKind;
+    /** Lowered items. */
+    items: LoweredAsmItem[];
+};
+type LoweredAsmSymbol = {
+    /** Compile-time named constant. */
+    kind: 'constant';
+    /** Constant identifier text. */
+    name: string;
+    /** Folded imm expression. */
+    value: LoweredImmExpr;
+} | {
+    /** Runtime label or reserved-data symbol. */
+    kind: 'label' | 'data' | 'unknown';
+    /** Symbol name. */
+    name: string;
+    /** Address expression (may reference other symbols). */
+    address: LoweredImmExpr;
+};
+export type LoweredAsmItem = {
+    kind: 'label';
+    /** Label name for this position. */
+    name: string;
+} | {
+    kind: 'const';
+    /** Const name. */
+    name: string;
+    /** Const value expression. */
+    value: LoweredImmExpr;
+} | {
+    kind: 'db';
+    /** Byte values. */
+    values: LoweredImmExpr[];
+} | {
+    kind: 'dw';
+    /** Word values. */
+    values: LoweredImmExpr[];
+} | {
+    kind: 'ds';
+    /** Reserve size in bytes. */
+    size: LoweredImmExpr;
+    /** Optional fill byte; omit for undefined fill. */
+    fill?: LoweredImmExpr;
+} | {
+    kind: 'instr';
+    /** Mnemonic head token. */
+    head: string;
+    /** Rendered operands. */
+    operands: LoweredOperand[];
+    /** Encoded bytes when available; omit before encoding. */
+    bytes?: number[];
+} | {
+    kind: 'comment';
+    /** Comment text. */
+    text: string;
+    /** User source comment vs compiler-generated trace. */
+    origin: 'user' | 'generated';
+};
+export type LoweredOperand = {
+    kind: 'reg';
+    /** Canonical register name. */
+    name: string;
+} | {
+    kind: 'imm';
+    /** Immediate subexpression. */
+    expr: LoweredImmExpr;
+} | {
+    kind: 'mem';
+    /** Memory EA expression. */
+    expr: LoweredEaExpr;
+} | {
+    kind: 'ea';
+    /** Standalone EA operand. */
+    expr: LoweredEaExpr;
+} | {
+    kind: 'portImm8';
+    /** 8-bit port immediate. */
+    expr: LoweredImmExpr;
+} | {
+    /** `(C)` port form. */
+    kind: 'portC';
+};
+export type LoweredImmExpr = {
+    kind: 'literal';
+    /** Numeric literal value. */
+    value: number;
+} | {
+    kind: 'symbol';
+    /** Symbol name (may be address-bearing). */
+    name: string;
+    /** Byte offset added to the symbol’s value. */
+    addend: number;
+} | {
+    kind: 'unary';
+    /** Unary operator. */
+    op: '+' | '-' | '~';
+    /** Inner expression. */
+    expr: LoweredImmExpr;
+} | {
+    kind: 'binary';
+    /** Binary operator. */
+    op: '*' | '/' | '%' | '+' | '-' | '&' | '^' | '|' | '<<' | '>>';
+    /** Left operand. */
+    left: LoweredImmExpr;
+    /** Right operand. */
+    right: LoweredImmExpr;
+} | {
+    kind: 'opaque';
+    /** Unparsed / passthrough text for listing. */
+    text: string;
+};
+export type LoweredEaExpr = {
+    kind: 'name';
+    /** Identifier in an EA. */
+    name: string;
+} | {
+    kind: 'imm';
+    /** Nested immediate. */
+    expr: LoweredImmExpr;
+} | {
+    kind: 'layoutCast';
+    /** Target type name for the layout cast. */
+    typeName: string;
+    /** Base EA. */
+    base: LoweredEaExpr;
+} | {
+    kind: 'field';
+    /** Record/union base. */
+    base: LoweredEaExpr;
+    /** Field name. */
+    field: string;
+} | {
+    kind: 'index';
+    /** Array base. */
+    base: LoweredEaExpr;
+    /** Index selector. */
+    index: LoweredIndexExpr;
+} | {
+    kind: 'add';
+    /** Base EA. */
+    base: LoweredEaExpr;
+    /** Positive offset imm. */
+    offset: LoweredImmExpr;
+} | {
+    kind: 'sub';
+    /** Base EA. */
+    base: LoweredEaExpr;
+    /** Subtracted offset imm. */
+    offset: LoweredImmExpr;
+};
+export type LoweredIndexExpr = {
+    kind: 'imm';
+    /** Constant index expression. */
+    value: LoweredImmExpr;
+} | {
+    kind: 'reg8';
+    /** 8-bit index register name. */
+    reg: string;
+} | {
+    kind: 'reg16';
+    /** 16-bit index register name. */
+    reg: string;
+} | {
+    /** `(HL)` addressing form. */
+    kind: 'memHL';
+} | {
+    kind: 'memIxIy';
+    /** Which index register. */
+    base: 'IX' | 'IY';
+    /** Displacement; omit for 0. */
+    disp?: LoweredImmExpr;
+} | {
+    kind: 'ea';
+    /** General EA used as index. */
+    expr: LoweredEaExpr;
+};
+export {};

package/dist/src/lowering/loweredAsmTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/src/lowering/loweredFormat.d.ts

@@ -0,0 +1,3 @@
+import type { LoweredImmExpr } from './loweredAsmTypes.js';
+export declare const formatLoweredNumber: (value: number) => string;
+export declare function formatLoweredImmExpr(expr: LoweredImmExpr): string;

package/dist/src/lowering/loweredFormat.js

@@ -0,0 +1,26 @@
+const toHex = (value, width) => value.toString(16).toUpperCase().padStart(width, '0');
+export const formatLoweredNumber = (value) => {
+    if (value < 0) {
+        const abs = Math.abs(value);
+        return `-$${toHex(abs, abs > 0xff ? 4 : 2)}`;
+    }
+    return `$${toHex(value, value > 0xff ? 4 : 2)}`;
+};
+export function formatLoweredImmExpr(expr) {
+    switch (expr.kind) {
+        case 'literal':
+            return formatLoweredNumber(expr.value);
+        case 'symbol': {
+            if (expr.addend === 0)
+                return expr.name;
+            const addend = formatLoweredNumber(Math.abs(expr.addend));
+            return expr.addend > 0 ? `${expr.name}+${addend}` : `${expr.name}-${addend}`;
+        }
+        case 'unary':
+            return `${expr.op}${formatLoweredImmExpr(expr.expr)}`;
+        case 'binary':
+            return `(${formatLoweredImmExpr(expr.left)} ${expr.op} ${formatLoweredImmExpr(expr.right)})`;
+        case 'opaque':
+            return expr.text;
+    }
+}

package/dist/src/lowering/loweredItemSize.d.ts

@@ -0,0 +1,4 @@
+import type { LoweredAsmItem, LoweredImmExpr } from './loweredAsmTypes.js';
+type LoweredSizeEvaluator = (expr: LoweredImmExpr) => number | undefined;
+export declare function loweredItemSize(item: LoweredAsmItem, evalSize?: LoweredSizeEvaluator): number;
+export {};

package/dist/src/lowering/loweredItemSize.js

@@ -0,0 +1,17 @@
+const literalSize = (expr) => expr.kind === 'literal' ? expr.value : undefined;
+export function loweredItemSize(item, evalSize = literalSize) {
+    switch (item.kind) {
+        case 'label':
+        case 'const':
+        case 'comment':
+            return 0;
+        case 'db':
+            return item.values.length;
+        case 'dw':
+            return item.values.length * 2;
+        case 'ds':
+            return Math.max(0, evalSize(item.size) ?? 0);
+        case 'instr':
+            return item.bytes?.length ?? 0;
+    }
+}

package/dist/src/lowering/loweringDiagnostics.d.ts

@@ -0,0 +1,9 @@
+import type { Diagnostic, DiagnosticId } from '../diagnosticTypes.js';
+import type { SourceSpan } from '../frontend/ast.js';
+export declare function diag(diagnostics: Diagnostic[], file: string, message: string): void;
+/** Encoder-time diagnostic with stable {@link DiagnosticIds.EncodeError} id and source span. */
+export declare function diagEncodeAt(diagnostics: Diagnostic[], span: SourceSpan, message: string): void;
+export declare function diagAt(diagnostics: Diagnostic[], span: SourceSpan, message: string): void;
+export declare function diagAtWithId(diagnostics: Diagnostic[], span: SourceSpan, id: DiagnosticId, message: string): void;
+export declare function diagAtWithSeverityAndId(diagnostics: Diagnostic[], span: SourceSpan, id: DiagnosticId, severity: 'error' | 'warning', message: string): void;
+export declare function warnAt(diagnostics: Diagnostic[], span: SourceSpan, message: string): void;

package/dist/src/lowering/loweringDiagnostics.js

@@ -0,0 +1,55 @@
+import { DiagnosticIds } from '../diagnosticTypes.js';
+export function diag(diagnostics, file, message) {
+    diagnostics.push({ id: DiagnosticIds.EmitError, severity: 'error', message, file });
+}
+/** Encoder-time diagnostic with stable {@link DiagnosticIds.EncodeError} id and source span. */
+export function diagEncodeAt(diagnostics, span, message) {
+    diagnostics.push({
+        id: DiagnosticIds.EncodeError,
+        severity: 'error',
+        message,
+        file: span.file,
+        line: span.start.line,
+        column: span.start.column,
+    });
+}
+export function diagAt(diagnostics, span, message) {
+    diagnostics.push({
+        id: DiagnosticIds.EmitError,
+        severity: 'error',
+        message,
+        file: span.file,
+        line: span.start.line,
+        column: span.start.column,
+    });
+}
+export function diagAtWithId(diagnostics, span, id, message) {
+    diagnostics.push({
+        id,
+        severity: 'error',
+        message,
+        file: span.file,
+        line: span.start.line,
+        column: span.start.column,
+    });
+}
+export function diagAtWithSeverityAndId(diagnostics, span, id, severity, message) {
+    diagnostics.push({
+        id,
+        severity,
+        message,
+        file: span.file,
+        line: span.start.line,
+        column: span.start.column,
+    });
+}
+export function warnAt(diagnostics, span, message) {
+    diagnostics.push({
+        id: DiagnosticIds.EmitWarning,
+        severity: 'warning',
+        message,
+        file: span.file,
+        line: span.start.line,
+        column: span.start.column,
+    });
+}

package/dist/src/lowering/loweringTypes.d.ts

@@ -0,0 +1,27 @@
+import type { TypeExprNode } from '../frontend/ast.js';
+import type { EmittedSourceSegment } from '../formats/types.js';
+export type PlacementKind = 'code' | 'data';
+export type PendingSymbol = {
+    /** What kind of symbol is pending resolution. */
+    kind: 'label' | 'data';
+    /** Declared name (not yet bound to an address). */
+    name: string;
+    /** Target placement for the symbol. */
+    placement: PlacementKind;
+    /** Tentative offset within the placement; refined at finalize. */
+    offset: number;
+    /** Source file when known; omit for synthetic entries. */
+    file?: string;
+    /** 1-based source line when known. */
+    line?: number;
+    /** Local vs global source scope when applicable. */
+    scope?: 'global' | 'local';
+    /** Byte size for data when known. */
+    size?: number;
+};
+export type SourceSegmentTag = Omit<EmittedSourceSegment, 'start' | 'end'>;
+/** Array shape extracted for lowering; `length` omitted when unknown. */
+export type ResolvedArrayType = {
+    element: TypeExprNode;
+    length?: number;
+};

package/dist/src/lowering/loweringTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/src/lowering/opCandidateRegistry.d.ts

@@ -0,0 +1,9 @@
+import type { OpDeclNode } from '../frontend/ast.js';
+type OpCandidateRegistryContext = {
+    /** Per-file op overload lists keyed by lowercased op name. */
+    localOpsByFile: Map<string, Map<string, OpDeclNode[]>>;
+};
+export declare function createOpCandidateRegistryHelpers(ctx: OpCandidateRegistryContext): {
+    resolveOpCandidatesForFile: (name: string, file: string) => OpDeclNode[] | undefined;
+};
+export {};

package/dist/src/lowering/opCandidateRegistry.js

@@ -0,0 +1,9 @@
+export function createOpCandidateRegistryHelpers(ctx) {
+    const resolveOpCandidatesForFile = (name, file) => {
+        const lower = name.toLowerCase();
+        return ctx.localOpsByFile.get(file)?.get(lower);
+    };
+    return {
+        resolveOpCandidatesForFile,
+    };
+}

package/dist/src/lowering/opExpansionExecution.d.ts

@@ -0,0 +1,15 @@
+import type { AsmItemNode, AsmOperandNode, OpDeclNode } from '../frontend/ast.js';
+import type { AsmRangeLoweringCapability, HiddenLabelCapability, LoweringDiagnosticsCapability } from './capabilities.js';
+type OpExpansionExecutionContext = LoweringDiagnosticsCapability & HiddenLabelCapability & AsmRangeLoweringCapability;
+type ExpandAndLowerArgs = {
+    opDecl: OpDeclNode;
+    substituteOperandWithOpLabels: (operand: AsmOperandNode, localLabelMap: Map<string, string>) => AsmOperandNode;
+};
+type ExpandInlineOpBodyItemsArgs = ExpandAndLowerArgs & {
+    allocateLocalLabel: (labelName: string, opDecl: OpDeclNode) => string;
+};
+export declare function expandInlineOpBodyItems({ opDecl, allocateLocalLabel, substituteOperandWithOpLabels, }: ExpandInlineOpBodyItemsArgs): AsmItemNode[];
+export declare function createOpExpansionExecutionHelpers(ctx: OpExpansionExecutionContext): {
+    expandAndLowerOpBody: ({ opDecl, substituteOperandWithOpLabels, }: ExpandAndLowerArgs) => void;
+};
+export {};

package/dist/src/lowering/opExpansionExecution.js

@@ -0,0 +1,45 @@
+export function expandInlineOpBodyItems({ opDecl, allocateLocalLabel, substituteOperandWithOpLabels, }) {
+    const localLabelMap = new Map();
+    for (const bodyItem of opDecl.body.items) {
+        if (bodyItem.kind !== 'AsmLabel')
+            continue;
+        const key = bodyItem.name.toLowerCase();
+        if (!localLabelMap.has(key)) {
+            localLabelMap.set(key, allocateLocalLabel(bodyItem.name, opDecl));
+        }
+    }
+    return opDecl.body.items.map((bodyItem) => {
+        if (bodyItem.kind === 'AsmInstruction') {
+            return {
+                kind: 'AsmInstruction',
+                span: bodyItem.span,
+                head: bodyItem.head,
+                operands: bodyItem.operands.map((operand) => substituteOperandWithOpLabels(operand, localLabelMap)),
+            };
+        }
+        if (bodyItem.kind === 'AsmLabel') {
+            return {
+                kind: 'AsmLabel',
+                span: bodyItem.span,
+                name: localLabelMap.get(bodyItem.name.toLowerCase()) ?? bodyItem.name,
+            };
+        }
+        return bodyItem;
+    });
+}
+export function createOpExpansionExecutionHelpers(ctx) {
+    const expandAndLowerOpBody = ({ opDecl, substituteOperandWithOpLabels, }) => {
+        const expandedItems = expandInlineOpBodyItems({
+            opDecl,
+            allocateLocalLabel: () => ctx.newHiddenLabel(`__azm_op_${opDecl.name.toLowerCase()}_lbl`),
+            substituteOperandWithOpLabels,
+        });
+        const consumed = ctx.lowerAsmRange(expandedItems, 0, new Set());
+        if (consumed < expandedItems.length) {
+            ctx.diagAt(ctx.diagnostics, expandedItems[consumed].span, 'Internal control-flow lowering error.');
+        }
+    };
+    return {
+        expandAndLowerOpBody,
+    };
+}

package/dist/src/lowering/opExpansionOrchestration.d.ts

@@ -0,0 +1,15 @@
+import type { AsmInstructionNode, SourceSpan } from '../frontend/ast.js';
+import type { AsmRangeLoweringCapability, AstCloneCapability, CompileEnvCapability, DottedEaNameCapability, FixedTokenNormalizationCapability, FlowSyncCapability, HiddenLabelCapability, InverseConditionCapability, LoweringDiagnosticsWithSeverityCapability, OpCandidateResolverCapability, OpOperandFormattingCapability, OpOverloadSelectionCapability } from './capabilities.js';
+type OpExpansionStackEntry = {
+    key: string;
+    name: string;
+    declSpan: SourceSpan;
+    callSiteSpan: SourceSpan;
+};
+type OpExpansionOrchestrationContext = LoweringDiagnosticsWithSeverityCapability & CompileEnvCapability & OpCandidateResolverCapability & OpOperandFormattingCapability & OpOverloadSelectionCapability & AstCloneCapability & DottedEaNameCapability & FixedTokenNormalizationCapability & InverseConditionCapability & HiddenLabelCapability & AsmRangeLoweringCapability & FlowSyncCapability & {
+    opExpansionStack: OpExpansionStackEntry[];
+};
+export declare function createOpExpansionOrchestrationHelpers(ctx: OpExpansionOrchestrationContext): {
+    tryHandleOpExpansion: (asmItem: AsmInstructionNode) => boolean;
+};
+export {};

package/dist/src/lowering/opExpansionOrchestration.js

@@ -0,0 +1,88 @@
+import { DiagnosticIds } from '../diagnosticTypes.js';
+import { createOpExpansionExecutionHelpers } from './opExpansionExecution.js';
+import { createOpSubstitutionHelpers } from './opSubstitution.js';
+export function createOpExpansionOrchestrationHelpers(ctx) {
+    const tryHandleOpExpansion = (asmItem) => {
+        const opCandidates = ctx.resolveOpCandidates(asmItem.head, asmItem.span.file);
+        if (!opCandidates || opCandidates.length === 0)
+            return false;
+        const selection = ctx.selectOpOverload(opCandidates, asmItem.operands);
+        if (selection.kind === 'arity_mismatch') {
+            const available = selection.signatures.map((signature) => `  - ${signature}`).join('\n');
+            ctx.diagAtWithId(ctx.diagnostics, asmItem.span, DiagnosticIds.OpArityMismatch, `No op overload of "${asmItem.head}" accepts ${asmItem.operands.length} operand(s).\n` +
+                `available overloads:\n${available}`);
+            return true;
+        }
+        if (selection.kind === 'no_match') {
+            const operandSummary = asmItem.operands.map(ctx.formatAsmOperandForOpDiag).join(', ');
+            const available = selection.mismatchDetails.map((detail) => `  - ${detail}`).join('\n');
+            ctx.diagAtWithId(ctx.diagnostics, asmItem.span, DiagnosticIds.OpNoMatchingOverload, `No matching op overload for "${asmItem.head}" with provided operands.\n` +
+                `call-site operands: (${operandSummary})\n` +
+                `available overloads:\n${available}`);
+            return true;
+        }
+        if (selection.kind === 'ambiguous') {
+            const operandSummary = asmItem.operands.map(ctx.formatAsmOperandForOpDiag).join(', ');
+            const equallySpecific = selection.definitions
+                .map((definition) => `  - ${definition}`)
+                .join('\n');
+            ctx.diagAtWithId(ctx.diagnostics, asmItem.span, DiagnosticIds.OpAmbiguousOverload, `Ambiguous op overload for "${asmItem.head}" (${selection.overloads.length} matches).\n` +
+                `call-site operands: (${operandSummary})\n` +
+                `equally specific candidates:\n${equallySpecific}`);
+            return true;
+        }
+        const opDecl = selection.overload;
+        const opKey = opDecl.name.toLowerCase();
+        const cycleStart = ctx.opExpansionStack.findIndex((entry) => entry.key === opKey);
+        if (cycleStart !== -1) {
+            const cycleChain = [
+                ...ctx.opExpansionStack
+                    .slice(cycleStart)
+                    .map((entry) => `${entry.name} (${entry.declSpan.file}:${entry.declSpan.start.line})`),
+                `${opDecl.name} (${opDecl.span.file}:${opDecl.span.start.line})`,
+            ].join(' -> ');
+            ctx.diagAtWithId(ctx.diagnostics, asmItem.span, DiagnosticIds.OpExpansionCycle, `Cyclic op expansion detected for "${opDecl.name}".\n` + `expansion chain: ${cycleChain}`);
+            return true;
+        }
+        const bindings = new Map();
+        for (let idx = 0; idx < opDecl.params.length; idx++) {
+            bindings.set(opDecl.params[idx].name.toLowerCase(), asmItem.operands[idx]);
+        }
+        const { substituteOperandWithOpLabels } = createOpSubstitutionHelpers({
+            bindings,
+            env: ctx.env,
+            diagnostics: ctx.diagnostics,
+            diagAt: ctx.diagAt,
+            cloneImmExpr: ctx.cloneImmExpr,
+            cloneEaExpr: ctx.cloneEaExpr,
+            cloneOperand: ctx.cloneOperand,
+            flattenEaDottedName: ctx.flattenEaDottedName,
+        });
+        ctx.opExpansionStack.push({
+            key: opKey,
+            name: opDecl.name,
+            declSpan: opDecl.span,
+            callSiteSpan: asmItem.span,
+        });
+        try {
+            const { expandAndLowerOpBody } = createOpExpansionExecutionHelpers({
+                diagnostics: ctx.diagnostics,
+                diagAt: ctx.diagAt,
+                newHiddenLabel: ctx.newHiddenLabel,
+                lowerAsmRange: ctx.lowerAsmRange,
+            });
+            expandAndLowerOpBody({
+                opDecl,
+                substituteOperandWithOpLabels,
+            });
+        }
+        finally {
+            ctx.opExpansionStack.pop();
+        }
+        ctx.syncToFlow();
+        return true;
+    };
+    return {
+        tryHandleOpExpansion,
+    };
+}

package/dist/src/lowering/opExpansionStream.d.ts

@@ -0,0 +1,12 @@
+import type { AsmInstructionNode, AsmLabelNode, ProgramNode } from '../frontend/ast.js';
+type ExpandedOpStreamItem = {
+    kind: 'label';
+    label: AsmLabelNode;
+} | {
+    kind: 'instruction';
+    instruction: AsmInstructionNode;
+};
+export declare function createInlineOpInstructionStreamExpander(program: ProgramNode): {
+    expandInstruction: (inst: AsmInstructionNode) => ExpandedOpStreamItem[];
+};
+export {};