@jhlagado/azm 0.2.0 → 0.2.1

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;

package/dist/src/register-care/instruction-shape.js

@@ -0,0 +1,129 @@
+export function instructionHead(item) {
+    return item.instruction.mnemonic.toLowerCase();
+}
+export function regName(operand) {
+    if (operand === undefined)
+        return undefined;
+    switch (operand.kind) {
+        case 'reg8':
+            return operand.register.toUpperCase();
+        case 'reg16':
+            return operand.register.toUpperCase();
+        case 'reg-index16':
+            return operand.register.toUpperCase();
+        case 'reg-half-index':
+            return operand.register.toUpperCase();
+        default:
+            return undefined;
+    }
+}
+function immValue(operand) {
+    if (operand?.kind !== 'imm')
+        return undefined;
+    const expression = operand.expression;
+    return expression.kind === 'number' ? expression.value : undefined;
+}
+export function instructionOperandCount(instruction) {
+    switch (instruction.mnemonic) {
+        case 'ret':
+        case 'ret-cc':
+            return instruction.mnemonic === 'ret' ? 0 : 1;
+        case 'ld':
+            return 2;
+        case 'ex':
+            return 2;
+        case 'jp':
+        case 'jp-cc':
+        case 'jr':
+        case 'jr-cc':
+        case 'djnz':
+        case 'call':
+        case 'call-cc':
+            return 1;
+        case 'add':
+        case 'adc':
+        case 'sbc':
+            return 'target' in instruction ? 2 : 1;
+        case 'sub':
+        case 'and':
+        case 'or':
+        case 'xor':
+        case 'cp':
+            return 1;
+        default:
+            return 0;
+    }
+}
+export function instructionOperand(instruction, index) {
+    switch (instruction.mnemonic) {
+        case 'ld':
+            return index === 0 ? instruction.target : index === 1 ? instruction.source : undefined;
+        case 'ex': {
+            if (index === 0) {
+                return instruction.form === 'de-hl'
+                    ? { kind: 'reg16', register: 'de' }
+                    : instruction.form === 'af-af'
+                        ? { kind: 'reg16', register: 'af' }
+                        : undefined;
+            }
+            if (index === 1) {
+                return instruction.form === 'de-hl'
+                    ? { kind: 'reg16', register: 'hl' }
+                    : undefined;
+            }
+            return undefined;
+        }
+        case 'add':
+        case 'adc':
+        case 'sbc':
+            if ('target' in instruction) {
+                return index === 0 ? instruction.target : index === 1 ? instruction.source : undefined;
+            }
+            return index === 0 ? instruction.source : undefined;
+        case 'sub':
+        case 'and':
+        case 'or':
+        case 'xor':
+        case 'cp':
+            return index === 0 ? instruction.source : undefined;
+        default:
+            return undefined;
+    }
+}
+export function isUnconditionalReturnInstruction(item) {
+    const head = instructionHead(item);
+    if (head === 'ret')
+        return item.instruction.mnemonic === 'ret';
+    return head === 'retn' || head === 'reti';
+}
+export function isPureTokenTransferInstruction(item) {
+    const head = instructionHead(item);
+    if (head === 'ex')
+        return true;
+    if (head !== 'ld' || instructionOperandCount(item.instruction) !== 2)
+        return false;
+    const dst = instructionOperand(item.instruction, 0);
+    const src = instructionOperand(item.instruction, 1);
+    if (regName(dst) === undefined)
+        return false;
+    return regName(src) !== undefined || src?.kind === 'imm';
+}
+export function isAccumulatorSelfOperand(item) {
+    const inst = item.instruction;
+    if (inst.mnemonic === 'or' || inst.mnemonic === 'and' || inst.mnemonic === 'xor') {
+        return inst.source.kind === 'reg8' && inst.source.register === 'a';
+    }
+    return false;
+}
+export function isImmediateZeroOperand(item) {
+    const inst = item.instruction;
+    if (inst.mnemonic !== 'cp')
+        return false;
+    return immValue(inst.source) === 0;
+}
+export function isRegisterOperand(item, index, name) {
+    if (item === undefined)
+        return false;
+    const operand = instructionOperand(item.instruction, index);
+    return regName(operand) === name.toUpperCase();
+}

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

@@ -48,10 +48,7 @@ function hintUnitsForLine(hints, file, callLine) {
     return prior?.comment.kind === 'expectOut' ? unique(prior.comment.carriers) : [];
 }
 function outputUnits(summary) {
-    return unique([
-        ...(summary.valueRelations?.flatMap((relation) => relation.out) ?? []),
-        ...(summary.mayOutput ?? []),
-    ]);
+    return unique(summary.valueRelations.flatMap((relation) => relation.out));
 }
 function setEqual(left, right) {
     if (left.size !== right.size)
@@ -148,7 +145,7 @@ export function findRegisterCareConflicts(routine, summaries, hints) {
         for (const unit of outputUnits(summary))
             accepted.add(unit);
         const carriers = unique(summary.mayWrite.filter((unit) => liveOut[index].has(unit) && !accepted.has(unit)));
-        if (carriers.length > 0 && !boundary.conditional) {
+        if (carriers.length > 0) {
             conflicts.push({
                 file: item.file,
                 line: item.line,
@@ -171,8 +168,19 @@ export function findCallerOutputCandidateObservations(routines, summaries) {
     for (const routine of routines) {
         const { liveOut } = liveSetsForRoutine(routine, summaries);
         for (const { item, index, boundary, target, summary } of resolvedBoundariesForRoutine(routine, summaries)) {
-            const alreadyOutput = new Set(outputUnits(summary));
-            const carriers = unique(summary.mayWrite.filter((unit) => liveOut[index].has(unit) && !alreadyOutput.has(unit)));
+            const intentionalOutputs = new Set(outputUnits(summary));
+            const carrierSources = [];
+            for (const unit of summary.mayWrite) {
+                if (liveOut[index].has(unit) && !intentionalOutputs.has(unit)) {
+                    carrierSources.push(unit);
+                }
+            }
+            for (const unit of intentionalOutputs) {
+                if (liveOut[index].has(unit)) {
+                    carrierSources.push(unit);
+                }
+            }
+            const carriers = unique(carrierSources);
             if (carriers.length > 0) {
                 out.push({
                     file: item.file,

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

@@ -23,6 +23,8 @@ export function getRegisterCareProfile(name) {
                     mayOutput: [],
                     preserved: ['B', 'C', 'D', 'E', 'H', 'L'],
                     valueRelations: [],
+                    stackBalanced: true,
+                    hasUnknownStackEffect: false,
                 },
             ],
         ]),
@@ -36,6 +38,8 @@ export function getRegisterCareProfile(name) {
                     mayOutput: ['A', 'carry', 'zero'],
                     preserved: ['B', 'C', 'D', 'E', 'H', 'L'],
                     valueRelations: [{ out: ['A', 'carry', 'zero'], from: [] }],
+                    stackBalanced: true,
+                    hasUnknownStackEffect: false,
                 },
             ],
         ]),

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

@@ -13,6 +13,21 @@ function instructionCallTarget(item) {
     }
     return undefined;
 }
+function instructionTailJumpTarget(item, entryNames) {
+    if (item.kind !== 'instruction')
+        return undefined;
+    const mnemonic = item.instruction.mnemonic;
+    if (mnemonic === 'jp-cc' && entryNames === undefined)
+        return undefined;
+    if (mnemonic !== 'jp' && mnemonic !== 'jp-cc')
+        return undefined;
+    const target = routineNameFromExpression(item.instruction.expression);
+    if (target === undefined || target.startsWith('.'))
+        return undefined;
+    if (entryNames !== undefined && !entryNames.has(target))
+        return undefined;
+    return target;
+}
 function toInstruction(item, labels) {
     return {
         instruction: item.instruction,
@@ -22,9 +37,16 @@ function toInstruction(item, labels) {
         labels: [...labels],
     };
 }
+function pushDirectBoundary(boundaries, target, subject, file, line, column) {
+    boundaries.push({ target, subject, file, line, column });
+}
 export function buildRegisterCareProgramModel(items) {
     const routines = [];
     const directCalls = [];
+    const filesWithEntryLabels = new Set(items
+        .filter((item) => item.kind === 'label')
+        .filter((item) => item.isEntry === true)
+        .map((item) => item.span.sourceName));
     let routineName;
     let entryLabels = [];
     let labels = [];
@@ -35,14 +57,28 @@ export function buildRegisterCareProgramModel(items) {
     const startRoutine = (item) => {
         sourceName = item.span.sourceName;
         routineName = item.name;
-        entryLabels = [item.name];
+        entryLabels = item.isEntry === true ? [item.name] : [];
         labels = [item.name];
         routineStartLine = item.span.line;
         routineStartColumn = item.span.column;
         instructions = [];
     };
     const flushRoutine = () => {
-        if (routineName === undefined || instructions.length === 0 || routineStartLine === undefined) {
+        if (routineName === undefined || routineStartLine === undefined) {
+            return;
+        }
+        if (instructions.length === 0) {
+            routines.push({
+                name: routineName,
+                labels: [...labels],
+                entryLabels: [...entryLabels],
+                instructions: [],
+                span: {
+                    file: sourceName ?? '',
+                    start: { line: routineStartLine, column: routineStartColumn ?? 1 },
+                    end: { line: routineStartLine, column: routineStartColumn ?? 1 },
+                },
+            });
             return;
         }
         const end = instructions[instructions.length - 1];
@@ -88,12 +124,7 @@ export function buildRegisterCareProgramModel(items) {
             instructions.push(toInstruction(item, labels));
             const directTarget = instructionCallTarget(item);
             if (directTarget !== undefined) {
-                directCalls.push({
-                    target: directTarget,
-                    file: item.span.sourceName,
-                    line: item.span.line,
-                    column: item.span.column,
-                });
+                pushDirectBoundary(directCalls, directTarget, `CALL ${directTarget}`, item.span.sourceName, item.span.line, item.span.column);
             }
             continue;
         }
@@ -104,19 +135,54 @@ export function buildRegisterCareProgramModel(items) {
             continue;
         }
         if (routineName === undefined) {
+            if (filesWithEntryLabels.has(item.span.sourceName) && item.isEntry !== true) {
+                continue;
+            }
             startRoutine(item);
             continue;
         }
-        if (instructions.length > 0 ||
-            sourceName === undefined ||
-            sourceName !== item.span.sourceName) {
+        if (sourceName === undefined || sourceName !== item.span.sourceName) {
+            finalizeAndRestart(item);
+            continue;
+        }
+        if (instructions.length > 0) {
+            if (filesWithEntryLabels.has(item.span.sourceName) && item.isEntry !== true) {
+                labels.push(item.name);
+                continue;
+            }
             finalizeAndRestart(item);
             continue;
         }
         // Multiple global labels before body on same routine are coalesced as entry labels.
         labels.push(item.name);
-        entryLabels.push(item.name);
+        if (item.isEntry === true) {
+            entryLabels.push(item.name);
+        }
     }
     flushRoutine();
-    return { routines, directCalls };
+    const entryNamesByFile = new Map();
+    for (const item of items) {
+        if (item.kind !== 'label' || item.isEntry !== true)
+            continue;
+        const names = entryNamesByFile.get(item.span.sourceName) ?? new Set();
+        names.add(item.name);
+        entryNamesByFile.set(item.span.sourceName, names);
+    }
+    const directTailJumps = [];
+    for (const item of items) {
+        if (item.kind !== 'instruction')
+            continue;
+        const entryNames = filesWithEntryLabels.has(item.span.sourceName)
+            ? entryNamesByFile.get(item.span.sourceName)
+            : undefined;
+        const target = instructionTailJumpTarget(item, entryNames);
+        if (target === undefined)
+            continue;
+        pushDirectBoundary(directTailJumps, target, `JP ${target}`, item.span.sourceName, item.span.line, item.span.column);
+    }
+    return {
+        routines,
+        directCalls,
+        directBoundaries: [...directCalls, ...directTailJumps],
+    };
 }

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

@@ -1,4 +1,5 @@
 import type { RegisterCareReportModel, RegisterCareUnit, RoutineSummary } from './types.js';
-export declare function renderRegisterCareReport(model: RegisterCareReportModel): string;
 export declare function contractCarrierList(units: RegisterCareUnit[]): string;
+export declare function renderRegisterCareReport(model: RegisterCareReportModel): string;
 export declare function renderRegisterCareInterface(summaries: RoutineSummary[]): string;
+export declare function renderRegisterCareSourceBlock(summary: RoutineSummary): string[];