@el-j/magic-helix-plugins 4.0.0-beta.1 → 4.0.0-beta.3

package/dist/architecture/codeowners.md

@@ -0,0 +1,123 @@
+# CODEOWNERS Guidelines
+
+## Overview
+This project uses CODEOWNERS file to define code ownership and automate review requests.
+
+## File Location
+- `.github/CODEOWNERS` (recommended)
+- `CODEOWNERS` (root)
+- `docs/CODEOWNERS`
+
+## Syntax
+```
+# Comments start with #
+# Each line: pattern followed by owners
+
+# Default owners for everything
+* @org/default-team
+
+# Specific directories
+/docs/ @org/docs-team @user1
+/src/api/ @org/backend-team
+/src/ui/ @org/frontend-team
+
+# Specific files
+package.json @org/platform-team
+Dockerfile @org/devops-team
+
+# Wildcards
+*.md @org/docs-team
+**/*.test.ts @org/qa-team
+
+# Multiple owners
+/src/auth/ @org/security-team @org/backend-team
+```
+
+## Pattern Matching
+- `*`: Matches any files
+- `**`: Matches directories recursively
+- `?`: Matches single character
+- `[abc]`: Matches a, b, or c
+- Last matching pattern takes precedence
+
+## Owner Types
+- Individual users: `@username`
+- Teams: `@org/team-name`
+- Email addresses: `user@example.com`
+
+## Best Practices
+- Define default owners at the top
+- Be specific with critical paths
+- Assign multiple owners for coverage
+- Keep teams small and focused
+- Document ownership rationale
+- Review and update regularly
+
+## Review Requirements
+- Owners are automatically requested for reviews
+- Can require approval from code owners (branch protection)
+- Blocks merge without owner approval
+
+## Responsibilities
+- Code owners should:
+  - Review PRs affecting their code
+  - Maintain code quality
+  - Update documentation
+  - Mentor contributors
+  - Keep ownership updated
+
+## Common Patterns
+```
+# Backend API
+/src/api/**/*.ts @org/backend-team
+
+# Frontend Components
+/src/components/**/*.tsx @org/frontend-team
+
+# Infrastructure
+/infrastructure/ @org/devops-team
+/.github/workflows/ @org/devops-team
+
+# Documentation
+/docs/ @org/docs-team
+*.md @org/docs-team
+
+# Configuration
+*.config.js @org/platform-team
+package.json @org/platform-team
+
+# Database
+/migrations/ @org/backend-team @org/dba-team
+
+# Security
+/src/auth/ @org/security-team
+```
+
+## Branch Protection
+- Enable "Require review from Code Owners"
+- Set minimum number of approvals
+- Dismiss stale reviews on push
+
+## Notifications
+- Owners receive review requests
+- Configure notification preferences
+- Use team mentions for broader awareness
+
+## Troubleshooting
+- Validate CODEOWNERS syntax
+- Check team membership
+- Verify file patterns match
+- Test with specific files
+
+## Integration
+- Works with pull requests
+- Integrates with branch protection
+- Appears in PR sidebar
+- Can be queried via API
+
+## Maintenance
+- Review quarterly
+- Update for new teams/members
+- Remove inactive owners
+- Refactor for restructuring
+- Document in team wiki

package/dist/architecture/monorepo.md

@@ -0,0 +1,146 @@
+# Monorepo Development Guidelines
+
+## Overview
+This project uses a monorepo structure to manage multiple packages/applications in a single repository.
+
+## Structure
+```
+project-root/
+├── packages/
+│   ├── package-a/
+│   ├── package-b/
+│   └── shared/
+├── apps/
+│   ├── web/
+│   └── mobile/
+├── package.json (workspace root)
+└── turbo.json or nx.json
+```
+
+## Workspace Commands
+- Install all dependencies: `npm install` (at root)
+- Run script in workspace: `npm run <script> --workspace=<package-name>`
+- Run script in all workspaces: `npm run <script> --workspaces`
+- Add dependency to workspace: `npm install <pkg> --workspace=<name>`
+
+## Benefits
+- Code sharing between packages
+- Atomic changes across multiple packages
+- Unified versioning and releases
+- Shared tooling and configuration
+- Single source of truth
+
+## Package Dependencies
+- Reference workspace packages: `"package-a": "*"` or `"workspace:*"`
+- Changes in dependencies trigger downstream rebuilds
+- Use semver for external dependencies
+
+## Build Orchestration
+- Define build order based on dependencies
+- Use `turbo` or `nx` for caching and parallelization
+- Run only affected packages on changes
+
+## Common Tools
+
+### Turborepo
+```json
+{
+  "pipeline": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**"]
+    },
+    "test": {
+      "dependsOn": ["build"]
+    }
+  }
+}
+```
+
+### Nx
+```json
+{
+  "tasksRunnerOptions": {
+    "default": {
+      "runner": "@nrwl/workspace/tasks-runners/default",
+      "options": {
+        "cacheableOperations": ["build", "test"]
+      }
+    }
+  }
+}
+```
+
+## Best Practices
+- Keep packages focused and small
+- Use consistent naming conventions
+- Share common configuration files
+- Version packages independently or together
+- Document package purposes in README
+- Use path mappings for imports
+- Hoist dependencies when possible
+
+## Scripts Management
+- Define common scripts at root
+- Delegate to workspace-specific scripts
+- Use parallel execution for independent tasks
+- Run affected packages only
+
+## Testing
+- Run tests from root: `npm test --workspaces`
+- Run tests for specific package: `npm test --workspace=<name>`
+- Use shared test configuration
+- Test cross-package integration
+
+## Versioning
+- **Independent**: Each package has own version
+- **Fixed**: All packages share same version
+- Use changesets for version management
+- Document breaking changes
+
+## Publishing
+- Publish packages independently
+- Use automated versioning tools
+- Test before publishing
+- Update changelogs
+
+## TypeScript Configuration
+```json
+{
+  "references": [
+    { "path": "./packages/package-a" },
+    { "path": "./packages/package-b" }
+  ]
+}
+```
+
+## Import Paths
+- Use path aliases: `@company/package-name`
+- Configure in `tsconfig.json` paths
+- Set up module resolution
+
+## Challenges & Solutions
+- **Problem**: Dependency hell
+  - **Solution**: Use workspaces, hoist dependencies
+- **Problem**: Slow builds
+  - **Solution**: Use caching (turbo/nx), build affected only
+- **Problem**: Complex tooling
+  - **Solution**: Share configs, document setup
+
+## CI/CD
+- Build only affected packages
+- Cache build outputs
+- Run tasks in parallel
+- Use matrix builds for packages
+
+## Performance
+- Enable caching for build outputs
+- Use incremental builds
+- Parallelize independent tasks
+- Skip unchanged packages
+
+## Documentation
+- Maintain root-level README
+- Document each package purpose
+- Explain workspace structure
+- Provide contribution guidelines

package/dist/architecture/nx.md

@@ -0,0 +1,122 @@
+# Nx Monorepo Guidelines
+
+## Overview
+This monorepo uses Nx for build orchestration, code generation, and project management.
+
+## Commands
+- Run target: `nx run <project>:<target>`
+- Run for all projects: `nx run-many --target=build --all`
+- Run affected: `nx affected --target=build`
+- Show dependency graph: `nx graph`
+- Generate code: `nx generate @nx/react:component`
+
+## Project Configuration
+```json
+{
+  "name": "my-app",
+  "targets": {
+    "build": {
+      "executor": "@nx/webpack:webpack",
+      "outputs": ["{workspaceRoot}/dist/apps/my-app"],
+      "options": {
+        "outputPath": "dist/apps/my-app"
+      }
+    }
+  }
+}
+```
+
+## Affected Commands
+- Build affected: `nx affected:build`
+- Test affected: `nx affected:test`
+- Lint affected: `nx affected:lint`
+- Based on git diff from base branch
+
+## Caching
+- Nx caches task outputs automatically
+- Cache key based on inputs
+- Restore from cache for unchanged code
+- Configure cacheable operations
+
+## Generators
+- Generate applications: `nx g @nx/react:app`
+- Generate libraries: `nx g @nx/js:lib`
+- Custom generators for consistency
+- Automated code scaffolding
+
+## Project Graph
+- Visualize dependencies: `nx graph`
+- See affected projects
+- Understand project relationships
+- Detect circular dependencies
+
+## Configuration Files
+- `nx.json`: Nx configuration
+- `workspace.json` or `project.json`: Project config
+- `.nxignore`: Files to ignore
+
+## Task Pipeline
+```json
+{
+  "targetDefaults": {
+    "build": {
+      "dependsOn": ["^build"]
+    }
+  }
+}
+```
+
+## Plugins
+- Framework-specific plugins: React, Angular, Next.js
+- Tool-specific plugins: Jest, Cypress, ESLint
+- Custom plugins for specific needs
+
+## Workspace Libraries
+- Organize code into libraries
+- Enforce module boundaries
+- Share code between apps
+- Use tags for constraints
+
+## Best Practices
+- Use affected commands in CI
+- Organize libs by scope and type
+- Set up import restrictions
+- Use generators for consistency
+- Enable computation caching
+- Configure remote caching for teams
+
+## CI/CD Integration
+```yaml
+- name: Nx Cache
+  uses: actions/cache@v4
+  with:
+    path: node_modules/.cache/nx
+    key: nx-${{ github.sha }}
+    restore-keys: nx-
+
+- name: Build affected
+  run: nx affected --target=build --base=origin/main
+```
+
+## Performance
+- Parallel execution of independent tasks
+- Computation caching
+- Remote caching with Nx Cloud
+- Affected-only builds in CI
+
+## Module Boundaries
+```json
+{
+  "@nx/enforce-module-boundaries": [
+    "error",
+    {
+      "depConstraints": [
+        {
+          "sourceTag": "scope:shared",
+          "onlyDependOnLibsWithTags": ["scope:shared"]
+        }
+      ]
+    }
+  ]
+}
+```

package/dist/architecture/turborepo.md

@@ -0,0 +1,114 @@
+# Turborepo Guidelines
+
+## Overview
+This monorepo uses Turborepo for build orchestration and caching.
+
+## Configuration
+```json
+{
+  "$schema": "https://turbo.build/schema.json",
+  "pipeline": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**", ".next/**"]
+    },
+    "test": {
+      "dependsOn": ["build"],
+      "outputs": []
+    },
+    "lint": {
+      "outputs": []
+    },
+    "dev": {
+      "cache": false
+    }
+  }
+}
+```
+
+## Commands
+- Run task across all workspaces: `turbo run build`
+- Run task in specific workspace: `turbo run build --filter=package-name`
+- Run with no cache: `turbo run build --force`
+- Clear cache: `turbo run build --no-cache`
+- Dry run: `turbo run build --dry-run`
+
+## Pipeline Configuration
+- `dependsOn`: Task dependencies
+- `^dependsOn`: Dependencies from workspace dependencies
+- `outputs`: Files to cache
+- `cache`: Enable/disable caching
+- `inputs`: Files that affect cache validity
+
+## Caching
+- Turborepo caches task outputs
+- Cache key based on inputs (files, env vars)
+- Shared cache across team (remote caching)
+- Restore from cache for unchanged code
+
+## Filtering
+- By package: `--filter=package-name`
+- By directory: `--filter=./apps/*`
+- By dependency: `--filter=...package-name`
+- By changed files: `--filter=[HEAD^1]`
+
+## Remote Caching
+```bash
+# Enable remote cache
+turbo login
+turbo link
+
+# Or use Vercel
+vercel link
+```
+
+## Environment Variables
+- Automatically included in cache key
+- Prefix with `TURBO_` for Turbo-specific vars
+- Use `.env` files for local development
+
+## Performance
+- Tasks run in parallel when possible
+- Skips cached tasks
+- Shows cache hit ratio
+- Optimizes based on dependencies
+
+## Best Practices
+- Define clear task dependencies
+- Specify all outputs for caching
+- Use `^` for workspace dependencies
+- Enable remote caching for teams
+- Run affected tasks only in CI
+- Keep pipeline config simple
+
+## Monorepo Commands
+```json
+{
+  "scripts": {
+    "build": "turbo run build",
+    "dev": "turbo run dev --parallel",
+    "test": "turbo run test",
+    "lint": "turbo run lint"
+  }
+}
+```
+
+## CI/CD Integration
+```yaml
+# GitHub Actions
+- name: Setup Turborepo cache
+  uses: actions/cache@v4
+  with:
+    path: .turbo
+    key: turbo-${{ github.sha }}
+    restore-keys: turbo-
+
+- name: Build
+  run: turbo run build
+```
+
+## Debugging
+- Use `--dry-run` to see execution plan
+- Check `.turbo/runs/*.json` for logs
+- Enable verbose output: `--verbose`
+- View graph: `turbo run build --graph`