From da528bb031c94f7ad511fc5bec55486e0b4f7099 Mon Sep 17 00:00:00 2001 From: Krishna Acondy Date: Mon, 22 Mar 2021 20:36:19 +0000 Subject: [PATCH] chore(*): add PR template, add TSDoc comments --- PULL_REQUEST_TEMPLATE.md | 20 ++++++++++++++++++++ src/example.ts | 4 ++++ src/lint.ts | 10 ++++++++++ src/rules/hasDoxygenHeader.ts | 3 +++ src/rules/noEncodedPasswords.ts | 3 +++ src/rules/noTrailingSpaces.ts | 3 +++ src/types/Diagnostic.ts | 3 +++ src/types/LintConfig.ts | 7 +++++++ src/types/LintRule.ts | 10 ++++++++++ src/types/LintRuleType.ts | 4 ++++ src/utils/getLintConfig.ts | 4 ++++ src/utils/getProjectRoot.ts | 7 ++++++- 12 files changed, 77 insertions(+), 1 deletion(-) create mode 100644 PULL_REQUEST_TEMPLATE.md diff --git a/PULL_REQUEST_TEMPLATE.md b/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..e6bc3c9 --- /dev/null +++ b/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,20 @@ +## Issue + +Link any related issue(s) in this section. + +## Intent + +What this PR intends to achieve. + +## Implementation + +What code changes have been made to achieve the intent. + +## Checks + +- [ ] Code is formatted correctly (`npm run lint:fix`). +- [ ] Any new functionality has been unit tested. +- [ ] All unit tests are passing (`npm test`). +- [ ] All CI checks are green. +- [ ] JSDoc comments have been added or updated. +- [ ] Reviewer is assigned. diff --git a/src/example.ts b/src/example.ts index d76f13e..67ad5fc 100644 --- a/src/example.ts +++ b/src/example.ts @@ -1,5 +1,9 @@ import { lint } from './lint' +/** + * Example which tests a piece of text with all known violations. + */ + const text = `/** @file @brief Returns an unused libref diff --git a/src/lint.ts b/src/lint.ts index 0b46108..bd6c9fa 100644 --- a/src/lint.ts +++ b/src/lint.ts @@ -2,11 +2,21 @@ import { Diagnostic } from './types/Diagnostic' import { LintConfig } from './types/LintConfig' import { getLintConfig } from './utils/getLintConfig' +/** + * Analyses and produces a set of diagnostics for the given text content. + * @param {string} text - the text content to be linted. + * @returns {Diagnostic[]} array of diagnostic objects, each containing a warning, line number and column number. + */ export const lint = async (text: string) => { const config = await getLintConfig() return processText(text, config) } +/** + * Splits the given content into a list of lines, regardless of CRLF or LF line endings. + * @param {string} text - the text content to be split into lines. + * @returns {string[]} an array of lines from the given text + */ export const splitText = (text: string): string[] => { if (!text) return [] return text.replace(/\r\n/g, '\n').split('\n') diff --git a/src/rules/hasDoxygenHeader.ts b/src/rules/hasDoxygenHeader.ts index 70866cf..18feb5d 100644 --- a/src/rules/hasDoxygenHeader.ts +++ b/src/rules/hasDoxygenHeader.ts @@ -15,6 +15,9 @@ const test = (value: string) => { } } +/** + * Lint rule that checks for the presence of a Doxygen header in a given file. + */ export const hasDoxygenHeader: FileLintRule = { type: LintRuleType.File, name, diff --git a/src/rules/noEncodedPasswords.ts b/src/rules/noEncodedPasswords.ts index cacb333..7b3b68b 100644 --- a/src/rules/noEncodedPasswords.ts +++ b/src/rules/noEncodedPasswords.ts @@ -15,6 +15,9 @@ const test = (value: string, lineNumber: number) => { })) } +/** + * Lint rule that checks for the presence of encoded password(s) in a given line of text. + */ export const noEncodedPasswords: LineLintRule = { type: LintRuleType.Line, name, diff --git a/src/rules/noTrailingSpaces.ts b/src/rules/noTrailingSpaces.ts index 19d50b0..5fae710 100644 --- a/src/rules/noTrailingSpaces.ts +++ b/src/rules/noTrailingSpaces.ts @@ -9,6 +9,9 @@ const test = (value: string, lineNumber: number) => ? [] : [{ warning, lineNumber, columnNumber: value.trimEnd().length + 1 }] +/** + * Lint rule that checks for the presence of trailing space(s) in a given line of text. + */ export const noTrailingSpaces: LineLintRule = { type: LintRuleType.Line, name, diff --git a/src/types/Diagnostic.ts b/src/types/Diagnostic.ts index 429a5d9..c034a9d 100644 --- a/src/types/Diagnostic.ts +++ b/src/types/Diagnostic.ts @@ -1,3 +1,6 @@ +/** + * A diagnostic is produced by the execution of a lint rule against a file or line of text. + */ export interface Diagnostic { lineNumber: number columnNumber: number diff --git a/src/types/LintConfig.ts b/src/types/LintConfig.ts index 39aff4d..99c1470 100644 --- a/src/types/LintConfig.ts +++ b/src/types/LintConfig.ts @@ -3,6 +3,13 @@ import { noEncodedPasswords } from '../rules/noEncodedPasswords' import { noTrailingSpaces } from '../rules/noTrailingSpaces' import { FileLintRule, LineLintRule } from './LintRule' +/** + * LintConfig is the logical representation of the .sasjslint file. + * It exposes two sets of rules - one to be run against each line in a file, + * and one to be run once per file. + * + * More types of rules, when available, will be added here. + */ export class LintConfig { readonly lineLintRules: LineLintRule[] = [] readonly fileLintRules: FileLintRule[] = [] diff --git a/src/types/LintRule.ts b/src/types/LintRule.ts index 9f584a5..96fd498 100644 --- a/src/types/LintRule.ts +++ b/src/types/LintRule.ts @@ -1,6 +1,10 @@ import { Diagnostic } from './Diagnostic' import { LintRuleType } from './LintRuleType' +/** + * A lint rule is defined by a type, name, description, warning text and a test function. + * The test function produces a set of diagnostics when executed. + */ export interface LintRule { type: LintRuleType name: string @@ -9,10 +13,16 @@ export interface LintRule { test: (value: string, lineNumber: number) => Diagnostic[] } +/** + * A LineLintRule is run once per line of text. + */ export interface LineLintRule extends LintRule { type: LintRuleType.Line } +/** + * A FileLintRule is run once per file. + */ export interface FileLintRule extends LintRule { type: LintRuleType.File test: (value: string) => Diagnostic[] diff --git a/src/types/LintRuleType.ts b/src/types/LintRuleType.ts index ce39ed1..370fc33 100644 --- a/src/types/LintRuleType.ts +++ b/src/types/LintRuleType.ts @@ -1,3 +1,7 @@ +/** + * The types of lint rules available. + * This might be expanded to include lint rules for entire folders and projects. + */ export enum LintRuleType { Line, File diff --git a/src/utils/getLintConfig.ts b/src/utils/getLintConfig.ts index 4003971..5fc1582 100644 --- a/src/utils/getLintConfig.ts +++ b/src/utils/getLintConfig.ts @@ -3,6 +3,10 @@ import { LintConfig } from '../types/LintConfig' import { readFile } from '@sasjs/utils/file' import { getProjectRoot } from './getProjectRoot' +/** + * Fetches the config from the .sasjslint file and creates a LintConfig object. + * @returns {Promise} resolves with an object representing the current lint configuration. + */ export async function getLintConfig(): Promise { const projectRoot = await getProjectRoot() const configuration = await readFile(path.join(projectRoot, '.sasjslint')) diff --git a/src/utils/getProjectRoot.ts b/src/utils/getProjectRoot.ts index 3977923..73db38e 100644 --- a/src/utils/getProjectRoot.ts +++ b/src/utils/getProjectRoot.ts @@ -1,7 +1,12 @@ import path from 'path' import { fileExists } from '@sasjs/utils/file' -export async function getProjectRoot() { +/** + * Returns the absolute path to the location of the .sasjslint file. + * Traverses the folder tree until the .sasjslint file is found. + * @returns {Promise} the path to the folder containing the lint config. + */ +export async function getProjectRoot(): Promise { let root = '' let rootFound = false let i = 1