@jhlagado/azm 0.1.1 → 0.2.1

package/dist/src/outputs/write-d8.d.ts

@@ -0,0 +1,2 @@
+import type { D8mArtifact, EmittedByteMap, SymbolEntry, WriteD8mOptions } from './types.js';
+export declare function writeD8m(map: EmittedByteMap, symbols: readonly SymbolEntry[], opts?: WriteD8mOptions): D8mArtifact;

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

@@ -0,0 +1,257 @@
+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));
+}
+export function writeD8m(map, symbols, opts) {
+    const { start, end } = getWrittenRange(map);
+    const writtenSegments = getWrittenSegments(map);
+    const segments = writtenSegments.length > 0
+        ? writtenSegments
+        : 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 fileSet = new Set(jsonSymbols
+        .map((symbol) => symbol.file)
+        .filter((file) => typeof file === 'string' && file.length > 0));
+    for (const segment of normalizedSourceSegments) {
+        if (segment.file.length > 0)
+            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 generatorInputs = opts?.inputs !== undefined ? normalizeInputs(opts.inputs, opts.rootDir) : undefined;
+    const generator = {
+        name: 'azm',
+        tool: 'azm',
+        ...(opts?.packageVersion !== undefined ? { version: opts.packageVersion } : {}),
+        ...(generatorInputs !== undefined ? { inputs: generatorInputs } : {}),
+        ...(opts?.entrySymbol !== undefined ? { entrySymbol: opts.entrySymbol } : {}),
+        ...(opts?.entryAddress !== undefined ? { entryAddress: opts.entryAddress & 0xffff } : {}),
+    };
+    return {
+        kind: 'd8m',
+        json: {
+            format: 'd8-debug-map',
+            version: 1,
+            arch: 'z80',
+            addressWidth: 16,
+            endianness: 'little',
+            files,
+            segments,
+            ...(fileList.length > 0 ? { fileList } : {}),
+            symbols: sortedSymbolList,
+            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/outputs/write-hex.d.ts

@@ -0,0 +1,2 @@
+import type { EmittedByteMap, HexArtifact, SymbolEntry, WriteHexOptions } from './types.js';
+export declare function writeHex(map: EmittedByteMap, _symbols: readonly SymbolEntry[], opts?: WriteHexOptions): HexArtifact;

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

@@ -0,0 +1,53 @@
+function toHexByte(n) {
+    return (n & 0xff).toString(16).toUpperCase().padStart(2, '0');
+}
+function toChecksum(bytes) {
+    const sum = bytes.reduce((acc, b) => acc + (b & 0xff), 0) & 0xff;
+    return ((0x100 - sum) & 0xff) >>> 0;
+}
+function writeSegments(map) {
+    const addresses = [...map.bytes.keys()].sort((a, b) => a - b);
+    if (addresses.length === 0) {
+        return [];
+    }
+    const [firstAddress, ...rest] = addresses;
+    if (firstAddress === undefined) {
+        return [];
+    }
+    const out = [];
+    let segmentStart = firstAddress;
+    let segmentEnd = firstAddress + 1;
+    for (const address of rest) {
+        if (address === segmentEnd) {
+            segmentEnd = address + 1;
+            continue;
+        }
+        out.push({ start: segmentStart, end: segmentEnd });
+        segmentStart = address;
+        segmentEnd = address + 1;
+    }
+    out.push({ start: segmentStart, end: segmentEnd });
+    return out;
+}
+export function writeHex(map, _symbols, opts) {
+    const lineEnding = opts?.lineEnding ?? '\n';
+    const lines = [];
+    for (const segment of writeSegments(map)) {
+        for (let address = segment.start; address < segment.end; address += 16) {
+            const count = Math.min(16, segment.end - address);
+            const data = [];
+            for (let index = 0; index < count; index += 1) {
+                data.push(map.bytes.get(address + index) ?? 0);
+            }
+            const hi = (address >> 8) & 0xff;
+            const lo = address & 0xff;
+            const recType = 0x00;
+            const payload = [count, hi, lo, recType, ...data];
+            lines.push(`:${toHexByte(count)}${toHexByte(hi)}${toHexByte(lo)}00${data
+                .map(toHexByte)
+                .join('')}${toHexByte(toChecksum(payload))}`);
+        }
+    }
+    lines.push(':00000001FF');
+    return { kind: 'hex', text: lines.join(lineEnding) + lineEnding };
+}

package/dist/src/outputs/write-listing.d.ts

@@ -0,0 +1,2 @@
+import type { EmittedByteMap, ListingArtifact, SymbolEntry, WriteListingOptions } from './types.js';
+export declare function writeListing(map: EmittedByteMap, symbols: readonly SymbolEntry[], opts?: WriteListingOptions): ListingArtifact;

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

@@ -0,0 +1,79 @@
+import { getWrittenRange, getWrittenSegments } from './range.js';
+function toHexByte(n) {
+    return (n & 0xff).toString(16).toUpperCase().padStart(2, '0');
+}
+function toHexWord(n) {
+    return (n & 0xffff).toString(16).toUpperCase().padStart(4, '0');
+}
+function symbolAddress(symbol) {
+    return symbol.kind === 'constant' ? symbol.value & 0xffff : symbol.address & 0xffff;
+}
+function sortSymbols(a, b) {
+    const aClass = a.kind === 'constant' ? 1 : 0;
+    const bClass = b.kind === 'constant' ? 1 : 0;
+    if (aClass !== bClass) {
+        return aClass - bClass;
+    }
+    const addressCmp = symbolAddress(a) - symbolAddress(b);
+    if (addressCmp !== 0) {
+        return addressCmp;
+    }
+    return a.name.toLowerCase().localeCompare(b.name.toLowerCase());
+}
+export function writeListing(map, symbols, opts) {
+    const lineEnding = opts?.lineEnding ?? '\n';
+    const bytesPerLine = opts?.bytesPerLine ?? 16;
+    const { start, end } = getWrittenRange(map);
+    const segments = getWrittenSegments(map);
+    const lines = [];
+    lines.push('; AZM listing');
+    lines.push(`; range: $${toHexWord(start)}..$${toHexWord(end)} (end exclusive)`);
+    lines.push('');
+    const lineBaseSet = new Set();
+    for (const segment of segments) {
+        const first = segment.start - (segment.start % bytesPerLine);
+        const last = segment.end - 1 - ((segment.end - 1) % bytesPerLine);
+        for (let address = first; address <= last; address += bytesPerLine) {
+            lineBaseSet.add(address);
+        }
+    }
+    const lineBases = [...lineBaseSet].sort((a, b) => a - b);
+    let previousBase;
+    for (const address of lineBases) {
+        if (previousBase !== undefined && address > previousBase + bytesPerLine) {
+            const gapStart = previousBase + bytesPerLine;
+            const gapEndInclusive = address - 1;
+            const gapLineCount = Math.ceil((address - gapStart) / bytesPerLine);
+            lines.push(`; ... gap $${toHexWord(gapStart)}..$${toHexWord(gapEndInclusive)} (${gapLineCount} lines)`);
+        }
+        const lineBytes = [];
+        const lineChars = [];
+        const count = Math.min(bytesPerLine, end - address);
+        for (let offset = 0; offset < count; offset += 1) {
+            const byte = map.bytes.get(address + offset);
+            if (byte === undefined) {
+                lineBytes.push('..');
+                lineChars.push(' ');
+            }
+            else {
+                const value = byte & 0xff;
+                lineBytes.push(toHexByte(value));
+                lineChars.push(value >= 0x20 && value <= 0x7e ? String.fromCharCode(value) : '.');
+            }
+        }
+        const payload = lineBytes.join(' ').padEnd(bytesPerLine * 3 - 1, ' ');
+        lines.push(`${toHexWord(address)}: ${payload}  |${lineChars.join('')}|`);
+        previousBase = address;
+    }
+    lines.push('');
+    lines.push('; symbols:');
+    for (const symbol of [...symbols].sort(sortSymbols)) {
+        if (symbol.kind === 'constant') {
+            lines.push(`; constant ${symbol.name} = $${toHexWord(symbol.value)} (${symbol.value})`);
+        }
+        else {
+            lines.push(`; ${symbol.kind} ${symbol.name} = $${toHexWord(symbol.address)}`);
+        }
+    }
+    return { kind: 'lst', text: lines.join(lineEnding) + lineEnding };
+}

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

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

package/dist/src/register-care/accept-output.js

@@ -0,0 +1,35 @@
+import { expandCarrierList } from './carriers.js';
+function appendUniqueUnits(target, units) {
+    for (const unit of units) {
+        if (!target.includes(unit))
+            target.push(unit);
+    }
+}
+export function parseAcceptedOutputCandidates(items = []) {
+    const out = new Map();
+    for (const item of items) {
+        const splitIndex = item.indexOf(':');
+        if (splitIndex <= 0 || splitIndex === item.length - 1) {
+            throw new Error(`Invalid --accept-out value "${item}" (expected ROUTINE:carriers)`);
+        }
+        const name = item.slice(0, splitIndex).trim();
+        if (!name) {
+            throw new Error(`Invalid --accept-out value "${item}" (missing routine name)`);
+        }
+        const carriers = item
+            .slice(splitIndex + 1)
+            .split(',')
+            .map((candidate) => candidate.trim());
+        if (carriers.length === 0 || carriers.some((candidate) => candidate.length === 0)) {
+            throw new Error(`Invalid --accept-out value "${item}" (missing carriers)`);
+        }
+        const units = expandCarrierList(carriers);
+        if (!units) {
+            throw new Error(`Invalid --accept-out value "${item}" (unknown carrier)`);
+        }
+        const existing = out.get(name) ?? [];
+        appendUniqueUnits(existing, units);
+        out.set(name, existing);
+    }
+    return out;
+}

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

@@ -0,0 +1,26 @@
+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 {
+    diagnostics: Diagnostic[];
+    outputCandidates?: RegisterCareOutputCandidate[];
+    reportText?: string;
+    interfaceText?: string;
+    annotations?: readonly RegisterCareAnnotationFile[];
+    unknownCalls?: string[];
+}
+export declare function analyzeRegisterCare(loaded: {
+    program: {
+        files: readonly [
+            {
+                readonly kind: 'SourceFile';
+                readonly name: string;
+                readonly items: readonly SourceItem[];
+            }
+        ];
+        entryFile: string;
+    };
+    sourceLineComments: ReadonlyMap<string, ReadonlyMap<number, string>>;
+    sourceTexts: ReadonlyMap<string, string>;
+}, options: AnalyzeRegisterCareOptions): AnalyzeRegisterCareResult;
+export {};

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

@@ -0,0 +1,115 @@
+import { buildRegisterCareProgramModel } from './programModel.js';
+import { buildRoutineContracts, parseSmartComments } from './smartComments.js';
+import { renderRegisterCareInterface, renderRegisterCareReport } from './report.js';
+import { autoFixableCandidateKeys } from './fix.js';
+import { findCallerOutputCandidateObservations, findRegisterCareConflicts, } from './liveness.js';
+import { buildAnnotations } from './annotations.js';
+import { buildOutputCandidateFixability, buildProfileSummaries, buildProfileSummaryLookup, buildSummaries, buildSummaryByName, outputCandidateKey, routineNames, unknownBoundaryDiagnostics, unknownCallList, withAcceptedOutputs, } from './summaries.js';
+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 analyzeRegisterCare(loaded, options) {
+    const file = loaded.program.files[0];
+    const items = file?.items ?? [];
+    const program = buildRegisterCareProgramModel(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.registerCareProfile);
+    let summaries = buildSummaries(program.routines, contractMap, profileSummaries);
+    summaries = withAcceptedOutputs(summaries, options.acceptedOutputCandidates);
+    const allSummaries = [...summaries, ...profileSummaries];
+    const summariesByName = buildSummaryByName(program.routines, summaries, profileSummaries);
+    const knownRoutines = new Set(routineNames(program.routines));
+    for (const [name] of contractMap) {
+        knownRoutines.add(name);
+    }
+    for (const name of buildProfileSummaryLookup(options.registerCareProfile).keys()) {
+        knownRoutines.add(name);
+    }
+    const diagnostics = [];
+    const shouldBuildOutputCandidates = options.mode !== 'off' ||
+        options.emitAnnotations === true ||
+        options.fixRegisterContracts === true;
+    const analyzed = shouldBuildOutputCandidates
+        ? {
+            conflicts: program.routines.flatMap((routine) => findRegisterCareConflicts(routine, summariesByName, smartComments)),
+            outputCandidates: findCallerOutputCandidateObservations(program.routines, summariesByName),
+        }
+        : { conflicts: [], outputCandidates: [] };
+    const conflicts = analyzed.conflicts;
+    const outputCandidates = analyzed.outputCandidates;
+    const outputCandidateFixability = buildOutputCandidateFixability(program.routines, outputCandidates, autoFixableCandidateKeys);
+    const outputCandidatesWithFixability = outputCandidates.map((candidate) => {
+        const autoFixable = outputCandidateFixability.get(outputCandidateKey(candidate.file, candidate.line, candidate.column)) ?? false;
+        return {
+            ...candidate,
+            autoFixable,
+            message: candidateMessageWithFixability(candidate, autoFixable),
+        };
+    });
+    if (options.mode !== 'audit') {
+        for (const conflict of conflicts) {
+            diagnostics.push({
+                severity: options.mode === 'error' ? 'error' : 'warning',
+                code: 'AZMN_REGISTER_CARE',
+                sourceName: conflict.file,
+                line: conflict.line,
+                column: conflict.column,
+                message: conflict.message,
+            });
+        }
+    }
+    if (options.mode === 'strict') {
+        diagnostics.push(...unknownBoundaryDiagnostics(program.directBoundaries, knownRoutines));
+    }
+    const reportModel = {
+        entryFile: loaded.program.entryFile,
+        mode: options.mode,
+        summaries: allSummaries,
+        conflicts,
+        outputCandidates: outputCandidatesWithFixability,
+        ...(options.registerCareProfile !== undefined ? { profile: options.registerCareProfile } : {}),
+        unknownCalls: options.mode === 'off' ? [] : unknownCallList(program.directBoundaries, knownRoutines),
+    };
+    const summariesForAnnotations = new Map(summariesByName);
+    const outputCandidatesByRoutine = new Map();
+    for (const candidate of outputCandidatesWithFixability) {
+        const existing = outputCandidatesByRoutine.get(candidate.routine) ?? [];
+        for (const unit of candidate.carriers) {
+            if (!existing.includes(unit))
+                existing.push(unit);
+        }
+        outputCandidatesByRoutine.set(candidate.routine, existing);
+    }
+    for (const [name, summary] of summariesForAnnotations) {
+        const candidates = outputCandidatesByRoutine.get(name);
+        if (candidates !== undefined && candidates.length > 0) {
+            summariesForAnnotations.set(name, { ...summary, outputCandidates: candidates });
+        }
+    }
+    const annotations = options.emitAnnotations
+        ? buildAnnotations(loaded, program.routines, summariesForAnnotations, outputCandidatesWithFixability, {
+            fixOutputCandidates: options.fixRegisterContracts === true,
+            outputCandidateFixability,
+            outputCandidateKey,
+        })
+        : [];
+    return {
+        diagnostics,
+        outputCandidates: outputCandidatesWithFixability,
+        ...(options.emitReport ? { reportText: renderRegisterCareReport(reportModel) } : {}),
+        ...(options.emitInterface ? { interfaceText: renderRegisterCareInterface(summaries) } : {}),
+        ...(annotations.length > 0 ? { annotations } : {}),
+        ...(reportModel.unknownCalls.length > 0 ? { unknownCalls: reportModel.unknownCalls } : {}),
+    };
+}

package/dist/src/register-care/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 {};

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

@@ -0,0 +1,76 @@
+import { renderRegisterCareSourceBlock } 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) {
+    return /^\s*;/.test(line);
+}
+function isGeneratedCompactLine(line) {
+    return GENERATED_COMPACT_LINE_RE.test(line);
+}
+function precedingCommentBlockStart(lines, labelIndex) {
+    let index = labelIndex - 1;
+    if (index < 0 || !isCommentLine(lines[index] ?? ''))
+        return undefined;
+    while (index >= 0 && isCommentLine(lines[index] ?? ''))
+        index -= 1;
+    return index + 1;
+}
+function generatedBlockBeforeLabel(lines, labelIndex) {
+    let compactStart = labelIndex;
+    while (compactStart > 0 && isGeneratedCompactLine(lines[compactStart - 1] ?? '')) {
+        compactStart -= 1;
+    }
+    if (compactStart < labelIndex)
+        return { start: compactStart, end: labelIndex - 1 };
+    return undefined;
+}
+function hasPrecedingCommentBlock(lines, labelIndex) {
+    return precedingCommentBlockStart(lines, labelIndex) !== undefined;
+}
+function isExplicitEntryRoutine(routine) {
+    return routine.entryLabels?.includes(routine.name) === true;
+}
+function annotateFile(source, routines) {
+    const sourceLines = splitSourceLines(source);
+    const { lines } = sourceLines;
+    const sorted = [...routines].sort((a, b) => b.routine.span.start.line - a.routine.span.start.line);
+    for (const item of sorted) {
+        const labelIndex = item.routine.span.start.line - 1;
+        if (labelIndex < 0 || labelIndex > lines.length)
+            continue;
+        const block = renderRegisterCareSourceBlock(item.summary);
+        const hasContractContent = block.length > 0;
+        const existing = generatedBlockBeforeLabel(lines, labelIndex);
+        if (existing) {
+            lines.splice(existing.start, existing.end - existing.start + 1, ...(hasContractContent ? block : []));
+            continue;
+        }
+        if (!hasContractContent)
+            continue;
+        if (!isExplicitEntryRoutine(item.routine) && !hasPrecedingCommentBlock(lines, labelIndex)) {
+            continue;
+        }
+        lines.splice(labelIndex, 0, ...block);
+    }
+    return joinSourceLines(sourceLines);
+}
+export function annotateRegisterCareContracts(sourceTexts, routines) {
+    const byFile = new Map();
+    for (const item of routines) {
+        if (!sourceTexts.has(item.routine.span.file))
+            continue;
+        const items = byFile.get(item.routine.span.file) ?? [];
+        items.push(item);
+        byFile.set(item.routine.span.file, items);
+    }
+    const out = [];
+    for (const [file, items] of [...byFile].sort(([a], [b]) => a.localeCompare(b))) {
+        const source = sourceTexts.get(file);
+        if (source === undefined)
+            continue;
+        const text = annotateFile(source, items);
+        if (text !== source)
+            out.push({ path: file, text });
+    }
+    return out;
+}