@opencodehub/cli 0.2.1 → 0.2.3
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.
- package/dist/commands/ci-templates/github-nightly.yml +35 -0
- package/dist/commands/ci-templates/github-rescan.yml +52 -0
- package/dist/commands/ci-templates/github-verdict.yml +24 -0
- package/dist/commands/ci-templates/github-weekly.yml +49 -0
- package/dist/commands/ci-templates/gitlab-ci.yml +56 -0
- package/dist/index.js +9 -1
- package/dist/index.js.map +1 -1
- package/dist/plugin-assets/agents/code-analyst.md +18 -0
- package/dist/plugin-assets/commands/audit-deps.md +29 -0
- package/dist/plugin-assets/commands/owners.md +20 -0
- package/dist/plugin-assets/commands/probe.md +21 -0
- package/dist/plugin-assets/commands/rename.md +20 -0
- package/dist/plugin-assets/commands/verdict.md +18 -0
- package/dist/plugin-assets/hooks/augment.sh +128 -0
- package/dist/plugin-assets/hooks/docs-staleness.sh +45 -0
- package/dist/plugin-assets/hooks.json +34 -0
- package/dist/plugin-assets/skills/codehub-code-pack/SKILL.md +181 -0
- package/dist/plugin-assets/skills/codehub-code-pack/references/determinism-contract.md +150 -0
- package/dist/plugin-assets/skills/codehub-contract-map/SKILL.md +144 -0
- package/dist/plugin-assets/skills/codehub-document/SKILL.md +152 -0
- package/dist/plugin-assets/skills/codehub-document/references/cross-reference-spec.md +142 -0
- package/dist/plugin-assets/skills/codehub-document/references/data-source-map.md +139 -0
- package/dist/plugin-assets/skills/codehub-document/references/document-templates.md +347 -0
- package/dist/plugin-assets/skills/codehub-document/references/mermaid-patterns.md +181 -0
- package/dist/plugin-assets/skills/codehub-document/templates/agents/README.md +64 -0
- package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-analysis-dead-code.md +104 -0
- package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-analysis-ownership.md +101 -0
- package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-analysis-risk-hotspots.md +105 -0
- package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-architecture-data-flow.md +103 -0
- package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-architecture-module-map.md +102 -0
- package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-architecture-system-overview.md +100 -0
- package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-behavior-processes.md +103 -0
- package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-behavior-state-machines.md +101 -0
- package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-cross-repo-contracts-matrix.md +104 -0
- package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-cross-repo-dependency-flow.md +111 -0
- package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-cross-repo-portfolio-map.md +106 -0
- package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-diagrams-components.md +99 -0
- package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-diagrams-dependency-graph.md +104 -0
- package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-diagrams-sequences.md +103 -0
- package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-reference-cli.md +110 -0
- package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-reference-mcp-tools.md +100 -0
- package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-reference-public-api.md +111 -0
- package/dist/plugin-assets/skills/codehub-document/templates/orchestrator-prompt.md +110 -0
- package/dist/plugin-assets/skills/codehub-onboarding/SKILL.md +111 -0
- package/dist/plugin-assets/skills/codehub-pr-description/SKILL.md +122 -0
- package/dist/plugin-assets/skills/opencodehub-debugging/SKILL.md +144 -0
- package/dist/plugin-assets/skills/opencodehub-exploring/SKILL.md +120 -0
- package/dist/plugin-assets/skills/opencodehub-guide/SKILL.md +180 -0
- package/dist/plugin-assets/skills/opencodehub-impact-analysis/SKILL.md +151 -0
- package/dist/plugin-assets/skills/opencodehub-pr-review/SKILL.md +246 -0
- package/dist/plugin-assets/skills/opencodehub-refactoring/SKILL.md +180 -0
- package/package.json +16 -14
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: opencodehub-impact-analysis
|
|
3
|
+
description: "Use when the user wants to know what will break if they change something, or needs safety analysis before editing or merging code. Examples: \"Is it safe to change X?\", \"What depends on this?\", \"What will break?\", \"Blast radius for this change\"."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Impact Analysis with OpenCodeHub
|
|
7
|
+
|
|
8
|
+
## When to Use
|
|
9
|
+
|
|
10
|
+
- "Is it safe to change this function?"
|
|
11
|
+
- "What will break if I modify X?"
|
|
12
|
+
- "Show me the blast radius."
|
|
13
|
+
- "Who uses this code?"
|
|
14
|
+
- Before committing or merging a non-trivial change.
|
|
15
|
+
|
|
16
|
+
## Decision Tree
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
Is the target a symbol (function, class, method, property)?
|
|
20
|
+
└─ yes → mcp__opencodehub__impact
|
|
21
|
+
Is the target an HTTP route or API endpoint?
|
|
22
|
+
└─ yes → mcp__opencodehub__api_impact + mcp__opencodehub__route_map
|
|
23
|
+
Is the change a response-shape edit on a route?
|
|
24
|
+
└─ yes → mcp__opencodehub__shape_check (find consumer key-access mismatches)
|
|
25
|
+
Is the target a dependency version bump?
|
|
26
|
+
└─ yes → mcp__opencodehub__dependencies + mcp__opencodehub__license_audit
|
|
27
|
+
Want to see what the working tree currently touches?
|
|
28
|
+
└─ yes → mcp__opencodehub__detect_changes
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Workflow
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
1. mcp__opencodehub__impact({ name, direction: "upstream", repo }) → Dependents of the target
|
|
35
|
+
2. Read confidenceBreakdown → Trust the confirmed count
|
|
36
|
+
3. If HTTP-adjacent: mcp__opencodehub__api_impact + shape_check → Route + shape mismatches
|
|
37
|
+
4. mcp__opencodehub__detect_changes → Map the current diff to flows
|
|
38
|
+
5. Assess risk tier and write the summary
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
> If the context envelope warns the index is stale, run `codehub analyze` first — stale impact results are worse than no impact results.
|
|
42
|
+
|
|
43
|
+
## Checklist
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
- [ ] mcp__opencodehub__impact({ name, direction: "upstream", repo })
|
|
47
|
+
- [ ] Review byDepth.d1 first — these WILL BREAK
|
|
48
|
+
- [ ] Read confidenceBreakdown; demand confirmed >= heuristic for destructive calls
|
|
49
|
+
- [ ] Filter to confidence >= 0.9 if the target is load-bearing (auth, payments, data integrity)
|
|
50
|
+
- [ ] If target is a Route: mcp__opencodehub__api_impact + mcp__opencodehub__shape_check
|
|
51
|
+
- [ ] mcp__opencodehub__detect_changes to map the current diff to affected processes
|
|
52
|
+
- [ ] Produce a risk tier and a one-paragraph summary
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## Understanding impact output
|
|
56
|
+
|
|
57
|
+
Risk levels map to blast-radius tiers:
|
|
58
|
+
|
|
59
|
+
| Depth | Risk Level | Meaning |
|
|
60
|
+
| ----- | ---------------- | -------------------------------------- |
|
|
61
|
+
| d=1 | WILL BREAK | Direct callers / importers / overrides |
|
|
62
|
+
| d=2 | LIKELY AFFECTED | One hop through d=1 |
|
|
63
|
+
| d=3 | MAY NEED TESTING | Two hops — transitive effects |
|
|
64
|
+
|
|
65
|
+
`confidenceBreakdown` on the impact response categorises the edges the tool actually traversed:
|
|
66
|
+
|
|
67
|
+
- `confirmed` — a SCIP indexer (scip-typescript, scip-python, scip-go, rust-analyzer, scip-java) confirmed the edge at confidence ≥ 0.95. Trust these for refactor/impact decisions.
|
|
68
|
+
- `heuristic` — tree-sitter or tier-1/tier-2 inference; no SCIP indexer covers this triple. Treat as a signal, not a ground truth.
|
|
69
|
+
- `unknown` — confidence ≤ 0.2. The demote phase flagged the edge (`+scip-unconfirmed`). Do not act on these alone.
|
|
70
|
+
|
|
71
|
+
## Risk Tier Guide
|
|
72
|
+
|
|
73
|
+
| Signal | Risk |
|
|
74
|
+
| ---------------------------------------------- | -------- |
|
|
75
|
+
| < 5 symbols, ≤ 1 process, all confirmed | LOW |
|
|
76
|
+
| 5–15 symbols, 2–5 processes | MEDIUM |
|
|
77
|
+
| > 15 symbols OR many processes OR many heuristic edges | HIGH |
|
|
78
|
+
| Critical path (auth, payments, data integrity) | CRITICAL |
|
|
79
|
+
|
|
80
|
+
## Tools
|
|
81
|
+
|
|
82
|
+
### `mcp__opencodehub__impact` — symbol blast radius
|
|
83
|
+
|
|
84
|
+
```
|
|
85
|
+
mcp__opencodehub__impact({
|
|
86
|
+
name: "validateUser",
|
|
87
|
+
direction: "upstream",
|
|
88
|
+
depth: 3,
|
|
89
|
+
repo: "my-app"
|
|
90
|
+
})
|
|
91
|
+
|
|
92
|
+
→ target: {uid, kind, filePath}
|
|
93
|
+
→ byDepth: {d1: [...], d2: [...], d3: [...]}
|
|
94
|
+
→ affected_processes: [CheckoutFlow, LoginFlow]
|
|
95
|
+
→ confidenceBreakdown: {confirmed, heuristic, unknown}
|
|
96
|
+
→ risk: LOW | MEDIUM | HIGH | CRITICAL
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Disambiguation: if the name is ambiguous, `impact` returns a ranked candidate list; pass `uid` (preferred) or `{name, file_path, kind}` to pick one.
|
|
100
|
+
|
|
101
|
+
### `mcp__opencodehub__api_impact` — route blast radius
|
|
102
|
+
|
|
103
|
+
```
|
|
104
|
+
mcp__opencodehub__api_impact({ method: "POST", path: "/api/payments", repo })
|
|
105
|
+
|
|
106
|
+
→ consumers: FETCHES callers across this repo (and across repos when a group is defined)
|
|
107
|
+
→ middleware: applied handlers
|
|
108
|
+
→ mismatches: producer/consumer shape mismatches
|
|
109
|
+
→ affected_processes: flows that pass through this route
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
### `mcp__opencodehub__shape_check` — response-shape sanity
|
|
113
|
+
|
|
114
|
+
```
|
|
115
|
+
mcp__opencodehub__shape_check({ repo })
|
|
116
|
+
|
|
117
|
+
→ mismatches: [{route, producer_keys, consumer_access, consumer_file}]
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Run it when a PR changes a response payload. Any new entry in `mismatches` is a bug surface.
|
|
121
|
+
|
|
122
|
+
### `mcp__opencodehub__detect_changes` — map the current diff to flows
|
|
123
|
+
|
|
124
|
+
```
|
|
125
|
+
mcp__opencodehub__detect_changes({ scope: "staged", repo })
|
|
126
|
+
|
|
127
|
+
→ changed_symbols: [{uid, name, kind, filePath, change}]
|
|
128
|
+
→ affected_processes: [...]
|
|
129
|
+
→ risk_level: LOW | MEDIUM | HIGH | CRITICAL
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Scopes: `unstaged`, `staged`, `all`, `compare` (requires `base_ref`).
|
|
133
|
+
|
|
134
|
+
## Example: "What breaks if I change `validateUser`?"
|
|
135
|
+
|
|
136
|
+
```
|
|
137
|
+
1. mcp__opencodehub__impact({ name: "validateUser", direction: "upstream", depth: 3, repo: "my-app" })
|
|
138
|
+
→ byDepth.d1: loginHandler, apiMiddleware (WILL BREAK)
|
|
139
|
+
→ byDepth.d2: authRouter, sessionManager (LIKELY AFFECTED)
|
|
140
|
+
→ affected_processes: [LoginFlow, TokenRefresh]
|
|
141
|
+
→ confidenceBreakdown: {confirmed: 4, heuristic: 0, unknown: 0}
|
|
142
|
+
→ risk: MEDIUM
|
|
143
|
+
|
|
144
|
+
2. Every d=1 edge is LSP-confirmed — high trust. Two processes touch the target.
|
|
145
|
+
|
|
146
|
+
3. mcp__opencodehub__detect_changes({ scope: "unstaged", repo: "my-app" })
|
|
147
|
+
→ changed_symbols: [validateUser]
|
|
148
|
+
→ affected_processes: [LoginFlow, TokenRefresh]
|
|
149
|
+
|
|
150
|
+
4. Verdict: MEDIUM risk. LoginFlow and TokenRefresh need regression tests before merging.
|
|
151
|
+
```
|
|
@@ -0,0 +1,246 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: opencodehub-pr-review
|
|
3
|
+
description: "Use when the user wants to review a pull request, understand what a PR changes, assess risk of merging, or check missing test coverage. Examples: \"Review this PR\", \"What does PR #42 change?\", \"Is this PR safe to merge?\", \"Audit the dependencies in this PR\"."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# PR Review with OpenCodeHub
|
|
7
|
+
|
|
8
|
+
## When to Use
|
|
9
|
+
|
|
10
|
+
- "Review this PR."
|
|
11
|
+
- "What does PR #42 change?"
|
|
12
|
+
- "Is this safe to merge?"
|
|
13
|
+
- "What's the blast radius of this PR?"
|
|
14
|
+
- "Are there missing tests for this PR?"
|
|
15
|
+
- "Did this PR introduce a copyleft / unknown license?"
|
|
16
|
+
- Reviewing someone else's code changes before merge.
|
|
17
|
+
|
|
18
|
+
## The Golden Workflow
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
1. mcp__opencodehub__verdict({ base, head }) → 5-tier merge decision
|
|
22
|
+
2. mcp__opencodehub__list_findings_delta({ base }) → New / fixed / unchanged / updated findings
|
|
23
|
+
3. mcp__opencodehub__detect_changes({ scope: "compare", base_ref }) → Changed symbols + affected flows
|
|
24
|
+
4. For each non-trivial changed symbol:
|
|
25
|
+
mcp__opencodehub__impact({ name, direction: "upstream" }) → Blast radius + confidenceBreakdown
|
|
26
|
+
5. mcp__opencodehub__license_audit → Copyleft / unknown / proprietary tiers
|
|
27
|
+
6. mcp__opencodehub__scan (opt-in) → Fresh scanner run — spawns processes
|
|
28
|
+
7. Write the review using the output template below
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
> If the context envelope warns the index is stale, run `codehub analyze` before starting — stale graphs produce stale verdicts.
|
|
32
|
+
|
|
33
|
+
## Checklist
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
- [ ] Fetch the PR diff (gh pr diff <n> or git diff <base>...<head>)
|
|
37
|
+
- [ ] mcp__opencodehub__verdict — start here; it aggregates the review signal
|
|
38
|
+
- [ ] Capture the verdict tier, top drivers, and blockers
|
|
39
|
+
- [ ] mcp__opencodehub__list_findings_delta — new findings since the baseline
|
|
40
|
+
- [ ] mcp__opencodehub__detect_changes — map the diff to affected processes
|
|
41
|
+
- [ ] mcp__opencodehub__impact on each non-trivial changed symbol
|
|
42
|
+
- [ ] Inspect confidenceBreakdown per impact — prefer confirmed edges for breakage claims
|
|
43
|
+
- [ ] mcp__opencodehub__license_audit — flag copyleft or unknown license changes
|
|
44
|
+
- [ ] (optional) mcp__opencodehub__scan to re-run scanners if the baseline is stale
|
|
45
|
+
- [ ] Write the review in the output template below
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Tools
|
|
49
|
+
|
|
50
|
+
### `mcp__opencodehub__verdict` — the starting point
|
|
51
|
+
|
|
52
|
+
```
|
|
53
|
+
mcp__opencodehub__verdict({ base: "main", head: "HEAD", repo: "my-app" })
|
|
54
|
+
|
|
55
|
+
→ tier: "auto_merge" | "single_review" | "dual_review" | "expert_review" | "block"
|
|
56
|
+
→ drivers: [{ signal, weight, evidence }] // top reasons the tier was chosen
|
|
57
|
+
→ blockers: [...] // non-empty only for tier=block
|
|
58
|
+
→ next_action: "merge" | "request review from X" | "add tests for Y" | "fix finding Z"
|
|
59
|
+
→ exit_code: 0 | 1 | 2
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Always lead your review with the tier. If it is `block`, do not recommend merge. If it is `auto_merge`, the rest of the review is confirmation, not discovery.
|
|
63
|
+
|
|
64
|
+
### `mcp__opencodehub__list_findings_delta` — what changed since baseline
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
mcp__opencodehub__list_findings_delta({
|
|
68
|
+
repo: "my-app",
|
|
69
|
+
base: "main" // compare current scan output to the baseline frozen at base
|
|
70
|
+
})
|
|
71
|
+
|
|
72
|
+
→ new: [{rule, severity, file, line, message}] // introduced by this PR — the scariest bucket
|
|
73
|
+
→ fixed: [...] // removed by this PR — give credit
|
|
74
|
+
→ unchanged: [...] // still present, not touched
|
|
75
|
+
→ updated: [...] // same rule hit at a shifted location
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
The `new` bucket is the first thing to surface — it is the PR author's new debt.
|
|
79
|
+
|
|
80
|
+
### `mcp__opencodehub__detect_changes` — diff → flows
|
|
81
|
+
|
|
82
|
+
```
|
|
83
|
+
mcp__opencodehub__detect_changes({ scope: "compare", base_ref: "main", repo: "my-app" })
|
|
84
|
+
|
|
85
|
+
→ changed_symbols: [{uid, name, kind, filePath, change}]
|
|
86
|
+
→ affected_processes: [CheckoutFlow, RefundFlow]
|
|
87
|
+
→ risk_level: LOW | MEDIUM | HIGH | CRITICAL
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### `mcp__opencodehub__impact` — blast radius per changed symbol
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
mcp__opencodehub__impact({
|
|
94
|
+
name: "validatePayment",
|
|
95
|
+
direction: "upstream",
|
|
96
|
+
depth: 2,
|
|
97
|
+
repo: "my-app"
|
|
98
|
+
})
|
|
99
|
+
|
|
100
|
+
→ byDepth.d1: processCheckout, webhookHandler // WILL BREAK if signature changed
|
|
101
|
+
→ byDepth.d2: checkoutRouter // LIKELY AFFECTED
|
|
102
|
+
→ affected_processes: [CheckoutFlow]
|
|
103
|
+
→ confidenceBreakdown: {confirmed, heuristic, unknown}
|
|
104
|
+
→ risk: MEDIUM
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
If any d=1 caller is NOT in the PR diff, flag it as a potential breakage in your review.
|
|
108
|
+
|
|
109
|
+
### `mcp__opencodehub__license_audit` — dependency license tiers
|
|
110
|
+
|
|
111
|
+
```
|
|
112
|
+
mcp__opencodehub__license_audit({ repo: "my-app" })
|
|
113
|
+
|
|
114
|
+
→ by_tier: {
|
|
115
|
+
copyleft: [{ name, ecosystem, version, license, manifest }],
|
|
116
|
+
unknown: [...],
|
|
117
|
+
proprietary: [...],
|
|
118
|
+
permissive: [...]
|
|
119
|
+
}
|
|
120
|
+
→ warnings: [...] // e.g. "package `foo` has no license field in manifest"
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
If the PR diff touches `package.json`, `pyproject.toml`, `go.mod`, or `Cargo.toml`, run this and compare tiers against the pre-PR baseline. A new `copyleft` or `unknown` entry is a review finding.
|
|
124
|
+
|
|
125
|
+
### `mcp__opencodehub__scan` — re-run scanners
|
|
126
|
+
|
|
127
|
+
Only run this when the baseline is obviously stale. `scan` has `openWorldHint: true` and spawns child processes, so use it deliberately.
|
|
128
|
+
|
|
129
|
+
```
|
|
130
|
+
mcp__opencodehub__scan({ repo: "my-app" })
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### `mcp__opencodehub__risk_trends` — context on the area being changed
|
|
134
|
+
|
|
135
|
+
```
|
|
136
|
+
mcp__opencodehub__risk_trends({ repo: "my-app" })
|
|
137
|
+
|
|
138
|
+
→ communities: [{ name, risk_score, trend, projection_30d }]
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Useful when a PR lands inside a community whose risk is already trending up — call that out in the review.
|
|
142
|
+
|
|
143
|
+
### `mcp__opencodehub__owners` — who should review?
|
|
144
|
+
|
|
145
|
+
```
|
|
146
|
+
mcp__opencodehub__owners({ repo: "my-app", path: "src/payments" })
|
|
147
|
+
|
|
148
|
+
→ [{ owner, source: "codeowners" | "git-blame", files, recent_edits }]
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## Review Dimensions
|
|
152
|
+
|
|
153
|
+
| Dimension | OpenCodeHub surface |
|
|
154
|
+
| -------------------- | ------------------------------------------------------------------------- |
|
|
155
|
+
| **Correctness** | `context` shows callers — are they all compatible with the change? |
|
|
156
|
+
| **Blast radius** | `impact.byDepth` — anything at d=1 not in the diff is a potential miss |
|
|
157
|
+
| **Completeness** | `detect_changes.affected_processes` — are they all handled? |
|
|
158
|
+
| **Confidence** | `confidenceBreakdown.confirmed` vs `heuristic` — LSP-backed claims win |
|
|
159
|
+
| **Net new bugs** | `list_findings_delta.new` — introduced by this PR |
|
|
160
|
+
| **Tests** | `impact` filtered to `kind = 'Function'` inside test files |
|
|
161
|
+
| **License hygiene** | `license_audit` before/after diff |
|
|
162
|
+
| **Ownership** | `owners` — right reviewers requested? |
|
|
163
|
+
| **Trend** | `risk_trends` — is this area already hot? |
|
|
164
|
+
|
|
165
|
+
## Risk Tier Guide
|
|
166
|
+
|
|
167
|
+
| Signal | Risk |
|
|
168
|
+
| ------------------------------------------------------- | -------- |
|
|
169
|
+
| < 3 symbols touched, 0–1 processes, no new findings | LOW |
|
|
170
|
+
| 3–10 symbols, 2–5 processes, ≤ 1 new finding | MEDIUM |
|
|
171
|
+
| > 10 symbols OR many processes OR several new findings | HIGH |
|
|
172
|
+
| Touches auth, payments, data integrity, or new copyleft | CRITICAL |
|
|
173
|
+
| d=1 callers exist outside the PR diff | Flag it |
|
|
174
|
+
|
|
175
|
+
## Example: "Review PR #42"
|
|
176
|
+
|
|
177
|
+
```
|
|
178
|
+
1. gh pr diff 42 > /tmp/pr42.diff
|
|
179
|
+
→ 4 files changed: payments.ts, checkout.ts, types.ts, utils.ts
|
|
180
|
+
|
|
181
|
+
2. mcp__opencodehub__verdict({ base: "main", head: "HEAD", repo: "my-app" })
|
|
182
|
+
→ tier: "dual_review"
|
|
183
|
+
→ drivers: [
|
|
184
|
+
{signal: "high-impact symbol changed", weight: 0.4, evidence: "validatePayment"},
|
|
185
|
+
{signal: "new scanner finding", weight: 0.3, evidence: "security/no-eval"},
|
|
186
|
+
{signal: "missing test coverage on CheckoutFlow", weight: 0.3}
|
|
187
|
+
]
|
|
188
|
+
→ next_action: "request review from @payments-team"
|
|
189
|
+
|
|
190
|
+
3. mcp__opencodehub__list_findings_delta({ repo: "my-app", base: "main" })
|
|
191
|
+
→ new: [{rule: "security/no-eval", severity: "error", file: "src/utils/format.ts", line: 44}]
|
|
192
|
+
→ fixed: []
|
|
193
|
+
|
|
194
|
+
4. mcp__opencodehub__detect_changes({ scope: "compare", base_ref: "main", repo: "my-app" })
|
|
195
|
+
→ changed_symbols: [validatePayment, PaymentInput, formatAmount]
|
|
196
|
+
→ affected_processes: [CheckoutFlow, RefundFlow]
|
|
197
|
+
→ risk_level: MEDIUM
|
|
198
|
+
|
|
199
|
+
5. mcp__opencodehub__impact({ name: "validatePayment", direction: "upstream", repo: "my-app" })
|
|
200
|
+
→ byDepth.d1: processCheckout, webhookHandler
|
|
201
|
+
→ webhookHandler is NOT in the PR diff — flag as potential breakage.
|
|
202
|
+
→ confidenceBreakdown: {confirmed: 2, heuristic: 0, unknown: 0}
|
|
203
|
+
|
|
204
|
+
6. mcp__opencodehub__impact({ name: "PaymentInput", direction: "upstream", repo: "my-app" })
|
|
205
|
+
→ byDepth.d1: validatePayment (in PR), createPayment (NOT in PR)
|
|
206
|
+
→ createPayment uses the old PaymentInput shape — breaking change.
|
|
207
|
+
|
|
208
|
+
7. mcp__opencodehub__license_audit({ repo: "my-app" })
|
|
209
|
+
→ No tier changes vs. main — clean.
|
|
210
|
+
|
|
211
|
+
8. Compose the review (template below).
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
## Review Output Template
|
|
215
|
+
|
|
216
|
+
```markdown
|
|
217
|
+
## PR Review: <title>
|
|
218
|
+
|
|
219
|
+
**Tier: dual_review** **Risk: MEDIUM**
|
|
220
|
+
|
|
221
|
+
### Verdict drivers
|
|
222
|
+
- validatePayment blast radius crosses the PR boundary
|
|
223
|
+
- 1 new scanner finding: security/no-eval at src/utils/format.ts:44
|
|
224
|
+
- CheckoutFlow has no test coverage for the new branch
|
|
225
|
+
|
|
226
|
+
### Changes
|
|
227
|
+
- 3 symbols changed across 4 files
|
|
228
|
+
- 2 execution flows affected: CheckoutFlow, RefundFlow
|
|
229
|
+
|
|
230
|
+
### Findings
|
|
231
|
+
1. **[blocker]** `webhookHandler` (src/webhooks.ts:15) calls `validatePayment`
|
|
232
|
+
but is NOT updated in this PR. New signature will throw at runtime.
|
|
233
|
+
2. **[blocker]** `createPayment` (src/payments/create.ts:22) uses the old
|
|
234
|
+
`PaymentInput` shape. This change is breaking.
|
|
235
|
+
3. **[error]** New scanner finding: security/no-eval at src/utils/format.ts:44.
|
|
236
|
+
`eval(userInput)` is unsafe.
|
|
237
|
+
4. **[ok]** `formatAmount` added optional param — backwards compatible.
|
|
238
|
+
|
|
239
|
+
### Missing coverage
|
|
240
|
+
- CheckoutFlow has no integration test for the new branch.
|
|
241
|
+
- No webhook test exercises validatePayment.
|
|
242
|
+
|
|
243
|
+
### Recommendation
|
|
244
|
+
REQUEST CHANGES — resolve the three blockers and add a CheckoutFlow
|
|
245
|
+
integration test before re-review.
|
|
246
|
+
```
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: opencodehub-refactoring
|
|
3
|
+
description: "Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: \"Rename this function\", \"Extract this into a module\", \"Refactor this class\", \"Move this to a separate file\"."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Refactoring with OpenCodeHub
|
|
7
|
+
|
|
8
|
+
## When to Use
|
|
9
|
+
|
|
10
|
+
- "Rename this function safely."
|
|
11
|
+
- "Extract this into a module."
|
|
12
|
+
- "Split this service."
|
|
13
|
+
- "Move this to a new file."
|
|
14
|
+
- Any task involving renaming, extracting, splitting, or restructuring code.
|
|
15
|
+
|
|
16
|
+
## Workflow
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
1. mcp__opencodehub__impact({ name: target, direction: "upstream" }) → All dependents
|
|
20
|
+
2. mcp__opencodehub__context({ name: target }) → Incoming / outgoing / processes
|
|
21
|
+
3. mcp__opencodehub__rename({ ..., dry_run: true }) → Preview every edit
|
|
22
|
+
4. Review confidence tags on each edit (graph vs. text-search)
|
|
23
|
+
5. mcp__opencodehub__rename({ ..., dry_run: false }) → Apply
|
|
24
|
+
6. mcp__opencodehub__detect_changes → Verify the diff matches the plan
|
|
25
|
+
7. Run tests for the affected processes
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
> If the context envelope warns the index is stale, run `codehub analyze` first — a stale graph produces incomplete rename plans.
|
|
29
|
+
|
|
30
|
+
## Checklists
|
|
31
|
+
|
|
32
|
+
### Rename a symbol
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
- [ ] mcp__opencodehub__impact({ name, direction: "upstream" }) — enumerate all dependents
|
|
36
|
+
- [ ] mcp__opencodehub__rename({ name, new_name, dry_run: true })
|
|
37
|
+
(pass `file_path` and/or `kind` to disambiguate when the name is ambiguous)
|
|
38
|
+
- [ ] Review edits: graph edges (high confidence, LSP-backed where available)
|
|
39
|
+
vs. text_search edits (review line-by-line — config files, docs, tests)
|
|
40
|
+
- [ ] Cross-check the dry-run edit count against impact's d=1 count —
|
|
41
|
+
gaps mean a dynamic reference the rename missed
|
|
42
|
+
- [ ] mcp__opencodehub__rename({ ..., dry_run: false }) — apply
|
|
43
|
+
- [ ] mcp__opencodehub__detect_changes({ scope: "unstaged" }) — confirm scope
|
|
44
|
+
- [ ] Run tests for every affected process
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
### Extract a module
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
- [ ] mcp__opencodehub__context({ name: target }) — see every external ref
|
|
51
|
+
- [ ] mcp__opencodehub__impact({ name: target, direction: "upstream" }) — callers outside the new module
|
|
52
|
+
- [ ] Define the new public surface (exports only what external callers use)
|
|
53
|
+
- [ ] Move code; update imports
|
|
54
|
+
- [ ] mcp__opencodehub__detect_changes — verify scope
|
|
55
|
+
- [ ] Run tests for the affected processes
|
|
56
|
+
- [ ] Re-run codehub analyze so the next agent sees the new module boundary
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### Split a function or service
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
- [ ] mcp__opencodehub__context({ name: target }) — understand outgoing calls
|
|
63
|
+
- [ ] Group outgoing calls by responsibility (the seams for the split)
|
|
64
|
+
- [ ] mcp__opencodehub__impact({ name: target, direction: "upstream" }) — map callers to update
|
|
65
|
+
- [ ] Create the new functions / services
|
|
66
|
+
- [ ] Update callers
|
|
67
|
+
- [ ] mcp__opencodehub__detect_changes — verify scope
|
|
68
|
+
- [ ] Run tests
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Tools
|
|
72
|
+
|
|
73
|
+
### `mcp__opencodehub__rename` — multi-file coordinated rename
|
|
74
|
+
|
|
75
|
+
```
|
|
76
|
+
mcp__opencodehub__rename({
|
|
77
|
+
name: "validateUser",
|
|
78
|
+
new_name: "authenticateUser",
|
|
79
|
+
repo: "my-app",
|
|
80
|
+
dry_run: true // default: true
|
|
81
|
+
})
|
|
82
|
+
|
|
83
|
+
→ edits: [{
|
|
84
|
+
file_path,
|
|
85
|
+
line,
|
|
86
|
+
old_text,
|
|
87
|
+
new_text,
|
|
88
|
+
confidence, // 0.95+ = graph-backed (ideally LSP-confirmed); lower = text_search
|
|
89
|
+
source // "graph" | "text_search"
|
|
90
|
+
}]
|
|
91
|
+
→ summary: {total, by_source: {graph, text_search}}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
**Rule**: always review `text_search` edits line-by-line. They are the ones that hit dynamic references (config JSON, doc comments, test fixtures) where a rename may or may not be correct. Graph-backed edits on LSP-confirmed edges are safe to apply in bulk.
|
|
95
|
+
|
|
96
|
+
Disambiguation: when `name` matches more than one symbol, pass `file_path` and optionally `kind` to pick the target. A future wave will add `symbol_uid` for a direct UID-only path.
|
|
97
|
+
|
|
98
|
+
### `mcp__opencodehub__impact` — enumerate dependents before renaming
|
|
99
|
+
|
|
100
|
+
```
|
|
101
|
+
mcp__opencodehub__impact({
|
|
102
|
+
name: "validateUser",
|
|
103
|
+
direction: "upstream",
|
|
104
|
+
depth: 2,
|
|
105
|
+
repo: "my-app"
|
|
106
|
+
})
|
|
107
|
+
|
|
108
|
+
→ byDepth.d1: direct callers — every one needs updating
|
|
109
|
+
→ confidenceBreakdown: {confirmed, heuristic, unknown}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
If `unknown > 0`, the demote phase contradicted a heuristic edge. That edge may not be a real call — inspect before updating.
|
|
113
|
+
|
|
114
|
+
### `mcp__opencodehub__detect_changes` — verify the post-refactor diff
|
|
115
|
+
|
|
116
|
+
```
|
|
117
|
+
mcp__opencodehub__detect_changes({ scope: "unstaged", repo: "my-app" })
|
|
118
|
+
|
|
119
|
+
→ changed_symbols: [...]
|
|
120
|
+
→ affected_processes: [...]
|
|
121
|
+
→ risk_level: LOW | MEDIUM | HIGH | CRITICAL
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Always run this **after** applying the rename. Any symbol you did not expect to change is a miss.
|
|
125
|
+
|
|
126
|
+
### `mcp__opencodehub__sql` — custom reference query
|
|
127
|
+
|
|
128
|
+
All files referencing a symbol (useful when rename misses dynamic refs):
|
|
129
|
+
|
|
130
|
+
```sql
|
|
131
|
+
SELECT DISTINCT caller.file_path
|
|
132
|
+
FROM relations r
|
|
133
|
+
JOIN nodes caller ON caller.id = r.from_id
|
|
134
|
+
JOIN nodes target ON target.id = r.to_id
|
|
135
|
+
WHERE r.type IN ('CALLS', 'REFERENCES', 'IMPORTS')
|
|
136
|
+
AND target.name = 'validateUser'
|
|
137
|
+
ORDER BY caller.file_path;
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
## Risk Rules
|
|
141
|
+
|
|
142
|
+
| Risk factor | Mitigation |
|
|
143
|
+
| --------------------------------- | ----------------------------------------------------------------------- |
|
|
144
|
+
| Many callers (> 5) | Let `rename` do the mechanical work — do not hand-edit |
|
|
145
|
+
| Cross-module references | Run `detect_changes` after applying; watch for missed imports |
|
|
146
|
+
| String / dynamic references | Use `sql` with `type = 'REFERENCES'` + text_search edits |
|
|
147
|
+
| Public / exported API | Version and deprecate; mirror symbol names in a transition layer |
|
|
148
|
+
| Heuristic edges (confirmed = 0) | Cross-check by reading source; LSP did not weigh in |
|
|
149
|
+
|
|
150
|
+
## Example: Rename `validateUser` to `authenticateUser`
|
|
151
|
+
|
|
152
|
+
```
|
|
153
|
+
1. mcp__opencodehub__impact({ name: "validateUser", direction: "upstream", repo: "my-app" })
|
|
154
|
+
→ d=1: loginHandler, apiMiddleware, tests/auth.test.ts
|
|
155
|
+
→ affected_processes: [LoginFlow, TokenRefresh]
|
|
156
|
+
→ confidenceBreakdown: {confirmed: 3, heuristic: 0, unknown: 0}
|
|
157
|
+
|
|
158
|
+
2. mcp__opencodehub__rename({
|
|
159
|
+
name: "validateUser", new_name: "authenticateUser",
|
|
160
|
+
repo: "my-app", dry_run: true
|
|
161
|
+
})
|
|
162
|
+
→ 12 edits across 8 files
|
|
163
|
+
→ summary: {graph: 10, text_search: 2}
|
|
164
|
+
→ text_search edits: config/routes.json (line 14), docs/auth.md (line 33)
|
|
165
|
+
|
|
166
|
+
3. Review text_search edits: config/routes.json references validateUser by
|
|
167
|
+
string name — apply the rename manually, the JSON schema allows it.
|
|
168
|
+
docs/auth.md is prose, safe to rewrite.
|
|
169
|
+
|
|
170
|
+
4. mcp__opencodehub__rename({ ..., dry_run: false })
|
|
171
|
+
→ Applied 12 edits across 8 files.
|
|
172
|
+
|
|
173
|
+
5. mcp__opencodehub__detect_changes({ scope: "unstaged", repo: "my-app" })
|
|
174
|
+
→ changed_symbols: [authenticateUser, loginHandler, apiMiddleware, ...]
|
|
175
|
+
→ affected_processes: [LoginFlow, TokenRefresh]
|
|
176
|
+
→ risk_level: MEDIUM
|
|
177
|
+
|
|
178
|
+
6. Run LoginFlow + TokenRefresh integration tests. Re-run codehub analyze
|
|
179
|
+
so the graph picks up the new name.
|
|
180
|
+
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@opencodehub/cli",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.3",
|
|
4
4
|
"description": "OpenCodeHub — codehub CLI (analyze, setup, mcp, list, status, clean, query, context, impact, sql)",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
@@ -26,7 +26,9 @@
|
|
|
26
26
|
"dist/**/*.js.map",
|
|
27
27
|
"!dist/**/*.test.js.map",
|
|
28
28
|
"dist/**/*.d.ts.map",
|
|
29
|
-
"!dist/**/*.test.d.ts.map"
|
|
29
|
+
"!dist/**/*.test.d.ts.map",
|
|
30
|
+
"dist/plugin-assets/**",
|
|
31
|
+
"dist/commands/ci-templates/**"
|
|
30
32
|
],
|
|
31
33
|
"dependencies": {
|
|
32
34
|
"@iarna/toml": "2.2.5",
|
|
@@ -36,18 +38,18 @@
|
|
|
36
38
|
"listr2": "10.2.1",
|
|
37
39
|
"write-file-atomic": "8.0.0",
|
|
38
40
|
"yaml": "2.8.4",
|
|
39
|
-
"@opencodehub/analysis": "0.1.
|
|
40
|
-
"@opencodehub/
|
|
41
|
-
"@opencodehub/
|
|
42
|
-
"@opencodehub/
|
|
43
|
-
"@opencodehub/
|
|
44
|
-
"@opencodehub/
|
|
45
|
-
"@opencodehub/
|
|
46
|
-
"@opencodehub/
|
|
47
|
-
"@opencodehub/
|
|
48
|
-
"@opencodehub/
|
|
49
|
-
"@opencodehub/wiki": "0.1.
|
|
50
|
-
"@opencodehub/storage": "0.1.
|
|
41
|
+
"@opencodehub/analysis": "0.1.2",
|
|
42
|
+
"@opencodehub/core-types": "0.3.0",
|
|
43
|
+
"@opencodehub/embedder": "0.1.2",
|
|
44
|
+
"@opencodehub/policy": "0.1.1",
|
|
45
|
+
"@opencodehub/pack": "0.1.3",
|
|
46
|
+
"@opencodehub/sarif": "0.1.2",
|
|
47
|
+
"@opencodehub/mcp": "0.3.1",
|
|
48
|
+
"@opencodehub/scanners": "0.1.2",
|
|
49
|
+
"@opencodehub/search": "0.1.2",
|
|
50
|
+
"@opencodehub/ingestion": "0.3.2",
|
|
51
|
+
"@opencodehub/wiki": "0.1.1",
|
|
52
|
+
"@opencodehub/storage": "0.1.2"
|
|
51
53
|
},
|
|
52
54
|
"devDependencies": {
|
|
53
55
|
"@types/node": "25.6.2",
|