@jhlagado/azm 0.2.7 → 0.2.8

package/dist/src/expansion/op-selection.js

@@ -0,0 +1,172 @@
+import { expressionFitsKnownImm16, expressionFitsKnownImm8, } from './op-constant-expression.js';
+import { formatOpOperand, isConditionToken, } from './op-operands.js';
+const MATCHER_OPERAND_PREDICATES = {
+    reg8: (operand) => operand.kind === 'reg8',
+    reg16: (operand) => operand.kind === 'reg16',
+    imm8: (operand) => operand.kind === 'imm' && expressionFitsKnownImm8(operand.expression),
+    imm16: (operand) => operand.kind === 'imm' && expressionFitsKnownImm16(operand.expression),
+    cc: (operand) => isConditionToken(operand.text),
+    idx16: (operand) => operand.kind === 'indexed',
+    ea: (operand) => operand.kind === 'imm',
+    mem8: (operand) => isMemoryOperand(operand),
+    mem16: (operand) => isMemoryOperand(operand),
+};
+const MATCHER_EXPECTATIONS = {
+    reg8: 'reg8',
+    reg16: 'reg16',
+    imm8: 'imm8',
+    imm16: 'imm16',
+    cc: 'condition token NZ/Z/NC/C/PO/PE/P/M',
+    idx16: 'IX/IY indexed memory operand',
+    ea: 'ea',
+    mem8: 'mem8 dereference',
+    mem16: 'mem16 dereference',
+};
+export function selectOpOverload(overloads, operands) {
+    const arityMatches = overloads.filter((overload) => overload.params.length === operands.length);
+    if (arityMatches.length === 0) {
+        return { kind: 'arity_mismatch' };
+    }
+    const matches = arityMatches.filter((overload) => overload.params.every((param, index) => matcherMatchesOperand(param.matcher, operands[index])));
+    if (matches.length === 0) {
+        return { kind: 'no_match', candidates: arityMatches };
+    }
+    if (matches.length === 1) {
+        return { kind: 'selected', overload: matches[0] };
+    }
+    const selected = mostSpecificOverload(matches, operands);
+    return selected
+        ? { kind: 'selected', overload: selected }
+        : { kind: 'ambiguous', candidates: matches };
+}
+function mostSpecificOverload(overloads, operands) {
+    for (const candidate of overloads) {
+        let beatsAll = true;
+        for (const other of overloads) {
+            if (candidate === other)
+                continue;
+            if (compareOverloadSpecificity(candidate, other, operands) !== 'x') {
+                beatsAll = false;
+                break;
+            }
+        }
+        if (beatsAll)
+            return candidate;
+    }
+    return undefined;
+}
+function compareOverloadSpecificity(x, y, operands) {
+    const votes = operands.reduce((current, operand, index) => {
+        return addSpecificityVote(current, compareMatcherSpecificity(x.params[index].matcher, y.params[index].matcher, operand));
+    }, { x: 0, y: 0 });
+    return specificityFromVotes(votes);
+}
+function addSpecificityVote(votes, comparison) {
+    if (comparison === 'x')
+        return { ...votes, x: votes.x + 1 };
+    if (comparison === 'y')
+        return { ...votes, y: votes.y + 1 };
+    return votes;
+}
+function specificityFromVotes(votes) {
+    if (votes.x > 0 && votes.y === 0)
+        return 'x';
+    if (votes.y > 0 && votes.x === 0)
+        return 'y';
+    if (votes.x === 0 && votes.y === 0)
+        return 'equal';
+    return 'incomparable';
+}
+function compareMatcherSpecificity(x, y, operand) {
+    if (x.kind === y.kind)
+        return 'equal';
+    return (compareFixedMatcherSpecificity(x, y, operand) ??
+        compareImmediateMatcherSpecificity(x, y, operand) ??
+        'equal');
+}
+function compareFixedMatcherSpecificity(x, y, operand) {
+    if (x.kind === 'fixed' && fixedTokenBeatsMatcher(x, y, operand))
+        return 'x';
+    if (y.kind === 'fixed' && fixedTokenBeatsMatcher(y, x, operand))
+        return 'y';
+    return undefined;
+}
+function compareImmediateMatcherSpecificity(x, y, operand) {
+    if (operand.kind !== 'imm' || !expressionFitsKnownImm8(operand.expression))
+        return undefined;
+    if (x.kind === 'imm8' && y.kind === 'imm16')
+        return 'x';
+    if (x.kind === 'imm16' && y.kind === 'imm8')
+        return 'y';
+    return undefined;
+}
+function fixedTokenBeatsMatcher(fixed, other, operand) {
+    return ((other.kind === 'reg8' && operand.kind === 'reg8' && operand.text === fixed.token) ||
+        (other.kind === 'reg16' && operand.kind === 'reg16' && operand.text === fixed.token) ||
+        (other.kind === 'cc' &&
+            isConditionToken(fixed.token) &&
+            operand.text.toUpperCase() === fixed.token));
+}
+function matcherMatchesOperand(matcher, operand) {
+    if (matcher.kind === 'fixed')
+        return operand.text.toUpperCase() === matcher.token;
+    return MATCHER_OPERAND_PREDICATES[matcher.kind]?.(operand) ?? false;
+}
+function isMemoryOperand(operand) {
+    return operand.kind === 'reg-indirect' || operand.kind === 'mem-abs' || operand.kind === 'indexed';
+}
+export function formatOpSelectionDiagnostic(selection, overloads, operands) {
+    const name = overloads[0]?.name ?? '<unknown>';
+    const operandSummary = `call-site operands: (${operands.map(formatOpOperand).join(', ')})`;
+    switch (selection.kind) {
+        case 'arity_mismatch':
+            return [
+                `No op overload of "${name}" accepts ${operands.length} operand(s).`,
+                'available overloads:',
+                ...overloads.map((overload) => `  - ${formatOpSignature(overload)}`),
+            ].join('\n');
+        case 'no_match':
+            return noMatchDiagnostic(selection.candidates, operands, name, operandSummary);
+        case 'ambiguous':
+            return [
+                `Ambiguous op overload for "${name}" (${selection.candidates.length} matches).`,
+                operandSummary,
+                'equally specific candidates:',
+                ...selection.candidates.map((candidate) => `  - ${formatOpSignatureWithLocation(candidate)}`),
+            ].join('\n');
+    }
+}
+function noMatchDiagnostic(candidates, operands, name, operandSummary) {
+    return [
+        `No matching op overload for "${name}" with provided operands.`,
+        operandSummary,
+        'available overloads:',
+        ...candidates.map((candidate) => {
+            const mismatch = firstMismatchReason(candidate, operands);
+            return `  - ${formatOpSignatureWithLocation(candidate)}${mismatch ? ` ; ${mismatch}` : ''}`;
+        }),
+    ].join('\n');
+}
+function firstMismatchReason(overload, operands) {
+    for (let index = 0; index < overload.params.length; index += 1) {
+        const param = overload.params[index];
+        const operand = operands[index];
+        if (!matcherMatchesOperand(param.matcher, operand)) {
+            return `${param.name}: ${matcherMismatchReason(param.matcher, operand)}`;
+        }
+    }
+    return undefined;
+}
+function matcherMismatchReason(matcher, operand) {
+    const expected = matcher.kind === 'fixed' ? matcher.token : MATCHER_EXPECTATIONS[matcher.kind];
+    return `expects ${expected}, got ${formatOpOperand(operand)}`;
+}
+function formatOpSignature(op) {
+    return `${op.name}(${op.params.map((param) => `${param.name} ${formatMatcher(param.matcher)}`).join(', ')})`;
+}
+function formatOpSignatureWithLocation(op) {
+    return `${formatOpSignature(op)} (${op.sourceName}:${op.line})`;
+}
+function formatMatcher(matcher) {
+    return matcher.kind === 'fixed' ? matcher.token : matcher.kind;
+}

package/dist/src/index.d.ts

@@ -6,9 +6,10 @@ 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 { analyzeRegisterCareForTools, analyzeRegisterContractsForTools, 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 { 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 { RegisterCareMode, RegisterCareOutputCandidate, RegisterCareUnit, RegisterContractsMode, RegisterContractsOutputCandidate, RegisterContractsUnit, } from './register-contracts/types.js';
 export type { D8mArtifact, D8mGenerator, D8mJson, D8mFileEntry, D8mFileSymbol, D8mSegment, D8mSymbol, SymbolEntry, WriteD8mOptions, } from './outputs/types.js';

package/dist/src/index.js

@@ -3,5 +3,5 @@ export { compileArtifacts, compileNextArtifacts } from './core/compile-artifacts
 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 { analyzeRegisterCareForTools, analyzeRegisterContractsForTools, } from './register-contracts/tooling.js';
 export { compile, defaultFormatWriters, writeHex } from './api-compile.js';

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

@@ -44,7 +44,11 @@ export declare const DiagnosticIds: {
     readonly TypeError: "AZM403";
     readonly CaseStyleLint: "AZM500";
     readonly IndexParenRedundant: "AZM501";
+    readonly RegisterContractsConflict: "AZM600";
+    readonly RegisterContractsUnknownBoundary: "AZM601";
+    /** @deprecated Use RegisterContractsConflict. */
     readonly RegisterCareConflict: "AZM600";
+    /** @deprecated Use RegisterContractsUnknownBoundary. */
     readonly RegisterCareUnknownBoundary: "AZM601";
 };
 export type DiagnosticId = (typeof DiagnosticIds)[keyof typeof DiagnosticIds];

package/dist/src/model/diagnostic.js

@@ -24,6 +24,10 @@ export const DiagnosticIds = {
     TypeError: 'AZM403',
     CaseStyleLint: 'AZM500',
     IndexParenRedundant: 'AZM501',
+    RegisterContractsConflict: 'AZM600',
+    RegisterContractsUnknownBoundary: 'AZM601',
+    /** @deprecated Use RegisterContractsConflict. */
     RegisterCareConflict: 'AZM600',
+    /** @deprecated Use RegisterContractsUnknownBoundary. */
     RegisterCareUnknownBoundary: 'AZM601',
 };

package/dist/src/outputs/asm80-expression-evaluation.d.ts

@@ -0,0 +1,10 @@
+import type { Expression } from '../model/expression.js';
+import { type LayoutRecord } from '../semantics/expression-evaluation.js';
+export type ConstantMap = ReadonlyMap<string, number>;
+export type LayoutMap = ReadonlyMap<string, LayoutRecord>;
+export type LoweredEvalContext = {
+    readonly constants: ConstantMap;
+    readonly symbols: ConstantMap;
+    readonly layouts: LayoutMap;
+};
+export declare function evaluateLoweredConstant(expression: Expression, evalContext: LoweredEvalContext): number | undefined;

package/dist/src/outputs/asm80-expression-evaluation.js

@@ -0,0 +1,75 @@
+import { evaluateExpression, } from '../semantics/expression-evaluation.js';
+import { applyBinaryOperator, applyByteFunction, applyUnaryOperator, } from '../semantics/constant-operators.js';
+const silentSpan = { sourceName: '', line: 0, column: 0 };
+export function evaluateLoweredConstant(expression, evalContext) {
+    switch (expression.kind) {
+        case 'number':
+            return expression.value;
+        case 'symbol':
+            return evalContext.constants.get(expression.name);
+        case 'type-size':
+            return evaluateLoweredTypeSize(expression, evalContext);
+        case 'offset':
+        case 'sizeof':
+            return evaluateLayoutExpression(expression, evalContext);
+        case 'byte-function':
+            return evaluateLoweredByteFunction(expression, evalContext);
+        case 'unary':
+            return evaluateLoweredUnary(expression, evalContext);
+        case 'binary':
+            return evaluateLoweredBinary(expression, evalContext);
+        default:
+            return undefined;
+    }
+}
+function evaluateLoweredTypeSize(expression, evalContext) {
+    const constant = evalContext.constants.get(expression.typeExpr.name);
+    return constant ?? evaluateLayoutExpression(expression, evalContext);
+}
+function evaluateLayoutExpression(expression, evalContext) {
+    return evaluateExpression(expression, {}, new Map(), silentSpan, [], {
+        currentLocation: 0,
+        layouts: evalContext.layouts,
+        reportUnknown: false,
+    });
+}
+function evaluateLoweredByteFunction(expression, evalContext) {
+    const value = evaluateLoweredResolvedConstant(expression.expression, evalContext);
+    return value === undefined ? undefined : applyByteFunction(expression.function, value);
+}
+function evaluateLoweredUnary(expression, evalContext) {
+    const value = evaluateLoweredConstant(expression.expression, evalContext);
+    return value === undefined ? undefined : applyUnaryOperator(expression.operator, value);
+}
+function evaluateLoweredBinary(expression, evalContext) {
+    const left = evaluateLoweredConstant(expression.left, evalContext);
+    const right = evaluateLoweredConstant(expression.right, evalContext);
+    return left === undefined || right === undefined
+        ? undefined
+        : applyBinaryOperator(expression.operator, left, right);
+}
+function evaluateLoweredResolvedConstant(expression, evalContext) {
+    switch (expression.kind) {
+        case 'symbol':
+            return evalContext.symbols.get(expression.name) ?? evalContext.constants.get(expression.name);
+        case 'unary':
+            return evaluateResolvedUnary(expression, evalContext);
+        case 'binary':
+            return evaluateResolvedBinary(expression, evalContext);
+        case 'byte-function':
+            return evaluateLoweredByteFunction(expression, evalContext);
+        default:
+            return evaluateLoweredConstant(expression, evalContext);
+    }
+}
+function evaluateResolvedUnary(expression, evalContext) {
+    const value = evaluateLoweredResolvedConstant(expression.expression, evalContext);
+    return value === undefined ? undefined : applyUnaryOperator(expression.operator, value);
+}
+function evaluateResolvedBinary(expression, evalContext) {
+    const left = evaluateLoweredResolvedConstant(expression.left, evalContext);
+    const right = evaluateLoweredResolvedConstant(expression.right, evalContext);
+    return left === undefined || right === undefined
+        ? undefined
+        : applyBinaryOperator(expression.operator, left, right);
+}

package/dist/src/outputs/asm80-expressions.d.ts

@@ -0,0 +1,5 @@
+import type { Expression } from '../model/expression.js';
+import { type LoweredEvalContext } from './asm80-expression-evaluation.js';
+export { evaluateLoweredConstant, type ConstantMap, type LayoutMap, type LoweredEvalContext, } from './asm80-expression-evaluation.js';
+export declare function formatExpression(expression: Expression, evalContext: LoweredEvalContext, width: 'byte' | 'word' | 'auto'): string | undefined;
+export declare function formatLoweredNumber(value: number, width: 'byte' | 'word' | 'auto'): string;

package/dist/src/outputs/asm80-expressions.js

@@ -0,0 +1,47 @@
+import { evaluateLoweredConstant } from './asm80-expression-evaluation.js';
+export { evaluateLoweredConstant, } from './asm80-expression-evaluation.js';
+const formatUnaryExpression = {
+    '+': (inner) => inner,
+    '-': (inner) => `-${inner}`,
+    '~': () => undefined,
+};
+export function formatExpression(expression, evalContext, width) {
+    const value = evaluateLoweredConstant(expression, evalContext);
+    if (value !== undefined) {
+        return formatLoweredNumber(value, width);
+    }
+    return formatUnevaluatedExpression(expression, evalContext, width);
+}
+export function formatLoweredNumber(value, width) {
+    const normalized = value < 0 ? value & 0xffff : value;
+    const digits = normalized.toString(16).toUpperCase();
+    const minWidth = width === 'word' || (width === 'auto' && normalized > 0xff) ? 4 : 2;
+    return `$${digits.padStart(minWidth, '0')}`;
+}
+function formatUnevaluatedExpression(expression, evalContext, width) {
+    switch (expression.kind) {
+        case 'symbol':
+            return expression.name;
+        case 'type-size':
+            return expression.typeExpr.name;
+        case 'current-location':
+            return '$';
+        case 'unary':
+            return formatUnary(expression, evalContext, width);
+        case 'binary':
+            return formatBinary(expression, evalContext, width);
+        default:
+            return undefined;
+    }
+}
+function formatUnary(expression, evalContext, width) {
+    const inner = formatExpression(expression.expression, evalContext, width);
+    return inner === undefined ? undefined : formatUnaryExpression[expression.operator](inner);
+}
+function formatBinary(expression, evalContext, width) {
+    const left = formatExpression(expression.left, evalContext, width);
+    const right = formatExpression(expression.right, evalContext, width);
+    return left === undefined || right === undefined
+        ? undefined
+        : `${left}${expression.operator}${right}`;
+}

package/dist/src/outputs/asm80-instruction-operands.d.ts

@@ -0,0 +1,16 @@
+import type { Z80Instruction } from '../z80/instruction.js';
+import { type LoweredEvalContext } from './asm80-expressions.js';
+import { formatIndexedMemory, formatLd, type LdOperand } from './asm80-ld-operands.js';
+export type BitInstruction = Extract<Z80Instruction, {
+    readonly mnemonic: 'bit' | 'res' | 'set';
+}>;
+export type RotateShiftInstruction = Extract<Z80Instruction, {
+    readonly mnemonic: 'rlc' | 'rrc' | 'rl' | 'rr' | 'sla' | 'sra' | 'sll' | 'sls' | 'srl';
+}>;
+export { formatIndexedMemory, formatLd, type LdOperand };
+export declare function formatRotateShift(instruction: RotateShiftInstruction, evalContext: LoweredEvalContext): {
+    readonly text: string;
+} | undefined;
+export declare function formatBitOp(instruction: BitInstruction, evalContext: LoweredEvalContext): {
+    readonly text: string;
+} | undefined;

package/dist/src/outputs/asm80-instruction-operands.js

@@ -0,0 +1,38 @@
+import { formatLoweredNumber } from './asm80-expressions.js';
+import { formatIndexedMemory, formatLd } from './asm80-ld-operands.js';
+export { formatIndexedMemory, formatLd };
+export function formatRotateShift(instruction, evalContext) {
+    const operand = formatBitOperand(instruction.operand, evalContext);
+    if (operand === undefined) {
+        return undefined;
+    }
+    const parts = [operand];
+    if (instruction.destination) {
+        parts.push(instruction.destination.register);
+    }
+    return { text: `${instruction.mnemonic} ${parts.join(', ')}` };
+}
+export function formatBitOp(instruction, evalContext) {
+    const bit = formatLoweredNumber(instruction.bit, 'byte');
+    const operand = formatBitOperand(instruction.operand, evalContext);
+    if (operand === undefined) {
+        return undefined;
+    }
+    const parts = [bit, operand];
+    if (instruction.destination) {
+        parts.push(instruction.destination.register);
+    }
+    return { text: `${instruction.mnemonic} ${parts.join(', ')}` };
+}
+function formatBitOperand(operand, evalContext) {
+    if (operand.kind === 'reg8') {
+        return operand.register;
+    }
+    if (operand.kind === 'reg-indirect' && operand.register === 'hl') {
+        return '(HL)';
+    }
+    if (operand.kind === 'indexed') {
+        return formatIndexedMemory(operand.register, operand.displacement, evalContext);
+    }
+    return undefined;
+}

package/dist/src/outputs/asm80-instructions.d.ts

@@ -0,0 +1,5 @@
+import type { Z80Instruction } from '../z80/instruction.js';
+import { type LoweredEvalContext } from './asm80-expressions.js';
+export declare function formatInstruction(instruction: Z80Instruction, evalContext: LoweredEvalContext): {
+    readonly text: string;
+} | undefined;