dirsql 0.4.67 → 0.4.69

package/docs/getting-started.md

@@ -68,11 +68,11 @@ this directory anyway — from inside `my-notes`, run one command:
 ::: code-group
 
 ```bash [npm]
-npx dirsql "SELECT COUNT(*) AS files FROM './'"
+npx dirsql "SELECT COUNT(*) AS files FROM './**'"
 ```
 
 ```bash [PyPI]
-uvx dirsql "SELECT COUNT(*) AS files FROM './'"
+uvx dirsql "SELECT COUNT(*) AS files FROM './**'"
 ```
 
 :::
@@ -91,10 +91,11 @@ files
 Three files, three rows. That one command scanned the directory, handed
 SQLite one row per file, ran your SQL, and printed the answer.
 
-There is no named table here — you never declared one. `'./'` is a
+There is no named table here — you never declared one. `'./**'` is a
 [path-table](./reference/path-tables.md): a quoted path written where a table
-name goes. `'./'` means everything under the directory you ran the command
-in. The path *is* the query.
+name goes. `'./**'` means every file under the directory you ran the command
+in, at any depth; `'./'` alone would list only the files directly inside it,
+like `ls`. The path *is* the query.
 
 ## 3. Select some columns
 
@@ -105,11 +106,11 @@ pretty-print. Ask for two columns instead of a count:
 ::: code-group
 
 ```bash [npm]
-npx dirsql query "SELECT path, size FROM './' ORDER BY path" | jq
+npx dirsql query "SELECT path, size FROM './**' ORDER BY path" | jq
 ```
 
 ```bash [PyPI]
-uvx dirsql query "SELECT path, size FROM './' ORDER BY path" | jq
+uvx dirsql query "SELECT path, size FROM './**' ORDER BY path" | jq
 ```
 
 :::

package/docs/howto/define-tables.md

@@ -116,8 +116,8 @@ templates, with the trigger mistakes that fail silently, are in
 
 ## Going further
 
-- The parser mechanics — placeholders, stdout protocol, per-file failure
-  isolation — are the [`on-file` hook contract](../reference/hooks.md#on-file);
+- The parser mechanics — placeholders, stdout protocol, failure semantics —
+  are the [`on-file` hook contract](../reference/hooks.md#on-file);
   [Extract rows from file contents](./extract-from-contents.md) is the fuller
   recipe.
 - Your directory layout encodes data (authors, dates, IDs)? Split the path in

package/docs/howto/persist.md

@@ -4,8 +4,8 @@ By default the database is ephemeral: rebuilt from your files on every
 startup and discarded on exit. The [`--persist [PATH]`](../reference/cli.md#dirsql-server)
 flag keeps the SQLite index on disk instead, so a restart only re-parses
 files that actually changed — the difference between seconds and
-milliseconds on large trees, and between re-running and skipping expensive
-[`on-file`](./extract-from-contents.md) commands.
+milliseconds on large trees, and between re-running and skipping an expensive
+declared-table [`on-file`](./extract-from-contents.md) command.
 
 Whether and where to cache is a machine-local operational choice — it
 belongs to the command you run, not to the shared `.dirsql.toml`. That is
@@ -58,15 +58,11 @@ exactly what a non-persistent startup does.
 A run that changes nothing writes nothing: the cache file is read and left
 exactly as it was.
 
-This covers both kinds of table. Declared tables keep their indexed rows, and
-a [path-table](../reference/path-tables.md) parsed with `--on-file` keeps each
-file's parser output — so the second run over an unchanged tree spawns no
-parser process at all. A path-table's cached rows are keyed by the tree, the
-glob, the parser command and the `dirsql` version together, so changing any of
-them parses afresh rather than serving rows the current command never
-produced. A *stat* path-table caches nothing, because there is nothing to
-save: its columns are the metadata the scan already collected, and `content`
-is read live by design.
+This covers declared tables, which keep their indexed rows. A
+[path-table](../reference/path-tables.md) is not cached: a *stat* path-table
+has nothing to save, since its columns are the metadata the scan already
+collected and `content` is read live by design, and a path-table parsed with
+`--on-file` runs its parser on every start.
 
 Persistence is a startup-time optimization, not a change in meaning: the
 database remains a derived view of your files, and queries return the same

package/docs/howto/query-without-config.md

@@ -67,5 +67,5 @@ why indexes belong to only one of them, are in
 - Paths outside the root resolve too — `'/var/log/*.log'`, `'../notes'`,
   `'~/notes/*.md'` — reporting absolute paths
   ([path-tables reference](../reference/path-tables.md#paths-outside-the-index-root)).
-- `node_modules/` and `.git/` are skipped by default so a bare `'./'` does not
-  drown in machinery ([skip rules](../reference/path-tables.md#skip-rules)).
+- `node_modules/` and `.git/` are skipped by default so a bare `'./**'` does
+  not drown in machinery ([skip rules](../reference/path-tables.md#skip-rules)).

package/docs/reference/cli.md

@@ -88,7 +88,7 @@ front.
 ### Output format
 
 Rows go where they are useful: a **table** when stdout is a terminal, the
-**JSON array** when it is piped or redirected. `SELECT * FROM './'` in a
+**JSON array** when it is piped or redirected. `SELECT * FROM './**'` in a
 5000-file tree should not put a 5000-element JSON array in front of a person,
 and `dirsql "…" | jq` should not have to parse a table.
 
@@ -223,11 +223,7 @@ every statement, so it is reported once and exits `1` before the first prompt.
 | Code | Meaning |
 |---|---|
 | `0` | Clean EOF (Ctrl-D, `exit`, `quit`, or the end of a piped script) — **including when statements failed**. Matches interactive `sqlite3`; use [`dirsql query`](#dirsql-query) when a script needs a statement's exit status. |
-| `1` | The index could not be built (a bad `-c`, an unresolvable `--on-file`), or stdin could not be read. Nothing was executed. |
-
-`23` (partial scan) is not produced here: skipped files are reported before the
-first prompt, and a session's exit code describes the session rather than one
-scan.
+| `1` | The index could not be built (a bad `-c`, an unresolvable `--on-file`, a failed `on-file` command), or stdin could not be read. Nothing was executed. |
 
 ## `dirsql server`
 
@@ -283,7 +279,7 @@ curl -s localhost:7117/query -H 'content-type: application/json' \
 ```
 
 Earlier versions served an implicit table named `files` here. It is gone; a
-`SELECT ... FROM files` with no config now fails and points at `FROM './'`.
+`SELECT ... FROM files` with no config now fails and points at `FROM './**'`.
 
 Passing a config with `-c` fully overrules this default. A `-c` naming a file
 that does not exist is an error (not a fallback to the default); a config that
@@ -403,8 +399,8 @@ takes, with the same `auto` default. A one-shot query is usually piped, so
 ## `dirsql init`
 
 Writes a starter `.dirsql.toml` as a scaffold to edit. It does **not**
-duplicate the zero-config floor (`SELECT * FROM './'` already lists every file
-with no config); instead it shows the **escalation**: one named `[[table]]`
+duplicate the zero-config floor (`SELECT * FROM './**'` already lists every
+file with no config); instead it shows the **escalation**: one named `[[table]]`
 with a glob, a schema, and a real `on-file` hook that pulls structured rows
 out of your files.
 

package/docs/reference/config.md

@@ -330,9 +330,9 @@ integral number → `INTEGER`, any other number → `REAL`; a string → `TEXT`;
 nested array or object → its JSON text as `TEXT`.
 
 A row's columns are exactly the keys the command emits, narrowed to the DDL;
-dirsql merges nothing else in. Output that is not a JSON array of objects is a
-per-file failure: the file is skipped with a stderr warning and the scan
-continues (see [failure semantics](./hooks.md#failure-semantics)).
+dirsql merges nothing else in. Output that is not a JSON array of objects fails
+the table, and a failed table fails the build (see
+[failure semantics](./hooks.md#failure-semantics)).
 
 ## Composing multiple configs
 
@@ -396,7 +396,7 @@ SDKs raise/reject) when:
 - A `[[table]]` entry omits `on-file` (or it is empty/whitespace). The error
   names the offending glob and points at the fix:
 
-  > `[[table]] '**/*.md' has no on-file hook, so every row would be all-NULL. Add an `on-file` hook that emits the columns, or, for stat columns with no code, query the path directly: `FROM './'``
+  > `[[table]] '**/*.md' has no on-file hook, so every row would be all-NULL. Add an `on-file` hook that emits the columns, or, for stat columns with no code, query the path directly: `FROM './**'``
 
 - A `[[dirsql.extension]]` entry omits `path`, or `path` is empty.
 - A `[[dirsql.function]]` entry omits `name`, `command`, or `args` (or

package/docs/reference/hooks.md

@@ -69,8 +69,8 @@ on-file = "timeout 30 my-extractor"
 ```
 
 When the wrapper kills an overrunning command, the run exits non-zero and
-the ordinary [failure semantics](#failure-semantics) apply — the file is
-skipped, the scan continues.
+the ordinary [failure semantics](#failure-semantics) apply — the table's
+command failed, so the build fails.
 
 ::: warning Windows
 Windows's built-in `timeout` command is a *sleep*, not a bound — it cannot
@@ -94,18 +94,17 @@ A hook run fails when the command:
 - exits zero but prints no non-empty stdout line,
 - or prints output that does not parse as a JSON array of row objects.
 
-What a failure *means*: **per-file isolation.** The file contributes no rows
-and is reported as skipped; the scan indexes every other file and commits.
-The CLI names up to ten skipped files on stderr, then `... and N more`, and
-exits `23` — distinct from `0` (clean) and `1` (the run failed), so a caller
-can tell a partial index from a complete one. A row the table rejects under
-`strict` counts as the same kind of failure.
+What a failure *means*: the command ran once for the whole table, so its
+failure is the table's, and a table that cannot be filled fails the build.
+The error names the table and carries the command's exit status and stderr
+tail; the CLI prints it and exits `1`. A row the table rejects under `strict`
+counts as the same kind of failure.
 
 ## `on-file` contract
 
-Runs once per file matched by the table's `glob`, at initial scan and on
-every watched change. The command reads the file itself and prints a JSON
-array of row objects; see [`[[table]]`](./config.md#table) for the
+Runs once per table, over every file matched by the table's `glob`, at
+initial scan and on every watched change. The command reads the files itself
+and prints a JSON array of row objects; see [`[[table]]`](./config.md#table) for the
 row-mapping rules.
 
 The same command is attachable two ways, over the same contract: the

package/docs/reference/path-tables.md

@@ -35,14 +35,16 @@ Two consequences follow directly:
 A `./` path is relative to the **index root** — the directory dirsql is
 indexing, not your shell's working directory.
 
-**Directories are recursive by default.** Naming a directory scans everything
-beneath it; the non-recursive form is spelled explicitly with `*`.
+**A directory name is one level, like `ls`.** Naming a directory lists the
+files directly inside it and no deeper; `*` matches one level and `**` any
+depth, as in the shell.
 
 | You write | dirsql scans |
 | --- | --- |
-| `'./'` | every file under the index root, recursively |
-| `'./docs'` | every file under `docs/`, recursively |
-| `'./*'` | files directly inside the index root, and no deeper |
+| `'./'` | files directly inside the index root, and no deeper |
+| `'./docs'`, `'./docs/'` | files directly inside `docs/` |
+| `'./*'` | the same as `'./'` |
+| `'./**'` | every file under the index root, recursively |
 | `'./docs/*.md'` | markdown files directly inside `docs/` |
 | `'./docs/**/*.md'` | markdown files at any depth under `docs/` |
 | `'./notes/today.md'` | exactly that one file — one file is one row |
@@ -87,6 +89,7 @@ Three other prefixes resolve, with their usual shell meanings:
 | `'../notes'` | relative to the index root's parent |
 | `'~/notes/*.md'` | relative to your home directory |
 
+A directory named this way is one level too; `'../notes/**'` descends.
 `..` is folded out textually, not followed through symlinks, so the directory
 scanned is a function of the string you wrote.
 
@@ -156,18 +159,14 @@ placeholder, same timeout. Its output *is* the table:
   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 the paths). 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.
+- **A parser failure is the table's failure.** A run that fails (spawn,
+  non-zero exit, a `timeout(1)` kill, or no output) or whose output is not a
+  JSON array of rows fails the query with an error naming the table; there is
+  no partial table.
 - **The skip rules still apply.** A parsed scan honors the same `node_modules`
   /`.git`/`ignore` rules a stat scan does (see below).
-- **`--persist` skips the parser for unchanged files.** With a
-  [persistent cache](/howto/persist), each file's parser output is stored
-  against its stat metadata, so a later run over an unchanged tree serves the
-  rows from the cache and spawns no process. Change the file, the glob, the
-  parser command, or the dirsql version and that file (or that whole table) is
-  parsed again.
+- **The parser runs on every start.** A parsed path-table is not kept in the
+  [persistent cache](/howto/persist); declared tables are.
 
 `--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
@@ -216,7 +215,7 @@ A path-table scan applies the same [`ignore`](/reference/config) patterns your
 declared tables use — matched against root-relative paths under the same
 [glob rule](/reference/config#glob-rule) as the path itself, `*` one level and
 `**` any depth — plus two built-in defaults so a zero-config
-`SELECT * FROM './'` does not drown in machinery:
+`SELECT * FROM './**'` does not drown in machinery:
 
 - `**/node_modules/**`
 - `**/.git/**`
@@ -246,7 +245,7 @@ Skip rules are judged from the directory the scan starts in, so pointing at a
 skipped directory — built-in or gitignored — still scans it:
 
 ```sql
-SELECT path FROM './';                     -- no node_modules rows
+SELECT path FROM './**';                   -- no node_modules rows
 SELECT path FROM './node_modules/*/package.json';  -- scans it anyway
 SELECT path FROM './dist';                 -- scans dist/ even when gitignored
 ```

package/package.json

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