@jhlagado/azm 0.2.7 → 0.2.9

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

@@ -1,166 +0,0 @@
-import { buildRegisterCareProgramModel } from './programModel.js';
-import { buildRoutineContracts, parseSmartComments } from './smartComments.js';
-import { renderRegisterCareInterface, renderRegisterCareReport } from './report.js';
-import { autoFixableCandidateKeys, findExpectOutFixesForCandidates } from './fix.js';
-import { findCallerOutputCandidateObservations, findRegisterCareConflicts, } from './liveness.js';
-import { buildAnnotations } from './annotations.js';
-import { buildOutputCandidateFixability, buildProfileSummaries, buildProfileSummaryLookup, buildSummaries, buildSummaryByName, outputCandidateKey, routineNames, unknownBoundaryDiagnostics, unknownCallList, withAcceptedOutputs, } from './summaries.js';
-function candidateMessageWithFixability(candidate, autoFixable) {
-    const carriers = candidate.carriers.join(',');
-    const expectation = candidate.carriers.length === 1 ? candidate.carriers[0] : `{${carriers}}`;
-    const base = `CALL ${candidate.routine} writes ${carriers} and caller reads it later`;
-    return autoFixable
-        ? `${base}; generated contracts promote this to \`out ${expectation}\` automatically.`
-        : `${base}; manual review required before adding \`; expects out ${expectation}\` because the later read is not a simple direct continuation.`;
-}
-export function analyzeRegisterCare(loaded, options) {
-    const file = loaded.program.files[0];
-    const items = file?.items ?? [];
-    const program = buildRegisterCareProgramModel(items);
-    const smartComments = parseSmartComments(loaded.sourceLineComments);
-    const contractMap = buildRoutineContracts(smartComments, program.routines, loaded.sourceTexts);
-    if (options.interfaceContracts !== undefined) {
-        for (const contract of options.interfaceContracts) {
-            contractMap.set(contract.name, contract);
-        }
-    }
-    const profileSummaries = buildProfileSummaries(options.registerCareProfile);
-    let summaries = buildSummaries(program.routines, contractMap, profileSummaries);
-    summaries = withAcceptedOutputs(summaries, options.acceptedOutputCandidates);
-    let summariesByName = buildSummaryByName(program.routines, summaries, profileSummaries);
-    const knownRoutines = new Set(routineNames(program.routines));
-    for (const [name] of contractMap) {
-        knownRoutines.add(name);
-    }
-    for (const name of buildProfileSummaryLookup(options.registerCareProfile).keys()) {
-        knownRoutines.add(name);
-    }
-    const diagnostics = [];
-    const shouldBuildOutputCandidates = options.mode !== 'off' ||
-        options.emitAnnotations === true ||
-        options.fixRegisterContracts === true;
-    const outputCandidates = shouldBuildOutputCandidates
-        ? findCallerOutputCandidateObservations(program.routines, summariesByName)
-        : [];
-    const autoAcceptedOutputs = autoAcceptedOutputCandidateMap(program.routines, outputCandidates, loaded.sourceTexts);
-    if (autoAcceptedOutputs.size > 0) {
-        summaries = withAcceptedOutputs(summaries, autoAcceptedOutputs);
-        summariesByName = buildSummaryByName(program.routines, summaries, profileSummaries);
-    }
-    const allSummaries = [...summaries, ...profileSummaries];
-    const conflicts = shouldBuildOutputCandidates
-        ? program.routines.flatMap((routine) => findRegisterCareConflicts(routine, summariesByName, smartComments))
-        : [];
-    const outputCandidateFixability = buildOutputCandidateFixability(program.routines, outputCandidates, autoFixableCandidateKeys);
-    const outputCandidatesWithFixability = outputCandidates.map((candidate) => {
-        const autoFixable = outputCandidateFixability.get(outputCandidateKey(candidate.file, candidate.line, candidate.column)) ?? false;
-        return {
-            ...candidate,
-            autoFixable,
-            message: candidateMessageWithFixability(candidate, autoFixable),
-        };
-    });
-    if (options.mode !== 'audit') {
-        for (const conflict of conflicts) {
-            diagnostics.push({
-                severity: options.mode === 'error' ? 'error' : 'warning',
-                code: 'AZMN_REGISTER_CARE',
-                sourceName: conflict.file,
-                line: conflict.line,
-                column: conflict.column,
-                message: conflict.message,
-            });
-        }
-    }
-    if (options.mode === 'strict') {
-        diagnostics.push(...unknownBoundaryDiagnostics(program.directBoundaries, knownRoutines));
-    }
-    const reportModel = {
-        entryFile: loaded.program.entryFile,
-        mode: options.mode,
-        summaries: allSummaries,
-        conflicts,
-        outputCandidates: outputCandidatesWithFixability,
-        ...(options.registerCareProfile !== undefined ? { profile: options.registerCareProfile } : {}),
-        unknownCalls: options.mode === 'off' ? [] : unknownCallList(program.directBoundaries, knownRoutines),
-    };
-    const summariesForAnnotations = new Map(summariesByName);
-    const outputCandidatesByRoutine = new Map();
-    for (const candidate of outputCandidatesWithFixability) {
-        const existing = outputCandidatesByRoutine.get(candidate.routine) ?? [];
-        for (const unit of candidate.carriers) {
-            if (!existing.includes(unit))
-                existing.push(unit);
-        }
-        outputCandidatesByRoutine.set(candidate.routine, existing);
-    }
-    for (const [name, summary] of summariesForAnnotations) {
-        const candidates = outputCandidatesByRoutine.get(name);
-        if (candidates !== undefined && candidates.length > 0) {
-            summariesForAnnotations.set(name, { ...summary, outputCandidates: candidates });
-        }
-    }
-    const annotations = options.emitAnnotations
-        ? buildAnnotations(loaded, program.routines, summariesForAnnotations, outputCandidatesWithFixability, {
-            fixOutputCandidates: options.fixRegisterContracts === true,
-            outputCandidateFixability,
-            outputCandidateKey,
-        })
-        : [];
-    return {
-        diagnostics,
-        outputCandidates: outputCandidatesWithFixability,
-        ...(options.emitReport ? { reportText: renderRegisterCareReport(reportModel) } : {}),
-        ...(options.emitInterface ? { interfaceText: renderRegisterCareInterface(summaries) } : {}),
-        ...(annotations.length > 0 ? { annotations } : {}),
-        ...(reportModel.unknownCalls.length > 0 ? { unknownCalls: reportModel.unknownCalls } : {}),
-    };
-}
-function autoAcceptedOutputCandidateMap(routines, outputCandidates, sourceTexts) {
-    const out = new Map();
-    const sourceMaybeOut = sourceMaybeOutByRoutine(routines, sourceTexts);
-    for (const fix of findExpectOutFixesForCandidates([...routines], [...outputCandidates])) {
-        const declaredMaybeOut = sourceMaybeOut.get(fix.routine) ?? [];
-        const eligibleCarriers = fix.carriers.filter((carrier) => declaredMaybeOut.includes(carrier));
-        if (eligibleCarriers.length === 0)
-            continue;
-        const carriers = out.get(fix.routine) ?? [];
-        for (const carrier of eligibleCarriers) {
-            if (!carriers.includes(carrier))
-                carriers.push(carrier);
-        }
-        out.set(fix.routine, carriers);
-    }
-    return out;
-}
-function sourceMaybeOutByRoutine(routines, sourceTexts) {
-    const out = new Map();
-    for (const routine of routines) {
-        const source = sourceTexts.get(routine.span.file);
-        if (source === undefined)
-            continue;
-        const lines = source.split(/\r?\n/);
-        const units = [];
-        for (let index = routine.span.start.line - 2; index >= 0; index -= 1) {
-            const text = lines[index] ?? '';
-            if (!/^\s*;/.test(text))
-                break;
-            const match = /^\s*;\s*!\s*maybe-out\s+(.+)$/i.exec(text);
-            if (!match)
-                continue;
-            for (const token of match[1].split(',')) {
-                const unit = token.trim();
-                if (unit.length > 0 && !units.includes(unit))
-                    units.push(unit);
-            }
-        }
-        if (units.length === 0)
-            continue;
-        out.set(routine.name, units);
-        for (const label of routine.labels)
-            out.set(label, units);
-        for (const label of routine.entryLabels)
-            out.set(label, units);
-    }
-    return out;
-}

package/dist/src/register-care/annotate.d.ts

@@ -1,11 +0,0 @@
-import type { RegisterCareRoutine, RoutineSummary } from './types.js';
-export interface RegisterCareAnnotatedFile {
-    path: string;
-    text: string;
-}
-interface RegisterCareAnnotationInput {
-    routine: RegisterCareRoutine;
-    summary: RoutineSummary;
-}
-export declare function annotateRegisterCareContracts(sourceTexts: ReadonlyMap<string, string>, routines: RegisterCareAnnotationInput[]): RegisterCareAnnotatedFile[];
-export {};

package/dist/src/register-care/annotations.d.ts

@@ -1,8 +0,0 @@
-import type { RegisterCareAnnotationFile, RegisterCareOutputCandidate, RegisterCareRoutine, RoutineSummary } from './types.js';
-export declare function buildAnnotations(loaded: {
-    sourceTexts: ReadonlyMap<string, string>;
-}, programRoutines: readonly RegisterCareRoutine[], summariesByName: ReadonlyMap<string, RoutineSummary>, outputCandidates: readonly RegisterCareOutputCandidate[], options: {
-    fixOutputCandidates: boolean;
-    outputCandidateFixability: ReadonlyMap<string, boolean>;
-    outputCandidateKey: (file: string, line: number, column: number) => string;
-}): readonly RegisterCareAnnotationFile[];

package/dist/src/register-care/boundaryHints.d.ts

@@ -1,3 +0,0 @@
-import type { RegisterCareInstruction } from './types.js';
-export declare function precedingCServiceName(item: RegisterCareInstruction | undefined): string | undefined;
-export declare function precedingRegisterImmediateValue(item: RegisterCareInstruction | undefined, register: string): number | undefined;

package/dist/src/register-care/boundaryHints.js

@@ -1,80 +0,0 @@
-export function precedingCServiceName(item) {
-    const instruction = item?.instruction;
-    if (!instruction || instruction.mnemonic !== 'ld')
-        return undefined;
-    if (instruction.target?.kind !== 'reg8' || instruction.target.register !== 'c')
-        return undefined;
-    if (instruction.source.kind === 'imm' && instruction.source.expression.kind === 'symbol') {
-        return instruction.source.expression.name;
-    }
-    return undefined;
-}
-function evaluateKnownConstant(expression, constants) {
-    switch (expression.kind) {
-        case 'number':
-            return expression.value;
-        case 'symbol':
-            return constants.get(expression.name);
-        case 'unary': {
-            const value = evaluateKnownConstant(expression.expression, constants);
-            if (value === undefined)
-                return undefined;
-            switch (expression.operator) {
-                case '+':
-                    return value;
-                case '-':
-                    return -value;
-                case '~':
-                    return ~value;
-            }
-        }
-        case 'binary': {
-            const left = evaluateKnownConstant(expression.left, constants);
-            const right = evaluateKnownConstant(expression.right, constants);
-            if (left === undefined || right === undefined)
-                return undefined;
-            switch (expression.operator) {
-                case '+':
-                    return left + right;
-                case '-':
-                    return left - right;
-                case '*':
-                    return left * right;
-                case '/':
-                    return right === 0 ? undefined : Math.trunc(left / right);
-                case '%':
-                    return right === 0 ? undefined : left % right;
-                case '&':
-                    return left & right;
-                case '^':
-                    return left ^ right;
-                case '|':
-                    return left | right;
-                case '<<':
-                    return left << right;
-                case '>>':
-                    return left >> right;
-            }
-        }
-        case 'byte-function': {
-            const value = evaluateKnownConstant(expression.expression, constants);
-            if (value === undefined)
-                return undefined;
-            return expression.function === 'LSB' ? value & 0xff : (value >> 8) & 0xff;
-        }
-        default:
-            return undefined;
-    }
-}
-export function precedingRegisterImmediateValue(item, register) {
-    const instruction = item?.instruction;
-    if (!instruction || instruction.mnemonic !== 'ld')
-        return undefined;
-    if (instruction.target?.kind !== 'reg8' ||
-        instruction.target.register !== register.toLowerCase()) {
-        return undefined;
-    }
-    if (instruction.source.kind !== 'imm')
-        return undefined;
-    return evaluateKnownConstant(instruction.source.expression, item.constants ?? new Map());
-}

package/dist/src/register-care/carriers.d.ts

@@ -1,2 +0,0 @@
-import type { RegisterCareUnit } from './types.js';
-export declare function expandCarrierList(raw: readonly string[]): RegisterCareUnit[] | undefined;

package/dist/src/register-care/controlFlow.d.ts

@@ -1,5 +0,0 @@
-import type { InstructionEffect, RegisterCareRoutine } from './types.js';
-export declare function labelIndex(routine: RegisterCareRoutine): Map<string, number>;
-export declare function instructionSuccessors(routine: RegisterCareRoutine, index: number, effect: InstructionEffect, labels: ReadonlyMap<string, number>, options?: {
-    boundaryFallthrough?: boolean;
-}): number[];

package/dist/src/register-care/controlFlow.js

@@ -1,38 +0,0 @@
-function unique(items) {
-    return [...new Set(items)];
-}
-export function labelIndex(routine) {
-    const out = new Map();
-    routine.instructions.forEach((item, index) => {
-        for (const label of item.labels)
-            out.set(label, index);
-    });
-    return out;
-}
-function localTargetIndex(labels, target) {
-    if (!target)
-        return undefined;
-    return labels.get(target);
-}
-export function instructionSuccessors(routine, index, effect, labels, options = {}) {
-    const next = index + 1 < routine.instructions.length ? index + 1 : undefined;
-    if (effect.control.kind === 'fallthrough' ||
-        (options.boundaryFallthrough &&
-            (effect.control.kind === 'call' || effect.control.kind === 'rst'))) {
-        return next === undefined ? [] : [next];
-    }
-    if (effect.control.kind === 'jump') {
-        const target = localTargetIndex(labels, effect.control.target);
-        if (effect.control.conditional) {
-            return unique([
-                ...(target === undefined ? [] : [target]),
-                ...(next === undefined ? [] : [next]),
-            ]);
-        }
-        return target === undefined ? [] : [target];
-    }
-    if (effect.control.kind === 'return') {
-        return effect.control.conditional && next !== undefined ? [next] : [];
-    }
-    return [];
-}

package/dist/src/register-care/fix.d.ts

@@ -1,11 +0,0 @@
-import type { RegisterCareOutputCandidate, RegisterCareRoutine, RegisterCareUnit } from './types.js';
-export interface RegisterCareExpectOutFix {
-    file: string;
-    line: number;
-    column: number;
-    routine: string;
-    carriers: RegisterCareUnit[];
-}
-export declare function findExpectOutFixesForCandidates(routines: RegisterCareRoutine[], candidates: RegisterCareOutputCandidate[]): RegisterCareExpectOutFix[];
-export declare function autoFixableCandidateKeys(routines: RegisterCareRoutine[], candidates: RegisterCareOutputCandidate[]): Set<string>;
-export declare function applyExpectOutFixesToSource(source: string, fixes: RegisterCareExpectOutFix[], referenceSource?: string): string;

package/dist/src/register-care/instruction-shape.d.ts

@@ -1,11 +0,0 @@
-import type { Z80Instruction, Z80Operand } from '../z80/instruction.js';
-import type { RegisterCareInstruction } from './types.js';
-export declare function instructionHead(item: RegisterCareInstruction): string;
-export declare function regName(operand: Z80Operand | undefined): string | undefined;
-export declare function instructionOperandCount(instruction: Z80Instruction): number;
-export declare function instructionOperand(instruction: Z80Instruction, index: number): Z80Operand | undefined;
-export declare function isUnconditionalReturnInstruction(item: RegisterCareInstruction): boolean;
-export declare function isPureTokenTransferInstruction(item: RegisterCareInstruction): boolean;
-export declare function isAccumulatorSelfOperand(item: RegisterCareInstruction): boolean;
-export declare function isImmediateZeroOperand(item: RegisterCareInstruction): boolean;
-export declare function isRegisterOperand(item: RegisterCareInstruction | undefined, index: number, name: string): boolean;

package/dist/src/register-care/instruction-shape.js

@@ -1,129 +0,0 @@
-export function instructionHead(item) {
-    return item.instruction.mnemonic.toLowerCase();
-}
-export function regName(operand) {
-    if (operand === undefined)
-        return undefined;
-    switch (operand.kind) {
-        case 'reg8':
-            return operand.register.toUpperCase();
-        case 'reg16':
-            return operand.register.toUpperCase();
-        case 'reg-index16':
-            return operand.register.toUpperCase();
-        case 'reg-half-index':
-            return operand.register.toUpperCase();
-        default:
-            return undefined;
-    }
-}
-function immValue(operand) {
-    if (operand?.kind !== 'imm')
-        return undefined;
-    const expression = operand.expression;
-    return expression.kind === 'number' ? expression.value : undefined;
-}
-export function instructionOperandCount(instruction) {
-    switch (instruction.mnemonic) {
-        case 'ret':
-        case 'ret-cc':
-            return instruction.mnemonic === 'ret' ? 0 : 1;
-        case 'ld':
-            return 2;
-        case 'ex':
-            return 2;
-        case 'jp':
-        case 'jp-cc':
-        case 'jr':
-        case 'jr-cc':
-        case 'djnz':
-        case 'call':
-        case 'call-cc':
-            return 1;
-        case 'add':
-        case 'adc':
-        case 'sbc':
-            return 'target' in instruction ? 2 : 1;
-        case 'sub':
-        case 'and':
-        case 'or':
-        case 'xor':
-        case 'cp':
-            return 1;
-        default:
-            return 0;
-    }
-}
-export function instructionOperand(instruction, index) {
-    switch (instruction.mnemonic) {
-        case 'ld':
-            return index === 0 ? instruction.target : index === 1 ? instruction.source : undefined;
-        case 'ex': {
-            if (index === 0) {
-                return instruction.form === 'de-hl'
-                    ? { kind: 'reg16', register: 'de' }
-                    : instruction.form === 'af-af'
-                        ? { kind: 'reg16', register: 'af' }
-                        : undefined;
-            }
-            if (index === 1) {
-                return instruction.form === 'de-hl'
-                    ? { kind: 'reg16', register: 'hl' }
-                    : undefined;
-            }
-            return undefined;
-        }
-        case 'add':
-        case 'adc':
-        case 'sbc':
-            if ('target' in instruction) {
-                return index === 0 ? instruction.target : index === 1 ? instruction.source : undefined;
-            }
-            return index === 0 ? instruction.source : undefined;
-        case 'sub':
-        case 'and':
-        case 'or':
-        case 'xor':
-        case 'cp':
-            return index === 0 ? instruction.source : undefined;
-        default:
-            return undefined;
-    }
-}
-export function isUnconditionalReturnInstruction(item) {
-    const head = instructionHead(item);
-    if (head === 'ret')
-        return item.instruction.mnemonic === 'ret';
-    return head === 'retn' || head === 'reti';
-}
-export function isPureTokenTransferInstruction(item) {
-    const head = instructionHead(item);
-    if (head === 'ex')
-        return true;
-    if (head !== 'ld' || instructionOperandCount(item.instruction) !== 2)
-        return false;
-    const dst = instructionOperand(item.instruction, 0);
-    const src = instructionOperand(item.instruction, 1);
-    if (regName(dst) === undefined)
-        return false;
-    return regName(src) !== undefined || src?.kind === 'imm';
-}
-export function isAccumulatorSelfOperand(item) {
-    const inst = item.instruction;
-    if (inst.mnemonic === 'or' || inst.mnemonic === 'and' || inst.mnemonic === 'xor') {
-        return inst.source.kind === 'reg8' && inst.source.register === 'a';
-    }
-    return false;
-}
-export function isImmediateZeroOperand(item) {
-    const inst = item.instruction;
-    if (inst.mnemonic !== 'cp')
-        return false;
-    return immValue(inst.source) === 0;
-}
-export function isRegisterOperand(item, index, name) {
-    if (item === undefined)
-        return false;
-    const operand = instructionOperand(item.instruction, index);
-    return regName(operand) === name.toUpperCase();
-}

package/dist/src/register-care/liveness.d.ts

@@ -1,3 +0,0 @@
-import type { LocatedSmartComment, RegisterCareConflict, RegisterCareOutputCandidate, RegisterCareRoutine, RoutineSummary } from './types.js';
-export declare function findRegisterCareConflicts(routine: RegisterCareRoutine, summaries: Map<string, RoutineSummary>, hints: LocatedSmartComment[]): RegisterCareConflict[];
-export declare function findCallerOutputCandidateObservations(routines: RegisterCareRoutine[], summaries: Map<string, RoutineSummary>): RegisterCareOutputCandidate[];

package/dist/src/register-care/programModel.d.ts

@@ -1,3 +0,0 @@
-import type { SourceItem } from '../model/source-item.js';
-import type { RegisterCareProgramModel } from './types.js';
-export declare function buildRegisterCareProgramModel(items: readonly SourceItem[]): RegisterCareProgramModel;