skills and formatting

Author: ecraig12345

.claude/shared/rust-and-go.md

@@ -0,0 +1,51 @@
+<!-- This is referenced from the rust and go skills -->
+
+## Rust and Go Implementation Guidelines
+
+The `rust/` and `go/` directories contain parallel re-implementations of beachball's `check` and `change` commands and the corresponding tests.
+
+### Scope
+
+Implemented:
+
+- CLI args (as relevant for supported commands)
+- JSON config loading (`.beachballrc.json` and `package.json` `"beachball"` field)
+- workspaces detection (npm, yarn, pnpm, rush, lerna)
+- `getChangedPackages` (git diff + file-to-package mapping + change file dedup)
+- `validate()` (minus `bumpInMemory`/dependency validation)
+- non-interactive `change` command (`--type` + `--message`)
+- `check` command.
+
+Not implemented:
+
+- JS config files
+- interactive prompts
+- all bumping and publishing operations
+- sync
+
+### Implementation requirements
+
+The behavior, log messages, and tests as specified in the TypeScript code MUST BE MATCHED in the Go/Rust code.
+
+- Do not change behavior or logs or remove tests, unless it's exclusively related to features which you've been asked not to implement yet.
+- If a different pattern would be more idiomatic in the target language, or it's not possible to implement the exact same behavior in the target language, ask the user before changing anything.
+- Don't make assumptions about the implementation of functions from `workspace-tools`. Check the JS implementation in `node_modules` and exactly follow that.
+
+When porting tests, add a comment by each Rust/Go test with the name of the corresponding TS test. If any TS tests have been omitted or combined, add a comment indicating which tests and why.
+
+Use syntax and helpers from the newest version of the language where it makes sense. If a particular scenario is most commonly handled in this language by some external library, and the library would meaningfully simplify the code, ask the user about adding the library as a dependency.
+
+After making changes, run the commands to build, test, lint, and format.
+
+### Key Implementation Details
+
+**Git commands**: Both shell out to `git` (matching the TS approach via workspace-tools). The git flags used should exactly match the workspace-tools code. Three-dot range (`branch...`) is used for diffs.
+
+**Config loading**: Searches `.beachballrc.json` then `package.json` `"beachball"` field, walking up from cwd but stopping at git root.
+
+**Glob matching**: Two modes matching the TS behavior — `matchBase` (patterns without `/` match basename) for `ignorePatterns`, full path matching for `scope`/`groups`.
+
+### Known Gotchas
+
+- **macOS `/tmp` symlink**: `/tmp` is a symlink to `/private/tmp`. `git rev-parse --show-toplevel` resolves symlinks but `tempfile`/`os.MkdirTemp` does not. Both implementations canonicalize paths (`std::fs::canonicalize` in Rust, `filepath.EvalSymlinks` in Go) when comparing git-returned paths with filesystem paths.
+- **Default branch name**: Modern git defaults to `main`. Test fixtures use `--initial-branch=master` for bare repo init to match the `origin/master` refs used in tests.

.claude/skills/go-impl.md

@@ -0,0 +1,11 @@
+---
+name: go-impl
+description: |
+  Go implementation guide for beachball's Go port.
+  TRIGGER when: user asks to edit, write, test, or debug Go code under the go/ directory, or opens/references go/*.go files.
+  DO NOT TRIGGER when: working only with TypeScript or Rust code.
+---
+
+!`cat go/README.md`
+
+!`cat .claude/skills/rust-and-go.md`

.claude/skills/rust-impl.md

@@ -0,0 +1,11 @@
+---
+name: rust-impl
+description: |
+  Rust implementation guide for beachball's Rust port.
+  TRIGGER when: user asks to edit, write, test, or debug Rust code under the rust/ directory, or opens/references rust/*.rs files.
+  DO NOT TRIGGER when: working only with TypeScript or Go code.
+---
+
+!`cat rust/README.md`
+
+!`cat .claude/skills/rust-and-go.md`

.github/workflows/pr.yml

@@ -120,14 +120,14 @@ jobs:
         working-directory: ./rust
         if: ${{ matrix.os == 'ubuntu-latest' }}
 
-      - name: Lint
-        run: cargo clippy --all-targets -- -D warnings
-        working-directory: ./rust
-
       - name: Build
         run: cargo build
         working-directory: ./rust
 
+      - name: Lint
+        run: cargo clippy --all-targets -- -D warnings
+        working-directory: ./rust
+
       - name: Test
         run: cargo test
         working-directory: ./rust
@@ -162,14 +162,14 @@ jobs:
         working-directory: ./go
         if: ${{ matrix.os == 'ubuntu-latest' }}
 
-      - name: Lint
-        run: go vet ./...
-        working-directory: ./go
-
       - name: Build
         run: go build ./...
         working-directory: ./go
 
+      - name: Lint
+        run: go vet ./...
+        working-directory: ./go
+
       - name: Test
         run: go test ./...
         working-directory: ./go

.gitignore

@@ -9,6 +9,7 @@ package-lock.json
 # ignore when switching between yarn 1/4 branches
 /.yarn
 rust/target
+go/beachball
 .claude/settings.local.json
 
 docs/.vuepress/.cache

.prettierignore

@@ -16,5 +16,7 @@ LICENSE
 node_modules/
 SECURITY.md
 yarn.lock
-rust/
-go/
+rust/**
+!rust/README.md
+go/**
+!go/README.md

CLAUDE.md

@@ -87,15 +87,13 @@ Multi-pass algorithm that calculates version bumps. See comments in file.
 
 - Change files stored in `change/` directory track intended version changes
 - See `src/types/ChangeInfo.ts` `ChangeFileInfo` for the info stored in each change file. For grouped change files (config has `groupChanges: true`), the type will be `ChangeInfoMultiple`.
-- `readChangeFiles()` - Loads and validates from disk
-- `writeChangeFiles()` - Persists new change files
-- `unlinkChangeFiles()` - Deletes after consumption during bump
+- Folder contains helper to read, write, and unlink change files
 
 **Publishing** (`src/publish/`):
 
 - `publishToRegistry()` - Validates, applies publishConfig, runs hooks, publishes (respects dependency order)
 - `bumpAndPush()` - Git operations: creates temp `publish_*` branch, fetches, merges, bumps, commits, tags, pushes
-- Pre/post hooks available: `prebump`, `postbump`, `prepublish`, `postpublish`, `precommit`
+- Pre/post hooks available (see `HooksOptions` in `src/types/BeachballOptions.ts`)
 
 **Context Passing:**
 `CommandContext` aggregates reusable data (packages, version groups, change files, and more) to avoid repeated calculations. See source in `src/types/CommandContext.ts`.
@@ -143,7 +141,7 @@ Multi-pass algorithm that calculates version bumps. See comments in file.
 
 **Testing Structure:**
 
-- Fixtures: `__fixtures__` directory
+- Fixtures and helpers: `__fixtures__/` directory
 - Unit tests: `__tests__/` directory
 - Functional tests: `__functional__/` directory
 - E2E tests: `__e2e__/` directory
@@ -164,69 +162,4 @@ Multi-pass algorithm that calculates version bumps. See comments in file.
 
 ## Experimental: Rust and Go Implementations
 
-The `rust/` and `go/` directories contain parallel re-implementations of beachball's `check` and `change` commands and the corresponding tests.
-
-### Building and Testing
-
-```bash
-# Rust (from rust/ directory)
-cargo build
-cargo test
-
-# Go (from go/ directory)
-go build ./...
-go test ./...
-```
-
-### Scope
-
-Both implement:
-
-- CLI args (as relevant for supported commands)
-- JSON config loading (`.beachballrc.json` and `package.json` `"beachball"` field)
-- workspaces detection (npm, yarn, pnpm, rush, lerna)
-- `getChangedPackages` (git diff + file-to-package mapping + change file dedup)
-- `validate()` (minus `bumpInMemory`/dependency validation)
-- non-interactive `change` command (`--type` + `--message`)
-- `check` command.
-
-Not implemented:
-
-- JS config files
-- interactive prompts
-- all bumping and publishing operations
-- sync
-
-### Implementation requirements
-
-The behavior, log messages, and tests as specified in the TypeScript code MUST BE MATCHED in the Go/Rust code.
-
-- Do not change behavior or logs or remove tests, unless it's exclusively related to features which you've been asked not to implement yet.
-- If a different pattern would be more idiomatic in the target language, or it's not possible to implement the exact same behavior in the target language, ask the user before changing anything.
-- Don't make assumptions about the implementation of functions from `workspace-tools`. Check the JS implementation in `node_modules` and exactly follow that.
-
-When porting tests, add a comment by each Rust/Go test with the name of the corresponding TS test. If any TS tests have been omitted or combined, add a comment indicating which tests and why.
-
-Use syntax and helpers from the newest version of the language where it makes sense. If a particular scenario is most commonly handled in this language by some external library, and the library would meaningfully simplify the code, ask the user about adding the library as a dependency.
-
-Where possible, use the LSP instead of grep to understand the code. Also use the LSP to check for errors after making changes.
-
-After making changes, run the commands to build, test, lint, and format.
-
-### Structure
-
-- **Rust**: `src/` with nested modules, integration tests in `tests/` with shared helpers in `tests/common/`
-- **Go**: `cmd/beachball/` CLI entry, `internal/` packages, test helpers in `internal/testutil/`, tests alongside source (`_test.go`)
-
-### Key Implementation Details
-
-**Git commands**: Both shell out to `git` (matching the TS approach via workspace-tools). The git flags used should exactly match the workspace-tools code. Three-dot range (`branch...`) is used for diffs.
-
-**Config loading**: Searches `.beachballrc.json` then `package.json` `"beachball"` field, walking up from cwd but stopping at git root.
-
-**Glob matching**: Two modes matching the TS behavior — `matchBase` (patterns without `/` match basename) for `ignorePatterns`, full path matching for `scope`/`groups`.
-
-### Known Gotchas
-
-- **macOS `/tmp` symlink**: `/tmp` is a symlink to `/private/tmp`. `git rev-parse --show-toplevel` resolves symlinks but `tempfile`/`os.MkdirTemp` does not. Both implementations canonicalize paths (`std::fs::canonicalize` in Rust, `filepath.EvalSymlinks` in Go) when comparing git-returned paths with filesystem paths.
-- **Default branch name**: Modern git defaults to `main`. Test fixtures use `--initial-branch=master` for bare repo init to match the `origin/master` refs used in tests.
+The `rust/` and `go/` directories contain experimental parallel re-implementations. See the `go-impl` and `rust-impl` custom skills as relevant.

go/README.md

@@ -2,9 +2,11 @@
 
 A Go re-implementation of beachball's `check` and `change` commands.
 
+<!-- See .claude/shared/rust-and-go.md for details of what's implemented or not -->
+
 ## Prerequisites
 
-- Go 1.23+
+- Go 1.26+
 - `git` on PATH
 
 ## Building
@@ -68,81 +70,23 @@ Or after building:
 
 ## CLI Options
 
-```
-beachball check [flags]
-beachball change [flags]
-
-Flags:
-  -b, --branch string       Target branch (default: origin/master)
-      --path string          Path to the repository
-  -t, --type string          Change type: patch, minor, major, none, etc.
-  -m, --message string       Change description
-      --all                  Include all packages
-      --verbose              Verbose output
-      --config-path string   Path to beachball config
-```
-
-## What's Implemented
-
-- CLI parsing (cobra)
-- JSON config loading (`.beachballrc.json`, `package.json` `"beachball"` field)
-- Workspace detection (npm/yarn `workspaces` field)
-- `getChangedPackages` (git diff + file-to-package mapping + change file dedup)
-- `validate()` (minus `bumpInMemory`/dependency validation)
-- Non-interactive `change` command (`--type` + `--message`)
-- `check` command
-
-## What's Not Implemented
-
-- JS config files (`beachball.config.js`)
-- Interactive prompts
-- `bumpInMemory` / dependency validation
-- `publish`, `bump`, `canary`, `sync` commands
-- Changelog generation
-- pnpm/rush/lerna workspace detection
+Currently the `check` command and non-interactive `change` command have been implemented. Options should be the same as JS Beachball.
 
 ## Project Structure
 
+Tests (`*_test.go`) live alongside the corresponding files.
+
 ```
 cmd/beachball/
-  main.go                        # CLI entry point (cobra)
+  main.go       # CLI entry point (cobra)
 internal/
-  types/
-    change_info.go               # ChangeType, ChangeFileInfo, ChangeSet
-    package_info.go              # PackageJson, PackageInfo, PackageGroups
-    options.go                   # BeachballOptions, CliOptions
-  options/
-    get_options.go               # Option merging
-    repo_options.go              # Config file loading
-  git/
-    commands.go                  # Git operations (shell out to git)
-    helpers.go                   # File/workspace helpers
-    ensure_shared_history.go     # Fetch/deepen for shallow clones
-  monorepo/
-    package_infos.go             # Package discovery
-    scoped_packages.go           # Scope filtering
-    package_groups.go            # Version group resolution
-    filter_ignored.go            # Ignore pattern matching
-  changefile/
-    changed_packages.go          # Changed package detection
-    changed_packages_test.go     # 11 tests
-    read_change_files.go         # Read change files from disk
-    write_change_files.go        # Write change files
-    change_types.go              # Disallowed type resolution
-  validation/
-    validate.go                  # Main validation logic
-    validate_test.go             # 3 tests
-    validators.go                # Type/auth validators
-    are_change_files_deleted.go  # Deleted change file detection
-  commands/
-    check.go                     # Check command
-    change.go                    # Change command
-    change_test.go               # 2 tests
-  logging/
-    logging.go                   # Output helpers
-  testutil/
-    repository.go                # Test git repo wrapper
-    repository_factory.go        # Bare repo + clone factory
-    fixtures.go                  # Fixture setup helpers
-    change_files.go              # Test change file helpers
+  types/        # Basic types
+  options/      # Option merging, config file loading
+  git/          # Git operations (shell out to git)
+  monorepo/     # Package discovery, groups, filtering
+  changefile/   # Change file handling, changed package detection
+  validation/   # Validation
+  commands/     # Main commands
+  logging/      # Output helpers
+  testutil/     # Test helpers
 ```