yidaima/RuoYi-Vue/docs/superpowers/specs/2026-07-07-code-analysis-core-selection-design.md

Code Analysis Core Source Selection Design

Background

The current code-analysis flow collects preview source from backend, frontend, admin_frontend, and sql, reads every allowed source-like file, and then truncates the assembled prompt context at 120KB. This works for small projects, but it can send too much low-value code to the AI and leave less room for the files that explain the real architecture and business flow.

The requested change is to send fewer files while keeping the most useful Java, Vue, SQL, and mapper/config context. The AI should receive a curated source snapshot, not a broad dump of every allowed file.

Goal

Make ProjectCodeAnalysisService intelligently select a compact set of core files for AI code interpretation. The default expanded source budget is 60KB, with clear metadata and warnings for files that were skipped, summarized, or truncated.

Non-Goals

• Do not add a second AI call to ask the model which files to choose.
• Do not require the user to manually pick files.
• Do not scan arbitrary server directories or uploaded ZIP files.
• Do not remove existing ownership checks or preview-read safeguards.
• Do not change the report page layout in this feature.

Selection Strategy

The backend keeps using the existing preview source tree as input:

• frontProjectPreviewService.getStructure(userId, projectId, "backend")
• frontProjectPreviewService.getStructure(userId, projectId, "frontend")
• frontProjectPreviewService.getStructure(userId, projectId, "admin_frontend")
• frontProjectPreviewService.getStructure(userId, projectId, "sql")

Instead of sending every allowed file until the prompt is full, the service will score each candidate file and assemble the prompt from highest-value files first.

High-priority files:

• Java controllers, especially paths or class names containing Controller
• Java services and service implementations
• Java mappers and mapper XML files
• Java entity/domain/model/DTO classes
• SQL files containing table definitions
• Vue route files, API wrappers, and core page components
• Project dependency/config files such as pom.xml, package.json, application.yml, and router files

Low-priority or skipped files:

• Build artifacts and dependency folders: target, dist, node_modules, .git, .idea
• Static assets, generated bundles, minified files, maps, images, fonts, archives, binaries
• Tests, screenshots, audit artifacts, demo-only files, mockups, and style-only files unless no better frontend files exist
• Very large files after their useful header and structural content have been captured

Budget Rules

The default expanded prompt source budget is 60KB. This is the total size of actual source content sent to the AI, not counting a small file manifest.

Recommended limits:

• Total expanded source budget: 60 * 1024 characters
• Per-file expanded budget for Java/Vue/XML/SQL/config: about 20 * 1024 characters
• Keep a compact manifest of selected and skipped files outside the expanded source body
• If the budget is exhausted, include remaining important file names in metadata, but do not expand their contents

The AI prompt should explicitly say that the source snapshot is curated and compact. It must not infer details from files that were not expanded.

Data Shape

Reuse CodeAnalysisSourceSummary and its existing file/skipped-file lists where possible.

Expected summary behavior:

• includedFiles contains only selected core files with content or compact extracted content
• skippedFiles includes non-core files and budget-excluded files with a reason
• warnings describes budget limits and any important omitted areas
• promptContext contains the curated file manifest and expanded core source blocks
• analyzedFileCount reflects selected files, while fileCount still reflects all scanned candidate files

Example prompt context shape:

Selected core source files:
- backend / src/main/java/.../UserController.java (controller, expanded)
- backend / src/main/java/.../UserServiceImpl.java (service, expanded)
- backend / src/main/resources/mapper/.../UserMapper.xml (mapper, expanded)
- sql / user.sql (table schema, expanded)
- frontend / src/views/user/index.vue (vue page, expanded)

Skipped or summarized files:
- frontend / src/styles/index.scss (style-only)
- frontend / src/utils/request.js (lower priority after budget)

## backend / src/main/java/.../UserController.java
...

Scoring Details

The score should be deterministic and testable. A simple weighted rule set is enough for this feature.

Suggested scoring:

• SQL schema files: very high
• *Controller.java: very high
• *Service.java and *ServiceImpl.java: high
• *Mapper.java and *Mapper.xml: high
• domain, entity, model, dto: medium-high
• Vue views/pages and router/API files: medium-high
• application.yml, pom.xml, package.json: medium
• Utility, style, test, demo, and docs files: low or skipped

Tie-breakers:

• Prefer files with shorter, clearer business paths over generic utility paths
• Keep a balanced mix of backend, frontend, and SQL rather than letting one layer consume all 60KB
• Preserve current stable ordering where scores are equal to avoid noisy test changes

Prompt Requirements

Update the code-analysis prompt wording to make the source selection explicit:

• "The following source snapshot is a curated subset of core files."
• "Use only the expanded source and listed metadata as evidence."
• "If a detail is not present in the selected source, say it cannot be confirmed."
• "When explaining architecture, cite real class, method, component, table, or field names from the selected files."

Testing Plan

Backend tests should cover:

• Core files are selected before low-value files when budget is limited
• Controller, Service, Mapper/XML, Vue page/API/router, and SQL files appear in the prompt when present
• Style-only, test, demo, dependency, and build artifact files are skipped or deprioritized
• Total expanded source context stays near the 60KB budget
• A large high-priority file is truncated per-file instead of consuming the whole prompt
• Budget-excluded but relevant files are recorded in skipped files or warnings

Acceptance Criteria

• Code analysis sends a compact curated source snapshot by default.
• The expanded source content sent to AI is about 60KB, not the previous 120KB broad dump.
• Java, Vue, SQL, and mapper/config files receive priority based on their architectural value.
• The prompt includes enough metadata for the AI to know which important files were selected or omitted.
• Existing code-analysis generation, streaming, history, and continuation flows keep working.