@jhlagado/azm 0.2.11 → 0.2.13

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

@@ -2,6 +2,9 @@ import { instructionCallTarget, pushDirectBoundary } from './programModel-bounda
 function isGlobalLabel(name) {
     return !name.startsWith('.');
 }
+function isGeneratedOpLabel(name) {
+    return name.startsWith('__azm_op_');
+}
 function emptyState() {
     return {
         entryLabels: [],
@@ -10,17 +13,40 @@ function emptyState() {
     };
 }
 function toInstruction(item, labels, constants) {
+    const span = effectiveInstructionSpan(item);
     return {
         instruction: item.instruction,
-        file: item.span.sourceName,
-        line: item.span.line,
-        column: item.span.column,
+        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 }
+            : {}),
         labels: [...labels],
         constants,
     };
 }
+function effectiveInstructionSpan(item) {
+    return item.emittedSource?.span ?? item.span;
+}
 function startRoutine(state, item) {
     state.sourceName = item.span.sourceName;
+    if (item.span.sourceUnit !== undefined)
+        state.sourceUnit = item.span.sourceUnit;
+    else
+        delete state.sourceUnit;
+    if (item.span.sourceRelation !== undefined)
+        state.sourceRelation = item.span.sourceRelation;
+    else
+        delete state.sourceRelation;
+    if (item.span.sourceUnitRelation !== undefined) {
+        state.sourceUnitRelation = item.span.sourceUnitRelation;
+    }
+    else {
+        delete state.sourceUnitRelation;
+    }
     state.routineName = item.name;
     state.entryLabels = item.isEntry === true ? [item.name] : [];
     state.labels = [item.name];
@@ -32,6 +58,11 @@ function routineSpan(state, end) {
     const line = state.routineStartLine ?? 1;
     return {
         file: state.sourceName ?? '',
+        ...(state.sourceUnit !== undefined ? { sourceUnit: state.sourceUnit } : {}),
+        ...(state.sourceRelation !== undefined ? { sourceRelation: state.sourceRelation } : {}),
+        ...(state.sourceUnitRelation !== undefined
+            ? { sourceUnitRelation: state.sourceUnitRelation }
+            : {}),
         start: { line, column: state.routineStartColumn ?? 1 },
         end: { line: end?.line ?? line, column: end?.column ?? state.routineStartColumn ?? 1 },
     };
@@ -58,12 +89,12 @@ function appendDirectCall(directCalls, item) {
     const directTarget = instructionCallTarget(item);
     if (directTarget === undefined)
         return;
-    pushDirectBoundary(directCalls, directTarget, `CALL ${directTarget}`, item.span.sourceName, item.span.line, item.span.column);
+    pushDirectBoundary(directCalls, directTarget, `CALL ${directTarget}`, effectiveInstructionSpan(item));
 }
 function handleInstruction(state, directCalls, item, context) {
     if (state.routineName === undefined || state.sourceName === undefined)
         return;
-    if (item.span.sourceName !== state.sourceName)
+    if (effectiveInstructionSpan(item).sourceName !== state.sourceName)
         return;
     state.instructions.push(toInstruction(item, state.labels, context.constants));
     appendDirectCall(directCalls, item);
@@ -106,7 +137,7 @@ function appendRoutineLabel(state, item) {
         state.entryLabels.push(item.name);
 }
 function handleLabel(routines, state, item, context) {
-    if (!isGlobalLabel(item.name)) {
+    if (!isGlobalLabel(item.name) || isGeneratedOpLabel(item.name)) {
         if (state.routineName !== undefined)
             state.labels.push(item.name);
         return;

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

@@ -0,0 +1,3 @@
+import type { RegisterContractsJsonFinding, RegisterContractsJsonReportModel, RegisterContractsRatchetResult } from './types.js';
+export declare function registerContractsFindingIdentity(finding: RegisterContractsJsonFinding): string;
+export declare function compareRegisterContractsBaseline(current: RegisterContractsJsonReportModel, baseline: RegisterContractsJsonReportModel, baselineFile: string | undefined): RegisterContractsRatchetResult;

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

@@ -0,0 +1,88 @@
+function carriersKey(finding) {
+    return [...(finding.carriers ?? [])].sort().join(',');
+}
+export function registerContractsFindingIdentity(finding) {
+    const target = finding.callTarget ?? finding.routine ?? finding.subject ?? '';
+    return [
+        finding.kind,
+        target,
+        carriersKey(finding),
+    ].join('|');
+}
+function displayIdentity(finding) {
+    return [
+        registerContractsFindingIdentity(finding),
+        finding.location.file,
+        finding.location.line,
+        finding.location.column,
+    ].join('|');
+}
+function ratchetEntries(findings) {
+    const out = new Map();
+    for (const finding of findings) {
+        const identity = registerContractsFindingIdentity(finding);
+        const entries = out.get(identity) ?? [];
+        entries.push({ identity: displayIdentity(finding), finding });
+        out.set(identity, entries);
+    }
+    return out;
+}
+function findingFingerprint(finding) {
+    return JSON.stringify({
+        location: finding.location,
+        message: finding.message,
+        remediationCategory: finding.remediation.category,
+        remediationHint: finding.remediation.hint,
+    });
+}
+export function compareRegisterContractsBaseline(current, baseline, baselineFile) {
+    const currentEntries = ratchetEntries(current.findings);
+    const baselineEntries = ratchetEntries(baseline.findings);
+    const identities = new Set([...currentEntries.keys(), ...baselineEntries.keys()]);
+    const newFindings = [];
+    const removedFindings = [];
+    const changedFindings = [];
+    for (const identity of identities) {
+        const currentGroup = [...(currentEntries.get(identity) ?? [])];
+        const baselineGroup = [...(baselineEntries.get(identity) ?? [])];
+        const matchedBaseline = new Set();
+        const matchedCurrent = new Set();
+        for (const [currentIndex, currentEntry] of currentGroup.entries()) {
+            const exactIndex = baselineGroup.findIndex((baselineEntry, baselineIndex) => !matchedBaseline.has(baselineIndex) &&
+                findingFingerprint(baselineEntry.finding) === findingFingerprint(currentEntry.finding));
+            if (exactIndex === -1)
+                continue;
+            matchedCurrent.add(currentIndex);
+            matchedBaseline.add(exactIndex);
+        }
+        for (const [currentIndex, currentEntry] of currentGroup.entries()) {
+            if (matchedCurrent.has(currentIndex))
+                continue;
+            const changedIndex = baselineGroup.findIndex((_baselineEntry, baselineIndex) => !matchedBaseline.has(baselineIndex));
+            if (changedIndex === -1)
+                continue;
+            const baselineEntry = baselineGroup[changedIndex];
+            matchedCurrent.add(currentIndex);
+            matchedBaseline.add(changedIndex);
+            changedFindings.push({
+                identity,
+                baseline: baselineEntry.finding,
+                current: currentEntry.finding,
+            });
+        }
+        for (const [currentIndex, currentEntry] of currentGroup.entries()) {
+            if (!matchedCurrent.has(currentIndex))
+                newFindings.push(currentEntry);
+        }
+        for (const [baselineIndex, baselineEntry] of baselineGroup.entries()) {
+            if (!matchedBaseline.has(baselineIndex))
+                removedFindings.push(baselineEntry);
+        }
+    }
+    return {
+        ...(baselineFile !== undefined ? { baselineFile } : {}),
+        newFindings,
+        removedFindings,
+        changedFindings,
+    };
+}

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

@@ -1,5 +1,12 @@
-import type { RegisterContractsReportModel, RegisterContractsUnit, RoutineSummary } from './types.js';
+import type { RegisterContractsJsonReportModel, RegisterContractsInferenceModel, RegisterContractsReportModel, RegisterContractsUnit, RoutineSummary } from './types.js';
 export declare function contractCarrierList(units: RegisterContractsUnit[]): string;
 export declare function renderRegisterContractsReport(model: RegisterContractsReportModel): string;
+export declare function buildRegisterContractsJsonReport(model: RegisterContractsReportModel): RegisterContractsJsonReportModel;
+export declare function renderRegisterContractsJsonReport(model: RegisterContractsReportModel): {
+    json: RegisterContractsJsonReportModel;
+    text: string;
+};
 export declare function renderRegisterContractsInterface(summaries: RoutineSummary[]): string;
+export declare function buildRegisterContractsInference(summaries: readonly RoutineSummary[]): RegisterContractsInferenceModel;
+export declare function renderRegisterContractsInferenceMarkdown(model: RegisterContractsInferenceModel): string;
 export declare function renderRegisterContractsSourceBlock(summary: RoutineSummary): string[];

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

@@ -90,11 +90,123 @@ export function renderRegisterContractsReport(model) {
         lines.push(`Profile: ${model.profile}`);
     lines.push('');
     appendRoutineSummaries(lines, model);
+    appendFindings(lines, model);
     appendConflicts(lines, model);
     appendOutputCandidates(lines, model);
+    appendRatchet(lines, model);
     appendUnknownCalls(lines, model);
     return `${lines.join('\n')}\n`;
 }
+export function buildRegisterContractsJsonReport(model) {
+    return {
+        format: 'azm-register-contracts-report',
+        version: 1,
+        entryFile: model.entryFile,
+        mode: model.mode,
+        ...(model.profile !== undefined ? { profile: model.profile } : {}),
+        summaries: model.summaries,
+        findings: (model.findings ?? []).map(jsonFinding),
+        ...(model.suppressedFindings !== undefined && model.suppressedFindings.length > 0
+            ? {
+                suppressedFindings: model.suppressedFindings.map((item) => ({
+                    finding: jsonFinding(item.finding),
+                    suppression: item.suppression,
+                })),
+            }
+            : {}),
+        unknownCalls: model.unknownCalls,
+        ...(model.ratchet !== undefined ? { ratchet: model.ratchet } : {}),
+    };
+}
+export function renderRegisterContractsJsonReport(model) {
+    const json = buildRegisterContractsJsonReport(model);
+    return { json, text: `${JSON.stringify(json, null, 2)}\n` };
+}
+function jsonFinding(finding) {
+    return {
+        kind: finding.kind,
+        location: jsonLocation(finding),
+        message: finding.message,
+        ...('routine' in finding && finding.routine !== undefined ? { routine: finding.routine } : {}),
+        ...('callTarget' in finding ? { callTarget: finding.callTarget } : {}),
+        ...('subject' in finding ? { subject: finding.subject } : {}),
+        ...(finding.carriers !== undefined ? { carriers: finding.carriers } : {}),
+        ...('stackBalanced' in finding ? { stackBalanced: finding.stackBalanced } : {}),
+        ...('hasUnknownStackEffect' in finding && finding.hasUnknownStackEffect !== undefined
+            ? { hasUnknownStackEffect: finding.hasUnknownStackEffect }
+            : {}),
+        ...('autoFixable' in finding && finding.autoFixable !== undefined
+            ? { autoFixable: finding.autoFixable }
+            : {}),
+        remediation: remediationForFinding(finding),
+    };
+}
+function jsonLocation(finding) {
+    return {
+        file: finding.file,
+        line: finding.line,
+        column: finding.column,
+        ...(finding.sourceUnit !== undefined ? { sourceUnit: finding.sourceUnit } : {}),
+        ...(finding.sourceRelation !== undefined ? { sourceRelation: finding.sourceRelation } : {}),
+        ...(finding.sourceUnitRelation !== undefined
+            ? { sourceUnitRelation: finding.sourceUnitRelation }
+            : {}),
+    };
+}
+function remediationForFinding(finding) {
+    switch (finding.kind) {
+        case 'missing_callee_contract':
+        case 'external_interface_unknown':
+            return {
+                category: 'add_contract',
+                hint: 'Add a routine body or .asmi extern contract for the boundary target.',
+            };
+        case 'unknown_control_flow':
+            return {
+                category: 'review_control_flow',
+                hint: 'Keep stack-changing paths inside one @ routine boundary or split the flow into explicit routines.',
+            };
+        case 'output_candidate':
+            return {
+                category: 'review_output_contract',
+                hint: finding.autoFixable === true
+                    ? 'Generated contracts can promote this candidate to an output.'
+                    : 'Review the caller and callee before marking this carrier as an output.',
+            };
+        case 'definite_contract_violation':
+        case 'flag_lifetime_risk':
+            return {
+                category: 'fix_call_or_contract',
+                hint: 'Fix the caller liveness issue or update the callee contract if the value is an intentional output.',
+            };
+    }
+}
+function appendFindings(lines, model) {
+    lines.push('Findings:');
+    if (!model.findings || model.findings.length === 0) {
+        lines.push('  none');
+    }
+    else {
+        for (const finding of model.findings) {
+            const carriers = finding.carriers ? `: ${list(finding.carriers)}` : '';
+            const target = 'callTarget' in finding ? `: ${finding.callTarget}` : '';
+            lines.push(`  ${finding.file}:${finding.line}:${finding.column}: ${finding.kind}${target}${carriers}: ${finding.message}`);
+        }
+    }
+    lines.push('');
+    lines.push('Suppressed findings:');
+    if (!model.suppressedFindings || model.suppressedFindings.length === 0) {
+        lines.push('  none');
+    }
+    else {
+        for (const item of model.suppressedFindings) {
+            const finding = item.finding;
+            const target = 'callTarget' in finding ? `: ${finding.callTarget}` : '';
+            lines.push(`  ${finding.file}:${finding.line}:${finding.column}: ${finding.kind}${target}: ${item.suppression.reason}`);
+        }
+    }
+    lines.push('');
+}
 function appendRoutineSummaries(lines, model) {
     if (model.summaries.length === 0) {
         lines.push('Routines: none', '');
@@ -149,6 +261,27 @@ function appendUnknownCalls(lines, model) {
     }
     lines.push('');
 }
+function appendRatchet(lines, model) {
+    if (model.ratchet === undefined)
+        return;
+    lines.push('Ratchet:');
+    if (model.ratchet.baselineFile !== undefined) {
+        lines.push(`  baseline: ${model.ratchet.baselineFile}`);
+    }
+    lines.push(`  new findings: ${model.ratchet.newFindings.length}`);
+    for (const entry of model.ratchet.newFindings) {
+        lines.push(`    ${entry.finding.location.file}:${entry.finding.location.line}:${entry.finding.location.column}: ${entry.finding.kind}: ${entry.finding.message}`);
+    }
+    lines.push(`  removed findings: ${model.ratchet.removedFindings.length}`);
+    for (const entry of model.ratchet.removedFindings) {
+        lines.push(`    ${entry.finding.location.file}:${entry.finding.location.line}:${entry.finding.location.column}: ${entry.finding.kind}: ${entry.finding.message}`);
+    }
+    lines.push(`  changed findings: ${model.ratchet.changedFindings.length}`);
+    for (const entry of model.ratchet.changedFindings) {
+        lines.push(`    ${entry.current.location.file}:${entry.current.location.line}:${entry.current.location.column}: ${entry.current.kind}: ${entry.current.message}`);
+    }
+    lines.push('');
+}
 export function renderRegisterContractsInterface(summaries) {
     const lines = [];
     for (const summary of summaries) {
@@ -160,6 +293,47 @@ export function renderRegisterContractsInterface(summaries) {
     }
     return `${lines.join('\n')}\n`;
 }
+export function buildRegisterContractsInference(summaries) {
+    return {
+        format: 'azm-register-contracts-inference',
+        version: 1,
+        routines: summaries.map((summary) => {
+            const out = relationOutputUnits(summary.valueRelations);
+            const outputCandidateCarriers = summary.outputCandidates ?? [];
+            return {
+                name: summary.name,
+                in: summary.mayRead,
+                out,
+                clobbers: summary.mayWrite.filter((unit) => !out.includes(unit)),
+                preserves: summary.preserved,
+                confidence: out.length > 0 || summary.mayRead.length > 0 || summary.preserved.length > 0
+                    ? 'inferred'
+                    : 'draft',
+                callerImpact: {
+                    outputCandidateCount: outputCandidateCarriers.length,
+                    outputCandidateCarriers,
+                },
+            };
+        }),
+    };
+}
+export function renderRegisterContractsInferenceMarkdown(model) {
+    const lines = ['# AZM Register Contracts Inference', ''];
+    for (const routine of model.routines) {
+        lines.push(`## ${routine.name}`);
+        lines.push(`- confidence: ${routine.confidence}`);
+        lines.push(`- in: ${contractCarrierList(routine.in)}`);
+        lines.push(`- out: ${contractCarrierList(routine.out)}`);
+        lines.push(`- clobbers: ${contractCarrierList(routine.clobbers)}`);
+        lines.push(`- preserves: ${contractCarrierList(routine.preserves)}`);
+        lines.push(`- caller impact: ${routine.callerImpact.outputCandidateCount} output candidate carrier(s)`);
+        if (routine.callerImpact.outputCandidateCarriers.length > 0) {
+            lines.push(`- output candidates: ${contractCarrierList(routine.callerImpact.outputCandidateCarriers)}`);
+        }
+        lines.push('');
+    }
+    return `${lines.join('\n')}\n`;
+}
 export function renderRegisterContractsSourceBlock(summary) {
     const entries = sourceContractEntries(summary);
     if (entries.length === 0)

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

@@ -4,6 +4,14 @@ const COMPACT_SOURCE_CLAUSE_RE = /^(in|out|clobbers|preserves)(?:\s+(.+))?$/i;
 const COMPACT_SOURCE_LINE_RE = /^\s*;\s*!\s*(?:in|out|maybe-out|clobbers|preserves)(?:\s|$)/i;
 const CARRIER_RE = /^\{([^}]+)\}(?:\s+(.+))?$/;
 const CONTRACT_COMMENT_KINDS = new Set(['in', 'out', 'clobbers', 'preserves']);
+const FINDING_KINDS = new Set([
+    'definite_contract_violation',
+    'flag_lifetime_risk',
+    'missing_callee_contract',
+    'unknown_control_flow',
+    'external_interface_unknown',
+    'output_candidate',
+]);
 function parseCarrierPayload(rest) {
     if (!rest)
         return undefined;
@@ -40,6 +48,9 @@ export function parseSmartCommentLine(line) {
 }
 export function parseSmartCommentLines(line) {
     const trimmed = line.trim();
+    const rcIgnoreNext = parseRcIgnoreNextComment(trimmed);
+    if (rcIgnoreNext !== undefined)
+        return [rcIgnoreNext];
     const expectOut = parseExpectOutComment(trimmed);
     if (expectOut !== undefined)
         return [expectOut];
@@ -56,6 +67,17 @@ export function parseSmartCommentLines(line) {
     }
     return [];
 }
+function parseRcIgnoreNextComment(trimmed) {
+    const match = /^;?\s*!\s*rc-ignore-next\s+([A-Za-z0-9_]+)\s*:\s*(.+)$/i.exec(trimmed);
+    if (match === null)
+        return undefined;
+    const findingKind = match[1];
+    const reason = match[2]?.trim();
+    if (!FINDING_KINDS.has(findingKind) || reason === undefined || reason.length === 0) {
+        return undefined;
+    }
+    return { kind: 'rcIgnoreNext', findingKind, reason };
+}
 function parseSemicolonSeparatedSourceComments(trimmed) {
     const sourcePrefix = /^;?\s*!\s*/.exec(trimmed);
     if (sourcePrefix === null)

package/dist/src/register-contracts/summary-boundary.js

@@ -1,5 +1,5 @@
 import { getZ80InstructionEffect } from '../z80/effects.js';
-import { precedingCServiceName } from './boundaryHints.js';
+import { precedingCServiceName, precedingRegisterImmediateValue } from './boundaryHints.js';
 import { instructionHead } from './instruction-head.js';
 import { rstServiceTargetName, rstTargetName } from './profiles.js';
 export function boundarySummary(routine, index, summaries) {
@@ -35,6 +35,13 @@ function rstBoundarySummary(routine, index, effect, summaries) {
         summaries.get(rstTargetName(effect.control.vector)));
 }
 function rstServiceBoundarySummary(routine, index, vector, summaries) {
-    const service = precedingCServiceName(routine.instructions[index - 1]);
+    const previous = routine.instructions[index - 1];
+    const numericService = precedingRegisterImmediateValue(previous, 'C');
+    if (numericService !== undefined) {
+        const numericSummary = summaries.get(rstServiceTargetName(vector, String(numericService)));
+        if (numericSummary !== undefined)
+            return numericSummary;
+    }
+    const service = precedingCServiceName(previous);
     return service ? summaries.get(rstServiceTargetName(vector, service)) : undefined;
 }

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

@@ -1,6 +1,6 @@
 import type { Diagnostic } from '../model/diagnostic.js';
 import type { LoadedProgram } from '../tooling/api.js';
-import type { AnalyzeRegisterContractsOptions, RegisterContractsOutputCandidate, RegisterContractsUnit } from './types.js';
+import type { AnalyzeRegisterContractsOptions, RegisterContractsFinding, RegisterContractsOutputCandidate, RegisterContractsUnit } from './types.js';
 export interface RegisterContractsTextEdit {
     file: string;
     line: number;
@@ -42,6 +42,7 @@ export interface AnalyzeRegisterContractsForToolsOptions extends Omit<AnalyzeReg
 export type AnalyzeRegisterCareForToolsOptions = AnalyzeRegisterContractsForToolsOptions;
 export interface AnalyzeRegisterContractsForToolsResult {
     diagnostics: Diagnostic[];
+    findings: RegisterContractsFinding[];
     outputCandidates: RegisterContractsOutputCandidate[];
     candidateDiagnostics: RegisterContractsCandidateDiagnostic[];
     codeActions: RegisterContractsCodeAction[];

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

@@ -46,12 +46,14 @@ export function analyzeRegisterContractsForTools(loaded, options) {
         ? baseResultOptions
         : { ...baseResultOptions, registerContractsProfile: profile });
     const outputCandidates = result.outputCandidates ?? [];
+    const findings = result.findings ?? [];
     const candidateDiagnostics = outputCandidates.map(diagnosticForOutputCandidate);
     const codeActions = outputCandidates
         .filter((candidate) => candidate.autoFixable === true)
         .map(codeActionForOutputCandidate);
     return {
         diagnostics: result.diagnostics,
+        findings,
         outputCandidates,
         candidateDiagnostics,
         codeActions,