@jhlagado/azm 0.2.12 → 0.2.14

package/dist/src/api-compile.d.ts

@@ -3,7 +3,7 @@ import { writeHex } from './outputs/write-hex.js';
 import type { AddressRange, Artifact, D8mArtifact, D8mFileEntry, D8mFileSymbol, D8mGenerator, D8mJson, D8mSegment, D8mSymbol, EmittedByteMap, FormatWriters, SymbolEntry, WriteD8mOptions } from './outputs/types.js';
 import type { Diagnostic } from './model/diagnostic.js';
 import type { CaseStyleMode } from './tooling/case-style.js';
-import type { RegisterContractsMode } from './register-contracts/types.js';
+import type { RegisterContractsMode, RegisterContractsPolicy, RegisterContractsReportFormat } from './register-contracts/types.js';
 export { writeHex, defaultFormatWriters };
 export type { AddressRange, Artifact, D8mArtifact, D8mFileEntry, D8mFileSymbol, D8mGenerator, D8mJson, D8mSegment, D8mSymbol, EmittedByteMap, FormatWriters, SymbolEntry, WriteD8mOptions, };
 export type CompileDependencies = CompileNextDependencies;
@@ -30,8 +30,14 @@ export interface CompileNextFunctionOptions {
     readonly registerContracts?: RegisterContractsMode;
     /** @deprecated Use registerContracts. */
     readonly registerCare?: RegisterContractsMode;
+    readonly registerContractsPolicy?: RegisterContractsPolicy;
     readonly emitRegisterReport?: boolean;
+    readonly registerContractsReportFormat?: RegisterContractsReportFormat;
+    readonly registerContractsBaseline?: string;
+    readonly registerContractsRatchet?: boolean;
     readonly emitRegisterInterface?: boolean;
+    readonly emitRegisterInference?: boolean;
+    readonly registerContractsInferenceFormat?: 'json' | 'markdown';
     readonly emitRegisterAnnotations?: boolean;
     readonly fixRegisterContracts?: boolean;
     readonly acceptRegisterOutputCandidates?: string[];

package/dist/src/api-compile.js

@@ -5,12 +5,13 @@ import { runRegisterContracts, shouldAnalyzeRegisterContracts } from './api-regi
 import { analyzeProgramNext, loadProgramNext } from './tooling/api.js';
 import { defaultFormatWriters } from './outputs/index.js';
 import { writeHex } from './outputs/write-hex.js';
+import { registerContractsPolicyModeForFile } from './register-contracts/policy.js';
 import { buildRegisterContractsProgramModel } from './register-contracts/programModel.js';
 function parseUnresolvedSymbolName(message) {
     const match = /^Unresolved symbol "([^"]+)"/.exec(message);
     return match?.[1];
 }
-function isSuppressedUnknownSymbolInRegisterContractsMode(diagnostic, directCalls) {
+function isSuppressedUnknownSymbolInRegisterContractsMode(diagnostic, directCalls, policy, fallbackMode) {
     if (directCalls === undefined || directCalls.length === 0) {
         return false;
     }
@@ -27,7 +28,11 @@ function isSuppressedUnknownSymbolInRegisterContractsMode(diagnostic, directCall
     return directCalls.some((call) => call.target === symbol &&
         call.file === diagnostic.sourceName &&
         call.line === diagnostic.line &&
-        call.column === diagnostic.column);
+        call.column === diagnostic.column &&
+        !isRegisterContractsPolicyOffForFile(call.file, policy, fallbackMode));
+}
+function isRegisterContractsPolicyOffForFile(file, policy, fallbackMode) {
+    return policy !== undefined && registerContractsPolicyModeForFile(file, policy, fallbackMode) === 'off';
 }
 export { writeHex, defaultFormatWriters };
 /**
@@ -56,10 +61,14 @@ export async function compile(entryFile, options = {}, deps = { formats: default
             .directCalls
         : undefined;
     diagnostics.push(...analysis.diagnostics.filter((diagnostic) => analyzeRegisterContractsNow
-        ? !isSuppressedUnknownSymbolInRegisterContractsMode(diagnostic, directCalls)
+        ? !isSuppressedUnknownSymbolInRegisterContractsMode(diagnostic, directCalls, options.registerContractsPolicy, options.registerContracts ?? options.registerCare)
         : true));
     const artifacts = [];
     if (hasErrors(diagnostics)) {
+        if (analyzeRegisterContractsNow && options.emitRegisterReport === true) {
+            const registerContracts = await runRegisterContracts(loaded.loadedProgram, options);
+            artifacts.push(...registerContractsReportArtifacts(registerContracts.artifacts));
+        }
         sortDiagnosticsInPlace(diagnostics);
         return { diagnostics, artifacts };
     }
@@ -76,11 +85,11 @@ export async function compile(entryFile, options = {}, deps = { formats: default
     const program = loaded.loadedProgram.program.files[0]?.items ?? [];
     const assembled = assembleProgram(program);
     diagnostics.push(...assembled.diagnostics.filter((diagnostic) => analyzeRegisterContractsNow
-        ? !isSuppressedUnknownSymbolInRegisterContractsMode(diagnostic, directCalls)
+        ? !isSuppressedUnknownSymbolInRegisterContractsMode(diagnostic, directCalls, options.registerContractsPolicy, options.registerContracts ?? options.registerCare)
         : true));
     sortDiagnosticsInPlace(diagnostics);
     if (hasErrors(diagnostics)) {
-        return { diagnostics, artifacts: [] };
+        return { diagnostics, artifacts: registerContractsReportArtifacts(artifacts) };
     }
     const emittedArtifacts = await emitAssemblyArtifacts({
         entryFile: normalizedEntry,
@@ -100,6 +109,9 @@ export async function compile(entryFile, options = {}, deps = { formats: default
 function hasErrors(diagnostics) {
     return diagnostics.some((diagnostic) => diagnostic.severity === 'error');
 }
+function registerContractsReportArtifacts(artifacts) {
+    return artifacts.filter((artifact) => artifact.kind === 'register-contracts-report');
+}
 function sortDiagnosticsInPlace(diagnostics) {
     dedupeDiagnosticsInPlace(diagnostics);
     diagnostics.sort((left, right) => {

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

@@ -8,10 +8,13 @@ export function shouldAnalyzeRegisterContracts(options) {
     return (registerContractsMode !== 'off' ||
         options.emitRegisterReport === true ||
         options.emitRegisterInterface === true ||
+        options.emitRegisterInference === true ||
         options.emitRegisterAnnotations === true ||
         options.fixRegisterContracts === true ||
+        options.registerContractsPolicy !== undefined ||
         (options.acceptRegisterOutputCandidates?.length ?? 0) > 0 ||
-        (options.registerContractsInterfaces?.length ?? options.registerCareInterfaces?.length ?? 0) > 0);
+        (options.registerContractsInterfaces?.length ?? options.registerCareInterfaces?.length ?? 0) > 0 ||
+        options.registerContractsBaseline !== undefined);
 }
 export async function runRegisterContracts(loadedProgram, options) {
     const diagnostics = [];
@@ -20,10 +23,24 @@ export async function runRegisterContracts(loadedProgram, options) {
     if (hasErrors(diagnostics)) {
         return { diagnostics, artifacts };
     }
+    const baselineReport = await loadBaselineReport(options.registerContractsBaseline, diagnostics);
+    if (hasErrors(diagnostics)) {
+        return { diagnostics, artifacts };
+    }
     const registerContracts = analyzeRegisterContracts(loadedProgram, {
         mode: options.registerContracts ?? options.registerCare ?? 'off',
+        ...(options.registerContractsPolicy !== undefined
+            ? { policy: options.registerContractsPolicy }
+            : {}),
         emitReport: options.emitRegisterReport === true,
+        ...(options.registerContractsReportFormat !== undefined
+            ? { reportFormat: options.registerContractsReportFormat }
+            : {}),
         emitInterface: options.emitRegisterInterface === true,
+        emitInference: options.emitRegisterInference === true,
+        ...(options.registerContractsInferenceFormat !== undefined
+            ? { inferenceFormat: options.registerContractsInferenceFormat }
+            : {}),
         emitAnnotations: options.emitRegisterAnnotations === true || options.fixRegisterContracts === true,
         fixRegisterContracts: options.fixRegisterContracts === true,
         acceptedOutputCandidates: parseAcceptedOutputCandidates(options.acceptRegisterOutputCandidates ?? []),
@@ -33,13 +50,36 @@ export async function runRegisterContracts(loadedProgram, options) {
             }
             : {}),
         ...(interfaceContracts.length > 0 ? { interfaceContracts } : {}),
+        ...(baselineReport !== undefined ? { baselineReport } : {}),
+        ...(options.registerContractsBaseline !== undefined
+            ? { baselineFile: normalize(options.registerContractsBaseline) }
+            : {}),
+        ratchet: options.registerContractsRatchet === true,
     });
     if (registerContracts.reportText !== undefined) {
-        artifacts.push({ kind: 'register-contracts-report', text: registerContracts.reportText });
+        artifacts.push({
+            kind: 'register-contracts-report',
+            ...(registerContracts.reportFormat !== undefined
+                ? { format: registerContracts.reportFormat }
+                : {}),
+            text: registerContracts.reportText,
+            ...(registerContracts.reportJson !== undefined ? { json: registerContracts.reportJson } : {}),
+            ...(registerContracts.findings !== undefined ? { findings: registerContracts.findings } : {}),
+        });
     }
     if (registerContracts.interfaceText !== undefined) {
         artifacts.push({ kind: 'register-contracts-interface', text: registerContracts.interfaceText });
     }
+    if (registerContracts.inferenceText !== undefined) {
+        artifacts.push({
+            kind: 'register-contracts-inference',
+            format: registerContracts.inferenceFormat ?? 'json',
+            text: registerContracts.inferenceText,
+            ...(registerContracts.inferenceJson !== undefined
+                ? { json: registerContracts.inferenceJson }
+                : {}),
+        });
+    }
     if (registerContracts.annotations !== undefined && registerContracts.annotations.length > 0) {
         artifacts.push({
             kind: 'register-contracts-annotations',
@@ -52,6 +92,33 @@ export async function runRegisterContracts(loadedProgram, options) {
     diagnostics.push(...registerContracts.diagnostics);
     return { artifacts, diagnostics };
 }
+async function loadBaselineReport(rawPath, diagnostics) {
+    if (rawPath === undefined)
+        return undefined;
+    const baselinePath = normalize(rawPath);
+    try {
+        const parsed = JSON.parse(await readFile(baselinePath, 'utf8'));
+        if (parsed.format !== 'azm-register-contracts-report' || !Array.isArray(parsed.findings)) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'AZMN_REGISTER_CONTRACTS',
+                sourceName: baselinePath,
+                message: 'Register contracts baseline must be a JSON register-contracts report',
+            });
+            return undefined;
+        }
+        return parsed;
+    }
+    catch (error) {
+        diagnostics.push({
+            severity: 'error',
+            code: 'AZMN_REGISTER_CONTRACTS',
+            sourceName: baselinePath,
+            message: `Unable to read register contracts baseline: ${String(error)}`,
+        });
+        return undefined;
+    }
+}
 async function loadInterfaceContracts(interfaces, diagnostics) {
     const interfaceContracts = [];
     for (const rawInterface of interfaces) {

package/dist/src/api-tooling.d.ts

@@ -4,4 +4,4 @@ export { DiagnosticIds } from './model/diagnostic.js';
 export type { AnalyzeProgramOptions, AnalyzeProgramResult, LoadedProgram, LoadProgramOptions, LoadProgramResult, AnalyzeProgramNextOptions, AnalyzeProgramNextResult, LoadedProgramNext, LoadProgramNextOptions, LoadProgramNextResult, } from './tooling/api.js';
 export type { CaseStyleMode } from './tooling/case-style.js';
 export type { Diagnostic, DiagnosticId, DiagnosticSeverity } from './model/diagnostic.js';
-export type { RegisterCareMode, RegisterCareOutputCandidate, RegisterCareUnit, RegisterContractsMode, RegisterContractsOutputCandidate, RegisterContractsUnit, } from './register-contracts/types.js';
+export type { RegisterCareMode, RegisterCareOutputCandidate, RegisterCareUnit, RegisterContractsMode, RegisterContractsFinding, RegisterContractsFindingKind, RegisterContractsOutputCandidate, RegisterContractsUnit, } from './register-contracts/types.js';

package/dist/src/cli/artifact-files.d.ts

@@ -6,6 +6,7 @@ interface ArtifactPaths {
     readonly asm80: string;
     readonly registerContractsReport: string;
     readonly registerContractsInterface: string;
+    readonly registerContractsInference: string;
 }
 interface ArtifactWriteResult {
     readonly primaryPath?: string;

package/dist/src/cli/artifact-files.js

@@ -57,6 +57,11 @@ function queueRegisterContractsArtifacts(writes, byKind, paths) {
         writes.push(writeTextArtifact(paths.registerContractsInterface, iface.text));
         registerContractsPath ??= paths.registerContractsInterface;
     }
+    const inference = byKind.get('register-contracts-inference');
+    if (inference?.kind === 'register-contracts-inference') {
+        writes.push(writeTextArtifact(paths.registerContractsInference, inference.text));
+        registerContractsPath ??= paths.registerContractsInference;
+    }
     return registerContractsPath;
 }
 function queueRegisterContractsAnnotationArtifacts(writes, byKind) {

package/dist/src/cli/parse-args.d.ts

@@ -1,4 +1,4 @@
-import type { RegisterContractsMode } from '../register-contracts/types.js';
+import type { RegisterContractsInferenceFormat, RegisterContractsMode, RegisterContractsReportFormat } from '../register-contracts/types.js';
 import type { CaseStyleMode } from '../tooling/case-style.js';
 import { cliUsage } from './usage.js';
 export type CliExit = {
@@ -16,7 +16,12 @@ export type CliOptions = {
     caseStyle: CaseStyleMode;
     registerContracts: RegisterContractsMode;
     emitRegisterReport: boolean;
+    registerContractsReportFormat: RegisterContractsReportFormat;
+    registerContractsBaseline: string | undefined;
+    registerContractsRatchet: boolean;
     emitRegisterInterface: boolean;
+    emitRegisterInference: boolean;
+    registerContractsInferenceFormat: RegisterContractsInferenceFormat;
     emitRegisterAnnotations: boolean;
     fixRegisterContracts: boolean;
     acceptRegisterOutputCandidates: string[];

package/dist/src/cli/parse-args.js

@@ -38,6 +38,20 @@ const BOOLEAN_FLAG_ACTIONS = [
             state.emitRegisterInterface = true;
         },
     },
+    {
+        flags: ['--reg-infer'],
+        apply: (state) => {
+            state.emitRegisterInference = true;
+        },
+    },
+    {
+        flags: ['--reg-ratchet'],
+        apply: (state) => {
+            state.registerContractsRatchet = true;
+            state.emitRegisterReport = true;
+            state.registerContractsReportFormat = 'json';
+        },
+    },
     {
         flags: ['--fix'],
         apply: (state) => {
@@ -67,7 +81,12 @@ function createDefaultCliState() {
         caseStyle: 'off',
         registerContracts: 'off',
         emitRegisterReport: false,
+        registerContractsReportFormat: 'text',
+        registerContractsBaseline: undefined,
+        registerContractsRatchet: false,
         emitRegisterInterface: false,
+        emitRegisterInference: false,
+        registerContractsInferenceFormat: 'json',
         emitRegisterAnnotations: false,
         fixRegisterContracts: false,
         acceptRegisterOutputCandidates: [],
@@ -199,6 +218,37 @@ function parseRegisterProfileArg(arg, argv, indexRef, state) {
     state.registerContractsProfile = parsed.value;
     return true;
 }
+function parseRegisterReportFormatArg(arg, argv, indexRef, state) {
+    const parsed = readMatchedFlagValue(arg, argv, indexRef, ['--reg-report-format']);
+    if (!parsed)
+        return false;
+    if (parsed.value !== 'text' && parsed.value !== 'json') {
+        fail(`Unsupported ${parsed.flag} "${parsed.value}" (expected text|json)`);
+    }
+    state.emitRegisterReport = true;
+    state.registerContractsReportFormat = parsed.value;
+    return true;
+}
+function parseRegisterInferenceFormatArg(arg, argv, indexRef, state) {
+    const parsed = readMatchedFlagValue(arg, argv, indexRef, ['--reg-infer-format']);
+    if (!parsed)
+        return false;
+    if (parsed.value !== 'json' && parsed.value !== 'markdown') {
+        fail(`Unsupported ${parsed.flag} "${parsed.value}" (expected json|markdown)`);
+    }
+    state.emitRegisterInference = true;
+    state.registerContractsInferenceFormat = parsed.value;
+    return true;
+}
+function parseRegisterBaselineArg(arg, argv, indexRef, state) {
+    const parsed = readMatchedFlagValue(arg, argv, indexRef, ['--reg-baseline']);
+    if (!parsed)
+        return false;
+    state.registerContractsBaseline = parsed.value;
+    state.emitRegisterReport = true;
+    state.registerContractsReportFormat = 'json';
+    return true;
+}
 function parseRegisterInterfaceArg(arg, argv, indexRef, state) {
     if (arg !== '--interface' && !arg.startsWith('--interface='))
         return false;
@@ -264,7 +314,12 @@ function finalizeCliOptions(state) {
         caseStyle: state.caseStyle,
         registerContracts: state.registerContracts,
         emitRegisterReport: state.emitRegisterReport,
+        registerContractsReportFormat: state.registerContractsBaseline !== undefined ? 'json' : state.registerContractsReportFormat,
+        registerContractsBaseline: state.registerContractsBaseline,
+        registerContractsRatchet: state.registerContractsRatchet,
         emitRegisterInterface: state.emitRegisterInterface,
+        emitRegisterInference: state.emitRegisterInference,
+        registerContractsInferenceFormat: state.registerContractsInferenceFormat,
         emitRegisterAnnotations: state.emitRegisterAnnotations,
         fixRegisterContracts: state.fixRegisterContracts,
         acceptRegisterOutputCandidates: state.acceptRegisterOutputCandidates,
@@ -299,6 +354,7 @@ function emitsRegisterContractsArtifact(state) {
         state.registerContracts !== 'off',
         state.emitRegisterReport,
         state.emitRegisterInterface,
+        state.emitRegisterInference,
         state.emitRegisterAnnotations,
         state.fixRegisterContracts,
         state.acceptRegisterOutputCandidates.length > 0,
@@ -324,6 +380,9 @@ const VALUE_ARG_PARSERS = [
     (arg, { argv, indexRef, state }) => parseDirectiveAliasFileArg(arg, argv, indexRef, state),
     (arg, { argv, indexRef, state }) => parseRegisterContractsArg(arg, argv, indexRef, state),
     (arg, { argv, indexRef, state }) => parseRegisterProfileArg(arg, argv, indexRef, state),
+    (arg, { argv, indexRef, state }) => parseRegisterReportFormatArg(arg, argv, indexRef, state),
+    (arg, { argv, indexRef, state }) => parseRegisterInferenceFormatArg(arg, argv, indexRef, state),
+    (arg, { argv, indexRef, state }) => parseRegisterBaselineArg(arg, argv, indexRef, state),
     (arg, { argv, indexRef, state }) => parseAcceptOutputArg(arg, argv, indexRef, state),
     (arg, { argv, indexRef, state }) => parseRegisterInterfaceArg(arg, argv, indexRef, state),
     (arg, { argv, indexRef, state }) => parseIncludeArg(arg, argv, indexRef, state),

package/dist/src/cli/run.js

@@ -19,11 +19,11 @@ export async function runCli(argv) {
         }
         if (sortedDiagnostics.some((diagnostic) => diagnostic.severity === 'error')) {
             if (compileResult.artifacts.length > 0) {
-                await writeArtifacts(base, compileResult.artifacts, parsed.outputType);
+                await writeArtifacts(base, compileResult.artifacts, parsed.outputType, parsed.registerContractsReportFormat);
             }
             return 1;
         }
-        const primaryPath = await writeArtifacts(base, compileResult.artifacts, parsed.outputType);
+        const primaryPath = await writeArtifacts(base, compileResult.artifacts, parsed.outputType, parsed.registerContractsReportFormat);
         if (primaryPath !== undefined) {
             process.stdout.write(primaryPath);
         }

package/dist/src/cli/usage.js

@@ -12,7 +12,12 @@ export function cliUsage() {
         '      --register-contracts <m> Register contracts mode: off|audit|warn|error|strict',
         '      --rc <m>           Register contracts mode alias for --register-contracts',
         '      --reg-report       Emit register contracts report artifact',
+        '      --reg-report-format <f> Report format: text|json (default: text)',
+        '      --reg-baseline <f> Compare against a JSON register contracts report',
+        '      --reg-ratchet      Fail if register contract findings increase',
         '      --reg-interface     Emit inferred register contracts interface (.asmi)',
+        '      --reg-infer         Emit inferred register contracts review artifact',
+        '      --reg-infer-format <f> Inference format: json|markdown (default: json)',
         '      --contracts        Rewrite source with inferred register contracts',
         '      --fix              Enable contract rewrite and conservative fixes',
         '      --accept-out <x>   Accept register contracts output candidates',

package/dist/src/cli/write-artifacts.d.ts

@@ -17,5 +17,5 @@ export declare function compareDiagnosticsForCli(a: {
     message: string;
 }): number;
 export declare function artifactBase(entryFile: string, outputType: 'hex' | 'bin', outputPath?: string): string;
-export declare function writeArtifacts(base: string, artifacts: readonly Artifact[], outputType: 'hex' | 'bin'): Promise<string | undefined>;
+export declare function writeArtifacts(base: string, artifacts: readonly Artifact[], outputType: 'hex' | 'bin', registerContractsReportFormat?: 'text' | 'json'): Promise<string | undefined>;
 export declare function buildCompileOptions(parsed: CliOptions, base: string): CompileNextFunctionOptions;

package/dist/src/cli/write-artifacts.js

@@ -46,14 +46,20 @@ export function artifactBase(entryFile, outputType, outputPath) {
     const entryExt = extname(resolvedEntry);
     return entryExt.length > 0 ? resolvedEntry.slice(0, -entryExt.length) : resolvedEntry;
 }
-export async function writeArtifacts(base, artifacts, outputType) {
+export async function writeArtifacts(base, artifacts, outputType, registerContractsReportFormat = 'text') {
+    const registerContractsReportExt = registerContractsReportFormat === 'json' ? 'json' : 'txt';
+    const inference = artifacts.find((artifact) => artifact.kind === 'register-contracts-inference');
+    const registerContractsInferenceExt = inference?.kind === 'register-contracts-inference' && inference.format === 'markdown'
+        ? 'md'
+        : 'json';
     const result = await writeArtifactFiles(artifacts, {
         hex: `${base}.hex`,
         bin: `${base}.bin`,
         d8m: `${base}.d8.json`,
         asm80: `${base}.z80`,
-        registerContractsReport: `${base}.regcontracts.txt`,
+        registerContractsReport: `${base}.regcontracts.${registerContractsReportExt}`,
         registerContractsInterface: `${base}.asmi`,
+        registerContractsInference: `${base}.regcontracts.inference.${registerContractsInferenceExt}`,
     }, outputType);
     return result.primaryPath ?? result.registerContractsPath;
 }
@@ -70,7 +76,14 @@ export function buildCompileOptions(parsed, base) {
         caseStyle: parsed.caseStyle,
         registerContracts: parsed.registerContracts,
         emitRegisterReport: parsed.emitRegisterReport,
+        registerContractsReportFormat: parsed.registerContractsReportFormat,
+        ...(parsed.registerContractsBaseline !== undefined
+            ? { registerContractsBaseline: parsed.registerContractsBaseline }
+            : {}),
+        registerContractsRatchet: parsed.registerContractsRatchet,
         emitRegisterInterface: parsed.emitRegisterInterface,
+        emitRegisterInference: parsed.emitRegisterInference,
+        registerContractsInferenceFormat: parsed.registerContractsInferenceFormat,
         emitRegisterAnnotations: parsed.emitRegisterAnnotations,
         fixRegisterContracts: parsed.fixRegisterContracts,
         acceptRegisterOutputCandidates: parsed.acceptRegisterOutputCandidates,

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

@@ -127,7 +127,18 @@ function parseOpBodyTemplates(line, paramNames, diagnostics, parseOptions) {
                     kind: 'label',
                     name: label.name,
                     ...(label.isEntry ? { isEntry: true } : {}),
-                    span: { sourceName: segmentLine.sourceName, line: segmentLine.line, column: label.labelColumn },
+                    span: {
+                        sourceName: segmentLine.sourceName,
+                        line: segmentLine.line,
+                        column: label.labelColumn,
+                        ...(segmentLine.sourceUnit !== undefined ? { sourceUnit: segmentLine.sourceUnit } : {}),
+                        ...(segmentLine.sourceRelation !== undefined
+                            ? { sourceRelation: segmentLine.sourceRelation }
+                            : {}),
+                        ...(segmentLine.sourceUnitRelation !== undefined
+                            ? { sourceUnitRelation: segmentLine.sourceUnitRelation }
+                            : {}),
+                    },
                 },
             ],
         }),

package/dist/src/index.d.ts

@@ -11,5 +11,5 @@ export { compile, defaultFormatWriters, writeHex } from './api-compile.js';
 export type { AddressRange, Artifact, CompileDependencies, CompileFunctionOptions, CompileResult, CompileNextDependencies, CompileNextFunctionOptions, EmittedByteMap, FormatWriters, CompileNextResult as CompileNextProgramResult, } from './api-compile.js';
 export type { AnalyzeProgramOptions, AnalyzeProgramResult, LoadProgramOptions, LoadProgramResult, LoadedProgram, AnalyzeProgramNextOptions, AnalyzeProgramNextResult, LoadProgramNextOptions, LoadProgramNextResult, LoadedProgramNext, } from './tooling/api.js';
 export type { CaseStyleMode } from './tooling/case-style.js';
-export type { RegisterCareMode, RegisterCareOutputCandidate, RegisterCareUnit, RegisterContractsMode, RegisterContractsOutputCandidate, RegisterContractsUnit, } from './register-contracts/types.js';
+export type { RegisterCareMode, RegisterCareOutputCandidate, RegisterCareUnit, RegisterContractsMode, RegisterContractsFinding, RegisterContractsFindingKind, RegisterContractsInferenceFormat, RegisterContractsInferenceModel, RegisterContractsInferenceRoutine, RegisterContractsOutputCandidate, RegisterContractsPolicy, RegisterContractsPolicyMode, RegisterContractsReportFormat, RegisterContractsUnit, } from './register-contracts/types.js';
 export type { D8mArtifact, D8mGenerator, D8mJson, D8mFileEntry, D8mFileSymbol, D8mSegment, D8mSymbol, SymbolEntry, WriteD8mOptions, } from './outputs/types.js';

package/dist/src/outputs/types.d.ts

@@ -1,4 +1,5 @@
 import type { SourceItem } from '../model/source-item.js';
+import type { RegisterContractsFinding, RegisterContractsInferenceFormat, RegisterContractsInferenceModel, RegisterContractsJsonReportModel, RegisterContractsReportFormat } from '../register-contracts/types.js';
 /** Half-open address range in the Z80 16-bit address space. */
 export interface AddressRange {
     /** Inclusive start address. */
@@ -54,7 +55,10 @@ export interface HexArtifact {
 export interface RegisterContractsReportArtifact {
     kind: 'register-contracts-report';
     path?: string;
+    format?: RegisterContractsReportFormat;
     text: string;
+    json?: RegisterContractsJsonReportModel;
+    findings?: RegisterContractsFinding[];
 }
 /** @deprecated Use RegisterContractsReportArtifact. */
 export type RegisterCareReportArtifact = RegisterContractsReportArtifact;
@@ -66,6 +70,14 @@ export interface RegisterContractsInterfaceArtifact {
 }
 /** @deprecated Use RegisterContractsInterfaceArtifact. */
 export type RegisterCareInterfaceArtifact = RegisterContractsInterfaceArtifact;
+/** In-memory inferred register contracts review artifact. */
+export interface RegisterContractsInferenceArtifact {
+    kind: 'register-contracts-inference';
+    path?: string;
+    format: RegisterContractsInferenceFormat;
+    text: string;
+    json?: RegisterContractsInferenceModel;
+}
 /** In-memory register contracts source annotation artifact. */
 export interface RegisterContractsAnnotationsArtifact {
     kind: 'register-contracts-annotations';
@@ -166,7 +178,7 @@ export interface WriteD8mOptions {
 }
 export interface WriteAsm80Options {
 }
-export type Artifact = BinArtifact | HexArtifact | D8mArtifact | Asm80Artifact | RegisterContractsReportArtifact | RegisterContractsInterfaceArtifact | RegisterContractsAnnotationsArtifact;
+export type Artifact = BinArtifact | HexArtifact | D8mArtifact | Asm80Artifact | RegisterContractsReportArtifact | RegisterContractsInterfaceArtifact | RegisterContractsInferenceArtifact | RegisterContractsAnnotationsArtifact;
 /** Writer contract used by the compile API. */
 export interface FormatWriters {
     writeHex(map: EmittedByteMap, symbols: readonly SymbolEntry[], opts?: WriteHexOptions): HexArtifact;

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

@@ -1,6 +1,6 @@
 import type { Diagnostic } from '../model/diagnostic.js';
 import { unknownCallList } from './summaries.js';
-import type { AnalyzeRegisterContractsOptions, RegisterContractsOutputCandidate, RegisterContractsReportModel, RegisterContractsRoutine, RegisterContractsUnit, RoutineSummary } from './types.js';
+import type { AnalyzeRegisterContractsOptions, RegisterContractsDirectCall, RegisterContractsFinding, 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[]): {
@@ -14,12 +14,17 @@ export declare function diagnosticsForConflicts(conflicts: readonly {
     message: string;
 }[], mode: AnalyzeRegisterContractsOptions['mode']): Diagnostic[];
 export declare function strictStackDiagnostics(routines: readonly RegisterContractsRoutine[], summaries: readonly RoutineSummary[]): Diagnostic[];
+export declare function strictStackFindings(routines: readonly RegisterContractsRoutine[], summaries: readonly RoutineSummary[]): RegisterContractsFinding[];
+export declare function unknownBoundaryFindings(directBoundaries: readonly RegisterContractsDirectCall[], knownRoutines: ReadonlySet<string>): RegisterContractsFinding[];
+export declare function diagnosticsForFindings(findings: readonly RegisterContractsFinding[], mode: AnalyzeRegisterContractsOptions['mode']): 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[];
+    findings: readonly RegisterContractsFinding[];
+    suppressedFindings?: RegisterContractsReportModel['suppressedFindings'];
     conflicts: RegisterContractsReportModel['conflicts'];
     outputCandidates: readonly RegisterContractsOutputCandidate[];
     profile: AnalyzeRegisterContractsOptions['registerContractsProfile'];

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

@@ -24,6 +24,7 @@ export function outputCandidatesWithFixability(routines, outputCandidates) {
             const autoFixable = outputCandidateFixability.get(outputCandidateKey(candidate.file, candidate.line, candidate.column)) ?? false;
             return {
                 ...candidate,
+                kind: 'output_candidate',
                 autoFixable,
                 message: candidateMessageWithFixability(candidate, autoFixable),
             };
@@ -63,6 +64,68 @@ export function strictStackDiagnostics(routines, summaries) {
     }
     return diagnostics;
 }
+export function strictStackFindings(routines, summaries) {
+    const routinesByName = new Map(routines.map((routine) => [routine.name, routine]));
+    const findings = [];
+    for (const summary of summaries) {
+        const routine = routinesByName.get(summary.name);
+        if (routine === undefined)
+            continue;
+        const stackIssues = strictStackIssueText(summary);
+        if (stackIssues === undefined)
+            continue;
+        findings.push({
+            kind: 'unknown_control_flow',
+            routine: summary.name,
+            stackBalanced: summary.stackBalanced,
+            ...(summary.hasUnknownStackEffect !== undefined
+                ? { hasUnknownStackEffect: summary.hasUnknownStackEffect }
+                : {}),
+            file: routine.span.file,
+            line: routine.span.start.line,
+            column: routine.span.start.column,
+            ...(routine.span.sourceUnit !== undefined ? { sourceUnit: routine.span.sourceUnit } : {}),
+            ...(routine.span.sourceRelation !== undefined
+                ? { sourceRelation: routine.span.sourceRelation }
+                : {}),
+            ...(routine.span.sourceUnitRelation !== undefined
+                ? { sourceUnitRelation: routine.span.sourceUnitRelation }
+                : {}),
+            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 findings;
+}
+export function unknownBoundaryFindings(directBoundaries, knownRoutines) {
+    return directBoundaries
+        .filter((boundary) => !knownRoutines.has(boundary.target))
+        .map((boundary) => ({
+        kind: 'missing_callee_contract',
+        callTarget: boundary.target,
+        subject: boundary.subject,
+        file: boundary.file,
+        line: boundary.line,
+        column: boundary.column,
+        ...(boundary.sourceUnit !== undefined ? { sourceUnit: boundary.sourceUnit } : {}),
+        ...(boundary.sourceRelation !== undefined ? { sourceRelation: boundary.sourceRelation } : {}),
+        ...(boundary.sourceUnitRelation !== undefined
+            ? { sourceUnitRelation: boundary.sourceUnitRelation }
+            : {}),
+        message: `Register contracts cannot prove ${boundary.subject}; add a routine body or .asmi extern contract.`,
+    }));
+}
+export function diagnosticsForFindings(findings, mode) {
+    if (mode === 'audit')
+        return [];
+    return findings.map((finding) => ({
+        severity: mode === 'error' || mode === 'strict' ? 'error' : 'warning',
+        code: 'AZMN_REGISTER_CONTRACTS',
+        sourceName: finding.file,
+        line: finding.line,
+        column: finding.column,
+        message: finding.message,
+    }));
+}
 function strictStackIssueText(summary) {
     const issues = [];
     if (!summary.stackBalanced)
@@ -99,6 +162,10 @@ export function buildRegisterContractsReportModel(input) {
         entryFile: input.entryFile,
         mode: input.mode,
         summaries: [...input.summaries, ...input.profileSummaries],
+        findings: [...input.findings],
+        ...(input.suppressedFindings !== undefined && input.suppressedFindings.length > 0
+            ? { suppressedFindings: [...input.suppressedFindings] }
+            : {}),
         conflicts: [...input.conflicts],
         outputCandidates: [...input.outputCandidates],
         ...(input.profile !== undefined ? { profile: input.profile } : {}),

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

@@ -1,11 +1,18 @@
 import type { Diagnostic } from '../model/diagnostic.js';
 import type { SourceItem } from '../model/source-item.js';
-import type { AnalyzeRegisterContractsOptions, RegisterContractsAnnotationFile, RegisterContractsOutputCandidate } from './types.js';
+import type { AnalyzeRegisterContractsOptions, RegisterContractsFinding, RegisterContractsAnnotationFile, RegisterContractsJsonReportModel, RegisterContractsOutputCandidate } from './types.js';
+import { buildRegisterContractsInference } from './report.js';
 interface AnalyzeRegisterContractsResult {
     diagnostics: Diagnostic[];
+    findings?: RegisterContractsFinding[];
     outputCandidates?: RegisterContractsOutputCandidate[];
     reportText?: string;
+    reportJson?: RegisterContractsJsonReportModel;
+    reportFormat?: 'text' | 'json';
     interfaceText?: string;
+    inferenceText?: string;
+    inferenceJson?: ReturnType<typeof buildRegisterContractsInference>;
+    inferenceFormat?: 'json' | 'markdown';
     annotations?: readonly RegisterContractsAnnotationFile[];
     unknownCalls?: string[];
 }