@jhlagado/azm 0.2.9 → 0.2.11

package/dist/src/syntax/parse-instruction-chain.js

@@ -0,0 +1,62 @@
+import { splitInstructionChain } from '../source/instruction-chain.js';
+import { hasLeadingLabel, parseLeadingLabel } from './names.js';
+import { isChainedDirectiveOrDeclaration } from './statement-classification.js';
+export function parseInstructionChain(options) {
+    const segments = splitInstructionChain(options.line.text);
+    if (segments === undefined)
+        return undefined;
+    const items = [];
+    const diagnostics = [];
+    for (let index = 0; index < segments.length; index += 1) {
+        const segment = segments[index];
+        const parsed = parseInstructionChainSegment(options, segment.text, segment.column, index);
+        diagnostics.push(...parsed.diagnostics);
+        items.push(...parsed.items);
+    }
+    options.appendLineComment?.(items, options.line);
+    return { items, diagnostics };
+}
+function parseInstructionChainSegment(options, text, column, segmentIndex) {
+    if (text.length === 0) {
+        return {
+            items: [],
+            diagnostics: [
+                options.makeDiagnostic(options.line, column, 'empty instruction segment in chained line'),
+            ],
+        };
+    }
+    if (segmentIndex > 0 && hasLeadingLabel(text)) {
+        return {
+            items: [],
+            diagnostics: [
+                options.makeDiagnostic(options.line, column, 'labels are only allowed before the first chained instruction'),
+            ],
+        };
+    }
+    const labeled = segmentIndex === 0 ? parseLeadingLabel(text, column) : undefined;
+    const statementText = labeled?.statementText ?? text;
+    const statementColumn = labeled?.statementColumn ?? column;
+    if (statementText.length === 0) {
+        return {
+            items: [],
+            diagnostics: [
+                options.makeDiagnostic(options.line, statementColumn, 'empty instruction segment in chained line'),
+            ],
+        };
+    }
+    if (isChainedDirectiveOrDeclaration(statementText)) {
+        return {
+            items: [],
+            diagnostics: [
+                options.makeDiagnostic(options.line, statementColumn, 'directives must be on their own line; chained lines only support instructions and ops'),
+            ],
+        };
+    }
+    const items = [];
+    if (labeled) {
+        items.push(options.makeLabelItem(labeled, options.line));
+    }
+    const statement = options.parseStatement(options.line, statementText, statementColumn);
+    items.push(...statement.items);
+    return { items, diagnostics: statement.diagnostics };
+}

package/dist/src/syntax/parse-layout-declarations.js

@@ -1,4 +1,6 @@
 import { stripLineComment } from '../source/strip-line-comment.js';
+import { IDENTIFIER_PATTERN } from './names.js';
+import { firstNonWhitespaceColumn, parseLineError } from './parse-diagnostics.js';
 import { parseTypeExpr } from './parse-expression.js';
 export function parseLayoutDeclarationAt(lines, index) {
     const line = lines[index];
@@ -9,7 +11,7 @@ export function parseLayoutDeclarationAt(lines, index) {
     if (typeAlias !== undefined) {
         return { consumedUntilIndex: index, ...typeAlias };
     }
-    const prefixLayoutHeader = /^\.(type|union)\s+([A-Za-z_][A-Za-z0-9_]*)\s*$/.exec(text);
+    const prefixLayoutHeader = new RegExp(`^\\.(type|union)\\s+(${IDENTIFIER_PATTERN})\\s*$`).exec(text);
     if (prefixLayoutHeader) {
         const directive = prefixLayoutHeader[1] ?? 'type';
         return {
@@ -26,7 +28,7 @@ export function parseLayoutDeclarationAt(lines, index) {
     return parseLayoutBlock(lines, index, layoutHeader);
 }
 function parseTypeAlias(line, text) {
-    const nameLeftTypeAlias = /^([A-Za-z_][A-Za-z0-9_]*)(?::\s*|\s+)\.typealias\s+(.+)$/.exec(text);
+    const nameLeftTypeAlias = new RegExp(`^(${IDENTIFIER_PATTERN})(?::\\s*|\\s+)\\.typealias\\s+(.+)$`).exec(text);
     if (nameLeftTypeAlias) {
         const typeExprText = nameLeftTypeAlias[2] ?? '';
         const typeExpr = parseTypeExpr(typeExprText);
@@ -43,7 +45,7 @@ function parseTypeAlias(line, text) {
             diagnostics: [],
         };
     }
-    const oldTypeAlias = /^\.type\s+([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.+)$/.exec(text);
+    const oldTypeAlias = new RegExp(`^\\.type\\s+(${IDENTIFIER_PATTERN})\\s*=\\s*(.+)$`).exec(text);
     if (oldTypeAlias) {
         return {
             diagnostics: [
@@ -54,7 +56,7 @@ function parseTypeAlias(line, text) {
     return undefined;
 }
 function parseNameLeftLayoutHeader(text) {
-    const match = /^([A-Za-z_][A-Za-z0-9_]*)(?::\s*|\s+)\.(type|union)\s*$/.exec(text);
+    const match = new RegExp(`^(${IDENTIFIER_PATTERN})(?::\\s*|\\s+)\\.(type|union)\\s*$`).exec(text);
     return match
         ? {
             directive: match[2] ?? '',
@@ -107,7 +109,7 @@ function spanForLine(line) {
     return {
         sourceName: line.sourceName,
         line: line.line,
-        column: firstColumn(line.text),
+        column: firstNonWhitespaceColumn(line.text),
         ...(line.sourceUnit !== undefined ? { sourceUnit: line.sourceUnit } : {}),
         ...(line.sourceRelation !== undefined ? { sourceRelation: line.sourceRelation } : {}),
     };
@@ -122,7 +124,7 @@ function skipToLayoutEnd(lines, index, directive) {
     return index;
 }
 function parseLayoutField(text) {
-    const match = /^([A-Za-z_][A-Za-z0-9_]*)\s+(\.(?:field|byte|word|addr))(?:\s+(.+))?$/.exec(text);
+    const match = new RegExp(`^(${IDENTIFIER_PATTERN})\\s+(\\.(?:field|byte|word|addr))(?:\\s+(.+))?$`).exec(text);
     if (!match) {
         return undefined;
     }
@@ -174,16 +176,5 @@ function scalarFieldSize(typeName) {
     }
 }
 function parseDiagnostic(line, message) {
-    return {
-        severity: 'error',
-        code: 'AZMN_PARSE',
-        message,
-        sourceName: line.sourceName,
-        line: line.line,
-        column: firstColumn(line.text),
-    };
-}
-function firstColumn(text) {
-    const match = /\S/.exec(text);
-    return match ? match.index + 1 : 1;
+    return parseLineError(line, message);
 }

package/dist/src/syntax/parse-layout-expression.js

@@ -1,6 +1,7 @@
+import { IDENTIFIER_PATTERN } from './names.js';
 export function parseTypeExpr(text) {
     const trimmed = text.trim();
-    const match = /^([A-Za-z_][A-Za-z0-9_]*)(?:\[\s*([0-9]+)\s*\])?$/.exec(trimmed);
+    const match = new RegExp(`^(${IDENTIFIER_PATTERN})(?:\\[\\s*([0-9]+)\\s*\\])?$`).exec(trimmed);
     if (!match) {
         return undefined;
     }
@@ -118,7 +119,7 @@ function parseLayoutCastPathPart(text, parseNestedExpression) {
         : parseLayoutCastIndex(text, parseNestedExpression);
 }
 function parseLayoutCastField(text) {
-    const field = /^\.([A-Za-z_][A-Za-z0-9_]*)/.exec(text);
+    const field = new RegExp(`^\\.(${IDENTIFIER_PATTERN})`).exec(text);
     return field ? { part: { kind: 'field', name: field[1] ?? '' }, rest: text.slice(field[0].length) } : undefined;
 }
 function parseLayoutCastIndex(text, parseNestedExpression) {
@@ -168,7 +169,7 @@ function parseOffsetIndex(text) {
         : undefined;
 }
 function parseOffsetField(text) {
-    const field = /^[A-Za-z_][A-Za-z0-9_]*/.exec(text);
+    const field = new RegExp(`^${IDENTIFIER_PATTERN}`).exec(text);
     return field
         ? { part: { kind: 'field', name: field[0] }, rest: text.slice(field[0].length) }
         : undefined;

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

@@ -1,5 +1,7 @@
 import { extractLineComment, stripLineComment } from '../source/strip-line-comment.js';
 import { normalizeDirectiveAlias } from './directive-aliases.js';
+import { LABEL_NAME_PATTERN, parseEntryLabel } from './names.js';
+import { firstNonWhitespaceColumn, parseLineError } from './parse-diagnostics.js';
 import { parseColonDeclaration, parseDirectiveStatement } from './parse-directive-statement.js';
 import { parseZ80Instruction } from '../z80/parse-instruction.js';
 export function parseLogicalLine(line, options = {}) {
@@ -8,34 +10,38 @@ export function parseLogicalLine(line, options = {}) {
         return commentOnlyLine(line);
     }
     const span = spanForLine(line);
-    const labelWithStatement = /^(@?[A-Za-z_.$?][A-Za-z0-9_.$?]*):\s*(.+)$/.exec(text);
+    const labelWithStatement = new RegExp(`^(@?${LABEL_NAME_PATTERN}):\\s*(.+)$`).exec(text);
     if (labelWithStatement) {
         const rawLabel = labelWithStatement[1] ?? '';
-        const labelName = normalizeEntryLabelName(rawLabel);
-        const isEntry = rawLabel.startsWith('@');
+        const label = parseEntryLabel(rawLabel);
+        if (!label)
+            return withLineComment(line, parseCanonicalStatement(line, text, span));
         const statementText = labelWithStatement[2] ?? '';
-        const declaration = parseColonDeclaration(line, labelName, statementText, span);
+        const declaration = parseColonDeclaration(line, label.name, statementText, span);
         if (declaration) {
             return withLineComment(line, declaration);
         }
         const parsedStatement = parseCanonicalStatement(line, statementText, span);
         return withLineComment(line, {
             items: [
-                { kind: 'label', name: labelName, ...(isEntry ? { isEntry: true } : {}), span },
+                { kind: 'label', name: label.name, ...(label.isEntry ? { isEntry: true } : {}), span },
                 ...parsedStatement.items,
             ],
             diagnostics: parsedStatement.diagnostics,
         });
     }
-    const labelOnly = /^(@?[A-Za-z_.$?][A-Za-z0-9_.$?]*):$/.exec(text);
+    const labelOnly = new RegExp(`^(@?${LABEL_NAME_PATTERN}):$`).exec(text);
     if (labelOnly) {
         const rawLabel = labelOnly[1] ?? '';
+        const label = parseEntryLabel(rawLabel);
+        if (!label)
+            return withLineComment(line, parseCanonicalStatement(line, text, span));
         return withLineComment(line, {
             items: [
                 {
                     kind: 'label',
-                    name: normalizeEntryLabelName(rawLabel),
-                    ...(rawLabel.startsWith('@') ? { isEntry: true } : {}),
+                    name: label.name,
+                    ...(label.isEntry ? { isEntry: true } : {}),
                     span,
                 },
             ],
@@ -58,7 +64,7 @@ function commentOnlyLine(line) {
                 span: {
                     sourceName: line.sourceName,
                     line: line.line,
-                    column: firstColumn(line.text),
+                    column: firstNonWhitespaceColumn(line.text),
                     ...(line.sourceUnit !== undefined ? { sourceUnit: line.sourceUnit } : {}),
                     ...(line.sourceRelation !== undefined ? { sourceRelation: line.sourceRelation } : {}),
                 },
@@ -82,7 +88,7 @@ function withLineComment(line, result) {
                 span: {
                     sourceName: line.sourceName,
                     line: line.line,
-                    column: firstColumn(line.text),
+                    column: firstNonWhitespaceColumn(line.text),
                     ...(line.sourceUnit !== undefined ? { sourceUnit: line.sourceUnit } : {}),
                     ...(line.sourceRelation !== undefined ? { sourceRelation: line.sourceRelation } : {}),
                 },
@@ -106,37 +112,20 @@ function parseCanonicalStatement(line, text, span) {
     if (instruction?.diagnostics && instruction.diagnostics.length > 0) {
         return {
             items: [],
-            diagnostics: instruction.diagnostics.map((message) => parseError(line, message)),
+            diagnostics: instruction.diagnostics.map((message) => parseLineError(line, message)),
         };
     }
     if (instruction?.error) {
-        return { items: [], diagnostics: [parseError(line, instruction.error)] };
+        return { items: [], diagnostics: [parseLineError(line, instruction.error)] };
     }
-    return { items: [], diagnostics: [parseError(line, `unsupported source line: ${text}`)] };
+    return { items: [], diagnostics: [parseLineError(line, `unsupported source line: ${text}`)] };
 }
 function spanForLine(line) {
     return {
         sourceName: line.sourceName,
         line: line.line,
-        column: firstColumn(line.text),
+        column: firstNonWhitespaceColumn(line.text),
         ...(line.sourceUnit !== undefined ? { sourceUnit: line.sourceUnit } : {}),
         ...(line.sourceRelation !== undefined ? { sourceRelation: line.sourceRelation } : {}),
     };
 }
-function normalizeEntryLabelName(raw) {
-    return raw.startsWith('@') ? raw.slice(1) : raw;
-}
-function firstColumn(text) {
-    const match = /\S/.exec(text);
-    return match ? match.index + 1 : 1;
-}
-function parseError(line, message) {
-    return {
-        severity: 'error',
-        code: 'AZMN_PARSE',
-        message,
-        sourceName: line.sourceName,
-        line: line.line,
-        column: firstColumn(line.text),
-    };
-}

package/dist/src/syntax/parse-location-directives.d.ts

@@ -0,0 +1,7 @@
+import type { LogicalLine } from '../source/logical-lines.js';
+import type { ParseLineResult } from './parse-line.js';
+export declare function parseExpressionDirective(line: LogicalLine, kind: 'align' | 'binfrom' | 'binto' | 'org', expressionText: string, span: {
+    readonly sourceName: string;
+    readonly line: number;
+    readonly column: number;
+}): ParseLineResult;

package/dist/src/syntax/parse-location-directives.js

@@ -0,0 +1,15 @@
+import { parseLineError } from './parse-diagnostics.js';
+import { parseExpression } from './parse-expression.js';
+export function parseExpressionDirective(line, kind, expressionText, span) {
+    const expression = parseExpression(expressionText);
+    if (!expression) {
+        return {
+            items: [],
+            diagnostics: [parseLineError(line, `invalid .${kind} expression: ${expressionText}`)],
+        };
+    }
+    if (kind === 'align') {
+        return { items: [{ kind, alignment: expression, span }], diagnostics: [] };
+    }
+    return { items: [{ kind, expression, span }], diagnostics: [] };
+}

package/dist/src/syntax/statement-classification.d.ts

@@ -0,0 +1,2 @@
+export declare function isChainedDirectiveOrDeclaration(text: string): boolean;
+export declare function isPotentialOpInvocationStatement(text: string): boolean;

package/dist/src/syntax/statement-classification.js

@@ -0,0 +1,24 @@
+import { IDENTIFIER_PATTERN, LABEL_NAME_PATTERN } from './names.js';
+const CHAIN_DECLARATION_RE = new RegExp(`^${LABEL_NAME_PATTERN}\\s+\\.?(?:equ|enum|type|union|typealias)\\b`, 'i');
+const IDENTIFIER_STATEMENT_RE = new RegExp(`^${IDENTIFIER_PATTERN}(?:\\s+.*)?$`);
+const EQU_DECLARATION_RE = new RegExp(`^${IDENTIFIER_PATTERN}\\s+\\.?equ\\b`, 'i');
+const LAYOUT_DECLARATION_RE = new RegExp(`^${IDENTIFIER_PATTERN}\\s+\\.(?:enum|type|union|typealias|field|byte|word|addr)\\b`);
+export function isChainedDirectiveOrDeclaration(text) {
+    return (/^\./.test(text) ||
+        /^(?:org|equ|db|dw|ds|align|include|import|binfrom|binto|cstr|pstr|istr|end|enum|type|union|field|byte|word|addr|endtype|endunion|typealias|if|else|endif|op)\b/i.test(text) ||
+        CHAIN_DECLARATION_RE.test(text));
+}
+export function isPotentialOpInvocationStatement(text) {
+    if (!IDENTIFIER_STATEMENT_RE.test(text))
+        return false;
+    if (EQU_DECLARATION_RE.test(text))
+        return false;
+    if (LAYOUT_DECLARATION_RE.test(text))
+        return false;
+    if (/^(?:op|end|enum|type|union|field|byte|word|addr)\b/i.test(text))
+        return false;
+    if (/^(?:org|equ|db|dw|ds|align|include|binfrom|binto|cstr|pstr|istr)\b/i.test(text)) {
+        return false;
+    }
+    return true;
+}

package/dist/src/tooling/case-style.js

@@ -1,4 +1,7 @@
+import { splitInstructionChain } from '../source/instruction-chain.js';
 import { stripLineComment } from '../source/strip-line-comment.js';
+import { IDENTIFIER_PATTERN } from '../syntax/names.js';
+import { isPotentialOpInvocationStatement } from '../syntax/statement-classification.js';
 const REGISTER_RE = /(?<![A-Za-z0-9_$])(AF'|AF|BC|DE|HL|SP|IXH|IXL|IYH|IYL|IX|IY|A|B|C|D|E|H|L|I|R)(?![A-Za-z0-9_])/gi;
 export function lintCaseStyleNext(options) {
     if (options.mode === 'off')
@@ -23,19 +26,32 @@ function buildSourceLineMap(sourceTexts) {
     return result;
 }
 function lintInstructionLine(rawLine, sourceName, line, mode, state, diagnostics) {
-    const text = stripLeadingLabels(stripLineComment(rawLine)).trim();
+    const segments = splitInstructionChain(rawLine);
+    if (segments !== undefined) {
+        for (let index = 0; index < segments.length; index += 1) {
+            const stripped = index === 0
+                ? stripLeadingLabelsWithOffset(segments[index].text)
+                : { text: segments[index].text, offset: 0 };
+            lintInstructionSegment(stripped.text.trim(), segments[index].column + stripped.offset + firstColumn(stripped.text) - 1, sourceName, line, mode, state, diagnostics);
+        }
+        return;
+    }
+    const stripped = stripLeadingLabelsWithOffset(stripLineComment(rawLine));
+    lintInstructionSegment(stripped.text.trim(), stripped.offset + firstColumn(stripped.text), sourceName, line, mode, state, diagnostics);
+}
+function lintInstructionSegment(text, baseColumn, sourceName, line, mode, state, diagnostics) {
     if (text.length === 0)
         return;
     const mnemonic = text.split(/\s+/, 1)[0] ?? '';
     if (mnemonic.length > 0) {
-        lintToken(mode, state, mnemonic, 'mnemonic', sourceName, line, diagnostics);
+        lintToken(mode, state, mnemonic, 'mnemonic', sourceName, line, baseColumn, diagnostics);
     }
     const scrubbed = scrubCharLiterals(text);
     for (const match of scrubbed.matchAll(REGISTER_RE)) {
         const raw = match[1];
         if (!raw)
             continue;
-        lintToken(mode, state, raw, 'register', sourceName, line, diagnostics);
+        lintToken(mode, state, raw, 'register', sourceName, line, baseColumn + match.index, diagnostics);
     }
 }
 function lintSourceLines(sourceLines, instructionLines, mode, state, diagnostics) {
@@ -67,42 +83,30 @@ function shouldLintCaseStyleLine(rawLine, sourceName, line, instructionLines, st
         isPotentialOpInvocationLine(text));
 }
 function isOpHeaderLine(text) {
-    return /^op\s+[A-Za-z_][A-Za-z0-9_]*\s*\(/i.test(text);
+    return new RegExp(`^op\\s+${IDENTIFIER_PATTERN}\\s*\\(`, 'i').test(text);
 }
 function isOpEndLine(text) {
     return /^end\s*$/i.test(text);
 }
 function isPotentialOpInvocationLine(text) {
-    if (!/^[A-Za-z_][A-Za-z0-9_]*(?:\s+.*)?$/.test(text))
-        return false;
-    if (/^[A-Za-z_][A-Za-z0-9_]*\s+\.?equ\b/i.test(text))
-        return false;
-    if (/^[A-Za-z_][A-Za-z0-9_]*\s+\.(?:enum|type|union|typealias|field|byte|word|addr)\b/.test(text)) {
-        return false;
-    }
-    if (/^(?:op|end|enum|type|union|field|byte|word|addr)\b/i.test(text))
-        return false;
-    if (/^(?:org|equ|db|dw|ds|align|include|binfrom|binto|cstr|pstr|istr)\b/i.test(text)) {
-        return false;
-    }
-    return true;
+    return isPotentialOpInvocationStatement(text);
 }
 function lineKey(sourceName, line) {
     return `${sourceName}:${line}`;
 }
-function lintToken(mode, state, token, category, sourceName, line, diagnostics) {
+function lintToken(mode, state, token, category, sourceName, line, column, diagnostics) {
     const style = classifyTokenStyle(token);
     if (!style)
         return;
     if (mode === 'consistent') {
-        lintConsistentToken(state, style, token, category, sourceName, line, diagnostics);
+        lintConsistentToken(state, style, token, category, sourceName, line, column, diagnostics);
         return;
     }
     if (mode === 'off')
         return;
-    lintFixedStyleToken(mode, style, token, category, sourceName, line, diagnostics);
+    lintFixedStyleToken(mode, style, token, category, sourceName, line, column, diagnostics);
 }
-function lintConsistentToken(state, style, token, category, sourceName, line, diagnostics) {
+function lintConsistentToken(state, style, token, category, sourceName, line, column, diagnostics) {
     if (!state.consistentStyle && (style === 'upper' || style === 'lower')) {
         state.consistentStyle = style;
         return;
@@ -116,10 +120,10 @@ function lintConsistentToken(state, style, token, category, sourceName, line, di
         message: `Case-style lint: ${category} "${token}" does not match established ${expected}case style under --case-style=consistent.`,
         sourceName,
         line,
-        column: 1,
+        column,
     });
 }
-function lintFixedStyleToken(mode, style, token, category, sourceName, line, diagnostics) {
+function lintFixedStyleToken(mode, style, token, category, sourceName, line, column, diagnostics) {
     if (style === mode)
         return;
     const expectedText = mode === 'upper' ? 'uppercase' : 'lowercase';
@@ -129,7 +133,7 @@ function lintFixedStyleToken(mode, style, token, category, sourceName, line, dia
         message: `Case-style lint: ${category} "${token}" should be ${expectedText} under --case-style=${mode}.`,
         sourceName,
         line,
-        column: 1,
+        column,
     });
 }
 function classifyTokenStyle(token) {
@@ -143,14 +147,26 @@ function classifyTokenStyle(token) {
     return 'mixed';
 }
 function stripLeadingLabels(text) {
+    return stripLeadingLabelsWithOffset(text).text;
+}
+function stripLeadingLabelsWithOffset(text) {
     let remaining = text;
+    let offset = 0;
     while (true) {
-        const stripped = remaining.replace(/^\s*[A-Za-z_.$?][A-Za-z0-9_.$?]*\s*:\s*/, '');
+        const match = /^\s*[A-Za-z_.$?][A-Za-z0-9_.$?]*\s*:\s*/.exec(remaining);
+        if (!match)
+            return { text: remaining, offset };
+        const stripped = remaining.slice(match[0].length);
         if (stripped === remaining)
-            return remaining;
+            return { text: remaining, offset };
         remaining = stripped;
+        offset += match[0].length;
     }
 }
+function firstColumn(text) {
+    const match = /\S/.exec(text);
+    return match ? match.index + 1 : 1;
+}
 function scrubCharLiterals(text) {
     let output = '';
     let inChar = false;

package/docs/codebase/02-source-loading-and-parsing.md

@@ -15,9 +15,9 @@ tooling and register contracts consume.
 
 The loading boundary lives in `src/node/source-host.ts`. The parser is
 orchestrated by `parseNextSourceItems()` in `src/core/compile.ts`, with
-single-line parsing in `src/syntax/parse-line.ts`. Expression and declaration
-parsing is split across tokenizer, token-expression, directive and layout
-modules in `src/syntax/`.
+single-line parsing in `src/syntax/parse-line.ts`. Expression, name,
+instruction-chain and directive parsing is split across small syntax helpers in
+`src/syntax/`.
 
 ## Entry Files and Source Text
 
@@ -123,6 +123,7 @@ The source helpers are small and important:
 | `logical-lines.ts`        | Splits text into line records.                         |
 | `source-span.ts`          | Defines the common span shape.                         |
 | `line-comment-scanner.ts` | Finds line comments while respecting quoted text.      |
+| `instruction-chain.ts`    | Finds spaced-backslash separators and segment columns. |
 | `strip-line-comment.ts`   | Removes semicolon comments through the shared scanner. |
 
 `strip-line-comment.ts` is used by source-loading directive recognition, layout parsing,
@@ -130,6 +131,15 @@ conditional assembly and single-line parsing. Shared comment handling prevents
 each stage from inventing a slightly different rule for semicolons inside
 strings and character literals.
 
+`src/source/instruction-chain.ts` uses the same quoted-text rules to find
+readable ` \ ` separators without splitting byte and string operands. It
+reports trimmed segment text plus the original 1-based column for each segment,
+so later stages can keep diagnostics and source maps aligned to the exact
+instruction inside a physical line. `src/syntax/parse-instruction-chain.ts`
+then applies the syntax rules: labels are allowed only before the first segment,
+directives and declarations are rejected, and each segment is parsed as an
+instruction or op invocation.
+
 ## Directive Aliases
 
 Directive aliases are loaded during `loadProgramNext()`:
@@ -182,13 +192,16 @@ spans to connect emitted bytes back to files and lines.
 4. Record and union headers collect `.field` declarations until `.endtype` or
    `.endunion`.
 5. Visible op invocations expand into ordinary source items.
-6. `parseLogicalLine()` handles single-line labels, directives, data and
-   instructions.
+6. Chained instruction lines are split on spaced backslashes and each segment is
+   parsed as an instruction or op invocation.
+7. `parseLogicalLine()` handles remaining single-line labels, directives, data
+   and instructions.
 
 This order matters. Ops must be collected before invocation expansion. Layout
 declarations must collect their body lines as one source item. Ordinary
 instruction parsing should see the lines that remain after those structural
-forms have been handled.
+forms have been handled. Chained instruction parsing also needs the op registry
+up front so later segments can expand ops and keep segment-level columns.
 
 ## Layout and Declaration Parsing
 
@@ -237,10 +250,17 @@ assembler-time value based on expression evaluation.
 `src/syntax/expression-tokenizer.ts` tokenizes expression text.
 `parse-token-expression.ts` builds expression trees from tokens.
 `parse-expression.ts` is the public syntax wrapper used by line parsing.
+`names.ts` centralises identifier, label and `@` entry-label parsing so line
+parsing, chained-line parsing, op expansion and tooling share the same name
+rules.
+`statement-classification.ts` distinguishes potential op invocations from
+declarations and rejects directives inside chained instruction segments.
 `parse-layout-expression.ts` parses layout type expressions used by `.ds`,
 `.field`, `.typealias`, `sizeof(...)`, `offset(...)` and layout casts.
-`parse-directive-statement.ts` parses directive statements that need more than
-single-token recognition.
+`parse-directive-statement.ts` dispatches directive statements into focused
+parsers: declaration directives in `parse-declaration-directives.ts`, data and
+string directives in `parse-data-directives.ts` and expression-bearing location
+directives in `parse-location-directives.ts`.
 
 The parser produces expression trees from `src/model/expression.ts`.
 `src/semantics/expression-evaluation.ts` evaluates those trees when the

package/docs/codebase/04-ops-and-register-contracts.md

@@ -67,6 +67,12 @@ The parser handles op invocations before `parseLogicalLine()`. An op head can
 look like an instruction head at the source level. The expansion stage resolves
 it before ordinary line parsing.
 
+Top-level parsing also recognises chained instruction lines separated by a
+spaced backslash. Each segment is parsed independently, with labels only
+allowed before the first segment and directives still restricted to their own
+physical lines. That lets short instruction runs compact onto one source line
+without changing directive or declaration shape.
+
 ## Overloads and Templates
 
 Ops support overloads. `op-selection.ts` compares invocation operands against
@@ -84,6 +90,12 @@ from the call site are substituted into the template by
 `op-instruction-instantiation.ts`. The result is formatted as ordinary source
 text and parsed through the same line parser used for top-level source.
 
+Op bodies now accept the same chained-instruction form as top-level source.
+`collectOps()` splits a spaced-backslash body line into template segments before
+it decides whether each segment is a parameterised instruction template, an
+ordinary source-item fragment or a nested op invocation. A first label may lead
+the chain and becomes an ordinary label item in the expanded body.
+
 Local label rewriting lives in `op-local-labels.ts`. A local label in an op
 expansion becomes unique at the use site so each expansion receives its own
 generated label. Once the rewritten labels become source items, address planning
@@ -148,7 +160,10 @@ items. Routine-specific extraction is split into
 `programModel-boundaries.ts` and `programModel-routines.ts`. Together they find
 routine boundaries, direct calls, labels and instructions. Routine entry labels
 use `@` in source and become callable public routine names after the marker is
-removed.
+removed. When an imported public routine calls private labels inside the same
+import unit, the routine builder keeps those direct call targets in the
+internal routine set so strict analysis can follow imported helper routines
+without exposing them outside the module.
 
 `src/register-contracts/smartComments.ts` reads AZMDoc comments from the comment maps
 captured during loading. Comment-block splitting and token parsing live in
@@ -166,6 +181,8 @@ Contracts can describe:
 Source comments and external interfaces describe the same kind of fact: a
 routine contract. Source comments attach to routines in the current program.
 `.asmi` entries attach to routines whose source is assembled elsewhere.
+The compact source form can place several clauses on one `;!` line, for
+example `;! in A; out A; clobbers F`.
 
 ## Effects, Summaries and Liveness
 
@@ -198,8 +215,12 @@ boundary may leave the stack in an unknown state.
 ## Reports, Interfaces and Tooling
 
 `report.ts` renders human-readable `.regcontracts.txt` reports and `.asmi` interface
-metadata. `annotate.ts`, `annotations.ts`, `fix.ts` and `sourceText.ts` support
-source updates for generated AZMDoc comments and conservative fixes.
+metadata. It also renders generated source contracts as one compact `;!` line,
+joining `in`, `out`, `maybe-out` and `clobbers` clauses with semicolons.
+When a routine may clobber the full flag set, the source form uses `F` as the
+compact carrier name. `annotate.ts`, `annotations.ts`, `fix.ts` and
+`sourceText.ts` support source updates for generated AZMDoc comments and
+conservative fixes.
 
 The CLI can request these behaviours through:
 

package/docs/codebase/05-interfaces-and-output-artifacts.md

@@ -164,6 +164,11 @@ When `loaded.loadedProgram` is present, the editor can call
 `analyzeRegisterContractsForTools()` for register contract candidate diagnostics
 and code actions.
 
+Case-style linting now understands chained instruction lines. A physical line
+such as `LD A,B \ inc c \ RET` is linted per segment, and warnings report the
+column of the specific mnemonic or register inside the chain rather than the
+start of the line.
+
 ## Artifact Types
 
 The output layer uses structured artifact objects from `src/outputs/types.ts`:
@@ -212,6 +217,11 @@ The writer normalizes source paths through `sourceRoot` when provided. It also
 coalesces source segments and clips them to written ranges so Debug80 receives a
 clean map of source lines to emitted bytes.
 
+When one physical line emits multiple chained instructions, each emitted segment
+keeps its own source column in the D8 map. Debug80 can therefore point at the
+exact chained instruction that produced each byte range instead of collapsing
+the whole line to one column.
+
 The D8 map distinguishes addressable symbols from constants. Labels and
 addressable data carry addresses. Constants carry values. Debug80 can then use
 addressable symbols for breakpoints and display constants as metadata.