@jhlagado/azm 0.1.1 → 0.2.0

package/dist/src/index.d.ts

@@ -1,3 +1,14 @@
-export * from './api-compile.js';
-export * from './api-tooling.js';
-export type { RegisterCareMode } from './registerCare/types.js';
+export { compileSource, compileNext } from './core/compile.js';
+export type { CompileOptions, CompileSourceResult, CompileNextOptions } from './core/compile.js';
+export { compileArtifacts, compileNextArtifacts } from './core/compile-artifacts.js';
+export type { CompileArtifactOptions, CompileArtifactsResult, SourceArtifact, CompileNextArtifactOptions, CompileNextArtifactsResult, NextArtifact, } from './core/compile-artifacts.js';
+export { formatDiagnostic, formatNextDiagnostic } from './diagnostics/format.js';
+export { analyzeProgram, loadProgram, analyzeProgramNext, loadProgramNext } from './tooling/api.js';
+export { DiagnosticIds } from './model/diagnostic.js';
+export type { DiagnosticId, DiagnosticSeverity, Diagnostic } from './model/diagnostic.js';
+export { analyzeRegisterCareForTools, type AnalyzeRegisterCareForToolsOptions, type AnalyzeRegisterCareForToolsResult, type RegisterCareCandidateDiagnostic, type RegisterCareCodeAction, } from './register-care/tooling.js';
+export { compile, defaultFormatWriters, writeHex } from './api-compile.js';
+export type { AddressRange, Artifact, CompileDependencies, CompileFunctionOptions, CompileResult, CompileNextDependencies, CompileNextFunctionOptions, EmittedByteMap, FormatWriters, CompileNextResult as CompileNextProgramResult, } from './api-compile.js';
+export type { AnalyzeProgramOptions, AnalyzeProgramResult, LoadProgramOptions, LoadProgramResult, LoadedProgram, AnalyzeProgramNextOptions, AnalyzeProgramNextResult, LoadProgramNextOptions, LoadProgramNextResult, LoadedProgramNext, } from './tooling/api.js';
+export type { CaseStyleMode } from './tooling/case-style.js';
+export type { D8mArtifact, D8mGenerator, D8mJson, D8mFileEntry, D8mFileSymbol, D8mSegment, D8mSymbol, SymbolEntry, WriteD8mOptions, } from './outputs/types.js';

package/dist/src/index.js

@@ -1,2 +1,7 @@
-export * from './api-compile.js';
-export * from './api-tooling.js';
+export { compileSource, compileNext } from './core/compile.js';
+export { compileArtifacts, compileNextArtifacts } from './core/compile-artifacts.js';
+export { formatDiagnostic, formatNextDiagnostic } from './diagnostics/format.js';
+export { analyzeProgram, loadProgram, analyzeProgramNext, loadProgramNext } from './tooling/api.js';
+export { DiagnosticIds } from './model/diagnostic.js';
+export { analyzeRegisterCareForTools, } from './register-care/tooling.js';
+export { compile, defaultFormatWriters, writeHex } from './api-compile.js';

package/dist/src/model/diagnostic.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Severity level for a diagnostic.
+ */
+export type DiagnosticSeverity = 'error' | 'warning' | 'info';
+/**
+ * A compiler diagnostic (error/warning/info) with an optional source location.
+ *
+ * Diagnostics use stable `code` values so downstream tooling can rely on them.
+ */
+export interface Diagnostic {
+    readonly severity: DiagnosticSeverity;
+    /** Stable diagnostic identifier (e.g. `AZM400` or `AZMN_PARSE`). */
+    readonly code: string;
+    readonly message: string;
+    readonly sourceName?: string;
+    /** 1-based line number, when known. */
+    readonly line?: number;
+    /** 1-based column number, when known. */
+    readonly column?: number;
+}
+/**
+ * Known diagnostic IDs for the public tooling surface.
+ *
+ * Runtime diagnostics may also use AZM Next-specific codes (`AZMN_*`); this
+ * catalog preserves stable AZM-branded IDs for semver-sensitive consumers.
+ */
+export declare const DiagnosticIds: {
+    readonly Unknown: "AZM000";
+    readonly IoReadFailed: "AZM001";
+    readonly InternalParseError: "AZM002";
+    readonly IncludeNotFound: "AZM003";
+    readonly ParseError: "AZM100";
+    readonly EncodeError: "AZM200";
+    readonly EmitError: "AZM300";
+    readonly EmitWarning: "AZM301";
+    readonly OpArityMismatch: "AZM310";
+    readonly OpNoMatchingOverload: "AZM311";
+    readonly OpAmbiguousOverload: "AZM312";
+    readonly OpExpansionCycle: "AZM313";
+    readonly OpInvalidExpansion: "AZM314";
+    readonly SemanticsError: "AZM400";
+    readonly ImmDivideByZero: "AZM401";
+    readonly ImmModuloByZero: "AZM402";
+    readonly TypeError: "AZM403";
+    readonly CaseStyleLint: "AZM500";
+    readonly IndexParenRedundant: "AZM501";
+    readonly RegisterCareConflict: "AZM600";
+    readonly RegisterCareUnknownBoundary: "AZM601";
+};
+export type DiagnosticId = (typeof DiagnosticIds)[keyof typeof DiagnosticIds];

package/dist/src/model/diagnostic.js

@@ -0,0 +1,29 @@
+/**
+ * Known diagnostic IDs for the public tooling surface.
+ *
+ * Runtime diagnostics may also use AZM Next-specific codes (`AZMN_*`); this
+ * catalog preserves stable AZM-branded IDs for semver-sensitive consumers.
+ */
+export const DiagnosticIds = {
+    Unknown: 'AZM000',
+    IoReadFailed: 'AZM001',
+    InternalParseError: 'AZM002',
+    IncludeNotFound: 'AZM003',
+    ParseError: 'AZM100',
+    EncodeError: 'AZM200',
+    EmitError: 'AZM300',
+    EmitWarning: 'AZM301',
+    OpArityMismatch: 'AZM310',
+    OpNoMatchingOverload: 'AZM311',
+    OpAmbiguousOverload: 'AZM312',
+    OpExpansionCycle: 'AZM313',
+    OpInvalidExpansion: 'AZM314',
+    SemanticsError: 'AZM400',
+    ImmDivideByZero: 'AZM401',
+    ImmModuloByZero: 'AZM402',
+    TypeError: 'AZM403',
+    CaseStyleLint: 'AZM500',
+    IndexParenRedundant: 'AZM501',
+    RegisterCareConflict: 'AZM600',
+    RegisterCareUnknownBoundary: 'AZM601',
+};

package/dist/src/model/expression.d.ts

@@ -0,0 +1,51 @@
+export type Expression = {
+    readonly kind: 'number';
+    readonly value: number;
+} | {
+    readonly kind: 'symbol';
+    readonly name: string;
+} | {
+    readonly kind: 'current-location';
+} | {
+    readonly kind: 'type-size';
+    readonly typeExpr: TypeExpr;
+} | {
+    readonly kind: 'sizeof';
+    readonly typeExpr: TypeExpr;
+} | {
+    readonly kind: 'offset';
+    readonly typeExpr: TypeExpr;
+    readonly path: readonly OffsetPathPart[];
+} | {
+    readonly kind: 'layout-cast';
+    readonly typeExpr: TypeExpr;
+    readonly base: Expression;
+    readonly path: readonly LayoutCastPathPart[];
+} | {
+    readonly kind: 'unary';
+    readonly operator: '+' | '-' | '~';
+    readonly expression: Expression;
+} | {
+    readonly kind: 'binary';
+    readonly operator: '*' | '/' | '%' | '+' | '-' | '&' | '^' | '|' | '<<' | '>>';
+    readonly left: Expression;
+    readonly right: Expression;
+};
+export interface TypeExpr {
+    readonly name: string;
+    readonly length?: number;
+}
+export type OffsetPathPart = {
+    readonly kind: 'field';
+    readonly name: string;
+} | {
+    readonly kind: 'index';
+    readonly index: number;
+};
+export type LayoutCastPathPart = {
+    readonly kind: 'field';
+    readonly name: string;
+} | {
+    readonly kind: 'index';
+    readonly expression: Expression;
+};

package/dist/src/model/expression.js

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

package/dist/src/model/fixup.d.ts

@@ -0,0 +1,18 @@
+import type { SourceSpan } from '../source/source-span.js';
+export interface FixupTarget {
+    readonly symbol: string;
+    readonly addend: number;
+}
+export type Fixup = {
+    readonly kind: 'abs16';
+    readonly offset: number;
+    readonly target: FixupTarget;
+    readonly span: SourceSpan;
+} | {
+    readonly kind: 'rel8';
+    readonly offset: number;
+    readonly origin: number;
+    readonly target: FixupTarget;
+    readonly mnemonic: string;
+    readonly span: SourceSpan;
+};

package/dist/src/model/fixup.js

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

package/dist/src/model/source-item.d.ts

@@ -0,0 +1,81 @@
+import type { Expression, TypeExpr } from './expression.js';
+import type { SourceSpan } from '../source/source-span.js';
+import type { Z80Instruction } from '../z80/instruction.js';
+export type SourceItem = {
+    readonly kind: 'org';
+    readonly expression: Expression;
+    readonly span: SourceSpan;
+} | {
+    readonly kind: 'equ';
+    readonly name: string;
+    readonly expression: Expression;
+    readonly stringValue?: string;
+    readonly span: SourceSpan;
+} | {
+    readonly kind: 'label';
+    readonly name: string;
+    readonly span: SourceSpan;
+} | {
+    readonly kind: 'db';
+    readonly values: readonly DataValue[];
+    readonly span: SourceSpan;
+} | {
+    readonly kind: 'dw';
+    readonly values: readonly Expression[];
+    readonly span: SourceSpan;
+} | {
+    readonly kind: 'ds';
+    readonly size: Expression;
+    readonly fill?: Expression;
+    readonly span: SourceSpan;
+} | {
+    readonly kind: 'align';
+    readonly alignment: Expression;
+    readonly span: SourceSpan;
+} | {
+    readonly kind: 'end';
+    readonly span: SourceSpan;
+} | {
+    readonly kind: 'binfrom';
+    readonly expression: Expression;
+    readonly span: SourceSpan;
+} | {
+    readonly kind: 'binto';
+    readonly expression: Expression;
+    readonly span: SourceSpan;
+} | {
+    readonly kind: 'enum';
+    readonly name: string;
+    readonly members: readonly string[];
+    readonly span: SourceSpan;
+} | {
+    readonly kind: 'type';
+    readonly name: string;
+    readonly layoutKind: 'record' | 'union';
+    readonly fields: readonly LayoutField[];
+    readonly span: SourceSpan;
+} | {
+    readonly kind: 'string-data';
+    readonly directive: 'cstr' | 'pstr' | 'istr';
+    readonly value: string;
+    readonly span: SourceSpan;
+} | {
+    readonly kind: 'instruction';
+    readonly instruction: Instruction;
+    readonly span: SourceSpan;
+    readonly emittedSource?: EmittedSource;
+};
+export type Instruction = Z80Instruction;
+export type DataValue = Expression | {
+    readonly kind: 'string-fragment';
+    readonly value: string;
+};
+export interface LayoutField {
+    readonly name: string;
+    readonly size: number;
+    readonly typeExpr?: TypeExpr;
+}
+export interface EmittedSource {
+    readonly span: SourceSpan;
+    readonly kind: 'code' | 'macro';
+}

package/dist/src/model/source-item.js

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

package/dist/src/model/symbol.d.ts

@@ -0,0 +1 @@
+export type SymbolTable = Readonly<Record<string, number>>;

package/dist/src/model/symbol.js

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

package/dist/src/node/source-host.d.ts

@@ -0,0 +1,19 @@
+import type { Diagnostic } from '../model/diagnostic.js';
+import type { LogicalLine } from '../source/logical-lines.js';
+export interface LoadProgramNextOptions {
+    readonly entryFile: string;
+    readonly includeDirs?: readonly string[];
+    readonly directiveAliasFiles?: readonly string[];
+    readonly preloadedText?: string;
+    readonly signal?: AbortSignal;
+}
+export interface ExpandedNextSource {
+    readonly entryFile: string;
+    readonly lines: readonly LogicalLine[];
+    readonly sourceTexts: ReadonlyMap<string, string>;
+    readonly sourceLineComments: ReadonlyMap<string, ReadonlyMap<number, string>>;
+}
+export declare function expandSourceForTooling(options: LoadProgramNextOptions): Promise<{
+    readonly diagnostics: readonly Diagnostic[];
+    readonly expanded?: ExpandedNextSource;
+}>;

package/dist/src/node/source-host.js

@@ -0,0 +1,146 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, extname, join, normalize } from 'node:path';
+import { createSourceFile } from '../source/source-file.js';
+import { scanLogicalLines } from '../source/logical-lines.js';
+import { stripLineComment } from '../source/strip-line-comment.js';
+export async function expandSourceForTooling(options) {
+    const diagnostics = [];
+    const entryFile = normalize(options.entryFile);
+    const extension = extname(entryFile).toLowerCase();
+    if (extension !== '.asm' && extension !== '.z80') {
+        diagnostics.push({
+            severity: 'error',
+            code: 'AZMN_SOURCE',
+            message: 'unsupported source file extension (expected .asm or .z80)',
+            sourceName: entryFile,
+        });
+        return { diagnostics };
+    }
+    const sourceTexts = new Map();
+    const sourceLineComments = new Map();
+    const includeDirs = (options.includeDirs ?? []).map((path) => normalize(path));
+    const lines = await expandFile({
+        sourcePath: entryFile,
+        includeDirs,
+        sourceTexts,
+        sourceLineComments,
+        diagnostics,
+        includeStack: [],
+        ...(options.preloadedText !== undefined ? { preloadedText: options.preloadedText } : {}),
+        ...(options.signal !== undefined ? { signal: options.signal } : {}),
+    });
+    if (diagnostics.some((diagnostic) => diagnostic.severity === 'error') || lines === undefined) {
+        return { diagnostics };
+    }
+    return { diagnostics, expanded: { entryFile, lines, sourceTexts, sourceLineComments } };
+}
+async function expandFile(options) {
+    options.signal?.throwIfAborted();
+    const sourcePath = normalize(options.sourcePath);
+    if (options.includeStack.includes(sourcePath)) {
+        options.diagnostics.push({
+            severity: 'error',
+            code: 'AZMN_SOURCE',
+            message: `recursive include: ${sourcePath}`,
+            sourceName: sourcePath,
+        });
+        return undefined;
+    }
+    const text = await readSourceText(options, sourcePath);
+    if (text === undefined) {
+        return undefined;
+    }
+    options.sourceTexts.set(sourcePath, text);
+    const output = [];
+    for (const line of scanLogicalLines(createSourceFile(sourcePath, text))) {
+        recordLineComment(options.sourceLineComments, line);
+        const includePath = parseIncludePath(line.text);
+        if (!includePath) {
+            output.push(line);
+            continue;
+        }
+        const result = await resolveInclude(sourcePath, includePath, options.includeDirs);
+        if (result.resolved === undefined) {
+            options.diagnostics.push({
+                severity: 'error',
+                code: 'AZMN_SOURCE',
+                message: `Failed to resolve include "${includePath}" from "${sourcePath}". Tried:\n${result.searchCandidates.map((candidate) => `- ${candidate}`).join('\n')}`,
+                sourceName: sourcePath,
+                line: line.line,
+                column: firstColumn(line.text),
+            });
+            continue;
+        }
+        const { preloadedText: _preloadedText, ...includeOptions } = options;
+        const included = await expandFile({
+            ...includeOptions,
+            sourcePath: result.resolved,
+            includeStack: [...options.includeStack, sourcePath],
+        });
+        if (included !== undefined) {
+            output.push(...included);
+        }
+    }
+    return output;
+}
+function recordLineComment(comments, line) {
+    const commentText = lineComment(line.text);
+    if (commentText === undefined) {
+        return;
+    }
+    let sourceComments = comments.get(line.sourceName);
+    if (!sourceComments) {
+        sourceComments = new Map();
+        comments.set(line.sourceName, sourceComments);
+    }
+    sourceComments.set(line.line, commentText);
+}
+async function readSourceText(options, sourcePath) {
+    if (options.preloadedText !== undefined) {
+        return options.preloadedText;
+    }
+    try {
+        return await readFile(sourcePath, 'utf8');
+    }
+    catch (error) {
+        options.diagnostics.push({
+            severity: 'error',
+            code: 'AZMN_SOURCE',
+            message: `failed to read source file: ${String(error)}`,
+            sourceName: sourcePath,
+        });
+        return undefined;
+    }
+}
+async function resolveInclude(importer, includePath, includeDirs) {
+    const candidates = [
+        join(dirname(importer), includePath),
+        ...includeDirs.map((dir) => join(dir, includePath)),
+    ];
+    for (const candidate of candidates) {
+        try {
+            await readFile(candidate, 'utf8');
+            return { resolved: normalize(candidate), searchCandidates: candidates.map(normalize) };
+        }
+        catch {
+            continue;
+        }
+    }
+    return { searchCandidates: candidates.map(normalize) };
+}
+function parseIncludePath(text) {
+    const match = /^\.?include\s+"([^"]+)"\s*$/i.exec(stripLineComment(text).trim());
+    return match?.[1];
+}
+function lineComment(text) {
+    const prefix = stripLineComment(text);
+    if (prefix.length === text.length) {
+        return undefined;
+    }
+    const value = text.slice(prefix.length + 1).trim();
+    return value.length === 0 ? undefined : value;
+}
+function firstColumn(text) {
+    const match = /\S/.exec(text);
+    return match ? match.index + 1 : 1;
+}

package/dist/src/outputs/hex.d.ts

@@ -0,0 +1 @@
+export declare function writeIntelHex(origin: number, bytes: Uint8Array, reservedAddresses?: readonly number[], initializedAddresses?: readonly number[]): string;

package/dist/src/outputs/hex.js

@@ -0,0 +1,75 @@
+export function writeIntelHex(origin, bytes, reservedAddresses = [], initializedAddresses = []) {
+    if (bytes.length === 0) {
+        return ':00000001FF\n';
+    }
+    const records = [];
+    const end = origin + bytes.length;
+    const segments = toNonReservedSegments(origin, end, reservedAddresses, initializedAddresses);
+    if (segments.length === 0) {
+        for (let address = origin; address < end; address += 16) {
+            const count = Math.min(16, end - address);
+            const startOffset = address - origin;
+            const chunk = Array.from(bytes.slice(startOffset, startOffset + count));
+            records.push(writeRecord(count, address, 0x00, chunk));
+        }
+        return `${records.join('\n')}\n:00000001FF\n`;
+    }
+    for (const segment of segments) {
+        for (let address = segment.start; address < segment.end; address += 16) {
+            const startOffset = address - origin;
+            const count = Math.min(16, segment.end - address);
+            const chunk = Array.from(bytes.slice(startOffset, startOffset + count));
+            records.push(writeRecord(count, address, 0x00, chunk));
+        }
+    }
+    return `${records.join('\n')}\n:00000001FF\n`;
+}
+function toNonReservedSegments(start, end, reservedAddresses, initializedAddresses) {
+    if (reservedAddresses.length === 0 || initializedAddresses.length === 0) {
+        return [];
+    }
+    const inRangeInitialized = initializedAddresses.filter((address) => address >= start && address < end);
+    if (inRangeInitialized.length === 0) {
+        return [];
+    }
+    const firstInitialized = inRangeInitialized.reduce((best, address) => Math.min(best, address), end);
+    const lastInitialized = inRangeInitialized.reduce((best, address) => Math.max(best, address), start - 1);
+    const reservedInRange = new Set(reservedAddresses.filter((address) => address >= start && address < end));
+    if (reservedInRange.size === 0) {
+        return [];
+    }
+    const segments = [];
+    let segmentStart;
+    let segmentEnd = start;
+    for (let address = start; address < end; address += 1) {
+        const skipReserved = address > firstInitialized &&
+            address < lastInitialized &&
+            reservedInRange.has(address);
+        if (skipReserved) {
+            if (segmentStart !== undefined) {
+                segments.push({ start: segmentStart, end: segmentEnd });
+            }
+            segmentStart = undefined;
+            segmentEnd = address + 1;
+            continue;
+        }
+        if (segmentStart === undefined) {
+            segmentStart = address;
+        }
+        segmentEnd = address + 1;
+    }
+    if (segmentStart !== undefined) {
+        segments.push({ start: segmentStart, end: segmentEnd });
+    }
+    return segments;
+}
+function writeRecord(length, address, type, bytes) {
+    const fields = [length, (address >> 8) & 0xff, address & 0xff, type, ...bytes];
+    const checksum = ((~fields.reduce((sum, value) => sum + value, 0) + 1) & 0xff) >>> 0;
+    return `:${toHex(length)}${toHex((address >> 8) & 0xff)}${toHex(address & 0xff)}${toHex(type)}${bytes
+        .map(toHex)
+        .join('')}${toHex(checksum)}`;
+}
+function toHex(value) {
+    return (value & 0xff).toString(16).toUpperCase().padStart(2, '0');
+}

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

@@ -0,0 +1,3 @@
+import type { FormatWriters } from './types.js';
+/** Default in-memory writers for Stage 12 compile API. */
+export declare const defaultFormatWriters: FormatWriters;

package/dist/src/outputs/index.js

@@ -0,0 +1,13 @@
+import { writeBin } from './write-bin.js';
+import { writeD8m } from './write-d8.js';
+import { writeHex } from './write-hex.js';
+import { writeListing } from './write-listing.js';
+import { writeAsm80 } from './write-asm80.js';
+/** Default in-memory writers for Stage 12 compile API. */
+export const defaultFormatWriters = {
+    writeBin,
+    writeHex,
+    writeD8m,
+    writeListing,
+    writeAsm80,
+};

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

@@ -0,0 +1,3 @@
+import type { AddressRange, EmittedByteMap } from './types.js';
+export declare function getWrittenSegments(map: EmittedByteMap): AddressRange[];
+export declare function getWrittenRange(map: EmittedByteMap): AddressRange;

package/dist/src/outputs/range.js

@@ -0,0 +1,31 @@
+export function getWrittenSegments(map) {
+    if (map.bytes.size === 0)
+        return [];
+    const addresses = [...new Set(map.bytes.keys())].sort((a, b) => a - b);
+    const segments = [];
+    let start = addresses[0];
+    let previous = start;
+    for (let index = 1; index < addresses.length; index += 1) {
+        const address = addresses[index];
+        if (address <= previous + 1) {
+            previous = address;
+            continue;
+        }
+        segments.push({ start, end: previous + 1 });
+        start = address;
+        previous = address;
+    }
+    segments.push({ start, end: previous + 1 });
+    return segments;
+}
+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,
+    };
+}