@jhlagado/azm 0.2.7 → 0.2.9

package/dist/src/outputs/write-d8.js

@@ -1,69 +1,6 @@
-import { normalize, relative, resolve, isAbsolute } from 'node:path';
 import { getWrittenRange, getWrittenSegments } from './range.js';
-function toHexFilePath(path, rootDir) {
-    const normalized = normalize(path).replace(/\\/g, '/');
-    if (!rootDir) {
-        return normalized;
-    }
-    const root = normalize(resolve(rootDir)).replace(/\\/g, '/');
-    const resolvedPath = normalize(resolve(path)).replace(/\\/g, '/');
-    const rel = relative(root, resolvedPath).replace(/\\/g, '/');
-    if (rel.startsWith('..') || rel === '' || isAbsolute(rel)) {
-        return resolvedPath;
-    }
-    return rel;
-}
-function compareSymbol(a, b) {
-    const aClass = a.kind === 'constant' ? 1 : 0;
-    const bClass = b.kind === 'constant' ? 1 : 0;
-    if (aClass !== bClass)
-        return aClass - bClass;
-    const aAddress = a.kind === 'constant' ? (a.value ?? 0) & 0xffff : (a.address ?? 0) & 0xffff;
-    const bAddress = b.kind === 'constant' ? (b.value ?? 0) & 0xffff : (b.address ?? 0) & 0xffff;
-    if (aAddress !== bAddress) {
-        return aAddress - bAddress;
-    }
-    const nameCmp = a.name.toLowerCase().localeCompare(b.name.toLowerCase());
-    if (nameCmp !== 0)
-        return nameCmp;
-    const kindCmp = a.kind.localeCompare(b.kind);
-    if (kindCmp !== 0)
-        return kindCmp;
-    const fileCmp = (a.file ?? '').localeCompare(b.file ?? '');
-    if (fileCmp !== 0)
-        return fileCmp;
-    const lineCmp = (a.line ?? 0) - (b.line ?? 0);
-    if (lineCmp !== 0)
-        return lineCmp;
-    if (a.kind === 'constant' && b.kind === 'constant') {
-        return (a.value ?? 0) - (b.value ?? 0);
-    }
-    return (a.size ?? 0) - (b.size ?? 0);
-}
-function compareFileSymbol(a, b) {
-    return compareSymbol(a, b);
-}
-function compareSegment(a, b) {
-    if (a.start !== b.start)
-        return a.start - b.start;
-    if (a.end !== b.end)
-        return a.end - b.end;
-    if (a.lstLine !== b.lstLine)
-        return a.lstLine - b.lstLine;
-    const lineCmp = (a.line ?? 0) - (b.line ?? 0);
-    if (lineCmp !== 0)
-        return lineCmp;
-    const kindCmp = a.kind.localeCompare(b.kind);
-    if (kindCmp !== 0)
-        return kindCmp;
-    return a.confidence.localeCompare(b.confidence);
-}
-function rangesOverlap(a, b) {
-    return a.start < b.end && b.start < a.end;
-}
-function hasOverlappingSourceSegment(sourceSegmentsByFile, file, range) {
-    return (sourceSegmentsByFile.get(file) ?? []).some((segment) => rangesOverlap({ start: segment.start, end: segment.end }, range));
-}
+import { normalizeInputs, normalizeSourceSegments, toD8mSymbol, } from './d8-helpers.js';
+import { buildD8mFiles } from './d8-files.js';
 export function writeD8m(map, symbols, opts) {
     const { start, end } = getWrittenRange(map);
     const writtenSegments = getWrittenSegments(map);
@@ -72,28 +9,8 @@ export function writeD8m(map, symbols, opts) {
         : start < end
             ? [{ start, end }]
             : [{ start: 0, end: 0 }];
-    const jsonSymbols = symbols.map((symbol) => symbol.kind === 'constant'
-        ? {
-            name: symbol.name,
-            kind: symbol.kind,
-            value: symbol.value,
-            ...(symbol.file !== undefined ? { file: toHexFilePath(symbol.file, opts?.rootDir) } : {}),
-            ...(symbol.line !== undefined ? { line: symbol.line } : {}),
-            ...(symbol.scope !== undefined ? { scope: symbol.scope } : {}),
-        }
-        : {
-            name: symbol.name,
-            kind: symbol.kind,
-            address: symbol.address,
-            ...(symbol.file !== undefined ? { file: toHexFilePath(symbol.file, opts?.rootDir) } : {}),
-            ...(symbol.line !== undefined ? { line: symbol.line } : {}),
-            ...(symbol.scope !== undefined ? { scope: symbol.scope } : {}),
-            ...(symbol.size !== undefined ? { size: symbol.size } : {}),
-        });
-    const normalizedSourceSegments = coalesceSourceSegments((map.sourceSegments ?? []).flatMap((segment) => clipSourceSegmentToWrittenSegments(segment, segments).map((clipped) => ({
-        ...clipped,
-        file: toHexFilePath(clipped.file, opts?.rootDir),
-    }))));
+    const jsonSymbols = symbols.map((symbol) => toD8mSymbol(symbol, opts?.rootDir));
+    const normalizedSourceSegments = normalizeSourceSegments(map.sourceSegments ?? [], segments, opts?.rootDir);
     const fileSet = new Set(jsonSymbols
         .map((symbol) => symbol.file)
         .filter((file) => typeof file === 'string' && file.length > 0));
@@ -102,88 +19,7 @@ export function writeD8m(map, symbols, opts) {
             fileSet.add(segment.file);
     }
     const fileList = [...fileSet].sort((a, b) => a.localeCompare(b));
-    const entries = new Map();
-    const ensureEntry = (file) => {
-        let entry = entries.get(file);
-        if (!entry) {
-            entry = { symbols: [], segments: [] };
-            entries.set(file, entry);
-        }
-        return entry;
-    };
-    const sortedSymbolList = [...jsonSymbols].sort(compareSymbol);
-    for (const symbol of sortedSymbolList) {
-        const entry = ensureEntry(symbol.file ?? '');
-        const symbolWithoutFile = { ...symbol };
-        delete symbolWithoutFile.file;
-        entry.symbols?.push(symbolWithoutFile);
-    }
-    for (const segment of normalizedSourceSegments) {
-        ensureEntry(segment.file).segments.push({
-            start: segment.start,
-            end: segment.end,
-            line: segment.line,
-            lstLine: segment.line,
-            kind: segment.kind,
-            confidence: segment.confidence,
-        });
-    }
-    const sourceSegmentsByFile = new Map();
-    for (const segment of normalizedSourceSegments) {
-        const sourceSegments = sourceSegmentsByFile.get(segment.file);
-        if (sourceSegments) {
-            sourceSegments.push(segment);
-        }
-        else {
-            sourceSegmentsByFile.set(segment.file, [segment]);
-        }
-    }
-    const symbolRangesByFile = new Map();
-    for (const symbol of sortedSymbolList) {
-        if (symbol.kind === 'constant' || symbol.file === undefined)
-            continue;
-        if (symbol.address === undefined)
-            continue;
-        const size = symbol.size !== undefined && symbol.size > 0 ? symbol.size : 1;
-        const ranges = symbolRangesByFile.get(symbol.file) ?? [];
-        ranges.push({ start: symbol.address, end: Math.min(0x10000, symbol.address + size) });
-        symbolRangesByFile.set(symbol.file, ranges);
-    }
-    for (const segment of segments) {
-        const targetFiles = [...symbolRangesByFile.entries()]
-            .filter(([, ranges]) => ranges.some((range) => rangesOverlap(range, segment)))
-            .map(([file]) => file)
-            .sort((a, b) => a.localeCompare(b));
-        const targets = targetFiles.length > 0 ? targetFiles : [fileList[0] ?? ''];
-        for (const target of targets) {
-            if (hasOverlappingSourceSegment(sourceSegmentsByFile, target, segment))
-                continue;
-            ensureEntry(target).segments.push({
-                start: segment.start,
-                end: segment.end,
-                lstLine: 1,
-                kind: 'unknown',
-                confidence: 'low',
-            });
-        }
-    }
-    for (const entry of entries.values()) {
-        entry.symbols.sort(compareFileSymbol);
-        entry.segments.sort(compareSegment);
-    }
-    const files = Object.fromEntries([...entries.entries()]
-        .sort(([a], [b]) => a.localeCompare(b))
-        .map(([path, fileEntry]) => [
-        path,
-        {
-            ...(fileEntry.segments && fileEntry.segments.length > 0
-                ? { segments: fileEntry.segments }
-                : {}),
-            ...(fileEntry.symbols && fileEntry.symbols.length > 0
-                ? { symbols: fileEntry.symbols }
-                : {}),
-        },
-    ]));
+    const { files, sortedSymbols } = buildD8mFiles(jsonSymbols, normalizedSourceSegments, segments, fileList);
     const generatorInputs = opts?.inputs !== undefined ? normalizeInputs(opts.inputs, opts.rootDir) : undefined;
     const generator = {
         name: 'azm',
@@ -204,54 +40,8 @@ export function writeD8m(map, symbols, opts) {
             files,
             segments,
             ...(fileList.length > 0 ? { fileList } : {}),
-            symbols: sortedSymbolList,
+            symbols: sortedSymbols,
             generator,
         },
     };
 }
-function normalizeInputs(inputs, rootDir) {
-    const out = {};
-    for (const [key, value] of Object.entries(inputs)) {
-        if (value !== undefined && value.length > 0) {
-            out[key] = toHexFilePath(value, rootDir);
-        }
-    }
-    return Object.keys(out).length > 0 ? out : undefined;
-}
-function clipSourceSegmentToWrittenSegments(segment, writtenSegments) {
-    const clipped = [];
-    for (const writtenSegment of writtenSegments) {
-        const start = Math.max(segment.start, writtenSegment.start);
-        const end = Math.min(segment.end, writtenSegment.end);
-        if (end > start) {
-            clipped.push({ ...segment, start, end });
-        }
-    }
-    return clipped;
-}
-function coalesceSourceSegments(segments) {
-    const sorted = [...segments].sort((a, b) => a.file.localeCompare(b.file) ||
-        a.line - b.line ||
-        a.column - b.column ||
-        a.kind.localeCompare(b.kind) ||
-        a.confidence.localeCompare(b.confidence) ||
-        a.start - b.start ||
-        a.end - b.end);
-    const coalesced = [];
-    for (const segment of sorted) {
-        const previous = coalesced[coalesced.length - 1];
-        if (previous &&
-            previous.file === segment.file &&
-            previous.line === segment.line &&
-            previous.column === segment.column &&
-            previous.kind === segment.kind &&
-            previous.confidence === segment.confidence &&
-            previous.end === segment.start) {
-            coalesced[coalesced.length - 1] = { ...previous, end: segment.end };
-        }
-        else {
-            coalesced.push(segment);
-        }
-    }
-    return coalesced;
-}

package/dist/src/register-contracts/accept-output.d.ts

@@ -0,0 +1,2 @@
+import type { RegisterContractsUnit } from './types.js';
+export declare function parseAcceptedOutputCandidates(items?: readonly string[]): Map<string, RegisterContractsUnit[]>;

package/dist/src/register-contracts/analyze-helpers.d.ts

@@ -0,0 +1,29 @@
+import type { Diagnostic } from '../model/diagnostic.js';
+import { unknownCallList } from './summaries.js';
+import type { AnalyzeRegisterContractsOptions, RegisterContractsOutputCandidate, RegisterContractsReportModel, RegisterContractsRoutine, RegisterContractsUnit, RoutineSummary } from './types.js';
+export declare function candidateMessageWithFixability(candidate: RegisterContractsOutputCandidate, autoFixable: boolean): string;
+export declare function knownRoutineNames(routines: readonly RegisterContractsRoutine[], contractNames: Iterable<string>, profile: AnalyzeRegisterContractsOptions['registerContractsProfile']): Set<string>;
+export declare function outputCandidatesWithFixability(routines: readonly RegisterContractsRoutine[], outputCandidates: readonly RegisterContractsOutputCandidate[]): {
+    outputCandidates: RegisterContractsOutputCandidate[];
+    outputCandidateFixability: ReadonlyMap<string, boolean>;
+};
+export declare function diagnosticsForConflicts(conflicts: readonly {
+    file: string;
+    line: number;
+    column: number;
+    message: string;
+}[], mode: AnalyzeRegisterContractsOptions['mode']): Diagnostic[];
+export declare function strictStackDiagnostics(routines: readonly RegisterContractsRoutine[], summaries: readonly RoutineSummary[]): Diagnostic[];
+export declare function summariesForAnnotations(summariesByName: ReadonlyMap<string, RoutineSummary>, outputCandidates: readonly RegisterContractsOutputCandidate[]): Map<string, RoutineSummary>;
+export declare function buildRegisterContractsReportModel(input: {
+    entryFile: string;
+    mode: AnalyzeRegisterContractsOptions['mode'];
+    summaries: readonly RoutineSummary[];
+    profileSummaries: readonly RoutineSummary[];
+    conflicts: RegisterContractsReportModel['conflicts'];
+    outputCandidates: readonly RegisterContractsOutputCandidate[];
+    profile: AnalyzeRegisterContractsOptions['registerContractsProfile'];
+    directBoundaries: Parameters<typeof unknownCallList>[0];
+    knownRoutines: ReadonlySet<string>;
+}): RegisterContractsReportModel;
+export declare function autoAcceptedOutputCandidateMap(routines: readonly RegisterContractsRoutine[], outputCandidates: readonly RegisterContractsOutputCandidate[], sourceTexts: ReadonlyMap<string, string>): ReadonlyMap<string, RegisterContractsUnit[]>;

package/dist/src/register-contracts/analyze-helpers.js

@@ -0,0 +1,162 @@
+import { autoFixableCandidateKeys, findExpectOutFixesForCandidates } from './fix.js';
+import { buildOutputCandidateFixability, buildProfileSummaryLookup, outputCandidateKey, routineNames, unknownCallList, } from './summaries.js';
+export function candidateMessageWithFixability(candidate, autoFixable) {
+    const carriers = candidate.carriers.join(',');
+    const expectation = candidate.carriers.length === 1 ? candidate.carriers[0] : `{${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.`;
+}
+export function knownRoutineNames(routines, contractNames, profile) {
+    const known = new Set(routineNames(routines));
+    for (const name of contractNames)
+        known.add(name);
+    for (const name of buildProfileSummaryLookup(profile).keys())
+        known.add(name);
+    return known;
+}
+export function outputCandidatesWithFixability(routines, outputCandidates) {
+    const outputCandidateFixability = buildOutputCandidateFixability(routines, outputCandidates, autoFixableCandidateKeys);
+    return {
+        outputCandidateFixability,
+        outputCandidates: outputCandidates.map((candidate) => {
+            const autoFixable = outputCandidateFixability.get(outputCandidateKey(candidate.file, candidate.line, candidate.column)) ?? false;
+            return {
+                ...candidate,
+                autoFixable,
+                message: candidateMessageWithFixability(candidate, autoFixable),
+            };
+        }),
+    };
+}
+export function diagnosticsForConflicts(conflicts, mode) {
+    if (mode === 'audit')
+        return [];
+    return conflicts.map((conflict) => ({
+        severity: mode === 'error' || mode === 'strict' ? 'error' : 'warning',
+        code: 'AZMN_REGISTER_CONTRACTS',
+        sourceName: conflict.file,
+        line: conflict.line,
+        column: conflict.column,
+        message: conflict.message,
+    }));
+}
+export function strictStackDiagnostics(routines, summaries) {
+    const routinesByName = new Map(routines.map((routine) => [routine.name, routine]));
+    const diagnostics = [];
+    for (const summary of summaries) {
+        const routine = routinesByName.get(summary.name);
+        if (routine === undefined)
+            continue;
+        const stackIssues = strictStackIssueText(summary);
+        if (stackIssues === undefined)
+            continue;
+        diagnostics.push({
+            severity: 'error',
+            code: 'AZMN_REGISTER_CONTRACTS',
+            sourceName: routine.span.file,
+            line: routine.span.start.line,
+            column: routine.span.start.column,
+            message: `Register contracts cannot prove stack discipline for ${summary.name}: ${stackIssues}. Keep PUSH/POP pairs and stack-changing exits inside one @ routine boundary, or split the code into explicit callable routines.`,
+        });
+    }
+    return diagnostics;
+}
+function strictStackIssueText(summary) {
+    const issues = [];
+    if (!summary.stackBalanced)
+        issues.push('stack is unbalanced');
+    if (summary.hasUnknownStackEffect === true)
+        issues.push('stack effect is unknown');
+    return issues.length > 0 ? issues.join('; ') : undefined;
+}
+export function summariesForAnnotations(summariesByName, outputCandidates) {
+    const summariesForAnnotations = new Map(summariesByName);
+    const outputCandidatesByRoutine = outputCandidateUnitsByRoutine(outputCandidates);
+    for (const [name, summary] of summariesForAnnotations) {
+        const candidates = outputCandidatesByRoutine.get(name);
+        if (candidates !== undefined && candidates.length > 0) {
+            summariesForAnnotations.set(name, { ...summary, outputCandidates: candidates });
+        }
+    }
+    return summariesForAnnotations;
+}
+function outputCandidateUnitsByRoutine(outputCandidates) {
+    const out = new Map();
+    for (const candidate of outputCandidates) {
+        const existing = out.get(candidate.routine) ?? [];
+        for (const unit of candidate.carriers) {
+            if (!existing.includes(unit))
+                existing.push(unit);
+        }
+        out.set(candidate.routine, existing);
+    }
+    return out;
+}
+export function buildRegisterContractsReportModel(input) {
+    return {
+        entryFile: input.entryFile,
+        mode: input.mode,
+        summaries: [...input.summaries, ...input.profileSummaries],
+        conflicts: [...input.conflicts],
+        outputCandidates: [...input.outputCandidates],
+        ...(input.profile !== undefined ? { profile: input.profile } : {}),
+        unknownCalls: input.mode === 'off' ? [] : unknownCallList(input.directBoundaries, input.knownRoutines),
+    };
+}
+export function autoAcceptedOutputCandidateMap(routines, outputCandidates, sourceTexts) {
+    const out = new Map();
+    const sourceMaybeOut = sourceMaybeOutByRoutine(routines, sourceTexts);
+    for (const fix of findExpectOutFixesForCandidates([...routines], [...outputCandidates])) {
+        const declaredMaybeOut = sourceMaybeOut.get(fix.routine) ?? [];
+        const eligibleCarriers = fix.carriers.filter((carrier) => declaredMaybeOut.includes(carrier));
+        if (eligibleCarriers.length === 0)
+            continue;
+        const carriers = out.get(fix.routine) ?? [];
+        for (const carrier of eligibleCarriers) {
+            if (!carriers.includes(carrier))
+                carriers.push(carrier);
+        }
+        out.set(fix.routine, carriers);
+    }
+    return out;
+}
+function sourceMaybeOutByRoutine(routines, sourceTexts) {
+    const out = new Map();
+    for (const routine of routines) {
+        const maybeOutUnits = sourceMaybeOutUnits(routine, sourceTexts);
+        if (maybeOutUnits.length === 0)
+            continue;
+        out.set(routine.name, maybeOutUnits);
+        for (const label of routine.labels)
+            out.set(label, maybeOutUnits);
+        for (const label of routine.entryLabels)
+            out.set(label, maybeOutUnits);
+    }
+    return out;
+}
+function sourceMaybeOutUnits(routine, sourceTexts) {
+    const source = sourceTexts.get(routine.span.file);
+    if (source === undefined)
+        return [];
+    const lines = source.split(/\r?\n/);
+    const units = [];
+    for (let index = routine.span.start.line - 2; index >= 0; index -= 1) {
+        const text = lines[index] ?? '';
+        if (!/^\s*;/.test(text))
+            break;
+        const match = /^\s*;\s*!\s*maybe-out\s+(.+)$/i.exec(text);
+        if (!match)
+            continue;
+        addUnits(units, match[1]);
+    }
+    return units;
+}
+function addUnits(out, text) {
+    for (const token of text.split(',')) {
+        const unit = token.trim();
+        if (unit.length > 0 && !out.includes(unit))
+            out.push(unit);
+    }
+}

package/dist/src/{register-care → register-contracts}/analyze.d.ts

@@ -1,15 +1,15 @@
 import type { Diagnostic } from '../model/diagnostic.js';
 import type { SourceItem } from '../model/source-item.js';
-import type { AnalyzeRegisterCareOptions, RegisterCareAnnotationFile, RegisterCareOutputCandidate } from './types.js';
-interface AnalyzeRegisterCareResult {
+import type { AnalyzeRegisterContractsOptions, RegisterContractsAnnotationFile, RegisterContractsOutputCandidate } from './types.js';
+interface AnalyzeRegisterContractsResult {
     diagnostics: Diagnostic[];
-    outputCandidates?: RegisterCareOutputCandidate[];
+    outputCandidates?: RegisterContractsOutputCandidate[];
     reportText?: string;
     interfaceText?: string;
-    annotations?: readonly RegisterCareAnnotationFile[];
+    annotations?: readonly RegisterContractsAnnotationFile[];
     unknownCalls?: string[];
 }
-export declare function analyzeRegisterCare(loaded: {
+export declare function analyzeRegisterContracts(loaded: {
     program: {
         files: readonly [
             {
@@ -22,5 +22,5 @@ export declare function analyzeRegisterCare(loaded: {
     };
     sourceLineComments: ReadonlyMap<string, ReadonlyMap<number, string>>;
     sourceTexts: ReadonlyMap<string, string>;
-}, options: AnalyzeRegisterCareOptions): AnalyzeRegisterCareResult;
+}, options: AnalyzeRegisterContractsOptions): AnalyzeRegisterContractsResult;
 export {};

package/dist/src/register-contracts/analyze.js

@@ -0,0 +1,73 @@
+import { buildRegisterContractsProgramModel } from './programModel.js';
+import { buildRoutineContracts, parseSmartComments } from './smartComments.js';
+import { renderRegisterContractsInterface, renderRegisterContractsReport } from './report.js';
+import { findCallerOutputCandidateObservations, findRegisterContractsConflicts, } from './liveness.js';
+import { buildAnnotations } from './annotations.js';
+import { autoAcceptedOutputCandidateMap, buildRegisterContractsReportModel, diagnosticsForConflicts, knownRoutineNames, outputCandidatesWithFixability, strictStackDiagnostics, summariesForAnnotations, } from './analyze-helpers.js';
+import { buildProfileSummaries, buildSummaries, buildSummaryByName, outputCandidateKey, unknownBoundaryDiagnostics, withAcceptedOutputs, } from './summaries.js';
+export function analyzeRegisterContracts(loaded, options) {
+    const file = loaded.program.files[0];
+    const items = file?.items ?? [];
+    const program = buildRegisterContractsProgramModel(items);
+    const smartComments = parseSmartComments(loaded.sourceLineComments);
+    const contractMap = buildRoutineContracts(smartComments, program.routines, loaded.sourceTexts);
+    if (options.interfaceContracts !== undefined) {
+        for (const contract of options.interfaceContracts) {
+            contractMap.set(contract.name, contract);
+        }
+    }
+    const profileSummaries = buildProfileSummaries(options.registerContractsProfile);
+    let summaries = buildSummaries(program.routines, contractMap, profileSummaries);
+    summaries = withAcceptedOutputs(summaries, options.acceptedOutputCandidates);
+    let summariesByName = buildSummaryByName(program.routines, summaries, profileSummaries);
+    const knownRoutines = knownRoutineNames(program.routines, contractMap.keys(), options.registerContractsProfile);
+    const shouldBuildOutputCandidates = options.mode !== 'off' ||
+        options.emitAnnotations === true ||
+        options.fixRegisterContracts === true;
+    const outputCandidates = shouldBuildOutputCandidates
+        ? findCallerOutputCandidateObservations(program.routines, summariesByName)
+        : [];
+    const autoAcceptedOutputs = autoAcceptedOutputCandidateMap(program.routines, outputCandidates, loaded.sourceTexts);
+    if (autoAcceptedOutputs.size > 0) {
+        summaries = withAcceptedOutputs(summaries, autoAcceptedOutputs);
+        summariesByName = buildSummaryByName(program.routines, summaries, profileSummaries);
+    }
+    const conflicts = shouldBuildOutputCandidates
+        ? program.routines.flatMap((routine) => findRegisterContractsConflicts(routine, summariesByName, smartComments))
+        : [];
+    const { outputCandidates: outputCandidatesWithAutoFixability, outputCandidateFixability } = outputCandidatesWithFixability(program.routines, outputCandidates);
+    const diagnostics = diagnosticsForConflicts(conflicts, options.mode);
+    if (options.mode === 'strict') {
+        diagnostics.push(...unknownBoundaryDiagnostics(program.directBoundaries, knownRoutines, 'error'));
+        diagnostics.push(...strictStackDiagnostics(program.routines, summaries));
+    }
+    const reportModel = buildRegisterContractsReportModel({
+        entryFile: loaded.program.entryFile,
+        mode: options.mode,
+        summaries,
+        profileSummaries,
+        conflicts,
+        outputCandidates: outputCandidatesWithAutoFixability,
+        profile: options.registerContractsProfile,
+        directBoundaries: program.directBoundaries,
+        knownRoutines,
+    });
+    const summariesForAnnotationsByName = summariesForAnnotations(summariesByName, outputCandidatesWithAutoFixability);
+    const annotations = options.emitAnnotations
+        ? buildAnnotations(loaded, program.routines, summariesForAnnotationsByName, outputCandidatesWithAutoFixability, {
+            fixOutputCandidates: options.fixRegisterContracts === true,
+            outputCandidateFixability,
+            outputCandidateKey,
+        })
+        : [];
+    return {
+        diagnostics,
+        outputCandidates: outputCandidatesWithAutoFixability,
+        ...(options.emitReport ? { reportText: renderRegisterContractsReport(reportModel) } : {}),
+        ...(options.emitInterface
+            ? { interfaceText: renderRegisterContractsInterface(summaries) }
+            : {}),
+        ...(annotations.length > 0 ? { annotations } : {}),
+        ...(reportModel.unknownCalls.length > 0 ? { unknownCalls: reportModel.unknownCalls } : {}),
+    };
+}

package/dist/src/register-contracts/annotate.d.ts

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

package/dist/src/{register-care → register-contracts}/annotate.js

@@ -1,4 +1,4 @@
-import { renderRegisterCareSourceBlock } from './report.js';
+import { renderRegisterContractsSourceBlock } from './report.js';
 import { joinSourceLines, splitSourceLines } from './sourceText.js';
 const GENERATED_COMPACT_LINE_RE = /^\s*;\s*!\s*(?:in|out|maybe-out|clobbers|preserves)(?:\s|$)/i;
 function isCommentLine(line) {
@@ -38,7 +38,7 @@ function annotateFile(source, routines) {
         const labelIndex = item.routine.span.start.line - 1;
         if (labelIndex < 0 || labelIndex > lines.length)
             continue;
-        const block = renderRegisterCareSourceBlock(item.summary);
+        const block = renderRegisterContractsSourceBlock(item.summary);
         const hasContractContent = block.length > 0;
         const existing = generatedBlockBeforeLabel(lines, labelIndex);
         if (existing) {
@@ -54,7 +54,7 @@ function annotateFile(source, routines) {
     }
     return joinSourceLines(sourceLines);
 }
-export function annotateRegisterCareContracts(sourceTexts, routines) {
+export function annotateRegisterContractsContracts(sourceTexts, routines) {
     const byFile = new Map();
     for (const item of routines) {
         if (!sourceTexts.has(item.routine.span.file))

package/dist/src/register-contracts/annotations.d.ts

@@ -0,0 +1,8 @@
+import type { RegisterContractsAnnotationFile, RegisterContractsOutputCandidate, RegisterContractsRoutine, RoutineSummary } from './types.js';
+export declare function buildAnnotations(loaded: {
+    sourceTexts: ReadonlyMap<string, string>;
+}, programRoutines: readonly RegisterContractsRoutine[], summariesByName: ReadonlyMap<string, RoutineSummary>, outputCandidates: readonly RegisterContractsOutputCandidate[], options: {
+    fixOutputCandidates: boolean;
+    outputCandidateFixability: ReadonlyMap<string, boolean>;
+    outputCandidateKey: (file: string, line: number, column: number) => string;
+}): readonly RegisterContractsAnnotationFile[];

package/dist/src/{register-care → register-contracts}/annotations.js

@@ -1,5 +1,5 @@
-import { annotateRegisterCareContracts } from './annotate.js';
-import { applyExpectOutFixesToSource, findExpectOutFixesForCandidates, } from './fix.js';
+import { annotateRegisterContractsContracts } from './annotate.js';
+import { applyExpectOutFixesToSource, findExpectOutFixesForCandidates } from './fix.js';
 export function buildAnnotations(loaded, programRoutines, summariesByName, outputCandidates, options) {
     const routines = programRoutines
         .filter((routine) => summariesByName.has(routine.name))
@@ -7,7 +7,7 @@ export function buildAnnotations(loaded, programRoutines, summariesByName, outpu
         routine,
         summary: summariesByName.get(routine.name),
     }));
-    const annotated = annotateRegisterCareContracts(loaded.sourceTexts, routines);
+    const annotated = annotateRegisterContractsContracts(loaded.sourceTexts, routines);
     if (!options.fixOutputCandidates) {
         return annotated.map((file) => ({ path: file.path, text: file.text }));
     }

package/dist/src/register-contracts/boundaryHints.d.ts

@@ -0,0 +1,3 @@
+import type { RegisterContractsInstruction } from './types.js';
+export declare function precedingCServiceName(item: RegisterContractsInstruction | undefined): string | undefined;
+export declare function precedingRegisterImmediateValue(item: RegisterContractsInstruction | undefined, register: string): number | undefined;

package/dist/src/register-contracts/boundaryHints.js

@@ -0,0 +1,24 @@
+import { evaluateKnownConstant } from './constants.js';
+export function precedingCServiceName(item) {
+    const instruction = item?.instruction;
+    if (!instruction || instruction.mnemonic !== 'ld')
+        return undefined;
+    if (instruction.target?.kind !== 'reg8' || instruction.target.register !== 'c')
+        return undefined;
+    if (instruction.source.kind === 'imm' && instruction.source.expression.kind === 'symbol') {
+        return instruction.source.expression.name;
+    }
+    return undefined;
+}
+export function precedingRegisterImmediateValue(item, register) {
+    const instruction = item?.instruction;
+    if (!instruction || instruction.mnemonic !== 'ld')
+        return undefined;
+    if (instruction.target?.kind !== 'reg8' ||
+        instruction.target.register !== register.toLowerCase()) {
+        return undefined;
+    }
+    if (instruction.source.kind !== 'imm')
+        return undefined;
+    return evaluateKnownConstant(instruction.source.expression, item.constants ?? new Map());
+}

package/dist/src/register-contracts/carriers.d.ts

@@ -0,0 +1,2 @@
+import type { RegisterContractsUnit } from './types.js';
+export declare function expandCarrierList(raw: readonly string[]): RegisterContractsUnit[] | undefined;

package/dist/src/register-contracts/constants.d.ts

@@ -0,0 +1,4 @@
+import type { Expression } from '../model/expression.js';
+import type { SourceItem } from '../model/source-item.js';
+export declare function evaluateKnownConstant(expression: Expression, constants: ReadonlyMap<string, number>): number | undefined;
+export declare function collectConstants(items: readonly SourceItem[]): ReadonlyMap<string, number>;