dirsql 0.3.121 → 0.3.123

package/docs/reference/cli.md

@@ -151,6 +151,25 @@ uses**, so behavior is identical to `POST /query` by construction:
   statements; dirsql separately never modifies the files it indexes — see
   [Read-only by design](../explanation#read-only-by-design).
 
+#### `--on-file <command>`
+
+Attach a parser to every [path-table](./path-tables.md#parsing-rows-with-on-file)
+in the query, so each matched file yields the rows the command prints (a JSON
+array of row objects) instead of the stat columns:
+
+```sh
+dirsql query "SELECT title, author FROM './posts/*.md'" \
+  --on-file 'extract.py {path}'
+```
+
+The command follows the [`on-file` hook contract](./hooks.md#on-file) — argv
+splitting, `{path}`/`{root}` placeholders, per-file failure isolation, and the
+timeout. The parser's output is the whole schema; the stat columns are not
+reachable on a parsed path-table. `--on-file` may be given **at most once** (a
+repeat is an error pointing at config files) and never touches config-declared
+tables. It is a `query`-only flag — server mode rejects it as an unknown
+argument.
+
 Errors print the same diagnostic the HTTP `{"error": …}` body carries —
 config failures, SQL errors, rejected reads, hook failures, timeouts — to
 stderr, with exit code `1`.

package/docs/reference/path-tables.md

@@ -114,6 +114,39 @@ SELECT path FROM './docs/*.md' WHERE content LIKE '%deprecated%';
 A file that cannot be read, or is not valid UTF-8, yields `NULL` content rather
 than failing the query.
 
+## Parsing rows with `--on-file`
+
+By default a path-table's columns are the stat columns above — one row per
+file. When you want *one row per record inside* each file, attach a parser with
+the `dirsql query` flag [`--on-file`](/reference/cli):
+
+```sh
+dirsql query "SELECT title, author FROM './posts/*.md'" \
+  --on-file 'extract.py {path}'
+```
+
+The command runs once per matched file and prints a JSON array of row objects,
+exactly like a declared table's [`on-file` hook](/reference/hooks) — same argv
+splitting, same `{path}`/`{root}` placeholders, same timeout. Its output *is*
+the table:
+
+- **The parser supplies the whole schema.** Columns are inferred from the keys
+  across the emitted rows. The stat columns (`path`, `size`, …) are **not**
+  reachable on a parsed path-table — a parser that wants the path emits it (it
+  has `{path}`). The two modes stay cleanly separate.
+- **Failures are isolated per file.** A file whose parser fails (spawn, non-zero
+  exit, timeout, or no output) or whose output is not a JSON array of rows
+  contributes no rows; a one-line warning naming the file goes to stderr and the
+  scan continues. The schema is inferred from the files that did parse.
+- **The skip rules still apply.** A parsed scan honors the same `node_modules`
+  /`.git`/`ignore` rules a stat scan does (see below).
+
+`--on-file` applies to **every** path-table in the query and may be given **at
+most once**. For different parsers per file set, define named tables in a
+`.dirsql.toml` with their own `on-file` keys and pass it with `-c` — the flag
+never touches config-declared tables. It is a `query`-subcommand flag; server
+mode does not accept it.
+
 ## Freshness and scope
 
 A path-table is scanned when the statement runs, so it always reflects the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dirsql",
-  "version": "0.3.121",
+  "version": "0.3.123",
   "description": "Ephemeral SQL index over a local directory",
   "license": "MIT",
   "repository": "https://github.com/thekevinscott/dirsql",
@@ -212,15 +212,15 @@
     ]
   },
   "optionalDependencies": {
-    "@dirsql/lib-linux-x64-gnu": "0.3.121",
-    "@dirsql/lib-linux-arm64-gnu": "0.3.121",
-    "@dirsql/lib-darwin-x64": "0.3.121",
-    "@dirsql/lib-darwin-arm64": "0.3.121",
-    "@dirsql/lib-win32-x64-msvc": "0.3.121",
-    "@dirsql/cli-linux-x64-gnu": "0.3.121",
-    "@dirsql/cli-linux-arm64-gnu": "0.3.121",
-    "@dirsql/cli-darwin-x64": "0.3.121",
-    "@dirsql/cli-darwin-arm64": "0.3.121",
-    "@dirsql/cli-win32-x64-msvc": "0.3.121"
+    "@dirsql/lib-linux-x64-gnu": "0.3.123",
+    "@dirsql/lib-linux-arm64-gnu": "0.3.123",
+    "@dirsql/lib-darwin-x64": "0.3.123",
+    "@dirsql/lib-darwin-arm64": "0.3.123",
+    "@dirsql/lib-win32-x64-msvc": "0.3.123",
+    "@dirsql/cli-linux-x64-gnu": "0.3.123",
+    "@dirsql/cli-linux-arm64-gnu": "0.3.123",
+    "@dirsql/cli-darwin-x64": "0.3.123",
+    "@dirsql/cli-darwin-arm64": "0.3.123",
+    "@dirsql/cli-win32-x64-msvc": "0.3.123"
   }
 }