👔 Enhance hostname normalization (#125)

Author: stoe

readme.md

@@ -77,10 +77,10 @@ $ action-reporting-cli --<scope> <name> --<report-options> --<output-options>
 
 ### Authentication and Connection
 
-| Option              | Description                                                                                                                                                                                                                      | Default                             |
-| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| `--token`,<br/>`-t` | Your GitHub Personal Access Token                                                                                                                                                                                                | Environment variable `GITHUB_TOKEN` |
-| `--hostname`        | GitHub Enterprise Server hostname or GitHub Enterprise Cloud with Data Residency endpoint:<br/>- For GitHub Enterprise Server: `github.example.com`<br/>- For GitHub Enterprise Cloud with Data Residency: `api.example.ghe.com` | `api.github.com`                    |
+| Option              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                     | Default                             |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| `--token`,<br/>`-t` | Your GitHub Personal Access Token                                                                                                                                                                                                                                                                                                                                                                                                               | Environment variable `GITHUB_TOKEN` |
+| `--hostname`        | GitHub Enterprise Server hostname **or** GitHub Enterprise Cloud with Data Residency regional hostname.<br/>Examples:<br/>- GHES: `github.example.com` (resolved -> `https://github.example.com/api/v3`)<br/>- GHEC+DR: `example.ghe.com` (auto-resolved -> `https://api.example.ghe.com`)<br/>- GHEC+DR (explicit API host also accepted): `api.example.ghe.com` (left unchanged)<br/>If omitted, defaults to public: `https://api.github.com` | `api.github.com`                    |
 
 ### Report Content Options
 
@@ -130,6 +130,35 @@ The tool generates reports in your specified format(s):
 
 When you use `--unique both` with `--uses`, you'll get an additional file with the `.unique` suffix containing only unique third-party actions.
 
+### Hostname Handling
+
+The CLI automatically normalizes the GitHub API base URL based on the value you pass to `--hostname`:
+
+| Input Provided                | Resolved API Base URL               | Classification                     |
+| ----------------------------- | ----------------------------------- | ---------------------------------- |
+| (none)                        | `https://api.github.com`            | Public GitHub                      |
+| `github.example.com`          | `https://github.example.com/api/v3` | GitHub Enterprise Server (GHES)    |
+| `https://github.example.com/` | `https://github.example.com/api/v3` | GHES (normalized)                  |
+| `example.ghe.com`             | `https://api.example.ghe.com`       | GHEC+DR regional (prefixed)        |
+| `api.example.ghe.com`         | `https://api.example.ghe.com`       | GHEC+DR regional (already API)     |
+| `HTTPS://Api.Example.GHE.COM` | `https://api.example.ghe.com`       | GHEC+DR (case + protocol stripped) |
+| `example.ghe.com/anything`    | `https://api.example.ghe.com`       | GHEC+DR (path stripped)            |
+
+Rules applied in order:
+
+1. If no hostname is provided, use the public API.
+2. If the hostname ends with `.ghe.com` (GitHub Enterprise Cloud with Data Residency):
+
+- If it already starts with `api.`, it's used as-is.
+- Otherwise `api.` is prefixed (no `/api/v3` suffix is added).
+
+3. All other custom hostnames are treated as GitHub Enterprise Server and `/api/v3` is appended.
+4. Protocol, trailing slashes, mixed case, and extraneous path segments are stripped/normalized.
+
+You can safely pass either the regional base (`example.ghe.com`) or the explicit API host (`api.example.ghe.com`); both resolve to the correct endpoint.
+
+> Tip: If your environment migrates between public GitHub and GHES/GHEC+DR, you can centralize logic by always providing `--hostname` and letting the tool normalize.
+
 ## Examples
 
 Here are some common usage scenarios to help you get started:

src/github/octokit.js

@@ -27,14 +27,25 @@ export default function getOctokit(token, hostname = null, debug = false) {
   // Create separate logger instance for Octokit
   const logger = log('octokit', token, debug, true)
 
-  // Normalize hostname for GitHub Enterprise servers
+  // Normalize hostname for GitHub Enterprise (Server or Cloud with Data Residency)
+  // Rules:
+  //  - If hostname ends with `.ghe.com` (GHEC+DR regional hostname like `example.ghe.com`),
+  //    the API hostname is `https://api.<hostname>` (no `/api/v3` suffix).
+  //  - Otherwise (enterprise server host provided), append `/api/v3`.
+  //  - If no hostname provided, use public github.com API.
   if (hostname) {
     const normalizedHost = normalizeUrl(hostname, {
       removeTrailingSlash: true,
       stripProtocol: true,
     }).split('/')[0]
 
-    hostname = `https://${normalizedHost}/api/v3`
+    if (/\.ghe\.com$/i.test(normalizedHost)) {
+      // GHEC+DR regional host. If already api-prefixed, keep as-is; else prefix with api.
+      const gheCloudHost = normalizedHost.startsWith('api.') ? normalizedHost : `api.${normalizedHost}`
+      hostname = `https://${gheCloudHost}`
+    } else {
+      hostname = `https://${normalizedHost}/api/v3`
+    }
   } else {
     hostname = 'https://api.github.com'
   }
@@ -70,3 +81,12 @@ export default function getOctokit(token, hostname = null, debug = false) {
 
   return instance
 }
+
+/**
+ * Helper to retrieve the resolved baseUrl from an Octokit instance.
+ * @param {import('@octokit/core').Octokit} octokit
+ * @returns {string|undefined}
+ */
+export function getBaseUrl(octokit) {
+  return octokit?.request?.endpoint?.DEFAULTS?.baseUrl
+}

test/github/octokit.test.js

@@ -3,6 +3,11 @@
  */
 import {jest} from '@jest/globals'
 
+// Reset singleton between tests by clearing module cache
+beforeEach(() => {
+  jest.resetModules()
+})
+
 describe('octokit', () => {
   beforeEach(() => {})
 
@@ -11,33 +16,49 @@ describe('octokit', () => {
   /**
    * Test that Octokit client is created with correct token and options.
    */
-  test('should create Octokit client with valid token and options', () => {
-    // TODO: Implement test logic
-    expect(true).toBe(true)
+  test('should create Octokit client with valid token and default api.github.com', async () => {
+    const {default: getOctokit, getBaseUrl} = await import('../../src/github/octokit.js')
+    const client = getOctokit('token')
+    expect(getBaseUrl(client)).toBe('https://api.github.com')
   })
 
   /**
    * Test constructor options
    */
   describe('constructor options', () => {
-    test('should handle all constructor parameters', () => {
-      // TODO: Implement test logic
-      expect(true).toBe(true)
+    test('should normalize classic GHE hostname to /api/v3', async () => {
+      const {default: getOctokit, getBaseUrl} = await import('../../src/github/octokit.js')
+      const client = getOctokit('token', 'ghe.internal.example.com')
+      expect(getBaseUrl(client)).toBe('https://ghe.internal.example.com/api/v3')
+    })
+
+    test('should transform GHEC+DR hostname *.ghe.com to api.<host>', async () => {
+      const {default: getOctokit, getBaseUrl} = await import('../../src/github/octokit.js')
+      const client = getOctokit('token', 'region1.ghe.com')
+      expect(getBaseUrl(client)).toBe('https://api.region1.ghe.com')
+    })
+
+    test('should preserve already api-prefixed GHEC+DR hostname without /api/v3', async () => {
+      const {default: getOctokit, getBaseUrl} = await import('../../src/github/octokit.js')
+      const client = getOctokit('token', 'api.region1.ghe.com')
+      expect(getBaseUrl(client)).toBe('https://api.region1.ghe.com')
     })
 
-    test('should handle default values', () => {
-      // TODO: Implement test logic
-      expect(true).toBe(true)
+    test('should handle default values', async () => {
+      const {default: getOctokit, getBaseUrl} = await import('../../src/github/octokit.js')
+      const client = getOctokit('token')
+      expect(getBaseUrl(client)).toBe('https://api.github.com')
     })
   })
 
   /**
    * Test client operations
    */
   describe('client operations', () => {
-    test('should perform API requests correctly', () => {
-      // TODO: Implement test logic
-      expect(true).toBe(true)
+    test('should perform API requests correctly', async () => {
+      const {default: getOctokit} = await import('../../src/github/octokit.js')
+      const client = getOctokit('token')
+      expect(typeof client.request).toBe('function')
     })
   })
 })