feat: added JSDoc notation for input parameters

#5
public-js · Sep 19, 2021 · 92e365f · 92e365f
1 parent d1a68d1
commit 92e365f
Show file tree

Hide file tree

Showing 3 changed files with 147 additions and 13 deletions.
diff --git a/src/analyze.ts b/src/analyze.ts
@@ -1,12 +1,6 @@
 import { existsSync } from 'fs';
 import { resolve } from 'path';
 
-import { checkLocal } from './utils/check-deps';
-import { checkImports } from './utils/check-imports';
-import { checkPackageVersion } from './utils/check-package-version';
-import { countImportHits } from './utils/count-import-hits';
-import { getImports } from './utils/get-imports';
-import { getPackageJson } from './utils/get-package-json';
 import {
     IAnalyzeInput,
     IObject,
@@ -16,7 +10,18 @@ import {
     IPackageJsonData,
     packageImportsDefault,
 } from './types';
+import { checkLocal } from './utils/check-deps';
+import { checkImports } from './utils/check-imports';
+import { checkPackageVersion } from './utils/check-package-version';
+import { countImportHits } from './utils/count-import-hits';
+import { getImports } from './utils/get-imports';
+import { getPackageJson } from './utils/get-package-json';
 
+/**
+ * Run the packages analysis
+ * @param {IAnalyzeInput} params - Analysis configuration
+ * @returns {IPackage[]}
+ */
 export function analyze(params: IAnalyzeInput): IPackage[] {
     const timeStart = Date.now();
     analysisPreChecks(params);
@@ -149,7 +154,7 @@ export function analyze(params: IAnalyzeInput): IPackage[] {
 
 function analysisPreChecks(params: IAnalyzeInput): void {
     if (params.packageJson && !existsSync(params.packageJson)) {
-        throw new Error(`The provided package.json path (${ params.packageJson }) does not exist`);
+        throw new Error(`The provided package.json path (${params.packageJson}) does not exist`);
     }
     if (params.checkDeps === 'full' && !params.packageJson) {
         throw new Error('Can not fully check dependencies without package.json');

diff --git a/src/types.ts b/src/types.ts
@@ -1,6 +1,20 @@
+/**
+ * @typedef IPackageInput
+ * @type {object}
+ */
 export interface IPackageInput {
+    /**
+     * @type {string} - Package name
+     */
     name: string;
+    /**
+     * @type {string} - Absolute package path
+     */
     path: string;
+    /**
+     * @type {string} - Absolute path to package.json file
+     * If left unset, it must be available at 'path/package.json'
+     */
     packageJson?: string;
 }
 
@@ -47,20 +61,75 @@ export const packageImportsDefault: IPackageImports = {
     },
 };
 
+/**
+ * @typedef IAnalyzeInput
+ * @type {object}
+ */
 export interface IAnalyzeInput {
+    /**
+     * @type {IPackageInput[]} - List of packages to analyze
+     */
     packages: ReadonlyArray<IPackageInput>;
+    /**
+     * @type {string[]} - File extensions to analyze
+     * If left unset, all the files containing 'import {...} from' will be analyzed
+     */
     matchExt?: string[];
+    /**
+     * @type {string[]} - Imports to exclude from the analysis
+     */
     ignoreImports?: string[];
+    /**
+     * @type {string[]} - Imports to be reported as banned
+     */
     bannedImports?: string[];
+    /**
+     * @type {string} - An absolute path to the root project package.json file
+     * Required if checkDeps of checkPackageVersion is passed
+     */
     packageJson?: string;
+    /**
+     * @type {boolean} - Count import hits; useful for statistic
+     */
     countHits?: true;
+    /**
+     * @type {boolean} - Check and report imports
+     */
     checkImports?: true;
+    /**
+     * @type {(TTreatTypes|TTreatCallbackImport)} - Report level for failed import checks
+     * If left unset or null, no imports will be reported
+     */
     treatImports?: TTreatTypes | TTreatCallbackImport;
-    checkDeps?: 'full' | 'local';
+    /**
+     * @type {TCheckDepsTypes} - Check and report dependencies
+     * Requires packageJson to be provided
+     */
+    checkDeps?: TCheckDepsTypes;
+    /**
+     * @type {(TTreatTypes|TTreatCallbackDep)} - Report level for failed dependency checks
+     * If left unset or null, no dependencies will be reported
+     */
     treatDeps?: TTreatTypes | TTreatCallbackDep;
+    /**
+     * @type {boolean} - Check and report package versions
+     * Requires packageJson to be provided
+     */
     checkPackageVersion?: true;
+    /**
+     * @type {(TTreatTypes|TTreatCallbackVersion)} - Report level for failed version checks
+     * If left unset or null, no packages will be reported
+     */
     treatPackageVersion?: TTreatTypes | TTreatCallbackVersion;
+    /**
+     * @type {boolean} - Log report to console
+     * Useful to create pre-commit analysis report
+     */
     logToConsole?: true;
+    /**
+     * @type {boolean} - Throw an error after the analysis if any errors occurred
+     * Useful for strict pre-commit rules
+     */
     throwError?: true;
 }
 
@@ -87,11 +156,68 @@ export interface IObject<T = IObjectTypes> {
 export type TImportsReport = Map<string, IObjectTypes>;
 export type TImportsReports = Map<string, IObject>;
 
-export type TTreatTypes = 'err' | 'warn' | null;
+/**
+ * @callback TTreatCallbackImport
+ * @param {string} pkgName - The package name in which an issue occurred
+ * @param {TImportTypes} importType - Issue type
+ * @param {string} importPath - Import that triggered an issue
+ * @returns {TTreatTypes}
+ */
 export type TTreatCallbackImport = (
     pkgName: string,
-    importType: 'absSame' | 'relExt' | 'banned',
+    importType: TImportTypes,
     importPath: string
 ) => TTreatTypes;
-export type TTreatCallbackDep = (pkgName: string, depType: 'local' | 'root', depName: string) => TTreatTypes;
+
+/**
+ * @callback TTreatCallbackDep
+ * @param {string} pkgName - The package name in which an issue occurred
+ * @param {TDepsTypes} depType - Issue type
+ * @param {string} depName - Dependency name that triggered an issue
+ * @returns {TTreatTypes}
+ */
+export type TTreatCallbackDep = (pkgName: string, depType: TDepsTypes, depName: string) => TTreatTypes;
+
+/**
+ * @callback TTreatCallbackVersion
+ * @param {string} pkgName - The package name in which an issue occurred
+ * @returns {TTreatTypes}
+ */
 export type TTreatCallbackVersion = (pkgName: string) => TTreatTypes;
+
+/**
+ * @typedef TTreatTypes
+ * @type {(string|null)}
+ * Report levels:
+ * err - error,
+ * warn - warning,
+ * null - none
+ */
+export type TTreatTypes = 'err' | 'warn' | null;
+
+/**
+ * @typedef TImportTypes
+ * @type {string}
+ * Import issue types:
+ * absSame - absolute import from the same package,
+ * relExt - relative import from an external package,
+ * banned - banned import
+ */
+type TImportTypes = 'absSame' | 'relExt' | 'banned';
+
+/**
+ * @typedef TCheckDepsTypes
+ * Dependency check types:
+ * local - check only local (per-package) package.json files,
+ * full - check local & root package.json files for issues
+ */
+export type TCheckDepsTypes = 'local' | 'full';
+
+/**
+ * @typedef TDepsTypes
+ * @type {string}
+ * Dependency issue types:
+ * local - local package issue,
+ * root - root package.json issue
+ */
+type TDepsTypes = 'local' | 'root';
diff --git a/src/utils/check-deps.ts b/src/utils/check-deps.ts
@@ -34,8 +34,11 @@ export function checkLocal(
         .filter((item: string) => item !== 'tslib')
         .forEach((item: string) => {
             const treat: TTreatTypes =
-            typeof treatAs === 'function' ? treatAs(pkg.name, 'local', item) : treatAs;
-            tempReport.set(item, { data: getTreatIcon(treat) + 'Listed in local package.json, unused', treat });
+                typeof treatAs === 'function' ? treatAs(pkg.name, 'local', item) : treatAs;
+            tempReport.set(item, {
+                data: getTreatIcon(treat) + 'Listed in local package.json, unused',
+                treat,
+            });
         });
 
     const reportEntries = Array.from(tempReport.entries());