@dreamboard-games/workspace-codegen 0.1.0

package/src/ownership.ts

@@ -0,0 +1,127 @@
+export type OwnershipPattern = {
+  prefix: string;
+  suffix: string;
+};
+
+export type ScaffoldingOwnership = {
+  version: number;
+  allowedPaths: {
+    rootFiles: string[];
+    directoryPrefixes: string[];
+  };
+  dynamic: {
+    generatedFiles: string[];
+    seedFiles: string[];
+    seedFilePatterns: OwnershipPattern[];
+  };
+  cliStatic: {
+    exactFiles: string[];
+    directoryPrefixes: string[];
+  };
+  preservedUserFiles: string[];
+};
+
+export const WORKSPACE_CODEGEN_OWNERSHIP: ScaffoldingOwnership = {
+  version: 26,
+  allowedPaths: {
+    rootFiles: [
+      ".npmrc",
+      "package.json",
+      "pnpm-lock.yaml",
+      "package-lock.json",
+      "manifest.ts",
+      "manifest.tsconfig.json",
+      "rule.md",
+    ],
+    directoryPrefixes: ["app/", "ui/", "shared/", "test/"],
+  },
+  dynamic: {
+    generatedFiles: [
+      "shared/manifest-literals.ts",
+      "shared/manifest-types.ts",
+      "shared/manifest-runtime.ts",
+      "shared/manifest-contract.ts",
+      "shared/generated/ui-contract.ts",
+      "app/index.ts",
+      "app/tsconfig.framework.json",
+      "ui/tsconfig.framework.json",
+    ],
+    seedFiles: [
+      "app/README.md",
+      "ui/App.tsx",
+      "app/game-contract.ts",
+      "app/game.ts",
+      "app/setup-profiles.ts",
+      "app/reducer-support.ts",
+      "app/derived.ts",
+    ],
+    seedFilePatterns: [{ prefix: "app/phases/", suffix: ".ts" }],
+  },
+  cliStatic: {
+    exactFiles: [
+      ".npmrc",
+      "package.json",
+      "app/tsconfig.json",
+      "ui/index.tsx",
+      "ui/package.json",
+      "ui/style.css",
+      "ui/tsconfig.json",
+    ],
+    directoryPrefixes: [],
+  },
+  preservedUserFiles: [],
+} as const;
+
+export const AUTHORITATIVE_GENERATED_FILES =
+  WORKSPACE_CODEGEN_OWNERSHIP.dynamic.generatedFiles;
+export const SEED_FILES = WORKSPACE_CODEGEN_OWNERSHIP.dynamic.seedFiles;
+export const SEED_FILE_PATTERNS =
+  WORKSPACE_CODEGEN_OWNERSHIP.dynamic.seedFilePatterns;
+export const PRESERVED_USER_FILES = new Set(
+  WORKSPACE_CODEGEN_OWNERSHIP.preservedUserFiles,
+);
+
+function normalizeProjectPath(filePath: string): string {
+  return filePath.replace(/^\.\//, "").replace(/^\/+/, "").replace(/\\/g, "/");
+}
+
+export function isAllowedGamePath(filePath: string): boolean {
+  const path = normalizeProjectPath(filePath);
+  if (WORKSPACE_CODEGEN_OWNERSHIP.allowedPaths.rootFiles.includes(path)) {
+    return true;
+  }
+  return WORKSPACE_CODEGEN_OWNERSHIP.allowedPaths.directoryPrefixes.some(
+    (prefix) => path.startsWith(prefix),
+  );
+}
+
+export function isAuthoritativeGeneratedPath(filePath: string): boolean {
+  const path = normalizeProjectPath(filePath);
+  return WORKSPACE_CODEGEN_OWNERSHIP.dynamic.generatedFiles.includes(path);
+}
+
+export function isDynamicSeedPath(filePath: string): boolean {
+  const path = normalizeProjectPath(filePath);
+  if (WORKSPACE_CODEGEN_OWNERSHIP.dynamic.seedFiles.includes(path)) {
+    return true;
+  }
+  return WORKSPACE_CODEGEN_OWNERSHIP.dynamic.seedFilePatterns.some(
+    (pattern) =>
+      path.startsWith(pattern.prefix) && path.endsWith(pattern.suffix),
+  );
+}
+
+export function isCliStaticPath(filePath: string): boolean {
+  const path = normalizeProjectPath(filePath);
+  if (WORKSPACE_CODEGEN_OWNERSHIP.cliStatic.exactFiles.includes(path)) {
+    return true;
+  }
+  return WORKSPACE_CODEGEN_OWNERSHIP.cliStatic.directoryPrefixes.some(
+    (prefix) => path.startsWith(prefix),
+  );
+}
+
+export function isLibraryPath(filePath: string): boolean {
+  const path = normalizeProjectPath(filePath);
+  return isAuthoritativeGeneratedPath(path);
+}

package/src/preset-card-sets.ts

@@ -0,0 +1,169 @@
+import type {
+  BoardCard,
+  GameTopologyManifest,
+  ManualCardSetDefinition,
+  ObjectSchema,
+  PresetCardSetDefinition,
+  PropertySchema,
+} from "@dreamboard/sdk-types";
+
+const STANDARD_DECK_ID = "standard_52_deck";
+
+function createEnumPropertySchema(
+  enums: string[],
+  description: string,
+): PropertySchema {
+  return {
+    type: "enum",
+    description,
+    enums,
+  };
+}
+
+function createStringPropertySchema(description: string): PropertySchema {
+  return {
+    type: "string",
+    description,
+  };
+}
+
+export function createStandard52CardDeck(): ManualCardSetDefinition {
+  const suits = ["SPADES", "HEARTS", "CLUBS", "DIAMONDS"];
+  const ranks = [
+    "3",
+    "4",
+    "5",
+    "6",
+    "7",
+    "8",
+    "9",
+    "10",
+    "J",
+    "Q",
+    "K",
+    "A",
+    "2",
+  ];
+
+  const cards: BoardCard[] = [];
+  for (const suit of suits) {
+    for (const rank of ranks) {
+      cards.push({
+        type: `${suit}_${rank}`,
+        name: `${rank} of ${suit}`,
+        imageUrl: `/cards/${suit.toLowerCase()}_${rank.toLowerCase()}.png`,
+        text: `A playing card: ${rank} of ${suit}. Value: ${getBigTwoCardValue(rank)}, Suit value: ${getSuitValue(suit)}`,
+        count: 1,
+        cardType: `${suit}_${rank}`,
+        properties: {
+          suit,
+          rank,
+        },
+      });
+    }
+  }
+
+  return {
+    id: STANDARD_DECK_ID,
+    name: "Standard 52-Card Deck",
+    type: "manual",
+    cards,
+    cardSchema: {
+      properties: {
+        suit: createEnumPropertySchema(
+          ["SPADES", "HEARTS", "CLUBS", "DIAMONDS"],
+          "The suit of the card",
+        ),
+        rank: createStringPropertySchema("The rank of the card"),
+      },
+    } satisfies ObjectSchema,
+  };
+}
+
+export function addStandardDecksIfNeeded(
+  manifest: GameTopologyManifest,
+): GameTopologyManifest {
+  return {
+    ...manifest,
+    cardSets: manifest.cardSets.map((cardSet) =>
+      cardSet.type === "preset" && cardSet.presetId === STANDARD_DECK_ID
+        ? {
+            ...createStandard52CardDeck(),
+            id: cardSet.id,
+            name: cardSet.name,
+          }
+        : cardSet,
+    ),
+  };
+}
+
+export function materializePresetCardSet(
+  presetCardSet: PresetCardSetDefinition,
+): ManualCardSetDefinition {
+  if (presetCardSet.presetId !== STANDARD_DECK_ID) {
+    throw new Error(`Unsupported preset deck: ${presetCardSet.presetId}`);
+  }
+
+  const standardDeck = createStandard52CardDeck();
+  return {
+    ...standardDeck,
+    id: presetCardSet.id,
+    name: presetCardSet.name,
+  };
+}
+
+export function materializeCardSet(
+  cardSet: GameTopologyManifest["cardSets"][number],
+): ManualCardSetDefinition {
+  return cardSet.type === "manual"
+    ? cardSet
+    : materializePresetCardSet(cardSet);
+}
+
+function getBigTwoCardValue(rank: string): number {
+  switch (rank) {
+    case "3":
+      return 3;
+    case "4":
+      return 4;
+    case "5":
+      return 5;
+    case "6":
+      return 6;
+    case "7":
+      return 7;
+    case "8":
+      return 8;
+    case "9":
+      return 9;
+    case "10":
+      return 10;
+    case "J":
+      return 11;
+    case "Q":
+      return 12;
+    case "K":
+      return 13;
+    case "A":
+      return 14;
+    case "2":
+      return 15;
+    default:
+      return 0;
+  }
+}
+
+function getSuitValue(suit: string): number {
+  switch (suit) {
+    case "DIAMONDS":
+      return 1;
+    case "CLUBS":
+      return 2;
+    case "HEARTS":
+      return 3;
+    case "SPADES":
+      return 4;
+    default:
+      return 0;
+  }
+}

package/src/sdk-types-authoring.test.ts

@@ -0,0 +1,361 @@
+import { readdirSync } from "node:fs";
+import path from "node:path";
+import { expect, test } from "bun:test";
+import ts from "typescript";
+
+const fixtureRoot = path.join(import.meta.dir, "__fixtures__", "sdk-types");
+const workspaceCodegenRoot = path.resolve(import.meta.dir, "..");
+
+const FIXTURE_FILES: readonly string[] = readdirSync(fixtureRoot)
+  .filter((name) => name.endsWith(".ts"))
+  .map((name) => path.join(fixtureRoot, name));
+
+const COMPILER_OPTIONS: ts.CompilerOptions = {
+  noEmit: true,
+  strict: true,
+  target: ts.ScriptTarget.ES2022,
+  module: ts.ModuleKind.ESNext,
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  skipLibCheck: true,
+};
+
+const DIAGNOSTIC_FORMAT_HOST: ts.FormatDiagnosticsHost = {
+  getCanonicalFileName: (fileName) => fileName,
+  getCurrentDirectory: () => workspaceCodegenRoot,
+  getNewLine: () => "\n",
+};
+
+/**
+ * Shared TypeScript program covering every fixture file. Building one program
+ * per test process lets us reuse the parsed lib + SDK declaration graph across
+ * ~40 fixtures instead of spawning a cold `tsc --noEmit` per case
+ * (previously ~4s per spawn, ~120s total).
+ */
+let cachedProgram: ts.Program | null = null;
+function getProgram(): ts.Program {
+  if (!cachedProgram) {
+    cachedProgram = ts.createProgram({
+      rootNames: [...FIXTURE_FILES],
+      options: COMPILER_OPTIONS,
+    });
+  }
+  return cachedProgram;
+}
+
+function fixtureFilePath(fileName: string): string {
+  return path.join(fixtureRoot, fileName);
+}
+
+function getDiagnosticsForFixture(fileName: string): ts.Diagnostic[] {
+  const program = getProgram();
+  const targetPath = fixtureFilePath(fileName);
+  const sourceFile = program.getSourceFile(targetPath);
+  if (!sourceFile) {
+    throw new Error(
+      `Fixture not loaded into shared program: ${targetPath}. Ensure the file exists and is included in FIXTURE_FILES.`,
+    );
+  }
+  return [
+    ...program.getSyntacticDiagnostics(sourceFile),
+    ...program.getSemanticDiagnostics(sourceFile),
+  ];
+}
+
+function formatDiagnostics(diagnostics: readonly ts.Diagnostic[]): string {
+  return ts.formatDiagnostics(diagnostics, DIAGNOSTIC_FORMAT_HOST);
+}
+
+function expectFixtureTypechecks(fileName: string): void {
+  const diagnostics = getDiagnosticsForFixture(fileName);
+  if (diagnostics.length > 0) {
+    throw new Error(
+      `Typecheck failed for ${fileName}\n${formatDiagnostics(diagnostics)}`,
+    );
+  }
+}
+
+function expectTypecheckFailure(
+  fileName: string,
+  expectedSnippets: readonly string[],
+): void {
+  const diagnostics = getDiagnosticsForFixture(fileName);
+  const output = formatDiagnostics(diagnostics);
+
+  expect(diagnostics.length).toBeGreaterThan(0);
+  for (const snippet of expectedSnippets) {
+    expect(output).toContain(snippet);
+  }
+}
+
+test("defineTopologyManifest accepts valid typed references", () => {
+  expectFixtureTypechecks("valid-manifest.ts");
+});
+
+test("defineTopologyManifest accepts valid player-scoped seed homes with ownerId", () => {
+  expectFixtureTypechecks("valid-player-scoped-seed-homes.ts");
+});
+
+test("defineTopologyManifest accepts omitted boardTemplates", () => {
+  expectFixtureTypechecks("valid-manifest-omits-board-templates.ts");
+});
+
+test("defineTopologyManifest accepts die types that omit sides", () => {
+  expectFixtureTypechecks("valid-die-type-omits-sides.ts");
+});
+
+test("defineTopologyManifest rejects invalid typed references", () => {
+  expectTypecheckFailure("invalid-manifest.ts", [
+    "Type '\"discard\"' is not assignable to type '\"draw\"'",
+    "Type '\"missing-card-set\"' is not assignable to type '\"main\"'",
+    "Type '\"space-b\"' is not assignable to type '\"space-a\"'",
+    'Type \'"missing-slot"\' is not assignable to type \'"worker-rest" | "staging"\'',
+    "Type '\"draft\"' is not assignable to type '\"standard\"'",
+  ]);
+});
+
+test("defineTopologyManifest rejects invalid strict slot host ids", () => {
+  expectTypecheckFailure("invalid-slot-host-manifest.ts", [
+    "Type '\"missing-host\"' is not assignable to type '\"mat-alpha\"'",
+  ]);
+});
+
+test("defineTopologyManifest rejects invalid strict slot ids", () => {
+  expectTypecheckFailure("invalid-slot-id-manifest.ts", [
+    "Type '\"missing-slot\"' is not assignable to type '\"staging\"'",
+  ]);
+});
+
+test("defineTopologyManifest rejects missing required card properties", () => {
+  expectTypecheckFailure("invalid-card-properties-missing-required.ts", [
+    "Property 'value' is missing",
+  ]);
+});
+
+test("defineTopologyManifest rejects extra card property keys", () => {
+  expectTypecheckFailure("invalid-card-properties-extra-key.ts", [
+    "'unexpected' does not exist in type",
+  ]);
+});
+
+test("defineTopologyManifest rejects wrong card scalar property values", () => {
+  expectTypecheckFailure("invalid-card-properties-wrong-scalar.ts", [
+    "Type 'string' is not assignable to type 'number'",
+  ]);
+});
+
+test("defineTopologyManifest rejects wrong card enum values", () => {
+  expectTypecheckFailure("invalid-card-properties-wrong-enum.ts", [
+    'Type \'"stars"\' is not assignable to type \'"sun" | "moon"\'',
+  ]);
+});
+
+test("defineTopologyManifest rejects wrong nested card property values", () => {
+  expectTypecheckFailure("invalid-card-properties-wrong-nested.ts", [
+    "Type 'number' is not assignable to type 'string'",
+  ]);
+});
+
+test("defineTopologyManifest rejects wrong piece scalar field values", () => {
+  expectTypecheckFailure("invalid-piece-fields-wrong-scalar.ts", [
+    "Type 'string' is not assignable to type 'number'",
+  ]);
+});
+
+test("defineTopologyManifest rejects wrong piece enum field values", () => {
+  expectTypecheckFailure("invalid-piece-fields-wrong-enum.ts", [
+    'Type \'"resting"\' is not assignable to type \'"ready" | "spent"\'',
+  ]);
+});
+
+test("defineTopologyManifest rejects wrong piece card id references", () => {
+  expectTypecheckFailure("invalid-piece-fields-wrong-card-id.ts", [
+    "Type '\"missing-card\"' is not assignable to type '\"ace\"'",
+  ]);
+});
+
+test("defineTopologyManifest rejects wrong piece zone id references", () => {
+  expectTypecheckFailure("invalid-piece-fields-wrong-zone-id.ts", [
+    "Type '\"discard\"' is not assignable to type '\"draw\"'",
+  ]);
+});
+
+test("defineTopologyManifest rejects extra piece field keys", () => {
+  expectTypecheckFailure("invalid-piece-fields-extra-key.ts", [
+    "'extra' does not exist in type",
+  ]);
+});
+
+test("defineTopologyManifest rejects per-player space homes without ownerId", () => {
+  expectTypecheckFailure("invalid-piece-home-per-player-space-no-owner.ts", [
+    "Property 'ownerId' is missing",
+    '"player-grid"',
+  ]);
+});
+
+test("defineTopologyManifest rejects per-player container homes without ownerId", () => {
+  expectTypecheckFailure(
+    "invalid-piece-home-per-player-container-no-owner.ts",
+    ["Property 'ownerId' is missing", '"player-grid"'],
+  );
+});
+
+test("defineTopologyManifest rejects per-player edge homes without ownerId", () => {
+  expectTypecheckFailure("invalid-piece-home-per-player-edge-no-owner.ts", [
+    "Property 'ownerId' is missing",
+    '"player-grid"',
+  ]);
+});
+
+test("defineTopologyManifest rejects per-player vertex homes without ownerId", () => {
+  expectTypecheckFailure("invalid-piece-home-per-player-vertex-no-owner.ts", [
+    "Property 'ownerId' is missing",
+    '"player-grid"',
+  ]);
+});
+
+test("defineTopologyManifest rejects piece seeds with unknown type ids", () => {
+  expectTypecheckFailure("invalid-piece-seed-type-id.ts", [
+    "Type '\"missing-meeple\"' is not assignable to type '\"meeple\"'",
+  ]);
+});
+
+test("defineTopologyManifest rejects wrong die player id references", () => {
+  expectTypecheckFailure("invalid-die-fields-wrong-player-id.ts", [
+    `Type '"player-3"' is not assignable to type`,
+  ]);
+});
+
+test("defineTopologyManifest rejects wrong die resource id references", () => {
+  expectTypecheckFailure("invalid-die-fields-wrong-resource-id.ts", [
+    "Type '\"missing-resource\"' is not assignable to type '\"supply\"'",
+  ]);
+});
+
+test("defineTopologyManifest rejects wrong die array item values", () => {
+  expectTypecheckFailure("invalid-die-fields-wrong-array-item.ts", [
+    "Type 'string' is not assignable to type 'number'",
+  ]);
+});
+
+test("defineTopologyManifest rejects die seeds with unknown type ids", () => {
+  expectTypecheckFailure("invalid-die-seed-type-id.ts", [
+    "Type '\"missing-d6\"' is not assignable to type '\"d6\"'",
+  ]);
+});
+
+test("defineTopologyManifest rejects per-player zone homes without ownerId", () => {
+  expectTypecheckFailure("invalid-die-home-per-player-zone-no-owner.ts", [
+    "Property 'ownerId' is missing",
+    '"main-hand"',
+  ]);
+});
+
+test("defineTopologyManifest rejects invalid board container card-set references", () => {
+  expectTypecheckFailure("invalid-container-card-set-manifest.ts", [
+    "Type '\"missing-card-set\"' is not assignable to type '\"main\"'",
+  ]);
+});
+
+test("defineTopologyManifest rejects edge ids in generic board field schemas", () => {
+  expectTypecheckFailure("invalid-generic-board-edge-id.ts", [
+    "not assignable to type 'never'",
+  ]);
+});
+
+test("defineTopologyManifest rejects invalid nested generic board fields", () => {
+  expectTypecheckFailure("invalid-generic-board-nested-field.ts", [
+    "Type 'number' is not assignable to type 'string'",
+  ]);
+});
+
+test("defineTopologyManifest rejects wrong square-board space ids in board fields", () => {
+  expectTypecheckFailure("invalid-square-board-space-id.ts", [
+    "missing-space",
+    "not assignable to type",
+  ]);
+});
+
+test("defineTopologyManifest rejects wrong square-board edge ids in board fields", () => {
+  expectTypecheckFailure("invalid-square-board-edge-id.ts", [
+    "square-edge:missing",
+    "not assignable to type",
+  ]);
+});
+
+test("defineTopologyManifest rejects wrong square-board vertex ids in board fields", () => {
+  expectTypecheckFailure("invalid-square-board-vertex-id.ts", [
+    "square-vertex:9,9",
+    "not assignable to type",
+  ]);
+});
+
+test("defineTopologyManifest rejects extra square-template space field keys", () => {
+  expectTypecheckFailure("invalid-square-space-fields-extra-key.ts", [
+    "'extra' does not exist in type",
+  ]);
+});
+
+test("defineTopologyManifest rejects wrong square-template space field enums", () => {
+  expectTypecheckFailure("invalid-square-space-fields-enum.ts", [
+    'Type \'"lava"\' is not assignable to type \'"grass" | "water"\'',
+  ]);
+});
+
+test("defineTopologyManifest rejects wrong square relation space ids", () => {
+  expectTypecheckFailure("invalid-square-relation-space-id.ts", [
+    "missing-space",
+    "not assignable to type",
+  ]);
+});
+
+test("defineTopologyManifest rejects wrong square relation field scalars", () => {
+  expectTypecheckFailure("invalid-square-relation-field-scalar.ts", [
+    "Type 'string' is not assignable to type 'number'",
+  ]);
+});
+
+test("defineTopologyManifest rejects wrong square container host space ids", () => {
+  expectTypecheckFailure("invalid-square-container-host-space-id.ts", [
+    "missing-space",
+    "not assignable to type",
+  ]);
+});
+
+test("defineTopologyManifest rejects wrong square container field space ids", () => {
+  expectTypecheckFailure("invalid-square-container-field-space-id.ts", [
+    "missing-space",
+    "not assignable to type",
+  ]);
+});
+
+test("defineTopologyManifest rejects wrong hex edge ids in edge fields", () => {
+  expectTypecheckFailure("invalid-hex-edge-field-edge-id.ts", [
+    "hex-edge:missing",
+    "not assignable to type",
+  ]);
+});
+
+test("defineTopologyManifest rejects wrong hex vertex ids in vertex fields", () => {
+  expectTypecheckFailure("invalid-hex-vertex-field-vertex-id.ts", [
+    "hex-vertex:missing",
+    "not assignable to type",
+  ]);
+});
+
+test("defineTopologyManifest rejects invalid card visibility player ids", () => {
+  expectTypecheckFailure("invalid-card-visibility.ts", [
+    `Type '"player-3"' is not assignable to type`,
+  ]);
+});
+
+test("defineTopologyManifest rejects invalid piece visibility player ids", () => {
+  expectTypecheckFailure("invalid-piece-visibility.ts", [
+    `Type '"player-3"' is not assignable to type`,
+  ]);
+});
+
+test("defineTopologyManifest rejects invalid die visibility player ids", () => {
+  expectTypecheckFailure("invalid-die-visibility.ts", [
+    `Type '"player-3"' is not assignable to type`,
+  ]);
+});