dirsql 0.4.66 → 0.4.68

package/README.md

@@ -2,7 +2,7 @@
 
 Ephemeral SQL index over a local directory. `dirsql` watches a filesystem, ingests structured files into an in-memory SQLite database, and exposes a SQL query interface -- the filesystem is always the source of truth. Built on the Rust core via napi-rs bindings.
 
-[Documentation](https://thekevinscott.github.io/dirsql/?lang=typescript)
+[Documentation](https://dirsql.dev/?lang=typescript)
 
 Also available as [`dirsql` on crates.io](https://crates.io/crates/dirsql) and [`dirsql` on PyPI](https://pypi.org/project/dirsql/).
 
@@ -89,7 +89,7 @@ Each event has `.action` (`'insert'` | `'update'` | `'delete'` | `'error'`), `.t
 
 ## CLI
 
-`npx dirsql "<sql>"` runs one query and prints the rows as JSON — the default. `npx dirsql server` starts an HTTP server exposing the SDK over HTTP: `POST /query` for SQL and `GET /events` for a Server-Sent Events change stream. Requires **Node >= 20.11**. See the [CLI reference](https://thekevinscott.github.io/dirsql/reference/cli).
+`npx dirsql "<sql>"` runs one query and prints the rows as JSON — the default. `npx dirsql server` starts an HTTP server exposing the SDK over HTTP: `POST /query` for SQL and `GET /events` for a Server-Sent Events change stream. Requires **Node >= 20.11**. See the [CLI reference](https://dirsql.dev/reference/cli).
 
 ## License
 

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/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.
 
@@ -283,7 +283,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 +403,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

@@ -24,7 +24,7 @@ the config file's location. See [`--config`](./cli.md#flags).
 
 | Key | Type | Default | Description |
 |---|---|---|---|
-| `ignore` | array of strings | `[]` | Glob patterns matched against root-relative paths. Matched files are skipped entirely — excluded from the initial scan and from watch events. |
+| `ignore` | array of strings | `[]` | Glob patterns matched against root-relative paths, under the [one glob rule](#glob-rule): `*` matches one level, `**` any depth. Matched files are skipped entirely — excluded from the initial scan and from watch events. |
 
 There is no timeout key. `on-file` hook runs are unbounded; to bound one, wrap
 its command in `timeout(1)` (see [Command hooks](./hooks.md#bounding-a-hook)).
@@ -43,6 +43,16 @@ directory.
 ignore = ["node_modules/**", ".git/**"]
 ```
 
+### Glob rule
+
+Every glob in dirsql — `ignore`, a `[[table]]`'s `glob`, and a
+[path-table](./path-tables.md#writing-the-path) — reads as the shell does:
+`*` and `?` match within one path segment and never cross `/`; `**` matches
+any depth. So `ignore = ["*"]` hides only the files directly inside the root,
+`ignore = ["build/*"]` hides `build/a.o` but not `build/sub/b.o`, and
+`glob = "*.json"` selects only the top-level `.json` files; write
+`**/*.json` to select them at every depth.
+
 Persistence is not a config key. Keep the SQLite index on disk between runs
 with the [`--persist [PATH]` CLI flag](./cli.md#dirsql-server) — a machine-local
 operational choice that belongs to the runner, not to shareable config.
@@ -220,7 +230,7 @@ what its required `on-file` command emits — dirsql injects nothing (see
 |---|---|---|
 | `name` | yes | The table's SQL name — the name you query it by. Declared, never derived from `ddl`: dirsql does not read the DDL text. The `ddl` must create a table by this name; if it doesn't, loading fails. |
 | `ddl` | yes | A SQL batch, run verbatim — any number of statements. It must create a table called `name`; that table holds the file rows, and only the columns it declares are kept (keys the `on-file` command emits that are not declared are dropped). The rest of the batch is yours: indexes, virtual tables, triggers. See [Batch `ddl`](#batch-ddl). |
-| `glob` | yes | Glob pattern matched against root-relative paths. Every table whose glob matches a file receives that file's rows — a file can populate multiple tables. A `{name}` segment is rewritten to `*` (it matches one path segment but captures nothing). |
+| `glob` | yes | Glob pattern matched against root-relative paths, under the [one glob rule](#glob-rule): `*` matches one level, `**` any depth. Every table whose glob matches a file receives that file's rows — a file can populate multiple tables. A `{name}` segment is rewritten to `*` (it matches one path segment but captures nothing). |
 | `on-file` | **yes** | A command run once per table, with every matched file's absolute path appended as a trailing argument; its stdout (one JSON array of row objects) is the table's rows. Must be non-empty. A `[[table]]` with no `on-file` is a load error (see [parse errors](#parse-errors)). See [Command hooks](./hooks.md#on-file). |
 | `strict` | no (default `false`) | When `true`, rows whose keys do not exactly match the declared columns are rejected with an error: extra keys error, and every declared column must be supplied by the `on-file` output. When `false`, extra keys are dropped and missing columns become `NULL`. |
 
@@ -386,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/path-tables.md

@@ -35,20 +35,27 @@ 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 |
 
-A path containing `*`, `?` or `[` is a glob and is used exactly as written: `*`
-matches within a single directory, `**` crosses directories.
+A path containing `*`, `?`, `[` or `{` is a glob and is used exactly as
+written: `*` matches within a single directory, `**` crosses directories.
+
+The scan starts at the last directory named outright before the first glob
+component -- `'./small/*.md'` walks `small/` and nothing else -- so a query
+over one directory costs what `find ./small` costs, however large the
+directories beside it.
 
 A path naming a single file yields exactly one row. dirsql never splits a file
 into rows on its own — that is what a table's `on_file` hook is for.
@@ -82,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.
 
@@ -186,8 +194,9 @@ bug to design around.
 The table itself is per-connection: it lives in `temp`, so it cannot leak into
 `sqlite_master` or survive a restart. Under `--persist` a *parsed* table's rows
 outlive the connection in the cache (above), but the table is still minted
-fresh each run and the scan still decides what exists. The reserved top-level
-`.dirsql/` directory is excluded from the scan, as everywhere else.
+fresh each run and the scan still decides what exists. A `.dirsql/` directory
+at the top of the directory the scan starts in is reserved and excluded, as
+everywhere else.
 
 ### When to promote to a declared table
 
@@ -207,8 +216,10 @@ choice is stated as one trade in
 ## Skip rules
 
 A path-table scan applies the same [`ignore`](/reference/config) patterns your
-declared tables use, plus two built-in defaults so a zero-config
-`SELECT * FROM './'` does not drown in machinery:
+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:
 
 - `**/node_modules/**`
 - `**/.git/**`
@@ -234,17 +245,17 @@ defaults and configured `ignore` patterns still apply.
 
 ### Naming a skipped directory
 
-Skip rules are judged on the part of the path *below* what you named outright,
-so pointing at a skipped directory — built-in or gitignored — still scans it:
+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
 ```
 
-A `.gitignore` at or below the directory you named still filters beneath it;
-only rules inherited from above it are set aside.
+A `.gitignore` at or below the directory the scan starts in still filters
+beneath it; one above it is never read.
 
 ### Hidden files
 

package/docs/reference/sdk.md

@@ -116,8 +116,9 @@ shortcut was removed in #603 — use
 - `root` — Directory to index. When omitted, the index roots at the process
   cwd (even when `config` is supplied).
 - `tables` — Programmatic [`Table`](#table) definitions.
-- `ignore` — Glob patterns matched against root-relative paths; matched
-  files are skipped entirely (scan and watch).
+- `ignore` — Glob patterns matched against root-relative paths under the
+  [glob rule](./config.md#glob-rule) (`*` one level, `**` any depth);
+  matched files are skipped entirely (scan and watch).
 - `no_ignore` / `noIgnore` — Scan files a `.gitignore` would hide.
   [Path-tables](./path-tables.md#skip-rules) respect `.gitignore` files by
   default; the built-in `node_modules`/`.git` skips and any `ignore` patterns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dirsql",
-  "version": "0.4.66",
+  "version": "0.4.68",
   "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.66",
-    "@dirsql/lib-linux-arm64-gnu": "0.4.66",
-    "@dirsql/lib-darwin-x64": "0.4.66",
-    "@dirsql/lib-darwin-arm64": "0.4.66",
-    "@dirsql/lib-win32-x64-msvc": "0.4.66"
+    "@dirsql/lib-linux-x64-gnu": "0.4.68",
+    "@dirsql/lib-linux-arm64-gnu": "0.4.68",
+    "@dirsql/lib-darwin-x64": "0.4.68",
+    "@dirsql/lib-darwin-arm64": "0.4.68",
+    "@dirsql/lib-win32-x64-msvc": "0.4.68"
   }
 }