Skip to main content

Scenario 18: Code-optimization analysis

Analyze an individual file, inspect suggestions and exit codes, then verify the proposed change with tests and measurements before applying it.

User Guides

Scenario 18 helps developers identify code to inspect and returns suggestions by category. Choose a file and analysis category, inspect the suggestions, and submit an accepted suggestion to a separate implementation task. The analysis routes preserve source files.

Choose a supported analysis route

Local scanning requires a CodeGraph source checkout, the project Python environment, and an enabled local CLI. Follow the prerequisites in the CLI guide. Save this complete file as optimization_example.py in the repository root:

def total(items):
    result = 0
    for index in range(len(items)):
        result += items[index]
    return result

Run these commands in PowerShell:

python -m src.cli optimize analyze optimization_example.py --category performance --output suggestions.json
python -m src.cli optimize patterns --category performance
Get-Content suggestions.json -Raw | ConvertFrom-Json | Select-Object pattern_id, category, severity, start_line

Expected result: suggestions.json contains a PERF-002 suggestion with category performance, severity suggestion, and start line 3. patterns lists the category’s rules. Neither command changes the source file.

This is a regular-expression match, not proof of a performance problem. In this example, len(items) is evaluated before the loop starts; the rule’s repeated-call label does not establish repeated calls. Inspect the proposal against source and measure its effect on your workload.

analyze accepts a file or directory. Repeat --category to select more than one of performance, security, readability, and best_practice; omitting it checks all categories. --severity selects the minimum level: critical, warning, suggestion, or info. --limit caps displayed and saved suggestions; its default is 50. --output names the JSON file. With no suggestions, the command prints No optimization suggestions found., returns 0, and does not write a file. Choose a new report filename for each run and match it to the current command output.

Run the typed scenario

from src.digital_employees.runtime.scenarios import (
    RoleBoundScenarioInvocationRequest,
    invoke_role_bound_scenario_request,
)

request = RoleBoundScenarioInvocationRequest(
    query="Analyze optimization opportunities in optimization_example.py.",
    employee_id="codegraph_developer",
    scenario_id="scenario_18",
    event_type="implementation_start",
    context={
        "project_key": "codegraph",
        "namespace": "default",
        "task_id": "<task-id>",
        "source_refs": ["<revision-ref>", "<measurement-ref>"],
        "file_paths": ["optimization_example.py"],
    },
)
result = invoke_role_bound_scenario_request(request)
if result.get("error"):
    raise RuntimeError(result["error"])
if not result.get("scenario_id") or not result.get("answer"):
    raise RuntimeError("Scenario returned no scenario identity or answer")
print(result["answer"])
print(result.get("optimization_suggestions", []))

Replace the task scope, revision reference, and measurement reference with your values. See the Programmatic Guide for execution conditions: the workflow needs a configured runtime and available project context. When suggestions are found, the result includes optimization_suggestions. Match metadata.analyzed_paths to the intended files and metadata.suggestion_count to the number of suggestions. Read an empty list alongside the answer, paths, and analysis messages. Retain the role-bound evidence and submit accepted suggestions to a separate implementation task.

MCP and composite analysis

The codegraph_runtime_composition_workflow_run tool uses the project selected in the active MCP connection. Pass the analysis query, orchestrator, namespace, and task_id:

{
  "query": "Analyze optimization opportunities in file optimization_example.py",
  "orchestrator": "s18",
  "language": "en",
  "namespace": "<namespace>",
  "task_id": "<task-id>"
}

The tool routes s18 to role-bound scenario_18. The response contains answer, evidence, and metadata; review suggestions in the answer and compare metadata.analyzed_paths and metadata.suggestion_count with the request.

The CLI python -m src.cli composition run "<query>" -o s18 runs a broader composite analysis and stores its session only in the current process. Save the analysis result and use it to prepare a separate implementation task.

From analysis to implementation

Use analyze and patterns to review suggestions. Implement an accepted suggestion in a separate change. Run focused tests, compare measurements with the baseline, and inspect the diff. The registered list-suggestions, approve, reject, apply, and undo handlers print not yet implemented and return exit code 1.

composition apply does not apply changes. Its session exists only in the current process; a separate command invocation normally returns Session not found and 1. When a session exists, the handler prints Edit application not implemented in CLI demo, leaves source files unchanged, and returns 0. Verify application through the source diff and test results in the implementation task. The MCP composition analysis tool returns suggestions for that step.

Read and verify suggestions

Confirm each suggestion against the bound revision, a measurable objective, compatibility constraints, and focused tests. Performance measurements, security checks, and maintainability review establish the resulting benefit.

Failure and recovery

  • Path not found: the command prints Path not found: and returns 1. Correct the file or directory path.
  • No suggestions: check the selected category, available rules, and analysis path.
  • Command reports not yet implemented: return to the analysis report and submit the selected suggestion to an implementation task.
  • Composite session missing: rerun analysis, save the result, and submit suggestions to an implementation task.
Report a documentation issue