Release v1.0.0-beta.3

.github/workflows/cd.yml

@@ -17,6 +17,7 @@ jobs:
         uses: actions/setup-node@v1
         with:
           node-version: 12
+          registry-url: 'https://registry.npmjs.org'
 
       - name: Get npm cache path
         id: npm-cache-path

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@public-js/ng-pkg-keeper",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.3",
   "description": "Add description",
   "scripts": {
     "build": "npm run clean:dist && tsc",

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);
@@ -69,7 +74,7 @@ export function analyze(params: IAnalyzeInput): IPackage[] {
                 report: data,
                 hasErrors,
                 hasWarnings,
-            } = checkImports(pkg, packages, params.treatImports || null);
+            } = checkImports(pkg, packages, params.bannedImports || [], params.treatImports || null);
             Array.from(data.entries()).forEach(([key, report]: [string, IObjectTypes]) => {
                 const item = pkg.importsReport.get(key) || {};
                 item.Imports = report;

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,19 +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;
 }
 
@@ -86,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',
+    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';

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());

src/utils/check-imports.ts

@@ -6,6 +6,7 @@ import { getTreatIcon } from './get-treat-icon';
 export function checkImports(
     pkg: IPackage,
     packages: IPackage[],
+    bannedImports: string[],
     treatAs: TTreatTypes | TTreatCallbackImport
 ): { report: TImportsReport; hasErrors: boolean; hasWarnings: boolean } {
     const tempReport = new Map<string, { data: IObjectTypes; treat: TTreatTypes }>([]);
@@ -64,6 +65,16 @@ export function checkImports(
         });
     }
 
+    if (bannedImports.length > 0) {
+        pkg.imports.importsUnique.forEach((item: string) => {
+            if (bannedImports.some((banned: string) => item.includes(banned))) {
+                const treat: TTreatTypes =
+                    typeof treatAs === 'function' ? treatAs(pkg.name, 'banned', item) : treatAs;
+                tempReport.set(item, { data: getTreatIcon(treat) + 'Banned import', treat });
+            }
+        });
+    }
+
     const reportEntries = Array.from(tempReport.entries());
     const report: TImportsReport = new Map<string, IObjectTypes>([]);
     reportEntries.forEach(([key, item]: [string, { data: IObjectTypes; treat: TTreatTypes }]) => {