feat(source): the unbalanced-format error offers to insert the missing ^XA or ^XZ

Author: u8array

README.md

@@ -97,7 +97,7 @@ The **ZPL** panel highlights syntax and collapses long blocks of image data. Sel
 
 The **ZPL reference** beside the code follows the cursor. Search to filter the list, or click a command to pin its details. A double-click or the right-click menu inserts the command at the cursor. The chevron in the heading folds the list.
 
-While you edit, the canvas shows a live preview. Canvas editing and the **Properties** tab are disabled. Page switching stays enabled. The editor refuses source that is too large or has mismatched `^XA`/`^XZ` commands, and marks the mismatches.
+While you edit, the canvas shows a live preview. Canvas editing and the **Properties** tab are disabled. Page switching stays enabled. The editor refuses source that is too large or has mismatched `^XA`/`^XZ` commands, and marks the mismatches. Click a mark to insert the missing command.
 
 - **Apply** or leaving the panel commits your changes.
 - `Esc` or **Cancel** discards them.

src/components/Output/ZplCodeMirror.test.tsx

@@ -368,7 +368,7 @@ describe("ZplCodeMirror diagnostics", () => {
         value={value}
         onChange={onChange}
         ariaLabel="zpl" placeholderText="ph"
-        diagnostics={[{ from, to: from + dropped.length, severity: "warning", message: "dropped", fix: { command: "^FS", label: "Insert ^FS" } }]}
+        diagnostics={[{ from, to: from + dropped.length, severity: "warning", message: "dropped", fix: { command: "^FS", label: "Insert ^FS", place: "after" } }]}
       />,
     );
     const view = EditorView.findFromDOM(container as HTMLElement)!;
@@ -380,6 +380,25 @@ describe("ZplCodeMirror diagnostics", () => {
     expect(onChange).toHaveBeenCalledWith(expect.stringContaining(`${dropped}#FS#FO10,60`));
   });
 
+  it("closes an open format before the opener that interrupts it, spelled with the prefix in force", async () => {
+    const { forEachDiagnostic } = await import("@codemirror/lint");
+    const value = "^CC#\n#XA#FO10,10#FDa#FS\n#XA#FDb#FS#XZ";
+    const from = value.indexOf("#XA");
+    const { container } = render(
+      <ZplCodeMirror
+        value={value}
+        onChange={vi.fn()}
+        ariaLabel="zpl" placeholderText="ph"
+        diagnostics={[{ from, to: from + 3, severity: "error", message: "open", fix: { command: "^XZ", label: "Insert ^XZ", place: "closeFormat" } }]}
+      />,
+    );
+    const view = EditorView.findFromDOM(container as HTMLElement)!;
+    const seen: { d: Diagnostic; from: number; to: number }[] = [];
+    forEachDiagnostic(view.state, (d, start, end) => seen.push({ d, from: start, to: end }));
+    act(() => seen[0]?.d.actions?.[0]?.apply(view, seen[0].from, seen[0].to));
+    expect(view.state.doc.toString()).toBe("^CC#\n#XA#FO10,10#FDa#FS\n#XZ\n#XA#FDb#FS#XZ");
+  });
+
   it("keeps the field's trailing data when the lint's end was trimmed", async () => {
     const { forEachDiagnostic } = await import("@codemirror/lint");
     // The parser trims the span for the underline, but "ab   " is the data.
@@ -390,7 +409,7 @@ describe("ZplCodeMirror diagnostics", () => {
         value={value}
         onChange={vi.fn()}
         ariaLabel="zpl" placeholderText="ph"
-        diagnostics={[{ from: 3, to, severity: "warning", message: "dropped", fix: { command: "^FS", label: "Insert ^FS" } }]}
+        diagnostics={[{ from: 3, to, severity: "warning", message: "dropped", fix: { command: "^FS", label: "Insert ^FS", place: "after" } }]}
       />,
     );
     const view = EditorView.findFromDOM(container as HTMLElement)!;
@@ -409,7 +428,7 @@ describe("ZplCodeMirror diagnostics", () => {
         value={value}
         onChange={onChange}
         ariaLabel="zpl" placeholderText="ph" readOnly
-        diagnostics={[{ from: 3, to: 12, severity: "warning", message: "dropped", fix: { command: "^FS", label: "Insert ^FS" } }]}
+        diagnostics={[{ from: 3, to: 12, severity: "warning", message: "dropped", fix: { command: "^FS", label: "Insert ^FS", place: "after" } }]}
       />,
     );
     const view = EditorView.findFromDOM(container as HTMLElement)!;

src/lib/sourceDiagnostics.test.ts

@@ -6,16 +6,19 @@ import { fallbackTranslations as en } from "../locales";
 import type { ImportFinding } from "@zplab/core/lib/importReport";
 
 describe("buildSourceDiagnostics", () => {
-  it("names each imbalance kind with the bytes it found", () => {
+  it("names each imbalance kind with the bytes it found and offers the missing command", () => {
     const of = (ub: { kind: "strayXz" | "unclosedXa"; at: number; cmd: string }) =>
       buildSourceDiagnostics({ reason: "unbalanced", unbalanced: ub }, [], en);
     // The generic banner told the user to ADD what the diagnostic points at.
     expect(of({ kind: "strayXz", at: 0, cmd: "#XZ" })).toEqual([{
       from: 0, to: 3, severity: "error",
       message: formatTemplate(en.output.lintStrayXzFmt, { cmd: "#XZ" }),
+      fix: { command: "^XA", label: formatTemplate(en.output.lintInsertCmdFmt, { cmd: "^XA" }), place: "openFormat" },
     }]);
     expect(of({ kind: "unclosedXa", at: 4, cmd: "#XA" })[0]?.message)
       .toBe(formatTemplate(en.output.lintUnclosedXaFmt, { cmd: "#XA" }));
+    expect(of({ kind: "unclosedXa", at: 4, cmd: "#XA" })[0]?.fix)
+      .toEqual({ command: "^XZ", label: formatTemplate(en.output.lintInsertCmdFmt, { cmd: "^XZ" }), place: "closeFormat" });
   });
 
   it("adds the repair site as a weaker second mark", () => {
@@ -25,6 +28,7 @@ describe("buildSourceDiagnostics", () => {
     }, [], en);
     expect(lints.map((l) => [l.from, l.severity])).toEqual([[0, "error"], [40, "related"]]);
     expect(lints[1]?.message).toBe(formatTemplate(en.output.lintStillOpenHereFmt, { cmd: "^XA" }));
+    expect(lints.map((l) => l.fix?.place)).toEqual(["closeFormat", "before"]);
   });
 
   it("stays silent for a refusal without a located command", () => {
@@ -65,7 +69,7 @@ describe("buildSourceDiagnostics", () => {
     const [a, b] = buildSourceDiagnostics(null, [dropped, other], en);
     expect(a?.to).toBe(29);
     expect(a?.message).toContain(en.importReport.unterminatedFieldTitleFmt.replace("{fs}", "^FS"));
-    expect(a?.fix).toEqual({ command: "^FS", label: formatTemplate(en.output.lintInsertCmdFmt, { cmd: "^FS" }) });
+    expect(a?.fix).toEqual({ command: "^FS", label: formatTemplate(en.output.lintInsertCmdFmt, { cmd: "^FS" }), place: "after" });
     expect(b?.fix).toBeUndefined();
   });
 

src/lib/sourceDiagnostics.ts

@@ -5,12 +5,14 @@ import { describeFinding } from './importReport';
 import { formatTemplate } from './formatTemplate';
 import type { Translations } from '../locales';
 
-/** One-click repair: the command the editor inserts at the first command boundary at
- *  or after the lint, spelled with the prefix in force there; the label stays canonical,
- *  as in the catalog. The imbalance kinds get none, as no single byte is the right spot. */
+/** Where a repair lands: after its lint, before it, where the open format must close, or where the orphan run must open. */
+export type FixPlace = 'after' | 'before' | 'closeFormat' | 'openFormat';
+
+/** One-click repair whose label stays canonical, as in the catalog, while the editor re-spells `command` where it inserts it. */
 export interface SourceFix {
   command: string;
   label: string;
+  place: FixPlace;
 }
 
 /** Editor-framework-neutral lint in STRING offsets of its build's text. */
@@ -45,11 +47,14 @@ export function buildSourceDiagnostics(
   const lints: SourceLint[] = [];
   if (refusal?.reason === 'unbalanced') {
     const ub: UnbalancedFormat = refusal.unbalanced;
+    const missing = ub.kind === 'strayXz' ? '^XA' : '^XZ';
+    const label = formatTemplate(t.output.lintInsertCmdFmt, { cmd: missing });
     lints.push({
       from: ub.at,
       to: ub.at + ub.cmd.length,
       severity: 'error',
       message: formatTemplate(t.output[KIND_MSG[ub.kind]], { cmd: ub.cmd }),
+      fix: { command: missing, label, place: ub.kind === 'strayXz' ? 'openFormat' : 'closeFormat' },
     });
     // The defect is the unterminated format, but the repair goes here, which in
     // a multi-label document is a whole label away from the opener.
@@ -59,6 +64,7 @@ export function buildSourceDiagnostics(
         to: ub.related.at + ub.related.cmd.length,
         severity: 'related',
         message: formatTemplate(t.output.lintStillOpenHereFmt, { cmd: ub.cmd }),
+        fix: { command: missing, label, place: 'before' },
       });
     }
   }
@@ -74,7 +80,7 @@ export function buildSourceDiagnostics(
     };
     // The field ends where the next command begins, which is where ^FS belongs.
     if (f.kind === 'unterminatedField') {
-      lint.fix = { command: '^FS', label: formatTemplate(t.output.lintInsertCmdFmt, { cmd: '^FS' }) };
+      lint.fix = { command: '^FS', label: formatTemplate(t.output.lintInsertCmdFmt, { cmd: '^FS' }), place: 'after' };
     }
     warnings.push(lint);
   }

src/lib/zplCmLint.ts

@@ -22,10 +22,10 @@ export function toDiagnostic(d: SourceLint, docPos: (offset: number) => number):
       ? [
           {
             name: fix.label,
-            // `to` arrives live: CM has mapped the range through edits made since the build.
-            apply: (view: EditorView, _from: number, to: number) => {
+            // CM has mapped this range through the edits made since the build.
+            apply: (view: EditorView, from: number, to: number) => {
               if (view.state.readOnly) return;
-              view.dispatch(fixInsertion(view.state, fix.command, to));
+              view.dispatch(fixInsertion(view.state, fix.command, fix.place, from, to));
             },
           },
         ]

src/lib/zplLanguage.test.ts

@@ -3,6 +3,7 @@ import { describe, it, expect } from "vitest";
 import { EditorState, type TransactionSpec } from "@codemirror/state";
 import { ensureSyntaxTree, foldable, syntaxTree } from "@codemirror/language";
 import { highlightCode } from "@lezer/highlight";
+import type { FixPlace } from "./sourceDiagnostics";
 import {
   buildZplTree,
   commandAtCursor,
@@ -296,15 +297,79 @@ describe("placesCaret", () => {
   });
 });
 
+const NL = String.fromCharCode(10);
+const CRLF = String.fromCharCode(13) + NL;
+
 describe("fixInsertion", () => {
   it("lands before the next command as the tokenizer sees it, not before a payload tilde", () => {
     // ^BX escapes like ~1 are data; only a tilde that opens a command ends the field.
     const doc = "^XA^FO1,1^BXN,5,200,,,,~^FDab~1x^FO2,2^FDb^FS^XZ";
     const state = EditorState.create({ doc, extensions: [zpl()] });
     const at = doc.indexOf("~1x");
-    const spec = fixInsertion(state, "^FS", at);
+    const spec = fixInsertion(state, "^FS", "after", at, at);
     expect(state.update(spec).state.doc.toString()).toBe("^XA^FO1,1^BXN,5,200,,,,~^FDab~1x^FS^FO2,2^FDb^FS^XZ");
   });
+
+  const fixed = (doc: string, command: string, place: FixPlace, from: number, to: number) => {
+    const state = EditorState.create({ doc, extensions: [zpl()] });
+    return state.update(fixInsertion(state, command, place, from, to)).state.doc.toString();
+  };
+
+  it("closes an open format on its own line before the opener that interrupts it", () => {
+    expect(fixed("^XA^FO1,1^FDa^FS^XA^FDb^FS^XZ", "^XZ", "closeFormat", 0, 3)).toBe("^XA^FO1,1^FDa^FS\n^XZ\n^XA^FDb^FS^XZ");
+  });
+
+  it("closes a format with no later opener at the end of the document", () => {
+    expect(fixed("^XA^FO1,1^FDa^FS", "^XZ", "closeFormat", 0, 3)).toBe("^XA^FO1,1^FDa^FS\n^XZ");
+  });
+
+  it("inserts the closer in front of the command the repair points at", () => {
+    const doc = "^XA^FO1,1^FDa^FS\n^XA^FDb^FS^XZ";
+    const at = doc.lastIndexOf("^XA");
+    expect(fixed(doc, "^XZ", "before", at, at + 3)).toBe("^XA^FO1,1^FDa^FS\n^XZ\n^XA^FDb^FS^XZ");
+  });
+
+  it("opens an orphan run after the previous closer", () => {
+    const doc = "^XA^FDa^FS^XZ^FO1,1^FDb^FS^XZ";
+    const at = doc.lastIndexOf("^XZ");
+    expect(fixed(doc, "^XA", "openFormat", at, at + 3)).toBe("^XA^FDa^FS^XZ\n^XA\n^FO1,1^FDb^FS^XZ");
+  });
+
+  it("opens an orphan run at the start of the stream", () => {
+    const doc = "^FO1,1^FDb^FS^XZ";
+    const at = doc.indexOf("^XZ");
+    expect(fixed(doc, "^XA", "openFormat", at, at + 3)).toBe("^XA\n^FO1,1^FDb^FS^XZ");
+  });
+
+  it("places the caret after the inserted closer under CRLF too", () => {
+    const doc = "^XA^FO1,1^FDa^FS" + CRLF + "^XA^FDb^FS^XZ";
+    const state = EditorState.create({ doc, extensions: [zpl(), EditorState.lineSeparator.of(CRLF)] });
+    const next = state.update(fixInsertion(state, "^XZ", "closeFormat", 0, 3)).state;
+    expect(next.doc.toString()).toBe("^XA^FO1,1^FDa^FS" + NL + "^XZ" + NL + "^XA^FDb^FS^XZ");
+    expect(next.doc.sliceString(next.selection.main.head - 3, next.selection.main.head)).toBe("^XZ");
+    const end = EditorState.create({ doc: "^XA^FO1,1^FDa^FS", extensions: [zpl(), EditorState.lineSeparator.of(CRLF)] });
+    expect(() => end.update(fixInsertion(end, "^XZ", "closeFormat", 0, 3))).not.toThrow();
+  });
+
+  it("still inserts when a byte payload ends in the same letters", () => {
+    const doc = "^XA^FO1,1^FDa^FS~DYE:X.TTF,B,T,5,,ab^XZ^XA^FDb^FS^XZ";
+    expect(fixed(doc, "^XZ", "closeFormat", 0, 3)).toContain("ab^XZ" + NL + "^XZ" + NL + "^XA^FDb");
+  });
+
+  it("inserts nothing when the command already sits at the spot", () => {
+    const doc = "^XA^FO1,1^FDa^FS\n^XZ\n^XA^FDb^FS^XZ";
+    expect(fixed(doc, "^XZ", "closeFormat", 0, 3)).toBe(doc);
+    const fs = "^XA^FO1,1^FDa^FS^XZ";
+    expect(fixed(fs, "^FS", "after", 9, 13)).toBe(fs);
+  });
+
+  it("finds the interrupting opener beyond the reach of the live tree", () => {
+    const filler = Array.from({ length: 4000 }, (_, i) => `^FXfiller ${i} ................^FS`).join(NL);
+    const doc = `^XA^FO1,1^FDa^FS${NL}${filler}${NL}^XA^FDb^FS^XZ`;
+    const out = fixed(doc, "^XZ", "closeFormat", 0, 3);
+    expect(out.endsWith(`^XZ${NL}^XA^FDb^FS^XZ`)).toBe(true);
+    expect(out.indexOf("^XZ")).toBeGreaterThan(doc.length - 40);
+  });
 });
 
 describe("zpl highlight style", () => {

src/lib/zplLanguage.ts

@@ -16,6 +16,7 @@ import {
 import type { EditorState, Transaction, TransactionSpec } from "@codemirror/state";
 import { applyPrefixRemap, PAYLOAD_CMDS, tokenize, type TokenizerChars } from "@zplab/core/lib/zplParser/helpers";
 import { commandBoundaryAt, prefixCharsAt, spellPrefix } from "@zplab/core/lib/zplCanonicalPrefixes";
+import type { FixPlace } from "./sourceDiagnostics";
 
 // A ~DY/~DG payload can be megabytes on one line; folding keeps the editor
 // responsive, and the read-only preview truncates at the same length.
@@ -306,11 +307,9 @@ export interface CommandOccurrence {
   to: number;
 }
 
-/** Command names touching [from, to] on the tree parsed so far: a range past the parse
- *  budget yields nothing now, and the parser's next step revisits it. */
-export function commandOccurrences(state: EditorState, from: number, to: number): CommandOccurrence[] {
+function namesIn(state: EditorState, tree: Tree, from: number, to: number): CommandOccurrence[] {
   const out: CommandOccurrence[] = [];
-  syntaxTree(state).iterate({
+  tree.iterate({
     from,
     to,
     enter: (n) => {
@@ -322,20 +321,23 @@ export function commandOccurrences(state: EditorState, from: number, to: number)
   return out;
 }
 
+/** The live tree may end before the partner command, so the whole document is parsed. */
+const wholeDocNames = (state: EditorState) => namesIn(state, treeUpTo(state, state.doc.length, WHOLE_DOC_PARSE_MS), 0, state.doc.length);
+
+const structuralAt = (state: EditorState, id: "^XA" | "^XZ") => wholeDocNames(state).filter((c) => c.id === id);
+
+/** Command names touching [from, to] on the tree parsed so far: a range past the parse
+ *  budget yields nothing now, and the parser's next step revisits it. */
+export function commandOccurrences(state: EditorState, from: number, to: number): CommandOccurrence[] {
+  return namesIn(state, syntaxTree(state), from, to);
+}
+
 /** Positional: the page-th ^XZ of the live document (the export emits one block per page),
  *  else the last ^XZ, else null; goes stale if the user removes earlier blocks mid-session.
  *  Read from the tree, so a ^CC remap still finds it. */
 export function formatCloseFor(state: EditorState, page: number): number | null {
-  const tree = treeUpTo(state, state.doc.length, WHOLE_DOC_PARSE_MS);
-  const closes: number[] = [];
-  tree.iterate({
-    enter: (n) => {
-      // Only the caret form closes a format; the core parser reports ~XZ as unknown.
-      if (!NAME_NODES.has(n.name) || readCommandName(state, n).id !== "^XZ") return undefined;
-      closes.push(n.from);
-      return false;
-    },
-  });
+  // Only the caret form closes a format; the core parser reports ~XZ as unknown.
+  const closes = structuralAt(state, "^XZ").map((c) => c.from);
   return closes[page] ?? closes[closes.length - 1] ?? null;
 }
 
@@ -362,12 +364,30 @@ export function placesCaret(tr: Transaction): boolean {
 /** The tree keeps only spelled names, so the head up to `pos` is replayed for the prefix in force. */
 const spellAt = (state: EditorState, text: string, pos: number): string => spellPrefix(text, prefixCharsAt(state.doc.sliceString(0, pos)));
 
-/** Transaction for a lint's repair: `command` in front of the first command at or after `at`,
- *  spelled with the prefix in force. Data runs up to that prefix, trailing whitespace included,
- *  so the lint's trimmed end would cut it short. */
-export function fixInsertion(state: EditorState, command: string, at: number): TransactionSpec {
+/** Transaction that inserts `command` at `place`, spelled with the prefix in force there, or an empty one when it already sits there.
+ *  For `after` the data runs up to the next prefix, trailing whitespace included, so the lint's trimmed end would cut it short. */
+export function fixInsertion(state: EditorState, command: string, place: FixPlace, from: number, to: number): TransactionSpec {
+  const at =
+    place === "after"
+      ? to
+      : place === "before"
+        ? from
+        : place === "closeFormat"
+          ? (structuralAt(state, "^XA").find((c) => c.from >= to)?.from ?? state.doc.length)
+          : (structuralAt(state, "^XZ").filter((c) => c.to <= from).at(-1)?.to ?? 0);
   const { pos, chars } = commandBoundaryAt(state.doc.toString(), at);
-  return { changes: { from: pos, insert: spellPrefix(command, chars) }, userEvent: LINTFIX_USER_EVENT };
+  const spelled = spellPrefix(command, chars);
+  // The diagnostic outlives the first click by the reparse window, so a second click must not stack a copy.
+  const before = state.doc.sliceString(0, pos).trimEnd().length;
+  const already = wholeDocNames(state).some((c) => c.id === command && (c.from === pos || c.to === before));
+  if (already) return { userEvent: LINTFIX_USER_EVENT };
+  if (place === "after") return { changes: { from: pos, insert: spelled }, userEvent: LINTFIX_USER_EVENT };
+  // The generator writes a format command on its own line.
+  const lead = pos > 0 && state.doc.lineAt(pos).from !== pos ? state.lineBreak : "";
+  const tail = pos < state.doc.length ? state.lineBreak : "";
+  // A line break is one document position whatever the separator's length.
+  const anchor = pos + (lead ? 1 : 0) + spelled.length;
+  return { changes: { from: pos, insert: `${lead}${spelled}${tail}` }, selection: { anchor }, scrollIntoView: true, userEvent: LINTFIX_USER_EVENT };
 }
 
 /** Where a catalog insert goes: the user's caret, or a page's block. */