@jhlagado/azm 0.2.11 → 0.2.13

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

@@ -1,15 +1,19 @@
 import { buildRegisterContractsProgramModel } from './programModel.js';
+import { registerContractsPolicyModeForFile } from './policy.js';
 import { buildRoutineContracts, parseSmartComments } from './smartComments.js';
-import { renderRegisterContractsInterface, renderRegisterContractsReport } from './report.js';
+import { renderRegisterContractsInterface, buildRegisterContractsJsonReport, buildRegisterContractsInference, renderRegisterContractsInferenceMarkdown, renderRegisterContractsJsonReport, renderRegisterContractsReport, } from './report.js';
+import { compareRegisterContractsBaseline } from './ratchet.js';
 import { findCallerOutputCandidateObservations, findRegisterContractsConflicts, } from './liveness.js';
 import { buildAnnotations } from './annotations.js';
-import { autoAcceptedOutputCandidateMap, buildRegisterContractsReportModel, diagnosticsForConflicts, knownRoutineNames, outputCandidatesWithFixability, strictStackDiagnostics, summariesForAnnotations, } from './analyze-helpers.js';
-import { buildProfileSummaries, buildSummaries, buildSummaryByName, outputCandidateKey, unknownBoundaryDiagnostics, withAcceptedOutputs, } from './summaries.js';
+import { autoAcceptedOutputCandidateMap, buildRegisterContractsReportModel, diagnosticsForFindings, knownRoutineNames, outputCandidatesWithFixability, strictStackFindings, summariesForAnnotations, unknownBoundaryFindings, } from './analyze-helpers.js';
+import { buildProfileSummaries, buildSummaries, buildSummaryByName, outputCandidateKey, withAcceptedOutputs, } from './summaries.js';
 export function analyzeRegisterContracts(loaded, options) {
     const file = loaded.program.files[0];
     const items = file?.items ?? [];
     const program = buildRegisterContractsProgramModel(items);
     const smartComments = parseSmartComments(loaded.sourceLineComments);
+    const suppressionSyntaxDiagnostics = malformedSuppressionDiagnostics(loaded.sourceLineComments, options.mode, options.policy);
+    const suppressions = registerContractsSuppressions(smartComments);
     const contractMap = buildRoutineContracts(smartComments, program.routines, loaded.sourceTexts);
     if (options.interfaceContracts !== undefined) {
         for (const contract of options.interfaceContracts) {
@@ -22,12 +26,28 @@ export function analyzeRegisterContracts(loaded, options) {
     let summariesByName = buildSummaryByName(program.routines, summaries, profileSummaries);
     const knownRoutines = knownRoutineNames(program.routines, contractMap.keys(), options.registerContractsProfile);
     const shouldBuildOutputCandidates = options.mode !== 'off' ||
+        options.policy !== undefined ||
         options.emitAnnotations === true ||
-        options.fixRegisterContracts === true;
+        options.fixRegisterContracts === true ||
+        options.emitInference === true;
     const outputCandidates = shouldBuildOutputCandidates
         ? findCallerOutputCandidateObservations(program.routines, summariesByName)
         : [];
-    const autoAcceptedOutputs = autoAcceptedOutputCandidateMap(program.routines, outputCandidates, loaded.sourceTexts);
+    const suppressedOutputCandidateKeys = new Set(outputCandidates
+        .filter((candidate) => isSuppressedFinding(candidate, 'output_candidate', suppressions))
+        .map((candidate) => findingKey({
+        kind: 'output_candidate',
+        file: candidate.file,
+        line: candidate.line,
+        column: candidate.column,
+    })));
+    const outputCandidatesForPromotion = outputCandidates.filter((candidate) => !suppressedOutputCandidateKeys.has(findingKey({
+        kind: 'output_candidate',
+        file: candidate.file,
+        line: candidate.line,
+        column: candidate.column,
+    })));
+    const autoAcceptedOutputs = autoAcceptedOutputCandidateMap(program.routines, outputCandidatesForPromotion, loaded.sourceTexts);
     if (autoAcceptedOutputs.size > 0) {
         summaries = withAcceptedOutputs(summaries, autoAcceptedOutputs);
         summariesByName = buildSummaryByName(program.routines, summaries, profileSummaries);
@@ -35,39 +55,356 @@ export function analyzeRegisterContracts(loaded, options) {
     const conflicts = shouldBuildOutputCandidates
         ? program.routines.flatMap((routine) => findRegisterContractsConflicts(routine, summariesByName, smartComments))
         : [];
-    const { outputCandidates: outputCandidatesWithAutoFixability, outputCandidateFixability } = outputCandidatesWithFixability(program.routines, outputCandidates);
-    const diagnostics = diagnosticsForConflicts(conflicts, options.mode);
-    if (options.mode === 'strict') {
-        diagnostics.push(...unknownBoundaryDiagnostics(program.directBoundaries, knownRoutines, 'error'));
-        diagnostics.push(...strictStackDiagnostics(program.routines, summaries));
+    const { outputCandidates: outputCandidatesWithAutoFixability, outputCandidateFixability } = outputCandidatesWithFixability(program.routines, outputCandidatesForPromotion);
+    const { outputCandidates: allOutputCandidatesWithAutoFixability } = outputCandidatesWithFixability(program.routines, outputCandidates);
+    const diagnostics = [...suppressionSyntaxDiagnostics];
+    const unknownFindings = unknownBoundaryFindings(program.directBoundaries, knownRoutines);
+    const stackFindings = strictStackFindings(program.routines, summaries);
+    const scopedBoundaryFindings = scopedBoundaryContractFindings({
+        directBoundaries: program.directBoundaries,
+        routines: program.routines,
+        contractMap,
+        summariesByName,
+        profileSummaryNames: new Set(profileSummaries.map((summary) => summary.name)),
+        policy: options.policy,
+        mode: options.mode,
+    });
+    const findings = options.mode === 'off' && options.policy === undefined
+        ? []
+        : [
+            ...conflicts.map((conflict) => ({
+                kind: conflict.kind ?? 'definite_contract_violation',
+                callTarget: conflict.callTarget,
+                file: conflict.file,
+                line: conflict.line,
+                column: conflict.column,
+                ...(conflict.sourceUnit !== undefined ? { sourceUnit: conflict.sourceUnit } : {}),
+                ...(conflict.sourceRelation !== undefined
+                    ? { sourceRelation: conflict.sourceRelation }
+                    : {}),
+                ...(conflict.sourceUnitRelation !== undefined
+                    ? { sourceUnitRelation: conflict.sourceUnitRelation }
+                    : {}),
+                ...(conflict.routine !== undefined ? { routine: conflict.routine } : {}),
+                carriers: conflict.carriers,
+                message: conflict.message,
+            })),
+            ...unknownFindings,
+            ...stackFindings,
+            ...outputCandidatesWithAutoFixability.map((candidate) => {
+                return {
+                    kind: 'output_candidate',
+                    routine: candidate.routine,
+                    file: candidate.file,
+                    line: candidate.line,
+                    column: candidate.column,
+                    ...(candidate.sourceUnit !== undefined ? { sourceUnit: candidate.sourceUnit } : {}),
+                    ...(candidate.sourceRelation !== undefined
+                        ? { sourceRelation: candidate.sourceRelation }
+                        : {}),
+                    ...(candidate.sourceUnitRelation !== undefined
+                        ? { sourceUnitRelation: candidate.sourceUnitRelation }
+                        : {}),
+                    carriers: candidate.carriers,
+                    message: candidate.message,
+                    ...(candidate.autoFixable !== undefined ? { autoFixable: candidate.autoFixable } : {}),
+                };
+            }),
+            ...scopedBoundaryFindings,
+        ];
+    const { activeFindings, suppressedFindings: directlySuppressedFindings } = applyRegisterContractsSuppressions(findings, suppressions);
+    const suppressedOutputCandidateFindings = allOutputCandidatesWithAutoFixability
+        .filter((candidate) => suppressedOutputCandidateKeys.has(findingKey({ ...candidate, kind: 'output_candidate' })))
+        .map((candidate) => {
+        const suppression = suppressions.find((item) => item.file === candidate.file &&
+            item.line === candidate.line &&
+            item.findingKind === 'output_candidate');
+        if (suppression === undefined)
+            return undefined;
+        return {
+            suppression,
+            finding: {
+                kind: 'output_candidate',
+                routine: candidate.routine,
+                file: candidate.file,
+                line: candidate.line,
+                column: candidate.column,
+                ...(candidate.sourceUnit !== undefined ? { sourceUnit: candidate.sourceUnit } : {}),
+                ...(candidate.sourceRelation !== undefined ? { sourceRelation: candidate.sourceRelation } : {}),
+                ...(candidate.sourceUnitRelation !== undefined
+                    ? { sourceUnitRelation: candidate.sourceUnitRelation }
+                    : {}),
+                carriers: candidate.carriers,
+                message: candidate.message,
+                ...(candidate.autoFixable !== undefined ? { autoFixable: candidate.autoFixable } : {}),
+            },
+        };
+    })
+        .filter((item) => item !== undefined);
+    const suppressedFindings = [
+        ...directlySuppressedFindings,
+        ...suppressedOutputCandidateFindings,
+    ];
+    const activeOutputCandidates = outputCandidatesWithAutoFixability.filter((candidate) => !suppressedOutputCandidateKeys.has(findingKey({ ...candidate, kind: 'output_candidate' })));
+    const activeConflictFindings = activeFindings.filter((finding) => finding.kind === 'definite_contract_violation' || finding.kind === 'flag_lifetime_risk');
+    if (options.policy !== undefined) {
+        diagnostics.push(...diagnosticsForScopedPolicy(activeFindings, options.policy, options.mode));
+    }
+    else if (options.mode === 'strict') {
+        diagnostics.push(...diagnosticsForFindings(activeConflictFindings, options.mode));
+        diagnostics.push(...diagnosticsForFindings(activeFindings.filter((finding) => finding.kind === 'missing_callee_contract' || finding.kind === 'unknown_control_flow'), 'strict'));
+    }
+    else {
+        diagnostics.push(...diagnosticsForFindings(activeConflictFindings, options.mode));
     }
     const reportModel = buildRegisterContractsReportModel({
         entryFile: loaded.program.entryFile,
         mode: options.mode,
         summaries,
         profileSummaries,
-        conflicts,
-        outputCandidates: outputCandidatesWithAutoFixability,
+        findings: activeFindings,
+        ...(suppressedFindings.length > 0 ? { suppressedFindings } : {}),
+        conflicts: conflicts.filter((conflict) => activeConflictFindings.some((finding) => finding.file === conflict.file &&
+            finding.line === conflict.line &&
+            finding.column === conflict.column &&
+            'callTarget' in finding &&
+            finding.callTarget === conflict.callTarget)),
+        outputCandidates: activeOutputCandidates,
         profile: options.registerContractsProfile,
         directBoundaries: program.directBoundaries,
         knownRoutines,
     });
-    const summariesForAnnotationsByName = summariesForAnnotations(summariesByName, outputCandidatesWithAutoFixability);
+    if (options.baselineReport !== undefined) {
+        const currentJson = buildRegisterContractsJsonReport(reportModel);
+        const ratchet = compareRegisterContractsBaseline(currentJson, options.baselineReport, options.baselineFile);
+        reportModel.ratchet = ratchet;
+        if (options.ratchet === true) {
+            for (const entry of ratchet.newFindings) {
+                diagnostics.push({
+                    severity: 'error',
+                    code: 'AZMN_REGISTER_CONTRACTS',
+                    sourceName: entry.finding.location.file,
+                    line: entry.finding.location.line,
+                    column: entry.finding.location.column,
+                    message: `Register contract ratchet found new ${entry.finding.kind}: ${entry.finding.message}`,
+                });
+            }
+            for (const entry of ratchet.changedFindings) {
+                diagnostics.push({
+                    severity: 'error',
+                    code: 'AZMN_REGISTER_CONTRACTS',
+                    sourceName: entry.current.location.file,
+                    line: entry.current.location.line,
+                    column: entry.current.location.column,
+                    message: `Register contract ratchet found changed ${entry.current.kind}: ${entry.current.message}`,
+                });
+            }
+        }
+    }
+    const summariesForAnnotationsByName = summariesForAnnotations(summariesByName, activeOutputCandidates);
     const annotations = options.emitAnnotations
-        ? buildAnnotations(loaded, program.routines, summariesForAnnotationsByName, outputCandidatesWithAutoFixability, {
+        ? buildAnnotations(loaded, program.routines, summariesForAnnotationsByName, activeOutputCandidates, {
             fixOutputCandidates: options.fixRegisterContracts === true,
             outputCandidateFixability,
             outputCandidateKey,
         })
         : [];
+    const renderedJsonReport = options.emitReport && (options.reportFormat ?? 'text') === 'json'
+        ? renderRegisterContractsJsonReport(reportModel)
+        : undefined;
+    const canonicalSummariesByName = new Map(summaries.map((summary) => [summary.name, summary]));
+    const activeOutputCandidatesForInference = activeOutputCandidates.map((candidate) => {
+        const canonicalName = summariesByName.get(candidate.routine)?.name;
+        return canonicalName === undefined || canonicalName === candidate.routine
+            ? candidate
+            : { ...candidate, routine: canonicalName };
+    });
+    const summariesForInference = summariesForAnnotations(canonicalSummariesByName, activeOutputCandidatesForInference);
+    const inferenceModel = options.emitInference
+        ? buildRegisterContractsInference([...summariesForInference.values()])
+        : undefined;
+    const inferenceFormat = options.inferenceFormat ?? 'json';
     return {
         diagnostics,
-        outputCandidates: outputCandidatesWithAutoFixability,
-        ...(options.emitReport ? { reportText: renderRegisterContractsReport(reportModel) } : {}),
+        ...(activeFindings.length > 0 ? { findings: activeFindings } : {}),
+        outputCandidates: activeOutputCandidates,
+        ...(options.emitReport
+            ? renderedJsonReport !== undefined
+                ? {
+                    reportText: renderedJsonReport.text,
+                    reportJson: renderedJsonReport.json,
+                    reportFormat: 'json',
+                }
+                : { reportText: renderRegisterContractsReport(reportModel), reportFormat: 'text' }
+            : {}),
         ...(options.emitInterface
             ? { interfaceText: renderRegisterContractsInterface(summaries) }
             : {}),
+        ...(inferenceModel !== undefined
+            ? inferenceFormat === 'markdown'
+                ? {
+                    inferenceText: renderRegisterContractsInferenceMarkdown(inferenceModel),
+                    inferenceJson: inferenceModel,
+                    inferenceFormat,
+                }
+                : {
+                    inferenceText: `${JSON.stringify(inferenceModel, null, 2)}\n`,
+                    inferenceJson: inferenceModel,
+                    inferenceFormat,
+                }
+            : {}),
         ...(annotations.length > 0 ? { annotations } : {}),
         ...(reportModel.unknownCalls.length > 0 ? { unknownCalls: reportModel.unknownCalls } : {}),
     };
 }
+function isSuppressedFinding(finding, kind, suppressions) {
+    return suppressions.some((item) => item.file === finding.file &&
+        item.line === finding.line &&
+        item.findingKind === kind);
+}
+function registerContractsSuppressions(comments) {
+    return comments
+        .filter((item) => item.comment.kind === 'rcIgnoreNext')
+        .map((item) => {
+        if (item.comment.kind !== 'rcIgnoreNext') {
+            throw new Error('unreachable');
+        }
+        return {
+            file: item.file,
+            line: item.line + 1,
+            column: 1,
+            findingKind: item.comment.findingKind,
+            reason: item.comment.reason,
+        };
+    });
+}
+function applyRegisterContractsSuppressions(findings, suppressions) {
+    const suppressedFindings = [];
+    const activeFindings = [];
+    for (const finding of findings) {
+        const suppression = suppressions.find((item) => item.file === finding.file &&
+            item.line === finding.line &&
+            item.findingKind === finding.kind);
+        if (suppression === undefined) {
+            activeFindings.push(finding);
+        }
+        else {
+            suppressedFindings.push({ finding, suppression });
+        }
+    }
+    return { activeFindings, suppressedFindings };
+}
+function malformedSuppressionDiagnostics(sourceLineComments, mode, policy) {
+    const diagnostics = [];
+    for (const [file, comments] of sourceLineComments) {
+        for (const [line, text] of comments) {
+            const commentText = `;${text}`;
+            if (!/^;?\s*!\s*rc-ignore-next\b/iu.test(commentText))
+                continue;
+            if (!isStrictSuppressionContext(file, mode, policy))
+                continue;
+            const parsed = parseSmartComments(new Map([[file, new Map([[line, text]])]]));
+            if (parsed.some((item) => item.comment.kind === 'rcIgnoreNext'))
+                continue;
+            diagnostics.push({
+                severity: 'error',
+                code: 'AZMN_REGISTER_CONTRACTS',
+                sourceName: file,
+                line,
+                column: 1,
+                message: 'Malformed register-contract suppression; use `;! rc-ignore-next <finding-kind>: <reason>`.',
+            });
+        }
+    }
+    return diagnostics;
+}
+function isStrictSuppressionContext(file, mode, policy) {
+    if (policy !== undefined) {
+        return registerContractsPolicyModeForFile(file, policy, mode) === 'strict';
+    }
+    return mode === 'strict' || mode === 'error';
+}
+function findingKey(finding) {
+    return `${finding.kind ?? ''}:${finding.file}:${finding.line}:${finding.column}`;
+}
+function scopedBoundaryContractFindings(input) {
+    if (input.policy === undefined)
+        return [];
+    const routinesByLabel = routinesByBoundaryLabel(input.routines);
+    const out = [];
+    for (const boundary of input.directBoundaries) {
+        const callerMode = policyModeForFile(boundary.file, input.policy, input.mode);
+        if (callerMode !== 'strict')
+            continue;
+        const targetRoutine = routinesByLabel.get(boundary.target);
+        if (targetRoutine === undefined)
+            continue;
+        const targetMode = policyModeForFile(targetRoutine.span.file, input.policy, input.mode);
+        if (targetMode === 'strict')
+            continue;
+        if (hasExplicitBoundaryContract(boundary.target, input.contractMap, input.summariesByName, input.profileSummaryNames)) {
+            continue;
+        }
+        const routine = routineNameForBoundary(boundary.file, boundary.line, input.routines);
+        const targetDescription = registerContractsPolicyModeDescription(targetMode);
+        out.push({
+            kind: 'external_interface_unknown',
+            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 }
+                : {}),
+            ...(routine !== undefined ? { routine } : {}),
+            message: `strict register-contract source calls ${targetDescription} ${boundary.target}; add an explicit source, .asmi, or profile contract at the boundary.`,
+        });
+    }
+    return out;
+}
+function routinesByBoundaryLabel(routines) {
+    const out = new Map();
+    for (const routine of routines) {
+        for (const label of routine.labels)
+            out.set(label, routine);
+        for (const label of routine.entryLabels)
+            out.set(label, routine);
+        out.set(routine.name, routine);
+    }
+    return out;
+}
+function routineNameForBoundary(file, line, routines) {
+    return routines.find((routine) => routine.span.file === file &&
+        routine.span.start.line <= line &&
+        routine.span.end.line >= line)?.name;
+}
+function hasExplicitBoundaryContract(target, contractMap, summariesByName, profileSummaryNames) {
+    if (contractMap.has(target))
+        return true;
+    const summary = summariesByName.get(target);
+    if (summary === undefined)
+        return false;
+    return contractMap.has(summary.name) || profileSummaryNames.has(target) || profileSummaryNames.has(summary.name);
+}
+function diagnosticsForScopedPolicy(findings, policy, fallbackMode) {
+    return findings
+        .filter((finding) => policyModeForFile(finding.file, policy, fallbackMode) === 'strict')
+        .filter((finding) => finding.kind !== 'output_candidate')
+        .map((finding) => ({
+        severity: 'error',
+        code: 'AZMN_REGISTER_CONTRACTS',
+        sourceName: finding.file,
+        line: finding.line,
+        column: finding.column,
+        message: finding.message,
+    }));
+}
+function policyModeForFile(file, policy, fallbackMode) {
+    return registerContractsPolicyModeForFile(file, policy, fallbackMode);
+}
+function registerContractsPolicyModeDescription(mode) {
+    return mode === 'off' ? 'disabled' : `${mode}ed`;
+}

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

@@ -1,4 +1,5 @@
 import { expandCarrierList } from './carriers.js';
+import { rstServiceTargetName } from './profiles.js';
 import { buildRoutineContracts } from './smartComments.js';
 const INTERFACE_TAG_RE = /^\s*(in|out|clobbers|preserves)(?:\s+(.+))?$/i;
 const INTERFACE_CONTRACT_BUILDERS = {
@@ -9,6 +10,7 @@ const INTERFACE_CONTRACT_BUILDERS = {
 };
 export function parseInterfaceContracts(text, file = '<register-contracts-interface>') {
     const comments = [];
+    const serviceAliases = new Map();
     const lines = text.split(/\r?\n/u);
     for (const [index, line] of lines.entries()) {
         const trimmed = line.trim();
@@ -21,9 +23,23 @@ export function parseInterfaceContracts(text, file = '<register-contracts-interf
         if (comment === undefined) {
             throw new Error(`${file}:${index + 1}: invalid register contracts interface line \"${trimmed}\"`);
         }
+        if (comment.kind === 'extern') {
+            const serviceAliasesForComment = parseInterfaceServiceAliases(trimmed);
+            if (serviceAliasesForComment !== undefined) {
+                serviceAliases.set(comment.name, serviceAliasesForComment);
+            }
+        }
         comments.push({ file, line: index + 1, comment });
     }
     const routines = buildRoutineContracts(comments);
+    for (const [primary, aliases] of serviceAliases) {
+        const contract = routines.get(primary);
+        if (contract === undefined)
+            continue;
+        for (const alias of aliases) {
+            routines.set(alias, { ...contract, name: alias });
+        }
+    }
     const out = new Map();
     for (const [name, contract] of routines) {
         if (hasContractContent(contract))
@@ -46,11 +62,40 @@ function parseInterfaceContractLine(line) {
     return carriers === undefined ? undefined : INTERFACE_CONTRACT_BUILDERS[tag](carriers);
 }
 function parseInterfaceBoundary(trimmed) {
+    const service = parseInterfaceService(trimmed);
+    if (service !== undefined)
+        return { kind: 'extern', name: service.primary };
     const extern = /^extern\s+(\S+)\s*$/i.exec(trimmed);
     if (extern !== null)
         return { kind: 'extern', name: extern[1] };
     return /^end\s*$/i.test(trimmed) ? { kind: 'end' } : undefined;
 }
+function parseInterfaceServiceAliases(trimmed) {
+    return parseInterfaceService(trimmed)?.aliases;
+}
+function parseInterfaceService(trimmed) {
+    const match = /^service\s+rst\s+(\S+)\s+(\S+)\s+(\S+)(?:\s+(\S+))?\s*$/i.exec(trimmed);
+    if (match === null)
+        return undefined;
+    const vector = parseInterfaceNumber(match[1]);
+    const selector = match[2].toUpperCase();
+    const value = parseInterfaceNumber(match[3]);
+    if (vector === undefined || value === undefined || selector !== 'C')
+        return undefined;
+    const primary = rstServiceTargetName(vector, String(value));
+    const name = match[4];
+    const aliases = name === undefined ? [] : [rstServiceTargetName(vector, name)];
+    return { primary, aliases };
+}
+function parseInterfaceNumber(raw) {
+    const trimmed = raw.trim();
+    const value = trimmed.startsWith('$')
+        ? Number.parseInt(trimmed.slice(1), 16)
+        : /^0x/iu.test(trimmed)
+            ? Number.parseInt(trimmed.slice(2), 16)
+            : Number.parseInt(trimmed, 10);
+    return Number.isInteger(value) && value >= 0 && value <= 0xff ? value : undefined;
+}
 function parseInterfaceCarrierList(rest) {
     if (!rest)
         return undefined;

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

@@ -49,7 +49,9 @@ function rstBoundaryTarget(routine, index, effect) {
 function rstBoundaryTargets(routine, index, vector, fallbackTarget) {
     const previous = routine.instructions[index - 1];
     const service = precedingCServiceName(previous);
+    const numericService = precedingRegisterImmediateValue(previous, 'C');
     return [
+        ...(numericService !== undefined ? [rstServiceTargetName(vector, String(numericService))] : []),
         ...rstDispatcherServiceTargetNames(vector, (register) => precedingRegisterImmediateValue(previous, register)),
         ...(service ? [rstServiceTargetName(vector, service)] : []),
         fallbackTarget,
@@ -195,9 +197,18 @@ export function findRegisterContractsConflicts(routine, summaries, hints) {
         const carriers = unique(summary.mayWrite.filter((unit) => liveOut[index].has(unit) && !accepted.has(unit)));
         if (carriers.length > 0) {
             conflicts.push({
+                kind: carriers.every((unit) => isFlagUnit(unit))
+                    ? 'flag_lifetime_risk'
+                    : 'definite_contract_violation',
                 file: item.file,
                 line: item.line,
                 column: item.column,
+                ...(item.sourceUnit !== undefined ? { sourceUnit: item.sourceUnit } : {}),
+                ...(item.sourceRelation !== undefined ? { sourceRelation: item.sourceRelation } : {}),
+                ...(item.sourceUnitRelation !== undefined
+                    ? { sourceUnitRelation: item.sourceUnitRelation }
+                    : {}),
+                routine: routine.name,
                 callTarget: target,
                 carriers,
                 message: `${boundary.subject} may modify ${carriers.join(',')}, but the pre-call value is used later.`,
@@ -206,6 +217,13 @@ export function findRegisterContractsConflicts(routine, summaries, hints) {
     }
     return conflicts;
 }
+function isFlagUnit(unit) {
+    return (unit === 'carry' ||
+        unit === 'zero' ||
+        unit === 'sign' ||
+        unit === 'parity' ||
+        unit === 'halfCarry');
+}
 function candidateMessage(boundary, units) {
     const carriers = units.join(',');
     const expectation = units.length === 1 ? units[0] : `{${carriers}}`;
@@ -230,6 +248,11 @@ function callerOutputCandidate(item, boundary, target, summary, liveAfter) {
             file: item.file,
             line: item.line,
             column: item.column,
+            ...(item.sourceUnit !== undefined ? { sourceUnit: item.sourceUnit } : {}),
+            ...(item.sourceRelation !== undefined ? { sourceRelation: item.sourceRelation } : {}),
+            ...(item.sourceUnitRelation !== undefined
+                ? { sourceUnitRelation: item.sourceUnitRelation }
+                : {}),
             routine: target,
             carriers,
             message: candidateMessage(boundary, carriers),

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

@@ -0,0 +1,2 @@
+import type { RegisterContractsMode, RegisterContractsPolicy, RegisterContractsPolicyMode } from './types.js';
+export declare function registerContractsPolicyModeForFile(file: string, policy: RegisterContractsPolicy, fallbackMode: RegisterContractsMode | undefined): RegisterContractsPolicyMode;

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

@@ -0,0 +1,54 @@
+const POLICY_MODE_PRIORITY = {
+    strict: 3,
+    audit: 2,
+    off: 1,
+};
+export function registerContractsPolicyModeForFile(file, policy, fallbackMode) {
+    const normalized = normalizePolicyPath(file);
+    const matches = [
+        ...policyMatchesForMode(normalized, policy.strict, 'strict'),
+        ...policyMatchesForMode(normalized, policy.audit, 'audit'),
+        ...policyMatchesForMode(normalized, policy.off, 'off'),
+    ].sort(comparePolicyMatches);
+    return matches[0]?.mode ?? fallbackPolicyMode(fallbackMode);
+}
+function policyMatchesForMode(file, patterns, mode) {
+    return (patterns
+        ?.map((pattern) => {
+        const normalized = normalizePolicyPath(pattern);
+        if (!matchPolicyPattern(file, normalized))
+            return undefined;
+        return { mode, specificity: policyPatternSpecificity(normalized) };
+    })
+        .filter((match) => match !== undefined) ?? []);
+}
+function comparePolicyMatches(left, right) {
+    return (right.specificity - left.specificity ||
+        POLICY_MODE_PRIORITY[right.mode] - POLICY_MODE_PRIORITY[left.mode]);
+}
+function fallbackPolicyMode(fallbackMode) {
+    return fallbackMode === 'strict' || fallbackMode === 'error' || fallbackMode === 'warn'
+        ? 'strict'
+        : fallbackMode === 'off'
+            ? 'off'
+            : 'audit';
+}
+function normalizePolicyPath(path) {
+    return path.replace(/\\/g, '/');
+}
+function policyPatternSpecificity(pattern) {
+    return pattern.replace(/\*/g, '').length;
+}
+function matchPolicyPattern(file, pattern) {
+    if (pattern === file)
+        return true;
+    if (!pattern.includes('*'))
+        return false;
+    const globStar = '\u0000';
+    const escaped = pattern
+        .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*\*/g, globStar)
+        .replace(/\*/g, '[^/]*')
+        .replaceAll(globStar, '.*');
+    return new RegExp(`^${escaped}$`).test(file);
+}

package/dist/src/register-contracts/programModel-boundaries.d.ts

@@ -1,6 +1,10 @@
 import type { SourceItem } from '../model/source-item.js';
 import type { RegisterContractsDirectCall } from './types.js';
+type InstructionItem = Extract<SourceItem, {
+    readonly kind: 'instruction';
+}>;
 export declare function instructionCallTarget(item: SourceItem): string | undefined;
-export declare function pushDirectBoundary(boundaries: RegisterContractsDirectCall[], target: string, subject: string, file: string, line: number, column: number): void;
+export declare function pushDirectBoundary(boundaries: RegisterContractsDirectCall[], target: string, subject: string, span: InstructionItem['span']): void;
 export declare function collectFilesWithEntryLabels(items: readonly SourceItem[]): Set<string>;
 export declare function collectDirectTailJumps(items: readonly SourceItem[], filesWithEntryLabels: ReadonlySet<string>): RegisterContractsDirectCall[];
+export {};

package/dist/src/register-contracts/programModel-boundaries.js

@@ -26,8 +26,22 @@ function isEligibleTailJumpTarget(target, entryNames) {
         return false;
     return entryNames === undefined || entryNames.has(target);
 }
-export function pushDirectBoundary(boundaries, target, subject, file, line, column) {
-    boundaries.push({ target, subject, file, line, column });
+export function pushDirectBoundary(boundaries, target, subject, span) {
+    boundaries.push({
+        target,
+        subject,
+        file: span.sourceName,
+        line: span.line,
+        column: span.column,
+        ...(span.sourceUnit !== undefined ? { sourceUnit: span.sourceUnit } : {}),
+        ...(span.sourceRelation !== undefined ? { sourceRelation: span.sourceRelation } : {}),
+        ...(span.sourceUnitRelation !== undefined
+            ? { sourceUnitRelation: span.sourceUnitRelation }
+            : {}),
+    });
+}
+function effectiveInstructionSpan(item) {
+    return item.emittedSource?.span ?? item.span;
 }
 export function collectFilesWithEntryLabels(items) {
     return new Set(items
@@ -52,13 +66,14 @@ export function collectDirectTailJumps(items, filesWithEntryLabels) {
     for (const item of items) {
         if (item.kind !== 'instruction')
             continue;
-        const entryNames = filesWithEntryLabels.has(item.span.sourceName)
-            ? entriesByFile.get(item.span.sourceName)
+        const span = effectiveInstructionSpan(item);
+        const entryNames = filesWithEntryLabels.has(span.sourceName)
+            ? entriesByFile.get(span.sourceName)
             : undefined;
         const target = instructionTailJumpTarget(item, entryNames);
         if (target === undefined)
             continue;
-        pushDirectBoundary(directTailJumps, target, `JP ${target}`, item.span.sourceName, item.span.line, item.span.column);
+        pushDirectBoundary(directTailJumps, target, `JP ${target}`, effectiveInstructionSpan(item));
     }
     return directTailJumps;
 }