@jhlagado/azm 0.1.1 → 0.2.1

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

@@ -0,0 +1,9 @@
+import type { RoutineSummary } from './types.js';
+export interface RegisterCareProfileSummary {
+    name: 'mon3';
+    rst: Map<number, RoutineSummary>;
+    rstServices: Map<string, RoutineSummary>;
+}
+export declare function rstTargetName(vector: number): string;
+export declare function rstServiceTargetName(vector: number, service: string): string;
+export declare function getRegisterCareProfile(name: 'mon3' | undefined): RegisterCareProfileSummary | undefined;

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

@@ -0,0 +1,47 @@
+const FLAG_UNITS = ['carry', 'zero', 'sign', 'parity', 'halfCarry'];
+export function rstTargetName(vector) {
+    return `RST_$${vector.toString(16).toUpperCase().padStart(2, '0')}`;
+}
+function normalizeServiceName(raw) {
+    return raw.replace(/[^A-Za-z0-9]/gu, '').toUpperCase();
+}
+export function rstServiceTargetName(vector, service) {
+    return `${rstTargetName(vector)}:${normalizeServiceName(service)}`;
+}
+export function getRegisterCareProfile(name) {
+    if (name !== 'mon3')
+        return undefined;
+    return {
+        name: 'mon3',
+        rst: new Map([
+            [
+                0x10,
+                {
+                    name: rstTargetName(0x10),
+                    mayRead: [],
+                    mayWrite: ['A', ...FLAG_UNITS],
+                    mayOutput: [],
+                    preserved: ['B', 'C', 'D', 'E', 'H', 'L'],
+                    valueRelations: [],
+                    stackBalanced: true,
+                    hasUnknownStackEffect: false,
+                },
+            ],
+        ]),
+        rstServices: new Map([
+            [
+                rstServiceTargetName(0x10, 'API_SCANKEYS'),
+                {
+                    name: rstServiceTargetName(0x10, 'API_SCANKEYS'),
+                    mayRead: ['C'],
+                    mayWrite: ['sign', 'parity', 'halfCarry'],
+                    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.d.ts

@@ -0,0 +1,3 @@
+import type { SourceItem } from '../model/source-item.js';
+import type { RegisterCareProgramModel } from './types.js';
+export declare function buildRegisterCareProgramModel(items: readonly SourceItem[]): RegisterCareProgramModel;

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

@@ -0,0 +1,188 @@
+function isGlobalLabel(name) {
+    return !name.startsWith('.');
+}
+function routineNameFromExpression(expression) {
+    return expression.kind === 'symbol' ? expression.name : undefined;
+}
+function instructionCallTarget(item) {
+    if (item.kind !== 'instruction')
+        return undefined;
+    const mnemonic = item.instruction.mnemonic;
+    if (mnemonic === 'call' || mnemonic === 'call-cc') {
+        return routineNameFromExpression(item.instruction.expression);
+    }
+    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,
+        file: item.span.sourceName,
+        line: item.span.line,
+        column: item.span.column,
+        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 = [];
+    let sourceName;
+    let routineStartLine;
+    let routineStartColumn;
+    let instructions = [];
+    const startRoutine = (item) => {
+        sourceName = item.span.sourceName;
+        routineName = 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 || 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];
+        if (end === undefined)
+            return;
+        routines.push({
+            name: routineName,
+            labels: [...labels],
+            entryLabels: [...entryLabels],
+            instructions: [...instructions],
+            span: {
+                file: sourceName ?? '',
+                start: { line: routineStartLine, column: routineStartColumn ?? 1 },
+                end: { line: end.line, column: end.column },
+            },
+        });
+    };
+    const resetRoutine = () => {
+        routineName = undefined;
+        entryLabels = [];
+        labels = [];
+        sourceName = undefined;
+        routineStartLine = undefined;
+        routineStartColumn = undefined;
+        instructions = [];
+    };
+    const finalizeAndRestart = (item) => {
+        flushRoutine();
+        resetRoutine();
+        startRoutine(item);
+    };
+    for (const item of items) {
+        if (item.kind !== 'label') {
+            if (item.kind !== 'instruction') {
+                continue;
+            }
+            if (routineName === undefined || sourceName === undefined) {
+                continue;
+            }
+            if (item.span.sourceName !== sourceName) {
+                continue;
+            }
+            instructions.push(toInstruction(item, labels));
+            const directTarget = instructionCallTarget(item);
+            if (directTarget !== undefined) {
+                pushDirectBoundary(directCalls, directTarget, `CALL ${directTarget}`, item.span.sourceName, item.span.line, item.span.column);
+            }
+            continue;
+        }
+        if (!isGlobalLabel(item.name)) {
+            if (routineName !== undefined) {
+                labels.push(item.name);
+            }
+            continue;
+        }
+        if (routineName === undefined) {
+            if (filesWithEntryLabels.has(item.span.sourceName) && item.isEntry !== true) {
+                continue;
+            }
+            startRoutine(item);
+            continue;
+        }
+        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);
+        if (item.isEntry === true) {
+            entryLabels.push(item.name);
+        }
+    }
+    flushRoutine();
+    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

@@ -0,0 +1,5 @@
+import type { RegisterCareReportModel, RegisterCareUnit, RoutineSummary } from './types.js';
+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[];

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

@@ -0,0 +1,139 @@
+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}`];
+    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: ${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('');
+        }
+    }
+    lines.push('Conflicts:');
+    if (model.conflicts.length === 0) {
+        lines.push('  none');
+    }
+    else {
+        for (const conflict of model.conflicts) {
+            lines.push(`  ${conflict.file}:${conflict.line}:${conflict.column}: ${conflict.callTarget}: ${list(conflict.carriers)}: ${conflict.message}`);
+        }
+    }
+    lines.push('');
+    lines.push('Output candidates:');
+    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}: ${list(candidate.carriers)}: ${candidate.message}`);
+        }
+    }
+    lines.push('');
+    lines.push('Unknown calls:');
+    if (model.unknownCalls.length === 0) {
+        lines.push('  none');
+    }
+    else {
+        for (const call of model.unknownCalls)
+            lines.push(`  ${call}`);
+    }
+    lines.push('');
+    return `${lines.join('\n')}\n`;
+}
+export function renderRegisterCareInterface(summaries) {
+    const lines = [];
+    for (const summary of summaries) {
+        lines.push(`extern ${summary.name}`);
+        for (const entry of contractEntries(summary)) {
+            lines.push(`${entry.keyword} ${entry.carriers}`);
+        }
+        lines.push('end', '');
+    }
+    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/smartComments.d.ts

@@ -0,0 +1,5 @@
+import type { LocatedSmartComment, RegisterCareRoutine, RoutineContract, SmartComment } from './types.js';
+export declare function parseSmartCommentLine(line: string): SmartComment | undefined;
+export declare function parseSmartComments(sourceLineComments: ReadonlyMap<string, ReadonlyMap<number, string>>): LocatedSmartComment[];
+export declare function buildRoutineContracts(comments: LocatedSmartComment[], routines?: RegisterCareRoutine[], sourceTexts?: ReadonlyMap<string, string>): Map<string, RoutineContract>;
+export declare function parseInterfaceContracts(text: string, file?: string): Map<string, RoutineContract>;