@spyglassmc/mcdoc 0.1.0

package/lib/type/index.d.ts

@@ -0,0 +1,161 @@
+import type { FullResourceLocation, ProcessorContext, SymbolPath } from '@spyglassmc/core';
+import type { EnumKind } from '../node';
+export interface Attribute {
+    name: string;
+    value: AttributeValue;
+}
+export declare type AttributeValue = string | {
+    [key: string | number]: AttributeValue;
+};
+export declare type NumericRange = [number | undefined, number | undefined];
+interface StaticIndex {
+    kind: 'static';
+    value: string | {
+        keyword: 'fallback' | 'none' | 'unknown';
+    };
+}
+interface DynamicIndex {
+    kind: 'dynamic';
+    accessor: (string | {
+        keyword: 'key' | 'parent';
+    })[];
+}
+export declare type Index = StaticIndex | DynamicIndex;
+export declare type ParallelIndices = [Index, ...Index[]];
+export interface DispatcherData {
+    registry: FullResourceLocation | undefined;
+    index: ParallelIndices;
+}
+interface TypeBase {
+    kind: string;
+    attributes?: Attribute[];
+    indices?: ParallelIndices[];
+}
+export interface DispatcherType extends TypeBase, DispatcherData {
+    kind: 'dispatcher';
+}
+export interface StructType extends TypeBase {
+    kind: 'struct';
+    fields: ({
+        kind: 'field';
+        key: string;
+        type: McdocType;
+        symbol: SymbolPath;
+    } | {
+        kind: 'spread';
+        type: McdocType;
+    })[];
+}
+export interface EnumType extends TypeBase {
+    kind: 'enum';
+    enumKind: EnumKind;
+    values: {
+        identifier: string;
+        value: string | number | bigint;
+    }[];
+}
+export interface ReferenceType extends TypeBase {
+    kind: 'reference';
+    symbol?: SymbolPath;
+    index?: Index;
+}
+export interface UnionType<T extends McdocType = McdocType> extends TypeBase {
+    kind: 'union';
+    members: T[];
+}
+export declare const EmptyUnion: UnionType<never> & NoIndices;
+export declare function createEmptyUnion(attributes?: Attribute[]): UnionType<never> & NoIndices;
+interface KeywordType extends TypeBase {
+    kind: 'any' | 'boolean';
+}
+interface StringType extends TypeBase {
+    kind: 'string';
+    lengthRange?: NumericRange;
+}
+declare type LiteralValue = {
+    kind: 'boolean';
+    value: boolean;
+} | {
+    kind: 'string';
+    value: string;
+} | {
+    kind: 'number';
+    value: number;
+    suffix: 'b' | 's' | 'L' | 'f' | 'd' | undefined;
+};
+interface LiteralType extends TypeBase {
+    kind: 'literal';
+    value: LiteralValue;
+}
+interface NumericType extends TypeBase {
+    kind: 'byte' | 'short' | 'int' | 'long' | 'float' | 'double';
+    valueRange?: NumericRange;
+}
+interface PrimitiveArrayType extends TypeBase {
+    kind: 'byte_array' | 'int_array' | 'long_array';
+    valueRange?: NumericRange;
+    lengthRange?: NumericRange;
+}
+export interface ListType extends TypeBase {
+    kind: 'list';
+    item: McdocType;
+    lengthRange?: NumericRange;
+}
+export interface TupleType extends TypeBase {
+    kind: 'tuple';
+    items: McdocType[];
+}
+export declare type McdocType = DispatcherType | EnumType | KeywordType | ListType | LiteralType | NumericType | PrimitiveArrayType | ReferenceType | StringType | StructType | TupleType | UnionType;
+export declare namespace McdocType {
+    function toString(type: McdocType | undefined): string;
+}
+/**
+ * A type that doesn't include a dispatcher type.
+ */
+export declare type DispatchedType = Exclude<McdocType, DispatcherType | UnionType> | UnionType<DispatchedType>;
+/**
+ * A type that doesn't include a reference type.
+ */
+export declare type DereferencedType = Exclude<McdocType, ReferenceType | UnionType> | UnionType<DereferencedType>;
+/**
+ * A type that doesn't include a dispatcher type or a reference type.
+ */
+export declare type TangibleType = Exclude<McdocType, DispatcherType | ReferenceType | UnionType> | UnionType<TangibleType>;
+/**
+ * A type that is {@link TangibleType} and doesn't have any indices.
+ */
+export declare type ResolvedType = (Exclude<McdocType, DispatcherType | ReferenceType | UnionType> | UnionType<ResolvedType>) & NoIndices;
+declare type NoIndices = {
+    indices?: undefined;
+};
+export interface FlatStructType extends TypeBase {
+    kind: 'flat_struct';
+    fields: Record<string, {
+        type: McdocType;
+        symbol: SymbolPath;
+    }>;
+}
+export declare const flattenUnionType: (union: UnionType) => UnionType;
+export declare const unionTypes: (a: McdocType, b: McdocType) => McdocType;
+export declare const simplifyUnionType: (union: UnionType) => McdocType;
+export declare const simplifyListType: (list: ListType) => ListType;
+export declare const simplifyType: (data: McdocType) => McdocType;
+export declare const checkAssignability: ({ source, target }: {
+    source: McdocType | undefined;
+    target: McdocType | undefined;
+}) => {
+    isAssignable: boolean;
+    errorMessage?: string;
+};
+/**
+ * https://spyglassmc.com/user/mcdoc/#p-RuntimeValue
+ */
+export interface RuntimeValue {
+    asString(): string | undefined;
+    getKeyOnParent(): RuntimeValue | undefined;
+    getParent(): RuntimeValue | undefined;
+    getValue(key: string): RuntimeValue | undefined;
+}
+export declare function resolveType(inputType: McdocType, ctx: ProcessorContext, value: RuntimeValue | undefined): ResolvedType;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/lib/type/index.js

@@ -0,0 +1,398 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveType = exports.checkAssignability = exports.simplifyType = exports.simplifyListType = exports.simplifyUnionType = exports.unionTypes = exports.flattenUnionType = exports.McdocType = exports.createEmptyUnion = exports.EmptyUnion = void 0;
+const core_1 = require("@spyglassmc/core");
+const locales_1 = require("@spyglassmc/locales");
+exports.EmptyUnion = Object.freeze({ kind: 'union', members: [] });
+function createEmptyUnion(attributes) {
+    return {
+        ...exports.EmptyUnion,
+        attributes,
+    };
+}
+exports.createEmptyUnion = createEmptyUnion;
+var McdocType;
+(function (McdocType) {
+    function toString(type) {
+        const rangeToString = (range) => {
+            if (!range) {
+                return '';
+            }
+            const [min, max] = range;
+            return min === max ? ` @ ${min}` : ` @ ${min ?? ''}..${max ?? ''}`;
+        };
+        const indicesToString = (indices) => {
+            const strings = [];
+            for (const index of core_1.Arrayable.toArray(indices)) {
+                if (index === undefined) {
+                    strings.push('()');
+                }
+                else {
+                    strings.push(index.kind === 'static'
+                        ? `[${index.value}]`
+                        : `[[${index.accessor.map(v => typeof v === 'string' ? v : v.keyword).join('.')}]]`);
+                }
+            }
+            return `[${strings.join(', ')}]`;
+        };
+        if (type === undefined) {
+            return '<unknown>';
+        }
+        switch (type.kind) {
+            case 'any':
+            case 'boolean':
+                return type.kind;
+            case 'byte':
+                return `byte${rangeToString(type.valueRange)}`;
+            case 'byte_array':
+                return `byte${rangeToString(type.valueRange)}[]${rangeToString(type.lengthRange)}`;
+            case 'dispatcher':
+                return `${type.registry ?? 'spyglass:unknown'}[${indicesToString(type.index)}]`;
+            case 'double':
+                return `double${rangeToString(type.valueRange)}`;
+            case 'enum':
+                return '<anonymous_enum>';
+            case 'float':
+                return `float${rangeToString(type.valueRange)}`;
+            case 'int':
+                return `int${rangeToString(type.valueRange)}`;
+            case 'int_array':
+                return `int${rangeToString(type.valueRange)}[]${rangeToString(type.lengthRange)}`;
+            case 'list':
+                return `[${toString(type.item)}]${rangeToString(type.lengthRange)}`;
+            case 'literal':
+                return `${type.value}`;
+            case 'long':
+                return `long${rangeToString(type.valueRange)}`;
+            case 'long_array':
+                return `long${rangeToString(type.valueRange)}[]${rangeToString(type.lengthRange)}`;
+            case 'reference':
+                return type.symbol?.path.join('::') ?? '<unknown_reference>';
+            case 'short':
+                return `short${rangeToString(type.valueRange)}`;
+            case 'string':
+                return `string${rangeToString(type.lengthRange)}`;
+            case 'struct':
+                return '<anonymous_compound>';
+            case 'tuple':
+                return `[${type.items.map(v => toString(v)).join(',')}${type.items.length === 1 ? ',' : ''}]`;
+            case 'union':
+                return `(${type.members.map(toString).join(' | ')})`;
+        }
+    }
+    McdocType.toString = toString;
+})(McdocType = exports.McdocType || (exports.McdocType = {}));
+var CheckResult;
+(function (CheckResult) {
+    CheckResult[CheckResult["Nah"] = 0] = "Nah";
+    CheckResult[CheckResult["Assignable"] = 1] = "Assignable";
+    CheckResult[CheckResult["StrictlyAssignable"] = 3] = "StrictlyAssignable";
+})(CheckResult || (CheckResult = {}));
+const areRangesMatch = (s, t) => {
+    if (!t) {
+        return true;
+    }
+    if (!s) {
+        return false;
+    }
+    const [sMin, sMax] = s;
+    const [tMin, tMax] = t;
+    return (tMin === undefined || (sMin !== undefined && sMin >= tMin)) &&
+        (tMax === undefined || (sMax !== undefined && sMax <= tMax));
+};
+const flattenUnionType = (union) => {
+    const set = new Set();
+    const add = (data) => {
+        for (const existingMember of set) {
+            if ((check(data, existingMember) & CheckResult.StrictlyAssignable) === CheckResult.StrictlyAssignable) {
+                return;
+            }
+            if ((check(existingMember, data) & CheckResult.StrictlyAssignable) === CheckResult.StrictlyAssignable) {
+                set.delete(existingMember);
+            }
+        }
+        set.add(data);
+    };
+    for (const member of union.members) {
+        if (member.kind === 'union') {
+            (0, exports.flattenUnionType)(member).members.forEach(add);
+        }
+        else {
+            add(member);
+        }
+    }
+    return {
+        kind: 'union',
+        members: [...set],
+    };
+};
+exports.flattenUnionType = flattenUnionType;
+const unionTypes = (a, b) => {
+    if ((check(a, b) & CheckResult.StrictlyAssignable) === CheckResult.StrictlyAssignable) {
+        return b;
+    }
+    if ((check(b, a) & CheckResult.StrictlyAssignable) === CheckResult.StrictlyAssignable) {
+        return a;
+    }
+    const ans = {
+        kind: 'union',
+        members: [
+            ...a.kind === 'union' ? a.members : [a],
+            ...b.kind === 'union' ? b.members : [b],
+        ],
+    };
+    return ans;
+};
+exports.unionTypes = unionTypes;
+const simplifyUnionType = (union) => {
+    union = (0, exports.flattenUnionType)(union);
+    if (union.members.length === 1) {
+        return union.members[0];
+    }
+    return union;
+};
+exports.simplifyUnionType = simplifyUnionType;
+const simplifyListType = (list) => ({
+    kind: 'list',
+    item: (0, exports.simplifyType)(list.item),
+    ...list.lengthRange ? { lengthRange: [...list.lengthRange] } : {},
+});
+exports.simplifyListType = simplifyListType;
+const simplifyType = (data) => {
+    if (data.kind === 'union') {
+        data = (0, exports.simplifyUnionType)(data);
+    }
+    else if (data.kind === 'list') {
+        data = (0, exports.simplifyListType)(data);
+    }
+    return data;
+};
+exports.simplifyType = simplifyType;
+const check = (s, t, errors = []) => {
+    const strictlyAssignableIfTrue = (value) => value ? CheckResult.StrictlyAssignable : CheckResult.Nah;
+    const assignableIfTrue = (value) => value ? CheckResult.Assignable : CheckResult.Nah;
+    let ans;
+    s = (0, exports.simplifyType)(s);
+    t = (0, exports.simplifyType)(t);
+    if (s.kind === 'any' || s.kind === 'reference' || t.kind === 'reference') {
+        // Reference types are treated as any for now.
+        ans = CheckResult.Assignable;
+    }
+    else if (t.kind === 'any') {
+        ans = CheckResult.StrictlyAssignable;
+    }
+    else if (s.kind === 'union') {
+        ans = assignableIfTrue(s.members.every(v => check(v, t, errors)));
+    }
+    else if (t.kind === 'union') {
+        ans = assignableIfTrue(t.members.some(v => check(s, v)));
+    }
+    else if (s.kind === 'boolean') {
+        ans = strictlyAssignableIfTrue(t.kind === 'boolean' || t.kind === 'byte');
+    }
+    else if (s.kind === 'byte') {
+        if (t.kind === 'boolean') {
+            ans = check(s, { kind: 'byte', valueRange: [0, 1] }, errors);
+        }
+        else if (t.kind === 'byte') {
+            ans = strictlyAssignableIfTrue(areRangesMatch(s.valueRange, t.valueRange));
+        }
+        else if (t.kind === 'enum') {
+            ans = assignableIfTrue(!t.enumKind || t.enumKind === 'byte');
+        }
+        else {
+            ans = CheckResult.Nah;
+        }
+    }
+    else if (s.kind === 'byte_array' || s.kind === 'int_array' || s.kind === 'long_array') {
+        ans = strictlyAssignableIfTrue(t.kind === s.kind && areRangesMatch(s.lengthRange, t.lengthRange) && areRangesMatch(s.valueRange, t.valueRange));
+    }
+    else if (s.kind === 'struct' || s.kind === 'dispatcher') {
+        ans = assignableIfTrue(t.kind === 'struct' || t.kind === 'dispatcher');
+    }
+    else if (s.kind === 'enum') {
+        ans = assignableIfTrue((t.kind === 'byte' || t.kind === 'float' || t.kind === 'double' || t.kind === 'int' || t.kind === 'long' || t.kind === 'short' || t.kind === 'string') && (!s.enumKind || s.enumKind === t.kind));
+    }
+    else if (s.kind === 'float' || s.kind === 'double' || s.kind === 'int' || s.kind === 'long' || s.kind === 'short') {
+        if (t.kind === s.kind) {
+            ans = strictlyAssignableIfTrue(areRangesMatch(s.valueRange, t.valueRange));
+        }
+        else if (t.kind === 'enum') {
+            ans = assignableIfTrue(!t.enumKind || t.enumKind === s.kind);
+        }
+        else {
+            ans = CheckResult.Nah;
+        }
+    }
+    else if (s.kind === 'list') {
+        if (t.kind === 'list' && areRangesMatch(s.lengthRange, t.lengthRange)) {
+            ans = check(s.item, t.item, errors);
+        }
+        else {
+            ans = CheckResult.Nah;
+        }
+    }
+    else if (s.kind === 'string') {
+        if (t.kind === 'string') {
+            ans = CheckResult.StrictlyAssignable;
+        }
+        else {
+            ans = assignableIfTrue(t.kind === 'enum' && (!t.enumKind || t.enumKind === 'string'));
+        }
+    }
+    else {
+        ans = CheckResult.Nah;
+    }
+    if (!ans) {
+        errors.push((0, locales_1.localize)('mcdoc.checker.type-not-assignable', (0, locales_1.localeQuote)(McdocType.toString(s)), (0, locales_1.localeQuote)(McdocType.toString(t))));
+    }
+    return ans;
+};
+const checkAssignability = ({ source, target }) => {
+    if (source === undefined || target === undefined) {
+        return { isAssignable: true };
+    }
+    const errors = [];
+    check(source, target, errors);
+    return {
+        isAssignable: errors.length === 0,
+        ...errors.length ? { errorMessage: errors.reverse().map((m, i) => `${'  '.repeat(i)}${m}`).join('\n') } : {},
+    };
+};
+exports.checkAssignability = checkAssignability;
+function resolveType(inputType, ctx, value) {
+    const type = getTangibleType(inputType, ctx, value);
+    let ans = (() => {
+        if (type.kind === 'union') {
+            return {
+                kind: 'union',
+                members: type.members.map(t => resolveType(t, ctx, value)),
+                attributes: type.attributes,
+            };
+        }
+        else {
+            return {
+                ...type,
+                indices: undefined,
+            };
+        }
+    })();
+    for (const parallelIndices of type.indices ?? []) {
+        ans = navigateParallelIndices(ans, parallelIndices, ctx, value);
+    }
+    return ans;
+}
+exports.resolveType = resolveType;
+function dispatchType(type, ctx) {
+    throw '// TODO';
+}
+function dereferenceType(type, ctx) {
+    throw '// TODO';
+}
+function getTangibleType(type, ctx, value) {
+    let ans;
+    if (type.kind === 'dispatcher') {
+        const dispatchedType = dispatchType(type, ctx);
+        return getTangibleType(dispatchedType, ctx, value);
+    }
+    else if (type.kind === 'reference') {
+        const dereferencedType = dereferenceType(type, ctx);
+        return getTangibleType(dereferencedType, ctx, value);
+    }
+    else if (type.kind === 'union') {
+        ans = mapUnion(type, t => getTangibleType(t, ctx, value));
+    }
+    else {
+        ans = type;
+    }
+    return ans;
+}
+function navigateParallelIndices(type, indices, ctx, value) {
+    if (indices.length === 1) {
+        return navigateIndex(type, indices[0], ctx, value);
+    }
+    else {
+        return {
+            kind: 'union',
+            members: indices.map(i => navigateIndex(type, i, ctx, value)),
+            attributes: type.attributes,
+        };
+    }
+}
+function navigateIndex(type, index, ctx, value) {
+    if (type.kind === 'struct') {
+        const key = index.kind === 'static'
+            ? typeof index.value === 'string' ? index.value : undefined // Special static indices have no meaning on structs.
+            : resolveDynamicIndex(index, value);
+        if (key === undefined) {
+            return createEmptyUnion(type.attributes);
+        }
+        const flatStruct = flattenStruct(type, ctx, value);
+        return resolveType(flatStruct.fields[key].type, ctx, value);
+    }
+    else if (type.kind === 'union') {
+        return mapUnion(type, t => navigateIndex(t, index, ctx, value));
+    }
+    else {
+        return createEmptyUnion(type.attributes);
+    }
+}
+function resolveDynamicIndex(index, value) {
+    for (const key of index.accessor) {
+        if (value === undefined) {
+            break;
+        }
+        if (typeof key === 'string') {
+            value = value.getValue(key);
+        }
+        else if (key.keyword === 'key') {
+            value = value.getKeyOnParent();
+        }
+        else if (key.keyword === 'parent') {
+            value = value.getParent();
+        }
+    }
+    return value?.asString();
+}
+function mapUnion(type, mapper) {
+    const ans = {
+        kind: 'union',
+        members: type.members.map(mapper),
+        attributes: type.attributes,
+        indices: type.indices,
+    };
+    return ans;
+}
+function flattenStruct(type, ctx, value) {
+    const ans = {
+        kind: 'flat_struct',
+        fields: Object.create(null),
+        attributes: type.attributes,
+        indices: type.indices,
+    };
+    for (const field of type.fields) {
+        if (field.kind === 'spread') {
+            const target = resolveType(field.type, ctx, value);
+            addAttributes(ans, ...target.attributes ?? []);
+            if (target.kind === 'struct') {
+                const flatTarget = flattenStruct(target, ctx, value);
+                for (const [key, value] of Object.entries(flatTarget)) {
+                    ans.fields[key] = value;
+                }
+            }
+        }
+        else {
+            ans.fields[field.key] = { type: field.type, symbol: field.symbol };
+        }
+    }
+    return ans;
+}
+function addAttributes(type, ...attributes) {
+    for (const attr of attributes) {
+        type.attributes ?? (type.attributes = []);
+        if (!type.attributes.some(a => a.name === attr.name)) {
+            type.attributes.push(attr);
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@spyglassmc/mcdoc",
+  "version": "0.1.0",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "author": "SPGoding",
+  "license": "MIT",
+  "directories": {
+    "test": "test/"
+  },
+  "scripts": {
+    "release": "npm publish",
+    "release:dry": "npm publish --dry-run"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SpyglassMC/Spyglass.git"
+  },
+  "homepage": "https://spyglassmc.com",
+  "bugs": {
+    "url": "https://github.com/SpyglassMC/Spyglass/issues"
+  },
+  "dependencies": {
+    "@spyglassmc/core": "0.1.2",
+    "@spyglassmc/locales": "0.1.2"
+  }
+}