Skip to content

CLAUDE.md

Latest commit

 

History

History
225 lines (170 loc) · 9.77 KB

CLAUDE.md

File metadata and controls

225 lines (170 loc) · 9.77 KB

Projen-managed Project Instructions

This project is managed by projen, a project configuration management tool.

Important Guidelines

Task Execution

  • Always use projen for task execution: Run tasks using pnpm exec 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:
    • pnpm exec projen - Synthesize project configuration files
    • pnpm exec projen build - Builds the project, including running tests
    • pnpm exec projen test - Runs tests only
    • pnpm exec 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 pnpm exec 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 pnpm exec 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

Development Best Practices

  • Always run build after changes: After modifying any source or test file, run pnpm exec projen build to ensure your changes compile and pass all tests.
  • Task completion criteria: A task is not considered complete until:
    • All tests pass (pnpm exec projen test)
    • There are no compilation errors (pnpm exec 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 (pnpm exec 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

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:

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:

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().