sensez 0.2.4 → 0.2.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +68 -44
  2. package/package.json +5 -5
package/README.md CHANGED
@@ -1,22 +1,67 @@
1
- # Sensez
1
+ # sensez
2
2
 
3
- [![PyPI](https://img.shields.io/pypi/v/sensez?logo=pypi&logoColor=white)](https://pypi.org/project/sensez/) [![npm](https://img.shields.io/npm/v/sensez?logo=npm&logoColor=white)](https://www.npmjs.com/package/sensez) [![CI](https://github.com/popov95s/sensez/actions/workflows/ci.yml/badge.svg)](https://github.com/popov95s/sensez/actions/workflows/ci.yml) [![Website](https://img.shields.io/badge/website-sensez.dev-222222?logo=googlechrome&logoColor=white)](https://sensez.dev) [![Documentation](https://img.shields.io/badge/docs-latest-222222?logo=readthedocs&logoColor=white)](https://popov95s.github.io/sensez/latest/) [![License: MIT](https://img.shields.io/badge/license-MIT-2ea44f)](https://github.com/popov95s/sensez/blob/main/LICENSE.MD)
3
+ [![PyPI](https://img.shields.io/pypi/v/sensez?logo=pypi&logoColor=white)](https://pypi.org/project/sensez/) [![npm](https://img.shields.io/npm/v/sensez?logo=npm&logoColor=white)](https://www.npmjs.com/package/sensez) [![CI](https://github.com/popov95s/sensez/actions/workflows/ci.yml/badge.svg)](https://github.com/popov95s/sensez/actions/workflows/ci.yml) [![Website](https://img.shields.io/badge/website-sensez.dev-222222?logo=googlechrome&logoColor=white)](https://sensez.dev) [![Documentation](https://img.shields.io/badge/docs-latest-222222?logo=readthedocs&logoColor=white)](https://popov95s.github.io/sensez/latest/) [![License: MIT](https://img.shields.io/badge/license-MIT-2ea44f)](https://github.com/popov95s/sensez/blob/main/LICENSE)
4
4
 
5
- **Structural maintainability checks for coding agents and teams.**
5
+ **Bring your coding agent to its senses.**
6
6
 
7
- Sensez is a suite of Rust CLIs and an MCP server that runs alongside your linter
8
- and type-checker. It finds cross-file problems that those tools do not usually
9
- own: duplication, dead code, import cycles, architecture-boundary violations,
10
- and design smells.
7
+ Coding agents drift. CI catches the result too late, and non-blocking reports become Jira tickets nobody picks up.
11
8
 
12
- It gives coding agents the `noze` to detect code smells, the `bonez` to respect
13
- architectural boundaries, and the `spine` to do it fast. Python, JavaScript,
14
- TypeScript/TSX, and Rust profiles are supported (Rust primarily for dogfooding).
9
+ sensez runs inside the coding-agent loop, giving agents fast, structured feedback on duplication, dead code, cycles, architecture violations, and design smells—so they fix problems before technical debt compounds.
10
+
11
+ In controlled evaluations, agents using Sensez produced 86% fewer quality issues, 90% less duplicated code, and 67% fewer lines.
15
12
 
16
13
  **[Website](https://sensez.dev)** ·
17
14
  **[Documentation](https://popov95s.github.io/sensez/latest/)** ·
18
15
  **[MCP and agent guide](https://popov95s.github.io/sensez/latest/usage/mcp-and-agents/)** ·
19
- **[Configuration reference](https://popov95s.github.io/sensez/latest/reference/configuration/)** ·
16
+ **[Configuration reference](https://popov95s.github.io/sensez/latest/reference/configuration/)**
17
+
18
+ ## Quick start
19
+
20
+ ### Python
21
+
22
+ ```bash
23
+ uv add --dev sensez # or install globally: uv tool install sensez
24
+ uv run sensez init # writes a starter config and registers the MCP server
25
+ uv run sensez noze . # scan once — no install needed with: uvx sensez noze .
26
+ ```
27
+
28
+ ### JavaScript and TypeScript
29
+
30
+ ```bash
31
+ npm install --save-dev sensez
32
+ npx sensez init
33
+ npx sensez noze .
34
+ ```
35
+
36
+ `sensez init` writes a commented starter `sensez.toml` and registers Sensez as
37
+ an MCP server with your coding agent — Claude Code, Cursor, Cline, Codex,
38
+ OpenCode, and Pi are supported. **Restart the agent afterwards** so the server
39
+ is picked up. `sensez .` and `sensez noze .` both run the default scan.
40
+
41
+ A report is one screen, focused on what to fix first:
42
+
43
+ ```text
44
+ $ sensez noze .
45
+ sensez — structural maintainability report
46
+
47
+ Circular imports (1)
48
+ [warning] ↻ shop.promo → shop.cart
49
+ ./shop/promo.py:1 shop.promo → shop.cart
50
+ ./shop/cart.py:1 shop.cart → shop.promo
51
+
52
+ Duplication (1)
53
+ [advisory] structural clone (53):
54
+ ./shop/clone_a.py:1-12
55
+ ./shop/clone_b.py:1-12
56
+
57
+ Dead code candidates (2)
58
+ [advisory] ./shop/legacy.py:1 shop.legacy::orphan_helper (function) [high]
59
+ [advisory] ./shop/promo.py:10 shop.promo::recap (function) [high]
60
+
61
+ Code smells (0)
62
+
63
+ Boundary violations (not configured)
64
+ ```
20
65
 
21
66
  ## Why Sensez?
22
67
 
@@ -46,37 +91,6 @@ Sensez complements—not replaces—Ruff, ty, mypy, ESLint, TypeScript, `rustc`,
46
91
  and Clippy. Use those tools for local correctness; use Sensez for the structural
47
92
  relationships across the codebase.
48
93
 
49
- ## Quick start
50
-
51
- ### Python
52
-
53
- ```bash
54
- # Add to a project; run it with `uv run sensez ...`
55
- uv add --dev sensez
56
- uv run sensez init
57
-
58
- # Or install a global CLI
59
- uv tool install sensez
60
- sensez init
61
-
62
- # Or run a one-off scan
63
- uvx sensez noze .
64
- ```
65
-
66
- ### JavaScript and TypeScript
67
-
68
- ```bash
69
- # Add as a development dependency
70
- npm install --save-dev sensez
71
-
72
- # Generate a starter config and scan
73
- npx sensez init .
74
- npx sensez noze .
75
- ```
76
-
77
- `sensez .` and `sensez noze .` both run the default scan. The explicit form
78
- `sensez noze sniff .` remains available for agent-oriented workflows.
79
-
80
94
  ## What it finds
81
95
 
82
96
  | Area | Output key | What it catches |
@@ -102,6 +116,7 @@ Some examples of the included smells:
102
116
  | `magic_string_default` | <code>&#124;&#124; ""</code> or <code>or ""</code> hides a string that should be required. |
103
117
  | `split_variable` | Multiple reassignments of a variable in one scope add hidden state. |
104
118
  | `nested_loop` | **Beta, opt-in:** nested iteration may have unintended complexity. |
119
+ | `nested_ternary` | Nested conditional expressions make agent-generated decisions hard to follow. |
105
120
  | `n_plus_one_call` | **Beta, opt-in:** one-by-one external calls may need batching. |
106
121
 
107
122
  The default report is intentionally fixable in one screen: each pillar shows its
@@ -162,13 +177,16 @@ for the methodology and per-benchmark results.
162
177
  ## MCP for agents
163
178
 
164
179
  MCP is the recommended integration when Sensez should run repeatedly during a
165
- coding session rather than as a one-off shell command. The `init` command would set this up automatically on agent start.
180
+ coding session rather than as a one-off shell command. `sensez init` registers
181
+ the server with your coding agent, which then launches it automatically at
182
+ startup — there is nothing to run by hand.
166
183
 
167
184
  | Tool | Use |
168
185
  | --- | --- |
169
186
  | `noze_sniff` | Scan the repository for smells and structural issues. |
170
187
  | `noze_gate` | Experimental end-of-turn diff gate; may be noisy for short or Q&A turns. |
171
188
  | `noze_explain` | Explain a finding category. |
189
+ | `get_configuration_summary` | Summarize the effective configuration and noisiest rules when tuning. |
172
190
  | `brainz_report` | Summarize local usage and resolution metrics. |
173
191
  | `brainz_triage` | Record user-approved debt or false-positive verdicts. |
174
192
  | `eyez_search_docs` | Disabled unless `eyez` is enabled; searches docstrings and comments. |
@@ -214,6 +232,12 @@ enabled = true
214
232
  enabled = true
215
233
  ```
216
234
 
235
+ Smell rules can also be overridden per language, and every finding carries an
236
+ action level (`info` → `must_fix`) that drives gates and CI. See the
237
+ [Configuration reference](https://popov95s.github.io/sensez/latest/reference/configuration/)
238
+ for action levels, per-language overrides, boundary patterns, and accepting
239
+ findings.
240
+
217
241
  ## Local-only metrics and privacy
218
242
 
219
243
  `brainz` records scans, gate blocks, triage decisions, resolved findings,
@@ -237,7 +261,7 @@ enabled = false
237
261
  - `spine`: file discovery, parsing, shared IR, and dependency graph.
238
262
  - `profiles`: language adapters for Python, JS/TS, TSX, and Rust.
239
263
  - `noze`: duplication, dead code, cycles, and design smells.
240
- - `bonez`: architecture-boundary auditing; not yet enabled.
264
+ - `bonez`: architecture-boundary auditing.
241
265
  - `brainz`: local-only metrics and feedback memory.
242
266
  - `eyez`: optional doc/comment search; not yet enabled.
243
267
  - `mcp`: JSON-RPC/MCP surface for agent integration.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sensez",
3
- "version": "0.2.4",
3
+ "version": "0.2.5",
4
4
  "description": "Sensez CLI launcher for structural maintainability checks",
5
5
  "license": "MIT",
6
6
  "readme": "README.md",
@@ -18,10 +18,10 @@
18
18
  "README.md"
19
19
  ],
20
20
  "optionalDependencies": {
21
- "sensez-darwin-arm64": "0.2.4",
22
- "sensez-darwin-x64": "0.2.4",
23
- "sensez-linux-arm64-gnu": "0.2.4",
24
- "sensez-linux-x64-gnu": "0.2.4"
21
+ "sensez-darwin-arm64": "0.2.5",
22
+ "sensez-darwin-x64": "0.2.5",
23
+ "sensez-linux-arm64-gnu": "0.2.5",
24
+ "sensez-linux-x64-gnu": "0.2.5"
25
25
  },
26
26
  "publishConfig": {
27
27
  "provenance": true