Merge pull request #6 from matheusdc/feat/add-usage-details

Add usage details for tokens, functions, objects and JSXElements

Author: luistak

.eslintrc

@@ -9,5 +9,9 @@
   "env": {
     "node": true,
     "jest": true
+  },
+  "rules": {
+    "no-unused-vars": "off",
+    "@typescript-eslint/no-unused-vars": "error"
   }
 }

README.md

@@ -26,6 +26,8 @@ import { getPackagesUsages } from 'pkg-usage';
 const usages: PackageUsage[] = getPackagesUsages({
   packages: ['react'],
   fileGlobs: `**/**.ts`,
+  packageJsonCWD: './package.json',
+  analyzeImportUsages: false,
 });
 
 console.log(usages);
@@ -34,11 +36,42 @@ console.log(usages);
 Package Usage types
 
 ```ts
+export type JSXElementUsage = {
+  line: number;
+  props: string[];
+  text: string;
+};
+
+export type CallExpressionUsage = {
+  line: number;
+  text: string;
+};
+
+export type ValueUsage = {
+  line: number;
+  text: string;
+};
+
+export type PropertyAccessExpressionUsage = {
+  line: number;
+  property: string;
+  text: string;
+};
+
+export type Usages =
+  | JSXElementUsage[]
+  | (CallExpressionUsage | PropertyAccessExpressionUsage | ValueUsage)[];
+
+export type Import = {
+  name: string;
+  type: ExportType;
+  usages?: Usages;
+};
+
 export type FileUsage = {
   name: string;
   filePath: string;
-  defaultImport: string | undefined;
-  namedImports: string[];
+  imports: Import[];
 };
 
 export type PackageUsage = {
@@ -51,11 +84,12 @@ export type PackageUsage = {
 
 ## CLI usage
 
-| Options                  | Description                          | Example                                        |
-| ------------------------ | ------------------------------------ | ---------------------------------------------- |
-| -p, --packages           | Packages to analyze                  | -p vue,vuex or --packages="react,redux"        |
-| -f, --file-globs         | Files to analyze based on file globs | -f "_.(ts\|tsx)" or --file-globs="_.(js\|jsx)" |
-| -cwd, --package-json-CWD | Directory to start from              | -cwd "/path/to/start/from"                     |
+| Options                     | Description                           | Example                                        |
+| --------------------------- | ------------------------------------- | ---------------------------------------------- |
+| -p, --packages              | Packages to analyze                   | -p vue,vuex or --packages="react,redux"        |
+| -f, --file-globs            | Files to analyze based on file globs  | -f "_.(ts\|tsx)" or --file-globs="_.(js\|jsx)" |
+| -u, --analyze-import-usages | (Experimental) Analyzes import usages | -u                                             |
+| -cwd, --package-json-CWD    | Directory to start from               | -cwd "/path/to/start/from"                     |
 
 ### npx
 

__tests__/pkg-usage.test.ts

@@ -17,7 +17,7 @@ beforeEach(() => {
 describe('getPackagesUsages()', () => {
   describe('given a wrong file glob', () => {
     it('should THROW an Error', () => {
-      const { pkg } = mockPackageUsageFile();
+      const { pkg } = mockPackageUsageFile({});
 
       expect(() =>
         getPackagesUsages({
@@ -30,39 +30,68 @@ describe('getPackagesUsages()', () => {
 
   describe('given a file without import declaration', () => {
     it('should return a package usage without a single count', () => {
-      const { pkg, version } = mockPackageUsageFile(
-        ` file data without import declaration `
-      );
+      const { pkg, version } = mockPackageUsageFile({
+        customData: ` file data without import declaration `,
+      });
 
       expect(
         getPackagesUsages({
           packages: [pkg],
-          fileGlobs: `${MOCKS_DIR}/**.ts`,
+          fileGlobs: `${MOCKS_DIR}/**.tsx`,
           packageJsonCWD: MOCKS_DIR_CWD,
         })
       ).toStrictEqual([{ count: 0, files: [], name: pkg, version }]);
     });
   });
 
-  describe('given any package name and named imports', () => {
+  describe('given any package name and imports', () => {
     it('should return the right package usage', () => {
-      const { fileName, imports, pkg, version } = mockPackageUsageFile();
+      const { fileName, imports, pkg, version } = mockPackageUsageFile({});
 
       expect(
         getPackagesUsages({
           packages: [pkg],
-          fileGlobs: `${MOCKS_DIR}/**.ts`,
+          fileGlobs: `${MOCKS_DIR}/**.tsx`,
           packageJsonCWD: MOCKS_DIR_CWD,
         })
       ).toStrictEqual([
         {
           count: 1,
           files: [
             {
-              defaultImport: undefined,
-              filePath: `${MOCKS_DIR_CWD}/${fileName}.ts`,
-              name: `${fileName}.ts`,
-              namedImports: imports,
+              filePath: `${MOCKS_DIR_CWD}/${fileName}.tsx`,
+              name: `${fileName}.tsx`,
+              imports,
+            },
+          ],
+          name: pkg,
+          version,
+        },
+      ]);
+    });
+  });
+
+  describe('given any package name and imports, and analyzeImportUsages as true', () => {
+    it('should return the right package usage', () => {
+      const { fileName, imports, pkg, version } = mockPackageUsageFile({
+        analyzeImportUsages: true,
+      });
+
+      expect(
+        getPackagesUsages({
+          packages: [pkg],
+          fileGlobs: `${MOCKS_DIR}/**.tsx`,
+          analyzeImportUsages: true,
+          packageJsonCWD: MOCKS_DIR_CWD,
+        })
+      ).toStrictEqual([
+        {
+          count: 1,
+          files: [
+            {
+              filePath: `${MOCKS_DIR_CWD}/${fileName}.tsx`,
+              name: `${fileName}.tsx`,
+              imports,
             },
           ],
           name: pkg,

__tests__/utils.ts

@@ -2,6 +2,7 @@ import { join, dirname } from 'path';
 import { cwd } from 'process';
 import { writeFileSync, existsSync, mkdirSync, rmdirSync } from 'fs';
 import f from 'faker';
+import { ExportType, Import } from '../src';
 
 export const MOCKS_DIR = '__mocks__';
 export const MOCKS_DIR_CWD = join(join(cwd(), MOCKS_DIR));
@@ -30,15 +31,107 @@ function mockUniqueList<T, U>(
     .filter((value, index, self) => self.indexOf(value) === index);
 }
 
-export function mockPackageUsageFile(customData?: string) {
-  const imports = mockUniqueList(() => f.hacker.noun().replace(/ |-/g, ''));
+function word() {
+  return f.hacker.noun().replace(/ |-/g, '');
+}
+
+function capitalize(word: string) {
+  return `${word.charAt(0).toUpperCase()}${word.slice(1)}`;
+}
+
+function generatePropList(props: string[]) {
+  return props.map((prop) => `${prop}="${prop}"`).join(' ');
+}
+
+function jsxElement(value: string, line: number): [Import, string] {
+  const props = mockUniqueList(() => word().toLowerCase());
+  return [
+    {
+      name: value,
+      type: ExportType.named,
+      usages: [
+        {
+          line: line + 2,
+          props,
+          text: `<${value} ${generatePropList(props)}/>`,
+        },
+      ],
+    },
+    `function ${capitalize(word())}() { return (<${value} ${generatePropList(
+      props
+    )}/>)}`,
+  ];
+}
+
+function propertyAccess(value: string, line: number): [Import, string] {
+  const property = word();
+  return [
+    {
+      name: value,
+      type: ExportType.named,
+      usages: [{ line: line + 2, property, text: `\n${value}.${property}` }],
+    },
+    `${value}.${property}`,
+  ];
+}
+
+function callExpression(value: string, line: number): [Import, string] {
+  return [
+    {
+      name: value,
+      type: ExportType.named,
+      usages: [{ line: line + 2, text: `\n${value}()` }],
+    },
+    `${value}()`,
+  ];
+}
+
+function valueUsage(value: string, line: number): [Import, string] {
+  return [
+    {
+      name: value,
+      type: ExportType.named,
+      usages: [{ line: line + 2, text: `\n${value};` }],
+    },
+    `${value};`,
+  ];
+}
+
+const possibleUsages = [propertyAccess, callExpression, valueUsage, jsxElement];
+
+function mockTSFile(pkgName: string, imports: string[]) {
+  const importSection = `import { ${imports.join(', ')} } from '${pkgName}';`;
+
+  const usages = imports.map((entry, index) =>
+    possibleUsages[index % possibleUsages.length](entry, index)
+  );
+
+  const mockedImports = usages.map((data) => data[1]);
+
+  return {
+    file: [importSection, ...mockedImports].join('\n'),
+    imports: usages.map((data) => data[0]),
+  };
+}
+
+type mockPackageUsageFileAttributes = {
+  customData?: string;
+  analyzeImportUsages?: boolean;
+};
+
+export function mockPackageUsageFile({
+  customData,
+  analyzeImportUsages = false,
+}: mockPackageUsageFileAttributes) {
+  const importNames = mockUniqueList(() => capitalize(word()));
   const fileName = f.datatype.uuid();
   const pkg = f.hacker.noun();
   const version = f.system.semver();
 
+  const { file, imports } = mockTSFile(pkg, importNames);
   // Mocked with random data to generate a resilient test
-  const data = customData ?? `import { ${imports.join(', ')} } from '${pkg}';`;
-  writeFile(`${fileName}.ts`, data);
+  const data = customData ?? file;
+  writeFile(`${fileName}.tsx`, data);
 
   writeFile(
     'package.json',
@@ -54,8 +147,18 @@ export function mockPackageUsageFile(customData?: string) {
     })
   );
 
+  if (customData) {
+    return {
+      fileName,
+      pkg,
+      version,
+    };
+  }
+
   return {
-    imports,
+    imports: analyzeImportUsages
+      ? imports
+      : imports.map(({ name, type }) => ({ name, type })),
     fileName,
     pkg,
     version,

example/bla.ts

@@ -1,3 +1,5 @@
-import { apiX, apiB, apiC } from 'bla';
+import { apiA, apiB, apiC } from 'bla';
 
-const a = bla;
+const a = apiA;
+
+console.log(apiB);

example/package.json

@@ -5,7 +5,8 @@
   "author": "Luis Takahashi",
   "license": "MIT",
   "dependencies": {
-    "bla": "^0.0.1"
+    "bla": "^0.0.1",
+    "@scoped/package": "1.5.0"
   },
   "peerDependencies": {
     "@scoped/package": "^4.3.5"

example/run-in-ci.js

@@ -1,9 +1,16 @@
-const { getPackagesUsages } = require('../dist');
+const { getPackagesUsages } = require('../dist/src/index');
 
 /**
  * You could use the result in many use cases example:
  *
  * - To fill an S3 with every usage of the desired builds
  * - To block the CI if the package is not being used
  */
-const result = getPackagesUsages();
+const result = getPackagesUsages({
+  packages: ['bla', '@scoped/package'],
+  fileGlobs: './*{.ts,.tsx}',
+  packageJsonCWD: './package.json',
+  analyzeImportUsages: true,
+});
+
+console.log(JSON.stringify(result, null, 2));

example/something.ts

@@ -0,0 +1,19 @@
+import SomeDefaultImport, { AwesomeStuff, CoolStuff } from '@scoped/package';
+import coolApi, { apiD } from 'bla';
+
+export const Comp = () => {
+  const data = apiD();
+
+  coolApi.run();
+
+  return (
+    <>
+      <AwesomeStuff first={1} second="2" />
+      <CoolStuff first={2} second="4" />
+      <CoolStuff second="4" />
+      <SomeDefaultImport first={1} second="2" third={data}></SomeDefaultImport>
+      <SomeDefaultImport first={1} third="3" forth={data}></SomeDefaultImport>
+      <SomeDefaultImport second={1}></SomeDefaultImport>
+    </>
+  );
+};

example/something.tsx

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 const { getPackagesUsages } = require('pkg-usage');
-// const { getPackagesUsages } = require('../dist/src');
+
 const { Command } = require('commander');
 
 const program = new Command();
@@ -24,10 +24,15 @@ program
     '-cwd, --package-json-CWD <value>',
     'Directory to start from ex: -cwd "/path/to/start/from"'
   )
-  .action(({ packages, fileGlobs, packageJsonCWD }) => {
+  .option(
+    '-u, --analyze-import-usages',
+    'Experimental feature that analyzes usages of imported JSXElements, function calls, object properties, and value usages'
+  )
+  .action(({ packages, fileGlobs, analyzeImportUsages, packageJsonCWD }) => {
     const usages = getPackagesUsages({
       packages,
       fileGlobs,
+      analyzeImportUsages,
       packageJsonCWD,
     });