Merge pull request #188 from mona-actions/feat/json-output

Add JSON output for repo statistics

Author: amenocal

README.md

@@ -27,6 +27,8 @@ Options:
      -H, --hostname                : The GitHub hostname for the request
                                      Default: github.com
      -i, --input                   : Set path to a file with a list of organizations to scan, one per line, newline delimited
+     -J, --json                    : Output results in JSON format instead of CSV
+                                     Conforms to the schema defined in json-schema.md
      -o, --org                     : Name of the GitHub Organization to be analyzed
      -O, --output                  : Format of output, can either be "CSV" or "Table"
                                      Default: CSV
@@ -49,6 +51,7 @@ Description:
 Example:
   gh repo-stats -o my-org-name
   gh repo-stats -o my-org-name -H github.example.com
+  gh repo-stats -o my-org-name --json
 ```
 
 ## Permissions
@@ -69,7 +72,7 @@ The permissions needed by `gh repo-stats` depends based on `-y, --token-type`:
 
 ## Output
 
-`gh repo-stats` produces either a visual table or `*.csv` file containing detailed information about various records within repositories.
+`gh repo-stats` produces either a visual table or `*.csv` file containing detailed information about various records within repositories. When the `--json` (`-J`) flag is provided, output is written as JSON conforming to the schema defined in [`json-schema.md`](docs/json-schema.md). The output conforms to the [gh-stats-visualizer](https://github.com/mona-actions/gh-stats-visualizer) input format.
 
 ```csv
 Org_Name,Repo_Name,Is_Empty,Last_Push,Last_Update,isFork,isArchive,Repo_Size(mb),Record_Count,Collaborator_Count,Protected_Branch_Count,PR_Review_Count,Milestone_Count,Issue_Count,PR_Count,PR_Review_Comment_Count,Commit_Comment_Count,Issue_Comment_Count,Issue_Event_Count,Release_Count,Project_Count,Branch_Count,Tag_Count,Discussion_Count,Has_Wiki,Full_URL,Migration_Issue,Created

docs/json-schema.md

@@ -0,0 +1,96 @@
+# gh-repo-stats JSON Schema Specification
+
+This document defines the JSON output format produced by `gh-repo-stats --json`.
+
+---
+
+## Table of Contents
+
+- [Top-Level Structure](#top-level-structure)
+- [Repository Object](#repository-object-repos)
+  - [Core Fields](#core-fields)
+- [Example](#example)
+
+---
+
+## Top-Level Structure
+
+```json
+{
+  "repos": []
+}
+```
+
+| Field  | Type    | Required | Description                                                |
+| ------ | ------- | -------- | ---------------------------------------------------------- |
+| `repos`| `array` | ✅        | Array of [repository objects](#repository-object-repos)    |
+
+---
+
+## Repository Object (`repos[]`)
+
+### Core Fields
+
+| Field               | Type      | Description                                           |
+| ------------------- | --------- | ----------------------------------------------------- |
+| `org`               | `string`  | Organization name                                     |
+| `name`              | `string`  | Repository name                                       |
+| `url`               | `string`  | Repository URL                                        |
+| `isFork`            | `boolean` | Whether the repository is a fork                      |
+| `isArchived`        | `boolean` | Whether the repository is archived                    |
+| `diskUsage`         | `number`  | Repository size in **KB**                             |
+| `sizeMB`            | `number`  | Repository size in **MB**                             |
+| `hasWikiEnabled`    | `boolean` | Whether the wiki is enabled                           |
+| `createdAt`         | `string`  | ISO 8601 creation timestamp                           |
+| `updatedAt`         | `string`  | ISO 8601 last update timestamp                        |
+| `pushedAt`          | `string`  | ISO 8601 last push timestamp                          |
+| `collaborators`     | `number`  | Number of collaborators                               |
+| `branches`          | `number`  | Number of branches                                    |
+| `tags`              | `number`  | Number of tags                                        |
+| `branchProtections` | `number`  | Number of branch protection rules                     |
+| `issues`            | `number`  | Total issue count                                     |
+| `pullRequests`      | `number`  | Total pull request count                              |
+| `milestones`        | `number`  | Number of milestones                                  |
+| `releases`          | `number`  | Number of releases                                    |
+| `projects`          | `number`  | Number of projects                                    |
+| `discussions`       | `number`  | Number of discussions                                 |
+| `commitComments`    | `number`  | Number of commit comments                             |
+| `issueEvents`       | `number`  | Number of issue events                                |
+
+All fields are always present in the output.
+
+---
+
+## Example
+
+```json
+{
+  "repos": [
+    {
+      "org": "my-org",
+      "name": "my-repo",
+      "url": "https://github.com/my-org/my-repo",
+      "isFork": false,
+      "isArchived": false,
+      "diskUsage": 51200,
+      "sizeMB": 50,
+      "hasWikiEnabled": false,
+      "createdAt": "2024-01-15T10:30:00Z",
+      "updatedAt": "2025-06-01T14:00:00Z",
+      "pushedAt": "2025-06-01T14:00:00Z",
+      "collaborators": 12,
+      "branches": 8,
+      "tags": 15,
+      "branchProtections": 2,
+      "issues": 45,
+      "pullRequests": 120,
+      "milestones": 4,
+      "releases": 12,
+      "projects": 2,
+      "discussions": 8,
+      "commitComments": 5,
+      "issueEvents": 350
+    }
+  ]
+}
+```