@jhlagado/azm 0.2.8 → 0.2.10

package/README.md

@@ -120,9 +120,7 @@ Use `@Name:` for callable routine entries. The `@` marks a register contracts
 routine boundary; call sites still write the symbol name without `@`:
 
 ```asm
-;!      in        A
-;!      out       A
-;!      clobbers  BC
+;! in A; out A; clobbers BC
 @MxMask:
         LD      C,A
         OR      A
@@ -335,18 +333,78 @@ azm -I include -I vendor program.asm
 Included source contributes labels, constants, enums, types, ops and routines to
 the same assembly.
 
+## Imports
+
+`.import` is AZM's module-style source composition directive:
+
+```asm
+; main.asm
+        .import "keyboard.asm"
+
+@Start:
+        call    ReadKey
+        ret
+```
+
+```asm
+; keyboard.asm
+@ReadKey:
+        call    ScanMatrix
+        ret
+
+ScanMatrix:
+        xor     a
+        ret
+```
+
+Imported source assembles at the point where `.import` appears, so native
+`.bin`, `.hex` and `.d8.json` output contain the imported bytes as part of the
+same program. Paths resolve like includes: relative to the importing file first,
+then through `-I` include directories.
+
+The difference is visibility. In an imported file, labels written with `@` are
+public exports. Code outside `keyboard.asm` can call `ReadKey`, using the name
+without `@`. Plain labels in an imported file, such as `ScanMatrix`, are private
+to that imported file or import unit. The imported file may call its own private
+helpers, but outside references fail with a direct visibility diagnostic.
+
+`.include` remains textual. Included text belongs to the including source unit
+and is intended for shared constants, declarations and compatibility source.
+Use `.import` when a source file should behave like a module with public `@`
+entry points and private implementation labels.
+
+Repeated imports of the same resolved file are idempotent: the first import
+loads and emits the module, later imports of that same file are skipped.
+Repeated includes are still textual and repeat every time. Recursive includes or
+imports are rejected with source diagnostics.
+
+Register contracts use the same `@` routine boundaries across imported files.
+Imported public routines are analyzed as internal routines under `--rc strict`,
+and private helpers called inside an imported public routine are summarized as
+part of the same program analysis.
+
+ASM80-compatible lowered `.z80` output does not yet support imported source
+units. If `--asm80` is requested for a program that uses `.import`, AZM reports
+an explicit `AZMN_ASM80` diagnostic instead of silently flattening the module
+boundary. Use native `.bin`, `.hex` and `.d8.json` output for imported programs.
+
 ## Register Contracts
 
 Register contracts check whether subroutines preserve the register values that their
 callers still need. It is designed to catch register collisions, a common source
 of assembly bugs.
 
+The benefit is practical: AZM can stop a plausible-looking routine at compile
+time when it reads a register after calling code that may clobber it. In larger
+Z80 projects this encourages smaller routines, clearer `@` boundaries, explicit
+helper outputs, and proof or test harnesses that stay honest under
+`--rc strict`. The friction is intentional: strict contracts make hidden
+register and stack assumptions visible before they become debugger sessions.
+
 Routine entry labels start with `@`:
 
 ```asm
-;! in A,HL
-;! out carry
-;! clobbers B
+;! in A,HL; out carry; clobbers B
 @CheckTile:
         ld      b,(hl)
         cp      b
@@ -361,9 +419,11 @@ name:
 ```
 
 AZMDoc register contract comments use `;!` and may record inputs, outputs,
-clobbered registers and preserved registers. `clobbers B` means the routine may
-change `B`. `preserves B` means the value that enters in `B` is still present
-when the routine returns.
+clobbered registers and preserved registers. Separate clauses on the same line
+with semicolons. Older one-clause-per-line comments are still accepted, but AZM
+generated annotations use the compact single-line form. `clobbers B` means the
+routine may change `B`. `preserves B` means the value that enters in `B` is
+still present when the routine returns.
 
 Run the analysis with:
 
@@ -498,8 +558,8 @@ The main switches are:
 | `-V, --version`                               | Print package version.                                              |
 | `-h, --help`                                  | Print CLI help.                                                     |
 
-See [docs/reference/cli.md](docs/reference/cli.md) for the complete option
-reference.
+See the [AZM Engineering Manual](docs/codebase/) for the maintained codebase,
+CLI and package-interface reference.
 
 ## Output Artifacts
 
@@ -618,8 +678,8 @@ Public tooling types include `Diagnostic`, `LoadedProgram`,
 `AnalyzeProgramResult`, `LoadProgramResult`, `RegisterContractsCandidateDiagnostic`
 and the Debug80 map artifact types `D8mArtifact`, `D8mJson` and `D8mSymbol`.
 
-See [docs/reference/tooling-api.md](docs/reference/tooling-api.md) for current
-API notes.
+See the [public surface reference](docs/codebase/appendices/c-public-surface-reference.md)
+for current API notes.
 
 ## Development
 
@@ -634,8 +694,8 @@ npm run test:azm:corpus
 npm test
 ```
 
-The live source map is maintained in
-[docs/reference/source-overview.md](docs/reference/source-overview.md).
+The live source map is maintained in the
+[AZM Engineering Manual](docs/codebase/).
 
 ## License
 

package/dist/src/api-compile.js

@@ -59,6 +59,10 @@ export async function compile(entryFile, options = {}, deps = { formats: default
         ? !isSuppressedUnknownSymbolInRegisterContractsMode(diagnostic, directCalls)
         : true));
     const artifacts = [];
+    if (hasErrors(diagnostics)) {
+        sortDiagnosticsInPlace(diagnostics);
+        return { diagnostics, artifacts };
+    }
     if (analyzeRegisterContractsNow) {
         const registerContracts = await runRegisterContracts(loaded.loadedProgram, options);
         artifacts.push(...registerContracts.artifacts);
@@ -97,6 +101,7 @@ function hasErrors(diagnostics) {
     return diagnostics.some((diagnostic) => diagnostic.severity === 'error');
 }
 function sortDiagnosticsInPlace(diagnostics) {
+    dedupeDiagnosticsInPlace(diagnostics);
     diagnostics.sort((left, right) => {
         const lineDelta = (left.line ?? 0) - (right.line ?? 0);
         if (lineDelta !== 0) {
@@ -105,3 +110,25 @@ function sortDiagnosticsInPlace(diagnostics) {
         return (left.column ?? 0) - (right.column ?? 0);
     });
 }
+function dedupeDiagnosticsInPlace(diagnostics) {
+    const seen = new Set();
+    for (let index = diagnostics.length - 1; index >= 0; index -= 1) {
+        const diagnostic = diagnostics[index];
+        const key = diagnosticKey(diagnostic);
+        if (seen.has(key)) {
+            diagnostics.splice(index, 1);
+            continue;
+        }
+        seen.add(key);
+    }
+}
+function diagnosticKey(diagnostic) {
+    return [
+        diagnostic.severity,
+        diagnostic.code,
+        diagnostic.message,
+        diagnostic.sourceName ?? '',
+        diagnostic.line ?? '',
+        diagnostic.column ?? '',
+    ].join('\0');
+}

package/dist/src/assembly/assemble-program.js

@@ -1,4 +1,5 @@
 import { buildAddressState, resolveSymbols } from './address-planning.js';
+import { validateImportVisibility } from './import-visibility.js';
 import { emitProgramImage } from './program-emission.js';
 function emptyAssemblyResult(diagnostics, partial = {}) {
     return {
@@ -13,6 +14,10 @@ function emptyAssemblyResult(diagnostics, partial = {}) {
 }
 export function assembleProgram(items) {
     const diagnostics = [];
+    validateImportVisibility(items, diagnostics);
+    if (diagnostics.length > 0) {
+        return emptyAssemblyResult(diagnostics);
+    }
     const addressState = buildAddressState(items, diagnostics);
     if (diagnostics.length > 0) {
         return emptyAssemblyResult(diagnostics, { origin: addressState.origin });

package/dist/src/assembly/import-visibility.d.ts

@@ -0,0 +1,3 @@
+import type { Diagnostic } from '../model/diagnostic.js';
+import type { SourceItem } from '../model/source-item.js';
+export declare function validateImportVisibility(items: readonly SourceItem[], diagnostics: Diagnostic[]): void;

package/dist/src/assembly/import-visibility.js

@@ -0,0 +1,204 @@
+import { diagnostic } from '../semantics/diagnostics.js';
+export function validateImportVisibility(items, diagnostics) {
+    const labels = collectLabelVisibility(items);
+    for (const item of items) {
+        validateItemReferences(item, labels, diagnostics);
+    }
+}
+function collectLabelVisibility(items) {
+    const labels = new Map();
+    const importedSourceUnits = importedUnitNames(items);
+    for (const item of items) {
+        if (item.kind !== 'label')
+            continue;
+        labels.set(item.name, {
+            name: item.name,
+            definingSourceUnit: item.span.sourceUnit,
+            definingSourceName: item.span.sourceName,
+            public: isPublicLabel(item, importedSourceUnits),
+        });
+    }
+    return labels;
+}
+function importedUnitNames(items) {
+    const units = new Set();
+    for (const item of items) {
+        if (item.span.sourceRelation === 'import' && item.span.sourceUnit !== undefined) {
+            units.add(item.span.sourceUnit);
+        }
+    }
+    return units;
+}
+function isPublicLabel(item, importedSourceUnits) {
+    return (item.isEntry === true ||
+        item.span.sourceUnit === undefined ||
+        !importedSourceUnits.has(item.span.sourceUnit));
+}
+function validateItemReferences(item, labels, diagnostics) {
+    switch (item.kind) {
+        case 'org':
+            validateExpression(item.expression, item.span, labels, diagnostics);
+            return;
+        case 'equ':
+            validateExpression(item.expression, item.span, labels, diagnostics);
+            return;
+        case 'db':
+            for (const value of item.values) {
+                validateDataValue(value, item.span, labels, diagnostics);
+            }
+            return;
+        case 'dw':
+            for (const value of item.values) {
+                validateExpression(value, item.span, labels, diagnostics);
+            }
+            return;
+        case 'ds':
+            validateExpression(item.size, item.span, labels, diagnostics);
+            if (item.fill !== undefined) {
+                validateExpression(item.fill, item.span, labels, diagnostics);
+            }
+            return;
+        case 'align':
+            validateExpression(item.alignment, item.span, labels, diagnostics);
+            return;
+        case 'binfrom':
+        case 'binto':
+            validateExpression(item.expression, item.span, labels, diagnostics);
+            return;
+        case 'instruction':
+            validateInstruction(item.instruction, item.span, labels, diagnostics);
+            return;
+        case 'label':
+        case 'comment':
+        case 'end':
+        case 'enum':
+        case 'type':
+        case 'type-alias':
+        case 'string-data':
+            return;
+    }
+}
+function validateDataValue(value, span, labels, diagnostics) {
+    if ('kind' in value && value.kind === 'string-fragment')
+        return;
+    validateExpression(value, span, labels, diagnostics);
+}
+function validateInstruction(instruction, span, labels, diagnostics) {
+    for (const expression of instructionExpressions(instruction)) {
+        validateExpression(expression, span, labels, diagnostics);
+    }
+}
+function instructionExpressions(instruction) {
+    switch (instruction.mnemonic) {
+        case 'ld-a-imm':
+        case 'jp':
+        case 'call':
+        case 'jr':
+        case 'djnz':
+            return [instruction.expression];
+        case 'jp-cc':
+        case 'call-cc':
+        case 'jr-cc':
+            return [instruction.expression];
+        case 'ld':
+            return [...operandExpressions(instruction.target), ...operandExpressions(instruction.source)];
+        case 'in':
+            return instruction.port.kind === 'imm' ? [instruction.port.expression] : [];
+        case 'out':
+            return instruction.port.kind === 'imm' ? [instruction.port.expression] : [];
+        case 'inc':
+        case 'dec':
+            return 'displacement' in instruction.operand ? [instruction.operand.displacement] : [];
+        case 'bit':
+        case 'res':
+        case 'set':
+        case 'rlc':
+        case 'rrc':
+        case 'rl':
+        case 'rr':
+        case 'sla':
+        case 'sra':
+        case 'sll':
+        case 'sls':
+        case 'srl':
+            return 'displacement' in instruction.operand ? [instruction.operand.displacement] : [];
+        case 'add':
+            if ('source' in instruction && 'target' in instruction) {
+                return [
+                    ...operandExpressions(instruction.target),
+                    ...operandExpressions(instruction.source),
+                ];
+            }
+            return 'source' in instruction ? operandExpressions(instruction.source) : [];
+        case 'adc':
+        case 'sbc':
+            return 'source' in instruction ? operandExpressions(instruction.source) : [];
+        case 'sub':
+        case 'and':
+        case 'or':
+        case 'xor':
+        case 'cp':
+            return operandExpressions(instruction.source);
+        default:
+            return [];
+    }
+}
+function operandExpressions(operand) {
+    switch (operand.kind) {
+        case 'mem-abs':
+        case 'imm':
+            return [operand.expression];
+        case 'indexed':
+            return [operand.displacement];
+        default:
+            return [];
+    }
+}
+function validateExpression(expression, span, labels, diagnostics) {
+    switch (expression.kind) {
+        case 'symbol':
+            validateSymbolReference(expression.name, span, labels, diagnostics);
+            return;
+        case 'byte-function':
+        case 'unary':
+            validateExpression(expression.expression, span, labels, diagnostics);
+            return;
+        case 'binary':
+            validateExpression(expression.left, span, labels, diagnostics);
+            validateExpression(expression.right, span, labels, diagnostics);
+            return;
+        case 'layout-cast':
+            validateExpression(expression.base, span, labels, diagnostics);
+            for (const part of expression.path) {
+                if (part.kind === 'index') {
+                    validateExpression(part.expression, span, labels, diagnostics);
+                }
+            }
+            return;
+        case 'number':
+        case 'current-location':
+        case 'type-size':
+        case 'sizeof':
+        case 'offset':
+            return;
+    }
+}
+function validateSymbolReference(name, referenceSpan, labels, diagnostics) {
+    const label = lookupLabel(labels, name);
+    if (!label || label.public)
+        return;
+    if (referenceSpan.sourceUnit === label.definingSourceUnit)
+        return;
+    diagnostics.push(diagnostic(referenceSpan, `symbol "${name}" is private to ${label.definingSourceName}; export it with @${label.name} or keep the reference inside that file`));
+}
+function lookupLabel(labels, name) {
+    const direct = labels.get(name);
+    if (direct)
+        return direct;
+    const lowerName = name.toLowerCase();
+    for (const [key, label] of labels) {
+        if (key.toLowerCase() === lowerName)
+            return label;
+    }
+    return undefined;
+}

package/dist/src/node/source-host.js

@@ -18,6 +18,7 @@ export async function expandSourceForTooling(options) {
     }
     const sourceTexts = new Map();
     const sourceLineComments = new Map();
+    const loadedImports = new Set();
     const includeDirs = (options.includeDirs ?? []).map((path) => normalize(path));
     const lines = await expandFile({
         sourcePath: entryFile,
@@ -25,7 +26,10 @@ export async function expandSourceForTooling(options) {
         sourceTexts,
         sourceLineComments,
         diagnostics,
-        includeStack: [],
+        loadedImports,
+        sourceStack: [],
+        sourceUnit: entryFile,
+        sourceRelation: 'entry',
         ...(options.preloadedText !== undefined ? { preloadedText: options.preloadedText } : {}),
         ...(options.signal !== undefined ? { signal: options.signal } : {}),
     });
@@ -37,11 +41,11 @@ export async function expandSourceForTooling(options) {
 async function expandFile(options) {
     options.signal?.throwIfAborted();
     const sourcePath = normalize(options.sourcePath);
-    if (options.includeStack.includes(sourcePath)) {
+    if (options.sourceStack.some((entry) => entry.sourcePath === sourcePath)) {
         options.diagnostics.push({
             severity: 'error',
             code: 'AZMN_SOURCE',
-            message: `recursive include: ${sourcePath}`,
+            message: `recursive ${options.sourceRelation}: ${sourcePath}`,
             sourceName: sourcePath,
         });
         return undefined;
@@ -54,28 +58,36 @@ async function expandFile(options) {
     const output = [];
     for (const line of scanLogicalLines(createSourceFile(sourcePath, text))) {
         recordLineComment(options.sourceLineComments, line);
-        const includePath = parseIncludePath(line.text);
-        if (!includePath) {
-            output.push(line);
+        const directive = parseSourceLoadDirective(line.text);
+        if (!directive) {
+            output.push(withSourceOwnership(line, options.sourceUnit, options.sourceRelation));
             continue;
         }
-        const result = await resolveInclude(sourcePath, includePath, options.includeDirs);
+        const result = await resolveSourcePath(sourcePath, directive.path, options.includeDirs);
         if (result.resolved === undefined) {
             options.diagnostics.push({
                 severity: 'error',
                 code: 'AZMN_SOURCE',
-                message: `Failed to resolve include "${includePath}" from "${sourcePath}". Tried:\n${result.searchCandidates.map((candidate) => `- ${candidate}`).join('\n')}`,
+                message: `Failed to resolve ${directive.kind} "${directive.path}" from "${sourcePath}". Tried:\n${result.searchCandidates.map((candidate) => `- ${candidate}`).join('\n')}`,
                 sourceName: sourcePath,
                 line: line.line,
                 column: firstColumn(line.text),
             });
             continue;
         }
+        if (directive.kind === 'import' && options.loadedImports.has(result.resolved)) {
+            continue;
+        }
+        if (directive.kind === 'import') {
+            options.loadedImports.add(result.resolved);
+        }
         const { preloadedText: _preloadedText, ...includeOptions } = options;
         const included = await expandFile({
             ...includeOptions,
             sourcePath: result.resolved,
-            includeStack: [...options.includeStack, sourcePath],
+            sourceStack: [...options.sourceStack, { sourcePath }],
+            sourceUnit: directive.kind === 'import' ? result.resolved : options.sourceUnit,
+            sourceRelation: directive.kind,
         });
         if (included !== undefined) {
             output.push(...included);
@@ -83,6 +95,13 @@ async function expandFile(options) {
     }
     return output;
 }
+function withSourceOwnership(line, sourceUnit, sourceRelation) {
+    return {
+        ...line,
+        sourceUnit,
+        sourceRelation,
+    };
+}
 function recordLineComment(comments, line) {
     const commentText = lineComment(line.text);
     if (commentText === undefined) {
@@ -112,7 +131,7 @@ async function readSourceText(options, sourcePath) {
         return undefined;
     }
 }
-async function resolveInclude(importer, includePath, includeDirs) {
+async function resolveSourcePath(importer, includePath, includeDirs) {
     const candidates = [
         join(dirname(importer), includePath),
         ...includeDirs.map((dir) => join(dir, includePath)),
@@ -128,9 +147,17 @@ async function resolveInclude(importer, includePath, includeDirs) {
     }
     return { searchCandidates: candidates.map(normalize) };
 }
-function parseIncludePath(text) {
-    const match = /^\.?include\s+"([^"]+)"\s*$/i.exec(stripLineComment(text).trim());
-    return match?.[1];
+function parseSourceLoadDirective(text) {
+    const trimmed = stripLineComment(text).trim();
+    const include = /^\.?include\s+"([^"]+)"\s*$/i.exec(trimmed);
+    if (include) {
+        return { kind: 'include', path: include[1] ?? '' };
+    }
+    const sourceImport = /^\.import\s+"([^"]+)"\s*$/.exec(trimmed);
+    if (sourceImport) {
+        return { kind: 'import', path: sourceImport[1] ?? '' };
+    }
+    return undefined;
 }
 function lineComment(text) {
     const prefix = stripLineComment(text);

package/dist/src/outputs/write-asm80.js

@@ -31,6 +31,10 @@ export class UnsupportedAsm80LoweringError extends Error {
 }
 export function writeAsm80(items, symbols, opts = {}) {
     void opts;
+    const importedItem = items.find((item) => item.span.sourceRelation === 'import');
+    if (importedItem !== undefined) {
+        throw new UnsupportedAsm80LoweringError('lowered .z80 output does not yet support .import source units', importedItem);
+    }
     const evalContext = {
         constants: collectConstants(symbols),
         symbols: collectSymbolValues(symbols),

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

@@ -49,8 +49,8 @@ function flushRoutine(routines, state, constants) {
         span: routineSpan(state, end),
     });
 }
-function resetAndStart(routines, state, constants, item) {
-    flushRoutine(routines, state, constants);
+function resetAndStart(routines, state, context, item) {
+    flushRoutine(routines, state, context.constants);
     Object.assign(state, emptyState());
     startRoutine(state, item);
 }
@@ -60,69 +60,85 @@ function appendDirectCall(directCalls, item) {
         return;
     pushDirectBoundary(directCalls, directTarget, `CALL ${directTarget}`, item.span.sourceName, item.span.line, item.span.column);
 }
-function handleInstruction(state, directCalls, item, constants) {
+function handleInstruction(state, directCalls, item, context) {
     if (state.routineName === undefined || state.sourceName === undefined)
         return;
     if (item.span.sourceName !== state.sourceName)
         return;
-    state.instructions.push(toInstruction(item, state.labels, constants));
+    state.instructions.push(toInstruction(item, state.labels, context.constants));
     appendDirectCall(directCalls, item);
 }
-function handleGlobalLabel(routines, state, item, constants, filesWithEntryLabels) {
+function handleGlobalLabel(routines, state, item, context) {
     if (state.routineName === undefined) {
-        if (shouldIgnoreNonEntryLabel(item, filesWithEntryLabels))
+        if (shouldIgnoreNonEntryLabel(item, context))
             return;
         startRoutine(state, item);
         return;
     }
     if (isDifferentRoutineSource(state, item)) {
-        resetAndStart(routines, state, constants, item);
+        resetAndStart(routines, state, context, item);
         return;
     }
     if (state.instructions.length > 0) {
-        if (shouldKeepPostInstructionAlias(item, filesWithEntryLabels)) {
+        if (shouldKeepPostInstructionAlias(item, context)) {
             appendRoutineLabel(state, item);
             return;
         }
-        resetAndStart(routines, state, constants, item);
+        resetAndStart(routines, state, context, item);
         return;
     }
     appendRoutineLabel(state, item);
 }
-function shouldIgnoreNonEntryLabel(item, filesWithEntryLabels) {
-    return filesWithEntryLabels.has(item.span.sourceName) && item.isEntry !== true;
+function shouldIgnoreNonEntryLabel(item, context) {
+    return (context.filesWithEntryLabels.has(item.span.sourceName) &&
+        item.isEntry !== true &&
+        !context.directCallTargets.has(item.name));
 }
 function isDifferentRoutineSource(state, item) {
     return state.sourceName === undefined || state.sourceName !== item.span.sourceName;
 }
-function shouldKeepPostInstructionAlias(item, filesWithEntryLabels) {
-    return shouldIgnoreNonEntryLabel(item, filesWithEntryLabels);
+function shouldKeepPostInstructionAlias(item, context) {
+    return shouldIgnoreNonEntryLabel(item, context);
 }
 function appendRoutineLabel(state, item) {
     state.labels.push(item.name);
     if (item.isEntry === true)
         state.entryLabels.push(item.name);
 }
-function handleLabel(routines, state, item, constants, filesWithEntryLabels) {
+function handleLabel(routines, state, item, context) {
     if (!isGlobalLabel(item.name)) {
         if (state.routineName !== undefined)
             state.labels.push(item.name);
         return;
     }
-    handleGlobalLabel(routines, state, item, constants, filesWithEntryLabels);
+    handleGlobalLabel(routines, state, item, context);
 }
 export function buildRoutinesAndDirectCalls(items, constants, filesWithEntryLabels) {
     const routines = [];
     const directCalls = [];
+    const context = {
+        constants,
+        filesWithEntryLabels,
+        directCallTargets: collectDirectCallTargets(items),
+    };
     const state = emptyState();
     for (const item of items) {
         if (item.kind === 'instruction') {
-            handleInstruction(state, directCalls, item, constants);
+            handleInstruction(state, directCalls, item, context);
         }
         else if (item.kind === 'label') {
-            handleLabel(routines, state, item, constants, filesWithEntryLabels);
+            handleLabel(routines, state, item, context);
         }
     }
     flushRoutine(routines, state, constants);
     return { routines, directCalls };
 }
+function collectDirectCallTargets(items) {
+    const targets = new Set();
+    for (const item of items) {
+        const target = instructionCallTarget(item);
+        if (target !== undefined)
+            targets.add(target);
+    }
+    return targets;
+}