@vgai/engine 0.5.0 → 0.5.2

package/dist/data/data-check-core.d.ts

@@ -1,110 +0,0 @@
-/**
- * Data-asset integrity core — the PURE half of W5 enforcement
- * (docs/DATA-TOOLS-DESIGN.md §6.6 "dangling `file#key` ref" / §6.7 build-path
- * validation). No filesystem, no vite, no zod: plain parsed-JSON in, findings
- * out, so BOTH consumers — `vgai doctor`'s data checks
- * (`packages/editor/src/doctor/data-checks.ts`) and the build-time plugin
- * (`./vite-plugin-data.ts`) — share one definition of "what is a ref" and
- * "what counts as dangling" and can never drift apart.
- *
- * What is a ref (§2.2): a cross-asset reference is a plain string
- * `"file#key"` — optionally with a field path, `"tuning#economy.slotGrowth"`
- * (file `#` key `.` field-path). There is no branded-ref Zod helper shipped
- * yet (W1 deferred it), so ref DETECTION is by convention, tuned against
- * false positives: a string is treated as a ref IFF it matches
- * {@link DATA_REF_PATTERN} AND its `file` prefix names a data asset that
- * actually exists in the project (`src/data/<file>.data.json`). Strings that
- * merely contain `#` — hex colors (`"#ff0000"`, no prefix), URLs with
- * fragments (`/` and `:` never match), musical pitches (`"C#4"` only matches
- * if a `C.data.json` exists) — never fire. The flip side is deliberate and
- * honest: a ref whose file prefix names a NONEXISTENT asset is
- * indistinguishable from an arbitrary string and is NOT flagged ("error if
- * refs exist yet" — the check only bites once the target file exists).
- *
- * `dataRef` (`./data-ref.ts`) now exists, closing that flip side for anyone
- * who adopts it: a `dataRef(target)` field's EMITTED schema carries
- * `"x-vgai-ref": target` — a declared intent, independent of whether the
- * target file currently exists. {@link collectDeclaredRefFields} /
- * {@link findMissingRefTargets} below walk that (zod-free — plain emitted
- * JSON Schema in, findings out, same purity contract as the rest of this
- * module) to catch the §9.4 hole for DECLARED refs: renaming/deleting a
- * target file used to silently un-check every ref into it; now a declared
- * ref's target is checked by NAME, not by "does a string happen to look
- * like one right now." Undeclared conventional-string refs keep the
- * calibrated behavior above, unchanged.
- */
-/**
- * `file#key(.field)*` — prefix must look like an asset stem (letters,
- * digits, `_`, `-`), key path is dot-separated segments of the same alphabet.
- */
-export declare const DATA_REF_PATTERN: RegExp;
-/** One ref-shaped string found while walking a data file's parsed JSON. */
-export interface DataRefOccurrence {
-    /** Asset stem of the data file the ref string was found IN (e.g. `"tuning"`). */
-    readonly inAsset: string;
-    /** JSON path of the string inside that file (e.g. `"rows.goblin.drops[2]"`). */
-    readonly atPath: string;
-    /** The full ref string, verbatim (e.g. `"enemies#goblin"`). */
-    readonly ref: string;
-    /** Parsed target asset stem (`"enemies"`). */
-    readonly targetAsset: string;
-    /** Parsed dot-separated key path into the target (`["goblin"]`). */
-    readonly targetKeyPath: readonly string[];
-}
-/** One dangling ref: the target FILE exists but the key path does not resolve in it. */
-export interface DanglingRefFinding extends DataRefOccurrence {
-    /** The first key-path segment that failed to resolve, for the teaching message. */
-    readonly missingSegment: string;
-}
-/**
- * Walk one data file's parsed JSON and collect every ref-shaped string whose
- * file prefix names an asset in `assetNames`. The top-level `"$schema"`
- * interchange line is skipped (it is wiring, not data — same special-casing
- * as `parseDataJson`'s strip).
- */
-export declare function collectDataRefs(inAsset: string, json: unknown, assetNames: ReadonlySet<string>): DataRefOccurrence[];
-/**
- * Find every dangling `file#key(.field)*` ref across a project's data assets.
- *
- * @param files parsed `.data.json` payloads keyed by asset stem (the
- *   filename minus `.data.json` — the same name the ref's prefix uses, §2.2).
- *   Pass only files that parsed as JSON; unparseable files are already an
- *   error in their own right and can't be resolved against anyway.
- * @returns one finding per ref whose target FILE is in `files` but whose key
- *   path does not fully resolve inside it (a table row that doesn't exist, a
- *   singleton field path that walks off the object).
- */
-export declare function findDanglingDataRefs(files: ReadonlyMap<string, unknown>): DanglingRefFinding[];
-/** One `dataRef` field declared in an emitted JSON Schema. */
-export interface DeclaredRefField {
-    /** Dot-separated field path within the schema (e.g. `"drop"`, `"loot.dropTable"`). A table's row-schema fields are reported WITHOUT a row-key segment — the declaration applies to every row alike. */
-    readonly fieldPath: string;
-    /** The asset stem the field's `dataRef(...)` call named. */
-    readonly targetStem: string;
-}
-/** One declared ref whose target stem names no asset that currently exists. */
-export interface MissingRefTargetFinding {
-    readonly fieldPath: string;
-    readonly targetStem: string;
-}
-/**
- * Walk an emitted data-asset JSON Schema (`toDataJsonSchema`'s output, or the
- * committed `.schema.json` twin — same shape either way) and collect every
- * field stamped `"x-vgai-ref": <target>` by `dataRef` (`./data-ref.ts`).
- * Handles both blessed shapes (spec §2.1): a singleton's `properties`, and a
- * table's `additionalProperties` row schema — walked with the SAME field
- * path (a table's declared ref applies uniformly to every row, there is no
- * per-row schema variation). Nested `properties` inside a ref-declaring
- * field are not walked further (a ref leaf has no children); nested groups
- * elsewhere recurse via their own `properties`.
- */
-export declare function collectDeclaredRefFields(schema: unknown): DeclaredRefField[];
-/**
- * Every declared ref field whose target stem names no asset in
- * `assetNames` — the §9.4 fix: a `dataRef('items')` field stays flagged if
- * `items.data.json` is renamed or deleted, independent of whether any
- * CURRENT value happens to look like an `items#...` string (the gap the
- * conventional-string calibration above deliberately leaves open).
- */
-export declare function findMissingRefTargets(declared: readonly DeclaredRefField[], assetNames: ReadonlySet<string>): MissingRefTargetFinding[];
-//# sourceMappingURL=data-check-core.d.ts.map

package/dist/data/data-check-core.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"data-check-core.d.ts","sourceRoot":"","sources":["../../src/data/data-check-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH;;;GAGG;AACH,eAAO,MAAM,gBAAgB,QAA6D,CAAC;AAE3F,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAED,wFAAwF;AACxF,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC3D,mFAAmF;IACnF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAMD;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,OAAO,EACb,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,GAC9B,iBAAiB,EAAE,CAOrB;AA6CD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,kBAAkB,EAAE,CAU9F;AAYD,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,uMAAuM;IACvM,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,+EAA+E;AAC/E,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAeD;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,OAAO,GAAG,gBAAgB,EAAE,CAI5E;AAwBD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,GAC9B,uBAAuB,EAAE,CAI3B"}

package/dist/data/data-check-core.js

@@ -1,178 +0,0 @@
-/**
- * Data-asset integrity core — the PURE half of W5 enforcement
- * (docs/DATA-TOOLS-DESIGN.md §6.6 "dangling `file#key` ref" / §6.7 build-path
- * validation). No filesystem, no vite, no zod: plain parsed-JSON in, findings
- * out, so BOTH consumers — `vgai doctor`'s data checks
- * (`packages/editor/src/doctor/data-checks.ts`) and the build-time plugin
- * (`./vite-plugin-data.ts`) — share one definition of "what is a ref" and
- * "what counts as dangling" and can never drift apart.
- *
- * What is a ref (§2.2): a cross-asset reference is a plain string
- * `"file#key"` — optionally with a field path, `"tuning#economy.slotGrowth"`
- * (file `#` key `.` field-path). There is no branded-ref Zod helper shipped
- * yet (W1 deferred it), so ref DETECTION is by convention, tuned against
- * false positives: a string is treated as a ref IFF it matches
- * {@link DATA_REF_PATTERN} AND its `file` prefix names a data asset that
- * actually exists in the project (`src/data/<file>.data.json`). Strings that
- * merely contain `#` — hex colors (`"#ff0000"`, no prefix), URLs with
- * fragments (`/` and `:` never match), musical pitches (`"C#4"` only matches
- * if a `C.data.json` exists) — never fire. The flip side is deliberate and
- * honest: a ref whose file prefix names a NONEXISTENT asset is
- * indistinguishable from an arbitrary string and is NOT flagged ("error if
- * refs exist yet" — the check only bites once the target file exists).
- *
- * `dataRef` (`./data-ref.ts`) now exists, closing that flip side for anyone
- * who adopts it: a `dataRef(target)` field's EMITTED schema carries
- * `"x-vgai-ref": target` — a declared intent, independent of whether the
- * target file currently exists. {@link collectDeclaredRefFields} /
- * {@link findMissingRefTargets} below walk that (zod-free — plain emitted
- * JSON Schema in, findings out, same purity contract as the rest of this
- * module) to catch the §9.4 hole for DECLARED refs: renaming/deleting a
- * target file used to silently un-check every ref into it; now a declared
- * ref's target is checked by NAME, not by "does a string happen to look
- * like one right now." Undeclared conventional-string refs keep the
- * calibrated behavior above, unchanged.
- */
-/**
- * `file#key(.field)*` — prefix must look like an asset stem (letters,
- * digits, `_`, `-`), key path is dot-separated segments of the same alphabet.
- */
-export const DATA_REF_PATTERN = /^([A-Za-z0-9_-]+)#([A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*)$/;
-function isPlainObject(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-/**
- * Walk one data file's parsed JSON and collect every ref-shaped string whose
- * file prefix names an asset in `assetNames`. The top-level `"$schema"`
- * interchange line is skipped (it is wiring, not data — same special-casing
- * as `parseDataJson`'s strip).
- */
-export function collectDataRefs(inAsset, json, assetNames) {
-    const out = [];
-    visitForRefs(json, '', true, (node, path) => {
-        const occurrence = asRefOccurrence(inAsset, node, path, assetNames);
-        if (occurrence)
-            out.push(occurrence);
-    });
-    return out;
-}
-/** Depth-first walk over parsed JSON, calling `onString` for every string leaf with its JSON path. */
-function visitForRefs(node, path, topLevel, onString) {
-    if (typeof node === 'string') {
-        onString(node, path);
-        return;
-    }
-    if (Array.isArray(node)) {
-        node.forEach((item, i) => {
-            visitForRefs(item, `${path}[${i}]`, false, onString);
-        });
-        return;
-    }
-    if (isPlainObject(node)) {
-        for (const [key, value] of Object.entries(node)) {
-            if (topLevel && key === '$schema')
-                continue;
-            visitForRefs(value, path ? `${path}.${key}` : key, false, onString);
-        }
-    }
-}
-/** The string is a ref iff it matches the pattern AND its file prefix names a real asset. */
-function asRefOccurrence(inAsset, value, path, assetNames) {
-    const m = DATA_REF_PATTERN.exec(value);
-    if (!m || !assetNames.has(m[1]))
-        return null;
-    return {
-        inAsset,
-        atPath: path || '(root)',
-        ref: value,
-        targetAsset: m[1],
-        targetKeyPath: m[2].split('.'),
-    };
-}
-/**
- * Find every dangling `file#key(.field)*` ref across a project's data assets.
- *
- * @param files parsed `.data.json` payloads keyed by asset stem (the
- *   filename minus `.data.json` — the same name the ref's prefix uses, §2.2).
- *   Pass only files that parsed as JSON; unparseable files are already an
- *   error in their own right and can't be resolved against anyway.
- * @returns one finding per ref whose target FILE is in `files` but whose key
- *   path does not fully resolve inside it (a table row that doesn't exist, a
- *   singleton field path that walks off the object).
- */
-export function findDanglingDataRefs(files) {
-    const assetNames = new Set(files.keys());
-    const findings = [];
-    for (const [name, json] of files) {
-        for (const occurrence of collectDataRefs(name, json, assetNames)) {
-            const missing = firstUnresolvedSegment(files.get(occurrence.targetAsset), occurrence);
-            if (missing !== null)
-                findings.push({ ...occurrence, missingSegment: missing });
-        }
-    }
-    return findings;
-}
-/** The first key-path segment that fails to resolve in the target payload, or `null` if the whole path resolves. */
-function firstUnresolvedSegment(target, ref) {
-    let node = target;
-    for (const segment of ref.targetKeyPath) {
-        if (!isPlainObject(node) || !(segment in node))
-            return segment;
-        node = node[segment];
-    }
-    return null;
-}
-function asSchemaNode(value) {
-    return value && typeof value === 'object' && !Array.isArray(value)
-        ? value
-        : null;
-}
-/**
- * Walk an emitted data-asset JSON Schema (`toDataJsonSchema`'s output, or the
- * committed `.schema.json` twin — same shape either way) and collect every
- * field stamped `"x-vgai-ref": <target>` by `dataRef` (`./data-ref.ts`).
- * Handles both blessed shapes (spec §2.1): a singleton's `properties`, and a
- * table's `additionalProperties` row schema — walked with the SAME field
- * path (a table's declared ref applies uniformly to every row, there is no
- * per-row schema variation). Nested `properties` inside a ref-declaring
- * field are not walked further (a ref leaf has no children); nested groups
- * elsewhere recurse via their own `properties`.
- */
-export function collectDeclaredRefFields(schema) {
-    const out = [];
-    walkForDeclaredRefs(schema, '', out);
-    return out;
-}
-function walkForDeclaredRefs(raw, path, out) {
-    const node = asSchemaNode(raw);
-    if (!node)
-        return;
-    if (typeof node['x-vgai-ref'] === 'string') {
-        out.push({ fieldPath: path || '(root)', targetStem: node['x-vgai-ref'] });
-        return; // a ref leaf — nothing further to walk under it
-    }
-    if (isPlainObject(node.properties)) {
-        for (const [key, child] of Object.entries(node.properties)) {
-            if (key === '$schema')
-                continue;
-            walkForDeclaredRefs(child, path ? `${path}.${key}` : key, out);
-        }
-    }
-    // A table's row schema (`z.record(rowSchema)` emits an object-valued
-    // `additionalProperties`) — same field-path grammar, no row-key segment.
-    if (isPlainObject(node.additionalProperties)) {
-        walkForDeclaredRefs(node.additionalProperties, path, out);
-    }
-}
-/**
- * Every declared ref field whose target stem names no asset in
- * `assetNames` — the §9.4 fix: a `dataRef('items')` field stays flagged if
- * `items.data.json` is renamed or deleted, independent of whether any
- * CURRENT value happens to look like an `items#...` string (the gap the
- * conventional-string calibration above deliberately leaves open).
- */
-export function findMissingRefTargets(declared, assetNames) {
-    return declared
-        .filter((d) => !assetNames.has(d.targetStem))
-        .map((d) => ({ fieldPath: d.fieldPath, targetStem: d.targetStem }));
-}

package/dist/data/data-ref.d.ts

@@ -1,79 +0,0 @@
-/**
- * `file#key` refs — the resolvable half (docs/DATA-TOOLS-DESIGN.md §2.2).
- *
- * Cross-asset references (`"enemies#goblin"`, `"tuning#economy.slotGrowth"`)
- * have been DETECTED and VALIDATED since W5 (`data-check-core.ts`'s
- * `DATA_REF_PATTERN` + `findDanglingDataRefs`, enforced by both `vgai doctor`
- * and the build plugin) — but nothing could actually RESOLVE one at runtime,
- * and nothing declared a field AS a ref in its schema (detection was by
- * string-shape convention alone). This module closes both halves:
- *
- * - {@link dataRef} — a typed Zod schema for a ref FIELD. Stamps the emitted
- *   JSON Schema with a precise `pattern` (the target stem is baked into the
- *   regex, so VS Code validates the prefix for free) and a machine-readable
- *   `"x-vgai-ref": target` marker (a Zod `.meta()` that survives
- *   `toDataJsonSchema`, including inside a table's `additionalProperties` row
- *   schema — no emitter changes needed). The editor's Data panel
- *   (`json-schema-fields.ts`'s `'ref'` kind) reads that marker to render a
- *   `stem#key` PICKER instead of free text.
- * - {@link getRef} — lazy, read-time resolution. The caller names the target
- *   HANDLE explicitly (`getRef(items, goblin.drop)`), so the resolved type is
- *   the handle's own row type — no stem→handle registry, no load-order
- *   problem, no cycle hazard (nothing walks a graph; two refs resolved when
- *   you choose to resolve them isn't a cycle), and it's HMR-correct for free
- *   (it reads `target.get()` at CALL time, same doctrine as every other data
- *   read — "read every frame", never cache across frames).
- *
- * Deliberately NOT built (see docs/DATA-TOOLS-DESIGN.md §2.2 and the design
- * note this module's history carries): eager resolution inside `defineData`
- * (would change `get()`'s shipped output type and entangle HMR — an edit to
- * `enemies.data.json` would have to re-notify every OTHER asset that
- * references it), and a global `resolveRef(addressString)` (needs a runtime
- * stem→handle registry that `src/data/assets.ts` — side-effect-free,
- * config-load-time, schemas-only by its own module doc — must not become).
- */
-import { z } from 'zod';
-import type { DataHandle } from './data-asset';
-/** An asset-stem-tagged `file#key` string — `` `${Stem}#${string}` ``. */
-export type DataRef<Stem extends string = string> = `${Stem}#${string}`;
-/**
- * A Zod schema for a data-asset FIELD that references another asset by
- * `"<target>#<key>(.<field>)*"`. Use it in a `.schema.ts`:
- *
- * ```ts
- * export const EnemyRowSchema = z.object({
- *   name: z.string(),
- *   drop: dataRef('items'), // -> "items#potion"
- * });
- * ```
- *
- * The emitted JSON Schema (`toDataJsonSchema`) carries both a precise
- * `pattern` (VS Code validates the target-stem prefix for free) and
- * `"x-vgai-ref": target` (the editor's Data panel picker keys off this).
- * Detection by `data-check-core.ts`'s conventional-string calibration still
- * applies at the VALUE level (a `dataRef` field's actual string still has to
- * look like `target#key` to resolve) — this only makes the field's INTENT
- * declared in the schema, closing the §9.4 "renamed target file silently
- * un-checks its refs" hole for anything that adopts it (see
- * `collectDeclaredRefFields`/`findMissingRefTargets` in `data-check-core.ts`).
- */
-export declare function dataRef<Stem extends string>(target: Stem): z.ZodType<DataRef<Stem>>;
-/**
- * Resolve a `"target#key(.field)*"` ref against the named target HANDLE,
- * read live (`target.get()` at call time — HMR-correct, no caching across
- * frames, same doctrine as any other data read).
- *
- * `ref`'s stem prefix should name `target`'s own asset — when `target` was
- * built with a `sourcePath` (every `defineData` call populates it), a
- * mismatch throws a teaching error instead of silently walking the wrong
- * handle's data. Without a `sourcePath` (a hand-rolled `DataHandle`, or an
- * older one built before this field existed) the mismatch check is skipped —
- * resolution still proceeds against `target`, since the caller named it
- * explicitly and that's the actual contract.
- *
- * Throws a teaching error naming the ref and the first key-path segment that
- * doesn't resolve (a deleted row, a typo'd key) — never returns `undefined`
- * silently, matching `parseDataJson`'s "errors teach" doctrine (§6.5).
- */
-export declare function getRef<T>(target: DataHandle<Record<string, T>>, ref: string): T;
-//# sourceMappingURL=data-ref.d.ts.map

package/dist/data/data-ref.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"data-ref.d.ts","sourceRoot":"","sources":["../../src/data/data-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG/C,0EAA0E;AAC1E,MAAM,MAAM,OAAO,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,IAAI,GAAG,IAAI,IAAI,MAAM,EAAE,CAAC;AAOxE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,OAAO,CAAC,IAAI,SAAS,MAAM,EAAE,MAAM,EAAE,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CASnF;AAcD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAoC/E"}

package/dist/data/data-ref.js

@@ -1,130 +0,0 @@
-/**
- * `file#key` refs — the resolvable half (docs/DATA-TOOLS-DESIGN.md §2.2).
- *
- * Cross-asset references (`"enemies#goblin"`, `"tuning#economy.slotGrowth"`)
- * have been DETECTED and VALIDATED since W5 (`data-check-core.ts`'s
- * `DATA_REF_PATTERN` + `findDanglingDataRefs`, enforced by both `vgai doctor`
- * and the build plugin) — but nothing could actually RESOLVE one at runtime,
- * and nothing declared a field AS a ref in its schema (detection was by
- * string-shape convention alone). This module closes both halves:
- *
- * - {@link dataRef} — a typed Zod schema for a ref FIELD. Stamps the emitted
- *   JSON Schema with a precise `pattern` (the target stem is baked into the
- *   regex, so VS Code validates the prefix for free) and a machine-readable
- *   `"x-vgai-ref": target` marker (a Zod `.meta()` that survives
- *   `toDataJsonSchema`, including inside a table's `additionalProperties` row
- *   schema — no emitter changes needed). The editor's Data panel
- *   (`json-schema-fields.ts`'s `'ref'` kind) reads that marker to render a
- *   `stem#key` PICKER instead of free text.
- * - {@link getRef} — lazy, read-time resolution. The caller names the target
- *   HANDLE explicitly (`getRef(items, goblin.drop)`), so the resolved type is
- *   the handle's own row type — no stem→handle registry, no load-order
- *   problem, no cycle hazard (nothing walks a graph; two refs resolved when
- *   you choose to resolve them isn't a cycle), and it's HMR-correct for free
- *   (it reads `target.get()` at CALL time, same doctrine as every other data
- *   read — "read every frame", never cache across frames).
- *
- * Deliberately NOT built (see docs/DATA-TOOLS-DESIGN.md §2.2 and the design
- * note this module's history carries): eager resolution inside `defineData`
- * (would change `get()`'s shipped output type and entangle HMR — an edit to
- * `enemies.data.json` would have to re-notify every OTHER asset that
- * references it), and a global `resolveRef(addressString)` (needs a runtime
- * stem→handle registry that `src/data/assets.ts` — side-effect-free,
- * config-load-time, schemas-only by its own module doc — must not become).
- */
-import { z } from 'zod';
-import { DATA_REF_PATTERN } from './data-check-core';
-/** Prefix/key-path grammar a ref must match, parameterized by target stem (mirrors `DATA_REF_PATTERN` in `data-check-core.ts`, minus the alternation — this one is anchored to ONE target). */
-function refPattern(target) {
-    return new RegExp(`^${target}#[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*$`);
-}
-/**
- * A Zod schema for a data-asset FIELD that references another asset by
- * `"<target>#<key>(.<field>)*"`. Use it in a `.schema.ts`:
- *
- * ```ts
- * export const EnemyRowSchema = z.object({
- *   name: z.string(),
- *   drop: dataRef('items'), // -> "items#potion"
- * });
- * ```
- *
- * The emitted JSON Schema (`toDataJsonSchema`) carries both a precise
- * `pattern` (VS Code validates the target-stem prefix for free) and
- * `"x-vgai-ref": target` (the editor's Data panel picker keys off this).
- * Detection by `data-check-core.ts`'s conventional-string calibration still
- * applies at the VALUE level (a `dataRef` field's actual string still has to
- * look like `target#key` to resolve) — this only makes the field's INTENT
- * declared in the schema, closing the §9.4 "renamed target file silently
- * un-checks its refs" hole for anything that adopts it (see
- * `collectDeclaredRefFields`/`findMissingRefTargets` in `data-check-core.ts`).
- */
-export function dataRef(target) {
-    return z
-        .string()
-        .regex(refPattern(target), {
-        message: `must be a "${target}#<key>" reference (docs/DATA-TOOLS-DESIGN.md §2.2) — ` +
-            `expected the target asset stem "${target}", e.g. "${target}#some-key".`,
-    })
-        .meta({ 'x-vgai-ref': target });
-}
-/** First failing key-path segment, or `null` if the whole path resolves — same walk `data-check-core.ts`'s `firstUnresolvedSegment` does over parsed JSON, here over a live handle's value. */
-function firstMissingSegment(root, keyPath) {
-    let node = root;
-    for (const segment of keyPath) {
-        if (node === null || typeof node !== 'object' || Array.isArray(node) || !(segment in node)) {
-            return segment;
-        }
-        node = node[segment];
-    }
-    return null;
-}
-/**
- * Resolve a `"target#key(.field)*"` ref against the named target HANDLE,
- * read live (`target.get()` at call time — HMR-correct, no caching across
- * frames, same doctrine as any other data read).
- *
- * `ref`'s stem prefix should name `target`'s own asset — when `target` was
- * built with a `sourcePath` (every `defineData` call populates it), a
- * mismatch throws a teaching error instead of silently walking the wrong
- * handle's data. Without a `sourcePath` (a hand-rolled `DataHandle`, or an
- * older one built before this field existed) the mismatch check is skipped —
- * resolution still proceeds against `target`, since the caller named it
- * explicitly and that's the actual contract.
- *
- * Throws a teaching error naming the ref and the first key-path segment that
- * doesn't resolve (a deleted row, a typo'd key) — never returns `undefined`
- * silently, matching `parseDataJson`'s "errors teach" doctrine (§6.5).
- */
-export function getRef(target, ref) {
-    const m = DATA_REF_PATTERN.exec(ref);
-    if (!m) {
-        throw new Error(`getRef: "${ref}" is not a "file#key" reference (docs/DATA-TOOLS-DESIGN.md §2.2) — ` +
-            'expected a string shaped like "some-file#some-key".');
-    }
-    const refStem = m[1];
-    const keyPathStr = m[2];
-    const targetStem = target.sourcePath
-        ?.split('\\')
-        .join('/')
-        .split('/')
-        .pop()
-        ?.replace(/\.data\.json$/, '');
-    if (targetStem !== undefined && targetStem !== refStem) {
-        throw new Error(`getRef: ref "${ref}" names target asset "${refStem}", but the handle passed in is ` +
-            `"${targetStem}" (${target.sourcePath}). Pass the handle ` +
-            `"${refStem}#..." actually names — getRef(${refStem}, ...), not getRef(${targetStem}, ...).`);
-    }
-    const keyPath = keyPathStr.split('.');
-    const root = target.get();
-    const missing = firstMissingSegment(root, keyPath);
-    if (missing !== null) {
-        throw new Error(`getRef: dangling ref "${ref}" — "${missing}" does not exist` +
-            (targetStem ? ` in ${targetStem}.data.json` : '') +
-            '. Fix the key or remove the ref (refs are "file#key" strings — docs/DATA-TOOLS-DESIGN.md §2.2).');
-    }
-    let node = root;
-    for (const segment of keyPath)
-        node = node[segment];
-    return node;
-}

package/dist/data/vite-plugin-data.d.ts

@@ -1,79 +0,0 @@
-/**
- * `vgaiDataCheck` — build-path validation for data assets and project tools
- * (docs/DATA-TOOLS-DESIGN.md §6.7, the enforcement half of W5). A Vite plugin
- * for the PROJECT's own `vite.config.ts` (the template wires it; the editor
- * dev server boots Vite from the ENGINE's config and never runs this — its
- * surface is covered by `vgai doctor` instead). Build-only (`apply: 'build'`):
- * in dev, `defineData`'s parse-on-load already fails loud in the console.
- *
- * Three checks, all failing the build loud:
- *
- * 1. **Schema integrity** (`buildStart`): every registered asset's
- *    `.data.json` is read fresh from disk and validated through
- *    {@link parseDataJson} — the EXACT parse `defineData` runs at load (§9.1:
- *    an emitted-JSON-Schema validator here could disagree with runtime; the
- *    Zod schema itself never can). The schemas arrive EXECUTABLE because
- *    `vite.config.ts` statically imports the project's data-asset registry
- *    (`src/data/assets.ts` in the template) — Vite's config loader bundles
- *    config-relative TS imports, which is what makes this the one build-side
- *    place project Zod schemas can run.
- * 2. **Ref integrity** (`buildStart`): every `file#key(.field)*` string in
- *    every `src/data/*.data.json` (registered or not) must resolve — shared
- *    definition with `vgai doctor` via {@link findDanglingDataRefs}, so the
- *    two surfaces can never disagree about what "dangling" means. A second,
- *    narrower ref check runs alongside it for REGISTERED assets only: any
- *    field declared with `dataRef(target)` (`./data-ref.ts`) whose `target`
- *    names no asset currently on disk fails loud too (§9.4's "renamed the
- *    target file" hole, closed for declared refs — see
- *    `collectDeclaredRefFields`/`findMissingRefTargets` in `data-check-core.ts`).
- * 3. **Tools never ship** (`generateBundle`): no emitted chunk may contain a
- *    module from `src/tools/` or a `*.tool.*` file (§4: tester serves and
- *    standalone builds strip tools entirely; W4 made this true by
- *    construction — nothing imports tools — and this check PINS it against
- *    the day some game module imports a tool "just for a helper").
- *
- * Unregistered data files (a `.data.json` with no entry in the passed
- * `assets` list) are a WARNING, not an error: they still get ref-integrity
- * and runtime parse-on-load, but no build-time schema check — the warning
- * names the registry file to fix.
- */
-import type { Plugin } from 'vite';
-import type { z } from 'zod';
-/** One registered data asset: its executable Zod schema + the project-relative path of its `.data.json`. */
-export interface DataCheckAsset {
-    readonly schema: z.ZodType;
-    /** e.g. `'src/data/tuning.data.json'` — read fresh from disk at buildStart. */
-    readonly sourcePath: string;
-}
-export interface VgaiDataCheckOptions {
-    readonly assets: readonly DataCheckAsset[];
-    /** Project root the `sourcePath`s resolve against. Default: `process.cwd()` (vite build's cwd). */
-    readonly root?: string;
-}
-/**
- * The fs half of checks 1 + 2, extracted from the plugin hook so it is
- * directly unit-testable against a fixture folder (no rollup context needed).
- */
-export declare function collectDataCheckProblems(options: VgaiDataCheckOptions): {
-    errors: string[];
-    warnings: string[];
-};
-/** True iff a bundled module id is tool code that must never ship (§4). Pure, unit-tested. */
-export declare function isToolModuleId(id: string): boolean;
-/**
- * Build-path validation plugin — see the module doc. Wire it in the project's
- * `vite.config.ts`, passing the data-asset registry:
- *
- * ```ts
- * import { vgaiDataCheck } from '@vgai/engine/data/vite-plugin-data';
- * import { dataAssets } from './src/data/assets';
- * export default defineConfig({
- *   plugins: [vgaiDataCheck({
- *     root: __dirname,
- *     assets: dataAssets.map((a) => ({ schema: a.schema, sourcePath: `src/data/${a.name}.data.json` })),
- *   })],
- * });
- * ```
- */
-export declare function vgaiDataCheck(options: VgaiDataCheckOptions): Plugin;
-//# sourceMappingURL=vite-plugin-data.d.ts.map

package/dist/data/vite-plugin-data.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"vite-plugin-data.d.ts","sourceRoot":"","sources":["../../src/data/vite-plugin-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQ7B,4GAA4G;AAC5G,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C,mGAAmG;IACnG,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAuGD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,oBAAoB,GAAG;IACvE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CA2DA;AAED,8FAA8F;AAC9F,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAGlD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAmCnE"}