Skip to content

Commit 0970965

Browse files
orenlaborenlab
committed
docs(clients): standardize uv installs and tighten Codex MCP-only guardrails
1 parent ed6b003 commit 0970965

22 files changed

Lines changed: 134 additions & 97 deletions

‎AGENTS.md‎

Lines changed: 14 additions & 14 deletions
Large diffs are not rendered by default.

‎CHANGELOG.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,8 @@
1313
- Bump canonical report schema to `2.3`.
1414
- Add `metrics.overloaded_modules` — report-only module-hotspot ranking by size, complexity, and coupling pressure.
1515
- Surface Overloaded Modules across JSON, text/markdown, HTML, and MCP without affecting findings, health, or gates.
16-
- Normalize the canonical family name and MCP/report output to `overloaded_modules`; `god_modules` remains accepted as a read-only MCP input alias during transition.
16+
- Normalize the canonical family name and MCP/report output to `overloaded_modules`; `god_modules` remains accepted as a
17+
read-only MCP input alias during transition.
1718

1819
### CLI and HTML
1920

‎README.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ Live sample report:
5757
## Quick Start
5858

5959
```bash
60-
pip install codeclone # or: uv tool install codeclone
60+
uv tool install codeclone
6161

6262
codeclone . # analyze
6363
codeclone . --html # HTML report
@@ -164,7 +164,7 @@ Optional read-only MCP server for AI agents and IDE clients.
164164
21 tools + 10 resources — never mutates source, baselines, or repo state.
165165
166166
```bash
167-
pip install "codeclone[mcp]"
167+
uv tool install "codeclone[mcp]"
168168

169169
codeclone-mcp --transport stdio # local (Claude Code, Codex, Copilot, Gemini CLI)
170170
codeclone-mcp --transport streamable-http # remote / HTTP-only clients
@@ -177,11 +177,11 @@ Docs:
177177

178178
### Native Client Surfaces
179179

180-
| Surface | Location | Purpose |
181-
|---------|----------|---------|
182-
| **VS Code extension** | [`extensions/vscode-codeclone/`](https://github.com/orenlab/codeclone/tree/main/extensions/vscode-codeclone) | Triage-first structural review in the editor |
183-
| **Claude Desktop bundle** | [`extensions/claude-desktop-codeclone/`](https://github.com/orenlab/codeclone/tree/main/extensions/claude-desktop-codeclone) | Local `.mcpb` install surface |
184-
| **Codex plugin** | [`plugins/codeclone/`](https://github.com/orenlab/codeclone/tree/main/plugins/codeclone) | Native Codex discovery, skill, and MCP definition |
180+
| Surface | Location | Purpose |
181+
|---------------------------|------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|
182+
| **VS Code extension** | [`extensions/vscode-codeclone/`](https://github.com/orenlab/codeclone/tree/main/extensions/vscode-codeclone) | Triage-first structural review in the editor |
183+
| **Claude Desktop bundle** | [`extensions/claude-desktop-codeclone/`](https://github.com/orenlab/codeclone/tree/main/extensions/claude-desktop-codeclone) | Local `.mcpb` install surface |
184+
| **Codex plugin** | [`plugins/codeclone/`](https://github.com/orenlab/codeclone/tree/main/plugins/codeclone) | Native Codex discovery, skill, and MCP definition |
185185

186186
All three are thin wrappers over the same `codeclone-mcp` contract — no second analysis engine.
187187

‎docs/README.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,11 @@ This site is built with MkDocs and published to
44
[orenlab.github.io/codeclone](https://orenlab.github.io/codeclone/).
55

66
!!! note "Version Notice"
7-
This site currently documents the in-development `v2.0.x` line from `main`.
8-
For the latest stable CodeClone documentation (`v1.4.4`), see the
9-
[`v1.4.4` README](https://github.com/orenlab/codeclone/blob/v1.4.4/README.md)
10-
and the
11-
[`v1.4.4` docs tree](https://github.com/orenlab/codeclone/tree/v1.4.4/docs).
7+
This site currently documents the in-development `v2.0.x` line from `main`.
8+
For the latest stable CodeClone documentation (`v1.4.4`), see the
9+
[`v1.4.4` README](https://github.com/orenlab/codeclone/blob/v1.4.4/README.md)
10+
and the
11+
[`v1.4.4` docs tree](https://github.com/orenlab/codeclone/tree/v1.4.4/docs).
1212

1313
It has two documentation layers:
1414

‎docs/assets/codeclone-wordmark-dark.svg‎

Lines changed: 2 additions & 1 deletion
Loading

‎docs/assets/codeclone-wordmark.svg‎

Lines changed: 2 additions & 1 deletion
Loading

‎docs/book/01-architecture-map.md‎

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -23,22 +23,22 @@ Main ownership layers:
2323

2424
## Data model
2525

26-
| Layer | Modules | Responsibility |
27-
|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|
28-
| Contracts | `codeclone/contracts.py`, `codeclone/errors.py` | Shared schema versions, URLs, exit-code enum, typed exceptions |
29-
| Domain models | `codeclone/models.py`, `codeclone/domain/*.py` | Typed dataclasses/enums plus centralized finding/scope/severity taxonomies |
30-
| Discovery + parsing | `codeclone/scanner.py`, `codeclone/extractor.py` | Enumerate files, parse AST, extract function/block/segment units |
31-
| Structural analysis | `codeclone/cfg.py`, `codeclone/normalize.py`, `codeclone/fingerprint.py`, `codeclone/blocks.py` | CFG, normalization, statement hashes, block/segment windows |
32-
| Grouping | `codeclone/grouping.py` | Build function/block/segment groups |
33-
| Metrics | `codeclone/metrics/*` | Compute complexity/coupling/cohesion/dependency/dead-code/health signals |
34-
| Report core | `codeclone/report/*`, `codeclone/_cli_meta.py` | Canonical report building, deterministic projections, explainability facts, and shared metadata |
35-
| Persistence | `codeclone/baseline.py`, `codeclone/metrics_baseline.py`, `codeclone/cache.py` | Baseline/cache trust/compat/integrity and atomic persistence |
36-
| Runtime orchestration | `codeclone/pipeline.py`, `codeclone/cli.py`, `codeclone/_cli_args.py`, `codeclone/_cli_paths.py`, `codeclone/_cli_summary.py`, `codeclone/_cli_config.py`, `codeclone/ui_messages.py` | CLI UX, stage orchestration, status handling, outputs, error markers |
37-
| MCP agent interface | `codeclone/mcp_service.py`, `codeclone/mcp_server.py` | Read-only MCP tools/resources over canonical analysis and report layers |
26+
| Layer | Modules | Responsibility |
27+
|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
28+
| Contracts | `codeclone/contracts.py`, `codeclone/errors.py` | Shared schema versions, URLs, exit-code enum, typed exceptions |
29+
| Domain models | `codeclone/models.py`, `codeclone/domain/*.py` | Typed dataclasses/enums plus centralized finding/scope/severity taxonomies |
30+
| Discovery + parsing | `codeclone/scanner.py`, `codeclone/extractor.py` | Enumerate files, parse AST, extract function/block/segment units |
31+
| Structural analysis | `codeclone/cfg.py`, `codeclone/normalize.py`, `codeclone/fingerprint.py`, `codeclone/blocks.py` | CFG, normalization, statement hashes, block/segment windows |
32+
| Grouping | `codeclone/grouping.py` | Build function/block/segment groups |
33+
| Metrics | `codeclone/metrics/*` | Compute complexity/coupling/cohesion/dependency/dead-code/health signals |
34+
| Report core | `codeclone/report/*`, `codeclone/_cli_meta.py` | Canonical report building, deterministic projections, explainability facts, and shared metadata |
35+
| Persistence | `codeclone/baseline.py`, `codeclone/metrics_baseline.py`, `codeclone/cache.py` | Baseline/cache trust/compat/integrity and atomic persistence |
36+
| Runtime orchestration | `codeclone/pipeline.py`, `codeclone/cli.py`, `codeclone/_cli_args.py`, `codeclone/_cli_paths.py`, `codeclone/_cli_summary.py`, `codeclone/_cli_config.py`, `codeclone/ui_messages.py` | CLI UX, stage orchestration, status handling, outputs, error markers |
37+
| MCP agent interface | `codeclone/mcp_service.py`, `codeclone/mcp_server.py` | Read-only MCP tools/resources over canonical analysis and report layers |
3838
| VS Code extension | `extensions/vscode-codeclone/*` | Native VS Code control surface over MCP, with limited Restricted Mode, triage-first review, and source-first drill-down |
39-
| Claude Desktop bundle | `extensions/claude-desktop-codeclone/*` | Installable local MCPB wrapper over `codeclone-mcp`, keeping Claude Desktop on the canonical read-only MCP surface |
40-
| Codex plugin | `plugins/codeclone/*`, `.agents/plugins/marketplace.json` | Native Codex plugin surface over `codeclone-mcp`, with repo-local discovery metadata and CodeClone skill guidance |
41-
| Rendering | `codeclone/html_report.py`, `codeclone/_html_report/*`, `codeclone/_html_badges.py`, `codeclone/_html_js.py`, `codeclone/_html_escape.py`, `codeclone/_html_snippets.py`, `codeclone/templates.py` | HTML-only view layer over report data |
39+
| Claude Desktop bundle | `extensions/claude-desktop-codeclone/*` | Installable local MCPB wrapper over `codeclone-mcp`, keeping Claude Desktop on the canonical read-only MCP surface |
40+
| Codex plugin | `plugins/codeclone/*`, `.agents/plugins/marketplace.json` | Native Codex plugin surface over `codeclone-mcp`, with repo-local discovery metadata and CodeClone skill guidance |
41+
| Rendering | `codeclone/html_report.py`, `codeclone/_html_report/*`, `codeclone/_html_badges.py`, `codeclone/_html_js.py`, `codeclone/_html_escape.py`, `codeclone/_html_snippets.py`, `codeclone/templates.py` | HTML-only view layer over report data |
4242

4343
Refs:
4444

@@ -140,8 +140,8 @@ Refs:
140140
| Report schema and provenance | [08-report.md](08-report.md), [10-html-render.md](10-html-render.md) |
141141
| MCP agent surface | [20-mcp-interface.md](20-mcp-interface.md) |
142142
| VS Code IDE surface | [21-vscode-extension.md](21-vscode-extension.md) |
143-
| Claude Desktop install surface | [22-claude-desktop-bundle.md](22-claude-desktop-bundle.md) |
144-
| Codex plugin surface | [23-codex-plugin.md](23-codex-plugin.md) |
143+
| Claude Desktop install surface | [22-claude-desktop-bundle.md](22-claude-desktop-bundle.md) |
144+
| Codex plugin surface | [23-codex-plugin.md](23-codex-plugin.md) |
145145
| Health score model | [15-health-score.md](15-health-score.md) |
146146
| Metrics gates and metrics baseline | [15-metrics-and-quality-gates.md](15-metrics-and-quality-gates.md) |
147147
| Dead-code liveness policy | [16-dead-code-contract.md](16-dead-code-contract.md) |

‎docs/book/11-security-model.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -59,13 +59,13 @@ Refs:
5959

6060
## Failure modes
6161

62-
| Condition | Security behavior |
63-
|------------------------------------------|-------------------|
64-
| Symlink points outside root | File skipped |
65-
| Root under sensitive dirs | Validation error |
66-
| Oversized baseline | Baseline rejected |
67-
| Oversized cache | Cache ignored |
68-
| HTML-injected payload in metadata/source | Escaped output |
62+
| Condition | Security behavior |
63+
|------------------------------------------|--------------------|
64+
| Symlink points outside root | File skipped |
65+
| Root under sensitive dirs | Validation error |
66+
| Oversized baseline | Baseline rejected |
67+
| Oversized cache | Cache ignored |
68+
| HTML-injected payload in metadata/source | Escaped output |
6969
| `--allow-remote` not passed for HTTP | Transport rejected |
7070
| `cache_policy=refresh` requested | Policy rejected |
7171
| `git_diff_ref` fails regex | Parameter rejected |

‎docs/book/19-inline-suppressions.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,9 @@ Refs:
3333
- Supported placements:
3434
- previous line before declaration (`leading`)
3535
- end-of-line comment on declaration header (`inline`)
36-
- same-line single-line declaration
37-
- first line of a multiline declaration header
38-
- closing header line containing `:`
36+
- same-line single-line declaration
37+
- first line of a multiline declaration header
38+
- closing header line containing `:`
3939
- Current supported dead-code rule id: `dead-code`.
4040
- Rule list supports comma-separated values and deduplicates deterministically.
4141
- Suppression applies only to declaration targets (`def`, `async def`, `class`).

‎docs/book/22-claude-desktop-bundle.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,8 @@ The bundle currently provides:
4040
- one installable `.mcpb` package
4141
- one local Node launcher wrapper
4242
- two user settings:
43-
- launcher command
44-
- advanced launcher args as a JSON array
43+
- launcher command
44+
- advanced launcher args as a JSON array
4545
- one build script for deterministic local packaging
4646

4747
It intentionally does not add bundle-only MCP tools or prompts.

0 commit comments

Comments
 (0)