@jhlagado/azm 0.2.0 → 0.2.1

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

@@ -1,23 +1,94 @@
-function listUnits(units) {
+function list(units) {
     return units.length === 0 ? '-' : units.join(',');
 }
+const FLAG_UNITS = new Set(['carry', 'zero', 'sign', 'parity', 'halfCarry']);
+const CONTRACT_CARRIER_PAIRS = [
+    { label: 'BC', hi: 'B', lo: 'C' },
+    { label: 'DE', hi: 'D', lo: 'E' },
+    { label: 'HL', hi: 'H', lo: 'L' },
+    { label: 'IX', hi: 'IXH', lo: 'IXL' },
+    { label: 'IY', hi: 'IYH', lo: 'IYL' },
+    { label: 'SP', hi: 'SPH', lo: 'SPL' },
+];
+export function contractCarrierList(units) {
+    const unique = [...new Set(units)];
+    const unitSet = new Set(unique);
+    const emitted = new Set();
+    const parts = [];
+    for (const unit of unique) {
+        if (emitted.has(unit))
+            continue;
+        const pair = CONTRACT_CARRIER_PAIRS.find((candidate) => (candidate.hi === unit || candidate.lo === unit) &&
+            unitSet.has(candidate.hi) &&
+            unitSet.has(candidate.lo));
+        if (pair) {
+            parts.push(pair.label);
+            emitted.add(pair.hi);
+            emitted.add(pair.lo);
+            continue;
+        }
+        parts.push(unit);
+        emitted.add(unit);
+    }
+    return parts.length === 0 ? '-' : parts.join(',');
+}
+function relationOutputUnits(relations) {
+    return relations.flatMap((rel) => rel.out);
+}
+function contractEntries(summary) {
+    const out = [];
+    if (summary.mayRead.length > 0)
+        out.push({ keyword: 'in', carriers: contractCarrierList(summary.mayRead) });
+    const outputUnits = relationOutputUnits(summary.valueRelations);
+    if (outputUnits.length > 0)
+        out.push({ keyword: 'out', carriers: contractCarrierList(outputUnits) });
+    const relationOut = relationOutUnits(summary);
+    const clobbers = summary.mayWrite.filter((unit) => !relationOut.has(unit));
+    if (clobbers.length > 0)
+        out.push({ keyword: 'clobbers', carriers: contractCarrierList(clobbers) });
+    return out;
+}
+function sourceContractEntries(summary) {
+    const out = [];
+    if (summary.mayRead.length > 0)
+        out.push({ keyword: 'in', carriers: contractCarrierList(summary.mayRead) });
+    const relationOut = relationOutUnits(summary);
+    const candidates = (summary.outputCandidates ?? []).filter((unit) => !relationOut.has(unit));
+    if (candidates.length > 0)
+        out.push({ keyword: 'maybe-out', carriers: contractCarrierList(candidates) });
+    const outputUnits = relationOutputUnits(summary.valueRelations);
+    if (outputUnits.length > 0)
+        out.push({ keyword: 'out', carriers: contractCarrierList(outputUnits) });
+    const clobbers = summary.mayWrite.filter((unit) => !relationOut.has(unit) && !FLAG_UNITS.has(unit));
+    if (clobbers.length > 0)
+        out.push({ keyword: 'clobbers', carriers: contractCarrierList(clobbers) });
+    return out;
+}
+function stackStatus(summary) {
+    const balance = summary.stackBalanced ? 'balanced' : 'unbalanced';
+    return summary.hasUnknownStackEffect ? `${balance}, unknown effect` : balance;
+}
+function relationOutUnits(summary) {
+    return new Set(summary.valueRelations.flatMap((rel) => rel.out));
+}
 export function renderRegisterCareReport(model) {
-    const lines = [
-        'AZM Register-Care Report',
-        `Entry: ${model.entryFile}`,
-        `Mode: ${model.mode}`,
-        ...(model.profile !== undefined ? [`Profile: ${model.profile}`] : []),
-        '',
-    ];
+    const lines = ['AZM Register-Care Report', `Entry: ${model.entryFile}`, `Mode: ${model.mode}`];
+    if (model.profile)
+        lines.push(`Profile: ${model.profile}`);
+    lines.push('');
     if (model.summaries.length === 0) {
         lines.push('Routines: none', '');
     }
     else {
         for (const summary of model.summaries) {
             lines.push(`Routine: ${summary.name}`);
-            lines.push(`  reads: ${listUnits(summary.mayRead)}`);
-            lines.push(`  writes: ${listUnits(summary.mayWrite)}`);
-            lines.push(`  preserves: ${listUnits(summary.preserved)}`);
+            lines.push(`  reads: ${list(summary.mayRead)}`);
+            lines.push(`  writes: ${list(summary.mayWrite)}`);
+            lines.push(`  preserves: ${list(summary.preserved)}`);
+            lines.push(`  stack: ${stackStatus(summary)}`);
+            for (const rel of summary.valueRelations) {
+                lines.push(`  relation: ${list(rel.out)} <= ${list(rel.from)}`);
+            }
             lines.push('');
         }
     }
@@ -27,17 +98,17 @@ export function renderRegisterCareReport(model) {
     }
     else {
         for (const conflict of model.conflicts) {
-            lines.push(`  ${conflict.file}:${conflict.line}:${conflict.column}: ${conflict.callTarget}: ${conflict.message}`);
+            lines.push(`  ${conflict.file}:${conflict.line}:${conflict.column}: ${conflict.callTarget}: ${list(conflict.carriers)}: ${conflict.message}`);
         }
     }
     lines.push('');
     lines.push('Output candidates:');
-    if (model.outputCandidates === undefined || model.outputCandidates.length === 0) {
+    if (!model.outputCandidates || model.outputCandidates.length === 0) {
         lines.push('  none');
     }
     else {
         for (const candidate of model.outputCandidates) {
-            lines.push(`  ${candidate.file}:${candidate.line}:${candidate.column}: ${candidate.routine}: ${candidate.carriers.join(',')}: ${candidate.message}`);
+            lines.push(`  ${candidate.file}:${candidate.line}:${candidate.column}: ${candidate.routine}: ${list(candidate.carriers)}: ${candidate.message}`);
         }
     }
     lines.push('');
@@ -46,37 +117,23 @@ export function renderRegisterCareReport(model) {
         lines.push('  none');
     }
     else {
-        for (const call of model.unknownCalls) {
+        for (const call of model.unknownCalls)
             lines.push(`  ${call}`);
-        }
     }
     lines.push('');
     return `${lines.join('\n')}\n`;
 }
-export function contractCarrierList(units) {
-    return units.length === 0 ? '-' : units.join(',');
-}
 export function renderRegisterCareInterface(summaries) {
     const lines = [];
     for (const summary of summaries) {
-        if (summary.mayRead.length === 0 &&
-            summary.mayWrite.length === 0 &&
-            summary.preserved.length === 0) {
-            continue;
-        }
         lines.push(`extern ${summary.name}`);
-        if (summary.mayRead.length > 0) {
-            lines.push(`in ${contractCarrierList(summary.mayRead)}`);
-        }
-        if (summary.mayWrite.length > 0) {
-            lines.push(`clobbers ${contractCarrierList(summary.mayWrite)}`);
-        }
-        if (summary.preserved.length > 0) {
-            lines.push(`preserves ${contractCarrierList(summary.preserved)}`);
+        for (const entry of contractEntries(summary)) {
+            lines.push(`${entry.keyword} ${entry.carriers}`);
         }
         lines.push('end', '');
     }
-    if (lines.length === 0)
-        lines.push('No inferred contracts were emitted.', '');
     return `${lines.join('\n')}\n`;
 }
+export function renderRegisterCareSourceBlock(summary) {
+    return sourceContractEntries(summary).map((entry) => `;!      ${entry.keyword.padEnd(10)}${entry.carriers}`);
+}

package/dist/src/register-care/routine-summaries.d.ts

@@ -0,0 +1,6 @@
+import type { RegisterCareRoutine, RoutineContract, RoutineSummary } from './types.js';
+export declare function summariesWithExternalContracts(summaries: RoutineSummary[], contracts: Map<string, RoutineContract>, routineNameSet: Set<string>): RoutineSummary[];
+export declare function inferRoutineSummariesToFixedPoint(routines: RegisterCareRoutine[], contracts: Map<string, RoutineContract>, routineNameSet: Set<string>, profileSummaries: RoutineSummary[]): Array<{
+    routine: RegisterCareRoutine;
+    summary: RoutineSummary;
+}>;

package/dist/src/register-care/routine-summaries.js

@@ -0,0 +1,89 @@
+import { applyRoutineContract, inferRoutineSummary } from './summary.js';
+function emptyRoutineSummary(name) {
+    return {
+        name,
+        mayRead: [],
+        mayWrite: [],
+        preserved: [],
+        valueRelations: [],
+        stackBalanced: true,
+        hasUnknownStackEffect: false,
+    };
+}
+function isLocalLabel(name) {
+    return name.startsWith('.');
+}
+function nonLocalLabels(labels) {
+    return labels.filter((label) => !isLocalLabel(label));
+}
+function boundaryLabels(routine) {
+    return routine.entryLabels.length > 0 ? routine.entryLabels : nonLocalLabels(routine.labels);
+}
+function contractForRoutine(routine, contracts) {
+    return boundaryLabels(routine)
+        .map((label) => contracts.get(label))
+        .find((contract) => contract !== undefined);
+}
+export function summariesWithExternalContracts(summaries, contracts, routineNameSet) {
+    const out = [...summaries];
+    for (const contract of contracts.values()) {
+        if (!routineNameSet.has(contract.name)) {
+            out.push(applyRoutineContract(emptyRoutineSummary(contract.name), contract));
+        }
+    }
+    return out;
+}
+function buildBoundarySummaryMap(summaries, routineSummaries, profileSummaries) {
+    const boundarySummaryMap = new Map(profileSummaries.map((summary) => [summary.name, summary]));
+    for (const summary of summaries) {
+        boundarySummaryMap.set(summary.name, summary);
+    }
+    for (const { routine, summary } of routineSummaries) {
+        for (const label of boundaryLabels(routine)) {
+            boundarySummaryMap.set(label, summary);
+        }
+    }
+    return boundarySummaryMap;
+}
+function summarizeRoutines(routines, contracts, boundarySummaryMap = new Map()) {
+    return routines.map((routine) => {
+        const inferred = inferRoutineSummary(routine, boundarySummaryMap);
+        const contract = contractForRoutine(routine, contracts);
+        return { routine, summary: contract ? applyRoutineContract(inferred, contract) : inferred };
+    });
+}
+function sortedUnique(values) {
+    return Array.from(new Set(values)).sort();
+}
+function summaryFingerprint(summary) {
+    const relations = summary.valueRelations
+        .map((relation) => `${relation.out.join(',')}<-${relation.from.join(',')}`)
+        .sort();
+    return JSON.stringify({
+        name: summary.name,
+        mayRead: sortedUnique(summary.mayRead),
+        mayWrite: sortedUnique(summary.mayWrite),
+        preserved: sortedUnique(summary.preserved),
+        relations,
+        stackBalanced: summary.stackBalanced,
+        hasUnknownStackEffect: summary.hasUnknownStackEffect,
+    });
+}
+function routineSummariesFingerprint(routineSummaries) {
+    return routineSummaries.map((item) => summaryFingerprint(item.summary)).join('\n');
+}
+export function inferRoutineSummariesToFixedPoint(routines, contracts, routineNameSet, profileSummaries) {
+    let routineSummaries = summarizeRoutines(routines, contracts);
+    const maxPasses = Math.max(2, routines.length + 2);
+    for (let pass = 0; pass < maxPasses; pass += 1) {
+        const summaries = summariesWithExternalContracts(routineSummaries.map((item) => item.summary), contracts, routineNameSet);
+        const boundarySummaryMap = buildBoundarySummaryMap(summaries, routineSummaries, profileSummaries);
+        const nextRoutineSummaries = summarizeRoutines(routines, contracts, boundarySummaryMap);
+        if (routineSummariesFingerprint(nextRoutineSummaries) ===
+            routineSummariesFingerprint(routineSummaries)) {
+            return nextRoutineSummaries;
+        }
+        routineSummaries = nextRoutineSummaries;
+    }
+    return routineSummaries;
+}

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

@@ -0,0 +1,8 @@
+type SourceLines = {
+    lines: string[];
+    trailingNewline: boolean;
+    eol: '\n' | '\r\n';
+};
+export declare function splitSourceLines(text: string): SourceLines;
+export declare function joinSourceLines({ lines, trailingNewline, eol }: SourceLines): string;
+export {};

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

@@ -0,0 +1,15 @@
+function lineEnding(text) {
+    return text.includes('\r\n') ? '\r\n' : '\n';
+}
+export function splitSourceLines(text) {
+    const eol = lineEnding(text);
+    const trailingNewline = text.endsWith('\n');
+    const lines = text.split(/\r?\n/);
+    if (trailingNewline)
+        lines.pop();
+    return { lines, trailingNewline, eol };
+}
+export function joinSourceLines({ lines, trailingNewline, eol }) {
+    const text = lines.join(eol);
+    return trailingNewline ? `${text}${eol}` : text;
+}

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

@@ -3,10 +3,10 @@ import type { AnalyzeRegisterCareOptions, RegisterCareDirectCall, RegisterCareRo
 export declare function buildProfileSummaries(profileName: AnalyzeRegisterCareOptions['registerCareProfile']): RoutineSummary[];
 export declare function buildProfileSummaryLookup(profileName: AnalyzeRegisterCareOptions['registerCareProfile']): Map<string, RoutineSummary>;
 export declare function routineNames(routines: readonly RegisterCareRoutine[]): string[];
-export declare function buildSummaries(routines: readonly RegisterCareRoutine[], contractMap: Map<string, RoutineContract>): RoutineSummary[];
+export declare function buildSummaries(routines: readonly RegisterCareRoutine[], contractMap: Map<string, RoutineContract>, profileSummaries?: readonly RoutineSummary[]): RoutineSummary[];
 export declare function buildSummaryByName(routines: readonly RegisterCareRoutine[], summaries: readonly RoutineSummary[], profileSummaries?: readonly RoutineSummary[]): Map<string, RoutineSummary>;
 export declare function withAcceptedOutputs(summaries: readonly RoutineSummary[], acceptedOutputCandidates: ReadonlyMap<string, RegisterCareUnit[]> | undefined): RoutineSummary[];
-export declare function unknownBoundaryDiagnostics(directCalls: readonly RegisterCareDirectCall[], knownRoutines: ReadonlySet<string>): Diagnostic[];
-export declare function unknownCallList(directCalls: readonly RegisterCareDirectCall[], knownRoutines: ReadonlySet<string>): string[];
+export declare function unknownBoundaryDiagnostics(directBoundaries: readonly RegisterCareDirectCall[], knownRoutines: ReadonlySet<string>): Diagnostic[];
+export declare function unknownCallList(directBoundaries: readonly RegisterCareDirectCall[], knownRoutines: ReadonlySet<string>): string[];
 export declare function buildOutputCandidateFixability(routines: readonly RegisterCareRoutine[], outputCandidates: readonly RegisterCareOutputCandidate[], autoFixableCandidateKeys: (routines: RegisterCareRoutine[], outputCandidates: RegisterCareOutputCandidate[]) => ReadonlySet<string>): ReadonlyMap<string, boolean>;
 export declare function outputCandidateKey(file: string, line: number, column: number): string;

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

@@ -1,5 +1,5 @@
 import { getRegisterCareProfile } from './profiles.js';
-import { getZ80InstructionEffect } from '../z80/effects.js';
+import { inferRoutineSummariesToFixedPoint, summariesWithExternalContracts, } from './routine-summaries.js';
 function unique(values) {
     const out = [];
     for (const value of values) {
@@ -8,22 +8,16 @@ function unique(values) {
     }
     return out;
 }
-function inferRoutineSummary(routine) {
-    const reads = new Set();
-    const writes = new Set();
-    for (const instruction of routine.instructions) {
-        const effect = getZ80InstructionEffect(instruction.instruction);
-        for (const unit of effect.reads)
-            reads.add(unit);
-        for (const unit of effect.writes)
-            writes.add(unit);
-    }
-    return {
-        name: routine.name,
-        mayRead: Array.from(reads),
-        mayWrite: Array.from(writes),
-        preserved: [],
-    };
+function isLocalLabel(name) {
+    return name.startsWith('.');
+}
+function boundaryLabels(routine) {
+    return routine.entryLabels.length > 0
+        ? routine.entryLabels
+        : routine.labels.filter((label) => !isLocalLabel(label));
+}
+function routineNameSet(routines) {
+    return new Set(routines.flatMap((routine) => boundaryLabels(routine)));
 }
 export function buildProfileSummaries(profileName) {
     const profile = getRegisterCareProfile(profileName);
@@ -46,48 +40,13 @@ export function buildProfileSummaryLookup(profileName) {
     return out;
 }
 export function routineNames(routines) {
-    return routines.flatMap((routine) => routine.entryLabels.length > 0 ? routine.entryLabels : [routine.name]);
+    return routines.flatMap((routine) => boundaryLabels(routine));
 }
-function entryContract(routine, contractMap) {
-    for (const label of routine.entryLabels.length > 0 ? routine.entryLabels : [routine.name]) {
-        const contract = contractMap.get(label);
-        if (contract !== undefined)
-            return contract;
-    }
-    return contractMap.get(routine.name);
-}
-export function buildSummaries(routines, contractMap) {
-    const out = [];
-    const written = new Set();
-    for (const routine of routines) {
-        const inferred = inferRoutineSummary(routine);
-        const contract = entryContract(routine, contractMap);
-        out.push({
-            name: routine.name,
-            mayRead: unique([...inferred.mayRead, ...(contract?.in ?? [])]),
-            mayWrite: unique([
-                ...inferred.mayWrite,
-                ...(contract?.out ?? []),
-                ...(contract?.clobbers ?? []),
-            ]),
-            preserved: unique([...inferred.preserved, ...(contract?.preserves ?? [])]),
-        });
-        written.add(routine.name);
-        for (const alias of routine.entryLabels)
-            written.add(alias);
-    }
-    for (const [name, contract] of contractMap) {
-        if (written.has(name))
-            continue;
-        out.push({
-            name,
-            mayRead: [...contract.in],
-            mayWrite: [...contract.out, ...contract.clobbers],
-            preserved: [...contract.preserves],
-        });
-        written.add(name);
-    }
-    return out;
+export function buildSummaries(routines, contractMap, profileSummaries = []) {
+    const names = routineNameSet(routines);
+    const routineSummaries = inferRoutineSummariesToFixedPoint([...routines], contractMap, names, [...profileSummaries]);
+    const summaries = routineSummaries.map((item) => item.summary);
+    return summariesWithExternalContracts(summaries, contractMap, names);
 }
 export function buildSummaryByName(routines, summaries, profileSummaries = []) {
     const out = new Map();
@@ -103,7 +62,7 @@ export function buildSummaryByName(routines, summaries, profileSummaries = []) {
         const routineSummary = byRoutine.get(routine.name);
         if (routineSummary === undefined)
             continue;
-        for (const alias of routine.entryLabels.length > 0 ? routine.entryLabels : [routine.name]) {
+        for (const alias of boundaryLabels(routine)) {
             out.set(alias, routineSummary);
         }
     }
@@ -118,28 +77,36 @@ export function withAcceptedOutputs(summaries, acceptedOutputCandidates) {
         if (!accepted || accepted.length === 0) {
             return summary;
         }
-        const merged = unique([...summary.mayWrite, ...accepted]);
-        return {
-            ...summary,
-            mayWrite: merged,
-            mayOutput: unique([...accepted]),
-        };
+        const written = new Set(summary.mayWrite);
+        const promoted = accepted.filter((unit) => written.has(unit));
+        if (promoted.length === 0) {
+            return summary;
+        }
+        const valueRelations = [...summary.valueRelations];
+        for (const unit of promoted) {
+            if (!valueRelations.some((relation) => relation.out.includes(unit))) {
+                valueRelations.push({ out: [unit], from: [] });
+            }
+        }
+        return { ...summary, valueRelations };
     });
 }
-export function unknownBoundaryDiagnostics(directCalls, knownRoutines) {
-    return directCalls
-        .filter((call) => !knownRoutines.has(call.target))
-        .map((call) => ({
+export function unknownBoundaryDiagnostics(directBoundaries, knownRoutines) {
+    return directBoundaries
+        .filter((boundary) => !knownRoutines.has(boundary.target))
+        .map((boundary) => ({
         severity: 'warning',
         code: 'AZMN_REGISTER_CARE',
-        message: `Register-care cannot prove ${call.target}; add a routine body or .asmi extern contract.`,
-        sourceName: call.file,
-        line: call.line,
-        column: call.column,
+        message: `Register-care cannot prove ${boundary.subject}; add a routine body or .asmi extern contract.`,
+        sourceName: boundary.file,
+        line: boundary.line,
+        column: boundary.column,
     }));
 }
-export function unknownCallList(directCalls, knownRoutines) {
-    return unique(directCalls.filter((call) => !knownRoutines.has(call.target)).map((call) => call.target)).sort();
+export function unknownCallList(directBoundaries, knownRoutines) {
+    return unique(directBoundaries
+        .filter((boundary) => !knownRoutines.has(boundary.target))
+        .map((boundary) => boundary.target)).sort();
 }
 export function buildOutputCandidateFixability(routines, outputCandidates, autoFixableCandidateKeys) {
     const autoFixable = autoFixableCandidateKeys([...routines], [...outputCandidates]);

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

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