dirsql 0.4.100 → 0.4.102

package/dist/dirsql.d.ts

@@ -43,7 +43,7 @@ export interface DirSQLOptions {
     config?: string | string[];
     /**
      * Enable persistent on-disk SQLite cache. When `true`, the database is
-     * written to `<root>/.dirsql/cache.db` (override via `persistPath`) so
+     * written to the platform cache directory (override via `persistPath`) so
      * subsequent startups only re-parse files that have actually changed.
      */
     persist?: boolean;

package/docs/howto/persist.md

@@ -17,9 +17,11 @@ why it is a CLI flag, not a config key.
 dirsql --persist
 ```
 
-That's the whole change. On the next run the cache is written to
-`.dirsql/cache.db` under the root; runs after that start from it. To put
-the cache elsewhere (a CI cache dir, a tmpfs), pass a path:
+That's the whole change. On the next run the cache is written to your platform cache directory
+(`$XDG_CACHE_HOME/dirsql/<root hash>/cache.db` on Linux, `~/Library/Caches`
+on macOS, `%LOCALAPPDATA%` on Windows), outside the scanned tree; runs after
+that start from it. To put the cache elsewhere (a CI cache dir, a tmpfs), pass
+a path:
 
 ```bash
 dirsql --persist /var/cache/dirsql.db
@@ -30,20 +32,13 @@ put a bare `--persist` after the SQL there so it does not consume the query
 argument. Embedding `dirsql`? The SDK constructors expose the same switch —
 see [_Embedding `dirsql`?_](#embedding-dirsql) below.
 
-## 2. Keep the cache out of git
+## 2. Nothing to ignore in git
 
-The cache is derived data — reproducible from the tree and frequently
-large. Add it to `.gitignore`:
-
-```
-.dirsql/
-```
-
-The top-level `.dirsql/` directory is reserved for `dirsql`'s metadata and
-is never scanned as data, so the cache can't index itself
-([config reference](../reference/config.md#dirsql-keys)). While running,
-`dirsql` also creates transient `cache.db-wal` and `cache.db-shm` sidecar
-files next to the cache; the `.dirsql/` ignore already covers all three.
+The default cache lives outside the scanned tree, so there is nothing to add
+to `.gitignore` and the cache can't index itself. With `--persist <path>`, keep
+that path out of the scanned tree too, or ignore it. While running, `dirsql`
+also creates transient `cache.db-wal` and `cache.db-shm` sidecar files next to
+the cache.
 
 ## What survives, what rebuilds
 

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

@@ -67,5 +67,6 @@ 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)).
+- `.git/` is skipped by default, and a git repo's `.gitignore` hides what it
+  lists, so a bare `'./**'` does not drown in machinery
+  ([skip rules](../reference/path-tables.md#skip-rules)).

package/docs/howto/search-indexes.md

@@ -224,7 +224,7 @@ Rows are embedded once, at ingest, and cached on disk by content and model
 ::: warning Editing `ddl` wedges a persisted `vec0` cache
 Under `--persist`, editing any part of a `ddl` batch whose cache holds a
 `vec0` table currently fails with `SQLite error: no such module: vec0`, and
-keeps failing until the cache is deleted (`rm -rf <root>/.dirsql`). Tracked in
+keeps failing until the cache is deleted (delete it, or pass a fresh `--persist <path>`). Tracked in
 [#1008](https://github.com/thekevinscott/dirsql/issues/1008); FTS5 is
 unaffected.
 :::

package/docs/howto/skip-files.md

@@ -51,9 +51,6 @@ dirsql query "SELECT basename FROM notes ORDER BY basename" -c ./.dirsql.toml
   list, though its path-tables still apply the built-in
   [skip rules](../reference/path-tables.md#skip-rules) and respect
   `.gitignore`.
-- The top-level `.dirsql/` directory is always excluded, ignore list or
-  not — it is reserved for `dirsql`'s own metadata
-  ([config reference](../reference/config.md#dirsql-keys)).
 - Narrow table globs are the other half of the story: a file matching no
   table's glob contributes no rows either. Use `ignore` for things that
   should never be looked at; use precise globs to shape what each table

package/docs/reference/cli.md

@@ -248,8 +248,8 @@ Config flags are subcommand-local: pass them after `server`
 | `--host <addr>` | `localhost` | Bind address. |
 | `--port <n>` | `7117` | TCP port to bind. |
 | `--cors-origin <origin>` | off | Let browser pages on `<origin>` (an exact origin such as `http://localhost:3202`, or `*` for any) call `/query` and open `/events`. See [Cross-origin requests](#cross-origin-requests). |
-| `--persist [<path>]` | off | Keep the SQLite index on disk between runs so a restart only re-parses files that actually changed. Bare `--persist` caches at `<root>/.dirsql/cache.db`; `--persist <path>` caches at `<path>`. Off by default (the index is ephemeral). Also available on [`dirsql query`](#dirsql-query). See [Keep the index across restarts](../howto/persist.md). |
-| `--no-ignore` | off | Scan files a `.gitignore` would hide. [Path-tables](./path-tables.md#skip-rules) respect `.gitignore` files by default; this flag restores the full walk. The built-in skips (`node_modules`/`.git`) and configured `ignore` patterns still apply. Also available on [`dirsql query`](#dirsql-query). |
+| `--persist [<path>]` | off | Keep the SQLite index on disk between runs so a restart only re-parses files that actually changed. Bare `--persist` caches under the platform cache directory (`$XDG_CACHE_HOME/dirsql/<root hash>/cache.db` on Linux), outside the root; `--persist <path>` caches at `<path>`. Off by default (the index is ephemeral). Also available on [`dirsql query`](#dirsql-query). See [Keep the index across restarts](../howto/persist.md). |
+| `--no-ignore` | off | Scan files a `.gitignore` would hide. [Path-tables](./path-tables.md#skip-rules) respect `.gitignore` files by default; this flag restores the full walk. The built-in `.git` skip and configured `ignore` patterns still apply. Also available on [`dirsql query`](#dirsql-query). |
 | `--extension <path>` | none | Load a SQLite extension by literal path, overriding the config's `[[dirsql.extension]]` entries. Repeatable. Format: `<path>` or `<path>::<entrypoint>`. Internal plumbing for the pip/npm launchers, which resolve package-name extensions and pass the resolved paths here — not intended for direct use. When any `--extension` is present, the config file's own extension entries are not loaded. |
 | `--version` | | Print the version and exit. |
 | `--help` | | Print usage and exit. |

package/docs/reference/config.md

@@ -34,12 +34,6 @@ A config that still declares the removed `hook-timeout` key fails to load with
 an error naming that replacement. [`[[dirsql.function]]`](#dirsql-function)
 worker calls have their own per-call `timeout` key (default 30 seconds).
 
-The top-level `.dirsql/` directory under the root is always excluded from
-scanning, whether or not it appears in `ignore` — it is reserved for
-`dirsql`'s own metadata (the persist cache lives there by default). Only the
-top-level `.dirsql/` is reserved; a nested `sub/.dirsql/` is an ordinary
-directory.
-
 ```toml
 [dirsql]
 ignore = ["node_modules/**", ".git/**"]

package/docs/reference/glob.md

@@ -70,7 +70,7 @@ A test runs every row against dirsql as a path-table and, with the leading
 | --- | --- | --- |
 | `./*.md` | `1.md`, `2.md`, `3.md`, `4.md`, `[a].md`, `[z.md`, `a.md`, `b.md`, `c.md`, `link.md`, `my file.md`, `top.md`, `{q}.md` |  |
 | `./**/*.md` | `1.md`, `2.md`, `3.md`, `4.md`, `[a].md`, `[z.md`, `a.md`, `b.md`, `c.md`, `docs/api.md`, `docs/guide.md`, `docs/nested/deep.md`, `link.md`, `linkdir/r.md`, `my file.md`, `real/r.md`, `top.md`, `{q}.md` |  |
-| `./**` | `1.md`, `2.md`, `3.md`, `4.md`, `[a].md`, `[z.md`, `a.md`, `b.md`, `c.md`, `docs/api.md`, `docs/guide.md`, `docs/nested/deep.md`, `link.md`, `my file.md`, `real/r.md`, `top.md`, `x.txt`, `{q}.md` |  |
+| `./**` | `1.md`, `2.md`, `3.md`, `4.md`, `[a].md`, `[z.md`, `a.md`, `b.md`, `c.md`, `docs/api.md`, `docs/guide.md`, `docs/nested/deep.md`, `link.md`, `my file.md`, `node_modules/pkg/index.js`, `real/r.md`, `top.md`, `x.txt`, `{q}.md` |  |
 | `./?.md` | `1.md`, `2.md`, `3.md`, `4.md`, `a.md`, `b.md`, `c.md` |  |
 | `./[ab].md` | `a.md`, `b.md` |  |
 | `./[!a].md` | `1.md`, `2.md`, `3.md`, `4.md`, `b.md`, `c.md` |  |
@@ -96,7 +96,7 @@ A test runs every row against dirsql as a path-table and, with the leading
 | `./*/` | `docs/api.md`, `docs/guide.md`, `linkdir/r.md`, `real/r.md` | directory-name |
 | `./d*` | none | files-only |
 | `./*.log` | none | gitignore |
-| `./**/*.js` | none | node-modules |
+| `./**/*.js` | `node_modules/pkg/index.js` |  |
 | `./node_modules/*/index.js` | `node_modules/pkg/index.js` |  |
 | `./docs/**/*.md` | `docs/api.md`, `docs/guide.md`, `docs/nested/deep.md` |  |
 | `./docs/*.md` | `docs/api.md`, `docs/guide.md` |  |
@@ -111,7 +111,6 @@ A test runs every row against dirsql as a path-table and, with the leading
 | `gitignore` | Inside a git repo, `.gitignore` files hide matching files and directories. `--no-ignore` turns it off. | A query over a repo should not drown in build output. |
 | `directory-name` | A pattern's last component that names a directory lists the files directly inside it, like `ls docs`. A trailing `/` is `*` appended. | A table is rows of files, and `ls` is the shell habit. |
 | `files-only` | A pattern that matches a directory but no file returns nothing. | Every row is a file. |
-| `node-modules` | A `node_modules` directory is skipped unless the pattern spells its name. | A zero-config `./**` should not walk dependencies. |
 | `absolute` | `/`, `~/` and `../` patterns report absolute `path` values, with `..` folded out textually. | The scanned root is derived from the pattern, so there is no relative base. |
 
 `.git` needs no rule of its own: the dotfile rule hides it.

package/docs/reference/path-tables.md

@@ -198,8 +198,8 @@ over a very large table. Its output *is* the table:
   ```
   dirsql_parsed: parser produced no rows for `posts/*.md`; cannot infer a schema
   ```
-- **The skip rules still apply.** A parsed scan honors the same `node_modules`
-  /`.git`/`ignore` rules a stat scan does (see below).
+- **The skip rules still apply.** A parsed scan honors the same `.git`
+  /`ignore` rules a stat scan does (see below).
 - **The parser runs on every start.** A parsed path-table is not kept in the
   [persistent cache](/howto/persist); declared tables are.
 
@@ -228,8 +228,7 @@ 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. A `.dirsql/` directory
-at the top of the directory the scan starts in is reserved and excluded, as
-everywhere else.
+is an ordinary dot directory.
 
 ### When to promote to a declared table
 
@@ -251,14 +250,9 @@ choice is stated as one trade in
 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:
-
-- `**/node_modules/**`
-- `**/.git/**`
-
-Both apply at any depth, so a `node_modules` nested inside a subdirectory is
-skipped just like one at the top.
+`**` any depth — plus one built-in default, `**/.git/**`, which applies at any depth.
+`node_modules` is an ordinary directory: a `.gitignore` that lists it hides it,
+as it hides any other.
 
 ### `.gitignore`
 
@@ -266,9 +260,7 @@ Path-table scans also respect `.gitignore` files by default, inside a git
 repo, the way git, fd and ripgrep do: a `.gitignore` applies below its own
 directory, deeper files override shallower ones, `!pattern` re-includes, and
 an ignored directory is pruned rather than walked. In a typical repo this
-excludes build output, virtualenvs, and caches with zero ceremony. The
-built-in defaults above remain as a floor for directories with no
-`.gitignore` at all.
+excludes build output, virtualenvs, and caches with zero ceremony.
 
 A `.gitignore` is in force only when a directory holding `.git` encloses it.
 Outside a repo none applies, at the scan's start, above it or below it: a
@@ -280,7 +272,7 @@ applies, including those above the directory a scan starts in, so
 Pass [`--no-ignore`](./cli.md#flags) to restore the full walk — the
 determinism switch for scripted use, since results otherwise depend on
 `.gitignore` state. It disables only the `.gitignore` respect; the built-in
-defaults and configured `ignore` patterns still apply.
+default and configured `ignore` patterns still apply.
 
 ### Naming a skipped directory
 
@@ -288,23 +280,13 @@ 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 './node_modules/*/package.json';  -- scans it anyway
+SELECT path FROM './.git/*';               -- scans .git anyway
 SELECT path FROM './dist';                 -- scans dist/ even when gitignored
 ```
 
 The `.gitignore` files in force there, including those above it, still
 filter what lies beneath it.
 
-A `node_modules` component after a glob names it too, at any depth:
-
-```sql
-SELECT path FROM './**/node_modules/*/package.json';  -- every node_modules
-SELECT path FROM './*/node_modules/**';               -- one level down
-```
-
-Only the literal name counts; `'./**/*.js'` still skips every `node_modules`.
-
 ### Hidden files
 
 A path component starting with `.` is skipped unless the path spells it, the

package/docs/reference/sdk.md

@@ -86,7 +86,7 @@ DirSQL::builder()
     .config(config_toml_path)       // optional; repeatable — call again to
                                     //   merge another config in call order
     .persist(cache_path)            // optional; Some(path), or None for the
-                                    //   default <root>/.dirsql/cache.db
+                                    //   platform cache dir
     .extensions(extensions)         // optional; append one with .extension(e)
     .poll_interval(duration)        // optional; watch-loop cadence, default 200ms
     .build()                        // -> Result<DirSQL>  (synchronous scan)
@@ -123,7 +123,7 @@ shortcut was removed in #603 — use
   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
+  default; the built-in `.git` skip and any `ignore` patterns
   still apply. The CLI's [`--no-ignore`](./cli.md#flags).
 - `config` — Path to a [`.dirsql.toml`](./config.md). Its `[[table]]`
   entries are appended after any programmatic `tables`; its `ignore`
@@ -139,8 +139,8 @@ shortcut was removed in #603 — use
   accumulate; a duplicate table name across configs errors), mirroring the
   CLI's repeatable [`-c/--config`](./cli.md#flags).
 - `persist` — Keep the SQLite index on disk between runs (default off:
-  ephemeral, rebuilt every startup). The cache lives at
-  `<root>/.dirsql/cache.db` by default; on restart, only files whose stat
+  ephemeral, rebuilt every startup). The cache lives in the
+  platform cache directory by default (outside `<root>`); on restart, only files whose stat
   changed are re-parsed. (The CLI exposes the same switch as the
   [`--persist [PATH]`](./cli.md#dirsql-server) flag; it is not a config key.)
 - `persist_path` / `persistPath` — Override the cache location. Ignored when

package/package.json

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