Skip to content

Commit c51f4c7

Browse files
paulcruse3paulcruse3
committed
initial code
Configures CI/CD pipeline with CircleCI Sets up CircleCI configuration for automated testing, linting, building, and deployment. - Defines jobs for installing dependencies, type checking, linting, building, testing, and deploying to NPM. - Configures workflows for testing on all branches and deploying on tagged commits. - Adds .npmignore file to exclude unnecessary files from the published package. - Introduces a script to fix ESM import paths by adding '.js' extensions. - Adjusts the build process to generate package.json files for cjs and esm folders and fixes import statements. Initializes acai-ts project in TypeScript Adds initial project setup, including: - Core library in TypeScript with dual module support - API Gateway module with Router, Request, and Response classes - Validation using JSON Schema - Common utilities like Logger and Timer - AWS service support for DynamoDB, S3, and SQS - Examples showcasing various features - Comprehensive documentation and migration guide - CircleCI config to match source structure This commit marks the first release of acai-ts as a TypeScript-native rewrite of acai-js. Adds dedicated test and coverage jobs Refactors the CircleCI configuration to include dedicated jobs for running tests and generating coverage reports. This change improves the clarity and organization of the CI pipeline. It also fixes an issue where the coverage directory was not being created before running the coverage command. Adds JUnit reporter for Jest test results Configures Jest to output JUnit-formatted test results, enabling better integration with CI systems. Stores the JUnit XML report in the coverage directory. Also removes the CI environment variable definition from the test command in CircleCI, as it is not needed. Adds project badges to README Enhances the README with badges for project status, quality, and dependencies. This provides a quick overview of the project's health, code quality, TypeScript version, and license. Removes example code directory Removes the examples directory to streamline the project structure and focus on core library functionality. This directory is no longer needed in the repository. Adds documentation website and examples link Enhances documentation by providing links to the full documentation website and examples repository in the README, CHANGELOG, and MIGRATION files. This change improves discoverability and access to comprehensive documentation and example code for users. Publishes beta versions with the 'beta' tag. This commit enhances the CircleCI configuration to automatically publish beta versions of the package to npm with the "beta" tag when the `CIRCLE_TAG` environment variable contains "beta". Stable versions are published to the "latest" tag. Enables publishing from any tag Removes the tag name restriction to allow publishing from any tag. This facilitates more flexible release processes.
1 parent 2ab73eb commit c51f4c7

File tree

124 files changed

+21617
-2
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

124 files changed

+21617
-2
lines changed

‎.circleci/README.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# CircleCI Configuration for acai-ts
2+
3+
This directory contains the CI/CD configuration for the acai-ts project using CircleCI.
4+
5+
## Configuration Overview
6+
7+
The CircleCI configuration (`config.yml`) defines two main workflows:
8+
9+
### 1. Test Workflow (`install-build-test-workflow`)
10+
11+
**Triggers**: All branch pushes (excludes tags)
12+
13+
**Steps**:
14+
1. **Install dependencies** - `npm ci`
15+
2. **Type checking** - `npm run type-check` (verify TypeScript compiles)
16+
3. **Linting** - `npm run lint` (ESLint with HTML output)
17+
4. **Build** - `npm run build` (compile ESM + CJS outputs)
18+
5. **Test** - `npm run test:ci` (Jest with coverage)
19+
6. **Coverage reports** - Store artifacts
20+
7. **SonarCloud scan** - Code quality analysis
21+
22+
**Context Required**: `sonarcloud`
23+
24+
### 2. Deploy Workflow (`install-build-deploy-workflow`)
25+
26+
**Triggers**: Git tags matching `v*` pattern (e.g., `v1.0.0`, `v2.1.3`)
27+
28+
**Steps**:
29+
1. **Install dependencies** - `npm ci`
30+
2. **Build** - `npm run build`
31+
3. **Publish to NPM** - `npm publish --access public`
32+
33+
**Context Required**: `npm-publish`
34+
35+
## Required Environment Variables
36+
37+
### SonarCloud Context
38+
- `SONAR_TOKEN` - SonarCloud authentication token
39+
40+
### NPM Publish Context
41+
- `NPM_TOKEN` - NPM registry authentication token
42+
43+
## Setting Up Contexts
44+
45+
1. Go to CircleCI → Organization Settings → Contexts
46+
2. Create `sonarcloud` context:
47+
- Add `SONAR_TOKEN` environment variable
48+
3. Create `npm-publish` context:
49+
- Add `NPM_TOKEN` environment variable
50+
51+
## Publishing a New Release
52+
53+
To publish a new version to NPM:
54+
55+
```bash
56+
# 1. Update version in package.json
57+
npm version patch # or minor, or major
58+
59+
# 2. Push with tags
60+
git push origin main --tags
61+
62+
# 3. CircleCI will automatically:
63+
# - Build the project
64+
# - Run npm publish
65+
# - Package will be available on npm
66+
```
67+
68+
## Docker Image
69+
70+
Uses `cimg/node:18.18.2` - CircleCI's official Node.js 18 image with common tools pre-installed.
71+
72+
## Resource Class
73+
74+
Uses `medium` resource class (2 vCPUs, 4GB RAM) for both jobs.
75+
76+
## Artifacts
77+
78+
The following artifacts are stored:
79+
- **Lint report**: HTML report at `./coverage/lint/index.html`
80+
- **Test results**: JUnit XML in `./coverage/`
81+
- **Coverage report**: LCOV and HTML coverage reports
82+
83+
## Local Testing
84+
85+
To simulate the CI pipeline locally:
86+
87+
```bash
88+
# Install dependencies
89+
npm ci
90+
91+
# Type check
92+
npm run type-check
93+
94+
# Lint
95+
npm run lint
96+
97+
# Build
98+
npm run build
99+
100+
# Test with coverage
101+
npm run test:ci
102+
103+
# Check package contents
104+
npm pack --dry-run
105+
```
106+
107+
## Package Publishing
108+
109+
The package is configured to publish:
110+
- `dist/` directory (ESM + CJS builds)
111+
- `README.md`
112+
- `LICENSE`
113+
- `package.json`
114+
115+
All source files, tests, and config files are excluded (see `.npmignore`).
116+
117+
## Troubleshooting
118+
119+
### Build fails on type-check
120+
- Ensure all TypeScript files compile without errors
121+
- Run `npm run type-check` locally
122+
123+
### Tests fail on CI
124+
- Run `npm run test:ci` locally to reproduce
125+
- Check for environment-specific issues
126+
127+
### SonarCloud scan fails
128+
- Verify `SONAR_TOKEN` is set in CircleCI context
129+
- Check `sonar-project.properties` configuration
130+
131+
### NPM publish fails
132+
- Verify `NPM_TOKEN` is valid and has publish permissions
133+
- Ensure package name is available on npm registry
134+
- Check version tag format (must start with `v`)
135+
136+
## Additional Resources
137+
138+
- [CircleCI Documentation](https://circleci.com/docs/)
139+
- [SonarCloud Documentation](https://docs.sonarcloud.io/)
140+
- [NPM Publishing Guide](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry)

‎.circleci/config.yml‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
version: 2.1
2+
orbs:
3+
sonarcloud: sonarsource/[email protected]
4+
commands:
5+
node-install:
6+
description: "Install Node.js dependencies"
7+
steps:
8+
- run:
9+
name: Install dependencies
10+
command: npm ci
11+
node-type-check:
12+
description: "Run TypeScript type checking"
13+
steps:
14+
- run:
15+
name: TypeScript type check
16+
command: npm run type-check
17+
node-linter:
18+
description: "Run ESLint with HTML output"
19+
steps:
20+
- run:
21+
name: Run linter
22+
command: |
23+
mkdir -p ./lint
24+
npm run lint -- --format html --output-file ./lint/index.html || true
25+
- store_artifacts:
26+
path: ./lint
27+
node-build:
28+
description: "Build TypeScript project (ESM + CJS)"
29+
steps:
30+
- run:
31+
name: Build project
32+
command: npm run build
33+
node-test:
34+
description: "Run Jest tests"
35+
steps:
36+
- run:
37+
name: Run tests
38+
command: npm run test
39+
node-coverage-report:
40+
description: "Run Jest tests with coverage"
41+
steps:
42+
- run:
43+
name: Run tests with coverage
44+
command: |
45+
mkdir -p ./coverage
46+
npm run test:ci
47+
environment:
48+
CI: true
49+
- store_test_results:
50+
path: ./coverage/junit.xml
51+
- store_artifacts:
52+
path: ./coverage
53+
npm-deploy:
54+
description: "Deploy package to NPM registry"
55+
steps:
56+
- attach_workspace:
57+
at: .
58+
- run:
59+
name: Authenticate with NPM
60+
command: echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > .npmrc
61+
- run:
62+
name: Set package version from tag
63+
command: npm version $CIRCLE_TAG --allow-same-version --no-git-tag-version
64+
- run:
65+
name: Publish to NPM
66+
command: |
67+
if echo "$CIRCLE_TAG" | grep -iq "beta"; then
68+
echo "Beta version detected in tag: $CIRCLE_TAG"
69+
echo "Publishing with --tag beta"
70+
npm publish --access public --tag beta
71+
else
72+
echo "Stable version detected in tag: $CIRCLE_TAG"
73+
echo "Publishing to latest"
74+
npm publish --access public
75+
fi
76+
77+
jobs:
78+
install-build:
79+
docker:
80+
- image: cimg/node:18.18.2
81+
steps:
82+
- checkout:
83+
method: full
84+
- node-install
85+
- node-build
86+
- persist_to_workspace:
87+
root: ~/project
88+
paths:
89+
- ./*
90+
type-check:
91+
docker:
92+
- image: cimg/node:18.18.2
93+
steps:
94+
- attach_workspace:
95+
at: ~/project
96+
- node-type-check
97+
lint:
98+
docker:
99+
- image: cimg/node:18.18.2
100+
steps:
101+
- attach_workspace:
102+
at: ~/project
103+
- node-linter
104+
test:
105+
docker:
106+
- image: cimg/node:18.18.2
107+
steps:
108+
- attach_workspace:
109+
at: ~/project
110+
- node-test
111+
coverage:
112+
docker:
113+
- image: cimg/node:18.18.2
114+
steps:
115+
- attach_workspace:
116+
at: ~/project
117+
- node-coverage-report
118+
- sonarcloud/scan
119+
install-build-deploy:
120+
docker:
121+
- image: cimg/node:18.18.2
122+
steps:
123+
- checkout:
124+
method: full
125+
- node-install
126+
- node-build
127+
- npm-deploy
128+
workflows:
129+
version: 2
130+
# Deploy workflow: Runs on git tags, deploys to NPM
131+
install-build-deploy-workflow:
132+
jobs:
133+
- install-build-deploy:
134+
context:
135+
- npm-publish
136+
filters:
137+
tags:
138+
only: /.*/
139+
branches:
140+
ignore: /.*/
141+
# Test workflow: Runs on all branches, performs full testing
142+
install-build-test-workflow:
143+
jobs:
144+
- install-build
145+
- type-check:
146+
requires:
147+
- install-build
148+
- lint:
149+
requires:
150+
- install-build
151+
- test:
152+
requires:
153+
- install-build
154+
- coverage:
155+
context:
156+
- sonarcloud
157+
requires:
158+
- install-build

‎.eslintrc.js‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
module.exports = {
2+
root: true,
3+
parser: '@typescript-eslint/parser',
4+
parserOptions: {
5+
ecmaVersion: 2020,
6+
sourceType: 'module',
7+
project: './tsconfig.json'
8+
},
9+
plugins: ['@typescript-eslint', 'prettier'],
10+
extends: [
11+
'eslint:recommended',
12+
'plugin:@typescript-eslint/recommended',
13+
'plugin:@typescript-eslint/recommended-requiring-type-checking',
14+
'plugin:prettier/recommended'
15+
],
16+
env: {
17+
node: true,
18+
es6: true
19+
},
20+
rules: {
21+
'prettier/prettier': [
22+
'warn',
23+
{
24+
trailingComma: 'none',
25+
printWidth: 140,
26+
tabWidth: 4,
27+
singleQuote: true,
28+
bracketSpacing: false,
29+
arrowParens: 'always'
30+
}
31+
],
32+
'eqeqeq': 'error',
33+
'@typescript-eslint/no-explicit-any': 'error',
34+
'@typescript-eslint/explicit-function-return-type': 'off',
35+
'@typescript-eslint/explicit-module-boundary-types': 'off',
36+
'@typescript-eslint/no-unused-vars': ['warn', {argsIgnorePattern: '^_'}],
37+
'@typescript-eslint/no-non-null-assertion': 'warn',
38+
'no-console': 'off'
39+
}
40+
};

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,3 +137,9 @@ dist
137137
# Vite logs files
138138
vite.config.js.timestamp-*
139139
vite.config.ts.timestamp-*
140+
141+
# Documentation directory
142+
docs/
143+
144+
# Test results
145+
test-results/

0 commit comments

Comments
 (0)