@jhlagado/azm 0.2.7 → 0.2.9

package/dist/src/register-contracts/summary-token-transfer.js

@@ -0,0 +1,67 @@
+import { instructionHead } from './instruction-head.js';
+import { regName } from './operand-register-name.js';
+import { instructionOperand, instructionOperandCount } from './instruction-operands.js';
+import { getRegisterUnits, readToken, unique } from './summary-state.js';
+export function applyPureTokenTransfer(tokens, consumedProduced, item) {
+    const head = instructionHead(item).toLowerCase();
+    if (head === 'ld')
+        return applyLdTokenTransfer(tokens, consumedProduced, item);
+    if (head === 'ex')
+        return applyExTokenTransfer(tokens, item);
+    return [];
+}
+function applyLdTokenTransfer(tokens, consumedProduced, item) {
+    if (instructionOperandCount(item.instruction) !== 2)
+        return [];
+    const dstUnits = operandRegisterUnits(item, 0);
+    if (!dstUnits)
+        return [];
+    const srcUnits = operandRegisterUnits(item, 1);
+    if (srcUnits && srcUnits.length === dstUnits.length) {
+        copyTokenUnits(tokens, consumedProduced, dstUnits, srcUnits);
+    }
+    else {
+        markUnitsProduced(tokens, consumedProduced, dstUnits);
+    }
+    return dstUnits;
+}
+function applyExTokenTransfer(tokens, item) {
+    if (instructionOperandCount(item.instruction) !== 2)
+        return [];
+    const leftUnits = operandRegisterUnits(item, 0);
+    const rightUnits = operandRegisterUnits(item, 1);
+    if (!leftUnits || !rightUnits || leftUnits.length !== rightUnits.length)
+        return [];
+    swapTokenUnits(tokens, leftUnits, rightUnits);
+    return unique([...leftUnits, ...rightUnits]);
+}
+function operandRegisterUnits(item, operandIndex) {
+    const name = regName(instructionOperand(item.instruction, operandIndex));
+    return name ? getRegisterUnits(name) : undefined;
+}
+function copyTokenUnits(tokens, consumedProduced, dstUnits, srcUnits) {
+    dstUnits.forEach((unit, index) => {
+        const sourceUnit = srcUnits[index];
+        const sourceToken = readToken(tokens, sourceUnit);
+        tokens.set(unit, sourceToken);
+        if (sourceToken.origin === 'produced')
+            consumedProduced.add(sourceUnit);
+        consumedProduced.delete(unit);
+    });
+}
+function markUnitsProduced(tokens, consumedProduced, units) {
+    for (const unit of units) {
+        tokens.set(unit, { origin: 'produced' });
+        consumedProduced.delete(unit);
+    }
+}
+function swapTokenUnits(tokens, leftUnits, rightUnits) {
+    const leftTokens = leftUnits.map((unit) => readToken(tokens, unit));
+    const rightTokens = rightUnits.map((unit) => readToken(tokens, unit));
+    leftUnits.forEach((unit, index) => {
+        tokens.set(unit, rightTokens[index] ?? { origin: 'unknown' });
+    });
+    rightUnits.forEach((unit, index) => {
+        tokens.set(unit, leftTokens[index] ?? { origin: 'unknown' });
+    });
+}

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

@@ -0,0 +1,3 @@
+export { applyRoutineContract } from './summary-contract.js';
+import type { RegisterContractsRoutine, RoutineSummary } from './types.js';
+export declare function inferRoutineSummary(routine: RegisterContractsRoutine, boundarySummaries?: ReadonlyMap<string, RoutineSummary>): RoutineSummary;

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

@@ -0,0 +1,266 @@
+import { getZ80InstructionEffect } from '../z80/effects.js';
+import { instructionHead } from './instruction-head.js';
+import { isAccumulatorSelfOperand, isImmediateZeroOperand, isPureTokenTransferInstruction, isRegisterOperand, } from './instruction-predicates.js';
+import { boundarySummary } from './summary-boundary.js';
+import { CONTRACT_FLAG_UNITS, STACK_POINTER_UNITS, TRACKED_UNITS, isTrackedUnit, markProducedReadsConsumed, readToken, semanticReadOrigins, } from './summary-state.js';
+import { applyPureTokenTransfer } from './summary-token-transfer.js';
+export { applyRoutineContract } from './summary-contract.js';
+import { buildRoutineSummary } from './summary-result.js';
+function isOpaqueBoundary(item, effect) {
+    if (effect.control.kind === 'call' || effect.control.kind === 'rst')
+        return true;
+    return (effect.control.kind === 'jump' &&
+        (instructionHead(item) === 'jp' || instructionHead(item) === 'jp-cc') &&
+        !effect.control.conditional &&
+        Boolean(effect.control.target) &&
+        !effect.control.target?.startsWith('.'));
+}
+function isRoutineReturn(effect) {
+    return effect.control.kind === 'return';
+}
+function isPureTokenTransfer(item) {
+    return isPureTokenTransferInstruction(item);
+}
+function isCarryClearBeforeSbcHl(item, next) {
+    const head = instructionHead(item).toLowerCase();
+    if (head !== 'or' && head !== 'and')
+        return false;
+    if (!isAccumulatorSelfOperand(item))
+        return false;
+    return next !== undefined && instructionHead(next) === 'sbc' && isRegisterOperand(next, 0, 'HL');
+}
+function intentOutputUnits(item) {
+    const head = instructionHead(item).toLowerCase();
+    if (head === 'scf' || head === 'ccf')
+        return ['carry'];
+    if (head === 'cp')
+        return isImmediateZeroOperand(item) ? ['A', 'carry', 'zero'] : ['carry', 'zero'];
+    if ((head === 'or' || head === 'and' || head === 'xor') && isAccumulatorSelfOperand(item)) {
+        return ['A', 'carry', 'zero'];
+    }
+    return [];
+}
+function isMechanicalResidueWrite(item, unit) {
+    const head = instructionHead(item).toLowerCase();
+    if (head === 'djnz')
+        return unit === 'B';
+    if (BLOCK_TRANSFER_HEADS.has(head))
+        return BLOCK_TRANSFER_RESIDUE_UNITS.has(unit);
+    return false;
+}
+const BLOCK_TRANSFER_HEADS = new Set(['ldi', 'ldir', 'ldd', 'lddr']);
+const BLOCK_TRANSFER_RESIDUE_UNITS = new Set(['B', 'C', 'D', 'E', 'H', 'L']);
+function applyKnownBoundarySummary(tokens, consumedProduced, intendedProduced, directMayWrite, summary) {
+    for (const relation of summary.valueRelations) {
+        const sameCarrierRelation = relation.out.length === relation.from.length &&
+            relation.out.every((unit, index) => unit === relation.from[index]);
+        relation.out.forEach((unit, index) => {
+            if (!sameCarrierRelation &&
+                relation.from.length === relation.out.length &&
+                relation.from[index]) {
+                tokens.set(unit, readToken(tokens, relation.from[index]));
+            }
+            else {
+                tokens.set(unit, { origin: 'produced' });
+                consumedProduced.delete(unit);
+                if (CONTRACT_FLAG_UNITS.has(unit))
+                    intendedProduced.add(unit);
+            }
+        });
+    }
+    for (const unit of summary.mayWrite) {
+        if (STACK_POINTER_UNITS.has(unit))
+            continue;
+        if (isTrackedUnit(unit)) {
+            tokens.set(unit, { origin: 'unknown' });
+            consumedProduced.delete(unit);
+            intendedProduced.delete(unit);
+        }
+        else {
+            directMayWrite.push(unit);
+        }
+    }
+}
+function applyStackPop(tokens, consumedProduced, intendedProduced, stack, state, units) {
+    const popped = stack.pop();
+    if (!popped) {
+        state.stackBalanced = false;
+        for (const unit of units) {
+            tokens.set(unit, { origin: 'unknown' });
+            intendedProduced.delete(unit);
+        }
+        return;
+    }
+    if (popped.length !== units.length) {
+        for (const unit of units) {
+            tokens.set(unit, { origin: 'unknown' });
+            consumedProduced.delete(unit);
+            intendedProduced.delete(unit);
+        }
+        return;
+    }
+    units.forEach((unit, idx) => {
+        tokens.set(unit, popped[idx] ?? { origin: 'unknown' });
+        consumedProduced.delete(unit);
+        intendedProduced.delete(unit);
+    });
+}
+function applyUnknownStackUnits(tokens, consumedProduced, intendedProduced, units) {
+    for (const unit of units) {
+        tokens.set(unit, { origin: 'unknown' });
+        consumedProduced.delete(unit);
+        intendedProduced.delete(unit);
+    }
+}
+function applyStackEffect(tokens, consumedProduced, intendedProduced, stack, state, effect, expectedTerminalReturn, knownBoundary) {
+    if (effect.stack.kind === 'push') {
+        stack.push(effect.stack.units.map((unit) => readToken(tokens, unit)));
+        return;
+    }
+    if (effect.stack.kind === 'pop') {
+        applyStackPop(tokens, consumedProduced, intendedProduced, stack, state, effect.stack.units);
+        return;
+    }
+    if (effect.stack.kind === 'exchangeTop') {
+        state.hasUnknownStackEffect = true;
+        applyUnknownStackUnits(tokens, consumedProduced, intendedProduced, effect.stack.units);
+        return;
+    }
+    if (expectedTerminalReturn && stack.length !== 0) {
+        state.stackBalanced = false;
+    }
+    if (effect.stack.kind === 'unknown' &&
+        !expectedTerminalReturn &&
+        (!knownBoundary || !knownBoundary.stackBalanced || knownBoundary.hasUnknownStackEffect)) {
+        state.hasUnknownStackEffect = true;
+    }
+}
+function applyEffectWrites(tokens, consumedProduced, intendedProduced, directMayWrite, item, effect, transferWrites, instructionIntentOutputs, carryClearBeforeSbcHl) {
+    for (const unit of effect.writes) {
+        if (shouldIgnoreEffectWrite(unit, effect, transferWrites))
+            continue;
+        if (applyAccumulatorSelfWrite(unit, item, intendedProduced, carryClearBeforeSbcHl))
+            continue;
+        applyEffectWriteUnit(tokens, consumedProduced, intendedProduced, directMayWrite, item, unit, instructionIntentOutputs);
+    }
+}
+function shouldIgnoreEffectWrite(unit, effect, transferWrites) {
+    return (STACK_POINTER_UNITS.has(unit) ||
+        isStackPopTrackedWrite(unit, effect) ||
+        (transferWrites.has(unit) && isTrackedUnit(unit)));
+}
+function isStackPopTrackedWrite(unit, effect) {
+    return effect.stack.kind === 'pop' && effect.stack.units.includes(unit) && isTrackedUnit(unit);
+}
+function applyAccumulatorSelfWrite(unit, item, intendedProduced, carryClearBeforeSbcHl) {
+    if (unit !== 'A' || !isOrAndAccumulatorSelf(item))
+        return false;
+    if (!carryClearBeforeSbcHl)
+        intendedProduced.add(unit);
+    return true;
+}
+function isOrAndAccumulatorSelf(item) {
+    const head = instructionHead(item).toLowerCase();
+    return (head === 'or' || head === 'and') && isAccumulatorSelfOperand(item);
+}
+function applyEffectWriteUnit(tokens, consumedProduced, intendedProduced, directMayWrite, item, unit, instructionIntentOutputs) {
+    if (!isTrackedUnit(unit)) {
+        directMayWrite.push(unit);
+        return;
+    }
+    tokens.set(unit, { origin: isMechanicalResidueWrite(item, unit) ? 'unknown' : 'produced' });
+    consumedProduced.delete(unit);
+    if (instructionIntentOutputs.includes(unit))
+        intendedProduced.add(unit);
+    else
+        intendedProduced.delete(unit);
+}
+function addInstructionIntentOutputs(intendedProduced, effectWrites, instructionIntentOutputs) {
+    for (const unit of instructionIntentOutputs) {
+        if (!isTrackedUnit(unit) || effectWrites.has(unit))
+            continue;
+        intendedProduced.add(unit);
+    }
+}
+function recordInstructionReads(tokens, consumedProduced, intendedProduced, mayRead, item, effect, knownBoundary, semanticReads, effectWrites) {
+    if (effect.stack.kind !== 'push' && !isPureTokenTransfer(item)) {
+        mayRead.push(...semanticReadOrigins(tokens, semanticReads));
+        markProducedReadsConsumed(tokens, consumedProduced, semanticReads, effectWrites, item);
+    }
+    if (instructionHead(item).toLowerCase() === 'djnz') {
+        for (const unit of TRACKED_UNITS) {
+            if (readToken(tokens, unit).origin === 'produced')
+                consumedProduced.add(unit);
+            intendedProduced.delete(unit);
+        }
+    }
+    if (knownBoundary) {
+        mayRead.push(...semanticReadOrigins(tokens, knownBoundary.mayRead));
+        markProducedReadsConsumed(tokens, consumedProduced, knownBoundary.mayRead, new Set());
+    }
+}
+function createInferenceState() {
+    const tokens = new Map();
+    for (const unit of TRACKED_UNITS)
+        tokens.set(unit, { origin: unit });
+    return {
+        tokens,
+        stack: [],
+        mayRead: [],
+        directMayWrite: [],
+        consumedProduced: new Set(),
+        intendedProduced: new Set(),
+        stackState: {
+            stackBalanced: true,
+            hasUnknownStackEffect: false,
+        },
+    };
+}
+function instructionInferenceContext(routine, index, boundarySummaries) {
+    const item = routine.instructions[index];
+    const effect = getZ80InstructionEffect(item.instruction);
+    const carryClearBeforeSbcHl = isCarryClearBeforeSbcHl(item, routine.instructions[index + 1]);
+    return {
+        item,
+        effect,
+        knownBoundary: boundarySummary(routine, index, boundarySummaries),
+        carryClearBeforeSbcHl,
+        expectedTerminalReturn: isRoutineReturn(effect),
+        effectWrites: new Set(effect.writes),
+        instructionIntentOutputs: carryClearBeforeSbcHl ? [] : intentOutputUnits(item),
+        semanticReads: carryClearBeforeSbcHl
+            ? effect.reads.filter((unit) => unit !== 'A')
+            : effect.reads,
+    };
+}
+function applyBoundaryOrOpaqueWrites(state, context) {
+    if (context.knownBoundary) {
+        applyKnownBoundarySummary(state.tokens, state.consumedProduced, state.intendedProduced, state.directMayWrite, context.knownBoundary);
+    }
+    else if (isOpaqueBoundary(context.item, context.effect)) {
+        for (const unit of TRACKED_UNITS) {
+            state.tokens.set(unit, { origin: 'unknown' });
+            state.consumedProduced.delete(unit);
+            state.intendedProduced.delete(unit);
+        }
+    }
+}
+function inferInstructionSummaryStep(state, context) {
+    recordInstructionReads(state.tokens, state.consumedProduced, state.intendedProduced, state.mayRead, context.item, context.effect, context.knownBoundary, [...context.semanticReads], context.effectWrites);
+    applyStackEffect(state.tokens, state.consumedProduced, state.intendedProduced, state.stack, state.stackState, context.effect, context.expectedTerminalReturn, context.knownBoundary);
+    const transferWrites = new Set(isPureTokenTransfer(context.item)
+        ? applyPureTokenTransfer(state.tokens, state.consumedProduced, context.item)
+        : []);
+    applyBoundaryOrOpaqueWrites(state, context);
+    applyEffectWrites(state.tokens, state.consumedProduced, state.intendedProduced, state.directMayWrite, context.item, context.effect, transferWrites, context.instructionIntentOutputs, context.carryClearBeforeSbcHl);
+    addInstructionIntentOutputs(state.intendedProduced, context.effectWrites, context.instructionIntentOutputs);
+}
+export function inferRoutineSummary(routine, boundarySummaries = new Map()) {
+    const state = createInferenceState();
+    for (let index = 0; index < routine.instructions.length; index += 1) {
+        inferInstructionSummaryStep(state, instructionInferenceContext(routine, index, boundarySummaries));
+    }
+    if (state.stack.length !== 0)
+        state.stackState.stackBalanced = false;
+    return buildRoutineSummary(routine, state.tokens, state.consumedProduced, state.intendedProduced, state.directMayWrite, state.mayRead, state.stackState);
+}

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

@@ -0,0 +1,57 @@
+import type { Diagnostic } from '../model/diagnostic.js';
+import type { LoadedProgram } from '../tooling/api.js';
+import type { AnalyzeRegisterContractsOptions, RegisterContractsOutputCandidate, RegisterContractsUnit } from './types.js';
+export interface RegisterContractsTextEdit {
+    file: string;
+    line: number;
+    column: number;
+    text: string;
+}
+/** @deprecated Use RegisterContractsTextEdit. */
+export type RegisterCareTextEdit = RegisterContractsTextEdit;
+export interface RegisterContractsCodeAction {
+    title: string;
+    kind: 'quickfix';
+    edit: RegisterContractsTextEdit;
+}
+/** @deprecated Use RegisterContractsCodeAction. */
+export type RegisterCareCodeAction = RegisterContractsCodeAction;
+export interface RegisterContractsCandidateDiagnostic {
+    kind: 'register-contracts-output-candidate';
+    severity: 'info';
+    file: string;
+    line: number;
+    column: number;
+    routine: string;
+    carriers: RegisterContractsUnit[];
+    autoFixable: boolean;
+    message: string;
+    codeAction?: RegisterContractsCodeAction;
+}
+/** @deprecated Use RegisterContractsCandidateDiagnostic. */
+export type RegisterCareCandidateDiagnostic = RegisterContractsCandidateDiagnostic;
+export interface AnalyzeRegisterContractsForToolsOptions extends Omit<AnalyzeRegisterContractsOptions, 'emitReport' | 'emitInterface' | 'emitAnnotations' | 'fixRegisterContracts'> {
+    emitReport?: boolean;
+    emitInterface?: boolean;
+    /** Back-compat alias for registerContractsProfile used by some tooling integrations. */
+    profile?: AnalyzeRegisterContractsOptions['registerContractsProfile'];
+    /** @deprecated Use registerContractsProfile. */
+    registerCareProfile?: AnalyzeRegisterContractsOptions['registerContractsProfile'];
+}
+/** @deprecated Use AnalyzeRegisterContractsForToolsOptions. */
+export type AnalyzeRegisterCareForToolsOptions = AnalyzeRegisterContractsForToolsOptions;
+export interface AnalyzeRegisterContractsForToolsResult {
+    diagnostics: Diagnostic[];
+    outputCandidates: RegisterContractsOutputCandidate[];
+    candidateDiagnostics: RegisterContractsCandidateDiagnostic[];
+    codeActions: RegisterContractsCodeAction[];
+    reportText?: string;
+    interfaceText?: string;
+}
+/** @deprecated Use AnalyzeRegisterContractsForToolsResult. */
+export type AnalyzeRegisterCareForToolsResult = AnalyzeRegisterContractsForToolsResult;
+export declare function codeActionForOutputCandidate(candidate: RegisterContractsOutputCandidate): RegisterContractsCodeAction;
+export declare function diagnosticForOutputCandidate(candidate: RegisterContractsOutputCandidate): RegisterContractsCandidateDiagnostic;
+export declare function analyzeRegisterContractsForTools(loaded: LoadedProgram, options: AnalyzeRegisterContractsForToolsOptions): AnalyzeRegisterContractsForToolsResult;
+/** @deprecated Use analyzeRegisterContractsForTools. */
+export declare const analyzeRegisterCareForTools: typeof analyzeRegisterContractsForTools;

package/dist/src/{register-care → register-contracts}/tooling.js

@@ -1,4 +1,4 @@
-import { analyzeRegisterCare } from './analyze.js';
+import { analyzeRegisterContracts } from './analyze.js';
 import { contractCarrierList } from './report.js';
 function expectOutText(carriers) {
     return `; expects out ${contractCarrierList(carriers)}\n`;
@@ -18,7 +18,7 @@ export function codeActionForOutputCandidate(candidate) {
 export function diagnosticForOutputCandidate(candidate) {
     const codeAction = candidate.autoFixable === true ? codeActionForOutputCandidate(candidate) : undefined;
     const diagnostic = {
-        kind: 'register-care-output-candidate',
+        kind: 'register-contracts-output-candidate',
         severity: 'info',
         file: candidate.file,
         line: candidate.line,
@@ -33,8 +33,8 @@ export function diagnosticForOutputCandidate(candidate) {
     }
     return diagnostic;
 }
-export function analyzeRegisterCareForTools(loaded, options) {
-    const profile = options.registerCareProfile ?? options.profile;
+export function analyzeRegisterContractsForTools(loaded, options) {
+    const profile = options.registerContractsProfile ?? options.registerCareProfile ?? options.profile;
     const baseResultOptions = {
         ...options,
         emitReport: options.emitReport === true,
@@ -42,9 +42,9 @@ export function analyzeRegisterCareForTools(loaded, options) {
         emitAnnotations: false,
         fixRegisterContracts: false,
     };
-    const result = analyzeRegisterCare(loaded, profile === undefined
+    const result = analyzeRegisterContracts(loaded, profile === undefined
         ? baseResultOptions
-        : { ...baseResultOptions, registerCareProfile: profile });
+        : { ...baseResultOptions, registerContractsProfile: profile });
     const outputCandidates = result.outputCandidates ?? [];
     const candidateDiagnostics = outputCandidates.map(diagnosticForOutputCandidate);
     const codeActions = outputCandidates
@@ -59,3 +59,5 @@ export function analyzeRegisterCareForTools(loaded, options) {
         ...(result.interfaceText !== undefined ? { interfaceText: result.interfaceText } : {}),
     };
 }
+/** @deprecated Use analyzeRegisterContractsForTools. */
+export const analyzeRegisterCareForTools = analyzeRegisterContractsForTools;

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

@@ -0,0 +1,188 @@
+import type { Z80Instruction } from '../z80/instruction.js';
+export type RegisterContractsMode = 'off' | 'audit' | 'warn' | 'error' | 'strict';
+/** @deprecated Use RegisterContractsMode. */
+export type RegisterCareMode = RegisterContractsMode;
+export type RegisterContractsUnit = 'A' | 'B' | 'C' | 'D' | 'E' | 'H' | 'L' | 'IXH' | 'IXL' | 'IYH' | 'IYL' | 'SPH' | 'SPL' | 'carry' | 'zero' | 'sign' | 'parity' | 'halfCarry';
+/** @deprecated Use RegisterContractsUnit. */
+export type RegisterCareUnit = RegisterContractsUnit;
+export type SmartComment = {
+    kind: 'extern';
+    name: string;
+} | {
+    kind: 'end';
+} | {
+    kind: 'in';
+    carriers: RegisterContractsUnit[];
+    name?: string;
+} | {
+    kind: 'out';
+    carriers: RegisterContractsUnit[];
+    name?: string;
+} | {
+    kind: 'clobbers';
+    carriers: RegisterContractsUnit[];
+} | {
+    kind: 'preserves';
+    carriers: RegisterContractsUnit[];
+} | {
+    kind: 'expectOut';
+    carriers: RegisterContractsUnit[];
+    name?: string;
+};
+export interface LocatedSmartComment {
+    file: string;
+    line: number;
+    comment: SmartComment;
+}
+export interface RoutineContract {
+    name: string;
+    in: RegisterContractsUnit[];
+    out: RegisterContractsUnit[];
+    clobbers: RegisterContractsUnit[];
+    preserves: RegisterContractsUnit[];
+    complete?: boolean;
+}
+export interface RegisterContractsInstruction {
+    instruction: Z80Instruction;
+    file: string;
+    line: number;
+    column: number;
+    labels: string[];
+    constants?: ReadonlyMap<string, number>;
+}
+/** @deprecated Use RegisterContractsInstruction. */
+export type RegisterCareInstruction = RegisterContractsInstruction;
+export interface RegisterContractsRoutine {
+    name: string;
+    labels: string[];
+    entryLabels: string[];
+    instructions: RegisterContractsInstruction[];
+    constants?: ReadonlyMap<string, number>;
+    span: {
+        file: string;
+        start: {
+            line: number;
+            column: number;
+        };
+        end: {
+            line: number;
+            column: number;
+        };
+    };
+}
+/** @deprecated Use RegisterContractsRoutine. */
+export type RegisterCareRoutine = RegisterContractsRoutine;
+export interface RegisterContractsDirectCall {
+    target: string;
+    subject: string;
+    file: string;
+    line: number;
+    column: number;
+}
+/** @deprecated Use RegisterContractsDirectCall. */
+export type RegisterCareDirectCall = RegisterContractsDirectCall;
+export interface RegisterContractsProgramModel {
+    routines: RegisterContractsRoutine[];
+    directCalls: RegisterContractsDirectCall[];
+    directBoundaries: RegisterContractsDirectCall[];
+}
+/** @deprecated Use RegisterContractsProgramModel. */
+export type RegisterCareProgramModel = RegisterContractsProgramModel;
+export type StackEffect = {
+    kind: 'none';
+} | {
+    kind: 'push';
+    units: RegisterContractsUnit[];
+} | {
+    kind: 'pop';
+    units: RegisterContractsUnit[];
+} | {
+    kind: 'exchangeTop';
+    units: RegisterContractsUnit[];
+} | {
+    kind: 'unknown';
+};
+export type ControlEffect = {
+    kind: 'fallthrough';
+} | {
+    kind: 'call';
+    target?: string;
+    conditional: boolean;
+} | {
+    kind: 'rst';
+    vector?: number;
+} | {
+    kind: 'return';
+    conditional: boolean;
+} | {
+    kind: 'jump';
+    target?: string;
+    conditional: boolean;
+} | {
+    kind: 'unknown';
+};
+export interface InstructionEffect {
+    reads: RegisterContractsUnit[];
+    writes: RegisterContractsUnit[];
+    stack: StackEffect;
+    control: ControlEffect;
+}
+export interface ValueRelation {
+    out: RegisterContractsUnit[];
+    from: RegisterContractsUnit[];
+}
+export interface RoutineSummary {
+    name: string;
+    mayRead: RegisterContractsUnit[];
+    mayWrite: RegisterContractsUnit[];
+    mayOutput?: RegisterContractsUnit[];
+    preserved: RegisterContractsUnit[];
+    valueRelations: ValueRelation[];
+    stackBalanced: boolean;
+    hasUnknownStackEffect?: boolean;
+    outputCandidates?: RegisterContractsUnit[];
+}
+export interface RegisterContractsOutputCandidate {
+    file: string;
+    line: number;
+    column: number;
+    routine: string;
+    carriers: RegisterContractsUnit[];
+    autoFixable?: boolean;
+    message: string;
+}
+/** @deprecated Use RegisterContractsOutputCandidate. */
+export type RegisterCareOutputCandidate = RegisterContractsOutputCandidate;
+export interface RegisterContractsConflict {
+    file: string;
+    line: number;
+    column: number;
+    callTarget: string;
+    carriers: RegisterContractsUnit[];
+    message: string;
+}
+/** @deprecated Use RegisterContractsConflict. */
+export type RegisterCareConflict = RegisterContractsConflict;
+export interface RegisterContractsReportModel {
+    entryFile: string;
+    mode: RegisterContractsMode;
+    profile?: string;
+    summaries: RoutineSummary[];
+    conflicts: RegisterContractsConflict[];
+    outputCandidates?: RegisterContractsOutputCandidate[];
+    unknownCalls: string[];
+}
+export interface AnalyzeRegisterContractsOptions {
+    mode: RegisterContractsMode;
+    emitReport: boolean;
+    emitInterface: boolean;
+    emitAnnotations?: boolean;
+    fixRegisterContracts?: boolean;
+    registerContractsProfile?: 'mon3';
+    interfaceContracts?: RoutineContract[];
+    acceptedOutputCandidates?: ReadonlyMap<string, RegisterContractsUnit[]>;
+}
+export interface RegisterContractsAnnotationFile {
+    readonly path: string;
+    readonly text: string;
+}

package/dist/src/semantics/binary-operators.d.ts

@@ -0,0 +1,2 @@
+import type { BinaryOperator } from './constant-operator-types.js';
+export declare function applyBinaryOperator(operator: BinaryOperator, left: number, right: number): number | undefined;

package/dist/src/semantics/binary-operators.js

@@ -0,0 +1,15 @@
+const binaryOperators = {
+    '+': (left, right) => left + right,
+    '-': (left, right) => left - right,
+    '*': (left, right) => left * right,
+    '/': (left, right) => (right === 0 ? undefined : Math.trunc(left / right)),
+    '%': (left, right) => (right === 0 ? undefined : left % right),
+    '&': (left, right) => left & right,
+    '^': (left, right) => left ^ right,
+    '|': (left, right) => left | right,
+    '<<': (left, right) => left << right,
+    '>>': (left, right) => left >> right,
+};
+export function applyBinaryOperator(operator, left, right) {
+    return binaryOperators[operator](left, right);
+}

package/dist/src/semantics/byte-functions.d.ts

@@ -0,0 +1,2 @@
+import type { ByteFunction } from './constant-operator-types.js';
+export declare function applyByteFunction(functionName: ByteFunction, value: number): number;

package/dist/src/semantics/byte-functions.js

@@ -0,0 +1,7 @@
+const byteFunctions = {
+    LSB: (value) => value & 0xff,
+    MSB: (value) => (value >> 8) & 0xff,
+};
+export function applyByteFunction(functionName, value) {
+    return byteFunctions[functionName](value);
+}

package/dist/src/semantics/constant-operator-types.d.ts

@@ -0,0 +1,10 @@
+import type { Expression } from '../model/expression.js';
+export type UnaryOperator = Extract<Expression, {
+    readonly kind: 'unary';
+}>['operator'];
+export type BinaryOperator = Extract<Expression, {
+    readonly kind: 'binary';
+}>['operator'];
+export type ByteFunction = Extract<Expression, {
+    readonly kind: 'byte-function';
+}>['function'];

package/dist/src/semantics/constant-operator-types.js

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

package/dist/src/semantics/constant-operators.d.ts

@@ -0,0 +1,3 @@
+export { applyBinaryOperator } from './binary-operators.js';
+export { applyByteFunction } from './byte-functions.js';
+export { applyUnaryOperator } from './unary-operators.js';