@ninjaxtools/slopdex 0.28.0 → 0.30.0

package/README.md

@@ -52,31 +52,47 @@ Vector search requires an embedding-provider API key from OpenAI or Jina.
 
 ```console
 $ export OPENAI_API_KEY="your-api-key"
+$ slopdex update
 $ slopdex search "validate an authenticated session"
 ...
 ```
 
-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).
+The index is created with the `update` command and tracks the current Git commit and is refreshed with the latest changes before it is used. Index data is stored in the current user's global 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
 
-`slopdex map` doesn't use vector search and works locally without a provider or API key.
+`slopdex map` works locally without a provider or API key.
 
 ```console
 $ slopdex map src docs
 $ slopdex map src -g '*.rs' -k fns -e 'refresh|search'
 $ slopdex map src --private
 $ slopdex map -g '*.md' -e '^Guide\.Setup' -i --format json
+$ slopdex map docs --detail expanded
 $ slopdex map --no-reindex
+$ slopdex map src -q 'validate session' -q 'authenticate user' -k fns
+$ slopdex map docs -q 'installation' --symbol-threshold 0.6 --detail expanded
 ```
 
 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.
 
+Symbols can be filtered by using `-e <regex>` or `-q <symbol>` (OR). The `-q` filter uses vector search
+and will be ignored if an index doesn't exist.
+
+Use `--detail expanded` to to show full code or markdown of matched symbols.
+
 See the [selector reference](docs/reference.md#shared-selectors).
 
+> [!NOTE]
+> Add this to your `AGENTS.md` to let the agent use the map command to explore the codebase:
+>
+> ```text
+> - Start discovery with one scoped `slopdex map -g "<glob>" -i -e "<term|term>" -q "<short symbol concept>" --private --callers 2 --callees 2 <paths...>`. Use known paths or `.`. Immediately read plausible implementation ranges and follow calls in source; grep for usages or missing links. Map again only for unknown declaration locations. Batch reads; skip repeated inventories and setup/help.
+> ```
+
 ### Search
 
-By default all available indexes are searched and ranked together.
+By default code/docs and generated descriptions, are searched and ranked together.
 
 ```console
 $ slopdex search "keep the repository index synchronized"
@@ -97,9 +113,20 @@ To search code/docs individually:
 ```console
 $ slopdex search-code "configure the embedding provider"
 $ slopdex search-md "configure the embedding provider" 
+$ slopdex search-code 'reject expired credentials' -q 'validate session' --symbol-threshold 0.6
+```
+
+Symbol index is searched with either `search-symbols` or `--symbols`:
+
+```console
+$ slopdex search-symbols 'validate session' --threshold 0.6 --limit 20
+$ slopdex search 'installation' --symbols -g '*.md' --detail expanded
+$ slopdex search 'validate session' --code --symbols
+$ slopdex search-symbols 'read settings' -q 'configuration' --symbol-threshold 0.7
 ```
 
-You can also enable optional description generation which will automatically generate file and function descriptions with a configured LLM provider and include them in the search.
+You can also enable optional description generation which will automatically generate file and
+function descriptions with a configured LLM provider and include them in the search.
 
 I use OpenCode Go usually with DeepSeek or Muse Spark, which are fairly good low-cost models. If you
 sign up for OpenCode Go through [this link](https://opencode.ai/go?ref=RAR3Z744DZ), we both receive
@@ -129,6 +156,13 @@ The fallback-model is used if the main model reports an error, and if the fallba
 
 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`.
 
+> [!NOTE]
+> Add this to your `AGENTS.md` to use semantic code search with your agent:
+>
+> ```text
+> - use semantic code search to find code with: `slopdex search "<query>" --threshold 0.3 --limit 20`; vary the search query if you get no results
+> ```
+
 ### Interactive Config
 
 To configure all configurable settings interactively run:
@@ -145,7 +179,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"
 ```
 
-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.
+First a `search` is performed with `--detail expanded` and `--expanded-callers 2` and `--expanded-callees 2` which expands generated descriptions and function implementations in the result, which is then given to an LLM which is asked to interpret the result, and the final output will be the result of the LLM interpretation as well as the `compact` results from the earlier search. This provides a tailored description for the specific query based on the `expanded` search results as well as the `compact` version of those results.
 
 ### Find duplicate code
 
@@ -153,29 +187,15 @@ Compare functions across files, exclude short wrappers, and group matches into c
 
 ```console
 $ 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
+*** Cluster 1 · 3 symbols · similarity 0.91-0.96
+src/auth/session.ts:18-29:validateSession
+src/http/middleware.ts:42-57:authenticate
+src/users/user-service.ts:27-48:UserService.authenticate
 ...
 ```
 
 Using `--cross-file-only` is useful to exclude similar code in the same file.
 
-Cross-search defaults to `--threshold 0.8` (query search defaults to `0.3`).
-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 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:
@@ -184,6 +204,12 @@ lines:
 $ 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
 ```
+> [!NOTE]
+> Add this to your `AGENTS.md` to detect and refactor duplicate code before it is committed:
+>
+> ```text
+> - when reviewing uncommitted determine if similar code elsewhere warrants a refactor: `slopdex cross-search --uncommitted --cross-file-only --threshold 0.8`
+> ```
 
 ### Restrict functions used in the cross-search
 
@@ -212,16 +238,6 @@ When code is similar but not actually duplicated, then `--cohesion` can help fin
 ```console
 $ slopdex cross-search --cross-file-only --cohesion --threshold 0.8
 ```
-### Use with agents
-
-Just put this in your `AGENTS.md` file and adjust as desired, no skill necessary:
-
-```
-- 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
-```
 
 ### Reranking
 

package/npm-shrinkwrap.json

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

package/package.json

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