@jhlagado/azm 0.2.0 → 0.2.2

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

@@ -1,5 +1,5 @@
 import { getRegisterCareProfile } from './profiles.js';
-import { getZ80InstructionEffect } from '../z80/effects.js';
+import { inferRoutineSummariesToFixedPoint, summariesWithExternalContracts, } from './routine-summaries.js';
 function unique(values) {
     const out = [];
     for (const value of values) {
@@ -8,22 +8,16 @@ function unique(values) {
     }
     return out;
 }
-function inferRoutineSummary(routine) {
-    const reads = new Set();
-    const writes = new Set();
-    for (const instruction of routine.instructions) {
-        const effect = getZ80InstructionEffect(instruction.instruction);
-        for (const unit of effect.reads)
-            reads.add(unit);
-        for (const unit of effect.writes)
-            writes.add(unit);
-    }
-    return {
-        name: routine.name,
-        mayRead: Array.from(reads),
-        mayWrite: Array.from(writes),
-        preserved: [],
-    };
+function isLocalLabel(name) {
+    return name.startsWith('.');
+}
+function boundaryLabels(routine) {
+    return routine.entryLabels.length > 0
+        ? routine.entryLabels
+        : routine.labels.filter((label) => !isLocalLabel(label));
+}
+function routineNameSet(routines) {
+    return new Set(routines.flatMap((routine) => boundaryLabels(routine)));
 }
 export function buildProfileSummaries(profileName) {
     const profile = getRegisterCareProfile(profileName);
@@ -46,48 +40,13 @@ export function buildProfileSummaryLookup(profileName) {
     return out;
 }
 export function routineNames(routines) {
-    return routines.flatMap((routine) => routine.entryLabels.length > 0 ? routine.entryLabels : [routine.name]);
+    return routines.flatMap((routine) => boundaryLabels(routine));
 }
-function entryContract(routine, contractMap) {
-    for (const label of routine.entryLabels.length > 0 ? routine.entryLabels : [routine.name]) {
-        const contract = contractMap.get(label);
-        if (contract !== undefined)
-            return contract;
-    }
-    return contractMap.get(routine.name);
-}
-export function buildSummaries(routines, contractMap) {
-    const out = [];
-    const written = new Set();
-    for (const routine of routines) {
-        const inferred = inferRoutineSummary(routine);
-        const contract = entryContract(routine, contractMap);
-        out.push({
-            name: routine.name,
-            mayRead: unique([...inferred.mayRead, ...(contract?.in ?? [])]),
-            mayWrite: unique([
-                ...inferred.mayWrite,
-                ...(contract?.out ?? []),
-                ...(contract?.clobbers ?? []),
-            ]),
-            preserved: unique([...inferred.preserved, ...(contract?.preserves ?? [])]),
-        });
-        written.add(routine.name);
-        for (const alias of routine.entryLabels)
-            written.add(alias);
-    }
-    for (const [name, contract] of contractMap) {
-        if (written.has(name))
-            continue;
-        out.push({
-            name,
-            mayRead: [...contract.in],
-            mayWrite: [...contract.out, ...contract.clobbers],
-            preserved: [...contract.preserves],
-        });
-        written.add(name);
-    }
-    return out;
+export function buildSummaries(routines, contractMap, profileSummaries = []) {
+    const names = routineNameSet(routines);
+    const routineSummaries = inferRoutineSummariesToFixedPoint([...routines], contractMap, names, [...profileSummaries]);
+    const summaries = routineSummaries.map((item) => item.summary);
+    return summariesWithExternalContracts(summaries, contractMap, names);
 }
 export function buildSummaryByName(routines, summaries, profileSummaries = []) {
     const out = new Map();
@@ -103,7 +62,7 @@ export function buildSummaryByName(routines, summaries, profileSummaries = []) {
         const routineSummary = byRoutine.get(routine.name);
         if (routineSummary === undefined)
             continue;
-        for (const alias of routine.entryLabels.length > 0 ? routine.entryLabels : [routine.name]) {
+        for (const alias of boundaryLabels(routine)) {
             out.set(alias, routineSummary);
         }
     }
@@ -118,28 +77,36 @@ export function withAcceptedOutputs(summaries, acceptedOutputCandidates) {
         if (!accepted || accepted.length === 0) {
             return summary;
         }
-        const merged = unique([...summary.mayWrite, ...accepted]);
-        return {
-            ...summary,
-            mayWrite: merged,
-            mayOutput: unique([...accepted]),
-        };
+        const written = new Set(summary.mayWrite);
+        const promoted = accepted.filter((unit) => written.has(unit));
+        if (promoted.length === 0) {
+            return summary;
+        }
+        const valueRelations = [...summary.valueRelations];
+        for (const unit of promoted) {
+            if (!valueRelations.some((relation) => relation.out.includes(unit))) {
+                valueRelations.push({ out: [unit], from: [] });
+            }
+        }
+        return { ...summary, valueRelations };
     });
 }
-export function unknownBoundaryDiagnostics(directCalls, knownRoutines) {
-    return directCalls
-        .filter((call) => !knownRoutines.has(call.target))
-        .map((call) => ({
+export function unknownBoundaryDiagnostics(directBoundaries, knownRoutines) {
+    return directBoundaries
+        .filter((boundary) => !knownRoutines.has(boundary.target))
+        .map((boundary) => ({
         severity: 'warning',
         code: 'AZMN_REGISTER_CARE',
-        message: `Register-care cannot prove ${call.target}; add a routine body or .asmi extern contract.`,
-        sourceName: call.file,
-        line: call.line,
-        column: call.column,
+        message: `Register-care cannot prove ${boundary.subject}; add a routine body or .asmi extern contract.`,
+        sourceName: boundary.file,
+        line: boundary.line,
+        column: boundary.column,
     }));
 }
-export function unknownCallList(directCalls, knownRoutines) {
-    return unique(directCalls.filter((call) => !knownRoutines.has(call.target)).map((call) => call.target)).sort();
+export function unknownCallList(directBoundaries, knownRoutines) {
+    return unique(directBoundaries
+        .filter((boundary) => !knownRoutines.has(boundary.target))
+        .map((boundary) => boundary.target)).sort();
 }
 export function buildOutputCandidateFixability(routines, outputCandidates, autoFixableCandidateKeys) {
     const autoFixable = autoFixableCandidateKeys([...routines], [...outputCandidates]);

package/dist/{legacy-root-azm/src/registerCare → src/register-care}/summary.js

@@ -1,6 +1,7 @@
 import { getZ80InstructionEffect } from '../z80/effects.js';
+import { instructionHead, instructionOperand, instructionOperandCount, isAccumulatorSelfOperand, isImmediateZeroOperand, isPureTokenTransferInstruction, isRegisterOperand, isUnconditionalReturnInstruction, regName, } from './instruction-shape.js';
 import { precedingCServiceName } from './boundaryHints.js';
-import { expandCarrier } from './carriers.js';
+import { expandCarrierList } from './carriers.js';
 import { rstServiceTargetName, rstTargetName } from './profiles.js';
 const FLAG_UNIT_LIST = ['carry', 'zero', 'sign', 'parity', 'halfCarry'];
 const TRACKED_UNITS = [
@@ -32,7 +33,7 @@ function isTrackedUnit(unit) {
     return TRACKED_UNITS.includes(unit);
 }
 function getRegisterUnits(name) {
-    return expandCarrier(name);
+    return expandCarrierList([name]);
 }
 function readToken(tokens, unit) {
     return tokens.get(unit) ?? { origin: 'unknown' };
@@ -54,7 +55,7 @@ function markProducedReadsConsumed(tokens, consumedProduced, reads, writes, item
     for (const unit of reads) {
         if (!isTrackedUnit(unit) || writes.has(unit))
             continue;
-        if (item?.head.toLowerCase() === 'cp' && unit === 'A')
+        if (item !== undefined && instructionHead(item) === 'cp' && unit === 'A')
             continue;
         if (readToken(tokens, unit).origin === 'produced')
             consumedProduced.add(unit);
@@ -67,7 +68,7 @@ function isOpaqueBoundary(item, effect) {
     if (effect.control.kind === 'call' || effect.control.kind === 'rst')
         return true;
     return (effect.control.kind === 'jump' &&
-        item.head.toLowerCase() === 'jp' &&
+        (instructionHead(item) === 'jp' || instructionHead(item) === 'jp-cc') &&
         !effect.control.conditional &&
         Boolean(effect.control.target) &&
         !effect.control.target?.startsWith('.'));
@@ -81,7 +82,7 @@ function boundarySummary(routine, index, summaries) {
         return summaries.get(effect.control.target);
     }
     if (effect.control.kind === 'jump' &&
-        item.head.toLowerCase() === 'jp' &&
+        (instructionHead(item) === 'jp' || instructionHead(item) === 'jp-cc') &&
         effect.control.target &&
         !effect.control.target.startsWith('.') &&
         !routine.labels.includes(effect.control.target)) {
@@ -147,46 +148,23 @@ function contractOutRelation(contractIn, contractOut) {
     };
 }
 function isUnconditionalReturn(item) {
-    const head = item.head.toLowerCase();
-    if (head === 'ret')
-        return item.instruction.operands.length === 0;
-    return head === 'retn' || head === 'reti';
+    return isUnconditionalReturnInstruction(item);
 }
 function isPureTokenTransfer(item) {
-    const inst = item.instruction;
-    const head = item.head.toLowerCase();
-    if (head === 'ex')
-        return true;
-    if (head !== 'ld' || inst.operands.length !== 2)
-        return false;
-    const dst = inst.operands[0];
-    const src = inst.operands[1];
-    if (dst?.kind !== 'Reg')
-        return false;
-    return src?.kind === 'Reg' || src?.kind === 'Imm';
-}
-function isAccumulatorSelfOperand(item) {
-    const operand = item.instruction.operands[0];
-    return operand?.kind === 'Reg' && operand.name.toUpperCase() === 'A';
-}
-function isImmediateZeroOperand(item) {
-    const operand = item.instruction.operands[0];
-    return operand?.kind === 'Imm' && operand.expr.kind === 'ImmLiteral' && operand.expr.value === 0;
-}
-function isRegisterOperand(item, index, name) {
-    const operand = item?.instruction.operands[index];
-    return operand?.kind === 'Reg' && operand.name.toUpperCase() === name;
+    return isPureTokenTransferInstruction(item);
 }
 function isCarryClearBeforeSbcHl(item, next) {
-    const head = item.head.toLowerCase();
+    const head = instructionHead(item).toLowerCase();
     if (head !== 'or' && head !== 'and')
         return false;
     if (!isAccumulatorSelfOperand(item))
         return false;
-    return next?.head.toLowerCase() === 'sbc' && isRegisterOperand(next, 0, 'HL');
+    return (next !== undefined &&
+        instructionHead(next) === 'sbc' &&
+        isRegisterOperand(next, 0, 'HL'));
 }
 function intentOutputUnits(item) {
-    const head = item.head.toLowerCase();
+    const head = instructionHead(item).toLowerCase();
     if (head === 'scf' || head === 'ccf')
         return ['carry'];
     if (head === 'cp')
@@ -197,7 +175,7 @@ function intentOutputUnits(item) {
     return [];
 }
 function isMechanicalResidueWrite(item, unit) {
-    const head = item.head.toLowerCase();
+    const head = instructionHead(item).toLowerCase();
     if (head === 'djnz')
         return unit === 'B';
     if (head === 'ldi' || head === 'ldir' || head === 'ldd' || head === 'lddr') {
@@ -207,16 +185,18 @@ function isMechanicalResidueWrite(item, unit) {
 }
 function applyPureTokenTransfer(tokens, consumedProduced, item) {
     const inst = item.instruction;
-    const head = item.head.toLowerCase();
-    if (head === 'ld' && inst.operands.length === 2) {
-        const dst = inst.operands[0];
-        const src = inst.operands[1];
-        if (dst?.kind !== 'Reg')
+    const head = instructionHead(item).toLowerCase();
+    if (head === 'ld' && instructionOperandCount(inst) === 2) {
+        const dst = instructionOperand(inst, 0);
+        const src = instructionOperand(inst, 1);
+        const dstName = regName(dst);
+        if (dstName === undefined)
             return [];
-        const dstUnits = dst.kind === 'Reg' ? getRegisterUnits(dst.name) : undefined;
+        const dstUnits = getRegisterUnits(dstName);
         if (!dstUnits)
             return [];
-        const srcUnits = src?.kind === 'Reg' ? getRegisterUnits(src.name) : undefined;
+        const srcName = regName(src);
+        const srcUnits = srcName ? getRegisterUnits(srcName) : undefined;
         if (srcUnits && srcUnits.length === dstUnits.length) {
             dstUnits.forEach((unit, index) => {
                 tokens.set(unit, readToken(tokens, srcUnits[index]));
@@ -234,13 +214,15 @@ function applyPureTokenTransfer(tokens, consumedProduced, item) {
         }
         return dstUnits;
     }
-    if (head === 'ex' && inst.operands.length === 2) {
-        const left = inst.operands[0];
-        const right = inst.operands[1];
-        if (left?.kind !== 'Reg' || right?.kind !== 'Reg')
+    if (head === 'ex' && instructionOperandCount(inst) === 2) {
+        const left = instructionOperand(inst, 0);
+        const right = instructionOperand(inst, 1);
+        const leftName = regName(left);
+        const rightName = regName(right);
+        if (leftName === undefined || rightName === undefined)
             return [];
-        const leftUnits = getRegisterUnits(left.name);
-        const rightUnits = getRegisterUnits(right.name);
+        const leftUnits = getRegisterUnits(leftName);
+        const rightUnits = getRegisterUnits(rightName);
         if (!leftUnits || !rightUnits || leftUnits.length !== rightUnits.length)
             return [];
         const leftTokens = leftUnits.map((unit) => readToken(tokens, unit));
@@ -308,7 +290,7 @@ export function inferRoutineSummary(routine, boundarySummaries = new Map()) {
             mayRead.push(...semanticReadOrigins(tokens, semanticReads));
             markProducedReadsConsumed(tokens, consumedProduced, semanticReads, effectWrites, item);
         }
-        if (item.head.toLowerCase() === 'djnz') {
+        if (instructionHead(item).toLowerCase() === 'djnz') {
             for (const unit of TRACKED_UNITS) {
                 if (readToken(tokens, unit).origin === 'produced')
                     consumedProduced.add(unit);
@@ -379,7 +361,7 @@ export function inferRoutineSummary(routine, boundarySummaries = new Map()) {
             if (transferWrites.has(unit) && isTrackedUnit(unit))
                 continue;
             if (unit === 'A' &&
-                (item.head.toLowerCase() === 'or' || item.head.toLowerCase() === 'and') &&
+                (instructionHead(item).toLowerCase() === 'or' || instructionHead(item).toLowerCase() === 'and') &&
                 isAccumulatorSelfOperand(item)) {
                 if (!carryClearBeforeSbcHl)
                     intendedProduced.add(unit);

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

@@ -64,6 +64,7 @@ export interface RegisterCareRoutine {
 }
 export interface RegisterCareDirectCall {
     target: string;
+    subject: string;
     file: string;
     line: number;
     column: number;
@@ -71,6 +72,7 @@ export interface RegisterCareDirectCall {
 export interface RegisterCareProgramModel {
     routines: RegisterCareRoutine[];
     directCalls: RegisterCareDirectCall[];
+    directBoundaries: RegisterCareDirectCall[];
 }
 export type StackEffect = {
     kind: 'none';
@@ -121,7 +123,10 @@ export interface RoutineSummary {
     mayWrite: RegisterCareUnit[];
     mayOutput?: RegisterCareUnit[];
     preserved: RegisterCareUnit[];
-    valueRelations?: ValueRelation[];
+    valueRelations: ValueRelation[];
+    stackBalanced: boolean;
+    hasUnknownStackEffect?: boolean;
+    outputCandidates?: RegisterCareUnit[];
 }
 export interface RegisterCareOutputCandidate {
     file: string;

package/dist/src/semantics/expression-evaluation.d.ts

@@ -1,5 +1,5 @@
 import type { Diagnostic } from '../model/diagnostic.js';
-import type { Expression } from '../model/expression.js';
+import type { Expression, TypeExpr } from '../model/expression.js';
 import type { LayoutField } from '../model/source-item.js';
 import type { SourceSpan } from '../source/source-span.js';
 export interface EquateRecord {
@@ -9,11 +9,15 @@ export interface EquateRecord {
     readonly enumMember?: boolean;
     readonly stringValue?: string;
 }
-export interface LayoutRecord {
+export type LayoutRecord = {
     readonly kind: 'record' | 'union';
     readonly fields: readonly LayoutField[];
     readonly span: SourceSpan;
-}
+} | {
+    readonly kind: 'alias';
+    readonly typeExpr: TypeExpr;
+    readonly span: SourceSpan;
+};
 export declare function lookupEquateRecord(equates: ReadonlyMap<string, EquateRecord>, name: string): {
     readonly key: string;
     readonly record: EquateRecord;

package/dist/src/semantics/expression-evaluation.js

@@ -39,6 +39,8 @@ export function evaluateExpression(expression, labels, equates, span, diagnostic
             return evaluateTypeSize(expression.typeExpr, labels, equates, span, diagnostics, options);
         case 'sizeof':
             return evaluateSizeof(expression.typeExpr, options.layouts, span, diagnostics);
+        case 'byte-function':
+            return evaluateByteFunction(expression, labels, equates, span, diagnostics, options);
         case 'offset':
             return evaluateOffset(expression.typeExpr, expression.path, options.layouts, span, diagnostics);
         case 'layout-cast':
@@ -51,6 +53,13 @@ export function evaluateExpression(expression, labels, equates, span, diagnostic
             return evaluateBinary(expression, labels, equates, span, diagnostics, options);
     }
 }
+function evaluateByteFunction(expression, labels, equates, span, diagnostics, options) {
+    const value = evaluateExpression(expression.expression, labels, equates, span, diagnostics, options);
+    if (value === undefined) {
+        return undefined;
+    }
+    return expression.function === 'LSB' ? value & 0xff : (value >> 8) & 0xff;
+}
 function evaluateTypeSize(typeExpr, labels, equates, span, diagnostics, options) {
     if (options.layouts) {
         const sizeDiagnostics = [];
@@ -146,6 +155,13 @@ function evaluateOffset(typeExpr, path, layouts, span, diagnostics) {
     return undefined;
 }
 function typeExprSize(typeExpr, layouts, span, diagnostics, visiting) {
+    const resolvedTypeExpr = resolveLayoutAlias(typeExpr, layouts, span, diagnostics, visiting);
+    if (!resolvedTypeExpr) {
+        return undefined;
+    }
+    if (resolvedTypeExpr !== typeExpr) {
+        return typeExprSize(resolvedTypeExpr, layouts, span, diagnostics, visiting);
+    }
     const scalar = scalarSize(typeExpr.name);
     const baseSize = scalar ??
         (() => {
@@ -162,6 +178,9 @@ function typeExprSize(typeExpr, layouts, span, diagnostics, visiting) {
     return typeExpr.length === undefined ? baseSize : baseSize * typeExpr.length;
 }
 function layoutSize(typeName, layout, layouts, span, diagnostics, visiting) {
+    if (layout.kind === 'alias') {
+        return typeExprSize(layout.typeExpr, layouts, span, diagnostics, visiting);
+    }
     const fieldSizes = [];
     for (const field of layout.fields) {
         const size = fieldSize(field, layouts, span, diagnostics, visiting);
@@ -187,6 +206,13 @@ function fieldSize(field, layouts, span, diagnostics, visiting) {
     return typeExprSize(field.typeExpr, layouts, span, diagnostics, new Set([...visiting, field.typeExpr.name]));
 }
 function offsetPath(typeExpr, parts, layouts, span, diagnostics) {
+    const resolvedTypeExpr = resolveLayoutAlias(typeExpr, layouts, span, diagnostics, new Set([typeExpr.name]));
+    if (!resolvedTypeExpr) {
+        return undefined;
+    }
+    if (resolvedTypeExpr !== typeExpr) {
+        return offsetPath(resolvedTypeExpr, parts, layouts, span, diagnostics);
+    }
     const [head, ...tail] = parts;
     if (head === undefined) {
         return undefined;
@@ -218,6 +244,9 @@ function offsetPath(typeExpr, parts, layouts, span, diagnostics) {
         diagnostics.push(diagnostic(span, `unknown type: ${typeExpr.name}`));
         return undefined;
     }
+    if (layout.kind === 'alias') {
+        return offsetPath(layout.typeExpr, parts, layouts, span, diagnostics);
+    }
     let currentOffset = 0;
     for (const field of layout.fields) {
         const fieldOffset = layout.kind === 'union' ? 0 : currentOffset;
@@ -246,6 +275,13 @@ function offsetPath(typeExpr, parts, layouts, span, diagnostics) {
     return undefined;
 }
 function layoutCastOffset(typeExpr, parts, labels, equates, layouts, span, diagnostics, options) {
+    const resolvedTypeExpr = resolveLayoutAlias(typeExpr, layouts, span, diagnostics, new Set([typeExpr.name]));
+    if (!resolvedTypeExpr) {
+        return undefined;
+    }
+    if (resolvedTypeExpr !== typeExpr) {
+        return layoutCastOffset(resolvedTypeExpr, parts, labels, equates, layouts, span, diagnostics, options);
+    }
     const [head, ...tail] = parts;
     if (head === undefined) {
         return 0;
@@ -286,6 +322,9 @@ function layoutCastOffset(typeExpr, parts, labels, equates, layouts, span, diagn
         diagnostics.push(diagnostic(span, `unknown type: ${typeExpr.name}`));
         return undefined;
     }
+    if (layout.kind === 'alias') {
+        return layoutCastOffset(layout.typeExpr, parts, labels, equates, layouts, span, diagnostics, options);
+    }
     let currentOffset = 0;
     for (const field of layout.fields) {
         const fieldOffset = layout.kind === 'union' ? 0 : currentOffset;
@@ -330,6 +369,24 @@ function registerIndexName(expression) {
 function formatTypeExpr(typeExpr) {
     return typeExpr.length === undefined ? typeExpr.name : `${typeExpr.name}[${typeExpr.length}]`;
 }
+function resolveLayoutAlias(typeExpr, layouts, span, diagnostics, visiting) {
+    const layout = layouts.get(typeExpr.name);
+    if (!layout || layout.kind !== 'alias') {
+        return typeExpr;
+    }
+    if (visiting.has(layout.typeExpr.name)) {
+        diagnostics.push(diagnostic(span, `recursive type: ${typeExpr.name}`));
+        return undefined;
+    }
+    const target = resolveLayoutAlias(layout.typeExpr, layouts, span, diagnostics, new Set([...visiting, layout.typeExpr.name]));
+    if (!target) {
+        return undefined;
+    }
+    const length = typeExpr.length === undefined
+        ? target.length
+        : (target.length ?? 1) * typeExpr.length;
+    return length === undefined ? { name: target.name } : { name: target.name, length };
+}
 function formatOffsetPath(path) {
     return path.map((part) => (part.kind === 'field' ? part.name : `[${part.index}]`)).join('.');
 }

package/dist/src/source/strip-line-comment.d.ts

@@ -2,3 +2,5 @@
  * Remove an ASM80-style end-of-line comment (`;`), respecting quoted strings.
  */
 export declare function stripLineComment(text: string): string;
+/** Trailing `;` comment text, or undefined when absent or whitespace-only. */
+export declare function extractLineComment(text: string): string | undefined;

package/dist/src/source/strip-line-comment.js

@@ -25,3 +25,29 @@ export function stripLineComment(text) {
     }
     return text;
 }
+/** Trailing `;` comment text, or undefined when absent or whitespace-only. */
+export function extractLineComment(text) {
+    let quote;
+    let escaped = false;
+    for (let index = 0; index < text.length; index += 1) {
+        const char = text[index];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === '\\' && quote) {
+            escaped = true;
+            continue;
+        }
+        if ((char === '"' || char === "'") &&
+            !(char === "'" && quote === undefined && /[A-Za-z0-9_]/.test(text[index - 1] ?? ''))) {
+            quote = quote === char ? undefined : (quote ?? char);
+            continue;
+        }
+        if (char === ';' && !quote) {
+            const comment = text.slice(index + 1).trim();
+            return comment.length > 0 ? comment : undefined;
+        }
+    }
+    return undefined;
+}

package/dist/src/syntax/directive-aliases.js

@@ -160,14 +160,14 @@ export function normalizeDirectiveAlias(text, policy = DEFAULT_DIRECTIVE_ALIAS_P
     if (label) {
         return `${leading}${label[1]} ${normalizeHead(label[2] ?? '', policy)}`;
     }
-    const equ = /^([A-Za-z_.$?][A-Za-z0-9_.$?]*)\s+([A-Za-z]+)\b(.*)$/.exec(trimmed);
+    const equ = /^([A-Za-z_.$?][A-Za-z0-9_.$?]*)\s+([A-Za-z][A-Za-z0-9_]*)\b(.*)$/.exec(trimmed);
     if (equ && resolveDirectiveAlias(equ[2] ?? '', policy) === '.equ') {
         return `${leading}${equ[1]} .equ${equ[3] ?? ''}`;
     }
     return `${leading}${normalizeHead(trimmed, policy)}`;
 }
 function normalizeHead(text, policy) {
-    const head = /^([A-Za-z]+)\b(.*)$/.exec(text);
+    const head = /^([A-Za-z][A-Za-z0-9_]*)\b(.*)$/.exec(text);
     if (!head) {
         return text;
     }
@@ -181,7 +181,7 @@ function normalizeAliasKey(key) {
     const trimmed = key.trim();
     if (!/^[.]?[A-Za-z][A-Za-z0-9_]*$/.test(trimmed))
         return undefined;
-    return trimmed.replace(/^\./, '').toUpperCase();
+    return trimmed.replace(/^\./, '');
 }
 function normalizeAliasTarget(value) {
     const trimmed = value.trim().toLowerCase();
@@ -189,11 +189,10 @@ function normalizeAliasTarget(value) {
     return CANONICAL_DIRECTIVES.has(dotted) ? dotted : undefined;
 }
 function resolveDirectiveAlias(head, policy) {
-    const key = normalizeAliasKey(head);
-    if (!key)
-        return undefined;
-    const dotted = `.${key.toLowerCase()}`;
-    if (head.trim().startsWith('.') && CANONICAL_DIRECTIVES.has(dotted))
-        return dotted;
-    return policy.directiveAliases.get(key);
+    const trimmed = head.trim();
+    if (trimmed.startsWith('.')) {
+        return CANONICAL_DIRECTIVES.has(trimmed) ? trimmed : undefined;
+    }
+    const key = head.trim();
+    return /^[A-Za-z][A-Za-z0-9_]*$/.test(key) ? policy.directiveAliases.get(key) : undefined;
 }

package/dist/src/syntax/parse-diagnostics.d.ts

@@ -0,0 +1,12 @@
+import type { Diagnostic, DiagnosticId, DiagnosticSeverity } from '../model/diagnostic.js';
+type ParseDiagLocation = {
+    line: number;
+    column: number;
+};
+/** Push a parse diagnostic with Next default code/severity (`AZMN_PARSE` / error). */
+export declare function parseDiag(diagnostics: Diagnostic[], sourceName: string, message: string, where?: ParseDiagLocation): void;
+/** Push a parse diagnostic at an explicit 1-based line/column. */
+export declare function parseDiagAt(diagnostics: Diagnostic[], sourceName: string, message: string, line: number, column: number): void;
+/** Push a diagnostic with explicit code, severity, and optional location. */
+export declare function parseDiagAtWithId(diagnostics: Diagnostic[], sourceName: string, code: DiagnosticId | string, severity: DiagnosticSeverity, message: string, where?: ParseDiagLocation): void;
+export {};

package/dist/src/syntax/parse-diagnostics.js

@@ -0,0 +1,18 @@
+/** Push a parse diagnostic with Next default code/severity (`AZMN_PARSE` / error). */
+export function parseDiag(diagnostics, sourceName, message, where) {
+    parseDiagAtWithId(diagnostics, sourceName, 'AZMN_PARSE', 'error', message, where);
+}
+/** Push a parse diagnostic at an explicit 1-based line/column. */
+export function parseDiagAt(diagnostics, sourceName, message, line, column) {
+    parseDiag(diagnostics, sourceName, message, { line, column });
+}
+/** Push a diagnostic with explicit code, severity, and optional location. */
+export function parseDiagAtWithId(diagnostics, sourceName, code, severity, message, where) {
+    diagnostics.push({
+        code,
+        severity,
+        message,
+        sourceName,
+        ...(where ? { line: where.line, column: where.column } : {}),
+    });
+}