@jhlagado/azm 0.2.7 → 0.2.9

package/dist/src/api-compile.js

@@ -1,19 +1,16 @@
-import { readFile } from 'node:fs/promises';
-import { dirname, normalize } from 'node:path';
+import { normalize } from 'node:path';
 import { assembleProgram } from './assembly/assemble-program.js';
+import { emitAssemblyArtifacts } from './api-artifacts.js';
+import { runRegisterContracts, shouldAnalyzeRegisterContracts } from './api-register-contracts.js';
 import { analyzeProgramNext, loadProgramNext } from './tooling/api.js';
 import { defaultFormatWriters } from './outputs/index.js';
-import { UnsupportedAsm80LoweringError } from './outputs/write-asm80.js';
 import { writeHex } from './outputs/write-hex.js';
-import { analyzeRegisterCare } from './register-care/analyze.js';
-import { buildRegisterCareProgramModel } from './register-care/programModel.js';
-import { parseAcceptedOutputCandidates } from './register-care/accept-output.js';
-import { parseInterfaceContracts } from './register-care/smartComments.js';
+import { buildRegisterContractsProgramModel } from './register-contracts/programModel.js';
 function parseUnresolvedSymbolName(message) {
     const match = /^Unresolved symbol "([^"]+)"/.exec(message);
     return match?.[1];
 }
-function isSuppressedUnknownSymbolInRegisterCareMode(diagnostic, directCalls) {
+function isSuppressedUnknownSymbolInRegisterContractsMode(diagnostic, directCalls) {
     if (directCalls === undefined || directCalls.length === 0) {
         return false;
     }
@@ -33,7 +30,6 @@ function isSuppressedUnknownSymbolInRegisterCareMode(diagnostic, directCalls) {
         call.column === diagnostic.column);
 }
 export { writeHex, defaultFormatWriters };
-let cachedPackageVersion;
 /**
  * Compile an AZM/ASM80-style program into in-memory artifacts.
  */
@@ -54,223 +50,58 @@ export async function compile(entryFile, options = {}, deps = { formats: default
     const analysis = analyzeProgramNext(loaded.loadedProgram, {
         ...(options.caseStyle !== undefined ? { caseStyle: options.caseStyle } : {}),
     });
-    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;
-    const directCalls = shouldAnalyzeRegisterCare
-        ? buildRegisterCareProgramModel(loaded.loadedProgram.program.files[0]?.items ?? []).directCalls
+    const analyzeRegisterContractsNow = shouldAnalyzeRegisterContracts(options);
+    const directCalls = analyzeRegisterContractsNow
+        ? buildRegisterContractsProgramModel(loaded.loadedProgram.program.files[0]?.items ?? [])
+            .directCalls
         : undefined;
-    diagnostics.push(...analysis.diagnostics.filter((diagnostic) => shouldAnalyzeRegisterCare
-        ? !isSuppressedUnknownSymbolInRegisterCareMode(diagnostic, directCalls)
+    diagnostics.push(...analysis.diagnostics.filter((diagnostic) => analyzeRegisterContractsNow
+        ? !isSuppressedUnknownSymbolInRegisterContractsMode(diagnostic, directCalls)
         : true));
     const artifacts = [];
-    if (shouldAnalyzeRegisterCare) {
-        // Validate interface references and accepted output markers now; full analysis is deferred.
-        const acceptedOutputCandidates = parseAcceptedOutputCandidates(options.acceptRegisterOutputCandidates ?? []);
-        const interfaceContracts = [];
-        for (const rawInterface of options.registerCareInterfaces ?? []) {
-            const contractPath = normalize(rawInterface);
-            if (contractPath.slice(-5).toLowerCase() !== '.asmi') {
-                diagnostics.push({
-                    severity: 'error',
-                    code: 'AZMN_REGISTER_CARE',
-                    message: 'Register-care interface files must use the .asmi extension',
-                    sourceName: contractPath,
-                });
-                continue;
-            }
-            const interfaceText = await readFile(contractPath, 'utf8');
-            for (const contract of parseInterfaceContracts(interfaceText, contractPath).values()) {
-                interfaceContracts.push(contract);
-            }
-        }
-        if (hasErrors(diagnostics)) {
-            return { diagnostics, artifacts: [] };
-        }
-        const registerCare = analyzeRegisterCare(loaded.loadedProgram, {
-            mode: registerCareMode,
-            emitReport: options.emitRegisterReport === true,
-            emitInterface: options.emitRegisterInterface === true,
-            emitAnnotations: options.emitRegisterAnnotations === true || options.fixRegisterContracts === true,
-            fixRegisterContracts: options.fixRegisterContracts === true,
-            acceptedOutputCandidates,
-            ...(options.registerCareProfile !== undefined
-                ? { registerCareProfile: options.registerCareProfile }
-                : {}),
-            ...(interfaceContracts.length > 0 ? { interfaceContracts } : {}),
-        });
-        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.annotations !== undefined && registerCare.annotations.length > 0) {
-            const files = registerCare.annotations.map((item) => ({
-                path: item.path,
-                text: item.text,
-            }));
-            artifacts.push({ kind: 'register-care-annotations', files });
-        }
-        diagnostics.push(...registerCare.diagnostics);
+    if (hasErrors(diagnostics)) {
+        sortDiagnosticsInPlace(diagnostics);
+        return { diagnostics, artifacts };
+    }
+    if (analyzeRegisterContractsNow) {
+        const registerContracts = await runRegisterContracts(loaded.loadedProgram, options);
+        artifacts.push(...registerContracts.artifacts);
+        diagnostics.push(...registerContracts.diagnostics);
         if (hasErrors(diagnostics))
-            return { diagnostics, artifacts: [] };
+            return { diagnostics, artifacts };
     }
     if (options.skipAssembly === true) {
         return { diagnostics, artifacts };
     }
     const program = loaded.loadedProgram.program.files[0]?.items ?? [];
     const assembled = assembleProgram(program);
-    diagnostics.push(...assembled.diagnostics.filter((diagnostic) => shouldAnalyzeRegisterCare
-        ? !isSuppressedUnknownSymbolInRegisterCareMode(diagnostic, directCalls)
+    diagnostics.push(...assembled.diagnostics.filter((diagnostic) => analyzeRegisterContractsNow
+        ? !isSuppressedUnknownSymbolInRegisterContractsMode(diagnostic, directCalls)
         : true));
     sortDiagnosticsInPlace(diagnostics);
     if (hasErrors(diagnostics)) {
         return { diagnostics, artifacts: [] };
     }
-    const map = assembledImageToMap(assembled.bytes, assembled.origin, assembled.sourceSegments);
-    const hexMap = assembledInitializedImageToMap(assembled.bytes, assembled.origin, assembled.initializedAddresses);
-    const sidecarMap = assembledInitializedImageToMap(assembled.bytes, assembled.origin, assembled.initializedAddresses, assembled.sourceSegments);
-    const symbols = collectSymbolEntries(program, assembled.symbols);
-    const emit = compileArtifactDefaults(options);
-    const d8Root = options.sourceRoot ?? dirname(normalizedEntry);
-    if (emit.emitBin) {
-        artifacts.push(deps.formats.writeBin(map, symbols));
-    }
-    if (emit.emitHex) {
-        artifacts.push(deps.formats.writeHex(hexMap, symbols));
-    }
-    if (emit.emitD8m) {
-        const main = symbols.find((symbol) => symbol.kind === 'label' && symbol.name.toLowerCase() === 'main');
-        const d8mOpts = {
-            rootDir: normalize(d8Root),
-            packageVersion: await readPackageVersion(),
-            inputs: {
-                entry: normalizedEntry,
-                ...(options.d8mInputs?.hex !== undefined ? { hex: options.d8mInputs.hex } : {}),
-                ...(options.d8mInputs?.bin !== undefined ? { bin: options.d8mInputs.bin } : {}),
-            },
-            ...(main !== undefined ? { entrySymbol: main.name } : {}),
-            ...(main !== undefined
-                ? { entryAddress: main.kind === 'constant' ? main.value : main.address }
-                : {}),
-        };
-        artifacts.push(deps.formats.writeD8m(sidecarMap, symbols, d8mOpts));
-    }
-    if (emit.emitAsm80) {
-        if (deps.formats.writeAsm80 !== undefined) {
-            try {
-                artifacts.push(deps.formats.writeAsm80(program, symbols));
-            }
-            catch (error) {
-                if (error instanceof UnsupportedAsm80LoweringError) {
-                    diagnostics.push({
-                        severity: 'error',
-                        code: 'AZMN_ASM80',
-                        message: error.message,
-                        sourceName: error.item.span.sourceName,
-                        line: error.item.span.line,
-                        column: error.item.span.column,
-                    });
-                    return { diagnostics, artifacts };
-                }
-                throw error;
-            }
-        }
-    }
+    const emittedArtifacts = await emitAssemblyArtifacts({
+        entryFile: normalizedEntry,
+        options,
+        formats: deps.formats,
+        program,
+        bytes: assembled.bytes,
+        origin: assembled.origin,
+        sourceSegments: assembled.sourceSegments,
+        initializedAddresses: assembled.initializedAddresses,
+        symbols: assembled.symbols,
+    });
+    artifacts.push(...emittedArtifacts.artifacts);
+    diagnostics.push(...emittedArtifacts.diagnostics);
     return { diagnostics, artifacts };
 }
-function compileArtifactDefaults(options) {
-    const anyPrimary = [options.emitBin, options.emitHex, options.emitD8m].some((value) => value !== undefined);
-    const emitBin = anyPrimary ? (options.emitBin ?? false) : true;
-    const emitHex = anyPrimary ? (options.emitHex ?? false) : true;
-    const emitD8m = anyPrimary ? (options.emitD8m ?? false) : true;
-    const emitAsm80 = options.emitAsm80 ?? false;
-    return { emitBin, emitHex, emitD8m, emitAsm80 };
-}
-function assembledImageToMap(bytes, origin, sourceSegments = []) {
-    const map = new Map();
-    for (let offset = 0; offset < bytes.length; offset += 1) {
-        map.set(origin + offset, bytes[offset] ?? 0);
-    }
-    const writtenRange = {
-        start: origin,
-        end: origin + bytes.length,
-    };
-    return { bytes: map, writtenRange, sourceSegments };
-}
-function assembledInitializedImageToMap(bytes, origin, initializedAddresses, sourceSegments = []) {
-    const map = new Map();
-    for (const address of initializedAddresses) {
-        const offset = address - origin;
-        if (offset >= 0 && offset < bytes.length) {
-            map.set(address, bytes[offset] ?? 0);
-        }
-    }
-    return { bytes: map, sourceSegments };
-}
-function collectSymbolEntries(items, resolvedSymbols) {
-    const map = new Map();
-    for (const item of items) {
-        switch (item.kind) {
-            case 'equ': {
-                const value = resolvedSymbols[item.name];
-                if (value !== undefined) {
-                    map.set(item.name, {
-                        kind: 'constant',
-                        name: item.name,
-                        value,
-                        file: item.span.sourceName,
-                        line: item.span.line,
-                        scope: 'global',
-                    });
-                }
-                break;
-            }
-            case 'label': {
-                const address = resolvedSymbols[item.name];
-                if (address !== undefined) {
-                    map.set(item.name, {
-                        kind: 'label',
-                        name: item.name,
-                        address,
-                        file: item.span.sourceName,
-                        line: item.span.line,
-                        scope: 'global',
-                    });
-                }
-                break;
-            }
-            case 'enum': {
-                for (const member of item.members) {
-                    const fullName = `${item.name}.${member}`;
-                    const value = resolvedSymbols[fullName];
-                    if (value !== undefined) {
-                        map.set(fullName, {
-                            kind: 'constant',
-                            name: fullName,
-                            value,
-                            file: item.span.sourceName,
-                            line: item.span.line,
-                            scope: 'global',
-                        });
-                    }
-                }
-                break;
-            }
-        }
-    }
-    return [...map.values()];
-}
 function hasErrors(diagnostics) {
     return diagnostics.some((diagnostic) => diagnostic.severity === 'error');
 }
 function sortDiagnosticsInPlace(diagnostics) {
+    dedupeDiagnosticsInPlace(diagnostics);
     diagnostics.sort((left, right) => {
         const lineDelta = (left.line ?? 0) - (right.line ?? 0);
         if (lineDelta !== 0) {
@@ -279,28 +110,25 @@ function sortDiagnosticsInPlace(diagnostics) {
         return (left.column ?? 0) - (right.column ?? 0);
     });
 }
-async function readPackageVersion() {
-    if (cachedPackageVersion !== undefined) {
-        return cachedPackageVersion;
-    }
-    const packageJsonCandidates = [
-        new URL('../package.json', import.meta.url),
-        new URL('../../package.json', import.meta.url),
-        new URL('../../../package.json', import.meta.url),
-    ];
-    for (const candidate of packageJsonCandidates) {
-        try {
-            const raw = await readFile(candidate, 'utf8');
-            const json = JSON.parse(raw);
-            if (json.version !== undefined) {
-                cachedPackageVersion = json.version;
-                return cachedPackageVersion;
-            }
-        }
-        catch {
-            // Continue searching candidates.
+function dedupeDiagnosticsInPlace(diagnostics) {
+    const seen = new Set();
+    for (let index = diagnostics.length - 1; index >= 0; index -= 1) {
+        const diagnostic = diagnostics[index];
+        const key = diagnosticKey(diagnostic);
+        if (seen.has(key)) {
+            diagnostics.splice(index, 1);
+            continue;
         }
+        seen.add(key);
     }
-    cachedPackageVersion = '0.0.0';
-    return cachedPackageVersion;
+}
+function diagnosticKey(diagnostic) {
+    return [
+        diagnostic.severity,
+        diagnostic.code,
+        diagnostic.message,
+        diagnostic.sourceName ?? '',
+        diagnostic.line ?? '',
+        diagnostic.column ?? '',
+    ].join('\0');
 }

package/dist/src/api-register-contracts.d.ts

@@ -0,0 +1,9 @@
+import type { Diagnostic } from './model/diagnostic.js';
+import type { Artifact } from './outputs/types.js';
+import type { LoadedProgramNext } from './tooling/api.js';
+import type { CompileNextFunctionOptions } from './api-compile.js';
+export declare function shouldAnalyzeRegisterContracts(options: CompileNextFunctionOptions): boolean;
+export declare function runRegisterContracts(loadedProgram: LoadedProgramNext, options: CompileNextFunctionOptions): Promise<{
+    readonly artifacts: readonly Artifact[];
+    readonly diagnostics: readonly Diagnostic[];
+}>;

package/dist/src/api-register-contracts.js

@@ -0,0 +1,77 @@
+import { readFile } from 'node:fs/promises';
+import { normalize } from 'node:path';
+import { analyzeRegisterContracts } from './register-contracts/analyze.js';
+import { parseAcceptedOutputCandidates } from './register-contracts/accept-output.js';
+import { parseInterfaceContracts } from './register-contracts/interfaceContracts.js';
+export function shouldAnalyzeRegisterContracts(options) {
+    const registerContractsMode = options.registerContracts ?? options.registerCare ?? 'off';
+    return (registerContractsMode !== 'off' ||
+        options.emitRegisterReport === true ||
+        options.emitRegisterInterface === true ||
+        options.emitRegisterAnnotations === true ||
+        options.fixRegisterContracts === true ||
+        (options.acceptRegisterOutputCandidates?.length ?? 0) > 0 ||
+        (options.registerContractsInterfaces?.length ?? options.registerCareInterfaces?.length ?? 0) > 0);
+}
+export async function runRegisterContracts(loadedProgram, options) {
+    const diagnostics = [];
+    const artifacts = [];
+    const interfaceContracts = await loadInterfaceContracts(options.registerContractsInterfaces ?? options.registerCareInterfaces ?? [], diagnostics);
+    if (hasErrors(diagnostics)) {
+        return { diagnostics, artifacts };
+    }
+    const registerContracts = analyzeRegisterContracts(loadedProgram, {
+        mode: options.registerContracts ?? options.registerCare ?? 'off',
+        emitReport: options.emitRegisterReport === true,
+        emitInterface: options.emitRegisterInterface === true,
+        emitAnnotations: options.emitRegisterAnnotations === true || options.fixRegisterContracts === true,
+        fixRegisterContracts: options.fixRegisterContracts === true,
+        acceptedOutputCandidates: parseAcceptedOutputCandidates(options.acceptRegisterOutputCandidates ?? []),
+        ...(options.registerContractsProfile !== undefined || options.registerCareProfile !== undefined
+            ? {
+                registerContractsProfile: options.registerContractsProfile ?? options.registerCareProfile,
+            }
+            : {}),
+        ...(interfaceContracts.length > 0 ? { interfaceContracts } : {}),
+    });
+    if (registerContracts.reportText !== undefined) {
+        artifacts.push({ kind: 'register-contracts-report', text: registerContracts.reportText });
+    }
+    if (registerContracts.interfaceText !== undefined) {
+        artifacts.push({ kind: 'register-contracts-interface', text: registerContracts.interfaceText });
+    }
+    if (registerContracts.annotations !== undefined && registerContracts.annotations.length > 0) {
+        artifacts.push({
+            kind: 'register-contracts-annotations',
+            files: registerContracts.annotations.map((item) => ({
+                path: item.path,
+                text: item.text,
+            })),
+        });
+    }
+    diagnostics.push(...registerContracts.diagnostics);
+    return { artifacts, diagnostics };
+}
+async function loadInterfaceContracts(interfaces, diagnostics) {
+    const interfaceContracts = [];
+    for (const rawInterface of interfaces) {
+        const contractPath = normalize(rawInterface);
+        if (contractPath.slice(-5).toLowerCase() !== '.asmi') {
+            diagnostics.push({
+                severity: 'error',
+                code: 'AZMN_REGISTER_CONTRACTS',
+                message: 'Register contracts interface files must use the .asmi extension',
+                sourceName: contractPath,
+            });
+            continue;
+        }
+        const interfaceText = await readFile(contractPath, 'utf8');
+        for (const contract of parseInterfaceContracts(interfaceText, contractPath).values()) {
+            interfaceContracts.push(contract);
+        }
+    }
+    return interfaceContracts;
+}
+function hasErrors(diagnostics) {
+    return diagnostics.some((diagnostic) => diagnostic.severity === 'error');
+}

package/dist/src/api-tooling.d.ts

@@ -1,7 +1,7 @@
 export { analyzeProgram, analyzeProgramNext, loadProgram, loadProgramNext } from './tooling/api.js';
-export { analyzeRegisterCareForTools, codeActionForOutputCandidate, diagnosticForOutputCandidate, type AnalyzeRegisterCareForToolsOptions, type AnalyzeRegisterCareForToolsResult, type RegisterCareCandidateDiagnostic, type RegisterCareCodeAction, type RegisterCareTextEdit, } from './register-care/tooling.js';
+export { analyzeRegisterCareForTools, analyzeRegisterContractsForTools, codeActionForOutputCandidate, diagnosticForOutputCandidate, type AnalyzeRegisterCareForToolsOptions, type AnalyzeRegisterCareForToolsResult, type AnalyzeRegisterContractsForToolsOptions, type AnalyzeRegisterContractsForToolsResult, type RegisterCareCandidateDiagnostic, type RegisterCareCodeAction, type RegisterCareTextEdit, type RegisterContractsCandidateDiagnostic, type RegisterContractsCodeAction, type RegisterContractsTextEdit, } from './register-contracts/tooling.js';
 export { DiagnosticIds } from './model/diagnostic.js';
 export type { AnalyzeProgramOptions, AnalyzeProgramResult, LoadedProgram, LoadProgramOptions, LoadProgramResult, AnalyzeProgramNextOptions, AnalyzeProgramNextResult, LoadedProgramNext, LoadProgramNextOptions, LoadProgramNextResult, } from './tooling/api.js';
 export type { CaseStyleMode } from './tooling/case-style.js';
 export type { Diagnostic, DiagnosticId, DiagnosticSeverity } from './model/diagnostic.js';
-export type { RegisterCareMode, RegisterCareOutputCandidate, RegisterCareUnit, } from './register-care/types.js';
+export type { RegisterCareMode, RegisterCareOutputCandidate, RegisterCareUnit, RegisterContractsMode, RegisterContractsOutputCandidate, RegisterContractsUnit, } from './register-contracts/types.js';

package/dist/src/api-tooling.js

@@ -1,3 +1,3 @@
 export { analyzeProgram, analyzeProgramNext, loadProgram, loadProgramNext } from './tooling/api.js';
-export { analyzeRegisterCareForTools, codeActionForOutputCandidate, diagnosticForOutputCandidate, } from './register-care/tooling.js';
+export { analyzeRegisterCareForTools, analyzeRegisterContractsForTools, codeActionForOutputCandidate, diagnosticForOutputCandidate, } from './register-contracts/tooling.js';
 export { DiagnosticIds } from './model/diagnostic.js';

package/dist/src/assembly/address-planning.d.ts

@@ -1,7 +1,7 @@
 import type { Diagnostic } from '../model/diagnostic.js';
 import type { SourceItem } from '../model/source-item.js';
-import type { SymbolTable } from '../model/symbol.js';
 import { type EquateRecord, type LayoutRecord } from '../semantics/expression-evaluation.js';
+export { resolveSymbols } from './address-symbols.js';
 export interface AddressState {
     readonly labels: Record<string, number>;
     readonly equates: Map<string, EquateRecord>;
@@ -16,4 +16,3 @@ export declare function buildAddressState(items: readonly SourceItem[], diagnost
 };
 export declare function stringDirectiveBytes(directive: 'cstr' | 'pstr' | 'istr', value: string): readonly number[];
 export declare function alignmentPadding(address: number, alignment: number): number;
-export declare function resolveSymbols(labels: Readonly<Record<string, number>>, equates: ReadonlyMap<string, EquateRecord>, layouts: ReadonlyMap<string, LayoutRecord>, diagnostics: Diagnostic[]): SymbolTable;