@jhlagado/azm 0.2.11 → 0.2.13

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/core/compile.js

@@ -158,6 +158,7 @@ function spanAt(line, column) {
         column,
         ...(line.sourceUnit !== undefined ? { sourceUnit: line.sourceUnit } : {}),
         ...(line.sourceRelation !== undefined ? { sourceRelation: line.sourceRelation } : {}),
+        ...(line.sourceUnitRelation !== undefined ? { sourceUnitRelation: line.sourceUnitRelation } : {}),
     };
 }
 function firstColumn(text) {

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

@@ -60,7 +60,14 @@ function expandTemplateItem(ops, item, bindings, line, diagnostics, overload, ex
 }
 function opEmittedSource(line) {
     return {
-        span: { sourceName: line.sourceName, line: line.line, column: firstColumn(line.text) },
+        span: {
+            sourceName: line.sourceName,
+            line: line.line,
+            column: firstColumn(line.text),
+            ...(line.sourceUnit !== undefined ? { sourceUnit: line.sourceUnit } : {}),
+            ...(line.sourceRelation !== undefined ? { sourceRelation: line.sourceRelation } : {}),
+            ...(line.sourceUnitRelation !== undefined ? { sourceUnitRelation: line.sourceUnitRelation } : {}),
+        },
         kind: 'macro',
     };
 }

package/dist/src/expansion/op-expansion.d.ts

@@ -6,6 +6,9 @@ export type LogicalLineLike = {
     readonly sourceName: string;
     readonly line: number;
     readonly text: string;
+    readonly sourceUnit?: string;
+    readonly sourceRelation?: 'entry' | 'include' | 'import';
+    readonly sourceUnitRelation?: 'entry' | 'include' | 'import';
 };
 interface OpParam {
     readonly name: string;

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/node/source-host.js

@@ -30,6 +30,7 @@ export async function expandSourceForTooling(options) {
         sourceStack: [],
         sourceUnit: entryFile,
         sourceRelation: 'entry',
+        sourceUnitRelation: 'entry',
         ...(options.preloadedText !== undefined ? { preloadedText: options.preloadedText } : {}),
         ...(options.signal !== undefined ? { signal: options.signal } : {}),
     });
@@ -60,7 +61,7 @@ async function expandFile(options) {
         recordLineComment(options.sourceLineComments, line);
         const directive = parseSourceLoadDirective(line.text);
         if (!directive) {
-            output.push(withSourceOwnership(line, options.sourceUnit, options.sourceRelation));
+            output.push(withSourceOwnership(line, options.sourceUnit, options.sourceRelation, options.sourceUnitRelation));
             continue;
         }
         const result = await resolveSourcePath(sourcePath, directive.path, options.includeDirs);
@@ -88,6 +89,7 @@ async function expandFile(options) {
             sourceStack: [...options.sourceStack, { sourcePath }],
             sourceUnit: directive.kind === 'import' ? result.resolved : options.sourceUnit,
             sourceRelation: directive.kind,
+            sourceUnitRelation: directive.kind === 'import' ? 'import' : options.sourceUnitRelation,
         });
         if (included !== undefined) {
             output.push(...included);
@@ -95,11 +97,12 @@ async function expandFile(options) {
     }
     return output;
 }
-function withSourceOwnership(line, sourceUnit, sourceRelation) {
+function withSourceOwnership(line, sourceUnit, sourceRelation, sourceUnitRelation) {
     return {
         ...line,
         sourceUnit,
         sourceRelation,
+        sourceUnitRelation,
     };
 }
 function recordLineComment(comments, line) {

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[];
 }