@jhlagado/azm 0.2.11 → 0.2.13

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/assembly/import-visibility.js

@@ -1,14 +1,22 @@
 import { diagnostic } from '../semantics/diagnostics.js';
 export function validateImportVisibility(items, diagnostics) {
-    const labels = collectLabelVisibility(items);
+    const symbols = collectSymbolVisibility(items);
     for (const item of items) {
-        validateItemReferences(item, labels, diagnostics);
+        validateItemReferences(item, symbols, diagnostics);
     }
 }
-function collectLabelVisibility(items) {
+function collectSymbolVisibility(items) {
     const labels = new Map();
+    const exactSymbols = new Set();
     const importedSourceUnits = importedUnitNames(items);
+    const symbolConflicts = buildSymbolConflictIndex(items);
     for (const item of items) {
+        for (const name of exactSymbolNames(item)) {
+            exactSymbols.add(name);
+        }
+    }
+    for (let index = 0; index < items.length; index += 1) {
+        const item = items[index];
         if (item.kind !== 'label')
             continue;
         labels.set(item.name, {
@@ -16,14 +24,75 @@ function collectLabelVisibility(items) {
             definingSourceUnit: item.span.sourceUnit,
             definingSourceName: item.span.sourceName,
             public: isPublicLabel(item, importedSourceUnits),
+            duplicateName: hasAddressPlanningNameConflict(item.name, symbolConflicts, items, index),
         });
     }
-    return labels;
+    return { labels, exactSymbols };
+}
+function buildSymbolConflictIndex(items) {
+    const exact = new Map();
+    const declarationLower = new Map();
+    for (const item of items) {
+        for (const name of exactSymbolNames(item)) {
+            exact.set(name, (exact.get(name) ?? 0) + 1);
+        }
+        const declarationName = caseInsensitiveDeclarationName(item);
+        if (declarationName !== undefined) {
+            const key = declarationName.toLowerCase();
+            declarationLower.set(key, (declarationLower.get(key) ?? 0) + 1);
+        }
+    }
+    return { exact, declarationLower };
+}
+function hasAddressPlanningNameConflict(labelName, conflicts, items, labelIndex) {
+    return ((conflicts.exact.get(labelName) ?? 0) > 1 ||
+        (conflicts.declarationLower.get(labelName.toLowerCase()) ?? 0) > 0 ||
+        hasReportedEnumMemberConflict(labelName, items, labelIndex));
+}
+function hasReportedEnumMemberConflict(labelName, items, labelIndex) {
+    const lowerName = labelName.toLowerCase();
+    for (let index = 0; index < items.length; index += 1) {
+        const item = items[index];
+        if (item.kind !== 'enum')
+            continue;
+        for (const memberName of qualifiedEnumMemberNames(item)) {
+            if (memberName === labelName)
+                return true;
+            if (index > labelIndex && memberName.toLowerCase() === lowerName)
+                return true;
+        }
+    }
+    return false;
+}
+function exactSymbolNames(item) {
+    switch (item.kind) {
+        case 'label':
+        case 'equ':
+            return [item.name];
+        case 'enum':
+            return qualifiedEnumMemberNames(item);
+        default:
+            return [];
+    }
+}
+function qualifiedEnumMemberNames(item) {
+    return item.kind === 'enum' ? item.members.map((member) => `${item.name}.${member}`) : [];
+}
+function caseInsensitiveDeclarationName(item) {
+    switch (item.kind) {
+        case 'enum':
+        case 'type':
+        case 'type-alias':
+            return item.name;
+        default:
+            return undefined;
+    }
 }
 function importedUnitNames(items) {
     const units = new Set();
     for (const item of items) {
-        if (item.span.sourceRelation === 'import' && item.span.sourceUnit !== undefined) {
+        if (item.span.sourceUnitRelation === 'import' &&
+            item.span.sourceUnit !== undefined) {
             units.add(item.span.sourceUnit);
         }
     }
@@ -34,39 +103,39 @@ function isPublicLabel(item, importedSourceUnits) {
         item.span.sourceUnit === undefined ||
         !importedSourceUnits.has(item.span.sourceUnit));
 }
-function validateItemReferences(item, labels, diagnostics) {
+function validateItemReferences(item, symbols, diagnostics) {
     switch (item.kind) {
         case 'org':
-            validateExpression(item.expression, item.span, labels, diagnostics);
+            validateExpression(item.expression, item.span, symbols, diagnostics);
             return;
         case 'equ':
-            validateExpression(item.expression, item.span, labels, diagnostics);
+            validateExpression(item.expression, item.span, symbols, diagnostics);
             return;
         case 'db':
             for (const value of item.values) {
-                validateDataValue(value, item.span, labels, diagnostics);
+                validateDataValue(value, item.span, symbols, diagnostics);
             }
             return;
         case 'dw':
             for (const value of item.values) {
-                validateExpression(value, item.span, labels, diagnostics);
+                validateExpression(value, item.span, symbols, diagnostics);
             }
             return;
         case 'ds':
-            validateExpression(item.size, item.span, labels, diagnostics);
+            validateExpression(item.size, item.span, symbols, diagnostics);
             if (item.fill !== undefined) {
-                validateExpression(item.fill, item.span, labels, diagnostics);
+                validateExpression(item.fill, item.span, symbols, diagnostics);
             }
             return;
         case 'align':
-            validateExpression(item.alignment, item.span, labels, diagnostics);
+            validateExpression(item.alignment, item.span, symbols, diagnostics);
             return;
         case 'binfrom':
         case 'binto':
-            validateExpression(item.expression, item.span, labels, diagnostics);
+            validateExpression(item.expression, item.span, symbols, diagnostics);
             return;
         case 'instruction':
-            validateInstruction(item.instruction, item.span, labels, diagnostics);
+            validateInstruction(item.instruction, item.span, symbols, diagnostics);
             return;
         case 'label':
         case 'comment':
@@ -78,14 +147,14 @@ function validateItemReferences(item, labels, diagnostics) {
             return;
     }
 }
-function validateDataValue(value, span, labels, diagnostics) {
+function validateDataValue(value, span, symbols, diagnostics) {
     if ('kind' in value && value.kind === 'string-fragment')
         return;
-    validateExpression(value, span, labels, diagnostics);
+    validateExpression(value, span, symbols, diagnostics);
 }
-function validateInstruction(instruction, span, labels, diagnostics) {
+function validateInstruction(instruction, span, symbols, diagnostics) {
     for (const expression of instructionExpressions(instruction)) {
-        validateExpression(expression, span, labels, diagnostics);
+        validateExpression(expression, span, symbols, diagnostics);
     }
 }
 function instructionExpressions(instruction) {
@@ -154,49 +223,55 @@ function operandExpressions(operand) {
             return [];
     }
 }
-function validateExpression(expression, span, labels, diagnostics) {
+function validateExpression(expression, span, symbols, diagnostics) {
     switch (expression.kind) {
         case 'symbol':
-            validateSymbolReference(expression.name, span, labels, diagnostics);
+            validateSymbolReference(expression.name, span, symbols, diagnostics);
             return;
         case 'byte-function':
         case 'unary':
-            validateExpression(expression.expression, span, labels, diagnostics);
+            validateExpression(expression.expression, span, symbols, diagnostics);
             return;
         case 'binary':
-            validateExpression(expression.left, span, labels, diagnostics);
-            validateExpression(expression.right, span, labels, diagnostics);
+            validateExpression(expression.left, span, symbols, diagnostics);
+            validateExpression(expression.right, span, symbols, diagnostics);
             return;
         case 'layout-cast':
-            validateExpression(expression.base, span, labels, diagnostics);
+            validateExpression(expression.base, span, symbols, diagnostics);
             for (const part of expression.path) {
                 if (part.kind === 'index') {
-                    validateExpression(part.expression, span, labels, diagnostics);
+                    validateExpression(part.expression, span, symbols, diagnostics);
                 }
             }
             return;
         case 'number':
         case 'current-location':
-        case 'type-size':
         case 'sizeof':
         case 'offset':
             return;
+        case 'type-size':
+            if (expression.typeExpr.length === undefined) {
+                validateSymbolReference(expression.typeExpr.name, span, symbols, diagnostics);
+            }
+            return;
     }
 }
-function validateSymbolReference(name, referenceSpan, labels, diagnostics) {
-    const label = lookupLabel(labels, name);
-    if (!label || label.public)
+function validateSymbolReference(name, referenceSpan, symbols, diagnostics) {
+    const label = lookupLabel(symbols, name);
+    if (!label || label.duplicateName || label.public)
         return;
     if (referenceSpan.sourceUnit === label.definingSourceUnit)
         return;
     diagnostics.push(diagnostic(referenceSpan, `symbol "${name}" is private to ${label.definingSourceName}; export it with @${label.name} or keep the reference inside that file`));
 }
-function lookupLabel(labels, name) {
-    const direct = labels.get(name);
+function lookupLabel(symbols, name) {
+    const direct = symbols.labels.get(name);
     if (direct)
         return direct;
+    if (symbols.exactSymbols.has(name))
+        return undefined;
     const lowerName = name.toLowerCase();
-    for (const [key, label] of labels) {
+    for (const [key, label] of symbols.labels) {
         if (key.toLowerCase() === lowerName)
             return label;
     }

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;