From e921a9c3cba9a2f3eca2a17a352168dcafc0a0c1 Mon Sep 17 00:00:00 2001 From: Rustaman Delvianova <96533738+Rustaman1280@users.noreply.github.com> Date: Sat, 31 Oct 2026 07:37:31 +0000 Subject: [PATCH] docs: publish architecture documentation, GitHub Action, and CI workflow - Publish reusable GitHub Action definition in action.yml - Add matrix testing CI workflow for Node.js 20 and 22 - Complete comprehensive production documentation in README.md - Add CLI usage examples, API reference, and badge assets Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .github/workflows/ci.yml | 33 ++++++++++ README.md | 137 +++++++++++++++++++++++++++++++++++---- action.yml | 22 +++++++ 3 files changed, 180 insertions(+), 12 deletions(-) create mode 100644 .github/workflows/ci.yml create mode 100644 action.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..b801167 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,33 @@ +name: CI + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + test: + runs-on: ubuntu-latest + strategy: + matrix: + node-version: [20.x, 22.x] + + steps: + - name: Checkout Code + uses: actions/checkout@v4 + + - name: Setup Node.js ${{ matrix.node-version }} + uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node-version }} + cache: "npm" + + - name: Install Dependencies + run: npm ci + + - name: Build TypeScript + run: npm run build + + - name: Run Test Suite + run: npm test diff --git a/README.md b/README.md index 8513166..0be913e 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,126 @@ # Collab Kit -Collaborative utilities and developer automation workflows. -## Guidelines -- Best practices for distributed teams -- Step 3: Automated team workflow 3 -- Step 4: Automated team workflow 4 -- Step 5: Automated team workflow 5 -- Step 6: Automated team workflow 6 -- Step 7: Automated team workflow 7 -- Step 8: Automated team workflow 8 -- Step 9: Automated team workflow 9 -- Step 10: Automated team workflow 10 -- Step 11: Automated team workflow 11 + +[![CI Status](https://github.com/Rustaman1280/collab-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/Rustaman1280/collab-kit/actions) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) +[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/) + +Production-grade developer toolkit for engineering collectives, pair programming, and multi-agent workflow attribution. Built by [crustdev](https://crusts.dev). + +--- + +## Overview + +When engineering teams and AI agents collaborate on modern software, tracking co-authorship and crediting contributors is essential. **Collab Kit** provides an automated engine to parse, format, validate, and credit git commit trailers (such as `Co-authored-by: Name `) according to RFC 2822 specifications and GitHub contribution guidelines. + +### Features + +- **Trailer Parser**: Robust extraction of commit subjects, bodies, and terminal git trailer blocks. +- **Co-author Formatter**: Generates RFC-compliant `Co-authored-by` commit trailers with automatic deduplication. +- **Validation Engine**: Verifies name and email syntax on staged commit messages or git hook files (`COMMIT_EDITMSG`). +- **Release Credits Generator**: Scans git commit ranges and produces clean markdown tables or lists for release notes. +- **GitHub Action & Git Hooks**: Integrates seamlessly into CI pipelines and local pre-commit hooks. + +--- + +## Installation + +```bash +npm install -g @crustdev/collab-kit +``` + +Or run directly via `npx`: + +```bash +npx @crustdev/collab-kit help +``` + +--- + +## CLI Usage + +### 1. Validate Commit Message + +Validate whether a commit message has properly formatted trailers and valid emails: + +```bash +# Validate a git hook file +collab-kit validate .git/COMMIT_EDITMSG + +# Or validate an inline commit string +collab-kit validate "feat: core update\n\nCo-authored-by: Alice " +``` + +### 2. Generate Co-author Trailer + +Format a standard co-author trailer: + +```bash +collab-kit format "Rustaman Delvianova" "rustaman@crusts.dev" +``` + +Output: +```text +Co-authored-by: Rustaman Delvianova +``` + +### 3. Generate Release Attribution Credits + +Scan commits between branches or tags to generate markdown attribution for your changelog: + +```bash +collab-kit credits origin/main..HEAD +``` + +Output: +```markdown +### Contributors & Co-authors + +Thanks to everyone who paired and contributed code in this release: +- **Rustaman Delvianova** (`rustaman@crusts.dev`) +- **github-actions[bot]** (`41898282+github-actions[bot]@users.noreply.github.com`) +``` + +--- + +## Programmatic API + +```typescript +import { + parseCommitMessage, + validateCommitMessage, + formatCoAuthorTrailers, + generateReleaseCredits +} from "@crustdev/collab-kit"; + +// Parse commit message +const parsed = parseCommitMessage(rawMessage); +console.log(parsed.coAuthors); + +// Validate +const result = validateCommitMessage(rawMessage); +if (!result.valid) { + console.error(result.errors); +} + +// Generate release markdown +const credits = generateReleaseCredits(parsed.coAuthors); +``` + +--- + +## GitHub Actions Integration + +Add this step to your PR validation workflow to ensure all paired commits follow clean trailer conventions: + +```yaml +- name: Validate PR Co-authors + uses: Rustaman1280/collab-kit@main + with: + range: origin/main..HEAD +``` + +--- + +## License + +MIT (c) 2026 Rustaman Delvianova / crustdev. diff --git a/action.yml b/action.yml new file mode 100644 index 0000000..ed66bc9 --- /dev/null +++ b/action.yml @@ -0,0 +1,22 @@ +name: "Collab Kit Trailer Validator" +description: "Validates git commit trailers and co-authorship metadata for pull requests" +author: "Rustaman Delvianova" + +inputs: + range: + description: "Commit range to inspect" + required: false + default: "origin/main..HEAD" + +runs: + using: "composite" + steps: + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: 22 + + - name: Validate PR Commit Trailers + shell: bash + run: | + node ${{ github.action_path }}/dist/cli.js credits "${{ inputs.range }}"