@jhlagado/azm 0.2.0 → 0.2.1

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

@@ -0,0 +1,474 @@
+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 { expandCarrierList } from './carriers.js';
+import { rstServiceTargetName, rstTargetName } from './profiles.js';
+const FLAG_UNIT_LIST = ['carry', 'zero', 'sign', 'parity', 'halfCarry'];
+const TRACKED_UNITS = [
+    'A',
+    'B',
+    'C',
+    'D',
+    'E',
+    'H',
+    'L',
+    'IXH',
+    'IXL',
+    'IYH',
+    'IYL',
+    ...FLAG_UNIT_LIST,
+];
+const GENERAL_REGISTER_UNITS = new Set(['A', 'B', 'C', 'D', 'E', 'H', 'L']);
+const CONTRACT_FLAG_UNITS = new Set(['carry', 'zero']);
+const STACK_POINTER_UNITS = new Set(['SPH', 'SPL']);
+const REGISTER_PAIRS = [
+    ['B', 'C'],
+    ['D', 'E'],
+    ['H', 'L'],
+];
+function unique(items) {
+    return [...new Set(items)];
+}
+function isTrackedUnit(unit) {
+    return TRACKED_UNITS.includes(unit);
+}
+function getRegisterUnits(name) {
+    return expandCarrierList([name]);
+}
+function readToken(tokens, unit) {
+    return tokens.get(unit) ?? { origin: 'unknown' };
+}
+function semanticReadOrigins(tokens, units) {
+    const origins = [];
+    for (const unit of units) {
+        if (!isTrackedUnit(unit)) {
+            origins.push(unit);
+            continue;
+        }
+        const token = readToken(tokens, unit);
+        if (token.origin !== 'unknown' && token.origin !== 'produced')
+            origins.push(token.origin);
+    }
+    return origins;
+}
+function markProducedReadsConsumed(tokens, consumedProduced, reads, writes, item) {
+    for (const unit of reads) {
+        if (!isTrackedUnit(unit) || writes.has(unit))
+            continue;
+        if (item !== undefined && instructionHead(item) === 'cp' && unit === 'A')
+            continue;
+        if (readToken(tokens, unit).origin === 'produced')
+            consumedProduced.add(unit);
+    }
+}
+function tokenPreservesUnit(token, unit) {
+    return token?.origin === unit;
+}
+function isOpaqueBoundary(item, effect) {
+    if (effect.control.kind === 'call' || effect.control.kind === 'rst')
+        return true;
+    return (effect.control.kind === 'jump' &&
+        (instructionHead(item) === 'jp' || instructionHead(item) === 'jp-cc') &&
+        !effect.control.conditional &&
+        Boolean(effect.control.target) &&
+        !effect.control.target?.startsWith('.'));
+}
+function boundarySummary(routine, index, summaries) {
+    const item = routine.instructions[index];
+    if (!item)
+        return undefined;
+    const effect = getZ80InstructionEffect(item.instruction);
+    if (effect.control.kind === 'call' && effect.control.target) {
+        return summaries.get(effect.control.target);
+    }
+    if (effect.control.kind === 'jump' &&
+        (instructionHead(item) === 'jp' || instructionHead(item) === 'jp-cc') &&
+        effect.control.target &&
+        !effect.control.target.startsWith('.') &&
+        !routine.labels.includes(effect.control.target)) {
+        return summaries.get(effect.control.target);
+    }
+    if (effect.control.kind === 'rst' && effect.control.vector !== undefined) {
+        const service = precedingCServiceName(routine.instructions[index - 1]);
+        if (service) {
+            const serviceSummary = summaries.get(rstServiceTargetName(effect.control.vector, service));
+            if (serviceSummary)
+                return serviceSummary;
+        }
+        return summaries.get(rstTargetName(effect.control.vector));
+    }
+    return undefined;
+}
+function relationKey(relation) {
+    return `${relation.out.join(',')}<- ${relation.from.join(',')}`;
+}
+function addRelation(out, relation) {
+    if (relation.out.length === 0 || relation.from.length === 0)
+        return;
+    const key = relationKey(relation);
+    if (!out.some((existing) => relationKey(existing) === key))
+        out.push(relation);
+}
+function addContractRelation(out, relation) {
+    if (relation.out.length === 0)
+        return;
+    const key = relationKey(relation);
+    if (!out.some((existing) => relationKey(existing) === key))
+        out.push(relation);
+}
+function pairRelation(tokens, out) {
+    const from = [];
+    for (const unit of out) {
+        const token = tokens.get(unit);
+        if (!token || token.origin === 'unknown' || token.origin === 'produced')
+            return undefined;
+        from.push(token.origin);
+    }
+    if (out.every((unit, idx) => unit === from[idx]))
+        return undefined;
+    if (out.some((unit, idx) => unit === from[idx]))
+        return undefined;
+    return { out, from };
+}
+function producedPairRelation(tokens, consumedProduced, out) {
+    if (out.some((unit) => tokens.get(unit)?.origin !== 'produced' || consumedProduced.has(unit))) {
+        return undefined;
+    }
+    return { out, from: [] };
+}
+function withImpliedFlagUnits(units) {
+    return unique(units);
+}
+function contractOutRelation(contractIn, contractOut) {
+    if (contractOut.length === 0)
+        return undefined;
+    return {
+        out: contractOut,
+        from: contractIn.length === contractOut.length ? contractIn : [],
+    };
+}
+function isUnconditionalReturn(item) {
+    return isUnconditionalReturnInstruction(item);
+}
+function isPureTokenTransfer(item) {
+    return isPureTokenTransferInstruction(item);
+}
+function isCarryClearBeforeSbcHl(item, next) {
+    const head = instructionHead(item).toLowerCase();
+    if (head !== 'or' && head !== 'and')
+        return false;
+    if (!isAccumulatorSelfOperand(item))
+        return false;
+    return (next !== undefined &&
+        instructionHead(next) === 'sbc' &&
+        isRegisterOperand(next, 0, 'HL'));
+}
+function intentOutputUnits(item) {
+    const head = instructionHead(item).toLowerCase();
+    if (head === 'scf' || head === 'ccf')
+        return ['carry'];
+    if (head === 'cp')
+        return isImmediateZeroOperand(item) ? ['A', 'carry', 'zero'] : ['carry', 'zero'];
+    if ((head === 'or' || head === 'and' || head === 'xor') && isAccumulatorSelfOperand(item)) {
+        return ['A', 'carry', 'zero'];
+    }
+    return [];
+}
+function isMechanicalResidueWrite(item, unit) {
+    const head = instructionHead(item).toLowerCase();
+    if (head === 'djnz')
+        return unit === 'B';
+    if (head === 'ldi' || head === 'ldir' || head === 'ldd' || head === 'lddr') {
+        return (unit === 'B' || unit === 'C' || unit === 'D' || unit === 'E' || unit === 'H' || unit === 'L');
+    }
+    return false;
+}
+function applyPureTokenTransfer(tokens, consumedProduced, item) {
+    const inst = item.instruction;
+    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 = getRegisterUnits(dstName);
+        if (!dstUnits)
+            return [];
+        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]));
+                if (readToken(tokens, srcUnits[index]).origin === 'produced') {
+                    consumedProduced.add(srcUnits[index]);
+                }
+                consumedProduced.delete(unit);
+            });
+        }
+        else {
+            for (const unit of dstUnits) {
+                tokens.set(unit, { origin: 'produced' });
+                consumedProduced.delete(unit);
+            }
+        }
+        return dstUnits;
+    }
+    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(leftName);
+        const rightUnits = getRegisterUnits(rightName);
+        if (!leftUnits || !rightUnits || leftUnits.length !== rightUnits.length)
+            return [];
+        const leftTokens = leftUnits.map((unit) => readToken(tokens, unit));
+        const rightTokens = rightUnits.map((unit) => readToken(tokens, unit));
+        leftUnits.forEach((unit, index) => tokens.set(unit, rightTokens[index] ?? { origin: 'unknown' }));
+        rightUnits.forEach((unit, index) => tokens.set(unit, leftTokens[index] ?? { origin: 'unknown' }));
+        return unique([...leftUnits, ...rightUnits]);
+    }
+    return [];
+}
+function applyKnownBoundarySummary(tokens, consumedProduced, intendedProduced, directMayWrite, summary) {
+    for (const relation of summary.valueRelations) {
+        const sameCarrierRelation = relation.out.length === relation.from.length &&
+            relation.out.every((unit, index) => unit === relation.from[index]);
+        relation.out.forEach((unit, index) => {
+            if (!sameCarrierRelation &&
+                relation.from.length === relation.out.length &&
+                relation.from[index]) {
+                tokens.set(unit, readToken(tokens, relation.from[index]));
+            }
+            else {
+                tokens.set(unit, { origin: 'produced' });
+                consumedProduced.delete(unit);
+                if (CONTRACT_FLAG_UNITS.has(unit))
+                    intendedProduced.add(unit);
+            }
+        });
+    }
+    for (const unit of summary.mayWrite) {
+        if (STACK_POINTER_UNITS.has(unit))
+            continue;
+        if (isTrackedUnit(unit)) {
+            tokens.set(unit, { origin: 'unknown' });
+            consumedProduced.delete(unit);
+            intendedProduced.delete(unit);
+        }
+        else {
+            directMayWrite.push(unit);
+        }
+    }
+}
+export function inferRoutineSummary(routine, boundarySummaries = new Map()) {
+    const tokens = new Map();
+    for (const unit of TRACKED_UNITS)
+        tokens.set(unit, { origin: unit });
+    const stack = [];
+    const mayRead = [];
+    const directMayWrite = [];
+    const consumedProduced = new Set();
+    const intendedProduced = new Set();
+    let stackBalanced = true;
+    let hasUnknownStackEffect = false;
+    for (let index = 0; index < routine.instructions.length; index += 1) {
+        const item = routine.instructions[index];
+        const effect = getZ80InstructionEffect(item.instruction);
+        const knownBoundary = boundarySummary(routine, index, boundarySummaries);
+        const carryClearBeforeSbcHl = isCarryClearBeforeSbcHl(item, routine.instructions[index + 1]);
+        const expectedTerminalReturn = index === routine.instructions.length - 1 && isUnconditionalReturn(item);
+        const effectWrites = new Set(effect.writes);
+        const instructionIntentOutputs = carryClearBeforeSbcHl ? [] : intentOutputUnits(item);
+        const semanticReads = carryClearBeforeSbcHl
+            ? effect.reads.filter((unit) => unit !== 'A')
+            : effect.reads;
+        if (effect.stack.kind !== 'push' && !isPureTokenTransfer(item)) {
+            mayRead.push(...semanticReadOrigins(tokens, semanticReads));
+            markProducedReadsConsumed(tokens, consumedProduced, semanticReads, effectWrites, item);
+        }
+        if (instructionHead(item).toLowerCase() === 'djnz') {
+            for (const unit of TRACKED_UNITS) {
+                if (readToken(tokens, unit).origin === 'produced')
+                    consumedProduced.add(unit);
+                intendedProduced.delete(unit);
+            }
+        }
+        if (knownBoundary) {
+            mayRead.push(...semanticReadOrigins(tokens, knownBoundary.mayRead));
+            markProducedReadsConsumed(tokens, consumedProduced, knownBoundary.mayRead, new Set());
+        }
+        if (effect.stack.kind === 'push') {
+            stack.push(effect.stack.units.map((unit) => readToken(tokens, unit)));
+        }
+        else if (effect.stack.kind === 'pop') {
+            const popped = stack.pop();
+            if (!popped) {
+                stackBalanced = false;
+                for (const unit of effect.stack.units) {
+                    tokens.set(unit, { origin: 'unknown' });
+                    intendedProduced.delete(unit);
+                }
+            }
+            else if (popped.length !== effect.stack.units.length) {
+                for (const unit of effect.stack.units) {
+                    tokens.set(unit, { origin: 'unknown' });
+                    consumedProduced.delete(unit);
+                    intendedProduced.delete(unit);
+                }
+            }
+            else {
+                effect.stack.units.forEach((unit, idx) => {
+                    tokens.set(unit, popped[idx] ?? { origin: 'unknown' });
+                    consumedProduced.delete(unit);
+                    intendedProduced.delete(unit);
+                });
+            }
+        }
+        else if (effect.stack.kind === 'exchangeTop') {
+            hasUnknownStackEffect = true;
+            for (const unit of effect.stack.units) {
+                tokens.set(unit, { origin: 'unknown' });
+                consumedProduced.delete(unit);
+                intendedProduced.delete(unit);
+            }
+        }
+        else if (effect.stack.kind === 'unknown' &&
+            !expectedTerminalReturn &&
+            (!knownBoundary || !knownBoundary.stackBalanced || knownBoundary.hasUnknownStackEffect)) {
+            hasUnknownStackEffect = true;
+        }
+        const transferWrites = new Set(isPureTokenTransfer(item) ? applyPureTokenTransfer(tokens, consumedProduced, item) : []);
+        if (knownBoundary) {
+            applyKnownBoundarySummary(tokens, consumedProduced, intendedProduced, directMayWrite, knownBoundary);
+        }
+        else if (isOpaqueBoundary(item, effect)) {
+            for (const unit of TRACKED_UNITS) {
+                tokens.set(unit, { origin: 'unknown' });
+                consumedProduced.delete(unit);
+                intendedProduced.delete(unit);
+            }
+        }
+        for (const unit of effect.writes) {
+            if (STACK_POINTER_UNITS.has(unit))
+                continue;
+            if (effect.stack.kind === 'pop' && effect.stack.units.includes(unit) && isTrackedUnit(unit)) {
+                continue;
+            }
+            if (transferWrites.has(unit) && isTrackedUnit(unit))
+                continue;
+            if (unit === 'A' &&
+                (instructionHead(item).toLowerCase() === 'or' || instructionHead(item).toLowerCase() === 'and') &&
+                isAccumulatorSelfOperand(item)) {
+                if (!carryClearBeforeSbcHl)
+                    intendedProduced.add(unit);
+                continue;
+            }
+            if (isTrackedUnit(unit)) {
+                tokens.set(unit, { origin: isMechanicalResidueWrite(item, unit) ? 'unknown' : 'produced' });
+                consumedProduced.delete(unit);
+                if (instructionIntentOutputs.includes(unit))
+                    intendedProduced.add(unit);
+                else
+                    intendedProduced.delete(unit);
+            }
+            else {
+                directMayWrite.push(unit);
+            }
+        }
+        for (const unit of instructionIntentOutputs) {
+            if (!isTrackedUnit(unit) || effectWrites.has(unit))
+                continue;
+            intendedProduced.add(unit);
+        }
+    }
+    if (stack.length !== 0)
+        stackBalanced = false;
+    const mayWrite = [...directMayWrite];
+    const preserved = [];
+    const valueRelations = [];
+    const outputUnits = new Set();
+    for (const pair of REGISTER_PAIRS) {
+        const relation = producedPairRelation(tokens, consumedProduced, pair);
+        if (relation) {
+            addContractRelation(valueRelations, relation);
+            for (const unit of pair)
+                outputUnits.add(unit);
+        }
+    }
+    for (const unit of TRACKED_UNITS) {
+        if (outputUnits.has(unit))
+            continue;
+        const current = tokens.get(unit);
+        const eligibleProduced = current?.origin === 'produced' &&
+            (GENERAL_REGISTER_UNITS.has(unit) ||
+                (CONTRACT_FLAG_UNITS.has(unit) && intendedProduced.has(unit)));
+        const eligiblePreservedIntent = current?.origin === unit && GENERAL_REGISTER_UNITS.has(unit) && intendedProduced.has(unit);
+        if ((eligibleProduced || eligiblePreservedIntent) && !consumedProduced.has(unit)) {
+            addContractRelation(valueRelations, {
+                out: [unit],
+                from: eligiblePreservedIntent ? [unit] : [],
+            });
+            outputUnits.add(unit);
+        }
+    }
+    for (const unit of TRACKED_UNITS) {
+        const current = tokens.get(unit);
+        if (tokenPreservesUnit(current, unit)) {
+            preserved.push(unit);
+            continue;
+        }
+        if (outputUnits.has(unit))
+            continue;
+        mayWrite.push(unit);
+    }
+    for (const pair of REGISTER_PAIRS) {
+        const relation = pairRelation(tokens, pair);
+        if (relation)
+            addRelation(valueRelations, relation);
+    }
+    mayRead.push(...valueRelations.flatMap((relation) => relation.from));
+    return {
+        name: routine.name,
+        mayRead: unique(mayRead),
+        mayWrite: unique(mayWrite),
+        preserved: unique(preserved),
+        valueRelations,
+        stackBalanced,
+        hasUnknownStackEffect,
+    };
+}
+export function applyRoutineContract(summary, contract) {
+    const contractIn = withImpliedFlagUnits(contract.in);
+    const contractOut = withImpliedFlagUnits(contract.out);
+    const contractClobbers = withImpliedFlagUnits(contract.clobbers);
+    const contractPreserves = withImpliedFlagUnits(contract.preserves);
+    const outputSet = new Set(contractOut);
+    const preservedSet = new Set(contractPreserves);
+    const inferredWrites = withImpliedFlagUnits(summary.mayWrite);
+    const baseMayWrite = contract.complete
+        ? inferredWrites.filter((unit) => FLAG_UNIT_LIST.includes(unit))
+        : inferredWrites;
+    const mayWrite = baseMayWrite.filter((unit) => !outputSet.has(unit) && !preservedSet.has(unit));
+    for (const unit of contractClobbers) {
+        if (!outputSet.has(unit) && !preservedSet.has(unit) && !mayWrite.includes(unit)) {
+            mayWrite.push(unit);
+        }
+    }
+    const mayWriteSet = new Set(withImpliedFlagUnits(mayWrite));
+    const preserved = unique([...summary.preserved, ...contractPreserves]).filter((unit) => !outputSet.has(unit) && !mayWriteSet.has(unit));
+    const valueRelations = [...summary.valueRelations];
+    const relation = contractOutRelation(contractIn, contractOut);
+    if (relation)
+        addContractRelation(valueRelations, relation);
+    return {
+        ...summary,
+        mayRead: unique(contractIn),
+        mayWrite,
+        preserved,
+        valueRelations,
+    };
+}

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/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/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 } : {}),
+    });
+}

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

@@ -1,35 +1,88 @@
-import { stripLineComment } from '../source/strip-line-comment.js';
+import { extractLineComment, stripLineComment } from '../source/strip-line-comment.js';
 import { normalizeDirectiveAlias } from './directive-aliases.js';
 import { parseExpression, parseTypeExpr } from './parse-expression.js';
 import { parseZ80Instruction } from '../z80/parse-instruction.js';
 export function parseLogicalLine(line, options = {}) {
     const text = normalizeDirectiveAlias(stripLineComment(line.text), options.directiveAliasPolicy).trim();
     if (text.length === 0) {
-        return { items: [], diagnostics: [] };
+        return commentOnlyLine(line);
     }
     const span = { sourceName: line.sourceName, line: line.line, column: firstColumn(line.text) };
     const labelWithStatement = /^(@?[A-Za-z_.$?][A-Za-z0-9_.$?]*):\s*(.+)$/.exec(text);
     if (labelWithStatement) {
-        const labelName = normalizeEntryLabelName(labelWithStatement[1] ?? '');
+        const rawLabel = labelWithStatement[1] ?? '';
+        const labelName = normalizeEntryLabelName(rawLabel);
+        const isEntry = rawLabel.startsWith('@');
         const statementText = labelWithStatement[2] ?? '';
         const equStatement = parseColonLabelEqu(line, labelName, statementText, span);
         if (equStatement) {
             return equStatement;
         }
         const parsedStatement = parseCanonicalStatement(line, statementText, span);
-        return {
-            items: [{ kind: 'label', name: labelName, span }, ...parsedStatement.items],
+        return withLineComment(line, {
+            items: [{ kind: 'label', name: labelName, ...(isEntry ? { isEntry: true } : {}), span }, ...parsedStatement.items],
             diagnostics: parsedStatement.diagnostics,
-        };
+        });
     }
     const labelOnly = /^(@?[A-Za-z_.$?][A-Za-z0-9_.$?]*):$/.exec(text);
     if (labelOnly) {
-        return {
-            items: [{ kind: 'label', name: normalizeEntryLabelName(labelOnly[1] ?? ''), span }],
+        const rawLabel = labelOnly[1] ?? '';
+        return withLineComment(line, {
+            items: [
+                {
+                    kind: 'label',
+                    name: normalizeEntryLabelName(rawLabel),
+                    ...(rawLabel.startsWith('@') ? { isEntry: true } : {}),
+                    span,
+                },
+            ],
             diagnostics: [],
-        };
+        });
+    }
+    return withLineComment(line, parseCanonicalStatement(line, text, span));
+}
+function commentOnlyLine(line) {
+    const comment = extractLineComment(line.text);
+    if (!comment) {
+        return { items: [], diagnostics: [] };
     }
-    return parseCanonicalStatement(line, text, span);
+    return {
+        items: [
+            {
+                kind: 'comment',
+                text: comment,
+                origin: 'user',
+                span: {
+                    sourceName: line.sourceName,
+                    line: line.line,
+                    column: firstColumn(line.text),
+                },
+            },
+        ],
+        diagnostics: [],
+    };
+}
+function withLineComment(line, result) {
+    const comment = extractLineComment(line.text);
+    if (!comment) {
+        return result;
+    }
+    return {
+        items: [
+            ...result.items,
+            {
+                kind: 'comment',
+                text: comment,
+                origin: 'user',
+                span: {
+                    sourceName: line.sourceName,
+                    line: line.line,
+                    column: firstColumn(line.text),
+                },
+            },
+        ],
+        diagnostics: result.diagnostics,
+    };
 }
 function parseEquItem(line, name, expressionText, span) {
     const stringValue = parseWholeQuotedString(expressionText.trim());