refactor: update headless payload to be config-based instead of file-based (#182)

- based on #125 (cc @camc314)

I took @camc314's branch and updated based on the latest code. I'm not familiar with Go, so it's very possible I've made some mistakes here, please review carefully 🙏

The goal of this PR is to ultimately enable doing custom configurations for rules without needing to specify redudant rule information. The new config format emphasizes configs over files, where each config defines a set of files it should apply to, and the rules that should be run.

Author: camchenry

cmd/tsgolint/headless.go

@@ -25,14 +25,6 @@ import (
 	"github.com/typescript-eslint/tsgolint/internal/utils"
 )
 
-type headlessConfigForFile struct {
-	FilePath string   `json:"file_path"`
-	Rules    []string `json:"rules"`
-}
-type headlessConfig struct {
-	Files []headlessConfigForFile `json:"files"`
-}
-
 type headlessRange struct {
 	Pos int `json:"pos"`
 	End int `json:"end"`
@@ -154,51 +146,56 @@ func runHeadless(args []string) int {
 		return 1
 	}
 
-	var config headlessConfig
+	payload, err := deserializePayload(configRaw)
 
-	if err := json.Unmarshal(configRaw, &config); err != nil {
+	if err != nil {
 		writeErrorMessage(fmt.Sprintf("error parsing config: %v", err))
 		return 1
 	}
-	if len(config.Files) == 0 {
-		writeErrorMessage("no files specified in config")
-		return 1
-	}
 
-	fileConfigs := make(map[string]headlessConfigForFile, len(config.Files))
 	workload := linter.Workload{
 		Programs:       make(map[string][]string),
 		UnmatchedFiles: []string{},
 	}
 
+	totalFileCount := 0
+	for _, config := range payload.Configs {
+		totalFileCount += len(config.FilePaths)
+	}
 	if logLevel == utils.LogLevelDebug {
-		log.Printf("Starting to assign files to programs. Total files: %d", len(config.Files))
+		log.Printf("Starting to assign files to programs. Total files: %d", totalFileCount)
 	}
 
 	tsConfigResolver := utils.NewTsConfigResolver(fs, cwd)
 
-	for idx, fileConfig := range config.Files {
-		if logLevel == utils.LogLevelDebug {
-			log.Printf("[%d/%d] Processing file: %s", idx+1, len(config.Files), fileConfig.FilePath)
-		}
+	fileConfigs := make(map[string][]headlessRule, totalFileCount)
+
+	idx := 0
+	for _, config := range payload.Configs {
+		for _, filePath := range config.FilePaths {
+			if logLevel == utils.LogLevelDebug {
+				log.Printf("[%d/%d] Processing file: %s", idx+1, totalFileCount, filePath)
+			}
 
-		normalizedFilePath := tspath.NormalizeSlashes(fileConfig.FilePath)
+			normalizedFilePath := tspath.NormalizeSlashes(filePath)
 
-		tsconfig, found := tsConfigResolver.FindTsconfigForFile(normalizedFilePath, false)
-		if logLevel == utils.LogLevelDebug {
-			tsconfigStr := "<none>"
-			if found {
-				tsconfigStr = tsconfig
+			tsconfig, found := tsConfigResolver.FindTsconfigForFile(normalizedFilePath, false)
+			if logLevel == utils.LogLevelDebug {
+				tsconfigStr := "<none>"
+				if found {
+					tsconfigStr = tsconfig
+				}
+				log.Printf("Got tsconfig for file %s: %s", normalizedFilePath, tsconfigStr)
 			}
-			log.Printf("Got tsconfig for file %s: %s", normalizedFilePath, tsconfigStr)
-		}
 
-		if !found {
-			workload.UnmatchedFiles = append(workload.UnmatchedFiles, normalizedFilePath)
-		} else {
-			workload.Programs[tsconfig] = append(workload.Programs[tsconfig], normalizedFilePath)
+			if !found {
+				workload.UnmatchedFiles = append(workload.UnmatchedFiles, normalizedFilePath)
+			} else {
+				workload.Programs[tsconfig] = append(workload.Programs[tsconfig], normalizedFilePath)
+			}
+			fileConfigs[normalizedFilePath] = config.Rules
+			idx++
 		}
-		fileConfigs[normalizedFilePath] = fileConfig
 	}
 
 	if logLevel == utils.LogLevelDebug {
@@ -279,12 +276,12 @@ func runHeadless(args []string) int {
 		runtime.GOMAXPROCS(0),
 		func(sourceFile *ast.SourceFile) []linter.ConfiguredRule {
 			cfg := fileConfigs[sourceFile.FileName()]
-			rules := make([]linter.ConfiguredRule, len(cfg.Rules))
+			rules := make([]linter.ConfiguredRule, len(cfg))
 
-			for i, ruleName := range cfg.Rules {
-				r, ok := allRulesByName[ruleName]
+			for i, headlessRule := range cfg {
+				r, ok := allRulesByName[headlessRule.Name]
 				if !ok {
-					panic(fmt.Sprintf("unknown rule: %v", ruleName))
+					panic(fmt.Sprintf("unknown rule: %v", headlessRule.Name))
 				}
 				rules[i] = linter.ConfiguredRule{
 					Name: r.Name,

cmd/tsgolint/payload.go

@@ -0,0 +1,90 @@
+package main
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/go-json-experiment/json"
+)
+
+// V1 Headless payload format
+type headlessConfigForFileV1 struct {
+	FilePath string   `json:"file_path"`
+	Rules    []string `json:"rules"`
+}
+type headlessPayloadV1 struct {
+	Files []headlessConfigForFileV1 `json:"files"`
+}
+
+// V2 (current) Headless payload format
+type headlessPayload struct {
+	Version int              `json:"version"` // version must be 2
+	Configs []headlessConfig `json:"configs"`
+}
+
+type headlessConfig struct {
+	FilePaths []string       `json:"file_paths"`
+	Rules     []headlessRule `json:"rules"`
+}
+
+type headlessRule struct {
+	Name string `json:"name"`
+}
+
+func deserializePayload(data []byte) (*headlessPayload, error) {
+	version, err := getPayloadVersion(data)
+	if err != nil {
+		return nil, err
+	}
+
+	if version == 2 {
+		var payload headlessPayload
+		if err := json.Unmarshal(data, &payload); err != nil {
+			return nil, errors.New("failed to deserialize V2 payload: " + err.Error())
+		}
+		return &payload, nil
+	}
+
+	// Version 0 or unset indicates V1 payload
+	if version != 0 {
+		return nil, fmt.Errorf("unsupported version `%d`: expected `unset` or `2`", version)
+	}
+
+	var payloadV1 headlessPayloadV1
+	if err := json.Unmarshal(data, &payloadV1); err != nil {
+		return nil, errors.New("failed to deserialize V1 payload: " + err.Error())
+	}
+
+	// Validate V1 payload
+	if len(payloadV1.Files) == 0 {
+		return nil, errors.New("V1 payload has no files")
+	}
+
+	// Convert V1 to V2
+	payloadV2 := &headlessPayload{
+		Version: 2,
+		Configs: make([]headlessConfig, len(payloadV1.Files)),
+	}
+	for i, fileV1 := range payloadV1.Files {
+		config := headlessConfig{
+			FilePaths: []string{fileV1.FilePath}, // V1 has single file, V2 supports multiple
+			Rules:     make([]headlessRule, len(fileV1.Rules)),
+		}
+		for j, rule := range fileV1.Rules {
+			config.Rules[j] = headlessRule{Name: rule} // V1 rules are just strings
+		}
+		payloadV2.Configs[i] = config
+	}
+
+	return payloadV2, nil
+}
+
+func getPayloadVersion(data []byte) (int, error) {
+	var versionCheck struct {
+		Version int `json:"version"`
+	}
+	if err := json.Unmarshal(data, &versionCheck); err != nil {
+		return 0, err
+	}
+	return versionCheck.Version, nil
+}

e2e/snapshot.test.ts

@@ -146,12 +146,26 @@ async function getTestFiles(testPath: string): Promise<string[]> {
 }
 
 function generateConfig(files: string[], rules: readonly (typeof ALL_RULES)[number][] = ALL_RULES): string {
+  // Headless payload format:
+  // ```json
+  // {
+  //   "configs": [
+  //     {
+  //       "file_paths": ["/abs/path/a.ts", ...],
+  //       "rules": [ { "name": "rule-a" }, { "name": "rule-b" } ]
+  //     }
+  //   ]
+  // }
+  // ```
   const config = {
-    files: files.map((filePath) => ({
-      file_path: filePath,
-      rules,
-    })),
-  };
+    version: 2,
+    configs: [
+      {
+        file_paths: files,
+        rules: rules.map((r) => ({ name: r })),
+      },
+    ],
+  } as const;
   return JSON.stringify(config);
 }
 
@@ -194,13 +208,13 @@ describe('TSGoLint E2E Snapshot Tests', () => {
       const rustStylePath = testFile.replace(/\//g, '\\');
 
       const config = {
-        files: [
+        configs: [
           {
-            file_path: rustStylePath,
-            rules: ['no-floating-promises'],
+            file_paths: [rustStylePath],
+            rules: [{ name: 'no-floating-promises' }],
           },
         ],
-      };
+      } as const;
 
       const env = { ...process.env, GOMAXPROCS: '1' };
 
@@ -252,4 +266,41 @@ describe('TSGoLint E2E Snapshot Tests', () => {
 
     expect(diagnostics).toMatchSnapshot();
   });
+
+  it('should work with the old version of the headless payload', async () => {
+    function generateV1HeadlessPayload(
+      files: string[],
+      rules: readonly (typeof ALL_RULES)[number][] = ALL_RULES,
+    ): string {
+      const config = {
+        files: files.map((filePath) => ({
+          file_path: filePath,
+          rules,
+        })),
+      };
+      return JSON.stringify(config);
+    }
+
+    function getDiagnostics(config: string): Diagnostic[] {
+      let output: Buffer;
+      output = execFileSync(TSGOLINT_BIN, ['headless'], {
+        input: config,
+        env: { ...process.env, GOMAXPROCS: '1' },
+      });
+
+      const diagnostics = parseHeadlessOutput(output);
+      return sortDiagnostics(diagnostics);
+    }
+
+    const testFiles = await getTestFiles('basic');
+    expect(testFiles.length).toBeGreaterThan(0);
+
+    const v1Config = generateV1HeadlessPayload(testFiles);
+    const v1Diagnostics = getDiagnostics(v1Config);
+
+    const v2Config = generateConfig(testFiles);
+    const v2Diagnostics = getDiagnostics(v2Config);
+
+    expect(v1Diagnostics).toStrictEqual(v2Diagnostics);
+  });
 });

internal/linter/linter.go

@@ -94,7 +94,6 @@ func RunLinter(logLevel utils.LogLevel, currentDirectory string, workload Worklo
 			return err
 		}
 
-
 		files := make([]*ast.SourceFile, 0, len(workload.UnmatchedFiles))
 		for _, f := range workload.UnmatchedFiles {
 			sf := program.GetSourceFile(f)