sweet-search 2.5.13 → 2.5.14

package/eval/agent-read-workflows/bin/_ss-argparse.mjs

@@ -77,6 +77,10 @@ export function stripInertFlags(args) {
 // so they parse instead of being mistaken for an unknown flag or the pattern.
 export const VALUE_SHORTS = new Set(['k']);
 export const BOOL_SHORTS = new Set(['i', 'w', 'F']);
+export const VALUE_LONGS = new Set([
+  '--top', '--regex', '--mode', '--max-tokens',
+  '--in', '--file', '--query', '--hint', '--depth', '--budget',
+]);
 
 export function normalizeArgs(args) {
   const out = [];
@@ -85,9 +89,11 @@ export function normalizeArgs(args) {
     if (positionalOnly || typeof tok !== 'string') { out.push(tok); continue; }
     if (tok === '--') { out.push(tok); positionalOnly = true; continue; }
 
-    // --name=value  →  --name value
+    // --name=value  →  --name value, but only for known value flags. Unknown
+    // long options stay intact so the guard can reject the whole token, and
+    // optional-value no-ops like --color=always can be stripped atomically.
     let m = /^(--[A-Za-z][\w-]*)=(.*)$/.exec(tok);
-    if (m) { out.push(m[1], m[2]); continue; }
+    if (m && VALUE_LONGS.has(m[1])) { out.push(m[1], m[2]); continue; }
 
     // attached short value or boolean bundle:  -k5, -iw, -iwk5
     m = /^-([A-Za-z])(.+)$/.exec(tok);
@@ -123,9 +129,49 @@ export function normalizeArgs(args) {
 // dash-leading pattern works WITHOUT the agent needing to know about `--`.
 export function looksLikeOption(tok) {
   if (typeof tok !== 'string' || tok === '-' || tok === '--') return false;
-  return /^-[A-Za-z]$/.test(tok)            // -i
-    || /^-[A-Za-z]{2,}$/.test(tok)          // -iw  (pure-letter bundle)
-    || /^--[A-Za-z][\w-]*$/.test(tok);      // --ignore-case
+  return /^-[A-Za-z][A-Za-z0-9]*$/.test(tok)      // -i, -iw, -C2
+    || /^--[A-Za-z][\w-]*(?:=.*)?$/.test(tok);    // --ignore-case, --foo=bar
+}
+
+export function parseValueFlag(args, names, fallback, { allowOptionValue = false } = {}) {
+  const allNames = Array.isArray(names) ? names : [names];
+  for (const n of allNames) {
+    const i = args.indexOf(n);
+    if (i === -1) continue;
+    const v = args[i + 1];
+    if (v == null || (!allowOptionValue && looksLikeOption(v))) {
+      return { value: fallback, flag: n, error: `${n} requires a value` };
+    }
+    args.splice(i, 2);
+    return { value: v, flag: n, error: null };
+  }
+  return { value: fallback, flag: null, error: null };
+}
+
+export function parsePositiveIntFlag(args, names, fallback, { min = 1 } = {}) {
+  const parsed = parseValueFlag(args, names, fallback);
+  if (parsed.error) return parsed;
+  if (parsed.flag == null) return { ...parsed, value: fallback };
+  const n = Number(parsed.value);
+  if (!Number.isInteger(n) || n < min) {
+    return { value: fallback, flag: parsed.flag, error: `${parsed.flag} must be an integer >= ${min}` };
+  }
+  return { value: n, flag: parsed.flag, error: null };
+}
+
+// Parse a line range supplied as a single positional token — `10-20`, `10:20`
+// or `10,20` (sed/bat/"lines 10-20" muscle memory). Returns { start, end } only
+// for a well-formed ascending range; null otherwise (so the caller falls back to
+// the plain numeric path or its own validation). Deliberately strict: both ends
+// required, no open-ended `10-` (which previously caused accidental over-reads).
+export function parseLineRange(token) {
+  if (typeof token !== 'string') return null;
+  const m = /^(\d+)[-:,](\d+)$/.exec(token);
+  if (!m) return null;
+  const start = +m[1];
+  const end = +m[2];
+  if (start < 1 || end < start) return null;
+  return { start, end };
 }
 
 // After known flags are consumed, resolve the positional pattern. `--` ends

package/eval/agent-read-workflows/bin/_ss-helpers.mjs

@@ -14,8 +14,9 @@ import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import {
-  parseFlag, parseShortFlag, parseBoolFlag,
+  parseBoolFlag, parseValueFlag, parsePositiveIntFlag,
   buildGrepPattern, stripInertFlags, normalizeArgs, extractPositional,
+  parseLineRange, looksLikeOption,
 } from './_ss-argparse.mjs';
 
 // 8-char SHA1 prefix is enough for grouping identical queries across
@@ -52,12 +53,33 @@ const rest = process.argv.slice(3);
 function resolvePositional(args, usage) {
   const { pattern, unknownFlag } = extractPositional(args);
   if (unknownFlag) {
-    process.stderr.write(`[ss] unrecognised option "${unknownFlag}"\n${usage}\n`);
-    process.exit(2);
+    failUsage(`unrecognised option "${unknownFlag}"`, usage);
   }
   return pattern;
 }
 
+function failUsage(message, usage) {
+  process.stderr.write(`[ss] ${message}\n${usage}\n`);
+  process.exit(2);
+}
+
+function readPositiveIntFlag(args, names, fallback, usage) {
+  const parsed = parsePositiveIntFlag(args, names, fallback);
+  if (parsed.error) failUsage(parsed.error, usage);
+  return parsed.value;
+}
+
+function readValueFlag(args, names, fallback, usage, opts = {}) {
+  const parsed = parseValueFlag(args, names, fallback, opts);
+  if (parsed.error) failUsage(parsed.error, usage);
+  return parsed.value;
+}
+
+function rejectUnknownOptions(args, usage) {
+  const bad = args.find(looksLikeOption);
+  if (bad) failUsage(`unrecognised option "${bad}"`, usage);
+}
+
 async function getSweetSearch() {
   const { SweetSearch } = await import(path.join(REPO_ROOT, 'core/search/sweet-search.js'));
   const s = new SweetSearch({ projectRoot: PROJECT_ROOT });
@@ -88,7 +110,7 @@ async function cmdGrep(rawArgs) {
   const ignoreCase = parseBoolFlag(args, ['-i', '--ignore-case']);
   const wordBound = parseBoolFlag(args, ['-w', '--word-regexp']);
   const fixedString = parseBoolFlag(args, ['-F', '--fixed-strings']);
-  const k = +parseShortFlag(args, ['-k', '--top'], 20);
+  const k = readPositiveIntFlag(args, ['-k', '--top'], 20, GREP_USAGE);
   stripInertFlags(args);
   const regex = buildGrepPattern(resolvePositional(args, GREP_USAGE), { ignoreCase, wordBound, fixedString });
   if (!regex) {
@@ -133,8 +155,8 @@ async function cmdFind(rawArgs) {
   const ignoreCase = parseBoolFlag(args, ['-i', '--ignore-case']);
   const wordBound = parseBoolFlag(args, ['-w', '--word-regexp']);
   const fixedString = parseBoolFlag(args, ['-F', '--fixed-strings']);
-  const k = +parseShortFlag(args, ['-k', '--top'], 6);
-  const regex = parseFlag(args, '--regex', '');
+  const k = readPositiveIntFlag(args, ['-k', '--top'], 6, FIND_USAGE);
+  const regex = readValueFlag(args, '--regex', '', FIND_USAGE, { allowOptionValue: true });
   stripInertFlags(args);
   const query = resolvePositional(args, FIND_USAGE);
   if (!query) {
@@ -188,12 +210,26 @@ async function cmdFind(rawArgs) {
   process.exit(0);
 }
 
+// ss-read takes NO flags — only positional <file> [start] [end] (or a single
+// "start-end" / "start:end" / "start,end" range token). Unlike ss-grep, a stray
+// flag here can never silently corrupt the result: the line slots are validated
+// as numbers, so a misuse is already a loud error. These hints exist only to
+// turn that error into a self-correcting one (the M++ prompt, which we may not
+// touch, documents the positional form, not these recovery messages).
+const READ_USAGE =
+  'Usage: ss-read <file>            # whole file\n' +
+  '       ss-read <file> <start>    # ONE line\n' +
+  '       ss-read <file> <start> <end>\n' +
+  '       ss-read <file> 10-20      # range (also 10:20, 10,20)\n' +
+  'Note: ss-read has no flags (no -n/--limit/-r); line selection is positional.';
 async function cmdRead(args) {
   const file = args[0];
   if (!file) {
-    process.stderr.write('Usage: ss-read <file>             # whole file\n');
-    process.stderr.write('       ss-read <file> <start>     # ONE line\n');
-    process.stderr.write('       ss-read <file> <start> <end>\n');
+    process.stderr.write(READ_USAGE + '\n');
+    process.exit(2);
+  }
+  if (looksLikeOption(file)) {
+    process.stderr.write(`[ss-read] "${file}" looks like a flag, but ss-read takes a file path first.\n${READ_USAGE}\n`);
     process.exit(2);
   }
   // If start is provided and end is omitted, read EXACTLY that one line —
@@ -201,19 +237,27 @@ async function cmdRead(args) {
   // caused accidental over-reading on large files).
   let start = null, end = null;
   if (args[1] != null) {
-    start = +args[1];
-    if (!Number.isFinite(start) || start < 1) {
-      process.stderr.write(`[ss-read] invalid start line: "${args[1]}"\n`);
-      process.exit(2);
-    }
-    if (args[2] != null) {
-      end = +args[2];
-      if (!Number.isFinite(end) || end < start) {
-        process.stderr.write(`[ss-read] invalid end line: "${args[2]}" (must be ≥ start ${start})\n`);
+    // Accept a single-token range (10-20 / 10:20 / 10,20) before the plain
+    // numeric path, so "lines 10-20" muscle memory works without a wasted call.
+    const range = parseLineRange(args[1]);
+    if (range && args[2] == null) {
+      start = range.start;
+      end = range.end;
+    } else {
+      start = +args[1];
+      if (!Number.isFinite(start) || start < 1) {
+        process.stderr.write(`[ss-read] invalid start line: "${args[1]}" (expected a line number, e.g. 10, or a range like 10-20)\n${READ_USAGE}\n`);
         process.exit(2);
       }
-    } else {
-      end = start;     // single-line read
+      if (args[2] != null) {
+        end = +args[2];
+        if (!Number.isFinite(end) || end < start) {
+          process.stderr.write(`[ss-read] invalid end line: "${args[2]}" (must be ≥ start ${start})\n`);
+          process.exit(2);
+        }
+      } else {
+        end = start;     // single-line read
+      }
     }
   }
   const { readFile } = await import(path.join(REPO_ROOT, 'core/search/search-read.js'));
@@ -228,7 +272,9 @@ async function cmdRead(args) {
   process.exit(0);
 }
 
-async function cmdAgentSearch(args) {
+const SEARCH_USAGE = 'Usage: ss-search "<query>" [--full|--xl] [-k N] [--mode auto|lexical|semantic|hybrid]';
+async function cmdAgentSearch(rawArgs) {
+  const args = normalizeArgs(rawArgs);
   // Main sweet-search auto/CatBoost search with token-budgeted agent packaging.
   //
   // Usage:
@@ -245,11 +291,11 @@ async function cmdAgentSearch(args) {
   let format = 'agent';
   if (args.includes('--full')) { format = 'agent_full'; args.splice(args.indexOf('--full'), 1); }
   if (args.includes('--xl'))   { format = 'agent_full_xl'; args.splice(args.indexOf('--xl'), 1); }
-  const k = +parseShortFlag(args, ['-k', '--top'], 5);
-  const mode = parseFlag(args, '--mode', 'auto');
-  const query = args[0];
+  const k = readPositiveIntFlag(args, ['-k', '--top'], 5, SEARCH_USAGE);
+  const mode = readValueFlag(args, '--mode', 'auto', SEARCH_USAGE);
+  const query = resolvePositional(args, SEARCH_USAGE);
   if (!query) {
-    process.stderr.write('Usage: ss-search "<query>" [--full|--xl] [-k N] [--mode auto|lexical|semantic|hybrid]\n');
+    process.stderr.write(SEARCH_USAGE + '\n');
     process.exit(2);
   }
 
@@ -399,18 +445,21 @@ async function cmdAgentSearch(args) {
   process.exit(0);
 }
 
-async function cmdSemantic(args) {
+const SEMANTIC_USAGE = 'Usage: ss-semantic <file> "<question>" [--max-tokens N]';
+async function cmdSemantic(rawArgs) {
+  const args = normalizeArgs(rawArgs);
+  // Default 600 (was 800) per the 2026-06 budget sweep — scaled with the 3k
+  // preview tier. Env hook overrides the default for sweeps; an explicit
+  // --max-tokens flag from the agent always wins.
+  const maxTokens = readPositiveIntFlag(args, '--max-tokens',
+    Number(process.env.SS_SMOKE_SEMANTIC_MAXTOKENS || '') || 600, SEMANTIC_USAGE);
+  rejectUnknownOptions(args, SEMANTIC_USAGE);
   const file = args[0];
   const query = args[1];
   if (!file || !query) {
-    process.stderr.write('Usage: ss-semantic <file> "<question>" [--max-tokens N]\n');
+    process.stderr.write(SEMANTIC_USAGE + '\n');
     process.exit(2);
   }
-  // Default 600 (was 800) per the 2026-06 budget sweep — scaled with the 3k
-  // preview tier. Env hook overrides the default for sweeps; an explicit
-  // --max-tokens flag from the agent always wins.
-  const maxTokens = +parseFlag(args.slice(2), '--max-tokens',
-    Number(process.env.SS_SMOKE_SEMANTIC_MAXTOKENS || '') || 600);
   const { readSemantic } = await import(path.join(REPO_ROOT, 'core/search/search-read-semantic.js'));
   const r = await readSemantic({
     path: file, query, projectRoot: PROJECT_ROOT,
@@ -429,29 +478,31 @@ async function cmdSemantic(args) {
   process.exit(0);
 }
 
-async function cmdTrace(args) {
+const TRACE_USAGE = 'Usage: ss-trace <symbol> [--in <file>] [--query <hint>] [--depth N] [--budget N]';
+async function cmdTrace(rawArgs) {
+  const args = normalizeArgs(rawArgs);
   let json = false;
   if (args.includes('--json')) {
     json = true;
     args.splice(args.indexOf('--json'), 1);
   }
-  const symbol = args[0];
-  if (!symbol) {
-    process.stderr.write('Usage: ss-trace <symbol> [--in <file>] [--query <hint>] [--depth N] [--budget N]\n');
-    process.exit(2);
-  }
   const { traceSymbol, formatStructuralContext } = await import(path.join(REPO_ROOT, 'core/search/search-trace.js'));
 
   const opts = { projectRoot: PROJECT_ROOT };
-  const file = parseFlag(args, '--in', null) || parseFlag(args, '--file', null);
-  const queryHint = parseFlag(args, '--query', '') || parseFlag(args, '--hint', '');
-  const depth = parseFlag(args, '--depth', null);
-  const budget = parseFlag(args, '--budget', null);
+  const file = readValueFlag(args, ['--in', '--file'], null, TRACE_USAGE);
+  const queryHint = readValueFlag(args, ['--query', '--hint'], '', TRACE_USAGE, { allowOptionValue: true });
+  const depth = readPositiveIntFlag(args, '--depth', null, TRACE_USAGE);
+  const budget = readPositiveIntFlag(args, '--budget', null, TRACE_USAGE);
+  const symbol = resolvePositional(args, TRACE_USAGE);
+  if (!symbol) {
+    process.stderr.write(TRACE_USAGE + '\n');
+    process.exit(2);
+  }
   if (file) opts.filePath = file;
   if (queryHint) opts.queryHint = queryHint;
-  if (depth != null) opts.maxDepth = +depth;
+  if (depth != null) opts.maxDepth = depth;
   // Budget-sweep experiment hook: env sets the default; explicit --budget wins.
-  if (budget != null) opts.tokenBudget = +budget;
+  if (budget != null) opts.tokenBudget = budget;
   else if (Number(process.env.SS_SMOKE_TRACE_BUDGET || '') > 0) opts.tokenBudget = Number(process.env.SS_SMOKE_TRACE_BUDGET);
 
   const response = traceSymbol(symbol, opts);

package/eval/agent-read-workflows/bin/ss-read

@@ -3,6 +3,8 @@
 #   ss-read <file>                  # whole file
 #   ss-read <file> <start>          # ONE line (NOT start-to-EOF)
 #   ss-read <file> <start> <end>    # explicit range
+#   ss-read <file> 10-20            # range token (also 10:20, 10,20)
+# No flags: ss-read takes no -n/--limit/-r — line selection is positional.
 # Open-ended start-to-EOF is intentionally not supported in the bench wrapper
 # to prevent accidental over-reading. To pull a span, give an explicit end.
 DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sweet-search",
-  "version": "2.5.13",
+  "version": "2.5.14",
   "description": "Sweet Search - SOTA Hybrid Code Search Engine with WASM CatBoost Query Router, Semantic/Lexical/Structural Search, and Multilingual Support",
   "type": "module",
   "main": "core/search/sweet-search.js",
@@ -165,12 +165,12 @@
   },
   "optionalDependencies": {
     "usearch": "^2.21.4",
-    "@sweet-search/native-darwin-arm64": "2.5.13",
-    "@sweet-search/native-darwin-x64": "2.5.13",
-    "@sweet-search/native-linux-arm64-gnu": "2.5.13",
-    "@sweet-search/native-linux-arm64-gnu-cuda": "2.5.13",
-    "@sweet-search/native-linux-x64-gnu": "2.5.13",
-    "@sweet-search/native-linux-x64-gnu-cuda": "2.5.13"
+    "@sweet-search/native-darwin-arm64": "2.5.14",
+    "@sweet-search/native-darwin-x64": "2.5.14",
+    "@sweet-search/native-linux-arm64-gnu": "2.5.14",
+    "@sweet-search/native-linux-arm64-gnu-cuda": "2.5.14",
+    "@sweet-search/native-linux-x64-gnu": "2.5.14",
+    "@sweet-search/native-linux-x64-gnu-cuda": "2.5.14"
   },
   "engines": {
     "node": ">=18.0.0"