@jhlagado/azm 0.1.0

package/dist/src/frontend/asm80/parseAsmRawValues.js

@@ -0,0 +1,94 @@
+import { parseImmExprFromText } from '../parseImm.js';
+import { advanceAsmQuoteScan, createAsmQuoteScanState } from './quoteScan.js';
+export function parseAsmRawValues(path, valuesText, lineSpan, diagnostics, stringEquates) {
+    const out = [];
+    const parts = splitTopLevelComma(valuesText)
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+    for (const part of parts) {
+        const rawString = parseWholeQuotedString(part);
+        if (rawString !== undefined) {
+            if (part[0] === "'" && rawString.length === 1) {
+                const expr = parseImmExprFromText(path, part, lineSpan, diagnostics);
+                if (expr) {
+                    out.push(expr);
+                    continue;
+                }
+            }
+            out.push({ kind: 'AsmString', value: rawString });
+            continue;
+        }
+        const stringEquate = /^[A-Za-z_][A-Za-z0-9_]*$/.exec(part)
+            ? stringEquates.get(part.toLowerCase())
+            : undefined;
+        if (stringEquate !== undefined) {
+            out.push({ kind: 'AsmString', value: stringEquate });
+            continue;
+        }
+        const expr = parseImmExprFromText(path, normalizeDoubleQuotedCharExpr(part), lineSpan, diagnostics);
+        if (expr)
+            out.push(expr);
+    }
+    return out;
+}
+export function parseWholeQuotedString(text) {
+    if (text.length < 2)
+        return undefined;
+    const quote = text[0];
+    if ((quote !== '"' && quote !== "'") || text[text.length - 1] !== quote)
+        return undefined;
+    let value = '';
+    for (let i = 1; i < text.length - 1; i++) {
+        const ch = text[i];
+        if (ch === '\\') {
+            if (i + 1 >= text.length - 1)
+                return undefined;
+            value += text[i + 1];
+            i++;
+            continue;
+        }
+        if (ch === quote)
+            return undefined;
+        value += ch;
+    }
+    return value;
+}
+function normalizeDoubleQuotedCharExpr(text) {
+    return text.replace(/"([^"\\])"/g, (_match, char) => `'${char}'`);
+}
+function splitTopLevelComma(text) {
+    const parts = [];
+    let start = 0;
+    const quoteState = createAsmQuoteScanState();
+    let parenDepth = 0;
+    let bracketDepth = 0;
+    for (let i = 0; i < text.length; i++) {
+        if (advanceAsmQuoteScan(text, i, quoteState))
+            continue;
+        if (quoteState.inString || quoteState.inChar)
+            continue;
+        const ch = text[i];
+        if (ch === '(') {
+            parenDepth++;
+            continue;
+        }
+        if (ch === ')') {
+            parenDepth = Math.max(0, parenDepth - 1);
+            continue;
+        }
+        if (ch === '[') {
+            bracketDepth++;
+            continue;
+        }
+        if (ch === ']') {
+            bracketDepth = Math.max(0, bracketDepth - 1);
+            continue;
+        }
+        if (ch === ',' && parenDepth === 0 && bracketDepth === 0) {
+            parts.push(text.slice(start, i));
+            start = i + 1;
+        }
+    }
+    parts.push(text.slice(start));
+    return parts;
+}

package/dist/src/frontend/asm80/quoteScan.d.ts

@@ -0,0 +1,10 @@
+type AsmQuoteScanState = {
+    inString: boolean;
+    inChar: boolean;
+    escaped: boolean;
+};
+export declare function createAsmQuoteScanState(): AsmQuoteScanState;
+export declare function advanceAsmQuoteScan(text: string, index: number, state: AsmQuoteScanState, options?: {
+    singleQuoteStartsCharAt?: (text: string, index: number) => boolean;
+}): boolean;
+export {};

package/dist/src/frontend/asm80/quoteScan.js

@@ -0,0 +1,25 @@
+export function createAsmQuoteScanState() {
+    return { inString: false, inChar: false, escaped: false };
+}
+export function advanceAsmQuoteScan(text, index, state, options = {}) {
+    const ch = text[index];
+    if (state.escaped) {
+        state.escaped = false;
+        return true;
+    }
+    if ((state.inString || state.inChar) && ch === '\\') {
+        state.escaped = true;
+        return true;
+    }
+    if (!state.inChar && ch === '"') {
+        state.inString = !state.inString;
+        return true;
+    }
+    if (!state.inString &&
+        ch === "'" &&
+        (state.inChar || (options.singleQuoteStartsCharAt?.(text, index) ?? true))) {
+        state.inChar = !state.inChar;
+        return true;
+    }
+    return false;
+}

package/dist/src/frontend/ast.d.ts

@@ -0,0 +1,376 @@
+/**
+ * Frontend AST contracts for AZM.
+ *
+ * This module intentionally defines types/interfaces only (no parsing/semantics).
+ * Later PRs extend these contracts via coordinated changes.
+ */
+export interface SourcePosition {
+    /** 1-based line number. */
+    line: number;
+    /** 1-based column number. */
+    column: number;
+    /** 0-based byte offset in the file. */
+    offset: number;
+}
+/**
+ * Source span with inclusive start and end positions.
+ */
+export interface SourceSpan {
+    /** User-facing file path (as provided on input). */
+    file: string;
+    start: SourcePosition;
+    end: SourcePosition;
+}
+/**
+ * Base shape for all AST nodes.
+ */
+export interface BaseNode {
+    kind: string;
+    span: SourceSpan;
+}
+/**
+ * Parsed compilation unit, including the entry file and all loaded source files.
+ */
+export interface ProgramNode extends BaseNode {
+    kind: 'Program';
+    entryFile: string;
+    files: SourceFileNode[];
+}
+/**
+ * A single AZM source file.
+ */
+export interface SourceFileNode extends BaseNode {
+    kind: 'SourceFile';
+    path: string;
+    items: SourceItemNode[];
+}
+interface AsmEquNode extends BaseNode {
+    kind: 'AsmEqu';
+    name: string;
+    exprText: string;
+}
+interface AsmOrgNode extends BaseNode {
+    kind: 'AsmOrg';
+    exprText: string;
+}
+interface AsmBinFromNode extends BaseNode {
+    kind: 'AsmBinFrom';
+    exprText: string;
+}
+interface AsmBinToNode extends BaseNode {
+    kind: 'AsmBinTo';
+    exprText: string;
+}
+interface AsmEndNode extends BaseNode {
+    kind: 'AsmEnd';
+}
+interface AsmAlignNode extends BaseNode {
+    kind: 'AsmAlign';
+    value: ImmExprNode;
+}
+type AsmRawDataValueNode = ImmExprNode | {
+    kind: 'AsmString';
+    value: string;
+};
+export type AsmRawDataNode = {
+    kind: 'AsmRawData';
+    span: SourceSpan;
+    name?: string;
+    directive: 'db' | 'dw' | 'cstr' | 'pstr' | 'istr';
+    values: AsmRawDataValueNode[];
+    valuesText?: string;
+} | {
+    kind: 'AsmRawData';
+    span: SourceSpan;
+    name?: string;
+    directive: 'ds';
+    values?: AsmRawDataValueNode[];
+    size?: ImmExprNode;
+    fill?: ImmExprNode;
+    valuesText?: string;
+};
+/**
+ * Top-level items permitted in a source file.
+ */
+export type SourceItemNode = AsmEquNode | AsmOrgNode | AsmBinFromNode | AsmBinToNode | AsmEndNode | AsmAlignNode | AsmRawDataNode | AsmLabelNode | AsmInstructionNode | EnumDeclNode | UnionDeclNode | TypeDeclNode | OpDeclNode;
+/**
+ * Packed record layout declaration.
+ */
+export interface TypeDeclNode extends BaseNode {
+    kind: 'TypeDecl';
+    name: string;
+    typeExpr: Extract<TypeExprNode, {
+        kind: 'RecordType';
+    }>;
+}
+/**
+ * Union declaration.
+ */
+export interface UnionDeclNode extends BaseNode {
+    kind: 'UnionDecl';
+    name: string;
+    fields: RecordFieldNode[];
+}
+/**
+ * Enum declaration.
+ */
+export interface EnumDeclNode extends BaseNode {
+    kind: 'EnumDecl';
+    name: string;
+    members: string[];
+}
+/**
+ * `op` (macro-instruction) declaration.
+ */
+export interface OpDeclNode extends BaseNode {
+    kind: 'OpDecl';
+    name: string;
+    params: OpParamNode[];
+    body: AsmBlockNode;
+}
+/**
+ * `op` parameter with a matcher type.
+ */
+export interface OpParamNode extends BaseNode {
+    kind: 'OpParam';
+    name: string;
+    matcher: OpMatcherNode;
+}
+/**
+ * Operand matcher variants for `op` parameters.
+ */
+export type OpMatcherNode = {
+    kind: 'MatcherReg8';
+    span: SourceSpan;
+} | {
+    kind: 'MatcherReg16';
+    span: SourceSpan;
+} | {
+    kind: 'MatcherIdx16';
+    span: SourceSpan;
+} | {
+    kind: 'MatcherCc';
+    span: SourceSpan;
+} | {
+    kind: 'MatcherImm8';
+    span: SourceSpan;
+} | {
+    kind: 'MatcherImm16';
+    span: SourceSpan;
+} | {
+    kind: 'MatcherEa';
+    span: SourceSpan;
+} | {
+    kind: 'MatcherMem8';
+    span: SourceSpan;
+} | {
+    kind: 'MatcherMem16';
+    span: SourceSpan;
+} | {
+    kind: 'MatcherFixed';
+    span: SourceSpan;
+    token: string;
+};
+/**
+ * Instruction stream inside ASM source or an `op` body.
+ */
+export interface AsmBlockNode extends BaseNode {
+    kind: 'AsmBlock';
+    items: AsmItemNode[];
+}
+/**
+ * Items that can appear inside an instruction stream.
+ */
+export type AsmItemNode = AsmInstructionNode | AsmLabelNode;
+/**
+ * Label definition inside an `asm` stream.
+ */
+export interface AsmLabelNode extends BaseNode {
+    kind: 'AsmLabel';
+    name: string;
+    /** True when the source label used the ASM80-style `@Name:` entry marker. */
+    isEntry?: boolean;
+}
+/**
+ * Z80 instruction-like statement inside an `asm` stream.
+ */
+export interface AsmInstructionNode extends BaseNode {
+    kind: 'AsmInstruction';
+    /** Canonical lower-case instruction mnemonic. */
+    head: string;
+    operands: AsmOperandNode[];
+    /** Original unparsed operand tail for ASM80 source preservation. */
+    operandText?: string;
+}
+/**
+ * Operand variants in `asm` instructions.
+ */
+export type AsmOperandNode = {
+    kind: 'Reg';
+    span: SourceSpan; /** Canonical upper-case register token. */
+    name: string;
+} | {
+    kind: 'Imm';
+    span: SourceSpan;
+    expr: ImmExprNode;
+} | {
+    kind: 'Ea';
+    span: SourceSpan;
+    expr: EaExprNode;
+} | {
+    kind: 'Mem';
+    span: SourceSpan;
+    expr: EaExprNode;
+} | {
+    kind: 'PortC';
+    span: SourceSpan;
+} | {
+    kind: 'PortImm8';
+    span: SourceSpan;
+    expr: ImmExprNode;
+};
+/**
+ * Type expression variants.
+ */
+export type TypeExprNode = {
+    kind: 'TypeName';
+    span: SourceSpan;
+    name: string;
+} | {
+    kind: 'ArrayType';
+    span: SourceSpan;
+    element: TypeExprNode;
+    length?: number;
+} | {
+    kind: 'RecordType';
+    span: SourceSpan;
+    fields: RecordFieldNode[];
+};
+/**
+ * Field inside a record type.
+ */
+export interface RecordFieldNode extends BaseNode {
+    kind: 'RecordField';
+    name: string;
+    typeExpr: TypeExprNode;
+}
+/**
+ * Immediate-expression variants.
+ */
+export type ImmExprNode = {
+    kind: 'ImmLiteral';
+    span: SourceSpan;
+    value: number;
+} | {
+    kind: 'ImmCurrentLocation';
+    span: SourceSpan;
+} | {
+    kind: 'ImmName';
+    span: SourceSpan;
+    name: string;
+} | {
+    kind: 'ImmSizeof';
+    span: SourceSpan;
+    typeExpr: TypeExprNode;
+} | {
+    kind: 'ImmOffset';
+    span: SourceSpan;
+    typeExpr: TypeExprNode;
+    path: OffsetPathNode;
+} | {
+    kind: 'ImmUnary';
+    span: SourceSpan;
+    op: '+' | '-' | '~';
+    expr: ImmExprNode;
+} | {
+    kind: 'ImmBinary';
+    span: SourceSpan;
+    op: '*' | '/' | '%' | '+' | '-' | '&' | '^' | '|' | '<<' | '>>';
+    left: ImmExprNode;
+    right: ImmExprNode;
+};
+/**
+ * Effective-address expression variants.
+ */
+export type EaExprNode = {
+    kind: 'EaName';
+    span: SourceSpan;
+    name: string;
+} | {
+    kind: 'EaImm';
+    span: SourceSpan;
+    expr: ImmExprNode;
+} | {
+    kind: 'EaLayoutCast';
+    span: SourceSpan;
+    typeExpr: TypeExprNode;
+    base: EaExprNode;
+} | {
+    kind: 'EaField';
+    span: SourceSpan;
+    base: EaExprNode;
+    field: string;
+} | {
+    kind: 'EaIndex';
+    span: SourceSpan;
+    base: EaExprNode;
+    index: EaIndexNode;
+} | {
+    kind: 'EaAdd';
+    span: SourceSpan;
+    base: EaExprNode;
+    offset: ImmExprNode;
+} | {
+    kind: 'EaSub';
+    span: SourceSpan;
+    base: EaExprNode;
+    offset: ImmExprNode;
+};
+/**
+ * Index expression variants for effective addresses.
+ */
+export type EaIndexNode = {
+    kind: 'IndexImm';
+    span: SourceSpan;
+    value: ImmExprNode;
+} | {
+    kind: 'IndexReg8';
+    span: SourceSpan; /** Canonical upper-case reg8 token. */
+    reg: string;
+} | {
+    kind: 'IndexReg16';
+    span: SourceSpan; /** Canonical upper-case reg16 token. */
+    reg: string;
+} | {
+    kind: 'IndexMemHL';
+    span: SourceSpan;
+} | {
+    kind: 'IndexMemIxIy';
+    span: SourceSpan;
+    /** Canonical upper-case base register token. */
+    base: 'IX' | 'IY';
+    /** Optional displacement imm expression (signed). */
+    disp?: ImmExprNode;
+} | {
+    kind: 'IndexEa';
+    span: SourceSpan;
+    expr: EaExprNode;
+};
+/**
+ * Field path used by the `offset(Type, path)` built-in.
+ */
+export interface OffsetPathNode extends BaseNode {
+    kind: 'OffsetPath';
+    base?: string;
+    steps: OffsetPathStepNode[];
+}
+export type OffsetPathStepNode = {
+    kind: 'OffsetField';
+    span: SourceSpan;
+    name: string;
+} | {
+    kind: 'OffsetIndex';
+    span: SourceSpan;
+    expr: ImmExprNode;
+};
+export {};

package/dist/src/frontend/ast.js

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

package/dist/src/frontend/directiveAliases.d.ts

@@ -0,0 +1,14 @@
+type DirectiveAliasProfileName = 'azm';
+export type DirectiveAliasProfile = {
+    name?: string;
+    extends?: DirectiveAliasProfileName;
+    directiveAliases?: Record<string, string>;
+};
+export type DirectiveAliasPolicy = {
+    directiveAliases: Map<string, string>;
+};
+export declare function defaultDirectiveAliasProfileName(): DirectiveAliasProfileName;
+export declare function buildDirectiveAliasPolicy(profileName: DirectiveAliasProfileName, projectProfiles?: DirectiveAliasProfile[]): DirectiveAliasPolicy;
+export declare function readDirectiveAliasProfile(path: string): Promise<DirectiveAliasProfile>;
+export declare function resolveDirectiveAlias(head: string, policy: DirectiveAliasPolicy | undefined): string | undefined;
+export {};

package/dist/src/frontend/directiveAliases.js

@@ -0,0 +1,189 @@
+import { readFile } from 'node:fs/promises';
+import { TOP_LEVEL_KEYWORDS } from './grammarData.js';
+const RESERVED_INSTRUCTION_HEADS = new Set([
+    'adc',
+    'add',
+    'and',
+    'bit',
+    'call',
+    'ccf',
+    'cp',
+    'cpd',
+    'cpdr',
+    'cpi',
+    'cpir',
+    'cpl',
+    'daa',
+    'dec',
+    'di',
+    'djnz',
+    'ei',
+    'ex',
+    'exx',
+    'halt',
+    'im',
+    'in',
+    'inc',
+    'ind',
+    'indr',
+    'ini',
+    'inir',
+    'jp',
+    'jr',
+    'ld',
+    'ldd',
+    'lddr',
+    'ldi',
+    'ldir',
+    'neg',
+    'nop',
+    'or',
+    'otdr',
+    'otir',
+    'out',
+    'outd',
+    'outi',
+    'pop',
+    'push',
+    'res',
+    'ret',
+    'reti',
+    'retn',
+    'rl',
+    'rla',
+    'rlc',
+    'rlca',
+    'rld',
+    'rr',
+    'rra',
+    'rrc',
+    'rrca',
+    'rrd',
+    'rst',
+    'sbc',
+    'scf',
+    'set',
+    'sla',
+    'sll',
+    'sra',
+    'srl',
+    'sub',
+    'xor',
+]);
+const CANONICAL_DIRECTIVES = new Set([
+    '.align',
+    '.binfrom',
+    '.binto',
+    '.cstr',
+    '.db',
+    '.ds',
+    '.dw',
+    '.end',
+    '.equ',
+    '.include',
+    '.istr',
+    '.org',
+    '.pstr',
+]);
+const BUILTIN_PROFILES = {
+    azm: {
+        name: 'azm',
+        directiveAliases: {
+            ALIGN: '.align',
+            BINFROM: '.binfrom',
+            BINTO: '.binto',
+            CSTR: '.cstr',
+            DB: '.db',
+            DS: '.ds',
+            DW: '.dw',
+            END: '.end',
+            EQU: '.equ',
+            INCLUDE: '.include',
+            ISTR: '.istr',
+            ORG: '.org',
+            PSTR: '.pstr',
+        },
+    },
+};
+export function defaultDirectiveAliasProfileName() {
+    return 'azm';
+}
+function normalizeAliasKey(key) {
+    const trimmed = key.trim();
+    if (!/^[.]?[A-Za-z][A-Za-z0-9_]*$/.test(trimmed))
+        return undefined;
+    return trimmed.replace(/^\./, '').toLowerCase();
+}
+function normalizeAliasTarget(value) {
+    const trimmed = value.trim().toLowerCase();
+    const dotted = trimmed.startsWith('.') ? trimmed : `.${trimmed}`;
+    if (!CANONICAL_DIRECTIVES.has(dotted))
+        return undefined;
+    return dotted;
+}
+function mergeProfile(profile, out, seen, source, baselineKeys = new Set()) {
+    if (profile.extends) {
+        if (seen.has(profile.extends)) {
+            throw new Error(`Directive alias profile cycle at "${profile.extends}"`);
+        }
+        seen.add(profile.extends);
+        mergeProfile(BUILTIN_PROFILES[profile.extends], out, seen, 'builtin', baselineKeys);
+        seen.delete(profile.extends);
+    }
+    for (const [rawKey, rawTarget] of Object.entries(profile.directiveAliases ?? {})) {
+        const key = normalizeAliasKey(rawKey);
+        if (!key)
+            throw new Error(`Invalid directive alias head "${rawKey}"`);
+        if (source === 'project') {
+            if (baselineKeys.has(key)) {
+                throw new Error(`Directive alias "${rawKey}" conflicts with the AZM baseline`);
+            }
+            if (RESERVED_INSTRUCTION_HEADS.has(key)) {
+                throw new Error(`Directive alias "${rawKey}" conflicts with a Z80 instruction`);
+            }
+            if (TOP_LEVEL_KEYWORDS.has(key)) {
+                throw new Error(`Directive alias "${rawKey}" conflicts with an AZM language keyword`);
+            }
+        }
+        const target = normalizeAliasTarget(rawTarget);
+        if (!target)
+            throw new Error(`Invalid directive alias target "${rawTarget}" for "${rawKey}"`);
+        out.set(key, target);
+    }
+}
+export function buildDirectiveAliasPolicy(profileName, projectProfiles = []) {
+    const directiveAliases = new Map();
+    mergeProfile(BUILTIN_PROFILES[profileName], directiveAliases, new Set([profileName]), 'builtin');
+    const baselineKeys = new Set(directiveAliases.keys());
+    for (const profile of projectProfiles) {
+        mergeProfile(profile, directiveAliases, new Set(), 'project', baselineKeys);
+    }
+    return { directiveAliases };
+}
+export async function readDirectiveAliasProfile(path) {
+    const text = await readFile(path, 'utf8');
+    const parsed = JSON.parse(text);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`Directive alias file "${path}" must contain a JSON object`);
+    }
+    const profile = parsed;
+    if (profile.extends !== undefined && profile.extends !== 'azm') {
+        throw new Error(`Unsupported directive alias base "${String(profile.extends)}" in "${path}"`);
+    }
+    if (profile.directiveAliases !== undefined &&
+        (!profile.directiveAliases ||
+            typeof profile.directiveAliases !== 'object' ||
+            Array.isArray(profile.directiveAliases))) {
+        throw new Error(`Directive alias file "${path}" has invalid "directiveAliases"`);
+    }
+    return profile;
+}
+export function resolveDirectiveAlias(head, policy) {
+    const normalized = normalizeAliasKey(head);
+    if (!normalized)
+        return undefined;
+    const dotted = `.${normalized}`;
+    if (head.trim().startsWith('.') && CANONICAL_DIRECTIVES.has(dotted))
+        return dotted;
+    return policy?.directiveAliases.get(normalized);
+}