@jhlagado/azm 0.2.10 → 0.2.12

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.

package/docs/codebase/06-verification-and-maintenance.md

@@ -74,6 +74,11 @@ These tests compare AZM behaviour against ASM80 expectations, lowered output and
 real-program fixtures. For an assembler, a one-byte difference is a behavioural
 change.
 
+The chained-instruction feature currently lives in `test/asm80/` because it
+crosses parser, op expansion, D8 map output and case-style linting in one user
+visible source shape. `multi_instruction_lines.test.ts` is the focused
+acceptance suite for that contract.
+
 ## Fixtures and Helpers
 
 `test/fixtures/` contains small source programs named after the issue or
@@ -115,11 +120,11 @@ Use this map when choosing a verification lane:
 
 | Change                      | Tests                                                                |
 | --------------------------- | -------------------------------------------------------------------- |
-| Parser or expression syntax | `test/unit/syntax/**`, relevant integration tests.                   |
+| Parser or expression syntax | `test/unit/syntax/**`, relevant integration tests and `test/asm80/multi_instruction_lines.test.ts` when the change affects chained physical lines. |
 | Source loading or tooling provenance | `test/integration/stage-11-tooling-api.test.ts`, relevant unit tests in `test/unit/source/**`. |
 | Z80 instruction support     | `test/unit/z80/**`, diagnostic matrices, ASM80 parity when relevant. |
 | Layout semantics            | layout integration tests and output tests.                           |
-| Ops                         | `test/unit/expansion/**`, op integration tests.                      |
+| Ops                         | `test/unit/expansion/**`, op integration tests and `test/asm80/multi_instruction_lines.test.ts` for chained bodies and invocation segments. |
 | Register contracts          | register contract unit, integration and CLI tests.                   |
 | CLI options                 | `test/cli/**`.                                                       |
 | Output artifacts            | `test/unit/outputs/**`, CLI artifact tests.                          |
@@ -145,7 +150,8 @@ Ask what kind of fact the change affects:
   `core/compile.ts`.
 - Assembler-time facts belong in `assembly/` and `semantics/`.
 - Instruction forms belong in `z80/`.
-- Inline source generation belongs in `expansion/`.
+- Instruction-chain splitting belongs in `source/`, while inline source
+  generation and op template expansion belong in `expansion/`.
 - Routine contracts and liveness belong in `register-contracts/`.
 - Artifact shape belongs in `outputs/`.
 - User commands belong in `cli/`.

package/docs/codebase/appendices/a-directory-file-reference.md

@@ -172,21 +172,28 @@ you need to find the owner of a behaviour quickly.
 | `logical-lines.ts`        | Splits source text into logical line records.            |
 | `source-span.ts`          | Defines source span shape.                               |
 | `line-comment-scanner.ts` | Finds semicolon comments while respecting quoted text.   |
+| `instruction-chain.ts`    | Splits spaced-backslash instruction lines into segments. |
 | `strip-line-comment.ts`   | Removes semicolon comments while respecting quoted text. |
 
 ## `src/syntax/`
 
 | File                           | Role                                                  |
 | ------------------------------ | ----------------------------------------------------- |
-| `parse-line.ts`                | Parses single logical lines into source items.        |
-| `expression-tokenizer.ts`      | Tokenizes expression text.                            |
-| `parse-token-expression.ts`    | Parses tokenized expressions into ASTs.               |
-| `parse-expression.ts`          | Public expression parse wrapper.                      |
-| `parse-directive-statement.ts` | Parses directive statements with structured operands. |
-| `parse-layout-declarations.ts` | Parses layout declaration forms.                      |
-| `parse-layout-expression.ts`   | Parses layout type expressions.                       |
-| `parse-diagnostics.ts`         | Shared parse diagnostic helpers.                      |
-| `directive-aliases.ts`         | Built-in and project directive alias policy.          |
+| `parse-line.ts`                    | Parses single logical lines into source items.                    |
+| `expression-tokenizer.ts`          | Tokenizes expression text.                                        |
+| `parse-token-expression.ts`        | Parses tokenized expressions into ASTs.                           |
+| `parse-expression.ts`              | Public expression parse wrapper.                                  |
+| `names.ts`                         | Shared identifier, label and entry-label parsing primitives.      |
+| `parse-instruction-chain.ts`       | Parses spaced-backslash chained instruction segments.             |
+| `statement-classification.ts`      | Shared chained-line and op-invocation classification helpers.     |
+| `parse-directive-statement.ts`     | Dispatches directive statements to focused directive parsers.      |
+| `parse-data-directives.ts`         | Parses `.db`, `.dw`, `.ds`, `.cstr`, `.pstr` and `.istr`.         |
+| `parse-declaration-directives.ts`  | Parses `.equ`, `.enum` and quoted declaration payloads.           |
+| `parse-location-directives.ts`     | Parses `.org`, `.align`, `.binfrom` and `.binto`.                 |
+| `parse-layout-declarations.ts`     | Parses layout declaration forms.                                  |
+| `parse-layout-expression.ts`       | Parses layout type expressions.                                   |
+| `parse-diagnostics.ts`             | Shared parse diagnostic helpers.                                  |
+| `directive-aliases.ts`             | Built-in and project directive alias policy.                      |
 
 ## `src/tooling/`
 
@@ -232,7 +239,7 @@ you need to find the owner of a behaviour quickly.
 | `test/integration/`                    | Cross-stage compiler tests.                      |
 | `test/integration/register-contracts/` | End-to-end register contract tests.              |
 | `test/cli/`                            | CLI option, artifact and exit-code contracts.    |
-| `test/asm80/`                          | ASM80 compatibility and real-program acceptance. |
+| `test/asm80/`                          | ASM80 compatibility, real-program acceptance and chained-line behaviour. |
 | `test/differential/`                   | Differential comparison fixtures and runners.    |
 | `test/fixtures/`                       | Source fixture programs.                         |
 | `test/helpers/`                        | Shared test setup and helpers.                   |

package/docs/codebase/appendices/b-compile-flow-reference.md

@@ -30,9 +30,10 @@ compile(entryFile, options, deps)
     parseNextSourceItems()
       applyConditionalAssembly()
       collect op definitions
+      expand op invocations
+      split chained instruction lines
       tokenize and parse expressions
       parse layouts, aliases, enums, directives and instructions
-      expand op invocations
   analyzeProgramNext()
     assembleProgram() for symbols
     lintCaseStyleNext()
@@ -98,6 +99,6 @@ tooling integrations that still use the older name.
 | Parsing            | logical lines        | source items                          |
 | Analysis           | source items         | diagnostics, symbols                  |
 | Register contracts | loaded program       | summaries, conflicts, reports         |
-| Assembly           | source items         | byte map, symbols, source segments    |
+| Assembly           | source items         | byte map, symbols, source segments with per-item columns |
 | Outputs            | byte map and symbols | artifacts                             |
 | CLI                | artifacts            | files on disk                         |

package/docs/codebase/index.md

@@ -44,3 +44,7 @@ modules. The directory appendix is the current file map for those modules.
 - [Appendix A - Directory and File Reference](appendices/a-directory-file-reference.md)
 - [Appendix B - Compile Flow Reference](appendices/b-compile-flow-reference.md)
 - [Appendix C - Public Surface Reference](appendices/c-public-surface-reference.md)
+
+## Related References
+
+- [AZM Grammar Reference](../reference/azm-grammar.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhlagado/azm",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "AZM assembler for the Z80 family (Node.js CLI)",
   "license": "GPL-3.0-only",
   "engines": {