Use this workflow when you need to change code structure while preserving product behavior. CodeGraph shows the impact zone and helps you compare evidence before and after the edit. Use the verification results to record your decision to keep, revise, or roll back the change.
Outcome
At the end you should have:
- a named symbol and a recorded base revision;
- a pre-change impact report and read-only audit;
- a small source change made in your normal editor;
- project tests and lint results;
- a refreshed CPG plus post-change review evidence;
- a clear decision to keep, revise, or roll back the change.
Check exit status together with the report. It does not establish unchanged behavior; tests, linting, and review are required.
Prerequisites
Prepare the local Python environment using the CLI guide. Run commands from the CodeGraph repository root in PowerShell. Impact analysis requires a reachable GoCPG gRPC service; a CPG file alone is insufficient. Replace the illustrative values with the selected project scope and an existing method name. Prepare the CPG for the baseline revision using Prepare the project so you can compare impact before and after the edit.
- The repository is already imported into CodeGraph.
- The working tree contains only changes you intend to evaluate.
- You know the project test and lint commands.
- You can identify the DuckDB path shown by project information.
The examples below use PowerShell variables so that paths with spaces are handled safely:
$ProjectName = "my-project"
$RepoPath = "D:\src\my-project"
$CpgDb = "D:\codegraph-data\my-project.duckdb"
$BaseRef = "origin/main"
$Symbol = "qualified_symbol_name"
python -m src.cli projects info $ProjectName
Confirm that the reported source and DuckDB paths match the repository you are about to change. Stop if they do not.
1. Record the baseline
Capture the Git revision and current changes using your normal version-control tooling. Then run a deterministic, read-only audit:
python -m src.cli audit --db $CpgDb --source-path $RepoPath --profile ci_fast --format json --skip-llm-conclusion --skip-persistence
The --skip-persistence flag prevents this diagnostic run from updating audit projections. Save the output in your task evidence system if the refactoring is governed; the command does not write a report unless you pass an output option.
2. Bound the impact zone
Analyze the symbol before editing it:
python -m src.cli impact $Symbol --db $CpgDb --max-depth 5 --format json
Read each report field by its relationship direction:
| Field | What it contains | How to use it |
|---|---|---|
direct_callers |
Functions that call the selected method directly | Check whether their calls remain compatible with the change |
transitive_callers |
Callers at subsequent graph levels, excluding direct callers | Select regression scenarios and entry points |
affected_methods |
Functions called by the selected method, directly or through other functions | Inspect dependencies of the code being changed |
impact_score |
A normalized connectivity score from 0 to 1 | Compare the original and refreshed graphs using the same traversal depth and import settings |
impact_score counts unique callers and callees. It divides that count by 10% of the project’s total method count and caps the result at one. For a method with more than 100 direct callers, the calculation uses direct relationships instead of the full transitive traversal. Save the function lists and --max-depth with the score so that the comparison can be interpreted.
The traversal has both a depth limit and a result-size limit. By default, each direction returns up to 1,000 names for a direct query and 3,000 names for a transitive query, sorted by name. The score uses the relationships returned by these queries. Keep the traversal limits unchanged when comparing reports; increasing --max-depth changes the depth, not the number of results allowed.
If a list is empty, check the exact symbol name, project database, language import, and CPG freshness. Correct the context, repeat the command, and compare the returned relationships with the source.
Stop and split the work if the result crosses an ownership boundary, public API, persistence schema, authorization path, or release-critical entry point that is outside the approved task.
3. Make one bounded change
Edit the code in your normal editor. Keep behavior-preserving changes separate from feature work. Do not combine a rename, dependency upgrade, API change, and algorithm change in one refactoring slice.
Run the project’s focused tests and lint immediately. If either fails, restore the known-good version through your normal version-control workflow or correct the smallest failing slice before continuing.
4. Refresh the graph
The impact report is based on the imported CPG. Refresh it after the source change. The command below writes the database: coordinate with other process owners and stop conflicting operations before running it:
python -m src.cli cpg --path $RepoPath --output $CpgDb
Use the exact database reported for this project. If your installation manages imports through another approved pipeline, run that pipeline instead and verify the resulting project information before reusing the reports.
5. Review the changed slice
Run the unified review against the recorded base:
python -m src.cli review --db $CpgDb --base-ref $BaseRef --format markdown
Then repeat the impact analysis:
python -m src.cli impact $Symbol --db $CpgDb --max-depth 5 --format json
The second result should explain the intended structural change without introducing unexpected callers, security findings, or unrelated files. Re-run the read-only audit when the refactoring can affect project-wide quality metrics.
Decision table
| Evidence | Decision |
|---|---|
| Focused tests and lint pass; impact remains within the approved scope; review has no unresolved high-risk finding | Keep the slice and attach the evidence |
| Symbol is unresolved or the CPG is stale | Refresh or correct project context, then rerun |
| New callers, public surfaces, or security-sensitive paths appear | Stop and request a broader review |
| Behavior changes or acceptance criteria need revision | Reclassify the work as a product change |
| Tests, lint, or review fail | Revise the smallest slice or roll back through version control |
Evidence checklist
Record the project name, source revision, base ref, CPG identity, exact commands, exit codes, relevant report fields, test results, and the final human decision.
Troubleshooting
impact analysis requires explicit --db: pass the DuckDB path from projects info.- No callers for a known symbol: verify the qualified name and refresh the CPG.
- Review shows unrelated files: use the correct base ref and clean the task scope.
- Audit updates operational state: rerun with
--skip-persistence. - Results differ between runs: verify source revision, database path, import freshness, and configuration before comparing them.
See also Project import, Code review, and Scenario 09: Code review.