@microsoft/tsdoc - npm Package Compare versions

Comparing version 0.12.10 to 0.12.11

CHANGELOG.json

@@ -5,2 +5,14 @@ {
     {
+      "version": "0.12.11",
+      "tag": "@microsoft/tsdoc_v0.12.11",
+      "date": "Wed, 24 Jul 2019 00:38:18 GMT",
+      "comments": {
+        "patch": [
+          {
+            "comment": "Add new meanings to DeclarationReference and fix some parsing bugs"
+          }
+        ]
+      }
+    },
+    {
       "version": "0.12.10",
@@ -7,0 +19,0 @@ "tag": "@microsoft/tsdoc_v0.12.10",

CHANGELOG.md

 # Change Log - @microsoft/tsdoc
 
-This log was last generated on Fri, 19 Jul 2019 02:47:09 GMT and should not be manually modified.
+This log was last generated on Wed, 24 Jul 2019 00:38:18 GMT and should not be manually modified.
 
+## 0.12.11
+Wed, 24 Jul 2019 00:38:18 GMT
+
+### Patches
+
+- Add new meanings to DeclarationReference and fix some parsing bugs
+
 ## 0.12.10
@@ -6,0 +13,0 @@ Fri, 19 Jul 2019 02:47:09 GMT

lib/beta/DeclarationReference.d.ts

@@ -15,13 +15,28 @@ /**
     static parse(text: string): DeclarationReference;
-    static makeSafeComponent(text: string): string;
+    static parseComponent(text: string): Component;
+    /**
+     * Escapes a string for use as a symbol navigation component. If the string contains `!.#~:,"{}()` or starts with
+     * `[`, it is enclosed in quotes.
+     */
+    static escapeComponentString(text: string): string;
+    /**
+     * Unescapes a string used as a symbol navigation component.
+     */
+    static unescapeComponentString(text: string): string;
+    /**
+     * Determines whether the provided string is a well-formed symbol navigation component string.
+     */
+    static isWellFormedComponentString(text: string): boolean;
     static empty(): DeclarationReference;
-    static module(path: string): DeclarationReference;
+    static package(packageName: string, importPath?: string): DeclarationReference;
+    static module(path: string, userEscaped?: boolean): DeclarationReference;
     static global(): DeclarationReference;
+    static from(base: DeclarationReference | undefined): DeclarationReference;
     withSource(source: ModuleSource | GlobalSource | undefined): DeclarationReference;
     withNavigation(navigation: Navigation.Locals | Navigation.Exports | undefined): DeclarationReference;
     withSymbol(symbol: SymbolReference | undefined): DeclarationReference;
-    withComponent(component: Component): DeclarationReference;
+    withComponentPath(componentPath: ComponentPath): DeclarationReference;
     withMeaning(meaning: Meaning | undefined): DeclarationReference;
     withOverloadIndex(overloadIndex: number | undefined): DeclarationReference;
-    addNavigationStep(navigation: Navigation, text: string): DeclarationReference;
+    addNavigationStep(navigation: Navigation, component: ComponentLike): DeclarationReference;
     toString(): string;
@@ -44,4 +59,9 @@ }
     readonly path: string;
-    constructor(path: string, escapeIfNeeded?: boolean);
+    private _pathComponents;
+    constructor(path: string, userEscaped?: boolean);
+    readonly packageName: string;
+    readonly importPath: string;
+    static fromPackage(packageName: string, importPath?: string): ModuleSource;
     toString(): string;
+    private _parsePathComponents;
 }
@@ -60,10 +80,42 @@ /**
  */
-export declare type Component = RootComponent | NavigationComponent;
+export declare type Component = ComponentString | ComponentReference;
 /**
  * @beta
  */
-export declare abstract class ComponentBase {
+export declare namespace Component {
+    function from(value: ComponentLike): Component;
+}
+/**
+ * @beta
+ */
+export declare type ComponentLike = Component | DeclarationReference | string;
+/**
+ * @beta
+ */
+export declare class ComponentString {
     readonly text: string;
-    constructor(text: string, escapeIfNeeded?: boolean);
-    addNavigationStep(this: Component, navigation: Navigation, text: string): Component;
+    constructor(text: string, userEscaped?: boolean);
+    toString(): string;
+}
+/**
+ * @beta
+ */
+export declare class ComponentReference {
+    readonly reference: DeclarationReference;
+    constructor(reference: DeclarationReference);
+    static parse(text: string): ComponentReference;
+    withReference(reference: DeclarationReference): ComponentReference;
+    toString(): string;
+}
+/**
+ * @beta
+ */
+export declare type ComponentPath = ComponentRoot | ComponentNavigation;
+/**
+ * @beta
+ */
+export declare abstract class ComponentPathBase {
+    readonly component: Component;
+    constructor(component: Component);
+    addNavigationStep(this: ComponentPath, navigation: Navigation, component: ComponentLike): ComponentPath;
     abstract toString(): string;
@@ -74,3 +126,4 @@ }
  */
-export declare class RootComponent extends ComponentBase {
+export declare class ComponentRoot extends ComponentPathBase {
+    withComponent(component: ComponentLike): ComponentRoot;
     toString(): string;
@@ -81,6 +134,9 @@ }
  */
-export declare class NavigationComponent extends ComponentBase {
-    readonly parent: Component;
+export declare class ComponentNavigation extends ComponentPathBase {
+    readonly parent: ComponentPath;
     readonly navigation: Navigation;
-    constructor(source: Component, navigation: Navigation, text: string, escapeIfNeeded?: boolean);
+    constructor(parent: ComponentPath, navigation: Navigation, component: Component);
+    withParent(parent: ComponentPath): ComponentNavigation;
+    withNavigation(navigation: Navigation): ComponentNavigation;
+    withComponent(component: ComponentLike): ComponentNavigation;
     toString(): string;
@@ -94,13 +150,14 @@ }
     Interface = "interface",
-    TypeAlias = "typealias",
+    TypeAlias = "type",
     Enum = "enum",
     Namespace = "namespace",
     Function = "function",
-    Variable = "variable",
+    Variable = "var",
     Constructor = "constructor",
     Member = "member",
     Event = "event",
-    EnumMember = "enummember",
-    Signature = "signature",
-    Type = "type"
+    CallSignature = "call",
+    ConstructSignature = "new",
+    IndexSignature = "index",
+    ComplexType = "complex"
 }
@@ -119,11 +176,12 @@ /**
 export declare class SymbolReference {
-    readonly component: Component;
+    readonly componentPath: ComponentPath | undefined;
     readonly meaning: Meaning | undefined;
     readonly overloadIndex: number | undefined;
-    constructor(component: Component, { meaning, overloadIndex }?: ISymbolReferenceOptions);
-    withComponent(component: Component): SymbolReference;
+    constructor(component: ComponentPath | undefined, { meaning, overloadIndex }?: ISymbolReferenceOptions);
+    static empty(): SymbolReference;
+    withComponentPath(componentPath: ComponentPath | undefined): SymbolReference;
     withMeaning(meaning: Meaning | undefined): SymbolReference;
     withOverloadIndex(overloadIndex: number | undefined): SymbolReference;
-    addNavigationStep(navigation: Navigation, text: string): SymbolReference;
+    addNavigationStep(navigation: Navigation, component: ComponentLike): SymbolReference;
     toString(): string;
 }

lib/beta/DeclarationReference.js

@@ -69,2 +69,5 @@ "use strict";
         var reference = parser.parseDeclarationReference();
+        if (parser.errors.length) {
+            throw new SyntaxError("Invalid DeclarationReference '" + text + "':\n  " + parser.errors.join('\n  '));
+        }
         if (!parser.eof) {
@@ -75,6 +78,48 @@ throw new SyntaxError("Invalid DeclarationReference '" + text + "'");
     };
-    DeclarationReference.makeSafeComponent = function (text) {
+    DeclarationReference.parseComponent = function (text) {
+        if (text[0] === '[') {
+            return ComponentReference.parse(text);
+        }
+        else {
+            return new ComponentString(text, true);
+        }
+    };
+    /**
+     * Escapes a string for use as a symbol navigation component. If the string contains `!.#~:,"{}()` or starts with
+     * `[`, it is enclosed in quotes.
+     */
+    DeclarationReference.escapeComponentString = function (text) {
+        if (text.length === 0) {
+            return '""';
+        }
+        var ch = text.charAt(0);
+        if (ch === '"' || ch === '[' || !this.isWellFormedComponentString(text)) {
+            return JSON.stringify(text);
+        }
+        return text;
+    };
+    /**
+     * Unescapes a string used as a symbol navigation component.
+     */
+    DeclarationReference.unescapeComponentString = function (text) {
+        if (text.length > 2 && text.charAt(0) === '"' && text.charAt(text.length - 1) === '"') {
+            try {
+                return JSON.parse(text);
+            }
+            catch (_a) {
+                throw new SyntaxError("Invalid Component '" + text + "'");
+            }
+        }
+        if (!this.isWellFormedComponentString(text)) {
+            throw new SyntaxError("Invalid Component '" + text + "'");
+        }
+        return text;
+    };
+    /**
+     * Determines whether the provided string is a well-formed symbol navigation component string.
+     */
+    DeclarationReference.isWellFormedComponentString = function (text) {
         var parser = new Parser(text);
-        parser.parseComponent();
-        return parser.eof ? text : JSON.stringify(text);
+        parser.parseComponentString();
+        return parser.errors.length === 0 && parser.eof;
     };
@@ -84,8 +129,14 @@ DeclarationReference.empty = function () {
     };
-    DeclarationReference.module = function (path) {
-        return new DeclarationReference(new ModuleSource(path));
+    DeclarationReference.package = function (packageName, importPath) {
+        return new DeclarationReference(ModuleSource.fromPackage(packageName, importPath));
     };
+    DeclarationReference.module = function (path, userEscaped) {
+        return new DeclarationReference(new ModuleSource(path, userEscaped));
+    };
     DeclarationReference.global = function () {
         return new DeclarationReference(GlobalSource.instance);
     };
+    DeclarationReference.from = function (base) {
+        return base || this.empty();
+    };
     DeclarationReference.prototype.withSource = function (source) {
@@ -100,4 +151,5 @@ return this._source === source ? this : new DeclarationReference(source, this._navigation, this._symbol);
     };
-    DeclarationReference.prototype.withComponent = function (component) {
-        return this.withSymbol(this.symbol ? this.symbol.withComponent(component) : new SymbolReference(component));
+    DeclarationReference.prototype.withComponentPath = function (componentPath) {
+        return this.withSymbol(this.symbol ? this.symbol.withComponentPath(componentPath) :
+            new SymbolReference(componentPath));
     };
@@ -109,3 +161,3 @@ DeclarationReference.prototype.withMeaning = function (meaning) {
             }
-            throw new Error('Cannot set a meaning on a DeclarationReference without a symbol');
+            return this.withSymbol(SymbolReference.empty().withMeaning(meaning));
         }
@@ -119,9 +171,9 @@ return this.withSymbol(this.symbol.withMeaning(meaning));
             }
-            throw new Error('Cannot set an overloadIndex on a DeclarationReference without a symbol');
+            return this.withSymbol(SymbolReference.empty().withOverloadIndex(overloadIndex));
         }
         return this.withSymbol(this.symbol.withOverloadIndex(overloadIndex));
     };
-    DeclarationReference.prototype.addNavigationStep = function (navigation, text) {
+    DeclarationReference.prototype.addNavigationStep = function (navigation, component) {
         if (this.symbol) {
-            return this.withSymbol(this.symbol.addNavigationStep(navigation, text));
+            return this.withSymbol(this.symbol.addNavigationStep(navigation, component));
         }
@@ -131,3 +183,4 @@ if (navigation === "#" /* Members */) {
         }
-        return new DeclarationReference(this.source, navigation, new SymbolReference(new RootComponent(text)));
+        var symbol = new SymbolReference(new ComponentRoot(Component.from(component)));
+        return new DeclarationReference(this.source, navigation, symbol);
     };
@@ -148,12 +201,96 @@ DeclarationReference.prototype.toString = function () {
 var ModuleSource = /** @class */ (function () {
-    function ModuleSource(path, escapeIfNeeded) {
-        if (escapeIfNeeded === void 0) { escapeIfNeeded = true; }
-        this.path = escapeIfNeeded ? DeclarationReference.makeSafeComponent(path) : path;
+    function ModuleSource(path, userEscaped) {
+        if (userEscaped === void 0) { userEscaped = true; }
+        this.path = escapeIfNeeded(path, userEscaped);
     }
+    Object.defineProperty(ModuleSource.prototype, "packageName", {
+        get: function () {
+            return this._parsePathComponents().packageName;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(ModuleSource.prototype, "importPath", {
+        get: function () {
+            return this._parsePathComponents().importPath;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    ModuleSource.fromPackage = function (packageName, importPath) {
+        if (!isValidPackageName(packageName)) {
+            throw new SyntaxError("Invalid package name '" + packageName + "'");
+        }
+        var path = packageName;
+        if (importPath) {
+            if (invalidImportPathRegExp.test(importPath)) {
+                throw new SyntaxError("Invalid import path '" + importPath);
+            }
+            path += '/' + importPath;
+        }
+        var source = new ModuleSource(path);
+        source._pathComponents = { packageName: packageName, importPath: importPath || '' };
+        return source;
+    };
     ModuleSource.prototype.toString = function () {
         return this.path + "!";
     };
+    ModuleSource.prototype._parsePathComponents = function () {
+        if (!this._pathComponents) {
+            var path = DeclarationReference.unescapeComponentString(this.path);
+            var match = packageNameRegExp.exec(path);
+            if (match && isValidPackageName(match[1], match)) {
+                this._pathComponents = {
+                    packageName: match[1],
+                    importPath: match[2] || ''
+                };
+            }
+            else {
+                this._pathComponents = {
+                    packageName: '',
+                    importPath: path
+                };
+            }
+        }
+        return this._pathComponents;
+    };
     return ModuleSource;
 }());
 exports.ModuleSource = ModuleSource;
+// matches the following:
+//   'foo'            -> ["foo", "foo", undefined, "foo", undefined]
+//   'foo/bar'        -> ["foo/bar", "foo", undefined, "foo", "bar"]
+//   '@scope/foo'     -> ["@scope/foo", "@scope/foo", "scope", "foo", undefined]
+//   '@scope/foo/bar' -> ["@scope/foo/bar", "@scope/foo", "scope", "foo", "bar"]
+// does not match:
+//   '/'
+//   '@/'
+//   '@scope/'
+// capture groups:
+//   1. The package name (including scope)
+//   2. The scope name (excluding the leading '@')
+//   3. The unscoped package name
+//   4. The package-relative import path
+var packageNameRegExp = /^((?:@([^/]+?)\/)?([^/]+?))(?:\/(.*))?$/;
+// according to validate-npm-package-name:
+// no leading '.'
+// no leading '_'
+// no leading or trailing whitespace
+// no capital letters or special characters (~'!()*)
+// not 'node_modules' or 'favicon.ico' (blacklisted)
+var invalidPackageNameRegExp = /^[._\s]|\s$|[A-Z~'!()*]|^(node_modules|favicon.ico)$/s;
+// no leading './'
+// no leading '../'
+// no leading '/'
+// not '.' or '..'
+var invalidImportPathRegExp = /^(\.\.?([\\/]|$)|\/)/;
+function isValidPackageName(packageName, match) {
+    if (match === void 0) { match = packageNameRegExp.exec(packageName); }
+    return !!match // must match the minimal pattern
+        && match[1] === packageName // must not contain excess characters
+        && packageName.length <= 214 // maximum length, per validate-npm-package-name
+        && !invalidPackageNameRegExp.test(packageName) // must not contain invalid characters
+        && (!match[2] || encodeURIComponent(match[2]) === match[2]) // scope must be URL-friendly
+        && encodeURIComponent(match[3]) === match[3]; // package must be URL-friendly
+}
 /**
@@ -176,46 +313,115 @@ * Represents the global scope.
  */
-var ComponentBase = /** @class */ (function () {
-    function ComponentBase(text, escapeIfNeeded) {
-        if (escapeIfNeeded === void 0) { escapeIfNeeded = true; }
-        this.text = escapeIfNeeded ? DeclarationReference.makeSafeComponent(text) : text;
+var Component;
+(function (Component) {
+    function from(value) {
+        if (typeof value === 'string') {
+            return new ComponentString(value);
+        }
+        if (value instanceof DeclarationReference) {
+            return new ComponentReference(value);
+        }
+        return value;
     }
-    ComponentBase.prototype.addNavigationStep = function (navigation, text) {
+    Component.from = from;
+})(Component = exports.Component || (exports.Component = {}));
+/**
+ * @beta
+ */
+var ComponentString = /** @class */ (function () {
+    function ComponentString(text, userEscaped) {
+        this.text = this instanceof ParsedComponentString ? text : escapeIfNeeded(text, userEscaped);
+    }
+    ComponentString.prototype.toString = function () {
+        return this.text;
+    };
+    return ComponentString;
+}());
+exports.ComponentString = ComponentString;
+var ParsedComponentString = /** @class */ (function (_super) {
+    __extends(ParsedComponentString, _super);
+    function ParsedComponentString() {
+        return _super !== null && _super.apply(this, arguments) || this;
+    }
+    return ParsedComponentString;
+}(ComponentString));
+/**
+ * @beta
+ */
+var ComponentReference = /** @class */ (function () {
+    function ComponentReference(reference) {
+        this.reference = reference;
+    }
+    ComponentReference.parse = function (text) {
+        if (text.length > 2 && text.charAt(0) === '[' && text.charAt(text.length - 1) === ']') {
+            return new ComponentReference(DeclarationReference.parse(text.slice(1, -1)));
+        }
+        throw new SyntaxError("Invalid component reference: '" + text + "'");
+    };
+    ComponentReference.prototype.withReference = function (reference) {
+        return this.reference === reference ? this : new ComponentReference(reference);
+    };
+    ComponentReference.prototype.toString = function () {
+        return "[" + this.reference + "]";
+    };
+    return ComponentReference;
+}());
+exports.ComponentReference = ComponentReference;
+/**
+ * @beta
+ */
+var ComponentPathBase = /** @class */ (function () {
+    function ComponentPathBase(component) {
+        this.component = component;
+    }
+    ComponentPathBase.prototype.addNavigationStep = function (navigation, component) {
         // tslint:disable-next-line:no-use-before-declare
-        return new NavigationComponent(this, navigation, text);
+        return new ComponentNavigation(this, navigation, Component.from(component));
     };
-    return ComponentBase;
+    return ComponentPathBase;
 }());
-exports.ComponentBase = ComponentBase;
+exports.ComponentPathBase = ComponentPathBase;
 /**
  * @beta
  */
-var RootComponent = /** @class */ (function (_super) {
-    __extends(RootComponent, _super);
-    function RootComponent() {
+var ComponentRoot = /** @class */ (function (_super) {
+    __extends(ComponentRoot, _super);
+    function ComponentRoot() {
         return _super !== null && _super.apply(this, arguments) || this;
     }
-    RootComponent.prototype.toString = function () {
-        return this.text;
+    ComponentRoot.prototype.withComponent = function (component) {
+        return this.component === component ? this : new ComponentRoot(Component.from(component));
     };
-    return RootComponent;
-}(ComponentBase));
-exports.RootComponent = RootComponent;
+    ComponentRoot.prototype.toString = function () {
+        return this.component.toString();
+    };
+    return ComponentRoot;
+}(ComponentPathBase));
+exports.ComponentRoot = ComponentRoot;
 /**
  * @beta
  */
-var NavigationComponent = /** @class */ (function (_super) {
-    __extends(NavigationComponent, _super);
-    function NavigationComponent(source, navigation, text, escapeIfNeeded) {
-        if (escapeIfNeeded === void 0) { escapeIfNeeded = true; }
-        var _this = _super.call(this, text, escapeIfNeeded) || this;
-        _this.parent = source;
+var ComponentNavigation = /** @class */ (function (_super) {
+    __extends(ComponentNavigation, _super);
+    function ComponentNavigation(parent, navigation, component) {
+        var _this = _super.call(this, component) || this;
+        _this.parent = parent;
         _this.navigation = navigation;
         return _this;
     }
-    NavigationComponent.prototype.toString = function () {
-        return "" + this.parent + formatNavigation(this.navigation) + this.text;
+    ComponentNavigation.prototype.withParent = function (parent) {
+        return this.parent === parent ? this : new ComponentNavigation(parent, this.navigation, this.component);
     };
-    return NavigationComponent;
-}(ComponentBase));
-exports.NavigationComponent = NavigationComponent;
+    ComponentNavigation.prototype.withNavigation = function (navigation) {
+        return this.navigation === navigation ? this : new ComponentNavigation(this.parent, navigation, this.component);
+    };
+    ComponentNavigation.prototype.withComponent = function (component) {
+        return this.component === component ? this :
+            new ComponentNavigation(this.parent, this.navigation, Component.from(component));
+    };
+    ComponentNavigation.prototype.toString = function () {
+        return "" + this.parent + formatNavigation(this.navigation) + this.component;
+    };
+    return ComponentNavigation;
+}(ComponentPathBase));
+exports.ComponentNavigation = ComponentNavigation;
 /**
@@ -228,8 +434,11 @@ * Represents a reference to a TypeScript symbol.
         var _b = _a === void 0 ? {} : _a, meaning = _b.meaning, overloadIndex = _b.overloadIndex;
-        this.component = component;
+        this.componentPath = component;
         this.overloadIndex = overloadIndex;
         this.meaning = meaning;
     }
-    SymbolReference.prototype.withComponent = function (component) {
-        return this.component === component ? this : new SymbolReference(component, {
+    SymbolReference.empty = function () {
+        return new SymbolReference(/*component*/ undefined);
+    };
+    SymbolReference.prototype.withComponentPath = function (componentPath) {
+        return this.componentPath === componentPath ? this : new SymbolReference(componentPath, {
             meaning: this.meaning,
@@ -240,3 +449,3 @@ overloadIndex: this.overloadIndex
     SymbolReference.prototype.withMeaning = function (meaning) {
-        return this.meaning === meaning ? this : new SymbolReference(this.component, {
+        return this.meaning === meaning ? this : new SymbolReference(this.componentPath, {
             meaning: meaning,
@@ -247,3 +456,3 @@ overloadIndex: this.overloadIndex
     SymbolReference.prototype.withOverloadIndex = function (overloadIndex) {
-        return this.overloadIndex === overloadIndex ? this : new SymbolReference(this.component, {
+        return this.overloadIndex === overloadIndex ? this : new SymbolReference(this.componentPath, {
             meaning: this.meaning,
@@ -253,7 +462,10 @@ overloadIndex: overloadIndex
     };
-    SymbolReference.prototype.addNavigationStep = function (navigation, text) {
-        return new SymbolReference(this.component.addNavigationStep(navigation, text));
+    SymbolReference.prototype.addNavigationStep = function (navigation, component) {
+        if (!this.componentPath) {
+            throw new Error('Cannot add a navigation step to an empty symbol reference.');
+        }
+        return new SymbolReference(this.componentPath.addNavigationStep(navigation, component));
     };
     SymbolReference.prototype.toString = function () {
-        var result = "" + (this.component || '');
+        var result = "" + (this.componentPath || '');
         if (this.meaning && this.overloadIndex !== undefined) {
@@ -273,2 +485,37 @@ result += ":" + this.meaning + "(" + this.overloadIndex + ")";
 exports.SymbolReference = SymbolReference;
+function tokenToString(token) {
+    switch (token) {
+        case 2 /* OpenBraceToken */: return '{';
+        case 3 /* CloseBraceToken */: return '}';
+        case 4 /* OpenParenToken */: return '(';
+        case 5 /* CloseParenToken */: return ')';
+        case 6 /* OpenBracketToken */: return '[';
+        case 7 /* CloseBracketToken */: return ']';
+        case 8 /* ExclamationToken */: return '!';
+        case 9 /* DotToken */: return '.';
+        case 10 /* HashToken */: return '#';
+        case 11 /* TildeToken */: return '~';
+        case 12 /* ColonToken */: return ':';
+        case 13 /* CommaToken */: return ',';
+        case 17 /* ClassKeyword */: return 'class';
+        case 18 /* InterfaceKeyword */: return 'interface';
+        case 19 /* TypeKeyword */: return 'type';
+        case 20 /* EnumKeyword */: return 'enum';
+        case 21 /* NamespaceKeyword */: return 'namespace';
+        case 22 /* FunctionKeyword */: return 'function';
+        case 23 /* VarKeyword */: return 'var';
+        case 24 /* ConstructorKeyword */: return 'constructor';
+        case 25 /* MemberKeyword */: return 'member';
+        case 26 /* EventKeyword */: return 'event';
+        case 27 /* CallKeyword */: return 'call';
+        case 28 /* NewKeyword */: return 'new';
+        case 29 /* IndexKeyword */: return 'index';
+        case 30 /* ComplexKeyword */: return 'complex';
+        case 0 /* None */: return '<none>';
+        case 1 /* EofToken */: return '<eof>';
+        case 14 /* DecimalDigits */: return '<decimal digits>';
+        case 15 /* String */: return '<string>';
+        case 16 /* Text */: return '<text>';
+    }
+}
 var Scanner = /** @class */ (function () {
@@ -370,13 +617,14 @@ function Scanner(text) {
                 case 'interface': return this._token = 18 /* InterfaceKeyword */;
-                case 'typealias': return this._token = 19 /* TypealiasKeyword */;
+                case 'type': return this._token = 19 /* TypeKeyword */;
                 case 'enum': return this._token = 20 /* EnumKeyword */;
                 case 'namespace': return this._token = 21 /* NamespaceKeyword */;
                 case 'function': return this._token = 22 /* FunctionKeyword */;
-                case 'variable': return this._token = 23 /* VariableKeyword */;
+                case 'var': return this._token = 23 /* VarKeyword */;
                 case 'constructor': return this._token = 24 /* ConstructorKeyword */;
                 case 'member': return this._token = 25 /* MemberKeyword */;
                 case 'event': return this._token = 26 /* EventKeyword */;
-                case 'enummember': return this._token = 27 /* EnumMemberKeyword */;
-                case 'signature': return this._token = 28 /* SignatureKeyword */;
-                case 'type': return this._token = 29 /* TypeKeyword */;
+                case 'call': return this._token = 27 /* CallKeyword */;
+                case 'new': return this._token = 28 /* NewKeyword */;
+                case 'index': return this._token = 29 /* IndexKeyword */;
+                case 'complex': return this._token = 30 /* ComplexKeyword */;
             }
@@ -488,8 +736,9 @@ }
     function Parser(text) {
-        this.scanner = new Scanner(text);
-        this.scanner.scan();
+        this._errors = [];
+        this._scanner = new Scanner(text);
+        this._scanner.scan();
     }
     Object.defineProperty(Parser.prototype, "eof", {
         get: function () {
-            return this.scanner.eof;
+            return this._scanner.eof;
         },
@@ -499,2 +748,9 @@ enumerable: true,
     });
+    Object.defineProperty(Parser.prototype, "errors", {
+        get: function () {
+            return this._errors;
+        },
+        enumerable: true,
+        configurable: true
+    });
     Parser.prototype.parseDeclarationReference = function () {
@@ -512,5 +768,5 @@ var source;
             var root = this.parseComponent();
-            if (this.optionalToken(8 /* ExclamationToken */)) {
+            if (root instanceof ComponentString && this.optionalToken(8 /* ExclamationToken */)) {
                 // Definitely path for module source
-                source = new ModuleSource(root, /*escapeIfNeeded*/ false);
+                source = new ModuleSource(root.text, /*userEscaped*/ true);
                 // Check for optional `~` navigation token.
@@ -526,17 +782,20 @@ if (this.optionalToken(11 /* TildeToken */)) {
                 // Definitely a symbol
-                symbol = this.parseSymbolRest(this.parseComponentRest(new RootComponent(root, /*escapeIfNeeded*/ false)));
+                symbol = this.parseSymbolRest(this.parseComponentRest(new ComponentRoot(root)));
             }
         }
+        else if (this.token() === 12 /* ColonToken */) {
+            symbol = this.parseSymbolRest(new ComponentRoot(new ComponentString('', /*userEscaped*/ true)));
+        }
         return new DeclarationReference(source, navigation, symbol);
     };
-    Parser.prototype.parseComponent = function () {
-        switch (this.scanner.token()) {
+    Parser.prototype.parseComponentString = function () {
+        switch (this._scanner.token()) {
             case 15 /* String */:
                 return this.parseString();
             default:
-                return this.parseComponentAtoms();
+                return this.parseComponentCharacters();
         }
     };
     Parser.prototype.token = function () {
-        return this.scanner.token();
+        return this._scanner.token();
     };
@@ -558,6 +817,6 @@ Parser.prototype.parseSymbol = function () {
         if (!this.isStartOfComponent()) {
-            return this.fail();
+            return this.fail('Component expected', new ComponentRoot(new ComponentString('', /*userEscaped*/ true)));
         }
-        var text = this.parseComponent();
-        return new RootComponent(text, /*escapeIfNeeded*/ false);
+        var component = this.parseComponent();
+        return new ComponentRoot(component);
     };
@@ -571,4 +830,4 @@ Parser.prototype.parseComponentRest = function (component) {
                     var navigation = this.parseNavigation();
-                    var text = this.parseComponent();
-                    component = new NavigationComponent(component, navigation, text, /*escapeIfNeeded*/ false);
+                    var right = this.parseComponent();
+                    component = new ComponentNavigation(component, navigation, right);
                     break;
@@ -581,24 +840,25 @@ default:
     Parser.prototype.parseNavigation = function () {
-        switch (this.scanner.token()) {
-            case 9 /* DotToken */: return this.scanner.scan(), "." /* Exports */;
-            case 10 /* HashToken */: return this.scanner.scan(), "#" /* Members */;
-            case 11 /* TildeToken */: return this.scanner.scan(), "~" /* Locals */;
-            default: return this.fail();
+        switch (this._scanner.token()) {
+            case 9 /* DotToken */: return this._scanner.scan(), "." /* Exports */;
+            case 10 /* HashToken */: return this._scanner.scan(), "#" /* Members */;
+            case 11 /* TildeToken */: return this._scanner.scan(), "~" /* Locals */;
+            default: return this.fail('Expected \'.\', \'#\', or \'~\'', "." /* Exports */);
         }
     };
     Parser.prototype.tryParseMeaning = function () {
-        switch (this.scanner.rescanMeaning()) {
-            case 17 /* ClassKeyword */: return this.scanner.scan(), "class" /* Class */;
-            case 18 /* InterfaceKeyword */: return this.scanner.scan(), "interface" /* Interface */;
-            case 19 /* TypealiasKeyword */: return this.scanner.scan(), "typealias" /* TypeAlias */;
-            case 20 /* EnumKeyword */: return this.scanner.scan(), "enum" /* Enum */;
-            case 21 /* NamespaceKeyword */: return this.scanner.scan(), "namespace" /* Namespace */;
-            case 22 /* FunctionKeyword */: return this.scanner.scan(), "function" /* Function */;
-            case 23 /* VariableKeyword */: return this.scanner.scan(), "variable" /* Variable */;
-            case 24 /* ConstructorKeyword */: return this.scanner.scan(), "constructor" /* Constructor */;
-            case 25 /* MemberKeyword */: return this.scanner.scan(), "member" /* Member */;
-            case 26 /* EventKeyword */: return this.scanner.scan(), "event" /* Event */;
-            case 27 /* EnumMemberKeyword */: return this.scanner.scan(), "enummember" /* EnumMember */;
-            case 28 /* SignatureKeyword */: return this.scanner.scan(), "signature" /* Signature */;
-            case 29 /* TypeKeyword */: return this.scanner.scan(), "type" /* Type */;
+        switch (this._scanner.rescanMeaning()) {
+            case 17 /* ClassKeyword */: return this._scanner.scan(), "class" /* Class */;
+            case 18 /* InterfaceKeyword */: return this._scanner.scan(), "interface" /* Interface */;
+            case 19 /* TypeKeyword */: return this._scanner.scan(), "type" /* TypeAlias */;
+            case 20 /* EnumKeyword */: return this._scanner.scan(), "enum" /* Enum */;
+            case 21 /* NamespaceKeyword */: return this._scanner.scan(), "namespace" /* Namespace */;
+            case 22 /* FunctionKeyword */: return this._scanner.scan(), "function" /* Function */;
+            case 23 /* VarKeyword */: return this._scanner.scan(), "var" /* Variable */;
+            case 24 /* ConstructorKeyword */: return this._scanner.scan(), "constructor" /* Constructor */;
+            case 25 /* MemberKeyword */: return this._scanner.scan(), "member" /* Member */;
+            case 26 /* EventKeyword */: return this._scanner.scan(), "event" /* Event */;
+            case 27 /* CallKeyword */: return this._scanner.scan(), "call" /* CallSignature */;
+            case 28 /* NewKeyword */: return this._scanner.scan(), "new" /* ConstructSignature */;
+            case 29 /* IndexKeyword */: return this._scanner.scan(), "index" /* IndexSignature */;
+            case 30 /* ComplexKeyword */: return this._scanner.scan(), "complex" /* ComplexType */;
             default: return undefined;
@@ -619,9 +879,9 @@ }
     Parser.prototype.parseDecimalDigits = function () {
-        switch (this.scanner.rescanDecimalDigits()) {
+        switch (this._scanner.rescanDecimalDigits()) {
             case 14 /* DecimalDigits */:
-                var value = +this.scanner.tokenText;
-                this.scanner.scan();
+                var value = +this._scanner.tokenText;
+                this._scanner.scan();
                 return value;
             default:
-                return this.fail();
+                return this.fail('Decimal digit expected', 0);
         }
@@ -639,12 +899,9 @@ };
     };
-    Parser.prototype.parseComponentAtoms = function () {
+    Parser.prototype.parseComponentCharacters = function () {
         var text = '';
         for (;;) {
-            switch (this.scanner.token()) {
+            switch (this._scanner.token()) {
                 case 16 /* Text */:
                     text += this.parseText();
                     break;
-                case 6 /* OpenBracketToken */:
-                    text += this.parseBracketedComponent();
-                    break;
                 default:
@@ -656,44 +913,38 @@ return text;
     Parser.prototype.parseText = function () {
-        if (this.scanner.token() === 16 /* Text */) {
-            var text = this.scanner.tokenText;
-            this.scanner.scan();
+        if (this._scanner.token() === 16 /* Text */) {
+            var text = this._scanner.tokenText;
+            this._scanner.scan();
             return text;
         }
-        return this.fail();
+        return this.fail('Text expected', '');
     };
     Parser.prototype.parseString = function () {
-        if (this.scanner.token() === 15 /* String */) {
-            var text = this.scanner.tokenText;
-            this.scanner.scan();
+        if (this._scanner.token() === 15 /* String */) {
+            var text = this._scanner.tokenText;
+            var stringIsUnterminated = this._scanner.stringIsUnterminated;
+            this._scanner.scan();
+            if (stringIsUnterminated) {
+                return this.fail('Unterminated string literal', text);
+            }
             return text;
         }
-        return this.fail();
+        return this.fail('String expected', '');
     };
+    Parser.prototype.parseComponent = function () {
+        switch (this._scanner.token()) {
+            case 6 /* OpenBracketToken */:
+                return this.parseBracketedComponent();
+            default:
+                return new ParsedComponentString(this.parseComponentString(), /*userEscaped*/ true);
+        }
+    };
     Parser.prototype.parseBracketedComponent = function () {
         this.expectToken(6 /* OpenBracketToken */);
-        var text = this.parseBracketedAtoms();
+        var reference = this.parseDeclarationReference();
         this.expectToken(7 /* CloseBracketToken */);
-        return "[" + text + "]";
+        return new ComponentReference(reference);
     };
-    Parser.prototype.parseBracketedAtoms = function () {
-        var text = '';
-        for (;;) {
-            switch (this.scanner.token()) {
-                case 15 /* String */:
-                    text += this.parseString();
-                    break;
-                case 16 /* Text */:
-                    text += this.parseText();
-                    break;
-                case 6 /* OpenBracketToken */:
-                    text += this.parseBracketedComponent();
-                    break;
-                default:
-                    return text;
-            }
-        }
-    };
     Parser.prototype.optionalToken = function (token) {
-        if (this.scanner.token() === token) {
-            this.scanner.scan();
+        if (this._scanner.token() === token) {
+            this._scanner.scan();
             return true;
@@ -704,9 +955,12 @@ }
     Parser.prototype.expectToken = function (token, message) {
-        if (this.scanner.token() !== token) {
-            return this.fail(message);
+        if (this._scanner.token() !== token) {
+            var expected = tokenToString(token);
+            var actual = tokenToString(this._scanner.token());
+            return this.fail(message || "Expected token '" + expected + "', received '" + actual + "' instead.", undefined);
         }
-        this.scanner.scan();
+        this._scanner.scan();
     };
-    Parser.prototype.fail = function (message) {
-        throw new SyntaxError("Invalid DeclarationReference '" + this.scanner.text + "'" + (message ? ": " + message : ''));
+    Parser.prototype.fail = function (message, fallback) {
+        this._errors.push(message);
+        return fallback;
     };
@@ -822,2 +1076,11 @@ return Parser;
 }
+function escapeIfNeeded(text, userEscaped) {
+    if (userEscaped) {
+        if (!DeclarationReference.isWellFormedComponentString(text)) {
+            throw new SyntaxError("Invalid Component '" + text + "'");
+        }
+        return text;
+    }
+    return DeclarationReference.escapeComponentString(text);
+}
 //# sourceMappingURL=DeclarationReference.js.map

package.json

 {
   "name": "@microsoft/tsdoc",
-  "version": "0.12.10",
+  "version": "0.12.11",
   "description": "A parser for the TypeScript doc comment syntax",
@@ -5,0 +5,0 @@ "keywords": [

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

Improved metrics

Total package byte prevSize

730055

increased by3.07%

Lines of code

12637

increased by2.71%

No dependency changes