@spyglassmc/mcdoc 0.2.0 → 0.3.0

package/lib/parser/index.js

@@ -1,6 +1,8 @@
 import * as core from '@spyglassmc/core';
 import { any, Arrayable, failOnEmpty, failOnError, Failure, map, optional, Range, repeat, ResourceLocation, select, sequence, setType, stopBefore, validate } from '@spyglassmc/core';
 import { arrayToMessage, localeQuote, localize } from '@spyglassmc/locales';
+import { RangeExclusiveChar } from '../node/index.js';
+import { LiteralNumberCaseInsensitiveSuffixes, NumericTypeFloatKinds, NumericTypeIntKinds, PrimitiveArrayValueKinds, StaticIndexKeywords } from '../type/index.js';
 /**
  * @returns A comment parser that accepts normal comments (`//`) and reports an error if it's a doc comment (`///`).
  *
@@ -143,7 +145,7 @@ function indexBody(options) {
     const index = select([
         {
             prefix: '%',
-            parser: literal(['%fallback', '%none', '%unknown'], { specialChars: new Set(['%']) }),
+            parser: literal(StaticIndexKeywords.map(v => `%${v}`), { specialChars: new Set(['%']) }),
         },
         {
             prefix: '"',
@@ -151,7 +153,9 @@ function indexBody(options) {
         },
         {
             prefix: '[',
-            parser: dynamicIndex,
+            parser: options?.noDynamic
+                ? validate(dynamicIndex, () => false, localize('mcdoc.parser.index-body.dynamic-index-not-allowed'))
+                : dynamicIndex,
         },
         {
             parser: any([resLoc({ category: 'mcdoc/dispatcher', accessType: options?.accessType }), identifier]),
@@ -278,7 +282,7 @@ export const float = core.float({
 });
 export const typedNumber = setType('mcdoc:typed_number', sequence([
     float,
-    optional(keyword(['b', 'B', 'd', 'D', 'f', 'F', 'l', 'L', 's', 'S'], { colorTokenType: 'keyword' })),
+    optional(keyword(LiteralNumberCaseInsensitiveSuffixes, { colorTokenType: 'keyword' })),
 ]));
 const enumValue = select([
     { prefix: '"', parser: string },
@@ -313,29 +317,6 @@ export const enum_ = setType('mcdoc:enum', syntax([
     optional(failOnError(identifier)),
     enumBlock,
 ], true));
-const typeParam = setType('mcdoc:type_param', syntax([
-    identifier,
-    optional(syntax([failOnError(literal('extends')), path])),
-]));
-const typeParamBlock = setType('mcdoc:type_param_block', syntax([
-    punctuation('<'),
-    select([
-        { prefix: '>', parser: punctuation('>') },
-        {
-            parser: syntax([
-                typeParam,
-                syntaxRepeat(syntax([marker(','), failOnEmpty(typeParam)])),
-                optional(marker(',')),
-                punctuation('>'),
-            ]),
-        },
-    ]),
-]));
-const noop = () => undefined;
-const optionalTypeParamBlock = select([
-    { prefix: '<', parser: typeParamBlock },
-    { parser: noop },
-]);
 const structMapKey = setType('mcdoc:struct/map_key', syntax([
     punctuation('['),
     { get: () => type },
@@ -394,7 +375,6 @@ export const struct = setType('mcdoc:struct', syntax([
     prelim,
     keyword('struct'),
     optional(failOnEmpty(identifier)),
-    optionalTypeParamBlock,
     structBlock,
 ], true));
 const enumInjection = setType('mcdoc:injection/enum', syntax([
@@ -408,7 +388,6 @@ const enumInjection = setType('mcdoc:injection/enum', syntax([
 const structInjection = setType('mcdoc:injection/struct', syntax([
     literal('struct'),
     path,
-    optionalTypeParamBlock,
     structBlock,
 ]));
 export const injection = setType('mcdoc:injection', syntax([
@@ -418,8 +397,31 @@ export const injection = setType('mcdoc:injection', syntax([
         { parser: structInjection },
     ]),
 ]));
+const typeParam = setType('mcdoc:type_param', syntax([
+    identifier,
+    // optional(syntax([failOnError(literal('extends')), { get: () => type }])),
+]));
+const typeParamBlock = setType('mcdoc:type_param_block', syntax([
+    punctuation('<'),
+    select([
+        { prefix: '>', parser: punctuation('>') },
+        {
+            parser: syntax([
+                typeParam,
+                syntaxRepeat(syntax([marker(','), failOnEmpty(typeParam)])),
+                optional(marker(',')),
+                punctuation('>'),
+            ]),
+        },
+    ]),
+]));
+const noop = () => undefined;
+const optionalTypeParamBlock = select([
+    { prefix: '<', parser: typeParamBlock },
+    { parser: noop },
+]);
 export const typeAlias = setType('mcdoc:type_alias', syntax([
-    prelim,
+    docComments,
     keyword('type'),
     identifier,
     optionalTypeParamBlock,
@@ -458,11 +460,20 @@ export const integer = core.integer({
     pattern: /^(?:0|[-+]?[1-9][0-9]*)$/,
 });
 function range(type, number) {
+    const delimiterPredicate = (src) => src.tryPeek('..') || src.tryPeek(`${RangeExclusiveChar}..`);
+    const delimiterParser = literal([
+        '..',
+        `..${RangeExclusiveChar}`,
+        `${RangeExclusiveChar}..`,
+        `${RangeExclusiveChar}..${RangeExclusiveChar}`,
+    ], {
+        allowedChars: new Set(['.', RangeExclusiveChar]),
+    });
     return setType(type, select([
         {
-            prefix: '..',
+            predicate: delimiterPredicate,
             parser: sequence([
-                literal('..', { allowedChars: new Set('.') }),
+                delimiterParser,
                 number,
             ]),
         },
@@ -471,9 +482,9 @@ function range(type, number) {
                 stopBefore(number, '..'),
                 select([
                     {
-                        prefix: '..',
+                        predicate: delimiterPredicate,
                         parser: sequence([
-                            literal('..', { allowedChars: new Set('.') }),
+                            delimiterParser,
                             optional(failOnEmpty(number)),
                         ]),
                     },
@@ -483,7 +494,7 @@ function range(type, number) {
         },
     ]));
 }
-const intRange = range('mcdoc:int_range', integer);
+export const intRange = range('mcdoc:int_range', integer);
 const atIntRange = optional((src, ctx) => {
     if (!src.trySkip('@')) {
         return Failure;
@@ -500,7 +511,7 @@ export const literalType = typeBase('mcdoc:type/literal', select([
     { prefix: '"', parser: failOnEmpty(string) },
     { parser: failOnError(typedNumber) },
 ]));
-const floatRange = range('mcdoc:float_range', float);
+export const floatRange = range('mcdoc:float_range', float);
 const atFloatRange = optional((src, ctx) => {
     if (!src.trySkip('@')) {
         return Failure;
@@ -510,21 +521,21 @@ const atFloatRange = optional((src, ctx) => {
 });
 export const numericType = typeBase('mcdoc:type/numeric_type', select([
     {
-        predicate: src => src.tryPeek('float') || src.tryPeek('double'),
+        predicate: src => NumericTypeFloatKinds.some(k => src.tryPeek(k)),
         parser: syntax([
-            keyword(['float', 'double'], { colorTokenType: 'type' }),
+            keyword(NumericTypeFloatKinds, { colorTokenType: 'type' }),
             atFloatRange,
         ]),
     },
     {
         parser: syntax([
-            keyword(['byte', 'short', 'int', 'long'], { colorTokenType: 'type' }),
+            keyword(NumericTypeIntKinds, { colorTokenType: 'type' }),
             atIntRange,
         ]),
     },
 ]));
 export const primitiveArrayType = typeBase('mcdoc:type/primitive_array', syntax([
-    literal(['byte', 'int', 'long']),
+    literal(PrimitiveArrayValueKinds),
     atIntRange,
     keyword('[]', { allowedChars: new Set(['[', ']']), colorTokenType: 'type' }),
     atIntRange,
@@ -569,7 +580,7 @@ export const unionType = typeBase('mcdoc:type/union', syntax([
         },
     ]),
 ]));
-export const pathType = typeBase('mcdoc:type/path', syntax([
+export const referenceType = typeBase('mcdoc:type/reference', syntax([
     path,
     optional(syntax([
         marker('<'),
@@ -599,6 +610,6 @@ export const type = any([
     struct,
     tupleType,
     unionType,
-    pathType,
+    referenceType,
 ]);
 //# sourceMappingURL=index.js.map

package/lib/type/index.d.ts

@@ -1,32 +1,43 @@
-import type { FullResourceLocation, ProcessorContext, SymbolPath } from '@spyglassmc/core';
-import type { EnumKind } from '../node/index.js';
+import type { FullResourceLocation, ProcessorContext } from '@spyglassmc/core';
+import type { EnumKind, RangeKind } from '../node/index.js';
 export interface Attribute {
     name: string;
-    value: AttributeValue;
+    value?: AttributeValue;
 }
-export declare type AttributeValue = string | {
+export declare type AttributeValue = McdocType | {
+    kind: 'tree';
+    values: AttributeTree;
+};
+export declare type AttributeTree = {
     [key: string | number]: AttributeValue;
 };
-export declare type NumericRange = [number | undefined, number | undefined];
-interface StaticIndex {
+export declare type NumericRange = {
+    kind: RangeKind;
+    min?: number;
+    max?: number;
+};
+export declare const StaticIndexKeywords: readonly ["fallback", "none", "unknown"];
+export declare type StaticIndexKeyword = typeof StaticIndexKeywords[number];
+export interface StaticIndex {
     kind: 'static';
-    value: string | {
-        keyword: 'fallback' | 'none' | 'unknown';
-    };
+    value: string;
 }
-interface DynamicIndex {
+export interface DynamicIndex {
     kind: 'dynamic';
     accessor: (string | {
         keyword: 'key' | 'parent';
     })[];
 }
 export declare type Index = StaticIndex | DynamicIndex;
-export declare type ParallelIndices = [Index, ...Index[]];
+/**
+ * Corresponds to the IndexBodyNode
+ */
+export declare type ParallelIndices = Index[];
 export interface DispatcherData {
-    registry: FullResourceLocation | undefined;
+    registry: FullResourceLocation;
     index: ParallelIndices;
 }
-interface TypeBase {
+export interface TypeBase {
     kind: string;
     attributes?: Attribute[];
     indices?: ParallelIndices[];
@@ -36,28 +47,35 @@ export interface DispatcherType extends TypeBase, DispatcherData {
 }
 export interface StructType extends TypeBase {
     kind: 'struct';
-    fields: ({
-        kind: 'field';
-        key: string;
-        type: McdocType;
-        symbol: SymbolPath;
-    } | {
-        kind: 'spread';
-        type: McdocType;
-    })[];
+    fields: StructTypeField[];
+}
+export declare type StructTypeField = StructTypePairField | StructTypeSpreadField;
+export interface StructTypePairField {
+    kind: 'pair';
+    attributes?: Attribute[];
+    key: string | McdocType;
+    type: McdocType;
+    optional?: boolean;
+}
+export interface StructTypeSpreadField {
+    kind: 'spread';
+    attributes?: Attribute[];
+    type: McdocType;
 }
 export interface EnumType extends TypeBase {
     kind: 'enum';
-    enumKind: EnumKind;
-    values: {
-        identifier: string;
-        value: string | number | bigint;
-    }[];
+    enumKind?: EnumKind;
+    values: EnumTypeField[];
+}
+export interface EnumTypeField {
+    attributes?: Attribute[];
+    identifier: string;
+    value: string | number | bigint;
 }
 export interface ReferenceType extends TypeBase {
     kind: 'reference';
-    symbol?: SymbolPath;
-    index?: Index;
+    path?: string;
+    typeParameters?: McdocType[];
 }
 export interface UnionType<T extends McdocType = McdocType> extends TypeBase {
     kind: 'union';
@@ -65,14 +83,14 @@ export interface UnionType<T extends McdocType = McdocType> extends TypeBase {
 }
 export declare const EmptyUnion: UnionType<never> & NoIndices;
 export declare function createEmptyUnion(attributes?: Attribute[]): UnionType<never> & NoIndices;
-interface KeywordType extends TypeBase {
+export interface KeywordType extends TypeBase {
     kind: 'any' | 'boolean';
 }
-interface StringType extends TypeBase {
+export interface StringType extends TypeBase {
     kind: 'string';
     lengthRange?: NumericRange;
 }
-declare type LiteralValue = {
+export declare type LiteralValue = {
     kind: 'boolean';
     value: boolean;
 } | {
@@ -81,21 +99,35 @@ declare type LiteralValue = {
 } | {
     kind: 'number';
     value: number;
-    suffix: 'b' | 's' | 'L' | 'f' | 'd' | undefined;
+    suffix: 'b' | 's' | 'l' | 'f' | 'd' | undefined;
 };
-interface LiteralType extends TypeBase {
+export interface LiteralType extends TypeBase {
     kind: 'literal';
     value: LiteralValue;
 }
-interface NumericType extends TypeBase {
-    kind: 'byte' | 'short' | 'int' | 'long' | 'float' | 'double';
+export declare const LiteralNumberSuffixes: readonly ["b", "s", "l", "f", "d"];
+export declare type LiteralNumberSuffix = typeof LiteralNumberSuffixes[number];
+export declare const LiteralNumberCaseInsensitiveSuffixes: readonly ["b", "s", "l", "f", "d", "B", "S", "L", "F", "D"];
+export declare type LiteralNumberCaseInsensitiveSuffix = typeof LiteralNumberCaseInsensitiveSuffixes[number];
+export interface NumericType extends TypeBase {
+    kind: NumericTypeKind;
     valueRange?: NumericRange;
 }
-interface PrimitiveArrayType extends TypeBase {
+export declare const NumericTypeIntKinds: readonly ["byte", "short", "int", "long"];
+export declare type NumericTypeIntKind = typeof NumericTypeIntKinds[number];
+export declare const NumericTypeFloatKinds: readonly ["float", "double"];
+export declare type NumericTypeFloatKind = typeof NumericTypeFloatKinds[number];
+export declare const NumericTypeKinds: readonly ["byte", "short", "int", "long", "float", "double"];
+export declare type NumericTypeKind = typeof NumericTypeKinds[number];
+export interface PrimitiveArrayType extends TypeBase {
     kind: 'byte_array' | 'int_array' | 'long_array';
     valueRange?: NumericRange;
     lengthRange?: NumericRange;
 }
+export declare const PrimitiveArrayValueKinds: readonly ["byte", "int", "long"];
+export declare type PrimitiveArrayValueKind = typeof PrimitiveArrayValueKinds[number];
+export declare const PrimitiveArrayKinds: readonly ("byte_array" | "int_array" | "long_array")[];
+export declare type PrimitiveArrayKind = typeof PrimitiveArrayKinds[number];
 export interface ListType extends TypeBase {
     kind: 'list';
     item: McdocType;
@@ -130,10 +162,7 @@ declare type NoIndices = {
 };
 export interface FlatStructType extends TypeBase {
     kind: 'flat_struct';
-    fields: Record<string, {
-        type: McdocType;
-        symbol: SymbolPath;
-    }>;
+    fields: Record<string, McdocType>;
 }
 export declare const flattenUnionType: (union: UnionType) => UnionType;
 export declare const unionTypes: (a: McdocType, b: McdocType) => McdocType;

package/lib/type/index.js

@@ -1,5 +1,7 @@
 import { Arrayable } from '@spyglassmc/core';
 import { localeQuote, localize } from '@spyglassmc/locales';
+import { getRangeDelimiter } from '../node/index.js';
+export const StaticIndexKeywords = Object.freeze(['fallback', 'none', 'unknown']);
 export const EmptyUnion = Object.freeze({ kind: 'union', members: [] });
 export function createEmptyUnion(attributes) {
     return {
@@ -7,6 +9,13 @@ export function createEmptyUnion(attributes) {
         attributes,
     };
 }
+export const LiteralNumberSuffixes = Object.freeze(['b', 's', 'l', 'f', 'd']);
+export const LiteralNumberCaseInsensitiveSuffixes = Object.freeze([...LiteralNumberSuffixes, 'B', 'S', 'L', 'F', 'D']);
+export const NumericTypeIntKinds = Object.freeze(['byte', 'short', 'int', 'long']);
+export const NumericTypeFloatKinds = Object.freeze(['float', 'double']);
+export const NumericTypeKinds = Object.freeze([...NumericTypeIntKinds, ...NumericTypeFloatKinds]);
+export const PrimitiveArrayValueKinds = Object.freeze(['byte', 'int', 'long']);
+export const PrimitiveArrayKinds = Object.freeze(PrimitiveArrayValueKinds.map(kind => `${kind}_array`));
 export var McdocType;
 (function (McdocType) {
     function toString(type) {
@@ -14,8 +23,8 @@ export var McdocType;
             if (!range) {
                 return '';
             }
-            const [min, max] = range;
-            return min === max ? ` @ ${min}` : ` @ ${min ?? ''}..${max ?? ''}`;
+            const { kind, min, max } = range;
+            return min === max ? ` @ ${min}` : ` @ ${min ?? ''}${getRangeDelimiter(kind)}${max ?? ''}`;
         };
         const indicesToString = (indices) => {
             const strings = [];
@@ -63,7 +72,7 @@ export var McdocType;
             case 'long_array':
                 return `long${rangeToString(type.valueRange)}[]${rangeToString(type.lengthRange)}`;
             case 'reference':
-                return type.symbol?.path.join('::') ?? '<unknown_reference>';
+                return type.path ?? '<unknown_reference>';
             case 'short':
                 return `short${rangeToString(type.valueRange)}`;
             case 'string':
@@ -91,8 +100,8 @@ const areRangesMatch = (s, t) => {
     if (!s) {
         return false;
     }
-    const [sMin, sMax] = s;
-    const [tMin, tMax] = t;
+    const { min: sMin, max: sMax } = s;
+    const { min: tMin, max: tMax } = t;
     return (tMin === undefined || (sMin !== undefined && sMin >= tMin)) &&
         (tMax === undefined || (sMax !== undefined && sMax <= tMax));
 };
@@ -148,7 +157,7 @@ export const simplifyUnionType = (union) => {
 export const simplifyListType = (list) => ({
     kind: 'list',
     item: simplifyType(list.item),
-    ...list.lengthRange ? { lengthRange: [...list.lengthRange] } : {},
+    ...list.lengthRange ? { lengthRange: { ...list.lengthRange } } : {},
 });
 export const simplifyType = (data) => {
     if (data.kind === 'union') {
@@ -183,7 +192,7 @@ const check = (s, t, errors = []) => {
     }
     else if (s.kind === 'byte') {
         if (t.kind === 'boolean') {
-            ans = check(s, { kind: 'byte', valueRange: [0, 1] }, errors);
+            ans = check(s, { kind: 'byte', valueRange: { kind: 0b00, min: 0, max: 1 } }, errors);
         }
         else if (t.kind === 'byte') {
             ans = strictlyAssignableIfTrue(areRangesMatch(s.valueRange, t.valueRange));
@@ -317,7 +326,7 @@ function navigateIndex(type, index, ctx, value) {
             return createEmptyUnion(type.attributes);
         }
         const flatStruct = flattenStruct(type, ctx, value);
-        return resolveType(flatStruct.fields[key].type, ctx, value);
+        return resolveType(flatStruct.fields[key], ctx, value);
     }
     else if (type.kind === 'union') {
         return mapUnion(type, t => navigateIndex(t, index, ctx, value));
@@ -371,7 +380,12 @@ function flattenStruct(type, ctx, value) {
             }
         }
         else {
-            ans.fields[field.key] = { type: field.type, symbol: field.symbol };
+            if (typeof field.key === 'string') {
+                ans.fields[field.key] = field.type;
+            }
+            else {
+                // TODO: Handle map keys
+            }
         }
     }
     return ans;

package/lib/uri_processors.d.ts

@@ -0,0 +1,4 @@
+import type { UriBinder, UriSorterRegistration } from '@spyglassmc/core';
+export declare const uriBinder: UriBinder;
+export declare const uriSorter: UriSorterRegistration;
+//# sourceMappingURL=uri_processors.d.ts.map

package/lib/{binder/uriBinder.js → uri_processors.js}

@@ -1,5 +1,5 @@
 import { fileUtil } from '@spyglassmc/core';
-import { segToIdentifier } from './util.js';
+import { segToIdentifier } from './common.js';
 const Extension = '.mcdoc';
 const McdocRootPrefix = 'mcdoc/';
 export const uriBinder = (uris, ctx) => {
@@ -34,13 +34,20 @@ export const uriBinder = (uris, ctx) => {
             .query(uri, 'mcdoc', segToIdentifier(rel.split('/')))
             .ifKnown(() => { })
             .elseEnter({
-            data: {
-                subcategory: 'module',
-            },
-            usage: {
-                type: 'implementation',
-            },
+            data: { subcategory: 'module' },
+            usage: { type: 'definition' },
         });
     }
 };
-//# sourceMappingURL=uriBinder.js.map
+export const uriSorter = (a, b, next) => {
+    if (a.endsWith(Extension) && !b.endsWith(Extension)) {
+        return -1;
+    }
+    else if (!a.endsWith(Extension) && b.endsWith(Extension)) {
+        return 1;
+    }
+    else {
+        return next(a, b);
+    }
+};
+//# sourceMappingURL=uri_processors.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spyglassmc/mcdoc",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -25,7 +25,7 @@
     "url": "https://github.com/SpyglassMC/Spyglass/issues"
   },
   "dependencies": {
-    "@spyglassmc/core": "0.2.0",
-    "@spyglassmc/locales": "0.2.0"
+    "@spyglassmc/core": "0.3.0",
+    "@spyglassmc/locales": "0.3.0"
   }
 }

package/lib/binder/uriBinder.d.ts

@@ -1,3 +0,0 @@
-import type { UriBinder } from '@spyglassmc/core';
-export declare const uriBinder: UriBinder;
-//# sourceMappingURL=uriBinder.d.ts.map

package/lib/checker/CheckerContext.d.ts

@@ -1,18 +0,0 @@
-import type * as core from '@spyglassmc/core';
-import type { Symbol } from '@spyglassmc/core';
-import type { Segments } from '../binder/index.js';
-export interface CheckerContext extends core.CheckerContext {
-    /**
-     * The current module's identifier.
-     */
-    modIdentifier: string;
-    /**
-     * The current module's segments.
-     */
-    modSeg: Segments;
-    /**
-     * The current module's symbol.
-     */
-    modSymbol: Symbol;
-}
-//# sourceMappingURL=CheckerContext.d.ts.map

package/lib/checker/CheckerContext.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=CheckerContext.js.map

package/lib/checker/entry.d.ts

@@ -1,4 +0,0 @@
-import type { Checker } from '@spyglassmc/core';
-import type { ModuleNode } from '../node/index.js';
-export declare const module_: Checker<ModuleNode>;
-//# sourceMappingURL=entry.d.ts.map