@jhlagado/azm 0.1.0

package/dist/src/registerCare/summary.js

@@ -0,0 +1,492 @@
+import { getZ80InstructionEffect } from '../z80/effects.js';
+import { precedingCServiceName } from './boundaryHints.js';
+import { expandCarrier } from './carriers.js';
+import { rstServiceTargetName, rstTargetName } from './profiles.js';
+const FLAG_UNIT_LIST = ['carry', 'zero', 'sign', 'parity', 'halfCarry'];
+const TRACKED_UNITS = [
+    'A',
+    'B',
+    'C',
+    'D',
+    'E',
+    'H',
+    'L',
+    'IXH',
+    'IXL',
+    'IYH',
+    'IYL',
+    ...FLAG_UNIT_LIST,
+];
+const GENERAL_REGISTER_UNITS = new Set(['A', 'B', 'C', 'D', 'E', 'H', 'L']);
+const CONTRACT_FLAG_UNITS = new Set(['carry', 'zero']);
+const STACK_POINTER_UNITS = new Set(['SPH', 'SPL']);
+const REGISTER_PAIRS = [
+    ['B', 'C'],
+    ['D', 'E'],
+    ['H', 'L'],
+];
+function unique(items) {
+    return [...new Set(items)];
+}
+function isTrackedUnit(unit) {
+    return TRACKED_UNITS.includes(unit);
+}
+function getRegisterUnits(name) {
+    return expandCarrier(name);
+}
+function readToken(tokens, unit) {
+    return tokens.get(unit) ?? { origin: 'unknown' };
+}
+function semanticReadOrigins(tokens, units) {
+    const origins = [];
+    for (const unit of units) {
+        if (!isTrackedUnit(unit)) {
+            origins.push(unit);
+            continue;
+        }
+        const token = readToken(tokens, unit);
+        if (token.origin !== 'unknown' && token.origin !== 'produced')
+            origins.push(token.origin);
+    }
+    return origins;
+}
+function markProducedReadsConsumed(tokens, consumedProduced, reads, writes, item) {
+    for (const unit of reads) {
+        if (!isTrackedUnit(unit) || writes.has(unit))
+            continue;
+        if (item?.head.toLowerCase() === 'cp' && unit === 'A')
+            continue;
+        if (readToken(tokens, unit).origin === 'produced')
+            consumedProduced.add(unit);
+    }
+}
+function tokenPreservesUnit(token, unit) {
+    return token?.origin === unit;
+}
+function isOpaqueBoundary(item, effect) {
+    if (effect.control.kind === 'call' || effect.control.kind === 'rst')
+        return true;
+    return (effect.control.kind === 'jump' &&
+        item.head.toLowerCase() === 'jp' &&
+        !effect.control.conditional &&
+        Boolean(effect.control.target) &&
+        !effect.control.target?.startsWith('.'));
+}
+function boundarySummary(routine, index, summaries) {
+    const item = routine.instructions[index];
+    if (!item)
+        return undefined;
+    const effect = getZ80InstructionEffect(item.instruction);
+    if (effect.control.kind === 'call' && effect.control.target) {
+        return summaries.get(effect.control.target);
+    }
+    if (effect.control.kind === 'jump' &&
+        item.head.toLowerCase() === 'jp' &&
+        effect.control.target &&
+        !effect.control.target.startsWith('.') &&
+        !routine.labels.includes(effect.control.target)) {
+        return summaries.get(effect.control.target);
+    }
+    if (effect.control.kind === 'rst' && effect.control.vector !== undefined) {
+        const service = precedingCServiceName(routine.instructions[index - 1]);
+        if (service) {
+            const serviceSummary = summaries.get(rstServiceTargetName(effect.control.vector, service));
+            if (serviceSummary)
+                return serviceSummary;
+        }
+        return summaries.get(rstTargetName(effect.control.vector));
+    }
+    return undefined;
+}
+function relationKey(relation) {
+    return `${relation.out.join(',')}<- ${relation.from.join(',')}`;
+}
+function addRelation(out, relation) {
+    if (relation.out.length === 0 || relation.from.length === 0)
+        return;
+    const key = relationKey(relation);
+    if (!out.some((existing) => relationKey(existing) === key))
+        out.push(relation);
+}
+function addContractRelation(out, relation) {
+    if (relation.out.length === 0)
+        return;
+    const key = relationKey(relation);
+    if (!out.some((existing) => relationKey(existing) === key))
+        out.push(relation);
+}
+function pairRelation(tokens, out) {
+    const from = [];
+    for (const unit of out) {
+        const token = tokens.get(unit);
+        if (!token || token.origin === 'unknown' || token.origin === 'produced')
+            return undefined;
+        from.push(token.origin);
+    }
+    if (out.every((unit, idx) => unit === from[idx]))
+        return undefined;
+    if (out.some((unit, idx) => unit === from[idx]))
+        return undefined;
+    return { out, from };
+}
+function producedPairRelation(tokens, consumedProduced, out) {
+    if (out.some((unit) => tokens.get(unit)?.origin !== 'produced' || consumedProduced.has(unit))) {
+        return undefined;
+    }
+    return { out, from: [] };
+}
+function withImpliedFlagUnits(units) {
+    return unique(units);
+}
+function contractOutRelation(contractIn, contractOut) {
+    if (contractOut.length === 0)
+        return undefined;
+    return {
+        out: contractOut,
+        from: contractIn.length === contractOut.length ? contractIn : [],
+    };
+}
+function isUnconditionalReturn(item) {
+    const head = item.head.toLowerCase();
+    if (head === 'ret')
+        return item.instruction.operands.length === 0;
+    return head === 'retn' || head === 'reti';
+}
+function isPureTokenTransfer(item) {
+    const inst = item.instruction;
+    const head = item.head.toLowerCase();
+    if (head === 'ex')
+        return true;
+    if (head !== 'ld' || inst.operands.length !== 2)
+        return false;
+    const dst = inst.operands[0];
+    const src = inst.operands[1];
+    if (dst?.kind !== 'Reg')
+        return false;
+    return src?.kind === 'Reg' || src?.kind === 'Imm';
+}
+function isAccumulatorSelfOperand(item) {
+    const operand = item.instruction.operands[0];
+    return operand?.kind === 'Reg' && operand.name.toUpperCase() === 'A';
+}
+function isImmediateZeroOperand(item) {
+    const operand = item.instruction.operands[0];
+    return operand?.kind === 'Imm' && operand.expr.kind === 'ImmLiteral' && operand.expr.value === 0;
+}
+function isRegisterOperand(item, index, name) {
+    const operand = item?.instruction.operands[index];
+    return operand?.kind === 'Reg' && operand.name.toUpperCase() === name;
+}
+function isCarryClearBeforeSbcHl(item, next) {
+    const head = item.head.toLowerCase();
+    if (head !== 'or' && head !== 'and')
+        return false;
+    if (!isAccumulatorSelfOperand(item))
+        return false;
+    return next?.head.toLowerCase() === 'sbc' && isRegisterOperand(next, 0, 'HL');
+}
+function intentOutputUnits(item) {
+    const head = item.head.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 = item.head.toLowerCase();
+    if (head === 'djnz')
+        return unit === 'B';
+    if (head === 'ldi' || head === 'ldir' || head === 'ldd' || head === 'lddr') {
+        return (unit === 'B' || unit === 'C' || unit === 'D' || unit === 'E' || unit === 'H' || unit === 'L');
+    }
+    return false;
+}
+function applyPureTokenTransfer(tokens, consumedProduced, item) {
+    const inst = item.instruction;
+    const head = item.head.toLowerCase();
+    if (head === 'ld' && inst.operands.length === 2) {
+        const dst = inst.operands[0];
+        const src = inst.operands[1];
+        if (dst?.kind !== 'Reg')
+            return [];
+        const dstUnits = dst.kind === 'Reg' ? getRegisterUnits(dst.name) : undefined;
+        if (!dstUnits)
+            return [];
+        const srcUnits = src?.kind === 'Reg' ? getRegisterUnits(src.name) : undefined;
+        if (srcUnits && srcUnits.length === dstUnits.length) {
+            dstUnits.forEach((unit, index) => {
+                tokens.set(unit, readToken(tokens, srcUnits[index]));
+                if (readToken(tokens, srcUnits[index]).origin === 'produced') {
+                    consumedProduced.add(srcUnits[index]);
+                }
+                consumedProduced.delete(unit);
+            });
+        }
+        else {
+            for (const unit of dstUnits) {
+                tokens.set(unit, { origin: 'produced' });
+                consumedProduced.delete(unit);
+            }
+        }
+        return dstUnits;
+    }
+    if (head === 'ex' && inst.operands.length === 2) {
+        const left = inst.operands[0];
+        const right = inst.operands[1];
+        if (left?.kind !== 'Reg' || right?.kind !== 'Reg')
+            return [];
+        const leftUnits = getRegisterUnits(left.name);
+        const rightUnits = getRegisterUnits(right.name);
+        if (!leftUnits || !rightUnits || leftUnits.length !== rightUnits.length)
+            return [];
+        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' }));
+        return unique([...leftUnits, ...rightUnits]);
+    }
+    return [];
+}
+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);
+        }
+    }
+}
+export function inferRoutineSummary(routine, boundarySummaries = new Map()) {
+    const tokens = new Map();
+    for (const unit of TRACKED_UNITS)
+        tokens.set(unit, { origin: unit });
+    const stack = [];
+    const mayRead = [];
+    const directMayWrite = [];
+    const consumedProduced = new Set();
+    const intendedProduced = new Set();
+    let stackBalanced = true;
+    let hasUnknownStackEffect = false;
+    for (let index = 0; index < routine.instructions.length; index += 1) {
+        const item = routine.instructions[index];
+        const effect = getZ80InstructionEffect(item.instruction);
+        const knownBoundary = boundarySummary(routine, index, boundarySummaries);
+        const carryClearBeforeSbcHl = isCarryClearBeforeSbcHl(item, routine.instructions[index + 1]);
+        const expectedTerminalReturn = index === routine.instructions.length - 1 && isUnconditionalReturn(item);
+        const effectWrites = new Set(effect.writes);
+        const instructionIntentOutputs = carryClearBeforeSbcHl ? [] : intentOutputUnits(item);
+        const semanticReads = carryClearBeforeSbcHl
+            ? effect.reads.filter((unit) => unit !== 'A')
+            : effect.reads;
+        if (effect.stack.kind !== 'push' && !isPureTokenTransfer(item)) {
+            mayRead.push(...semanticReadOrigins(tokens, semanticReads));
+            markProducedReadsConsumed(tokens, consumedProduced, semanticReads, effectWrites, item);
+        }
+        if (item.head.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());
+        }
+        if (effect.stack.kind === 'push') {
+            stack.push(effect.stack.units.map((unit) => readToken(tokens, unit)));
+        }
+        else if (effect.stack.kind === 'pop') {
+            const popped = stack.pop();
+            if (!popped) {
+                stackBalanced = false;
+                for (const unit of effect.stack.units) {
+                    tokens.set(unit, { origin: 'unknown' });
+                    intendedProduced.delete(unit);
+                }
+            }
+            else if (popped.length !== effect.stack.units.length) {
+                for (const unit of effect.stack.units) {
+                    tokens.set(unit, { origin: 'unknown' });
+                    consumedProduced.delete(unit);
+                    intendedProduced.delete(unit);
+                }
+            }
+            else {
+                effect.stack.units.forEach((unit, idx) => {
+                    tokens.set(unit, popped[idx] ?? { origin: 'unknown' });
+                    consumedProduced.delete(unit);
+                    intendedProduced.delete(unit);
+                });
+            }
+        }
+        else if (effect.stack.kind === 'exchangeTop') {
+            hasUnknownStackEffect = true;
+            for (const unit of effect.stack.units) {
+                tokens.set(unit, { origin: 'unknown' });
+                consumedProduced.delete(unit);
+                intendedProduced.delete(unit);
+            }
+        }
+        else if (effect.stack.kind === 'unknown' &&
+            !expectedTerminalReturn &&
+            (!knownBoundary || !knownBoundary.stackBalanced || knownBoundary.hasUnknownStackEffect)) {
+            hasUnknownStackEffect = true;
+        }
+        const transferWrites = new Set(isPureTokenTransfer(item) ? applyPureTokenTransfer(tokens, consumedProduced, item) : []);
+        if (knownBoundary) {
+            applyKnownBoundarySummary(tokens, consumedProduced, intendedProduced, directMayWrite, knownBoundary);
+        }
+        else if (isOpaqueBoundary(item, effect)) {
+            for (const unit of TRACKED_UNITS) {
+                tokens.set(unit, { origin: 'unknown' });
+                consumedProduced.delete(unit);
+                intendedProduced.delete(unit);
+            }
+        }
+        for (const unit of effect.writes) {
+            if (STACK_POINTER_UNITS.has(unit))
+                continue;
+            if (effect.stack.kind === 'pop' && effect.stack.units.includes(unit) && isTrackedUnit(unit)) {
+                continue;
+            }
+            if (transferWrites.has(unit) && isTrackedUnit(unit))
+                continue;
+            if (unit === 'A' &&
+                (item.head.toLowerCase() === 'or' || item.head.toLowerCase() === 'and') &&
+                isAccumulatorSelfOperand(item)) {
+                if (!carryClearBeforeSbcHl)
+                    intendedProduced.add(unit);
+                continue;
+            }
+            if (isTrackedUnit(unit)) {
+                tokens.set(unit, { origin: isMechanicalResidueWrite(item, unit) ? 'unknown' : 'produced' });
+                consumedProduced.delete(unit);
+                if (instructionIntentOutputs.includes(unit))
+                    intendedProduced.add(unit);
+                else
+                    intendedProduced.delete(unit);
+            }
+            else {
+                directMayWrite.push(unit);
+            }
+        }
+        for (const unit of instructionIntentOutputs) {
+            if (!isTrackedUnit(unit) || effectWrites.has(unit))
+                continue;
+            intendedProduced.add(unit);
+        }
+    }
+    if (stack.length !== 0)
+        stackBalanced = false;
+    const mayWrite = [...directMayWrite];
+    const preserved = [];
+    const valueRelations = [];
+    const outputUnits = new Set();
+    for (const pair of REGISTER_PAIRS) {
+        const relation = producedPairRelation(tokens, consumedProduced, pair);
+        if (relation) {
+            addContractRelation(valueRelations, relation);
+            for (const unit of pair)
+                outputUnits.add(unit);
+        }
+    }
+    for (const unit of TRACKED_UNITS) {
+        if (outputUnits.has(unit))
+            continue;
+        const current = tokens.get(unit);
+        const eligibleProduced = current?.origin === 'produced' &&
+            (GENERAL_REGISTER_UNITS.has(unit) ||
+                (CONTRACT_FLAG_UNITS.has(unit) && intendedProduced.has(unit)));
+        const eligiblePreservedIntent = current?.origin === unit && GENERAL_REGISTER_UNITS.has(unit) && intendedProduced.has(unit);
+        if ((eligibleProduced || eligiblePreservedIntent) && !consumedProduced.has(unit)) {
+            addContractRelation(valueRelations, {
+                out: [unit],
+                from: eligiblePreservedIntent ? [unit] : [],
+            });
+            outputUnits.add(unit);
+        }
+    }
+    for (const unit of TRACKED_UNITS) {
+        const current = tokens.get(unit);
+        if (tokenPreservesUnit(current, unit)) {
+            preserved.push(unit);
+            continue;
+        }
+        if (outputUnits.has(unit))
+            continue;
+        mayWrite.push(unit);
+    }
+    for (const pair of REGISTER_PAIRS) {
+        const relation = pairRelation(tokens, pair);
+        if (relation)
+            addRelation(valueRelations, relation);
+    }
+    mayRead.push(...valueRelations.flatMap((relation) => relation.from));
+    return {
+        name: routine.name,
+        mayRead: unique(mayRead),
+        mayWrite: unique(mayWrite),
+        preserved: unique(preserved),
+        valueRelations,
+        stackBalanced,
+        hasUnknownStackEffect,
+    };
+}
+export function applyRoutineContract(summary, contract) {
+    const contractIn = withImpliedFlagUnits(contract.in);
+    const contractOut = withImpliedFlagUnits(contract.out);
+    const contractClobbers = withImpliedFlagUnits(contract.clobbers);
+    const contractPreserves = withImpliedFlagUnits(contract.preserves);
+    const outputSet = new Set(contractOut);
+    const preservedSet = new Set(contractPreserves);
+    const inferredWrites = withImpliedFlagUnits(summary.mayWrite);
+    const baseMayWrite = contract.complete
+        ? inferredWrites.filter((unit) => FLAG_UNIT_LIST.includes(unit))
+        : inferredWrites;
+    const mayWrite = baseMayWrite.filter((unit) => !outputSet.has(unit) && !preservedSet.has(unit));
+    for (const unit of contractClobbers) {
+        if (!outputSet.has(unit) && !preservedSet.has(unit) && !mayWrite.includes(unit)) {
+            mayWrite.push(unit);
+        }
+    }
+    const mayWriteSet = new Set(withImpliedFlagUnits(mayWrite));
+    const preserved = unique([...summary.preserved, ...contractPreserves]).filter((unit) => !outputSet.has(unit) && !mayWriteSet.has(unit));
+    const valueRelations = [...summary.valueRelations];
+    const relation = contractOutRelation(contractIn, contractOut);
+    if (relation)
+        addContractRelation(valueRelations, relation);
+    return {
+        ...summary,
+        mayRead: unique(contractIn),
+        mayWrite,
+        preserved,
+        valueRelations,
+    };
+}

package/dist/src/registerCare/tooling.d.ts

@@ -0,0 +1,42 @@
+import type { Diagnostic } from '../diagnosticTypes.js';
+import type { LoadedProgram } from '../sourceLoader.js';
+import { type AnalyzeRegisterCareOptions } from './analyze.js';
+import type { RegisterCareOutputCandidate, RegisterCareUnit } from './types.js';
+export interface RegisterCareTextEdit {
+    file: string;
+    line: number;
+    column: number;
+    text: string;
+}
+export interface RegisterCareCodeAction {
+    title: string;
+    kind: 'quickfix';
+    edit: RegisterCareTextEdit;
+}
+export interface RegisterCareCandidateDiagnostic {
+    kind: 'register-care-output-candidate';
+    severity: 'info';
+    file: string;
+    line: number;
+    column: number;
+    routine: string;
+    carriers: RegisterCareUnit[];
+    autoFixable: boolean;
+    message: string;
+    codeAction: RegisterCareCodeAction;
+}
+export interface AnalyzeRegisterCareForToolsOptions extends Omit<AnalyzeRegisterCareOptions, 'emitReport' | 'emitInterface' | 'emitAnnotations'> {
+    emitReport?: boolean;
+    emitInterface?: boolean;
+}
+export interface AnalyzeRegisterCareForToolsResult {
+    diagnostics: Diagnostic[];
+    outputCandidates: RegisterCareOutputCandidate[];
+    candidateDiagnostics: RegisterCareCandidateDiagnostic[];
+    codeActions: RegisterCareCodeAction[];
+    reportText?: string;
+    interfaceText?: string;
+}
+export declare function codeActionForOutputCandidate(candidate: RegisterCareOutputCandidate): RegisterCareCodeAction;
+export declare function diagnosticForOutputCandidate(candidate: RegisterCareOutputCandidate): RegisterCareCandidateDiagnostic;
+export declare function analyzeRegisterCareForTools(loaded: LoadedProgram, options: AnalyzeRegisterCareForToolsOptions): AnalyzeRegisterCareForToolsResult;

package/dist/src/registerCare/tooling.js

@@ -0,0 +1,50 @@
+import { analyzeRegisterCare } from './analyze.js';
+import { contractCarrierList } from './report.js';
+function expectOutText(carriers) {
+    return `; expects out ${contractCarrierList(carriers)}\n`;
+}
+export function codeActionForOutputCandidate(candidate) {
+    return {
+        title: `Confirm ${candidate.routine} output ${contractCarrierList(candidate.carriers)}`,
+        kind: 'quickfix',
+        edit: {
+            file: candidate.file,
+            line: candidate.line,
+            column: 1,
+            text: expectOutText(candidate.carriers),
+        },
+    };
+}
+export function diagnosticForOutputCandidate(candidate) {
+    const codeAction = codeActionForOutputCandidate(candidate);
+    return {
+        kind: 'register-care-output-candidate',
+        severity: 'info',
+        file: candidate.file,
+        line: candidate.line,
+        column: candidate.column,
+        routine: candidate.routine,
+        carriers: candidate.carriers,
+        autoFixable: candidate.autoFixable === true,
+        message: candidate.message,
+        codeAction,
+    };
+}
+export function analyzeRegisterCareForTools(loaded, options) {
+    const result = analyzeRegisterCare(loaded, {
+        ...options,
+        emitReport: options.emitReport === true,
+        emitInterface: options.emitInterface === true,
+        emitAnnotations: false,
+    });
+    const outputCandidates = result.outputCandidates ?? [];
+    const candidateDiagnostics = outputCandidates.map(diagnosticForOutputCandidate);
+    return {
+        diagnostics: result.diagnostics,
+        outputCandidates,
+        candidateDiagnostics,
+        codeActions: candidateDiagnostics.map((diagnostic) => diagnostic.codeAction),
+        ...(result.reportText !== undefined ? { reportText: result.reportText } : {}),
+        ...(result.interfaceText !== undefined ? { interfaceText: result.interfaceText } : {}),
+    };
+}