@herodevs/cli 2.0.0-beta.12 → 2.0.0-beta.13

package/README.md

@@ -43,11 +43,11 @@ npm install -g @herodevs/cli@beta
 HeroDevs CLI is available as a binary installation, without requiring `npm`. To do that, you may either download and run the script manually, or use the following cURL or Wget command:
 
 ```sh
-curl -o- https://raw.githubusercontent.com/herodevs/cli/v2.0.0-beta.12/scripts/install.sh | bash
+curl -o- https://raw.githubusercontent.com/herodevs/cli/v2.0.0-beta.13/scripts/install.sh | bash
 ```
 
 ```sh
-wget -qO- https://raw.githubusercontent.com/herodevs/cli/v2.0.0-beta.12/scripts/install.sh | bash
+wget -qO- https://raw.githubusercontent.com/herodevs/cli/v2.0.0-beta.13/scripts/install.sh | bash
 ```
 
 ## Scanning Behavior
@@ -72,7 +72,7 @@ $ npm install -g @herodevs/cli@beta
 $ hd COMMAND
 running command...
 $ hd (--version)
-@herodevs/cli/2.0.0-beta.10 darwin-arm64 node-v22.18.0
+@herodevs/cli/2.0.0-beta.12 darwin-arm64 node-v24.10.0
 $ hd --help [COMMAND]
 USAGE
   $ hd COMMAND
@@ -82,6 +82,7 @@ USAGE
 ## Commands
 <!-- commands -->
 * [`hd help [COMMAND]`](#hd-help-command)
+* [`hd report committers`](#hd-report-committers)
 * [`hd scan eol`](#hd-scan-eol)
 * [`hd update [CHANNEL]`](#hd-update-channel)
   * **NOTE:** Only applies to [binary installation method](#binary-installation). NPM users should use [`npm install`](#global-npm-installation) to update to the latest version.
@@ -95,7 +96,7 @@ USAGE
   $ hd help [COMMAND...] [-n]
 
 ARGUMENTS
-  COMMAND...  Command to show help for.
+  [COMMAND...]  Command to show help for.
 
 FLAGS
   -n, --nested-commands  Include all nested commands in the output.
@@ -104,7 +105,38 @@ DESCRIPTION
   Display help for hd.
 ```
 
-_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v6.2.33/src/commands/help.ts)_
+_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v6.2.34/src/commands/help.ts)_
+
+## `hd report committers`
+
+Generate report of committers to a git repository
+
+```
+USAGE
+  $ hd report committers [--json] [-m <value>] [-c] [-s]
+
+FLAGS
+  -c, --csv             Output in CSV format
+  -m, --months=<value>  [default: 12] The number of months of git history to review
+  -s, --save            Save the committers report as herodevs.committers.<output>
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Generate report of committers to a git repository
+
+EXAMPLES
+  $ hd report committers
+
+  $ hd report committers --csv -s
+
+  $ hd report committers --json
+
+  $ hd report committers --csv
+```
+
+_See code: [src/commands/report/committers.ts](https://github.com/herodevs/cli/blob/v2.0.0-beta.12/src/commands/report/committers.ts)_
 
 ## `hd scan eol`
 
@@ -112,18 +144,20 @@ Scan a given SBOM for EOL data
 
 ```
 USAGE
-  $ hd scan eol [--json] [-f <value> | -d <value>] [-s] [-o <value>] [--saveSbom] [--sbomOutput <value>] [--saveTrimmedSbom] [--hideReportUrl] [--version]
+  $ hd scan eol [--json] [-f <value> | -d <value>] [-s] [-o <value>] [--saveSbom] [--sbomOutput <value>]
+    [--saveTrimmedSbom] [--hideReportUrl] [--version]
 
 FLAGS
-  -d, --dir=<value>      [default: <current directory>] The directory to scan in order to scan for EOL
-  -f, --file=<value>     The file path of an existing SBOM to scan for EOL (supports CycloneDX and SPDX 2.3 formats)
-  -s, --save             Save the generated report as herodevs.report.json in the scanned directory
-  -o, --output=<value>   Save the generated report to a custom path (requires --save, defaults to herodevs.report.json when not provided)
-      --hideReportUrl    Hide the generated web report URL for this scan
-      --saveSbom         Save the generated SBOM as herodevs.sbom.json in the scanned directory
-      --sbomOutput=<value>  Save the generated SBOM to a custom path (requires --saveSbom, defaults to herodevs.sbom.json when not provided)
-      --saveTrimmedSbom  Save the trimmed SBOM as herodevs.sbom-trimmed.json in the scanned directory
-      --version          Show CLI version.
+  -d, --dir=<value>         [default: <current directory>] The directory to scan in order to create a cyclonedx SBOM
+  -f, --file=<value>        The file path of an existing SBOM to scan for EOL (supports CycloneDX and SPDX 2.3 formats)
+  -o, --output=<value>      Save the generated report to a custom path (defaults to herodevs.report.json when not
+                            provided)
+  -s, --save                Save the generated report as herodevs.report.json in the scanned directory
+      --hideReportUrl       Hide the generated web report URL for this scan
+      --saveSbom            Save the generated SBOM as herodevs.sbom.json in the scanned directory
+      --saveTrimmedSbom     Save the trimmed SBOM as herodevs.sbom-trimmed.json in the scanned directory
+      --sbomOutput=<value>  Save the generated SBOM to a custom path (defaults to herodevs.sbom.json when not provided)
+      --version             Show CLI version.
 
 GLOBAL FLAGS
   --json  Format output as json.
@@ -157,7 +191,7 @@ EXAMPLES
     $ hd scan eol --json
 ```
 
-_See code: [src/commands/scan/eol.ts](https://github.com/herodevs/cli/blob/v2.0.0-beta.10/src/commands/scan/eol.ts)_
+_See code: [src/commands/scan/eol.ts](https://github.com/herodevs/cli/blob/v2.0.0-beta.12/src/commands/scan/eol.ts)_
 
 ## `hd update [CHANNEL]`
 
@@ -197,7 +231,7 @@ EXAMPLES
     $ hd update --available
 ```
 
-_See code: [@oclif/plugin-update](https://github.com/oclif/plugin-update/blob/v4.7.8/src/commands/update.ts)_
+_See code: [@oclif/plugin-update](https://github.com/oclif/plugin-update/blob/v4.7.13/src/commands/update.ts)_
 <!-- commandsstop -->
 
 ## CI/CD Usage

package/dist/commands/report/committers.d.ts

@@ -0,0 +1,23 @@
+import { Command } from '@oclif/core';
+import { type ReportData } from '../../service/committers.svc.ts';
+export default class Committers extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        months: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        csv: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        save: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<ReportData | string>;
+    /**
+     * Generates structured report data
+     * @param entries - parsed git log output for commits
+     */
+    private generateReportData;
+    /**
+     * Fetches git commit data with month and author information
+     * @param sinceDate - Date range for git log
+     */
+    private fetchGitCommitData;
+}

package/dist/commands/report/committers.js

@@ -0,0 +1,147 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { Command, Flags } from '@oclif/core';
+import { filenamePrefix } from "../../config/constants.js";
+import { calculateOverallStats, formatAsCsv, formatAsText, groupCommitsByMonth, parseGitLogOutput, } from "../../service/committers.svc.js";
+import { getErrorMessage, isErrnoException } from "../../service/error.svc.js";
+export default class Committers extends Command {
+    static description = 'Generate report of committers to a git repository';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+        '<%= config.bin %> <%= command.id %> --csv -s',
+        '<%= config.bin %> <%= command.id %> --json',
+        '<%= config.bin %> <%= command.id %> --csv',
+    ];
+    static flags = {
+        months: Flags.integer({
+            char: 'm',
+            description: 'The number of months of git history to review',
+            default: 12,
+        }),
+        csv: Flags.boolean({
+            char: 'c',
+            description: 'Output in CSV format',
+            default: false,
+        }),
+        save: Flags.boolean({
+            char: 's',
+            description: `Save the committers report as ${filenamePrefix}.committers.<output>`,
+            default: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(Committers);
+        const { months, csv, save } = flags;
+        const isJson = this.jsonEnabled();
+        const sinceDate = `${months} months ago`;
+        this.log('Starting committers report with flags: %O', flags);
+        try {
+            // Generate structured report data
+            const entries = this.fetchGitCommitData(sinceDate);
+            this.log('Fetched %d commit entries', entries.length);
+            const reportData = this.generateReportData(entries);
+            // Handle different output scenarios
+            if (isJson) {
+                // JSON mode
+                if (save) {
+                    try {
+                        fs.writeFileSync(path.resolve(`${filenamePrefix}.committers.json`), JSON.stringify(reportData, null, 2));
+                        this.log('Report written to json');
+                    }
+                    catch (error) {
+                        this.error(`Failed to save JSON report: ${getErrorMessage(error)}`);
+                    }
+                }
+                return reportData;
+            }
+            const textOutput = formatAsText(reportData);
+            if (csv) {
+                // CSV mode
+                const csvOutput = formatAsCsv(reportData);
+                if (save) {
+                    try {
+                        fs.writeFileSync(path.resolve(`${filenamePrefix}.committers.csv`), csvOutput);
+                        this.log('Report written to csv');
+                    }
+                    catch (error) {
+                        this.error(`Failed to save CSV report: ${getErrorMessage(error)}`);
+                    }
+                }
+                else {
+                    this.log(textOutput);
+                }
+                return csvOutput;
+            }
+            if (save) {
+                try {
+                    fs.writeFileSync(path.resolve(`${filenamePrefix}.committers.txt`), textOutput);
+                    this.log('Report written to txt');
+                }
+                catch (error) {
+                    this.error(`Failed to save txt report: ${getErrorMessage(error)}`);
+                }
+            }
+            else {
+                this.log(textOutput);
+            }
+            return textOutput;
+        }
+        catch (error) {
+            this.error(`Failed to generate report: ${getErrorMessage(error)}`);
+        }
+    }
+    /**
+     * Generates structured report data
+     * @param entries - parsed git log output for commits
+     */
+    generateReportData(entries) {
+        if (entries.length === 0) {
+            return { monthly: {}, overall: { total: 0 } };
+        }
+        const monthlyData = groupCommitsByMonth(entries);
+        const overallStats = calculateOverallStats(entries);
+        const grandTotal = entries.length;
+        // Format into a structured report data object
+        const report = {
+            monthly: {},
+            overall: { ...overallStats, total: grandTotal },
+        };
+        // Add monthly totals
+        for (const [month, authors] of Object.entries(monthlyData)) {
+            const monthTotal = Object.values(authors).reduce((sum, count) => sum + count, 0);
+            report.monthly[month] = { ...authors, total: monthTotal };
+        }
+        return report;
+    }
+    /**
+     * Fetches git commit data with month and author information
+     * @param sinceDate - Date range for git log
+     */
+    fetchGitCommitData(sinceDate) {
+        const logProcess = spawnSync('git', [
+            'log',
+            '--all', // Include committers on all branches in the repo
+            '--format="%ad|%an"', // Format: date|author
+            '--date=format:%Y-%m', // Format date as YYYY-MM
+            `--since="${sinceDate}"`,
+        ], { encoding: 'utf-8' });
+        if (logProcess.error) {
+            if (isErrnoException(logProcess.error)) {
+                if (logProcess.error.code === 'ENOENT') {
+                    this.error('Git command not found. Please ensure git is installed and available in your PATH.');
+                }
+                this.error(`Git command failed: ${getErrorMessage(logProcess.error)}`);
+            }
+            this.error(`Git command failed: ${getErrorMessage(logProcess.error)}`);
+        }
+        if (logProcess.status !== 0) {
+            this.error(`Git command failed with status ${logProcess.status}: ${logProcess.stderr}`);
+        }
+        if (!logProcess.stdout) {
+            return [];
+        }
+        return parseGitLogOutput(logProcess.stdout);
+    }
+}

package/dist/service/committers.svc.d.ts

@@ -0,0 +1,70 @@
+export interface CommitEntry {
+    month: string;
+    author: string;
+}
+export interface AuthorCommitCounts {
+    [author: string]: number;
+}
+export interface MonthlyData {
+    [month: string]: AuthorCommitCounts;
+}
+export interface ReportData {
+    monthly: {
+        [month: string]: {
+            [author: string]: number;
+            total: number;
+        };
+    };
+    overall: {
+        [author: string]: number;
+        total: number;
+    };
+}
+/**
+ * Parses git log output into structured data
+ * @param output - Git log command output
+ * @returns Parsed commit entries
+ */
+export declare function parseGitLogOutput(output: string): CommitEntry[];
+/**
+ * Groups commit data by month
+ * @param entries - Commit entries
+ * @returns Object with months as keys and author commit counts as values
+ */
+export declare function groupCommitsByMonth(entries: CommitEntry[]): MonthlyData;
+/**
+ * Calculates overall commit statistics by author
+ * @param entries - Commit entries
+ * @returns Object with authors as keys and total commit counts as values
+ */
+export declare function calculateOverallStats(entries: CommitEntry[]): AuthorCommitCounts;
+/**
+ * Formats monthly report sections
+ * @param monthlyData - Grouped commit data by month
+ * @returns Formatted monthly report sections
+ */
+export declare function formatMonthlyReport(monthlyData: MonthlyData): string;
+/**
+ * Formats overall statistics section
+ * @param overallStats - Overall commit counts by author
+ * @param grandTotal - Total number of commits
+ * @returns Formatted overall statistics section
+ */
+export declare function formatOverallStats(overallStats: AuthorCommitCounts, grandTotal: number): string;
+/**
+ * Formats the report data as CSV
+ * @param data - The structured report data
+ */
+export declare function formatAsCsv(data: ReportData): string;
+/**
+ * Formats the report data as text
+ * @param data - The structured report data
+ */
+export declare function formatAsText(data: ReportData): string;
+/**
+ * Format output based on user preference
+ * @param output
+ * @param reportData
+ * @returns
+ */
+export declare function formatOutputBasedOnFlag(output: string, reportData: ReportData): string;

package/dist/service/committers.svc.js

@@ -0,0 +1,196 @@
+/**
+ * Parses git log output into structured data
+ * @param output - Git log command output
+ * @returns Parsed commit entries
+ */
+export function parseGitLogOutput(output) {
+    return output
+        .split('\n')
+        .filter(Boolean)
+        .map((line) => {
+        // Remove surrounding double quotes if present (e.g. "March|John Doe" → March|John Doe)
+        const [month, author] = line.replace(/^"(.*)"$/, '$1').split('|');
+        return { month, author };
+    });
+}
+/**
+ * Groups commit data by month
+ * @param entries - Commit entries
+ * @returns Object with months as keys and author commit counts as values
+ */
+export function groupCommitsByMonth(entries) {
+    const result = {};
+    // Group commits by month
+    const commitsByMonth = entries.reduce((acc, entry) => {
+        const monthKey = entry.month;
+        if (!acc[monthKey]) {
+            acc[monthKey] = [];
+        }
+        acc[monthKey].push(entry);
+        return acc;
+    }, {});
+    // Process each month
+    for (const [month, commits] of Object.entries(commitsByMonth)) {
+        if (!commits) {
+            result[month] = {};
+            continue;
+        }
+        // Count commits per author for this month
+        const commitsByAuthor = commits.reduce((acc, entry) => {
+            const authorKey = entry.author;
+            if (!acc[authorKey]) {
+                acc[authorKey] = [];
+            }
+            acc[authorKey].push(entry);
+            return acc;
+        }, {});
+        const authorCounts = {};
+        for (const [author, authorCommits] of Object.entries(commitsByAuthor)) {
+            authorCounts[author] = authorCommits?.length ?? 0;
+        }
+        result[month] = authorCounts;
+    }
+    return result;
+}
+/**
+ * Calculates overall commit statistics by author
+ * @param entries - Commit entries
+ * @returns Object with authors as keys and total commit counts as values
+ */
+export function calculateOverallStats(entries) {
+    const commitsByAuthor = entries.reduce((acc, entry) => {
+        const authorKey = entry.author;
+        if (!acc[authorKey]) {
+            acc[authorKey] = [];
+        }
+        acc[authorKey].push(entry);
+        return acc;
+    }, {});
+    const result = {};
+    // Count commits for each author
+    for (const author in commitsByAuthor) {
+        result[author] = commitsByAuthor[author]?.length ?? 0;
+    }
+    return result;
+}
+/**
+ * Formats monthly report sections
+ * @param monthlyData - Grouped commit data by month
+ * @returns Formatted monthly report sections
+ */
+export function formatMonthlyReport(monthlyData) {
+    const sortedMonths = Object.keys(monthlyData).sort();
+    let report = '';
+    for (const month of sortedMonths) {
+        report += `\n## ${month}\n`;
+        const authors = Object.entries(monthlyData[month]).sort((a, b) => b[1] - a[1]);
+        for (const [author, count] of authors) {
+            report += `${count.toString().padStart(6)}  ${author}\n`;
+        }
+        const monthTotal = authors.reduce((sum, [_, count]) => sum + count, 0);
+        report += `${monthTotal.toString().padStart(6)}  TOTAL\n`;
+    }
+    return report;
+}
+/**
+ * Formats overall statistics section
+ * @param overallStats - Overall commit counts by author
+ * @param grandTotal - Total number of commits
+ * @returns Formatted overall statistics section
+ */
+export function formatOverallStats(overallStats, grandTotal) {
+    let report = '\n## Overall Statistics\n';
+    const sortedStats = Object.entries(overallStats).sort((a, b) => b[1] - a[1]);
+    for (const [author, count] of sortedStats) {
+        report += `${count.toString().padStart(6)}  ${author}\n`;
+    }
+    report += `${grandTotal.toString().padStart(6)}  GRAND TOTAL\n`;
+    return report;
+}
+/**
+ * Formats the report data as CSV
+ * @param data - The structured report data
+ */
+export function formatAsCsv(data) {
+    // First prepare all author names (for columns)
+    const allAuthors = new Set();
+    // Collect all unique author names
+    for (const monthData of Object.values(data.monthly)) {
+        for (const author of Object.keys(monthData)) {
+            if (author !== 'total')
+                allAuthors.add(author);
+        }
+    }
+    const authors = Array.from(allAuthors).sort();
+    // Create CSV header
+    let csv = `Month,${authors.join(',')},Total\n`;
+    // Add monthly data rows
+    const sortedMonths = Object.keys(data.monthly).sort();
+    for (const month of sortedMonths) {
+        csv += month;
+        // Add data for each author
+        for (const author of authors) {
+            const count = data.monthly[month][author] || 0;
+            csv += `,${count}`;
+        }
+        // Add monthly total
+        csv += `,${`${data.monthly[month].total}\n`}`;
+    }
+    // Add overall totals row
+    csv += 'Overall';
+    for (const author of authors) {
+        const count = data.overall[author] || 0;
+        csv += `,${count}`;
+    }
+    csv += `,${data.overall.total}\n`;
+    return csv;
+}
+/**
+ * Formats the report data as text
+ * @param data - The structured report data
+ */
+export function formatAsText(data) {
+    let report = 'Monthly Commit Report\n';
+    // Monthly sections
+    const sortedMonths = Object.keys(data.monthly).sort();
+    for (const month of sortedMonths) {
+        report += `\n## ${month}\n`;
+        const authors = Object.entries(data.monthly[month])
+            .filter(([author]) => author !== 'total')
+            .sort((a, b) => b[1] - a[1]);
+        for (const [author, count] of authors) {
+            report += `${count.toString().padStart(6)}  ${author}\n`;
+        }
+        report += `${data.monthly[month].total.toString().padStart(6)}  TOTAL\n`;
+    }
+    // Overall statistics
+    report += '\n## Overall Statistics\n';
+    const sortedEntries = Object.entries(data.overall)
+        .filter(([author]) => author !== 'total')
+        .sort((a, b) => b[1] - a[1]);
+    for (const [author, count] of sortedEntries) {
+        report += `${count.toString().padStart(6)}  ${author}\n`;
+    }
+    report += `${data.overall.total.toString().padStart(6)}  GRAND TOTAL\n`;
+    return report;
+}
+/**
+ * Format output based on user preference
+ * @param output
+ * @param reportData
+ * @returns
+ */
+export function formatOutputBasedOnFlag(output, reportData) {
+    let formattedOutput;
+    switch (output) {
+        case 'json':
+            formattedOutput = JSON.stringify(reportData, null, 2);
+            break;
+        case 'csv':
+            formattedOutput = formatAsCsv(reportData);
+            break;
+        default:
+            formattedOutput = formatAsText(reportData);
+    }
+    return formattedOutput;
+}

package/dist/service/error.svc.d.ts

@@ -0,0 +1,8 @@
+export declare const isError: (error: unknown) => error is Error;
+export declare const isErrnoException: (error: unknown) => error is NodeJS.ErrnoException;
+export declare const isApolloError: (error: unknown) => error is ApolloError;
+export declare const getErrorMessage: (error: unknown) => string;
+export declare class ApolloError extends Error {
+    readonly originalError?: unknown;
+    constructor(message: string, original?: unknown);
+}

package/dist/service/error.svc.js

@@ -0,0 +1,28 @@
+export const isError = (error) => {
+    return error instanceof Error;
+};
+export const isErrnoException = (error) => {
+    return isError(error) && 'code' in error;
+};
+export const isApolloError = (error) => {
+    return error instanceof ApolloError;
+};
+export const getErrorMessage = (error) => {
+    if (isError(error)) {
+        return error.message;
+    }
+    return 'Unknown error';
+};
+export class ApolloError extends Error {
+    originalError;
+    constructor(message, original) {
+        if (isError(original)) {
+            super(`${message}: ${original.message}`);
+        }
+        else {
+            super(`${message}: ${String(original)}`);
+        }
+        this.name = 'ApolloError';
+        this.originalError = original;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herodevs/cli",
-  "version": "2.0.0-beta.12",
+  "version": "2.0.0-beta.13",
   "author": "HeroDevs, Inc",
   "bin": {
     "hd": "./bin/run.js"
@@ -39,11 +39,11 @@
     "herodevs cli"
   ],
   "dependencies": {
-    "@amplitude/analytics-node": "^1.5.20",
+    "@amplitude/analytics-node": "^1.5.21",
     "@apollo/client": "^3.13.8",
     "@cyclonedx/cdxgen": "^11.11.0",
-    "@herodevs/eol-shared": "github:herodevs/eol-shared#v0.1.11",
-    "@oclif/core": "^4.5.3",
+    "@herodevs/eol-shared": "github:herodevs/eol-shared#v0.1.12",
+    "@oclif/core": "^4.8.0",
     "@oclif/plugin-help": "^6.2.32",
     "@oclif/plugin-update": "^4.7.13",
     "node-machine-id": "^1.1.12",
@@ -53,10 +53,10 @@
     "update-notifier": "^7.3.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.2.2",
+    "@biomejs/biome": "^2.3.3",
     "@oclif/test": "^4.1.13",
     "@types/inquirer": "^9.0.9",
-    "@types/node": "^24.9.2",
+    "@types/node": "^24.10.0",
     "@types/sinon": "^17.0.4",
     "@types/update-notifier": "^6.0.8",
     "globstar": "^1.0.0",
@@ -110,4 +110,4 @@
     }
   },
   "types": "dist/index.d.ts"
-}
+}