@styx-api/core 0.7.0 → 0.8.0

package/src/frontend/argtype/lower.ts

@@ -16,13 +16,28 @@ import { nodeRef } from "../../ir/meta.js";
 import type { AppMeta, NodeMeta, Output, OutputToken, StreamOutput } from "../../ir/meta.js";
 import type { Documentation } from "../../ir/types.js";
 import type { Expr, Sequence } from "../../ir/node.js";
-import type { AstAlias, AstDocument, AstNode, AstOutput } from "./ast.js";
+import type { AstAlias, AstDocument, AstNode, AstOutput, SourceSpan } from "./ast.js";
+
+/** A lowering diagnostic, optionally located at a source position. The location
+ * comes from the offending AST node's span, so an error like a misplaced
+ * `.join()` points at the node it was chained onto (parser/lexer diagnostics
+ * already carry positions; this extends the same to the lowering stage). */
+export interface LowerDiagnostic {
+  message: string;
+  line?: number;
+  column?: number;
+}
 
 export interface LowerResult {
   meta?: AppMeta;
   expr: Sequence;
-  errors: string[];
-  warnings: string[];
+  errors: LowerDiagnostic[];
+  warnings: LowerDiagnostic[];
+}
+
+/** Spread a node's span into a diagnostic (no-op when the node has no span). */
+function at(span: SourceSpan | undefined): { line?: number; column?: number } {
+  return span ? { line: span.line, column: span.column } : {};
 }
 
 /** Build IR `Documentation` from an AST node's already-split title/description. */
@@ -35,21 +50,28 @@ function docFrom(node: { title?: string; description?: string }): Documentation
 }
 
 class Lowerer {
-  readonly errors: string[] = [];
-  readonly warnings: string[] = [];
-  /** Extensions whose annotations the document actually uses, collected during
-   * lowering so `lowerDocument` can flag any used-but-undeclared in frontmatter. */
-  readonly usedExtensions = new Set<string>();
+  readonly errors: LowerDiagnostic[] = [];
+  readonly warnings: LowerDiagnostic[] = [];
   private aliases = new Map<string, AstNode>();
 
   constructor(aliases: AstAlias[]) {
     for (const a of aliases) {
       if (this.aliases.has(a.name))
-        this.warnings.push(`Duplicate alias '${a.name}'; last definition wins`);
+        this.warn(`Duplicate alias '${a.name}'; last definition wins`, a.expr);
       this.aliases.set(a.name, a.expr);
     }
   }
 
+  /** Record an error, located at `node`'s span when one is available. */
+  private err(message: string, node?: AstNode): void {
+    this.errors.push({ message, ...at(node?.span) });
+  }
+
+  /** Record a warning, located at `node`'s span when one is available. */
+  private warn(message: string, node?: AstNode): void {
+    this.warnings.push({ message, ...at(node?.span) });
+  }
+
   lower(doc: AstDocument): LowerResult {
     // Each output attaches to its nearest enclosing sequence scope (via the
     // `sink`), preserving nesting so a per-repeat / per-subcommand output keeps
@@ -90,47 +112,50 @@ class Lowerer {
 
     // `.join` collapses a node's subtree into one argv element. It is carried on
     // sequence/repeat in the IR directly, and on `opt` by pushing it onto the
-    // wrapped content (`lowerComb`). On other nodes it has no meaning, so warn.
+    // wrapped content (`lowerComb`). On any other node it would be silently
+    // dropped, changing command-line correctness with no failure signal (a tool
+    // gets `["A","B"]` instead of `"AB"`), so a misplaced modifier is a hard
+    // error, not a warning. Refs are already resolved above, so by here the
+    // node's concrete kind is known and these checks are accurate.
     const joinable =
       node.kind === "comb" &&
       (node.op === "seq" || node.op === "set" || node.op === "rep" || node.op === "opt");
     if (node.join !== undefined && !joinable) {
-      this.warnings.push("`.join()` is only supported on seq/set/rep/opt; ignored here");
+      this.err("`.join()` is only supported on seq/set/rep/opt", node);
     }
 
     // A type-specific modifier that lands on an incompatible node is silently
-    // dropped downstream (only the matching lower* case reads it), so warn -
-    // same contract as the `.join()` check. Refs are already resolved above, so
-    // by here the node's concrete kind is known and these checks are accurate.
+    // dropped downstream (only the matching lower* case reads it), which quietly
+    // discards a value/arity constraint - so, like `.join()`, it is a hard error.
     const isNumericTerminal =
       node.kind === "terminal" && (node.terminal === "int" || node.terminal === "float");
     const isRep = node.kind === "comb" && node.op === "rep";
     const isPath = node.kind === "terminal" && node.terminal === "path";
     if ((node.min !== undefined || node.max !== undefined) && !isNumericTerminal) {
-      this.warnings.push(
-        "`.min()`/`.max()` is only supported on int/float terminals; ignored here",
-      );
+      this.err("`.min()`/`.max()` is only supported on int/float terminals", node);
     }
     if ((node.countMin !== undefined || node.countMax !== undefined) && !isRep) {
-      this.warnings.push(
-        "`.count()`/`.countMin()`/`.countMax()` is only supported on rep; ignored here",
-      );
+      this.err("`.count()`/`.countMin()`/`.countMax()` is only supported on rep", node);
     }
     if ((node.mutable || node.resolveParent) && !isPath) {
-      this.warnings.push("`.mutable()`/`.resolveParent()` is only supported on path; ignored here");
+      this.err("`.mutable()`/`.resolveParent()` is only supported on path", node);
     }
     if (node.mediaTypes?.length && !isPath) {
-      this.warnings.push("`.mediaType()` is only supported on path; ignored here");
+      this.err("`.mediaType()` is only supported on path", node);
     }
 
-    // Record which extensions' annotations the author reached for, so a document
-    // that uses one without declaring it in frontmatter can be flagged. Only count
-    // an annotation that actually applies here: a misapplied `path`-only modifier
-    // is already warned about and dropped just above, so recording it would make
-    // declare-before-use contradict that ("ignored" yet "declare it").
-    if (node.outputs?.length) this.usedExtensions.add("outputs");
-    if (node.mediaTypes?.length && isPath) this.usedExtensions.add("mediatypes");
-    if ((node.mutable || node.resolveParent) && isPath) this.usedExtensions.add("paths");
+    // `.default()` / `= value` is meaningful on a terminal, and also on the
+    // combinators that model a defaultable value: `opt` (its default when
+    // omitted), `alt` (a union's default variant), `rep` (a default list). Only a
+    // `seq`/`set` struct has no scalar to default - a default there is nonsensical
+    // and, left in place, would flow to the node's `defaultValue` (which backends
+    // read) as a bogus value, so drop it and warn. It never changes which argv is
+    // valid, so this is a warning, not an error.
+    const isStruct = node.kind === "comb" && (node.op === "seq" || node.op === "set");
+    if (node.default !== undefined && isStruct) {
+      this.warn("`= value` / `.default()` is not supported on a seq/set struct; ignored", node);
+      node.default = undefined;
+    }
 
     // A `.output()` on a non-sequence node attaches to the enclosing sequence
     // scope (`sink`); seq/set own their outputs (handled in `lowerComb`).
@@ -150,7 +175,7 @@ class Lowerer {
       case "comb":
         return this.lowerComb(node, expanding, name, sink);
       default: {
-        this.errors.push(`Unknown AST node kind '${(node as AstNode).kind}'`);
+        this.err(`Unknown AST node kind '${(node as AstNode).kind}'`, node);
         return seq();
       }
     }
@@ -165,17 +190,20 @@ class Lowerer {
     const target = node.refName!;
     const aliasExpr = this.aliases.get(target);
     if (!aliasExpr) {
-      this.errors.push(`Unknown alias '${target}'`);
+      this.err(`Unknown alias '${target}'`, node);
       return seq();
     }
     if (expanding.has(target)) {
-      this.errors.push(`Recursive alias '${target}' is not allowed`);
+      this.err(`Recursive alias '${target}' is not allowed`, node);
       return seq();
     }
     const clone = structuredClone(aliasExpr);
     // Overlay use-site decorations onto the inlined alias. The use site wins for
     // each scalar decoration it specifies; outputs and media types accumulate.
     // Without this, `size: Dimension.join(",")` would silently drop the join.
+    // Point any diagnostic about the resolved node at the use site (a misplaced
+    // modifier there, not in the alias definition, is what the author must fix).
+    clone.span = node.span ?? clone.span;
     clone.name = node.name ?? clone.name;
     clone.title = node.title ?? clone.title;
     clone.description = node.description ?? clone.description;
@@ -200,7 +228,7 @@ class Lowerer {
     switch (node.terminal) {
       case "int": {
         const e = int();
-        this.checkBounds(node.min, node.max, "value", "min", "max");
+        this.checkBounds(node.min, node.max, "value", "min", "max", node);
         if (node.min !== undefined) e.attrs.minValue = node.min;
         if (node.max !== undefined) e.attrs.maxValue = node.max;
         this.applyMeta(e, node);
@@ -208,15 +236,15 @@ class Lowerer {
       }
       case "float": {
         const e = float();
-        this.checkBounds(node.min, node.max, "value", "min", "max");
+        this.checkBounds(node.min, node.max, "value", "min", "max", node);
         if (node.min !== undefined) e.attrs.minValue = node.min;
         if (node.max !== undefined) e.attrs.maxValue = node.max;
         this.applyMeta(e, node);
         return e;
       }
       case "str": {
-        // A `str.mediaType(...)` is warned about generically in `lowerNode`
-        // (media types are a `path`-only annotation), so nothing to do here.
+        // A `str.mediaType(...)` is rejected generically in `lowerNode` (media
+        // types are a `path`-only annotation), so nothing to do here.
         const e = str();
         this.applyMeta(e, node);
         return e;
@@ -230,7 +258,7 @@ class Lowerer {
         return e;
       }
       default: {
-        this.errors.push(`Unknown terminal '${String(node.terminal)}'`);
+        this.err(`Unknown terminal '${String(node.terminal)}'`, node);
         return str();
       }
     }
@@ -255,7 +283,7 @@ class Lowerer {
         const selfOutputs: Output[] = [];
         for (const o of node.outputs ?? []) selfOutputs.push(this.toOutput(o, name));
         const lowered = lowerChildren(selfOutputs);
-        this.dedupeSiblingNames(lowered);
+        this.dedupeSiblingNames(lowered, node);
         const e = seq(...lowered);
         if (node.join !== undefined) e.attrs.join = node.join;
         this.applyMeta(e, node);
@@ -271,7 +299,7 @@ class Lowerer {
         // same way. `any` is exempt: it emits branch 0 and its branches are
         // deliberately binding-compatible (same names by design).
         const arms = lowerChildren(sink);
-        this.dedupeSiblingNames(arms);
+        this.dedupeSiblingNames(arms, node);
         const e = alt(...arms);
         this.applyMeta(e, node);
         return e;
@@ -283,7 +311,7 @@ class Lowerer {
         // is lossless and expected, not a degradation worth warning about.
         // (Only a parser/validator would need to accept the other spellings.)
         if (children.length === 0) {
-          this.errors.push("`any(...)` requires at least one branch");
+          this.err("`any(...)` requires at least one branch", node);
           return seq();
         }
         const e = this.lowerNode(children[0]!, expanding, name, sink);
@@ -314,14 +342,21 @@ class Lowerer {
         const inner = this.wrapChildren(children, expanding, name, sink);
         const e = rep(inner);
         if (node.join !== undefined) e.attrs.join = node.join;
-        this.checkBounds(node.countMin, node.countMax, "repetition count", "countMin", "countMax");
+        this.checkBounds(
+          node.countMin,
+          node.countMax,
+          "repetition count",
+          "countMin",
+          "countMax",
+          node,
+        );
         if (node.countMin !== undefined) e.attrs.countMin = node.countMin;
         if (node.countMax !== undefined) e.attrs.countMax = node.countMax;
         this.applyMeta(e, node);
         return e;
       }
       default: {
-        this.errors.push(`Unknown combinator '${String(node.op)}'`);
+        this.err(`Unknown combinator '${String(node.op)}'`, node);
         return seq();
       }
     }
@@ -335,9 +370,10 @@ class Lowerer {
     what: string,
     minLabel: string,
     maxLabel: string,
+    node?: AstNode,
   ): void {
     if (min !== undefined && max !== undefined && min > max) {
-      this.warnings.push(`Inverted ${what} bounds: ${minLabel} (${min}) > ${maxLabel} (${max})`);
+      this.warn(`Inverted ${what} bounds: ${minLabel} (${min}) > ${maxLabel} (${max})`, node);
     }
   }
 
@@ -353,7 +389,7 @@ class Lowerer {
    * explicit labels; it does not detect collisions between solver-derived names
    * of otherwise-unnamed children, which the solver also does not guard.)
    */
-  private dedupeSiblingNames(children: Expr[]): void {
+  private dedupeSiblingNames(children: Expr[], parent?: AstNode): void {
     const used = new Set<string>();
     for (const child of children) {
       const nm = child.meta?.name;
@@ -367,7 +403,9 @@ class Lowerer {
       const renamed = `${nm}_${n}`;
       used.add(renamed);
       child.meta = { ...child.meta, name: renamed };
-      this.warnings.push(`Duplicate sibling name '${nm}'; renamed one occurrence to '${renamed}'`);
+      // Locate at the enclosing seq/set/alt node (the collision is between its
+      // direct children, which are lowered IR nodes without their own AST span).
+      this.warn(`Duplicate sibling name '${nm}'; renamed one occurrence to '${renamed}'`, parent);
     }
   }
 
@@ -405,16 +443,13 @@ class Lowerer {
       }
       const targetName = t.name ?? selfName;
       if (!targetName) {
-        this.warnings.push(
-          "Output self-reference '{}' has no named node to resolve to; emitting empty",
-        );
+        this.warn("Output self-reference '{}' has no named node to resolve to; emitting empty");
         tokens.push({ kind: "literal", value: "" });
         continue;
       }
       if (t.stripPrefix?.length)
-        this.warnings.push("Output ref op 'strip_prefix' is not supported by the IR; ignored");
-      if (t.basename)
-        this.warnings.push("Output ref op 'basename' is not supported by the IR; ignored");
+        this.warn("Output ref op 'strip_prefix' is not supported by the IR; ignored");
+      if (t.basename) this.warn("Output ref op 'basename' is not supported by the IR; ignored");
       tokens.push({
         kind: "ref",
         target: nodeRef(targetName),
@@ -423,7 +458,7 @@ class Lowerer {
       });
     }
     if (o.fallback !== undefined) {
-      this.warnings.push("Output-level '.or(...)' fallback is not supported by the IR; ignored");
+      this.warn("Output-level '.or(...)' fallback is not supported by the IR; ignored");
     }
     const doc = docFrom(o);
     return { ...(o.name && { name: o.name }), ...(doc && { doc }), tokens };
@@ -462,6 +497,30 @@ export function buildAppMeta(
   const urls = strList(fm.urls);
   const references = strList(fm.references);
 
+  // Validate the shape of known keys. A present-but-wrong-shape value is almost
+  // always an authoring mistake, and silently coercing it (dropping a scalar
+  // author, ignoring a malformed container) hides that - so warn rather than
+  // drop in silence. An empty key (`authors:` with no value, parsed as null) is
+  // left alone; only a non-null non-list scalar is flagged.
+  const checkList = (key: string, v: unknown): void => {
+    if (v !== undefined && v !== null && !Array.isArray(v)) {
+      warnings.push(`Frontmatter '${key}' should be a list; got a scalar - ignored`);
+    }
+  };
+  checkList("authors", fm.authors);
+  checkList("urls", fm.urls);
+  checkList("references", fm.references);
+  if (fm.version !== undefined && fm.version !== null && version === undefined) {
+    warnings.push(`Frontmatter 'version' should be a string or number; ignored`);
+  }
+  if (fm.container !== undefined && fm.container !== null) {
+    if (!isRecord(fm.container)) {
+      warnings.push(`Frontmatter 'container' should be a mapping with an 'image'; ignored`);
+    } else if (!asStr(fm.container.image)) {
+      warnings.push(`Frontmatter 'container' is missing an 'image'; ignored`);
+    }
+  }
+
   const doc: Documentation = {
     ...rootTitleDesc,
     ...(authors.length > 0 && { authors }),
@@ -531,31 +590,12 @@ export function lowerDocument(doc: AstDocument): LowerResult {
     doc.rootName,
   );
 
-  // Declare-before-use: when a document has frontmatter, an extension whose
-  // annotations it uses should be listed in `extensions:`. We only check this
-  // when frontmatter is present - a frontmatter-less snippet hasn't opted into
-  // the declaration discipline, so flagging every quick `.output()` would be
-  // noise. The warning is advisory (extensions are ignorable by contract).
-  const extWarnings: string[] = [];
-  if (doc.frontmatter) {
-    const declared = new Set(
-      Array.isArray(doc.frontmatter.extensions)
-        ? doc.frontmatter.extensions.filter((e): e is string => typeof e === "string")
-        : [],
-    );
-    for (const used of lowerer.usedExtensions) {
-      if (!declared.has(used)) {
-        extWarnings.push(
-          `Uses the '${used}' extension but does not declare it in frontmatter (add it to 'extensions:')`,
-        );
-      }
-    }
-  }
-
   return {
     ...(meta && { meta }),
     expr: result.expr,
     errors: result.errors,
-    warnings: [...result.warnings, ...warnings, ...extWarnings],
+    // Frontmatter warnings are location-less (the reader blanks those lines and
+    // does not track per-key positions), so they carry no line/column.
+    warnings: [...result.warnings, ...warnings.map((message) => ({ message }))],
   };
 }

package/src/frontend/argtype/parser-frontend.ts

@@ -38,8 +38,8 @@ export class ArgtypeParser implements Frontend {
     }
 
     const lowered = lowerDocument(doc);
-    warnings.push(...lowered.warnings.map((message) => ({ message })));
-    errors.push(...lowered.errors.map((message) => ({ message })));
+    warnings.push(...lowered.warnings.map((d) => ({ message: d.message, ...toLocation(d) })));
+    errors.push(...lowered.errors.map((d) => ({ message: d.message, ...toLocation(d) })));
 
     return {
       ...(lowered.meta && { meta: lowered.meta }),

package/src/frontend/argtype/parser.ts

@@ -57,6 +57,45 @@ const KNOWN_METHODS = new Set([
   "resolveParent",
 ]);
 
+/** Levenshtein edit distance between two strings. */
+function editDistance(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  let prev = Array.from({ length: n + 1 }, (_, j) => j);
+  for (let i = 1; i <= m; i++) {
+    const cur = [i];
+    for (let j = 1; j <= n; j++) {
+      cur[j] = Math.min(
+        prev[j]! + 1,
+        cur[j - 1]! + 1,
+        prev[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+    prev = cur;
+  }
+  return prev[n]!;
+}
+
+/** The closest candidate to `name` within a small edit distance, for a "did you
+ * mean?" hint on an unknown method. Returns undefined when nothing is close
+ * enough, so a deliberate unknown-extension method gets no spurious suggestion.
+ * A typo (`reqires`, `mediaTpe`) lands within distance 2 of a real method; an
+ * unrelated extension method (`conflicts`) does not. The `bestDist < name.length`
+ * clause additionally stops a very short unknown name from matching a longer
+ * method by pure insertion (a 1-char `.n()` is not "did you mean `.min()`"). */
+function suggestMethod(name: string, candidates: Iterable<string>): string | undefined {
+  let best: string | undefined;
+  let bestDist = Infinity;
+  for (const c of candidates) {
+    const d = editDistance(name, c);
+    if (d < bestDist) {
+      bestDist = d;
+      best = c;
+    }
+  }
+  return best !== undefined && bestDist <= 2 && bestDist < name.length ? best : undefined;
+}
+
 class Parser {
   private tokens: Token[];
   private pos = 0;
@@ -215,67 +254,61 @@ class Parser {
       this.next();
       alts.push(this.parseChain());
     }
-    return { kind: "comb", op: "alt", children: alts };
+    // The synthesized alt has no token of its own; point diagnostics at its first
+    // arm (e.g. a misplaced `.join()` on `(a | b).join()`).
+    return { kind: "comb", op: "alt", children: alts, ...(first.span && { span: first.span }) };
   }
 
   private parseChain(): AstNode {
     const node = this.parsePrimary();
     // Method chain.
-    let chained = false;
     while (this.at("dot")) {
       this.next();
       this.applyMethod(node);
-      chained = true;
     }
-    // `= value` default sugar. The spec restricts it to a bare terminal: once a
-    // chain has started, `.default(...)` must be used instead.
+    // `= value` is pure sugar for `.default(value)`, with no positional
+    // restriction: it binds after a method chain too (`float.min(0) = 0.5`),
+    // since the meaning is unambiguous and the terminal-only rule was a footgun.
     if (this.at("eq")) {
-      const eqTok = this.next();
-      const value = this.parseValue();
-      if (node.kind === "terminal" && !chained) {
-        node.default = value;
-      } else {
-        this.error(
-          "`= value` default is only allowed on a bare terminal; use `.default(...)` after a method chain",
-          eqTok,
-        );
-      }
+      this.next(); // '='
+      node.default = this.parseValue();
     }
     return node;
   }
 
   private parsePrimary(): AstNode {
     const tok = this.peek();
+    const span = { line: tok.line, column: tok.column };
 
     if (tok.kind === "string") {
       this.next();
-      return { kind: "literal", value: tok.value };
+      return { kind: "literal", value: tok.value, span };
     }
 
     if (tok.kind === "lparen") {
       // Anonymous sequence group.
       const children = this.parseParenList();
-      return { kind: "comb", op: "seq", children };
+      return { kind: "comb", op: "seq", children, span };
     }
 
     if (tok.kind === "ident") {
       if (COMBINATORS.has(tok.value as Combinator) && this.peek(1).kind === "lparen") {
         this.next();
         const children = this.parseParenList();
-        return { kind: "comb", op: tok.value as Combinator, children };
+        return { kind: "comb", op: tok.value as Combinator, children, span };
       }
       if (TERMINALS.has(tok.value as Terminal)) {
         this.next();
-        return { kind: "terminal", terminal: tok.value as Terminal };
+        return { kind: "terminal", terminal: tok.value as Terminal, span };
       }
       // Otherwise an alias reference.
       this.next();
-      return { kind: "ref", refName: tok.value };
+      return { kind: "ref", refName: tok.value, span };
     }
 
     this.error(`Unexpected token '${tok.value || tok.kind}' in expression`, tok);
     this.next();
-    return { kind: "literal", value: "" };
+    return { kind: "literal", value: "", span };
   }
 
   /** Parse `( elem, elem, ... )` with optional leading docs and trailing comma. */
@@ -308,9 +341,17 @@ class Parser {
       // An extension method we don't implement (e.g. the draft `constraints`
       // extension's `.requires()`/`.conflicts()`). The spec requires unknown
       // extension annotations to be ignorable, so skip the argument list
-      // (whatever its shape) and continue rather than failing the parse.
+      // (whatever its shape) and continue rather than failing the parse. A
+      // near-miss to a known method is almost certainly a typo, though, so add a
+      // "did you mean?" hint (the warning still just ignores it, preserving the
+      // ignorable contract for genuine extension methods).
       this.skipBalancedArgs();
-      this.warn(`Ignoring unsupported method '.${method}()'`, nameTok);
+      const hint = suggestMethod(method, [...KNOWN_METHODS, "output"]);
+      this.warn(
+        `Ignoring unsupported method '.${method}()'` +
+          (hint ? ` (did you mean '.${hint}()'?)` : ""),
+        nameTok,
+      );
       return;
     }
 
@@ -447,7 +488,12 @@ class Parser {
         }
       } else {
         this.skipBalancedArgs();
-        this.warn(`Ignoring unsupported output-template method '.${m.value}()'`, m);
+        const hint = suggestMethod(m.value, CHAIN);
+        this.warn(
+          `Ignoring unsupported output-template method '.${m.value}()'` +
+            (hint ? ` (did you mean '.${hint}()'?)` : ""),
+          m,
+        );
       }
     }
 

package/src/frontend/boutiques/destruct-template.ts

@@ -20,29 +20,36 @@ export function destructTemplate<T>(template: string, lookup: Record<string, T>)
       continue;
     }
 
-    let didSplit = false;
-
+    // Pick the leftmost match; on a tie in position, the longest alias wins
+    // (maximal munch), so a value-key that is a prefix of another (e.g. `foo`
+    // vs `foobar`) does not shadow it by mere iteration order.
+    let best: { idx: number; alias: string; replacement: T } | null = null;
     for (const [alias, replacement] of Object.entries(lookup)) {
+      if (alias.length === 0) continue;
       const idx = x.indexOf(alias);
-      if (idx !== -1) {
-        const left = x.slice(0, idx);
-        const right = x.slice(idx + alias.length);
-
-        if (right.length > 0) {
-          stack.unshift(right);
-        }
-        stack.unshift(replacement);
-        if (left.length > 0) {
-          stack.unshift(left);
-        }
-
-        didSplit = true;
-        break;
+      if (idx === -1) continue;
+      if (
+        best === null ||
+        idx < best.idx ||
+        (idx === best.idx && alias.length > best.alias.length)
+      ) {
+        best = { idx, alias, replacement };
       }
     }
 
-    if (!didSplit) {
+    if (best === null) {
       destructed.push(x);
+      continue;
+    }
+
+    const left = x.slice(0, best.idx);
+    const right = x.slice(best.idx + best.alias.length);
+    if (right.length > 0) {
+      stack.unshift(right);
+    }
+    stack.unshift(best.replacement);
+    if (left.length > 0) {
+      stack.unshift(left);
     }
   }