@zeroheight/adoption-cli 2.2.1 → 2.2.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Release notes
 
+## [2.2.3](https://www.npmjs.com/package/@zeroheight/adoption-cli/v/2.2.3) - 28th November 2024
+
+- Update README to explain new CLI options
+
+## [2.2.2](https://www.npmjs.com/package/@zeroheight/adoption-cli/v/2.2.2) - 26th November 2024
+
+- Add global `--log-level` and `--log-file` options
+
 ## [2.2.1](https://www.npmjs.com/package/@zeroheight/adoption-cli/v/2.2.1) - 13th November 2024
 
 - Handle API throttling

package/README.md

@@ -35,6 +35,19 @@ export ZEROHEIGHT_CLIENT_ID="your-client-id"
 export ZEROHEIGHT_ACCESS_TOKEN="your-access-token"
 ```
 
+#### Error logging
+
+When running a command with the `--log-level <level> --log-file ./my-log-file.log` flags, diagnostic information will be written to a file. This can help diagnose issues and can be optionally shared with zeroheight directly to help resolve. If you don't specify `--log-file`, logs will be output to `stderr`.
+
+There are 4 levels of increasing severity:
+
+1. `info`
+2. `warn`
+3. `error`
+4. `fatal`
+
+**Note**: You will see logs for the specified level and those from the higher severity groups. For example, if you you choose `--log-level error` then the `error` and `fatal` level logs will be surfaced.
+
 ---
 
 ### Component usage analysis
@@ -81,6 +94,22 @@ Pass in `false` to disable the interactive mode e.g. when running in a CI enviro
 zh-adoption analyze --interactive false -r "My Repo"
 ```
 
+`--log-level`
+
+Provide a severity to output diagnostic messages.
+
+```bash
+zh-adoption analyze --log-level info
+```
+
+Write logs to a file so they can read and/or shared later.
+
+`--log-file`
+
+```bash
+zh-adoption analyze --log-file ./dev.log
+```
+
 ---
 
 ### Monitor repo
@@ -105,6 +134,22 @@ Provide a path to the specific folder to find package.json and lock file. This o
 zh-adoption monitor-repo -d ./webApp
 ```
 
+`--log-level`
+
+Provide a severity to output diagnostic messages.
+
+```bash
+zh-adoption analyze --log-level info
+```
+
+Write logs to a file so they can read and/or shared later.
+
+`--log-file`
+
+```bash
+zh-adoption analyze --log-file ./dev.log
+```
+
 ---
 
 ### Track package
@@ -129,6 +174,22 @@ Pass in `false` to disable the interactive mode e.g. when running in a CI enviro
 zh-adoption track-package --interactive false
 ```
 
+`--log-level`
+
+Provide a severity to output diagnostic messages.
+
+```bash
+zh-adoption analyze --log-level info
+```
+
+Write logs to a file so they can read and/or shared later.
+
+`--log-file`
+
+```bash
+zh-adoption analyze --log-file ./dev.log
+```
+
 ---
 
 More info on the commands can be seen by running

package/dist/ast/analyze.js

@@ -1,4 +1,5 @@
 import * as walk from "acorn-walk";
+import logger from "../common/logging.js";
 const DYNAMIC_EXPRESSIONS = [
     "Identifier",
     "TemplateLiteral",
@@ -39,7 +40,10 @@ function transformVisitorStateToRawUsage(visitorState) {
         const componentProps = currentValue.props;
         props.forEach((prop) => {
             componentProps[prop.name] = {
-                type: Array.from(new Set([...(componentProps[prop.name]?.type ?? []), ...(prop.type ?? [])])),
+                type: Array.from(new Set([
+                    ...(componentProps[prop.name]?.type ?? []),
+                    ...(prop.type ?? []),
+                ])),
                 values: [...(componentProps[prop.name]?.values ?? []), ...prop.values],
             };
         });
@@ -133,21 +137,24 @@ export function analyze(ast) {
                                         values: [RUNTIME_VALUE],
                                     });
                                 }
-                                else if (expressionType && expressionType === 'ObjectExpression') {
+                                else if (expressionType &&
+                                    expressionType === "ObjectExpression") {
                                     attrProps.push({
                                         name: attr.name.name,
                                         type: [expressionType],
                                         values: [OBJECT_VALUE],
                                     });
                                 }
-                                else if (expressionType && expressionType === 'ArrayExpression') {
+                                else if (expressionType &&
+                                    expressionType === "ArrayExpression") {
                                     attrProps.push({
                                         name: attr.name.name,
                                         type: [expressionType],
                                         values: [ARRAY_VALUE],
                                     });
                                 }
-                                else if (expressionType && expressionType === 'BinaryExpression') {
+                                else if (expressionType &&
+                                    expressionType === "BinaryExpression") {
                                     attrProps.push({
                                         name: attr.name.name,
                                         type: [expressionType],
@@ -158,7 +165,9 @@ export function analyze(ast) {
                                     attrProps.push({
                                         name: attr.name.name,
                                         type: [expressionType],
-                                        values: [attr.value.expression.value || attr.value.expression.name],
+                                        values: [
+                                            attr.value.expression.value || attr.value.expression.name,
+                                        ],
                                     });
                                 }
                             }
@@ -230,8 +239,7 @@ export function analyze(ast) {
         walk.recursive(ast, visitorState, visitorFunctions, walk.base);
     }
     catch (e) {
-        // We don't want to log the error to the users - maybe could add some actually logging in the future
-        // console.log("error", e);
+        logger.error({ error: e, ast }, "Error analyzing file");
     }
     finally {
         return transformVisitorStateToRawUsage(visitorState);

package/dist/ast/parser.d.ts

@@ -7,4 +7,7 @@
  * @param sourceFilename a filename to help with inference
  * @returns Parsed AST
  */
-export declare function parse(code: string, sourceFilename?: string): any;
+export declare function parse(code: string, sourceFilename?: string): {
+    ast: any;
+    errors: string[];
+};

package/dist/ast/parser.js

@@ -10,7 +10,5 @@ import oxc from "oxc-parser";
  */
 export function parse(code, sourceFilename) {
     const result = oxc.parseSync(code, { sourceFilename, sourceType: "module" });
-    // TODO: Surface these errors to help in debugging
-    // console.error(result.errors)
-    return JSON.parse(result.program);
+    return { ast: JSON.parse(result.program), errors: result.errors };
 }

package/dist/cli.js

@@ -1,23 +1,41 @@
 #!/usr/bin/env node
 import * as React from "react";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { render } from "ink-render-string";
 import HelpInfo from "./components/help-info.js";
 import { analyzeCommand } from "./commands/analyze.js";
 import { authCommand } from "./commands/auth.js";
 import { monitorRepoCommand } from "./commands/monitor-repo.js";
 import { trackPackageCommand } from "./commands/track-package.js";
+import logger, { setFileStream } from "./common/logging.js";
 const program = new Command();
 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.2.1")
+    .version("2.2.3")
     .addHelpText("before", output)
+    .option("--log-file <path>", "Path to write logs to, if not provided logs only error logs will be written to stderr")
+    .addOption(new Option("--log-level <level>", "The lowest level of logs to display")
+    .default("error")
+    .choices(["fatal", "error", "warn", "info"]))
     .addCommand(analyzeCommand())
     .addCommand(authCommand())
     .addCommand(monitorRepoCommand())
-    .addCommand(trackPackageCommand());
+    .addCommand(trackPackageCommand())
+    .hook("preAction", (thisCommand, actionCommand) => {
+    logger.level = thisCommand.opts()["logLevel"];
+    if (thisCommand.opts()["logFile"]) {
+        setFileStream(thisCommand.opts()["logFile"]);
+    }
+    logger.info({
+        command: {
+            name: actionCommand.name(),
+            opts: actionCommand.opts(),
+            globalOpts: thisCommand.opts(),
+        },
+    }, "Running command");
+});
 cleanup();
 // Only start parsing if run as CLI, don't start parsing during testing
 if (process.env["NODE_ENV"] !== "test") {

package/dist/commands/analyze.js

@@ -5,6 +5,7 @@ import yn from "yn";
 import { analyzeFiles } from "./analyze.utils.js";
 import Analyze from "../components/analyze/analyze.js";
 import NonInteractiveAnalyze from "../components/analyze/non-interactive-analyze.js";
+import logger, { setStdErrStream } from "../common/logging.js";
 export async function analyzeAction(options, renderOptions) {
     if (options.interactive) {
         render(React.createElement(Analyze, { dryRun: options.dryRun, onAnalyzeFiles: () => analyzeFiles(options.extensions, options.ignore), repoName: options.repoName }), renderOptions);
@@ -18,6 +19,9 @@ export function analyzeCommand() {
     return command
         .command("analyze")
         .description("Analyze your codebase to determine component usage metrics")
+        .configureHelp({
+        showGlobalOptions: true,
+    })
         .addOption(new Option("-e, --extensions [ext]", "file extensions to include when searching for components").default("**/*.{js,jsx,ts,tsx}", "glob pattern to determine file extensions"))
         .addOption(new Option("-i, --ignore [ext]", "files to ignore when searching for components").default("**/*.{test,spec}.*", "glob pattern to determine ignored files"))
         .addOption(new Option("-d, --dry-run", "don't push results to zeroheight").default(false))
@@ -26,11 +30,14 @@ export function analyzeCommand() {
         .default(true)
         .argParser((value) => yn(value)))
         .action(async (options) => {
+        if (!options.interactive) {
+            setStdErrStream();
+        }
         try {
             await analyzeAction(options);
         }
         catch (e) {
-            console.error(e);
+            logger.error({ error: e }, "Unhandled exception running analyze command");
             process.exitCode = 1;
         }
     });

package/dist/commands/analyze.utils.js

@@ -5,6 +5,7 @@ import { Glob } from "glob";
 import ignore from "ignore";
 import { parse } from "../ast/parser.js";
 import { analyze } from "../ast/analyze.js";
+import logger from "../common/logging.js";
 /**
  * Get a list of files matching extensions, skips hidden files and node_modules
  * @param base starting directory
@@ -56,14 +57,20 @@ export async function analyzeFiles(extensions, ignorePattern) {
     for (const file of files) {
         try {
             const fileContents = await readFile(file, "utf-8");
-            const ast = parse(fileContents, file);
+            const { ast, errors } = parse(fileContents, file);
+            if (errors.length > 0) {
+                logger.error({ file, errors }, "Error parsing file");
+                parseErrors.push(`Can't parse file ${file}`);
+                continue;
+            }
             const usage = analyze(ast);
             if (usage.length > 0) {
                 const relativePath = file.slice(process.cwd().length);
                 usageMap.set(relativePath, usage);
             }
         }
-        catch {
+        catch (e) {
+            logger.error({ file, error: e }, "Error parsing file");
             parseErrors.push(`Can't parse file ${file}`);
         }
     }

package/dist/commands/auth.js

@@ -10,6 +10,9 @@ export function authCommand() {
     return command
         .command("auth")
         .description("Authenticate with zeroheight")
+        .configureHelp({
+        showGlobalOptions: true,
+    })
         .addHelpText("before", "Set credentials for performing actions with zeroheight. Credentials will default to ZEROHEIGHT_CLIENT_ID and ZEROHEIGHT_ACCESS_TOKEN environment variables if not supplied")
         .option("-c, --client <client_id>", "zeroheight Client ID", process.env["ZEROHEIGHT_CLIENT_ID"])
         .option("-t, --token <access_token>", "zeroheight Access Token", process.env["ZEROHEIGHT_ACCESS_TOKEN"])

package/dist/commands/monitor-repo.js

@@ -3,6 +3,7 @@ import { Command, Option } from "commander";
 import { render } from "ink";
 // import yn from "yn";
 import NonInteractiveMonitorRepo from "../components/monitor-repo/non-interactive-monitor-repo.js";
+import { setStdErrStream } from "../common/logging.js";
 export async function monitorRepoAction(options, _renderOptions) {
     // if (options.interactive) {
     //   render(<MonitorRepo />, renderOptions);
@@ -15,6 +16,9 @@ export function monitorRepoCommand() {
     return (command
         .command("monitor-repo")
         .description("Monitor package usage in a repository")
+        .configureHelp({
+        showGlobalOptions: true,
+    })
         // .addOption(
         //   new Option(
         //     "-in, --interactive [boolean]",
@@ -25,6 +29,7 @@ export function monitorRepoCommand() {
         // )
         .addOption(new Option("-d, --dir <path...>", "use package directory to find package.json and lockfile"))
         .action(async (options) => {
+        setStdErrStream();
         try {
             await monitorRepoAction(options);
         }

package/dist/commands/track-package.js

@@ -4,6 +4,7 @@ import { render } from "ink";
 import yn from "yn";
 import NonInteractiveTrackPackage from "../components/track-package/non-interactive-track-package.js";
 import TrackPackage from "../components/track-package/track-package.js";
+import { setStdErrStream } from "../common/logging.js";
 export async function trackPackageAction(options, renderOptions) {
     if (options.interactive) {
         render(React.createElement(TrackPackage, null), renderOptions);
@@ -17,10 +18,16 @@ export function trackPackageCommand() {
     return command
         .command("track-package")
         .description("Track the latest version of your package in zeroheight")
+        .configureHelp({
+        showGlobalOptions: true,
+    })
         .addOption(new Option("-in, --interactive [boolean]", "disable to skip manual input (useful when running in CI)")
         .default(true)
         .argParser((value) => yn(value)))
         .action(async (options) => {
+        if (!options.interactive) {
+            setStdErrStream();
+        }
         try {
             await trackPackageAction(options);
         }

package/dist/common/api.js

@@ -1,3 +1,5 @@
+import { MaxRetriesError, UnauthorizedError, UnknownError } from "./errors.js";
+import logger from "./logging.js";
 const API_PATH = "/open_api/v2";
 export var ResponseStatus;
 (function (ResponseStatus) {
@@ -64,6 +66,7 @@ async function request(path, credentials, init) {
     const maxRetries = 3;
     let retries = 0;
     while (retries < maxRetries) {
+        logger.info({ request: { url: url.toString(), init, retries } }, "Making API request");
         const response = await fetch(url, {
             ...init,
             headers: {
@@ -74,18 +77,26 @@ async function request(path, credentials, init) {
             },
         });
         if (response.status === 401) {
-            throw new Error("Unauthorized");
+            logger.error({ response: { status: response.status, body: await response.text() } }, "Unauthorized response from API");
+            throw new UnauthorizedError();
         }
         else if (response.status === 429) {
             retries++;
             const responseData = await response.json();
             const waitTime = responseData.data.reset_time * 1000 - Date.now();
+            logger.info(`Rate limited, waiting for ${waitTime}ms`);
             await sleep(waitTime);
             continue;
         }
-        return await response.json();
+        else if (response.status < 200 || response.status >= 300) {
+            logger.error({ response: { status: response.status, body: await response.text() } }, "API request failed");
+            throw new UnknownError();
+        }
+        const responseJson = await response.json();
+        logger.info({ response: { status: response.status, body: responseJson } }, "API response");
+        return responseJson;
     }
-    throw new Error(`Request failed after ${maxRetries} retries`);
+    throw new MaxRetriesError();
 }
 export function mergeUsageProps(newProps, currentProps) {
     if (!currentProps)

package/dist/common/errors.d.ts

@@ -0,0 +1,12 @@
+export declare class ApiError extends Error {
+    constructor(message: string);
+}
+export declare class UnauthorizedError extends ApiError {
+    constructor();
+}
+export declare class UnknownError extends ApiError {
+    constructor();
+}
+export declare class MaxRetriesError extends ApiError {
+    constructor();
+}

package/dist/common/errors.js

@@ -0,0 +1,21 @@
+export class ApiError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ApiError";
+    }
+}
+export class UnauthorizedError extends ApiError {
+    constructor() {
+        super("Unauthorized. Please reset your authentication by running: npx @zeroheight/adoption-cli auth");
+    }
+}
+export class UnknownError extends ApiError {
+    constructor() {
+        super("An unknown error occurred while calling the zeroheight API");
+    }
+}
+export class MaxRetriesError extends ApiError {
+    constructor() {
+        super("Max retries exceeded while calling the zeroheight API");
+    }
+}

package/dist/common/logging.d.ts

@@ -0,0 +1,4 @@
+declare const logger: import("pino").Logger<never, boolean>;
+export declare function setFileStream(path: string): void;
+export declare function setStdErrStream(): void;
+export default logger;

package/dist/common/logging.js

@@ -0,0 +1,26 @@
+import { pino } from "pino";
+import { createWriteStream } from "fs";
+import pretty from "pino-pretty";
+const streams = [];
+const loggerOptions = {
+    base: null,
+    level: "warn",
+    timestamp: pino.stdTimeFunctions.isoTime,
+    formatters: {
+        level: (label) => {
+            return { level: label.toUpperCase() };
+        },
+    },
+};
+const multistream = pino.multistream(streams);
+const logger = pino(loggerOptions, multistream);
+export function setFileStream(path) {
+    multistream.add({ stream: createWriteStream(path, { flags: "a" }) });
+}
+export function setStdErrStream() {
+    multistream.add({
+        stream: pretty({ destination: process.stderr, ignore: "pid,hostname" }),
+        level: "error",
+    });
+}
+export default logger;

package/dist/components/analyze/analyze.js

@@ -10,6 +10,7 @@ import UsageTable from "../usage-table.js";
 import { configPath, writeConfig, readConfig, } from "../../common/config.js";
 import { ResponseStatus, getAuthDetails, getZeroheightURL, submitUsageData, } from "../../common/api.js";
 import { calculateNumberOfComponents } from "../../commands/analyze.utils.js";
+import { ApiError } from "../../common/errors.js";
 export default function Analyze({ onAnalyzeFiles, dryRun, repoName, }) {
     const { exit } = useApp();
     const [usageResult, setUsageResult] = React.useState(null);
@@ -61,9 +62,10 @@ export default function Analyze({ onAnalyzeFiles, dryRun, repoName, }) {
             setResourceURL(resourceURL);
         }
         catch (e) {
-            const errorMessage = e.message === "Unauthorized"
-                ? "Unauthorized. Please reset your authentication by running: zh-adoption auth"
-                : "Failed to send data to zeroheight";
+            let errorMessage = "Failed to send data to zeroheight";
+            if (e instanceof ApiError) {
+                errorMessage = e.message;
+            }
             setErrorList((s) => [...s, errorMessage]);
         }
         finally {

package/dist/components/analyze/non-interactive-analyze.js

@@ -5,6 +5,7 @@ import Link from "ink-link";
 import { calculateNumberOfComponents } from "../../commands/analyze.utils.js";
 import { readConfig } from "../../common/config.js";
 import { submitUsageData } from "../../common/api.js";
+import { ApiError } from "../../common/errors.js";
 export default function NonInteractiveAnalyze({ repoName, onAnalyzeFiles, }) {
     const [isSendingData, setIsSendingData] = React.useState(false);
     const [isAnalyzingFiles, setIsAnalyzingFiles] = React.useState(false);
@@ -36,9 +37,10 @@ export default function NonInteractiveAnalyze({ repoName, onAnalyzeFiles, }) {
             await submitUsageData(result, repoName, credentials);
         }
         catch (e) {
-            const errorMessage = e.message === "Unauthorized"
-                ? "Unauthorized. Please reset your authentication by running: zh-adoption auth"
-                : "Failed to send data to zeroheight";
+            let errorMessage = "Failed to send data to zeroheight";
+            if (e instanceof ApiError) {
+                errorMessage = e.message;
+            }
             setErrorList((s) => [...s, errorMessage]);
         }
         finally {

package/dist/components/monitor-repo/non-interactive-monitor-repo.js

@@ -7,6 +7,7 @@ import { findPackageFiles } from "../../commands/track-package.utils.js";
 import { ResponseStatus, submitMonitoredRepoDetails, } from "../../common/api.js";
 import { readConfig } from "../../common/config.js";
 import YarnLockParser from "../../lockfile-parsers/yarn-lock-parser.js";
+import { ApiError } from "../../common/errors.js";
 var Step;
 (function (Step) {
     Step[Step["COMPLETE"] = 0] = "COMPLETE";
@@ -82,7 +83,11 @@ export default function NonInteractiveMonitorRepo({ packageDirs, }) {
                 }
             }
             catch (e) {
-                updateRepoStatus(packageMeta.name, Step.ERRORED, "Failed to send data to zeroheight");
+                let errorMessage = "Failed to send data to zeroheight";
+                if (e instanceof ApiError) {
+                    errorMessage = e.message;
+                }
+                updateRepoStatus(packageMeta.name, Step.ERRORED, errorMessage);
             }
         }
     }

package/dist/components/track-package/non-interactive-track-package.js

@@ -4,6 +4,7 @@ import Spinner from "ink-spinner";
 import { readConfig } from "../../common/config.js";
 import { getAliasesFromExports, getPackageInfo, } from "../../commands/track-package.utils.js";
 import { ResponseStatus, submitPackageDetails } from "../../common/api.js";
+import { ApiError } from "../../common/errors.js";
 var Step;
 (function (Step) {
     Step[Step["COMPLETE"] = 0] = "COMPLETE";
@@ -63,9 +64,10 @@ export default function NonInteractiveTrackPackage() {
             exit();
         }
         catch (e) {
-            const errorMessage = e.message === "Unauthorized"
-                ? "Unauthorized. Please reset your authentication by running: zh-adoption auth"
-                : "Failed to send data to zeroheight";
+            let errorMessage = "Failed to send data to zeroheight";
+            if (e instanceof ApiError) {
+                errorMessage = e.message;
+            }
             setErrorMessage(errorMessage);
             setCurrentStep(Step.ERRORED);
             exit();

package/dist/components/track-package/track-package.js

@@ -7,6 +7,7 @@ import ConfirmInput from "../ui/confirm-input.js";
 import { readConfig } from "../../common/config.js";
 import { getAliasesFromExports, getPackageInfo, } from "../../commands/track-package.utils.js";
 import { submitPackageDetails } from "../../common/api.js";
+import { ApiError } from "../../common/errors.js";
 var Step;
 (function (Step) {
     Step[Step["COMPLETE"] = 0] = "COMPLETE";
@@ -61,9 +62,10 @@ export default function TrackPackage() {
             }
         }
         catch (e) {
-            const errorMessage = e.message === "Unauthorized"
-                ? "Unauthorized. Please reset your authentication by running: zh-adoption auth"
-                : "Failed to send data to zeroheight";
+            let errorMessage = "Failed to send data to zeroheight";
+            if (e instanceof ApiError) {
+                errorMessage = e.message;
+            }
             setErrorMessage(errorMessage);
             setCurrentStep(Step.ERRORED);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroheight/adoption-cli",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "license": "ISC",
   "main": "dist/cli.js",
   "bin": {
@@ -39,6 +39,8 @@
     "ink-spinner": "^5.0.0",
     "ink-text-input": "^6.0.0",
     "oxc-parser": "^0.22.0",
+    "pino": "^9.5.0",
+    "pino-pretty": "^13.0.0",
     "react": "^18.2.0",
     "yaml": "^2.5.1",
     "yn": "^5.0.0"