dirsql 0.3.40__tar.gz → 0.3.42__tar.gz

{dirsql-0.3.40 → dirsql-0.3.42}/Cargo.lock

@@ -499,7 +499,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.3.40"
+version = "0.3.42"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.3.40 → dirsql-0.3.42}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.3.40
+Version: 0.3.42
 Requires-Dist: pytest>=8 ; extra == 'dev'
 Requires-Dist: pytest-describe>=2 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'

{dirsql-0.3.40 → dirsql-0.3.42}/dirsql/_async.py

@@ -1,20 +1,8 @@
 """Async-by-default DirSQL wrapper."""
 
 import asyncio
-from typing import TYPE_CHECKING
 
 from dirsql._dirsql import DirSQL as _RustDirSQL
-from dirsql.resolve_config import resolve_config
-
-if TYPE_CHECKING:
-    # `typing.override` is 3.12+; the package supports 3.11, so source it from
-    # `typing_extensions` for the type checker only. At runtime `@override` is
-    # a pure marker, so a no-op identity avoids the runtime dependency.
-    from typing_extensions import override
-else:
-
-    def override(func):
-        return func
 
 
 class _WatchStream:
@@ -55,9 +43,10 @@ class DirSQL:
         async for event in db.watch():
             ...
 
-    At least one of ``root`` or ``config`` must be supplied. When both are
-    set, the explicit ``root`` wins over any ``[dirsql].root`` in the config
-    file (a warning is emitted on stderr).
+    Supply a ``root``, a ``config`` path, or both. When both are set, the
+    explicit ``root`` wins over any ``[dirsql].root`` in the config file (a
+    warning is emitted on stderr). If neither is given, the initial scan
+    fails with a "no root directory" error raised by the core.
 
     Pass ``persist=True`` to keep an on-disk SQLite cache (default location:
     ``<root>/.dirsql/cache.db``). Override the location with ``persist_path``.
@@ -79,8 +68,6 @@ class DirSQL:
         persist_path=None,
         extensions=None,
     ):
-        if root is None and config is None:
-            raise TypeError("DirSQL requires either a root directory or a config= path")
         self._root = root
         self._tables = tables
         self._ignore = ignore
@@ -136,21 +123,3 @@ class DirSQL:
     def watch(self):
         """Start watching for file changes. Returns an async iterable of RowEvent."""
         return _WatchStream(self._db)
-
-    @property
-    @override
-    def __dict__(self):
-        """Resolved construction state as a JSON-serializable dict.
-
-        Recomputed on each access; reads the ``.dirsql.toml`` if ``config=``
-        was supplied. Works before ``await db.ready()``.
-        """
-        return resolve_config(
-            self._root,
-            self._tables,
-            self._ignore,
-            self._config,
-            self._persist,
-            self._persist_path,
-            self._extensions,
-        )

dirsql-0.3.42/dirsql/cli/interpret/__init__.py

@@ -0,0 +1,14 @@
+"""Empty package shell — the native-config ``interpret`` helper was removed.
+
+The ``dirsql interpret`` subcommand and its NDJSON ``extract`` loop (``run``,
+``load_app``, ``dispatch_extract``, ``write_message``) were removed in #321
+(#323). The CLI now accepts only ``.dirsql.toml``; to run user-defined
+``extract`` callbacks, use the programmatic SDK (``DirSQL(...)`` with
+in-process closures).
+
+This ``__init__.py`` carries no logic and no re-exports. It remains only
+because the colocated-test tooling cannot yet express *deleting* an exempt
+package barrel (the co-change check flags a deleted source that has no
+co-deleted colocated test, and a retained exempt for a deleted path is
+rejected as stale). The directory is removed once that is resolved.
+"""

{dirsql-0.3.40 → dirsql-0.3.42}/dirsql/cli/main.py

@@ -1,8 +1,6 @@
 """Console-script entry point. Execs the bundled binary on POSIX,
-subprocesses it on Windows. When ``argv[0] == "interpret"`` the
-in-process Python helper handles the subcommand directly so a Rust
-orchestrator can spawn this script for native-language configs (#196)
-without depending on the bundled Rust binary."""
+subprocesses it on Windows. All argv is forwarded transparently to the
+bundled Rust binary."""
 
 from __future__ import annotations
 
@@ -18,14 +16,6 @@ def main(argv: list[str] | None = None) -> int:
     if argv is None:
         argv = sys.argv[1:]
 
-    if argv and argv[0] == "interpret":
-        from .interpret.run import run
-
-        try:
-            return run(argv[1:])
-        except KeyboardInterrupt:
-            return 130
-
     try:
         binary = binary_path()
     except FileNotFoundError as exc:

{dirsql-0.3.40/packages/python → dirsql-0.3.42}/docs/.vitepress/config.ts

@@ -19,19 +19,12 @@ export default defineConfig({
       { text: 'GitHub', link: 'https://github.com/thekevinscott/dirsql' }
     ],
 
+    // A single global sidebar shown on every page. The CLI section is a
+    // self-contained group with all its subpages -- but it never *replaces*
+    // the rest of the nav. There is intentionally no path-scoped (`/cli/`)
+    // key: a path-scoped sidebar swaps the whole tree out, which deletes the
+    // other sections when you enter CLI (see #301). Keep one sidebar.
     sidebar: {
-      '/cli/': [
-        {
-          text: 'CLI',
-          items: [
-            { text: 'Overview & Installation', link: '/cli/' },
-            { text: 'Running the Server', link: '/cli/server' },
-            { text: 'Generating a Config (`init`)', link: '/cli/init' },
-            { text: 'Configuration File', link: '/cli/config' },
-            { text: 'HTTP API', link: '/cli/http-api' }
-          ]
-        }
-      ],
       '/': [
         {
           text: 'Tutorials',
@@ -53,7 +46,11 @@ export default defineConfig({
         {
           text: 'CLI',
           items: [
-            { text: 'Using `dirsql` from the CLI', link: '/cli/' }
+            { text: 'Overview & Installation', link: '/cli/' },
+            { text: 'Running the Server', link: '/cli/server' },
+            { text: 'Generating a Config (`init`)', link: '/cli/init' },
+            { text: 'Configuration File', link: '/cli/config' },
+            { text: 'HTTP API', link: '/cli/http-api' }
           ]
         },
         {

{dirsql-0.3.40/packages/rust → dirsql-0.3.42}/docs/api/index.md

@@ -59,6 +59,7 @@ new DirSQL({
     tables?: TableDef[],
     ignore?: string[],
     config?: string,
+    extensions?: ExtensionSpec[],  // [{ path: string, entrypoint?: string }]
 })
 ```
 
@@ -76,7 +77,7 @@ In Python, the constructor starts scanning in a background thread and returns im
 - `tables` -- List of `Table` definitions. Each defines a SQLite table, a glob pattern, and an extract function.
 - `ignore` -- Optional list of glob patterns. Files matching any ignore pattern are skipped regardless of table globs.
 - `config` -- Optional path to a `.dirsql.toml` config file. Its `[[table]]` entries are appended to any programmatic `tables`; its `[dirsql].ignore` patterns are appended to any explicit `ignore`; its optional `[dirsql].root` supplies the root directory when `root` is not passed explicitly; its `[[dirsql.extension]]` entries are appended to any programmatic `extensions`.
-- `extensions` -- Optional SQLite extensions to load onto the connection at startup, before any table DDL (enable → load → disable, so the SQL `load_extension()` function is never left exposed). Each entry pairs a shared-library `path` with an optional `entrypoint` init-symbol override (Python: `{ "path", "entrypoint"? }` dicts; Rust: `Extension { path, entrypoint }`). Programmatic entries load first, then any `[[dirsql.extension]]` from `config`. Available in the Python and Rust SDKs; the TypeScript constructor parameter is tracked in [#230](https://github.com/thekevinscott/dirsql/issues/230). See [Loading extensions](../cli/config.md#loading-extensions).
+- `extensions` -- Optional SQLite extensions to load onto the connection at startup, before any table DDL (enable → load → disable, so the SQL `load_extension()` function is never left exposed). Each entry pairs a shared-library `path` with an optional `entrypoint` init-symbol override (Python: `{ "path", "entrypoint"? }` dicts; Rust: `Extension { path, entrypoint }`; TypeScript: `{ path, entrypoint? }` objects). Programmatic entries load first, then any `[[dirsql.extension]]` from `config`. Available in the Python, Rust, and TypeScript SDKs. See [Loading extensions](../cli/config.md#loading-extensions).
 
 ### Methods
 
@@ -162,7 +163,7 @@ JSON.stringify(db)  // via db.toJSON()
 
 :::
 
-Returns the resolved construction state as a JSON-compatible value with fields `root`, `tables`, `ignore`, `persist`, `persist_path` (camelCase `persistPath` in TypeScript). Each table is `{ ddl, glob, strict }`. The Python and Rust snapshots also include `extensions` -- an array of `{ path, entrypoint }` (empty when none are configured); the TypeScript `toJSON` snapshot will gain it with [#230](https://github.com/thekevinscott/dirsql/issues/230). Excludes the original `config` path (already merged into `root` / `tables` / `ignore`), per-table `extract`, and per-table `name`. Available immediately after construction in Python and TypeScript; Rust's sync `build()` returns a ready instance.
+Returns the resolved construction state as a JSON-compatible value with fields `root`, `tables`, `ignore`, `persist`, `persist_path` (camelCase `persistPath` in TypeScript). Each table is `{ ddl, glob, strict }`. All three SDK snapshots also include `extensions` -- an array of `{ path, entrypoint }` (empty when none are configured; `entrypoint` is `null` when no override was supplied). Excludes the original `config` path (already merged into `root` / `tables` / `ignore`), per-table `extract`, and per-table `name`. Available immediately after construction in Python and TypeScript; Rust's sync `build()` returns a ready instance.
 
 ---
 

{dirsql-0.3.40/packages/python → dirsql-0.3.42}/docs/cli/config.md

@@ -239,7 +239,7 @@ def extract_meta(path):
 
 # Python must export a module-level `app`.
 app = DirSQL(
-    root="papers",  # required — see "Set a root" below
+    root="papers",  # optional; defaults to the current directory
     tables=[
         Table(
             ddl="CREATE TABLE papers (title TEXT, _path TEXT)",
@@ -269,7 +269,7 @@ import { readFileSync } from "node:fs";
 import { DirSQL } from "dirsql";
 
 export default new DirSQL({
-  root: "papers", // required — see "Set a root" below
+  root: "papers", // optional; defaults to the current directory
   tables: [
     {
       ddl: "CREATE TABLE papers (title TEXT, _path TEXT)",
@@ -285,7 +285,7 @@ const { readFileSync } = require("node:fs");
 const { DirSQL } = require("dirsql");
 
 module.exports = new DirSQL({
-  root: "papers", // required — see "Set a root" below
+  root: "papers", // optional; defaults to the current directory
   tables: [
     {
       ddl: "CREATE TABLE papers (title TEXT, _path TEXT)",
@@ -308,10 +308,15 @@ These apply to both the Python and JavaScript forms above.
   package) uses `module.exports = new DirSQL(...)`. Only the extension
   matters — the file can be named anything; `dirsql.config.{py,mjs,cjs}` is the
   suggested convention, not a requirement.
-- **Set a `root`.** Unlike TOML configs (which default the scan root to the
-  config file's directory), native-language configs require an explicit `root`.
-  Without one the Python launcher errors and the JavaScript launcher silently
-  indexes nothing.
+- **`root` defaults to the current directory.** A native-language config with
+  no `root` indexes the process's current working directory — the directory you
+  ran `dirsql` from. (This differs from TOML configs, which default the scan
+  root to the config file's own directory.) Pass `root` explicitly to index
+  somewhere else.
+- **No nested `config=`.** A native-language config builds its `DirSQL` from
+  `tables` and an optional `root`; it must not itself set `config=` to delegate
+  to another config file. `dirsql interpret` rejects such a config (a nested
+  config can't be represented in the handshake and would recurse).
 - **Install the launcher on your `PATH`.** To run your `extract`, the server
   spawns `dirsql interpret`, so the matching `dirsql` launcher must be installed
   and on your `PATH` — a global `pip`/`uv` install for `.py`, or `npm` for

{dirsql-0.3.40/packages/rust → dirsql-0.3.42}/docs/cli/index.md

@@ -20,7 +20,7 @@ Everything you need to run `dirsql` as a CLI lives in this section:
 - **[Configuration File](./config.md)** — the `.dirsql.toml` format and the
   `.py` / `.js` native-language alternative. Custom tables
   are defined through a config file; without one, the server runs in
-  [zero-config mode](./server.md#zero-config-mode).
+  [zero-config mode](./server.md#defaults).
 - **[HTTP API](./http-api.md)** — the `POST /query` and `GET /events`
   endpoints, status codes, and event streaming.
 

dirsql-0.3.42/docs/tests/integration/sidebar.spec.ts

@@ -0,0 +1,46 @@
+import { expect, test } from '@playwright/test'
+
+// Regression for #301: entering the CLI section must NOT replace the sidebar.
+// The full set of sections has to stay visible on every page, including
+// `/cli/*`, so navigation never loses its place.
+const SECTIONS = ['Tutorials', 'How-to Guides', 'CLI', 'Reference']
+
+async function sidebarSections(page: import('@playwright/test').Page) {
+  return await page.evaluate(() =>
+    Array.from(document.querySelectorAll('.VPSidebar .group .text'))
+      .map((el) => el.textContent?.trim())
+      .filter(Boolean)
+  )
+}
+
+for (const path of ['guide/tables.html', 'cli/index.html', 'cli/server.html']) {
+  test(`every section stays in the sidebar on ${path}`, async ({ page }) => {
+    await page.goto(`./${path}`)
+    await page.waitForSelector('.VPSidebar .group')
+    const sections = await sidebarSections(page)
+    for (const section of SECTIONS) {
+      expect(sections).toContain(section)
+    }
+  })
+}
+
+test('the CLI sidebar group lists all CLI subpages', async ({ page }) => {
+  await page.goto('./cli/index.html')
+  await page.waitForSelector('.VPSidebar .group')
+  const cliLinks = await page.evaluate(() => {
+    const groups = Array.from(document.querySelectorAll('.VPSidebar .group'))
+    const cli = groups.find(
+      (g) => g.querySelector('.text')?.textContent?.trim() === 'CLI'
+    )
+    return Array.from(cli?.querySelectorAll('a') ?? []).map(
+      (a) => new URL((a as HTMLAnchorElement).href).pathname
+    )
+  })
+  expect(cliLinks).toEqual([
+    '/dirsql/cli/',
+    '/dirsql/cli/server.html',
+    '/dirsql/cli/init.html',
+    '/dirsql/cli/config.html',
+    '/dirsql/cli/http-api.html'
+  ])
+})

dirsql-0.3.42/docs/tests/unit/config.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest'
+import config from '../../.vitepress/config'
+
+type SidebarItem = { text?: string; link?: string; items?: SidebarItem[] }
+
+describe('vitepress config', () => {
+  it('has the expected site title and base path', () => {
+    expect(config.title).toBe('dirsql')
+    expect(config.base).toBe('/dirsql/')
+  })
+
+  // Regression guard: CLI docs live in their own `/cli/` section, not
+  // interleaved with the SDK how-to guides (see #179).
+  it('keeps CLI pages out of the How-to Guides group', () => {
+    const sidebar = config.themeConfig!.sidebar as Record<string, SidebarItem[]>
+    const howTo = sidebar['/'].find((group) => group.text === 'How-to Guides')
+    const links = (howTo!.items ?? []).map((item) => item.link)
+    expect(links).not.toContain('/guide/cli')
+    expect(links).not.toContain('/guide/init')
+    expect(links).not.toContain('/guide/config')
+  })
+
+  // Regression guard: the sidebar must never *replace* itself when entering a
+  // section. A path-scoped key (e.g. `/cli/`) swaps the whole tree out, which
+  // deletes the other sections and reads as the nav breaking (see #301). There
+  // must be exactly one global `/` sidebar.
+  it('has a single global sidebar with no replacing path-scoped keys', () => {
+    const sidebar = config.themeConfig!.sidebar as Record<string, SidebarItem[]>
+    expect(Object.keys(sidebar)).toEqual(['/'])
+  })
+
+  // The CLI section is self-contained: its group carries all CLI subpages,
+  // alongside (never instead of) the other sections (see #301).
+  it('shows every CLI subpage in a self-contained CLI group', () => {
+    const sidebar = config.themeConfig!.sidebar as Record<string, SidebarItem[]>
+    const groupTexts = sidebar['/'].map((group) => group.text)
+    expect(groupTexts).toEqual(['Tutorials', 'How-to Guides', 'CLI', 'Reference'])
+
+    const cli = sidebar['/'].find((group) => group.text === 'CLI')
+    const links = (cli!.items ?? []).map((item) => item.link)
+    expect(links).toEqual([
+      '/cli/',
+      '/cli/server',
+      '/cli/init',
+      '/cli/config',
+      '/cli/http-api'
+    ])
+  })
+})

{dirsql-0.3.40 → dirsql-0.3.42}/packages/python/Cargo.toml

@@ -4,7 +4,7 @@ name = "dirsql-py-ext"
 # pypi/maturin handler can rewrite it via `write-version` before
 # `maturin build`. `pyproject.toml` declares `dynamic = ["version"]`
 # and maturin reads this field. Mirrors `packages/rust/Cargo.toml`.
-version = "0.3.40"
+version = "0.3.42"
 edition.workspace = true
 publish = false
 readme = "README.md"

{dirsql-0.3.40 → dirsql-0.3.42/packages/python}/docs/.vitepress/config.ts

@@ -19,19 +19,12 @@ export default defineConfig({
       { text: 'GitHub', link: 'https://github.com/thekevinscott/dirsql' }
     ],
 
+    // A single global sidebar shown on every page. The CLI section is a
+    // self-contained group with all its subpages -- but it never *replaces*
+    // the rest of the nav. There is intentionally no path-scoped (`/cli/`)
+    // key: a path-scoped sidebar swaps the whole tree out, which deletes the
+    // other sections when you enter CLI (see #301). Keep one sidebar.
     sidebar: {
-      '/cli/': [
-        {
-          text: 'CLI',
-          items: [
-            { text: 'Overview & Installation', link: '/cli/' },
-            { text: 'Running the Server', link: '/cli/server' },
-            { text: 'Generating a Config (`init`)', link: '/cli/init' },
-            { text: 'Configuration File', link: '/cli/config' },
-            { text: 'HTTP API', link: '/cli/http-api' }
-          ]
-        }
-      ],
       '/': [
         {
           text: 'Tutorials',
@@ -53,7 +46,11 @@ export default defineConfig({
         {
           text: 'CLI',
           items: [
-            { text: 'Using `dirsql` from the CLI', link: '/cli/' }
+            { text: 'Overview & Installation', link: '/cli/' },
+            { text: 'Running the Server', link: '/cli/server' },
+            { text: 'Generating a Config (`init`)', link: '/cli/init' },
+            { text: 'Configuration File', link: '/cli/config' },
+            { text: 'HTTP API', link: '/cli/http-api' }
           ]
         },
         {

{dirsql-0.3.40 → dirsql-0.3.42/packages/python}/docs/api/index.md

@@ -59,6 +59,7 @@ new DirSQL({
     tables?: TableDef[],
     ignore?: string[],
     config?: string,
+    extensions?: ExtensionSpec[],  // [{ path: string, entrypoint?: string }]
 })
 ```
 
@@ -76,7 +77,7 @@ In Python, the constructor starts scanning in a background thread and returns im
 - `tables` -- List of `Table` definitions. Each defines a SQLite table, a glob pattern, and an extract function.
 - `ignore` -- Optional list of glob patterns. Files matching any ignore pattern are skipped regardless of table globs.
 - `config` -- Optional path to a `.dirsql.toml` config file. Its `[[table]]` entries are appended to any programmatic `tables`; its `[dirsql].ignore` patterns are appended to any explicit `ignore`; its optional `[dirsql].root` supplies the root directory when `root` is not passed explicitly; its `[[dirsql.extension]]` entries are appended to any programmatic `extensions`.
-- `extensions` -- Optional SQLite extensions to load onto the connection at startup, before any table DDL (enable → load → disable, so the SQL `load_extension()` function is never left exposed). Each entry pairs a shared-library `path` with an optional `entrypoint` init-symbol override (Python: `{ "path", "entrypoint"? }` dicts; Rust: `Extension { path, entrypoint }`). Programmatic entries load first, then any `[[dirsql.extension]]` from `config`. Available in the Python and Rust SDKs; the TypeScript constructor parameter is tracked in [#230](https://github.com/thekevinscott/dirsql/issues/230). See [Loading extensions](../cli/config.md#loading-extensions).
+- `extensions` -- Optional SQLite extensions to load onto the connection at startup, before any table DDL (enable → load → disable, so the SQL `load_extension()` function is never left exposed). Each entry pairs a shared-library `path` with an optional `entrypoint` init-symbol override (Python: `{ "path", "entrypoint"? }` dicts; Rust: `Extension { path, entrypoint }`; TypeScript: `{ path, entrypoint? }` objects). Programmatic entries load first, then any `[[dirsql.extension]]` from `config`. Available in the Python, Rust, and TypeScript SDKs. See [Loading extensions](../cli/config.md#loading-extensions).
 
 ### Methods
 
@@ -162,7 +163,7 @@ JSON.stringify(db)  // via db.toJSON()
 
 :::
 
-Returns the resolved construction state as a JSON-compatible value with fields `root`, `tables`, `ignore`, `persist`, `persist_path` (camelCase `persistPath` in TypeScript). Each table is `{ ddl, glob, strict }`. The Python and Rust snapshots also include `extensions` -- an array of `{ path, entrypoint }` (empty when none are configured); the TypeScript `toJSON` snapshot will gain it with [#230](https://github.com/thekevinscott/dirsql/issues/230). Excludes the original `config` path (already merged into `root` / `tables` / `ignore`), per-table `extract`, and per-table `name`. Available immediately after construction in Python and TypeScript; Rust's sync `build()` returns a ready instance.
+Returns the resolved construction state as a JSON-compatible value with fields `root`, `tables`, `ignore`, `persist`, `persist_path` (camelCase `persistPath` in TypeScript). Each table is `{ ddl, glob, strict }`. All three SDK snapshots also include `extensions` -- an array of `{ path, entrypoint }` (empty when none are configured; `entrypoint` is `null` when no override was supplied). Excludes the original `config` path (already merged into `root` / `tables` / `ignore`), per-table `extract`, and per-table `name`. Available immediately after construction in Python and TypeScript; Rust's sync `build()` returns a ready instance.
 
 ---
 

{dirsql-0.3.40 → dirsql-0.3.42/packages/python}/docs/cli/config.md

@@ -239,7 +239,7 @@ def extract_meta(path):
 
 # Python must export a module-level `app`.
 app = DirSQL(
-    root="papers",  # required — see "Set a root" below
+    root="papers",  # optional; defaults to the current directory
     tables=[
         Table(
             ddl="CREATE TABLE papers (title TEXT, _path TEXT)",
@@ -269,7 +269,7 @@ import { readFileSync } from "node:fs";
 import { DirSQL } from "dirsql";
 
 export default new DirSQL({
-  root: "papers", // required — see "Set a root" below
+  root: "papers", // optional; defaults to the current directory
   tables: [
     {
       ddl: "CREATE TABLE papers (title TEXT, _path TEXT)",
@@ -285,7 +285,7 @@ const { readFileSync } = require("node:fs");
 const { DirSQL } = require("dirsql");
 
 module.exports = new DirSQL({
-  root: "papers", // required — see "Set a root" below
+  root: "papers", // optional; defaults to the current directory
   tables: [
     {
       ddl: "CREATE TABLE papers (title TEXT, _path TEXT)",
@@ -308,10 +308,15 @@ These apply to both the Python and JavaScript forms above.
   package) uses `module.exports = new DirSQL(...)`. Only the extension
   matters — the file can be named anything; `dirsql.config.{py,mjs,cjs}` is the
   suggested convention, not a requirement.
-- **Set a `root`.** Unlike TOML configs (which default the scan root to the
-  config file's directory), native-language configs require an explicit `root`.
-  Without one the Python launcher errors and the JavaScript launcher silently
-  indexes nothing.
+- **`root` defaults to the current directory.** A native-language config with
+  no `root` indexes the process's current working directory — the directory you
+  ran `dirsql` from. (This differs from TOML configs, which default the scan
+  root to the config file's own directory.) Pass `root` explicitly to index
+  somewhere else.
+- **No nested `config=`.** A native-language config builds its `DirSQL` from
+  `tables` and an optional `root`; it must not itself set `config=` to delegate
+  to another config file. `dirsql interpret` rejects such a config (a nested
+  config can't be represented in the handshake and would recurse).
 - **Install the launcher on your `PATH`.** To run your `extract`, the server
   spawns `dirsql interpret`, so the matching `dirsql` launcher must be installed
   and on your `PATH` — a global `pip`/`uv` install for `.py`, or `npm` for

{dirsql-0.3.40 → dirsql-0.3.42/packages/python}/docs/cli/index.md

@@ -20,7 +20,7 @@ Everything you need to run `dirsql` as a CLI lives in this section:
 - **[Configuration File](./config.md)** — the `.dirsql.toml` format and the
   `.py` / `.js` native-language alternative. Custom tables
   are defined through a config file; without one, the server runs in
-  [zero-config mode](./server.md#zero-config-mode).
+  [zero-config mode](./server.md#defaults).
 - **[HTTP API](./http-api.md)** — the `POST /query` and `GET /events`
   endpoints, status codes, and event streaming.
 

dirsql-0.3.42/packages/python/docs/tests/integration/sidebar.spec.ts

@@ -0,0 +1,46 @@
+import { expect, test } from '@playwright/test'
+
+// Regression for #301: entering the CLI section must NOT replace the sidebar.
+// The full set of sections has to stay visible on every page, including
+// `/cli/*`, so navigation never loses its place.
+const SECTIONS = ['Tutorials', 'How-to Guides', 'CLI', 'Reference']
+
+async function sidebarSections(page: import('@playwright/test').Page) {
+  return await page.evaluate(() =>
+    Array.from(document.querySelectorAll('.VPSidebar .group .text'))
+      .map((el) => el.textContent?.trim())
+      .filter(Boolean)
+  )
+}
+
+for (const path of ['guide/tables.html', 'cli/index.html', 'cli/server.html']) {
+  test(`every section stays in the sidebar on ${path}`, async ({ page }) => {
+    await page.goto(`./${path}`)
+    await page.waitForSelector('.VPSidebar .group')
+    const sections = await sidebarSections(page)
+    for (const section of SECTIONS) {
+      expect(sections).toContain(section)
+    }
+  })
+}
+
+test('the CLI sidebar group lists all CLI subpages', async ({ page }) => {
+  await page.goto('./cli/index.html')
+  await page.waitForSelector('.VPSidebar .group')
+  const cliLinks = await page.evaluate(() => {
+    const groups = Array.from(document.querySelectorAll('.VPSidebar .group'))
+    const cli = groups.find(
+      (g) => g.querySelector('.text')?.textContent?.trim() === 'CLI'
+    )
+    return Array.from(cli?.querySelectorAll('a') ?? []).map(
+      (a) => new URL((a as HTMLAnchorElement).href).pathname
+    )
+  })
+  expect(cliLinks).toEqual([
+    '/dirsql/cli/',
+    '/dirsql/cli/server.html',
+    '/dirsql/cli/init.html',
+    '/dirsql/cli/config.html',
+    '/dirsql/cli/http-api.html'
+  ])
+})

dirsql-0.3.42/packages/python/docs/tests/unit/config.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest'
+import config from '../../.vitepress/config'
+
+type SidebarItem = { text?: string; link?: string; items?: SidebarItem[] }
+
+describe('vitepress config', () => {
+  it('has the expected site title and base path', () => {
+    expect(config.title).toBe('dirsql')
+    expect(config.base).toBe('/dirsql/')
+  })
+
+  // Regression guard: CLI docs live in their own `/cli/` section, not
+  // interleaved with the SDK how-to guides (see #179).
+  it('keeps CLI pages out of the How-to Guides group', () => {
+    const sidebar = config.themeConfig!.sidebar as Record<string, SidebarItem[]>
+    const howTo = sidebar['/'].find((group) => group.text === 'How-to Guides')
+    const links = (howTo!.items ?? []).map((item) => item.link)
+    expect(links).not.toContain('/guide/cli')
+    expect(links).not.toContain('/guide/init')
+    expect(links).not.toContain('/guide/config')
+  })
+
+  // Regression guard: the sidebar must never *replace* itself when entering a
+  // section. A path-scoped key (e.g. `/cli/`) swaps the whole tree out, which
+  // deletes the other sections and reads as the nav breaking (see #301). There
+  // must be exactly one global `/` sidebar.
+  it('has a single global sidebar with no replacing path-scoped keys', () => {
+    const sidebar = config.themeConfig!.sidebar as Record<string, SidebarItem[]>
+    expect(Object.keys(sidebar)).toEqual(['/'])
+  })
+
+  // The CLI section is self-contained: its group carries all CLI subpages,
+  // alongside (never instead of) the other sections (see #301).
+  it('shows every CLI subpage in a self-contained CLI group', () => {
+    const sidebar = config.themeConfig!.sidebar as Record<string, SidebarItem[]>
+    const groupTexts = sidebar['/'].map((group) => group.text)
+    expect(groupTexts).toEqual(['Tutorials', 'How-to Guides', 'CLI', 'Reference'])
+
+    const cli = sidebar['/'].find((group) => group.text === 'CLI')
+    const links = (cli!.items ?? []).map((item) => item.link)
+    expect(links).toEqual([
+      '/cli/',
+      '/cli/server',
+      '/cli/init',
+      '/cli/config',
+      '/cli/http-api'
+    ])
+  })
+})

dirsql-0.3.42/packages/python/e2e-attestation.json

@@ -0,0 +1,6 @@
+{
+  "command": "uv run python -m pytest tests/e2e/ -x -q",
+  "ran_at": 1782833107,
+  "exit_code": 0,
+  "commit": "07bd37825c22f9ad73153d70fc65c9e3c92f855e"
+}

{dirsql-0.3.40/packages/python → dirsql-0.3.42/packages/rust}/docs/api/index.md

@@ -59,6 +59,7 @@ new DirSQL({
     tables?: TableDef[],
     ignore?: string[],
     config?: string,
+    extensions?: ExtensionSpec[],  // [{ path: string, entrypoint?: string }]
 })
 ```
 
@@ -76,7 +77,7 @@ In Python, the constructor starts scanning in a background thread and returns im
 - `tables` -- List of `Table` definitions. Each defines a SQLite table, a glob pattern, and an extract function.
 - `ignore` -- Optional list of glob patterns. Files matching any ignore pattern are skipped regardless of table globs.
 - `config` -- Optional path to a `.dirsql.toml` config file. Its `[[table]]` entries are appended to any programmatic `tables`; its `[dirsql].ignore` patterns are appended to any explicit `ignore`; its optional `[dirsql].root` supplies the root directory when `root` is not passed explicitly; its `[[dirsql.extension]]` entries are appended to any programmatic `extensions`.
-- `extensions` -- Optional SQLite extensions to load onto the connection at startup, before any table DDL (enable → load → disable, so the SQL `load_extension()` function is never left exposed). Each entry pairs a shared-library `path` with an optional `entrypoint` init-symbol override (Python: `{ "path", "entrypoint"? }` dicts; Rust: `Extension { path, entrypoint }`). Programmatic entries load first, then any `[[dirsql.extension]]` from `config`. Available in the Python and Rust SDKs; the TypeScript constructor parameter is tracked in [#230](https://github.com/thekevinscott/dirsql/issues/230). See [Loading extensions](../cli/config.md#loading-extensions).
+- `extensions` -- Optional SQLite extensions to load onto the connection at startup, before any table DDL (enable → load → disable, so the SQL `load_extension()` function is never left exposed). Each entry pairs a shared-library `path` with an optional `entrypoint` init-symbol override (Python: `{ "path", "entrypoint"? }` dicts; Rust: `Extension { path, entrypoint }`; TypeScript: `{ path, entrypoint? }` objects). Programmatic entries load first, then any `[[dirsql.extension]]` from `config`. Available in the Python, Rust, and TypeScript SDKs. See [Loading extensions](../cli/config.md#loading-extensions).
 
 ### Methods
 
@@ -162,7 +163,7 @@ JSON.stringify(db)  // via db.toJSON()
 
 :::
 
-Returns the resolved construction state as a JSON-compatible value with fields `root`, `tables`, `ignore`, `persist`, `persist_path` (camelCase `persistPath` in TypeScript). Each table is `{ ddl, glob, strict }`. The Python and Rust snapshots also include `extensions` -- an array of `{ path, entrypoint }` (empty when none are configured); the TypeScript `toJSON` snapshot will gain it with [#230](https://github.com/thekevinscott/dirsql/issues/230). Excludes the original `config` path (already merged into `root` / `tables` / `ignore`), per-table `extract`, and per-table `name`. Available immediately after construction in Python and TypeScript; Rust's sync `build()` returns a ready instance.
+Returns the resolved construction state as a JSON-compatible value with fields `root`, `tables`, `ignore`, `persist`, `persist_path` (camelCase `persistPath` in TypeScript). Each table is `{ ddl, glob, strict }`. All three SDK snapshots also include `extensions` -- an array of `{ path, entrypoint }` (empty when none are configured; `entrypoint` is `null` when no override was supplied). Excludes the original `config` path (already merged into `root` / `tables` / `ignore`), per-table `extract`, and per-table `name`. Available immediately after construction in Python and TypeScript; Rust's sync `build()` returns a ready instance.
 
 ---