chore(*): add PR template, add TSDoc comments

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.

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

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')

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,

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,

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,

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

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[] = []

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[]

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

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<LintConfig>} resolves with an object representing the current lint configuration.
+ */
 export async function getLintConfig(): Promise<LintConfig> {
   const projectRoot = await getProjectRoot()
   const configuration = await readFile(path.join(projectRoot, '.sasjslint'))

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<string>} the path to the folder containing the lint config.
+ */
+export async function getProjectRoot(): Promise<string> {
   let root = ''
   let rootFound = false
   let i = 1