@jhlagado/azm 0.1.1 → 0.2.1

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

@@ -0,0 +1,474 @@
+import { getZ80InstructionEffect } from '../z80/effects.js';
+import { instructionHead, instructionOperand, instructionOperandCount, isAccumulatorSelfOperand, isImmediateZeroOperand, isPureTokenTransferInstruction, isRegisterOperand, isUnconditionalReturnInstruction, regName, } from './instruction-shape.js';
+import { precedingCServiceName } from './boundaryHints.js';
+import { expandCarrierList } 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 expandCarrierList([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 !== undefined && instructionHead(item) === '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' &&
+        (instructionHead(item) === 'jp' || instructionHead(item) === 'jp-cc') &&
+        !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' &&
+        (instructionHead(item) === 'jp' || instructionHead(item) === 'jp-cc') &&
+        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) {
+    return isUnconditionalReturnInstruction(item);
+}
+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 (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 = instructionHead(item).toLowerCase();
+    if (head === 'ld' && instructionOperandCount(inst) === 2) {
+        const dst = instructionOperand(inst, 0);
+        const src = instructionOperand(inst, 1);
+        const dstName = regName(dst);
+        if (dstName === undefined)
+            return [];
+        const dstUnits = getRegisterUnits(dstName);
+        if (!dstUnits)
+            return [];
+        const srcName = regName(src);
+        const srcUnits = srcName ? getRegisterUnits(srcName) : 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' && instructionOperandCount(inst) === 2) {
+        const left = instructionOperand(inst, 0);
+        const right = instructionOperand(inst, 1);
+        const leftName = regName(left);
+        const rightName = regName(right);
+        if (leftName === undefined || rightName === undefined)
+            return [];
+        const leftUnits = getRegisterUnits(leftName);
+        const rightUnits = getRegisterUnits(rightName);
+        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 (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());
+        }
+        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' &&
+                (instructionHead(item).toLowerCase() === 'or' || instructionHead(item).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 → register-care}/tooling.d.ts

@@ -1,7 +1,6 @@
-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';
+import type { Diagnostic } from '../model/diagnostic.js';
+import type { LoadedProgram } from '../tooling/api.js';
+import type { AnalyzeRegisterCareOptions, RegisterCareOutputCandidate, RegisterCareUnit } from './types.js';
 export interface RegisterCareTextEdit {
     file: string;
     line: number;
@@ -23,11 +22,13 @@ export interface RegisterCareCandidateDiagnostic {
     carriers: RegisterCareUnit[];
     autoFixable: boolean;
     message: string;
-    codeAction: RegisterCareCodeAction;
+    codeAction?: RegisterCareCodeAction;
 }
-export interface AnalyzeRegisterCareForToolsOptions extends Omit<AnalyzeRegisterCareOptions, 'emitReport' | 'emitInterface' | 'emitAnnotations'> {
+export interface AnalyzeRegisterCareForToolsOptions extends Omit<AnalyzeRegisterCareOptions, 'emitReport' | 'emitInterface' | 'emitAnnotations' | 'fixRegisterContracts'> {
     emitReport?: boolean;
     emitInterface?: boolean;
+    /** Back-compat alias for registerCareProfile used by some tooling integrations. */
+    profile?: AnalyzeRegisterCareOptions['registerCareProfile'];
 }
 export interface AnalyzeRegisterCareForToolsResult {
     diagnostics: Diagnostic[];

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

@@ -16,8 +16,8 @@ export function codeActionForOutputCandidate(candidate) {
     };
 }
 export function diagnosticForOutputCandidate(candidate) {
-    const codeAction = codeActionForOutputCandidate(candidate);
-    return {
+    const codeAction = candidate.autoFixable === true ? codeActionForOutputCandidate(candidate) : undefined;
+    const diagnostic = {
         kind: 'register-care-output-candidate',
         severity: 'info',
         file: candidate.file,
@@ -27,23 +27,34 @@ export function diagnosticForOutputCandidate(candidate) {
         carriers: candidate.carriers,
         autoFixable: candidate.autoFixable === true,
         message: candidate.message,
-        codeAction,
     };
+    if (codeAction !== undefined) {
+        diagnostic.codeAction = codeAction;
+    }
+    return diagnostic;
 }
 export function analyzeRegisterCareForTools(loaded, options) {
-    const result = analyzeRegisterCare(loaded, {
+    const profile = options.registerCareProfile ?? options.profile;
+    const baseResultOptions = {
         ...options,
         emitReport: options.emitReport === true,
         emitInterface: options.emitInterface === true,
         emitAnnotations: false,
-    });
+        fixRegisterContracts: false,
+    };
+    const result = analyzeRegisterCare(loaded, profile === undefined
+        ? baseResultOptions
+        : { ...baseResultOptions, registerCareProfile: profile });
     const outputCandidates = result.outputCandidates ?? [];
     const candidateDiagnostics = outputCandidates.map(diagnosticForOutputCandidate);
+    const codeActions = outputCandidates
+        .filter((candidate) => candidate.autoFixable === true)
+        .map(codeActionForOutputCandidate);
     return {
         diagnostics: result.diagnostics,
         outputCandidates,
         candidateDiagnostics,
-        codeActions: candidateDiagnostics.map((diagnostic) => diagnostic.codeAction),
+        codeActions,
         ...(result.reportText !== undefined ? { reportText: result.reportText } : {}),
         ...(result.interfaceText !== undefined ? { interfaceText: result.interfaceText } : {}),
     };