diff --git a/.commitlintrc.json b/.commitlintrc.json new file mode 100644 index 0000000..c274d7c --- /dev/null +++ b/.commitlintrc.json @@ -0,0 +1,24 @@ +{ + "extends": ["@commitlint/config-conventional"], + "rules": { + "type-enum": [ + 2, + "always", + [ + "build", + "ci", + "docs", + "feat", + "fix", + "perf", + "refactor", + "revert", + "style", + "test", + "chore" + ] + ], + "subject-case": [2, "never", ["upper-case"]], + "header-max-length": [2, "always", 100] + } +} diff --git a/.github/workflows/pr-checks.yml b/.github/workflows/pr-checks.yml index 919a54a..6cfd421 100644 --- a/.github/workflows/pr-checks.yml +++ b/.github/workflows/pr-checks.yml @@ -44,6 +44,8 @@ jobs: node-version: 24 - name: Install yarn deps run: yarn install + - name: Run type-check + run: npx tsc --noEmit - name: Run eslint run: yarn lint - name: Run unit tests diff --git a/.gitignore b/.gitignore index 8620945..fd88a00 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,21 @@ node_modules/ coverage lib output +dist/ + +# TypeScript +*.tsbuildinfo + +# Editor files +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# Package managers +.npm/ +.pnpm-store/ # https://yarnpkg.com/getting-started/qa#which-files-should-be-gitignored # not zero-install mode diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..9ba31ce --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,113 @@ +# DevWorkspace Generator + +## Overview +This library generates DevWorkspace components and templates for Eclipse Che. It transforms devfile.yaml specifications and editor definitions into Kubernetes DevWorkspace custom resources. + +Published as [@eclipse-che/che-devworkspace-generator](https://www.npmjs.com/package/@eclipse-che/che-devworkspace-generator) on npm. + +## Architecture +- **TypeScript library** with InversifyJS dependency injection +- **Main entry**: `src/entrypoint.ts` - exports generator functions +- **Core generator**: `src/main.ts` - orchestrates devfile parsing and DevWorkspace generation +- **API models**: Uses `@devfile/api` for Kubernetes DevWorkspace resource types +- **YAML processing**: `js-yaml` for parsing and serialization + +## Development + +### Quick Start +```bash +# One-command setup for development +yarn setup + +# Or manually: +yarn install && yarn compile && yarn test +``` + +### Setup +```bash +yarn install # Install all dependencies +``` + +### Build +```bash +yarn build # Full build: format, compile, lint, test +yarn compile # TypeScript compilation only +``` + +### Testing +```bash +yarn test # Run Jest test suite with coverage +yarn lint # ESLint checks +yarn format # Prettier format check +yarn format:fix # Auto-format code +yarn lint:fix # Auto-fix lint issues +``` + +### Single-File Verification +Use these commands to verify individual files quickly (< 5 seconds): + +```bash +# Lint a single file +npx eslint + +# Type-check a single file +npx tsc --noEmit + +# Format check a single file +npx prettier --check +``` + +## Coding Standards +- **TypeScript strict mode** enabled in tsconfig.json +- **100% test coverage** required (branches, functions, lines, statements) +- **Prettier** for consistent formatting (120 char line width, single quotes) +- **ESLint** for code quality +- **No implicit any** types +- **Explicit type annotations** for function parameters and return types +- **Conventional commits** - Use format: `type(scope): subject` + - Types: feat, fix, docs, style, refactor, test, chore, ci, build, perf, revert + - Example: `feat: add gitlab resolver`, `fix: handle null in bitbucket url parser` + +## CI/CD +Pull requests must pass: +- License compliance checks +- ESLint validation +- TypeScript type checking +- Jest test suite with full coverage + +## Pattern References + +Common change patterns in this codebase: + +### Adding a New Git Provider Resolver +**Pattern**: `src/github/` or `src/bitbucket/` + +Each resolver follows a three-file structure: +- `{provider}-module.ts` - InversifyJS binding configuration +- `{provider}-resolver.ts` - Main resolver implementation with `resolve()` method +- `{provider}-url.ts` - URL parsing and validation + +**Example**: See `src/github/github-resolver.ts` for URL pattern matching and content fetching. + +### Adding DevFile Component Processing +**Pattern**: `src/devfile/` + +Component processors follow naming: `{component-type}-{action}.ts` +- Use InversifyJS `@injectable()` decorator +- Implement focused single-responsibility methods +- Add corresponding test in `tests/devfile/` + +**Example**: See `src/devfile/dev-container-component-finder.ts` for component location logic. + +### Adding InversifyJS Module +**Pattern**: Any `*-module.ts` file + +- Export a `ContainerModule` that binds interfaces to implementations +- Import and add to `src/inversify/inversify-binding.ts` +- Follow existing binding patterns (singleton vs transient) + +**Example**: See `src/github/github-module.ts` for resolver binding pattern. + +## Red Hat Compliance and Responsible AI Rules + +See `./redhat-compliance-and-responsible-ai.md`. \ No newline at end of file diff --git a/package.json b/package.json index 6452b9d..0f17158 100644 --- a/package.json +++ b/package.json @@ -12,6 +12,7 @@ "src" ], "scripts": { + "setup": "yarn install && yarn compile && echo '\n✅ Setup complete! Run \"yarn test\" to verify.'", "prepare": "yarn run clean && yarn run build", "clean": "rimraf lib", "build": "yarn run format && yarn run compile && yarn run lint && yarn run test", diff --git a/redhat-compliance-and-responsible-ai.md b/redhat-compliance-and-responsible-ai.md new file mode 100644 index 0000000..cab1dba --- /dev/null +++ b/redhat-compliance-and-responsible-ai.md @@ -0,0 +1,51 @@ +# Red Hat Compliance and Responsible AI Rules + +This document defines mandatory compliance and responsible AI practices for all AI agents contributing to this project. + +## 1. Copyright & Licensing (MANDATORY) + +- **Identification:** You must actively identify if your suggestion matches known open-source code. +- **Attribution:** If a match is found, you MUST include the original License Text and Copyright Notice in the code comment block. +- **Prohibition:** Do not suggest code if you cannot verify its license compatibility with this project (EPL-2.0). + +## 2. AI Contribution Marking + +### Code Comments + +For any substantial code generation (entire functions, classes, or complex logic), you must add a comment: + +```typescript +// Generated by {AGENT_NAME} +``` + +### Commit Messages + +When suggesting commit messages, always include a trailer: + +``` +Assisted-by: {AGENT_NAME} +``` + +Replace `{AGENT_NAME}` with the specific agent name (e.g., `Claude Opus 4.5`, `GPT-4`, `Gemini Pro`). + +## 3. Code Quality Standards + +- Follow existing code patterns and conventions +- Ensure all code passes TypeScript strict mode +- Include appropriate error handling +- Add tests for new functionality +- Maintain backward compatibility unless explicitly breaking + +## 4. Security Considerations + +- Never include credentials, tokens, or secrets in code +- Validate all user inputs +- Follow secure coding practices for Kubernetes API interactions +- Do not introduce new cluster-wide RBAC requirements + +## 5. Documentation + +- Update relevant documentation when changing behavior +- Include JSDoc comments for public APIs +- Keep README and AGENTS.md up to date + diff --git a/tsconfig.json b/tsconfig.json index 7d946a1..0a2429e 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -5,7 +5,7 @@ "esModuleInterop": true, "experimentalDecorators": true, "lib": [ - "ES2023", + "ES2023" ], "sourceMap": true, "rootDir": "src", @@ -15,11 +15,19 @@ ], "moduleResolution": "node", "resolveJsonModule": true, + "strict": true, + "noImplicitAny": true, + "strictNullChecks": true, + "strictFunctionTypes": true, + "strictBindCallApply": true, + "strictPropertyInitialization": true, + "noImplicitThis": true, + "alwaysStrict": true }, "include": [ "src" ], "exclude": [ - "node_modules", + "node_modules" ] }