ailabs/puaros
1
0
Fork 0
mirror of https://github.com/samiyev/puaros.git synced 2025-12-27 23:06:54 +05:00
Code Issues Packages Projects Releases Wiki Activity

docs: add monorepo versioning strategy and release pipeline

Browse Source 
- add Path Reference section with explicit paths
- add Monorepo Versioning Strategy with prefixed tags
- add 6-phase Release Pipeline documentation
- update Git Commit Format for monorepo (package scope)
- update .gitmessage with package scopes
- fix tsconfig.json references (remove non-existent, add ipuaro)
- fix guardian tsconfig formatting (4-space indent)
This commit is contained in:
imfozilbek
2025-11-29 22:41:03 +05:00
parent daace23814
commit 7f6180df37
4 changed files with 240 additions and 188 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
.gitmessage
View File

@@ -1,9 +1,17 @@
# <type>: <subject> # <type>(<package>): <subject>
# #
# <body> # <body>
# #
# <footer> # <footer>
# Format:
# - Package changes: <type>(<package>): <subject>
# Examples: feat(guardian): add detector
# fix(ipuaro): resolve memory leak
# - Root changes: <type>: <subject>
# Examples: chore: update eslint config
# docs: update root README
# Type should be one of the following: # Type should be one of the following:
# * feat: A new feature # * feat: A new feature
# * fix: A bug fix # * fix: A bug fix
@@ -16,6 +24,11 @@
# * ci: Changes to CI configuration files and scripts # * ci: Changes to CI configuration files and scripts
# * chore: Other changes that don't modify src or test files # * chore: Other changes that don't modify src or test files
# * revert: Reverts a previous commit # * revert: Reverts a previous commit
# Package scopes:
# * guardian - @puaros/guardian package
# * ipuaro - @puaros/ipuaro package
# * (none) - root-level changes
# #
# Subject line rules: # Subject line rules:
# - Use imperative mood ("add feature" not "added feature") # - Use imperative mood ("add feature" not "added feature")

358
CLAUDE.md
View File

@@ -12,6 +12,46 @@ Puaros is a TypeScript monorepo using pnpm workspaces. Contains two packages:
The project uses Node.js 22.18.0 (see `.nvmrc`). The project uses Node.js 22.18.0 (see `.nvmrc`).
## Path Reference
**Root:** `/Users/fozilbeksamiyev/projects/ailabs/puaros`
### Key Paths
| Description | Path |
|-------------|------|
| **Root** | `.` |
| **Guardian package** | `packages/guardian` |
| **Guardian src** | `packages/guardian/src` |
| **Guardian tests** | `packages/guardian/tests` |
| **Guardian CLI** | `packages/guardian/src/cli` |
| **Guardian domain** | `packages/guardian/src/domain` |
| **Guardian infrastructure** | `packages/guardian/src/infrastructure` |
| **ipuaro package** | `packages/ipuaro` |
| **ipuaro docs** | `packages/ipuaro/docs` |
### File Locations
| File | Location |
|------|----------|
| Root package.json | `./package.json` |
| Guardian package.json | `packages/guardian/package.json` |
| Guardian tsconfig | `packages/guardian/tsconfig.json` |
| Guardian TODO | `packages/guardian/TODO.md` |
| Guardian CHANGELOG | `packages/guardian/CHANGELOG.md` |
| ipuaro ROADMAP | `packages/ipuaro/ROADMAP.md` |
| ESLint config | `./eslint.config.mjs` |
| Prettier config | `./.prettierrc` |
| Base tsconfig | `./tsconfig.base.json` |
### Path Rules
1. **Always use relative paths from project root** (not absolute)
2. **Package paths start with** `packages/<name>/`
3. **Source code is in** `packages/<name>/src/`
4. **Tests are in** `packages/<name>/tests/`
5. **Docs are in** `packages/<name>/docs/` or `./docs/`
## Essential Commands ## Essential Commands
### Build & Development ### Build & Development
@@ -106,10 +146,24 @@ From `eslint.config.mjs` and detailed in `LINTING.md`:
Follow Conventional Commits format. See `.gitmessage` for full rules. Follow Conventional Commits format. See `.gitmessage` for full rules.
Format: `<type>: <subject>` (imperative mood, no caps, max 50 chars) **Monorepo format:** `<type>(<package>): <subject>`
**IMPORTANT: Do NOT add "Generated with Claude Code" footer or "Co-Authored-By: Claude" to commit messages.** Examples:
Commits should only follow the Conventional Commits format without any additional attribution. - `feat(guardian): add circular dependency detector`
- `fix(ipuaro): resolve memory leak in indexer`
- `docs(guardian): update CLI usage examples`
- `refactor(ipuaro): extract tool registry`
**Root-level changes:** `<type>: <subject>` (no scope)
- `chore: update eslint config`
- `docs: update root README`
**Types:** feat, fix, docs, style, refactor, test, chore
**Rules:**
- Imperative mood, no caps, max 50 chars
- Do NOT add "Generated with Claude Code" footer
- Do NOT add "Co-Authored-By: Claude"
## Monorepo Structure ## Monorepo Structure
@@ -238,232 +292,222 @@ Guardian package (`packages/guardian/tsconfig.json`):
- `@vitest/ui` - Interactive testing UI - `@vitest/ui` - Interactive testing UI
- `@vitest/coverage-v8` - Coverage reporting - `@vitest/coverage-v8` - Coverage reporting
## Development Workflow ## Monorepo Versioning Strategy
### Complete Feature Development & Release Workflow ### Git Tag Format
This workflow ensures high quality and consistency from feature implementation to package publication. **Prefixed tags for each package:**
```
#### Phase 1: Feature Planning & Implementation guardian-v0.5.0
ipuaro-v0.1.0
```bash
# 1. Create feature branch (if needed)
git checkout -b feature/your-feature-name
# 2. Implement feature following Clean Architecture
# - Add to appropriate layer (domain/application/infrastructure/cli)
# - Follow naming conventions
# - Keep functions small and focused
# 3. Update constants if adding CLI options
# Edit: packages/guardian/src/cli/constants.ts
``` ```
#### Phase 2: Quality Checks (Run After Implementation) **Why prefixed tags:**
- Independent versioning per package
- Clear release history for each package
- Works with npm publish and CI/CD
- Easy to filter: `git tag -l "guardian-*"`
**Legacy tags:** Tags before monorepo (v0.1.0, v0.2.0, etc.) are kept as-is for historical reference.
### Semantic Versioning
All packages follow SemVer: `MAJOR.MINOR.PATCH`
- **MAJOR** (1.0.0) - Breaking API changes
- **MINOR** (0.1.0) - New features, backwards compatible
- **PATCH** (0.0.1) - Bug fixes, backwards compatible
**Pre-1.0 policy:** Minor bumps (0.x.0) may include breaking changes.
## Release Pipeline
**Quick reference:** Say "run pipeline for [package]" to execute full release flow.
The pipeline has 6 phases. Each phase must pass before proceeding.
### Phase 1: Quality Gates
```bash ```bash
# Navigate to package cd packages/<package>
cd packages/guardian
# 1. Format code (REQUIRED - 4 spaces indentation) # All must pass:
pnpm format pnpm format # 4-space indentation
pnpm build # TypeScript compiles
# 2. Build to check compilation cd ../.. && pnpm eslint "packages/**/*.ts" --fix # 0 errors, 0 warnings
pnpm build cd packages/<package>
pnpm test:run # All tests pass
# 3. Run linter (must pass with 0 errors, 0 warnings) pnpm test:coverage # Coverage ≥80%
cd ../.. && pnpm eslint "packages/**/*.ts" --fix
# 4. Run tests (all must pass)
pnpm test:run
# 5. Check coverage (must be ≥80%)
pnpm test:coverage
``` ```
**Quality Gates:** ### Phase 2: Documentation
- ✅ Format: No changes after `pnpm format`
- ✅ Build: TypeScript compiles without errors
- ✅ Lint: 0 errors, 0 warnings
- ✅ Tests: All tests pass (292/292)
- ✅ Coverage: ≥80% on all metrics
#### Phase 3: Documentation Updates Update these files in `packages/<package>/`:
| File | Action |
|------|--------|
| `README.md` | Add feature docs, update CLI usage, update API |
| `TODO.md` | Mark completed tasks, add new tech debt if any |
| `CHANGELOG.md` | Add version entry with all changes |
| `ROADMAP.md` | Update if milestone completed |
**Tech debt rule:** If implementation leaves known issues, shortcuts, or future improvements needed — add them to TODO.md before committing.
### Phase 3: Manual Testing
```bash ```bash
# 1. Update README.md cd packages/<package>
# - Add new feature to Features section
# - Update CLI Usage examples if CLI changed
# - Update API documentation if public API changed
# - Update TypeScript interfaces
# 2. Update TODO.md # Test CLI/API manually
# - Mark completed tasks as done node dist/cli/index.js <command> ./examples
# - Add new technical debt if discovered
# - Document coverage issues for new files
# - Update "Recent Updates" section with changes
# 3. Update CHANGELOG.md (for releases) # Verify output, edge cases, error handling
# - Add entry with version number
# - List all changes (features, fixes, improvements)
# - Follow Keep a Changelog format
``` ```
#### Phase 4: Verification & Testing ### Phase 4: Commit
```bash ```bash
# 1. Test CLI manually with examples
cd packages/guardian
node dist/cli/index.js check ./examples --limit 5
# 2. Test new feature with different options
node dist/cli/index.js check ./examples --only-critical
node dist/cli/index.js check ./examples --min-severity high
# 3. Verify output formatting and messages
# - Check that all violations display correctly
# - Verify severity labels and suggestions
# - Test edge cases and error handling
# 4. Run full quality check suite
pnpm format && pnpm eslint "packages/**/*.ts" && pnpm build && pnpm test:run
```
#### Phase 5: Commit & Version
```bash
# 1. Stage changes
git add . git add .
git commit -m "<type>(<package>): <description>"
# 2. Commit with Conventional Commits format # Examples:
git commit -m "feat: add --limit option for output control" # feat(guardian): add --limit option
# or # fix(ipuaro): resolve memory leak in indexer
git commit -m "fix: resolve unused variable in detector" # docs(guardian): update API examples
# or
git commit -m "docs: update README with new features"
# Types: feat, fix, docs, style, refactor, test, chore
# 3. Update package version (if releasing)
cd packages/guardian
npm version patch # Bug fixes (0.5.2 → 0.5.3)
npm version minor # New features (0.5.2 → 0.6.0)
npm version major # Breaking changes (0.5.2 → 1.0.0)
# 4. Push changes
git push origin main # or your branch
git push --tags # Push version tags
``` ```
#### Phase 6: Publication (Maintainers Only) **Commit types:** feat, fix, docs, style, refactor, test, chore
### Phase 5: Version & Tag
```bash ```bash
# 1. Final verification before publish cd packages/<package>
cd packages/guardian
# Bump version
npm version patch # 0.5.2 → 0.5.3 (bug fix)
npm version minor # 0.5.2 → 0.6.0 (new feature)
npm version major # 0.5.2 → 1.0.0 (breaking change)
# Create prefixed git tag
git tag <package>-v<version>
# Example: git tag guardian-v0.6.0
# Push
git push origin main
git push origin <package>-v<version>
```
### Phase 6: Publish (Maintainers Only)
```bash
cd packages/<package>
# Final verification
pnpm build && pnpm test:run && pnpm test:coverage pnpm build && pnpm test:run && pnpm test:coverage
# 2. Verify package contents # Check package contents
npm pack --dry-run npm pack --dry-run
# 3. Publish to npm # Publish
npm publish --access public npm publish --access public
# 4. Verify publication # Verify
npm info @samiyev/guardian npm info @puaros/<package>
# 5. Test installation
npm install -g @samiyev/guardian@latest
guardian --version
``` ```
### Quick Checklist for New Features ## Pipeline Checklist
**Before Committing:** Copy and use for each release:
- [ ] Feature implemented in correct layer
- [ ] Code formatted with `pnpm format`
- [ ] Lint passes: `pnpm eslint "packages/**/*.ts"`
- [ ] Build succeeds: `pnpm build`
- [ ] All tests pass: `pnpm test:run`
- [ ] Coverage ≥80%: `pnpm test:coverage`
- [ ] CLI tested manually if CLI changed
- [ ] README.md updated with examples
- [ ] TODO.md updated with progress
- [ ] No `console.log` in production code
- [ ] TypeScript interfaces documented
**Before Publishing:** ```markdown
- [ ] CHANGELOG.md updated ## Release: <package> v<version>
### Quality Gates
- [ ] `pnpm format` - no changes
- [ ] `pnpm build` - compiles
- [ ] `pnpm eslint` - 0 errors, 0 warnings
- [ ] `pnpm test:run` - all pass
- [ ] `pnpm test:coverage` - ≥80%
### Documentation
- [ ] README.md updated
- [ ] TODO.md - completed tasks marked, new debt added
- [ ] CHANGELOG.md - version entry added
- [ ] ROADMAP.md updated (if needed)
### Testing
- [ ] CLI/API tested manually
- [ ] Edge cases verified
### Release
- [ ] Commit with conventional format
- [ ] Version bumped in package.json - [ ] Version bumped in package.json
- [ ] All quality gates pass - [ ] Git tag created: <package>-v<version>
- [ ] Examples work correctly - [ ] Pushed to origin
- [ ] Git tags pushed - [ ] Published to npm (if public release)
```
### Common Workflows ## Common Workflows
### Adding a new CLI option
**Adding a new CLI option:**
```bash ```bash
# 1. Add to cli/constants.ts (CLI_OPTIONS, CLI_DESCRIPTIONS) # 1. Add to cli/constants.ts (CLI_OPTIONS, CLI_DESCRIPTIONS)
# 2. Add option in cli/index.ts (.option() call) # 2. Add option in cli/index.ts (.option() call)
# 3. Parse and use option in action handler # 3. Parse and use option in action handler
# 4. Test with: node dist/cli/index.js check ./examples --your-option # 4. Test: node dist/cli/index.js <command> --your-option
# 5. Update README.md CLI Usage section # 5. Run pipeline
# 6. Run quality checks
``` ```
**Adding a new detector:** ### Adding a new detector (guardian)
```bash ```bash
# 1. Create value object in domain/value-objects/ # 1. Create value object in domain/value-objects/
# 2. Create detector in infrastructure/analyzers/ # 2. Create detector in infrastructure/analyzers/
# 3. Add detector interface to domain/services/ # 3. Add interface to domain/services/
# 4. Integrate in application/use-cases/AnalyzeProject.ts # 4. Integrate in application/use-cases/AnalyzeProject.ts
# 5. Add CLI output in cli/index.ts # 5. Add CLI output in cli/index.ts
# 6. Write tests (aim for >90% coverage) # 6. Write tests (aim for >90% coverage)
# 7. Update README.md Features section # 7. Run pipeline
# 8. Run full quality suite
``` ```
**Fixing technical debt:** ### Adding a new tool (ipuaro)
```bash
# 1. Define tool schema in infrastructure/tools/schemas/
# 2. Implement tool in infrastructure/tools/
# 3. Register in infrastructure/tools/index.ts
# 4. Add tests
# 5. Run pipeline
```
### Fixing technical debt
```bash ```bash
# 1. Find issue in TODO.md # 1. Find issue in TODO.md
# 2. Implement fix # 2. Implement fix
# 3. Run quality checks # 3. Update TODO.md (mark as completed)
# 4. Update TODO.md (mark as completed) # 4. Run pipeline with type: "refactor:" or "fix:"
# 5. Commit with type: "refactor:" or "fix:"
``` ```
### Debugging Tips ## Debugging Tips
**Build errors:** **Build errors:**
```bash ```bash
# Check TypeScript errors in detail
pnpm tsc --noEmit pnpm tsc --noEmit
pnpm tsc --noEmit packages/<package>/src/path/to/file.ts
# Check specific file
pnpm tsc --noEmit packages/guardian/src/path/to/file.ts
``` ```
**Test failures:** **Test failures:**
```bash ```bash
# Run single test file
pnpm vitest tests/path/to/test.test.ts pnpm vitest tests/path/to/test.test.ts
# Run tests with UI
pnpm test:ui pnpm test:ui
# Run tests in watch mode for debugging
pnpm test
``` ```
**Coverage issues:** **Coverage issues:**
```bash ```bash
# Generate detailed coverage report
pnpm test:coverage pnpm test:coverage
# View HTML report
open coverage/index.html open coverage/index.html
# Check specific file coverage
pnpm vitest --coverage --reporter=verbose
``` ```
## Important Notes ## Important Notes

11
packages/guardian/tsconfig.json
View File

@@ -14,6 +14,13 @@
"sourceMap": true, "sourceMap": true,
"resolveJsonModule": true "resolveJsonModule": true
}, },
"include": ["src/**/*"], "include": [
"exclude": ["node_modules", "dist", "**/*.spec.ts", "**/*.test.ts"] "src/**/*"
],
"exclude": [
"node_modules",
"dist",
"**/*.spec.ts",
"**/*.test.ts"
]
} }

14
tsconfig.json
View File

@@ -9,19 +9,7 @@
"path": "./packages/guardian" "path": "./packages/guardian"
}, },
{ {
"path": "./packages/server" "path": "./packages/ipuaro"
},
{
"path": "./packages/cli"
},
{
"path": "./packages/sdk"
},
{
"path": "./packages/mcp"
},
{
"path": "./packages/vscode"
} }
], ],
"files": [] "files": []