@sandstone-mc/mcdoc-ts-generator 0.1.0

package/dist/typegen/compile.d.ts

@@ -0,0 +1,2 @@
+import ts from 'typescript';
+export declare function compile_types(nodes: ts.Node[], file?: string): Promise<string>;

package/dist/typegen/export.d.ts

@@ -0,0 +1,39 @@
+import ts from 'typescript';
+import { type NonEmptyList } from './mcdoc/utils';
+import type { ResolvedDispatcher, ResolvedRegistry } from '.';
+export declare function export_registry(resolved_registries: Map<string, ResolvedRegistry>): {
+    readonly exports: ts.TypeAliasDeclaration[];
+    readonly paths: Set<string>;
+} | {
+    readonly imports: {
+        readonly ordered: NonEmptyList<string>;
+        readonly check: Map<string, number>;
+    };
+    readonly exports: ts.TypeAliasDeclaration[];
+    readonly paths: Set<string>;
+};
+/**
+ * Generates a `Dispatcher` type system with type-safe generic enforcement.
+ *
+ * Example output:
+ * ```ts
+ * interface DispatcherRequiredArgs {
+ *   'minecraft:data_component': []
+ *   'minecraft:entity_effect': [unknown]
+ * }
+ * type DefaultArgs<R extends keyof DispatcherRequiredArgs> = ...
+ * type ApplyDispatcher<R, Args> = ...
+ * export type Dispatcher<R, Args> = ApplyDispatcher<R, Args>
+ * ```
+ */
+export declare function export_dispatcher(resolved_dispatchers: Map<string, ResolvedDispatcher>): {
+    readonly exports: ts.TypeAliasDeclaration[];
+    readonly paths: Set<string>;
+} | {
+    readonly imports: {
+        readonly ordered: NonEmptyList<string>;
+        readonly check: Map<string, number>;
+    };
+    readonly exports: ts.TypeAliasDeclaration[];
+    readonly paths: Set<string>;
+};

package/dist/typegen/import.d.ts

@@ -0,0 +1,6 @@
+import ts from 'typescript';
+import type { NonEmptyList } from './mcdoc/utils';
+export declare function handle_imports(imports?: {
+    readonly ordered: NonEmptyList<string>;
+    readonly check: Map<string, number>;
+}): ts.ImportDeclaration[];

package/dist/typegen/index.d.ts

@@ -0,0 +1,38 @@
+import { type SymbolUtil } from '@spyglassmc/core';
+import ts from 'typescript';
+import { type TypeHandlerResult } from './mcdoc';
+import { Set } from './mcdoc/utils';
+export type ResolvedSymbol = {
+    readonly paths: Set<string>;
+    readonly imports?: NonNullable<TypeHandlerResult['imports']>;
+    readonly exports: (ts.TypeAliasDeclaration | ts.EnumDeclaration | ts.VariableStatement)[];
+};
+export type ResolvedRegistry = {
+    import_path: string;
+    registry: ts.Identifier;
+};
+export type ResolvedDispatcher = {
+    import_path: string;
+    type: ts.TypeReferenceNode;
+    /**
+     * Number of required generic parameters (excluding CASE)
+     */
+    generic_count: number;
+    /**
+     * The symbol type name (e.g., "SymbolDataComponent")
+     */
+    symbol_name: string;
+};
+export declare class TypesGenerator {
+    readonly resolved_registries: Map<string, ResolvedRegistry>;
+    readonly dispatcher_properties: Map<string, {
+        supports_none?: true;
+    }>;
+    readonly resolved_symbols: Map<string, ResolvedSymbol>;
+    readonly resolved_dispatchers: Map<string, ResolvedDispatcher>;
+    constructor();
+    resolve_types(symbols: SymbolUtil): void;
+    private resolve_registry_symbols;
+    private resolve_module_symbols;
+    private resolve_dispatcher_symbols;
+}

package/dist/typegen/mcdoc/assert.d.ts

@@ -0,0 +1,427 @@
+import * as mcdoc from '@spyglassmc/mcdoc';
+import { Set } from './utils';
+type ReferenceType = {
+    kind: 'reference';
+    path: string;
+    attributes: never;
+};
+type StringLiteral = Omit<(mcdoc.LiteralType & {
+    value: mcdoc.LiteralStringValue;
+}), 'attributes'>;
+/**
+ * These Attribute types are based on what actually appears in vanilla-mcdoc to simplify handling, these may need updates in the future.
+ */
+type AttributeTreeChildType = ((ReferenceType | (mcdoc.LiteralType & {
+    value: mcdoc.LiteralStringValue | mcdoc.LiteralBooleanValue;
+}) | (mcdoc.AttributeTreeValue & {
+    values: Record<`${number}`, StringLiteral>;
+})) & {
+    attributes: never;
+});
+type AttributeRootValueType = ((mcdoc.DispatcherType | ReferenceType | StringLiteral | (mcdoc.AttributeTreeValue & {
+    values: Record<string, AttributeTreeChildType>;
+})) & {
+    attributes: never;
+});
+type AttributeType = mcdoc.Attribute & {
+    value: AttributeRootValueType;
+};
+type CommandAttributeExtras = {
+    empty?: {
+        attributes: never;
+        kind: 'literal';
+        value: {
+            attributes: never;
+            kind: 'string';
+            value: 'allowed';
+        };
+    };
+    max_length?: {
+        attributes: never;
+        kind: 'literal';
+        value: {
+            attributes: never;
+            kind: 'int';
+            value: number;
+        };
+    };
+    incomplete?: {
+        attributes: never;
+        kind: 'literal';
+        value: {
+            attributes: never;
+            kind: 'string';
+            value: 'allowed';
+        };
+    };
+};
+type ImplementedAttributes = {
+    id: (undefined | {
+        attributes: never;
+        kind: 'literal';
+        value: {
+            attributes: never;
+            kind: 'string';
+            value: string;
+        };
+    } | {
+        attributes: never;
+        kind: 'tree';
+        values: {
+            registry: {
+                attributes: never;
+                kind: 'literal';
+                value: {
+                    attributes: never;
+                    kind: 'string';
+                    value: string;
+                };
+            };
+            path?: {
+                attributes: never;
+                kind: 'literal';
+                value: {
+                    attributes: never;
+                    kind: 'string';
+                    value: `${string}/`;
+                };
+            };
+            definition?: {
+                attributes: never;
+                kind: 'literal';
+                value: {
+                    attributes: never;
+                    kind: 'boolean';
+                    value: true;
+                };
+            };
+            exclude?: {
+                attributes: never;
+                kind: 'tree';
+                values: {
+                    [K in `${number}`]: {
+                        attributes: never;
+                        kind: 'literal';
+                        value: {
+                            attributes: never;
+                            kind: 'string';
+                            value: string;
+                        };
+                    };
+                };
+            };
+            tags?: {
+                attributes: never;
+                kind: 'literal';
+                value: {
+                    attributes: never;
+                    kind: 'string';
+                    value: KindType<typeof AssertKinds.RegistryAttributeTagsArgument>;
+                };
+            };
+            empty?: {
+                attributes: never;
+                kind: 'literal';
+                value: {
+                    attributes: never;
+                    kind: 'string';
+                    value: 'allowed';
+                };
+            };
+            prefix?: {
+                attributes: never;
+                kind: 'literal';
+                value: {
+                    attributes: never;
+                    kind: 'string';
+                    value: '!';
+                };
+            };
+        };
+    });
+    since: {
+        attributes: never;
+        kind: 'literal';
+        value: {
+            attributes: never;
+            kind: 'string';
+            value: `${number}.${number}.${number}`;
+        };
+    };
+    until: {
+        attributes: never;
+        kind: 'literal';
+        value: {
+            attributes: never;
+            kind: 'string';
+            value: `${number}.${number}.${number}`;
+        };
+    };
+    permutation: {
+        attributes: never;
+        kind: 'tree';
+        values: {
+            definition: {
+                attributes: never;
+                kind: 'literal';
+                value: {
+                    kind: 'boolean';
+                    value: true;
+                };
+            };
+        };
+    };
+    texture_slot: {
+        attributes: never;
+        kind: 'tree';
+        values: {
+            kind: {
+                attributes: never;
+                kind: 'literal';
+                value: {
+                    attributes: never;
+                    kind: 'string';
+                    value: KindType<typeof AssertKinds.TextureSlotAttributeKind>;
+                };
+            };
+        };
+    };
+    item_slots: undefined;
+    tag: undefined;
+    team: undefined;
+    translation_key: undefined;
+    translation_value: undefined;
+    crafting_ingredient: (undefined | {
+        attributes: never;
+        kind: 'tree';
+        values: {
+            definition: {
+                attributes: never;
+                kind: 'literal';
+                value: {
+                    attributes: never;
+                    kind: 'boolean';
+                    value: true;
+                };
+            };
+        };
+    });
+    objective: undefined;
+    dispatcher_key: {
+        attributes: never;
+        kind: 'literal';
+        value: {
+            attributes: never;
+            kind: 'string';
+            value: `${string}:${string}`;
+        };
+    };
+    regex_pattern: undefined;
+    canonical: undefined;
+    color: {
+        attributes: never;
+        kind: 'literal';
+        value: {
+            attributes: never;
+            kind: 'string';
+            value: KindType<typeof AssertKinds.ColorAttributeKind>;
+        };
+    };
+    time_pattern: undefined;
+    criterion: (undefined | {
+        attributes: never;
+        kind: 'tree';
+        values: {
+            definition: {
+                attributes: never;
+                kind: 'literal';
+                value: {
+                    attributes: never;
+                    kind: 'boolean';
+                    value: true;
+                };
+            };
+        };
+    });
+    nbt: (undefined | mcdoc.DispatcherType | ReferenceType);
+    nbt_path: (undefined | mcdoc.DispatcherType);
+    match_regex: {
+        attributes: never;
+        kind: 'literal';
+        value: {
+            attributes: never;
+            kind: 'string';
+            value: string;
+        };
+    };
+    deprecated: undefined;
+    command: {
+        attributes: never;
+        kind: 'tree';
+        values: (({
+            macro: {
+                attributes: never;
+                kind: 'literal';
+                value: {
+                    attributes: never;
+                    kind: 'string';
+                    value: 'implicit' | 'allowed';
+                };
+            };
+        } & CommandAttributeExtras) | ({
+            slash: {
+                attributes: never;
+                kind: 'literal';
+                value: {
+                    attributes: never;
+                    kind: 'string';
+                    value: KindType<typeof AssertKinds.CommandAttributeSlashKind>;
+                };
+            };
+        } & CommandAttributeExtras));
+    };
+    uuid: undefined;
+    url: undefined;
+    random: undefined;
+    divisible_by: {
+        attributes: never;
+        kind: 'literal';
+        value: {
+            attributes: never;
+            kind: 'int';
+            value: number;
+        };
+    };
+    entity: (undefined | {
+        attributes: never;
+        kind: 'tree';
+        values: {
+            amount?: {
+                attributes: never;
+                kind: 'literal';
+                value: {
+                    attributes: never;
+                    kind: 'string';
+                    value: 'single' | 'multiple';
+                };
+            };
+            type?: {
+                attributes: never;
+                kind: 'literal';
+                value: {
+                    attributes: never;
+                    kind: 'string';
+                    value: 'entities' | 'players';
+                };
+            };
+        };
+    });
+    integer: {
+        attributes: never;
+        kind: 'tree';
+        values: {
+            min: {
+                attributes: never;
+                kind: 'literal';
+                value: {
+                    attributes: never;
+                    kind: 'int';
+                    value: 1;
+                };
+            };
+        };
+    };
+    /**
+     * This isn't correct, but ICBA
+     */
+    game_rule: undefined;
+    score_holder: undefined;
+    vector: {
+        attributes: never;
+        kind: 'tree';
+        values: {
+            dimension: {
+                attributes: never;
+                kind: 'literal';
+                value: {
+                    attributes: never;
+                    kind: 'int';
+                    value: 3;
+                };
+            };
+            integer: {
+                attributes: never;
+                kind: 'literal';
+                value: {
+                    attributes: never;
+                    kind: 'boolean';
+                    value: true;
+                };
+            };
+        };
+    };
+    bitfield: ReferenceType;
+    text_component: undefined;
+    block_predicate: undefined;
+};
+export type ImplementedAttributeType<KIND extends (keyof ImplementedAttributes | undefined) = undefined> = mcdoc.Attribute & (KIND extends undefined ? ({
+    [K in keyof ImplementedAttributes]: ({
+        name: K;
+    } & (ImplementedAttributes[K] extends undefined ? {} : {
+        value: ImplementedAttributes[K];
+    }));
+}[keyof ImplementedAttributes]) : (ImplementedAttributes[Extract<KIND, string>] extends undefined ? {
+    name: KIND;
+} : (Extract<ImplementedAttributes[Extract<KIND, string>], undefined> extends never ? {
+    name: KIND;
+    value: ImplementedAttributes[Extract<KIND, string>];
+} : {
+    name: KIND;
+    value?: NonNullable<ImplementedAttributes[Extract<KIND, string>]>;
+})));
+export type KindType<T> = T extends Set<infer U> ? U : never;
+export declare class AssertKinds {
+    static readonly AttributeRootValueKind: Set<"reference" | "literal" | "tree" | "dispatcher">;
+    static readonly AttributeTreeChildKind: Set<"reference" | "literal" | "tree">;
+    static readonly ImplementedAttributes: Set<"objective" | "score_holder" | "tag" | "team" | "texture_slot" | "translation_key" | "game_rule" | "id" | "since" | "until" | "permutation" | "item_slots" | "translation_value" | "crafting_ingredient" | "dispatcher_key" | "regex_pattern" | "canonical" | "color" | "time_pattern" | "criterion" | "nbt" | "nbt_path" | "match_regex" | "deprecated" | "command" | "uuid" | "url" | "random" | "divisible_by" | "entity" | "integer" | "vector" | "bitfield" | "text_component" | "block_predicate">;
+    static readonly RegistryAttributeArgument: Set<"definition" | "registry" | "path" | "exclude" | "tags" | "empty" | "prefix">;
+    static readonly RegistryAttributeTagsArgument: Set<"allowed" | "implicit" | "required">;
+    static readonly ColorAttributeKind: Set<"particle" | "composite_rgb" | "composite_argb" | "hex_rgb" | "hex_argb" | "dec_rgb" | "dec_rgba" | "named">;
+    static readonly CommandAttributeArgument: Set<"empty" | "macro" | "slash" | "incomplete" | "max_length">;
+    static readonly CommandAttributeSlashKind: Set<"allowed" | "required" | "chat" | "none">;
+    static readonly TextureSlotAttributeKind: Set<"reference" | "value" | "definition">;
+    static readonly ArrayKind: Set<"byte_array" | "int_array" | "long_array">;
+    static readonly StructKeyKind: Set<"string" | "reference" | "concrete" | "union">;
+    static readonly StructSpreadKind: Set<"reference" | "dispatcher" | "concrete" | "union" | "template" | "struct">;
+    static readonly NumericKind: Set<string>;
+}
+export declare class Assert {
+    static Attributes<IMPLEMENTED extends (undefined | true)>(type: mcdoc.Attribute[], implemented?: IMPLEMENTED): asserts type is (IMPLEMENTED extends true ? ImplementedAttributeType[] : AttributeType[]);
+    static DispatcherType(type: mcdoc.McdocType): asserts type is mcdoc.DispatcherType;
+    static IndexedType(type: mcdoc.McdocType): asserts type is mcdoc.IndexedType;
+    static TemplateType(type: mcdoc.McdocType): asserts type is mcdoc.TemplateType;
+    static ArrayType<KIND extends ('byte_array' | 'int_array' | 'long_array' | undefined) = undefined>(type: mcdoc.McdocType): asserts type is (KIND extends undefined ? never : mcdoc.PrimitiveArrayType & {
+        kind: KIND;
+    });
+    static ListType(type: mcdoc.McdocType): asserts type is mcdoc.ListType;
+    static EnumType(type: mcdoc.McdocType): asserts type is mcdoc.EnumType;
+    static StructType(type: mcdoc.McdocType): asserts type is mcdoc.StructType;
+    static StructKeyType(type: mcdoc.McdocType): asserts type is (ReferenceType | mcdoc.ConcreteType | mcdoc.StringType | mcdoc.UnionType);
+    static StructSpreadType(type: mcdoc.McdocType): asserts type is (ReferenceType | mcdoc.DispatcherType | mcdoc.ConcreteType | mcdoc.TemplateType | mcdoc.StructType | mcdoc.UnionType);
+    static TupleType(type: mcdoc.McdocType): asserts type is mcdoc.TupleType;
+    static UnionType(type: mcdoc.McdocType): asserts type is mcdoc.UnionType;
+    static KeywordType<KIND extends (mcdoc.KeywordType['kind'] | undefined) = undefined>(type: mcdoc.McdocType): asserts type is (KIND extends undefined ? never : mcdoc.KeywordType & {
+        kind: KIND;
+    });
+    static NumericType<KIND extends (mcdoc.NumericTypeKind | undefined) = undefined>(type: mcdoc.McdocType): asserts type is (KIND extends undefined ? never : mcdoc.NumericType & {
+        kind: KIND;
+    });
+    static ConcreteType(type: mcdoc.McdocType): asserts type is (mcdoc.ConcreteType & {
+        child: (ReferenceType | mcdoc.DispatcherType);
+    });
+    static LiteralType(type: mcdoc.McdocType): asserts type is mcdoc.LiteralType;
+    static ReferenceType(type: mcdoc.McdocType): asserts type is ReferenceType;
+    static StringType(type: mcdoc.McdocType): asserts type is mcdoc.StringType;
+    static ColorStringType(type: KindType<typeof AssertKinds.ColorAttributeKind>): asserts type is ('hex_argb' | 'hex_rgb');
+}
+export {};

package/dist/typegen/mcdoc/bind.d.ts

@@ -0,0 +1,61 @@
+import ts from 'typescript';
+type NonEmptyList<T> = T[] & {
+    0: T;
+};
+export declare class Bind {
+    static NumericLiteral(literal: number): ts.LiteralTypeNode;
+    static StringLiteral(literal: string): ts.LiteralTypeNode;
+    /**
+     * Creates a template literal type that represents a non-empty string.
+     * ```ts
+     * type NonEmptyString = `${any}${string}` // <-- This type
+     * ```
+     */
+    static readonly NonEmptyString: ts.TemplateLiteralTypeNode;
+    /**
+     * Creates a template literal type that represents a namespaced identifier.
+     * ```ts
+     * type Namespaced = `${string}:${string}` // <-- This type
+     * ```
+     */
+    static readonly Namespaced: ts.TemplateLiteralTypeNode;
+    /**
+     * Creates a mapped type with optional properties.
+     *
+     * The key type is always wrapped in `Extract<KeyType, string>` for safety.
+     *
+     * @param key_type - The type to iterate over (will be wrapped in Extract)
+     * @param value_type - The type of each property value
+     * @param options.key_name - The name of the type parameter (default `'Key'`)
+     * @param options.parenthesized - Whether to wrap the result in parentheses (default `true`)
+     * @returns A mapped type node: `({ [Key in Extract<KeyType, string>]?: ValueType })`
+     *
+     * @example
+     * ```ts
+     * // Default usage:
+     * Bind.MappedType(keyType, valueType)
+     * // Produces: ({ [Key in Extract<KeyType, string>]?: ValueType })
+     *
+     * // Custom key name, no parentheses:
+     * Bind.MappedType(keyType, valueType, { key_name: 'S', parenthesized: false })
+     * // Produces: { [S in Extract<KeyType, string>]?: ValueType }
+     * ```
+     */
+    static MappedType(key_type: ts.TypeNode, value_type: ts.TypeNode, options?: {
+        key_name?: string;
+        parenthesized?: boolean;
+    }): ts.MappedTypeNode | ts.ParenthesizedTypeNode;
+    /**
+     * Creates a TypeScript type that represents an empty object.
+     * ```ts
+     * type EmptyObject = Record<string, never>
+     * ```
+     */
+    static readonly EmptyObject: ts.TypeReferenceNode;
+    static DocPart(doc: string): string[];
+    /**
+     * https://stackoverflow.com/questions/67575784/typescript-ast-factory-how-to-use-comments
+     */
+    static Doc<N extends ts.Node>(node: N, docs?: NonEmptyList<string | [string]>): N;
+}
+export {};

package/dist/typegen/mcdoc/complex/dispatcher.d.ts

@@ -0,0 +1,34 @@
+import ts from 'typescript';
+import * as mcdoc from '@spyglassmc/mcdoc';
+import type { NonEmptyList } from '..';
+/**
+ * Handles `dispatcher` types which reference a dispatcher symbol map.
+ *
+ * A dispatcher type has:
+ * - `registry`: The dispatcher identifier (e.g., `minecraft:entity_effect`)
+ * - `parallelIndices`: How to look up into the dispatcher (static or dynamic)
+ *
+ * The generated type references the central Dispatcher type:
+ * - Static index: `Dispatcher<'minecraft:entity_effect'>['specific_key']`
+ * - Dynamic index: `Dispatcher<'minecraft:entity_effect'>[Key]`
+ * - Fallback: `Dispatcher<'minecraft:entity_effect', ['%fallback']>`
+ * - None: `Dispatcher<'minecraft:entity_effect', ['%none']>`
+ */
+declare function mcdoc_dispatcher(type: mcdoc.McdocType): (args: Record<string, unknown>) => {
+    readonly type: ts.TypeNode;
+    readonly imports: {
+        readonly ordered: NonEmptyList<string>;
+        readonly check: Map<string, number>;
+    };
+} | {
+    readonly child_dispatcher: [parent_count: number, property: string][] & {
+        0: [parent_count: number, property: string];
+    };
+    readonly type: ts.TypeNode;
+    readonly imports: {
+        readonly ordered: NonEmptyList<string>;
+        readonly check: Map<string, number>;
+    };
+};
+export declare const McdocDispatcher: typeof mcdoc_dispatcher;
+export {};

package/dist/typegen/mcdoc/complex/index.d.ts

@@ -0,0 +1,3 @@
+export { McdocDispatcher } from './dispatcher';
+export { McdocIndexed } from './indexed';
+export { McdocTemplate } from './template';

package/dist/typegen/mcdoc/complex/indexed.d.ts

@@ -0,0 +1,47 @@
+import * as mcdoc from '@spyglassmc/mcdoc';
+import type { NonEmptyList } from '..';
+/**
+ * Handles `indexed` types which access a specific property from a dispatcher type.
+ *
+ * An indexed type has:
+ * - `child`: The type to index into (typically a dispatcher)
+ * - `parallelIndices`: The indices to access (static string keys)
+ *
+ * Example from vanilla-mcdoc:
+ * ```mcdoc
+ * struct EnvironmentAttributeTrackMap {
+ *    [#[id="environment_attribute"] string]: minecraft:environment_attribute[[%key]][attribute_track],
+ * }
+ * ```
+ *
+ * The `[attribute_track]` is an indexed access into the dispatcher result.
+ * This needs to generate:
+ * ```ts
+ * SymbolEnvironmentAttribute[K]['attribute_track']
+ * ```
+ *
+ * Symbol structure:
+ * ```json
+ * {"kind":"indexed","child":{"kind":"dispatcher","parallelIndices":[{"kind":"dynamic","accessor":[{"keyword":"key"}]}],"registry":"minecraft:environment_attribute"},"parallelIndices":[{"kind":"static","value":"attribute_track"}]}
+ * ```
+ *
+ * The index keys are passed through to the dispatcher handler via args.
+ */
+declare function mcdoc_indexed(type: mcdoc.McdocType): (args: Record<string, unknown>) => {
+    readonly type: import("typescript").TypeNode;
+    readonly imports: {
+        readonly ordered: NonEmptyList<string>;
+        readonly check: Map<string, number>;
+    };
+} | {
+    readonly child_dispatcher: [parent_count: number, property: string][] & {
+        0: [parent_count: number, property: string];
+    };
+    readonly type: import("typescript").TypeNode;
+    readonly imports: {
+        readonly ordered: NonEmptyList<string>;
+        readonly check: Map<string, number>;
+    };
+};
+export declare const McdocIndexed: typeof mcdoc_indexed;
+export {};