Skip to content
Back to search

sem

Semantic version control => entity-level diffs, blame, and impact analysis on top of git. 28 languages via tree-sitter. Built for coding agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Ataraxy-Labs/sem with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Ataraxy-Labs/sem'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ataraxy-labs--sem/badge.svg)](/listings/ataraxy-labs--sem)

HTML

<a href="/listings/ataraxy-labs--sem"><img src="/api/listings/ataraxy-labs--sem/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

curl -fsSL https://raw.githubusercontent.com/Ataraxy-Labs/sem/main/install.sh | sh

Or via Homebrew:

brew install sem-cli

Or via winget on Windows:

winget install AtaraxyLabs.sem

Or via Scoop on Windows:

scoop install sem

Or install the npm wrapper into `node_modules`:

npm install --save-dev @ataraxy-labs/sem

With Bun, trust the package so its `postinstall` script can download the binary:

bun add -d @ataraxy-labs/sem
bun pm trust @ataraxy-labs/sem

Once installed, update to the latest release any time:

sem update

Or via cargo, from [crates.io](https://crates.io/crates/sem-cli):

cargo install sem-cli

Or build the latest `main` from source (requires Rust):

cargo install --git https://github.com/Ataraxy-Labs/sem sem-cli

Or grab a binary from [GitHub Releases](https://github.com/Ataraxy-Labs/sem/releases).

Or run via Docker:

docker build -t sem .
docker run --rm -it -u "$(id -u):$(id -g)" -v "$(pwd):/repo" sem diff

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 41 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # sem
  2. Semantic version control CLI. Entity-level diffs for Git (functions, classes, methods instead of lines).
  3. ## Structure
  4. Cargo workspace at `crates/`:
  5. - `sem-core` — entity extraction engine, tree-sitter parsers, dependency graph
  6. - `sem-cli` — CLI binary (`sem find`, `sem grep`, `sem impact`, `sem check`, `sem certify`, `sem diff`, `sem graph`, `sem history`)
  7. ## Build & Test
  8. ```bash
  9. cargo build --release -p sem-cli # binary at target/release/sem
  10. cargo test --workspace # 134 tests
  11. ```
  12. All cargo commands run from repo root. CI builds from `crates/` directory.
  13. ## Key Paths
  14. - Parsers: `crates/sem-core/src/parser/plugins/` (24 language plugins + shebang detection)
  15. - Commands: `crates/sem-cli/src/commands/`
  16. - Entity model: `crates/sem-core/src/model/`
  17. - Git integration: `crates/sem-core/src/git/`
  18. ## Adding a Language
  19. 1. Add tree-sitter grammar to `sem-core/Cargo.toml`
  20. 2. Create parser plugin in `sem-core/src/parser/plugins/`
  21. 3. Register in `sem-core/src/parser/mod.rs`
  22. 4. Add tests
  23. 5. See `CONTRIBUTING.md` for the full 7-step guide
  24. ## Conventions
  25. - Entity granularity: functions, classes, methods, structs, traits, interfaces
  26. - Methods have a `parentId` linking to their class
  27. - `structural_hash` for matching entities across versions
  28. - Release on tag push (`v*`)
  29. - License: MIT OR Apache-2.0
README.md · README · 750 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. > **Part of the [Ataraxy Labs](https://ataraxy-labs.com) stack**: agent-native infrastructure for software development. See also: [weave](https://ataraxy-labs.com/weave) (entity-level git merge driver) · [inspect](https://github.com/Ataraxy-Labs/inspect) (semantic code review) · [opensessions](https://github.com/Ataraxy-Labs/opensessions) (tmux sidebar for coding agents).
  2. >
  3. > Read the manifesto: https://ataraxy-labs.com/#thesis · Essays: https://ataraxy-labs.com/blogs · LLMs: https://ataraxy-labs.com/llms.txt
  4. <p align="center">
  5. <img src="assets/banner.svg" alt="sem" width="600" />
  6. </p>
  7. <p align="center">
  8. <a href="https://trendshift.io/repositories/25348" target="_blank"><img src="https://trendshift.io/api/badge/repositories/25348" alt="Ataraxy-Labs%2Fsem | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
  9. </p>
  10. <p align="center">
  11. <strong>Semantic version control built on Git.</strong><br>
  12. Instead of lines changed, sem tells you what entities changed: functions, methods, classes.
  13. </p>
  14. <p align="center">
  15. <a href="https://ataraxy-labs.com/blogs/code-is-not-text">Why sem?</a> ·
  16. <a href="#using-sem-with-agents">Using sem with agents</a> ·
  17. <a href="#install">Install</a> ·
  18. <a href="#commands">Commands</a> ·
  19. <a href="#use-with-ai-agents-mcp">Agents (MCP)</a> ·
  20. <a href="docs/cloud-consent.html">Cloud consent</a> ·
  21. <a href="https://github.com/Ataraxy-Labs/sem/releases/latest">Releases</a>
  22. </p>
  23. <p align="center">
  24. <a href="https://github.com/Ataraxy-Labs/sem/releases/latest"><img src="https://img.shields.io/github/v/release/Ataraxy-Labs/sem?color=blue&label=release" alt="Release"></a>
  25. <img src="https://img.shields.io/badge/rust-stable-orange" alt="Rust">
  26. <img src="https://img.shields.io/badge/tests-900%2B_passing-brightgreen" alt="Tests">
  27. <a href="LICENSE-MIT"><img src="https://img.shields.io/badge/license-MIT-yellow" alt="License"></a>
  28. <img src="https://img.shields.io/badge/languages-32-blue" alt="Languages">
  29. </p>
  30. sem is a semantic version control tool that works on top of Git. It parses your code with tree-sitter, extracts every function, class, and method as an entity, and diffs at the entity level instead of lines. This means you see "function `blahh` was modified" instead of "lines x-y changed."
  31. It works in any Git repo with no setup.
  32. Cloud-backed queries are opt-in per repo: logging in does not upload a repo or send a query. See the [cloud consent flow](docs/cloud-consent.html) for the public/private repo states, preview screen, local audit log, and forget controls.
  33. <p align="center">
  34. <img src="assets/terminal.svg" alt="sem diff" width="800" />
  35. </p>
  36. ## Using sem with agents
  37. Four questions, four verbs. Every verb takes `--json`.
  38. | Question | Verb |
  39. |---|---|
  40. | Where is it? | `sem find`, `sem grep` |
  41. | What does my change touch? | `sem impact` |
  42. | Is it correct? | `sem check` |
  43. | What should a human review? | `sem certify` |
  44. **Where is it?** Find a function, class or method by name:
  45. ```bash
  46. sem find parse_config
  47. ```
  48. ```
  49. function parse_config src/config.py:1
  50. ```
  51. Who calls it (`--callers`), what it uses (`--refs`), or its code with its callers and callees (`--context`):
  52. ```bash
  53. sem find parse_config --callers
  54. ```
  55. ```
  56. function parse_config src/config.py:1
  57. function load src/config.py:6
  58. function test_parse_config tests/test_config.py:4
  59. ```
  60. Search text, like `rg`:
  61. ```bash
  62. sem grep splitlines
  63. ```
  64. ```
  65. src/config.py:2: pairs = [line.split("=", 1) for line in text.splitlines() if line]
  66. ```
  67. **What does my change touch?** Everything that depends on an entity, and the tests to run:
  68. ```bash
  69. sem impact parse_config --tests
  70. ```
  71. ```
  72. ⚡ 1 tests affected:
  73. tests/test_config.py
  74. function test_parse_config (L4–5)
  75. ```
  76. `sem impact --diff HEAD --tests` answers the same for your whole uncommitted change.
  77. **Is it correct?** Run the project's own compiler, type checker, linter and tests, rechecking only what the change can affect when that gives the same answer. Exit 0 means pass, 1 fail, 2 could not decide:
  78. ```bash
  79. sem check
  80. ```
  81. ```
  82. cmd FAIL full sh (0 rechecked, 279 ms)
  83. `python3 -m pytest -q tests` exited 1:
  84. E AssertionError: assert {'a': '1'} == {'a': '2'}
  85. ```
  86. **What should a human review?** A review certificate for a commit range: what changed, which callers the change leaves behind, which tests reach it:
  87. ```bash
  88. sem certify main..HEAD
  89. ```
  90. ```
  91. # sem certificate 94f4bd74e26e..d73d4d092b43
  92. 1 files, 2 entities changed (1 added, 1 modified, 0 deleted, 0 renamed, 0 moved).
  93. - modified `parse_config` (src/config.py:1): 2 static caller(s) in 2 file(s) that this change does not modify
  94. ```
  95. For agents that speak MCP, `sem mcp` serves the same verbs as tools (see [Use with AI agents](#use-with-ai-agents-mcp)).
  96. ## Install
  97. ```bash
  98. curl -fsSL https://raw.githubusercontent.com/Ataraxy-Labs/sem/main/install.sh | sh
  99. ```
  100. Or via Homebrew:
  101. ```bash
  102. brew install sem-cli
  103. ```
  104. Or via winget on Windows:
  105. ```powershell
  106. winget install AtaraxyLabs.sem
  107. ```
  108. Or via Scoop on Windows:
  109. ```powershell
  110. scoop install sem
  111. ```
  112. Or install the npm wrapper into `node_modules`:
  113. ```bash
  114. npm install --save-dev @ataraxy-labs/sem
  115. ```
  116. With Bun, trust the package so its `postinstall` script can download the binary:
  117. ```bash
  118. bun add -d @ataraxy-labs/sem
  119. bun pm trust @ataraxy-labs/sem
  120. ```
  121. Once installed, update to the latest release any time:
  122. ```bash
  123. sem config update
  124. ```
  125. Or via cargo, from [crates.io](https://crates.io/crates/sem-cli):
  126. ```bash
  127. cargo install --locked sem-cli
  128. ```
  129. Or build the latest `main` from source (requires Rust):
  130. ```bash
  131. cargo install --locked --git https://github.com/Ataraxy-Labs/sem sem-cli
  132. ```
  133. Or grab a binary from [GitHub Releases](https://github.com/Ataraxy-Labs/sem/releases).
  134. Or run via Docker:
  135. ```bash
  136. docker build -t sem .
  137. docker run --rm -it -u "$(id -u):$(id -g)" -v "$(pwd):/repo" sem diff
  138. ```
  139. ## Name conflict with GNU Parallel
  140. GNU Parallel ships a `sem` binary (`/usr/bin/sem`) as a symlink to `parallel`. If you have both installed, they'll collide. Run `sem --version` to check which one you're using. ([#77](https://github.com/Ataraxy-Labs/sem/issues/77))
  141. **Quick fixes:**
  142. ```bash
  143. # Option 1: alias in your shell profile (~/.bashrc, ~/.zshrc)
  144. alias sem="$HOME/.cargo/bin/sem"
  145. # Option 2: make sure cargo bin comes first in PATH
  146. export PATH="$HOME/.cargo/bin:$PATH"
  147. # Option 3: if installed via Homebrew
  148. export PATH="$(brew --prefix)/bin:$PATH"
  149. ```
  150. If you installed via npm/bun, the binary lives in `node_modules/.bin/sem` and is invoked through `npx sem` or `bunx sem`, which avoids the conflict entirely.
  151. ## Commands
  152. Works in any Git repo. No setup required. Also works outside Git for arbitrary file comparison.
  153. | Verb | The question it answers |
  154. |---|---|
  155. | `sem find` | Where is it defined? Who calls it, what does it use, what is around it? |
  156. | `sem grep` | Where does this text appear? |
  157. | `sem impact` | What does changing this entity, or this diff, touch? |
  158. | `sem check` | Is my change correct? |
  159. | `sem certify` | What should a human review in this commit range? |
  160. | `sem diff` | Which functions and classes changed? |
  161. | `sem graph` | How is the code connected? |
  162. | `sem history` | How did this entity change over time? Who last changed it? |
  163. | `sem cloud` | Account, cloud reviews, cross-repo queries |
  164. | `sem config` | git diff integration, telemetry, completions, updates, stats |
  165. | `sem mcp` | The same verbs as MCP tools for agents |
  166. `sem <verb> --help` shows every flag with an example.
  167. sem stores its SQLite entity cache outside the repository, under the OS cache directory by default. Set `SEM_CACHE_DIR=/path/to/cache` to override the cache root; repo-local overrides are ignored so cache files do not dirty the working tree.
  168. ### sem find
  169. Find entity definitions by name, then ask about one: who calls it, what it uses, or its code with the code around it. Answers come from an on-disk query index (`index.sem`, next to the entity cache); the first call in a repo builds it, later calls read it directly, with no daemon.
  170. ```bash
  171. sem find "function diff_command" # where it is defined ("type name" narrows by kind)
  172. sem find diff_command load_config # several names in one call
  173. sem find diff_command --callers # who calls it; says when the caller set may be incomplete
  174. sem find diff_command --refs # what it calls and references
  175. sem find diff_command --context # its code plus callers and callees, within a token budget
  176. sem find diff_command --context --budget 4000 --hops 1
  177. sem find --in src/auth.ts # every entity in a file or directory
  178. sem find diff_command --in src/ # only definitions under src/
  179. sem find --text "retry budget" # entity bodies containing a string, named by entity
  180. sem find diff_command --json # JSON on any of the above
  181. ```
  182. With `--context`, when the target signature itself does not fit, JSON output reports `target_omitted: true`.
  183. ### sem grep
  184. Text search across source files, rg-compatible `file:line:text` output, served from the index's trigram postings when one exists.
  185. ```bash
  186. sem grep "TODO"
  187. sem grep -i todo src/ # case-insensitive, under src/
  188. sem grep -e foo -e bar --json # several patterns, hits kept apart
  189. ```
  190. ### sem impact
  191. What breaks if an entity changes: its dependencies, its dependents (transitively), and the tests that reach it.
  192. ```bash
  193. sem impact authenticateUser # full impact
  194. sem impact authenticateUser --deps # direct dependencies only
  195. sem impact authenticateUser --dependents
  196. sem impact authenticateUser --tests # the tests to run
  197. sem impact authenticateUser --file src/auth.ts # disambiguate by file
  198. sem impact --diff HEAD --tests # tests for the uncommitted change
  199. sem impact --diff main..HEAD --json # one impact report per changed entity
  200. ```
  201. With `--diff` and `--tests` in a JS/TS workspace, the answer is the module graph's affected-test selection over the changed files (`sem graph --modules affected-tests`); elsewhere it is the entity graph's. `--no-default-excludes` includes generated, fixture, vendor, benchmark and build trees.
  202. ### sem check
  203. Runs the project's compiler, type checker, linter and tests on the working tree and prints one verdict: exit 0 pass, 1 fail, 2 could not decide. Each checker gives the verdict the real tool would give on the whole project; it rechecks only what the change can affect when that is provably the same answer, and otherwise runs the tool in full and says why. Nothing to check is 2, never a pass.
  204. ```bash
  205. sem check # every checker the project has
  206. sem check --checkers ts,lint,tests # only these
  207. sem check --base origin/main # against origin/main instead of HEAD
  208. sem check --promises # also prove every promise in .sem/promises can fail
  209. sem check --json # one JSON object with a verification certificate
  210. ```
  211. Checkers are detected from the project. TypeScript, lint and JS tests (vitest, jest) follow the module graph, Go rechecks affected packages, Python type checking (pyright scoped by imports, or mypy) and pytest rerun only the files a change can reach, and C and C++ recompile only the translation units in `compile_commands.json` that include a changed file. Cargo, Gradle or Maven, dotnet and SwiftPM run their own build, which already rebuilds only what changed, and are skipped outright when no input changed since the base passed (a TypeScript edit never reruns the Rust build).
  212. An edit inside the body of a Python function that declares its return type cannot change what other files see, so only that file is rechecked.
  213. Commands of your own go in `.sem/check.json`, e.g. `{"commands": [{"run": "make lint", "inputs": ["src/**"]}]}`. A command that lists its `inputs` is skipped when none of them changed since it passed; one without runs every time.
  214. ### sem certify
  215. A review certificate for a commit range: entities touched, signature changes and the callers they leave behind, callee deltas, promises kept or broken (with witnesses), module reachability deltas (JS/TS), affected tests, and the static reference cone. `--arch` gives the architecture view instead: new or removed data paths, side effects, dependencies, cycles, and what did not change, ranked.
  216. ```bash
  217. sem certify main..HEAD # markdown certificate
  218. sem certify main..HEAD --json # the full certificate
  219. sem certify main..HEAD --arch # architecture delta
  220. sem certify main..HEAD --arch --view # at most 10 ranked items
  221. sem certify main..HEAD --html > view.html # one self-contained page
  222. ```
  223. `<base>...<head>` uses the merge base; one ref means `<ref>..HEAD`.
  224. ### sem diff
  225. Entity-level diff with rename detection, structural hashing, and word-level inline highlights.
  226. ```bash
  227. # Semantic diff of working changes
  228. sem diff
  229. # Staged changes only
  230. sem diff --staged
  231. # Specific commit
  232. sem diff --commit abc1234
  233. # Commit range
  234. sem diff --from HEAD~5 --to HEAD
  235. # Verbose mode (word-level inline diffs for each entity)
  236. sem diff -v
  237. # Plain text output (git status style)
  238. sem diff --format plain
  239. # JSON output (for AI agents, CI pipelines)
  240. sem diff --format json
  241. # Markdown output (for PRs, reports)
  242. sem diff --format markdown
  243. # Compare any two files (no git repo needed)
  244. sem diff file1.ts file2.ts
  245. # Read file changes from stdin (no git repo needed)
  246. echo '[{"filePath":"src/main.rs","status":"modified","beforeContent":"...","afterContent":"..."}]' \
  247. | sem diff --stdin --format json
  248. # Only specific file types
  249. sem diff --file-exts .py .rs
  250. ```
  251. ### sem graph
  252. How the code is connected. With no flag, the entity dependency graph (the graph `sem impact` and `sem find --context` are built on); the flags select other layers.
  253. ```bash
  254. sem graph --json # entities and the calls/references between them
  255. sem graph --modules metrics # JS/TS module graph: density, cycles, depth, centrality
  256. sem graph --modules blast-radius pkg-a # who breaks if pkg-a changes
  257. sem graph --modules path src/a.ts src/b.ts
  258. sem graph --dataflow # reads, writes and source -> sink paths
  259. sem graph --dataflow --witness # experimental: witness tasks per static flow
  260. sem graph --system # exact dependency versions from every lockfile
  261. sem graph --system build --out sys/ # the layered whole-system graph
  262. ```
  263. ### sem history
  264. How an entity changed through git history, logic changes told apart from cosmetic ones.
  265. ```bash
  266. sem history authenticateUser
  267. sem history authenticateUser -v # with the content diff of each version
  268. sem history authenticateUser --limit 20
  269. sem history # repo hotspots and co-change pairs
  270. sem history --blame src/auth.ts # who last changed each entity in the file
  271. ```
  272. With no entity, `sem history` analyzes recent repo history at the entity level: **hotspots** (most-changed functions/classes, with author counts) and **co-change pairs** (entities that repeatedly change in the same commits: "if you touch one, don't forget the other").
  273. ### sem cloud, sem config
  274. ```bash
  275. sem cloud login # API key, or GitHub when omitted
  276. sem cloud enable # cloud queries for this public repo (shows what is sent, asks first)
  277. sem cloud disable # stop cloud for this repo
  278. sem cloud review listen <diff-id> # attach an agent to a cloud code review
  279. sem cloud xref --json # cross-repo dependencies
  280. sem cloud repos # where your code is stored
  281. sem config setup # make `git diff` show sem's entity diff
  282. sem config telemetry off
  283. sem config completions zsh # shell completions
  284. sem config update
  285. sem config stats # local diff counters; nothing leaves your machine
  286. ```
  287. ### Old command names
  288. Every earlier command name and flag still works, with the same output. At a terminal, sem prints a one-line note on stderr with the new spelling; in `--json` mode or when output is piped, it prints nothing extra.
  289. | Old | New |
  290. |---|---|
  291. | `sem callers X` | `sem find X --callers` |
  292. | `sem refs X` | `sem find X --refs` |
  293. | `sem context X` | `sem find X --context` |
  294. | `sem entities PATH` | `sem find --in PATH` |
  295. | `sem log X` | `sem history X` |
  296. | `sem blame FILE` | `sem history --blame FILE` |
  297. | `sem arch-diff RANGE` | `sem certify RANGE --arch` |
  298. | `sem topology OP` | `sem graph --modules OP` |
  299. | `sem dataflow` | `sem graph --dataflow` |
  300. | `sem system OP` | `sem graph --system OP` |
  301. | `sem promises verify` | `sem check --promises` |
  302. | `sem login`, `logout`, `whoami`, `review`, `xref`, `repos` | `sem cloud ...` |
  303. | `sem cloud never` | `sem cloud disable` |
  304. | `sem setup`, `unsetup`, `telemetry`, `completions`, `update`, `stats` | `sem config ...` |
  305. ### Promises
  306. A promise is something an agent (or a person) claims about the codebase, written down as a check that either passes or fails. "Done" means the check passes. Promises live in `.sem/promises/*.json`; each law may carry a human `"promise"`. Code-shape laws are tree-sitter queries that work in any language sem parses; every capture whose name does not start with `_` counts as a violation, and nested captures are reported once, at the outermost node. For example, `.sem/promises/jsx-no-logic.json`:
  307. ```json
  308. { "laws": [
  309. { "id": "jsx-no-logic/conditionals",
  310. "promise": "JSX contains no conditional rendering",
  311. "forbidPattern": { "from": ["**/*.tsx", "**/*.jsx"], "within": ["jsx_expression"],
  312. "query": "(ternary_expression) @conditional" } },
  313. { "id": "jsx-no-logic/inline-handler-bodies",
  314. "promise": "JSX event handlers are references, not block bodies",
  315. "forbidPattern": { "from": ["**/*.tsx", "**/*.jsx"], "within": ["jsx_attribute"],
  316. "query": "(arrow_function body: (statement_block (_))) @handler_body" } }
  317. ] }
  318. ```
  319. ```bash
  320. sem promises check # KEPT / BROKEN n per promise, then file:line:col capture snippet; exit 1 if any broken
  321. sem promises check --changed src/App.tsx # only violations in these files (what an edit hook runs)
  322. sem promises check --since main # only files changed since a ref, uncommitted and untracked included
  323. sem promises status --json # id, kept, violation count per promise
  324. sem check --promises # prove every promise can fail (each needs a mutation)
  325. ```
  326. `sem promises` is not listed in `sem --help`; `sem certify` reports promises kept or broken for a range. The same file also works with `sem graph --modules check --laws <file>`, which adds graph and import laws (`forbid`, `only`, `acyclic`, `layers`, `forbidImport`, `allowImports`) for JS/TS workspaces. With `--changed` or `--since`, those laws still run over the whole graph, but only violations that involve a changed file (or the package containing it) are reported.
  327. To have an agent see a broken promise right after it makes an edit, run [`scripts/promises-hook.sh`](scripts/promises-hook.sh) after each edit. The script exits 2 and prints the violations to stderr when a promise breaks, and stays silent otherwise. In Claude Code, add it to your settings as a `PostToolUse` hook:
  328. ```json
  329. { "hooks": { "PostToolUse": [ { "matcher": "Edit|Write|MultiEdit",
  330. "hooks": [ { "type": "command", "command": "sh /path/to/sem/scripts/promises-hook.sh" } ] } ] } }
  331. ```
  332. The script reads `tool_input.file_path` from the hook's stdin. Other harnesses can pass the edited paths as arguments instead. In pi, for example, an extension can do this from its `tool_result` handler for the edit and write tools: run `sh promises-hook.sh <path>` and append the stderr to the tool result when the script exits 2.
  333. ## Use as default Git diff
  334. Replace `git diff` output with entity-level diffs. Agents and humans get sem output automatically without changing any commands.
  335. ```bash
  336. sem config setup
  337. ```
  338. Now `git diff` shows entity-level changes instead of line-level. No prompts, no agent configuration needed. Everything that calls `git diff` gets sem output automatically. Also installs a pre-commit hook that shows entity-level blast radius of staged changes.
  339. On macOS and Linux, `sem config setup` also registers a Claude Code `UserPromptSubmit` hook (`sem hook prompt-submit`) for prompt-time context injection, and `sem hook tool` around the Edit, Write and MultiEdit tools. After each edit that hook tells the agent which sibling implementations of a changed method it did not touch, which callers still use a signature it just changed, and which tests reach the change, with a command to run them; it stays silent when there is nothing to say. It edits `~/.claude/settings.json` idempotently, backs it up first, and leaves any hooks you already have untouched.
  340. To disable and go back to normal git diff (also removes the session hooks):
  341. ```bash
  342. sem config unsetup
  343. ```
  344. ## Entity-level diffs on every pull request
  345. Add the GitHub Action and every PR gets one sticky comment showing which
  346. functions, classes, and methods changed. It updates in place on each push and
  347. calls out cosmetic-only PRs (formatting/comments) explicitly:
  348. ```yaml
  349. # .github/workflows/entity-diff.yml
  350. name: Entity diff
  351. on: pull_request
  352. permissions:
  353. contents: read
  354. pull-requests: write
  355. jobs:
  356. entity-diff:
  357. runs-on: ubuntu-latest
  358. steps:
  359. - uses: actions/checkout@v4
  360. - uses: Ataraxy-Labs/sem/action@v0.23.1
  361. ```
  362. No config, no API keys, never fails your build. See [action/](action/) for details.
  363. ## Cloud acceleration (for scale and teams)
  364. Local is always free and always fast: the on-disk index answers day-to-day queries in single-digit milliseconds even from a cold process, so there's nothing to keep warm and no login required. You do not pay to make your laptop fast.
  365. Cloud is for what a laptop can't do. On a very large monorepo the first local graph build can take a few seconds; a shared team graph shouldn't be rebuilt per developer; and CI wants the graph without checking anything out. `sem cloud login` connects those cases to sem cloud, which keeps a warm, pre-built graph for your registered repos and serves the heavy queries from it instead of rebuilding locally.
  366. ```bash
  367. sem cloud login # GitHub device flow, one time
  368. sem impact myFunc --file src/foo.rs # served from the cloud's warm graph
  369. ```
  370. It is fully optional and transparent:
  371. - Not logged in, or the cloud is unreachable? sem computes locally and prints the exact same output. No failures, no difference in results.
  372. - `SEM_LOCAL=1` forces local computation even when logged in.
  373. - Small repos see no change, local is already fast. The win is for large codebases where rebuilding the graph each time is the bottleneck.
  374. Related commands, all cloud-account scoped:
  375. ```bash
  376. sem cloud logout # log out
  377. sem cloud whoami # show current cloud identity
  378. sem cloud enable # turn on cloud queries for a public repo (shows what's sent first)
  379. sem cloud disable # stop cloud for this repo
  380. sem cloud xref --json # cross-repo dependencies across your indexed repos
  381. sem cloud repos # where your code is stored: cloud-indexed repos + local caches
  382. sem cloud status # cloud + telemetry state for this repo (offline; sends nothing)
  383. sem cloud share # cloud queries for a private repo, with extra confirmation
  384. sem cloud forget # delete this repo's cloud index and unregister it
  385. ```
  386. `status`, `share`, `forget`, `list`, `preview` and `log` are not shown in `sem cloud --help` but work as listed; each one is read-only or requires explicit confirmation before it sends anything.
  387. If your team runs code review through sem cloud, `sem cloud review listen <diff-id-or-url>` execs a coding agent pre-configured to join that review as a live listener that answers reviewer questions anchored to specific lines of the diff.
  388. ## What it parses
  389. 32 programming languages with full entity extraction via tree-sitter:
  390. | Language | Extensions | Entities |
  391. |----------|-----------|----------|
  392. | TypeScript | `.ts` `.tsx` `.mts` `.cts` | functions, classes, interfaces, types, enums, exports |
  393. | JavaScript | `.js` `.jsx` `.mjs` `.cjs` `.es6` | functions, classes, variables, exports |
  394. | Python | `.py` `.pyi` | functions, classes, decorated definitions |
  395. | Starlark (Bazel, Buck2) | `BUILD` `BUCK` `WORKSPACE` `PACKAGE` `.bzl` `.bazel` `.bxl` `.star` | build targets, functions |
  396. | Go | `.go` | functions, methods, types, vars, consts |
  397. | Rust | `.rs` | functions, structs, enums, impls, traits, mods, consts |
  398. | Java | `.java` | classes, methods, interfaces, enums, fields, constructors |
  399. | C | `.c` `.h` | functions, structs, enums, unions, typedefs |
  400. | C++ | `.cpp` `.cc` `.cxx` `.hpp` `.hh` `.hxx` | functions, classes, structs, enums, namespaces, templates |
  401. | C# | `.cs` | classes, methods, interfaces, enums, structs, properties |
  402. | Ruby | `.rb` | methods, classes, modules |
  403. | PHP | `.php` `.inc` `.phtml` `.module` | functions, classes, methods, interfaces, traits, enums |
  404. | Swift | `.swift` | functions, classes, protocols, structs, enums, properties |
  405. | Elixir | `.ex` `.exs` | modules, functions, macros, guards, protocols |
  406. | Bash | `.sh` | functions |
  407. | Fish | `.fish` | functions |
  408. | jq (opt-in, `--features lang-jq`) | `.jq` | functions (`def`) |
  409. | Lua | `.lua` | functions (global, local, table, and method forms) |
  410. | HCL/Terraform | `.hcl` `.tf` `.tfvars` | blocks, attributes (qualified names for nested blocks) |
  411. | Kotlin | `.kt` `.kts` | classes, interfaces, objects, functions, properties, companion objects |
  412. | Fortran | `.f90` `.f95` `.f03` `.f08` `.f` `.for` | functions, subroutines, modules, programs |
  413. | Vue | `.vue` | template/script/style blocks + inner TS/JS entities |
  414. | XML | `.xml` `.plist` `.svg` `.csproj` + 9 more MSBuild/resource extensions | elements (nested, tag-name identity) |
  415. | ERB | `.erb` `.html.erb` | blocks, expressions, code tags |
  416. | Svelte | `.svelte` `.svelte.js` `.svelte.ts` (+ `.test`/`.spec` variants) | component blocks + rune JS/TS modules |
  417. | Perl | `.pl` `.pm` `.t` | subroutines, packages |
  418. | Dart | `.dart` | classes, mixins, extensions, enums, type aliases, functions |
  419. | OCaml | `.ml` `.mli` | values, modules, types, classes, externals |
  420. | Scala | `.scala` `.sc` `.sbt` `.kojo` `.mill` | classes, objects, traits, enums, functions, vals, extensions |
  421. | Nix | `.nix` | bindings, inherit declarations |
  422. | Haskell | `.hs` | functions, signatures, data types, newtypes, classes, instances, type synonyms |
  423. | Elm | `.elm` | value declarations, type aliases, type declarations, port annotations, infix declarations |
  424. | Clojure | `.clj` `.cljs` `.cljc` | vars, functions, macros, multimethods, protocols, records, types |
  425. | D | `.d` `.di` | modules, functions, classes, structs, interfaces, unions, enums, templates, aliases, unittests |
  426. | Zig | `.zig` | functions, tests, variables |
  427. | SQL | `.sql` `.psql` `.pgsql` `.ddl` | tables, views, functions, indexes, types, schemas, triggers, sequences |
  428. Plus structured data formats:
  429. | Format | Extensions | Entities |
  430. |--------|-----------|----------|
  431. | JSON | `.json` | properties, objects (RFC 6901 paths) |
  432. | YAML | `.yml` `.yaml` | sections, properties (dot paths) |
  433. | TOML | `.toml` | sections, properties |
  434. | EDN | `.edn` | top-level map entries (keyword keys) |
  435. | CSV | `.csv` `.tsv` | rows (first column as identity) |
  436. | Markdown | `.md` `.mdx` `.qmd` | heading-based sections |
  437. | LaTeX | `.tex` `.latex` `.cls` `.sty` | sections (part/chapter/section/…), plus theorem/lemma/proof/figure/table/algorithm and other tracked environments |
  438. Everything else falls back to chunk-based diffing.
  439. ### Custom extensions and extensionless files
  440. For files with non-standard extensions, create a `.semrc` in your project root:
  441. ```
  442. .xyz = cpp
  443. .j = json
  444. .mypy = python
  445. ```
  446. sem also reads `.gitattributes` patterns (`diff=` and `linguist-language=`) if you already have those set up. `.semrc` takes priority when both define the same extension.
  447. For files with no extension at all, sem detects the language automatically from content (shebang lines, vim modelines, and structural heuristics like `package`/`import`/`use` statements). This covers 30+ languages with no config needed.
  448. ## How matching works
  449. Three-phase entity matching:
  450. 1. **Exact ID match**: same entity in before/after = modified or unchanged
  451. 2. **Structural hash match**: same AST structure, different name = renamed or moved (ignores whitespace/comments)
  452. 3. **Fuzzy similarity**: >80% token overlap = probable rename
  453. This means sem detects renames and moves, not just additions and deletions. Structural hashing also distinguishes cosmetic changes (whitespace, formatting) from real logic changes.
  454. ## Use with AI agents (MCP)
  455. Need a URL-based client? The [Streamable HTTP preview](docs/mcp-http.md) adds authenticated, local read-only access; stdio remains the default.
  456. On macOS and Linux, clients in the same checkout share a warm repository daemon.
  457. Run `sem mcp --status` to check it. See the [shared runtime contract and reproducible benchmark](docs/shared-mcp.md)
  458. for session isolation, fallback behavior, and current platform limits.
  459. `sem mcp` starts a [Model Context Protocol](https://modelcontextprotocol.io) server over stdin/stdout. It's not a command you run and read yourself: it's a server your coding agent launches in the background so it can ask sem questions while it works. That's the reason `mcp` lives alongside the normal commands. The agent gets the core verbs as tools:
  460. | Tool | Answers |
  461. |---|---|
  462. | `sem_find` | Where is it defined? `mode`: `callers`, `refs` or `context`; `in` lists a file or directory |
  463. | `sem_grep` | Where does this text appear? |
  464. | `sem_impact` | What does changing this entity touch? Dependents, deps, tests |
  465. | `sem_check` | Is my change correct? A verdict: pass, fail, could not decide |
  466. | `sem_certify` | What should a human review in this commit range? |
  467. | `sem_diff` | Which entities changed between two refs? |
  468. | `sem_graph` | The entity, module, data-flow or system graph |
  469. | `sem_history` | How did an entity change? `blame` for a file |
  470. Clients that call the earlier tool names (`sem_entities`, `sem_context`, `sem_callers`, `sem_log`, `sem_blame`) still get answers; those names are just not listed. A review-listener session (`sem mcp --review`, which `sem cloud review listen` sets up) also lists `join_review`, `wait_for_branch`, `reply_to_branch` and `list_open_branches`.
  471. Why an agent wants these: instead of reading whole files and burning tokens, it can ask "what breaks if I change `submitOrder`" (`sem_impact`) or "give me just the context to refactor this function" (`sem_find` with mode `context`, which returns the function's source plus its callers and callees) and get a precise, deterministic answer from the dependency graph instead of a grep result that might miss a caller.
  472. Add it once, then talk to your agent normally. It calls the tools on its own.
  473. **Claude Code:**
  474. ```bash
  475. claude mcp add sem -- sem mcp
  476. ```
  477. Or one command that also installs the skill, so the agent knows *when* to reach for sem:
  478. ```bash
  479. npx @ataraxy-labs/sem-skill
  480. ```
  481. **Cursor, Claude Desktop, or any client with an `mcpServers` config:**
  482. ```json
  483. {
  484. "mcpServers": {
  485. "sem": {
  486. "command": "sem",
  487. "args": ["mcp"]
  488. }
  489. }
  490. }
  491. ```
  492. If `sem` isn't on the agent's PATH, use the absolute path to the binary. No separate install is needed: `sem mcp` ships in the same binary as every other command.
  493. ## JSON output
  494. ```bash
  495. sem diff --format json
  496. ```
  497. Real output, from a one-line logic change to a Python function:
  498. ```json
  499. {
  500. "summary": {
  501. "fileCount": 1,
  502. "added": 0,
  503. "modified": 1,
  504. "deleted": 0,
  505. "moved": 0,
  506. "renamed": 0,
  507. "reordered": 0,
  508. "binary": 0,
  509. "orphan": 0,
  510. "total": 1
  511. },
  512. "changes": [
  513. {
  514. "entityId": "auth.py::function::authenticate_user",
  515. "changeType": "modified",
  516. "entityType": "function",
  517. "entityName": "authenticate_user",
  518. "startLine": 1,
  519. "endLine": 6,
  520. "oldStartLine": 1,
  521. "oldEndLine": 4,
  522. "oldEntityName": null,
  523. "filePath": "auth.py",
  524. "oldFilePath": null,
  525. "oldParentId": null,
  526. "beforeContent": "def authenticate_user(username, password):\n if not username or not password:\n return False\n return check_credentials(username, password)",
  527. "afterContent": "def authenticate_user(username, password):\n if not username or not password:\n return False\n if not check_credentials(username, password):\n return False\n return True",
  528. "commitSha": null,
  529. "author": null,
  530. "structuralChange": true
  531. }
  532. ],
  533. "binaryChanges": []
  534. }
  535. ```
  536. The named change-type buckets (`added`, `modified`, `deleted`, `moved`, `renamed`, `reordered`) always sum to `total`. `orphan` is a cross-cutting metadata count for module-level changes, and those changes are already included in the named change-type buckets. `beforeContent`/`afterContent` carry the entity's full source on either side of the change; `structuralChange` is `false` when the diff is cosmetic only (whitespace, comments).
  537. ## As a library
  538. sem-core can be used as a Rust library dependency, from [crates.io](https://crates.io/crates/sem-core):
  539. ```toml
  540. [dependencies]
  541. sem-core = "0.23"
  542. ```
  543. Used by [weave](https://github.com/Ataraxy-Labs/weave) (semantic merge driver) and [inspect](https://github.com/Ataraxy-Labs/inspect) (entity-level code review).
  544. ## Architecture
  545. - **tree-sitter** for code parsing (native Rust, not WASM)
  546. - **git2** for Git operations
  547. - **rayon** for parallel file processing
  548. - **xxhash** for structural hashing
  549. - A per-repo cache directory (SQLite entity cache + an mmap-able query index) backs `find`/`callers`/`refs`/`grep` with cold-process lookups and no background daemon
  550. - Plugin system for adding new languages and formats (see [CONTRIBUTING.md](CONTRIBUTING.md))
  551. ## Telemetry
  552. Local by default: sem counts command names (e.g. `diff`, `impact`) on your own machine only, and in that mode nothing is ever uploaded. No code, file paths, repo names, or user identity is recorded, and no network call is made.
  553. ```bash
  554. sem config telemetry preview # see current mode and exactly what would be sent
  555. sem config telemetry on # opt in: also upload counts to help improve sem
  556. sem config telemetry off # record nothing at all
  557. ```
  558. `SEM_NO_TELEMETRY=1` or `DO_NOT_TRACK=1` force the record-nothing behavior regardless of mode. Development builds (anything run out of a `cargo build` `target/` directory) never record, so working on sem itself doesn't pollute the numbers.
  559. ## Contributing
  560. Want to add a new language? See [CONTRIBUTING.md](CONTRIBUTING.md) for a step-by-step guide.
  561. ## Star History
  562. [![Star History Chart](assets/star-history.png)](https://star-history.com/#Ataraxy-Labs/sem&Date)
  563. ## License
  564. MIT OR Apache-2.0
install.sh · Bundled script · 304 lines · 2 findings marked
  1. #!/bin/sh
  2. # sem installer — https://github.com/Ataraxy-Labs/sem
  3. #
  4. # Usage:
  5. # curl -fsSL https://raw.githubusercontent.com/Ataraxy-Labs/sem/main/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 5 on GitHub
  6. #
  7. # # pin a version
  8. # curl -fsSL https://raw.githubusercontent.com/Ataraxy-Labs/sem/main/install.sh | SEM_VERSION=v0.23.1 sh
  9. #
  10. # # or with flags (download first if you want flags)
  11. # curl -fsSL -o install.sh https://raw.githubusercontent.com/Ataraxy-Labs/sem/main/install.sh
  12. # sh install.sh --version v0.23.1 --install-dir /opt/sem/bin
  13. #
  14. # Env vars (all optional):
  15. # SEM_VERSION version to install, e.g. "v0.23.1" or "0.23.1" (default: latest)
  16. # SEM_INSTALL_DIR install directory (default: $HOME/.local/bin)
  17. # NO_COLOR disable colored output (any non-empty value)
  18. #
  19. # Supported platforms: macOS (arm64, x86_64), Linux (x86_64, arm64).
  20. # Windows: see https://github.com/Ataraxy-Labs/sem#installation (Scoop) or
  21. # download sem-windows-x86_64.zip from the releases page directly.
  22. #
  23. # This script never uses sudo and never writes outside INSTALL_DIR. It
  24. # verifies every downloaded archive against the release's checksums.txt and
  25. # refuses to install (fail closed) if that file can't be fetched or doesn't
  26. # cover the archive.
  27. set -eu
  28. REPO="Ataraxy-Labs/sem"
  29. BINARY="sem"
  30. VERSION="${SEM_VERSION:-latest}"
  31. INSTALL_DIR="${SEM_INSTALL_DIR:-$HOME/.local/bin}"
  32. FORCE=0
  33. SKIP_CHECKSUM=0
  34. # --- output -----------------------------------------------------------
  35. # Plain-output degradation: no tty, NO_COLOR set, or CI set -> no ANSI.
  36. if [ -n "${NO_COLOR:-}" ] || [ -n "${CI:-}" ] || [ ! -t 1 ]; then
  37. USE_COLOR=0
  38. else
  39. USE_COLOR=1
  40. fi
  41. info() {
  42. if [ "$USE_COLOR" -eq 1 ]; then
  43. printf ' \033[1;32m%s\033[0m %s\n' "$1" "$2"
  44. else
  45. printf ' %s %s\n' "$1" "$2"
  46. fi
  47. }
  48. warn() {
  49. if [ "$USE_COLOR" -eq 1 ]; then
  50. printf ' \033[1;33mwarning:\033[0m %s\n' "$1"
  51. else
  52. printf ' warning: %s\n' "$1"
  53. fi
  54. }
  55. error() {
  56. if [ "$USE_COLOR" -eq 1 ]; then
  57. printf ' \033[1;31merror:\033[0m %s\n' "$1" 1>&2
  58. else
  59. printf ' error: %s\n' "$1" 1>&2
  60. fi
  61. exit 1
  62. }
  63. # --- flags --------------------------------------------------------------
  64. usage() {
  65. cat <<EOF
  66. sem installer
  67. Usage: install.sh [options]
  68. Options:
  69. -v, --version VERSION install a specific version, e.g. v0.23.1 (default: latest)
  70. -d, --install-dir DIR install directory (default: \$HOME/.local/bin)
  71. -f, --force reinstall even if the target version is already present
  72. --skip-checksum install without SHA256 verification (NOT recommended)
  73. --no-color disable colored output
  74. -h, --help show this help
  75. Environment variables SEM_VERSION and SEM_INSTALL_DIR set the same defaults
  76. as --version and --install-dir.
  77. EOF
  78. }
  79. while [ $# -gt 0 ]; do
  80. case "$1" in
  81. -v|--version)
  82. [ $# -ge 2 ] || error "--version requires an argument"
  83. VERSION="$2"; shift 2 ;;
  84. -d|--install-dir)
  85. [ $# -ge 2 ] || error "--install-dir requires an argument"
  86. INSTALL_DIR="$2"; shift 2 ;;
  87. -f|--force)
  88. FORCE=1; shift ;;
  89. --skip-checksum)
  90. SKIP_CHECKSUM=1; shift ;;
  91. --no-color)
  92. USE_COLOR=0; shift ;;
  93. -h|--help)
  94. usage; exit 0 ;;
  95. *)
  96. error "unknown option: $1 (see --help)" ;;
  97. esac
  98. done
  99. require_cmd() {
  100. command -v "$1" >/dev/null 2>&1 || error "required command not found: $1"
  101. }
  102. # --- platform detection ---------------------------------------------------
  103. detect_platform() {
  104. OS=$(uname -s | tr '[:upper:]' '[:lower:]')
  105. ARCH=$(uname -m)
  106. case "$OS" in
  107. linux) OS_NAME="linux" ;;
  108. darwin) OS_NAME="darwin" ;;
  109. *)
  110. error "Unsupported OS: $OS. sem's install.sh supports macOS and Linux. \
  111. For Windows, see https://github.com/${REPO}#installation (Scoop) or download \
  112. sem-windows-x86_64.zip from https://github.com/${REPO}/releases." ;;
  113. esac
  114. case "$ARCH" in
  115. x86_64|amd64) ARCH_NAME="x86_64" ;;
  116. aarch64|arm64) ARCH_NAME="arm64" ;;
  117. *) error "Unsupported architecture: $ARCH (supported: x86_64, arm64/aarch64)" ;;
  118. esac
  119. ARTIFACT="sem-${OS_NAME}-${ARCH_NAME}"
  120. }
  121. # --- version resolution ---------------------------------------------------
  122. resolve_version() {
  123. if [ "$VERSION" = "latest" ]; then
  124. info "Resolving" "latest release"
  125. VERSION=$(curl -fsSL "https://api.github.com/repos/${REPO}/releases/latest" \
  126. | grep '"tag_name"' | head -1 | sed 's/.*"tag_name": *"//;s/".*//')
  127. [ -n "$VERSION" ] || error "Could not determine the latest version from the GitHub API"
  128. else
  129. # Accept "0.23.1" or "v0.23.1"; release tags are "vX.Y.Z".
  130. case "$VERSION" in
  131. v*) ;;
  132. *) VERSION="v${VERSION}" ;;
  133. esac
  134. fi
  135. }
  136. # --- idempotency: skip if this exact version is already installed --------
  137. already_installed() {
  138. [ "$FORCE" -eq 0 ] || return 1
  139. [ -x "${INSTALL_DIR}/${BINARY}" ] || return 1
  140. current=$("${INSTALL_DIR}/${BINARY}" --version 2>/dev/null || true)
  141. # `sem --version` output is expected to contain the version number.
  142. case "$current" in
  143. *"${VERSION#v}"*) return 0 ;;
  144. *) return 1 ;;
  145. esac
  146. }
  147. # --- checksum verification (fail closed) ----------------------------------
  148. sha256_of() {
  149. if command -v sha256sum >/dev/null 2>&1; then
  150. sha256sum "$1" | awk '{print $1}'
  151. elif command -v shasum >/dev/null 2>&1; then
  152. shasum -a 256 "$1" | awk '{print $1}'
  153. else
  154. error "no SHA256 tool found (need sha256sum or shasum) — cannot verify the download. Refusing to install."
  155. fi
  156. }
  157. verify_checksum() {
  158. archive="$1"
  159. if [ "$SKIP_CHECKSUM" -eq 1 ]; then
  160. warn "checksum verification skipped (--skip-checksum) — installing an UNVERIFIED binary"
  161. return 0
  162. fi
  163. sums_url="https://github.com/${REPO}/releases/download/${VERSION}/checksums.txt"
  164. sums=$(curl -fsSL "$sums_url" 2>/dev/null) || {
  165. error "could not fetch checksums.txt for ${VERSION} (${sums_url}). \
  166. Refusing to install an unverified binary. Re-run with --skip-checksum to \
  167. override at your own risk, or install a different --version."
  168. }
  169. expected=$(printf '%s\n' "$sums" | grep -F "${ARTIFACT}.tar.gz" | awk '{print $1}' | head -1)
  170. if [ -z "$expected" ]; then
  171. error "checksums.txt for ${VERSION} has no entry for ${ARTIFACT}.tar.gz. \
  172. Refusing to install an unverified binary. Re-run with --skip-checksum to \
  173. override at your own risk."
  174. fi
  175. actual=$(sha256_of "$archive")
  176. if [ "$actual" != "$expected" ]; then
  177. error "checksum mismatch for ${ARTIFACT}.tar.gz
  178. expected: ${expected}
  179. actual: ${actual}
  180. This could mean a corrupted download or a tampered release. Not installing."
  181. fi
  182. info "Verified" "SHA256 checksum"
  183. }
  184. # --- download + install ----------------------------------------------------
  185. download_and_install() {
  186. URL="https://github.com/${REPO}/releases/download/${VERSION}/${ARTIFACT}.tar.gz"
  187. TMPDIR=$(mktemp -d "${TMPDIR:-/tmp}/sem-install.XXXXXX")
  188. trap 'rm -rf "$TMPDIR"' EXIT INT TERM
  189. info "Downloading" "${ARTIFACT} ${VERSION}"
  190. curl -fsSL "$URL" -o "${TMPDIR}/${ARTIFACT}.tar.gz" \
  191. || error "download failed: ${URL}
  192. Check https://github.com/${REPO}/releases for available builds and versions."
  193. verify_checksum "${TMPDIR}/${ARTIFACT}.tar.gz"
  194. tar xzf "${TMPDIR}/${ARTIFACT}.tar.gz" -C "$TMPDIR"
  195. [ -f "${TMPDIR}/${BINARY}" ] || error "binary '${BINARY}' not found inside ${ARTIFACT}.tar.gz"
  196. mkdir -p "$INSTALL_DIR" || error "could not create install directory: ${INSTALL_DIR}"
  197. [ -w "$INSTALL_DIR" ] || error "install directory is not writable: ${INSTALL_DIR} \
  198. (this installer never uses sudo — pass --install-dir to pick a writable location)"
  199. # Atomic-ish install: write alongside, then rename into place.
  200. mv "${TMPDIR}/${BINARY}" "${INSTALL_DIR}/${BINARY}.new"
  201. chmod +x "${INSTALL_DIR}/${BINARY}.new"
  202. mv -f "${INSTALL_DIR}/${BINARY}.new" "${INSTALL_DIR}/${BINARY}"
  203. }
  204. # --- PATH guidance ----------------------------------------------------------
  205. path_guidance() {
  206. case ":$PATH:" in
  207. *":${INSTALL_DIR}:"*) return 0 ;;
  208. esac
  209. warn "${INSTALL_DIR} is not on your PATH"
  210. printf '\n'
  211. printf ' Add it in your shell rc file, then restart your shell:\n\n'
  212. printf ' bash/zsh: echo '\''export PATH="%s:$PATH"'\'' >> ~/.bashrc # or ~/.zshrc\n' "$INSTALL_DIR"
  213. printf ' fish: fish_add_path %s\n' "$INSTALL_DIR"
  214. printf '\n'
  215. }
  216. # --- main -------------------------------------------------------------------
  217. main() {
  218. require_cmd curl
  219. require_cmd tar
  220. require_cmd mktemp
  221. if [ "$USE_COLOR" -eq 1 ]; then
  222. printf '\n \033[1msem\033[0m installer\n\n'
  223. else
  224. printf '\n sem installer\n\n'
  225. fi
  226. detect_platform
  227. resolve_version
  228. if already_installed; then
  229. info "Already installed" "${VERSION} -> ${INSTALL_DIR}/${BINARY} (use --force to reinstall)"
  230. path_guidance
  231. exit 0
  232. fi
  233. download_and_install
  234. if [ -x "${INSTALL_DIR}/${BINARY}" ]; then
  235. if ! installed_version=$("${INSTALL_DIR}/${BINARY}" --version 2>&1); then
  236. # the binary is there but won't start (for example a glibc too old for it): say so, don't report success
  237. error "sem was installed to ${INSTALL_DIR}/${BINARY} but does not start on this system:
  238. ${installed_version}
  239. Please report it at https://github.com/${REPO}/issues with your OS version (cat /etc/os-release)."
  240. fi
  241. info "Installed" "${installed_version} -> ${INSTALL_DIR}/${BINARY}"
  242. else
  243. error "install appears to have failed: ${INSTALL_DIR}/${BINARY} is not executable"
  244. fi
  245. path_guidance
  246. if [ "$USE_COLOR" -eq 1 ]; then
  247. printf ' Run \033[1msem config setup\033[0m to replace git diff globally.\n'
  248. printf ' Run \033[1msem cloud login\033[0m to connect to sem cloud.\n'
  249. else
  250. printf ' Run "sem config setup" to replace git diff globally.\n'
  251. printf ' Run "sem cloud login" to connect to sem cloud.\n'
  252. fi
  253. printf '\n To uninstall: curl -fsSL https://raw.githubusercontent.com/%s/main/uninstall.sh | sh\n\n' "$REPO"
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 301 on GitHub
  254. }
  255. main
pi/src/bridge/bash-audit.ts · Bundled script · 415 lines · 1 finding marked
  1. import { isCodeFilePath, auditWriteCommand } from "./write-audit.ts";
  2. /**
  3. * Pure classifier for pi-sem's bash audit wrapper (no process spawning).
  4. *
  5. * Deliberately conservative: rules only ever match a statement's LEADING
  6. * command word(s) (after stripping an env-var prefix and normalizing an
  7. * absolute-path binary to its basename), a single level of $(...)/backtick
  8. * substitution, or (for "write") a redirect/verb pattern anywhere in the
  9. * statement, never scan mid-command generally beyond that, so a false
  10. * positive costs at most one audit-log entry by default (and one refusal
  11. * when PI_SEM_STRICT=1).
  12. *
  13. * NOT caught (deliberately, to keep this a "few regexes" classifier rather
  14. * than a shell parser -- a real adversary can defeat every rule below):
  15. * - nested command substitution, e.g. `$(echo $(cat f))` -- only one level
  16. * of $(...)/`...` is inspected
  17. * - a variable holding a command name, e.g. `CMD=cat; $CMD f.txt`
  18. * - `xargs cat`, `find . -exec cat {} \;`, or any command that itself
  19. * invokes a read verb as a sub-process argument rather than via -c/-e
  20. * - a read/write verb inside a heredoc BODY's own text content (the body
  21. * itself is stripped before classification -- see stripHeredocsAndHereStrings
  22. * -- but a verb appearing only as literal text inside that body, e.g. the
  23. * word "cat" mentioned in a comment being written, was never a command
  24. * anyway and correctly isn't classified)
  25. * - `python3 script.py` / `node script.js` running arbitrary file reads or
  26. * writes internally -- only the inline `-c`/`-e` forms are classified
  27. * - a `python -c '...'`/`node -e '...'` script's own file-write calls
  28. * (e.g. `open(path, "w")`) are not parsed -- the whole invocation is
  29. * already flagged "indirect" regardless of what the embedded script
  30. * does, which is as far as this classifier goes without a real
  31. * interpreter for that language
  32. * - shell aliases, functions, or `env` used as an indirection wrapper
  33. * (`env cat f.txt` is not normalized the way `/bin/cat` is)
  34. * - a `sed` in-place flag written via a variable (e.g. `FLAG=-i; sed $FLAG
  35. * ...`) -- both spellings recognized literally in the statement text
  36. * (`-i`, `--in-place`) are caught, but an indirect flag is not
  37. * - a flag that consumes a separate-token VALUE ahead of the trigger flag,
  38. * e.g. `node -r foo -e "..."` -- the leading-flag scan stops at the
  39. * first token that doesn't itself start with `-` (here, `foo`), so a
  40. * trigger flag appearing after such a value-bearing flag is not seen.
  41. * A flag that is merely ANOTHER leading `-`/`--` token (with no
  42. * separate-token value of its own), e.g. `bash --posix -c "..."`, does
  43. * NOT break the scan and so is correctly still caught.
  44. * - a backslash-escaped command (`\cat f.txt`, defeats shell aliasing),
  45. * the `command`/`builtin` prefix (`command cat f.txt`), bare `&`
  46. * backgrounding as a statement separator (`sleep 1 & cat f.txt`),
  47. * subshell parens (`( cat f.txt )`), or piping into a second-stage
  48. * shell (`echo 'cat f.txt' | sh`) -- none of these are normalized or
  49. * split on; each defeats every rule below (a later review's findings,
  50. * disclosed, not yet fixed)
  51. * - `base64 -d | sh`-style decode-then-execute chains -- no verb rule for
    • Note: Quoted as data in code: Mentions decoding base64 into a shell (no payload shown)
    • Line 52 on GitHub
  52. * decode utilities, and only one level of substitution is inspected
  53. * (disclosed, not yet fixed)
  54. * - a write's TARGET PATH extraction (below) is best-effort: quoted paths
  55. * with embedded spaces, `2>&1`-style fd duplication (deliberately
  56. * excluded, see REDIRECT_PATTERN), and multi-redirect statements only
  57. * ever resolve to the LAST redirect target found
  58. */
  59. export interface BashAuditMatch {
  60. ruleId: "read" | "search" | "find" | "list" | "indirect" | "write";
  61. statement: string;
  62. suggestedTool: string;
  63. /** Only set for ruleId "write" when a target path could be extracted (best-effort; see header). */
  64. path?: string;
  65. /** Only set alongside `path` -- whether that path's extension looks like a code file (see write-audit.ts's isCodeFilePath). */
  66. isCodeFile?: boolean;
  67. }
  68. /** Statements are split on these operators, then trimmed. `||` must come before `|`. */
  69. const STATEMENT_SPLIT = /\|\||&&|;|\||\n/;
  70. /** Leading `KEY=value ` assignments (`FOO=1 BAR=2 cmd`), stripped before matching. */
  71. const ENV_PREFIX = /^(?:[A-Za-z_][A-Za-z0-9_]*=(?:'[^']*'|"[^"]*"|\S*)\s+)+/;
  72. /** A single level of `$(...)` or `` `...` `` substitution content. */
  73. const SUBSTITUTION = /\$\(([^()]*)\)|`([^`]*)`/g;
  74. /**
  75. * A `>`/`>>` redirect NOT preceded by `-` (excludes `->`), NOT followed by
  76. * `=` (excludes `>=`), and NOT followed by `&` (excludes `2>&1`/`1>&2` fd
  77. * duplication, which never names a real file target). `&> file`/`&>> file`
  78. * (redirect both streams) IS matched -- the `&` sits before the `>`, which
  79. * this pattern doesn't look at, so the `>` itself still matches normally.
  80. */
  81. const REDIRECT_PATTERN = /(?<!-)>{1,2}(?!=)(?!&)\s*(['"]?)([^\s'"]+)\1/g;
  82. /**
  83. * Strips heredoc bodies and here-string tokens from the WHOLE command text,
  84. * before statement splitting -- both constructs can contain characters
  85. * STATEMENT_SPLIT treats as separators (`;`, `&&`, `|`, newlines), so this
  86. * must run first or a heredoc body gets shredded into bogus "statements".
  87. *
  88. * Here-strings (`<<< word` / `<<< 'quoted'` / `<<< "quoted"`) are a single
  89. * token, removed outright. Heredocs (`<<WORD`, `<<-WORD`, `<<~WORD`, with an
  90. * optionally quoted delimiter) keep whatever follows the marker on the SAME
  91. * line (e.g. `> out.txt` in `cat <<EOF > out.txt`) and strip everything from
  92. * the next line through the terminator line (a line consisting of just the
  93. * delimiter, optionally indented for `<<-`).
  94. *
  95. * This closes a real gap: the previous approach (skip
  96. * the WHOLE statement if it merely contained the substring "<<") meant
  97. * appending `<<< x` to ANY statement -- `head -100 file <<< x`, `cat foo.ts
  98. * <<< x` -- evaded classification entirely, a universal evasion suffix
  99. * disguised as a heredoc-write guard.
  100. */
  101. function stripHeredocsAndHereStrings(command: string): string {
  102. let result = command.replace(/<<<\s*(?:'[^']*'|"[^"]*"|\S+)/g, "");
  103. result = result.replace(/<<[-~]?(['"]?)(\w+)\1([^\n]*)\n[\s\S]*?^[ \t]*\2[ \t]*$\n?/gm, "$3");
  104. // Cosmetic only: stripping a token can leave a double space behind
  105. // (`cat <<EOF > out.txt` -> `cat > out.txt`) -- collapse horizontal
  106. // whitespace runs, never touching newlines (STATEMENT_SPLIT still needs
  107. // those as statement separators).
  108. return result.replace(/[ \t]{2,}/g, " ");
  109. }
  110. function stripEnvPrefix(statement: string): string {
  111. return statement.replace(ENV_PREFIX, "");
  112. }
  113. /** `/bin/cat foo.txt` -> `cat foo.txt`; `env`-based indirection is NOT unwrapped (see header). */
  114. function normalizeLeadingBinary(statement: string): string {
  115. return statement.replace(/^\/(?:[^\s/]+\/)*([^\s/]+)/, "$1");
  116. }
  117. /** Strip env-prefix then normalize an absolute-path binary, for matching only (reported statement stays raw). */
  118. function normalizeForMatch(statement: string): string {
  119. return normalizeLeadingBinary(stripEnvPrefix(statement));
  120. }
  121. /**
  122. * Recognizes sed's in-place flag in EITHER spelling: the short `-i`
  123. * (optionally with an attached suffix, `-i.bak`) or the GNU long form
  124. * `--in-place` (optionally `--in-place=.bak`). Previously only `-i` was
  125. * recognized, which meant `sed --in-place ...` fell through to the plain-
  126. * sed READ rule -- a MISCLASSIFICATION (reported as a read) rather than
  127. * merely uncaught, since neither the write rule's guard nor the read
  128. * rule's negated guard recognized the long form.
  129. */
  130. function hasSedInPlaceFlag(statement: string): boolean {
  131. return /(^|\s)-i\b/.test(statement) || /(^|\s)--in-place(\b|=)/.test(statement);
  132. }
  133. /**
  134. * True when `rest` (the tokens after the interpreter name) carries the
  135. * trigger letter (`c` for sh/bash/zsh/dash/python, `e` for node) in a
  136. * leading run of flag tokens -- either combined into one cluster
  137. * (`-lc`) or split across separate tokens (`-l -c`). Scans tokens from the
  138. * start and stops at the first non-flag token (the interpreter's actual
  139. * argument, e.g. the `-c` STRING itself, must not be scanned for stray
  140. * letters).
  141. */
  142. function hasIndirectTriggerFlag(rest: string, triggerLetter: string): boolean {
  143. const tokens = rest.trim().split(/\s+/);
  144. for (const token of tokens) {
  145. if (!token.startsWith("-")) break;
  146. if (token.slice(1).includes(triggerLetter)) return true;
  147. }
  148. return false;
  149. }
  150. /**
  151. * `sh|bash|zsh|dash|python(3)|node` followed by a leading run of flag
  152. * tokens carrying the trigger letter -- combined cluster (`bash -lc "..."`)
  153. * or split across separate tokens (`bash -l -c "..."`, `sh -e -c "..."`).
  154. * The split form was previously a documented gap:
  155. * `bash -lc` was caught but `bash -l -c` was not, even though both invoke
  156. * an opaque interpreted string identically.
  157. */
  158. function classifyIndirectShell(normalized: string): boolean {
  159. const match = /^(sh|bash|zsh|dash|python3?|node)\s*(.*)$/.exec(normalized);
  160. if (!match) return false;
  161. const interpreter = match[1] ?? "";
  162. const rest = match[2] ?? "";
  163. const trigger = interpreter === "node" ? "e" : "c";
  164. return hasIndirectTriggerFlag(rest, trigger);
  165. }
  166. /**
  167. * Best-effort write TARGET extraction for a statement already matched by
  168. * one of the "write" rules below. Not attempted for anything else -- this
  169. * is deliberately narrow, not a general shell-argument parser.
  170. */
  171. function extractWriteTargetPath(statement: string): string | undefined {
  172. REDIRECT_PATTERN.lastIndex = 0;
  173. const redirectMatches = [...statement.matchAll(REDIRECT_PATTERN)];
  174. if (redirectMatches.length > 0) {
  175. // Last redirect in the statement wins -- the common single-redirect
  176. // case has exactly one match; a multi-redirect statement's earlier
  177. // targets are a documented gap (see module header).
  178. return redirectMatches[redirectMatches.length - 1]?.[2];
  179. }
  180. const normalized = normalizeForMatch(statement);
  181. if (/^sed\b/.test(normalized) && hasSedInPlaceFlag(statement)) {
  182. const tokens = statement.trim().split(/\s+/);
  183. return tokens[tokens.length - 1];
  184. }
  185. if (/^tee\b/.test(normalized)) {
  186. const tokens = statement.trim().split(/\s+/).slice(1).filter((t) => !t.startsWith("-"));
  187. return tokens[0];
  188. }
  189. if (/^(cp|mv|truncate)\b/.test(normalized)) {
  190. // .slice(1) drops the leading command word itself -- without it, a
  191. // flags-only invocation with no real path argument (`truncate --help`)
  192. // would fall through to returning "truncate" itself as the "path"
  193. // once every flag token got filtered out.
  194. const tokens = statement.trim().split(/\s+/).slice(1).filter((t) => !t.startsWith("-"));
  195. return tokens[tokens.length - 1];
  196. }
  197. return undefined;
  198. }
  199. interface ClassificationRule {
  200. ruleId: BashAuditMatch["ruleId"];
  201. pattern: RegExp;
  202. suggestedTool: string;
  203. /** Extra predicate; when it returns false the rule does not apply. Receives the RAW (unnormalized) statement. */
  204. guard?: (statement: string) => boolean;
  205. }
  206. // Order matters: first match wins, one match max per statement. WRITE rules
  207. // come first so a statement that's both read-shaped and write-shaped
  208. // (`cat <<EOF > out.txt`, which after heredoc-stripping becomes
  209. // `cat > out.txt`) is classified by its write side -- the security-relevant
  210. // half -- not misreported as a plain read.
  211. const RULES: ClassificationRule[] = [
  212. {
  213. ruleId: "write",
  214. // `cmd > file` / `cmd >> file`, any leading command --
  215. // bash-side writes (redirection, sed -i, tee, cp, mv,
  216. // truncate) were never classified at all, so PI_SEM_STRICT's write
  217. // protection was fully bypassable through bash.
  218. pattern: REDIRECT_PATTERN,
  219. suggestedTool: "weave_edit for an existing entity, or the write tool for a new file, instead of a bash redirect",
  220. },
  221. {
  222. ruleId: "write",
  223. // The positive counterpart of the read rule's "sed without -i" guard
  224. // below -- WITH -i (short OR --in-place long form), sed genuinely
  225. // edits the file in place.
  226. guard: hasSedInPlaceFlag,
  227. pattern: /^sed\b/,
  228. suggestedTool: "weave_edit for an existing entity instead of bash sed -i/--in-place",
  229. },
  230. {
  231. ruleId: "write",
  232. pattern: /^(tee|cp|mv|truncate)\b/,
  233. suggestedTool: "weave_edit for an existing entity, or the write tool for a new file, instead of bash tee/cp/mv/truncate",
  234. },
  235. {
  236. ruleId: "read",
  237. // No heredoc/redirect guard needed here anymore: heredoc bodies are
  238. // stripped from the WHOLE command before statement splitting (see
  239. // stripHeredocsAndHereStrings), and a real `>`/`>>` redirect is caught
  240. // by the "write" rules above, which run first (first-match-wins) --
  241. // `cat file > out.txt` is classified "write", never reaching this rule.
  242. pattern: /^(cat|head|tail|less|more)\b/,
  243. suggestedTool: "sem_read (or sem_context) instead of bash cat/head/tail/less",
  244. },
  245. {
  246. ruleId: "read",
  247. // Plain `sed` (an edit) must NOT match; only sed WITHOUT an in-place
  248. // flag (short -i OR long --in-place) is a read (covers `sed -n ...` and
  249. // any other read-only use).
  250. guard: (statement) => !hasSedInPlaceFlag(statement),
  251. pattern: /^sed\b/,
  252. suggestedTool: "sem_read (or sem_context) instead of bash sed (no -i)",
  253. },
  254. {
  255. ruleId: "read",
  256. pattern: /^awk\b/,
  257. suggestedTool: "sem_read (or sem_context) instead of bash awk",
  258. },
  259. {
  260. ruleId: "search",
  261. pattern: /^(grep|rg|ag)\b/,
  262. suggestedTool: "sem_outline's text= (or sem_grep once available) instead of bash grep/rg/ag",
  263. },
  264. {
  265. ruleId: "find",
  266. pattern: /^(find|fd)\b/,
  267. suggestedTool: "sem_find (once available) instead of bash find/fd",
  268. },
  269. {
  270. ruleId: "list",
  271. pattern: /^(ls|tree)\b/,
  272. suggestedTool: "sem_outline (or sem_find once available) instead of bash ls/tree",
  273. },
  274. {
  275. ruleId: "indirect",
  276. // `sh -c "..."` / `bash -c "..."` / `python(3) -c "..."` / `node -e "..."`
  277. // run an opaque interpreted string -- classified as bypass-shaped
  278. // regardless of what the string contains (auditing its contents would
  279. // require actually parsing that language). The trigger letter (`c` for
  280. // sh/bash/zsh/dash/python, `e` for node) is matched whether it appears
  281. // in a combined CLUSTER (`bash -lc "..."`, `sh -ic "..."`, `bash -xc
  282. // "..."`) or split across separate leading flag tokens (`bash -l -c
  283. // "..."`, `sh -e -c "..."` -- previously a documented gap), so
  284. // `bash -lc` and `bash -l -c` are treated identically.
  285. // A false positive here only ever costs one audit-log entry, so
  286. // matching any leading flag run CONTAINING the trigger letter is the
  287. // conservative direction, even though a cluster like `-norc` (not a
  288. // real bash short-flag combination, but syntactically matches) would
  289. // also trip it.
  290. pattern: /^(sh|bash|zsh|dash|python3?|node)\b/,
  291. guard: (statement) => classifyIndirectShell(normalizeForMatch(statement)),
  292. suggestedTool: "an inline interpreter -c/-e invocation can run arbitrary reads/writes opaquely -- prefer sem_read/sem_outline/weave_edit directly",
  293. },
  294. ];
  295. function attachWriteFields(match: BashAuditMatch, statement: string): BashAuditMatch {
  296. if (match.ruleId !== "write") return match;
  297. const path = extractWriteTargetPath(statement);
  298. if (path === undefined) return match;
  299. return { ...match, path, isCodeFile: isCodeFilePath(path) };
  300. }
  301. function classifyLeadingCommand(rawStatement: string): BashAuditMatch | undefined {
  302. const normalized = normalizeForMatch(rawStatement);
  303. const rule = RULES.find((r) => r.pattern.test(normalized) && (r.guard?.(rawStatement) ?? true));
  304. if (!rule) return undefined;
  305. return attachWriteFields({ ruleId: rule.ruleId, statement: rawStatement, suggestedTool: rule.suggestedTool }, rawStatement);
  306. }
  307. /** Only a rule's own bare leading-command patterns are tried here -- not the "indirect" -c/-e rule itself (a substitution nested inside another -c/-e is not chased). */
  308. const SUBSTITUTION_INNER_RULES = RULES.filter((r) => r.ruleId !== "indirect");
  309. function classifySubstitutions(rawStatement: string): BashAuditMatch | undefined {
  310. SUBSTITUTION.lastIndex = 0;
  311. let match: RegExpExecArray | null;
  312. while ((match = SUBSTITUTION.exec(rawStatement))) {
  313. const inner = (match[1] ?? match[2] ?? "").trim();
  314. if (!inner) continue;
  315. const normalizedInner = normalizeForMatch(inner);
  316. const rule = SUBSTITUTION_INNER_RULES.find((r) => r.pattern.test(normalizedInner) && (r.guard?.(inner) ?? true));
  317. if (!rule) continue;
  318. return {
  319. ruleId: "indirect",
  320. statement: rawStatement,
  321. suggestedTool: `command substitution runs a ${rule.ruleId} (${inner.split(/\s+/)[0]}) whose output is used elsewhere -- ${rule.suggestedTool}`,
  322. };
  323. }
  324. return undefined;
  325. }
  326. export function classifyBashCommand(command: string): BashAuditMatch[] {
  327. const stripped = stripHeredocsAndHereStrings(command);
  328. const matches: BashAuditMatch[] = [];
  329. for (const rawStatement of stripped.split(STATEMENT_SPLIT)) {
  330. const statement = rawStatement.trim();
  331. if (statement.length === 0) continue;
  332. const match = classifyLeadingCommand(statement) ?? classifySubstitutions(statement);
  333. if (match) matches.push(match);
  334. }
  335. return matches;
  336. }
  337. export interface BashAuditDecision {
  338. matches: BashAuditMatch[];
  339. refuse: boolean;
  340. refusalMessage?: string;
  341. }
  342. /**
  343. * `resolveTargetExists` lets the caller (extensions/pi-sem.ts, which has
  344. * real fs access) answer "does this write's target already exist" for a
  345. * "write"-classified match with an extracted `path` -- mirroring
  346. * write-audit.ts's own pure-classifier-plus-caller-resolved-existence
  347. * split. Omitted (the default for every existing call site and test), a
  348. * "write" match never auto-refuses under strict mode -- audit-only, same
  349. * as a match with no extractable path at all. When provided and the write
  350. * targets an existing code file, the refusal is delegated to
  351. * write-audit.ts's own `auditWriteCommand` so the message is the SAME text
  352. * the builtin `write` tool wrapper already gives, not a separately-maintained
  353. * copy that can drift.
  354. */
  355. export function auditBashCommand(
  356. command: string,
  357. strict: boolean,
  358. resolveTargetExists?: (path: string) => boolean,
  359. ): BashAuditDecision {
  360. const matches = classifyBashCommand(command);
  361. if (matches.length === 0 || !strict) return { matches, refuse: false };
  362. const first = matches[0];
  363. if (first === undefined) return { matches, refuse: false };
  364. if (first.ruleId === "write") {
  365. if (first.path === undefined) return { matches, refuse: false };
  366. const targetExists = resolveTargetExists?.(first.path) ?? false;
  367. const writeDecision = auditWriteCommand(first.path, 0, targetExists, strict);
  368. if (!writeDecision.refuse) return { matches, refuse: false };
  369. // Prefix with the offending bash statement for context, then reuse the
  370. // builtin write wrapper's own refusalMessage's core guidance text
  371. // verbatim (its own leading "pi-sem: " is stripped so the two prefixes
  372. // don't double up) -- this is the "same message as the write wrapper",
  373. // guaranteed by sharing the string, not by separately maintaining
  374. // matching prose.
  375. return {
  376. matches,
  377. refuse: true,
  378. refusalMessage: `pi-sem: "${first.statement}" -- ${writeDecision.refusalMessage?.replace(/^pi-sem: /, "")}`,
  379. };
  380. }
  381. return {
  382. matches,
  383. refuse: true,
  384. refusalMessage:
  385. `pi-sem: "${first.statement}" looks like a file ${first.ruleId}` +
  386. ` -- use ${first.suggestedTool}.` +
  387. ` (PI_SEM_STRICT is set; unset it or set PI_SEM_STRICT=0 to audit instead of refuse.)`,
  388. };
  389. }

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.