Skip to content

Commit 4acbe87

Browse files
pgonzalpgonzal
committed
Update all projects to use the new PackageName API
1 parent 05dd86c commit 4acbe87

File tree

18 files changed

+54
-153
lines changed

18 files changed

+54
-153
lines changed

‎apps/api-documenter/src/markdown/MarkdownDocumenter.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
import * as fsx from 'fs-extra';
55
import * as path from 'path';
66

7-
import { Text } from '@microsoft/node-core-library';
7+
import { Text, PackageName } from '@microsoft/node-core-library';
88
import {
99
IApiClass,
1010
IApiEnum,
@@ -63,7 +63,7 @@ export class MarkdownDocumenter {
6363
private _writePackagePage(docPackage: DocItem): void {
6464
console.log(`Writing ${docPackage.name} package`);
6565

66-
const unscopedPackageName: string = Utilities.getUnscopedPackageName(docPackage.name);
66+
const unscopedPackageName: string = PackageName.getUnscopedName(docPackage.name);
6767

6868
const markupPage: IMarkupPage = Markup.createPage(`${unscopedPackageName} package`);
6969
this._writeBreadcrumb(markupPage, docPackage);
@@ -604,7 +604,7 @@ export class MarkdownDocumenter {
604604
let baseName: string = '';
605605
for (const part of docItem.getHierarchy()) {
606606
if (part.kind === DocItemKind.Package) {
607-
baseName = Utilities.getUnscopedPackageName(part.name);
607+
baseName = PackageName.getUnscopedName(part.name);
608608
} else {
609609
baseName += '.' + part.name;
610610
}

‎apps/api-documenter/src/utils/DocItemSet.ts‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,14 @@
11
// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
22
// See LICENSE in the project root for license information.
33

4+
import { PackageName } from '@microsoft/node-core-library';
45
import {
56
IApiPackage,
67
ApiItem,
78
ApiJsonFile,
89
IApiItemReference
910
} from '@microsoft/api-extractor';
1011

11-
import { Utilities } from './Utilities';
12-
1312
export enum DocItemKind {
1413
Package,
1514
Namespace,
@@ -219,11 +218,7 @@ export class DocItemSet {
219218
closestMatch: undefined
220219
};
221220

222-
const packageName: string = Utilities.getScopedPackageName(reference.scopeName, reference.packageName);
223-
if (!packageName) {
224-
// This would indicate an invalid data file, since API Extractor is supposed to normalize this
225-
throw new Error('resolveApiItemReference() failed because the packageName should not be empty');
226-
}
221+
const packageName: string = PackageName.combineParts(reference.scopeName, reference.packageName);
227222

228223
let current: DocItem | undefined = undefined;
229224

‎apps/api-documenter/src/utils/Utilities.ts‎

Lines changed: 0 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -32,27 +32,6 @@ export class Utilities {
3232

3333
}
3434

35-
/**
36-
* Strips the scope from an NPM package name. For example, given "@microsoft/decorators"
37-
* this function would return "decorators".
38-
*/
39-
public static getUnscopedPackageName(packageName: string): string {
40-
// If there is a "/", return everything after the last "/"
41-
return packageName.split('/').slice(-1)[0];
42-
}
43-
44-
/**
45-
* Creates a scoped package name by assembling the scope name and unscoped package name.
46-
* For example, getScopedPackageName("", "example") returns "example", whereas
47-
* getScopedPackageName("@ms", "example") returns "@ms/example".
48-
*/
49-
public static getScopedPackageName(scopeName: string, packageName: string): string {
50-
if (scopeName) {
51-
return scopeName + '/' + packageName;
52-
}
53-
return packageName;
54-
}
55-
5635
/**
5736
* Generates a concise signature for a function. Example: "getArea(width, height)"
5837
*/

‎apps/api-documenter/src/yaml/YamlDocumenter.ts‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ import * as path from 'path';
66
import * as colors from 'colors';
77

88
import yaml = require('js-yaml');
9-
import { JsonFile, JsonSchema, Text } from '@microsoft/node-core-library';
9+
import { JsonFile, JsonSchema, Text, PackageName } from '@microsoft/node-core-library';
1010
import {
1111
MarkupElement,
1212
IApiMethod,
@@ -165,7 +165,7 @@ export class YamlDocumenter {
165165
if (docItem.kind === DocItemKind.Namespace) {
166166
// Namespaces don't have nodes yet
167167
tocItem = {
168-
name: Utilities.getUnscopedPackageName(docItem.name)
168+
name: PackageName.getUnscopedName(docItem.name)
169169
};
170170
} else {
171171
if (this._shouldEmbed(docItem.kind)) {
@@ -174,7 +174,7 @@ export class YamlDocumenter {
174174
}
175175

176176
tocItem = {
177-
name: Utilities.getUnscopedPackageName(docItem.name),
177+
name: PackageName.getUnscopedName(docItem.name),
178178
uid: this._getUid(docItem)
179179
};
180180
}
@@ -399,7 +399,7 @@ export class YamlDocumenter {
399399
for (const current of docItem.getHierarchy()) {
400400
switch (current.kind) {
401401
case DocItemKind.Package:
402-
result += Utilities.getUnscopedPackageName(current.name);
402+
result += PackageName.getUnscopedName(current.name);
403403
break;
404404
default:
405405
result += '.';
@@ -425,7 +425,7 @@ export class YamlDocumenter {
425425
for (const current of docItem.getHierarchy()) {
426426
switch (current.kind) {
427427
case DocItemKind.Package:
428-
result += Utilities.getUnscopedPackageName(current.name);
428+
result += PackageName.getUnscopedName(current.name);
429429
break;
430430
default:
431431
if (current.parent && current.parent.kind === DocItemKind.Package) {

‎apps/api-extractor/src/ApiDefinitionReference.ts‎

Lines changed: 7 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
22
// See LICENSE in the project root for license information.
33

4+
import { IParsedPackageName, PackageName } from '@microsoft/node-core-library';
45
import { IApiItemReference } from './api/ApiItem';
56

67
/**
@@ -37,25 +38,6 @@ export interface IApiDefinitionReferenceParts {
3738
memberName: string;
3839
}
3940

40-
/**
41-
* A scope and package name are semantic information within an API reference expression.
42-
* If there is no scope or package, then the corresponding values will be an empty string.
43-
*
44-
* Example: '@microsoft/Utilities' -> \{ scope: '@microsoft', package: 'Utilities' \}
45-
* Example: 'Utilities' -> \{ scope: '', package: 'Utilities' \}
46-
*/
47-
export interface IScopedPackageName {
48-
/**
49-
* The scope name of an API reference expression.
50-
*/
51-
scope: string;
52-
53-
/**
54-
* The package name of an API reference expression.
55-
*/
56-
package: string;
57-
}
58-
5941
/**
6042
* {@inheritdoc IApiDefinitionReferenceParts}
6143
*/
@@ -124,9 +106,9 @@ export class ApiDefinitionReference {
124106
let parts: string[] | null = apiReferenceExpr.match(ApiDefinitionReference._packageRegEx);
125107
if (parts) {
126108
// parts[1] is of the form ‘@microsoft/sp-core-library’ or ‘sp-core-library’
127-
const scopePackageName: IScopedPackageName = ApiDefinitionReference.parseScopedPackageName(parts[1]);
128-
apiDefRefParts.scopeName = scopePackageName.scope;
129-
apiDefRefParts.packageName = scopePackageName.package;
109+
const parsedPackageName: IParsedPackageName = PackageName.parse(parts[1]);
110+
apiDefRefParts.scopeName = parsedPackageName.scope;
111+
apiDefRefParts.packageName = parsedPackageName.unscopedName;
130112
apiReferenceExpr = parts[2]; // e.g. Guid.equals
131113
}
132114

@@ -150,38 +132,17 @@ export class ApiDefinitionReference {
150132
return ApiDefinitionReference.createFromParts(apiDefRefParts);
151133
}
152134

153-
/**
154-
* For a scoped NPM package name this separates the scope and package parts. For example:
155-
* parseScopedPackageName('@my-scope/myproject') = { scope: '@my-scope', package: 'myproject' }
156-
* parseScopedPackageName('myproject') = { scope: '', package: 'myproject' }
157-
*/
158-
public static parseScopedPackageName(scopedName: string): IScopedPackageName {
159-
if (scopedName.substr(0, 1) !== '@') {
160-
return { scope: '', package: scopedName };
161-
}
162-
163-
const slashIndex: number = scopedName.indexOf('/');
164-
if (slashIndex >= 0) {
165-
return { scope: scopedName.substr(0, slashIndex), package: scopedName.substr(slashIndex + 1) };
166-
} else {
167-
throw new Error('Invalid scoped name: ' + scopedName);
168-
}
169-
}
170-
171135
/**
172136
* Stringifies the ApiDefinitionReferenceOptions up and including the
173137
* scope and package name.
174138
*
175139
* Example output: '@microsoft/Utilities'
176140
*/
177141
public toScopePackageString(): string {
178-
let result: string = '';
179-
if (this.scopeName) {
180-
result += `${this.scopeName}/${this.packageName}`;
181-
} else if (this.packageName) {
182-
result += this.packageName;
142+
if (!this.packageName) {
143+
return '';
183144
}
184-
return result;
145+
return PackageName.combineParts(this.scopeName, this.packageName);
185146
}
186147

187148
/**

‎apps/api-extractor/src/DocItemLoader.ts‎

Lines changed: 0 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -20,22 +20,6 @@ import { ResolvedApiItem } from './ResolvedApiItem';
2020
import { ApiJsonFile } from './api/ApiJsonFile';
2121
import { IReferenceResolver } from './aedoc/ApiDocumentation';
2222

23-
/**
24-
* Used to describe a parsed package name in the form of
25-
* scopedName/packageName. Ex: @microsoft/sp-core-library.
26-
*/
27-
export interface IParsedScopeName {
28-
/**
29-
* The scope prefix. Ex: @microsoft.
30-
*/
31-
scope: string;
32-
33-
/**
34-
* The specific package name. Ex: sp-core-library.
35-
*/
36-
name: string;
37-
}
38-
3923
/**
4024
* A loader for locating the ApiItem associated with a given project and API item, or
4125
* for locating an AstItem locally.

‎apps/api-extractor/src/ExtractorContext.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
import * as ts from 'typescript';
55
import * as fsx from 'fs-extra';
66
import * as path from 'path';
7-
import { PackageJsonLookup, IPackageJson } from '@microsoft/node-core-library';
7+
import { PackageJsonLookup, IPackageJson, PackageName, IParsedPackageName } from '@microsoft/node-core-library';
88

99
import { AstPackage } from './ast/AstPackage';
1010
import { DocItemLoader } from './DocItemLoader';
@@ -53,6 +53,8 @@ export class ExtractorContext {
5353
*/
5454
public readonly packageJson: IPackageJson;
5555

56+
public readonly parsedPackageName: IParsedPackageName;
57+
5658
/**
5759
* One DocItemLoader is needed per analyzer to look up external API members
5860
* as needed.
@@ -85,6 +87,8 @@ export class ExtractorContext {
8587

8688
this.packageJson = this.packageJsonLookup.tryLoadPackageJsonFor(this._packageFolder)!;
8789

90+
this.parsedPackageName = PackageName.parse(this.packageJson.name);
91+
8892
this.docItemLoader = new DocItemLoader(this._packageFolder);
8993

9094
this._logger = options.logger;

‎apps/api-extractor/src/aedoc/DocElementParser.ts‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,14 @@
11
// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
22
// See LICENSE in the project root for license information.
33

4+
import { IParsedPackageName } from '@microsoft/node-core-library';
45
import {
56
MarkupLinkTextElement,
67
MarkupBasicElement,
78
MarkupElement
89
} from '../markup/MarkupElement';
910
import { Markup } from '../markup/Markup';
10-
import { ApiDefinitionReference, IScopedPackageName } from '../ApiDefinitionReference';
11+
import { ApiDefinitionReference } from '../ApiDefinitionReference';
1112
import { ApiDocumentation } from '../aedoc/ApiDocumentation';
1213
import { AstItemKind } from '../ast/AstItem';
1314
import { Token, TokenType } from '../aedoc/Token';
@@ -178,11 +179,10 @@ export class DocElementParser {
178179
}
179180

180181
// If the package name is unspecified, assume it is the current package
181-
const scopePackageName: IScopedPackageName = ApiDefinitionReference.parseScopedPackageName(
182-
documentation.context.packageName);
182+
const parsedPackageName: IParsedPackageName = documentation.context.parsedPackageName;
183183

184-
normalizedApiLink.scopeName = scopePackageName.scope;
185-
normalizedApiLink.packageName = scopePackageName.package;
184+
normalizedApiLink.scopeName = parsedPackageName.scope;
185+
normalizedApiLink.packageName = parsedPackageName.unscopedName;
186186
}
187187

188188
linkMarkupElement = Markup.createApiLink(displayTextElements, normalizedApiLink);

‎apps/api-extractor/src/ast/AstItem.ts‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
/* tslint:disable:no-constant-condition */
66

77
import * as ts from 'typescript';
8+
import { IPackageJson, IParsedPackageName, PackageName } from '@microsoft/node-core-library';
89
import { ExtractorContext } from '../ExtractorContext';
910
import { ApiDocumentation } from '../aedoc/ApiDocumentation';
1011
import { MarkupElement } from '../markup/MarkupElement';
@@ -14,11 +15,9 @@ import { Markup } from '../markup/Markup';
1415
import { ResolvedApiItem } from '../ResolvedApiItem';
1516
import {
1617
ApiDefinitionReference,
17-
IScopedPackageName,
1818
IApiDefinitionReferenceParts
1919
} from '../ApiDefinitionReference';
2020
import { AstItemContainer } from './AstItemContainer';
21-
import { IPackageJson } from '@microsoft/node-core-library';
2221

2322
/**
2423
* Indicates the type of definition represented by a AstItem object.
@@ -650,12 +649,12 @@ export abstract class AstItem {
650649

651650
// External
652651
// Attempt to load from docItemLoader
653-
const scopedPackageName: IScopedPackageName = ApiDefinitionReference.parseScopedPackageName(
652+
const parsedPackageName: IParsedPackageName = PackageName.parse(
654653
typeReferencePackageName
655654
);
656655
const apiDefinitionRefParts: IApiDefinitionReferenceParts = {
657-
scopeName: scopedPackageName.scope,
658-
packageName: scopedPackageName.package,
656+
scopeName: parsedPackageName.scope,
657+
packageName: parsedPackageName.unscopedName,
659658
exportName: '',
660659
memberName: ''
661660
};

‎apps/api-extractor/src/ast/AstMethod.ts‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,12 @@
22
// See LICENSE in the project root for license information.
33

44
import * as ts from 'typescript';
5+
import { IParsedPackageName } from '@microsoft/node-core-library';
56
import { AstItem, AstItemKind, IAstItemOptions } from './AstItem';
67
import { AstMember } from './AstMember';
78
import { AstParameter } from './AstParameter';
89
import { TypeScriptHelpers } from '../utils/TypeScriptHelpers';
910
import { Markup } from '../markup/Markup';
10-
import { ApiDefinitionReference, IScopedPackageName } from '../ApiDefinitionReference';
1111

1212
/**
1313
* This class is part of the AstItem abstract syntax tree. It represents functions that are members of
@@ -70,17 +70,16 @@ export class AstMethod extends AstMember {
7070
this.documentation.summary.push(
7171
...Markup.createTextElements('Constructs a new instance of the '));
7272

73-
const scopedPackageName: IScopedPackageName = ApiDefinitionReference
74-
.parseScopedPackageName(this.context.package.name);
73+
const parsedPackageName: IParsedPackageName = this.context.parsedPackageName;
7574

7675
const parentParentContainer: AstItem | undefined = this.parentContainer.parentContainer;
7776
if (parentParentContainer && parentParentContainer.kind === AstItemKind.Namespace) {
7877
// This is a temporary workaround to support policies.namespaceSupport === permissive
7978
// until the new AstSymbolTable engine is wired up
8079
this.documentation.summary.push(
8180
Markup.createApiLinkFromText(this.parentContainer.name, {
82-
scopeName: scopedPackageName.scope,
83-
packageName: scopedPackageName.package,
81+
scopeName: parsedPackageName.scope,
82+
packageName: parsedPackageName.unscopedName,
8483
exportName: parentParentContainer.name,
8584
memberName: this.parentContainer.name
8685
}
@@ -89,8 +88,8 @@ export class AstMethod extends AstMember {
8988
} else {
9089
this.documentation.summary.push(
9190
Markup.createApiLinkFromText(this.parentContainer.name, {
92-
scopeName: scopedPackageName.scope,
93-
packageName: scopedPackageName.package,
91+
scopeName: parsedPackageName.scope,
92+
packageName: parsedPackageName.unscopedName,
9493
exportName: this.parentContainer.name,
9594
memberName: ''
9695
}

0 commit comments

Comments
 (0)