antlr4-c3 - npm Package Compare versions

Comparing version 3.0.0 to 3.0.1

lib/index.js

 "use strict";
+/*
+ * This file is released under the MIT license.
+ * Copyright (c) 2016, 2021 Mike Lischke
+ *
+ * See LICENSE file for more info.
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
@@ -3,0 +9,0 @@ if (k2 === undefined) k2 = k;

lib/src/ArrayType.js

 "use strict";
+/*
+ * This file is released under the MIT license.
+ * Copyright (c) 2023, Mike Lischke
+ *
+ * See LICENSE file for more info.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -3,0 +9,0 @@ exports.ArrayType = void 0;

lib/src/BaseSymbol.d.ts

@@ -5,5 +5,13 @@ import { ParseTree } from "antlr4ts/tree/ParseTree";
 import { type ISymbolTable } from "./SymbolTable";
+/**
+ * The root of the symbol table class hierarchy: a symbol can be any manageable entity (like a block), not only
+ * things like variables or classes.
+ * We are using a class hierarchy here, instead of an enum or similar, to allow for easy extension and certain
+ * symbols can so provide additional APIs for simpler access to their sub elements, if needed.
+ */
 export declare class BaseSymbol {
     #private;
+    /** The name of the symbol or empty if anonymous. */
     name: string;
+    /** Reference to the parse tree which contains this symbol. */
     context?: ParseTree;
@@ -15,16 +23,84 @@ readonly modifiers: Set<Modifier>;
     get firstSibling(): BaseSymbol | undefined;
+    /**
+     * @returns the symbol before this symbol in its scope.
+     */
     get previousSibling(): BaseSymbol | undefined;
+    /**
+     * @returns the symbol following this symbol in its scope.
+     */
     get nextSibling(): BaseSymbol | undefined;
     get lastSibling(): BaseSymbol | undefined;
+    /**
+     * @returns the next symbol in definition order, regardless of the scope.
+     */
     get next(): BaseSymbol | undefined;
+    /**
+     * @returns the outermost entity (below the symbol table) that holds us.
+     */
     get root(): BaseSymbol | undefined;
+    /**
+     * @returns the symbol table we belong too or undefined if we are not yet assigned.
+     */
     get symbolTable(): ISymbolTable | undefined;
+    /**
+     * @returns the list of symbols from this one up to root.
+     */
     get symbolPath(): BaseSymbol[];
+    /**
+     * This is rather an internal method and should rarely be used by external code.
+     *
+     * @param parent The new parent to use.
+     */
     setParent(parent?: IScopedSymbol): void;
+    /**
+     * Remove this symbol from its parent scope.
+     */
     removeFromParent(): void;
+    /**
+     * Asynchronously looks up a symbol with a given name, in a bottom-up manner.
+     *
+     * @param name The name of the symbol to find.
+     * @param localOnly If true only child symbols are returned, otherwise also symbols from the parent of this symbol
+     *                  (recursively).
+     *
+     * @returns A promise resolving to the first symbol with a given name, in the order of appearance in this scope
+     *          or any of the parent scopes (conditionally).
+     */
     resolve(name: string, localOnly?: boolean): Promise<BaseSymbol | undefined>;
+    /**
+     * Synchronously looks up a symbol with a given name, in a bottom-up manner.
+     *
+     * @param name The name of the symbol to find.
+     * @param localOnly If true only child symbols are returned, otherwise also symbols from the parent of this symbol
+     *                  (recursively).
+     *
+     * @returns the first symbol with a given name, in the order of appearance in this scope
+     *          or any of the parent scopes (conditionally).
+     */
     resolveSync(name: string, localOnly?: boolean): BaseSymbol | undefined;
+    /**
+     * @param t The type of objects to return.
+     *
+     * @returns the next enclosing parent of the given type.
+     */
     getParentOfType<T extends BaseSymbol>(t: SymbolConstructor<T, unknown[]>): T | undefined;
+    /**
+     * Creates a qualified identifier from this symbol and its parent.
+     * If `full` is true then all parents are traversed in addition to this instance.
+     *
+     * @param separator The string to be used between the parts.
+     * @param full A flag indicating if the full path is to be returned.
+     * @param includeAnonymous Use a special string for empty scope names.
+     *
+     * @returns the constructed qualified identifier.
+     */
     qualifiedName(separator?: string, full?: boolean, includeAnonymous?: boolean): string;
+    /**
+     * Type guard to check for ISymbolTable.
+     *
+     * @param candidate The object to check.
+     *
+     * @returns true if the object is a symbol table.
+     */
     private isSymbolTable;
 }

lib/src/BaseSymbol.js

 "use strict";
+/*
+ * This file is released under the MIT license.
+ * Copyright (c) 2023, Mike Lischke
+ *
+ * See LICENSE file for more info.
+ */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
@@ -26,2 +32,8 @@ function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
 const types_1 = require("./types");
+/**
+ * The root of the symbol table class hierarchy: a symbol can be any manageable entity (like a block), not only
+ * things like variables or classes.
+ * We are using a class hierarchy here, instead of an enum or similar, to allow for easy extension and certain
+ * symbols can so provide additional APIs for simpler access to their sub elements, if needed.
+ */
 class BaseSymbol {
@@ -44,2 +56,5 @@ constructor(name = "") {
     }
+    /**
+     * @returns the symbol before this symbol in its scope.
+     */
     get previousSibling() {
@@ -54,2 +69,5 @@ if (!__classPrivateFieldGet(this, _BaseSymbol_parent, "f")) {
     }
+    /**
+     * @returns the symbol following this symbol in its scope.
+     */
     get nextSibling() {
@@ -63,2 +81,5 @@ var _a;
     }
+    /**
+     * @returns the next symbol in definition order, regardless of the scope.
+     */
     get next() {
@@ -68,2 +89,5 @@ var _a;
     }
+    /**
+     * @returns the outermost entity (below the symbol table) that holds us.
+     */
     get root() {
@@ -79,2 +103,5 @@ let run = __classPrivateFieldGet(this, _BaseSymbol_parent, "f");
     }
+    /**
+     * @returns the symbol table we belong too or undefined if we are not yet assigned.
+     */
     get symbolTable() {
@@ -93,4 +120,8 @@ if (this.isSymbolTable(this)) {
     }
+    /**
+     * @returns the list of symbols from this one up to root.
+     */
     get symbolPath() {
         const result = [];
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
         let run = this;
@@ -106,5 +137,13 @@ while (run) {
     }
+    /**
+     * This is rather an internal method and should rarely be used by external code.
+     *
+     * @param parent The new parent to use.
+     */
     setParent(parent) {
         __classPrivateFieldSet(this, _BaseSymbol_parent, parent, "f");
     }
+    /**
+     * Remove this symbol from its parent scope.
+     */
     removeFromParent() {
@@ -115,2 +154,12 @@ var _a;
     }
+    /**
+     * Asynchronously looks up a symbol with a given name, in a bottom-up manner.
+     *
+     * @param name The name of the symbol to find.
+     * @param localOnly If true only child symbols are returned, otherwise also symbols from the parent of this symbol
+     *                  (recursively).
+     *
+     * @returns A promise resolving to the first symbol with a given name, in the order of appearance in this scope
+     *          or any of the parent scopes (conditionally).
+     */
     resolve(name, localOnly = false) {
@@ -122,2 +171,12 @@ var _a;
     }
+    /**
+     * Synchronously looks up a symbol with a given name, in a bottom-up manner.
+     *
+     * @param name The name of the symbol to find.
+     * @param localOnly If true only child symbols are returned, otherwise also symbols from the parent of this symbol
+     *                  (recursively).
+     *
+     * @returns the first symbol with a given name, in the order of appearance in this scope
+     *          or any of the parent scopes (conditionally).
+     */
     resolveSync(name, localOnly = false) {
@@ -127,2 +186,7 @@ var _a;
     }
+    /**
+     * @param t The type of objects to return.
+     *
+     * @returns the next enclosing parent of the given type.
+     */
     getParentOfType(t) {
@@ -138,2 +202,12 @@ let run = __classPrivateFieldGet(this, _BaseSymbol_parent, "f");
     }
+    /**
+     * Creates a qualified identifier from this symbol and its parent.
+     * If `full` is true then all parents are traversed in addition to this instance.
+     *
+     * @param separator The string to be used between the parts.
+     * @param full A flag indicating if the full path is to be returned.
+     * @param includeAnonymous Use a special string for empty scope names.
+     *
+     * @returns the constructed qualified identifier.
+     */
     qualifiedName(separator = ".", full = false, includeAnonymous = false) {
@@ -156,2 +230,9 @@ if (!includeAnonymous && this.name.length === 0) {
     }
+    /**
+     * Type guard to check for ISymbolTable.
+     *
+     * @param candidate The object to check.
+     *
+     * @returns true if the object is a symbol table.
+     */
     isSymbolTable(candidate) {
@@ -158,0 +239,0 @@ return candidate.info !== undefined;

lib/src/BlockSymbol.js

 "use strict";
+/*
+ * This file is released under the MIT license.
+ * Copyright (c) 2023, Mike Lischke
+ *
+ * See LICENSE file for more info.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -3,0 +9,0 @@ exports.BlockSymbol = void 0;

lib/src/ClassSymbol.d.ts

@@ -6,6 +6,9 @@ import { Type, ReferenceKind, TypeKind } from "./types";
 import { ScopedSymbol } from "./ScopedSymbol";
+/** Classes and structs. */
 export declare class ClassSymbol extends ScopedSymbol implements Type {
     isStruct: boolean;
     reference: ReferenceKind;
+    /** Usually only one member, unless the language supports multiple inheritance (like C++). */
     readonly extends: ClassSymbol[];
+    /** Typescript allows a class to implement a class, not only interfaces. */
     readonly implements: Array<ClassSymbol | InterfaceSymbol>;
@@ -15,4 +18,14 @@ constructor(name: string, ext: ClassSymbol[], impl: Array<ClassSymbol | InterfaceSymbol>);
     get kind(): TypeKind;
+    /**
+     * @param includeInherited Not used.
+     *
+     * @returns a list of all methods.
+     */
     getMethods(includeInherited?: boolean): Promise<MethodSymbol[]>;
+    /**
+     * @param includeInherited Not used.
+     *
+     * @returns all fields.
+     */
     getFields(includeInherited?: boolean): Promise<FieldSymbol[]>;
 }

lib/src/ClassSymbol.js

 "use strict";
+/*
+ * This file is released under the MIT license.
+ * Copyright (c) 2023, Mike Lischke
+ *
+ * See LICENSE file for more info.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -8,2 +14,3 @@ exports.ClassSymbol = void 0;
 const ScopedSymbol_1 = require("./ScopedSymbol");
+/** Classes and structs. */
 class ClassSymbol extends ScopedSymbol_1.ScopedSymbol {
@@ -19,5 +26,15 @@ constructor(name, ext, impl) {
     get kind() { return types_1.TypeKind.Class; }
+    /**
+     * @param includeInherited Not used.
+     *
+     * @returns a list of all methods.
+     */
     getMethods(includeInherited = false) {
         return this.getSymbolsOfType(MethodSymbol_1.MethodSymbol);
     }
+    /**
+     * @param includeInherited Not used.
+     *
+     * @returns all fields.
+     */
     getFields(includeInherited = false) {
@@ -24,0 +41,0 @@ return this.getSymbolsOfType(FieldSymbol_1.FieldSymbol);

lib/src/CodeCompletionCore.d.ts

@@ -38,9 +38,80 @@ import { Parser, ParserRuleContext } from "antlr4ts";
     constructor(parser: Parser);
+    /**
+     * This is the main entry point. The caret token index specifies the token stream index for the token which
+     * currently covers the caret (or any other position you want to get code completion candidates for).
+     * Optionally you can pass in a parser rule context which limits the ATN walk to only that or called rules.
+     * This can significantly speed up the retrieval process but might miss some candidates (if they are outside of
+     * the given context).
+     *
+     * @param caretTokenIndex The index of the token at the caret position.
+     * @param context An option parser rule context to limit the search space.
+     * @returns The collection of completion candidates.
+     */
     collectCandidates(caretTokenIndex: number, context?: ParserRuleContext): CandidatesCollection;
+    /**
+     * Checks if the predicate associated with the given transition evaluates to true.
+     *
+     * @param transition The transition to check.
+     * @returns the evaluation result of the predicate.
+     */
     private checkPredicate;
+    /**
+     * Walks the rule chain upwards or downwards (depending on translateRulesTopDown) to see if that matches any of the
+     * preferred rules. If found, that rule is added to the collection candidates and true is returned.
+     *
+     * @param ruleWithStartTokenList The list to convert.
+     * @returns true if any of the stack entries was converted.
+     */
     private translateStackToRuleIndex;
+    /**
+     * Given the index of a rule from a rule chain, check if that matches any of the preferred rules. If it matches,
+     * that rule is added to the collection candidates and true is returned.
+     *
+     * @param i The rule index.
+     * @param ruleWithStartTokenList The list to check.
+     * @returns true if the specified rule is in the list of preferred rules.
+     */
     private translateToRuleIndex;
+    /**
+     * This method follows the given transition and collects all symbols within the same rule that directly follow it
+     * without intermediate transitions to other rules and only if there is a single symbol for a transition.
+     *
+     * @param transition The transition from which to start.
+     * @returns A list of toke types.
+     */
     private getFollowingTokens;
+    /**
+     * Entry point for the recursive follow set collection function.
+     *
+     * @param start Start state.
+     * @param stop Stop state.
+     * @returns Follow sets.
+     */
     private determineFollowSets;
+    /**
+     * Collects possible tokens which could be matched following the given ATN state. This is essentially the same
+     * algorithm as used in the LL1Analyzer class, but here we consider predicates also and use no parser rule context.
+     *
+     * @param s The state to continue from.
+     * @param stopState The state which ends the collection routine.
+     * @param followSets A pass through parameter to add found sets to.
+     * @param stateStack A stack to avoid endless recursions.
+     * @param ruleStack The current rule stack.
+     * @returns true if the follow sets is exhaustive, i.e. we terminated before the rule end was reached, so no
+     * subsequent rules could add tokens
+     */
     private collectFollowSets;
+    /**
+     * Walks the ATN for a single rule only. It returns the token stream position for each path that could be matched
+     * in this rule.
+     * The result can be empty in case we hit only non-epsilon transitions that didn't match the current input or if we
+     * hit the caret position.
+     *
+     * @param startState The start state.
+     * @param tokenListIndex The token index we are currently at.
+     * @param callStack The stack that indicates where in the ATN we are currently.
+     * @param precedence The current precedence level.
+     * @param indentation A value to determine the current indentation when doing debug prints.
+     * @returns the set of token stream indexes (which depend on the ways that had to be taken).
+     */
     private processRule;
@@ -47,0 +118,0 @@ private generateBaseDescription;

lib/src/CodeCompletionCore.js

 "use strict";
+/*
+ * This file is released under the MIT license.
+ * Copyright (c) 2016, 2021, Mike Lischke
+ *
+ * See LICENSE file for more info.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CodeCompletionCore = exports.CandidatesCollection = void 0;
+/* eslint-disable max-classes-per-file */
 const antlr4ts_1 = require("antlr4ts");
 const atn_1 = require("antlr4ts/atn");
 const IntervalSet_1 = require("antlr4ts/misc/IntervalSet");
+// All the candidates which have been found. Tokens and rules are separated.
+// Token entries include a list of tokens that directly follow them (see also the "following" member in the
+// FollowSetWithPath class).
+// Rule entries include the index of the starting token within the evaluated rule, along with a call stack of rules
+// found during evaluation.
 class CandidatesCollection {
@@ -14,2 +26,7 @@ constructor() {
 exports.CandidatesCollection = CandidatesCollection;
+// A record for a follow set along with the path at which this set was found.
+// If there is only a single symbol in the interval set then we also collect and store tokens which follow
+// this symbol directly in its rule (i.e. there is no intermediate rule transition). Only single label transitions
+// are considered. This is useful if you have a chain of tokens which can be suggested as a whole, because there is
+// a fixed sequence in the grammar.
 class FollowSetWithPath {
@@ -21,14 +38,29 @@ constructor() {
 }
+// A list of follow sets (for a given state number) + all of them combined for quick hit tests + whether they are
+// exhaustive (false if subsequent yet-unprocessed rules could add further tokens to the follow set, true otherwise).
+// This data is static in nature (because the used ATN states are part of a static struct: the ATN).
+// Hence it can be shared between all C3 instances, however it depends on the actual parser class (type).
 class FollowSetsHolder {
 }
+// The main class for doing the collection process.
 class CodeCompletionCore {
     constructor(parser) {
+        // Debugging options. Print human readable ATN state and other info.
+        // Not dependent on showDebugOutput. Prints the collected rules + tokens to terminal.
         this.showResult = false;
+        // Enables printing ATN state info to terminal.
         this.showDebugOutput = false;
+        // Only relevant when showDebugOutput is true. Enables transition printing for a state.
         this.debugOutputWithTransitions = false;
+        // Also depends on showDebugOutput. Enables call stack printing for each rule recursion.
         this.showRuleStack = false;
+        // Specify if preferred rules should translated top-down (higher index rule returns first) or
+        // bottom-up (lower index rule returns first).
         this.translateRulesTopDown = false;
         this.tokenStartIndex = 0;
         this.statesProcessed = 0;
+        // A mapping of rule index + token stream position to end token positions.
+        // A rule which has been visited before with the same input position will always produce the same output positions.
         this.shortcutMap = new Map();
+        // The collected candidates (rules and tokens).
         this.candidates = new CandidatesCollection();
@@ -42,2 +74,13 @@ this.parser = parser;
     }
+    /**
+     * This is the main entry point. The caret token index specifies the token stream index for the token which
+     * currently covers the caret (or any other position you want to get code completion candidates for).
+     * Optionally you can pass in a parser rule context which limits the ATN walk to only that or called rules.
+     * This can significantly speed up the retrieval process but might miss some candidates (if they are outside of
+     * the given context).
+     *
+     * @param caretTokenIndex The index of the token at the caret position.
+     * @param context An option parser rule context to limit the search space.
+     * @returns The collection of completion candidates.
+     */
     collectCandidates(caretTokenIndex, context) {
@@ -61,2 +104,4 @@ this.shortcutMap.clear();
             }
+            // Do not check for the token index here, as we want to end with the first unhidden token on or after
+            // the caret.
             if (token.type === antlr4ts_1.Token.EOF) {
@@ -95,5 +140,18 @@ break;
     }
+    /**
+     * Checks if the predicate associated with the given transition evaluates to true.
+     *
+     * @param transition The transition to check.
+     * @returns the evaluation result of the predicate.
+     */
     checkPredicate(transition) {
         return transition.predicate.eval(this.parser, antlr4ts_1.ParserRuleContext.emptyContext());
     }
+    /**
+     * Walks the rule chain upwards or downwards (depending on translateRulesTopDown) to see if that matches any of the
+     * preferred rules. If found, that rule is added to the collection candidates and true is returned.
+     *
+     * @param ruleWithStartTokenList The list to convert.
+     * @returns true if any of the stack entries was converted.
+     */
     translateStackToRuleIndex(ruleWithStartTokenList) {
@@ -103,3 +161,6 @@ if (this.preferredRules.size === 0) {
         }
+        // Change the direction we iterate over the rule stack
         if (this.translateRulesTopDown) {
+            // Loop over the rule stack from lowest to highest rule level. This will prioritize a lower preferred rule
+            // if it is a child of a higher one that is also a preferred rule.
             for (let i = ruleWithStartTokenList.length - 1; i >= 0; i--) {
@@ -112,2 +173,4 @@ if (this.translateToRuleIndex(i, ruleWithStartTokenList)) {
         else {
+            // Loop over the rule stack from highest to lowest rule level. This will prioritize a higher preferred rule
+            // if it contains a lower one that is also a preferred rule.
             for (let i = 0; i < ruleWithStartTokenList.length; i++) {
@@ -121,5 +184,15 @@ if (this.translateToRuleIndex(i, ruleWithStartTokenList)) {
     }
+    /**
+     * Given the index of a rule from a rule chain, check if that matches any of the preferred rules. If it matches,
+     * that rule is added to the collection candidates and true is returned.
+     *
+     * @param i The rule index.
+     * @param ruleWithStartTokenList The list to check.
+     * @returns true if the specified rule is in the list of preferred rules.
+     */
     translateToRuleIndex(i, ruleWithStartTokenList) {
         const { ruleIndex, startTokenIndex } = ruleWithStartTokenList[i];
         if (this.preferredRules.has(ruleIndex)) {
+            // Add the rule to our candidates list along with the current rule path,
+            // but only if there isn't already an entry like that.
             const path = ruleWithStartTokenList.slice(0, i).map(({ ruleIndex: candidate }) => candidate);
@@ -131,2 +204,3 @@ let addNew = true;
                 }
+                // Found an entry for this rule. Same path? If so don't add a new (duplicate) entry.
                 if (path.every((v, j) => v === rule[1].ruleList[j])) {
@@ -150,2 +224,9 @@ addNew = false;
     }
+    /**
+     * This method follows the given transition and collects all symbols within the same rule that directly follow it
+     * without intermediate transitions to other rules and only if there is a single symbol for a transition.
+     *
+     * @param transition The transition from which to start.
+     * @returns A list of toke types.
+     */
     getFollowingTokens(transition) {
@@ -158,3 +239,3 @@ const result = [];
                 state.getTransitions().forEach((outgoing) => {
-                    if (outgoing.serializationType === 5) {
+                    if (outgoing.serializationType === 5 /* TransitionType.ATOM */) {
                         if (!outgoing.isEpsilon) {
@@ -176,2 +257,9 @@ const list = outgoing.label.toArray();
     }
+    /**
+     * Entry point for the recursive follow set collection function.
+     *
+     * @param start Start state.
+     * @param stop Stop state.
+     * @returns Follow sets.
+     */
     determineFollowSets(start, stop) {
@@ -182,2 +270,4 @@ const sets = [];
         const isExhaustive = this.collectFollowSets(start, stop, sets, stateStack, ruleStack);
+        // Sets are split by path to allow translating them to preferred rules. But for quick hit tests
+        // it is also useful to have a set with all symbols combined.
         const combined = new IntervalSet_1.IntervalSet();
@@ -189,2 +279,14 @@ for (const set of sets) {
     }
+    /**
+     * Collects possible tokens which could be matched following the given ATN state. This is essentially the same
+     * algorithm as used in the LL1Analyzer class, but here we consider predicates also and use no parser rule context.
+     *
+     * @param s The state to continue from.
+     * @param stopState The state which ends the collection routine.
+     * @param followSets A pass through parameter to add found sets to.
+     * @param stateStack A stack to avoid endless recursions.
+     * @param ruleStack The current rule stack.
+     * @returns true if the follow sets is exhaustive, i.e. we terminated before the rule end was reached, so no
+     * subsequent rules could add tokens
+     */
     collectFollowSets(s, stopState, followSets, stateStack, ruleStack) {
@@ -201,3 +303,3 @@ if (stateStack.find((x) => x === s)) {
         for (const transition of s.getTransitions()) {
-            if (transition.serializationType === 3) {
+            if (transition.serializationType === 3 /* TransitionType.RULE */) {
                 const ruleTransition = transition;
@@ -210,2 +312,4 @@ if (ruleStack.indexOf(ruleTransition.target.ruleIndex) !== -1) {
                 ruleStack.pop();
+                // If the subrule had an epsilon transition to the rule end, the tokens added to
+                // the follow set are non-exhaustive and we should continue processing subsequent transitions post-rule
                 if (!ruleFollowSetsIsExhaustive) {
@@ -216,3 +320,3 @@ const nextStateFollowSetsIsExhaustive = this.collectFollowSets(ruleTransition.followState, stopState, followSets, stateStack, ruleStack);
             }
-            else if (transition.serializationType === 4) {
+            else if (transition.serializationType === 4 /* TransitionType.PREDICATE */) {
                 if (this.checkPredicate(transition)) {
@@ -227,3 +331,3 @@ const nextStateFollowSetsIsExhaustive = this.collectFollowSets(transition.target, stopState, followSets, stateStack, ruleStack);
             }
-            else if (transition.serializationType === 9) {
+            else if (transition.serializationType === 9 /* TransitionType.WILDCARD */) {
                 const set = new FollowSetWithPath();
@@ -237,3 +341,3 @@ set.intervals = IntervalSet_1.IntervalSet.of(antlr4ts_1.Token.MIN_USER_TOKEN_TYPE, this.atn.maxTokenType);
                 if (label && label.size > 0) {
-                    if (transition.serializationType === 8) {
+                    if (transition.serializationType === 8 /* TransitionType.NOT_SET */) {
                         label = label.complement(IntervalSet_1.IntervalSet.of(antlr4ts_1.Token.MIN_USER_TOKEN_TYPE, this.atn.maxTokenType));
@@ -252,3 +356,18 @@ }
     }
+    /**
+     * Walks the ATN for a single rule only. It returns the token stream position for each path that could be matched
+     * in this rule.
+     * The result can be empty in case we hit only non-epsilon transitions that didn't match the current input or if we
+     * hit the caret position.
+     *
+     * @param startState The start state.
+     * @param tokenListIndex The token index we are currently at.
+     * @param callStack The stack that indicates where in the ATN we are currently.
+     * @param precedence The current precedence level.
+     * @param indentation A value to determine the current indentation when doing debug prints.
+     * @returns the set of token stream indexes (which depend on the ways that had to be taken).
+     */
     processRule(startState, tokenListIndex, callStack, precedence, indentation) {
+        // Start with rule specific handling before going into the ATN walk.
+        // Check first if we've taken this path with the same input before.
         let positionMap = this.shortcutMap.get(startState.ruleIndex);
@@ -268,2 +387,9 @@ if (!positionMap) {
         const result = new Set();
+        // For rule start states we determine and cache the follow set, which gives us 3 advantages:
+        // 1) We can quickly check if a symbol would be matched when we follow that rule. We can so check in advance
+        //    and can save us all the intermediate steps if there is no match.
+        // 2) We'll have all symbols that are collectable already together when we are at the caret on rule enter.
+        // 3) We get this lookup for free with any 2nd or further visit of the same rule, which often happens
+        //    in non trivial grammars, especially with (recursive) expressions and of course when invoking code
+        //    completion multiple times.
         let setsPerState = CodeCompletionCore.followSetsByATN.get(this.parser.constructor.name);
@@ -280,2 +406,3 @@ if (!setsPerState) {
         }
+        // Get the token index where our rule starts from our (possibly filtered) token list
         const startTokenIndex = this.tokens[tokenListIndex].tokenIndex;
@@ -286,9 +413,13 @@ callStack.push({
         });
-        if (tokenListIndex >= this.tokens.length - 1) {
+        if (tokenListIndex >= this.tokens.length - 1) { // At caret?
             if (this.preferredRules.has(startState.ruleIndex)) {
+                // No need to go deeper when collecting entries and we reach a rule that we want to collect anyway.
                 this.translateStackToRuleIndex(callStack);
             }
             else {
+                // Convert all follow sets to either single symbols or their associated preferred rule and add
+                // the result to our candidates list.
                 for (const set of followSets.sets) {
                     const fullPath = callStack.slice();
+                    // Rules derived from our followSet will always start at the same token as our current rule
                     const followSetPath = set.path.map((path) => ({
@@ -306,5 +437,7 @@ startTokenIndex,
                                 if (!this.candidates.tokens.has(symbol)) {
+                                    // Following is empty if there is more than one entry in the set.
                                     this.candidates.tokens.set(symbol, set.following);
                                 }
                                 else {
+                                    // More than one following list for the same symbol.
                                     if (this.candidates.tokens.get(symbol) !== set.following) {
@@ -320,2 +453,4 @@ this.candidates.tokens.set(symbol, []);
             if (!followSets.isExhaustive) {
+                // If we're at the caret but the follow sets is non-exhaustive (empty or all tokens are optional),
+                // we should continue to collect tokens following this rule
                 result.add(tokenListIndex);
@@ -327,2 +462,5 @@ }
         else {
+            // Process the rule if we either could pass it without consuming anything (epsilon transition)
+            // or if the current input symbol will be matched somewhere after this entry point.
+            // Otherwise stop here.
             const currentSymbol = this.tokens[tokenListIndex].type;
@@ -337,4 +475,7 @@ if (followSets.isExhaustive && !followSets.combined.contains(currentSymbol)) {
         }
+        // The current state execution pipeline contains all yet-to-be-processed ATN states in this rule.
+        // For each such state we store the token index + a list of rules that lead to it.
         const statePipeline = [];
         let currentEntry;
+        // Bootstrap the pipeline.
         statePipeline.push({ state: startState, tokenListIndex });
@@ -353,2 +494,3 @@ while (statePipeline.length > 0) {
             if (currentEntry.state.stateType === atn_1.ATNStateType.RULE_STOP) {
+                // Record the token index we are at, to report it to the caller.
                 result.add(currentEntry.tokenListIndex);
@@ -358,5 +500,7 @@ continue;
             const transitions = currentEntry.state.getTransitions();
+            // We simulate here the same precedence handling as the parser does, which uses hard coded values.
+            // For rules that are not left recursive this value is ignored (since there is no precedence transition).
             for (const transition of transitions) {
                 switch (transition.serializationType) {
-                    case 3: {
+                    case 3 /* TransitionType.RULE */: {
                         const ruleTransition = transition;
@@ -372,3 +516,3 @@ const endStatus = this.processRule(transition.target, currentEntry.tokenListIndex, callStack, ruleTransition.precedence, indentation + 1);
                     }
-                    case 4: {
+                    case 4 /* TransitionType.PREDICATE */: {
                         if (this.checkPredicate(transition)) {
@@ -382,3 +526,3 @@ statePipeline.push({
                     }
-                    case 10: {
+                    case 10 /* TransitionType.PRECEDENCE */: {
                         const predTransition = transition;
@@ -393,3 +537,3 @@ if (predTransition.precedence >= this.precedenceStack[this.precedenceStack.length - 1]) {
                     }
-                    case 9: {
+                    case 9 /* TransitionType.WILDCARD */: {
                         if (atCaret) {
@@ -415,2 +559,3 @@ if (!this.translateStackToRuleIndex(callStack)) {
                         if (transition.isEpsilon) {
+                            // Jump over simple states with a single outgoing epsilon transition.
                             statePipeline.push({
@@ -424,3 +569,3 @@ state: transition.target,
                         if (set && set.size > 0) {
-                            if (transition.serializationType === 8) {
+                            if (transition.serializationType === 8 /* TransitionType.NOT_SET */) {
                                 set = set.complement(IntervalSet_1.IntervalSet.of(antlr4ts_1.Token.MIN_USER_TOKEN_TYPE, this.atn.maxTokenType));
@@ -467,2 +612,3 @@ }
         }
+        // Cache the result, for later lookup to avoid duplicate walks.
         positionMap.set(tokenListIndex, result);
@@ -485,2 +631,3 @@ return result;
                 if (symbols.length > 2) {
+                    // Only print start and end symbols to avoid large lists in debug output.
                     labels = this.vocabulary.getDisplayName(symbols[0]) + " .. " +
@@ -487,0 +634,0 @@ this.vocabulary.getDisplayName(symbols[symbols.length - 1]);

lib/src/DuplicateSymbolError.js

 "use strict";
+/*
+ * This file is released under the MIT license.
+ * Copyright (c) 2023, Mike Lischke
+ *
+ * See LICENSE file for more info.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -3,0 +9,0 @@ exports.DuplicateSymbolError = void 0;

lib/src/FieldSymbol.d.ts

 import { MethodSymbol } from "./MethodSymbol";
 import { VariableSymbol } from "./VariableSymbol";
+/** A field which belongs to a class or other outer container structure. */
 export declare class FieldSymbol extends VariableSymbol {
@@ -4,0 +5,0 @@ setter?: MethodSymbol;

lib/src/FieldSymbol.js

 "use strict";
+/*
+ * This file is released under the MIT license.
+ * Copyright (c) 2023, Mike Lischke
+ *
+ * See LICENSE file for more info.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FieldSymbol = void 0;
 const VariableSymbol_1 = require("./VariableSymbol");
+/** A field which belongs to a class or other outer container structure. */
 class FieldSymbol extends VariableSymbol_1.VariableSymbol {
@@ -6,0 +13,0 @@ }

lib/src/FundamentalType.d.ts

 import { Type, TypeKind, ReferenceKind } from "./types";
+/** A single class for all fundamental types. They are distinguished via the kind field. */
 export declare class FundamentalType implements Type {
@@ -3,0 +4,0 @@ static readonly integerType: FundamentalType;

lib/src/FundamentalType.js

 "use strict";
+/*
+ * This file is released under the MIT license.
+ * Copyright (c) 2023, Mike Lischke
+ *
+ * See LICENSE file for more info.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FundamentalType = void 0;
 const types_1 = require("./types");
+/** A single class for all fundamental types. They are distinguished via the kind field. */
 class FundamentalType {
@@ -6,0 +13,0 @@ constructor(name, typeKind = types_1.TypeKind.Unknown, referenceKind = types_1.ReferenceKind.Irrelevant) {

lib/src/InterfaceSymbol.d.ts

@@ -8,2 +8,3 @@ import { Type, ReferenceKind, TypeKind } from "./types";
     reference: ReferenceKind;
+    /** Typescript allows an interface to extend a class, not only interfaces. */
     readonly extends: Array<ClassSymbol | InterfaceSymbol>;
@@ -13,4 +14,14 @@ constructor(name: string, ext: Array<ClassSymbol | InterfaceSymbol>);
     get kind(): TypeKind;
+    /**
+     * @param includeInherited Not used.
+     *
+     * @returns a list of all methods.
+     */
     getMethods(includeInherited?: boolean): Promise<MethodSymbol[]>;
+    /**
+     * @param includeInherited Not used.
+     *
+     * @returns all fields.
+     */
     getFields(includeInherited?: boolean): Promise<FieldSymbol[]>;
 }

lib/src/InterfaceSymbol.js

 "use strict";
+/*
+ * This file is released under the MIT license.
+ * Copyright (c) 2023, Mike Lischke
+ *
+ * See LICENSE file for more info.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -16,5 +22,15 @@ exports.InterfaceSymbol = void 0;
     get kind() { return types_1.TypeKind.Interface; }
+    /**
+     * @param includeInherited Not used.
+     *
+     * @returns a list of all methods.
+     */
     getMethods(includeInherited = false) {
         return this.getSymbolsOfType(MethodSymbol_1.MethodSymbol);
     }
+    /**
+     * @param includeInherited Not used.
+     *
+     * @returns all fields.
+     */
     getFields(includeInherited = false) {
@@ -21,0 +37,0 @@ return this.getSymbolsOfType(FieldSymbol_1.FieldSymbol);

lib/src/LiteralSymbol.js

 "use strict";
+/*
+ * This file is released under the MIT license.
+ * Copyright (c) 2023, Mike Lischke
+ *
+ * See LICENSE file for more info.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -3,0 +9,0 @@ exports.LiteralSymbol = void 0;

lib/src/MethodSymbol.d.ts

@@ -7,7 +7,10 @@ import { RoutineSymbol } from "./RoutineSymbol";
     Overwritten = 4,
+    /** Distinguished by the return type. */
     SetterOrGetter = 8,
+    /** Special flag used e.g. in C++ for explicit c-tors. */
     Explicit = 16
 }
+/** A function which belongs to a class or other outer container structure. */
 export declare class MethodSymbol extends RoutineSymbol {
     methodFlags: MethodFlags;
 }

lib/src/MethodSymbol.js

 "use strict";
+/*
+ * This file is released under the MIT license.
+ * Copyright (c) 2023, Mike Lischke
+ *
+ * See LICENSE file for more info.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -11,5 +17,8 @@ exports.MethodSymbol = exports.MethodFlags = void 0;
     MethodFlags[MethodFlags["Overwritten"] = 4] = "Overwritten";
+    /** Distinguished by the return type. */
     MethodFlags[MethodFlags["SetterOrGetter"] = 8] = "SetterOrGetter";
+    /** Special flag used e.g. in C++ for explicit c-tors. */
     MethodFlags[MethodFlags["Explicit"] = 16] = "Explicit";
 })(MethodFlags = exports.MethodFlags || (exports.MethodFlags = {}));
+/** A function which belongs to a class or other outer container structure. */
 class MethodSymbol extends RoutineSymbol_1.RoutineSymbol {
@@ -16,0 +25,0 @@ constructor() {

lib/src/NamespaceSymbol.js

 "use strict";
+/*
+ * This file is released under the MIT license.
+ * Copyright (c) 2023, Mike Lischke
+ *
+ * See LICENSE file for more info.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -3,0 +9,0 @@ exports.NamespaceSymbol = void 0;

lib/src/ParameterSymbol.js

 "use strict";
+/*
+ * This file is released under the MIT license.
+ * Copyright (c) 2023, Mike Lischke
+ *
+ * See LICENSE file for more info.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -3,0 +9,0 @@ exports.ParameterSymbol = void 0;

lib/src/RoutineSymbol.d.ts

@@ -5,2 +5,3 @@ import { ParameterSymbol } from "./ParameterSymbol";
 import { Type } from "./types";
+/** A standalone function/procedure/rule. */
 export declare class RoutineSymbol extends ScopedSymbol {
@@ -7,0 +8,0 @@ returnType?: Type;

lib/src/RoutineSymbol.js

 "use strict";
+/*
+ * This file is released under the MIT license.
+ * Copyright (c) 2023, Mike Lischke
+ *
+ * See LICENSE file for more info.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -7,2 +13,3 @@ exports.RoutineSymbol = void 0;
 const VariableSymbol_1 = require("./VariableSymbol");
+/** A standalone function/procedure/rule. */
 class RoutineSymbol extends ScopedSymbol_1.ScopedSymbol {
@@ -9,0 +16,0 @@ constructor(name, returnType) {

lib/src/ScopedSymbol.d.ts

 import { SymbolConstructor } from "./types";
 import { BaseSymbol } from "./BaseSymbol";
+/** Defines the  */
 export interface IScopedSymbol extends BaseSymbol {
+    /**
+     * @returns A promise resolving to all direct child symbols with a scope (e.g. classes in a module).
+     */
     directScopes: Promise<ScopedSymbol[]>;
@@ -9,22 +13,124 @@ children: BaseSymbol[];
     clear(): void;
+    /**
+     * Adds the given symbol to this scope. If it belongs already to a different scope
+     * it is removed from that before adding it here.
+     *
+     * @param symbol The symbol to add as a child.
+     */
     addSymbol(symbol: BaseSymbol): void;
+    /** Removes the given symbol from this scope, if it exists. */
     removeSymbol(symbol: BaseSymbol): void;
+    /**
+     * Asynchronously retrieves child symbols of a given type from this symbol.
+     *
+     * @param t The type of of the objects to return.
+     *
+     * @returns A promise resolving to all (nested) children of the given type.
+     */
     getNestedSymbolsOfType<T extends BaseSymbol, Args extends unknown[]>(t: SymbolConstructor<T, Args>): Promise<T[]>;
+    /**
+     * Synchronously retrieves child symbols of a given type from this symbol.
+     *
+     * @param t The type of of the objects to return.
+     *
+     * @returns A list of all (nested) children of the given type.
+     */
     getNestedSymbolsOfTypeSync<T extends BaseSymbol, Args extends unknown[]>(t: SymbolConstructor<T, Args>): T[];
+    /**
+     * @param name If given only returns symbols with that name.
+     *
+     * @returns A promise resolving to symbols from this and all nested scopes in the order they were defined.
+     */
     getAllNestedSymbols(name?: string): Promise<BaseSymbol[]>;
+    /**
+     * @param name If given only returns symbols with that name.
+     *
+     * @returns A list of all symbols from this and all nested scopes in the order they were defined.
+     */
     getAllNestedSymbolsSync(name?: string): BaseSymbol[];
+    /**
+     * @param t The type of of the objects to return.
+     *
+     * @returns A promise resolving to direct children of a given type.
+     */
     getSymbolsOfType<T extends BaseSymbol, Args extends unknown[]>(t: SymbolConstructor<T, Args>): Promise<T[]>;
+    /**
+     * TODO: add optional position dependency (only symbols defined before a given caret pos are viable).
+     *
+     * @param t The type of the objects to return.
+     * @param localOnly If true only child symbols are returned, otherwise also symbols from the parent of this symbol
+     *                  (recursively).
+     *
+     * @returns A promise resolving to all symbols of the the given type, accessible from this scope (if localOnly is
+     *          false), within the owning symbol table.
+     */
     getAllSymbols<T extends BaseSymbol, Args extends unknown[]>(t: SymbolConstructor<T, Args>, localOnly?: boolean): Promise<T[]>;
+    /**
+     * TODO: add optional position dependency (only symbols defined before a given caret pos are viable).
+     *
+     * @param t The type of the objects to return.
+     * @param localOnly If true only child symbols are returned, otherwise also symbols from the parent of this symbol
+     *                  (recursively).
+     *
+     * @returns A list with all symbols of the the given type, accessible from this scope (if localOnly is
+     *          false), within the owning symbol table.
+     */
     getAllSymbolsSync<T extends BaseSymbol, Args extends unknown[]>(t: SymbolConstructor<T, Args>, localOnly?: boolean): T[];
+    /**
+     * @param name The name of the symbol to resolve.
+     * @param localOnly If true only child symbols are returned, otherwise also symbols from the parent of this symbol
+     *                  (recursively).
+     *
+     * @returns A promise resolving to the first symbol with a given name, in the order of appearance in this scope
+     *          or any of the parent scopes (conditionally).
+     */
     resolve(name: string, localOnly?: boolean): Promise<BaseSymbol | undefined>;
+    /**
+     * @param name The name of the symbol to resolve.
+     * @param localOnly If true only child symbols are returned, otherwise also symbols from the parent of this symbol
+     *                  (recursively).
+     *
+     * @returns the first symbol with a given name, in the order of appearance in this scope
+     *          or any of the parent scopes (conditionally).
+     */
     resolveSync(name: string, localOnly?: boolean): BaseSymbol | undefined;
+    /**
+     * @param path The path consisting of symbol names separator by `separator`.
+     * @param separator The character to separate path segments.
+     *
+     * @returns the symbol located at the given path through the symbol hierarchy.
+     */
     symbolFromPath(path: string, separator: string): BaseSymbol | undefined;
+    /**
+     * @param child The child to search for.
+     *
+     * @returns the index of the given child symbol in the child list or -1 if it couldn't be found.
+     */
     indexOfChild(child: BaseSymbol): number;
+    /**
+     * @param child The reference node.
+     *
+     * @returns the sibling symbol after the given child symbol, if one exists.
+     */
     nextSiblingOf(child: BaseSymbol): BaseSymbol | undefined;
+    /**
+     * @param child The reference node.
+     *
+     * @returns the sibling symbol before the given child symbol, if one exists.
+     */
     previousSiblingOf(child: BaseSymbol): BaseSymbol | undefined;
+    /**
+     * @param child The reference node.
+     *
+     * @returns the next symbol in definition order, regardless of the scope.
+     */
     nextOf(child: BaseSymbol): BaseSymbol | undefined;
 }
+/** A symbol with a scope (so it can have child symbols). */
 export declare class ScopedSymbol extends BaseSymbol implements IScopedSymbol {
     #private;
     constructor(name?: string);
+    /**
+     * @returns A promise resolving to all direct child symbols with a scope (e.g. classes in a module).
+     */
     get directScopes(): Promise<ScopedSymbol[]>;
@@ -35,19 +141,116 @@ get children(): BaseSymbol[];
     clear(): void;
+    /**
+     * Adds the given symbol to this scope. If it belongs already to a different scope
+     * it is removed from that before adding it here.
+     *
+     * @param symbol The symbol to add as a child.
+     */
     addSymbol(symbol: BaseSymbol): void;
     removeSymbol(symbol: BaseSymbol): void;
+    /**
+     * Asynchronously retrieves child symbols of a given type from this symbol.
+     *
+     * @param t The type of of the objects to return.
+     *
+     * @returns A promise resolving to all (nested) children of the given type.
+     */
     getNestedSymbolsOfType<T extends BaseSymbol, Args extends unknown[]>(t: SymbolConstructor<T, Args>): Promise<T[]>;
+    /**
+     * Synchronously retrieves child symbols of a given type from this symbol.
+     *
+     * @param t The type of of the objects to return.
+     *
+     * @returns A list of all (nested) children of the given type.
+     */
     getNestedSymbolsOfTypeSync<T extends BaseSymbol, Args extends unknown[]>(t: SymbolConstructor<T, Args>): T[];
+    /**
+     * @param name If given only returns symbols with that name.
+     *
+     * @returns A promise resolving to symbols from this and all nested scopes in the order they were defined.
+     */
     getAllNestedSymbols(name?: string): Promise<BaseSymbol[]>;
+    /**
+     * @param name If given only returns symbols with that name.
+     *
+     * @returns A list of all symbols from this and all nested scopes in the order they were defined.
+     */
     getAllNestedSymbolsSync(name?: string): BaseSymbol[];
+    /**
+     * @param t The type of of the objects to return.
+     *
+     * @returns A promise resolving to direct children of a given type.
+     */
     getSymbolsOfType<T extends BaseSymbol, Args extends unknown[]>(t: SymbolConstructor<T, Args>): Promise<T[]>;
+    /**
+     * TODO: add optional position dependency (only symbols defined before a given caret pos are viable).
+     *
+     * @param t The type of the objects to return.
+     * @param localOnly If true only child symbols are returned, otherwise also symbols from the parent of this symbol
+     *                  (recursively).
+     *
+     * @returns A promise resolving to all symbols of the the given type, accessible from this scope (if localOnly is
+     *          false), within the owning symbol table.
+     */
     getAllSymbols<T extends BaseSymbol, Args extends unknown[]>(t: SymbolConstructor<T, Args>, localOnly?: boolean): Promise<T[]>;
+    /**
+     * TODO: add optional position dependency (only symbols defined before a given caret pos are viable).
+     *
+     * @param t The type of the objects to return.
+     * @param localOnly If true only child symbols are returned, otherwise also symbols from the parent of this symbol
+     *                  (recursively).
+     *
+     * @returns A list with all symbols of the the given type, accessible from this scope (if localOnly is
+     *          false), within the owning symbol table.
+     */
     getAllSymbolsSync<T extends BaseSymbol, Args extends unknown[]>(t: SymbolConstructor<T, Args>, localOnly?: boolean): T[];
+    /**
+     * @param name The name of the symbol to resolve.
+     * @param localOnly If true only child symbols are returned, otherwise also symbols from the parent of this symbol
+     *                  (recursively).
+     *
+     * @returns A promise resolving to the first symbol with a given name, in the order of appearance in this scope
+     *          or any of the parent scopes (conditionally).
+     */
     resolve(name: string, localOnly?: boolean): Promise<BaseSymbol | undefined>;
+    /**
+     * @param name The name of the symbol to resolve.
+     * @param localOnly If true only child symbols are returned, otherwise also symbols from the parent of this symbol
+     *                  (recursively).
+     *
+     * @returns the first symbol with a given name, in the order of appearance in this scope
+     *          or any of the parent scopes (conditionally).
+     */
     resolveSync(name: string, localOnly?: boolean): BaseSymbol | undefined;
+    /**
+     * @param path The path consisting of symbol names separator by `separator`.
+     * @param separator The character to separate path segments.
+     *
+     * @returns the symbol located at the given path through the symbol hierarchy.
+     */
     symbolFromPath(path: string, separator?: string): BaseSymbol | undefined;
+    /**
+     * @param child The child to search for.
+     *
+     * @returns the index of the given child symbol in the child list or -1 if it couldn't be found.
+     */
     indexOfChild(child: BaseSymbol): number;
+    /**
+     * @param child The reference node.
+     *
+     * @returns the sibling symbol after the given child symbol, if one exists.
+     */
     nextSiblingOf(child: BaseSymbol): BaseSymbol | undefined;
+    /**
+     * @param child The reference node.
+     *
+     * @returns the sibling symbol before the given child symbol, if one exists.
+     */
     previousSiblingOf(child: BaseSymbol): BaseSymbol | undefined;
+    /**
+     * @param child The reference node.
+     *
+     * @returns the next symbol in definition order, regardless of the scope.
+     */
     nextOf(child: BaseSymbol): BaseSymbol | undefined;
     private isNamespace;
 }

lib/src/ScopedSymbol.js

 "use strict";
+/*
+ * This file is released under the MIT license.
+ * Copyright (c) 2023, Mike Lischke
+ *
+ * See LICENSE file for more info.
+ */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
@@ -27,8 +33,14 @@ function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
 const DuplicateSymbolError_1 = require("./DuplicateSymbolError");
+/** A symbol with a scope (so it can have child symbols). */
 class ScopedSymbol extends BaseSymbol_1.BaseSymbol {
     constructor(name = "") {
         super(name);
+        /** All child symbols in definition order. */
         _ScopedSymbol_children.set(this, []);
+        // All used child names. Used to detect name collisions.
         _ScopedSymbol_names.set(this, new Map());
     }
+    /**
+     * @returns A promise resolving to all direct child symbols with a scope (e.g. classes in a module).
+     */
     get directScopes() {
@@ -56,5 +68,12 @@ return this.getSymbolsOfType(ScopedSymbol);
     }
+    /**
+     * Adds the given symbol to this scope. If it belongs already to a different scope
+     * it is removed from that before adding it here.
+     *
+     * @param symbol The symbol to add as a child.
+     */
     addSymbol(symbol) {
         var _a, _b;
         symbol.removeFromParent();
+        // Check for duplicates first.
         const symbolTable = this.symbolTable;
@@ -98,2 +117,9 @@ const count = __classPrivateFieldGet(this, _ScopedSymbol_names, "f").get(symbol.name);
     }
+    /**
+     * Asynchronously retrieves child symbols of a given type from this symbol.
+     *
+     * @param t The type of of the objects to return.
+     *
+     * @returns A promise resolving to all (nested) children of the given type.
+     */
     getNestedSymbolsOfType(t) {
@@ -118,2 +144,9 @@ return __awaiter(this, void 0, void 0, function* () {
     }
+    /**
+     * Synchronously retrieves child symbols of a given type from this symbol.
+     *
+     * @param t The type of of the objects to return.
+     *
+     * @returns A list of all (nested) children of the given type.
+     */
     getNestedSymbolsOfTypeSync(t) {
@@ -131,2 +164,7 @@ const result = [];
     }
+    /**
+     * @param name If given only returns symbols with that name.
+     *
+     * @returns A promise resolving to symbols from this and all nested scopes in the order they were defined.
+     */
     getAllNestedSymbols(name) {
@@ -151,2 +189,7 @@ return __awaiter(this, void 0, void 0, function* () {
     }
+    /**
+     * @param name If given only returns symbols with that name.
+     *
+     * @returns A list of all symbols from this and all nested scopes in the order they were defined.
+     */
     getAllNestedSymbolsSync(name) {
@@ -164,2 +207,7 @@ const result = [];
     }
+    /**
+     * @param t The type of of the objects to return.
+     *
+     * @returns A promise resolving to direct children of a given type.
+     */
     getSymbolsOfType(t) {
@@ -176,5 +224,17 @@ return new Promise((resolve) => {
     }
+    /**
+     * TODO: add optional position dependency (only symbols defined before a given caret pos are viable).
+     *
+     * @param t The type of the objects to return.
+     * @param localOnly If true only child symbols are returned, otherwise also symbols from the parent of this symbol
+     *                  (recursively).
+     *
+     * @returns A promise resolving to all symbols of the the given type, accessible from this scope (if localOnly is
+     *          false), within the owning symbol table.
+     */
     getAllSymbols(t, localOnly = false) {
         return __awaiter(this, void 0, void 0, function* () {
             const result = [];
+            // Special handling for namespaces, which act like grouping symbols in this scope,
+            // so we show them as available in this scope.
             for (const child of __classPrivateFieldGet(this, _ScopedSymbol_children, "f")) {
@@ -198,4 +258,16 @@ if (child instanceof t) {
     }
+    /**
+     * TODO: add optional position dependency (only symbols defined before a given caret pos are viable).
+     *
+     * @param t The type of the objects to return.
+     * @param localOnly If true only child symbols are returned, otherwise also symbols from the parent of this symbol
+     *                  (recursively).
+     *
+     * @returns A list with all symbols of the the given type, accessible from this scope (if localOnly is
+     *          false), within the owning symbol table.
+     */
     getAllSymbolsSync(t, localOnly = false) {
         const result = [];
+        // Special handling for namespaces, which act like grouping symbols in this scope,
+        // so we show them as available in this scope.
         for (const child of __classPrivateFieldGet(this, _ScopedSymbol_children, "f")) {
@@ -218,2 +290,10 @@ if (child instanceof t) {
     }
+    /**
+     * @param name The name of the symbol to resolve.
+     * @param localOnly If true only child symbols are returned, otherwise also symbols from the parent of this symbol
+     *                  (recursively).
+     *
+     * @returns A promise resolving to the first symbol with a given name, in the order of appearance in this scope
+     *          or any of the parent scopes (conditionally).
+     */
     resolve(name, localOnly = false) {
@@ -228,2 +308,3 @@ return __awaiter(this, void 0, void 0, function* () {
                 }
+                // Nothing found locally. Let the parent continue.
                 if (!localOnly) {
@@ -239,2 +320,10 @@ if (this.parent) {
     }
+    /**
+     * @param name The name of the symbol to resolve.
+     * @param localOnly If true only child symbols are returned, otherwise also symbols from the parent of this symbol
+     *                  (recursively).
+     *
+     * @returns the first symbol with a given name, in the order of appearance in this scope
+     *          or any of the parent scopes (conditionally).
+     */
     resolveSync(name, localOnly = false) {
@@ -246,2 +335,3 @@ for (const child of __classPrivateFieldGet(this, _ScopedSymbol_children, "f")) {
         }
+        // Nothing found locally. Let the parent continue.
         if (!localOnly) {
@@ -254,2 +344,8 @@ if (this.parent) {
     }
+    /**
+     * @param path The path consisting of symbol names separator by `separator`.
+     * @param separator The character to separate path segments.
+     *
+     * @returns the symbol located at the given path through the symbol hierarchy.
+     */
     symbolFromPath(path, separator = ".") {
@@ -261,2 +357,3 @@ const elements = path.split(separator);
         }
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
         let result = this;
@@ -267,2 +364,3 @@ while (index < elements.length) {
             }
+            // eslint-disable-next-line no-loop-func
             const child = result.children.find((candidate) => { return candidate.name === elements[index]; });
@@ -277,5 +375,15 @@ if (!child) {
     }
+    /**
+     * @param child The child to search for.
+     *
+     * @returns the index of the given child symbol in the child list or -1 if it couldn't be found.
+     */
     indexOfChild(child) {
         return __classPrivateFieldGet(this, _ScopedSymbol_children, "f").findIndex((value, index) => { return value === child; });
     }
+    /**
+     * @param child The reference node.
+     *
+     * @returns the sibling symbol after the given child symbol, if one exists.
+     */
     nextSiblingOf(child) {
@@ -288,2 +396,7 @@ const index = this.indexOfChild(child);
     }
+    /**
+     * @param child The reference node.
+     *
+     * @returns the sibling symbol before the given child symbol, if one exists.
+     */
     previousSiblingOf(child) {
@@ -296,2 +409,7 @@ const index = this.indexOfChild(child);
     }
+    /**
+     * @param child The reference node.
+     *
+     * @returns the next symbol in definition order, regardless of the scope.
+     */
     nextOf(child) {
@@ -298,0 +416,0 @@ if (!(child.parent)) {

lib/src/SymbolTable.d.ts

@@ -8,2 +8,5 @@ import { SymbolTableOptions, SymbolConstructor } from "./types";
     options: SymbolTableOptions;
+    /**
+     * @returns instance information, mostly relevant for unit testing.
+     */
     info: {
@@ -17,13 +20,85 @@ dependencyCount: number;
     addNewSymbolOfType<T extends BaseSymbol, Args extends unknown[]>(t: SymbolConstructor<T, Args>, parent: ScopedSymbol | undefined, ...args: Args): T;
+    /**
+     * Asynchronously adds a new namespace to the symbol table or the given parent. The path parameter specifies a
+     * single namespace name or a chain of namespaces (which can be e.g. "outer.intermittent.inner.final").
+     * If any of the parent namespaces is missing they are created implicitly. The final part must not exist however
+     * or you'll get a duplicate symbol error.
+     *
+     * @param parent The parent to add the namespace to.
+     * @param path The namespace path.
+     * @param delimiter The delimiter used in the path.
+     *
+     * @returns The new symbol.
+     */
     addNewNamespaceFromPath(parent: ScopedSymbol | undefined, path: string, delimiter?: string): Promise<NamespaceSymbol>;
+    /**
+     * Synchronously adds a new namespace to the symbol table or the given parent. The path parameter specifies a
+     * single namespace name or a chain of namespaces (which can be e.g. "outer.intermittent.inner.final").
+     * If any of the parent namespaces is missing they are created implicitly. The final part must not exist however
+     * or you'll get a duplicate symbol error.
+     *
+     * @param parent The parent to add the namespace to.
+     * @param path The namespace path.
+     * @param delimiter The delimiter used in the path.
+     *
+     * @returns The new symbol.
+     */
     addNewNamespaceFromPathSync(parent: ScopedSymbol | undefined, path: string, delimiter?: string): NamespaceSymbol;
+    /**
+     * Asynchronously returns all symbols from this scope (and optionally those from dependencies) of a specific type.
+     *
+     * @param t The type of the symbols to return.
+     * @param localOnly If true do not search dependencies.
+     *
+     * @returns A promise which resolves when all symbols are collected.
+     */
     getAllSymbols<T extends BaseSymbol, Args extends unknown[]>(t: SymbolConstructor<T, Args>, localOnly: boolean): Promise<T[]>;
+    /**
+     * Synchronously returns all symbols from this scope (and optionally those from dependencies) of a specific type.
+     *
+     * @param t The type of the symbols to return.
+     * @param localOnly If true do not search dependencies.
+     *
+     * @returns A list with all symbols.
+     */
     getAllSymbolsSync<T extends BaseSymbol, Args extends unknown[]>(t: SymbolConstructor<T, Args>, localOnly: boolean): T[];
+    /**
+     * Asynchronously looks for a symbol which is connected with a given parse tree context.
+     *
+     * @param context The context to search for.
+     *
+     * @returns A promise resolving to the found symbol or undefined.
+     */
     symbolWithContext(context: ParseTree): Promise<BaseSymbol | undefined>;
+    /**
+     * Synchronously looks for a symbol which is connected with a given parse tree context.
+     *
+     * @param context The context to search for.
+     *
+     * @returns The found symbol or undefined.
+     */
     symbolWithContextSync(context: ParseTree): BaseSymbol | undefined;
+    /**
+     * Asynchronously resolves a name to a symbol.
+     *
+     * @param name The name of the symbol to find.
+     * @param localOnly A flag indicating if only this symbol table should be used or also its dependencies.
+     *
+     * @returns A promise resolving to the found symbol or undefined.
+     */
     resolve(name: string, localOnly: boolean): Promise<BaseSymbol | undefined>;
+    /**
+     * Synchronously resolves a name to a symbol.
+     *
+     * @param name The name of the symbol to find.
+     * @param localOnly A flag indicating if only this symbol table should be used or also its dependencies.
+     *
+     * @returns The found symbol or undefined.
+     */
     resolveSync(name: string, localOnly: boolean): BaseSymbol | undefined;
 }
+/** The main class managing all the symbols for a top level entity like a file, library or similar. */
 export declare class SymbolTable extends ScopedSymbol implements ISymbolTable {
     readonly options: SymbolTableOptions;
+    /**  Other symbol information available to this instance. */
     protected dependencies: Set<SymbolTable>;
@@ -30,0 +105,0 @@ constructor(name: string, options: SymbolTableOptions);

lib/src/SymbolTable.js

 "use strict";
+/*
+ * This file is released under the MIT license.
+ * Copyright (c) 2017, 2021, Mike Lischke
+ *
+ * See LICENSE file for more info.
+ */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
@@ -16,2 +22,3 @@ function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
 const NamespaceSymbol_1 = require("./NamespaceSymbol");
+/** The main class managing all the symbols for a top level entity like a file, library or similar. */
 class SymbolTable extends ScopedSymbol_1.ScopedSymbol {
@@ -21,2 +28,3 @@ constructor(name, options) {
         this.options = options;
+        /**  Other symbol information available to this instance. */
         this.dependencies = new Set();
@@ -112,2 +120,9 @@ }
         return __awaiter(this, void 0, void 0, function* () {
+            /**
+             * Local function to find a symbol recursively.
+             *
+             * @param symbol The symbol to search through.
+             *
+             * @returns The symbol with the given context, if found.
+             */
             const findRecursive = (symbol) => {
@@ -147,2 +162,9 @@ if (symbol.context === context) {
     symbolWithContextSync(context) {
+        /**
+         * Local function to find a symbol recursively.
+         *
+         * @param symbol The symbol to search through.
+         *
+         * @returns The symbol with the given context, if found.
+         */
         const findRecursive = (symbol) => {
@@ -149,0 +171,0 @@ if (symbol.context === context) {

lib/src/TypeAlias.d.ts

 import { ReferenceKind, Type, TypeKind } from "./types";
 import { BaseSymbol } from "./BaseSymbol";
+/** An alias for another type. */
 export declare class TypeAlias extends BaseSymbol implements Type {
@@ -4,0 +5,0 @@ private targetType;

lib/src/TypeAlias.js

 "use strict";
+/*
+ * This file is released under the MIT license.
+ * Copyright (c) 2023, Mike Lischke
+ *
+ * See LICENSE file for more info.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -6,2 +12,3 @@ exports.TypeAlias = void 0;
 const BaseSymbol_1 = require("./BaseSymbol");
+/** An alias for another type. */
 class TypeAlias extends BaseSymbol_1.BaseSymbol {
@@ -8,0 +15,0 @@ constructor(name, target) {

lib/src/TypedSymbol.d.ts

 import { Type } from "./types";
 import { BaseSymbol } from "./BaseSymbol";
+/** A symbol with an attached type (variables, fields etc.). */
 export declare class TypedSymbol extends BaseSymbol {
@@ -4,0 +5,0 @@ type: Type | undefined;

lib/src/TypedSymbol.js

 "use strict";
+/*
+ * This file is released under the MIT license.
+ * Copyright (c) 2023, Mike Lischke
+ *
+ * See LICENSE file for more info.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TypedSymbol = void 0;
 const BaseSymbol_1 = require("./BaseSymbol");
+/** A symbol with an attached type (variables, fields etc.). */
 class TypedSymbol extends BaseSymbol_1.BaseSymbol {
@@ -6,0 +13,0 @@ constructor(name, type) {

lib/src/types.d.ts

 import { BaseSymbol } from "./BaseSymbol";
+/** Visibility (aka. accessibility) of a symbol member. */
 export declare enum MemberVisibility {
+    /** Not specified, default depends on the language and type. */
     Unknown = 0,
+    /** Used in Swift, member can be accessed outside of the defining module and extended. */
     Open = 1,
+    /** Like Open, but in Swift such a type cannot be extended. */
     Public = 2,
+    /** Member is only accessible in the defining class and any derived class. */
     Protected = 3,
+    /** Member can only be accessed from the defining class. */
     Private = 4,
+    /**
+     * Used in Swift and Java, member can be accessed from everywhere in a defining module, not outside however.
+     * Also known as package private.
+     */
     FilePrivate = 5,
+    /** Custom enum for special usage. */
     Library = 6
 }
+/** The modifier of a symbol member. */
 export declare enum Modifier {
@@ -21,2 +33,3 @@ Static = 0,
 }
+/** Rough categorization of a type. */
 export declare enum TypeKind {
@@ -37,10 +50,19 @@ Unknown = 0,
 }
+/** Describes a reference to a type. */
 export declare enum ReferenceKind {
     Irrelevant = 0,
+    /** Default for most languages for dynamically allocated memory ("Type*" in C++). */
     Pointer = 1,
+    /** "Type&" in C++, all non-primitive types in Java/Javascript/Typescript etc. */
     Reference = 2,
+    /** "Type" as such and default for all value types. */
     Instance = 3
 }
+/** The root type interface. Used for typed symbols and type aliases. */
 export interface Type {
     name: string;
+    /**
+     * The super type of this type or empty if this is a fundamental type.
+     * Also used as the target type for type aliases.
+     */
     baseTypes: Type[];
@@ -53,2 +75,3 @@ kind: TypeKind;
 }
+/** The type of constructors for symbols. Used mostly for factory and lookup functions. */
 export type SymbolConstructor<T extends BaseSymbol, Args extends unknown[]> = new (...args: Args) => T;

lib/src/types.js

 "use strict";
+/*
+ * This file is released under the MIT license.
+ * Copyright (c) 2023, Mike Lischke
+ *
+ * See LICENSE file for more info.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReferenceKind = exports.TypeKind = exports.Modifier = exports.MemberVisibility = void 0;
+/** Visibility (aka. accessibility) of a symbol member. */
 var MemberVisibility;
 (function (MemberVisibility) {
+    /** Not specified, default depends on the language and type. */
     MemberVisibility[MemberVisibility["Unknown"] = 0] = "Unknown";
+    /** Used in Swift, member can be accessed outside of the defining module and extended. */
     MemberVisibility[MemberVisibility["Open"] = 1] = "Open";
+    /** Like Open, but in Swift such a type cannot be extended. */
     MemberVisibility[MemberVisibility["Public"] = 2] = "Public";
+    /** Member is only accessible in the defining class and any derived class. */
     MemberVisibility[MemberVisibility["Protected"] = 3] = "Protected";
+    /** Member can only be accessed from the defining class. */
     MemberVisibility[MemberVisibility["Private"] = 4] = "Private";
+    /**
+     * Used in Swift and Java, member can be accessed from everywhere in a defining module, not outside however.
+     * Also known as package private.
+     */
     MemberVisibility[MemberVisibility["FilePrivate"] = 5] = "FilePrivate";
+    /** Custom enum for special usage. */
     MemberVisibility[MemberVisibility["Library"] = 6] = "Library";
 })(MemberVisibility = exports.MemberVisibility || (exports.MemberVisibility = {}));
+/** The modifier of a symbol member. */
 var Modifier;
@@ -25,2 +43,3 @@ (function (Modifier) {
 })(Modifier = exports.Modifier || (exports.Modifier = {}));
+/** Rough categorization of a type. */
 var TypeKind;
@@ -42,9 +61,13 @@ (function (TypeKind) {
 })(TypeKind = exports.TypeKind || (exports.TypeKind = {}));
+/** Describes a reference to a type. */
 var ReferenceKind;
 (function (ReferenceKind) {
     ReferenceKind[ReferenceKind["Irrelevant"] = 0] = "Irrelevant";
+    /** Default for most languages for dynamically allocated memory ("Type*" in C++). */
     ReferenceKind[ReferenceKind["Pointer"] = 1] = "Pointer";
+    /** "Type&" in C++, all non-primitive types in Java/Javascript/Typescript etc. */
     ReferenceKind[ReferenceKind["Reference"] = 2] = "Reference";
+    /** "Type" as such and default for all value types. */
     ReferenceKind[ReferenceKind["Instance"] = 3] = "Instance";
 })(ReferenceKind = exports.ReferenceKind || (exports.ReferenceKind = {}));
 //# sourceMappingURL=types.js.map

lib/src/VariableSymbol.js

 "use strict";
+/*
+ * This file is released under the MIT license.
+ * Copyright (c) 2023, Mike Lischke
+ *
+ * See LICENSE file for more info.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -3,0 +9,0 @@ exports.VariableSymbol = void 0;

package.json

 {
     "name": "antlr4-c3",
-    "version": "3.0.0",
+    "version": "3.0.1",
     "description": "A code completion core implementation for ANTLR4 based parsers",
@@ -5,0 +5,0 @@ "author": "Mike Lischke",

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

1140024

increased by4.2%

Lines of code

4425

increased by29.05%

Number of medium supply chain risk alerts

0

decreased by-100%

No dependency changes