split-by-codeowners 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anatolii (Nate) Kurochkin
+
+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,181 @@
+# split-by-codeowners
+
+Split a set of local changes into **CODEOWNERS buckets** and (optionally) create **one PR per bucket**.
+
+Works in two modes sharing the same core logic:
+
+- **GitHub Action**: run in CI after your codemod step; generates patches + can create/update PRs (no third-party PR actions).
+- **CLI (`npx`)**: run locally to bucketize current working tree changes; can create/update PRs using `gh` for best dev UX.
+
+## Why
+
+If a codemod touches files owned by different teams, you often want:
+
+- smaller PRs
+- clearer ownership/review routing
+- independent merge/rollback per owner group
+
+This tool groups changed files by their **effective CODEOWNERS owner set** (last-match-wins semantics).
+
+## Quickstart (GitHub Action)
+
+```yaml
+permissions:
+  contents: write
+  pull-requests: write
+
+steps:
+  - uses: actions/checkout@v4
+  - name: Run codemods
+    run: ./run-codemods.sh
+
+  - name: Split into CODEOWNERS PRs
+    uses: anatoliisf/split-by-codeowners@v1
+    with:
+      create_prs: "true"
+      github_token: ${{ github.token }}
+```
+
+## Quickstart (CLI)
+
+Bucketize + write patches:
+
+```bash
+npx split-by-codeowners
+```
+
+Create/update PRs locally (recommended: `gh` auth):
+
+```bash
+gh auth login -h github.com
+npx split-by-codeowners --create-prs --base-branch main
+```
+
+## GitHub Action
+
+### Inputs
+
+| Name | Required | Default | Description |
+| --- | --- | --- | --- |
+| `codeowners_path` | no | `CODEOWNERS` | Path to CODEOWNERS file |
+| `base_ref` | no | `""` | Base ref for changed-files discovery (currently workspace-focused; see notes) |
+| `include_unowned` | no | `"true"` | Include files with no owners in a special bucket |
+| `unowned_bucket_key` | no | `__UNOWNED__` | Bucket key for unowned files |
+| `max_buckets` | no | `"30"` | Fail if buckets exceed this number |
+| `exclude_patterns` | no | `""` | Newline-separated glob patterns to exclude (minimatch) |
+| `patch_dir` | no | `bucket-patches` | Directory to write per-bucket patch files |
+| `bucket_prefix` | no | `bucket` | Patch file prefix |
+| `dry_run` | no | `"false"` | Compute buckets but don’t write patches |
+| `cleanup_patches` | no | `"false"` | Delete `patch_dir` after a successful run |
+| `create_prs` | no | `"false"` | Create/update one PR per bucket |
+| `github_token` | no | `""` | Token used for pushing branches + GitHub API (defaults to env `GITHUB_TOKEN`) |
+| `base_branch` | no | `""` | Base branch for PRs (defaults to repo default branch) |
+| `branch_prefix` | no | `codemods/` | Prefix for created branches |
+| `commit_message` | no | `chore: automated changes` | Commit message for bucket PRs |
+| `pr_title` | no | `chore: automated changes ({owners})` | PR title template (`{owners}`, `{bucket_key}`) |
+| `pr_body` | no | *(see `action.yml`)* | PR body template (`{owners}`, `{bucket_key}`, `{files}`) |
+| `draft` | no | `"false"` | Create PRs as drafts |
+
+### Outputs
+
+| Name | Description |
+| --- | --- |
+| `matrix_json` | JSON for `strategy.matrix` (`{ include: [...] }`) |
+| `buckets_json` | Full buckets JSON (owners + files + matched rule) |
+| `prs_json` | If `create_prs=true`, list of created/updated PRs |
+
+### Example: bucketize only (matrix + patches)
+
+```yaml
+- name: Bucketize (patches + matrix)
+  id: split
+  uses: anatoliisf/split-by-codeowners@v1
+  with:
+    create_prs: "false"
+
+- name: Use matrix
+  run: echo '${{ steps.split.outputs.matrix_json }}'
+```
+
+### Required permissions (when `create_prs=true`)
+
+At minimum:
+
+```yaml
+permissions:
+  contents: write
+  pull-requests: write
+```
+
+## CLI
+
+The CLI operates on your **current working tree** (modified + untracked files) and groups them by CODEOWNERS.
+
+### Usage
+
+```bash
+npx split-by-codeowners --help
+```
+
+### Common examples
+
+Exclude some paths:
+
+```bash
+npx split-by-codeowners --exclude - < excludes.txt
+```
+
+Create/update PRs:
+
+```bash
+npx split-by-codeowners --create-prs --base-branch main
+```
+
+Force token auth locally (instead of `gh`):
+
+```bash
+export GH_TOKEN=...
+npx split-by-codeowners --create-prs --token "$GH_TOKEN" --base-branch main
+```
+
+### Notes on local PR creation
+
+- Locally (no `GITHUB_ACTIONS`), the tool **prefers `gh`** for PR creation.
+- In GitHub Actions (`GITHUB_ACTIONS=true`), the tool **requires a token** and uses API auth.
+
+## How it buckets files
+
+- Uses CODEOWNERS **last matching rule wins** for each file.
+- Bucket key is the sorted owners list (normalized) or `unowned_bucket_key`.
+
+## Troubleshooting
+
+### “Permission denied to github-actions[bot]”
+
+Ensure workflow permissions include:
+
+- `contents: write`
+- `pull-requests: write`
+
+### “Too many buckets”
+
+Raise `max_buckets` or add `exclude_patterns` to avoid noisy files (lockfiles, snapshots, etc.).
+
+## Development
+
+Build bundles (committed `dist/` is required for Marketplace Actions):
+
+```bash
+npm ci
+npm run build
+```
+
+## Maintainers
+
+### Publish CLI to npm (manual)
+
+This repo includes a manual workflow: `.github/workflows/publish-npm.yml`.
+
+- Create an npm token with publish rights and add it as repo secret **`NPM_TOKEN`**.
+- Bump `package.json` version and ensure `dist/` and `dist-cli/` are up to date.
+- Run the workflow from the GitHub Actions UI (`workflow_dispatch`).

package/action.yml

@@ -0,0 +1,109 @@
+name: "Split changes by CODEOWNERS (bucketize + patches)"
+description: "Bucketizes local git changes by effective CODEOWNERS and can optionally create one PR per bucket (no third-party PR actions)."
+author: "anatoliisf"
+branding:
+  icon: "shuffle"
+  color: "blue"
+
+inputs:
+  codeowners_path:
+    description: "Path to CODEOWNERS. Defaults to CODEOWNERS at repo root."
+    required: false
+    default: "CODEOWNERS"
+
+  base_ref:
+    description: "Optional base ref for changed files discovery. If empty, uses HEAD vs working tree."
+    required: false
+    default: ""
+
+  include_unowned:
+    description: "Include files with no owners in a special bucket"
+    required: false
+    default: "true"
+
+  unowned_bucket_key:
+    description: "Bucket key for unowned files"
+    required: false
+    default: "__UNOWNED__"
+
+  max_buckets:
+    description: "Fail if buckets exceed this number"
+    required: false
+    default: "30"
+
+  exclude_patterns:
+    description: "Newline-separated glob patterns to exclude"
+    required: false
+    default: ""
+
+  patch_dir:
+    description: "Directory to write patches"
+    required: false
+    default: "bucket-patches"
+
+  bucket_prefix:
+    description: "Patch file prefix"
+    required: false
+    default: "bucket"
+
+  dry_run:
+    description: "Compute buckets but don't write patches"
+    required: false
+    default: "false"
+
+  cleanup_patches:
+    description: "If true, delete patch_dir after successful run (useful when create_prs=true)."
+    required: false
+    default: "false"
+
+  create_prs:
+    description: "If true, create/update one PR per bucket by pushing branches and calling GitHub API."
+    required: false
+    default: "false"
+
+  github_token:
+    description: "GitHub token used for API + pushing branches. Defaults to GITHUB_TOKEN."
+    required: false
+    default: ""
+
+  base_branch:
+    description: "Base branch to open PRs against. If empty, uses repo default branch."
+    required: false
+    default: ""
+
+  branch_prefix:
+    description: "Prefix for created branches."
+    required: false
+    default: "codemods/"
+
+  commit_message:
+    description: "Commit message used in bucket PRs."
+    required: false
+    default: "chore: automated changes"
+
+  pr_title:
+    description: "PR title template. Supports {owners} and {bucket_key}."
+    required: false
+    default: "chore: automated changes ({owners})"
+
+  pr_body:
+    description: "PR body template. Supports {owners}, {bucket_key}, {files}."
+    required: false
+    default: "Automated changes bucketed by CODEOWNERS.\n\nOwners: {owners}\nBucket key: {bucket_key}\n\nFiles:\n{files}\n"
+
+  draft:
+    description: "Create PRs as drafts."
+    required: false
+    default: "false"
+
+outputs:
+  matrix_json:
+    description: "JSON for strategy.matrix (one bucket per job)"
+  buckets_json:
+    description: "Full buckets JSON"
+  prs_json:
+    description: "If create_prs=true, JSON list of created/updated PRs (url + number + bucket_key)."
+
+runs:
+  using: "node20"
+  main: "dist/index.js"