@roster-lock/shared 0.1.0

package/tests/engine/assets.spec.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect } from "vitest";
+import { cloneJSON } from "@roster-lock/utils";
+import { RosterLockV1Config } from "@roster-lock/types";
+
+import { ROSTERLOCK_V1_CASTER_JSONSCHEMA } from "../../src/match-lock-file/match-config/version-1/lock/index.js";
+import { EMPTY_ROSTER_LOCK } from "../../src/match-lock-file/match-config/version-1/usage/empty-configs.js";
+import { getMatchingAssetsForFile } from "../../src/match-lock-file/match-config/version-1/usage/files-and-assets/getMatchingAsset.js";
+import { PieceDefinition } from "../../src/match-lock-file/match-config/version-1/usage/files-and-assets/types.js";
+
+function buildLockWithAssetPiece(): RosterLockV1Config {
+  const lock = cloneJSON(EMPTY_ROSTER_LOCK);
+  lock.engine.pieceDefinitions["character"] = {
+    selectionStrategy: "mandatory",
+    requires: [],
+    pathVariables: ["skin"],
+    assets: [{ name: "sprite", classification: "media", count: 1, glob: ["<skin>/*.png"] }],
+  };
+  lock.rosters["character"] = [];
+  return lock;
+}
+
+describe("engine piece assets validation", () => {
+  it("accepts a piece whose asset names are unique and globs use declared path variables", () => {
+    const lock = buildLockWithAssetPiece();
+    expect(() => ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(lock)).not.toThrow();
+  });
+
+  it("rejects a piece with a duplicate asset name", () => {
+    const lock = buildLockWithAssetPiece();
+    lock.engine.pieceDefinitions["character"].assets.push(
+      { name: "sprite", classification: "media", count: 1, glob: ["other/*.png"] }
+    );
+
+    const result = ROSTERLOCK_V1_CASTER_JSONSCHEMA.safeCast(lock);
+    expect(result.valid).toBe(false);
+    if(result.valid) return;
+    expect(result.error.some((e) => /duplicate name/i.test(e.message ?? ""))).toBe(true);
+  });
+
+  it("rejects an asset glob referencing a path variable the piece type doesn't declare", () => {
+    const lock = buildLockWithAssetPiece();
+    lock.engine.pieceDefinitions["character"].assets[0].glob = ["<region>/*.png"];
+
+    const result = ROSTERLOCK_V1_CASTER_JSONSCHEMA.safeCast(lock);
+    expect(result.valid).toBe(false);
+    if(result.valid) return;
+    expect(result.error.some((e) => /undefined path variable/i.test(e.message ?? ""))).toBe(true);
+  });
+});
+
+function buildPieceDefinition(
+  pathVariables: PieceDefinition["pathVariables"],
+  assets: PieceDefinition["assets"],
+): PieceDefinition {
+  return { selectionStrategy: "mandatory", requires: [], pathVariables, assets };
+}
+
+describe("getMatchingAssetsForFile path variables and globs", () => {
+  it("matches a glob once its path variable is substituted with the roster's value", () => {
+    const piece = buildPieceDefinition(["skin"], [
+      { name: "sprite", classification: "media", count: 1, glob: ["<skin>/*.png"] },
+    ]);
+    const matches = getMatchingAssetsForFile(piece, { skin: "blue" }, "blue/idle.png");
+    expect(matches.map((a) => a.name)).toEqual(["sprite"]);
+  });
+
+  it("does not match when the file's path segment differs from the path variable's value", () => {
+    const piece = buildPieceDefinition(["skin"], [
+      { name: "sprite", classification: "media", count: 1, glob: ["<skin>/*.png"] },
+    ]);
+    expect(getMatchingAssetsForFile(piece, { skin: "blue" }, "red/idle.png")).toEqual([]);
+  });
+
+  it("matches a path variable used inside a filename, not just a directory segment", () => {
+    // Ikemen-Go style character defs, e.g. "<character>.def"
+    const piece = buildPieceDefinition(["character"], [
+      { name: "def-file", classification: "logic", count: 1, glob: ["<character>.def"] },
+    ]);
+    expect(getMatchingAssetsForFile(piece, { character: "kfm" }, "kfm.def").map((a) => a.name))
+      .toEqual(["def-file"]);
+    expect(getMatchingAssetsForFile(piece, { character: "kfm" }, "ryu.def")).toEqual([]);
+  });
+
+  it("resolves multiple path variables combined with a globstar across nested directories", () => {
+    const piece = buildPieceDefinition(["character", "skin"], [
+      { name: "sprite", classification: "media", count: 1, glob: ["<character>/<skin>/**/*.png"] },
+    ]);
+    const pathVariables = { character: "kfm", skin: "default" };
+    expect(getMatchingAssetsForFile(piece, pathVariables, "kfm/default/stance/1.png").length).toBe(1);
+    expect(getMatchingAssetsForFile(piece, pathVariables, "kfm/other/stance/1.png")).toEqual([]);
+    expect(getMatchingAssetsForFile(piece, pathVariables, "other/default/stance/1.png")).toEqual([]);
+  });
+
+  it("matches an asset if any of its globs match, mixing a literal glob with a path-variable glob", () => {
+    const piece = buildPieceDefinition(["skin"], [
+      { name: "sprite", classification: "media", count: 1, glob: ["portrait.png", "<skin>/*.png"] },
+    ]);
+    expect(getMatchingAssetsForFile(piece, { skin: "blue" }, "portrait.png").map((a) => a.name))
+      .toEqual(["sprite"]);
+    expect(getMatchingAssetsForFile(piece, { skin: "blue" }, "blue/idle.png").map((a) => a.name))
+      .toEqual(["sprite"]);
+    expect(getMatchingAssetsForFile(piece, { skin: "blue" }, "red/idle.png")).toEqual([]);
+  });
+
+  it("matches via exact equality when the glob has no wildcard characters", () => {
+    const piece = buildPieceDefinition([], [
+      { name: "portrait", classification: "media", count: 1, glob: ["assets/portrait.png"] },
+    ]);
+    expect(getMatchingAssetsForFile(piece, {}, "assets/portrait.png").map((a) => a.name))
+      .toEqual(["portrait"]);
+  });
+
+  it("allows path variable values containing spaces", () => {
+    const piece = buildPieceDefinition(["skin"], [
+      { name: "sprite", classification: "media", count: 1, glob: ["<skin>/*.png"] },
+    ]);
+    expect(getMatchingAssetsForFile(piece, { skin: "light blue" }, "light blue/idle.png").map((a) => a.name))
+      .toEqual(["sprite"]);
+  });
+
+  it("returns every asset whose glob matches, when globs overlap", () => {
+    const piece = buildPieceDefinition(["skin"], [
+      { name: "any-png", classification: "media", count: 1, glob: ["<skin>/*.png"] },
+      { name: "idle-png", classification: "media", count: 1, glob: ["<skin>/idle.png"] },
+    ]);
+    const matches = getMatchingAssetsForFile(piece, { skin: "blue" }, "blue/idle.png");
+    expect(matches.map((a) => a.name).sort()).toEqual(["any-png", "idle-png"]);
+  });
+
+  it("throws instead of matching when a path variable value contains disallowed characters", () => {
+    // Guards against path variable values being used to smuggle glob/traversal syntax into the pattern
+    const piece = buildPieceDefinition(["skin"], [
+      { name: "sprite", classification: "media", count: 1, glob: ["<skin>/*.png"] },
+    ]);
+    expect(() => getMatchingAssetsForFile(piece, { skin: "../etc" }, "../etc/idle.png"))
+      .toThrow(/invalid characters/i);
+    expect(() => getMatchingAssetsForFile(piece, { skin: "*" }, "*/idle.png"))
+      .toThrow(/invalid characters/i);
+  });
+
+  it("throws when a path variable value is empty", () => {
+    const piece = buildPieceDefinition(["skin"], [
+      { name: "sprite", classification: "media", count: 1, glob: ["<skin>/*.png"] },
+    ]);
+    expect(() => getMatchingAssetsForFile(piece, { skin: "" }, "idle.png")).toThrow(/too short/i);
+  });
+});

package/tests/engine/official-selections.spec.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from "vitest";
+import { cloneJSON } from "@roster-lock/utils";
+import { RosterLockV1Config } from "@roster-lock/types";
+
+import { ROSTERLOCK_V1_CASTER_JSONSCHEMA } from "../../src/match-lock-file/match-config/version-1/lock/index.js";
+import { EMPTY_ROSTER_LOCK } from "../../src/match-lock-file/match-config/version-1/usage/empty-configs.js";
+
+function buildLock(): RosterLockV1Config {
+  return cloneJSON(EMPTY_ROSTER_LOCK);
+}
+
+describe("engine officialSelections validation", () => {
+  it("is optional - a lock with no officialSelections is still valid", () => {
+    const lock = buildLock();
+    expect(() => ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(lock)).not.toThrow();
+  });
+
+  it("accepts a list of tagged, unique, well-formed hashes", () => {
+    const lock = buildLock();
+    lock.engine.officialSelections = [
+      { tag: "3v3-tag-team", hash: "a".repeat(64) },
+      { tag: "1v1", hash: "b".repeat(64) },
+    ];
+    expect(() => ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(lock)).not.toThrow();
+  });
+
+  it("rejects a hash that isn't a 64-char hex string", () => {
+    const lock = buildLock();
+    lock.engine.officialSelections = [{ tag: "1v1", hash: "not-a-hash" }];
+
+    const result = ROSTERLOCK_V1_CASTER_JSONSCHEMA.safeCast(lock);
+    expect(result.valid).toBe(false);
+    if(result.valid) return;
+    expect(result.error.some((e) => /not a valid SHA-256/i.test(e.message ?? ""))).toBe(true);
+  });
+
+  it("rejects two entries sharing the same hash, even under different tags", () => {
+    const lock = buildLock();
+    const hash = "a".repeat(64);
+    lock.engine.officialSelections = [
+      { tag: "3v3-tag-team", hash },
+      { tag: "3v3-tag-team-v2", hash },
+    ];
+
+    const result = ROSTERLOCK_V1_CASTER_JSONSCHEMA.safeCast(lock);
+    expect(result.valid).toBe(false);
+    if(result.valid) return;
+    expect(result.error.some((e) => /duplicate official selection hash/i.test(e.message ?? ""))).toBe(true);
+  });
+
+  it("allows two entries sharing the same tag with different hashes (a revision under the same UI screen)", () => {
+    const lock = buildLock();
+    lock.engine.officialSelections = [
+      { tag: "3v3-tag-team", hash: "a".repeat(64) },
+      { tag: "3v3-tag-team", hash: "b".repeat(64) },
+    ];
+    expect(() => ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(lock)).not.toThrow();
+  });
+
+  it("rejects an entry missing a tag", () => {
+    const lock = buildLock();
+    lock.engine.officialSelections = [{ hash: "a".repeat(64) } as any];
+
+    const result = ROSTERLOCK_V1_CASTER_JSONSCHEMA.safeCast(lock);
+    expect(result.valid).toBe(false);
+  });
+});

package/tests/engine/requirements.spec.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest";
+import { cloneJSON } from "@roster-lock/utils";
+import { RosterLockV1Config } from "@roster-lock/types";
+
+import { ROSTERLOCK_V1_CASTER_JSONSCHEMA } from "../../src/match-lock-file/match-config/version-1/lock/index.js";
+import { EMPTY_ROSTER_LOCK } from "../../src/match-lock-file/match-config/version-1/usage/empty-configs.js";
+
+function buildLockWithRequiresPiece(): RosterLockV1Config {
+  const lock = cloneJSON(EMPTY_ROSTER_LOCK);
+  lock.engine.pieceDefinitions["character"] = {
+    selectionStrategy: "mandatory",
+    requires: ["hat"],
+    pathVariables: [],
+    assets: [],
+  };
+  lock.engine.pieceDefinitions["hat"] = {
+    selectionStrategy: "on demand",
+    requires: [],
+    pathVariables: [],
+    assets: [],
+  };
+  lock.rosters["character"] = [];
+  lock.rosters["hat"] = [];
+  return lock;
+}
+
+describe("engine piece requirements validation", () => {
+  it("accepts a piece that requires an on-demand piece with no cycle", () => {
+    const lock = buildLockWithRequiresPiece();
+    expect(() => ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(lock)).not.toThrow();
+  });
+
+  it("rejects piece types whose requirements form a cycle", () => {
+    const lock = buildLockWithRequiresPiece();
+    lock.engine.pieceDefinitions["character"].selectionStrategy = "on demand";
+    lock.engine.pieceDefinitions["hat"].requires = ["character"];
+
+    const result = ROSTERLOCK_V1_CASTER_JSONSCHEMA.safeCast(lock);
+    expect(result.valid).toBe(false);
+    if(result.valid) return;
+    expect(result.error.some((e) => /form a cycle/i.test(e.message ?? ""))).toBe(true);
+  });
+});

package/tests/piece-info/cast.spec.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from "vitest";
+
+import { ROSTERLOCK_V1_PIECEINFO_CASTER_JSONSCHEMA } from "../../src/match-lock-file/match-config/version-1/piece-info/index.js";
+
+import pieceInfoJson from "./rosterlock.piece-info.json";
+
+describe("ROSTERLOCK_V1_PIECEINFO_CASTER_JSONSCHEMA", () => {
+  it("casts a valid piece-info JSON file", () => {
+    const result = ROSTERLOCK_V1_PIECEINFO_CASTER_JSONSCHEMA.safeCast(pieceInfoJson);
+    expect(result.valid).toBe(true);
+    if (!result.valid) return;
+    expect(result.value.configIdentity.namespace).toBe("roster-lock");
+    expect(result.value.configIdentity.purpose).toBe("piece-info");
+    expect(result.value.configIdentity.version).toBe(1);
+    expect(result.value.humanInfo.name).toBe("Blue");
+    expect(result.value.humanInfo.author).toBe("match-lock");
+    expect(result.value.downloadSources).toEqual(["http://localhost:7342/pieces/character/blue.tar"]);
+    expect(result.value.pathVariables).toEqual({});
+  });
+});

package/tests/piece-info/rosterlock.piece-info.json

@@ -0,0 +1,15 @@
+{
+  "configIdentity": {
+    "namespace": "roster-lock",
+    "purpose": "piece-info",
+    "version": 1
+  },
+  "humanInfo": {
+    "name": "Blue",
+    "author": "match-lock",
+    "url": "http://localhost:7342/pieces/character/blue"
+  },
+  "downloadSources": ["http://localhost:7342/pieces/character/blue.tar"],
+  "pathVariables": {}
+}
+

package/tests/piece-meta/cast.spec.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from "vitest";
+import { cloneJSON } from "@roster-lock/utils";
+import { RosterLockV1Config } from "@roster-lock/types";
+
+import { ROSTERLOCK_V1_CASTER_JSONSCHEMA } from "../../src/match-lock-file/match-config/version-1/lock/index.js";
+import { EMPTY_ROSTER_LOCK } from "../../src/match-lock-file/match-config/version-1/usage/empty-configs.js";
+
+function buildLockWithPieceMeta(): RosterLockV1Config {
+  const lock = cloneJSON(EMPTY_ROSTER_LOCK);
+  lock.engine.pieceDefinitions["character"] = {
+    selectionStrategy: "mandatory",
+    requires: [],
+    pathVariables: [],
+    assets: [],
+  };
+  lock.rosters["character"] = [{
+    id: "@author/blue",
+    version: { logic: "a".repeat(64), media: "b".repeat(64), docs: "c".repeat(64) },
+    humanInfo: { name: "Blue", author: "author", url: "https://example.com/blue" },
+    downloadSources: ["https://example.com/blue.tar"],
+    pathVariables: {},
+    requiredPieces: {},
+  }];
+  lock.selection.piece["character"] = {
+    type: "unselectable",
+  };
+  lock.pieceMeta["character"] = {
+    schema: { power: "number" },
+    defaultMeta: { power: 1 },
+    values: { "@author/blue": { power: 5 } },
+  };
+  return lock;
+}
+
+describe("piece meta validation", () => {
+  it("accepts default meta and per-piece meta that match the declared schema", () => {
+    const lock = buildLockWithPieceMeta();
+    expect(() => ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(lock)).not.toThrow();
+  });
+
+  it("rejects default meta missing a required schema key", () => {
+    const lock = buildLockWithPieceMeta();
+    lock.pieceMeta["character"].defaultMeta = {};
+
+    const result = ROSTERLOCK_V1_CASTER_JSONSCHEMA.safeCast(lock);
+    expect(result.valid).toBe(false);
+    if(result.valid) return;
+    expect(result.error.some((e) => /must have all required keys/i.test(e.message ?? ""))).toBe(true);
+  });
+
+  it("rejects per-piece meta for a piece that isn't in the roster", () => {
+    const lock = buildLockWithPieceMeta();
+    lock.pieceMeta["character"].values = { "@author/missing": { power: 2 } };
+
+    const result = ROSTERLOCK_V1_CASTER_JSONSCHEMA.safeCast(lock);
+    expect(result.valid).toBe(false);
+    if(result.valid) return;
+    expect(result.error.some((e) => /not in the roster/i.test(e.message ?? ""))).toBe(true);
+  });
+});

package/tests/rosters/path-variables.spec.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { cloneJSON } from "@roster-lock/utils";
+import { RosterLockV1Config } from "@roster-lock/types";
+
+import { ROSTERLOCK_V1_CASTER_JSONSCHEMA } from "../../src/match-lock-file/match-config/version-1/lock/index.js";
+import { EMPTY_ROSTER_LOCK } from "../../src/match-lock-file/match-config/version-1/usage/empty-configs.js";
+
+function buildLockWithPathVariablePiece(): RosterLockV1Config {
+  const lock = cloneJSON(EMPTY_ROSTER_LOCK);
+  lock.engine.pieceDefinitions["character"] = {
+    selectionStrategy: "mandatory",
+    requires: [],
+    pathVariables: ["skin"],
+    assets: [{ name: "sprite", classification: "media", count: 1, glob: ["{skin}/*.png"] }],
+  };
+  lock.rosters["character"] = [{
+    id: "@author/blue",
+    version: { logic: "a".repeat(64), media: "b".repeat(64), docs: "c".repeat(64) },
+    humanInfo: { name: "Blue", author: "author", url: "https://example.com/blue" },
+    downloadSources: ["https://example.com/blue.tar"],
+    pathVariables: { skin: "blue" },
+    requiredPieces: {},
+  }];
+  return lock;
+}
+
+describe("roster piece pathVariables validation", () => {
+  it("accepts a piece whose pathVariables match the piece type's declared names", () => {
+    const lock = buildLockWithPathVariablePiece();
+    expect(() => ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(lock)).not.toThrow();
+  });
+
+  it("rejects a piece missing a required path variable", () => {
+    const lock = buildLockWithPathVariablePiece();
+    lock.rosters["character"][0].pathVariables = {};
+
+    const result = ROSTERLOCK_V1_CASTER_JSONSCHEMA.safeCast(lock);
+    expect(result.valid).toBe(false);
+    if(result.valid) return;
+    expect(result.error.some((e) => /missing value for path variable/i.test(e.message ?? ""))).toBe(true);
+  });
+
+  it("rejects a piece with a path variable name the piece type doesn't declare", () => {
+    const lock = buildLockWithPathVariablePiece();
+    lock.rosters["character"][0].pathVariables = { skin: "blue", region: "eu" };
+
+    const result = ROSTERLOCK_V1_CASTER_JSONSCHEMA.safeCast(lock);
+    expect(result.valid).toBe(false);
+    if(result.valid) return;
+    expect(result.error.some((e) => /does not have path variable/i.test(e.message ?? ""))).toBe(true);
+  });
+});

package/tests/selection/cast-result.spec.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from "vitest";
+
+import { castSharedResult, castPersonalResult } from "../../src/match-lock-file/match-config/version-1/usage/validate-select/selection-types/normal/cast-result.js";
+
+function validPiece() {
+  return {
+    id: "@author/blue",
+    required: {
+      character: {
+        mandatory: [
+          {
+            id: "@author/red",
+            required: {},
+          },
+        ],
+        selectable: [],
+      },
+    },
+  };
+}
+
+describe("castSharedResult", () => {
+  it("accepts a SelectedPiece with required keyed by piece type", () => {
+    const value = [validPiece()];
+    expect(() => castSharedResult(value)).not.toThrow();
+    expect(castSharedResult(value)).toEqual(value);
+  });
+
+  it("accepts a piece with no required entries", () => {
+    const value = [{ id: "@author/blue", required: {} }];
+    expect(() => castSharedResult(value)).not.toThrow();
+  });
+
+  it("rejects required.mandatory/selectable placed directly on the piece instead of under a piece-type key", () => {
+    const value = [{
+      id: "@author/blue",
+      required: { mandatory: [], selectable: [] },
+    }];
+    expect(() => castSharedResult(value)).toThrow();
+  });
+
+  it("rejects a piece missing an id", () => {
+    const value = [{ required: {} }];
+    expect(() => castSharedResult(value)).toThrow();
+  });
+
+  it("rejects a piece-type entry missing mandatory/selectable", () => {
+    const value = [{
+      id: "@author/blue",
+      required: { character: { mandatory: [] } },
+    }];
+    expect(() => castSharedResult(value)).toThrow();
+  });
+
+  it("rejects unknown properties on a piece", () => {
+    const value = [{ id: "@author/blue", required: {}, extra: true }];
+    expect(() => castSharedResult(value)).toThrow();
+  });
+});
+
+describe("castPersonalResult", () => {
+  it("accepts a map of user id to selected pieces", () => {
+    const value = { user1: [validPiece()] };
+    expect(() => castPersonalResult(value)).not.toThrow();
+    expect(castPersonalResult(value)).toEqual(value);
+  });
+
+  it("rejects a user's selection containing an invalid piece", () => {
+    const value = { user1: [{ id: "@author/blue", required: { mandatory: [], selectable: [] } }] };
+    expect(() => castPersonalResult(value)).toThrow();
+  });
+});

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "types": ["node"],
+    "lib": ["es2022"],
+    "sourceMap": true,
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "removeComments": true,
+    "noImplicitAny": true
+  },
+  "files": ["src/index.ts"],
+  "include": ["./typings", "./types", "**/*.test.ts"],
+  "exclude": ["node_modules", "**/*.spec.ts"]
+}