Add additional utility methods to DeclarationReference

common/changes/@microsoft/tsdoc/beta-declref-utility_2022-05-16-07-02.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/tsdoc",
+      "comment": "add utility methods to DeclarationReference components",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@microsoft/tsdoc",
+  "email": "ron.buckton@microsoft.com"
+}

tsdoc/src/parser/StringChecks.ts

@@ -132,6 +132,44 @@ export class StringChecks {
     return undefined;
   }
 
+  /**
+   * Tests whether the input string is a valid scope portion of a scoped NPM package name.
+   */
+  public static explainIfInvalidPackageScope(scopeName: string): string | undefined {
+    if (scopeName.length === 0) {
+      return 'An package scope cannot be an empty string';
+    }
+
+    if (scopeName.charAt(0) !== '@') {
+      return `An package scope must start with '@'`;
+    }
+
+    if (!StringChecks._validPackageNameRegExp.test(`${scopeName}/package`)) {
+      return `The name ${JSON.stringify(scopeName)} is not a valid package scope`;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Tests whether the input string is a valid non-scope portion of a scoped NPM package name.
+   */
+  public static explainIfInvalidUnscopedPackageName(unscopedPackageName: string): string | undefined {
+    if (unscopedPackageName.length === 0) {
+      return 'An unscoped package name cannot be an empty string';
+    }
+
+    if (unscopedPackageName.charAt(0) === '@') {
+      return `An unscoped package name cannot start with '@'`;
+    }
+
+    if (!StringChecks._validPackageNameRegExp.test(`@scope/${unscopedPackageName}`)) {
+      return `The name ${JSON.stringify(unscopedPackageName)} is not a valid unscoped package name`;
+    }
+
+    return undefined;
+  }
+
   /**
    * Tests whether the input string is a valid declaration reference import path.
    */