@ninjaxtools/slopdex 0.24.0 → 0.27.0

package/README.md

@@ -22,7 +22,7 @@ The main supported functions are
 - `slopdex map [PATH]...`
    <br/>show a map/skeleton of the code structure
 
-`search` does a vector searche of code, and markdown, and when enabled generated code descriptions.
+`search` does a vector search of code, configuration and markup files, and, when enabled, generated code descriptions.
 
 `cross-search` also does a vector search but compares all functions with each other (scope can be limited with additional options) and helps with finding duplicated code, or code that is not necessarily duplicated but spread out across the codebase (with `--cohesion`).
 
@@ -56,7 +56,7 @@ $ slopdex search "validate an authenticated session"
 ...
 ```
 
-The index tracks the current git commit and is created or updated on every command and stored in `.slopdex/index.sqlite`. Add `.slopdex/` to your repository's `.gitignore` to prevent it from being committed.
+The index tracks the current Git commit and is created or updated on every command that uses it. Index data is stored in the current user's cache folder and project settings are stored in `.slopdex/config.json` (add `.slopdex` to `.gitignore`). See also [cache configuration](docs/reference.md#shared-provider-artifacts).
 
 ### Code map/skeleton
 
@@ -70,7 +70,7 @@ $ slopdex map -g '*.md' -e '^Guide\.Setup' -i --format json
 $ slopdex map --no-reindex
 ```
 
-The `map` command can be used to generate a source code skeleton that strips most of the code implementation but retains many of the structurally useful information that can act as an index into the source code. The resulting index output is most useful to conserve tokens and improve the agentic programming experience.
+The `map` command can be used to generate a source code skeleton that strips most of the code implementation but retains structurally useful information that can act as an index into the source code, which improves context usage.
 
 See the [selector reference](docs/reference.md#shared-selectors).
 
@@ -80,9 +80,15 @@ By default all available indexes are searched and ranked together.
 
 ```console
 $ slopdex search "keep the repository index synchronized"
-0.4284  tests/languages.test.ts :: refresh
-0.4200  src/cli.ts :: refreshIndex
-0.4113  src/code-index.ts :: CodeIndex.updateFromGit
+*** src/engine.rs
+@@ 914-1082 @@ score=0.4284
+impl Engine
+  pub fn search(&self, query: &str, kind: &str, options: &Value) -> Result<Vec<Value>>
+
+*** src/engine.rs
+@@ 376-409 @@ score=0.4200
+impl Engine
+  pub fn map(&self, options: &Value) -> Result<Vec<Value>>
 ...
 ```
 
@@ -120,7 +126,7 @@ $ slopdex config fallback-model opencode-go/muse-spark-1.3-contributor
 
 The fallback-model is used if the main model reports an error, and if the fallback-model reports an error the main model is tried again.
 
-File and function descriptions are cached. Function descriptions will only be regenerated when functions change. File descriptions need to be regenerated explcitily with the `reindex-files` command.
+File and function descriptions are cached by source and description context, so renaming a file can reuse its descriptions. Function changes or a changed file-description context can require new callable descriptions. File descriptions after edits can be refreshed explicitly with `reindex-files`.
 
 ### Interactive Config
 
@@ -138,18 +144,27 @@ The intention of the `describe` command is to use a low-cost model to summarise
 $ slopdex describe "I want to implement a new rpc endpoint"
 ```
 
-For the best matching files (configured with `--describe-full-file-threshold`, default `0.8`) the full file contents are used.
+The LLM receives expanded text search results with indexed code from callers and callees up to two edges away by default; it does not receive whole-file source.
 
 ### Find duplicate code
 
 Compare functions across files, exclude short wrappers, and group matches into clusters:
 
 ```console
-$ slopdex cross-search --cross-file-only --min-lines 4 --threshold 0.9
-Cluster 1 (3 functions, similarity 0.9124-0.9568)
-  src/auth/session.ts:18:1 :: validateSession
-  src/http/middleware.ts:42:1 :: authenticate
-  src/users/user-service.ts:27:3 :: UserService.authenticate
+$ slopdex cross-search --cross-file-only --lines 4 --threshold 0.9
+Cluster 1 · 3 functions · similarity 0.9124-0.9568
+
+*** src/auth/session.ts
+@@ 18-29 @@
+export function validateSession(token: string): Session
+
+*** src/http/middleware.ts
+@@ 42-57 @@
+export function authenticate(req: Request): Session
+
+*** src/users/user-service.ts
+@@ 27-48 @@ UserService.authenticate
+authenticate(token: string): Session
 ...
 ```
 
@@ -160,11 +175,13 @@ Clusters join matches transitively, so a low threshold can connect many groups
 into one large cluster. Use `0.9` for stricter duplicate detection, or explicitly
 pass `--threshold 0.3` for the pre-rewrite default.
 
-You can use threshold ranges as well:
+You can use threshold and line-count ranges as well. Range starts are inclusive
+and ends are exclusive, so `--lines 4-20` selects functions with 4 through 19
+lines:
 
 ```console
-$ slopdex cross-search --cross-file-only --min-lines 4 --threshold 0.9
-$ slopdex cross-search --cross-file-only --min-lines 4 --threshold 0.85-0.9
+$ slopdex cross-search --cross-file-only --lines 4 --threshold 0.9
+$ slopdex cross-search --cross-file-only --lines 4-20 --threshold 0.85-0.9
 ```
 
 ### Restrict functions used in the cross-search
@@ -172,7 +189,7 @@ $ slopdex cross-search --cross-file-only --min-lines 4 --threshold 0.85-0.9
 Only use uncommitted working-tree functions as sources:
 
 ```console
-$ slopdex cross-search --uncommitted --cross-file-only --min-lines 4 --threshold 0.9
+$ slopdex cross-search --uncommitted --cross-file-only --lines 4 --threshold 0.9
 ```
 
 Only use functions changed since origin/main as sources:
@@ -196,17 +213,15 @@ $ slopdex cross-search --cross-file-only --cohesion --threshold 0.8
 ```
 ### Use with agents
 
-Just put this in your `AGENTS.md` file, no skill required:
+Just put this in your `AGENTS.md` file and adjust as desired, no skill necessary:
 
 ```
-- use `slopdex map -g <glob> <files or directories...>` to obtain a compact structural code skeleton, and then perform targeted reads for implementation details. Line numbers are indicated in square brackets (e.g [5] means line 5, and [5-10] means lines 5 to 10). To filter for specific symbols, use `-e`. To only include specific kinds of symbols use `-k` with `imports`, `fns`, `consts`, `types`, or `classes`. For example: `slopdex map -g "*.ts" -i -e "manager|main" src`.
-- use semantic code search to find code with: `slopdex search "..." --threshold 0.5`
-- when reviewing uncommitted code avoid introducing duplicates by looking for related matches: `slopdex cross-search --uncommitted --threshold 0.8`
-- don't use `*` as the glob since that circumvents the default ignore rules.
+- use `slopdex map -g "<glob>" -i -e "<regex>" <files or directories...>` to obtain a compact structural code skeleton, and then perform targeted reads using the line numbers for implementation details. To filter for specific symbols, use `-e`. To only include specific kinds of symbols use `-k` with `imports`, `fns`, `consts`, `types`, or `classes`.
+- use semantic code search to find code with: `slopdex search "<query>" --threshold 0.5`; vary the search query if you get no results
+- when reviewing uncommitted code avoid introducing duplicates by looking for related matches: `slopdex cross-search --uncommitted --cross-file-only --threshold 0.8`
+- when tasked to do advanced codebase analysis, use `slopdex --help` first to see all options
 ```
 
-Any other use, like doing a full `cross-search` is probably better done interactively with the agent, in which case you can just ask the agent to run `slopdex --help` to get usage information.
-
 ### Reranking
 
 Optionally a second-stage reranker can be enabled for all query-search commands:
@@ -223,10 +238,12 @@ $ slopdex config reranker cohere
 ```console
 $ slopdex cross-search \
   --target-root /path/to/other/repo \
-  --target-index /path/to/other/repo/.slopdex/index.sqlite \
+  --target-index /path/to/other/index.sqlite \
   --threshold 0.9
 ```
 
+Pass the target's `indexPath` from `slopdex --root /path/to/other/repo --format json status` (or a custom `--index` path) as `--target-index`.
+
 ### Inspect index health
 
 If some functions can't be indexed a warning is printed. Index errors can be investigated and fixed with the `index-errors` command to ensure the index is complete.

package/npm-shrinkwrap.json

@@ -19,7 +19,7 @@
       "hasInstallScript": true,
       "license": "MIT",
       "name": "@ninjaxtools/slopdex",
-      "version": "0.24.0"
+      "version": "0.27.0"
     },
     "node_modules/detect-libc": {
       "engines": {
@@ -48,5 +48,5 @@
     }
   },
   "requires": true,
-  "version": "0.24.0"
+  "version": "0.27.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "artifactDownloadUrls": [
-    "https://github.com/ninjaxtools/slopdex/releases/download/v0.24.0"
+    "https://github.com/ninjaxtools/slopdex/releases/download/v0.27.0"
   ],
   "bin": {
     "slopdex": "run-slopdex.js"
@@ -80,7 +80,7 @@
       "zipExt": ".tar.xz"
     }
   },
-  "version": "0.24.0",
+  "version": "0.27.0",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"