fix(showcase): make railway-graphql .com scan guard fail-loud + harden endpoint constant

Author: jpr5

showcase/scripts/lib/__tests__/railway-graphql.scan.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import path from "node:path";
 
 const REPO_ROOT = path.resolve(__dirname, "../../../..");
@@ -8,20 +8,45 @@ describe("Railway GraphQL host unification", () => {
   it("no source file references backboard.railway.com (must be .app)", () => {
     // grep across showcase/ and .github/workflows/. Use -F (literal) so
     // the dot in the pattern is not regex-interpreted. The test file
-    // itself contains the forbidden literal; exclude it via --glob.
-    // Also exclude two files that legitimately reference the deprecated
-    // host in documentation/negative-assertion form (no functional use):
+    // itself contains the forbidden literal; exclude it via git pathspec
+    // `:(exclude)` magic. Also exclude two files that legitimately
+    // reference the deprecated host in documentation/negative-assertion
+    // form (no functional use):
     //   - railway-graphql.ts JSDoc explains the deprecated .com endpoint
     //   - railway-graphql.test.ts asserts the endpoint is NOT .com
+    // Use --untracked so a newly-added (not-yet-committed) file that
+    // reintroduces the forbidden host still trips the guard. Use
+    // execFileSync with an args array so REPO_ROOT is not shell-parsed.
     let out = "";
     try {
-      out = execSync(
-        `git -C ${REPO_ROOT} grep -nF "backboard.railway.com" -- showcase ':(exclude)showcase/scripts/lib/__tests__/railway-graphql.scan.test.ts' ':(exclude)showcase/scripts/lib/railway-graphql.ts' ':(exclude)showcase/scripts/lib/__tests__/railway-graphql.test.ts' .github/workflows`,
+      out = execFileSync(
+        "git",
+        [
+          "-C",
+          REPO_ROOT,
+          "grep",
+          "--untracked",
+          "-nF",
+          "backboard.railway.com",
+          "--",
+          "showcase",
+          ":(exclude)showcase/scripts/lib/__tests__/railway-graphql.scan.test.ts",
+          ":(exclude)showcase/scripts/lib/railway-graphql.ts",
+          ":(exclude)showcase/scripts/lib/__tests__/railway-graphql.test.ts",
+          ".github/workflows",
+        ],
         { encoding: "utf-8" },
       );
-    } catch {
-      // git grep exits 1 when no matches — that's the success case.
-      out = "";
+    } catch (err) {
+      // git grep exits 1 when no matches — that's the clean-miss success
+      // case. Any other exit status (git missing, bad cwd, pathspec
+      // syntax error, etc.) must fail loud rather than silently pass.
+      const status = (err as { status?: number }).status;
+      if (status === 1) {
+        out = "";
+      } else {
+        throw err;
+      }
     }
     expect(out).toBe("");
   });

showcase/scripts/lib/railway-graphql.ts

@@ -1,11 +1,20 @@
 /**
  * railway-graphql.ts — Single source of truth for the Railway GraphQL
- * endpoint host. ALL Railway GraphQL callers in this repo (TypeScript
- * scripts, workflow inline curls, and Ruby `bin/railway` via its own
- * constant) MUST resolve to this exact URL. The historic `.com` host
- * (`backboard.railway.com`) is unauthenticated for the public GraphQL
- * API and silently returns 401/403 — fixing here in one place prevents
- * it from coming back.
+ * endpoint host for TypeScript importers in this repo. The historic
+ * `.com` host (`backboard.railway.com`) is unauthenticated for the
+ * public GraphQL API and silently returns 401/403; the canonical host
+ * is `backboard.railway.app`.
+ *
+ * Note: the Ruby `bin/railway` script and the inline `curl` commands
+ * embedded in `.github/workflows/*.yml` hold their OWN copies of this
+ * URL because they cannot import a TypeScript module. Those copies are
+ * kept in sync by hand and enforced by the regression guard in
+ * `./__tests__/railway-graphql.scan.test.ts`, which fails the build if
+ * any source file under `showcase/` or `.github/workflows/` reintroduces
+ * the `.com` host.
  */
 export const RAILWAY_GRAPHQL_ENDPOINT =
-    "https://backboard.railway.app/graphql/v2";
+    "https://backboard.railway.app/graphql/v2" as const;
+
+// Fail-fast at module load if a hand-edit ever breaks the URL literal.
+new URL(RAILWAY_GRAPHQL_ENDPOINT);