@ninjaxtools/slopdex 0.26.0 → 0.28.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).
 
@@ -112,21 +112,22 @@ $ export OPENAI_API_KEY="your-api-key"
 # Or
 # opencode auth login                    # use stored credentials instead of env variables
 
-$ slopdex descriptions enable
+$ slopdex config set descriptionsEnabled true
 $ slopdex search-descriptions "keep the repository index synchronized"
 ```
 
 You can list and configure one of OpenCode's models like this (or use the interactive config):
 
 ```console
-$ slopdex models opencode-go
-$ slopdex config model opencode-go/gpt-5.6-luna
-$ slopdex config fallback-model opencode-go/muse-spark-1.3-contributor
+$ slopdex help models opencode-go
+$ slopdex config set descriptionProvider opencode-go
+$ slopdex config set descriptionModel gpt-5.6-luna
+$ slopdex config set descriptionFallbackModel 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 `index reindex-files`.
 
 ### Interactive Config
 
@@ -144,7 +145,7 @@ 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
 
@@ -213,26 +214,25 @@ $ 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:
 
 ```console
 $ export COHERE_API_KEY="your-api-key"
-$ slopdex config reranker cohere
-# Or: export JINA_API_KEY="your-api-key" && slopdex config reranker jina
-# Or use an LLM: export OPENAI_API_KEY="your-api-key" && slopdex config reranker openai
+$ slopdex config set rerankerProvider cohere
+$ slopdex config set rerankingEnabled true
+# Or: export JINA_API_KEY="your-api-key" && slopdex config set rerankerProvider jina
+# Or use an LLM: export OPENAI_API_KEY="your-api-key" && slopdex config set rerankerProvider openai
 ```
 
 ### Compare repositories
@@ -240,17 +240,19 @@ $ 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.
+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.
 
 ```console
 $ slopdex status
-$ slopdex index-errors --format summary
+$ slopdex index errors --format summary
 $ slopdex --version
 ```
 

package/npm-shrinkwrap.json

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

package/package.json

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