@randomplay/data 0.0.1

package/dist/index.mjs

@@ -0,0 +1,223 @@
+import { parseGameData, sourceDocumentSchema, sourceRefSchema } from "@randomplay/core";
+//#region src/adapters.ts
+function createDiscoveryOnlyAdapter(descriptor) {
+	return {
+		sourceId: descriptor.id,
+		async fetch() {
+			throw new Error(`Data source ${descriptor.id} is discovery-only; implement a real fetcher after source review.`);
+		},
+		async parse() {
+			return {
+				sourceId: descriptor.id,
+				sourceVersion: "discovery-only",
+				formalDataReady: false,
+				records: [],
+				notes: ["No formal data was parsed because this adapter is a skeleton."]
+			};
+		}
+	};
+}
+//#endregion
+//#region src/ingest.ts
+function createEmptyGameData(options) {
+	return parseGameData({
+		schemaVersion: options.schemaVersion ?? "game-data-v1",
+		gameVersion: options.gameVersion,
+		dataVersion: options.dataVersion,
+		sourceVersion: options.sourceVersion,
+		generatedAt: options.generatedAt,
+		sources: [...options.sources],
+		agents: {},
+		skills: {},
+		wEngines: {},
+		driveDiscs: {},
+		enemies: {},
+		resonium: {},
+		modifiers: {},
+		rules: {},
+		aliases: {
+			fields: {},
+			enumValues: {},
+			sourceTerms: {}
+		}
+	});
+}
+function assertDiscoveryOnlyGameData(gameData) {
+	const formalRecordCounts = {
+		agents: Object.keys(gameData.agents).length,
+		skills: Object.keys(gameData.skills).length,
+		wEngines: Object.keys(gameData.wEngines).length,
+		driveDiscs: Object.keys(gameData.driveDiscs).length,
+		enemies: Object.keys(gameData.enemies).length,
+		resonium: Object.keys(gameData.resonium).length,
+		modifiers: Object.keys(gameData.modifiers).length,
+		rules: Object.keys(gameData.rules).length,
+		"aliases.fields": Object.keys(gameData.aliases.fields).length,
+		"aliases.enumValues": Object.keys(gameData.aliases.enumValues).length,
+		"aliases.sourceTerms": Object.keys(gameData.aliases.sourceTerms).length
+	};
+	const populated = Object.entries(formalRecordCounts).filter(([, count]) => count > 0);
+	if (populated.length > 0) {
+		const details = populated.map(([name, count]) => `${name}=${count}`).join(", ");
+		throw new Error(`Discovery-only GameData must not contain formal data: ${details}`);
+	}
+}
+//#endregion
+//#region src/metadata.ts
+const DATA_SOURCE_SKELETON_PARSER_VERSION = "@randomplay/data-source-skeleton-v0.1.0";
+function buildSourceDocument(descriptor, options) {
+	const candidate = {
+		id: descriptor.id,
+		kind: descriptor.kind,
+		sourceVersion: options.sourceVersion,
+		parsedAt: options.parsedAt,
+		parserVersion: options.parserVersion ?? "@randomplay/data-source-skeleton-v0.1.0"
+	};
+	if (descriptor.url !== void 0) candidate.url = descriptor.url;
+	if (options.fileName !== void 0) candidate.fileName = options.fileName;
+	if (options.gameVersion !== void 0) candidate.gameVersion = options.gameVersion;
+	if (options.fetchedAt !== void 0) candidate.fetchedAt = options.fetchedAt;
+	if (options.licenseNote !== void 0) candidate.licenseNote = options.licenseNote;
+	return sourceDocumentSchema.parse(candidate);
+}
+function buildSourceRef(descriptor, options = {}) {
+	const candidate = { sourceId: descriptor.id };
+	if (options.sourceVersion !== void 0) candidate.sourceVersion = options.sourceVersion;
+	if (options.sourceAnchor !== void 0) candidate.sourceAnchor = options.sourceAnchor;
+	if (options.dataPath !== void 0) candidate.dataPath = options.dataPath;
+	return sourceRefSchema.parse(candidate);
+}
+//#endregion
+//#region src/sources.ts
+const dataSourceDescriptors = [
+	{
+		id: "lo-user-excel",
+		kind: "excel",
+		label: "lo-user provided ZZZ data workbook",
+		fileNameHint: "data/source/excel/data.xlsx",
+		status: "readyForAdapter",
+		formalDataReady: false,
+		parserTargets: [
+			"agent skill multipliers",
+			"daze multipliers",
+			"W-Engine passives",
+			"Drive Disc set effects",
+			"agent enhancement / potential activation fields"
+		],
+		sourceVersionStrategy: "Use the retained workbook hash plus the workbook-provided version marker from 首页!A1.",
+		discoveredAssets: [
+			"data/source/excel/data.xlsx",
+			"data/source/excel/META.md",
+			"data/source/excel/workbook-audit.json"
+		],
+		fetchPolicy: {
+			mode: "manualUpload",
+			maxRequestsPerMinute: 0,
+			cacheRequired: true,
+			conditionalRequestsPreferred: false,
+			requiresUserAgent: false
+		},
+		compliance: {
+			robotsTxt: "notApplicable",
+			termsStatus: "requiresHumanReview",
+			redistribution: "cleanedDataOnly",
+			notes: [
+				"The workbook is retained in git under data/source/excel/ as a raw/source archive.",
+				"The workbook and derived audit artifacts must not be published in the @randomplay/data package.",
+				"Use workbook-audit.json for sheet/column discovery; do not infer typed modifiers from text without deterministic parser support or manual acceptance."
+			]
+		}
+	},
+	{
+		id: "mihoyo-zzz-critical-assault",
+		kind: "mihoyoWiki",
+		label: "Mihoyo ZZZ wiki Critical Assault map",
+		url: "https://baike.mihoyo.com/zzz/wiki/channel/map/13/108",
+		status: "readyForAdapter",
+		formalDataReady: false,
+		parserTargets: [
+			"Deadly Assault period list",
+			"three selectable period buffs",
+			"three boss room detail texts and challenge targets",
+			"official Chinese labels and descriptions",
+			"Mihoyo/buhflipexplode zh/en source-text anchors"
+		],
+		sourceVersionStrategy: "Use the retained snapshot id plus fetch-manifest hashes for the channel and entry_page API payloads.",
+		discoveredAssets: [
+			"data/source/raw/mihoyo/zzz-da/2026-05-05T0850Z/channel-108/periods.json",
+			"data/source/raw/mihoyo/zzz-da/2026-05-05T0850Z/parsed/period-details.json",
+			"data/source/raw/mihoyo/zzz-da/2026-05-05T0850Z/alignment/mihoyo-buhflipexplode.json",
+			"data/source/raw/mihoyo/zzz-da/2026-05-05T0850Z/fetch-manifest.json"
+		],
+		fetchPolicy: {
+			mode: "httpGet",
+			maxRequestsPerMinute: 12,
+			cacheRequired: true,
+			conditionalRequestsPreferred: true,
+			requiresUserAgent: true
+		},
+		compliance: {
+			robotsTxt: "notFound",
+			termsStatus: "requiresHumanReview",
+			redistribution: "cleanedDataOnly",
+			notes: [
+				"robots.txt returned HTTP 404 on 2026-05-05.",
+				"The target page returned HTTP 200 with cache-control max-age=300.",
+				"The rendered Nuxt page shell does not contain detail content; use public JSON API payloads and parse embedded rich-text HTML fragments.",
+				"entry_page requests must include x-rpc-wiki_app: zzz to avoid cross-namespace content_id collisions.",
+				"Do not crawl authenticated or private APIs; use public wiki responses only."
+			]
+		}
+	},
+	{
+		id: "buhflipexplode-zzz-da",
+		kind: "thirdPartySite",
+		label: "buhflipexplode Deadly Assault data",
+		url: "https://www.buhflipexplode.org/zzz/da/",
+		status: "readyForAdapter",
+		formalDataReady: false,
+		parserTargets: [
+			"deadly assault version entries",
+			"enemy HP/daze/anomaly multipliers",
+			"boss buff metadata",
+			"Deadly Assault score / HP display algorithm evidence",
+			"algorithm drift manifest"
+		],
+		sourceVersionStrategy: "Use the accepted raw snapshot id plus fetch-manifest and algorithm-manifest hashes.",
+		discoveredAssets: [
+			"data/source/raw/buhflipexplode/2026-05-05T0445Z/da/da-versions.live.json",
+			"data/source/raw/buhflipexplode/2026-05-05T0445Z/assets/zzz/enemies.live.json",
+			"data/source/raw/buhflipexplode/2026-05-05T0445Z/assets/zzz/buffs.live.json",
+			"data/source/raw/buhflipexplode/2026-05-05T0445Z/da/da.js",
+			"data/source/raw/buhflipexplode/2026-05-05T0445Z/algorithm-manifest.json"
+		],
+		fetchPolicy: {
+			mode: "httpGet",
+			maxRequestsPerMinute: 12,
+			cacheRequired: true,
+			conditionalRequestsPreferred: true,
+			requiresUserAgent: true
+		},
+		compliance: {
+			robotsTxt: "notFound",
+			termsStatus: "requiresHumanReview",
+			redistribution: "cleanedDataOnly",
+			notes: [
+				"robots.txt returned HTTP 404 on 2026-05-05.",
+				"The site describes itself as fan-created and non-commercial.",
+				"The about page links source code at https://github.com/spiritfxxxx/buhflipexplode-src.",
+				"The source repository has a GPL-3.0 LICENSE for code; do not copy GPL JS into Fairy runtime packages.",
+				"The about page says most images/data are officially sourced from in-game and public fandoms.",
+				"D-12 locks option B: retain GPL JS for audit only; runtime implementation must remain independent MIT code.",
+				"Retained JSON payloads are filtered to live versions only; non-live / beta / leaks config is excluded."
+			]
+		}
+	}
+];
+function getDataSourceDescriptor(id) {
+	const descriptor = dataSourceDescriptors.find((source) => source.id === id);
+	if (descriptor === void 0) throw new Error(`Unknown data source descriptor: ${id}`);
+	return descriptor;
+}
+//#endregion
+export { DATA_SOURCE_SKELETON_PARSER_VERSION, assertDiscoveryOnlyGameData, buildSourceDocument, buildSourceRef, createDiscoveryOnlyAdapter, createEmptyGameData, dataSourceDescriptors, getDataSourceDescriptor };

package/dist/source-manifest-pBseE3aE.d.mts

@@ -0,0 +1,41 @@
+import { GameData } from "@randomplay/core";
+
+//#region src/types/cleaned-data.d.ts
+type CleanedDataKind = "gameData" | "gameLabelI18n" | "sourceManifest";
+interface CleanedDataArtifact<TData = unknown> {
+  kind: CleanedDataKind;
+  schemaVersion: string;
+  dataVersion: string;
+  generatedAt: string;
+  sourceManifestPath: string;
+  data: TData;
+}
+type CleanedGameDataArtifact = CleanedDataArtifact<GameData>;
+//#endregion
+//#region src/types/source-manifest.d.ts
+interface DistributionPolicy {
+  rawSourceArchive: "versioned-in-git-not-packaged";
+  publishedArtifacts: "cleaned-json-and-types-only";
+}
+interface SourceManifestEntry {
+  id: string;
+  kind: "excel" | "referenceGuide" | "rawHttpSnapshot";
+  path: string;
+  sha256: string;
+  bytes: number;
+  receivedAt?: string;
+  fetchedAt?: string;
+  providedBy?: string;
+  attachmentId?: string;
+  metadataPath?: string;
+  distribution: "raw-retained-not-packaged" | "reference-retained-not-packaged" | "cleaned-publishable";
+  usage: string;
+}
+interface SourceManifest {
+  schemaVersion: "source-manifest-v1";
+  generatedAt: string;
+  distributionPolicy: DistributionPolicy;
+  sources: SourceManifestEntry[];
+}
+//#endregion
+export { CleanedDataKind as a, CleanedDataArtifact as i, SourceManifest as n, CleanedGameDataArtifact as o, SourceManifestEntry as r, DistributionPolicy as t };

package/dist/types.d.mts

@@ -0,0 +1,2 @@
+import { a as CleanedDataKind, i as CleanedDataArtifact, n as SourceManifest, o as CleanedGameDataArtifact, r as SourceManifestEntry, t as DistributionPolicy } from "./source-manifest-pBseE3aE.mjs";
+export { CleanedDataArtifact, CleanedDataKind, CleanedGameDataArtifact, DistributionPolicy, SourceManifest, SourceManifestEntry };

package/dist/types.mjs

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@randomplay/data",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LoTwT/fairy.git",
+    "directory": "packages/data"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./types": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/types.mjs"
+    },
+    "./cleaned/*": "./cleaned/*"
+  },
+  "files": [
+    "dist",
+    "cleaned",
+    "README.md",
+    "package.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@randomplay/core": "0.0.1"
+  },
+  "devDependencies": {
+    "cheerio": "^1.2.0",
+    "tsx": "^4.21.0",
+    "xlsx": "^0.18.5"
+  },
+  "scripts": {
+    "audit:excel": "node scripts/excel-source.mjs audit --generated-at 2026-05-05T17:40:00+08:00",
+    "audit:golden-v1": "tsx scripts/golden-v1-replay.ts audit --generated-at 2026-05-05T18:20:00+08:00",
+    "build": "tsdown src/index.ts src/types.ts --format esm --dts --clean --out-dir dist",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "fetch:buhflipexplode-da": "node scripts/buhflipexplode-da-source.mjs fetch",
+    "fetch:mihoyo-da": "node scripts/mihoyo-da-source.mjs fetch",
+    "sync-cleaned": "node scripts/sync-cleaned.mjs",
+    "test": "vitest run",
+    "verify:buhflipexplode-da": "node scripts/buhflipexplode-da-source.mjs verify --snapshot 2026-05-05T0445Z",
+    "verify:excel": "node scripts/excel-source.mjs verify",
+    "verify:golden-v1": "tsx scripts/golden-v1-replay.ts verify",
+    "verify:mihoyo-da": "node scripts/mihoyo-da-source.mjs verify --snapshot 2026-05-05T0850Z"
+  }
+}