@bernierllc/github-parser 1.0.0

package/.eslintrc.cjs

@@ -0,0 +1,33 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended'
+  ],
+  plugins: ['@typescript-eslint'],
+  parserOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module',
+    project: './tsconfig.json'
+  },
+  env: {
+    node: true,
+    es6: true
+  },
+  rules: {
+    '@typescript-eslint/explicit-function-return-type': 'off',
+    '@typescript-eslint/no-explicit-any': 'error',
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+    '@typescript-eslint/no-non-null-assertion': 'warn'
+  },
+  ignorePatterns: ['dist/', 'node_modules/', '*.cjs']
+};
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bernier LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# @bernierllc/github-parser
+
+GitHub webhook payload parser and transformer
+
+## Installation
+
+```bash
+npm install @bernierllc/github-parser
+```
+
+## Features
+
+- **Webhook parsing** - Parse all GitHub webhook event types
+- **Commit extraction** - Extract commit information from push events
+- **Repository metadata** - Extract repository details
+- **Event normalization** - Normalize different payload structures
+- **Type-safe** - Full TypeScript support with interfaces
+- **Framework agnostic** - Pure parsing logic
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { GitHubParser } from '@bernierllc/github-parser';
+
+const parser = new GitHubParser();
+
+// Parse webhook payload
+const event = parser.parse(webhookPayload);
+
+console.log('Event type:', event.type);
+console.log('Repository:', event.repository.fullName);
+console.log('Commits:', event.commits);
+```
+
+### Parse Push Webhook
+
+```typescript
+const payload = {
+  ref: 'refs/heads/main',
+  repository: { /* ... */ },
+  commits: [
+    {
+      id: 'abc123',
+      message: 'Add feature',
+      author: { name: 'Developer', email: 'dev@example.com' },
+      // ...
+    }
+  ]
+};
+
+const event = parser.parse(payload);
+console.log('Branch:', event.branch); // 'main'
+console.log('Commits:', event.commits?.length);
+```
+
+### Extract Commits
+
+```typescript
+const commits = parser.extractCommits(payload);
+commits.forEach(commit => {
+  console.log('SHA:', commit.sha);
+  console.log('Message:', commit.message);
+  console.log('Files:', commit.files);
+  console.log('Additions:', commit.additions);
+  console.log('Deletions:', commit.deletions);
+});
+```
+
+### Extract Repository
+
+```typescript
+const repo = parser.extractRepository(payload);
+console.log('Name:', repo.name);
+console.log('Full name:', repo.fullName);
+console.log('Owner:', repo.owner.login);
+console.log('Private:', repo.private);
+```
+
+### Extract Single Commit
+
+```typescript
+const commit = parser.extractCommit(payload);
+if (commit) {
+  console.log('Commit SHA:', commit.sha);
+  console.log('Author:', commit.author.name);
+}
+```
+
+## API
+
+### `new GitHubParser()`
+
+Creates a new GitHub parser instance.
+
+### `parser.parse(payload: GitHubWebhookPayload): ParsedWebhookEvent`
+
+Parses a GitHub webhook payload into a normalized event structure.
+
+### `parser.extractCommits(payload: GitHubWebhookPayload): ParsedCommit[]`
+
+Extracts all commits from a push webhook payload.
+
+### `parser.extractCommit(payload: GitHubWebhookPayload): ParsedCommit | null`
+
+Extracts a single commit from a webhook payload.
+
+### `parser.extractRepository(payload: GitHubWebhookPayload): ParsedRepository`
+
+Extracts repository information from a webhook payload.
+
+### `parser.normalizeEventType(payload: GitHubWebhookPayload): string`
+
+Normalizes the event type from a webhook payload.
+
+## Integration Status
+
+### Logger Integration
+**Status**: ✅ Integrated
+
+Uses `@bernierllc/logger` for parsing events, errors, and webhook processing.
+
+### NeverHub Integration
+**Status**: ⚠️ Optional
+
+Can emit parsing events to NeverHub for distributed monitoring and observability. GitHub parser can publish events like `github.webhook.parsed`, `github.commit.extracted`, and `github.repository.extracted` to NeverHub when available.
+
+**Pattern**: Optional service discovery integration - package can emit parsing events to NeverHub for distributed monitoring.
+
+**Example Integration**:
+```typescript
+// If NeverHub is available, emit events
+if (typeof detectNeverHub === 'function') {
+  const event = parser.parse(payload);
+  neverhub.emit('github-parser.webhook.parsed', event);
+}
+```
+
+### Docs-Suite Integration
+**Status**: ✅ Ready
+
+TypeDoc-compatible JSDoc comments are included throughout the source code. All public APIs are documented with examples and type information.
+
+## License
+
+Copyright (c) 2025 Bernier LLC. All rights reserved.
+