Release: rename package to docs-coderef

[cawpea]

No description provided.

[github-actions]

Pull Request Review: Package Rename to docs-coderef

Overview

This PR renames the package from @cawpea/coderef to docs-coderef, removing the npm scope. This is a major breaking change that affects the CLI command, configuration files, and environment variables.

---

✅ Positive Aspects

1. Comprehensive and Consistent Renaming

The renaming has been applied systematically across all relevant areas:

• Package name and bin command
• Configuration files (.coderefrc.json → .docs-coderefrc.json)
• Environment variables (CODEREF_* → DOCS_CODEREF_*)
• All documentation files
• Test files
• CHANGELOG.md appropriately updated

2. Test Coverage

All test files have been updated to reflect the new naming:

• src/config.test.ts properly updated with new config file and env var names
• scripts/lib/path-checker.test.ts updated for new bin file name

3. Documentation Quality

• CHANGELOG.md clearly documents all breaking changes
• All user-facing documentation updated (README, CLI usage, configuration docs)
• Good migration guidance provided in CHANGELOG

4. Version Management

• Version correctly reset to 0.1.0 (appropriate for pre-1.0 breaking change)
• publishConfig.access removed (correct since it's no longer a scoped package)

---

⚠️ Issues & Concerns

1. Critical: Missing Migration Guide (High Priority)

Issue: While the CHANGELOG lists the changes, there's no dedicated migration guide for existing users.

Recommendation: Add a MIGRATION.md or a "Migrating from @cawpea/coderef" section to the README with:

• Step-by-step migration instructions
• Script or commands to help users migrate
• Example of before/after configurations

2. Commit Message Convention Violation (Medium Priority)

Issue: Based on the git conventions (docs/development/git-conventions.md), this should use a conventional commit type.

Expected format:

chore!: rename package to docs-coderef

BREAKING CHANGE: Package renamed from @cawpea/coderef to docs-coderef
- CLI command: coderef → docs-coderef
- Config file: .coderefrc.json → .docs-coderefrc.json
- Env vars: CODEREF_* → DOCS_CODEREF_*

Current: "Release: rename package to docs-coderef" doesn't follow the conventional commits format.

3. Documentation Inconsistency (Low Priority)

File: docs/development/release.md:240

- For scoped packages (e.g., `@company/package-name`), verify `publishConfig.access: "public"` is set

This comment was added as a generic example, but given the context of this PR (removing scope), it might confuse readers. Consider clarifying this is for hypothetical scoped packages only.

4. Potential Breaking Change Documentation (Medium Priority)

File: CHANGELOG.md

The CHANGELOG shows "Unreleased" section but the changes are quite substantial. Consider:

• Creating a proper version tag (e.g., 2.0.0 if this was already released, or keep as 0.1.0 for initial release)
• Adding a clear "BREAKING CHANGES" section at the top
• Including information about deprecation of the old package name

5. Package.json Scripts Not Updated (Low Priority)

The docs:validate script and other npm scripts don't reference the CLI directly, but future scripts might. Verify all scripts work with the new package name.

---

🔒 Security Review

✅ No security concerns identified

• No changes to core validation/parsing logic
• No new dependencies added
• No executable code changes beyond renaming

---

🎯 Testing Recommendations

Manual Testing Checklist:

1. ✅ Install package and verify CLI command works: npx docs-coderef validate
2. ✅ Test config file loading with .docs-coderefrc.json
3. ✅ Test environment variables with DOCS_CODEREF_* prefix
4. ✅ Test package.json "docs-coderef" field configuration
5. ✅ Verify programmatic API imports: import { validate } from 'docs-coderef'
6. ⚠️ Missing: Integration test for the complete rename

Recommendation: Add an integration test that:

• Installs the package fresh
• Runs all CLI commands
• Validates configuration loading from all sources

---

📋 Code Quality Assessment

Adherence to Coding Standards

✅ Compliant with CLAUDE.md standards:

• Indentation: 2 spaces maintained
• Quotes: Single quotes used
• Line endings: Consistent
• No code style changes, only string replacements

TypeScript & Type Safety

✅ No issues: All type definitions remain intact

---

🎨 Style & Consistency

Minor suggestion: The bin file rename (bin/coderef.js → bin/docs-coderef.js) is correct, but the shebang and file structure are maintained properly. ✅

---

📊 Performance & Maintainability

✅ No performance impact: This is purely a renaming change with no algorithmic modifications.
✅ Maintainability: Clean, consistent renaming makes the codebase easier to understand.

---

🎓 Recommendations Summary

Must Fix:

1. Update commit message to follow Conventional Commits format
2. Add migration guide for existing users

Should Fix:

3. Clarify CHANGELOG versioning (Unreleased vs 0.1.0 vs 2.0.0)
4. Add integration test for package installation

Nice to Have:

5. Consider publishing a deprecation notice for @cawpea/coderef on npm (if it was previously published)
6. Add a redirect or notice in the old repository if the GitHub repo was also renamed

---

✅ Final Verdict

Status: ✅ Approve with minor changes recommended

This is a well-executed package rename with comprehensive coverage across the codebase. The main concerns are around documentation (migration guide) and commit message format rather than code quality or functionality.

Suggested Next Steps:

1. Add MIGRATION.md with clear migration instructions
2. Update commit message to follow conventional commits
3. Consider whether this should be versioned as 0.1.0 (new project) or 2.0.0 (breaking change)
4. Merge after addressing documentation concerns

Risk Level: Low (renaming is comprehensive and tests are updated)

---

Great work on the thoroughness of this refactor! The systematic approach to renaming across all files and documentation is commendable. 👏

[github-actions]

🎉 This PR is included in version 1.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version 0.2.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀