@tikoci/centrs 0.1.4 → 0.1.7

package/src/explain/arg-tokens.ts

@@ -13,25 +13,50 @@
  * already rebased into document analyzed-byte space by `src/explain.ts`. The
  * name run is `[span.start, valueSpan.start - 1)` and the `=` is the single
  * byte at `valueSpan.start - 1`; the value itself is `valueSpan` and is left
- * for the next fill (see #293). A `positional` has no `name`/`valueSpan` and a
- * `query` is a `?` word whose interior `args.ts` explicitly refuses to split
- * (see `Argument.value`'s doc comment), so both are ignored — the `=` is
- * derived from the token shape, never by scanning for the byte.
+ * for the next fill (see #293). A `positional` has no `name` and a `query` is a
+ * `?` word whose interior `args.ts` explicitly refuses to split (see
+ * `Argument.value`'s doc comment), so both are ignored on `kind` before any
+ * span is read — the `=` is derived from the token shape, never by scanning for
+ * the byte.
  *
  * `Argument.value` is not `Argument.text` and is never read: `value` is absent
  * whenever the source spells a substitution or an escape this phase does not
  * decode. This slice claims `span`/`valueSpan` *positions* only.
  *
- * A statement whose bytes were normalized is not addressable: `explain.ts`
- * already refuses those (`its text was normalized`), and this fill inherits the
- * refusal — it only sees tokens from `read === true` statements, which are
- * exactly the addressable ones.
+ * The candidates are the SKIP-TOLERANT reading (#316), not `statement.arguments`:
+ * a token whose value only the device knows still has a `name=` run that is
+ * plainly an argument name, and abstaining on the whole statement because of its
+ * value left 48.2% of the corpus's argument lists unpainted. `value` was never
+ * read here (see below), so nothing about this fill's claim changes — only how
+ * many tokens reach it.
  *
- * Vocabulary is provisional until #264 B5: one `arg` class for both the name
- * bytes and the `=` separator (design decision 2 of #293 — emit first, name
- * later; `highlight`'s `syntax-meta` is a residual merge and never a source).
- * If B5 splits the `=` into its own class, the byte coverage does not move,
- * only the retag.
+ * Two things still reach it as nothing at all. A statement whose bytes were
+ * normalized is not addressable: `explain.ts` already refuses those (`its text
+ * was normalized`), and no token is rebased. And a WITHDRAWN reading — a
+ * second command-shaped run (#311) or a gate-parity disagreement — contributes
+ * nothing either: centrs cannot say which bytes are that command's arguments,
+ * and painting `name=` runs inside it would be that same claim in lexical
+ * clothing.
+ *
+ * **B5 split the `=` from the name** (#264). #293 emitted one `arg` class for
+ * both — emit first, name later — and two measurements then priced that merge:
+ * the `=` was the ENTIRE `arg` disagreement against the device, which reads a
+ * separator as `syntax-meta`, and it is not recoverable from the envelope,
+ * because a large minority of the runs this fill paints belong to a statement
+ * whose strict `arguments` reading refused — so there is no published
+ * `ExplainArgumentToken.valueSpan` to subtract one from. The spellings that
+ * dominate that share are the block binders (`do=`, `else=`, `in=`), which no
+ * strict reading ever publishes. The name run stays `arg`; the single `=` byte
+ * is `arg-sep`. Byte coverage does not move — this is a retag, and both runs
+ * keep `e11`, because the evidence is how `args.ts` located the bytes, not what
+ * they are called.
+ *
+ * The figures are deliberately not restated here: `bun run explain:arg-reach`
+ * re-derives the envelope gap and the leading spellings, and the agreement
+ * report re-derives the device cell. Both move when the corpus or the capture
+ * slice moves, and a count pasted into this header would not.
+ * `commands/explain/README.md` -> *The vocabulary, and what earns a class*
+ * carries them next to the generated blocks that keep them honest.
  */
 
 import type { ExplainArgumentToken, ExplainToken } from "../explain.ts";
@@ -44,10 +69,10 @@ export type ArgCandidate = ExplainArgumentToken;
  *
  * `analyzed` is the ASCII-normalized document text (only used for length
  * checks); `residual` is the gap set left by earlier fills (sorted, no
- * overlaps); `candidates` are the already-rebased `Argument` tokens from
- * `read === true` statements. Every emitted span's bytes are fully inside
- * `residual`, sorted by `start`, non-overlapping, and carry
- * `class: "arg"` + `ev: "e11"`.
+ * overlaps); `candidates` are the already-rebased `Argument` tokens of the
+ * statements `explain.ts` decided may be painted. Every emitted span's bytes are fully inside
+ * `residual`, sorted by `start`, non-overlapping, and carry `ev: "e11"` with
+ * `class: "arg"` on the name run and `class: "arg-sep"` on the `=`.
  */
 export function argSpans(
 	analyzed: string,
@@ -91,15 +116,19 @@ export function argSpans(
 		if (candidate.valueSpan.start < 0 || candidate.valueSpan.end > len)
 			continue;
 
-		// The name run and the `=` are contiguous (`nameEnd === eqStart`), so
-		// clip them as ONE range per candidate. That yields the maximal `[name=]`
-		// run for free — split only where the residual itself has a hole — and
-		// makes cross-candidate fusion structurally impossible rather than merely
-		// unreachable: coalescing adjacent runs globally would merge two distinct
+		// Two clips, not one, and in that order: the name run `[nameStart, eqStart)`
+		// then the single `=` byte `[eqStart, eqEnd)`. Each is offered to the
+		// residual on its own, so a `variable-*` span claiming only the `=` still
+		// leaves the name run behind and vice versa — the residual hole does the
+		// splitting, exactly as when the two were clipped together.
+		//
+		// Splitting here is also what makes cross-candidate fusion structurally
+		// impossible rather than merely unreachable. Two `arg` runs can never be
+		// adjacent, because every candidate puts an `arg-sep` byte after its name;
+		// coalescing adjacent runs globally would otherwise merge two distinct
 		// attributes into one token if `lexArguments` ever stopped guaranteeing a
-		// separator between them. A `variable-*` span claiming only the `=` still
-		// leaves the name run behind, because the residual hole does the splitting.
-		for (const r of clipToResidual(nameStart, eqEnd, residual)) {
+		// separator between them.
+		for (const r of clipToResidual(nameStart, eqStart, residual)) {
 			out.push({
 				start: r.start,
 				end: r.end,
@@ -107,6 +136,14 @@ export function argSpans(
 				ev: "e11",
 			});
 		}
+		for (const r of clipToResidual(eqStart, eqEnd, residual)) {
+			out.push({
+				start: r.start,
+				end: r.end,
+				class: "arg-sep" as const,
+				ev: "e11",
+			});
+		}
 	}
 
 	out.sort((a, b) => a.start - b.start || a.end - b.end);