@zeroheight/adoption-cli 2.0.1 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Release notes
 
+## [2.1.0](https://www.npmjs.com/package/@zeroheight/adoption-cli/v/2.1.0) - 8th November 2024
+
+- Start collecting component property usage data as part of component analyzing
+
+## [2.0.2](https://www.npmjs.com/package/@zeroheight/adoption-cli/v/2.0.2) - 29th October 2024
+
+- Update readme
+
 ## [2.0.1](https://www.npmjs.com/package/@zeroheight/adoption-cli/v/2.0.1) - 21st October 2024
 
 - Update help text and link

package/README.md

@@ -2,7 +2,9 @@
 
 CLI for measuring component usage to view in your [zeroheight](https://zeroheight.com/) account.
 
-See release notes [here](https://www.npmjs.com/package/@zeroheight/adoption-cli?activeTab=code)
+**For full walk through on how to use this CLI tool, head over to our [help centre article](https://zeroheight.com/help/article/adoption-private-beta-overview/).**
+
+[Release notes](https://www.npmjs.com/package/@zeroheight/adoption-cli?activeTab=code)
 
 ## Install
 
@@ -37,7 +39,9 @@ export ZEROHEIGHT_ACCESS_TOKEN="your-access-token"
 
 ### Component usage analysis
 
-In the repository in which you wish to analyze the component usage, run the following command:
+[Help center article](https://zeroheight.com/help/article/component-usage/)
+
+In the React repository in which you wish to get usage metrics around how components from your design system packages are being used, run the following command:
 
 ```bash
 zh-adoption analyze
@@ -81,7 +85,11 @@ zh-adoption analyze --interactive false -r "My Repo"
 
 ### Monitor repo
 
-In the repository in which you wish to monitor the package versions being used, run the following command:
+[Help center article](https://zeroheight.com/help/article/package-version-monitoring/)
+
+This will analyze your code repository to help you understand what packages are being used and at what version.
+
+In the repository in which you wish to monitor, run the following command:
 
 ```bash
 zh-adoption monitor-repo
@@ -101,7 +109,11 @@ zh-adoption monitor-repo -d ./webApp
 
 ### Track package
 
-In the repository containing the packages you wish to monitor the version of, run the following command:
+[Help center article](https://zeroheight.com/help/article/package-version-monitoring/)
+
+This will give zeroheight the name and current version of your design system package so you can compare it to the version being used by your other code repositories.
+
+In the repository containing your design system package, run the following command:
 
 ```bash
 zh-adoption track-package

package/dist/ast/analyze.d.ts

@@ -1,18 +1,39 @@
 import type { Node, Program, Identifier } from "acorn";
+type AttrValueType = "JSXExpressionContainer" | "NumericLiteral" | "StringLiteral" | "BooleanLiteral" | "Identifier" | "TemplateLiteral" | "ArrowFunctionExpression" | "StaticMemberExpression" | "CallExpression" | "TSAsExpression" | "ObjectExpression" | "ArrayExpression" | "BinaryExpression" | undefined;
 export interface PlainIdentifier extends Node {
     type: "Identifier";
     local: Identifier;
 }
+export interface Props {
+    name: string;
+    type?: AttrValueType[];
+    values: [string | number | typeof RUNTIME_VALUE | null | undefined];
+}
 export type VisitorState = {
     components: Map<string, number>;
+    props: Map<string, Props[]>;
     imports: Map<string, {
         package: string;
         name: string;
     }>;
 };
+type PropValues = string | number | null | undefined;
+export type ComponentProps = {
+    [propName: string]: {
+        type?: AttrValueType[];
+        count?: number;
+        values: PropValues[];
+    };
+};
 export type RawUsage = {
     name: string;
     count: number;
     package: string;
+    props: ComponentProps;
 };
+declare const RUNTIME_VALUE = "zh-runtime-value";
+export declare const ARRAY_VALUE = "zh-array-value";
+export declare const BINARY_VALUE = "zh-binary-value";
+export declare const OBJECT_VALUE = "zh-object-value";
 export declare function analyze(ast: Program): RawUsage[];
+export {};

package/dist/ast/analyze.js

@@ -1,4 +1,16 @@
 import * as walk from "acorn-walk";
+const DYNAMIC_EXPRESSIONS = [
+    "Identifier",
+    "TemplateLiteral",
+    "ArrowFunctionExpression",
+    "StaticMemberExpression",
+    "CallExpression",
+    "TSAsExpression",
+];
+const RUNTIME_VALUE = "zh-runtime-value";
+export const ARRAY_VALUE = "zh-array-value";
+export const BINARY_VALUE = "zh-binary-value";
+export const OBJECT_VALUE = "zh-object-value";
 function transformVisitorStateToRawUsage(visitorState) {
     const transformedUsageMap = new Map();
     for (const [name, count] of visitorState.components) {
@@ -10,10 +22,30 @@ function transformVisitorStateToRawUsage(visitorState) {
             name: actualName,
             count: 0,
             package: importInfo?.package ?? "",
+            props: {},
         };
         transformedUsageMap.set(key, {
             ...currentValue,
             count: currentValue.count + count,
+            props: {},
+        });
+    }
+    for (const [name, props] of visitorState.props) {
+        const importInfo = visitorState.imports.get(name);
+        const actualName = importInfo?.name ?? name;
+        const packageName = importInfo?.package ?? "";
+        const key = `package:${packageName} name:${actualName}`;
+        const currentValue = transformedUsageMap.get(key);
+        const componentProps = currentValue.props;
+        props.forEach((prop) => {
+            componentProps[prop.name] = {
+                type: Array.from(new Set([...(componentProps[prop.name]?.type ?? []), ...(prop.type ?? [])])),
+                values: [...(componentProps[prop.name]?.values ?? []), ...prop.values],
+            };
+        });
+        transformedUsageMap.set(key, {
+            ...currentValue,
+            props: componentProps,
         });
     }
     return Array.from(transformedUsageMap.values());
@@ -21,6 +53,7 @@ function transformVisitorStateToRawUsage(visitorState) {
 export function analyze(ast) {
     const visitorState = {
         components: new Map(),
+        props: new Map(),
         imports: new Map(),
     };
     const visitorFunctions = {
@@ -84,6 +117,63 @@ export function analyze(ast) {
             const elName = el.name.name;
             // Ignore html tags e.g. div, h1, span
             if (elName?.[0] !== elName?.[0]?.toLocaleLowerCase()) {
+                if (el.attributes.length > 0) {
+                    const attrProps = [];
+                    el.attributes.forEach((attr) => {
+                        // We won't have a name if it is a JSXSpreadAttribute
+                        if (attr.name) {
+                            if (attr.value?.type === "JSXExpressionContainer") {
+                                const expressionType = attr.value.expression.type;
+                                // These are props determined at runtime so we cannot parse them
+                                if (expressionType &&
+                                    DYNAMIC_EXPRESSIONS.includes(expressionType)) {
+                                    attrProps.push({
+                                        name: attr.name.name,
+                                        type: [expressionType],
+                                        values: [RUNTIME_VALUE],
+                                    });
+                                }
+                                else if (expressionType && expressionType === 'ObjectExpression') {
+                                    attrProps.push({
+                                        name: attr.name.name,
+                                        type: [expressionType],
+                                        values: [OBJECT_VALUE],
+                                    });
+                                }
+                                else if (expressionType && expressionType === 'ArrayExpression') {
+                                    attrProps.push({
+                                        name: attr.name.name,
+                                        type: [expressionType],
+                                        values: [ARRAY_VALUE],
+                                    });
+                                }
+                                else if (expressionType && expressionType === 'BinaryExpression') {
+                                    attrProps.push({
+                                        name: attr.name.name,
+                                        type: [expressionType],
+                                        values: [BINARY_VALUE],
+                                    });
+                                }
+                                else {
+                                    attrProps.push({
+                                        name: attr.name.name,
+                                        type: [expressionType],
+                                        values: [attr.value.expression.value || attr.value.expression.name],
+                                    });
+                                }
+                            }
+                            else {
+                                attrProps.push({
+                                    name: attr.name.name,
+                                    type: [attr.value?.type],
+                                    values: [attr.value?.value],
+                                });
+                            }
+                        }
+                    });
+                    const existingProps = state.props.get(elName) ?? [];
+                    state.props.set(elName, [...attrProps, ...existingProps]);
+                }
                 state.components.set(elName, (state.components.get(elName) ?? 0) + 1);
             }
             node.children.forEach((child) => {

package/dist/cli.js

@@ -12,7 +12,7 @@ const { output, cleanup } = render(React.createElement(HelpInfo, null));
 program
     .name("zh-adoption")
     .description("CLI for measuring design system usage usage in your products")
-    .version("2.0.1")
+    .version("2.1.0")
     .addHelpText("before", output)
     .addCommand(analyzeCommand())
     .addCommand(authCommand())

package/dist/commands/analyze.utils.d.ts

@@ -1,9 +1,11 @@
 import { RawUsageMap } from "./analyze.js";
+import { ComponentProps } from "../ast/analyze.js";
 export interface ComponentUsageRecord {
     name: string;
     files: string[];
     count: number;
     package: string;
+    props: ComponentProps;
 }
 /**
  * Get a list of files matching extensions, skips hidden files and node_modules

package/dist/common/api.d.ts

@@ -1,3 +1,4 @@
+import { ComponentProps } from "../ast/analyze.js";
 import { RawUsageMap } from "../commands/analyze.js";
 import { Credentials } from "./config.js";
 export declare enum ResponseStatus {
@@ -73,10 +74,10 @@ interface ComponentUsageDetailsSuccess {
     };
 }
 export declare function submitUsageData(usage: RawUsageMap, repoName: string, credentials: Credentials): Promise<APIResponse<ComponentUsageDetailsSuccess>>;
-interface RepoNamesSuccss {
+interface RepoNamesSuccess {
     repo_names: string[];
 }
-export declare function getExistingRepoNames(credentials: Credentials): Promise<APIResponse<RepoNamesSuccss>>;
+export declare function getExistingRepoNames(credentials: Credentials): Promise<APIResponse<RepoNamesSuccess>>;
 interface AuthTokensResponse {
     scopes: string[];
     email: string;
@@ -90,4 +91,5 @@ interface AuthTokensResponse {
     };
 }
 export declare function getAuthDetails(credentials: Credentials): Promise<APIResponse<AuthTokensResponse>>;
+export declare function mergeUsageProps(newProps: ComponentProps, currentProps?: ComponentProps): any;
 export {};

package/dist/common/api.js

@@ -71,13 +71,35 @@ async function request(path, credentials, init) {
     }
     return await response.json();
 }
+export function mergeUsageProps(newProps, currentProps) {
+    if (!currentProps)
+        return newProps;
+    if (!newProps)
+        return currentProps;
+    const props = Array.from(new Set([...Object.keys(currentProps), ...Object.keys(newProps)]));
+    const mergedProps = {};
+    props.forEach((prop) => {
+        const existingProp = currentProps[prop] ?? {};
+        const newProp = newProps[prop];
+        const mergedValues = [
+            ...(existingProp?.values ?? []),
+            ...(newProp?.values ?? []),
+        ];
+        mergedProps[prop] = {
+            type: Array.from(new Set([...(existingProp.type ?? []), ...(newProp?.type ?? [])])),
+            count: mergedValues.length,
+            values: mergedValues,
+        };
+    });
+    return mergedProps;
+}
 /**
  * Transform usage map grouped by file into usage map grouped by component
  */
 function transformUsageByName(usage) {
     const transformedUsageMap = new Map();
     for (const [file, rawUsage] of usage) {
-        for (const { count, package: packageName, name } of rawUsage) {
+        for (const { count, package: packageName, name, props } of rawUsage) {
             const key = `package:${packageName} name:${name}`;
             const currentValue = transformedUsageMap.get(key);
             const newFileList = [...(currentValue?.files ?? []), file]; // Add file to list
@@ -86,6 +108,7 @@ function transformUsageByName(usage) {
                 files: Array.from(new Set(newFileList)), // Ensure unique file paths
                 count: count + (currentValue?.count ?? 0),
                 package: packageName,
+                props: mergeUsageProps(props, currentValue?.props ?? {}),
             });
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroheight/adoption-cli",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "license": "ISC",
   "main": "dist/cli.js",
   "bin": {