/**
 * Where the golden fixtures are, and what an absent checkout means — Story 4.4 AC-3.
 *
 * Deliberately a sibling of `corpusCheckout.ts` rather than a reuse of it: the two absences are DIFFERENT. The
 * templates corpus is production data in one repository; the golden fixtures and the pre-migration baseline live in the
 * planning repository (`hexasync-ideation-hub`), and a developer can plausibly have one and not the other. Folding them
 * together would report the wrong path in the wrong message, which is the one thing a fail-loudly guard must not do.
 *
 * What IS shared is the rule, and the reasoning behind it (`CLAUDE.md`): an absent checkout is a **failure**, not a
 * skip, and it throws at MODULE LOAD so it cannot be mistaken for one failing case among many passes — nor, more to the
 * point, for a pass. AC-3 states it directly: *"the suite fails loudly rather than skipping green."*
 *
 * CI never runs it: `goldenFlowsCorpus.spec.ts` is registered in `vitest.config.ts`'s `CORPUS`, and `yarn test:ci`
 * selects the `unit` project only. Exclusion is by SELECTION, never by a guard inside the file.
 */
import { existsSync } from 'node:fs';
import { describe } from 'vitest';

/** The planning repository's feature folder. Overridable, because a checkout can live anywhere. */
const FEATURE_DIR =
  process.env.HEXASYNC_CONNECTIONS_FEATURE ??
  '/config/workspaces/hexasync-ideation-hub/doing/hexasync-templates-vscode-ext/features/connections-generator';

export const GOLDEN_FIXTURES_DIR = `${FEATURE_DIR}/golden-flows/fixtures`;

/** Resolved once, so no spec re-derives the path — the rule `corpusCheckout.spec.ts` states for its own half. */
const hasFixtures = existsSync(GOLDEN_FIXTURES_DIR);

/**
 * Narrower than `typeof describe`, on purpose — the same choice `corpusCheckout.ts` makes, for the same reason.
 *
 * ⛔ It WAS `typeof describe`, which carries `.skip` — so `goldenSuite(...).skip(...)` compiled cleanly, re-opening the
 * exact escape hatch this module exists to close (Story 4.4 review, LOW). AC-3 says the suite fails loudly; a type that
 * hands back a skippable suite invites the opposite.
 */
type Suite = (name: string, body: () => void) => void;

export function goldenSuite(
  tag: string,
  cannotRun: string,
  why: string,
): Suite {
  if (hasFixtures) return describe;

  throw new Error(
    `[${tag}] No golden fixtures at ${GOLDEN_FIXTURES_DIR}. ${cannotRun} ${why}\n` +
      'They live in the hexasync-ideation-hub repository. Clone it, or set HEXASYNC_CONNECTIONS_FEATURE to your ' +
      "checkout's feature folder.\n" +
      'On CI these are not run at all — use `yarn test:ci`, which selects the `unit` project only.',
  );
}