pi-supernova 0.5.0 → 0.7.0

package/src/context/surface.js

@@ -8,14 +8,20 @@ function scanPython(lines) {
     const line = lines[i];
     const match = /^([ \t]*)(def|class|async def)\s+([a-zA-Z0-9_]+)(\(.*?\))?:?/.exec(line);
 
-    if (!match) continue;
-    items.push({
-      kind: match[2].includes("def") ? "function" : "class",
-      name: match[3],
-      signature: match[0].trim(),
-      line: i + 1,
-      depth: Math.floor(match[1].length / 4),
-    });
+    if (match) {
+      items.push({
+        kind: match[2].includes("def") ? "function" : "class",
+        name: match[3],
+        signature: match[0].trim(),
+        line: i + 1,
+        depth: Math.floor(match[1].length / 4),
+      });
+      continue;
+    }
+
+    const constant = /^([ \t]*)([A-Z][A-Z0-9_]*)\s*(?::[^=\n]+)?=/.exec(line);
+
+    if (constant && constant[1].length === 0) items.push({ kind: "constant", name: constant[2], signature: constant[0].replace(/=\s*$/, "=").trim(), line: i + 1, depth: 0 });
   }
 
   return items;
@@ -110,15 +116,24 @@ function declarationItem(line, rawLine, lineNumber) {
   return null;
 }
 
+function skipJsNoise(line) {
+  return !line || line.startsWith("//") || line.startsWith("/*") || line.startsWith("*");
+}
+
+function jsItemAt(lines, i) {
+  const line = lines[i].trim();
+
+  if (skipJsNoise(line)) return null;
+  const indent = lines[i].length - lines[i].trimStart().length;
+
+  return declarationItem(line, lines[i], i + 1) || (indent > 0 && indent <= 8 ? methodItem(line, i + 1, Math.max(1, Math.floor(indent / 2))) : null);
+}
+
 function scanJavaScript(lines) {
   const items = [];
 
   for (let i = 0; i < lines.length; i++) {
-    const line = lines[i].trim();
-
-    if (!line || line.startsWith("//") || line.startsWith("/*") || line.startsWith("*")) continue;
-    const indent = lines[i].length - lines[i].trimStart().length;
-    const item = declarationItem(line, lines[i], i + 1) || (indent > 0 && indent <= 8 ? methodItem(line, i + 1, Math.max(1, Math.floor(indent / 2))) : null);
+    const item = jsItemAt(lines, i);
 
     if (item) items.push(item);
   }
@@ -141,7 +156,7 @@ const SCANNERS = {
 export function extractStructuralSurface(code, extension = "js") {
   if (!isString(code) || !code.trim()) return { items: [], lineCount: 0 };
   const lines = code.split("\n");
-  const ext = extension.replace(/^\./, "").toLowerCase();
+  const ext = String(extension ?? "").replace(/^\./, "").toLowerCase();
   const scanner = SCANNERS[ext] || SCANNERS.js;
   const items = scanner(lines);
 

package/src/contract/bash.js

@@ -0,0 +1,31 @@
+import { isString, isObject } from "../shared/decode.js";
+
+const ARGV_ERROR = "bash argv requires a command string and an array of string args";
+
+function quoteShellArg(value) {
+  return "'" + String(value).replaceAll("'", "'\\''") + "'";
+}
+
+/** Normalize guest bash(command, opts) / bash({command, args}) into host args. */
+function normalizeArgv(args) {
+  if (args.args === undefined) return;
+  if (!isString(args.command) || !Array.isArray(args.args)) throw new Error(ARGV_ERROR);
+
+  for (let i = 0; i < args.args.length; i++) if (!isString(args.args[i])) throw new Error(ARGV_ERROR);
+  args.args = args.args.map(String);
+
+  if (process.platform === "win32") {
+    delete args._directArgv;
+    args.command = [args.command, ...args.args].map(quoteShellArg).join(" ");
+    delete args.args;
+  } else args._directArgv = true;
+}
+
+export function normalizeBash(command, opts) {
+  const args = isObject(command) ? { ...opts, ...command } : { command, ...opts };
+  normalizeArgv(args);
+
+  if (args.timeout !== undefined && args.timeoutMs === undefined) args.timeoutMs = args.timeout * 1000;
+
+  return args;
+}

package/src/contract/edit.js

@@ -0,0 +1,95 @@
+import { isString, isObject, isFunction, isNumber } from "../shared/decode.js";
+
+export const EDIT_USAGE = 'invalid edit signature; use edit(path,oldText,newText), edit({path,edits:[{oldText,newText}]}), or edit({path,patch:"@@ -1 +1 @@\n-old\n+new\n"})';
+
+function spanStart(value) {
+  return isNumber(value.start) ? value.start : Array.isArray(value.lines) ? value.lines[0] : value.line;
+}
+
+function spanEnd(value, start) {
+  return isNumber(value.end) ? value.end : Array.isArray(value.lines) && value.lines.length > 1 ? value.lines[1] : start;
+}
+
+export function viewSpan(value) {
+  const start = spanStart(value);
+  const end = spanEnd(value, start);
+
+  if (!isNumber(start) || !isNumber(end) || start < 1 || end < start) return null;
+
+  return { start: Math.floor(start), end: Math.floor(end) };
+}
+
+export function isEditView(value) {
+  return isObject(value) && !Array.isArray(value) && isString(value.path) && value.path.trim() && isString(value.text) && (value.status === undefined || value.status === "found") && viewSpan(value);
+}
+
+function classifyViewEdit(p, oldText, newText) {
+  if (isNumber(p.nextOffset)) throw new Error("edit view is incomplete");
+  const span = viewSpan(p);
+  const args = { path: p.path, viewStart: span.start, viewEnd: span.end, viewText: p.text, newText: newText === undefined ? oldText : newText };
+
+  if (newText !== undefined) args.oldText = oldText;
+
+  return { kind: "view", command: "edit", args };
+}
+
+function namedEditObject(p, oldText, newText) {
+  if (isObject(p) && (Array.isArray(p) || oldText !== undefined || newText !== undefined)) throw new Error(EDIT_USAGE);
+
+  return p;
+}
+
+function namedEditPositional(p, oldText, newText) {
+  if (isObject(oldText) && !Array.isArray(oldText)) throw new Error(EDIT_USAGE);
+
+  return Array.isArray(oldText) ? { path: p, edits: oldText } : { path: p, oldText, newText };
+}
+
+function normalizeEditArgs(p, oldText, newText) {
+  return isObject(p) ? namedEditObject(p, oldText, newText) : namedEditPositional(p, oldText, newText);
+}
+
+function namedEditArgs(p, oldText, newText) {
+  const args = normalizeEditArgs(p, oldText, newText);
+
+  if (!isString(args.path) || !args.path.trim()) throw new Error(EDIT_USAGE);
+
+  return args;
+}
+
+function assertNamedEditMode(args, oldText, newText) {
+  const modes = Number(args.patch !== undefined) + Number(args.edits !== undefined) + Number(args.oldText !== undefined || args.newText !== undefined);
+
+  if (modes !== 1 || (Array.isArray(oldText) && newText !== undefined)) throw new Error(EDIT_USAGE);
+}
+
+function classifyPatch(args) {
+  if (!isString(args.patch) || !args.patch.trim()) throw new Error(EDIT_USAGE);
+
+  return { kind: "patch", command: "apply_patch", args };
+}
+
+function classifyReplacements(args) {
+  const edits = args.edits === undefined ? [args] : args.edits;
+
+  if (!Array.isArray(edits) || !edits.length) throw new Error(EDIT_USAGE);
+
+  for (const e of edits) if (!isString(e?.oldText) || !e.oldText.length || !isString(e?.newText)) throw new Error(EDIT_USAGE + "; replacements require non-empty oldText and string newText");
+
+  return { kind: "edits", command: "edit", args };
+}
+
+function classifyNamedEdit(p, oldText, newText) {
+  const args = namedEditArgs(p, oldText, newText);
+  assertNamedEditMode(args, oldText, newText);
+
+  return args.patch !== undefined ? classifyPatch(args) : classifyReplacements(args);
+}
+
+/** Guest signature → { command, args } for one host call. */
+export function classifyEdit(p, oldText, newText) {
+  if (isFunction(p)) return { kind: "checkpoint", fn: p };
+  if (isEditView(p) && isString(oldText) && (newText === undefined || isString(newText))) return classifyViewEdit(p, oldText, newText);
+
+  return classifyNamedEdit(p, oldText, newText);
+}

package/src/contract/read.js

@@ -0,0 +1,220 @@
+import { isString, isObject, isNumber, looksLikePath } from "../shared/decode.js";
+import { sessionJsonArgs, validateJsonRead } from "../fs/json-read.js";
+
+export const SESSION_URI = /^(?:agent|artifact):\/\//i;
+
+const BOOL_KEYS = ["resolve", "complete", "outline", "evidence"];
+
+export function isSessionUri(value) {
+  return isString(value) && SESSION_URI.test(value);
+}
+
+/** Guest call shape → one options object. */
+export function gatherReadArgs(p, a, b) {
+  if (isObject(p) && !Array.isArray(p)) {
+    const args = { ...p, path: p.path ?? p.target ?? p.query };
+
+    if (p.path === undefined && p.target !== undefined) delete args.target;
+
+    return args;
+  }
+
+  return isObject(a) && !Array.isArray(a) ? { path: p, ...a } : { path: p, offset: a, limit: b };
+}
+
+export function assertReadPaths(targetParam) {
+  if (!Array.isArray(targetParam)) return;
+  if (targetParam.length > 64) throw new Error("read accepts at most 64 paths per batch");
+
+  for (const item of targetParam) if (!isString(item) || !item.trim()) throw new Error("read paths must be non-empty strings");
+}
+
+function assertReadFlags(args) {
+  for (const key of BOOL_KEYS) {
+    if (args[key] !== undefined && args[key] !== true && args[key] !== false) throw new Error("read " + key + " must be a boolean");
+  }
+
+  if (args.about !== undefined && !isString(args.about)) throw new Error("read about must be a string");
+  if (args.query !== undefined && !isString(args.query)) throw new Error("read query must be a string");
+}
+
+function assertExclusiveRead(args) {
+  const focusModes = [args.about !== undefined, args.query !== undefined, args.outline === true].filter(Boolean).length;
+
+  if (focusModes > 1 || (args.outline === true && args.evidence === true)) throw new Error("read accepts only one of about, query, outline, or evidence");
+  if (args.resolve === true && args.complete === true) throw new Error("read accepts either resolve or complete, not both");
+  if ((focusModes === 1 || args.evidence === true) && args.complete === true) throw new Error("complete:true requires a raw file read, not a source view");
+}
+
+function autoResolve(args) {
+  if (!isString(args.path) || args.resolve !== undefined || args.complete === true || args.json !== undefined) return args;
+  if (args.about !== undefined || args.query !== undefined || looksLikePath(args.path) || isSessionUri(args.path)) return args;
+
+  return { ...args, resolve: true };
+}
+
+/** Exclusive-mode + JSON + auto-resolve. Same rules for guest and host. */
+export function normalizeRead(params) {
+  if (!isObject(params)) throw new Error("read requires an options object");
+  if (params.path !== undefined && params.target !== undefined && params.path !== params.target) {
+    throw new Error("read accepts either path or target, not both");
+  }
+
+  const args = sessionJsonArgs({ ...params, path: params.path ?? params.target });
+  validateJsonRead(args);
+  assertReadFlags(args);
+  assertExclusiveRead(args);
+  assertReadPaths(args.path);
+
+  return autoResolve(args);
+}
+
+export function needsProbe(params) {
+  if (isSessionUri(params.path)) return false;
+  if (params.evidence === true) return false;
+  if (isString(params.query)) return false;
+  if (params.outline === true) return false;
+
+  return true;
+}
+
+/**
+ * Kind of read after exclusive modes are already validated.
+ * `existing` is the probe result, or null/undefined when needsProbe is false or the path is missing.
+ */
+function classifyExisting(params, existing) {
+  if (existing.directory) {
+    if (params.json !== undefined) throw new Error("JSON read requires a file, not a directory");
+
+    return isString(params.about)
+      ? { kind: "snap", query: params.about, scoped: true, existing }
+      : { kind: "dir", existing };
+  }
+
+  if (params.resolve === true && isString(params.about)) {
+    throw new Error("resolve:true cannot combine with about on a file; use about for a focused outline or resolve for source text");
+  }
+
+  if (isString(params.about) && existing.size > 512 * 1024) return { kind: "focus", existing, about: params.about };
+
+  return { kind: params.resolve ? "open" : "file", existing };
+}
+
+function classifySession(params) {
+  if (params.about !== undefined || params.query !== undefined || params.outline === true || params.evidence === true) {
+    throw new Error("session resources do not support about/query/outline/evidence views");
+  }
+
+  return { kind: "session" };
+}
+
+function classifyEvidence(params, target) {
+  const query = params.about ?? params.query ?? target;
+  const scope = target !== query || looksLikePath(target) ? target : undefined;
+
+  return { kind: "evidence", query, scope };
+}
+
+function classifyBarePath(params, target) {
+  if (params.json === undefined && !looksLikePath(target)) {
+    return { kind: "snap", query: isString(params.about) ? params.about : target, scoped: isString(params.about) };
+  }
+
+  if (params.resolve === true && params.complete !== true) return { kind: "missing" };
+
+  return { kind: "file", existing: null };
+}
+
+export function classifyRead(params, existing) {
+  const target = params.path;
+
+  if (isSessionUri(target)) return classifySession(params);
+  if (params.evidence === true) return classifyEvidence(params, target);
+  if (isString(params.query)) return { kind: "snap", query: params.query, scoped: Boolean(target && target !== params.query) };
+  if (params.outline === true) return { kind: "outline" };
+  if (existing) return classifyExisting(params, existing);
+
+  return classifyBarePath(params, target);
+}
+
+function jsonSelectorNote(args) {
+  return args.json === undefined ? "" : " (" + (Array.isArray(args.json) ? args.json.join(", ") : String(args.json)) + ")";
+}
+
+export const ROUTING_STATUS = "too_large";
+
+const ROUTING_PREFIX = '{"status":"too_large",';
+
+export const ROUTING_KEYS_MAX = 32;
+
+export function isRoutingPayload(value) {
+  return isString(value) && value.startsWith(ROUTING_PREFIX);
+}
+
+function isRoutingObject(parsed) {
+  return isObject(parsed) && parsed.status === ROUTING_STATUS && isString(parsed.path)
+    && isNumber(parsed.chars) && (Array.isArray(parsed.keys) || isNumber(parsed.length));
+}
+
+/** Shape of an over-bound JSON document for in-band routing. Throws when text is not JSON. */
+export function buildJsonRouting(rel, text) {
+  const document = JSON.parse(text);
+  const base = { status: ROUTING_STATUS, path: rel, chars: text.length };
+
+  if (Array.isArray(document)) return { ...base, length: document.length };
+
+  if (isObject(document)) {
+    const keys = Object.keys(document);
+
+    return keys.length > ROUTING_KEYS_MAX
+      ? { ...base, keys: keys.slice(0, ROUTING_KEYS_MAX), keysTruncated: true }
+      : { ...base, keys };
+  }
+
+  return base;
+}
+
+export function routingText(routing) {
+  const text = JSON.stringify(routing);
+
+  if (!isRoutingPayload(text)) throw new Error("routing payload must start with the shared marker");
+
+  return text;
+}
+
+/** Shape of one over-budget selection for in-band routing; value is already parsed. */
+export function buildSelectionRouting(rel, selector, value, chars) {
+  const base = { status: ROUTING_STATUS, path: rel, selector, chars };
+
+  if (Array.isArray(value)) return { ...base, length: value.length };
+
+  if (isObject(value)) {
+    const keys = Object.keys(value);
+
+    return keys.length > ROUTING_KEYS_MAX
+      ? { ...base, keys: keys.slice(0, ROUTING_KEYS_MAX), keysTruncated: true }
+      : { ...base, keys };
+  }
+
+  return base;
+}
+
+function decodeByArgs(args, value) {
+  return (args.resolve || args.json !== undefined || args.outline || args.evidence) && isString(value);
+}
+
+export function decodeReadValue(args, value) {
+  const sniffed = isRoutingPayload(value);
+
+  if (!sniffed && !decodeByArgs(args, value)) return value;
+
+  try {
+    const parsed = JSON.parse(value);
+
+    return sniffed && !isRoutingObject(parsed) ? value : parsed;
+  } catch (error) {
+    if (sniffed && !decodeByArgs(args, value)) return value;
+
+    throw new Error("JSON read failed for " + String(args.path ?? args.target ?? "resource") + jsonSelectorNote(args) + ": " + (error instanceof Error ? error.message : String(error)));
+  }
+}

package/src/fs/check.js

@@ -60,7 +60,7 @@ function skipComment(text, i) {
 
   const end = text.indexOf("*/", i + 2);
 
-  return end < 0 ? text.length : end + 2;
+  return end < 0 ? -1 : end + 2;
 }
 
 function skipRegex(text, i) {
@@ -118,6 +118,21 @@ function consumeQuoted(text, i, stack) {
   return end < 0 ? { error: "unterminated string", at: i } : { end, prev: "value" };
 }
 
+function consumeSlash(text, i, prev) {
+  if (text[i + 1] === "/" || text[i + 1] === "*") {
+    const end = skipComment(text, i);
+
+    if (end < 0) return { error: "unterminated comment", at: i };
+
+    return { end, prev };
+  }
+
+  if (prev !== "" && !REGEX_PRECEDERS.has(prev)) return null;
+  const end = skipRegex(text, i);
+
+  return end > 0 ? { end, prev: "value" } : null;
+}
+
 /** Try to consume a comment, string, template, or regex at i. Returns { end, prev } | { error, at } | null. */
 function consumeLiteral(text, i, stack, prev) {
   const c = text[i];
@@ -126,12 +141,7 @@ function consumeLiteral(text, i, stack, prev) {
 
   if (c !== "/") return null;
 
-  if (text[i + 1] === "/" || text[i + 1] === "*") return { end: skipComment(text, i), prev };
-
-  if (prev !== "" && !REGEX_PRECEDERS.has(prev)) return null;
-  const end = skipRegex(text, i);
-
-  return end > 0 ? { end, prev: "value" } : null;
+  return consumeSlash(text, i, prev);
 }
 
 /** Push/pop a bracket; returns an error, a stop, or null to continue. */
@@ -190,6 +200,8 @@ const CODE_EXT = new Set([".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx", ".mts",
 
 /** { ok: true } | { ok: false, message }; message names the problem and line. */
 export function quickCheck(text, ext) {
+  ext = String(ext ?? "").toLowerCase();
+
   if (ext === ".json") {
     try {
       JSON.parse(text);

package/src/fs/diff.js

@@ -1,6 +1,9 @@
 
 import { isString } from "../shared/decode.js";
 
+/** Receipts render at most this many matches; totals still cover every match. */
+export const MAX_DIFF_MATCHES = 32;
+
 export function buildEditDiff(filePath, originalText, oldText, newText) {
   const fileLines = contentLines(originalText);
   const idx = isString(originalText) ? originalText.indexOf(oldText) : -1;
@@ -39,7 +42,8 @@ export function buildEditDiff(filePath, originalText, oldText, newText) {
 }
 
 export function buildMultiEditDiff(filePath, originalText, replacements) {
-  const parts = replacements.map(({ oldText, newText }) =>
+  const rendered = replacements.slice(0, MAX_DIFF_MATCHES);
+  const parts = rendered.map(({ oldText, newText }) =>
     buildEditDiff(filePath, originalText, oldText, newText),
   );
 
@@ -53,15 +57,16 @@ export function buildMultiEditDiff(filePath, originalText, replacements) {
         : { ...line, newLineNum: Math.max(1, line.lineNum + shift) });
     }
 
-    shift += replacements[index].newText.split("\n").length - replacements[index].oldText.split("\n").length;
+    shift += rendered[index].newText.split("\n").length - rendered[index].oldText.split("\n").length;
   }
 
   return {
     path: filePath,
     op: "edit",
-    added: parts.reduce((sum, part) => sum + part.added, 0),
-    removed: parts.reduce((sum, part) => sum + part.removed, 0),
+    added: replacements.reduce((sum, r) => sum + contentLines(r.newText).length, 0),
+    removed: replacements.reduce((sum, r) => sum + contentLines(r.oldText).length, 0),
     lines,
+    omittedMatches: replacements.length - rendered.length,
   };
 }
 
@@ -71,22 +76,28 @@ function classifyPatchLine(line) {
   return PATCH_LINE_KINDS[line[0]] || null;
 }
 
-export function buildPatchDiff(filePath, patchText) {
+export function buildPatchDiff(filePath, patchText, relocations = []) {
   const patchLines = isString(patchText) ? patchText.replace(/\r\n/g, "\n").split("\n") : [];
+  const shiftByHunk = new Map(relocations.map(entry => [entry.hunk, entry.offset]));
   const lines = [];
   let added = 0;
   let removed = 0;
   let oldLineNum = 1;
   let newLineNum = 1;
   let inHunk = false;
+  let hunkIndex = 0;
+  let relocatedBy = 0;
 
   for (const patchLine of patchLines) {
     const headerMatch = (/^@@\s+-(\d+)(?:,(\d+))?\s+\+(\d+)(?:,(\d+))?/).exec(patchLine);
 
     if (headerMatch) {
+      // Headers already carry length deltas, so only drift relocates the receipt.
+      hunkIndex += 1;
+      relocatedBy += shiftByHunk.get(hunkIndex) ?? 0;
       // A zero-length range names the line before the insertion/deletion point.
-      oldLineNum = Number(headerMatch[1]) + Number(headerMatch[2] === "0");
-      newLineNum = Number(headerMatch[3]) + Number(headerMatch[4] === "0");
+      oldLineNum = Number(headerMatch[1]) + Number(headerMatch[2] === "0") + relocatedBy;
+      newLineNum = Number(headerMatch[3]) + Number(headerMatch[4] === "0") + relocatedBy;
       inHunk = true;
       continue;
     }

package/src/fs/json-read.js

@@ -2,7 +2,37 @@ import { isString, isObject } from "../shared/decode.js";
 
 export const MAX_JSON_BYTES = 16 * 1024 * 1024;
 
-const SELECTOR_HELP = 'JSON selector supports .field, .nested[0], .items[0:3], .["quoted.key"], or . (whole value); not full jq';
+const SELECTOR_HELP = 'JSON selector supports .field, .nested[0], .items[0:3], .items.length, .["quoted.key"], or . (whole value); not full jq';
+
+function parseIdentStep(rest, first) {
+  const match = (first ? /^([A-Za-z_$][\w$]*)/ : /^\.([A-Za-z_$][\w$]*)/).exec(rest);
+
+  return match ? { step: { key: match[1] }, match } : null;
+}
+
+function parseQuotedStep(rest) {
+  const match = /^\[("(?:[^"\\]|\\.)*")\]/.exec(rest);
+
+  if (!match) return null;
+
+  try { return { step: { key: JSON.parse(match[1]) }, match }; } catch { throw new Error(SELECTOR_HELP); }
+}
+
+function parseIndexBounds(start, end) {
+  if (!Number.isSafeInteger(start) || (end !== undefined && (!Number.isSafeInteger(end) || end < start))) throw new Error(SELECTOR_HELP);
+
+  return end === undefined ? { index: start } : { start, end };
+}
+
+function parseIndexStep(rest) {
+  const match = /^\[(\d+)(?::(\d+))?\]/.exec(rest);
+
+  if (!match) return null;
+  const start = Number(match[1]);
+  const end = match[2] === undefined ? undefined : Number(match[2]);
+
+  return { step: parseIndexBounds(start, end), match };
+}
 
 /** Parse a small, non-evaluating selector language. No dynamic code or prototype lookup. */
 function parseSelector(selector) {
@@ -12,25 +42,46 @@ function parseSelector(selector) {
   let first = true;
 
   while (rest) {
-    let match;
-
-    if ((match = (first ? /^([A-Za-z_$][\w$]*)/ : /^\.([A-Za-z_$][\w$]*)/).exec(rest))) {
-      steps.push({ key: match[1] });
-    } else if ((match = /^\[("(?:[^"\\]|\\.)*")\]/.exec(rest))) {
-      try { steps.push({ key: JSON.parse(match[1]) }); } catch { throw new Error(SELECTOR_HELP); }
-    } else if ((match = /^\[(\d+)(?::(\d+))?\]/.exec(rest))) {
-      const start = Number(match[1]), end = match[2] === undefined ? undefined : Number(match[2]);
-
-      if (!Number.isSafeInteger(start) || (end !== undefined && (!Number.isSafeInteger(end) || end < start))) throw new Error(SELECTOR_HELP);
-      steps.push(end === undefined ? { index: start } : { start, end });
-    } else throw new Error(SELECTOR_HELP);
-    rest = rest.slice(match[0].length);
+    const parsed = parseIdentStep(rest, first) || parseQuotedStep(rest) || parseIndexStep(rest);
+
+    if (!parsed) throw new Error(SELECTOR_HELP);
+    steps.push(parsed.step);
+    rest = rest.slice(parsed.match[0].length);
     first = false;
   }
 
   return steps;
 }
 
+function missingJsonField(value, key) {
+  const keys = isObject(value) ? Object.keys(value) : [];
+  const preview = keys.length ? "; available keys: " + keys.slice(0, 24).map(key => JSON.stringify(key)).join(", ") + (keys.length > 24 ? ", …" : "") : "";
+
+  return new Error("JSON field not found: " + JSON.stringify(key) + preview);
+}
+
+function selectKey(value, key) {
+  if (Array.isArray(value) && key === "length") return value.length;
+
+  if (!isObject(value) || !Object.hasOwn(value, key)) throw missingJsonField(value, key);
+
+  return value[key];
+}
+
+function selectStep(value, step) {
+  if (step.key !== undefined) return selectKey(value, step.key);
+
+  if (!Array.isArray(value)) throw new Error("JSON index requires an array");
+
+  if (step.index !== undefined) {
+    if (step.index >= value.length) throw new Error("JSON index out of range: " + step.index);
+
+    return value[step.index];
+  }
+
+  return value.slice(step.start, step.end);
+}
+
 export function jsonProjector(json) {
   const many = Array.isArray(json);
   const selectors = many ? json : [json === true ? "." : json];
@@ -41,27 +92,7 @@ export function jsonProjector(json) {
   // Yield one selection at a time so the caller can budget it before the next
   // slice allocation. Eagerly mapping 64 large slices can exhaust the host heap.
   return function* (root) {
-    for (const steps of plans) yield steps.reduce((value, step) => {
-      if (step.key !== undefined) {
-        if (!isObject(value) || !Object.hasOwn(value, step.key)) {
-          const keys = isObject(value) ? Object.keys(value) : [];
-          const preview = keys.length ? "; available keys: " + keys.slice(0, 24).map(key => JSON.stringify(key)).join(", ") + (keys.length > 24 ? ", …" : "") : "";
-          throw new Error("JSON field not found: " + JSON.stringify(step.key) + preview);
-        }
-
-        return value[step.key];
-      }
-
-      if (!Array.isArray(value)) throw new Error("JSON index requires an array");
-
-      if (step.index !== undefined) {
-        if (step.index >= value.length) throw new Error("JSON index out of range: " + step.index);
-
-        return value[step.index];
-      }
-
-      return value.slice(step.start, step.end);
-    }, root);
+    for (const steps of plans) yield steps.reduce(selectStep, root);
   };
 }