Add shard_extra_artifacts feature flag to shard PHP text artifacts

Summary:
Adds a `ProjectConfig::create_path_for_extra_artifact()` helper in `relay-config` and a `shard_extra_artifacts` `FeatureFlag` in the shared OSS `FeatureFlags`. The helper mirrors `create_path_for_artifact()` (honoring `shardOutput` / `shardStripRegex`) but is rooted at `extraArtifactsOutput`, with sharding gated by an explicit `should_shard` argument so callers can roll it out behind a flag. No OSS call sites use the flag today — internal PHP text-artifact generation is the only current consumer.

 ---

Today, generated PHP text artifacts (`RelayOperation.php`, `RelayFragment.php`) are written to a flat directory under `extraArtifactsOutput`, ignoring the project's `shardOutput` / `shardStripRegex` configuration. Normal JS artifacts use `ProjectConfig::create_path_for_artifact()` which shards output into subdirectories mirroring the source file's relative path — but the PHP codepath bypasses this entirely with a simple `extra_artifacts_output.join(filename)`.

This diff adds:
- A new `ProjectConfig::create_path_for_extra_artifact()` helper in `relay-config` that mirrors the sharding logic of `create_path_for_artifact()` but rooted at `extra_artifacts_output`. It takes an explicit `should_shard: bool` so callers can gate the behavior during rollout.
- A `shard_extra_artifacts` `FeatureFlag` in the OSS `FeatureFlags` struct (same pattern as `text_artifacts` — both control FB-only PHP generation but live in the shared config for consistency with the `"featureFlags"` JSON block).
- Wiring in `text_artifacts_generators.rs` to call the new helper, checking `feature_flags.shard_extra_artifacts.is_enabled_for(source_name)`.
- Simplification of the `FBProjectConfig` fallback construction in `main.rs` to use `..Default::default()` (prevents breakage when new fields are added).
- 5 unit tests covering: sharded with regex, sharded without regex, unsharded, shard flag ignored when project doesn't shard, and panic on missing `extra_artifacts_output`.

When the flag is disabled (default), behavior is identical to today. When enabled, PHP artifacts are placed in subdirectories matching the source file layout (e.g. `flib/__generated__/.../js/enterprise/ui/foo/BarRelayOperation.php` instead of flat `flib/__generated__/.../BarRelayOperation.php`).

Note: the Hack preloader (`hack_query_preloader.rs`) has the same flat-path issue but is intentionally not changed in this diff — follow-up.

Reviewed By: evanyeung

Differential Revision: D105719732

fbshipit-source-id: 2cd22a6d1db50a9c3b833a0b1ed07eef43ccceef

Author: tyao1

compiler/crates/common/src/feature_flags.rs

@@ -54,6 +54,12 @@ pub struct FeatureFlags {
     #[serde(default)]
     pub text_artifacts: FeatureFlag,
 
+    /// Shard generated extra artifacts into subdirectories under
+    /// `extraArtifactsOutput` that mirror the source file's relative path,
+    /// honoring `shardOutput` / `shardStripRegex`.
+    #[serde(default)]
+    pub shard_extra_artifacts: FeatureFlag,
+
     #[serde(default)]
     pub skip_printing_nulls: FeatureFlag,
 
@@ -223,6 +229,7 @@ impl Default for FeatureFlags {
             no_inline: Default::default(),
             enable_3d_branch_arg_generation: Default::default(),
             text_artifacts: Default::default(),
+            shard_extra_artifacts: Default::default(),
             skip_printing_nulls: Default::default(),
             compact_query_text: Default::default(),
             enable_resolver_normalization_ast: Default::default(),

compiler/crates/relay-config/src/project_config.rs

@@ -447,6 +447,50 @@ impl ProjectConfig {
         }
     }
 
+    /// Gets the path for a generated *extra* artifact based on its
+    /// originating source file's location and the project's configuration.
+    ///
+    /// Mirrors [`Self::create_path_for_artifact`], except the output root is
+    /// `extra_artifacts_output`. Sharding is opt-in via `should_shard` —
+    /// callers gate this on a feature flag while the new behavior is rolled
+    /// out, so that passing `should_shard = false` reproduces the legacy
+    /// flat layout (`extra_artifacts_output.join(file_name)`).
+    ///
+    /// When `should_shard` is true but the project does not set
+    /// `shardOutput`, the call silently falls back to the flat layout. This
+    /// is intentional: the feature flag may be enabled across many projects
+    /// during rollout, but only those that already opt into `shardOutput`
+    /// get the new sharded layout.
+    ///
+    /// Panics if `extra_artifacts_output` is unset; only projects that
+    /// configure `extraArtifactsOutput` produce extra artifacts, so reaching
+    /// this with no output configured indicates an internal invariant
+    /// violation rather than user misconfiguration.
+    pub fn create_path_for_extra_artifact(
+        &self,
+        source_file: SourceLocationKey,
+        artifact_file_name: String,
+        should_shard: bool,
+    ) -> PathBuf {
+        let output = self.extra_artifacts_output.as_ref().expect(
+            "create_path_for_extra_artifact called without `extraArtifactsOutput` set on the project config",
+        );
+        if should_shard && self.shard_output {
+            if let Some(ref regex) = self.shard_strip_regex {
+                let full_source_path = regex.replace_all(source_file.path(), "");
+                let mut path = output.join(full_source_path.to_string());
+                // `full_source_path` still includes the source file name; pop it to get the directory.
+                path.pop();
+                path
+            } else {
+                output.join(source_file.get_dir())
+            }
+            .join(artifact_file_name)
+        } else {
+            output.join(artifact_file_name)
+        }
+    }
+
     /// Generates a path for an artifact file based on a definition name and its location.
     pub fn artifact_path_for_definition(
         &self,
@@ -533,3 +577,87 @@ fn format_normalized_path(path: &Path) -> String {
         .to_string()
         .replace(MAIN_SEPARATOR, "/")
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn project_with_extra(
+        extra_artifacts_output: Option<&str>,
+        shard_output: bool,
+        shard_strip_regex: Option<&str>,
+    ) -> ProjectConfig {
+        ProjectConfig {
+            extra_artifacts_output: extra_artifacts_output.map(PathBuf::from),
+            shard_output,
+            shard_strip_regex: shard_strip_regex.map(|r| Regex::new(r).unwrap()),
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn extra_artifact_path_unsharded_keeps_legacy_flat_layout() {
+        let config = project_with_extra(Some("out/extra"), true, Some("^src/"));
+        let path = config.create_path_for_extra_artifact(
+            SourceLocationKey::standalone("src/components/foo/Bar.js"),
+            "BarOperation.graphql.js".to_owned(),
+            false,
+        );
+        assert_eq!(
+            path,
+            PathBuf::from("out/extra/BarOperation.graphql.js"),
+            "shard=false should produce the same flat path as the legacy call site"
+        );
+    }
+
+    #[test]
+    fn extra_artifact_path_sharded_with_regex_mirrors_normal_artifact_layout() {
+        let config = project_with_extra(Some("out/extra"), true, Some("^src/"));
+        let path = config.create_path_for_extra_artifact(
+            SourceLocationKey::standalone("src/components/foo/Bar.js"),
+            "BarOperation.graphql.js".to_owned(),
+            true,
+        );
+        assert_eq!(
+            path,
+            PathBuf::from("out/extra/components/foo/BarOperation.graphql.js"),
+            "Source 'src/components/foo/Bar.js' with regex '^src/' should shard under 'components/foo/'"
+        );
+    }
+
+    #[test]
+    fn extra_artifact_path_sharded_without_regex_uses_full_source_dir() {
+        let config = project_with_extra(Some("out/extra"), true, None);
+        let path = config.create_path_for_extra_artifact(
+            SourceLocationKey::standalone("a/b/c/Bar.js"),
+            "BarOperation.graphql.js".to_owned(),
+            true,
+        );
+        assert_eq!(
+            path,
+            PathBuf::from("out/extra/a/b/c/BarOperation.graphql.js"),
+        );
+    }
+
+    #[test]
+    fn extra_artifact_path_shard_arg_ignored_when_project_does_not_shard() {
+        let config = project_with_extra(Some("out/extra"), false, Some("^src/"));
+        let path = config.create_path_for_extra_artifact(
+            SourceLocationKey::standalone("src/components/foo/Bar.js"),
+            "BarOperation.graphql.js".to_owned(),
+            true,
+        );
+        assert_eq!(path, PathBuf::from("out/extra/BarOperation.graphql.js"),);
+    }
+
+    #[test]
+    #[should_panic(expected = "extraArtifactsOutput")]
+    fn extra_artifact_path_panics_without_extra_artifacts_output() {
+        let config = project_with_extra(None, true, Some("^src/"));
+        let _ = config.create_path_for_extra_artifact(
+            SourceLocationKey::standalone("src/components/foo/Bar.js"),
+            "Bar.graphql.js".to_owned(),
+            true,
+        );
+    }
+}