@jhlagado/azm 0.1.0

package/dist/src/registerCare/programModel.js

@@ -0,0 +1,181 @@
+import { createInlineOpInstructionStreamExpander } from '../lowering/opExpansionStream.js';
+function flattenItems(items, out, expandInstruction) {
+    for (const item of items) {
+        if (item.kind === 'AsmLabel') {
+            out.push({ kind: 'label', label: item });
+            continue;
+        }
+        if (item.kind === 'AsmInstruction') {
+            out.push(...expandInstruction(item));
+        }
+    }
+}
+function directCallTarget(inst) {
+    if (inst.head.toLowerCase() !== 'call')
+        return undefined;
+    if (inst.operands.length !== 1 && inst.operands.length !== 2)
+        return undefined;
+    const op = inst.operands[inst.operands.length - 1];
+    if (op?.kind !== 'Imm' || op.expr.kind !== 'ImmName')
+        return undefined;
+    return op.expr.name;
+}
+function directTailJumpTarget(inst, entryNames) {
+    if (inst.head.toLowerCase() !== 'jp')
+        return undefined;
+    if (inst.operands.length !== 1 && inst.operands.length !== 2)
+        return undefined;
+    if (inst.operands.length === 2 && entryNames === undefined)
+        return undefined;
+    const op = inst.operands[inst.operands.length - 1];
+    if (op?.kind !== 'Imm' || op.expr.kind !== 'ImmName')
+        return undefined;
+    if (op.expr.name.startsWith('.'))
+        return undefined;
+    if (entryNames !== undefined && !entryNames.has(op.expr.name))
+        return undefined;
+    return op.expr.name;
+}
+function toInstruction(inst, labels = []) {
+    return {
+        instruction: inst,
+        head: inst.head.toLowerCase(),
+        file: inst.span.file,
+        line: inst.span.start.line,
+        column: inst.span.start.column,
+        labels,
+    };
+}
+function spanFrom(start, end) {
+    if (start.file !== end.file)
+        return start;
+    return {
+        file: start.file,
+        start: start.start,
+        end: end.end,
+    };
+}
+function isLocalLabel(name) {
+    return name.startsWith('.');
+}
+function isEntryLabel(label) {
+    return label.isEntry === true;
+}
+function flatItemFile(item) {
+    return item.kind === 'label' ? item.label.span.file : item.instruction.span.file;
+}
+function isTerminalReturn(inst) {
+    const head = inst.head.toLowerCase();
+    if (head === 'ret')
+        return inst.operands.length === 0;
+    return head === 'retn' || head === 'reti';
+}
+export function buildRegisterCareProgramModel(program) {
+    const flat = [];
+    const { expandInstruction } = createInlineOpInstructionStreamExpander(program);
+    for (const file of program.files) {
+        flattenItems(file.items, flat, expandInstruction);
+    }
+    const labelItems = flat.filter((item) => item.kind === 'label');
+    const filesWithEntryLabels = new Set(labelItems.filter((item) => isEntryLabel(item.label)).map((item) => item.label.span.file));
+    const entryLabelNames = new Set(labelItems
+        .filter((item) => isEntryLabel(item.label) ||
+        (!filesWithEntryLabels.has(item.label.span.file) && !isLocalLabel(item.label.name)))
+        .map((item) => item.label.name));
+    const directCalls = flat.flatMap((item) => {
+        if (item.kind !== 'instruction')
+            return [];
+        const target = directCallTarget(item.instruction);
+        if (target === undefined)
+            return [];
+        return [
+            {
+                target,
+                subject: `CALL ${target}`,
+                file: item.instruction.span.file,
+                line: item.instruction.span.start.line,
+                column: item.instruction.span.start.column,
+            },
+        ];
+    });
+    const directTailJumps = flat.flatMap((item) => {
+        if (item.kind !== 'instruction')
+            return [];
+        const sourceFileUsesEntryLabels = filesWithEntryLabels.has(item.instruction.span.file);
+        const target = directTailJumpTarget(item.instruction, sourceFileUsesEntryLabels ? entryLabelNames : undefined);
+        if (target === undefined)
+            return [];
+        return [
+            {
+                target,
+                subject: `JP ${target}`,
+                file: item.instruction.span.file,
+                line: item.instruction.span.start.line,
+                column: item.instruction.span.start.column,
+            },
+        ];
+    });
+    const directBoundaries = [...directCalls, ...directTailJumps];
+    const directCallTargets = Array.from(new Set(directCalls.map((call) => call.target))).sort();
+    const routines = [];
+    const coalescedGlobalLabelIndexes = new Set();
+    for (let index = 0; index < flat.length; index += 1) {
+        const item = flat[index];
+        if (coalescedGlobalLabelIndexes.has(index))
+            continue;
+        if (item?.kind !== 'label' || isLocalLabel(item.label.name))
+            continue;
+        const routineFile = item.label.span.file;
+        const fileUsesEntryLabels = filesWithEntryLabels.has(routineFile);
+        if (fileUsesEntryLabels && !isEntryLabel(item.label))
+            continue;
+        const labels = [item.label.name];
+        const entryLabels = isEntryLabel(item.label) ? [item.label.name] : undefined;
+        const instructions = [];
+        let pendingInstructionLabels = [item.label.name];
+        let endSpan = item.label.span;
+        for (let rangeIndex = index + 1; rangeIndex < flat.length; rangeIndex += 1) {
+            const rangeItem = flat[rangeIndex];
+            if (!rangeItem)
+                break;
+            if (flatItemFile(rangeItem) !== routineFile)
+                break;
+            if (rangeItem.kind === 'label') {
+                if (fileUsesEntryLabels && isEntryLabel(rangeItem.label)) {
+                    if (instructions.length > 0)
+                        break;
+                    labels.push(rangeItem.label.name);
+                    entryLabels?.push(rangeItem.label.name);
+                    coalescedGlobalLabelIndexes.add(rangeIndex);
+                    endSpan = rangeItem.label.span;
+                    continue;
+                }
+                if (!fileUsesEntryLabels && !isLocalLabel(rangeItem.label.name)) {
+                    if (instructions.length > 0)
+                        break;
+                    labels.push(rangeItem.label.name);
+                    coalescedGlobalLabelIndexes.add(rangeIndex);
+                    endSpan = rangeItem.label.span;
+                    continue;
+                }
+                labels.push(rangeItem.label.name);
+                pendingInstructionLabels.push(rangeItem.label.name);
+                endSpan = rangeItem.label.span;
+                continue;
+            }
+            instructions.push(toInstruction(rangeItem.instruction, pendingInstructionLabels));
+            pendingInstructionLabels = [];
+            endSpan = rangeItem.instruction.span;
+            if (isTerminalReturn(rangeItem.instruction))
+                break;
+        }
+        routines.push({
+            name: item.label.name,
+            span: spanFrom(item.label.span, endSpan),
+            labels,
+            ...(entryLabels ? { entryLabels } : {}),
+            instructions,
+        });
+    }
+    return { routines, directCallTargets, directCalls, directBoundaries };
+}

package/dist/src/registerCare/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/registerCare/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/registerCare/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: Map<string, Map<number, string>>): LocatedSmartComment[];
+export declare function buildRoutineContracts(comments: LocatedSmartComment[], routines?: RegisterCareRoutine[], sourceTexts?: Map<string, string>): Map<string, RoutineContract>;
+export declare function parseInterfaceContracts(text: string, file?: string): Map<string, RoutineContract>;

package/dist/src/registerCare/smartComments.js

@@ -0,0 +1,247 @@
+import { expandCarrierList } from './carriers.js';
+const COMPACT_SOURCE_TAG_RE = /^;?\s*!\s*(in|out|clobbers|preserves)(?:\s+(.+))?$/i;
+const COMPACT_SOURCE_LINE_RE = /^\s*;\s*!\s*(?:in|out|maybe-out|clobbers|preserves)(?:\s|$)/i;
+const INTERFACE_TAG_RE = /^\s*(in|out|clobbers|preserves)(?:\s+(.+))?$/i;
+const CARRIER_RE = /^\{([^}]+)\}(?:\s+(.+))?$/;
+function parseCarrierPayload(rest) {
+    if (!rest)
+        return undefined;
+    const match = CARRIER_RE.exec(rest.trim());
+    if (match) {
+        const carriers = match[1]
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+        const name = match[2]?.trim();
+        return { carriers, ...(name ? { name } : {}) };
+    }
+    const tokens = rest.trim().split(/\s+/);
+    const carriers = [];
+    let consumed = 0;
+    for (const token of tokens) {
+        const cleaned = token.replace(/[.:;]+$/u, '');
+        const parts = cleaned
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+        if (parts.length === 0 || !expandCarrierList(parts))
+            break;
+        carriers.push(...parts);
+        consumed += 1;
+    }
+    if (carriers.length === 0)
+        return undefined;
+    const name = tokens.slice(consumed).join(' ').trim();
+    return { carriers, ...(name ? { name } : {}) };
+}
+export function parseSmartCommentLine(line) {
+    const trimmed = line.trim();
+    const expectOut = /^;?\s*expects\s+out\s+(.+)$/i.exec(trimmed);
+    if (expectOut) {
+        const payload = parseCarrierPayload(expectOut[1]?.trim());
+        if (!payload)
+            return undefined;
+        const carriers = expandCarrierList(payload.carriers);
+        if (!carriers || carriers.length === 0)
+            return undefined;
+        return { kind: 'expectOut', carriers, ...(payload.name ? { name: payload.name } : {}) };
+    }
+    const match = COMPACT_SOURCE_TAG_RE.exec(trimmed);
+    if (!match)
+        return undefined;
+    const tag = match[1].toLowerCase();
+    const rest = match[2]?.trim();
+    const payload = parseCarrierPayload(rest);
+    if (!payload)
+        return undefined;
+    const carriers = expandCarrierList(payload.carriers);
+    if (!carriers || carriers.length === 0)
+        return undefined;
+    if (tag === 'in')
+        return { kind: 'in', carriers, ...(payload.name ? { name: payload.name } : {}) };
+    if (tag === 'out')
+        return { kind: 'out', carriers, ...(payload.name ? { name: payload.name } : {}) };
+    if (tag === 'clobbers')
+        return { kind: 'clobbers', carriers };
+    if (tag === 'preserves')
+        return { kind: 'preserves', carriers };
+    return undefined;
+}
+function parseInterfaceContractLine(line) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0 || trimmed.startsWith(';'))
+        return undefined;
+    const extern = /^extern\s+(\S+)\s*$/i.exec(trimmed);
+    if (extern)
+        return { kind: 'extern', name: extern[1] };
+    if (/^end\s*$/i.test(trimmed))
+        return { kind: 'end' };
+    const match = INTERFACE_TAG_RE.exec(trimmed);
+    if (!match)
+        return undefined;
+    const tag = match[1].toLowerCase();
+    const rest = match[2]?.trim();
+    if (!rest)
+        return undefined;
+    const rawCarriers = rest.split(',').map((part) => part.trim());
+    if (rawCarriers.length === 0 || rawCarriers.some((part) => part.length === 0)) {
+        return undefined;
+    }
+    const carriers = expandCarrierList(rawCarriers);
+    if (!carriers || carriers.length === 0)
+        return undefined;
+    if (tag === 'in')
+        return { kind: 'in', carriers };
+    if (tag === 'out')
+        return { kind: 'out', carriers };
+    if (tag === 'clobbers')
+        return { kind: 'clobbers', carriers };
+    if (tag === 'preserves')
+        return { kind: 'preserves', carriers };
+    return undefined;
+}
+function isCompactSourceContractLine(line) {
+    return COMPACT_SOURCE_LINE_RE.test(line);
+}
+export function parseSmartComments(sourceLineComments) {
+    const out = [];
+    for (const [file, comments] of sourceLineComments) {
+        for (const [line, text] of comments) {
+            const parsed = parseSmartCommentLine(`;${text}`);
+            if (parsed)
+                out.push({ file, line, comment: parsed });
+        }
+    }
+    return out.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+}
+function appendUnique(out, items) {
+    for (const item of items) {
+        if (!out.includes(item))
+            out.push(item);
+    }
+}
+function applyContractComment(contract, comment) {
+    if (comment.kind === 'in')
+        appendUnique(contract.in, comment.carriers);
+    if (comment.kind === 'out')
+        appendUnique(contract.out, comment.carriers);
+    if (comment.kind === 'clobbers')
+        appendUnique(contract.clobbers, comment.carriers);
+    if (comment.kind === 'preserves')
+        appendUnique(contract.preserves, comment.carriers);
+}
+function hasContractContent(contract) {
+    return (contract.in.length > 0 ||
+        contract.out.length > 0 ||
+        contract.clobbers.length > 0 ||
+        contract.preserves.length > 0);
+}
+function isCommentOnlyLine(line) {
+    return /^\s*;/.test(line);
+}
+function collectPrecedingCommentBlock(routine, sourceTexts) {
+    const source = sourceTexts.get(routine.span.file);
+    if (!source)
+        return { comments: [], complete: false };
+    const lines = source.split(/\r?\n/);
+    const rawBlock = [];
+    for (let index = routine.span.start.line - 2; index >= 0; index -= 1) {
+        const raw = lines[index] ?? '';
+        if (!isCommentOnlyLine(raw))
+            break;
+        rawBlock.push({ line: index + 1, text: raw });
+    }
+    rawBlock.reverse();
+    let compactStart = rawBlock.length;
+    while (compactStart > 0 && isCompactSourceContractLine(rawBlock[compactStart - 1]?.text ?? '')) {
+        compactStart -= 1;
+    }
+    if (compactStart < rawBlock.length) {
+        return {
+            complete: true,
+            comments: rawBlock.slice(compactStart).flatMap((item) => {
+                const parsed = parseSmartCommentLine(item.text);
+                return parsed ? [{ file: routine.span.file, line: item.line, comment: parsed }] : [];
+            }),
+        };
+    }
+    return {
+        complete: false,
+        comments: rawBlock.flatMap((item) => {
+            const parsed = parseSmartCommentLine(item.text);
+            return parsed ? [{ file: routine.span.file, line: item.line, comment: parsed }] : [];
+        }),
+    };
+}
+function buildImplicitRoutineContracts(routines, sourceTexts) {
+    const contracts = new Map();
+    for (const routine of routines) {
+        const docBlock = collectPrecedingCommentBlock(routine, sourceTexts);
+        if (docBlock.comments.some((item) => item.comment.kind === 'extern' || item.comment.kind === 'end')) {
+            continue;
+        }
+        const contract = {
+            name: routine.name,
+            in: [],
+            out: [],
+            clobbers: [],
+            preserves: [],
+            ...(docBlock.complete ? { complete: true } : {}),
+        };
+        for (const item of docBlock.comments) {
+            applyContractComment(contract, item.comment);
+        }
+        if (hasContractContent(contract))
+            contracts.set(routine.name, contract);
+    }
+    return contracts;
+}
+export function buildRoutineContracts(comments, routines = [], sourceTexts = new Map()) {
+    const contracts = new Map();
+    let current;
+    for (const item of comments) {
+        const comment = item.comment;
+        if (comment.kind === 'extern') {
+            current = {
+                name: comment.name,
+                in: [],
+                out: [],
+                clobbers: [],
+                preserves: [],
+                complete: true,
+            };
+            contracts.set(comment.name, current);
+            continue;
+        }
+        if (comment.kind === 'end') {
+            current = undefined;
+            continue;
+        }
+        if (!current)
+            continue;
+        applyContractComment(current, comment);
+    }
+    for (const [name, contract] of buildImplicitRoutineContracts(routines, sourceTexts)) {
+        if (!contracts.has(name))
+            contracts.set(name, contract);
+    }
+    return contracts;
+}
+export function parseInterfaceContracts(text, file = '<register-care-interface>') {
+    const comments = [];
+    const lines = text.split(/\r?\n/);
+    lines.forEach((line, index) => {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            return;
+        if (trimmed.startsWith(';')) {
+            throw new Error(`${file}:${index + 1}: .asmi files do not permit comments`);
+        }
+        const comment = parseInterfaceContractLine(line);
+        if (!comment) {
+            throw new Error(`${file}:${index + 1}: invalid register-care interface line "${trimmed}"`);
+        }
+        comments.push({ file, line: index + 1, comment });
+    });
+    return buildRoutineContracts(comments);
+}

package/dist/src/registerCare/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/registerCare/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/registerCare/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;