@jhlagado/azm 0.2.0 → 0.2.2

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

@@ -14,6 +14,7 @@ export function writeAsm80(items, symbols, opts = {}) {
     void opts;
     const evalContext = {
         constants: collectConstants(symbols),
+        symbols: collectSymbolValues(symbols),
         layouts: collectLayouts(items),
     };
     const lines = [asm80Header, ''];
@@ -43,6 +44,13 @@ function collectConstants(symbols) {
     }
     return constants;
 }
+function collectSymbolValues(symbols) {
+    const values = new Map();
+    for (const symbol of symbols) {
+        values.set(symbol.name, symbol.kind === 'constant' ? symbol.value : symbol.address);
+    }
+    return values;
+}
 function collectLayouts(items) {
     const layouts = new Map();
     for (const item of items) {
@@ -53,6 +61,13 @@ function collectLayouts(items) {
                 span: item.span,
             });
         }
+        else if (item.kind === 'type-alias') {
+            layouts.set(item.name, {
+                kind: 'alias',
+                typeExpr: item.typeExpr,
+                span: item.span,
+            });
+        }
     }
     return layouts;
 }
@@ -74,6 +89,11 @@ function formatItem(item, evalContext, state) {
                 ? undefined
                 : withImplicitOrg(state, `${item.name} EQU ${expression}`, 0);
         }
+        case 'comment':
+            return {
+                text: item.origin === 'user' ? `; ${item.text}` : `; AZM: ${item.text}`,
+                size: 0,
+            };
         case 'label':
             return withImplicitOrg(state, `${item.name}:`, 0);
         case 'db':
@@ -90,6 +110,7 @@ function formatItem(item, evalContext, state) {
             return withImplicitOrg(state, formatInstruction(item.instruction, evalContext)?.text, instructionSize(item.instruction));
         case 'enum':
         case 'type':
+        case 'type-alias':
         case 'end':
         case 'binfrom':
         case 'binto':
@@ -239,6 +260,16 @@ function formatInstruction(instruction, evalContext) {
         case 'res':
         case 'set':
             return formatBitOp(instruction, evalContext);
+        case 'rlc':
+        case 'rrc':
+        case 'rl':
+        case 'rr':
+        case 'sla':
+        case 'sra':
+        case 'sll':
+        case 'sls':
+        case 'srl':
+            return formatRotateShift(instruction, evalContext);
         case 'in':
             return formatIn(instruction, evalContext);
         case 'out':
@@ -264,6 +295,11 @@ function formatInstruction(instruction, evalContext) {
             return formatBranch(`call ${instruction.condition},`, instruction.expression, evalContext);
         case 'djnz':
             return formatBranch('djnz', instruction.expression, evalContext);
+        case 'push':
+        case 'pop':
+            return { text: `${instruction.mnemonic} ${instruction.register}` };
+        case 'ret-cc':
+            return { text: `ret ${instruction.condition}` };
         default:
             return undefined;
     }
@@ -282,7 +318,7 @@ function formatAlu(mnemonic, source, evalContext) {
     return { text: `${mnemonic} ${operand}` };
 }
 function formatAluOperand(source, evalContext) {
-    if (source.kind === 'reg8') {
+    if (source.kind === 'reg8' || source.kind === 'reg-half-index') {
         return source.register;
     }
     if (source.kind === 'reg-indirect' && source.register === 'hl') {
@@ -330,6 +366,18 @@ function formatLd(target, source, evalContext) {
     if (target.kind === 'reg8' && source.kind === 'reg8') {
         return { text: `ld ${target.register}, ${source.register}` };
     }
+    if (target.kind === 'reg8' && source.kind === 'reg-half-index') {
+        return { text: `ld ${target.register}, ${source.register}` };
+    }
+    if (target.kind === 'reg8' && target.register === 'a' && source.kind === 'special8') {
+        return { text: `ld a, ${source.register}` };
+    }
+    if (target.kind === 'special8' && source.kind === 'reg8' && source.register === 'a') {
+        return { text: `ld ${target.register}, a` };
+    }
+    if (target.kind === 'reg-index16' && source.kind === 'imm') {
+        return formatLdText(target.register, formatExpression(source.expression, evalContext, 'word'));
+    }
     if (target.kind === 'reg16' && source.kind === 'imm') {
         return formatLdText(target.register, formatExpression(source.expression, evalContext, 'word'));
     }
@@ -345,12 +393,44 @@ function formatLd(target, source, evalContext) {
         source.register === 'a') {
         return { text: `ld (${target.register}), a` };
     }
-    if (target.kind === 'reg8' && target.register === 'a' && source.kind === 'mem-abs') {
-        return formatLdText('a', formatParenthesizedExpression(source.expression, evalContext, 'auto'));
+    if (target.kind === 'reg8' && source.kind === 'reg-indirect' && source.register === 'hl') {
+        return { text: `ld ${target.register}, (hl)` };
+    }
+    if (target.kind === 'reg-indirect' && target.register === 'hl' && source.kind === 'reg8') {
+        return { text: `ld (hl), ${source.register}` };
+    }
+    if (target.kind === 'reg-indirect' && target.register === 'hl' && source.kind === 'imm') {
+        const value = formatExpression(source.expression, evalContext, 'byte');
+        return value === undefined ? undefined : { text: `ld (hl), ${value}` };
+    }
+    if (target.kind === 'reg8' && source.kind === 'indexed') {
+        const memory = formatIndexedMemory(source.register, source.displacement, evalContext);
+        return memory === undefined ? undefined : { text: `ld ${target.register}, ${memory}` };
+    }
+    if (target.kind === 'indexed' && source.kind === 'reg8') {
+        const memory = formatIndexedMemory(target.register, target.displacement, evalContext);
+        return memory === undefined ? undefined : { text: `ld ${memory}, ${source.register}` };
+    }
+    if (target.kind === 'reg8' && source.kind === 'mem-abs') {
+        return formatLdText(target.register, formatParenthesizedExpression(source.expression, evalContext, 'auto'));
     }
-    if (target.kind === 'mem-abs' && source.kind === 'reg8' && source.register === 'a') {
+    if (target.kind === 'mem-abs' && source.kind === 'reg8') {
         const targetText = formatParenthesizedExpression(target.expression, evalContext, 'auto');
-        return targetText === undefined ? undefined : { text: `ld ${targetText}, a` };
+        return targetText === undefined
+            ? undefined
+            : { text: `ld ${targetText}, ${source.register}` };
+    }
+    if (target.kind === 'mem-abs' && source.kind === 'reg16') {
+        const targetText = formatParenthesizedExpression(target.expression, evalContext, 'auto');
+        return targetText === undefined
+            ? undefined
+            : { text: `ld ${targetText}, ${source.register}` };
+    }
+    if (target.kind === 'mem-abs' && source.kind === 'reg-index16') {
+        const targetText = formatParenthesizedExpression(target.expression, evalContext, 'auto');
+        return targetText === undefined
+            ? undefined
+            : { text: `ld ${targetText}, ${source.register}` };
     }
     return undefined;
 }
@@ -383,6 +463,37 @@ function formatExpression(expression, evalContext, width) {
     if (expression.kind === 'symbol') {
         return expression.name;
     }
+    if (expression.kind === 'type-size') {
+        const value = evaluateLoweredConstant(expression, evalContext);
+        return value === undefined ? expression.typeExpr.name : formatLoweredNumber(value, width);
+    }
+    if (expression.kind === 'current-location') {
+        return '$';
+    }
+    if (expression.kind === 'unary') {
+        const inner = formatExpression(expression.expression, evalContext, width);
+        if (inner === undefined) {
+            return undefined;
+        }
+        switch (expression.operator) {
+            case '+':
+                return inner;
+            case '-':
+                return `-${inner}`;
+            case '~': {
+                const value = evaluateLoweredConstant(expression, evalContext);
+                return value === undefined ? undefined : formatLoweredNumber(value, width);
+            }
+        }
+    }
+    if (expression.kind === 'binary') {
+        const left = formatExpression(expression.left, evalContext, width);
+        const right = formatExpression(expression.right, evalContext, width);
+        if (left === undefined || right === undefined) {
+            return undefined;
+        }
+        return `${left}${expression.operator}${right}`;
+    }
     return undefined;
 }
 function evaluateLoweredConstant(expression, evalContext) {
@@ -391,12 +502,31 @@ function evaluateLoweredConstant(expression, evalContext) {
             return expression.value;
         case 'symbol':
             return evalContext.constants.get(expression.name);
+        case 'type-size': {
+            const constant = evalContext.constants.get(expression.typeExpr.name);
+            if (constant !== undefined) {
+                return constant;
+            }
+            return evaluateExpression(expression, {}, new Map(), silentSpan, [], {
+                currentLocation: 0,
+                layouts: evalContext.layouts,
+                reportUnknown: false,
+            });
+        }
+        case 'offset':
         case 'sizeof':
             return evaluateExpression(expression, {}, new Map(), silentSpan, [], {
                 currentLocation: 0,
                 layouts: evalContext.layouts,
                 reportUnknown: false,
             });
+        case 'byte-function': {
+            const value = evaluateLoweredResolvedConstant(expression.expression, evalContext);
+            if (value === undefined) {
+                return undefined;
+            }
+            return expression.function === 'LSB' ? value & 0xff : (value >> 8) & 0xff;
+        }
         case 'unary': {
             const value = evaluateLoweredConstant(expression.expression, evalContext);
             if (value === undefined) {
@@ -446,12 +576,83 @@ function evaluateLoweredConstant(expression, evalContext) {
             return undefined;
     }
 }
+function evaluateLoweredResolvedConstant(expression, evalContext) {
+    switch (expression.kind) {
+        case 'symbol':
+            return evalContext.symbols.get(expression.name);
+        case 'unary': {
+            const value = evaluateLoweredResolvedConstant(expression.expression, evalContext);
+            if (value === undefined) {
+                return undefined;
+            }
+            switch (expression.operator) {
+                case '+':
+                    return value;
+                case '-':
+                    return -value;
+                case '~':
+                    return ~value;
+            }
+            break;
+        }
+        case 'binary': {
+            const left = evaluateLoweredResolvedConstant(expression.left, evalContext);
+            const right = evaluateLoweredResolvedConstant(expression.right, evalContext);
+            if (left === undefined || right === undefined) {
+                return undefined;
+            }
+            switch (expression.operator) {
+                case '+':
+                    return left + right;
+                case '-':
+                    return left - right;
+                case '*':
+                    return left * right;
+                case '/':
+                    return right === 0 ? undefined : Math.trunc(left / right);
+                case '%':
+                    return right === 0 ? undefined : left % right;
+                case '&':
+                    return left & right;
+                case '^':
+                    return left ^ right;
+                case '|':
+                    return left | right;
+                case '<<':
+                    return left << right;
+                case '>>':
+                    return left >> right;
+            }
+            break;
+        }
+        case 'byte-function': {
+            const value = evaluateLoweredResolvedConstant(expression.expression, evalContext);
+            if (value === undefined) {
+                return undefined;
+            }
+            return expression.function === 'LSB' ? value & 0xff : (value >> 8) & 0xff;
+        }
+        default:
+            return evaluateLoweredConstant(expression, evalContext);
+    }
+}
 function formatLoweredNumber(value, width) {
     const normalized = value < 0 ? 0x10000 + (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 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(', ')}` };
+}
 function formatBitOp(instruction, evalContext) {
     const bit = formatLoweredNumber(instruction.bit, 'byte');
     const operand = formatBitOperand(instruction.operand, evalContext);

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

@@ -5,6 +5,14 @@ import { autoFixableCandidateKeys } from './fix.js';
 import { findCallerOutputCandidateObservations, findRegisterCareConflicts, } from './liveness.js';
 import { buildAnnotations } from './annotations.js';
 import { buildOutputCandidateFixability, buildProfileSummaries, buildProfileSummaryLookup, buildSummaries, buildSummaryByName, outputCandidateKey, routineNames, unknownBoundaryDiagnostics, unknownCallList, withAcceptedOutputs, } from './summaries.js';
+function candidateMessageWithFixability(candidate, autoFixable) {
+    const carriers = candidate.carriers.join(',');
+    const expectation = candidate.carriers.length === 1 ? candidate.carriers[0] : `{${carriers}}`;
+    const base = `CALL ${candidate.routine} writes ${carriers} and caller reads it later`;
+    return autoFixable
+        ? `${base}; generated contracts promote this to \`out ${expectation}\` automatically.`
+        : `${base}; manual review required before adding \`; expects out ${expectation}\` because the later read is not a simple direct continuation.`;
+}
 export function analyzeRegisterCare(loaded, options) {
     const file = loaded.program.files[0];
     const items = file?.items ?? [];
@@ -16,8 +24,8 @@ export function analyzeRegisterCare(loaded, options) {
             contractMap.set(contract.name, contract);
         }
     }
-    let summaries = buildSummaries(program.routines, contractMap);
     const profileSummaries = buildProfileSummaries(options.registerCareProfile);
+    let summaries = buildSummaries(program.routines, contractMap, profileSummaries);
     summaries = withAcceptedOutputs(summaries, options.acceptedOutputCandidates);
     const allSummaries = [...summaries, ...profileSummaries];
     const summariesByName = buildSummaryByName(program.routines, summaries, profileSummaries);
@@ -41,10 +49,14 @@ export function analyzeRegisterCare(loaded, options) {
     const conflicts = analyzed.conflicts;
     const outputCandidates = analyzed.outputCandidates;
     const outputCandidateFixability = buildOutputCandidateFixability(program.routines, outputCandidates, autoFixableCandidateKeys);
-    const outputCandidatesWithFixability = outputCandidates.map((candidate) => ({
-        ...candidate,
-        autoFixable: outputCandidateFixability.get(outputCandidateKey(candidate.file, candidate.line, candidate.column)) ?? false,
-    }));
+    const outputCandidatesWithFixability = outputCandidates.map((candidate) => {
+        const autoFixable = outputCandidateFixability.get(outputCandidateKey(candidate.file, candidate.line, candidate.column)) ?? false;
+        return {
+            ...candidate,
+            autoFixable,
+            message: candidateMessageWithFixability(candidate, autoFixable),
+        };
+    });
     if (options.mode !== 'audit') {
         for (const conflict of conflicts) {
             diagnostics.push({
@@ -58,7 +70,7 @@ export function analyzeRegisterCare(loaded, options) {
         }
     }
     if (options.mode === 'strict') {
-        diagnostics.push(...unknownBoundaryDiagnostics(program.directCalls, knownRoutines));
+        diagnostics.push(...unknownBoundaryDiagnostics(program.directBoundaries, knownRoutines));
     }
     const reportModel = {
         entryFile: loaded.program.entryFile,
@@ -67,10 +79,26 @@ export function analyzeRegisterCare(loaded, options) {
         conflicts,
         outputCandidates: outputCandidatesWithFixability,
         ...(options.registerCareProfile !== undefined ? { profile: options.registerCareProfile } : {}),
-        unknownCalls: options.mode === 'off' ? [] : unknownCallList(program.directCalls, knownRoutines),
+        unknownCalls: options.mode === 'off' ? [] : unknownCallList(program.directBoundaries, knownRoutines),
     };
+    const summariesForAnnotations = new Map(summariesByName);
+    const outputCandidatesByRoutine = new Map();
+    for (const candidate of outputCandidatesWithFixability) {
+        const existing = outputCandidatesByRoutine.get(candidate.routine) ?? [];
+        for (const unit of candidate.carriers) {
+            if (!existing.includes(unit))
+                existing.push(unit);
+        }
+        outputCandidatesByRoutine.set(candidate.routine, existing);
+    }
+    for (const [name, summary] of summariesForAnnotations) {
+        const candidates = outputCandidatesByRoutine.get(name);
+        if (candidates !== undefined && candidates.length > 0) {
+            summariesForAnnotations.set(name, { ...summary, outputCandidates: candidates });
+        }
+    }
     const annotations = options.emitAnnotations
-        ? buildAnnotations(loaded, program.routines, summariesByName, outputCandidatesWithFixability, {
+        ? buildAnnotations(loaded, program.routines, summariesForAnnotations, outputCandidatesWithFixability, {
             fixOutputCandidates: options.fixRegisterContracts === true,
             outputCandidateFixability,
             outputCandidateKey,

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

@@ -1,154 +1,41 @@
-function formatCarrierLine(tag, units) {
-    return `;!      ${tag.padEnd(10)}${units.join(',')}`;
-}
-function formatCandidateUnits(units) {
-    return units.length === 1 ? units[0] : `{${units.join(',')}}`;
-}
-function formatCarrierLineWithExpectOut(indentation, units) {
-    return `${indentation}; expects out ${formatCandidateUnits(units)}`;
-}
-function formatCarrierLineWithMaybeOut(indentation, units) {
-    return `${indentation};!      ${'maybe-out'.padEnd(10)}${formatCandidateUnits(units)}`;
-}
-function isGeneratedRegisterContractLine(line) {
-    return /^\s*;!\s*(in|out|clobbers|preserves|maybe-out)\b/i.test(line);
-}
-function isOutputCandidateHintLine(line) {
-    return /^\s*;\s*expects\s+out\b/i.test(line) || /^\s*;\s*!\s*maybe-out\b/i.test(line);
-}
-function normalizeLineEnding(text) {
-    return text.replace(/\r\n/g, '\n');
-}
-function splitSourceLines(text) {
-    return normalizeLineEnding(text).split('\n');
-}
-function lineDeltaForCandidate(line, deltas) {
-    let shift = 0;
-    for (const delta of deltas) {
-        if (delta.anchorLine < line) {
-            shift += delta.delta;
-        }
-    }
-    return shift;
-}
-function applyOutputCandidateHints(sourceText, outputCandidates, candidateFixability, deltas, outputCandidateKey) {
-    const lines = splitSourceLines(sourceText);
-    const grouped = new Map();
-    for (const candidate of outputCandidates) {
-        const adjustedLine = candidate.line + lineDeltaForCandidate(candidate.line, deltas);
-        const existing = grouped.get(adjustedLine);
-        const autoFixable = candidateFixability.get(outputCandidateKey(candidate.file, candidate.line, candidate.column)) ?? false;
-        if (existing === undefined) {
-            grouped.set(adjustedLine, { carriers: [...candidate.carriers], autoFixable });
-            continue;
-        }
-        const carriers = existing.carriers;
-        for (const carrier of candidate.carriers) {
-            if (!carriers.includes(carrier)) {
-                carriers.push(carrier);
-            }
-        }
-        existing.autoFixable = existing.autoFixable && autoFixable;
-    }
-    const candidates = [...grouped.entries()]
-        .map(([line, entry]) => ({ line, ...entry }))
-        .sort((left, right) => right.line - left.line);
-    for (const candidate of candidates) {
-        const index = candidate.line - 1;
-        if (index < 0 || index > lines.length)
-            continue;
-        if (index > 0 && isOutputCandidateHintLine(lines[index - 1] ?? ''))
-            continue;
-        const indentation = lines[index]?.match(/^\s*/)?.[0] ?? '';
-        const hint = candidate.autoFixable
-            ? formatCarrierLineWithExpectOut(indentation, candidate.carriers)
-            : formatCarrierLineWithMaybeOut(indentation, candidate.carriers);
-        lines.splice(index, 0, hint);
-    }
-    return lines.join('\n');
-}
-function annotateSourceFile(sourceText, routines, summariesByName) {
-    const routineLines = Array.from(routines)
+import { annotateRegisterCareContracts } from './annotate.js';
+import { applyExpectOutFixesToSource, findExpectOutFixesForCandidates, } from './fix.js';
+export function buildAnnotations(loaded, programRoutines, summariesByName, outputCandidates, options) {
+    const routines = programRoutines
         .filter((routine) => summariesByName.has(routine.name))
-        .sort((left, right) => right.span.start.line - left.span.start.line);
-    if (routineLines.length === 0)
-        return undefined;
-    const lines = splitSourceLines(sourceText);
-    let changed = false;
-    const deltas = [];
-    for (const routine of routineLines) {
-        const summary = summariesByName.get(routine.name);
-        if (!summary)
-            continue;
-        const insertLine = routine.span.start.line - 1;
-        if (insertLine < 0 || insertLine > lines.length)
-            continue;
-        const generatedLines = [
-            ...(summary.mayRead.length > 0 ? [formatCarrierLine('in', summary.mayRead)] : []),
-            ...(summary.mayWrite.length > 0 ? [formatCarrierLine('out', summary.mayWrite)] : []),
-            ...(summary.preserved.length > 0 ? [formatCarrierLine('preserves', summary.preserved)] : []),
-        ];
-        if (generatedLines.length === 0)
-            continue;
-        let start = insertLine;
-        for (let index = insertLine - 1; index >= 0 && isGeneratedRegisterContractLine(lines[index] ?? ''); index -= 1) {
-            start = index;
-        }
-        if (start === insertLine ||
-            lines.slice(start, insertLine).some((line) => line.trim().length === 0)) {
-            start = insertLine;
-        }
-        const existing = lines.slice(start, insertLine);
-        if (existing.length !== generatedLines.length ||
-            existing.some((line, index) => line !== generatedLines[index])) {
-            changed = true;
-            deltas.push({
-                anchorLine: routine.span.start.line,
-                delta: generatedLines.length - (insertLine - start),
-            });
-            lines.splice(start, insertLine - start, ...generatedLines);
-        }
+        .map((routine) => ({
+        routine,
+        summary: summariesByName.get(routine.name),
+    }));
+    const annotated = annotateRegisterCareContracts(loaded.sourceTexts, routines);
+    if (!options.fixOutputCandidates) {
+        return annotated.map((file) => ({ path: file.path, text: file.text }));
     }
-    if (!changed)
-        return undefined;
-    return {
-        text: lines.join('\n'),
-        deltas,
-    };
-}
-export function buildAnnotations(loaded, programRoutines, summariesByName, outputCandidates, options) {
-    const byFile = new Map();
-    for (const routine of programRoutines) {
-        if (!summariesByName.has(routine.name))
-            continue;
-        const file = byFile.get(routine.span.file);
-        if (file === undefined) {
-            byFile.set(routine.span.file, [routine]);
-        }
-        else {
-            file.push(routine);
-        }
+    const autoFixableCandidates = outputCandidates.filter((candidate) => options.outputCandidateFixability.get(options.outputCandidateKey(candidate.file, candidate.line, candidate.column)) === true);
+    const fixes = findExpectOutFixesForCandidates([...programRoutines], autoFixableCandidates);
+    if (fixes.length === 0) {
+        return annotated.map((file) => ({ path: file.path, text: file.text }));
+    }
+    const workingTexts = new Map(loaded.sourceTexts);
+    for (const file of annotated) {
+        workingTexts.set(file.path, file.text);
     }
     const out = [];
-    for (const [path, routines] of byFile) {
-        const sourceText = loaded.sourceTexts.get(path);
-        if (sourceText === undefined)
+    const fixesByFile = new Map();
+    for (const fix of fixes) {
+        const items = fixesByFile.get(fix.file) ?? [];
+        items.push(fix);
+        fixesByFile.set(fix.file, items);
+    }
+    for (const [path, text] of workingTexts) {
+        const reference = loaded.sourceTexts.get(path);
+        if (reference === undefined)
             continue;
-        let text = sourceText;
-        let deltas = [];
-        const annotation = annotateSourceFile(sourceText, routines, summariesByName);
-        if (annotation !== undefined) {
-            text = annotation.text;
-            deltas = annotation.deltas;
-        }
-        if (options.fixOutputCandidates) {
-            const candidatesForFile = outputCandidates.filter((candidate) => candidate.file === path);
-            if (candidatesForFile.length > 0) {
-                text = applyOutputCandidateHints(text, candidatesForFile, options.outputCandidateFixability, deltas, options.outputCandidateKey);
-            }
+        const fileFixes = fixesByFile.get(path) ?? [];
+        const nextText = fileFixes.length > 0 ? applyExpectOutFixesToSource(text, fileFixes, reference) : text;
+        if (nextText !== reference) {
+            out.push({ path, text: nextText });
         }
-        if (text !== sourceText)
-            out.push({ path, text });
     }
-    return out;
+    return out.sort((left, right) => left.path.localeCompare(right.path));
 }

package/dist/src/register-care/fix.d.ts

@@ -6,4 +6,6 @@ export interface RegisterCareExpectOutFix {
     routine: string;
     carriers: RegisterCareUnit[];
 }
+export declare function findExpectOutFixesForCandidates(routines: RegisterCareRoutine[], candidates: RegisterCareOutputCandidate[]): RegisterCareExpectOutFix[];
 export declare function autoFixableCandidateKeys(routines: RegisterCareRoutine[], candidates: RegisterCareOutputCandidate[]): Set<string>;
+export declare function applyExpectOutFixesToSource(source: string, fixes: RegisterCareExpectOutFix[], referenceSource?: string): string;

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

@@ -1,5 +1,7 @@
 import { getZ80InstructionEffect } from '../z80/effects.js';
 import { instructionSuccessors, labelIndex } from './controlFlow.js';
+import { contractCarrierList } from './report.js';
+import { joinSourceLines, splitSourceLines } from './sourceText.js';
 function sameLocation(a, b) {
     return a.file === b.file && a.line === b.line && a.column === b.column;
 }
@@ -68,6 +70,9 @@ function findExpectOutFixes(routines, candidates) {
     }
     return out;
 }
+export function findExpectOutFixesForCandidates(routines, candidates) {
+    return findExpectOutFixes(routines, candidates);
+}
 export function autoFixableCandidateKeys(routines, candidates) {
     const fixes = findExpectOutFixes(routines, candidates);
     const out = new Set();
@@ -76,3 +81,50 @@ export function autoFixableCandidateKeys(routines, candidates) {
     }
     return out;
 }
+function isExpectOutLine(line) {
+    return /^\s*;\s*expects\s+out\b/i.test(line);
+}
+function expectedCallLine(originalLines, fix) {
+    return originalLines[fix.line - 1]?.trim();
+}
+function findCallLineIndex(lines, originalLines, fix) {
+    const expected = expectedCallLine(originalLines, fix);
+    if (!expected)
+        return undefined;
+    const preferred = fix.line - 1;
+    if (lines[preferred]?.trim() === expected)
+        return preferred;
+    let best;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (let index = 0; index < lines.length; index += 1) {
+        if (lines[index]?.trim() !== expected)
+            continue;
+        const distance = Math.abs(index - preferred);
+        if (distance < bestDistance) {
+            best = index;
+            bestDistance = distance;
+        }
+    }
+    return best;
+}
+function indentation(line) {
+    return line.match(/^\s*/)?.[0] ?? '';
+}
+export function applyExpectOutFixesToSource(source, fixes, referenceSource = source) {
+    if (fixes.length === 0)
+        return source;
+    const originalLines = referenceSource.split(/\r?\n/);
+    const sourceLines = splitSourceLines(source);
+    const { lines } = sourceLines;
+    const sorted = [...fixes].sort((a, b) => b.line - a.line || b.column - a.column);
+    for (const fix of sorted) {
+        const index = findCallLineIndex(lines, originalLines, fix);
+        if (index === undefined)
+            continue;
+        if (index > 0 && isExpectOutLine(lines[index - 1] ?? ''))
+            continue;
+        const prefix = indentation(lines[index] ?? '');
+        lines.splice(index, 0, `${prefix}; expects out ${contractCarrierList(fix.carriers)}`);
+    }
+    return joinSourceLines(sourceLines);
+}

package/dist/src/register-care/instruction-shape.d.ts

@@ -0,0 +1,11 @@
+import type { Z80Instruction, Z80Operand } from '../z80/instruction.js';
+import type { RegisterCareInstruction } from './types.js';
+export declare function instructionHead(item: RegisterCareInstruction): string;
+export declare function regName(operand: Z80Operand | undefined): string | undefined;
+export declare function instructionOperandCount(instruction: Z80Instruction): number;
+export declare function instructionOperand(instruction: Z80Instruction, index: number): Z80Operand | undefined;
+export declare function isUnconditionalReturnInstruction(item: RegisterCareInstruction): boolean;
+export declare function isPureTokenTransferInstruction(item: RegisterCareInstruction): boolean;
+export declare function isAccumulatorSelfOperand(item: RegisterCareInstruction): boolean;
+export declare function isImmediateZeroOperand(item: RegisterCareInstruction): boolean;
+export declare function isRegisterOperand(item: RegisterCareInstruction | undefined, index: number, name: string): boolean;