@jhlagado/azm 0.1.0

package/dist/src/lowering/traceFormat.js

@@ -0,0 +1,211 @@
+const toHexByte = (n) => `$${(n & 0xff).toString(16).toUpperCase().padStart(2, '0')}`;
+const toHexWord = (n) => `$${(n & 0xffff).toString(16).toUpperCase().padStart(4, '0')}`;
+export const formatImmExprForAsm = (expr) => {
+    switch (expr.kind) {
+        case 'ImmLiteral':
+            return toHexWord(expr.value);
+        case 'ImmName':
+            return expr.name;
+        case 'ImmSizeof':
+            return 'sizeof(...)';
+        case 'ImmOffset':
+            return 'offset(...)';
+        case 'ImmUnary':
+            return `${expr.op}${formatImmExprForAsm(expr.expr)}`;
+        case 'ImmBinary':
+            return `${formatImmExprForAsm(expr.left)} ${expr.op} ${formatImmExprForAsm(expr.right)}`;
+        default:
+            return 'imm';
+    }
+};
+export const formatEaExpr = (ea, { formatImmExpr, wrapImmEa = false }) => {
+    switch (ea.kind) {
+        case 'EaName':
+            return ea.name;
+        case 'EaImm':
+            return wrapImmEa ? `(${formatImmExpr(ea.expr)})` : formatImmExpr(ea.expr);
+        case 'EaField':
+            return `${formatEaExpr(ea.base, { formatImmExpr, wrapImmEa })}.${ea.field}`;
+        case 'EaAdd':
+            return `${formatEaExpr(ea.base, { formatImmExpr, wrapImmEa })} + ${formatImmExpr(ea.offset)}`;
+        case 'EaSub':
+            return `${formatEaExpr(ea.base, { formatImmExpr, wrapImmEa })} - ${formatImmExpr(ea.offset)}`;
+        case 'EaIndex': {
+            let idx = '';
+            switch (ea.index.kind) {
+                case 'IndexImm':
+                    idx = formatImmExpr(ea.index.value);
+                    break;
+                case 'IndexReg8':
+                case 'IndexReg16':
+                    idx = ea.index.reg;
+                    break;
+                case 'IndexMemHL':
+                    idx = '(HL)';
+                    break;
+                case 'IndexMemIxIy':
+                    idx = ea.index.disp
+                        ? `${ea.index.base}${ea.index.disp.kind === 'ImmUnary' ? '' : '+'}${formatImmExpr(ea.index.disp)}`
+                        : ea.index.base;
+                    break;
+                case 'IndexEa':
+                    idx = formatEaExpr(ea.index.expr, { formatImmExpr, wrapImmEa });
+                    break;
+            }
+            return `${formatEaExpr(ea.base, { formatImmExpr, wrapImmEa })}[${idx}]`;
+        }
+        default:
+            return 'ea';
+    }
+};
+const formatEaExprForAsm = (ea) => formatEaExpr(ea, { formatImmExpr: formatImmExprForAsm });
+const formatAsmOperandForTrace = (operand) => {
+    switch (operand.kind) {
+        case 'Reg':
+            return operand.name;
+        case 'Imm':
+            return formatImmExprForAsm(operand.expr);
+        case 'Ea':
+            return formatEaExprForAsm(operand.expr);
+        case 'Mem':
+            return `(${formatEaExprForAsm(operand.expr)})`;
+        case 'PortC':
+            return '(C)';
+        case 'PortImm8':
+            return `(${formatImmExprForAsm(operand.expr)})`;
+        default:
+            return '?';
+    }
+};
+export const formatAsmInstrForTrace = (head, operands) => {
+    const lowerHead = head.toLowerCase();
+    if (operands.length === 0)
+        return lowerHead;
+    return `${lowerHead} ${operands.map(formatAsmOperandForTrace).join(', ')}`;
+};
+const formatFixupSymbolExpr = (baseLower, addend) => {
+    if (addend === 0)
+        return baseLower;
+    if (addend > 0)
+        return `${baseLower} + ${addend}`;
+    return `${baseLower} - ${Math.abs(addend)}`;
+};
+const jpCondFromOpcode = (opcode) => {
+    switch (opcode & 0xff) {
+        case 0xc2:
+            return 'NZ';
+        case 0xca:
+            return 'Z';
+        case 0xd2:
+            return 'NC';
+        case 0xda:
+            return 'C';
+        case 0xe2:
+            return 'PO';
+        case 0xea:
+            return 'PE';
+        case 0xf2:
+            return 'P';
+        case 0xfa:
+            return 'M';
+        default:
+            return undefined;
+    }
+};
+const callCondFromOpcode = (opcode) => {
+    switch (opcode & 0xff) {
+        case 0xc4:
+            return 'NZ';
+        case 0xcc:
+            return 'Z';
+        case 0xd4:
+            return 'NC';
+        case 0xdc:
+            return 'C';
+        case 0xe4:
+            return 'PO';
+        case 0xec:
+            return 'PE';
+        case 0xf4:
+            return 'P';
+        case 0xfc:
+            return 'M';
+        default:
+            return undefined;
+    }
+};
+export const formatAbs16FixupAsm = (opcode, baseLower, addend) => {
+    const sym = formatFixupSymbolExpr(baseLower, addend);
+    switch (opcode & 0xff) {
+        case 0x01:
+            return `ld BC, ${sym}`;
+        case 0x11:
+            return `ld DE, ${sym}`;
+        case 0x21:
+            return `ld HL, ${sym}`;
+        case 0x31:
+            return `ld SP, ${sym}`;
+        case 0x2a:
+            return `ld HL, (${sym})`;
+        case 0x3a:
+            return `ld A, (${sym})`;
+        case 0x22:
+            return `ld (${sym}), HL`;
+        case 0x32:
+            return `ld (${sym}), A`;
+        case 0xc3:
+            return `jp ${sym}`;
+        case 0xcd:
+            return `call ${sym}`;
+        default: {
+            const jpCc = jpCondFromOpcode(opcode);
+            if (jpCc)
+                return `jp ${jpCc}, ${sym}`;
+            const callCc = callCondFromOpcode(opcode);
+            if (callCc)
+                return `call ${callCc}, ${sym}`;
+            return `db ${toHexByte(opcode)}, lo(${baseLower}), hi(${baseLower})`;
+        }
+    }
+};
+export const formatAbs16FixupEdAsm = (opcode2, baseLower, addend) => {
+    const sym = formatFixupSymbolExpr(baseLower, addend);
+    switch (opcode2 & 0xff) {
+        case 0x4b:
+            return `ld BC, (${sym})`;
+        case 0x5b:
+            return `ld DE, (${sym})`;
+        case 0x7b:
+            return `ld SP, (${sym})`;
+        case 0x43:
+            return `ld (${sym}), BC`;
+        case 0x53:
+            return `ld (${sym}), DE`;
+        case 0x73:
+            return `ld (${sym}), SP`;
+        default:
+            return `db $ED, ${toHexByte(opcode2)}, lo(${baseLower}), hi(${baseLower})`;
+    }
+};
+export const formatAbs16FixupPrefixedAsm = (prefix, opcode2, baseLower, addend) => {
+    const sym = formatFixupSymbolExpr(baseLower, addend);
+    const reg16 = prefix === 0xdd ? 'IX' : prefix === 0xfd ? 'IY' : undefined;
+    if (!reg16) {
+        return `db ${toHexByte(prefix)}, ${toHexByte(opcode2)}, lo(${baseLower}), hi(${baseLower})`;
+    }
+    switch (opcode2 & 0xff) {
+        case 0x21:
+            return `ld ${reg16}, ${sym}`;
+        case 0x2a:
+            return `ld ${reg16}, (${sym})`;
+        case 0x22:
+            return `ld (${sym}), ${reg16}`;
+        default:
+            return `db ${toHexByte(prefix)}, ${toHexByte(opcode2)}, lo(${baseLower}), hi(${baseLower})`;
+    }
+};
+export const formatIxDisp = (disp) => {
+    const hex = Math.abs(disp).toString(16).padStart(2, '0');
+    const sign = disp >= 0 ? '+' : '-';
+    return `${sign}$${hex}`;
+};

package/dist/src/pathCompare.d.ts

@@ -0,0 +1,3 @@
+export declare function normalizePathForCompare(path: string, options?: {
+    realpath?: boolean;
+}): string;

package/dist/src/pathCompare.js

@@ -0,0 +1,26 @@
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+function stripExtendedWindowsPrefix(path) {
+    if (path.startsWith('\\\\?\\UNC\\'))
+        return `\\\\${path.slice(8)}`;
+    if (path.startsWith('\\\\?\\'))
+        return path.slice(4);
+    return path;
+}
+export function normalizePathForCompare(path, options = {}) {
+    const resolved = options.realpath ? resolve(path) : path;
+    const canonical = (() => {
+        if (!options.realpath)
+            return resolved;
+        try {
+            return realpathSync.native(resolved);
+        }
+        catch {
+            return resolved;
+        }
+    })();
+    const stripped = stripExtendedWindowsPrefix(canonical);
+    const normalized = stripped.replace(/\\/g, '/');
+    const normalizedDarwin = process.platform === 'darwin' ? normalized.replace(/^\/private\//, '/') : normalized;
+    return process.platform === 'win32' ? normalizedDarwin.toLowerCase() : normalizedDarwin;
+}

package/dist/src/pipeline.d.ts

@@ -0,0 +1,78 @@
+import type { Diagnostic } from './diagnosticTypes.js';
+import type { Artifact, FormatWriters } from './formats/types.js';
+import type { RegisterCareMode } from './registerCare/types.js';
+export type CaseStyleMode = 'off' | 'upper' | 'lower' | 'consistent';
+/**
+ * Options that influence compilation behavior and which artifacts are produced.
+ *
+ * PR1 implementation note: most options are accepted but only a subset is currently honored.
+ */
+export interface CompilerOptions {
+    /**
+     * Additional include/search directories used for textual includes and input assets.
+     *
+     * These directories are consulted after checking paths relative to the
+     * importing source file.
+     */
+    includeDirs?: string[];
+    /** Primary output path used to derive sibling artifacts (future). */
+    outputPath?: string;
+    /** Primary output type (future). */
+    outputType?: 'hex' | 'bin';
+    /** Emit flat binary (`.bin`). */
+    emitBin?: boolean;
+    /** Emit Intel HEX (`.hex`). */
+    emitHex?: boolean;
+    /** Emit D8 Debug Map (`.d8.json`). */
+    emitD8m?: boolean;
+    /** Emit listing (`.lst`). */
+    emitListing?: boolean;
+    /** Emit ASM80-compatible lowered source (`.asm`). */
+    emitAsm80?: boolean;
+    /** Optional case-style lint mode for asm keywords/register tokens. */
+    caseStyle?: CaseStyleMode;
+    /** Require a `main` entry label for runnable builds. */
+    requireMain?: boolean;
+    /** Default code base address. */
+    defaultCodeBase?: number;
+    /** JSON directive alias files. Later files extend or override earlier aliases. */
+    directiveAliasFiles?: string[];
+    /** Register-care analysis mode. */
+    registerCare?: RegisterCareMode;
+    /** Emit a register-care audit report artifact. */
+    emitRegisterReport?: boolean;
+    /** Emit an inferred register-care interface artifact. */
+    emitRegisterInterface?: boolean;
+    /** Rewrite source files with inferred register-care contract blocks. */
+    emitRegisterAnnotations?: boolean;
+    /** Apply conservative register-care source fixes. Implies source annotations. */
+    fixRegisterContracts?: boolean;
+    /**
+     * Promote selected caller-use output candidates while rewriting register-care
+     * source annotations. Entries use `ROUTINE:carriers`, for example `MxMask:A`.
+     */
+    acceptRegisterOutputCandidates?: string[];
+    /** Register-care analysis profile. */
+    registerCareProfile?: 'mon3';
+    /** Register-care contract files that provide contracts for external/library routines. */
+    registerCareInterfaces?: string[];
+}
+/**
+ * Result of a compilation run: diagnostics plus any produced artifacts.
+ */
+export interface CompileResult {
+    diagnostics: Diagnostic[];
+    artifacts: Artifact[];
+}
+/**
+ * Dependency injection surface for the compiler pipeline.
+ *
+ * Callers provide concrete format writers so the core pipeline can be pure/in-memory.
+ */
+export interface PipelineDeps {
+    formats: FormatWriters;
+}
+/**
+ * Top-level compile function signature used by the pipeline contract.
+ */
+export type CompileFn = (entryFile: string, options: CompilerOptions, deps: PipelineDeps) => Promise<CompileResult>;

package/dist/src/pipeline.js

@@ -0,0 +1 @@
+export {};

package/dist/src/registerCare/analyze.d.ts

@@ -0,0 +1,24 @@
+import { type Diagnostic } from '../diagnosticTypes.js';
+import type { LoadedProgram } from '../sourceLoader.js';
+import { type RegisterCareAnnotatedFile } from './annotate.js';
+import { type RegisterCareProfileName } from './profiles.js';
+import type { RegisterCareMode, RegisterCareReportModel, RoutineContract } from './types.js';
+export interface AnalyzeRegisterCareOptions {
+    mode: RegisterCareMode;
+    emitReport: boolean;
+    emitInterface: boolean;
+    emitAnnotations?: boolean;
+    fixRegisterContracts?: boolean;
+    acceptOutputCandidates?: string[];
+    profile?: RegisterCareProfileName;
+    interfaceContracts?: RoutineContract[];
+}
+interface AnalyzeRegisterCareResult {
+    diagnostics: Diagnostic[];
+    outputCandidates?: RegisterCareReportModel['outputCandidates'];
+    reportText?: string;
+    interfaceText?: string;
+    annotatedFiles?: RegisterCareAnnotatedFile[];
+}
+export declare function analyzeRegisterCare(loaded: LoadedProgram, options: AnalyzeRegisterCareOptions): AnalyzeRegisterCareResult;
+export {};

package/dist/src/registerCare/analyze.js

@@ -0,0 +1,327 @@
+import { DiagnosticIds } from '../diagnosticTypes.js';
+import { annotateRegisterCareContracts } from './annotate.js';
+import { expandCarrierList } from './carriers.js';
+import { diagnosticsForRegisterCareConflicts, findAcceptedOutputCandidatesFromHints, findCallerOutputCandidates, findCallerOutputCandidateObservations, findRegisterCareConflicts, } from './liveness.js';
+import { applyExpectOutFixesToSource, findExpectOutFixes } from './fix.js';
+import { getRegisterCareProfile } from './profiles.js';
+import { buildRegisterCareProgramModel } from './programModel.js';
+import { renderRegisterCareInterface, renderRegisterCareReport } from './report.js';
+import { buildRoutineContracts, parseSmartComments } from './smartComments.js';
+import { applyRoutineContract, inferRoutineSummary } from './summary.js';
+function emptyRoutineSummary(name) {
+    return {
+        name,
+        mayRead: [],
+        mayWrite: [],
+        preserved: [],
+        valueRelations: [],
+        stackBalanced: true,
+        hasUnknownStackEffect: false,
+    };
+}
+function unknownBoundaryForCall(call) {
+    return {
+        ...call,
+        message: `Register-care cannot prove ${call.subject}; add a routine body or .asmi extern contract.`,
+    };
+}
+function uniqueSortedTargets(boundaries) {
+    return Array.from(new Set(boundaries.map((boundary) => boundary.target))).sort();
+}
+function diagnosticsForUnknownBoundaries(boundaries) {
+    return boundaries.map((boundary) => ({
+        id: DiagnosticIds.RegisterCareUnknownBoundary,
+        severity: 'warning',
+        message: boundary.message,
+        file: boundary.file,
+        line: boundary.line,
+        column: boundary.column,
+    }));
+}
+function isLocalLabel(name) {
+    return name.startsWith('.');
+}
+function nonLocalLabels(labels) {
+    return labels.filter((label) => !isLocalLabel(label));
+}
+function boundaryLabels(routine) {
+    return routine.entryLabels ?? nonLocalLabels(routine.labels);
+}
+function contractForRoutine(routine, contracts) {
+    return boundaryLabels(routine)
+        .map((label) => contracts.get(label))
+        .find((contract) => contract !== undefined);
+}
+function summariesWithExternalContracts(summaries, contracts, routineNames) {
+    const out = [...summaries];
+    for (const contract of contracts.values()) {
+        if (!routineNames.has(contract.name)) {
+            out.push(applyRoutineContract(emptyRoutineSummary(contract.name), contract));
+        }
+    }
+    return out;
+}
+function externalContractsOnly(contracts, routineNames) {
+    return new Map([...contracts].filter(([name]) => !routineNames.has(name)));
+}
+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 appendUniqueUnits(target, units) {
+    for (const unit of units) {
+        if (!target.includes(unit))
+            target.push(unit);
+    }
+}
+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');
+}
+function inferRoutineSummariesToFixedPoint(routines, contracts, routineNames, 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, routineNames);
+        const boundarySummaryMap = buildBoundarySummaryMap(summaries, routineSummaries, profileSummaries);
+        const nextRoutineSummaries = summarizeRoutines(routines, contracts, boundarySummaryMap);
+        if (routineSummariesFingerprint(nextRoutineSummaries) ===
+            routineSummariesFingerprint(routineSummaries)) {
+            return nextRoutineSummaries;
+        }
+        routineSummaries = nextRoutineSummaries;
+    }
+    return routineSummaries;
+}
+function withCallerOutputCandidates(routineSummaries, boundarySummaryMap, acceptOutputCandidates = new Map()) {
+    const candidates = findCallerOutputCandidates(routineSummaries.map((item) => item.routine), new Map(boundarySummaryMap));
+    return routineSummaries.map((item) => {
+        const outputCandidates = candidates.get(item.summary.name);
+        const written = new Set(item.summary.mayWrite);
+        const accepted = (acceptOutputCandidates.get(item.summary.name) ?? []).filter((unit) => written.has(unit));
+        const acceptedSet = new Set(accepted);
+        const valueRelations = [...item.summary.valueRelations];
+        for (const unit of accepted) {
+            if (!valueRelations.some((relation) => relation.out.includes(unit))) {
+                valueRelations.push({ out: [unit], from: [] });
+            }
+        }
+        const remainingCandidates = outputCandidates?.filter((unit) => !acceptedSet.has(unit));
+        return outputCandidates && outputCandidates.length > 0
+            ? {
+                ...item,
+                summary: {
+                    ...item.summary,
+                    valueRelations,
+                    ...(remainingCandidates && remainingCandidates.length > 0
+                        ? { outputCandidates: remainingCandidates }
+                        : {}),
+                },
+            }
+            : item;
+    });
+}
+function autoAcceptedOutputCandidates(fixes) {
+    const out = new Map();
+    for (const fix of fixes) {
+        const existing = out.get(fix.routine) ?? [];
+        appendUniqueUnits(existing, fix.carriers);
+        out.set(fix.routine, existing);
+    }
+    return out;
+}
+function parseAcceptedOutputCandidates(items = []) {
+    const out = new Map();
+    for (const item of items) {
+        const sep = item.indexOf(':');
+        if (sep <= 0 || sep === item.length - 1) {
+            throw new Error(`Invalid --accept-out value "${item}" (expected ROUTINE:carriers)`);
+        }
+        const name = item.slice(0, sep).trim();
+        if (!name)
+            throw new Error(`Invalid --accept-out value "${item}" (missing routine name)`);
+        const carrierParts = item.slice(sep + 1).split(',');
+        const rawCarriers = carrierParts.map((part) => part.trim());
+        if (rawCarriers.length === 0 || rawCarriers.some((part) => part.length === 0)) {
+            throw new Error(`Invalid --accept-out value "${item}" (missing carriers)`);
+        }
+        const carriers = expandCarrierList(rawCarriers);
+        if (!carriers) {
+            throw new Error(`Invalid --accept-out value "${item}" (unknown carrier)`);
+        }
+        const existing = out.get(name) ?? [];
+        appendUniqueUnits(existing, carriers);
+        out.set(name, existing);
+    }
+    return out;
+}
+function mergeAcceptedOutputCandidates(...maps) {
+    const out = new Map();
+    for (const map of maps) {
+        for (const [name, units] of map) {
+            const existing = out.get(name) ?? [];
+            appendUniqueUnits(existing, units);
+            out.set(name, existing);
+        }
+    }
+    return out;
+}
+function fixedSourceTexts(referenceSourceTexts, workingSourceTexts, fixes) {
+    const byFile = new Map();
+    for (const fix of fixes) {
+        const items = byFile.get(fix.file) ?? [];
+        items.push(fix);
+        byFile.set(fix.file, items);
+    }
+    const out = new Map(workingSourceTexts);
+    for (const [file, items] of byFile) {
+        const source = workingSourceTexts.get(file);
+        const referenceSource = referenceSourceTexts.get(file);
+        if (source === undefined)
+            continue;
+        out.set(file, applyExpectOutFixesToSource(source, items, referenceSource));
+    }
+    return out;
+}
+function annotateAndFixRegisterCareContracts(sourceTexts, routines, fixes) {
+    const annotated = annotateRegisterCareContracts(sourceTexts, routines);
+    if (fixes.length === 0)
+        return annotated;
+    const workingTexts = new Map(sourceTexts);
+    for (const file of annotated) {
+        workingTexts.set(file.path, file.text);
+    }
+    const fixedTexts = fixedSourceTexts(sourceTexts, workingTexts, fixes);
+    const out = [];
+    for (const [path, text] of fixedTexts) {
+        if (text !== sourceTexts.get(path))
+            out.push({ path, text });
+    }
+    return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+function candidateKey(item) {
+    return `${item.file}:${item.line}:${item.column}:${item.routine}`;
+}
+function candidateExpectation(units) {
+    const carriers = units.join(',');
+    return units.length === 1 ? units[0] : `{${carriers}}`;
+}
+function candidateMessageWithFixability(candidate, autoFixable) {
+    const carriers = candidate.carriers.join(',');
+    const expectation = candidateExpectation(candidate.carriers);
+    const base = `CALL ${candidate.routine} writes ${carriers} and caller reads it later`;
+    return autoFixable
+        ? `${base}; generated contracts promote this to \`out ${expectation}\` automatically.`
+        : `${base}; manual review required before adding \`; expects out ${expectation}\` because the later read is not a simple direct continuation.`;
+}
+function withCandidateFixability(candidates, fixes) {
+    const fixable = new Map(fixes.map((fix) => [candidateKey(fix), new Set(fix.carriers)]));
+    return candidates.map((candidate) => {
+        const fixableCarriers = fixable.get(candidateKey(candidate));
+        const autoFixable = fixableCarriers !== undefined &&
+            candidate.carriers.every((carrier) => fixableCarriers.has(carrier));
+        return {
+            ...candidate,
+            autoFixable,
+            message: candidateMessageWithFixability(candidate, autoFixable),
+        };
+    });
+}
+function inferenceOnlyOutputFixes(programRoutines, routineSummaries, profileSummaries) {
+    const summaries = routineSummaries.map((item) => item.summary);
+    const boundarySummaryMap = buildBoundarySummaryMap(summaries, routineSummaries, profileSummaries);
+    const candidates = findCallerOutputCandidateObservations(programRoutines, boundarySummaryMap);
+    return findExpectOutFixes(programRoutines, candidates);
+}
+export function analyzeRegisterCare(loaded, options) {
+    const profile = getRegisterCareProfile(options.profile);
+    const programModel = buildRegisterCareProgramModel(loaded.program);
+    const smartComments = parseSmartComments(loaded.sourceLineComments);
+    const contracts = buildRoutineContracts(smartComments, programModel.routines, loaded.sourceTexts);
+    const cliAcceptedOutputCandidates = parseAcceptedOutputCandidates(options.acceptOutputCandidates);
+    for (const contract of options.interfaceContracts ?? []) {
+        contracts.set(contract.name, contract);
+    }
+    const routineNames = new Set(programModel.routines.flatMap((routine) => boundaryLabels(routine)));
+    const profileSummaries = profile
+        ? [...Array.from(profile.rst.values()), ...Array.from(profile.rstServices.values())]
+        : [];
+    const routineSummaries = inferRoutineSummariesToFixedPoint(programModel.routines, contracts, routineNames, profileSummaries);
+    const summaries = routineSummaries.map((item) => item.summary);
+    summaries.push(...summariesWithExternalContracts([], contracts, routineNames));
+    const boundarySummaryMap = buildBoundarySummaryMap(summaries, routineSummaries, profileSummaries);
+    const unknownBoundaries = programModel.directBoundaries
+        .filter((boundary) => !boundarySummaryMap.has(boundary.target))
+        .map(unknownBoundaryForCall);
+    const conflicts = programModel.routines.flatMap((routine) => findRegisterCareConflicts(routine, boundarySummaryMap, smartComments));
+    const rawOutputCandidates = findCallerOutputCandidateObservations(programModel.routines, boundarySummaryMap);
+    const possibleExpectOutFixes = findExpectOutFixes(programModel.routines, rawOutputCandidates);
+    const outputCandidates = withCandidateFixability(rawOutputCandidates, possibleExpectOutFixes);
+    const conflictDiagnostics = options.mode === 'warn' || options.mode === 'strict'
+        ? diagnosticsForRegisterCareConflicts(conflicts, 'warning')
+        : options.mode === 'error'
+            ? diagnosticsForRegisterCareConflicts(conflicts, 'error')
+            : [];
+    const diagnostics = options.mode === 'strict'
+        ? [...conflictDiagnostics, ...diagnosticsForUnknownBoundaries(unknownBoundaries)]
+        : conflictDiagnostics;
+    const reportModel = {
+        entryFile: loaded.program.entryFile,
+        mode: options.mode,
+        ...(profile ? { profile: profile.name } : {}),
+        summaries,
+        conflicts,
+        outputCandidates,
+        unknownCalls: uniqueSortedTargets(unknownBoundaries),
+    };
+    return {
+        diagnostics,
+        outputCandidates,
+        ...(options.emitReport ? { reportText: renderRegisterCareReport(reportModel) } : {}),
+        ...(options.emitInterface ? { interfaceText: renderRegisterCareInterface(summaries) } : {}),
+        ...(options.emitAnnotations
+            ? (() => {
+                const annotationRoutineSummaries = inferRoutineSummariesToFixedPoint(programModel.routines, externalContractsOnly(contracts, routineNames), routineNames, profileSummaries);
+                const annotationSummaries = annotationRoutineSummaries.map((item) => item.summary);
+                const annotationBoundarySummaryMap = buildBoundarySummaryMap(annotationSummaries, annotationRoutineSummaries, profileSummaries);
+                const expectOutFixes = options.fixRegisterContracts === true
+                    ? inferenceOnlyOutputFixes(programModel.routines, annotationRoutineSummaries, profileSummaries)
+                    : [];
+                return {
+                    annotatedFiles: annotateAndFixRegisterCareContracts(loaded.sourceTexts, withCallerOutputCandidates(annotationRoutineSummaries, annotationBoundarySummaryMap, mergeAcceptedOutputCandidates(cliAcceptedOutputCandidates, findAcceptedOutputCandidatesFromHints(programModel.routines, annotationBoundarySummaryMap, smartComments), autoAcceptedOutputCandidates(expectOutFixes))), []),
+                };
+            })()
+            : {}),
+    };
+}

package/dist/src/registerCare/annotate.d.ts

@@ -0,0 +1,11 @@
+import type { RegisterCareRoutine, RoutineSummary } from './types.js';
+export interface RegisterCareAnnotatedFile {
+    path: string;
+    text: string;
+}
+interface RegisterCareAnnotationInput {
+    routine: RegisterCareRoutine;
+    summary: RoutineSummary;
+}
+export declare function annotateRegisterCareContracts(sourceTexts: ReadonlyMap<string, string>, routines: RegisterCareAnnotationInput[]): RegisterCareAnnotatedFile[];
+export {};