@jhlagado/azm 0.1.0

package/dist/src/compile.js

@@ -0,0 +1,175 @@
+import { dirname, extname } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { analyzeLoadedProgram } from './analysis.js';
+import { hasErrors, normalizePath } from './compileShared.js';
+import { DiagnosticIds } from './diagnosticTypes.js';
+import { buildDirectiveAliasPolicy, defaultDirectiveAliasProfileName, readDirectiveAliasProfile, } from './frontend/directiveAliases.js';
+import { isSupportedSourcePath } from './frontend/sourceExtensions.js';
+import { emitProgram } from './lowering/emit.js';
+import { loadProgram } from './sourceLoader.js';
+import { analyzeRegisterCare } from './registerCare/analyze.js';
+import { parseInterfaceContracts } from './registerCare/smartComments.js';
+function withDefaults(options) {
+    const anyPrimaryEmitSpecified = [options.emitBin, options.emitHex, options.emitD8m].some((v) => v !== undefined);
+    const emitBin = anyPrimaryEmitSpecified ? (options.emitBin ?? false) : true;
+    const emitHex = anyPrimaryEmitSpecified ? (options.emitHex ?? false) : true;
+    const emitD8m = anyPrimaryEmitSpecified ? (options.emitD8m ?? false) : true;
+    // Listing is a sidecar artifact: default to on unless explicitly suppressed.
+    const emitListing = options.emitListing ?? true;
+    const emitAsm80 = options.emitAsm80 ?? false;
+    return { emitBin, emitHex, emitD8m, emitListing, emitAsm80 };
+}
+/**
+ * Compile an AZM/ASM80-family program starting from an entry file.
+ *
+ * - Expands textual includes transitively with deterministic cycle checks.
+ * - Runs parse → semantics → lowering → format writers.
+ * - Produces artifacts in-memory via `deps.formats`.
+ * - Defaults to emitting BIN + HEX + D8M unless an emit flag is explicitly provided.
+ */
+export const compile = async (entryFile, options, deps) => {
+    const entryPath = normalizePath(entryFile);
+    const diagnostics = [];
+    const artifacts = [];
+    if (!isSupportedSourcePath(entryPath)) {
+        diagnostics.push({
+            id: DiagnosticIds.Unknown,
+            severity: 'error',
+            message: 'Unsupported source file extension (expected .asm or .z80)',
+            file: entryPath,
+        });
+        return { diagnostics, artifacts };
+    }
+    const projectAliasProfiles = [];
+    for (const path of options.directiveAliasFiles ?? []) {
+        projectAliasProfiles.push(await readDirectiveAliasProfile(normalizePath(path)));
+    }
+    const directiveAliasPolicy = buildDirectiveAliasPolicy(defaultDirectiveAliasProfileName(), projectAliasProfiles);
+    const loaded = await loadProgram(entryPath, diagnostics, {
+        ...options,
+        directiveAliasPolicy,
+    });
+    if (!loaded)
+        return { diagnostics, artifacts };
+    const { program, sourceTexts, sourceLineComments } = loaded;
+    if (hasErrors(diagnostics)) {
+        return { diagnostics, artifacts };
+    }
+    const analysis = analyzeLoadedProgram(loaded, {
+        ...(options.caseStyle !== undefined ? { caseStyle: options.caseStyle } : {}),
+        ...(options.requireMain !== undefined ? { requireMain: options.requireMain } : {}),
+    });
+    diagnostics.push(...analysis.diagnostics);
+    if (hasErrors(diagnostics) || !analysis.env)
+        return { diagnostics, artifacts };
+    const env = analysis.env;
+    const registerCareMode = options.registerCare ?? 'off';
+    const shouldAnalyzeRegisterCare = registerCareMode !== 'off' ||
+        options.emitRegisterReport === true ||
+        options.emitRegisterInterface === true ||
+        options.emitRegisterAnnotations === true ||
+        options.fixRegisterContracts === true ||
+        (options.acceptRegisterOutputCandidates?.length ?? 0) > 0 ||
+        (options.registerCareInterfaces?.length ?? 0) > 0;
+    if (shouldAnalyzeRegisterCare) {
+        const interfaceContracts = [];
+        for (const path of options.registerCareInterfaces ?? []) {
+            const resolved = normalizePath(path);
+            if (extname(resolved).toLowerCase() !== '.asmi') {
+                diagnostics.push({
+                    id: DiagnosticIds.Unknown,
+                    severity: 'error',
+                    message: 'Register-care interface files must use the .asmi extension',
+                    file: resolved,
+                });
+                continue;
+            }
+            const text = await readFile(resolved, 'utf8');
+            interfaceContracts.push(...parseInterfaceContracts(text, resolved).values());
+        }
+        if (hasErrors(diagnostics))
+            return { diagnostics, artifacts };
+        const registerCare = analyzeRegisterCare(loaded, {
+            mode: registerCareMode,
+            emitReport: options.emitRegisterReport === true,
+            emitInterface: options.emitRegisterInterface === true,
+            emitAnnotations: options.emitRegisterAnnotations === true || options.fixRegisterContracts === true,
+            fixRegisterContracts: options.fixRegisterContracts === true,
+            ...(options.acceptRegisterOutputCandidates !== undefined
+                ? { acceptOutputCandidates: options.acceptRegisterOutputCandidates }
+                : {}),
+            ...(options.registerCareProfile !== undefined
+                ? { profile: options.registerCareProfile }
+                : {}),
+            ...(interfaceContracts.length > 0 ? { interfaceContracts } : {}),
+        });
+        diagnostics.push(...registerCare.diagnostics);
+        if (registerCare.reportText !== undefined) {
+            artifacts.push({ kind: 'register-care-report', text: registerCare.reportText });
+        }
+        if (registerCare.interfaceText !== undefined) {
+            artifacts.push({ kind: 'register-care-interface', text: registerCare.interfaceText });
+        }
+        if (registerCare.annotatedFiles !== undefined) {
+            artifacts.push({ kind: 'register-care-annotations', files: registerCare.annotatedFiles });
+        }
+        if (hasErrors(diagnostics)) {
+            return { diagnostics, artifacts };
+        }
+    }
+    const { map, symbols, placedLoweredAsmProgram } = emitProgram(program, env, diagnostics, {
+        ...(options.includeDirs ? { includeDirs: options.includeDirs } : {}),
+        ...(options.defaultCodeBase !== undefined ? { defaultCodeBase: options.defaultCodeBase } : {}),
+        sourceTexts,
+        sourceLineComments,
+    });
+    if (hasErrors(diagnostics)) {
+        return { diagnostics, artifacts };
+    }
+    const emit = withDefaults(options);
+    if (emit.emitBin) {
+        artifacts.push(deps.formats.writeBin(map, symbols));
+    }
+    if (emit.emitHex) {
+        artifacts.push(deps.formats.writeHex(map, symbols));
+    }
+    if (emit.emitD8m) {
+        const mainEntry = symbols.find((s) => s.kind === 'label' && s.name.toLowerCase() === 'main');
+        artifacts.push(deps.formats.writeD8m(map, symbols, {
+            rootDir: dirname(entryPath),
+            ...(mainEntry
+                ? {
+                    entrySymbol: mainEntry.name,
+                    entryAddress: mainEntry.address & 0xffff,
+                }
+                : {}),
+        }));
+    }
+    if (emit.emitListing) {
+        if (deps.formats.writeListing) {
+            artifacts.push(deps.formats.writeListing(map, symbols));
+        }
+        else {
+            diagnostics.push({
+                id: DiagnosticIds.Unknown,
+                severity: 'warning',
+                message: 'emitListing=true but no listing writer is configured; skipping .lst artifact.',
+                file: program.entryFile,
+            });
+        }
+    }
+    if (emit.emitAsm80) {
+        if (deps.formats.writeAsm80) {
+            artifacts.push(deps.formats.writeAsm80(placedLoweredAsmProgram));
+        }
+        else {
+            diagnostics.push({
+                id: DiagnosticIds.Unknown,
+                severity: 'warning',
+                message: 'emitAsm80=true but no asm80 writer is configured; skipping .asm artifact.',
+                file: program.entryFile,
+            });
+        }
+    }
+    return { diagnostics, artifacts };
+};

package/dist/src/compileShared.d.ts

@@ -0,0 +1,3 @@
+import type { Diagnostic } from './diagnosticTypes.js';
+export declare function hasErrors(diagnostics: Diagnostic[]): boolean;
+export declare function normalizePath(p: string): string;

package/dist/src/compileShared.js

@@ -0,0 +1,7 @@
+import { resolve } from 'node:path';
+export function hasErrors(diagnostics) {
+    return diagnostics.some((d) => d.severity === 'error');
+}
+export function normalizePath(p) {
+    return resolve(p);
+}

package/dist/src/diagnosticTypes.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Severity level for a diagnostic.
+ */
+export type DiagnosticSeverity = 'error' | 'warning' | 'info';
+/**
+ * A compiler diagnostic (error/warning/info) with an optional source location.
+ *
+ * Diagnostics must have stable IDs so downstream tooling can rely on them.
+ */
+export interface Diagnostic {
+    /** Stable diagnostic identifier (e.g., `AZM001`). */
+    id: DiagnosticId;
+    severity: DiagnosticSeverity;
+    message: string;
+    file: string;
+    /** 1-based line number, when known. */
+    line?: number;
+    /** 1-based column number, when known. */
+    column?: number;
+}
+/**
+ * Known diagnostic IDs.
+ *
+ * PR0 started with a minimal set; later PRs should extend this via contract changes.
+ */
+export declare const DiagnosticIds: {
+    /**
+     * Unknown/unclassified diagnostic.
+     *
+     * Use a more specific ID when possible; this remains for forward compatibility.
+     */
+    readonly Unknown: "AZM000";
+    /** Failed to read a source file from disk. */
+    readonly IoReadFailed: "AZM001";
+    /** Internal error during parsing (unexpected exception). */
+    readonly InternalParseError: "AZM002";
+    /** Include could not be resolved on any search path. */
+    readonly IncludeNotFound: "AZM003";
+    /** Generic parse error (syntax / unsupported in current PR subset). */
+    readonly ParseError: "AZM100";
+    /** Generic instruction encoding error (unsupported mnemonic/operands, out-of-range imm, etc.). */
+    readonly EncodeError: "AZM200";
+    /** Generic emission/lowering error (layout/packing/symbol collisions, etc.). */
+    readonly EmitError: "AZM300";
+    /** Generic emission/lowering warning. */
+    readonly EmitWarning: "AZM301";
+    /** Op invocation arity mismatch against available overload set. */
+    readonly OpArityMismatch: "AZM310";
+    /** No overload match for an op invocation with the provided operands. */
+    readonly OpNoMatchingOverload: "AZM311";
+    /** Ambiguous overload resolution for an op invocation. */
+    readonly OpAmbiguousOverload: "AZM312";
+    /** Cyclic op expansion detected in inline expansion graph. */
+    readonly OpExpansionCycle: "AZM313";
+    /** Op expansion produced an invalid concrete instruction after substitution. */
+    readonly OpInvalidExpansion: "AZM314";
+    /** Generic semantic evaluation error (env building, imm evaluation, etc.). */
+    readonly SemanticsError: "AZM400";
+    /** Divide by zero in an imm expression. */
+    readonly ImmDivideByZero: "AZM401";
+    /** Modulo by zero in an imm expression. */
+    readonly ImmModuloByZero: "AZM402";
+    /** Type/layout error (unknown type, recursion, missing array length, etc.). */
+    readonly TypeError: "AZM403";
+    /** Case-style lint warning for keyword/register casing policy. */
+    readonly CaseStyleLint: "AZM500";
+    /** Redundant outer parentheses in a constant-only array index expression. */
+    readonly IndexParenRedundant: "AZM501";
+    /** Register-care conflict where a call may destroy a live caller value. */
+    readonly RegisterCareConflict: "AZM600";
+    /** Register-care analysis cannot prove an external or indirect call contract. */
+    readonly RegisterCareUnknownBoundary: "AZM601";
+};
+/**
+ * Union type of all defined diagnostic IDs.
+ */
+export type DiagnosticId = (typeof DiagnosticIds)[keyof typeof DiagnosticIds];

package/dist/src/diagnosticTypes.js

@@ -0,0 +1,53 @@
+/**
+ * Known diagnostic IDs.
+ *
+ * PR0 started with a minimal set; later PRs should extend this via contract changes.
+ */
+export const DiagnosticIds = {
+    /**
+     * Unknown/unclassified diagnostic.
+     *
+     * Use a more specific ID when possible; this remains for forward compatibility.
+     */
+    Unknown: 'AZM000',
+    /** Failed to read a source file from disk. */
+    IoReadFailed: 'AZM001',
+    /** Internal error during parsing (unexpected exception). */
+    InternalParseError: 'AZM002',
+    /** Include could not be resolved on any search path. */
+    IncludeNotFound: 'AZM003',
+    /** Generic parse error (syntax / unsupported in current PR subset). */
+    ParseError: 'AZM100',
+    /** Generic instruction encoding error (unsupported mnemonic/operands, out-of-range imm, etc.). */
+    EncodeError: 'AZM200',
+    /** Generic emission/lowering error (layout/packing/symbol collisions, etc.). */
+    EmitError: 'AZM300',
+    /** Generic emission/lowering warning. */
+    EmitWarning: 'AZM301',
+    /** Op invocation arity mismatch against available overload set. */
+    OpArityMismatch: 'AZM310',
+    /** No overload match for an op invocation with the provided operands. */
+    OpNoMatchingOverload: 'AZM311',
+    /** Ambiguous overload resolution for an op invocation. */
+    OpAmbiguousOverload: 'AZM312',
+    /** Cyclic op expansion detected in inline expansion graph. */
+    OpExpansionCycle: 'AZM313',
+    /** Op expansion produced an invalid concrete instruction after substitution. */
+    OpInvalidExpansion: 'AZM314',
+    /** Generic semantic evaluation error (env building, imm evaluation, etc.). */
+    SemanticsError: 'AZM400',
+    /** Divide by zero in an imm expression. */
+    ImmDivideByZero: 'AZM401',
+    /** Modulo by zero in an imm expression. */
+    ImmModuloByZero: 'AZM402',
+    /** Type/layout error (unknown type, recursion, missing array length, etc.). */
+    TypeError: 'AZM403',
+    /** Case-style lint warning for keyword/register casing policy. */
+    CaseStyleLint: 'AZM500',
+    /** Redundant outer parentheses in a constant-only array index expression. */
+    IndexParenRedundant: 'AZM501',
+    /** Register-care conflict where a call may destroy a live caller value. */
+    RegisterCareConflict: 'AZM600',
+    /** Register-care analysis cannot prove an external or indirect call contract. */
+    RegisterCareUnknownBoundary: 'AZM601',
+};

package/dist/src/formats/index.d.ts

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

package/dist/src/formats/index.js

@@ -0,0 +1,17 @@
+import { writeBin } from './writeBin.js';
+import { writeD8m } from './writeD8m.js';
+import { writeHex } from './writeHex.js';
+import { writeListing } from './writeListing.js';
+import { writeAsm80 } from './writeAsm80.js';
+/**
+ * Default in-memory artifact writers for PR1.
+ *
+ * These writers implement the `FormatWriters` contract and return artifacts without writing to disk.
+ */
+export const defaultFormatWriters = {
+    writeHex,
+    writeBin,
+    writeD8m,
+    writeListing,
+    writeAsm80,
+};

package/dist/src/formats/range.d.ts

@@ -0,0 +1,17 @@
+import type { AddressRange, EmittedByteMap } from './types.js';
+/**
+ * Compute contiguous written segments from an emitted byte map.
+ *
+ * - Segments are half-open `[start, end)`.
+ * - Segment boundaries are based on concrete written byte addresses.
+ * - For an empty map, `[]` is returned.
+ */
+export declare function getWrittenSegments(map: EmittedByteMap): AddressRange[];
+/**
+ * Compute the effective written range for an emitted byte map.
+ *
+ * - If `map.writtenRange` is present, it is returned directly.
+ * - Otherwise, the range is derived from the min/max written addresses.
+ * - For an empty map, `{ start: 0, end: 0 }` is returned.
+ */
+export declare function getWrittenRange(map: EmittedByteMap): AddressRange;

package/dist/src/formats/range.js

@@ -0,0 +1,45 @@
+/**
+ * Compute contiguous written segments from an emitted byte map.
+ *
+ * - Segments are half-open `[start, end)`.
+ * - Segment boundaries are based on concrete written byte addresses.
+ * - For an empty map, `[]` is returned.
+ */
+export function getWrittenSegments(map) {
+    if (map.bytes.size === 0)
+        return [];
+    const sorted = [...new Set(map.bytes.keys())].sort((a, b) => a - b);
+    const segments = [];
+    let start = sorted[0];
+    let prev = start;
+    for (let index = 1; index < sorted.length; index++) {
+        const addr = sorted[index];
+        if (addr <= prev + 1) {
+            prev = addr;
+            continue;
+        }
+        segments.push({ start, end: prev + 1 });
+        start = addr;
+        prev = addr;
+    }
+    segments.push({ start, end: prev + 1 });
+    return segments;
+}
+/**
+ * Compute the effective written range for an emitted byte map.
+ *
+ * - If `map.writtenRange` is present, it is returned directly.
+ * - Otherwise, the range is derived from the min/max written addresses.
+ * - For an empty map, `{ start: 0, end: 0 }` is returned.
+ */
+export function getWrittenRange(map) {
+    if (map.writtenRange)
+        return map.writtenRange;
+    const segments = getWrittenSegments(map);
+    if (segments.length === 0)
+        return { start: 0, end: 0 };
+    return {
+        start: segments[0].start,
+        end: segments[segments.length - 1].end,
+    };
+}

package/dist/src/formats/types.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Half-open address range in the Z80 16-bit address space.
+ */
+export interface AddressRange {
+    /** Inclusive start address. */
+    start: number;
+    /** Exclusive end address. */
+    end: number;
+}
+/**
+ * Address->byte map for all emitted machine-code bytes.
+ */
+export interface EmittedByteMap {
+    /**
+     * Address -> byte (0..255). Addresses are 0..65535 for Z80.
+     */
+    bytes: Map<number, number>;
+    writtenRange?: AddressRange;
+    /**
+     * Optional source-attributed code segments emitted by lowering.
+     *
+     * Addresses are absolute in the final 16-bit address space.
+     */
+    sourceSegments?: EmittedSourceSegment[];
+}
+/**
+ * Source-attributed emitted range used by debug-map writers.
+ */
+export interface EmittedSourceSegment {
+    start: number;
+    end: number;
+    file: string;
+    line: number;
+    column: number;
+    kind: 'code' | 'data' | 'directive' | 'label' | 'macro' | 'unknown';
+    confidence: 'high' | 'medium' | 'low';
+}
+/**
+ * A symbol entry for debug maps and listings.
+ */
+export type SymbolEntry = {
+    kind: 'constant';
+    name: string;
+    /**
+     * Constant value (not an address).
+     *
+     * D8M serialization includes this as `value`.
+     */
+    value: number;
+    file?: string;
+    line?: number;
+    scope?: 'global' | 'local';
+} | {
+    kind: 'label' | 'data' | 'unknown';
+    name: string;
+    address: number;
+    file?: string;
+    line?: number;
+    scope?: 'global' | 'local';
+    size?: number;
+};
+/**
+ * Options for Intel HEX writing.
+ */
+export interface WriteHexOptions {
+    /**
+     * Line ending to use when emitting text formats.
+     */
+    lineEnding?: '\n' | '\r\n';
+}
+/**
+ * Options for BIN writing (reserved for future options).
+ */
+export interface WriteBinOptions {
+}
+/**
+ * Options for D8M writing (reserved for future options).
+ */
+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;
+    /**
+     * Optional runnable entry symbol metadata for harnesses.
+     */
+    entrySymbol?: string;
+    /**
+     * Optional resolved entry address metadata for harnesses.
+     */
+    entryAddress?: number;
+}
+/**
+ * Options for listing writing.
+ *
+ * Note: the listing format is currently a deterministic byte dump plus a symbol table.
+ */
+export interface WriteListingOptions {
+    /**
+     * Line ending to use when emitting text formats.
+     */
+    lineEnding?: '\n' | '\r\n';
+    /**
+     * Number of bytes shown per listing line.
+     */
+    bytesPerLine?: number;
+}
+/**
+ * Options for ASM80 source emission.
+ */
+export interface WriteAsm80Options {
+    /**
+     * Line ending to use when emitting text formats.
+     */
+    lineEnding?: '\n' | '\r\n';
+}
+/**
+ * In-memory Intel HEX artifact.
+ */
+export interface HexArtifact {
+    kind: 'hex';
+    path?: string;
+    text: string;
+}
+/**
+ * In-memory flat binary artifact.
+ */
+export interface BinArtifact {
+    kind: 'bin';
+    path?: string;
+    bytes: Uint8Array;
+}
+/**
+ * In-memory listing artifact.
+ */
+export interface ListingArtifact {
+    kind: 'lst';
+    path?: string;
+    text: string;
+}
+/**
+ * In-memory ASM80 `.z80` artifact.
+ */
+export interface Asm80Artifact {
+    kind: 'asm80';
+    path?: string;
+    text: string;
+}
+/**
+ * In-memory D8 Debug Map (D8M) artifact.
+ */
+export interface D8mArtifact {
+    kind: 'd8m';
+    path?: string;
+    json: D8mJson;
+}
+/**
+ * In-memory register-care audit report artifact.
+ */
+export interface RegisterCareReportArtifact {
+    kind: 'register-care-report';
+    path?: string;
+    text: string;
+}
+/**
+ * In-memory inferred register-care interface artifact.
+ */
+export interface RegisterCareInterfaceArtifact {
+    kind: 'register-care-interface';
+    path?: string;
+    text: string;
+}
+/**
+ * In-memory register-care source annotation artifact.
+ */
+export interface RegisterCareAnnotationsArtifact {
+    kind: 'register-care-annotations';
+    files: Array<{
+        path: string;
+        text: string;
+    }>;
+}
+/**
+ * Union of all artifact kinds produced by the compiler.
+ */
+export type Artifact = HexArtifact | BinArtifact | ListingArtifact | D8mArtifact | Asm80Artifact | RegisterCareReportArtifact | RegisterCareInterfaceArtifact | RegisterCareAnnotationsArtifact;
+/**
+ * Minimal D8 Debug Map (D8M) v1 JSON shape.
+ *
+ * Writers may add additional keys as needed.
+ */
+export type D8mJson = {
+    format: 'd8-debug-map';
+    version: 1;
+    arch: 'z80';
+    [key: string]: unknown;
+};
+/**
+ * Format writers used by the pipeline to turn emitted bytes/symbols into artifacts.
+ */
+export interface FormatWriters {
+    writeHex(map: EmittedByteMap, symbols: SymbolEntry[], opts?: WriteHexOptions): HexArtifact;
+    writeBin(map: EmittedByteMap, symbols: SymbolEntry[], opts?: WriteBinOptions): BinArtifact;
+    writeD8m(map: EmittedByteMap, symbols: SymbolEntry[], opts?: WriteD8mOptions): D8mArtifact;
+    writeListing?(map: EmittedByteMap, symbols: SymbolEntry[], opts?: WriteListingOptions): ListingArtifact;
+    writeAsm80?(program: import('../lowering/loweredAsmTypes.js').LoweredAsmProgram, opts?: WriteAsm80Options): Asm80Artifact;
+}

package/dist/src/formats/types.js

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

package/dist/src/formats/writeAsm80.d.ts

@@ -0,0 +1,6 @@
+import type { Asm80Artifact, WriteAsm80Options } from './types.js';
+import type { LoweredAsmProgram } from '../lowering/loweredAsmTypes.js';
+/**
+ * Emit ASM80-compatible source from a placed lowered assembly program.
+ */
+export declare function writeAsm80(program: LoweredAsmProgram, opts?: WriteAsm80Options): Asm80Artifact;