Update to the latest gRPC A3S proto spec

henryju · henryju · commit 70392836b40f · 2026-01-09T10:44:49.000+01:00
diff --git a/packages/grpc/src/proto/language_analyzer.proto b/packages/grpc/src/proto/language_analyzer.proto
@@ -9,26 +9,54 @@ package analyzer;
 // Language Analyzer Service
 service LanguageAnalyzerService {
   // Analyze a file
-  rpc AnalyzeFile(AnalyzeFileRequest) returns (AnalyzeFileResponse);
+  rpc Analyze(AnalyzeRequest) returns (AnalyzeResponse);
 }
 
 // Request to analyze a file
-message AnalyzeFileRequest {
-  map<string, string> context_ids = 1; // Map of context ID by kind
-  repeated SourceFile source_files = 2; // List of source files to analyze
-  repeated ActiveRule active_rules = 3; // List of active rules
+message AnalyzeRequest {
+  string analysis_id = 1; // A unique UUID identifier for each analysis
+  map<string, string> context_ids = 2; // Map of context ID by kind
+  repeated SourceFile source_files = 3; // List of source files to analyze
+  repeated ActiveRule active_rules = 4; // List of active rules
 }
 
-// Represents a source file
+// Represents a source file to be analyzed.
+//
+// relative_path: the relative path of the file
+// content: the content of the file
+// file_scope: the scope of the file (MAIN or TEST). This is optional.
+//             When provided, it takes precedence over any scope deduced from the context.
+//             When not provided, the scope should be deduced from the context if available.
+//             When neither is provided, the analyzer should perform best effort to determine the scope.
 message SourceFile {
-  string relative_path = 1;            // The repo-relative path and filename
-  string content = 2;                  // The full content of the file
+  string relative_path = 1;
+  string content = 2;
+  optional FileScope file_scope = 3;
+}
+
+// Enum for file scope
+enum FileScope {
+  MAIN = 0;
+  TEST = 1;
 }
 
 // Response containing analysis results
-message AnalyzeFileResponse {
+message AnalyzeResponse {
   repeated Issue issues = 1;
-  repeated string analysis_problems = 2;
+  repeated AnalysisProblem analysis_problems = 2;
+}
+
+// Represents a problem encountered during analysis
+message AnalysisProblem {
+  AnalysisProblemType type = 1;    // Type of the problem
+  string message = 2;              // Description of the problem
+  string file_path = 3;            // Optional path to the file where the problem occurred
+}
+
+// Enum for analysis problem types
+enum AnalysisProblemType {
+  ANALYSIS_PROBLEM_TYPE_UNDEFINED = 0;
+  ANALYSIS_PROBLEM_TYPE_PARSING = 1;
 }
 
 // Represents an active rule with configuration
@@ -61,9 +89,18 @@ message TextRange {
   int32 end_offset = 4;            // 0-indexed character offset
 }
 
+// Flow type enumeration
+enum FlowType {
+  FLOW_TYPE_UNDEFINED = 0;
+  FLOW_TYPE_DATA = 1;
+  FLOW_TYPE_EXECUTION = 2;
+}
+
 // Represents a flow (sequence of locations)
 message Flow {
-  repeated FlowLocation locations = 1;
+  FlowType type = 1;
+  string description = 2;
+  repeated FlowLocation locations = 3;
 }
 
 // Represents a location in a flow
diff --git a/packages/grpc/src/server.ts b/packages/grpc/src/server.ts
@@ -29,16 +29,16 @@ const HEALTH_SERVICE_NAME = 'grpc.health.v1.Health';
  */
 function createAnalyzerServiceDefinition(): grpc.ServiceDefinition {
   return {
-    AnalyzeFile: {
-      path: `/${ANALYZER_SERVICE_NAME}/AnalyzeFile`,
+    Analyze: {
+      path: `/${ANALYZER_SERVICE_NAME}/Analyze`,
       requestStream: false,
       responseStream: false,
-      requestSerialize: (value: analyzer.IAnalyzeFileRequest) =>
-        Buffer.from(analyzer.AnalyzeFileRequest.encode(value).finish()),
-      requestDeserialize: (buffer: Buffer) => analyzer.AnalyzeFileRequest.decode(buffer),
-      responseSerialize: (value: analyzer.IAnalyzeFileResponse) =>
-        Buffer.from(analyzer.AnalyzeFileResponse.encode(value).finish()),
-      responseDeserialize: (buffer: Buffer) => analyzer.AnalyzeFileResponse.decode(buffer),
+      requestSerialize: (value: analyzer.IAnalyzeRequest) =>
+        Buffer.from(analyzer.AnalyzeRequest.encode(value).finish()),
+      requestDeserialize: (buffer: Buffer) => analyzer.AnalyzeRequest.decode(buffer),
+      responseSerialize: (value: analyzer.IAnalyzeResponse) =>
+        Buffer.from(analyzer.AnalyzeResponse.encode(value).finish()),
+      responseDeserialize: (buffer: Buffer) => analyzer.AnalyzeResponse.decode(buffer),
     },
   };
 }
@@ -72,9 +72,9 @@ export function createGrpcServer(): grpc.Server {
 
   const analyzerServiceDefinition = createAnalyzerServiceDefinition();
   const analyzerImplementation: grpc.UntypedServiceImplementation = {
-    AnalyzeFile: (
-      call: grpc.ServerUnaryCall<analyzer.IAnalyzeFileRequest, analyzer.IAnalyzeFileResponse>,
-      callback: grpc.sendUnaryData<analyzer.IAnalyzeFileResponse>,
+    Analyze: (
+      call: grpc.ServerUnaryCall<analyzer.IAnalyzeRequest, analyzer.IAnalyzeResponse>,
+      callback: grpc.sendUnaryData<analyzer.IAnalyzeResponse>,
     ) => {
       analyzeFileHandler(call, callback);
     },
diff --git a/packages/grpc/src/service.ts b/packages/grpc/src/service.ts
@@ -24,16 +24,18 @@ import { analyzeProject } from '../../jsts/src/analysis/projectAnalysis/analyzeP
 import { info, error as logError } from '../../shared/src/helpers/logging.js';
 
 /**
- * gRPC handler for the AnalyzeFile RPC
+ * gRPC handler for the Analyze RPC
  */
 export async function analyzeFileHandler(
-  call: grpc.ServerUnaryCall<analyzer.IAnalyzeFileRequest, analyzer.IAnalyzeFileResponse>,
-  callback: grpc.sendUnaryData<analyzer.IAnalyzeFileResponse>,
+  call: grpc.ServerUnaryCall<analyzer.IAnalyzeRequest, analyzer.IAnalyzeResponse>,
+  callback: grpc.sendUnaryData<analyzer.IAnalyzeResponse>,
 ): Promise<void> {
   const request = call.request;
 
   try {
-    info(`Received AnalyzeFile request with ${request.sourceFiles?.length ?? 0} files`);
+    info(
+      `Received Analyze request (${request.analysisId ?? 'no id'}) with ${request.sourceFiles?.length ?? 0} files`,
+    );
 
     const projectInput = transformRequestToProjectInput(request);
 
@@ -45,7 +47,7 @@ export async function analyzeFileHandler(
     callback(null, response);
   } catch (err) {
     const errorMessage = err instanceof Error ? err.message : String(err);
-    logError(`AnalyzeFile error: ${errorMessage}`);
+    logError(`Analyze error: ${errorMessage}`);
     callback({
       code: grpc.status.INTERNAL,
       message: errorMessage,
diff --git a/packages/grpc/src/transformers/request.ts b/packages/grpc/src/transformers/request.ts
@@ -14,7 +14,7 @@
  * You should have received a copy of the Sonar Source-Available License
  * along with this program; if not, see https://sonarsource.com/license/ssal/
  */
-import type { analyzer } from '../proto/language_analyzer.js';
+import { analyzer } from '../proto/language_analyzer.js';
 import type {
   ProjectAnalysisInput,
   JsTsFiles,
@@ -75,12 +75,13 @@ function parseParamValue(value: string, defaultValue: unknown) {
 /**
  * Transform source files from gRPC protobuf format to the internal JsTsFiles format.
  *
- * The gRPC request contains an array of `ISourceFile` objects with `relativePath` and `content`.
- * This function converts them into a dictionary keyed by relative path, which is the format
- * expected by the `analyzeProject` function.
+ * The gRPC request contains an array of `ISourceFile` objects with `relativePath`, `content`,
+ * and optionally `fileScope`. This function converts them into a dictionary keyed by relative
+ * path, which is the format expected by the `analyzeProject` function.
  *
- * Note: File type is defaulted to 'MAIN'. In the future, this could be extended to accept
- * file type metadata from the gRPC request to properly distinguish test files.
+ * File scope handling:
+ * - If fileScope is explicitly set in the request, use it (MAIN or TEST)
+ * - Otherwise, default to 'MAIN' (context-based inference could be added in the future)
  *
  * @param sourceFiles - Array of source files from the gRPC request
  * @returns Dictionary of files keyed by relative path
@@ -90,10 +91,18 @@ function transformSourceFiles(sourceFiles: analyzer.ISourceFile[]): JsTsFiles {
 
   for (const sourceFile of sourceFiles) {
     const relativePath = sourceFile.relativePath ?? '';
+    let fileType: FileType = 'MAIN';
+
+    if (sourceFile.fileScope !== null && sourceFile.fileScope !== undefined) {
+      fileType = sourceFile.fileScope === analyzer.FileScope.TEST ? 'TEST' : 'MAIN';
+    } else {
+      // TODO: Infer file scope from context when not explicitly provided by the caller
+    }
+
     files[relativePath] = {
       filePath: relativePath,
       fileContent: sourceFile.content ?? '',
-      fileType: 'MAIN', // Default to MAIN, we will need metadata from context to know for sure
+      fileType,
     };
   }
 
@@ -365,7 +374,7 @@ function transformActiveRules(activeRules: analyzer.IActiveRule[]): RuleConfig[]
 }
 
 /**
- * Transform a gRPC AnalyzeFileRequest into the ProjectAnalysisInput format.
+ * Transform a gRPC AnalyzeRequest into the ProjectAnalysisInput format.
  *
  * This is the main entry point for request transformation in the gRPC workflow.
  * It converts the protobuf-based request format into the internal format expected
@@ -378,18 +387,18 @@ function transformActiveRules(activeRules: analyzer.IActiveRule[]): RuleConfig[]
  *
  * **Transformation flow:**
  * ```
- * IAnalyzeFileRequest
+ * IAnalyzeRequest
  *   ├── sourceFiles[] ──→ transformSourceFiles() ──→ JsTsFiles (keyed by path)
  *   └── activeRules[] ──→ transformActiveRules() ──→ RuleConfig[] (one per rule+language)
  * ```
  *
- * @param request - The gRPC AnalyzeFileRequest containing source files and active rules
+ * @param request - The gRPC AnalyzeRequest containing source files and active rules
  * @returns ProjectAnalysisInput ready to pass to analyzeProject()
  *
  * @see docs/DEV.md "External workflow (gRPC - without SonarQube)" section
  */
 export function transformRequestToProjectInput(
-  request: analyzer.IAnalyzeFileRequest,
+  request: analyzer.IAnalyzeRequest,
 ): ProjectAnalysisInput {
   // Handle empty/undefined arrays from proto3
   const sourceFiles = request.sourceFiles || [];
diff --git a/packages/grpc/src/transformers/response.ts b/packages/grpc/src/transformers/response.ts
@@ -14,7 +14,7 @@
  * You should have received a copy of the Sonar Source-Available License
  * along with this program; if not, see https://sonarsource.com/license/ssal/
  */
-import type { analyzer } from '../proto/language_analyzer.js';
+import { analyzer } from '../proto/language_analyzer.js';
 import type { ProjectAnalysisOutput } from '../../../jsts/src/analysis/projectAnalysis/projectAnalysis.js';
 import type { Issue } from '../../../jsts/src/linter/issues/issue.js';
 
@@ -41,7 +41,7 @@ const PARSING_ERROR_RULE_KEY = 'S2260';
  *
  * **Secondary Locations:**
  * Secondary locations provide additional context for issues (e.g., "this variable was declared here").
- * They are grouped into a single flow in the gRPC format.
+ * They are grouped into a single flow in the gRPC format with type FLOW_TYPE_DATA.
  *
  * @param issue - Internal Issue object from the linter
  * @returns gRPC IIssue object ready for protobuf serialization
@@ -57,7 +57,6 @@ function transformIssue(issue: Issue): analyzer.IIssue {
   // Transform secondary locations into flows
   const flows: analyzer.IFlow[] = [];
   if (issue.secondaryLocations && issue.secondaryLocations.length > 0) {
-    // Group secondary locations into a single flow
     const locations: analyzer.IFlowLocation[] = issue.secondaryLocations.map(loc => ({
       textRange: {
         startLine: loc.line,
@@ -69,7 +68,11 @@ function transformIssue(issue: Issue): analyzer.IIssue {
       file: issue.filePath,
     }));
 
-    flows.push({ locations });
+    flows.push({
+      type: analyzer.FlowType.FLOW_TYPE_DATA,
+      description: '',
+      locations,
+    });
   }
 
   return {
@@ -83,7 +86,7 @@ function transformIssue(issue: Issue): analyzer.IIssue {
 }
 
 /**
- * Transform the ProjectAnalysisOutput into a gRPC AnalyzeFileResponse.
+ * Transform the ProjectAnalysisOutput into a gRPC AnalyzeResponse.
  *
  * This is the main entry point for response transformation in the gRPC workflow.
  * It processes the analysis results for all files and converts them into the
@@ -94,41 +97,58 @@ function transformIssue(issue: Issue): analyzer.IIssue {
  * result can be one of three types:
  *
  * 1. **Error** (`'error' in result`): Analysis failed for this file
- *    - Added to `analysisProblems` array with file path context
+ *    - Added to `analysisProblems` array with UNDEFINED type
  *
  * 2. **Parsing Error** (`'parsingError' in result`): File could not be parsed
- *    - Converted to an issue with rule S2260 (parsing error rule)
- *    - Includes the error message and line number
+ *    - Added to `analysisProblems` array with PARSING type
+ *    - Also converted to an issue with rule S2260
  *
  * 3. **Success** (`'issues' in result`): Analysis completed successfully
  *    - All issues are transformed and added to the response
  *
  * **Response Structure:**
  * ```
- * IAnalyzeFileResponse
+ * IAnalyzeResponse
  *   ├── issues[] ──────────── All issues from successful analyses + parsing errors
- *   └── analysisProblems[] ── Warnings from meta + error messages for failed files
+ *   └── analysisProblems[] ── Structured problems with type, message, and file path
  * ```
  *
  * @param output - The ProjectAnalysisOutput from analyzeProject()
- * @returns gRPC IAnalyzeFileResponse ready for protobuf serialization
+ * @returns gRPC IAnalyzeResponse ready for protobuf serialization
  */
 export function transformProjectOutputToResponse(
   output: ProjectAnalysisOutput,
-): analyzer.IAnalyzeFileResponse {
+): analyzer.IAnalyzeResponse {
   const issues: analyzer.IIssue[] = [];
-  const analysisProblems: string[] = [...output.meta.warnings];
+  const analysisProblems: analyzer.IAnalysisProblem[] = [];
+
+  for (const warning of output.meta.warnings) {
+    analysisProblems.push({
+      type: analyzer.AnalysisProblemType.ANALYSIS_PROBLEM_TYPE_UNDEFINED,
+      message: warning,
+      filePath: '',
+    });
+  }
 
-  // Process each file result
   for (const [filePath, fileResult] of Object.entries(output.files)) {
     if ('error' in fileResult) {
-      analysisProblems.push(`Error analyzing ${filePath}: ${fileResult.error}`);
+      analysisProblems.push({
+        type: analyzer.AnalysisProblemType.ANALYSIS_PROBLEM_TYPE_UNDEFINED,
+        message: fileResult.error,
+        filePath,
+      });
       continue;
     }
 
     if ('parsingError' in fileResult) {
-      // Report parsing errors as issues with rule S2260
       const { message, line } = fileResult.parsingError;
+
+      analysisProblems.push({
+        type: analyzer.AnalysisProblemType.ANALYSIS_PROBLEM_TYPE_PARSING,
+        message,
+        filePath,
+      });
+
       issues.push(
         transformIssue({
           ruleId: PARSING_ERROR_RULE_KEY,
@@ -144,7 +164,6 @@ export function transformProjectOutputToResponse(
       continue;
     }
 
-    // Extract issues from successful analysis
     if ('issues' in fileResult) {
       for (const issue of fileResult.issues) {
         issues.push(transformIssue(issue));
diff --git a/packages/grpc/tests/server.test.ts b/packages/grpc/tests/server.test.ts
diff --git a/packages/grpc/tests/transformers.test.ts b/packages/grpc/tests/transformers.test.ts
