[compiler][snap] Fixes to relative path resolution; compile subcommand (#35688)

More snap improvements for use with agents:
* `yarn snap compile [--debug] <path>` for compiling any file,
optionally with debug logs
* `yarn snap minimize <path>` now accepts path as a positional param for
consistency w 'compile' command
* Both compile/minimize commands properly handle paths relative to the
compiler/ directory. When using `yarn snap` the current working
directory is compiler/packages/snap, but you're generally running it
from the compiler directory so this matches expectations of callers
better.

Author: josephsavona

compiler/.claude/agents/investigate-error.md

@@ -13,7 +13,7 @@ You are an expert React Compiler debugging specialist with deep knowledge of com
 Create a new fixture file at `packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/<fixture-name>.js` containing the problematic code. Use a descriptive name that reflects the issue (e.g., `bug-optional-chain-in-effect.js`).
 
 ### Step 2: Run Debug Compilation
-Execute `yarn snap -d -p <fixture-name>` to compile the fixture with full debug output. This shows the state of the program after each compilation pass.
+Execute `yarn snap -d -p <fixture-name>` to compile the fixture with full debug output. This shows the state of the program after each compilation pass. You can also use `yarn snap compile -d <path-to-fixture>`.
 
 ### Step 3: Analyze Compilation Results
 

compiler/CLAUDE.md

@@ -35,6 +35,31 @@ yarn snap -p <file-basename> -d
 yarn snap -u
 ```
 
+## Compiling Arbitrary Files
+
+Use `yarn snap compile` to compile any file (not just fixtures) with the React Compiler:
+
+```bash
+# Compile a file and see the output
+yarn snap compile <path>
+
+# Compile with debug logging to see the state after each compiler pass
+# This is an alternative to `yarn snap -d -p <pattern>` when you don't have a fixture file yet
+yarn snap compile --debug <path>
+```
+
+## Minimizing Test Cases
+
+Use `yarn snap minimize` to automatically reduce a failing test case to its minimal reproduction:
+
+```bash
+# Minimize a file that causes a compiler error
+yarn snap minimize <path>
+
+# Minimize and update the file in-place with the minimized version
+yarn snap minimize --update <path>
+```
+
 ## Version Control
 
 This repository uses Sapling (`sl`) for version control. Sapling is similar to Mercurial: there is not staging area, but new/deleted files must be explicitlyu added/removed.

compiler/docs/DEVELOPMENT_GUIDE.md

@@ -17,7 +17,32 @@ yarn snap:build
 yarn snap --watch
 ```
 
-`snap` is our custom test runner, which creates "golden" test files that have the expected output for each input fixture, as well as the results of executing a specific input (or sequence of inputs) in both the uncompiled and compiler versions of the input. 
+`snap` is our custom test runner, which creates "golden" test files that have the expected output for each input fixture, as well as the results of executing a specific input (or sequence of inputs) in both the uncompiled and compiler versions of the input.
+
+### Compiling Arbitrary Files
+
+You can compile any file (not just fixtures) using:
+
+```sh
+# Compile a file and see the output
+yarn snap compile <path>
+
+# Compile with debug output to see the state after each compiler pass
+# This is an alternative to `yarn snap -d -p <pattern>` when you don't have a fixture file yet
+yarn snap compile --debug <path>
+```
+
+### Minimizing Test Cases
+
+To reduce a failing test case to its minimal reproduction:
+
+```sh
+# Minimize a file that causes a compiler error
+yarn snap minimize <path>
+
+# Minimize and update the file in-place
+yarn snap minimize --update <path>
+```
 
 When contributing changes, we prefer to:
 * Add one or more fixtures that demonstrate the current compiled output for a particular combination of input and configuration. Send this as a first PR.

compiler/packages/babel-plugin-react-compiler/docs/passes/README.md

@@ -294,6 +294,15 @@ yarn snap -p <fixture-name>
 # Run with debug output (shows all passes)
 yarn snap -p <fixture-name> -d
 
+# Compile any file (not just fixtures) and see output
+yarn snap compile <path>
+
+# Compile any file with debug output (alternative to yarn snap -d -p when you don't have a fixture)
+yarn snap compile --debug <path>
+
+# Minimize a failing test case to its minimal reproduction
+yarn snap minimize <path>
+
 # Update expected outputs
 yarn snap -u
 ```

compiler/packages/snap/src/constants.ts

@@ -7,19 +7,21 @@
 
 import path from 'path';
 
+export const PROJECT_ROOT = path.join(process.cwd(), '..', '..');
+
 // We assume this is run from `babel-plugin-react-compiler`
-export const PROJECT_ROOT = path.normalize(
-  path.join(process.cwd(), '..', 'babel-plugin-react-compiler'),
+export const BABEL_PLUGIN_ROOT = path.normalize(
+  path.join(PROJECT_ROOT, 'packages', 'babel-plugin-react-compiler'),
 );
 
-export const PROJECT_SRC = path.normalize(
-  path.join(PROJECT_ROOT, 'dist', 'index.js'),
+export const BABEL_PLUGIN_SRC = path.normalize(
+  path.join(BABEL_PLUGIN_ROOT, 'dist', 'index.js'),
 );
 export const PRINT_HIR_IMPORT = 'printFunctionWithOutlined';
 export const PRINT_REACTIVE_IR_IMPORT = 'printReactiveFunction';
 export const PARSE_CONFIG_PRAGMA_IMPORT = 'parseConfigPragmaForTests';
 export const FIXTURES_PATH = path.join(
-  PROJECT_ROOT,
+  BABEL_PLUGIN_ROOT,
   'src',
   '__tests__',
   'fixtures',

compiler/packages/snap/src/minimize.ts

@@ -12,7 +12,7 @@ import traverse from '@babel/traverse';
 import * as t from '@babel/types';
 import type {parseConfigPragmaForTests as ParseConfigPragma} from 'babel-plugin-react-compiler/src/Utils/TestUtils';
 import {parseInput} from './compiler.js';
-import {PARSE_CONFIG_PRAGMA_IMPORT, PROJECT_SRC} from './constants.js';
+import {PARSE_CONFIG_PRAGMA_IMPORT, BABEL_PLUGIN_SRC} from './constants.js';
 
 type CompileSuccess = {kind: 'success'};
 type CompileParseError = {kind: 'parse_error'; message: string};
@@ -1919,7 +1919,7 @@ export function minimize(
   sourceType: 'module' | 'script',
 ): MinimizeResult {
   // Load the compiler plugin
-  const importedCompilerPlugin = require(PROJECT_SRC) as Record<
+  const importedCompilerPlugin = require(BABEL_PLUGIN_SRC) as Record<
     string,
     unknown
   >;

compiler/packages/snap/src/runner-watch.ts

@@ -8,7 +8,7 @@
 import watcher from '@parcel/watcher';
 import path from 'path';
 import ts from 'typescript';
-import {FIXTURES_PATH, PROJECT_ROOT} from './constants';
+import {FIXTURES_PATH, BABEL_PLUGIN_ROOT} from './constants';
 import {TestFilter, getFixtures} from './fixture-utils';
 import {execSync} from 'child_process';
 
@@ -17,7 +17,7 @@ export function watchSrc(
   onComplete: (isSuccess: boolean) => void,
 ): ts.WatchOfConfigFile<ts.SemanticDiagnosticsBuilderProgram> {
   const configPath = ts.findConfigFile(
-    /*searchPath*/ PROJECT_ROOT,
+    /*searchPath*/ BABEL_PLUGIN_ROOT,
     ts.sys.fileExists,
     'tsconfig.json',
   );
@@ -166,7 +166,7 @@ function subscribeTsc(
       let isCompilerBuildValid = false;
       if (isTypecheckSuccess) {
         try {
-          execSync('yarn build', {cwd: PROJECT_ROOT});
+          execSync('yarn build', {cwd: BABEL_PLUGIN_ROOT});
           console.log('Built compiler successfully with tsup');
           isCompilerBuildValid = true;
         } catch (e) {

compiler/packages/snap/src/runner-worker.ts

@@ -5,7 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {codeFrameColumns} from '@babel/code-frame';
 import type {PluginObj} from '@babel/core';
 import type {parseConfigPragmaForTests as ParseConfigPragma} from 'babel-plugin-react-compiler/src/Utils/TestUtils';
 import type {printFunctionWithOutlined as PrintFunctionWithOutlined} from 'babel-plugin-react-compiler/src/HIR/PrintHIR';
@@ -15,7 +14,7 @@ import {
   PARSE_CONFIG_PRAGMA_IMPORT,
   PRINT_HIR_IMPORT,
   PRINT_REACTIVE_IR_IMPORT,
-  PROJECT_SRC,
+  BABEL_PLUGIN_SRC,
 } from './constants';
 import {TestFixture, getBasename, isExpectError} from './fixture-utils';
 import {TestResult, writeOutputToString} from './reporter';
@@ -65,7 +64,7 @@ async function compile(
   let compileResult: TransformResult | null = null;
   let error: string | null = null;
   try {
-    const importedCompilerPlugin = require(PROJECT_SRC) as Record<
+    const importedCompilerPlugin = require(BABEL_PLUGIN_SRC) as Record<
       string,
       unknown
     >;