@jhlagado/azm 0.2.0 → 0.2.1

package/README.md

@@ -1,47 +1,54 @@
 # AZM
 
-AZM is a Z80 assembler in the ASM80 tradition: plain assembly input, predictable
-object output, and modern safety tooling for projects that still want to see the
-machine.
+AZM is the Z80 assembler used by the Debug80 toolchain. It assembles plain
+`.asm` and `.z80` source into machine-code artifacts for hardware, emulators,
+and Debug80: Intel HEX, flat binary, listings, Debug80 maps, and optional
+ASM80-compatible lowered source.
 
-The project goal is a good assembler, not a high-level language. AZM keeps
-labels, directives, instructions, branches, data bytes, register effects, and
-generated metadata visible in source and artifacts.
+The user manual is the AZM book in the Debug80 documentation site:
 
-## Product boundary
+[AZM Assembler Manual](https://jhlagado.github.io/debug80-docs/azm-book/book4/)
 
-AZM keeps:
+## What AZM Is
 
-- ASM80-style `.asm` / `.z80` source as the input baseline
-- `.asmi` external interface files for register-care contracts
+AZM is an assembler, not a high-level language or macro preprocessor. Source is
+intended to stay close to the machine: labels, directives, instructions, data,
+register contracts, and generated artifacts remain visible.
+
+AZM keeps the parts of the original assembler that matter for real Z80 work:
+
+- Z80 instructions with case-insensitive mnemonics and registers
+- case-sensitive labels and symbols
+- global labels, with `@NAME:` labels marking routine entries for register-care
+  analysis
+- canonical dotted directives such as `.org`, `.equ`, `.db`, `.dw`, and `.ds`
+- compatibility spelling for common undotted directive heads such as `ORG`,
+  `EQU`, `DB`, `DW`, and `DS`
 - textual `.include`
-- directive aliases for importing common assembler spellings
-- register-care analysis, compact AZMDoc comments, and `.asmi` external
-  contracts
-- AST-level `op` extensions
-- enums as constant namespaces
+- register-care contracts, AZMDoc comments, and `.asmi` external interfaces
+- `op` definitions for structured inline instruction idioms
+- enums and qualified enum constants
 - `.type` / `.union` layout metadata
 - compile-time layout constants such as `sizeof(...)`, `offset(...)`, scalar
   layout sizes, and constant-only layout casts
-- assembler data directives including `.db`, `.dw`, `.ds`, `.cstr`, `.pstr`,
-  and `.istr`
+- data directives including `.db`, `.dw`, `.ds`, `.cstr`, `.pstr`, and `.istr`
 
-AZM `.asm` and `.z80` source rejects old ZAX high-level features such as
-modules/imports, `func`, formal arguments, locals, typed assignment/storage
-lowering, structured control, generated frames, typed storage blocks, and named
-section blocks. Those inherited paths are removal work, not product
-compatibility.
+AZM does not implement text macros, local labels, modules/imports, `func`,
+formal arguments, generated stack frames, structured control flow, typed
+assignment lowering, hidden typed load/store lowering, or named section blocks.
+Those features belong to older high-level ZAX-era code paths, not current AZM
+source.
 
 ## Install
 
-Requires Node.js 20+.
+AZM requires Node.js 20 or newer.
 
 ```sh
 npm install -g @jhlagado/azm
-azm path/to/program.z80
+azm path/to/program.asm
 ```
 
-From a checkout, use the local CLI after building:
+From a checkout, build first and then use the local CLI:
 
 ```sh
 npm ci
@@ -49,56 +56,70 @@ npm run build
 npm run azm -- examples/hello.asm
 ```
 
-Output files for each compiled source:
+## Command Line
 
-| Extension  | Contents                  |
-| ---------- | ------------------------- |
-| `.hex`     | Intel HEX                 |
-| `.bin`     | Flat binary               |
-| `.lst`     | Byte dump plus symbols    |
-| `.z80`     | Plain Z80 source emission |
-| `.d8.json` | Debug80 map               |
+Basic use writes the default artifact set next to the source file:
 
-Small input example:
+```sh
+azm program.asm
+```
 
-```asm
-        ORG 0100H
-START:
-        LD A,42
-        RET
+Write a specific primary output:
+
+```sh
+azm --type bin --output build/program.bin program.asm
+azm --type hex --output build/program.hex program.asm
 ```
 
-Compile a binary and listing:
+Add include search paths:
 
 ```sh
-azm --type bin --output build/start.bin start.asm
+azm -I include -I vendor program.asm
+```
+
+Run register-care analysis:
+
+```sh
+azm --rc audit --reg-report program.asm
+azm --rc error --interface monitor.asmi program.asm
+```
+
+See [docs/reference/cli.md](docs/reference/cli.md) for the complete option
+reference.
+
+## Output Artifacts
+
+By default, AZM writes the requested primary output plus useful side artifacts
+using the same base path.
+
+| Extension      | Contents                                      |
+| -------------- | --------------------------------------------- |
+| `.hex`         | Intel HEX                                     |
+| `.bin`         | flat binary                                   |
+| `.lst`         | listing with bytes and symbols                |
+| `.d8.json`     | Debug80 map                                   |
+| `.z80`         | ASM80-compatible lowered source when enabled  |
+| `.regcare.txt` | register-care report when enabled             |
+| `.asmi`        | inferred register-care interface when enabled |
+
+The `.z80` output is a generated compatibility artifact for ASM80-style
+workflows and comparison tooling. BIN, HEX, listings, Debug80 maps, and
+register-care reports are the normal production outputs.
+
+## Small Example
+
+```asm
+        .org 0100H
+
+@START:
+        ld      a,42
+        ret
 ```
 
-```text
-azm [options] <entry.asm|entry.z80>
-
-Options:
-  -o, --output <file>   Primary output path (must match --type extension)
-  -t, --type <type>     Primary output type: hex|bin (default: hex)
-  -n, --nolist          Suppress .lst
-      --nobin           Suppress .bin
-      --nohex           Suppress .hex
-      --nod8m           Suppress .d8.json
-      --asm80           Emit assembler-valid lowered source (.z80)
-      --source-root <d> Normalize D8 source paths relative to this directory
-      --case-style <m>  Case-style lint mode: off|upper|lower|consistent
-      --rc <m>            Register-care mode: off|audit|warn|error|strict
-      --reg-report       Emit .regcare.txt report
-      --reg-interface    Emit inferred register-care interface (.asmi)
-      --fix             Apply conservative register-care source fixes
-      --contracts       Update source AZM contract blocks in place
-      --accept-out <r:c> Promote inferred output candidate while annotating
-      --interface <file> Load register-care interface contracts
-      --reg-profile <p> Register-care profile: mon3
-      --aliases <file>  Load project directive alias JSON (repeatable)
-  -I, --include <dir>   Add include search path (repeatable)
-  -V, --version         Print version
-  -h, --help            Show help
+Compile it:
+
+```sh
+azm --type bin --output build/start.bin start.asm
 ```
 
 ## Programmatic API
@@ -130,21 +151,25 @@ const result = await compile(
 console.log(result.diagnostics);
 ```
 
-See [docs/reference/cli.md](docs/reference/cli.md) for the full CLI reference
-and [docs/reference/tooling-api.md](docs/reference/tooling-api.md) for the
-current API notes.
+See [docs/reference/tooling-api.md](docs/reference/tooling-api.md) for current
+API notes.
 
-## Verification
+## Development
 
 Useful local verification lanes:
 
 ```sh
 npm run build
+npm run typecheck
+npm run lint
 npm run test:azm:alpha
 npm run test:azm:corpus
 npm test
 ```
 
+The live source map is maintained in
+[docs/reference/source-overview.md](docs/reference/source-overview.md).
+
 ## License
 
 GPL-3.0-only. See [LICENSE](LICENSE).

package/dist/src/api-compile.js

@@ -183,7 +183,7 @@ export async function compile(entryFile, options = {}, deps = { formats: default
                         line: error.item.span.line,
                         column: error.item.span.column,
                     });
-                    return { diagnostics, artifacts: [] };
+                    return { diagnostics, artifacts };
                 }
                 throw error;
             }

package/dist/src/assembly/address-planning.js

@@ -58,6 +58,8 @@ function buildAddressStateOnce(items, diagnostics, previous, reportUnknown) {
             case 'enum':
                 defineEnumMembers(equates, labels, layouts, enumNames, enumNamesLower, item.name, item.members, item.span, diagnostics);
                 break;
+            case 'comment':
+                break;
             case 'label':
                 defineLabel(labels, equates, layouts, enumNamesLower, item.name, placementAddress(placement), item.span, diagnostics);
                 break;

package/dist/src/assembly/program-emission.js

@@ -117,6 +117,7 @@ export function emitProgramImage(items, addressState, symbols, diagnostics) {
                 }
                 break;
             }
+            case 'comment':
             case 'equ':
             case 'label':
             case 'enum':

package/dist/src/expansion/op-expansion.js

@@ -663,6 +663,7 @@ function renameSourceItem(item, localLabelMap) {
                 ...item,
                 instruction: renameInstructionExpressions(item.instruction, localLabelMap),
             };
+        case 'comment':
         case 'end':
         case 'enum':
         case 'type':

package/dist/src/model/source-item.d.ts

@@ -14,6 +14,12 @@ export type SourceItem = {
 } | {
     readonly kind: 'label';
     readonly name: string;
+    readonly isEntry?: boolean;
+    readonly span: SourceSpan;
+} | {
+    readonly kind: 'comment';
+    readonly text: string;
+    readonly origin: 'user' | 'generated';
     readonly span: SourceSpan;
 } | {
     readonly kind: 'db';

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

@@ -74,6 +74,11 @@ function formatItem(item, evalContext, state) {
                 ? undefined
                 : withImplicitOrg(state, `${item.name} EQU ${expression}`, 0);
         }
+        case 'comment':
+            return {
+                text: item.origin === 'user' ? `; ${item.text}` : `; AZM: ${item.text}`,
+                size: 0,
+            };
         case 'label':
             return withImplicitOrg(state, `${item.name}:`, 0);
         case 'db':
@@ -239,6 +244,16 @@ function formatInstruction(instruction, evalContext) {
         case 'res':
         case 'set':
             return formatBitOp(instruction, evalContext);
+        case 'rlc':
+        case 'rrc':
+        case 'rl':
+        case 'rr':
+        case 'sla':
+        case 'sra':
+        case 'sll':
+        case 'sls':
+        case 'srl':
+            return formatRotateShift(instruction, evalContext);
         case 'in':
             return formatIn(instruction, evalContext);
         case 'out':
@@ -264,6 +279,11 @@ function formatInstruction(instruction, evalContext) {
             return formatBranch(`call ${instruction.condition},`, instruction.expression, evalContext);
         case 'djnz':
             return formatBranch('djnz', instruction.expression, evalContext);
+        case 'push':
+        case 'pop':
+            return { text: `${instruction.mnemonic} ${instruction.register}` };
+        case 'ret-cc':
+            return { text: `ret ${instruction.condition}` };
         default:
             return undefined;
     }
@@ -282,7 +302,7 @@ function formatAlu(mnemonic, source, evalContext) {
     return { text: `${mnemonic} ${operand}` };
 }
 function formatAluOperand(source, evalContext) {
-    if (source.kind === 'reg8') {
+    if (source.kind === 'reg8' || source.kind === 'reg-half-index') {
         return source.register;
     }
     if (source.kind === 'reg-indirect' && source.register === 'hl') {
@@ -330,6 +350,18 @@ function formatLd(target, source, evalContext) {
     if (target.kind === 'reg8' && source.kind === 'reg8') {
         return { text: `ld ${target.register}, ${source.register}` };
     }
+    if (target.kind === 'reg8' && source.kind === 'reg-half-index') {
+        return { text: `ld ${target.register}, ${source.register}` };
+    }
+    if (target.kind === 'reg8' && target.register === 'a' && source.kind === 'special8') {
+        return { text: `ld a, ${source.register}` };
+    }
+    if (target.kind === 'special8' && source.kind === 'reg8' && source.register === 'a') {
+        return { text: `ld ${target.register}, a` };
+    }
+    if (target.kind === 'reg-index16' && source.kind === 'imm') {
+        return formatLdText(target.register, formatExpression(source.expression, evalContext, 'word'));
+    }
     if (target.kind === 'reg16' && source.kind === 'imm') {
         return formatLdText(target.register, formatExpression(source.expression, evalContext, 'word'));
     }
@@ -345,12 +377,44 @@ function formatLd(target, source, evalContext) {
         source.register === 'a') {
         return { text: `ld (${target.register}), a` };
     }
-    if (target.kind === 'reg8' && target.register === 'a' && source.kind === 'mem-abs') {
-        return formatLdText('a', formatParenthesizedExpression(source.expression, evalContext, 'auto'));
+    if (target.kind === 'reg8' && source.kind === 'reg-indirect' && source.register === 'hl') {
+        return { text: `ld ${target.register}, (hl)` };
+    }
+    if (target.kind === 'reg-indirect' && target.register === 'hl' && source.kind === 'reg8') {
+        return { text: `ld (hl), ${source.register}` };
+    }
+    if (target.kind === 'reg-indirect' && target.register === 'hl' && source.kind === 'imm') {
+        const value = formatExpression(source.expression, evalContext, 'byte');
+        return value === undefined ? undefined : { text: `ld (hl), ${value}` };
+    }
+    if (target.kind === 'reg8' && source.kind === 'indexed') {
+        const memory = formatIndexedMemory(source.register, source.displacement, evalContext);
+        return memory === undefined ? undefined : { text: `ld ${target.register}, ${memory}` };
     }
-    if (target.kind === 'mem-abs' && source.kind === 'reg8' && source.register === 'a') {
+    if (target.kind === 'indexed' && source.kind === 'reg8') {
+        const memory = formatIndexedMemory(target.register, target.displacement, evalContext);
+        return memory === undefined ? undefined : { text: `ld ${memory}, ${source.register}` };
+    }
+    if (target.kind === 'reg8' && source.kind === 'mem-abs') {
+        return formatLdText(target.register, formatParenthesizedExpression(source.expression, evalContext, 'auto'));
+    }
+    if (target.kind === 'mem-abs' && source.kind === 'reg8') {
         const targetText = formatParenthesizedExpression(target.expression, evalContext, 'auto');
-        return targetText === undefined ? undefined : { text: `ld ${targetText}, a` };
+        return targetText === undefined
+            ? undefined
+            : { text: `ld ${targetText}, ${source.register}` };
+    }
+    if (target.kind === 'mem-abs' && source.kind === 'reg16') {
+        const targetText = formatParenthesizedExpression(target.expression, evalContext, 'auto');
+        return targetText === undefined
+            ? undefined
+            : { text: `ld ${targetText}, ${source.register}` };
+    }
+    if (target.kind === 'mem-abs' && source.kind === 'reg-index16') {
+        const targetText = formatParenthesizedExpression(target.expression, evalContext, 'auto');
+        return targetText === undefined
+            ? undefined
+            : { text: `ld ${targetText}, ${source.register}` };
     }
     return undefined;
 }
@@ -383,6 +447,37 @@ function formatExpression(expression, evalContext, width) {
     if (expression.kind === 'symbol') {
         return expression.name;
     }
+    if (expression.kind === 'type-size') {
+        const value = evaluateLoweredConstant(expression, evalContext);
+        return value === undefined ? expression.typeExpr.name : formatLoweredNumber(value, width);
+    }
+    if (expression.kind === 'current-location') {
+        return '$';
+    }
+    if (expression.kind === 'unary') {
+        const inner = formatExpression(expression.expression, evalContext, width);
+        if (inner === undefined) {
+            return undefined;
+        }
+        switch (expression.operator) {
+            case '+':
+                return inner;
+            case '-':
+                return `-${inner}`;
+            case '~': {
+                const value = evaluateLoweredConstant(expression, evalContext);
+                return value === undefined ? undefined : formatLoweredNumber(value, width);
+            }
+        }
+    }
+    if (expression.kind === 'binary') {
+        const left = formatExpression(expression.left, evalContext, width);
+        const right = formatExpression(expression.right, evalContext, width);
+        if (left === undefined || right === undefined) {
+            return undefined;
+        }
+        return `${left}${expression.operator}${right}`;
+    }
     return undefined;
 }
 function evaluateLoweredConstant(expression, evalContext) {
@@ -391,6 +486,17 @@ function evaluateLoweredConstant(expression, evalContext) {
             return expression.value;
         case 'symbol':
             return evalContext.constants.get(expression.name);
+        case 'type-size': {
+            const constant = evalContext.constants.get(expression.typeExpr.name);
+            if (constant !== undefined) {
+                return constant;
+            }
+            return evaluateExpression(expression, {}, new Map(), silentSpan, [], {
+                currentLocation: 0,
+                layouts: evalContext.layouts,
+                reportUnknown: false,
+            });
+        }
         case 'sizeof':
             return evaluateExpression(expression, {}, new Map(), silentSpan, [], {
                 currentLocation: 0,
@@ -452,6 +558,17 @@ function formatLoweredNumber(value, width) {
     const minWidth = width === 'word' || (width === 'auto' && normalized > 0xff) ? 4 : 2;
     return `$${digits.padStart(minWidth, '0')}`;
 }
+function formatRotateShift(instruction, evalContext) {
+    const operand = formatBitOperand(instruction.operand, evalContext);
+    if (operand === undefined) {
+        return undefined;
+    }
+    const parts = [operand];
+    if (instruction.destination) {
+        parts.push(instruction.destination.register);
+    }
+    return { text: `${instruction.mnemonic} ${parts.join(', ')}` };
+}
 function formatBitOp(instruction, evalContext) {
     const bit = formatLoweredNumber(instruction.bit, 'byte');
     const operand = formatBitOperand(instruction.operand, evalContext);

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

@@ -5,6 +5,14 @@ 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 ?? [];
@@ -16,8 +24,8 @@ export function analyzeRegisterCare(loaded, options) {
             contractMap.set(contract.name, contract);
         }
     }
-    let summaries = buildSummaries(program.routines, contractMap);
     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);
@@ -41,10 +49,14 @@ export function analyzeRegisterCare(loaded, options) {
     const conflicts = analyzed.conflicts;
     const outputCandidates = analyzed.outputCandidates;
     const outputCandidateFixability = buildOutputCandidateFixability(program.routines, outputCandidates, autoFixableCandidateKeys);
-    const outputCandidatesWithFixability = outputCandidates.map((candidate) => ({
-        ...candidate,
-        autoFixable: outputCandidateFixability.get(outputCandidateKey(candidate.file, candidate.line, candidate.column)) ?? false,
-    }));
+    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({
@@ -58,7 +70,7 @@ export function analyzeRegisterCare(loaded, options) {
         }
     }
     if (options.mode === 'strict') {
-        diagnostics.push(...unknownBoundaryDiagnostics(program.directCalls, knownRoutines));
+        diagnostics.push(...unknownBoundaryDiagnostics(program.directBoundaries, knownRoutines));
     }
     const reportModel = {
         entryFile: loaded.program.entryFile,
@@ -67,10 +79,26 @@ export function analyzeRegisterCare(loaded, options) {
         conflicts,
         outputCandidates: outputCandidatesWithFixability,
         ...(options.registerCareProfile !== undefined ? { profile: options.registerCareProfile } : {}),
-        unknownCalls: options.mode === 'off' ? [] : unknownCallList(program.directCalls, knownRoutines),
+        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, summariesByName, outputCandidatesWithFixability, {
+        ? buildAnnotations(loaded, program.routines, summariesForAnnotations, outputCandidatesWithFixability, {
             fixOutputCandidates: options.fixRegisterContracts === true,
             outputCandidateFixability,
             outputCandidateKey,

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;
+}