Added tags logic for completed-docs (#2415)

src/rules/completed-docs/blockExclusion.ts

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2017 Palantir Technologies, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as ts from "typescript";
+
+import * as Lint from "../../index";
+import { ALL, Visibility, VISIBILITY_EXPORTED, VISIBILITY_INTERNAL } from "../completedDocsRule";
+import { Exclusion } from "./exclusion";
+
+export interface IBlockExclusionDescriptor {
+    visibilities?: Visibility[];
+}
+
+export class BlockExclusion extends Exclusion<IBlockExclusionDescriptor> {
+    public readonly visibilities: Set<Visibility> = this.createSet(this.descriptor.visibilities);
+
+    public excludes(node: ts.Node) {
+        if (this.visibilities.has(ALL)) {
+            return false;
+        }
+
+        if (Lint.hasModifier(node.modifiers, ts.SyntaxKind.ExportKeyword)) {
+            return !this.visibilities.has(VISIBILITY_EXPORTED);
+        }
+
+        return !this.visibilities.has(VISIBILITY_INTERNAL);
+    }
+}

src/rules/completed-docs/classExclusion.ts

@@ -0,0 +1,68 @@
+/**
+ * @license
+ * Copyright 2013 Palantir Technologies, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as ts from "typescript";
+
+import * as Lint from "../../index";
+import {
+    ALL, Location, LOCATION_INSTANCE, LOCATION_STATIC, Privacy, PRIVACY_PRIVATE, PRIVACY_PROTECTED, PRIVACY_PUBLIC,
+} from "../completedDocsRule";
+import { Exclusion } from "./exclusion";
+
+export interface IClassExclusionDescriptor {
+    locations?: Location[];
+    privacies?: Privacy[];
+}
+
+export class ClassExclusion extends Exclusion<IClassExclusionDescriptor> {
+    public readonly locations: Set<Location> = this.createSet(this.descriptor.locations);
+    public readonly privacies: Set<Privacy> = this.createSet(this.descriptor.privacies);
+
+    public excludes(node: ts.Node) {
+        return !(
+            this.shouldLocationBeDocumented(node)
+            && this.shouldPrivacyBeDocumented(node));
+    }
+
+    private shouldLocationBeDocumented(node: ts.Node) {
+        if (this.locations.has(ALL)) {
+            return true;
+        }
+
+        if (Lint.hasModifier(node.modifiers, ts.SyntaxKind.StaticKeyword)) {
+            return this.locations.has(LOCATION_STATIC);
+        }
+
+        return this.locations.has(LOCATION_INSTANCE);
+    }
+
+    private shouldPrivacyBeDocumented(node: ts.Node) {
+        if (this.privacies.has(ALL)) {
+            return true;
+        }
+
+        if (Lint.hasModifier(node.modifiers, ts.SyntaxKind.PrivateKeyword)) {
+            return this.privacies.has(PRIVACY_PRIVATE);
+        }
+
+        if (Lint.hasModifier(node.modifiers, ts.SyntaxKind.ProtectedKeyword)) {
+            return this.privacies.has(PRIVACY_PROTECTED);
+        }
+
+        return this.privacies.has(PRIVACY_PUBLIC);
+    }
+}

src/rules/completed-docs/exclusion.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2013 Palantir Technologies, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as ts from "typescript";
+
+import { All, ALL } from "../completedDocsRule";
+import { ExclusionDescriptor } from "./exclusionDescriptors";
+
+export abstract class Exclusion<TDescriptor extends ExclusionDescriptor> {
+    public constructor(protected readonly descriptor: Partial<TDescriptor> = {}) { }
+
+    public abstract excludes(node: ts.Node): boolean;
+
+    protected createSet<T extends All | string>(values?: T[]): Set<T> {
+        if (values === undefined || values.length === 0) {
+            values = [ALL as T];
+        }
+
+        return new Set(values);
+    }
+}

src/rules/completed-docs/exclusionDescriptors.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2013 Palantir Technologies, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { DocType } from "../completedDocsRule";
+import { IBlockExclusionDescriptor } from "./blockExclusion";
+import { IClassExclusionDescriptor } from "./classExclusion";
+import { ITagExclusionDescriptor } from "./tagExclusion";
+
+export type ExclusionDescriptor = IBlockExclusionDescriptor | IClassExclusionDescriptor | ITagExclusionDescriptor;
+
+export type InputExclusionDescriptor = boolean | ExclusionDescriptor;
+
+export interface IExclusionDescriptors {
+    [type: string /* DocType */]: ExclusionDescriptor;
+}
+
+export type IInputExclusionDescriptors = DocType | {
+    [type: string /* DocType */]: InputExclusionDescriptor;
+};

src/rules/completed-docs/exclusionFactory.ts

@@ -0,0 +1,65 @@
+/**
+ * @license
+ * Copyright 2013 Palantir Technologies, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { hasOwnProperty } from "../../utils";
+import { DocType } from "../completedDocsRule";
+import { BlockExclusion, IBlockExclusionDescriptor } from "./blockExclusion";
+import { ClassExclusion, IClassExclusionDescriptor } from "./classExclusion";
+import { Exclusion } from "./exclusion";
+import { IInputExclusionDescriptors, InputExclusionDescriptor } from "./exclusionDescriptors";
+import { ITagExclusionDescriptor, TagExclusion } from "./tagExclusion";
+
+export class ExclusionFactory {
+    public constructExclusionsMap(ruleArguments: IInputExclusionDescriptors[]): Map<DocType, Array<Exclusion<any>>> {
+        const exclusionsMap: Map<DocType, Array<Exclusion<any>>> = new Map();
+
+        for (const ruleArgument of ruleArguments) {
+            this.addRequirements(exclusionsMap, ruleArgument);
+        }
+
+        return exclusionsMap;
+    }
+
+    private addRequirements(exclusionsMap: Map<DocType, Array<Exclusion<any>>>, descriptors: IInputExclusionDescriptors) {
+        if (typeof descriptors === "string") {
+            exclusionsMap.set(descriptors, this.createRequirementsForDocType(descriptors, {}));
+            return;
+        }
+
+        for (const docType in descriptors) {
+            if (hasOwnProperty(descriptors, docType)) {
+                exclusionsMap.set(docType as DocType, this.createRequirementsForDocType(docType as DocType, descriptors[docType]));
+            }
+        }
+    }
+
+    private createRequirementsForDocType(docType: DocType, descriptor: InputExclusionDescriptor) {
+        const requirements = [];
+
+        if (docType === "methods" || docType === "properties") {
+            requirements.push(new ClassExclusion(descriptor as IClassExclusionDescriptor));
+        } else {
+            requirements.push(new BlockExclusion(descriptor as IBlockExclusionDescriptor));
+        }
+
+        if ((descriptor as ITagExclusionDescriptor).tags !== undefined) {
+            requirements.push(new TagExclusion(descriptor as ITagExclusionDescriptor));
+        }
+
+        return requirements;
+    }
+}

src/rules/completed-docs/tagExclusion.ts

@@ -0,0 +1,99 @@
+/**
+ * @license
+ * Copyright 2013 Palantir Technologies, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as ts from "typescript";
+
+import { Exclusion } from "./exclusion";
+
+export interface ITagExclusionDescriptor {
+    tags?: {
+        content: IContentTags;
+        existence: string[];
+    };
+}
+
+export interface IContentTags {
+    [i: string]: string;
+}
+
+export class TagExclusion extends Exclusion<ITagExclusionDescriptor> {
+    private readonly contentTags: IContentTags = this.descriptor.tags === undefined
+        ? {}
+        : this.descriptor.tags.content;
+
+    private readonly existenceTags = new Set(
+        this.descriptor.tags !== undefined && this.descriptor.tags.existence !== undefined
+            ? this.descriptor.tags.existence
+            : undefined);
+
+    public excludes(node: ts.Node) {
+        const documentationNode = this.getDocumentationNode(node);
+        const tagsWithContents = this.parseTagsWithContents(documentationNode.getFullText());
+
+        for (const tagWithContent of tagsWithContents) {
+            if (this.existenceTags.has(tagWithContent[0])) {
+                return true;
+            }
+
+            const matcherBody = this.contentTags[tagWithContent[0]];
+            if (matcherBody === undefined) {
+                continue;
+            }
+
+            if (new RegExp(matcherBody).test(tagWithContent[1])) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    private getDocumentationNode(node: ts.Node) {
+        if (node.kind === ts.SyntaxKind.VariableDeclaration) {
+            return node.parent!;
+        }
+
+        return node;
+    }
+
+    private parseTagsWithContents(nodeText: string | undefined): Array<[string, string]> {
+        if (nodeText === undefined) {
+            return [];
+        }
+
+        const docMatches = nodeText.match((/\/\*\*\s*\n([^\*]*(\*[^\/])?)*\*\//));
+        if (docMatches === null || docMatches.length === 0) {
+            return [];
+        }
+
+        const lines = docMatches[0].match(/[\r\n\s]*\*\s*@.*[\r\n\s]/g);
+        if (lines === null) {
+            return [];
+        }
+
+        return lines
+            .map((line): [string, string] => {
+                const body = line.substring(line.indexOf("@"));
+                const firstSpaceIndex = body.search(/\s/);
+
+                return [
+                    body.substring(1, firstSpaceIndex),
+                    body.substring(firstSpaceIndex).trim(),
+                ];
+            });
+    }
+}