From 92e365f467934f78530725eaf1c21e3fd4e0b671 Mon Sep 17 00:00:00 2001 From: Michael Mullins Date: Sun, 19 Sep 2021 14:13:42 +0400 Subject: [PATCH] feat: added JSDoc notation for input parameters #5 --- src/analyze.ts | 19 +++--- src/types.ts | 134 ++++++++++++++++++++++++++++++++++++++-- src/utils/check-deps.ts | 7 ++- 3 files changed, 147 insertions(+), 13 deletions(-) diff --git a/src/analyze.ts b/src/analyze.ts index dce1e31..712f2ca 100644 --- 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 index cdc027f..fbd9dfc 100644 --- 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; + /** + * @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 { export type TImportsReport = Map; export type TImportsReports = Map; -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 index e3febd7..c2556af 100644 --- 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());