@tikoci/centrs 0.1.3 → 0.1.6

package/src/explain/arg-tokens.ts

@@ -0,0 +1,151 @@
+/**
+ * B2 arg fill — claims argument names and their `=` on the residual.
+ *
+ * This is the second B2 fill of #264, added after the operator fill. It runs
+ * **after** the proof-only spans (`comment` + `variable-*`) and **before** the
+ * operator fill, so the fill order is structural: `spans` claims first, then
+ * `arg`, then `operator` sees only what neither wanted. That ordering is why the
+ * operator fill can abstain on `, / = -` outside `( )`, on bytes glued after
+ * an argument `=`, and on bytes glued into an argument name — those bytes
+ * belong to a later fill, not to a smarter operator scanner.
+ *
+ * The source is `src/explain/args.ts`'s `Argument` — `span` and `valueSpan`
+ * 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` 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.
+ *
+ * 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.
+ *
+ * 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";
+import { clipToResidual } from "./token-ranges.ts";
+
+export type ArgCandidate = ExplainArgumentToken;
+
+/**
+ * Argument name + `=` spans on the residual.
+ *
+ * `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 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,
+	residual: readonly { start: number; end: number }[],
+	candidates: readonly ArgCandidate[],
+): ExplainToken[] {
+	const len = analyzed.length;
+	if (len === 0 || residual.length === 0 || candidates.length === 0) return [];
+
+	const out: ExplainToken[] = [];
+
+	for (const candidate of candidates) {
+		if (candidate.kind !== "attribute") continue;
+		if (candidate.valueSpan === undefined) continue;
+		if (candidate.name === undefined) continue;
+		const nameStart = candidate.span.start;
+		const eqEnd = candidate.valueSpan.start;
+		const eqStart = eqEnd - 1;
+		const nameEnd = eqStart;
+		// Defensive: token shape must give non-empty name and single-byte `=`.
+		if (
+			!Number.isInteger(nameStart) ||
+			!Number.isInteger(nameEnd) ||
+			!Number.isInteger(eqStart) ||
+			!Number.isInteger(eqEnd)
+		)
+			continue;
+		if (nameStart < 0 || eqEnd > len) continue;
+		// Non-empty name. This is also what rejects `valueSpan.start === 0`, where
+		// `eqStart` would be -1: `nameEnd` is -1 too, so any `nameStart >= 0` trips
+		// it. `analyzed[-1]` on the next line would be `undefined` and continue
+		// anyway, so the order is safe either way — but the name check is the one
+		// that carries the intent.
+		if (nameStart >= nameEnd) continue;
+		// The whole token's `=` byte must be `=` in the analyzed text — a cheap
+		// shape check that catches a caller that passed un-rebased or misaligned
+		// spans. Not a scan for `=`; the position is derived from `valueSpan`.
+		if (analyzed[eqStart] !== "=") continue;
+		// Also ensure the candidate lies fully inside the analyzed length.
+		if (candidate.span.start < 0 || candidate.span.end > len) continue;
+		if (candidate.valueSpan.start < 0 || candidate.valueSpan.end > len)
+			continue;
+
+		// 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.
+		for (const r of clipToResidual(nameStart, eqStart, residual)) {
+			out.push({
+				start: r.start,
+				end: r.end,
+				class: "arg" as const,
+				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);
+	return out;
+}