@ataraxy-labs/sem 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -4,6 +4,92 @@ All notable changes to sem are documented in this file.
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-06-30
+
+### Changed
+
+- Whole-repo commands (`sem graph`) now skip the file-discovery walk when git proves the cache is fresh (HEAD unchanged and the working tree clean), serving the cached topology directly. On a 200K-file repo this is about 9x faster with git fsmonitor and about 4.5x faster without it; small repos and non-git repos are unchanged. The oracle only ever declines to accelerate, never serves stale results, and the `git status` check is time-bounded (`SEM_FRESHNESS_TIMEOUT_MS`) with `SEM_FRESHNESS=scan|git|auto` to override.
+
+### Added
+
+- `sem xref` lists cross-repo dependencies across your indexed repos: entities in one repo that depend on entities in another. A single-repo local graph can't see this, so it's a cloud feature (requires `sem login`) and is gated to the team/enterprise tier. Adds `cross_deps()` to the shared cloud client.
+- `sem diff` now prints a one-line hint, when run interactively and logged out, that `sem login` reveals what your changes break across repos (a cross-repo question a local single-repo diff can't answer). It is heavily throttled (at most once a week), shown only on a terminal with real entity changes, and stays completely silent in CI, pipes, `--json`/non-terminal output, and for logged-in users.
+
+### Performance
+
+- Cache freshness checks now run the per-file `stat` + content-hash scan in parallel (rayon) instead of sequentially (#351). On touched-file cache hits over large repos, the freshness scan was the dominant remaining cost (~42ms of sequential filesystem/hash work on a 5K-file touched scenario); it now scales across cores. SQLite reads stay serial (the connection isn't shared across threads) and fingerprint-refresh writes remain serial and best-effort — only the pure filesystem+hash work is parallelized, so cache-hit validity is unchanged.
+
+### Documentation
+
+- The bundled `/sem` agent skill no longer hardcodes a language count. It said "31 languages", which went stale as grammars were added and disagreed with the README ("32") and the crate description ("28"); it now says "30+ languages" so it can't drift, and an en-dash was replaced with a hyphen.
+- README: documented the optional cloud acceleration flow (`sem login` serves `impact`/`context`/`entities` from a warm pre-built graph for large repos; local is unchanged and `SEM_LOCAL=1` forces local), and added Lua to the supported-languages table.
+
+### Added
+
+- Lua support, via the `tree-sitter-lua` grammar (gated behind the `lang-lua` feature in `grammar-all`). Extracts global, `local`, table (`t.f`), and method (`t:f`) functions. Thanks @mmgeorge for the request (#393).
+- `SemanticEntity` now carries optional `start_byte`/`end_byte` offsets, populated from the underlying tree-sitter node during code extraction. A consumer can slice the exact original bytes of an entity out of a file given only its `file_path` and span, without re-parsing. Persisted through the entity cache and surfaced in `sem entities --json`. Thanks to Thomas J. for the request.
+
+### Added
+
+- `npx @ataraxy-labs/sem-skill`: one-command setup of sem for coding agents. Installs the sem skill into `~/.claude/skills/` and registers the `sem mcp` server, so an agent uses sem (impact / context / orient / diff) over grep for structural questions without manual setup. Builds on the skill contributed in #376.
+
+### Added
+
+- An agent skill (`skills/sem/SKILL.md`) documenting sem's semantic diff, impact, blame, history, context, and graph workflows for coding agents. Thanks @linhlban150612 for the contribution (#376).
+- `self-update` Cargo feature (on by default) gates the built-in `sem update` and the background update-available check. Distro and package-manager builds that own the binary's lifecycle can opt out with `cargo build --no-default-features`; `sem update` then prints a "update through your package manager" message instead of replacing the binary. Thanks @0323pin (pkgsrc/NetBSD) for the request (#390).
+
+### Added
+
+- `sem context --hops N` bounds the related entities to N graph hops from the target (instead of filling to the token budget), so you can ask for "the entity and just its immediate neighborhood." The `sem_context` MCP tool gains the same `hops` parameter. 0 (the default) keeps the existing unbounded, budget-driven behavior.
+
+### Changed
+
+- The `sem mcp` instructions now tell agents to read code with `sem_context` (which returns an entity's full source plus its callers/callees, addressed by name) rather than opening the file, reserving direct file reads for editing and non-code. Reading by entity is robust to line drift and arrives with the dependency context.
+
+## [0.14.1] - 2026-06-23
+
+### Fixed
+
+- Release pipeline: the Intel macOS cross-build failed on `openssl-sys` (no target-arch OpenSSL when cross-compiling on Apple Silicon). It now builds OpenSSL from source via `--features vendored-openssl`, the same approach the Linux arm64 cross-build uses. 0.14.0's binaries never published because of this; 0.14.1 is the first release to ship binaries for every platform, including Intel macOS (#374).
+
+## [0.14.0] - 2026-06-23
+
+### Added
+
+- `sem orient <query>` finds the entities most relevant to a query, structural code search for when you're dropped into an unfamiliar codebase and don't know the symbol name yet (e.g. `sem orient "where is the retry logic"`). Two-pass ranking: lexical score over entity name (subtoken + prefix/stem + substring), file path, and signature line, then a graph-centrality re-rank so a central, widely-used entity outranks a trivially-named helper. Results show the entity, its `file:line`, signature, and dependent count. `--json` and `--limit` supported. This is the structural counterpart to grep: grep finds text, orient finds the entity and how connected it is.
+- The `sem_entities` MCP tool accepts a `query` parameter for the same intent search, so agents can find code by what it does (not just by name) without falling back to grep. The ranking is shared with the CLI (`sem_core::parser::orient`).
+- `sem orient` down-weights entities in test files so implementation outranks an equivalently-named test. Test functions often match a query strongly by name, but the implementation is almost always what you want; tests stay findable, just below the real code.
+- `sem entities` accepts `--only <kind>` and `--except <kind>` (both repeatable) to filter the listing by entity kind, e.g. `sem entities --only function --only struct` or `sem entities --except import`. The two flags are mutually exclusive. Because entity kinds are language-dependent, an unknown kind reports the kinds actually found in the scanned files rather than guessing a static list. Thanks @aleclarson for the request (#378).
+- `SEM_WIDTH` sets the terminal-diff box width. sem's per-file box was a fixed 55 columns with no TTY attached, so it didn't match the surrounding pane when used as a pager (e.g. `lazygit`). Set `SEM_WIDTH=<columns>` to control it. Thanks @franky47 for the request (#380).
+
+### Fixed
+
+- The Intel macOS binary now builds reliably. The release built `x86_64-apple-darwin` on a native Intel `macos-13` runner, which GitHub is retiring, so the job could queue indefinitely and stall the whole release (0.13.1's binaries never published for this reason). It now cross-compiles on Apple Silicon `macos-14`, where runners are plentiful. 0.14.0 is the first release to ship Intel macOS binaries.
+
+## [0.13.1] - 2026-06-23
+
+### Added
+
+- `sem impact` can answer direct dependency queries from a fresh SQL topology cache without rebuilding the entity graph.
+- `sem entities` reports phase timings and listing counters when `SEM_TIMINGS` is enabled.
+- Optional OSC8 terminal hyperlinks on entity names in `sem diff`, so a supporting terminal (kitty, WezTerm, iTerm2, Ghostty, ...) renders them clickable and can open the definition at `file:line`. Off by default; enable with `SEM_HYPERLINK` set to an editor preset (`vscode`, `cursor`, `windsurf`, `zed`, `idea`, `file`) or a raw URI template using `{file}` and `{line}` (e.g. `SEM_HYPERLINK="vscode://file/{file}:{line}"`). Strictly TTY-only, so pipes, JSON output, and MCP/agent sessions never see escape codes. Force off with `SEM_NO_HYPERLINKS=1`. Thanks @olejorgenb for the request (#381).
+
+### Changed
+
+- The `sem mcp` server now sends usage guidance to the agent instead of a bare tool list. The instructions tell the agent to prefer `sem_impact`/`sem_context`/`sem_entities` over grep/find for structural questions (what calls X, understand X, where is X) and to keep grep for text search and non-code files. Availability alone wasn't changing agent behavior; this biases agents toward the entity graph the moment the server connects, with no extra setup.
+- `sem impact --deps` can reuse fresh caches when unrelated files change by validating the cached source set, hashes, and import metadata before falling back to a graph rebuild.
+- `sem impact --deps` narrows cache freshness checks to the queried entity, direct dependencies, and relevant JavaScript/TypeScript imports when the query scope is explicit.
+- Source scans skip default-excluded high-volume paths such as generated source directories, fixture/vendor/benchmark trees, generated file suffixes, CSS module declarations, and asset declarations; pass `--no-default-excludes` to include them.
+- `sem entities` accepts `--file-exts` for large directory scans and avoids duplicate directory-listing post-processing.
+- `sem entities` can list entities from a fresh SQLite topology cache instead of reparsing matching directory scans.
+- `sem entities --json` streams rows to stdout instead of materializing an intermediate JSON value array.
+- `sem entities` uses listing-only extraction so local listings do not retain source text or entity hashes.
+
+### Fixed
+
+- Intel macOS (`x86_64-apple-darwin`) is now built and published. The release matrix only produced Apple Silicon (`arm64`) macOS binaries, so Intel Mac users got a 404 from `install.sh` and "Unsupported platform darwin:x64" from npm. Added the `x86_64-apple-darwin` target to the release build and the `darwin:x64` mapping to the npm wrapper. Thanks @stark-bit for the report (#374).
+- TOML array-of-tables entries no longer collapse to a single entity in `sem diff`. Repeated `[[array]]` headers all reduced to the same id (`...::property::array`), so appending an entry showed up as a modification of the previous one instead of an addition. Each `[[key]]` entry now gets an index-based identity (`key/0`, `key/1`, ...) and is hashed independently, mirroring the JSON array-index handling. This also stops a `[key]` table and a `[[key]]` array-of-tables with the same name from colliding. Thanks @Arpafaucon for the report and analysis (#362).
+
 ## [0.13.0] - 2026-06-16
 
 ### Fixed

package/README.md

@@ -173,7 +173,7 @@ sem impact authenticateUser --json
 # Disambiguate by file
 sem impact authenticateUser --file src/auth.ts
 
-# Include generated/build directories that repo-wide scans skip by default
+# Include default-excluded paths such as generated, fixture, vendor, benchmark, and build trees
 sem impact authenticateUser --no-default-excludes
 ```
 
@@ -220,7 +220,7 @@ sem entities src/auth.ts
 sem entities --json
 sem entities src/auth.ts --json
 
-# Include generated/build directories that repo-wide scans skip by default
+# Include default-excluded paths such as generated, fixture, vendor, benchmark, and build trees
 sem entities --no-default-excludes
 ```
 
@@ -238,7 +238,7 @@ sem context authenticateUser --budget 4000
 # JSON output
 sem context authenticateUser --json
 
-# Include generated/build directories that repo-wide scans skip by default
+# Include default-excluded paths such as generated, fixture, vendor, benchmark, and build trees
 sem context authenticateUser --no-default-excludes
 ```
 
@@ -258,9 +258,26 @@ To disable and go back to normal git diff:
 sem unsetup
 ```
 
+## Cloud acceleration (optional)
+
+sem builds an entity dependency graph to answer `impact`, `context`, and `entities`. On a small or medium repo that's instant. On a very large codebase, building the graph locally can take hundreds of milliseconds to a few seconds.
+
+`sem login` connects sem to sem cloud, which keeps a warm, pre-built graph for your registered repos. When you're logged in, those queries are served from the warm cache instead of rebuilt locally, so they stay fast no matter how big the repo gets.
+
+```bash
+sem login                              # GitHub device flow, one time
+sem impact myFunc --file src/foo.rs    # served from the cloud's warm graph
+```
+
+It is fully optional and transparent:
+
+- Not logged in, or the cloud is unreachable? sem computes locally and prints the exact same output. No failures, no difference in results.
+- `SEM_LOCAL=1` forces local computation even when logged in.
+- Small repos see no change, local is already fast. The win is for large codebases where rebuilding the graph each time is the bottleneck.
+
 ## What it parses
 
-31 programming languages with full entity extraction via tree-sitter:
+32 programming languages with full entity extraction via tree-sitter:
 
 | Language | Extensions | Entities |
 |----------|-----------|----------|
@@ -278,6 +295,7 @@ sem unsetup
 | Swift | `.swift` | functions, classes, protocols, structs, enums, properties |
 | Elixir | `.ex` `.exs` | modules, functions, macros, guards, protocols |
 | Bash | `.sh` | functions |
+| Lua | `.lua` | functions (global, local, table, and method forms) |
 | HCL/Terraform | `.hcl` `.tf` `.tfvars` | blocks, attributes (qualified names for nested blocks) |
 | Kotlin | `.kt` `.kts` | classes, interfaces, objects, functions, properties, companion objects |
 | Fortran | `.f90` `.f95` `.f` | functions, subroutines, modules, programs |
@@ -348,6 +366,12 @@ Add it once, then talk to your agent normally. It calls the tools on its own.
 claude mcp add sem -- sem mcp
 ```
 
+Or one command that also installs the skill, so the agent knows *when* to reach for sem:
+
+```bash
+npx @ataraxy-labs/sem-skill
+```
+
 **Cursor, Claude Desktop, or any client with an `mcpServers` config:**
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ataraxy-labs/sem",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "npm wrapper for the sem CLI. Downloads the matching release binary and exposes the sem command in node_modules/.bin.",
   "license": "MIT OR Apache-2.0",
   "type": "module",

package/scripts/package-meta.mjs

@@ -34,11 +34,13 @@ export function resolveReleaseArtifact({
       return 'sem-linux-arm64.tar.gz';
     case 'darwin:arm64':
       return 'sem-darwin-arm64.tar.gz';
+    case 'darwin:x64':
+      return 'sem-darwin-x86_64.tar.gz';
     case 'win32:x64':
       return 'sem-windows-x86_64.tar.gz';
     default:
       throw new Error(
-        `Unsupported platform ${key}. Supported targets: linux/x64, linux/arm64, darwin/arm64, win32/x64.`,
+        `Unsupported platform ${key}. Supported targets: linux/x64, linux/arm64, darwin/x64, darwin/arm64, win32/x64.`,
       );
   }
 }