projview 0.4.0 → 0.4.1

package/README.md

@@ -26,6 +26,25 @@ projview ./docs --port 5000
 projview /path/to/notes --no-open
 ```
 
+## use it from scripts or an AI
+
+projview also has a **machine interface** - subcommands that print JSON to stdout
+and exit (no server, no browser), so an agent or script can query your docs:
+
+```bash
+projview search "<query>" [path]   # ranked: filename matches + in-content hits w/ line snippets
+projview tree [path]               # the file tree as JSON
+projview search "mermaid" --demo   # quick test on the bundled docs
+```
+
+```jsonc
+// projview search "live reload"
+{ "query": "live reload",
+  "files":   [ /* fuzzy filename matches: {path, name, score} */ ],
+  "content": [ { "path": "reference/api.md", "count": 4,
+                 "snippets": [ { "line": 68, "text": "### live reload" } ] } ] }
+```
+
 ## what it does
 
 | step | detail |

package/docs/README.md

@@ -21,6 +21,7 @@ faults. use this tree while iterating on the tool.
 | edge | [syntax stress](edge-cases/syntax-stress.md) | gnarly markdown + inline broken fence |
 | edge | [faulty refs](edge-cases/faulty-refs.md) | **several dead links** on purpose |
 | edge | [buried file](edge-cases/deep/nested/buried.md) | deep nesting - indentation + auto-expand |
+| ai-tests | [search test](ai-tests/search.md) | AI-run test of the `projview search` machine interface |
 
 ## intentional faults (should NOT crash the app)
 

package/docs/ai-tests/search.md

@@ -0,0 +1,120 @@
+# search functionality - AI test
+
+An AI-driven test of projview's `search` **machine interface** (`projview search
+<query>` → JSON on stdout). The goal: probe distinct behaviours of the engine -
+content search, fuzzy filenames, multi-term logic, ranking, and edge cases - by
+running the published CLI and inspecting the JSON it returns.
+
+## experimental parameters
+
+| parameter | value |
+| --- | --- |
+| tool | `projview` (global install) |
+| version | `0.4.0` |
+| command form | `projview search "<query>" --demo` |
+| dataset | the bundled demo docs (`--demo`) - **14 files** at time of test |
+| output | JSON: `{ query, files[], content[] }` parsed from stdout |
+| ranking | filenames by fuzzy subsequence score; contents by term frequency |
+
+> Note: this very report is the 15th file in the set, so re-running the probes
+> below will now also surface `ai-tests/search.md` itself.
+
+## method
+
+Five search terms were chosen, each targeting a different aspect of the engine:
+
+| # | term | aspect under test |
+| --- | --- | --- |
+| 1 | `live reload` | content search across multiple files + snippet line numbers |
+| 2 | `mermaid` | frequency ranking + case-insensitivity (`MERMAID` vs `mermaid`) |
+| 3 | `cfg` | fuzzy **filename** match (subsequence), independent of content |
+| 4 | `broken diagram` | multi-term **AND** logic + cross-file ranking |
+| 5 | `kubernetes` | graceful **no-match** behaviour |
+
+## results
+
+### 1. content search - `live reload`
+
+```bash
+projview search "live reload" --demo
+```
+
+Three files matched, ranked by frequency, each snippet carrying a line number:
+
+| file | hits | top snippet |
+| --- | --- | --- |
+| `reference/api.md` | 4 | L68 `### live reload` |
+| `diagrams/sequence.mmd` | 2 | L13 `edit a file -> SSE -> live reload` |
+| `reference/glossary.md` | 2 | L9 `live reload - SSE-driven refresh` |
+
+✅ Multi-file content search, frequency-ordered, with usable `file:line` citations.
+
+### 2. ranking + case-insensitivity - `mermaid`
+
+`mermaid` returned **8** content matches. Crucially, `MERMAID` (uppercase)
+returned the **same 8** - the query is lower-cased before matching.
+
+✅ Case-insensitive; ranked by occurrence count.
+
+### 3. fuzzy filename match - `cfg`
+
+```bash
+projview search "cfg" --demo
+# files:   ["guides/configuration.md"]
+# content: (none)
+```
+
+`cfg` is not a substring of any document body, but it **is** a subsequence of
+`configuration.md`, so it surfaces in the `files` block while `content` stays empty.
+
+✅ Filename matching is fuzzy (subsequence) and independent of content search.
+
+### 4. multi-term AND + ranking - `broken diagram`
+
+```bash
+projview search "broken diagram" --demo
+```
+
+| file | hits |
+| --- | --- |
+| `README.md` | 12 |
+| `guides/troubleshooting.md` | 7 |
+| `edge-cases/syntax-stress.md` | 6 |
+| `guides/configuration.md` | 3 |
+| `edge-cases/faulty-refs.md` | 2 |
+
+Only files containing **both** terms appear; ranking is by total term frequency.
+
+✅ Multi-term is a **file-level AND** (every term must appear somewhere in the
+file), ranked by combined frequency.
+
+### 5. graceful no-match - `kubernetes`
+
+```bash
+projview search "kubernetes" --demo
+# { "query": "kubernetes", "files": [], "content": [] }
+```
+
+✅ Empty arrays, exit code `0` - a clean "nothing found", not an error.
+
+## observations & limitations
+
+- **Case-insensitive** matching (query is lower-cased).
+- **Multi-term = file-level AND**, not phrase match - the words can be anywhere in
+  the file, ranked by total frequency.
+- **Snippets are first-occurrence**: the shown snippet is the first line containing
+  *any* query term, which isn't always the most relevant line for multi-term
+  queries. (A future improvement: prefer lines matching the most terms.)
+- **Two independent result blocks**: `files` (fuzzy filename) and `content`
+  (full-text) - either can be populated without the other.
+
+## reproduce
+
+```bash
+npm i -g projview@latest
+projview search "live reload" --demo
+projview search "cfg" --demo
+projview search "broken diagram" --demo
+projview search "kubernetes" --demo
+projview tree --demo            # list the dataset
+```

package/docs/how-to-set-up.md

@@ -66,7 +66,7 @@ npm install
 npm run demo                 # preview the bundled docs/  (alias for --demo)
 npm start                    # index the current directory
 node bin/projview.js ./docs  # or call the CLI directly
-npm test                     # run the test suite (node:test, 23 tests)
+npm test                     # run the test suite (node:test, 29 tests)
 ```
 
 See the [project README](README.md) for the architecture and the
@@ -74,12 +74,27 @@ See the [project README](README.md) for the architecture and the
 
 ## CLI reference
 
+**Commands**
+
+| command | meaning |
+| --- | --- |
+| `projview [path]` | start the viewer (default) |
+| `projview search <query> [path]` | print ranked search results as JSON, then exit |
+| `projview tree [path]` | print the file tree as JSON, then exit |
+
+The `search` and `tree` subcommands are projview's **machine interface** - JSON on
+stdout, no server, no browser - built for agents and scripts. See
+[ai-tests/search.md](ai-tests/search.md) for a worked test.
+
+**Options**
+
 | argument / flag | meaning |
 | --- | --- |
 | `[path]` | directory to index (default: current directory) |
-| `--demo` | preview projview's own bundled sample docs |
+| `--demo` | use projview's own bundled sample docs (works with the subcommands too) |
 | `-p`, `--port <n>` | preferred port (default `4321`, climbs if taken) |
 | `--no-open` | don't auto-open the browser |
+| `-v`, `--version` | print the version and exit |
 | `-h`, `--help` | show help |
 
 **Environment variables** (handy for containers / servers):

package/docs/reference/api.md

@@ -21,6 +21,22 @@ Renders a single file to HTML on demand. Query param `p` is the relative path.
 
 Server-sent events stream for live reload.
 
+## machine interface (CLI)
+
+Besides the HTTP server, two subcommands print JSON to stdout and exit - no
+server, no browser - for agents and scripts.
+
+### projview search
+
+`projview search "<query>" [path]` returns `{ query, files[], content[] }`.
+Filenames match fuzzily (subsequence); contents are ranked by term frequency with
+line-numbered snippets. See [the AI search test](../ai-tests/search.md).
+
+### projview tree
+
+`projview tree [path]` returns `{ root, files, tree[] }` - the same structure
+`/api/tree` serves.
+
 ## the walker
 
 ### ignored directories
@@ -59,7 +75,7 @@ Requested paths are resolved and confined to the root.
 
 ### tree nav
 
-Collapsible dirs, filter box, auto-expand on navigate.
+Collapsible dirs, cmd+K search palette, auto-expand on navigate.
 
 ### viewer
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projview",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Ephemeral local previewer for markdown + mermaid files in any directory",
   "type": "module",
   "bin": {