Projen-managed Project Instructions

# Projen-managed Project Instructions

This project is managed by [projen](https://github.com/projen/projen), a project configuration management tool.

## Important Guidelines

### Task Execution

- **Always use projen for task execution**: Run tasks using `npx projen <task-name>` instead of directly using npm, yarn, or other package managers.
- **Check available tasks**: Look in `.projen/tasks.json` to see all available tasks, their descriptions, and steps.
- **Common tasks**:
  - `npx projen` - Synthesize project configuration files
  - `npx projen build` - Builds the project, including running tests
  - `npx projen test` - Runs tests only
  - `npx projen compile` - Compiles the source code only

### File Modifications

- **DO NOT manually edit generated files**: Files marked with a comment like "~~ Generated by projen. To modify..." should never be edited directly.
- **Modify configuration in .projenrc**: To change project configuration, always edit the `.projenrc.ts`, `.projenrc.py` or `.projenrc.json` etc. file and then run `npx projen` to regenerate the project files.
- **Check .projenrc first**: Before suggesting changes to package.json, tsconfig.json, or other configuration files, always check if these are managed by projen and suggest changes to .projenrc instead.

### Dependencies

- **Add dependencies through projen**: Use the projen configuration to add dependencies instead of manually editing package.json or using npm/yarn install directly.
- **Example**: In .projenrc, use methods like `addDeps()`, `addDevDeps()`, or `addPeerDeps()` to add dependencies.

### Workflow

1. Make changes to .projenrc configuration file
2. Run `npx projen` to synthesize and update generated files
3. Review the changes
4. Commit both .projenrc and the generated files

## Projen Configuration

This project's configuration is defined in the .projenrc file at the root of the repository. All project metadata, dependencies, scripts, and tooling configuration should be managed through this file.

## Additional Resources

- [Projen Documentation](https://projen.io)
- [Projen GitHub Repository](https://github.com/projen/projen)

# Development Best Practices

- **Always run build after changes**: After modifying any source or test file, run `npx projen build` to ensure your changes compile and pass all tests.
- **Task completion criteria**: A task is not considered complete until:
  - All tests pass (`npx projen test`)
  - There are no compilation errors (`npx projen compile`)
  - There are no linting errors (usually part of the build, if not, run the linter defined in tasks.json)
  - The full build succeeds (`npx projen build`)

## Overview

This repository provides Projen project types for ClickUp. It's a JSII library that exports custom Projen project classes for creating standardized TypeScript and CDK projects with opinionated configurations for ClickUp's development practices.

## Core Commands

### Development
- `pnpm projen` - Regenerate all project files from `.projenrc.ts`
- `pnpm build` - Compile TypeScript and run tests with coverage
- `pnpm test` - Run Jest tests
- `pnpm test:watch` - Run tests in watch mode
- `pnpm eslint` - Run ESLint linter
- `pnpm compile` - Compile TypeScript only

### Testing a Single Test File
```bash
pnpm test path/to/test-file.test.ts
```

### Local Development Testing
To test changes locally before publishing, build a local tarball and use it in another project:
```bash
pnpm build
# Creates: dist/js/clickup-projen@0.0.0.jsii.tgz
# Then in another project:
projen new --from /path/to/clickup-projen/dist/js/clickup-projen@0.0.0.jsii.tgz <project-type>
```

### Release
The release process is fully automated via GitHub Actions. Releases are triggered by conventional commits on the main branch.

## Architecture

### Project Structure
- `src/` - Source TypeScript files that define Projen project types
- `test/` - Jest test files with snapshot testing
- `.projenrc.ts` - Projen configuration for this repository itself
- `dist/` - Built JSII artifacts (generated)
- `lib/` - Compiled TypeScript (generated)

### Core Modules

#### `clickup-ts.ts`
Base TypeScript project class that all other project types extend. Key features:
- Enforces `@time-loop/` scoped package naming via `normalizeName()`
- Configures pnpm as package manager with version pinning
- Sets up Renovate bot for dependency management
- Integrates Prettier, ESLint, Jest with opinionated configs
- Supports TypeDoc documentation generation via `TypedocDocgen` component
- Manages node version constraints (min: 18.17.1, workflow: 22.14.0)

Key exports:
- `ClickUpTypeScriptProject` - Base class for TypeScript libraries
- `TypedocDocgen` - Component for TypeScript documentation
- `normalizeName()` - Ensures proper `@time-loop/` package naming
- `fixTsNodeDeps()` - Resolves ts-node dependency issues

#### `clickup-cdk.ts`
CDK-specific project types extending `clickup-ts`. Provides:
- `ClickUpCdkConstructLibrary` - For reusable CDK construct libraries (use `cdk-*` prefix naming)
- `ClickUpCdkTypeScriptApp` - For CDK applications (use `*-cdk` suffix naming)
- Pre-configured with `@time-loop/cdk-library`, `cdk-constants`, `multi-convention-namer`
- Minimum CDK version: 2.189.0
- Optional cdk-diff workflow integration
- Optional cdk.context.json self-mutation support

Key architectural patterns:
- All projects use deep merge for options via `ts-deepmerge`
- CDK apps include sample code with Widget example demonstrating ClickUp patterns
- Test files use CDK assertions for infrastructure testing

#### Workflow Modules
- `renovate-workflow.ts` - Configures Renovate bot with auto-merge for non-breaking updates
- `cdk-diff-workflow.ts` - Adds CDK diff visualization in PRs via GitHub Actions
- `cdk-context-json.ts` - Enables automatic cdk.context.json lookups and mutations
- `codecov-bypass-workflow.ts` - Allows codecov requirement bypass for specific scenarios
- `update-projen.ts` - Automated projen version upgrade workflows
- `add-to-project.ts` - Auto-adds issues/PRs to GitHub project boards

#### Integration Modules
- `datadog.ts` - Sends release events to Datadog
- `datadog-service-catalog.ts` - Updates Datadog service catalog
- `slack-alert.ts` - Posts release notifications to Slack
- `codecov.ts` - Configures codecov.yml with 90%+ coverage thresholds

### Configuration Philosophy

This library is highly opinionated. Key principles:
1. **Deep Merge Strategy**: Options use `ts-deepmerge` to overlay defaults → project options → forced overrides
2. **JSII Constraints**: As a JSII library, TypeScript features are limited to what's compatible with JSII
3. **Bundled Dependencies**: `cson-parser`, `semver`, and `ts-deepmerge` are bundled to avoid consumer dependency conflicts

### Testing Approach

Tests use snapshot testing extensively. When making changes:
1. Update the code
2. Run `pnpm test` - snapshots may fail
3. Review snapshot diffs carefully
4. Run `pnpm test -- -u` to update snapshots if changes are intentional
5. Commit updated snapshots with your changes

### Node and Package Manager Versions

Version management is centralized in `src/utils/parameters.ts`:
- `PROJEN_MIN_ENGINE_NODE_VERSION`: Minimum engine requirement (18.17.1)
- `PROJEN_NODE_VERSION`: Workflow and development version (22.14.0)
- `PROJEN_PNPM_VERSION`: PNPM version (10.22.0)

These cascade to all generated projects. Update in one place to affect all consumers.

### GitHub Actions Integration

Generated projects include:
- `build.yml` - Runs on PRs, includes self-mutation support
- `release.yml` - Auto-releases on main branch merges
- `renovate.yml` - Scheduled dependency updates (weekly)
- `update-projen-main.yml` - Updates projen version
- `pull-request-lint.yml` - Enforces conventional commit format
- `auto-approve.yml` - Auto-approves Renovate PRs

All workflows require GitHub Packages authentication configured in repository secrets.

## Common Development Patterns

### Adding a New Feature to Project Types

1. Create or modify a module in `src/`
2. Add corresponding test in `test/`
3. Export from `src/index.ts` if it's a public API
4. Run `pnpm projen` to regenerate API.md
5. Run `pnpm test -- -u` to update snapshots
6. Verify in a test project using local tarball

### Creating New Workflow Integrations

Follow the pattern in existing workflow modules:
1. Create a module that exports a function to add the workflow
2. Accept a project and optional configuration options
3. Use `project.github.addWorkflow()` or similar APIs
4. Add helper functions for common configurations
5. Call from project constructors in `clickup-cdk.ts` or `clickup-ts.ts`

## Repository-Specific Notes

- If package.json or lockfile changes after running `pnpm projen`, run `pnpm install` before committing
- This repository uses PNPM with version management via npmrc
- The `packageManager` field in package.json pins the exact pnpm version
- JSII version is pinned to `~5.8.0` (not semantically versioned, use minor updates only)
- TypeScript is pinned to `^5.9.3`
- Renovate ignores many dependencies that should only be updated deliberately
- Third-party Renovate PRs are deferred for 7 days to allow for community testing

## GitHub Packages Authentication

Consumers of this library need GitHub Packages access configured:
```bash
cat >> ~/.npmrc <<EOF
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT
@time-loop:registry=https://npm.pkg.github.com/
EOF
```

The PAT needs `read:packages` scope at minimum.

## Naming Conventions for Generated Projects

- **CDK Construct Libraries**: Use `cdk-*` prefix (e.g., `cdk-my-library`)
  - High quality, deep test coverage, intended for open source
- **CDK Applications**: Use `*-cdk` suffix (e.g., `my-app-cdk`)
  - Thin applications that assemble construct libraries
- **TypeScript Libraries**: No specific convention yet

All packages are automatically prefixed with `@time-loop/` scope by `normalizeName()`.