From d29dbc7f72b459594c1dcd7783de76097b154861 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 8 Nov 2025 00:58:15 +0000 Subject: [PATCH 1/5] Initial plan From d254ff9cc8f7d55dab865a5de9930534b02befa1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 8 Nov 2025 01:09:39 +0000 Subject: [PATCH 2/5] Add comprehensive modernization planning documents Co-authored-by: mohlsen <3265497+mohlsen@users.noreply.github.com> --- CLOUD_NATIVE_DEPLOYMENT.md | 980 ++++++++++++++++++++++++ CONTAINERIZATION_STRATEGY.md | 806 ++++++++++++++++++++ IMPLEMENTATION_PLAN.md | 1193 ++++++++++++++++++++++++++++++ MODERNIZATION_RECOMMENDATIONS.md | 747 +++++++++++++++++++ TESTING_STRATEGY.md | 853 +++++++++++++++++++++ 5 files changed, 4579 insertions(+) create mode 100644 CLOUD_NATIVE_DEPLOYMENT.md create mode 100644 CONTAINERIZATION_STRATEGY.md create mode 100644 IMPLEMENTATION_PLAN.md create mode 100644 MODERNIZATION_RECOMMENDATIONS.md create mode 100644 TESTING_STRATEGY.md diff --git a/CLOUD_NATIVE_DEPLOYMENT.md b/CLOUD_NATIVE_DEPLOYMENT.md new file mode 100644 index 0000000..ebef114 --- /dev/null +++ b/CLOUD_NATIVE_DEPLOYMENT.md @@ -0,0 +1,980 @@ +# check-engine Cloud-Native Deployment Guide + +**Document Version:** 1.0 +**Date:** 2025-11-08 +**Status:** Planning Phase + +## Overview + +This guide provides comprehensive strategies for deploying and using check-engine in cloud-native environments, including Kubernetes, serverless platforms, and major cloud providers (AWS, Google Cloud, Azure). + +--- + +## Table of Contents + +1. [Kubernetes Deployment](#kubernetes-deployment) +2. [Helm Charts](#helm-charts) +3. [AWS Deployment](#aws-deployment) +4. [Google Cloud Deployment](#google-cloud-deployment) +5. [Azure Deployment](#azure-deployment) +6. [Serverless Deployment](#serverless-deployment) +7. [CI/CD Integration](#cicd-integration) +8. [Best Practices](#best-practices) + +--- + +## Kubernetes Deployment + +### Use Cases in Kubernetes + +1. **Pre-deployment Validation** - InitContainer to validate environment before app starts +2. **Periodic Audits** - CronJob to regularly check environment compliance +3. **One-time Checks** - Job for ad-hoc validation +4. **Admission Control** - Webhook to validate deployments + +--- + +### 1. Job - One-Time Validation + +**Purpose:** Run environment validation as a one-time task + +```yaml +apiVersion: batch/v1 +kind: Job +metadata: + name: check-engine-validation + namespace: default + labels: + app: check-engine + type: validation +spec: + backoffLimit: 3 + completions: 1 + parallelism: 1 + template: + metadata: + labels: + app: check-engine + type: validation + spec: + restartPolicy: Never + + containers: + - name: check-engine + image: ghcr.io/mohlsen/check-engine:latest + imagePullPolicy: IfNotPresent + + command: ["check-engine"] + args: ["/config/package.json"] + + volumeMounts: + - name: package-config + mountPath: /config + readOnly: true + + resources: + requests: + memory: "64Mi" + cpu: "100m" + limits: + memory: "128Mi" + cpu: "200m" + + volumes: + - name: package-config + configMap: + name: package-json-config +``` + +**ConfigMap for package.json:** +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: package-json-config + namespace: default +data: + package.json: | + { + "name": "my-app", + "engines": { + "node": ">=18", + "npm": ">=8", + "git": ">=2.30" + } + } +``` + +**Usage:** +```bash +# Create ConfigMap +kubectl apply -f configmap.yaml + +# Run Job +kubectl apply -f job.yaml + +# Check status +kubectl get jobs +kubectl logs job/check-engine-validation + +# Cleanup +kubectl delete job check-engine-validation +``` + +--- + +### 2. InitContainer - Pre-Deployment Validation + +**Purpose:** Validate environment before starting application containers + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: my-application + namespace: default +spec: + replicas: 3 + selector: + matchLabels: + app: my-application + template: + metadata: + labels: + app: my-application + spec: + # Environment validation before app starts + initContainers: + - name: validate-environment + image: ghcr.io/mohlsen/check-engine:standard + imagePullPolicy: IfNotPresent + + command: ["check-engine"] + args: ["/config/package.json", "--ignore"] + + volumeMounts: + - name: package-config + mountPath: /config + readOnly: true + + resources: + requests: + memory: "64Mi" + cpu: "100m" + limits: + memory: "128Mi" + cpu: "200m" + + # Main application container + containers: + - name: app + image: my-application:latest + ports: + - containerPort: 8080 + + resources: + requests: + memory: "256Mi" + cpu: "250m" + limits: + memory: "512Mi" + cpu: "500m" + + volumes: + - name: package-config + configMap: + name: package-json-config +``` + +**Benefits:** +- App only starts if environment is valid +- Fast failure feedback +- Prevents invalid deployments +- No performance impact on running app + +--- + +### 3. CronJob - Periodic Validation + +**Purpose:** Regularly audit environment compliance + +```yaml +apiVersion: batch/v1 +kind: CronJob +metadata: + name: environment-audit + namespace: default +spec: + # Run every 6 hours + schedule: "0 */6 * * *" + + # Keep last 3 successful and 1 failed job + successfulJobsHistoryLimit: 3 + failedJobsHistoryLimit: 1 + + jobTemplate: + spec: + template: + metadata: + labels: + app: check-engine + type: audit + spec: + restartPolicy: OnFailure + + containers: + - name: check-engine + image: ghcr.io/mohlsen/check-engine:standard + imagePullPolicy: IfNotPresent + + command: ["check-engine"] + args: ["/config/package.json"] + + volumeMounts: + - name: package-config + mountPath: /config + readOnly: true + + # Send results to monitoring system + env: + - name: SLACK_WEBHOOK + valueFrom: + secretKeyRef: + name: monitoring-secrets + key: slack-webhook + + resources: + requests: + memory: "64Mi" + cpu: "100m" + limits: + memory: "128Mi" + cpu: "200m" + + volumes: + - name: package-config + configMap: + name: package-json-config +``` + +**With Notification Script:** +```yaml +# Add notification sidecar +containers: +- name: notifier + image: curlimages/curl:latest + command: ["/bin/sh"] + args: + - -c + - | + RESULT=$(cat /shared/result.json) + curl -X POST $SLACK_WEBHOOK -d "{\"text\": \"Environment Audit: $RESULT\"}" + volumeMounts: + - name: shared-data + mountPath: /shared + +volumes: +- name: shared-data + emptyDir: {} +``` + +--- + +### 4. DaemonSet - Node Validation + +**Purpose:** Validate environment on every node + +```yaml +apiVersion: apps/v1 +kind: DaemonSet +metadata: + name: node-validator + namespace: kube-system +spec: + selector: + matchLabels: + name: node-validator + template: + metadata: + labels: + name: node-validator + spec: + tolerations: + # Run on all nodes including master + - effect: NoSchedule + key: node-role.kubernetes.io/master + + hostNetwork: true + hostPID: true + + containers: + - name: validator + image: ghcr.io/mohlsen/check-engine:full + imagePullPolicy: IfNotPresent + + command: ["/bin/sh"] + args: + - -c + - | + while true; do + check-engine /config/package.json + sleep 3600 + done + + volumeMounts: + - name: package-config + mountPath: /config + readOnly: true + + resources: + requests: + memory: "128Mi" + cpu: "100m" + limits: + memory: "256Mi" + cpu: "200m" + + securityContext: + privileged: true + + volumes: + - name: package-config + configMap: + name: node-requirements +``` + +--- + +## Helm Charts + +### Chart Structure + +``` +check-engine-chart/ +├── Chart.yaml +├── values.yaml +├── templates/ +│ ├── _helpers.tpl +│ ├── configmap.yaml +│ ├── job.yaml +│ ├── cronjob.yaml +│ ├── serviceaccount.yaml +│ └── NOTES.txt +└── README.md +``` + +### Chart.yaml + +```yaml +apiVersion: v2 +name: check-engine +description: Environment validation for Kubernetes workloads +version: 1.0.0 +appVersion: "1.14.0" +keywords: + - validation + - environment + - nodejs +maintainers: + - name: Mike Ohlsen + url: https://github.com/mohlsen +sources: + - https://github.com/mohlsen/check-engine +``` + +### values.yaml + +```yaml +# Default values for check-engine + +image: + repository: ghcr.io/mohlsen/check-engine + tag: latest + pullPolicy: IfNotPresent + variant: standard # base, standard, or full + +packageJson: + # Inline package.json engines configuration + engines: + node: ">=18" + npm: ">=8" + git: ">=2.30" + +# Job configuration +job: + enabled: true + backoffLimit: 3 + restartPolicy: Never + annotations: {} + labels: {} + +# CronJob configuration +cronjob: + enabled: false + schedule: "0 */6 * * *" + successfulJobsHistoryLimit: 3 + failedJobsHistoryLimit: 1 + +# InitContainer configuration +initContainer: + enabled: false + ignoreErrors: false + +# Resource limits +resources: + requests: + memory: "64Mi" + cpu: "100m" + limits: + memory: "128Mi" + cpu: "200m" + +# Service Account +serviceAccount: + create: true + name: "" + annotations: {} + +# Notifications +notifications: + enabled: false + slack: + webhookUrl: "" + email: + enabled: false + to: "" +``` + +### Usage + +```bash +# Install chart +helm install my-validation ./check-engine-chart + +# With custom values +helm install my-validation ./check-engine-chart \ + --set image.tag=1.14.0 \ + --set cronjob.enabled=true \ + --set cronjob.schedule="0 0 * * *" + +# As InitContainer +helm install my-validation ./check-engine-chart \ + --set job.enabled=false \ + --set initContainer.enabled=true + +# Upgrade +helm upgrade my-validation ./check-engine-chart + +# Uninstall +helm uninstall my-validation +``` + +--- + +## AWS Deployment + +### 1. AWS ECS (Elastic Container Service) + +**Task Definition:** +```json +{ + "family": "check-engine", + "networkMode": "awsvpc", + "requiresCompatibilities": ["FARGATE"], + "cpu": "256", + "memory": "512", + "containerDefinitions": [ + { + "name": "check-engine", + "image": "ghcr.io/mohlsen/check-engine:standard", + "command": ["check-engine", "/config/package.json"], + "essential": true, + "logConfiguration": { + "logDriver": "awslogs", + "options": { + "awslogs-group": "/ecs/check-engine", + "awslogs-region": "us-east-1", + "awslogs-stream-prefix": "check-engine" + } + }, + "mountPoints": [ + { + "sourceVolume": "config", + "containerPath": "/config", + "readOnly": true + } + ] + } + ], + "volumes": [ + { + "name": "config", + "efsVolumeConfiguration": { + "fileSystemId": "fs-12345678", + "rootDirectory": "/config" + } + } + ] +} +``` + +**Run Task:** +```bash +aws ecs run-task \ + --cluster my-cluster \ + --task-definition check-engine \ + --launch-type FARGATE \ + --network-configuration "awsvpcConfiguration={subnets=[subnet-12345],securityGroups=[sg-12345]}" +``` + +--- + +### 2. AWS EKS (Elastic Kubernetes Service) + +Use standard Kubernetes manifests or Helm charts (see above). + +**EKS-specific configuration:** +```yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + name: check-engine + annotations: + eks.amazonaws.com/role-arn: arn:aws:iam::123456789:role/check-engine-role + +--- +apiVersion: batch/v1 +kind: Job +metadata: + name: check-engine +spec: + template: + spec: + serviceAccountName: check-engine + containers: + - name: check-engine + image: ghcr.io/mohlsen/check-engine:standard + # ... rest of configuration +``` + +--- + +### 3. AWS Lambda + +**For serverless validation:** + +```javascript +// lambda-handler.js +const { checkEngine } = require('check-engine'); + +exports.handler = async (event) => { + const packageJson = event.packageJson || '/var/task/package.json'; + + try { + const result = await checkEngine(packageJson); + + return { + statusCode: result.status === 0 ? 200 : 500, + body: JSON.stringify(result), + }; + } catch (error) { + return { + statusCode: 500, + body: JSON.stringify({ error: error.message }), + }; + } +}; +``` + +**Deploy with SAM:** +```yaml +# template.yaml +AWSTemplateFormatVersion: '2010-09-09' +Transform: AWS::Serverless-2016-10-31 + +Resources: + CheckEngineFunction: + Type: AWS::Serverless::Function + Properties: + Handler: lambda-handler.handler + Runtime: nodejs20.x + MemorySize: 512 + Timeout: 30 + Events: + Api: + Type: Api + Properties: + Path: /validate + Method: post +``` + +--- + +## Google Cloud Deployment + +### 1. Google Cloud Run + +**Deploy container:** +```bash +# Build and push +gcloud builds submit --tag gcr.io/PROJECT_ID/check-engine + +# Deploy to Cloud Run +gcloud run deploy check-engine \ + --image gcr.io/PROJECT_ID/check-engine \ + --platform managed \ + --region us-central1 \ + --allow-unauthenticated \ + --memory 512Mi \ + --cpu 1 \ + --max-instances 10 +``` + +**With Cloud Build:** +```yaml +# cloudbuild.yaml +steps: + # Build container + - name: 'gcr.io/cloud-builders/docker' + args: ['build', '-t', 'gcr.io/$PROJECT_ID/check-engine', '.'] + + # Push to Container Registry + - name: 'gcr.io/cloud-builders/docker' + args: ['push', 'gcr.io/$PROJECT_ID/check-engine'] + + # Deploy to Cloud Run + - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk' + entrypoint: gcloud + args: + - 'run' + - 'deploy' + - 'check-engine' + - '--image' + - 'gcr.io/$PROJECT_ID/check-engine' + - '--region' + - 'us-central1' + - '--platform' + - 'managed' +``` + +--- + +### 2. Google Kubernetes Engine (GKE) + +Use standard Kubernetes manifests or Helm charts. + +**GKE-specific Workload Identity:** +```yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + name: check-engine + annotations: + iam.gke.io/gcp-service-account: check-engine@PROJECT_ID.iam.gserviceaccount.com +``` + +--- + +### 3. Google Cloud Functions + +```javascript +// index.js +const { checkEngine } = require('check-engine'); + +exports.validateEnvironment = async (req, res) => { + try { + const result = await checkEngine('./package.json'); + + res.status(result.status === 0 ? 200 : 500).json(result); + } catch (error) { + res.status(500).json({ error: error.message }); + } +}; +``` + +**Deploy:** +```bash +gcloud functions deploy validateEnvironment \ + --runtime nodejs20 \ + --trigger-http \ + --allow-unauthenticated \ + --memory 512MB \ + --timeout 60s +``` + +--- + +## Azure Deployment + +### 1. Azure Container Instances (ACI) + +```bash +# Create container group +az container create \ + --resource-group myResourceGroup \ + --name check-engine \ + --image ghcr.io/mohlsen/check-engine:standard \ + --cpu 1 \ + --memory 1 \ + --restart-policy Never \ + --command-line "check-engine /config/package.json" +``` + +**With ARM Template:** +```json +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "resources": [ + { + "type": "Microsoft.ContainerInstance/containerGroups", + "apiVersion": "2021-09-01", + "name": "check-engine", + "location": "eastus", + "properties": { + "containers": [ + { + "name": "check-engine", + "properties": { + "image": "ghcr.io/mohlsen/check-engine:standard", + "command": ["check-engine", "/config/package.json"], + "resources": { + "requests": { + "cpu": 1.0, + "memoryInGB": 1.0 + } + } + } + } + ], + "osType": "Linux", + "restartPolicy": "Never" + } + } + ] +} +``` + +--- + +### 2. Azure Kubernetes Service (AKS) + +Use standard Kubernetes manifests or Helm charts. + +--- + +### 3. Azure Functions + +```javascript +// index.js +const { checkEngine } = require('check-engine'); + +module.exports = async function (context, req) { + try { + const result = await checkEngine('./package.json'); + + context.res = { + status: result.status === 0 ? 200 : 500, + body: result, + }; + } catch (error) { + context.res = { + status: 500, + body: { error: error.message }, + }; + } +}; +``` + +--- + +## CI/CD Integration + +### GitHub Actions + +```yaml +name: Validate Environment + +on: [push, pull_request] + +jobs: + validate: + runs-on: ubuntu-latest + + # Use container + container: + image: ghcr.io/mohlsen/check-engine:standard + + steps: + - uses: actions/checkout@v4 + + - name: Validate environment + run: check-engine package.json + + - name: Upload results + if: always() + uses: actions/upload-artifact@v3 + with: + name: validation-results + path: ./validation-results.json +``` + +--- + +### GitLab CI + +```yaml +validate: + image: ghcr.io/mohlsen/check-engine:standard + stage: test + script: + - check-engine package.json + artifacts: + when: always + paths: + - validation-results.json + reports: + junit: validation-results.xml +``` + +--- + +### Jenkins + +```groovy +pipeline { + agent { + kubernetes { + yaml ''' +apiVersion: v1 +kind: Pod +spec: + containers: + - name: check-engine + image: ghcr.io/mohlsen/check-engine:standard + command: ['cat'] + tty: true + ''' + } + } + + stages { + stage('Validate') { + steps { + container('check-engine') { + sh 'check-engine package.json' + } + } + } + } +} +``` + +--- + +## Best Practices + +### 1. Resource Management + +**Set appropriate limits:** +```yaml +resources: + requests: + memory: "64Mi" + cpu: "100m" + limits: + memory: "128Mi" + cpu: "200m" +``` + +### 2. Security + +**Run as non-root:** +```yaml +securityContext: + runAsNonRoot: true + runAsUser: 1001 + allowPrivilegeEscalation: false + capabilities: + drop: + - ALL +``` + +### 3. Monitoring + +**Add health checks:** +```yaml +livenessProbe: + exec: + command: ["check-engine", "--version"] + initialDelaySeconds: 5 + periodSeconds: 10 +``` + +### 4. Configuration Management + +**Use ConfigMaps for package.json:** +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: package-json +data: + package.json: | + { + "engines": { + "node": ">=18" + } + } +``` + +### 5. Secrets Management + +**Never bake secrets into images:** +```yaml +env: +- name: API_KEY + valueFrom: + secretKeyRef: + name: api-secrets + key: key +``` + +--- + +## Troubleshooting + +### Common Issues + +**1. Permission Denied** +```yaml +securityContext: + fsGroup: 1001 +``` + +**2. Out of Memory** +```yaml +resources: + limits: + memory: "256Mi" # Increase limit +``` + +**3. Timeout** +```yaml +spec: + activeDeadlineSeconds: 300 # 5 minutes +``` + +--- + +## Conclusion + +This guide provides comprehensive patterns for deploying check-engine in cloud-native environments. Key takeaways: + +1. **Flexibility:** Multiple deployment patterns for different use cases +2. **Cloud Agnostic:** Works across AWS, GCP, Azure, and bare-metal Kubernetes +3. **Integration:** Easy CI/CD integration +4. **Best Practices:** Security, resource management, and monitoring built-in + +Choose the deployment pattern that best fits your use case and infrastructure. + diff --git a/CONTAINERIZATION_STRATEGY.md b/CONTAINERIZATION_STRATEGY.md new file mode 100644 index 0000000..91436e8 --- /dev/null +++ b/CONTAINERIZATION_STRATEGY.md @@ -0,0 +1,806 @@ +# check-engine Containerization Strategy + +**Document Version:** 1.0 +**Date:** 2025-11-08 +**Status:** Planning Phase + +## Overview + +This document outlines the comprehensive strategy for containerizing the check-engine project, enabling consistent development environments, simplified CI/CD integration, and cloud-native deployments. + +--- + +## Goals + +### Primary Goals +1. **Consistency:** Ensure identical environments across development, CI/CD, and production +2. **Portability:** Run check-engine anywhere containers are supported +3. **Pre-installed Tools:** Include common development tools in the image +4. **Efficiency:** Optimize image size and build times +5. **Security:** Follow container security best practices + +### Secondary Goals +1. Support multiple architectures (amd64, arm64) +2. Provide multiple image variants for different use cases +3. Enable easy customization and extension +4. Integrate seamlessly with CI/CD pipelines +5. Support orchestration platforms (Kubernetes, Docker Swarm, etc.) + +--- + +## Architecture + +### Image Variants + +We will provide three primary image variants: + +#### 1. Base Image (`check-engine:base`) +**Purpose:** Minimal image with just check-engine installed + +**Contents:** +- Node.js runtime +- check-engine package +- Basic system utilities + +**Size Target:** <50MB +**Use Case:** When host has all required tools, just need check-engine + +```dockerfile +FROM node:20-alpine +RUN npm install -g check-engine@latest +WORKDIR /workspace +ENTRYPOINT ["check-engine"] +``` + +--- + +#### 2. Standard Image (`check-engine:latest`, `check-engine:standard`) +**Purpose:** Image with common development tools pre-installed + +**Contents:** +- Node.js runtime +- check-engine package +- git +- npm, yarn, pnpm +- Common build tools + +**Size Target:** <200MB +**Use Case:** Most common scenarios, general development environment validation + +```dockerfile +FROM node:20-alpine + +# Install common tools +RUN apk add --no-cache \ + git \ + python3 \ + make \ + g++ \ + && npm install -g check-engine@latest yarn pnpm + +WORKDIR /workspace +ENTRYPOINT ["check-engine"] +``` + +--- + +#### 3. Full Image (`check-engine:full`) +**Purpose:** Comprehensive image with extensive tooling for complex projects + +**Contents:** +- All tools from Standard image +- Additional language runtimes (Python, Ruby, Go) +- Cloud CLIs (aws, gcloud, az) +- Container tools (docker client) +- Build tools (gradle, maven) +- Additional utilities + +**Size Target:** <500MB +**Use Case:** Complex multi-language projects, full environment validation + +```dockerfile +FROM node:20 + +# Install comprehensive tooling +RUN apt-get update && apt-get install -y \ + git \ + python3 \ + ruby \ + golang \ + default-jdk \ + maven \ + gradle \ + && npm install -g check-engine@latest yarn pnpm bower \ + && apt-get clean \ + && rm -rf /var/lib/apt/lists/* + +# Install cloud CLIs +RUN curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" \ + && unzip awscliv2.zip \ + && ./aws/install \ + && rm -rf aws awscliv2.zip + +WORKDIR /workspace +ENTRYPOINT ["check-engine"] +``` + +--- + +## Multi-Stage Build Strategy + +### Build Stage +Optimize builds with multi-stage Dockerfiles: + +```dockerfile +# Stage 1: Build/Install +FROM node:20-alpine AS builder +WORKDIR /build +COPY package*.json ./ +RUN npm ci --only=production + +# Stage 2: Runtime +FROM node:20-alpine +RUN apk add --no-cache git +WORKDIR /app + +# Copy from builder +COPY --from=builder /build/node_modules ./node_modules +COPY . . + +# Security: Run as non-root +RUN addgroup -g 1001 -S checkengine && \ + adduser -S -D -H -u 1001 -s /sbin/nologin -G checkengine checkengine && \ + chown -R checkengine:checkengine /app + +USER checkengine + +ENTRYPOINT ["node", "/app/bin/check-engine.js"] +``` + +**Benefits:** +- Smaller final image +- No build dependencies in production image +- Better layer caching +- Improved security + +--- + +## Multi-Architecture Support + +### Supported Architectures +- `linux/amd64` (Intel/AMD 64-bit) +- `linux/arm64` (ARM 64-bit, Apple M1/M2, AWS Graviton) +- `linux/arm/v7` (ARM 32-bit, Raspberry Pi) + +### Build Configuration + +Using Docker Buildx for multi-architecture builds: + +```bash +# Create builder +docker buildx create --name multi-arch-builder --use + +# Build for multiple platforms +docker buildx build \ + --platform linux/amd64,linux/arm64,linux/arm/v7 \ + --tag ghcr.io/mohlsen/check-engine:latest \ + --push \ + . +``` + +### GitHub Actions Integration + +```yaml +name: Build Multi-Arch Images + +on: + push: + tags: + - 'v*' + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up QEMU + uses: docker/setup-qemu-action@v3 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Login to GHCR + uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Extract metadata + id: meta + uses: docker/metadata-action@v5 + with: + images: ghcr.io/mohlsen/check-engine + tags: | + type=semver,pattern={{version}} + type=semver,pattern={{major}}.{{minor}} + type=semver,pattern={{major}} + type=raw,value=latest,enable={{is_default_branch}} + + - name: Build and push + uses: docker/build-push-action@v5 + with: + context: . + platforms: linux/amd64,linux/arm64,linux/arm/v7 + push: true + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + cache-from: type=gha + cache-to: type=gha,mode=max +``` + +--- + +## Image Tagging Strategy + +### Semantic Versioning Tags +``` +ghcr.io/mohlsen/check-engine:1.15.0 # Specific version +ghcr.io/mohlsen/check-engine:1.15 # Minor version +ghcr.io/mohlsen/check-engine:1 # Major version +ghcr.io/mohlsen/check-engine:latest # Latest release +``` + +### Variant Tags +``` +ghcr.io/mohlsen/check-engine:base # Minimal +ghcr.io/mohlsen/check-engine:standard # Standard (default) +ghcr.io/mohlsen/check-engine:full # Full tooling +ghcr.io/mohlsen/check-engine:1.15.0-base # Version + variant +``` + +### Additional Tags +``` +ghcr.io/mohlsen/check-engine:edge # Latest from main branch +ghcr.io/mohlsen/check-engine:sha-abc123 # Specific commit +ghcr.io/mohlsen/check-engine:pr-42 # Pull request preview +``` + +--- + +## Security Best Practices + +### 1. Non-Root User +Always run as non-root user: + +```dockerfile +# Create user +RUN addgroup -g 1001 -S checkengine && \ + adduser -S -D -H -u 1001 -s /sbin/nologin -G checkengine checkengine + +# Switch to user +USER checkengine +``` + +### 2. Minimal Base Images +Use Alpine or distroless images: + +```dockerfile +# Alpine (small, has shell) +FROM node:20-alpine + +# Distroless (no shell, most secure) +FROM gcr.io/distroless/nodejs20-debian12 +``` + +### 3. Security Scanning +Integrate security scanning in CI/CD: + +```yaml +- name: Run Trivy scanner + uses: aquasecurity/trivy-action@master + with: + image-ref: ghcr.io/mohlsen/check-engine:latest + format: 'sarif' + output: 'trivy-results.sarif' + +- name: Upload Trivy results + uses: github/codeql-action/upload-sarif@v2 + with: + sarif_file: 'trivy-results.sarif' +``` + +### 4. No Secrets in Images +- Never bake secrets into images +- Use build secrets for private packages: + +```dockerfile +# Mount secret during build +RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \ + npm ci --only=production +``` + +### 5. Vulnerability Patching +- Regular base image updates +- Automated dependency updates via Dependabot +- Monitor CVE databases + +--- + +## Docker Compose Integration + +### Development Environment + +```yaml +# docker-compose.yml +version: '3.8' + +services: + check-engine: + image: ghcr.io/mohlsen/check-engine:latest + volumes: + - .:/workspace:ro + working_dir: /workspace + command: ["/workspace/package.json"] + environment: + - NODE_ENV=development + + # With custom package.json + check-custom: + image: ghcr.io/mohlsen/check-engine:latest + volumes: + - ./custom-package.json:/app/package.json:ro + command: ["/app/package.json"] + + # Full variant for complex projects + check-full: + image: ghcr.io/mohlsen/check-engine:full + volumes: + - .:/workspace:ro + working_dir: /workspace +``` + +### CI/CD Integration + +```yaml +# docker-compose.ci.yml +version: '3.8' + +services: + validate: + image: ghcr.io/mohlsen/check-engine:standard + volumes: + - .:/workspace:ro + working_dir: /workspace + command: ["/workspace/package.json"] + + # Run in CI + ci-check: + image: ghcr.io/mohlsen/check-engine:standard + volumes: + - ./package.json:/package.json:ro + command: ["/package.json", "--ignore"] + exit_code_from: 0 +``` + +--- + +## Usage Examples + +### Basic Usage + +```bash +# Pull image +docker pull ghcr.io/mohlsen/check-engine:latest + +# Run with current directory mounted +docker run --rm -v $(pwd):/workspace \ + ghcr.io/mohlsen/check-engine:latest \ + /workspace/package.json + +# Run with specific variant +docker run --rm -v $(pwd):/workspace \ + ghcr.io/mohlsen/check-engine:full \ + /workspace/package.json +``` + +### CI/CD Integration + +#### GitHub Actions +```yaml +jobs: + validate: + runs-on: ubuntu-latest + container: + image: ghcr.io/mohlsen/check-engine:standard + steps: + - uses: actions/checkout@v4 + - name: Validate environment + run: check-engine package.json +``` + +#### GitLab CI +```yaml +validate: + image: ghcr.io/mohlsen/check-engine:standard + script: + - check-engine package.json +``` + +#### Jenkins +```groovy +pipeline { + agent { + docker { + image 'ghcr.io/mohlsen/check-engine:standard' + } + } + stages { + stage('Validate') { + steps { + sh 'check-engine package.json' + } + } + } +} +``` + +### Local Development + +```bash +# Create alias for convenience +alias check-engine='docker run --rm -v $(pwd):/workspace ghcr.io/mohlsen/check-engine:latest /workspace/package.json' + +# Use like native command +check-engine + +# With options +check-engine --ignore +``` + +--- + +## Kubernetes Integration + +### Job for One-Time Validation + +```yaml +apiVersion: batch/v1 +kind: Job +metadata: + name: environment-validation +spec: + template: + spec: + restartPolicy: Never + containers: + - name: check-engine + image: ghcr.io/mohlsen/check-engine:standard + command: ["check-engine"] + args: ["/config/package.json"] + volumeMounts: + - name: config + mountPath: /config + readOnly: true + volumes: + - name: config + configMap: + name: package-json +``` + +### InitContainer for Pre-Deployment Validation + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: my-app +spec: + template: + spec: + initContainers: + - name: validate-environment + image: ghcr.io/mohlsen/check-engine:standard + command: ["check-engine"] + args: ["/config/package.json"] + volumeMounts: + - name: config + mountPath: /config + readOnly: true + + containers: + - name: app + image: my-app:latest + # ... app configuration + + volumes: + - name: config + configMap: + name: package-json +``` + +### CronJob for Periodic Validation + +```yaml +apiVersion: batch/v1 +kind: CronJob +metadata: + name: environment-check +spec: + schedule: "0 */6 * * *" # Every 6 hours + jobTemplate: + spec: + template: + spec: + restartPolicy: OnFailure + containers: + - name: check-engine + image: ghcr.io/mohlsen/check-engine:standard + command: ["check-engine"] + args: ["/config/package.json"] + volumeMounts: + - name: config + mountPath: /config + readOnly: true + volumes: + - name: config + configMap: + name: package-json +``` + +--- + +## Performance Optimization + +### 1. Layer Caching +Order Dockerfile commands from least to most frequently changing: + +```dockerfile +# Base layers (change rarely) +FROM node:20-alpine +RUN apk add --no-cache git + +# Dependencies (change occasionally) +COPY package*.json ./ +RUN npm ci --only=production + +# Application code (changes frequently) +COPY . . +``` + +### 2. .dockerignore +Exclude unnecessary files: + +``` +node_modules +npm-debug.log +.git +.github +.vscode +.DS_Store +*.md +!README.md +test +*.test.js +*.spec.js +coverage +.nyc_output +dist +build +``` + +### 3. Build Cache +Use BuildKit cache mounts: + +```dockerfile +RUN --mount=type=cache,target=/root/.npm \ + npm ci --only=production +``` + +### 4. Parallel Builds +Use GitHub Actions matrix for parallel builds: + +```yaml +strategy: + matrix: + variant: [base, standard, full] + platform: [linux/amd64, linux/arm64] +``` + +--- + +## Monitoring and Debugging + +### Health Check +Add health check to Dockerfile: + +```dockerfile +HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \ + CMD check-engine --version || exit 1 +``` + +### Logging +Configure for container environments: + +```dockerfile +ENV NODE_ENV=production +ENV LOG_LEVEL=info +ENV LOG_FORMAT=json +``` + +### Debugging +Enable debug mode: + +```bash +# Run with debug +docker run --rm -e DEBUG=check-engine:* \ + ghcr.io/mohlsen/check-engine:latest \ + package.json + +# Interactive shell for debugging +docker run --rm -it --entrypoint /bin/sh \ + ghcr.io/mohlsen/check-engine:latest +``` + +--- + +## Distribution Strategy + +### Primary: GitHub Container Registry (GHCR) +``` +ghcr.io/mohlsen/check-engine +``` + +**Advantages:** +- Free for public repositories +- Integrated with GitHub +- Automatic authentication +- Good performance + +### Secondary: Docker Hub +``` +docker.io/mohlsen/check-engine +``` + +**Advantages:** +- Most popular registry +- Better discoverability +- Broader compatibility + +### Image Synchronization +Sync images between registries: + +```yaml +- name: Push to Docker Hub + uses: akhilerm/tag-push-action@v2.1.0 + with: + src: ghcr.io/mohlsen/check-engine:${{ github.ref_name }} + dst: docker.io/mohlsen/check-engine:${{ github.ref_name }} +``` + +--- + +## Testing Strategy + +### 1. Build Testing +Test that images build successfully: + +```bash +docker build --target base -t check-engine:base . +docker build --target standard -t check-engine:standard . +docker build --target full -t check-engine:full . +``` + +### 2. Functionality Testing +Test that check-engine works in containers: + +```bash +# Test basic functionality +docker run --rm check-engine:standard --version + +# Test with sample package.json +docker run --rm -v ./test:/workspace check-engine:standard /workspace/package.json +``` + +### 3. Security Testing +Scan images for vulnerabilities: + +```bash +# Trivy scan +trivy image ghcr.io/mohlsen/check-engine:latest + +# Grype scan +grype ghcr.io/mohlsen/check-engine:latest +``` + +### 4. Size Testing +Monitor image sizes: + +```bash +docker images | grep check-engine +``` + +Target sizes: +- Base: <50MB +- Standard: <200MB +- Full: <500MB + +--- + +## Documentation Requirements + +### README Additions +- Container usage section +- Quick start with Docker +- Links to image registry +- Common use cases + +### Separate Container Docs +Create `docs/container-usage.md`: +- Detailed usage examples +- Kubernetes integration +- CI/CD examples +- Troubleshooting +- Custom image building + +--- + +## Migration Path + +### Phase 1: Create Basic Images +1. Create Dockerfile for base variant +2. Set up GitHub Actions for building +3. Push to GHCR +4. Document basic usage + +### Phase 2: Add Variants +1. Create standard variant +2. Create full variant +3. Add multi-arch support +4. Improve documentation + +### Phase 3: Advanced Features +1. Add Kubernetes manifests +2. Create Helm chart +3. Add cloud platform examples +4. Create comprehensive docs + +### Phase 4: Optimization +1. Optimize build times +2. Reduce image sizes +3. Improve caching +4. Performance tuning + +--- + +## Success Metrics + +### Build Metrics +- ✅ Build time <5 minutes per variant +- ✅ All variants build successfully +- ✅ Multi-arch support working + +### Size Metrics +- ✅ Base image <50MB +- ✅ Standard image <200MB +- ✅ Full image <500MB + +### Security Metrics +- ✅ Zero high/critical vulnerabilities +- ✅ Running as non-root +- ✅ No secrets in images + +### Usage Metrics +- ✅ Documentation complete +- ✅ Examples working +- ✅ Community feedback positive + +--- + +## Conclusion + +This containerization strategy provides a comprehensive approach to making check-engine container-ready. By offering multiple variants, supporting multiple architectures, and following security best practices, we ensure that check-engine can be used effectively in modern containerized and cloud-native environments. + +The phased approach allows for incremental implementation while maintaining quality and security standards. The resulting container images will be secure, efficient, and easy to use across a variety of platforms and use cases. + diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md new file mode 100644 index 0000000..117698f --- /dev/null +++ b/IMPLEMENTATION_PLAN.md @@ -0,0 +1,1193 @@ +# check-engine Modernization Implementation Plan + +**Document Version:** 1.0 +**Date:** 2025-11-08 +**Status:** Planning Phase + +## Overview + +This document provides a detailed, step-by-step implementation plan for modernizing the check-engine project. It breaks down each recommendation into actionable tasks with estimated effort, dependencies, and acceptance criteria. + +--- + +## Phase 1: Foundation (Weeks 1-2) + +**Goal:** Address critical security, stability, and basic modernization needs. + +### 1.1 Runtime & Dependency Updates + +**Priority:** HIGH | **Effort:** 2-3 days + +#### Tasks + +**1.1.1 Update Node.js Requirements** +- [ ] Update `package.json` engines field to `"node": ">=18.0.0"` +- [ ] Update CI/CD workflows to test on Node 18, 20, 22 +- [ ] Test all functionality on each supported version +- [ ] Document breaking change in migration guide + +**Dependencies:** None +**Acceptance Criteria:** +- All tests pass on Node 18.x, 20.x, 22.x +- CI runs successfully on all versions +- Documentation updated + +--- + +**1.1.2 Update Core Dependencies** +- [ ] Update `semver` to latest (7.6.x) +- [ ] Update `yargs` to latest (17.7.x) +- [ ] Update `jsonfile` to latest (6.1.x) +- [ ] Review if `jsonfile` can be replaced with native `fs.readFile` + `JSON.parse` +- [ ] Run tests after each update + +**Dependencies:** None +**Acceptance Criteria:** +- All dependencies at latest stable versions +- All tests pass +- No new security vulnerabilities + +--- + +**1.1.3 Replace/Modernize Legacy Dependencies** +- [ ] Evaluate removing `bluebird` in favor of native async/await +- [ ] Replace `colors` with `chalk` or native ANSI codes +- [ ] Update `command-line-usage` if newer version available +- [ ] Create adapter layer if needed for backward compatibility + +**Dependencies:** None +**Acceptance Criteria:** +- Native promises used throughout +- Modern color library integrated +- All tests pass +- API remains backward compatible + +--- + +**1.1.4 Update DevDependencies** +- [ ] Update ESLint to 8.x (prepare for 9.x in Phase 2) +- [ ] Update test dependencies (`tape`, `tap-min`) +- [ ] Update `proxyquire` if still needed +- [ ] Run linter and tests after updates + +**Dependencies:** None +**Acceptance Criteria:** +- All dev dependencies updated +- Linter and tests work correctly +- No breaking changes in developer workflow + +--- + +### 1.2 Security Enhancements + +**Priority:** HIGH | **Effort:** 1-2 days + +#### Tasks + +**1.2.1 Fix Current Vulnerabilities** +- [ ] Run `npm audit fix` to address brace-expansion vulnerability +- [ ] Run `npm audit fix` to address cross-spawn vulnerability +- [ ] Verify fixes don't break functionality +- [ ] Run full test suite +- [ ] Document any manual fixes needed + +**Dependencies:** None +**Acceptance Criteria:** +- `npm audit` shows 0 vulnerabilities +- All tests pass +- No functionality broken + +--- + +**1.2.2 Add Security Workflows** +- [ ] Create `.github/workflows/security.yml` +- [ ] Add npm audit check to CI +- [ ] Add CodeQL workflow for static analysis +- [ ] Add Dependabot security alerts (already configured) +- [ ] Configure branch protection rules + +**Example Security Workflow:** +```yaml +name: Security + +on: + push: + branches: [master] + pull_request: + branches: [master] + schedule: + - cron: '0 0 * * 0' # Weekly + +jobs: + audit: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: '20' + - run: npm ci + - run: npm audit --audit-level=moderate +``` + +**Dependencies:** None +**Acceptance Criteria:** +- Security workflow runs on every PR +- CodeQL scans complete successfully +- Alerts configured in GitHub + +--- + +**1.2.3 Create Security Documentation** +- [ ] Create `SECURITY.md` with: + - Supported versions + - Vulnerability reporting process + - Security update policy + - Contact information +- [ ] Add security badge to README +- [ ] Document security best practices for contributors + +**Dependencies:** None +**Acceptance Criteria:** +- SECURITY.md exists and is comprehensive +- README links to security policy +- Clear reporting process + +--- + +### 1.3 Documentation Enhancements + +**Priority:** HIGH | **Effort:** 2-3 days + +#### Tasks + +**1.3.1 Create CONTRIBUTING.md** +- [ ] Write development setup instructions +- [ ] Document coding standards +- [ ] Explain PR process +- [ ] Add commit message guidelines +- [ ] Include testing requirements +- [ ] Add release process documentation + +**Template Structure:** +```markdown +# Contributing to check-engine + +## Development Setup +## Coding Standards +## Testing +## Pull Request Process +## Release Process +## Code of Conduct +``` + +**Dependencies:** None +**Acceptance Criteria:** +- CONTRIBUTING.md is comprehensive +- New contributors can follow it easily +- All common questions answered + +--- + +**1.3.2 Create CHANGELOG.md** +- [ ] Set up Keep a Changelog format +- [ ] Document all previous releases (extract from git tags) +- [ ] Set up automated changelog generation +- [ ] Link from README + +**Dependencies:** None +**Acceptance Criteria:** +- CHANGELOG.md follows Keep a Changelog format +- All versions documented +- Linked from README + +--- + +**1.3.3 Add CODE_OF_CONDUCT.md** +- [ ] Adopt Contributor Covenant or similar +- [ ] Add contact information for violations +- [ ] Link from README and CONTRIBUTING + +**Dependencies:** None +**Acceptance Criteria:** +- CODE_OF_CONDUCT.md present +- Contact method clear +- Linked from other docs + +--- + +**1.3.4 Enhance README.md** +- [ ] Add badges (build status, coverage, version, downloads) +- [ ] Improve examples section +- [ ] Add troubleshooting section +- [ ] Add FAQ section +- [ ] Update installation instructions +- [ ] Add links to new documentation +- [ ] Add screenshots/animated GIFs if applicable + +**Dependencies:** 1.3.1, 1.3.2, 1.3.3 +**Acceptance Criteria:** +- README is comprehensive and well-organized +- Examples cover common use cases +- Professional appearance + +--- + +**1.3.5 Create Advanced Documentation** +- [ ] Create `docs/` folder +- [ ] Write architecture overview +- [ ] Document validator system design +- [ ] Create guide for adding new validators +- [ ] Write integration examples +- [ ] Create API reference + +**Dependencies:** None +**Acceptance Criteria:** +- docs/ folder structure clear +- All key topics covered +- Examples work correctly + +--- + +### 1.4 Containerization Support + +**Priority:** HIGH | **Effort:** 2-3 days + +#### Tasks + +**1.4.1 Create Dockerfile** +- [ ] Create multi-stage Dockerfile +- [ ] Install necessary system tools (git, etc.) +- [ ] Optimize image size +- [ ] Use Alpine or slim base image +- [ ] Support multiple architectures (amd64, arm64) +- [ ] Add health check + +**Example Dockerfile:** +```dockerfile +# Build stage +FROM node:20-alpine AS builder +WORKDIR /app +COPY package*.json ./ +RUN npm ci --only=production + +# Production stage +FROM node:20-alpine +RUN apk add --no-cache git +WORKDIR /app +COPY --from=builder /app/node_modules ./node_modules +COPY . . +ENTRYPOINT ["node", "/app/bin/check-engine.js"] +CMD ["--help"] +``` + +**Dependencies:** None +**Acceptance Criteria:** +- Dockerfile builds successfully +- Image size optimized (<100MB) +- Works on amd64 and arm64 +- All validators work in container + +--- + +**1.4.2 Create docker-compose.yml** +- [ ] Set up docker-compose for local development +- [ ] Mount local directory for testing +- [ ] Configure environment variables +- [ ] Add examples for different use cases + +**Dependencies:** 1.4.1 +**Acceptance Criteria:** +- docker-compose.yml works correctly +- Examples documented +- Easy to use for testing + +--- + +**1.4.3 Create .dockerignore** +- [ ] Exclude node_modules +- [ ] Exclude .git +- [ ] Exclude test files +- [ ] Exclude development files + +**Dependencies:** None +**Acceptance Criteria:** +- Build is faster +- Image is smaller +- No unnecessary files + +--- + +**1.4.4 Add Container Documentation** +- [ ] Document how to build image +- [ ] Document how to use image +- [ ] Provide usage examples +- [ ] Document environment variables +- [ ] Add to README + +**Dependencies:** 1.4.1, 1.4.2 +**Acceptance Criteria:** +- Documentation clear and complete +- Examples work +- Common issues addressed + +--- + +**1.4.5 Set up Container Registry** +- [ ] Configure GitHub Actions for image building +- [ ] Push to GitHub Container Registry (ghcr.io) +- [ ] Tag images appropriately (latest, version, sha) +- [ ] Document how to pull images +- [ ] Consider Docker Hub publication + +**Dependencies:** 1.4.1 +**Acceptance Criteria:** +- Images automatically built on release +- Images available on ghcr.io +- Versioning clear +- Pull instructions documented + +--- + +## Phase 2: Modernization (Weeks 3-4) + +**Goal:** Improve development experience and code quality. + +### 2.1 Code Quality Tooling + +**Priority:** MEDIUM | **Effort:** 1-2 days + +#### Tasks + +**2.1.1 Update ESLint Configuration** +- [ ] Migrate to ESLint v9 flat config +- [ ] Update rules for modern JavaScript +- [ ] Add TypeScript support (if implementing TypeScript) +- [ ] Configure for ES modules +- [ ] Add custom rules if needed + +**Dependencies:** None +**Acceptance Criteria:** +- ESLint 9.x working +- All rules appropriate +- No errors on existing code +- Documentation updated + +--- + +**2.1.2 Add Prettier** +- [ ] Install Prettier +- [ ] Create `.prettierrc` configuration +- [ ] Create `.prettierignore` +- [ ] Format all existing code +- [ ] Add prettier check to CI +- [ ] Integrate with ESLint + +**Dependencies:** None +**Acceptance Criteria:** +- All code formatted consistently +- CI checks formatting +- No conflicts with ESLint + +--- + +**2.1.3 Set up Husky and lint-staged** +- [ ] Install husky +- [ ] Install lint-staged +- [ ] Configure pre-commit hook +- [ ] Configure commit-msg hook (for commitlint) +- [ ] Test hooks work correctly + +**Dependencies:** 2.1.1, 2.1.2 +**Acceptance Criteria:** +- Git hooks work correctly +- Bad code can't be committed +- Commit messages validated + +--- + +**2.1.4 Add commitlint** +- [ ] Install commitlint +- [ ] Configure for conventional commits +- [ ] Add commit-msg hook +- [ ] Document commit format +- [ ] Update CONTRIBUTING.md + +**Dependencies:** 2.1.3 +**Acceptance Criteria:** +- Commit messages validated +- Conventional commits enforced +- Documentation clear + +--- + +**2.1.5 Add EditorConfig** +- [ ] Create `.editorconfig` +- [ ] Configure indentation, line endings, etc. +- [ ] Document in CONTRIBUTING.md + +**Dependencies:** None +**Acceptance Criteria:** +- EditorConfig file present +- Consistent editor settings +- Works across IDEs + +--- + +### 2.2 Testing Modernization + +**Priority:** MEDIUM | **Effort:** 2-4 days + +#### Tasks + +**2.2.1 Choose and Set up Modern Test Framework** +- [ ] Decide between Jest and Vitest +- [ ] Install chosen framework +- [ ] Configure test framework +- [ ] Set up coverage reporting +- [ ] Configure for both unit and integration tests + +**Recommendation:** Vitest for modern projects, Jest for broader ecosystem + +**Dependencies:** None +**Acceptance Criteria:** +- Test framework installed +- Basic tests run +- Coverage reports generated + +--- + +**2.2.2 Migrate Existing Tests** +- [ ] Convert checkSystem.spec.js +- [ ] Convert validatorRules.spec.js +- [ ] Ensure all tests pass +- [ ] Maintain or improve coverage +- [ ] Remove tape and tap-min + +**Dependencies:** 2.2.1 +**Acceptance Criteria:** +- All tests migrated +- All tests pass +- Coverage maintained or improved +- Old framework removed + +--- + +**2.2.3 Add Integration Tests** +- [ ] Create integration test suite +- [ ] Test CLI with various inputs +- [ ] Test programmatic API +- [ ] Test error conditions +- [ ] Test with different package.json configurations + +**Dependencies:** 2.2.1 +**Acceptance Criteria:** +- Integration tests cover main workflows +- Tests run in CI +- Tests are reliable + +--- + +**2.2.4 Set up Coverage Reporting** +- [ ] Configure coverage thresholds (>80%) +- [ ] Add coverage to CI +- [ ] Upload coverage to Codecov or Coveralls +- [ ] Add coverage badge to README +- [ ] Block PRs that decrease coverage + +**Dependencies:** 2.2.1, 2.2.2 +**Acceptance Criteria:** +- Coverage tracked automatically +- Badge shows current coverage +- CI fails on coverage decrease + +--- + +**2.2.5 Add E2E Tests** +- [ ] Create E2E test suite +- [ ] Test with real package.json files +- [ ] Test with real system tools +- [ ] Test container usage +- [ ] Test CLI output formats + +**Dependencies:** 2.2.1 +**Acceptance Criteria:** +- E2E tests cover critical paths +- Tests run reliably +- Tests catch real issues + +--- + +### 2.3 TypeScript Migration + +**Priority:** MEDIUM | **Effort:** 3-5 days + +#### Tasks + +**2.3.1 Set up TypeScript** +- [ ] Install TypeScript +- [ ] Create `tsconfig.json` +- [ ] Configure for Node.js +- [ ] Set up build process +- [ ] Configure source maps + +**Dependencies:** None +**Acceptance Criteria:** +- TypeScript compiles successfully +- Source maps work +- Build output correct + +--- + +**2.3.2 Add Type Definitions** +- [ ] Create `src/types/` folder +- [ ] Define interfaces for public API +- [ ] Define types for internal structures +- [ ] Export types for consumers +- [ ] Generate .d.ts files + +**Dependencies:** 2.3.1 +**Acceptance Criteria:** +- Type definitions complete +- Types exported correctly +- IDE autocomplete works + +--- + +**2.3.3 Convert Core Files** +- [ ] Convert checkSystem.js to .ts +- [ ] Convert validatorRules.js to .ts +- [ ] Convert promiseHelpers.js to .ts +- [ ] Convert bin/check-engine.js to .ts +- [ ] Fix all type errors + +**Dependencies:** 2.3.1, 2.3.2 +**Acceptance Criteria:** +- All files converted +- No type errors +- All tests pass + +--- + +**2.3.4 Update Tests for TypeScript** +- [ ] Convert test files to .ts +- [ ] Add type assertions +- [ ] Fix any type issues +- [ ] Ensure coverage maintained + +**Dependencies:** 2.3.3, 2.2.2 +**Acceptance Criteria:** +- Test files converted +- All tests pass +- Type safety in tests + +--- + +**2.3.5 Update Build and Release Process** +- [ ] Update package.json scripts +- [ ] Configure TypeScript compilation +- [ ] Set up pre-publish build +- [ ] Test published package +- [ ] Update documentation + +**Dependencies:** 2.3.3 +**Acceptance Criteria:** +- Build process works +- Package publishes correctly +- Types available to consumers + +--- + +### 2.4 CI/CD Pipeline Enhancements + +**Priority:** MEDIUM | **Effort:** 2-3 days + +#### Tasks + +**2.4.1 Separate Workflows** +- [ ] Create `pull_request.yml` workflow +- [ ] Create `release.yml` workflow +- [ ] Create `security.yml` workflow +- [ ] Create `docker.yml` workflow +- [ ] Update existing `validation.yml` + +**Dependencies:** None +**Acceptance Criteria:** +- Each workflow has clear purpose +- No duplicate work +- Fast feedback + +--- + +**2.4.2 Add Multi-Platform Testing** +- [ ] Test on Ubuntu (already done) +- [ ] Test on macOS +- [ ] Test on Windows +- [ ] Matrix test Node versions (18, 20, 22) +- [ ] Optimize for speed + +**Dependencies:** None +**Acceptance Criteria:** +- Tests run on all platforms +- Platform-specific issues caught +- CI completes in <10 minutes + +--- + +**2.4.3 Add Release Automation** +- [ ] Install release-please +- [ ] Configure release-please +- [ ] Automate version bumping +- [ ] Automate CHANGELOG updates +- [ ] Automate GitHub releases +- [ ] Automate npm publishing + +**Dependencies:** 1.3.2 +**Acceptance Criteria:** +- Releases fully automated +- Changelog updated automatically +- npm package published automatically + +--- + +**2.4.4 Add Security Scanning** +- [ ] Add CodeQL workflow (from 1.2.2) +- [ ] Add dependency review +- [ ] Add SAST scanning +- [ ] Configure alerts +- [ ] Add security checks to PR workflow + +**Dependencies:** 1.2.2 +**Acceptance Criteria:** +- Security scans run automatically +- Vulnerabilities caught early +- Clear alerts on issues + +--- + +**2.4.5 Add Performance Benchmarking** +- [ ] Create benchmark suite +- [ ] Add benchmark workflow +- [ ] Track performance over time +- [ ] Alert on regressions +- [ ] Document benchmarks + +**Dependencies:** None +**Acceptance Criteria:** +- Benchmarks run automatically +- Performance tracked +- Regressions caught + +--- + +## Phase 3: Enhancement (Weeks 5-6) + +**Goal:** Add modern features and improve the API. + +### 3.1 API Modernization + +**Priority:** MEDIUM | **Effort:** 2-3 days + +#### Tasks + +**3.1.1 Remove Bluebird (if not done in Phase 1)** +- [ ] Convert all Promise usage to native +- [ ] Remove Bluebird dependency +- [ ] Update all async code +- [ ] Test thoroughly + +**Dependencies:** 1.1.3 +**Acceptance Criteria:** +- No Bluebird dependency +- All async code uses native promises +- All tests pass + +--- + +**3.1.2 Add ESM Support** +- [ ] Configure package.json for dual mode +- [ ] Create ESM entry point +- [ ] Maintain CJS compatibility +- [ ] Test both module formats +- [ ] Document usage + +**Dependencies:** 2.3.5 (if using TypeScript) +**Acceptance Criteria:** +- ESM and CJS both work +- Exports configured correctly +- Tests pass for both formats + +--- + +**3.1.3 Enhance Configuration Options** +- [ ] Add options object to check function +- [ ] Support timeout configuration +- [ ] Support parallel execution +- [ ] Support custom validators +- [ ] Support output formatting options + +**Example:** +```typescript +interface CheckOptions { + packageJsonPath?: string; + parallel?: boolean; + timeout?: number; + customValidators?: Record; + format?: 'json' | 'text' | 'yaml'; + onProgress?: (pkg: Package) => void; +} +``` + +**Dependencies:** 2.3.2 (if using TypeScript) +**Acceptance Criteria:** +- Options well documented +- All options work correctly +- Backward compatible +- Tests cover all options + +--- + +**3.1.4 Add Event-Based Progress** +- [ ] Implement EventEmitter or custom events +- [ ] Emit progress events +- [ ] Emit validation events +- [ ] Document events +- [ ] Add examples + +**Dependencies:** None +**Acceptance Criteria:** +- Events work correctly +- Documentation clear +- Examples provided + +--- + +**3.1.5 Improve Error Handling** +- [ ] Create custom error classes +- [ ] Add error codes +- [ ] Improve error messages +- [ ] Add context to errors +- [ ] Document errors + +**Dependencies:** None +**Acceptance Criteria:** +- Errors are clear and actionable +- Error codes documented +- Easy to debug + +--- + +### 3.2 Developer Experience Improvements + +**Priority:** MEDIUM | **Effort:** 1-2 days + +#### Tasks + +**3.2.1 Add VS Code Configuration** +- [ ] Create `.vscode/` folder +- [ ] Add recommended extensions +- [ ] Add debug configurations +- [ ] Add tasks for common operations +- [ ] Add settings + +**Dependencies:** None +**Acceptance Criteria:** +- VS Code configuration works +- Debugging easy +- Tasks useful + +--- + +**3.2.2 Improve Package Scripts** +- [ ] Add `dev` script with watch mode +- [ ] Add `build` script +- [ ] Add `coverage` script +- [ ] Add `docs` script +- [ ] Add `clean` script +- [ ] Document all scripts + +**Dependencies:** None +**Acceptance Criteria:** +- All scripts work +- Scripts documented +- Development workflow smooth + +--- + +**3.2.3 Add Codespaces Configuration** +- [ ] Create `.devcontainer/` folder +- [ ] Configure devcontainer.json +- [ ] Add necessary extensions +- [ ] Pre-install dependencies +- [ ] Test in Codespaces + +**Dependencies:** 1.4.1 +**Acceptance Criteria:** +- Codespaces works +- All tools available +- Fast startup + +--- + +**3.2.4 Add Gitpod Configuration** +- [ ] Create `.gitpod.yml` +- [ ] Configure environment +- [ ] Pre-install dependencies +- [ ] Test in Gitpod + +**Dependencies:** None +**Acceptance Criteria:** +- Gitpod works +- Environment ready +- Fast startup + +--- + +**3.2.5 Improve CLI UX** +- [ ] Add progress indicators +- [ ] Add verbose/debug mode +- [ ] Add quiet mode +- [ ] Improve error messages +- [ ] Add colors and formatting + +**Dependencies:** None +**Acceptance Criteria:** +- CLI more user-friendly +- Feedback clear +- Options well documented + +--- + +### 3.3 Kubernetes & Cloud-Native Support + +**Priority:** MEDIUM | **Effort:** 2-3 days + +#### Tasks + +**3.3.1 Create Kubernetes Manifests** +- [ ] Create Job manifest +- [ ] Create CronJob manifest +- [ ] Create InitContainer example +- [ ] Create ConfigMap for package.json +- [ ] Document usage + +**Dependencies:** 1.4.1 +**Acceptance Criteria:** +- Manifests work correctly +- Examples clear +- Documentation complete + +--- + +**3.3.2 Create Helm Chart** +- [ ] Initialize Helm chart +- [ ] Configure values.yaml +- [ ] Create templates +- [ ] Test chart installation +- [ ] Document usage + +**Dependencies:** 3.3.1 +**Acceptance Criteria:** +- Helm chart works +- Customizable via values +- Documentation complete + +--- + +**3.3.3 Add Cloud Platform Examples** +- [ ] Create AWS ECS example +- [ ] Create AWS EKS example +- [ ] Create Google Cloud Run example +- [ ] Create GKE example +- [ ] Create Azure ACI example +- [ ] Create AKS example + +**Dependencies:** 1.4.1 +**Acceptance Criteria:** +- Examples work +- Each platform documented +- Common pitfalls addressed + +--- + +**3.3.4 Create CI/CD Integration Examples** +- [ ] GitHub Actions example +- [ ] GitLab CI example +- [ ] Jenkins example +- [ ] CircleCI example +- [ ] Azure DevOps example + +**Dependencies:** 3.3.1 +**Acceptance Criteria:** +- Examples work +- Common patterns documented +- Easy to adapt + +--- + +### 3.4 Package Manager Modernization + +**Priority:** LOW-MEDIUM | **Effort:** 1-2 days + +#### Tasks + +**3.4.1 Add Bun Validator** +- [ ] Implement bun version check +- [ ] Add to validatorRules.js +- [ ] Add tests +- [ ] Document in README + +**Dependencies:** None +**Acceptance Criteria:** +- Bun validator works +- Tests pass +- Documented + +--- + +**3.4.2 Add Deno Validator** +- [ ] Implement deno version check +- [ ] Add to validatorRules.js +- [ ] Add tests +- [ ] Document in README + +**Dependencies:** None +**Acceptance Criteria:** +- Deno validator works +- Tests pass +- Documented + +--- + +**3.4.3 Add Volta Validator** +- [ ] Implement volta version check +- [ ] Add to validatorRules.js +- [ ] Add tests +- [ ] Document in README + +**Dependencies:** None +**Acceptance Criteria:** +- Volta validator works +- Tests pass +- Documented + +--- + +**3.4.4 Improve Existing Validators** +- [ ] Better version detection +- [ ] Support for version managers +- [ ] Better error messages +- [ ] Add more validation options + +**Dependencies:** None +**Acceptance Criteria:** +- Validators more robust +- Better user experience +- Tests comprehensive + +--- + +## Phase 4: Expansion (Weeks 7+) + +**Goal:** Optional enhancements and new features. + +### 4.1 Output & Reporting Enhancements + +**Priority:** LOW-MEDIUM | **Effort:** 1-2 days + +#### Tasks + +**4.1.1 Add Multiple Output Formats** +- [ ] Implement JSON format +- [ ] Implement YAML format +- [ ] Implement JUnit XML format +- [ ] Implement HTML format +- [ ] Implement Markdown format + +**Dependencies:** None +**Acceptance Criteria:** +- All formats work +- Formats well-formed +- Easy to switch formats + +--- + +**4.1.2 Improve Terminal Output** +- [ ] Better colors and formatting +- [ ] Add summary statistics +- [ ] Add icons/emojis +- [ ] Improve table layout +- [ ] Add progress bars + +**Dependencies:** None +**Acceptance Criteria:** +- Output looks professional +- Information clear +- Customizable + +--- + +**4.1.3 Add Custom Formatters** +- [ ] Allow custom formatter functions +- [ ] Document formatter API +- [ ] Provide examples +- [ ] Test custom formatters + +**Dependencies:** 4.1.1 +**Acceptance Criteria:** +- Custom formatters work +- API documented +- Examples clear + +--- + +### 4.2 Platform & Tool Expansion + +**Priority:** LOW | **Effort:** Variable + +#### Tasks + +**4.2.1 Add Container Tool Validators** +- [ ] Docker validator +- [ ] Podman validator +- [ ] Buildah validator + +**4.2.2 Add Cloud Tool Validators** +- [ ] kubectl validator +- [ ] helm validator +- [ ] terraform validator +- [ ] aws-cli validator +- [ ] gcloud validator +- [ ] az validator + +**4.2.3 Add Build Tool Validators** +- [ ] make validator +- [ ] cmake validator +- [ ] gradle validator +- [ ] maven validator (improve existing) + +**4.2.4 Add Language Runtime Validators** +- [ ] python validator +- [ ] ruby validator +- [ ] go validator +- [ ] rust validator + +**4.2.5 Add Version Manager Validators** +- [ ] nvm validator +- [ ] fnm validator +- [ ] asdf validator +- [ ] pyenv validator +- [ ] rbenv validator + +**4.2.6 Make Validators Pluggable** +- [ ] Design plugin system +- [ ] Implement plugin loader +- [ ] Document plugin API +- [ ] Provide examples + +--- + +### 4.3 Monitoring & Telemetry + +**Priority:** LOW | **Effort:** 1-2 days + +#### Tasks + +**4.3.1 Add Optional Telemetry** +- [ ] Implement opt-in telemetry +- [ ] Collect usage statistics +- [ ] Track error rates +- [ ] Respect user privacy +- [ ] Add opt-out instructions + +**4.3.2 Add Monitoring Integration** +- [ ] Add Prometheus metrics +- [ ] Add OpenTelemetry support +- [ ] Add StatsD support +- [ ] Add health check endpoint + +**4.3.3 Document Telemetry** +- [ ] What is collected +- [ ] How to opt out +- [ ] How data is used +- [ ] Privacy policy + +--- + +## Success Criteria + +### Phase 1 Complete +- ✅ Node.js 18+ required +- ✅ 0 security vulnerabilities +- ✅ Container image available +- ✅ Complete documentation +- ✅ Security policy in place + +### Phase 2 Complete +- ✅ Modern test framework +- ✅ >90% test coverage +- ✅ ESLint 9 + Prettier +- ✅ Pre-commit hooks working +- ✅ TypeScript support (optional) +- ✅ Automated releases + +### Phase 3 Complete +- ✅ Modern API with options +- ✅ ESM support +- ✅ Kubernetes examples +- ✅ Cloud platform examples +- ✅ Better DX with VS Code config + +### Phase 4 Complete +- ✅ Multiple output formats +- ✅ Extended validator library +- ✅ Plugin system (optional) +- ✅ Monitoring support (optional) + +--- + +## Risk Management + +### Technical Risks +- **Breaking changes:** Mitigate with semantic versioning and deprecation warnings +- **Test failures:** Maintain comprehensive test suite +- **Performance regression:** Add benchmarking +- **Compatibility issues:** Test on multiple platforms + +### Project Risks +- **Scope creep:** Stick to phased approach +- **Timeline delays:** Prioritize critical items +- **Resource constraints:** Focus on high-priority items first + +--- + +## Timeline Summary + +| Phase | Duration | Priority | Key Deliverables | +|-------|----------|----------|------------------| +| Phase 1 | 2 weeks | HIGH | Security, Docs, Containers | +| Phase 2 | 2 weeks | MEDIUM | Testing, TypeScript, CI/CD | +| Phase 3 | 2 weeks | MEDIUM | API, K8s, DX | +| Phase 4 | Ongoing | LOW | Expansion features | + +**Total Estimated Time:** 6-8 weeks for core modernization + +--- + +## Next Steps + +1. ✅ Review and approve this implementation plan +2. ⬜ Set up project board for tracking +3. ⬜ Begin Phase 1 implementation +4. ⬜ Regular progress reviews +5. ⬜ Community engagement and feedback + +--- + +## Notes + +- This is a living document and should be updated as work progresses +- Priorities may shift based on user feedback and real-world needs +- Some tasks may be parallelized for efficiency +- Community contributions welcome for any phase + diff --git a/MODERNIZATION_RECOMMENDATIONS.md b/MODERNIZATION_RECOMMENDATIONS.md new file mode 100644 index 0000000..e040111 --- /dev/null +++ b/MODERNIZATION_RECOMMENDATIONS.md @@ -0,0 +1,747 @@ +# check-engine Modernization Recommendations + +**Document Version:** 1.0 +**Date:** 2025-11-08 +**Status:** Planning Phase + +## Executive Summary + +The `check-engine` project is a valuable Node.js utility for validating development environment dependencies. While the core functionality remains solid, the project would benefit from modernization to align with current best practices, improve maintainability, and expand its utility in modern development workflows including containerized and cloud-native environments. + +## Current State Assessment + +### Strengths +- ✅ Working core functionality +- ✅ Good test coverage (91 tests passing) +- ✅ Active GitHub Actions CI/CD +- ✅ Dependabot configured for dependency updates +- ✅ Clean, readable codebase +- ✅ Semantic versioning support +- ✅ MIT License (permissive) + +### Areas for Improvement +- ⚠️ Node.js requirement outdated (>=10, should be >=18 or >=20) +- ⚠️ Security vulnerabilities in dependencies (2 identified) +- ⚠️ Legacy testing framework (tape) +- ⚠️ No TypeScript support +- ⚠️ No containerization support +- ⚠️ Missing documentation (CONTRIBUTING, CHANGELOG) +- ⚠️ Limited modern package manager support (no bun support) +- ⚠️ No Kubernetes/cloud-native examples +- ⚠️ No pre-commit hooks +- ⚠️ Basic linting configuration + +## Modernization Recommendations + +### 1. Runtime & Dependency Updates + +#### Priority: HIGH + +**Recommendation:** Update Node.js requirements and dependencies + +**Details:** +- Update minimum Node.js version to `>=18` (LTS) or `>=20` (current LTS) +- Update ESLint to latest version (v9.x with flat config) +- Replace `tape` with more modern testing framework (Jest or Vitest) +- Update `bluebird` promises to native async/await +- Fix security vulnerabilities via `npm audit fix` +- Consider replacing outdated dependencies: + - `colors` → `chalk` or native ANSI codes + - Consider if `jsonfile` is still needed vs native JSON methods + +**Benefits:** +- Improved performance and security +- Access to modern JavaScript features +- Better developer experience +- Reduced technical debt + +**Effort:** Medium (2-3 days) + +--- + +### 2. TypeScript Migration + +#### Priority: MEDIUM + +**Recommendation:** Add TypeScript support with gradual migration path + +**Details:** +- Add TypeScript configuration (tsconfig.json) +- Convert to TypeScript or add JSDoc type annotations +- Provide type definitions for programmatic API +- Maintain backward compatibility with JavaScript consumers +- Use TypeScript for new code + +**Benefits:** +- Better IDE support and autocomplete +- Catch errors at compile time +- Improved documentation through types +- Easier refactoring +- More maintainable codebase + +**Effort:** Medium-High (3-5 days for full migration, 1-2 days for types only) + +--- + +### 3. Testing Modernization + +#### Priority: MEDIUM + +**Recommendation:** Migrate to modern testing framework and enhance test coverage + +**Details:** +- **Option A:** Migrate to Jest + - Industry standard + - Built-in coverage reports + - Snapshot testing + - Better mocking capabilities + +- **Option B:** Migrate to Vitest + - Faster than Jest + - ESM-first + - Compatible with Jest API + - Better for modern projects + +- Add test coverage reporting +- Add integration tests +- Add e2e tests for CLI +- Set up code coverage thresholds (>80%) +- Add test coverage badges to README + +**Benefits:** +- Better testing experience +- More comprehensive test coverage +- Easier to write and maintain tests +- Visual coverage reports + +**Effort:** Medium (2-4 days) + +--- + +### 4. Code Quality Tooling + +#### Priority: MEDIUM + +**Recommendation:** Implement comprehensive code quality tools + +**Details:** +- Update ESLint to v9 with flat config +- Add Prettier for consistent formatting +- Add husky for git hooks +- Add lint-staged for pre-commit linting +- Add commitlint for conventional commits +- Configure EditorConfig +- Add JSDoc or TypeScript for documentation +- Consider adding Biome as a faster alternative + +**Example Pre-commit Hook:** +```json +{ + "husky": { + "hooks": { + "pre-commit": "lint-staged", + "commit-msg": "commitlint -E HUSKY_GIT_PARAMS" + } + }, + "lint-staged": { + "*.js": ["eslint --fix", "prettier --write"] + } +} +``` + +**Benefits:** +- Consistent code style +- Prevent bad commits +- Better commit history +- Automated code quality checks + +**Effort:** Low-Medium (1-2 days) + +--- + +### 5. Containerization Support + +#### Priority: HIGH + +**Recommendation:** Add Docker support for consistent development and deployment + +**Details:** +- Create multi-stage Dockerfile for production +- Create docker-compose.yml for local development +- Add .dockerignore file +- Create container image with all validator tools pre-installed +- Publish to Docker Hub or GitHub Container Registry +- Add Dockerfile linting with hadolint +- Support multiple architectures (amd64, arm64) + +**Example Use Cases:** +```bash +# Run check-engine in container +docker run --rm -v $(pwd):/app check-engine + +# Run with docker-compose for CI +docker-compose run check-engine +``` + +**Benefits:** +- Consistent environment across machines +- Easy CI/CD integration +- Pre-installed validator tools +- Portable and reproducible builds +- No local installation needed + +**Effort:** Medium (2-3 days) + +--- + +### 6. Kubernetes & Cloud-Native Support + +#### Priority: MEDIUM + +**Recommendation:** Add Kubernetes manifests and cloud-native deployment examples + +**Details:** +- Create Kubernetes Job manifest for validation +- Create Helm chart for easy deployment +- Add examples for: + - InitContainer for environment validation + - Job for pre-deployment checks + - CronJob for periodic validation +- Add examples for cloud platforms: + - AWS ECS/EKS + - Google Cloud Run/GKE + - Azure Container Instances/AKS +- Document integration with CI/CD pipelines + +**Example Kubernetes Job:** +```yaml +apiVersion: batch/v1 +kind: Job +metadata: + name: check-engine-validation +spec: + template: + spec: + containers: + - name: check-engine + image: check-engine:latest + command: ["check-engine", "/config/package.json"] + restartPolicy: Never +``` + +**Benefits:** +- Easy integration with Kubernetes workflows +- Pre-deployment validation +- Cloud-native deployment patterns +- Infrastructure as Code + +**Effort:** Medium (2-3 days) + +--- + +### 7. Documentation Enhancements + +#### Priority: HIGH + +**Recommendation:** Comprehensive documentation overhaul + +**Details:** +- Add CONTRIBUTING.md with: + - Development setup + - Coding standards + - PR process + - Release process +- Add CHANGELOG.md following Keep a Changelog format +- Add CODE_OF_CONDUCT.md +- Add SECURITY.md for vulnerability reporting +- Enhance README.md with: + - Badges (coverage, downloads, version) + - Better examples + - Troubleshooting section + - FAQ section +- Add API documentation +- Create docs/ folder with: + - Architecture overview + - Adding new validators guide + - Integration examples + - Migration guides + +**Benefits:** +- Better onboarding for contributors +- Clearer communication +- Professional appearance +- Easier to maintain and extend + +**Effort:** Medium (2-3 days) + +--- + +### 8. CI/CD Pipeline Enhancements + +#### Priority: MEDIUM + +**Recommendation:** Expand GitHub Actions workflows + +**Details:** +- Add separate workflows for: + - Pull request validation + - Main branch protection + - Release automation + - Security scanning + - Container image building + - NPM package publishing +- Add CodeQL for security analysis +- Add dependency review +- Add automatic PR labeling +- Add release-please for automated releases +- Add version bumping automation +- Test on multiple OS (Ubuntu, macOS, Windows) +- Add performance benchmarking + +**Example Additional Workflows:** +- `security.yml` - SAST/dependency scanning +- `release.yml` - Automated releases +- `docker.yml` - Container image building +- `performance.yml` - Benchmark tests + +**Benefits:** +- Automated release process +- Better security posture +- Multi-platform support +- Consistent quality gates + +**Effort:** Medium (2-3 days) + +--- + +### 9. Package Manager Modernization + +#### Priority: LOW-MEDIUM + +**Recommendation:** Add support for modern package managers + +**Details:** +- Add validators for: + - `bun` (modern, fast package manager) + - `deno` (secure JavaScript runtime) + - `volta` (version management) +- Improve existing validators: + - Better version detection + - Support for version managers (nvm, fnm, volta) +- Add `.npmrc` configuration +- Consider pnpm workspace support +- Add package.json validation + +**Benefits:** +- Support for modern tooling +- Better developer experience +- More comprehensive validation + +**Effort:** Low-Medium (1-2 days per validator) + +--- + +### 10. Security Enhancements + +#### Priority: HIGH + +**Recommendation:** Implement comprehensive security practices + +**Details:** +- Fix existing security vulnerabilities +- Add npm audit check to CI/CD +- Add Snyk or Dependabot alerts +- Implement security.txt +- Add SECURITY.md policy +- Use npm provenance +- Sign releases with GPG +- Add supply chain security: + - Lock file integrity checks + - Dependency pinning strategy + - Regular security audits + +**Benefits:** +- Improved security posture +- User trust +- Compliance with best practices +- Reduced attack surface + +**Effort:** Low-Medium (1-2 days) + +--- + +### 11. Developer Experience Improvements + +#### Priority: MEDIUM + +**Recommendation:** Enhance developer experience and tooling + +**Details:** +- Add VS Code configuration: + - Recommended extensions + - Debug configurations + - Tasks for common operations +- Add development scripts in package.json: + - `dev` - watch mode + - `build` - production build + - `coverage` - test coverage + - `docs` - generate documentation +- Add GitHub Codespaces configuration +- Add Gitpod configuration +- Improve error messages and debugging +- Add verbose/debug mode +- Add progress indicators for long operations + +**Benefits:** +- Faster onboarding +- Better debugging +- More productive development +- Consistent development environment + +**Effort:** Low-Medium (1-2 days) + +--- + +### 12. API Modernization + +#### Priority: MEDIUM + +**Recommendation:** Modernize the programmatic API + +**Details:** +- Convert to native async/await (remove Bluebird) +- Add ESM module support (maintain CJS compatibility) +- Provide better error handling +- Add streaming API for large operations +- Add event emitters for progress +- Improve return types and structure +- Add configuration options: + - Timeout settings + - Parallel execution + - Custom validators + - Output formatting + +**Example Modern API:** +```javascript +import { checkEngine } from 'check-engine'; + +try { + const result = await checkEngine({ + packageJsonPath: './package.json', + parallel: true, + timeout: 30000, + onProgress: (pkg) => console.log(`Checking ${pkg.name}...`) + }); + + if (!result.success) { + console.error(result.errors); + } +} catch (error) { + console.error('Failed to validate:', error); +} +``` + +**Benefits:** +- Modern JavaScript patterns +- Better error handling +- More flexible API +- Better performance options + +**Effort:** Medium (2-3 days) + +--- + +### 13. Output & Reporting Enhancements + +#### Priority: LOW-MEDIUM + +**Recommendation:** Improve output formats and reporting + +**Details:** +- Add multiple output formats: + - JSON (machine-readable) + - YAML + - JUnit XML (for CI/CD) + - HTML report + - Markdown +- Add colored, formatted output (currently uses colors package) +- Add summary statistics +- Add exit codes for different scenarios +- Add quiet mode +- Add verbose/debug mode +- Support for custom formatters +- Add badges/shields generation + +**Benefits:** +- Better CI/CD integration +- More flexible reporting +- Easier debugging +- Better user experience + +**Effort:** Low-Medium (1-2 days) + +--- + +### 14. Platform & Tool Expansion + +#### Priority: LOW + +**Recommendation:** Add validators for modern development tools + +**Details:** +- Add validators for: + - **Container Tools:** Docker, Podman, Buildah + - **Cloud Tools:** kubectl, helm, terraform, aws-cli, gcloud, az + - **Build Tools:** Make, CMake, Gradle, Maven + - **Language Runtimes:** Python, Ruby, Go, Rust, Java + - **Version Managers:** nvm, fnm, volta, asdf, pyenv, rbenv + - **Development Tools:** VS Code, direnv + - **Database Tools:** psql, mysql, redis-cli, mongosh +- Make validators pluggable/extensible +- Allow custom validators via configuration + +**Benefits:** +- More comprehensive validation +- Support for diverse tech stacks +- Extensible architecture +- Wider adoption potential + +**Effort:** Low-Medium per validator (0.5-1 day each) + +--- + +### 15. Monitoring & Telemetry + +#### Priority: LOW + +**Recommendation:** Add optional telemetry and monitoring + +**Details:** +- Add optional anonymous usage statistics +- Track which validators are most used +- Monitor error rates +- Integration with monitoring tools: + - Prometheus metrics endpoint + - OpenTelemetry support + - StatsD support +- Add health check endpoint (for containerized deployments) +- Respect user privacy with opt-in telemetry + +**Benefits:** +- Understand usage patterns +- Identify common issues +- Improve popular validators +- Better monitoring in production + +**Effort:** Low-Medium (1-2 days) + +--- + +## Implementation Priority Matrix + +### Phase 1: Foundation (Weeks 1-2) +**Critical updates for stability and security** + +1. ✅ Runtime & Dependency Updates (HIGH) +2. ✅ Security Enhancements (HIGH) +3. ✅ Documentation Enhancements (HIGH) +4. ✅ Containerization Support (HIGH) + +**Estimated Effort:** 8-11 days + +--- + +### Phase 2: Modernization (Weeks 3-4) +**Improve development experience and code quality** + +5. ✅ Code Quality Tooling (MEDIUM) +6. ✅ Testing Modernization (MEDIUM) +7. ✅ TypeScript Migration (MEDIUM) +8. ✅ CI/CD Pipeline Enhancements (MEDIUM) + +**Estimated Effort:** 10-14 days + +--- + +### Phase 3: Enhancement (Weeks 5-6) +**Add modern features and improve API** + +9. ✅ API Modernization (MEDIUM) +10. ✅ Developer Experience Improvements (MEDIUM) +11. ✅ Kubernetes & Cloud-Native Support (MEDIUM) +12. ✅ Package Manager Modernization (LOW-MEDIUM) + +**Estimated Effort:** 7-10 days + +--- + +### Phase 4: Expansion (Weeks 7+) +**Optional enhancements and new features** + +13. ✅ Output & Reporting Enhancements (LOW-MEDIUM) +14. ✅ Platform & Tool Expansion (LOW) +15. ✅ Monitoring & Telemetry (LOW) + +**Estimated Effort:** Variable (ongoing) + +--- + +## Technology Stack Recommendations + +### Core Dependencies (Proposed) +```json +{ + "dependencies": { + "semver": "^7.6.0", + "chalk": "^5.3.0", + "yargs": "^17.7.2", + "commander": "^12.0.0" + }, + "devDependencies": { + "typescript": "^5.3.3", + "vitest": "^1.0.4", + "@types/node": "^20.10.0", + "eslint": "^9.0.0", + "prettier": "^3.1.0", + "husky": "^9.0.0", + "lint-staged": "^15.0.0", + "tsx": "^4.7.0" + } +} +``` + +### Modern Tooling Stack +- **Runtime:** Node.js 20.x LTS (minimum 18.x) +- **Testing:** Vitest or Jest +- **Linting:** ESLint v9 with flat config +- **Formatting:** Prettier +- **Type Checking:** TypeScript 5.x or JSDoc +- **Git Hooks:** Husky + lint-staged +- **Container:** Docker with multi-stage builds +- **CI/CD:** GitHub Actions with matrix testing +- **Package Manager:** npm (primary), with pnpm/yarn/bun support +- **Documentation:** Markdown + JSDoc/TSDoc + +--- + +## Backward Compatibility Considerations + +### Must Maintain +- ✅ CLI interface and command-line arguments +- ✅ Programmatic API (check function) +- ✅ Return value structure +- ✅ package.json engines format +- ✅ Exit codes + +### Can Change (with deprecation notice) +- ⚠️ Internal API structure +- ⚠️ Validator implementation details +- ⚠️ Output formatting (with --legacy flag) + +### Breaking Changes (Major Version) +- 🔴 Minimum Node.js version (10 → 18) +- 🔴 Testing framework migration +- 🔴 ESM as default module format + +**Recommendation:** Release as v2.0.0 after Phase 1-2 completion + +--- + +## Success Metrics + +### Code Quality +- ✅ 0 security vulnerabilities +- ✅ >90% test coverage +- ✅ <5 minutes CI/CD pipeline +- ✅ 100% passing tests on all supported platforms +- ✅ 0 ESLint errors/warnings + +### Documentation +- ✅ CONTRIBUTING.md present +- ✅ CHANGELOG.md maintained +- ✅ API documentation complete +- ✅ Examples for common use cases + +### Community +- ✅ <48 hour response time to issues +- ✅ Regular releases (monthly or as-needed) +- ✅ Active contributor base +- ✅ Good GitHub health metrics + +### Performance +- ✅ <500ms overhead for validation +- ✅ Parallel validator execution +- ✅ Efficient caching + +--- + +## Risk Assessment + +### Low Risk +- Updating dependencies +- Adding documentation +- Adding container support +- CI/CD enhancements + +### Medium Risk +- Testing framework migration +- ESLint configuration changes +- TypeScript migration +- API modernization + +### High Risk +- Breaking changes to public API +- Minimum Node.js version bump +- Module format changes (CJS → ESM) + +**Mitigation Strategy:** +- Comprehensive testing before releases +- Beta releases for major changes +- Clear migration guides +- Deprecation warnings before breaking changes +- Semantic versioning strictly followed + +--- + +## Resources & References + +### Best Practices +- [Node.js Best Practices](https://github.com/goldbergyoni/nodebestpractices) +- [12 Factor App](https://12factor.net/) +- [Semantic Versioning](https://semver.org/) +- [Keep a Changelog](https://keepachangelog.com/) +- [Conventional Commits](https://www.conventionalcommits.org/) + +### Tools +- [GitHub Actions Documentation](https://docs.github.com/en/actions) +- [Docker Best Practices](https://docs.docker.com/develop/dev-best-practices/) +- [TypeScript Handbook](https://www.typescriptlang.org/docs/) +- [Vitest Documentation](https://vitest.dev/) +- [ESLint v9 Migration](https://eslint.org/docs/latest/use/migrate-to-9.0.0) + +--- + +## Conclusion + +The check-engine project has a solid foundation and serves a valuable purpose. By implementing these modernization recommendations, the project will: + +1. **Stay Relevant:** Support modern tools and workflows +2. **Be More Secure:** Address vulnerabilities and follow security best practices +3. **Be Easier to Maintain:** Better tooling and documentation +4. **Be More Accessible:** Containerization and cloud-native support +5. **Be More Reliable:** Better testing and CI/CD +6. **Be More Extensible:** Modular architecture for custom validators + +The phased approach allows for incremental improvements while maintaining stability and backward compatibility where possible. The highest priority items (Phase 1) address critical security and usability concerns, while later phases add nice-to-have features that expand the tool's utility. + +--- + +**Next Steps:** +1. Review and prioritize recommendations based on project goals +2. Create detailed implementation plan for Phase 1 +3. Set up project board for tracking progress +4. Begin implementation with highest priority items +5. Engage community for feedback and contributions + +**Questions? Feedback?** +Please open an issue or discussion on GitHub to share your thoughts on these recommendations. diff --git a/TESTING_STRATEGY.md b/TESTING_STRATEGY.md new file mode 100644 index 0000000..831c8a8 --- /dev/null +++ b/TESTING_STRATEGY.md @@ -0,0 +1,853 @@ +# check-engine Testing Strategy Modernization + +**Document Version:** 1.0 +**Date:** 2025-11-08 +**Status:** Planning Phase + +## Current State Analysis + +### Existing Test Infrastructure +- **Framework:** Tape (minimalist TAP-producing test harness) +- **Reporter:** tap-min (minimal TAP reporter) +- **Coverage:** 91 tests passing +- **Test Files:** + - `lib/checkSystem.spec.js` (141 lines) + - `lib/validatorRules.spec.js` (292 lines) +- **Mocking:** proxyquire (for stubbing module dependencies) + +### Strengths +- ✅ Good test coverage +- ✅ Tests are passing +- ✅ Basic mocking in place +- ✅ Tests run in CI + +### Weaknesses +- ⚠️ Old testing framework (tape) +- ⚠️ No coverage reporting/tracking +- ⚠️ No integration tests +- ⚠️ No E2E tests +- ⚠️ Limited test organization +- ⚠️ No test documentation +- ⚠️ No performance/benchmark tests + +--- + +## Recommended Modern Testing Stack + +### Option 1: Vitest (Recommended) +**Best for:** Modern, fast, ESM-first projects + +**Advantages:** +- ⚡ Extremely fast (uses Vite) +- 🔄 Watch mode with HMR +- 📊 Built-in coverage (via c8/v8) +- 🎯 Jest-compatible API +- 📦 ESM and TypeScript support +- 🔍 Better error messages +- 🌐 Browser mode support + +**Installation:** +```bash +npm install -D vitest @vitest/ui @vitest/coverage-v8 +``` + +**Configuration:** +```javascript +// vitest.config.js +import { defineConfig } from 'vitest/config'; + +export default defineConfig({ + test: { + globals: true, + environment: 'node', + coverage: { + provider: 'v8', + reporter: ['text', 'json', 'html', 'lcov'], + exclude: [ + 'node_modules/', + 'test/', + '**/*.spec.js', + '**/*.test.js', + ], + thresholds: { + lines: 80, + functions: 80, + branches: 80, + statements: 80, + }, + }, + }, +}); +``` + +--- + +### Option 2: Jest +**Best for:** Established ecosystem, extensive plugins + +**Advantages:** +- 🏆 Industry standard +- 📚 Extensive documentation +- 🔌 Large plugin ecosystem +- 💾 Snapshot testing +- 🎭 Built-in mocking +- 🔄 Watch mode + +**Installation:** +```bash +npm install -D jest @types/jest +``` + +**Configuration:** +```javascript +// jest.config.js +module.exports = { + testEnvironment: 'node', + coverageDirectory: 'coverage', + collectCoverageFrom: [ + 'lib/**/*.js', + 'bin/**/*.js', + '!**/*.spec.js', + '!**/*.test.js', + ], + coverageThreshold: { + global: { + branches: 80, + functions: 80, + lines: 80, + statements: 80, + }, + }, + testMatch: [ + '**/*.spec.js', + '**/*.test.js', + ], +}; +``` + +--- + +## Test Organization Structure + +### Proposed Directory Structure + +``` +check-engine/ +├── lib/ +│ ├── checkSystem.js +│ ├── validatorRules.js +│ └── promiseHelpers.js +├── test/ +│ ├── unit/ +│ │ ├── checkSystem.test.js +│ │ ├── validatorRules.test.js +│ │ └── promiseHelpers.test.js +│ ├── integration/ +│ │ ├── cli.integration.test.js +│ │ ├── programmatic-api.integration.test.js +│ │ └── validators.integration.test.js +│ ├── e2e/ +│ │ ├── basic-validation.e2e.test.js +│ │ ├── error-handling.e2e.test.js +│ │ └── real-projects.e2e.test.js +│ ├── fixtures/ +│ │ ├── package.json.examples/ +│ │ ├── mock-executables/ +│ │ └── test-environments/ +│ ├── helpers/ +│ │ ├── mock-validator.js +│ │ ├── test-utils.js +│ │ └── assertions.js +│ └── performance/ +│ ├── benchmark.test.js +│ └── load.test.js +├── coverage/ +└── vitest.config.js (or jest.config.js) +``` + +--- + +## Migration Plan from Tape to Vitest/Jest + +### Step 1: Setup New Framework + +**Install Dependencies:** +```bash +# For Vitest +npm install -D vitest @vitest/ui @vitest/coverage-v8 + +# For Jest +npm install -D jest @types/jest +``` + +**Create Configuration:** +```javascript +// vitest.config.js +export default { + test: { + globals: true, + environment: 'node', + }, +}; +``` + +### Step 2: Create Test Helpers + +**Create `test/helpers/test-utils.js`:** +```javascript +export function mockExec(command, output, exitCode = 0) { + return vi.fn().mockImplementation(() => { + if (exitCode !== 0) { + return Promise.reject(new Error(output)); + } + return Promise.resolve(output); + }); +} + +export function createMockPackageJson(engines) { + return { + name: 'test-package', + version: '1.0.0', + engines, + }; +} +``` + +### Step 3: Migrate Tests + +**Before (Tape):** +```javascript +const test = require('tape'); +const proxyquire = require('proxyquire'); + +test('should validate node version', (t) => { + const checkSystem = proxyquire('./checkSystem', { + 'child_process': { + exec: (cmd, cb) => cb(null, 'v20.0.0'), + }, + }); + + checkSystem('./package.json').then((result) => { + t.equal(result.status, 0); + t.end(); + }); +}); +``` + +**After (Vitest):** +```javascript +import { describe, it, expect, vi } from 'vitest'; +import { checkSystem } from './checkSystem.js'; +import * as cp from 'child_process'; + +vi.mock('child_process'); + +describe('checkSystem', () => { + it('should validate node version', async () => { + vi.spyOn(cp, 'exec').mockImplementation((cmd, cb) => { + cb(null, 'v20.0.0'); + }); + + const result = await checkSystem('./package.json'); + + expect(result.status).toBe(0); + expect(result.message.type).toBe('success'); + }); +}); +``` + +### Step 4: Update package.json Scripts + +```json +{ + "scripts": { + "test": "vitest run", + "test:watch": "vitest", + "test:ui": "vitest --ui", + "test:coverage": "vitest run --coverage", + "test:unit": "vitest run test/unit", + "test:integration": "vitest run test/integration", + "test:e2e": "vitest run test/e2e" + } +} +``` + +### Step 5: Update CI Configuration + +```yaml +# .github/workflows/test.yml +name: Tests + +on: [push, pull_request] + +jobs: + test: + runs-on: ubuntu-latest + strategy: + matrix: + node-version: [18, 20, 22] + + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node-version }} + + - run: npm ci + - run: npm run test:coverage + + - name: Upload coverage + uses: codecov/codecov-action@v3 + with: + files: ./coverage/lcov.info +``` + +--- + +## Test Types and Coverage + +### 1. Unit Tests + +**Purpose:** Test individual functions and modules in isolation + +**Coverage:** +- All functions in `checkSystem.js` +- All validators in `validatorRules.js` +- Helper functions in `promiseHelpers.js` +- Edge cases and error conditions + +**Example:** +```javascript +import { describe, it, expect, vi, beforeEach } from 'vitest'; +import { validatorRules } from '../lib/validatorRules.js'; +import * as semver from 'semver'; + +describe('validatorRules', () => { + describe('node validator', () => { + it('should validate correct node version', () => { + const result = validatorRules.node.versionValidate('v20.0.0', '>=18'); + expect(result).toBe(true); + }); + + it('should reject incorrect node version', () => { + const result = validatorRules.node.versionValidate('v16.0.0', '>=18'); + expect(result).toBe(false); + }); + + it('should handle version ranges', () => { + expect(validatorRules.node.versionValidate('v20.0.0', '^20.0.0')).toBe(true); + expect(validatorRules.node.versionValidate('v20.5.0', '^20.0.0')).toBe(true); + expect(validatorRules.node.versionValidate('v21.0.0', '^20.0.0')).toBe(false); + }); + }); + + describe('npm validator', () => { + it('should validate npm version', () => { + const result = validatorRules.npm.versionValidate('9.0.0', '>=8'); + expect(result).toBe(true); + }); + }); +}); +``` + +### 2. Integration Tests + +**Purpose:** Test interactions between modules and with real commands + +**Coverage:** +- CLI argument parsing +- Package.json reading and parsing +- Multiple validators working together +- Error propagation +- Output formatting + +**Example:** +```javascript +import { describe, it, expect } from 'vitest'; +import { checkSystem } from '../lib/checkSystem.js'; +import { writeFileSync, unlinkSync } from 'fs'; +import { join } from 'path'; + +describe('checkSystem integration', () => { + const testPkgPath = join(__dirname, '../fixtures/test-package.json'); + + it('should validate complete package.json', async () => { + const pkg = { + name: 'test', + engines: { + node: '>=18', + npm: '>=8', + }, + }; + + writeFileSync(testPkgPath, JSON.stringify(pkg)); + + const result = await checkSystem(testPkgPath); + + expect(result.status).toBe(0); + expect(result.packages).toHaveLength(2); + expect(result.packages[0].name).toBe('node'); + expect(result.packages[1].name).toBe('npm'); + + unlinkSync(testPkgPath); + }); + + it('should handle missing package.json', async () => { + const result = await checkSystem('./nonexistent.json'); + + expect(result.status).toBe(-1); + expect(result.message.type).toBe('error'); + expect(result.message.text).toContain('not found'); + }); +}); +``` + +### 3. End-to-End Tests + +**Purpose:** Test complete workflows as a user would experience them + +**Coverage:** +- CLI invocation with various arguments +- Real-world package.json configurations +- Error messages and exit codes +- Output formatting +- Container usage + +**Example:** +```javascript +import { describe, it, expect } from 'vitest'; +import { exec } from 'child_process'; +import { promisify } from 'util'; + +const execAsync = promisify(exec); + +describe('CLI E2E', () => { + it('should run successfully with valid environment', async () => { + const { stdout, stderr } = await execAsync( + 'node bin/check-engine.js test/fixtures/valid-package.json' + ); + + expect(stdout).toContain('Environment looks good'); + expect(stderr).toBe(''); + }); + + it('should fail with invalid environment', async () => { + try { + await execAsync( + 'node bin/check-engine.js test/fixtures/invalid-package.json' + ); + expect.fail('Should have thrown'); + } catch (error) { + expect(error.code).toBe(1); + expect(error.stdout).toContain('Environment is invalid'); + } + }); + + it('should show help with --help flag', async () => { + const { stdout } = await execAsync('node bin/check-engine.js --help'); + + expect(stdout).toContain('check-engine'); + expect(stdout).toContain('Usage:'); + }); + + it('should show version with --version flag', async () => { + const { stdout } = await execAsync('node bin/check-engine.js --version'); + + expect(stdout).toMatch(/\d+\.\d+\.\d+/); + }); +}); +``` + +### 4. Performance/Benchmark Tests + +**Purpose:** Track performance characteristics and prevent regressions + +**Coverage:** +- Validation speed +- Memory usage +- Parallel execution performance +- Large package.json handling + +**Example:** +```javascript +import { describe, it, expect, bench } from 'vitest'; +import { checkSystem } from '../lib/checkSystem.js'; + +describe('Performance', () => { + bench('validate small package.json', async () => { + await checkSystem('test/fixtures/small-package.json'); + }); + + bench('validate large package.json', async () => { + await checkSystem('test/fixtures/large-package.json'); + }); + + it('should complete validation in under 5 seconds', async () => { + const start = Date.now(); + await checkSystem('test/fixtures/standard-package.json'); + const duration = Date.now() - start; + + expect(duration).toBeLessThan(5000); + }); +}); +``` + +--- + +## Test Fixtures and Mocks + +### Test Fixtures + +Create reusable test data: + +```javascript +// test/fixtures/packages.js +export const validPackages = { + minimal: { + name: 'test-minimal', + engines: { node: '>=18' }, + }, + standard: { + name: 'test-standard', + engines: { + node: '>=18', + npm: '>=8', + git: '>=2.30', + }, + }, + complex: { + name: 'test-complex', + engines: { + node: '>=18', + npm: '>=8', + yarn: '>=3', + pnpm: '>=8', + python: '>=3.9', + }, + }, +}; + +export const invalidPackages = { + futureNode: { + name: 'test-future', + engines: { node: '>=99' }, + }, + noEngines: { + name: 'test-no-engines', + }, +}; +``` + +### Mock Executables + +Create test doubles for system commands: + +```javascript +// test/helpers/mock-validator.js +export function createMockValidator(name, version, shouldFail = false) { + return { + versionCheck: `mock-${name} --version`, + versionValidate: (result, expected) => { + if (shouldFail) return false; + return semver.satisfies(version, expected); + }, + }; +} + +export function mockSystemCommands(commands) { + const mocks = {}; + + for (const [cmd, output] of Object.entries(commands)) { + mocks[cmd] = vi.fn().mockResolvedValue(output); + } + + return mocks; +} +``` + +--- + +## Coverage Requirements + +### Minimum Coverage Thresholds + +```javascript +{ + coverage: { + thresholds: { + lines: 85, + functions: 85, + branches: 80, + statements: 85, + }, + }, +} +``` + +### Coverage Reports + +Generate multiple report formats: +- **HTML:** For local viewing +- **LCOV:** For CI integration +- **JSON:** For programmatic analysis +- **Text:** For terminal output + +### Coverage Badges + +Add to README: +```markdown +[![Coverage](https://codecov.io/gh/mohlsen/check-engine/branch/master/graph/badge.svg)](https://codecov.io/gh/mohlsen/check-engine) +``` + +--- + +## Continuous Integration + +### GitHub Actions Configuration + +```yaml +name: Test Suite + +on: + push: + branches: [master] + pull_request: + branches: [master] + +jobs: + unit-tests: + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [ubuntu-latest, macos-latest, windows-latest] + node-version: [18, 20, 22] + + steps: + - uses: actions/checkout@v4 + + - name: Use Node.js ${{ matrix.node-version }} + uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node-version }} + + - name: Install dependencies + run: npm ci + + - name: Run unit tests + run: npm run test:unit + + - name: Run integration tests + run: npm run test:integration + + e2e-tests: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 20 + + - run: npm ci + - run: npm run test:e2e + + coverage: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 20 + + - run: npm ci + - run: npm run test:coverage + + - name: Upload to Codecov + uses: codecov/codecov-action@v3 + with: + files: ./coverage/lcov.info + fail_ci_if_error: true + + quality-gate: + needs: [unit-tests, e2e-tests, coverage] + runs-on: ubuntu-latest + + steps: + - name: Check all tests passed + run: echo "All tests passed!" +``` + +--- + +## Test Documentation + +### Writing Good Tests + +**Best Practices:** + +1. **Descriptive Names:** +```javascript +// ❌ Bad +it('test 1', () => {}); + +// ✅ Good +it('should reject version when node is below minimum required', () => {}); +``` + +2. **Arrange-Act-Assert Pattern:** +```javascript +it('should validate correct version', () => { + // Arrange + const validator = validatorRules.node; + const version = 'v20.0.0'; + const requirement = '>=18'; + + // Act + const result = validator.versionValidate(version, requirement); + + // Assert + expect(result).toBe(true); +}); +``` + +3. **One Assertion Per Test (Generally):** +```javascript +// ❌ Testing multiple things +it('should work', () => { + expect(result.status).toBe(0); + expect(result.message).toBeDefined(); + expect(result.packages.length).toBeGreaterThan(0); +}); + +// ✅ Focused tests +it('should return success status', () => { + expect(result.status).toBe(0); +}); + +it('should include message in result', () => { + expect(result.message).toBeDefined(); +}); + +it('should include validated packages', () => { + expect(result.packages.length).toBeGreaterThan(0); +}); +``` + +4. **Test Both Happy and Sad Paths:** +```javascript +describe('checkSystem', () => { + it('should succeed with valid environment', async () => { + // ... + }); + + it('should fail with invalid environment', async () => { + // ... + }); + + it('should handle missing package.json', async () => { + // ... + }); + + it('should handle corrupted package.json', async () => { + // ... + }); +}); +``` + +--- + +## Testing Tools and Utilities + +### Recommended Additional Tools + +1. **Test Data Generators:** +```bash +npm install -D @faker-js/faker +``` + +2. **Snapshot Testing:** +```javascript +import { expect, it } from 'vitest'; + +it('should match snapshot', () => { + const output = formatOutput(result); + expect(output).toMatchSnapshot(); +}); +``` + +3. **Mock Server (for API testing):** +```bash +npm install -D msw +``` + +4. **Test Utilities:** +```bash +npm install -D @testing-library/jest-dom +``` + +--- + +## Migration Checklist + +### Pre-Migration +- [ ] Audit current test coverage +- [ ] Document test dependencies +- [ ] Backup current tests +- [ ] Choose new framework (Vitest recommended) + +### Migration Phase +- [ ] Install new testing framework +- [ ] Create configuration files +- [ ] Set up test helpers and utilities +- [ ] Migrate unit tests +- [ ] Migrate integration tests +- [ ] Add E2E tests +- [ ] Set up coverage reporting +- [ ] Update CI/CD pipelines + +### Post-Migration +- [ ] Verify all tests passing +- [ ] Check coverage meets thresholds +- [ ] Update documentation +- [ ] Remove old testing dependencies +- [ ] Train team on new framework + +--- + +## Success Criteria + +### Test Quality +- ✅ >85% code coverage +- ✅ All tests passing on all platforms +- ✅ Fast test execution (<30s for unit tests) +- ✅ Clear, descriptive test names +- ✅ Good test organization + +### Developer Experience +- ✅ Easy to run tests locally +- ✅ Fast feedback in watch mode +- ✅ Clear error messages +- ✅ Easy to write new tests +- ✅ Good documentation + +### CI/CD Integration +- ✅ Tests run on every PR +- ✅ Coverage tracked and reported +- ✅ Quality gates enforced +- ✅ Fast CI pipelines (<10 minutes) + +--- + +## Conclusion + +Modernizing the testing infrastructure for check-engine will significantly improve code quality, developer experience, and confidence in releases. The recommended migration to Vitest (or Jest) provides: + +1. **Better tooling** with modern features +2. **Improved coverage** tracking and reporting +3. **Faster feedback** loops for developers +4. **More comprehensive testing** with unit, integration, and E2E tests +5. **Better CI/CD integration** for automated quality gates + +By following this strategy, check-engine will have a robust, maintainable test suite that supports future development and ensures high quality releases. + From c8b043f2b3ad0c43df3815a020b257efe4781d3f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 8 Nov 2025 01:11:48 +0000 Subject: [PATCH 3/5] Add executive summary for modernization planning Co-authored-by: mohlsen <3265497+mohlsen@users.noreply.github.com> --- MODERNIZATION_SUMMARY.md | 432 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 432 insertions(+) create mode 100644 MODERNIZATION_SUMMARY.md diff --git a/MODERNIZATION_SUMMARY.md b/MODERNIZATION_SUMMARY.md new file mode 100644 index 0000000..d7c94ed --- /dev/null +++ b/MODERNIZATION_SUMMARY.md @@ -0,0 +1,432 @@ +# check-engine Modernization Planning Summary + +**Date:** 2025-11-08 +**Version:** 1.0 +**Status:** Planning Complete + +## Executive Summary + +This document provides a quick overview of the comprehensive modernization plan for the check-engine project. Five detailed planning documents have been created to guide the modernization effort, covering all aspects from security updates to cloud-native deployment. + +--- + +## Quick Links + +### Planning Documents +1. **[MODERNIZATION_RECOMMENDATIONS.md](./MODERNIZATION_RECOMMENDATIONS.md)** - High-level recommendations and priorities +2. **[IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md)** - Detailed step-by-step implementation guide +3. **[CONTAINERIZATION_STRATEGY.md](./CONTAINERIZATION_STRATEGY.md)** - Docker and container deployment strategy +4. **[CLOUD_NATIVE_DEPLOYMENT.md](./CLOUD_NATIVE_DEPLOYMENT.md)** - Kubernetes and cloud platform deployment +5. **[TESTING_STRATEGY.md](./TESTING_STRATEGY.md)** - Modern testing framework migration + +--- + +## At a Glance + +### Current State +- **Version:** 1.14.0 +- **Node.js:** >=10 (outdated) +- **Testing:** Tape (91 tests passing) +- **CI/CD:** Basic GitHub Actions +- **Container:** None +- **Cloud Support:** None +- **Security:** 2 vulnerabilities +- **Documentation:** Basic README only + +### Target State +- **Version:** 2.0.0 (after Phase 1-2) +- **Node.js:** >=18 (LTS) +- **Testing:** Vitest/Jest with >85% coverage +- **CI/CD:** Advanced automation with multiple workflows +- **Container:** Multi-arch images on GHCR/Docker Hub +- **Cloud Support:** K8s, AWS, GCP, Azure examples +- **Security:** 0 vulnerabilities, CodeQL scanning +- **Documentation:** Complete with CONTRIBUTING, CHANGELOG, etc. + +--- + +## Implementation Timeline + +### Phase 1: Foundation (Weeks 1-2) - HIGH Priority +**Focus:** Critical security and basic modernization + +**Deliverables:** +- ✅ Node.js 18+ support +- ✅ Security vulnerabilities fixed +- ✅ Docker images (base, standard, full) +- ✅ CONTRIBUTING.md, CHANGELOG.md, SECURITY.md, CODE_OF_CONDUCT.md +- ✅ Enhanced README with badges + +**Effort:** 8-11 days + +--- + +### Phase 2: Modernization (Weeks 3-4) - MEDIUM Priority +**Focus:** Developer experience and code quality + +**Deliverables:** +- ✅ Vitest/Jest testing framework +- ✅ TypeScript support (optional but recommended) +- ✅ ESLint 9 + Prettier + Husky +- ✅ Pre-commit hooks +- ✅ Enhanced CI/CD workflows +- ✅ Code coverage >85% + +**Effort:** 10-14 days + +--- + +### Phase 3: Enhancement (Weeks 5-6) - MEDIUM Priority +**Focus:** Modern features and cloud-native support + +**Deliverables:** +- ✅ Modern async/await API +- ✅ ESM module support +- ✅ Kubernetes manifests and Helm chart +- ✅ Cloud platform examples (AWS, GCP, Azure) +- ✅ VS Code/Codespaces configuration +- ✅ Improved CLI UX + +**Effort:** 7-10 days + +--- + +### Phase 4: Expansion (Weeks 7+) - LOW Priority +**Focus:** Optional enhancements and new features + +**Deliverables:** +- ✅ Multiple output formats (JSON, YAML, HTML, etc.) +- ✅ Extended validator library (Docker, kubectl, cloud CLIs) +- ✅ Plugin system for custom validators +- ✅ Optional telemetry and monitoring + +**Effort:** Ongoing, as needed + +--- + +## Key Recommendations + +### Top 5 Priorities + +1. **Update Node.js and Fix Security Issues** (Phase 1) + - Update to Node.js 18+ + - Fix 2 security vulnerabilities + - Immediate impact on security and maintenance + +2. **Add Container Support** (Phase 1) + - Create Docker images + - Enable consistent environments + - Critical for modern deployment + +3. **Improve Documentation** (Phase 1) + - Add CONTRIBUTING.md, CHANGELOG.md, SECURITY.md + - Enhance README + - Better onboarding and transparency + +4. **Modernize Testing** (Phase 2) + - Migrate to Vitest/Jest + - Add coverage reporting + - Improve test quality + +5. **Add Cloud-Native Support** (Phase 3) + - Kubernetes manifests + - Helm chart + - Cloud platform examples + - Expand use cases + +--- + +## Technology Stack + +### Current +``` +Runtime: Node.js >=10 +Testing: tape + tap-min +Linting: ESLint 8 +Mocking: proxyquire +Promises: Bluebird +CLI: yargs +Colors: colors +``` + +### Proposed +``` +Runtime: Node.js >=18 +Testing: Vitest (or Jest) +Linting: ESLint 9 + Prettier +TypeScript: Optional but recommended +Git Hooks: Husky + lint-staged +Commits: commitlint +Promises: Native async/await +CLI: yargs (keep) or commander +Colors: chalk +Container: Docker (multi-arch) +K8s: Helm charts +CI/CD: Enhanced GitHub Actions +``` + +--- + +## Document Overview + +### 1. MODERNIZATION_RECOMMENDATIONS.md (19KB) +**Audience:** Decision makers, project leads +**Content:** +- 15 detailed recommendations with priorities +- Effort estimates and benefits +- Risk assessment +- Success metrics +- Technology stack comparison + +**Use this when:** Planning the overall modernization strategy + +--- + +### 2. IMPLEMENTATION_PLAN.md (26KB) +**Audience:** Developers, implementers +**Content:** +- Step-by-step tasks for each recommendation +- Task dependencies +- Acceptance criteria +- Code examples +- Migration checklists + +**Use this when:** Actually implementing the changes + +--- + +### 3. CONTAINERIZATION_STRATEGY.md (17KB) +**Audience:** DevOps, infrastructure teams +**Content:** +- Multi-stage Dockerfile examples +- Image variants (base, standard, full) +- Multi-architecture builds +- Security best practices +- Distribution strategy + +**Use this when:** Building and distributing container images + +--- + +### 4. CLOUD_NATIVE_DEPLOYMENT.md (19KB) +**Audience:** Platform engineers, SREs +**Content:** +- Kubernetes patterns (Job, InitContainer, CronJob, DaemonSet) +- Helm chart structure +- AWS, GCP, Azure deployment examples +- CI/CD integration +- Monitoring and troubleshooting + +**Use this when:** Deploying to cloud platforms + +--- + +### 5. TESTING_STRATEGY.md (19KB) +**Audience:** QA engineers, developers +**Content:** +- Testing framework comparison +- Migration plan from tape +- Test organization structure +- Coverage requirements +- Example test code + +**Use this when:** Migrating tests or adding new test coverage + +--- + +## Quick Start Guide + +### For Project Maintainers + +1. **Review** MODERNIZATION_RECOMMENDATIONS.md +2. **Prioritize** which phases align with project goals +3. **Create** project board from IMPLEMENTATION_PLAN.md +4. **Assign** tasks to team members +5. **Track** progress and adjust as needed + +### For Contributors + +1. **Read** CONTRIBUTING.md (to be created in Phase 1) +2. **Check** IMPLEMENTATION_PLAN.md for available tasks +3. **Pick** a task matching your skills +4. **Follow** the implementation guide +5. **Submit** PR following the guidelines + +### For Users + +1. **Wait** for Phase 1 completion for stable Node 18+ support +2. **Try** Docker images once available (Phase 1) +3. **Explore** cloud-native examples (Phase 3) +4. **Provide** feedback via GitHub issues +5. **Contribute** validators for your favorite tools + +--- + +## Success Metrics + +### After Phase 1 +- ✅ 0 security vulnerabilities +- ✅ Node.js 18+ support +- ✅ Container images published +- ✅ Complete documentation set +- ✅ All tests passing + +### After Phase 2 +- ✅ >85% test coverage +- ✅ Modern testing framework +- ✅ Pre-commit hooks working +- ✅ Automated releases +- ✅ TypeScript support (optional) + +### After Phase 3 +- ✅ Kubernetes ready +- ✅ Cloud platform examples +- ✅ Modern API +- ✅ Enhanced developer experience +- ✅ Wide platform support + +### After Phase 4 +- ✅ Extended validator library +- ✅ Multiple output formats +- ✅ Plugin system +- ✅ Community contributions + +--- + +## Estimated Costs + +### Time Investment +- **Phase 1:** 8-11 days (1-2 weeks) +- **Phase 2:** 10-14 days (2-3 weeks) +- **Phase 3:** 7-10 days (1-2 weeks) +- **Phase 4:** Ongoing + +**Total for Phases 1-3:** 25-35 days (5-7 weeks) + +### Resource Requirements +- **Developer(s):** 1-2 full-time +- **Reviewer(s):** 1 part-time +- **Infrastructure:** GitHub Actions (free), GHCR (free), Codecov (free for open source) + +### Return on Investment +- **Improved Security:** Reduced vulnerability risk +- **Better Maintainability:** Easier to update and extend +- **Wider Adoption:** More platforms and use cases +- **Community Growth:** Better contributor experience +- **Professional Image:** Modern, well-maintained project + +--- + +## Risk Mitigation + +### Breaking Changes +**Risk:** Minimum Node version bump breaks existing users +**Mitigation:** +- Clear communication in CHANGELOG +- Deprecation warnings in v1.x +- Migration guide +- Maintain v1.x with security fixes for 6 months + +### Testing Migration +**Risk:** Test coverage might decrease during migration +**Mitigation:** +- Migrate tests incrementally +- Maintain parallel test runs during transition +- Block PRs that decrease coverage + +### Scope Creep +**Risk:** Project might expand beyond original goals +**Mitigation:** +- Stick to phased approach +- Mark Phase 4 as optional +- Regular scope reviews + +--- + +## Community Engagement + +### Communication Plan +1. **Announce** modernization plan in GitHub Discussions +2. **Create** project board for transparency +3. **Label** issues as "modernization" or "help wanted" +4. **Share** progress updates monthly +5. **Welcome** community contributions + +### Contribution Opportunities +- Documentation improvements +- New validators for different tools +- Testing on different platforms +- Cloud platform examples +- Translation to other languages + +--- + +## Questions & Feedback + +### Where to Ask Questions +- **GitHub Issues:** For bugs and feature requests +- **GitHub Discussions:** For questions and ideas +- **Pull Requests:** For specific implementation questions + +### How to Provide Feedback +1. Review the planning documents +2. Open a discussion or issue +3. Suggest changes or alternatives +4. Vote on proposals with 👍/👎 + +--- + +## Next Steps + +### Immediate Actions +1. ✅ Review all planning documents +2. ⬜ Discuss and approve modernization approach +3. ⬜ Create project board +4. ⬜ Set up milestones for each phase +5. ⬜ Begin Phase 1 implementation + +### This Week +- Set up project infrastructure +- Create initial issues +- Assign Phase 1 tasks +- Update README with modernization notice + +### This Month +- Complete Phase 1 +- Release v2.0.0-beta.1 +- Gather community feedback +- Begin Phase 2 + +### This Quarter +- Complete Phases 1-2 +- Release v2.0.0 +- Begin Phase 3 +- Grow contributor base + +--- + +## Conclusion + +This comprehensive modernization plan provides a clear path forward for check-engine. By following the phased approach, the project will evolve into a modern, secure, and widely-adopted tool for environment validation across multiple platforms and deployment scenarios. + +The planning phase is now complete. The next step is to begin implementation of Phase 1, starting with the highest priority items that will have the most immediate impact on security, usability, and maintainability. + +--- + +**Document Status:** ✅ Planning Complete +**Last Updated:** 2025-11-08 +**Next Review:** After Phase 1 completion + +--- + +## Appendix: Document Sizes + +| Document | Size | Focus Area | +|----------|------|------------| +| MODERNIZATION_RECOMMENDATIONS.md | 19KB | Strategy & Recommendations | +| IMPLEMENTATION_PLAN.md | 26KB | Execution & Tasks | +| CONTAINERIZATION_STRATEGY.md | 17KB | Docker & Containers | +| CLOUD_NATIVE_DEPLOYMENT.md | 19KB | Kubernetes & Cloud | +| TESTING_STRATEGY.md | 19KB | Testing & Quality | +| **Total** | **~100KB** | **Complete Modernization Guide** | + From 4303f38b7cbfca07374377c41e51fcab94274faa Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 8 Nov 2025 04:30:21 +0000 Subject: [PATCH 4/5] Refocus modernization plan on developer utility scope Co-authored-by: mohlsen <3265497+mohlsen@users.noreply.github.com> --- CLOUD_NATIVE_DEPLOYMENT.md | 980 ------------------------ CONTAINERIZATION_STRATEGY.md | 806 -------------------- IMPLEMENTATION_PLAN.md | 1193 ------------------------------ MODERNIZATION_PLAN.md | 611 +++++++++++++++ MODERNIZATION_RECOMMENDATIONS.md | 747 ------------------- MODERNIZATION_SUMMARY.md | 432 ----------- TESTING_STRATEGY.md | 853 --------------------- 7 files changed, 611 insertions(+), 5011 deletions(-) delete mode 100644 CLOUD_NATIVE_DEPLOYMENT.md delete mode 100644 CONTAINERIZATION_STRATEGY.md delete mode 100644 IMPLEMENTATION_PLAN.md create mode 100644 MODERNIZATION_PLAN.md delete mode 100644 MODERNIZATION_RECOMMENDATIONS.md delete mode 100644 MODERNIZATION_SUMMARY.md delete mode 100644 TESTING_STRATEGY.md diff --git a/CLOUD_NATIVE_DEPLOYMENT.md b/CLOUD_NATIVE_DEPLOYMENT.md deleted file mode 100644 index ebef114..0000000 --- a/CLOUD_NATIVE_DEPLOYMENT.md +++ /dev/null @@ -1,980 +0,0 @@ -# check-engine Cloud-Native Deployment Guide - -**Document Version:** 1.0 -**Date:** 2025-11-08 -**Status:** Planning Phase - -## Overview - -This guide provides comprehensive strategies for deploying and using check-engine in cloud-native environments, including Kubernetes, serverless platforms, and major cloud providers (AWS, Google Cloud, Azure). - ---- - -## Table of Contents - -1. [Kubernetes Deployment](#kubernetes-deployment) -2. [Helm Charts](#helm-charts) -3. [AWS Deployment](#aws-deployment) -4. [Google Cloud Deployment](#google-cloud-deployment) -5. [Azure Deployment](#azure-deployment) -6. [Serverless Deployment](#serverless-deployment) -7. [CI/CD Integration](#cicd-integration) -8. [Best Practices](#best-practices) - ---- - -## Kubernetes Deployment - -### Use Cases in Kubernetes - -1. **Pre-deployment Validation** - InitContainer to validate environment before app starts -2. **Periodic Audits** - CronJob to regularly check environment compliance -3. **One-time Checks** - Job for ad-hoc validation -4. **Admission Control** - Webhook to validate deployments - ---- - -### 1. Job - One-Time Validation - -**Purpose:** Run environment validation as a one-time task - -```yaml -apiVersion: batch/v1 -kind: Job -metadata: - name: check-engine-validation - namespace: default - labels: - app: check-engine - type: validation -spec: - backoffLimit: 3 - completions: 1 - parallelism: 1 - template: - metadata: - labels: - app: check-engine - type: validation - spec: - restartPolicy: Never - - containers: - - name: check-engine - image: ghcr.io/mohlsen/check-engine:latest - imagePullPolicy: IfNotPresent - - command: ["check-engine"] - args: ["/config/package.json"] - - volumeMounts: - - name: package-config - mountPath: /config - readOnly: true - - resources: - requests: - memory: "64Mi" - cpu: "100m" - limits: - memory: "128Mi" - cpu: "200m" - - volumes: - - name: package-config - configMap: - name: package-json-config -``` - -**ConfigMap for package.json:** -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: package-json-config - namespace: default -data: - package.json: | - { - "name": "my-app", - "engines": { - "node": ">=18", - "npm": ">=8", - "git": ">=2.30" - } - } -``` - -**Usage:** -```bash -# Create ConfigMap -kubectl apply -f configmap.yaml - -# Run Job -kubectl apply -f job.yaml - -# Check status -kubectl get jobs -kubectl logs job/check-engine-validation - -# Cleanup -kubectl delete job check-engine-validation -``` - ---- - -### 2. InitContainer - Pre-Deployment Validation - -**Purpose:** Validate environment before starting application containers - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: my-application - namespace: default -spec: - replicas: 3 - selector: - matchLabels: - app: my-application - template: - metadata: - labels: - app: my-application - spec: - # Environment validation before app starts - initContainers: - - name: validate-environment - image: ghcr.io/mohlsen/check-engine:standard - imagePullPolicy: IfNotPresent - - command: ["check-engine"] - args: ["/config/package.json", "--ignore"] - - volumeMounts: - - name: package-config - mountPath: /config - readOnly: true - - resources: - requests: - memory: "64Mi" - cpu: "100m" - limits: - memory: "128Mi" - cpu: "200m" - - # Main application container - containers: - - name: app - image: my-application:latest - ports: - - containerPort: 8080 - - resources: - requests: - memory: "256Mi" - cpu: "250m" - limits: - memory: "512Mi" - cpu: "500m" - - volumes: - - name: package-config - configMap: - name: package-json-config -``` - -**Benefits:** -- App only starts if environment is valid -- Fast failure feedback -- Prevents invalid deployments -- No performance impact on running app - ---- - -### 3. CronJob - Periodic Validation - -**Purpose:** Regularly audit environment compliance - -```yaml -apiVersion: batch/v1 -kind: CronJob -metadata: - name: environment-audit - namespace: default -spec: - # Run every 6 hours - schedule: "0 */6 * * *" - - # Keep last 3 successful and 1 failed job - successfulJobsHistoryLimit: 3 - failedJobsHistoryLimit: 1 - - jobTemplate: - spec: - template: - metadata: - labels: - app: check-engine - type: audit - spec: - restartPolicy: OnFailure - - containers: - - name: check-engine - image: ghcr.io/mohlsen/check-engine:standard - imagePullPolicy: IfNotPresent - - command: ["check-engine"] - args: ["/config/package.json"] - - volumeMounts: - - name: package-config - mountPath: /config - readOnly: true - - # Send results to monitoring system - env: - - name: SLACK_WEBHOOK - valueFrom: - secretKeyRef: - name: monitoring-secrets - key: slack-webhook - - resources: - requests: - memory: "64Mi" - cpu: "100m" - limits: - memory: "128Mi" - cpu: "200m" - - volumes: - - name: package-config - configMap: - name: package-json-config -``` - -**With Notification Script:** -```yaml -# Add notification sidecar -containers: -- name: notifier - image: curlimages/curl:latest - command: ["/bin/sh"] - args: - - -c - - | - RESULT=$(cat /shared/result.json) - curl -X POST $SLACK_WEBHOOK -d "{\"text\": \"Environment Audit: $RESULT\"}" - volumeMounts: - - name: shared-data - mountPath: /shared - -volumes: -- name: shared-data - emptyDir: {} -``` - ---- - -### 4. DaemonSet - Node Validation - -**Purpose:** Validate environment on every node - -```yaml -apiVersion: apps/v1 -kind: DaemonSet -metadata: - name: node-validator - namespace: kube-system -spec: - selector: - matchLabels: - name: node-validator - template: - metadata: - labels: - name: node-validator - spec: - tolerations: - # Run on all nodes including master - - effect: NoSchedule - key: node-role.kubernetes.io/master - - hostNetwork: true - hostPID: true - - containers: - - name: validator - image: ghcr.io/mohlsen/check-engine:full - imagePullPolicy: IfNotPresent - - command: ["/bin/sh"] - args: - - -c - - | - while true; do - check-engine /config/package.json - sleep 3600 - done - - volumeMounts: - - name: package-config - mountPath: /config - readOnly: true - - resources: - requests: - memory: "128Mi" - cpu: "100m" - limits: - memory: "256Mi" - cpu: "200m" - - securityContext: - privileged: true - - volumes: - - name: package-config - configMap: - name: node-requirements -``` - ---- - -## Helm Charts - -### Chart Structure - -``` -check-engine-chart/ -├── Chart.yaml -├── values.yaml -├── templates/ -│ ├── _helpers.tpl -│ ├── configmap.yaml -│ ├── job.yaml -│ ├── cronjob.yaml -│ ├── serviceaccount.yaml -│ └── NOTES.txt -└── README.md -``` - -### Chart.yaml - -```yaml -apiVersion: v2 -name: check-engine -description: Environment validation for Kubernetes workloads -version: 1.0.0 -appVersion: "1.14.0" -keywords: - - validation - - environment - - nodejs -maintainers: - - name: Mike Ohlsen - url: https://github.com/mohlsen -sources: - - https://github.com/mohlsen/check-engine -``` - -### values.yaml - -```yaml -# Default values for check-engine - -image: - repository: ghcr.io/mohlsen/check-engine - tag: latest - pullPolicy: IfNotPresent - variant: standard # base, standard, or full - -packageJson: - # Inline package.json engines configuration - engines: - node: ">=18" - npm: ">=8" - git: ">=2.30" - -# Job configuration -job: - enabled: true - backoffLimit: 3 - restartPolicy: Never - annotations: {} - labels: {} - -# CronJob configuration -cronjob: - enabled: false - schedule: "0 */6 * * *" - successfulJobsHistoryLimit: 3 - failedJobsHistoryLimit: 1 - -# InitContainer configuration -initContainer: - enabled: false - ignoreErrors: false - -# Resource limits -resources: - requests: - memory: "64Mi" - cpu: "100m" - limits: - memory: "128Mi" - cpu: "200m" - -# Service Account -serviceAccount: - create: true - name: "" - annotations: {} - -# Notifications -notifications: - enabled: false - slack: - webhookUrl: "" - email: - enabled: false - to: "" -``` - -### Usage - -```bash -# Install chart -helm install my-validation ./check-engine-chart - -# With custom values -helm install my-validation ./check-engine-chart \ - --set image.tag=1.14.0 \ - --set cronjob.enabled=true \ - --set cronjob.schedule="0 0 * * *" - -# As InitContainer -helm install my-validation ./check-engine-chart \ - --set job.enabled=false \ - --set initContainer.enabled=true - -# Upgrade -helm upgrade my-validation ./check-engine-chart - -# Uninstall -helm uninstall my-validation -``` - ---- - -## AWS Deployment - -### 1. AWS ECS (Elastic Container Service) - -**Task Definition:** -```json -{ - "family": "check-engine", - "networkMode": "awsvpc", - "requiresCompatibilities": ["FARGATE"], - "cpu": "256", - "memory": "512", - "containerDefinitions": [ - { - "name": "check-engine", - "image": "ghcr.io/mohlsen/check-engine:standard", - "command": ["check-engine", "/config/package.json"], - "essential": true, - "logConfiguration": { - "logDriver": "awslogs", - "options": { - "awslogs-group": "/ecs/check-engine", - "awslogs-region": "us-east-1", - "awslogs-stream-prefix": "check-engine" - } - }, - "mountPoints": [ - { - "sourceVolume": "config", - "containerPath": "/config", - "readOnly": true - } - ] - } - ], - "volumes": [ - { - "name": "config", - "efsVolumeConfiguration": { - "fileSystemId": "fs-12345678", - "rootDirectory": "/config" - } - } - ] -} -``` - -**Run Task:** -```bash -aws ecs run-task \ - --cluster my-cluster \ - --task-definition check-engine \ - --launch-type FARGATE \ - --network-configuration "awsvpcConfiguration={subnets=[subnet-12345],securityGroups=[sg-12345]}" -``` - ---- - -### 2. AWS EKS (Elastic Kubernetes Service) - -Use standard Kubernetes manifests or Helm charts (see above). - -**EKS-specific configuration:** -```yaml -apiVersion: v1 -kind: ServiceAccount -metadata: - name: check-engine - annotations: - eks.amazonaws.com/role-arn: arn:aws:iam::123456789:role/check-engine-role - ---- -apiVersion: batch/v1 -kind: Job -metadata: - name: check-engine -spec: - template: - spec: - serviceAccountName: check-engine - containers: - - name: check-engine - image: ghcr.io/mohlsen/check-engine:standard - # ... rest of configuration -``` - ---- - -### 3. AWS Lambda - -**For serverless validation:** - -```javascript -// lambda-handler.js -const { checkEngine } = require('check-engine'); - -exports.handler = async (event) => { - const packageJson = event.packageJson || '/var/task/package.json'; - - try { - const result = await checkEngine(packageJson); - - return { - statusCode: result.status === 0 ? 200 : 500, - body: JSON.stringify(result), - }; - } catch (error) { - return { - statusCode: 500, - body: JSON.stringify({ error: error.message }), - }; - } -}; -``` - -**Deploy with SAM:** -```yaml -# template.yaml -AWSTemplateFormatVersion: '2010-09-09' -Transform: AWS::Serverless-2016-10-31 - -Resources: - CheckEngineFunction: - Type: AWS::Serverless::Function - Properties: - Handler: lambda-handler.handler - Runtime: nodejs20.x - MemorySize: 512 - Timeout: 30 - Events: - Api: - Type: Api - Properties: - Path: /validate - Method: post -``` - ---- - -## Google Cloud Deployment - -### 1. Google Cloud Run - -**Deploy container:** -```bash -# Build and push -gcloud builds submit --tag gcr.io/PROJECT_ID/check-engine - -# Deploy to Cloud Run -gcloud run deploy check-engine \ - --image gcr.io/PROJECT_ID/check-engine \ - --platform managed \ - --region us-central1 \ - --allow-unauthenticated \ - --memory 512Mi \ - --cpu 1 \ - --max-instances 10 -``` - -**With Cloud Build:** -```yaml -# cloudbuild.yaml -steps: - # Build container - - name: 'gcr.io/cloud-builders/docker' - args: ['build', '-t', 'gcr.io/$PROJECT_ID/check-engine', '.'] - - # Push to Container Registry - - name: 'gcr.io/cloud-builders/docker' - args: ['push', 'gcr.io/$PROJECT_ID/check-engine'] - - # Deploy to Cloud Run - - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk' - entrypoint: gcloud - args: - - 'run' - - 'deploy' - - 'check-engine' - - '--image' - - 'gcr.io/$PROJECT_ID/check-engine' - - '--region' - - 'us-central1' - - '--platform' - - 'managed' -``` - ---- - -### 2. Google Kubernetes Engine (GKE) - -Use standard Kubernetes manifests or Helm charts. - -**GKE-specific Workload Identity:** -```yaml -apiVersion: v1 -kind: ServiceAccount -metadata: - name: check-engine - annotations: - iam.gke.io/gcp-service-account: check-engine@PROJECT_ID.iam.gserviceaccount.com -``` - ---- - -### 3. Google Cloud Functions - -```javascript -// index.js -const { checkEngine } = require('check-engine'); - -exports.validateEnvironment = async (req, res) => { - try { - const result = await checkEngine('./package.json'); - - res.status(result.status === 0 ? 200 : 500).json(result); - } catch (error) { - res.status(500).json({ error: error.message }); - } -}; -``` - -**Deploy:** -```bash -gcloud functions deploy validateEnvironment \ - --runtime nodejs20 \ - --trigger-http \ - --allow-unauthenticated \ - --memory 512MB \ - --timeout 60s -``` - ---- - -## Azure Deployment - -### 1. Azure Container Instances (ACI) - -```bash -# Create container group -az container create \ - --resource-group myResourceGroup \ - --name check-engine \ - --image ghcr.io/mohlsen/check-engine:standard \ - --cpu 1 \ - --memory 1 \ - --restart-policy Never \ - --command-line "check-engine /config/package.json" -``` - -**With ARM Template:** -```json -{ - "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", - "contentVersion": "1.0.0.0", - "resources": [ - { - "type": "Microsoft.ContainerInstance/containerGroups", - "apiVersion": "2021-09-01", - "name": "check-engine", - "location": "eastus", - "properties": { - "containers": [ - { - "name": "check-engine", - "properties": { - "image": "ghcr.io/mohlsen/check-engine:standard", - "command": ["check-engine", "/config/package.json"], - "resources": { - "requests": { - "cpu": 1.0, - "memoryInGB": 1.0 - } - } - } - } - ], - "osType": "Linux", - "restartPolicy": "Never" - } - } - ] -} -``` - ---- - -### 2. Azure Kubernetes Service (AKS) - -Use standard Kubernetes manifests or Helm charts. - ---- - -### 3. Azure Functions - -```javascript -// index.js -const { checkEngine } = require('check-engine'); - -module.exports = async function (context, req) { - try { - const result = await checkEngine('./package.json'); - - context.res = { - status: result.status === 0 ? 200 : 500, - body: result, - }; - } catch (error) { - context.res = { - status: 500, - body: { error: error.message }, - }; - } -}; -``` - ---- - -## CI/CD Integration - -### GitHub Actions - -```yaml -name: Validate Environment - -on: [push, pull_request] - -jobs: - validate: - runs-on: ubuntu-latest - - # Use container - container: - image: ghcr.io/mohlsen/check-engine:standard - - steps: - - uses: actions/checkout@v4 - - - name: Validate environment - run: check-engine package.json - - - name: Upload results - if: always() - uses: actions/upload-artifact@v3 - with: - name: validation-results - path: ./validation-results.json -``` - ---- - -### GitLab CI - -```yaml -validate: - image: ghcr.io/mohlsen/check-engine:standard - stage: test - script: - - check-engine package.json - artifacts: - when: always - paths: - - validation-results.json - reports: - junit: validation-results.xml -``` - ---- - -### Jenkins - -```groovy -pipeline { - agent { - kubernetes { - yaml ''' -apiVersion: v1 -kind: Pod -spec: - containers: - - name: check-engine - image: ghcr.io/mohlsen/check-engine:standard - command: ['cat'] - tty: true - ''' - } - } - - stages { - stage('Validate') { - steps { - container('check-engine') { - sh 'check-engine package.json' - } - } - } - } -} -``` - ---- - -## Best Practices - -### 1. Resource Management - -**Set appropriate limits:** -```yaml -resources: - requests: - memory: "64Mi" - cpu: "100m" - limits: - memory: "128Mi" - cpu: "200m" -``` - -### 2. Security - -**Run as non-root:** -```yaml -securityContext: - runAsNonRoot: true - runAsUser: 1001 - allowPrivilegeEscalation: false - capabilities: - drop: - - ALL -``` - -### 3. Monitoring - -**Add health checks:** -```yaml -livenessProbe: - exec: - command: ["check-engine", "--version"] - initialDelaySeconds: 5 - periodSeconds: 10 -``` - -### 4. Configuration Management - -**Use ConfigMaps for package.json:** -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: package-json -data: - package.json: | - { - "engines": { - "node": ">=18" - } - } -``` - -### 5. Secrets Management - -**Never bake secrets into images:** -```yaml -env: -- name: API_KEY - valueFrom: - secretKeyRef: - name: api-secrets - key: key -``` - ---- - -## Troubleshooting - -### Common Issues - -**1. Permission Denied** -```yaml -securityContext: - fsGroup: 1001 -``` - -**2. Out of Memory** -```yaml -resources: - limits: - memory: "256Mi" # Increase limit -``` - -**3. Timeout** -```yaml -spec: - activeDeadlineSeconds: 300 # 5 minutes -``` - ---- - -## Conclusion - -This guide provides comprehensive patterns for deploying check-engine in cloud-native environments. Key takeaways: - -1. **Flexibility:** Multiple deployment patterns for different use cases -2. **Cloud Agnostic:** Works across AWS, GCP, Azure, and bare-metal Kubernetes -3. **Integration:** Easy CI/CD integration -4. **Best Practices:** Security, resource management, and monitoring built-in - -Choose the deployment pattern that best fits your use case and infrastructure. - diff --git a/CONTAINERIZATION_STRATEGY.md b/CONTAINERIZATION_STRATEGY.md deleted file mode 100644 index 91436e8..0000000 --- a/CONTAINERIZATION_STRATEGY.md +++ /dev/null @@ -1,806 +0,0 @@ -# check-engine Containerization Strategy - -**Document Version:** 1.0 -**Date:** 2025-11-08 -**Status:** Planning Phase - -## Overview - -This document outlines the comprehensive strategy for containerizing the check-engine project, enabling consistent development environments, simplified CI/CD integration, and cloud-native deployments. - ---- - -## Goals - -### Primary Goals -1. **Consistency:** Ensure identical environments across development, CI/CD, and production -2. **Portability:** Run check-engine anywhere containers are supported -3. **Pre-installed Tools:** Include common development tools in the image -4. **Efficiency:** Optimize image size and build times -5. **Security:** Follow container security best practices - -### Secondary Goals -1. Support multiple architectures (amd64, arm64) -2. Provide multiple image variants for different use cases -3. Enable easy customization and extension -4. Integrate seamlessly with CI/CD pipelines -5. Support orchestration platforms (Kubernetes, Docker Swarm, etc.) - ---- - -## Architecture - -### Image Variants - -We will provide three primary image variants: - -#### 1. Base Image (`check-engine:base`) -**Purpose:** Minimal image with just check-engine installed - -**Contents:** -- Node.js runtime -- check-engine package -- Basic system utilities - -**Size Target:** <50MB -**Use Case:** When host has all required tools, just need check-engine - -```dockerfile -FROM node:20-alpine -RUN npm install -g check-engine@latest -WORKDIR /workspace -ENTRYPOINT ["check-engine"] -``` - ---- - -#### 2. Standard Image (`check-engine:latest`, `check-engine:standard`) -**Purpose:** Image with common development tools pre-installed - -**Contents:** -- Node.js runtime -- check-engine package -- git -- npm, yarn, pnpm -- Common build tools - -**Size Target:** <200MB -**Use Case:** Most common scenarios, general development environment validation - -```dockerfile -FROM node:20-alpine - -# Install common tools -RUN apk add --no-cache \ - git \ - python3 \ - make \ - g++ \ - && npm install -g check-engine@latest yarn pnpm - -WORKDIR /workspace -ENTRYPOINT ["check-engine"] -``` - ---- - -#### 3. Full Image (`check-engine:full`) -**Purpose:** Comprehensive image with extensive tooling for complex projects - -**Contents:** -- All tools from Standard image -- Additional language runtimes (Python, Ruby, Go) -- Cloud CLIs (aws, gcloud, az) -- Container tools (docker client) -- Build tools (gradle, maven) -- Additional utilities - -**Size Target:** <500MB -**Use Case:** Complex multi-language projects, full environment validation - -```dockerfile -FROM node:20 - -# Install comprehensive tooling -RUN apt-get update && apt-get install -y \ - git \ - python3 \ - ruby \ - golang \ - default-jdk \ - maven \ - gradle \ - && npm install -g check-engine@latest yarn pnpm bower \ - && apt-get clean \ - && rm -rf /var/lib/apt/lists/* - -# Install cloud CLIs -RUN curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" \ - && unzip awscliv2.zip \ - && ./aws/install \ - && rm -rf aws awscliv2.zip - -WORKDIR /workspace -ENTRYPOINT ["check-engine"] -``` - ---- - -## Multi-Stage Build Strategy - -### Build Stage -Optimize builds with multi-stage Dockerfiles: - -```dockerfile -# Stage 1: Build/Install -FROM node:20-alpine AS builder -WORKDIR /build -COPY package*.json ./ -RUN npm ci --only=production - -# Stage 2: Runtime -FROM node:20-alpine -RUN apk add --no-cache git -WORKDIR /app - -# Copy from builder -COPY --from=builder /build/node_modules ./node_modules -COPY . . - -# Security: Run as non-root -RUN addgroup -g 1001 -S checkengine && \ - adduser -S -D -H -u 1001 -s /sbin/nologin -G checkengine checkengine && \ - chown -R checkengine:checkengine /app - -USER checkengine - -ENTRYPOINT ["node", "/app/bin/check-engine.js"] -``` - -**Benefits:** -- Smaller final image -- No build dependencies in production image -- Better layer caching -- Improved security - ---- - -## Multi-Architecture Support - -### Supported Architectures -- `linux/amd64` (Intel/AMD 64-bit) -- `linux/arm64` (ARM 64-bit, Apple M1/M2, AWS Graviton) -- `linux/arm/v7` (ARM 32-bit, Raspberry Pi) - -### Build Configuration - -Using Docker Buildx for multi-architecture builds: - -```bash -# Create builder -docker buildx create --name multi-arch-builder --use - -# Build for multiple platforms -docker buildx build \ - --platform linux/amd64,linux/arm64,linux/arm/v7 \ - --tag ghcr.io/mohlsen/check-engine:latest \ - --push \ - . -``` - -### GitHub Actions Integration - -```yaml -name: Build Multi-Arch Images - -on: - push: - tags: - - 'v*' - -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - - name: Set up QEMU - uses: docker/setup-qemu-action@v3 - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - - name: Login to GHCR - uses: docker/login-action@v3 - with: - registry: ghcr.io - username: ${{ github.actor }} - password: ${{ secrets.GITHUB_TOKEN }} - - - name: Extract metadata - id: meta - uses: docker/metadata-action@v5 - with: - images: ghcr.io/mohlsen/check-engine - tags: | - type=semver,pattern={{version}} - type=semver,pattern={{major}}.{{minor}} - type=semver,pattern={{major}} - type=raw,value=latest,enable={{is_default_branch}} - - - name: Build and push - uses: docker/build-push-action@v5 - with: - context: . - platforms: linux/amd64,linux/arm64,linux/arm/v7 - push: true - tags: ${{ steps.meta.outputs.tags }} - labels: ${{ steps.meta.outputs.labels }} - cache-from: type=gha - cache-to: type=gha,mode=max -``` - ---- - -## Image Tagging Strategy - -### Semantic Versioning Tags -``` -ghcr.io/mohlsen/check-engine:1.15.0 # Specific version -ghcr.io/mohlsen/check-engine:1.15 # Minor version -ghcr.io/mohlsen/check-engine:1 # Major version -ghcr.io/mohlsen/check-engine:latest # Latest release -``` - -### Variant Tags -``` -ghcr.io/mohlsen/check-engine:base # Minimal -ghcr.io/mohlsen/check-engine:standard # Standard (default) -ghcr.io/mohlsen/check-engine:full # Full tooling -ghcr.io/mohlsen/check-engine:1.15.0-base # Version + variant -``` - -### Additional Tags -``` -ghcr.io/mohlsen/check-engine:edge # Latest from main branch -ghcr.io/mohlsen/check-engine:sha-abc123 # Specific commit -ghcr.io/mohlsen/check-engine:pr-42 # Pull request preview -``` - ---- - -## Security Best Practices - -### 1. Non-Root User -Always run as non-root user: - -```dockerfile -# Create user -RUN addgroup -g 1001 -S checkengine && \ - adduser -S -D -H -u 1001 -s /sbin/nologin -G checkengine checkengine - -# Switch to user -USER checkengine -``` - -### 2. Minimal Base Images -Use Alpine or distroless images: - -```dockerfile -# Alpine (small, has shell) -FROM node:20-alpine - -# Distroless (no shell, most secure) -FROM gcr.io/distroless/nodejs20-debian12 -``` - -### 3. Security Scanning -Integrate security scanning in CI/CD: - -```yaml -- name: Run Trivy scanner - uses: aquasecurity/trivy-action@master - with: - image-ref: ghcr.io/mohlsen/check-engine:latest - format: 'sarif' - output: 'trivy-results.sarif' - -- name: Upload Trivy results - uses: github/codeql-action/upload-sarif@v2 - with: - sarif_file: 'trivy-results.sarif' -``` - -### 4. No Secrets in Images -- Never bake secrets into images -- Use build secrets for private packages: - -```dockerfile -# Mount secret during build -RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \ - npm ci --only=production -``` - -### 5. Vulnerability Patching -- Regular base image updates -- Automated dependency updates via Dependabot -- Monitor CVE databases - ---- - -## Docker Compose Integration - -### Development Environment - -```yaml -# docker-compose.yml -version: '3.8' - -services: - check-engine: - image: ghcr.io/mohlsen/check-engine:latest - volumes: - - .:/workspace:ro - working_dir: /workspace - command: ["/workspace/package.json"] - environment: - - NODE_ENV=development - - # With custom package.json - check-custom: - image: ghcr.io/mohlsen/check-engine:latest - volumes: - - ./custom-package.json:/app/package.json:ro - command: ["/app/package.json"] - - # Full variant for complex projects - check-full: - image: ghcr.io/mohlsen/check-engine:full - volumes: - - .:/workspace:ro - working_dir: /workspace -``` - -### CI/CD Integration - -```yaml -# docker-compose.ci.yml -version: '3.8' - -services: - validate: - image: ghcr.io/mohlsen/check-engine:standard - volumes: - - .:/workspace:ro - working_dir: /workspace - command: ["/workspace/package.json"] - - # Run in CI - ci-check: - image: ghcr.io/mohlsen/check-engine:standard - volumes: - - ./package.json:/package.json:ro - command: ["/package.json", "--ignore"] - exit_code_from: 0 -``` - ---- - -## Usage Examples - -### Basic Usage - -```bash -# Pull image -docker pull ghcr.io/mohlsen/check-engine:latest - -# Run with current directory mounted -docker run --rm -v $(pwd):/workspace \ - ghcr.io/mohlsen/check-engine:latest \ - /workspace/package.json - -# Run with specific variant -docker run --rm -v $(pwd):/workspace \ - ghcr.io/mohlsen/check-engine:full \ - /workspace/package.json -``` - -### CI/CD Integration - -#### GitHub Actions -```yaml -jobs: - validate: - runs-on: ubuntu-latest - container: - image: ghcr.io/mohlsen/check-engine:standard - steps: - - uses: actions/checkout@v4 - - name: Validate environment - run: check-engine package.json -``` - -#### GitLab CI -```yaml -validate: - image: ghcr.io/mohlsen/check-engine:standard - script: - - check-engine package.json -``` - -#### Jenkins -```groovy -pipeline { - agent { - docker { - image 'ghcr.io/mohlsen/check-engine:standard' - } - } - stages { - stage('Validate') { - steps { - sh 'check-engine package.json' - } - } - } -} -``` - -### Local Development - -```bash -# Create alias for convenience -alias check-engine='docker run --rm -v $(pwd):/workspace ghcr.io/mohlsen/check-engine:latest /workspace/package.json' - -# Use like native command -check-engine - -# With options -check-engine --ignore -``` - ---- - -## Kubernetes Integration - -### Job for One-Time Validation - -```yaml -apiVersion: batch/v1 -kind: Job -metadata: - name: environment-validation -spec: - template: - spec: - restartPolicy: Never - containers: - - name: check-engine - image: ghcr.io/mohlsen/check-engine:standard - command: ["check-engine"] - args: ["/config/package.json"] - volumeMounts: - - name: config - mountPath: /config - readOnly: true - volumes: - - name: config - configMap: - name: package-json -``` - -### InitContainer for Pre-Deployment Validation - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: my-app -spec: - template: - spec: - initContainers: - - name: validate-environment - image: ghcr.io/mohlsen/check-engine:standard - command: ["check-engine"] - args: ["/config/package.json"] - volumeMounts: - - name: config - mountPath: /config - readOnly: true - - containers: - - name: app - image: my-app:latest - # ... app configuration - - volumes: - - name: config - configMap: - name: package-json -``` - -### CronJob for Periodic Validation - -```yaml -apiVersion: batch/v1 -kind: CronJob -metadata: - name: environment-check -spec: - schedule: "0 */6 * * *" # Every 6 hours - jobTemplate: - spec: - template: - spec: - restartPolicy: OnFailure - containers: - - name: check-engine - image: ghcr.io/mohlsen/check-engine:standard - command: ["check-engine"] - args: ["/config/package.json"] - volumeMounts: - - name: config - mountPath: /config - readOnly: true - volumes: - - name: config - configMap: - name: package-json -``` - ---- - -## Performance Optimization - -### 1. Layer Caching -Order Dockerfile commands from least to most frequently changing: - -```dockerfile -# Base layers (change rarely) -FROM node:20-alpine -RUN apk add --no-cache git - -# Dependencies (change occasionally) -COPY package*.json ./ -RUN npm ci --only=production - -# Application code (changes frequently) -COPY . . -``` - -### 2. .dockerignore -Exclude unnecessary files: - -``` -node_modules -npm-debug.log -.git -.github -.vscode -.DS_Store -*.md -!README.md -test -*.test.js -*.spec.js -coverage -.nyc_output -dist -build -``` - -### 3. Build Cache -Use BuildKit cache mounts: - -```dockerfile -RUN --mount=type=cache,target=/root/.npm \ - npm ci --only=production -``` - -### 4. Parallel Builds -Use GitHub Actions matrix for parallel builds: - -```yaml -strategy: - matrix: - variant: [base, standard, full] - platform: [linux/amd64, linux/arm64] -``` - ---- - -## Monitoring and Debugging - -### Health Check -Add health check to Dockerfile: - -```dockerfile -HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \ - CMD check-engine --version || exit 1 -``` - -### Logging -Configure for container environments: - -```dockerfile -ENV NODE_ENV=production -ENV LOG_LEVEL=info -ENV LOG_FORMAT=json -``` - -### Debugging -Enable debug mode: - -```bash -# Run with debug -docker run --rm -e DEBUG=check-engine:* \ - ghcr.io/mohlsen/check-engine:latest \ - package.json - -# Interactive shell for debugging -docker run --rm -it --entrypoint /bin/sh \ - ghcr.io/mohlsen/check-engine:latest -``` - ---- - -## Distribution Strategy - -### Primary: GitHub Container Registry (GHCR) -``` -ghcr.io/mohlsen/check-engine -``` - -**Advantages:** -- Free for public repositories -- Integrated with GitHub -- Automatic authentication -- Good performance - -### Secondary: Docker Hub -``` -docker.io/mohlsen/check-engine -``` - -**Advantages:** -- Most popular registry -- Better discoverability -- Broader compatibility - -### Image Synchronization -Sync images between registries: - -```yaml -- name: Push to Docker Hub - uses: akhilerm/tag-push-action@v2.1.0 - with: - src: ghcr.io/mohlsen/check-engine:${{ github.ref_name }} - dst: docker.io/mohlsen/check-engine:${{ github.ref_name }} -``` - ---- - -## Testing Strategy - -### 1. Build Testing -Test that images build successfully: - -```bash -docker build --target base -t check-engine:base . -docker build --target standard -t check-engine:standard . -docker build --target full -t check-engine:full . -``` - -### 2. Functionality Testing -Test that check-engine works in containers: - -```bash -# Test basic functionality -docker run --rm check-engine:standard --version - -# Test with sample package.json -docker run --rm -v ./test:/workspace check-engine:standard /workspace/package.json -``` - -### 3. Security Testing -Scan images for vulnerabilities: - -```bash -# Trivy scan -trivy image ghcr.io/mohlsen/check-engine:latest - -# Grype scan -grype ghcr.io/mohlsen/check-engine:latest -``` - -### 4. Size Testing -Monitor image sizes: - -```bash -docker images | grep check-engine -``` - -Target sizes: -- Base: <50MB -- Standard: <200MB -- Full: <500MB - ---- - -## Documentation Requirements - -### README Additions -- Container usage section -- Quick start with Docker -- Links to image registry -- Common use cases - -### Separate Container Docs -Create `docs/container-usage.md`: -- Detailed usage examples -- Kubernetes integration -- CI/CD examples -- Troubleshooting -- Custom image building - ---- - -## Migration Path - -### Phase 1: Create Basic Images -1. Create Dockerfile for base variant -2. Set up GitHub Actions for building -3. Push to GHCR -4. Document basic usage - -### Phase 2: Add Variants -1. Create standard variant -2. Create full variant -3. Add multi-arch support -4. Improve documentation - -### Phase 3: Advanced Features -1. Add Kubernetes manifests -2. Create Helm chart -3. Add cloud platform examples -4. Create comprehensive docs - -### Phase 4: Optimization -1. Optimize build times -2. Reduce image sizes -3. Improve caching -4. Performance tuning - ---- - -## Success Metrics - -### Build Metrics -- ✅ Build time <5 minutes per variant -- ✅ All variants build successfully -- ✅ Multi-arch support working - -### Size Metrics -- ✅ Base image <50MB -- ✅ Standard image <200MB -- ✅ Full image <500MB - -### Security Metrics -- ✅ Zero high/critical vulnerabilities -- ✅ Running as non-root -- ✅ No secrets in images - -### Usage Metrics -- ✅ Documentation complete -- ✅ Examples working -- ✅ Community feedback positive - ---- - -## Conclusion - -This containerization strategy provides a comprehensive approach to making check-engine container-ready. By offering multiple variants, supporting multiple architectures, and following security best practices, we ensure that check-engine can be used effectively in modern containerized and cloud-native environments. - -The phased approach allows for incremental implementation while maintaining quality and security standards. The resulting container images will be secure, efficient, and easy to use across a variety of platforms and use cases. - diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md deleted file mode 100644 index 117698f..0000000 --- a/IMPLEMENTATION_PLAN.md +++ /dev/null @@ -1,1193 +0,0 @@ -# check-engine Modernization Implementation Plan - -**Document Version:** 1.0 -**Date:** 2025-11-08 -**Status:** Planning Phase - -## Overview - -This document provides a detailed, step-by-step implementation plan for modernizing the check-engine project. It breaks down each recommendation into actionable tasks with estimated effort, dependencies, and acceptance criteria. - ---- - -## Phase 1: Foundation (Weeks 1-2) - -**Goal:** Address critical security, stability, and basic modernization needs. - -### 1.1 Runtime & Dependency Updates - -**Priority:** HIGH | **Effort:** 2-3 days - -#### Tasks - -**1.1.1 Update Node.js Requirements** -- [ ] Update `package.json` engines field to `"node": ">=18.0.0"` -- [ ] Update CI/CD workflows to test on Node 18, 20, 22 -- [ ] Test all functionality on each supported version -- [ ] Document breaking change in migration guide - -**Dependencies:** None -**Acceptance Criteria:** -- All tests pass on Node 18.x, 20.x, 22.x -- CI runs successfully on all versions -- Documentation updated - ---- - -**1.1.2 Update Core Dependencies** -- [ ] Update `semver` to latest (7.6.x) -- [ ] Update `yargs` to latest (17.7.x) -- [ ] Update `jsonfile` to latest (6.1.x) -- [ ] Review if `jsonfile` can be replaced with native `fs.readFile` + `JSON.parse` -- [ ] Run tests after each update - -**Dependencies:** None -**Acceptance Criteria:** -- All dependencies at latest stable versions -- All tests pass -- No new security vulnerabilities - ---- - -**1.1.3 Replace/Modernize Legacy Dependencies** -- [ ] Evaluate removing `bluebird` in favor of native async/await -- [ ] Replace `colors` with `chalk` or native ANSI codes -- [ ] Update `command-line-usage` if newer version available -- [ ] Create adapter layer if needed for backward compatibility - -**Dependencies:** None -**Acceptance Criteria:** -- Native promises used throughout -- Modern color library integrated -- All tests pass -- API remains backward compatible - ---- - -**1.1.4 Update DevDependencies** -- [ ] Update ESLint to 8.x (prepare for 9.x in Phase 2) -- [ ] Update test dependencies (`tape`, `tap-min`) -- [ ] Update `proxyquire` if still needed -- [ ] Run linter and tests after updates - -**Dependencies:** None -**Acceptance Criteria:** -- All dev dependencies updated -- Linter and tests work correctly -- No breaking changes in developer workflow - ---- - -### 1.2 Security Enhancements - -**Priority:** HIGH | **Effort:** 1-2 days - -#### Tasks - -**1.2.1 Fix Current Vulnerabilities** -- [ ] Run `npm audit fix` to address brace-expansion vulnerability -- [ ] Run `npm audit fix` to address cross-spawn vulnerability -- [ ] Verify fixes don't break functionality -- [ ] Run full test suite -- [ ] Document any manual fixes needed - -**Dependencies:** None -**Acceptance Criteria:** -- `npm audit` shows 0 vulnerabilities -- All tests pass -- No functionality broken - ---- - -**1.2.2 Add Security Workflows** -- [ ] Create `.github/workflows/security.yml` -- [ ] Add npm audit check to CI -- [ ] Add CodeQL workflow for static analysis -- [ ] Add Dependabot security alerts (already configured) -- [ ] Configure branch protection rules - -**Example Security Workflow:** -```yaml -name: Security - -on: - push: - branches: [master] - pull_request: - branches: [master] - schedule: - - cron: '0 0 * * 0' # Weekly - -jobs: - audit: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-node@v4 - with: - node-version: '20' - - run: npm ci - - run: npm audit --audit-level=moderate -``` - -**Dependencies:** None -**Acceptance Criteria:** -- Security workflow runs on every PR -- CodeQL scans complete successfully -- Alerts configured in GitHub - ---- - -**1.2.3 Create Security Documentation** -- [ ] Create `SECURITY.md` with: - - Supported versions - - Vulnerability reporting process - - Security update policy - - Contact information -- [ ] Add security badge to README -- [ ] Document security best practices for contributors - -**Dependencies:** None -**Acceptance Criteria:** -- SECURITY.md exists and is comprehensive -- README links to security policy -- Clear reporting process - ---- - -### 1.3 Documentation Enhancements - -**Priority:** HIGH | **Effort:** 2-3 days - -#### Tasks - -**1.3.1 Create CONTRIBUTING.md** -- [ ] Write development setup instructions -- [ ] Document coding standards -- [ ] Explain PR process -- [ ] Add commit message guidelines -- [ ] Include testing requirements -- [ ] Add release process documentation - -**Template Structure:** -```markdown -# Contributing to check-engine - -## Development Setup -## Coding Standards -## Testing -## Pull Request Process -## Release Process -## Code of Conduct -``` - -**Dependencies:** None -**Acceptance Criteria:** -- CONTRIBUTING.md is comprehensive -- New contributors can follow it easily -- All common questions answered - ---- - -**1.3.2 Create CHANGELOG.md** -- [ ] Set up Keep a Changelog format -- [ ] Document all previous releases (extract from git tags) -- [ ] Set up automated changelog generation -- [ ] Link from README - -**Dependencies:** None -**Acceptance Criteria:** -- CHANGELOG.md follows Keep a Changelog format -- All versions documented -- Linked from README - ---- - -**1.3.3 Add CODE_OF_CONDUCT.md** -- [ ] Adopt Contributor Covenant or similar -- [ ] Add contact information for violations -- [ ] Link from README and CONTRIBUTING - -**Dependencies:** None -**Acceptance Criteria:** -- CODE_OF_CONDUCT.md present -- Contact method clear -- Linked from other docs - ---- - -**1.3.4 Enhance README.md** -- [ ] Add badges (build status, coverage, version, downloads) -- [ ] Improve examples section -- [ ] Add troubleshooting section -- [ ] Add FAQ section -- [ ] Update installation instructions -- [ ] Add links to new documentation -- [ ] Add screenshots/animated GIFs if applicable - -**Dependencies:** 1.3.1, 1.3.2, 1.3.3 -**Acceptance Criteria:** -- README is comprehensive and well-organized -- Examples cover common use cases -- Professional appearance - ---- - -**1.3.5 Create Advanced Documentation** -- [ ] Create `docs/` folder -- [ ] Write architecture overview -- [ ] Document validator system design -- [ ] Create guide for adding new validators -- [ ] Write integration examples -- [ ] Create API reference - -**Dependencies:** None -**Acceptance Criteria:** -- docs/ folder structure clear -- All key topics covered -- Examples work correctly - ---- - -### 1.4 Containerization Support - -**Priority:** HIGH | **Effort:** 2-3 days - -#### Tasks - -**1.4.1 Create Dockerfile** -- [ ] Create multi-stage Dockerfile -- [ ] Install necessary system tools (git, etc.) -- [ ] Optimize image size -- [ ] Use Alpine or slim base image -- [ ] Support multiple architectures (amd64, arm64) -- [ ] Add health check - -**Example Dockerfile:** -```dockerfile -# Build stage -FROM node:20-alpine AS builder -WORKDIR /app -COPY package*.json ./ -RUN npm ci --only=production - -# Production stage -FROM node:20-alpine -RUN apk add --no-cache git -WORKDIR /app -COPY --from=builder /app/node_modules ./node_modules -COPY . . -ENTRYPOINT ["node", "/app/bin/check-engine.js"] -CMD ["--help"] -``` - -**Dependencies:** None -**Acceptance Criteria:** -- Dockerfile builds successfully -- Image size optimized (<100MB) -- Works on amd64 and arm64 -- All validators work in container - ---- - -**1.4.2 Create docker-compose.yml** -- [ ] Set up docker-compose for local development -- [ ] Mount local directory for testing -- [ ] Configure environment variables -- [ ] Add examples for different use cases - -**Dependencies:** 1.4.1 -**Acceptance Criteria:** -- docker-compose.yml works correctly -- Examples documented -- Easy to use for testing - ---- - -**1.4.3 Create .dockerignore** -- [ ] Exclude node_modules -- [ ] Exclude .git -- [ ] Exclude test files -- [ ] Exclude development files - -**Dependencies:** None -**Acceptance Criteria:** -- Build is faster -- Image is smaller -- No unnecessary files - ---- - -**1.4.4 Add Container Documentation** -- [ ] Document how to build image -- [ ] Document how to use image -- [ ] Provide usage examples -- [ ] Document environment variables -- [ ] Add to README - -**Dependencies:** 1.4.1, 1.4.2 -**Acceptance Criteria:** -- Documentation clear and complete -- Examples work -- Common issues addressed - ---- - -**1.4.5 Set up Container Registry** -- [ ] Configure GitHub Actions for image building -- [ ] Push to GitHub Container Registry (ghcr.io) -- [ ] Tag images appropriately (latest, version, sha) -- [ ] Document how to pull images -- [ ] Consider Docker Hub publication - -**Dependencies:** 1.4.1 -**Acceptance Criteria:** -- Images automatically built on release -- Images available on ghcr.io -- Versioning clear -- Pull instructions documented - ---- - -## Phase 2: Modernization (Weeks 3-4) - -**Goal:** Improve development experience and code quality. - -### 2.1 Code Quality Tooling - -**Priority:** MEDIUM | **Effort:** 1-2 days - -#### Tasks - -**2.1.1 Update ESLint Configuration** -- [ ] Migrate to ESLint v9 flat config -- [ ] Update rules for modern JavaScript -- [ ] Add TypeScript support (if implementing TypeScript) -- [ ] Configure for ES modules -- [ ] Add custom rules if needed - -**Dependencies:** None -**Acceptance Criteria:** -- ESLint 9.x working -- All rules appropriate -- No errors on existing code -- Documentation updated - ---- - -**2.1.2 Add Prettier** -- [ ] Install Prettier -- [ ] Create `.prettierrc` configuration -- [ ] Create `.prettierignore` -- [ ] Format all existing code -- [ ] Add prettier check to CI -- [ ] Integrate with ESLint - -**Dependencies:** None -**Acceptance Criteria:** -- All code formatted consistently -- CI checks formatting -- No conflicts with ESLint - ---- - -**2.1.3 Set up Husky and lint-staged** -- [ ] Install husky -- [ ] Install lint-staged -- [ ] Configure pre-commit hook -- [ ] Configure commit-msg hook (for commitlint) -- [ ] Test hooks work correctly - -**Dependencies:** 2.1.1, 2.1.2 -**Acceptance Criteria:** -- Git hooks work correctly -- Bad code can't be committed -- Commit messages validated - ---- - -**2.1.4 Add commitlint** -- [ ] Install commitlint -- [ ] Configure for conventional commits -- [ ] Add commit-msg hook -- [ ] Document commit format -- [ ] Update CONTRIBUTING.md - -**Dependencies:** 2.1.3 -**Acceptance Criteria:** -- Commit messages validated -- Conventional commits enforced -- Documentation clear - ---- - -**2.1.5 Add EditorConfig** -- [ ] Create `.editorconfig` -- [ ] Configure indentation, line endings, etc. -- [ ] Document in CONTRIBUTING.md - -**Dependencies:** None -**Acceptance Criteria:** -- EditorConfig file present -- Consistent editor settings -- Works across IDEs - ---- - -### 2.2 Testing Modernization - -**Priority:** MEDIUM | **Effort:** 2-4 days - -#### Tasks - -**2.2.1 Choose and Set up Modern Test Framework** -- [ ] Decide between Jest and Vitest -- [ ] Install chosen framework -- [ ] Configure test framework -- [ ] Set up coverage reporting -- [ ] Configure for both unit and integration tests - -**Recommendation:** Vitest for modern projects, Jest for broader ecosystem - -**Dependencies:** None -**Acceptance Criteria:** -- Test framework installed -- Basic tests run -- Coverage reports generated - ---- - -**2.2.2 Migrate Existing Tests** -- [ ] Convert checkSystem.spec.js -- [ ] Convert validatorRules.spec.js -- [ ] Ensure all tests pass -- [ ] Maintain or improve coverage -- [ ] Remove tape and tap-min - -**Dependencies:** 2.2.1 -**Acceptance Criteria:** -- All tests migrated -- All tests pass -- Coverage maintained or improved -- Old framework removed - ---- - -**2.2.3 Add Integration Tests** -- [ ] Create integration test suite -- [ ] Test CLI with various inputs -- [ ] Test programmatic API -- [ ] Test error conditions -- [ ] Test with different package.json configurations - -**Dependencies:** 2.2.1 -**Acceptance Criteria:** -- Integration tests cover main workflows -- Tests run in CI -- Tests are reliable - ---- - -**2.2.4 Set up Coverage Reporting** -- [ ] Configure coverage thresholds (>80%) -- [ ] Add coverage to CI -- [ ] Upload coverage to Codecov or Coveralls -- [ ] Add coverage badge to README -- [ ] Block PRs that decrease coverage - -**Dependencies:** 2.2.1, 2.2.2 -**Acceptance Criteria:** -- Coverage tracked automatically -- Badge shows current coverage -- CI fails on coverage decrease - ---- - -**2.2.5 Add E2E Tests** -- [ ] Create E2E test suite -- [ ] Test with real package.json files -- [ ] Test with real system tools -- [ ] Test container usage -- [ ] Test CLI output formats - -**Dependencies:** 2.2.1 -**Acceptance Criteria:** -- E2E tests cover critical paths -- Tests run reliably -- Tests catch real issues - ---- - -### 2.3 TypeScript Migration - -**Priority:** MEDIUM | **Effort:** 3-5 days - -#### Tasks - -**2.3.1 Set up TypeScript** -- [ ] Install TypeScript -- [ ] Create `tsconfig.json` -- [ ] Configure for Node.js -- [ ] Set up build process -- [ ] Configure source maps - -**Dependencies:** None -**Acceptance Criteria:** -- TypeScript compiles successfully -- Source maps work -- Build output correct - ---- - -**2.3.2 Add Type Definitions** -- [ ] Create `src/types/` folder -- [ ] Define interfaces for public API -- [ ] Define types for internal structures -- [ ] Export types for consumers -- [ ] Generate .d.ts files - -**Dependencies:** 2.3.1 -**Acceptance Criteria:** -- Type definitions complete -- Types exported correctly -- IDE autocomplete works - ---- - -**2.3.3 Convert Core Files** -- [ ] Convert checkSystem.js to .ts -- [ ] Convert validatorRules.js to .ts -- [ ] Convert promiseHelpers.js to .ts -- [ ] Convert bin/check-engine.js to .ts -- [ ] Fix all type errors - -**Dependencies:** 2.3.1, 2.3.2 -**Acceptance Criteria:** -- All files converted -- No type errors -- All tests pass - ---- - -**2.3.4 Update Tests for TypeScript** -- [ ] Convert test files to .ts -- [ ] Add type assertions -- [ ] Fix any type issues -- [ ] Ensure coverage maintained - -**Dependencies:** 2.3.3, 2.2.2 -**Acceptance Criteria:** -- Test files converted -- All tests pass -- Type safety in tests - ---- - -**2.3.5 Update Build and Release Process** -- [ ] Update package.json scripts -- [ ] Configure TypeScript compilation -- [ ] Set up pre-publish build -- [ ] Test published package -- [ ] Update documentation - -**Dependencies:** 2.3.3 -**Acceptance Criteria:** -- Build process works -- Package publishes correctly -- Types available to consumers - ---- - -### 2.4 CI/CD Pipeline Enhancements - -**Priority:** MEDIUM | **Effort:** 2-3 days - -#### Tasks - -**2.4.1 Separate Workflows** -- [ ] Create `pull_request.yml` workflow -- [ ] Create `release.yml` workflow -- [ ] Create `security.yml` workflow -- [ ] Create `docker.yml` workflow -- [ ] Update existing `validation.yml` - -**Dependencies:** None -**Acceptance Criteria:** -- Each workflow has clear purpose -- No duplicate work -- Fast feedback - ---- - -**2.4.2 Add Multi-Platform Testing** -- [ ] Test on Ubuntu (already done) -- [ ] Test on macOS -- [ ] Test on Windows -- [ ] Matrix test Node versions (18, 20, 22) -- [ ] Optimize for speed - -**Dependencies:** None -**Acceptance Criteria:** -- Tests run on all platforms -- Platform-specific issues caught -- CI completes in <10 minutes - ---- - -**2.4.3 Add Release Automation** -- [ ] Install release-please -- [ ] Configure release-please -- [ ] Automate version bumping -- [ ] Automate CHANGELOG updates -- [ ] Automate GitHub releases -- [ ] Automate npm publishing - -**Dependencies:** 1.3.2 -**Acceptance Criteria:** -- Releases fully automated -- Changelog updated automatically -- npm package published automatically - ---- - -**2.4.4 Add Security Scanning** -- [ ] Add CodeQL workflow (from 1.2.2) -- [ ] Add dependency review -- [ ] Add SAST scanning -- [ ] Configure alerts -- [ ] Add security checks to PR workflow - -**Dependencies:** 1.2.2 -**Acceptance Criteria:** -- Security scans run automatically -- Vulnerabilities caught early -- Clear alerts on issues - ---- - -**2.4.5 Add Performance Benchmarking** -- [ ] Create benchmark suite -- [ ] Add benchmark workflow -- [ ] Track performance over time -- [ ] Alert on regressions -- [ ] Document benchmarks - -**Dependencies:** None -**Acceptance Criteria:** -- Benchmarks run automatically -- Performance tracked -- Regressions caught - ---- - -## Phase 3: Enhancement (Weeks 5-6) - -**Goal:** Add modern features and improve the API. - -### 3.1 API Modernization - -**Priority:** MEDIUM | **Effort:** 2-3 days - -#### Tasks - -**3.1.1 Remove Bluebird (if not done in Phase 1)** -- [ ] Convert all Promise usage to native -- [ ] Remove Bluebird dependency -- [ ] Update all async code -- [ ] Test thoroughly - -**Dependencies:** 1.1.3 -**Acceptance Criteria:** -- No Bluebird dependency -- All async code uses native promises -- All tests pass - ---- - -**3.1.2 Add ESM Support** -- [ ] Configure package.json for dual mode -- [ ] Create ESM entry point -- [ ] Maintain CJS compatibility -- [ ] Test both module formats -- [ ] Document usage - -**Dependencies:** 2.3.5 (if using TypeScript) -**Acceptance Criteria:** -- ESM and CJS both work -- Exports configured correctly -- Tests pass for both formats - ---- - -**3.1.3 Enhance Configuration Options** -- [ ] Add options object to check function -- [ ] Support timeout configuration -- [ ] Support parallel execution -- [ ] Support custom validators -- [ ] Support output formatting options - -**Example:** -```typescript -interface CheckOptions { - packageJsonPath?: string; - parallel?: boolean; - timeout?: number; - customValidators?: Record; - format?: 'json' | 'text' | 'yaml'; - onProgress?: (pkg: Package) => void; -} -``` - -**Dependencies:** 2.3.2 (if using TypeScript) -**Acceptance Criteria:** -- Options well documented -- All options work correctly -- Backward compatible -- Tests cover all options - ---- - -**3.1.4 Add Event-Based Progress** -- [ ] Implement EventEmitter or custom events -- [ ] Emit progress events -- [ ] Emit validation events -- [ ] Document events -- [ ] Add examples - -**Dependencies:** None -**Acceptance Criteria:** -- Events work correctly -- Documentation clear -- Examples provided - ---- - -**3.1.5 Improve Error Handling** -- [ ] Create custom error classes -- [ ] Add error codes -- [ ] Improve error messages -- [ ] Add context to errors -- [ ] Document errors - -**Dependencies:** None -**Acceptance Criteria:** -- Errors are clear and actionable -- Error codes documented -- Easy to debug - ---- - -### 3.2 Developer Experience Improvements - -**Priority:** MEDIUM | **Effort:** 1-2 days - -#### Tasks - -**3.2.1 Add VS Code Configuration** -- [ ] Create `.vscode/` folder -- [ ] Add recommended extensions -- [ ] Add debug configurations -- [ ] Add tasks for common operations -- [ ] Add settings - -**Dependencies:** None -**Acceptance Criteria:** -- VS Code configuration works -- Debugging easy -- Tasks useful - ---- - -**3.2.2 Improve Package Scripts** -- [ ] Add `dev` script with watch mode -- [ ] Add `build` script -- [ ] Add `coverage` script -- [ ] Add `docs` script -- [ ] Add `clean` script -- [ ] Document all scripts - -**Dependencies:** None -**Acceptance Criteria:** -- All scripts work -- Scripts documented -- Development workflow smooth - ---- - -**3.2.3 Add Codespaces Configuration** -- [ ] Create `.devcontainer/` folder -- [ ] Configure devcontainer.json -- [ ] Add necessary extensions -- [ ] Pre-install dependencies -- [ ] Test in Codespaces - -**Dependencies:** 1.4.1 -**Acceptance Criteria:** -- Codespaces works -- All tools available -- Fast startup - ---- - -**3.2.4 Add Gitpod Configuration** -- [ ] Create `.gitpod.yml` -- [ ] Configure environment -- [ ] Pre-install dependencies -- [ ] Test in Gitpod - -**Dependencies:** None -**Acceptance Criteria:** -- Gitpod works -- Environment ready -- Fast startup - ---- - -**3.2.5 Improve CLI UX** -- [ ] Add progress indicators -- [ ] Add verbose/debug mode -- [ ] Add quiet mode -- [ ] Improve error messages -- [ ] Add colors and formatting - -**Dependencies:** None -**Acceptance Criteria:** -- CLI more user-friendly -- Feedback clear -- Options well documented - ---- - -### 3.3 Kubernetes & Cloud-Native Support - -**Priority:** MEDIUM | **Effort:** 2-3 days - -#### Tasks - -**3.3.1 Create Kubernetes Manifests** -- [ ] Create Job manifest -- [ ] Create CronJob manifest -- [ ] Create InitContainer example -- [ ] Create ConfigMap for package.json -- [ ] Document usage - -**Dependencies:** 1.4.1 -**Acceptance Criteria:** -- Manifests work correctly -- Examples clear -- Documentation complete - ---- - -**3.3.2 Create Helm Chart** -- [ ] Initialize Helm chart -- [ ] Configure values.yaml -- [ ] Create templates -- [ ] Test chart installation -- [ ] Document usage - -**Dependencies:** 3.3.1 -**Acceptance Criteria:** -- Helm chart works -- Customizable via values -- Documentation complete - ---- - -**3.3.3 Add Cloud Platform Examples** -- [ ] Create AWS ECS example -- [ ] Create AWS EKS example -- [ ] Create Google Cloud Run example -- [ ] Create GKE example -- [ ] Create Azure ACI example -- [ ] Create AKS example - -**Dependencies:** 1.4.1 -**Acceptance Criteria:** -- Examples work -- Each platform documented -- Common pitfalls addressed - ---- - -**3.3.4 Create CI/CD Integration Examples** -- [ ] GitHub Actions example -- [ ] GitLab CI example -- [ ] Jenkins example -- [ ] CircleCI example -- [ ] Azure DevOps example - -**Dependencies:** 3.3.1 -**Acceptance Criteria:** -- Examples work -- Common patterns documented -- Easy to adapt - ---- - -### 3.4 Package Manager Modernization - -**Priority:** LOW-MEDIUM | **Effort:** 1-2 days - -#### Tasks - -**3.4.1 Add Bun Validator** -- [ ] Implement bun version check -- [ ] Add to validatorRules.js -- [ ] Add tests -- [ ] Document in README - -**Dependencies:** None -**Acceptance Criteria:** -- Bun validator works -- Tests pass -- Documented - ---- - -**3.4.2 Add Deno Validator** -- [ ] Implement deno version check -- [ ] Add to validatorRules.js -- [ ] Add tests -- [ ] Document in README - -**Dependencies:** None -**Acceptance Criteria:** -- Deno validator works -- Tests pass -- Documented - ---- - -**3.4.3 Add Volta Validator** -- [ ] Implement volta version check -- [ ] Add to validatorRules.js -- [ ] Add tests -- [ ] Document in README - -**Dependencies:** None -**Acceptance Criteria:** -- Volta validator works -- Tests pass -- Documented - ---- - -**3.4.4 Improve Existing Validators** -- [ ] Better version detection -- [ ] Support for version managers -- [ ] Better error messages -- [ ] Add more validation options - -**Dependencies:** None -**Acceptance Criteria:** -- Validators more robust -- Better user experience -- Tests comprehensive - ---- - -## Phase 4: Expansion (Weeks 7+) - -**Goal:** Optional enhancements and new features. - -### 4.1 Output & Reporting Enhancements - -**Priority:** LOW-MEDIUM | **Effort:** 1-2 days - -#### Tasks - -**4.1.1 Add Multiple Output Formats** -- [ ] Implement JSON format -- [ ] Implement YAML format -- [ ] Implement JUnit XML format -- [ ] Implement HTML format -- [ ] Implement Markdown format - -**Dependencies:** None -**Acceptance Criteria:** -- All formats work -- Formats well-formed -- Easy to switch formats - ---- - -**4.1.2 Improve Terminal Output** -- [ ] Better colors and formatting -- [ ] Add summary statistics -- [ ] Add icons/emojis -- [ ] Improve table layout -- [ ] Add progress bars - -**Dependencies:** None -**Acceptance Criteria:** -- Output looks professional -- Information clear -- Customizable - ---- - -**4.1.3 Add Custom Formatters** -- [ ] Allow custom formatter functions -- [ ] Document formatter API -- [ ] Provide examples -- [ ] Test custom formatters - -**Dependencies:** 4.1.1 -**Acceptance Criteria:** -- Custom formatters work -- API documented -- Examples clear - ---- - -### 4.2 Platform & Tool Expansion - -**Priority:** LOW | **Effort:** Variable - -#### Tasks - -**4.2.1 Add Container Tool Validators** -- [ ] Docker validator -- [ ] Podman validator -- [ ] Buildah validator - -**4.2.2 Add Cloud Tool Validators** -- [ ] kubectl validator -- [ ] helm validator -- [ ] terraform validator -- [ ] aws-cli validator -- [ ] gcloud validator -- [ ] az validator - -**4.2.3 Add Build Tool Validators** -- [ ] make validator -- [ ] cmake validator -- [ ] gradle validator -- [ ] maven validator (improve existing) - -**4.2.4 Add Language Runtime Validators** -- [ ] python validator -- [ ] ruby validator -- [ ] go validator -- [ ] rust validator - -**4.2.5 Add Version Manager Validators** -- [ ] nvm validator -- [ ] fnm validator -- [ ] asdf validator -- [ ] pyenv validator -- [ ] rbenv validator - -**4.2.6 Make Validators Pluggable** -- [ ] Design plugin system -- [ ] Implement plugin loader -- [ ] Document plugin API -- [ ] Provide examples - ---- - -### 4.3 Monitoring & Telemetry - -**Priority:** LOW | **Effort:** 1-2 days - -#### Tasks - -**4.3.1 Add Optional Telemetry** -- [ ] Implement opt-in telemetry -- [ ] Collect usage statistics -- [ ] Track error rates -- [ ] Respect user privacy -- [ ] Add opt-out instructions - -**4.3.2 Add Monitoring Integration** -- [ ] Add Prometheus metrics -- [ ] Add OpenTelemetry support -- [ ] Add StatsD support -- [ ] Add health check endpoint - -**4.3.3 Document Telemetry** -- [ ] What is collected -- [ ] How to opt out -- [ ] How data is used -- [ ] Privacy policy - ---- - -## Success Criteria - -### Phase 1 Complete -- ✅ Node.js 18+ required -- ✅ 0 security vulnerabilities -- ✅ Container image available -- ✅ Complete documentation -- ✅ Security policy in place - -### Phase 2 Complete -- ✅ Modern test framework -- ✅ >90% test coverage -- ✅ ESLint 9 + Prettier -- ✅ Pre-commit hooks working -- ✅ TypeScript support (optional) -- ✅ Automated releases - -### Phase 3 Complete -- ✅ Modern API with options -- ✅ ESM support -- ✅ Kubernetes examples -- ✅ Cloud platform examples -- ✅ Better DX with VS Code config - -### Phase 4 Complete -- ✅ Multiple output formats -- ✅ Extended validator library -- ✅ Plugin system (optional) -- ✅ Monitoring support (optional) - ---- - -## Risk Management - -### Technical Risks -- **Breaking changes:** Mitigate with semantic versioning and deprecation warnings -- **Test failures:** Maintain comprehensive test suite -- **Performance regression:** Add benchmarking -- **Compatibility issues:** Test on multiple platforms - -### Project Risks -- **Scope creep:** Stick to phased approach -- **Timeline delays:** Prioritize critical items -- **Resource constraints:** Focus on high-priority items first - ---- - -## Timeline Summary - -| Phase | Duration | Priority | Key Deliverables | -|-------|----------|----------|------------------| -| Phase 1 | 2 weeks | HIGH | Security, Docs, Containers | -| Phase 2 | 2 weeks | MEDIUM | Testing, TypeScript, CI/CD | -| Phase 3 | 2 weeks | MEDIUM | API, K8s, DX | -| Phase 4 | Ongoing | LOW | Expansion features | - -**Total Estimated Time:** 6-8 weeks for core modernization - ---- - -## Next Steps - -1. ✅ Review and approve this implementation plan -2. ⬜ Set up project board for tracking -3. ⬜ Begin Phase 1 implementation -4. ⬜ Regular progress reviews -5. ⬜ Community engagement and feedback - ---- - -## Notes - -- This is a living document and should be updated as work progresses -- Priorities may shift based on user feedback and real-world needs -- Some tasks may be parallelized for efficiency -- Community contributions welcome for any phase - diff --git a/MODERNIZATION_PLAN.md b/MODERNIZATION_PLAN.md new file mode 100644 index 0000000..8871cc0 --- /dev/null +++ b/MODERNIZATION_PLAN.md @@ -0,0 +1,611 @@ +# check-engine Modernization Plan + +**Document Version:** 1.0 +**Date:** 2025-11-08 +**Status:** Planning Phase + +## Executive Summary + +The `check-engine` project is a valuable Node.js utility that developers run manually or include in scripts/workflows to validate their development environment. This plan focuses on modernizing the tool itself to align with current best practices while expanding its ability to validate modern development tools and environments. + +## What check-engine Is + +check-engine is a **command-line utility** and **programmatic library** that: +- Validates that required tools are installed (node, npm, git, etc.) +- Checks tool versions against requirements in package.json +- Runs locally on developer machines or in CI/CD pipelines +- Helps teams maintain consistent development environments + +## What check-engine Is NOT + +- ❌ Not a cloud service or deployed application +- ❌ Not a containerized service +- ❌ Not a Kubernetes workload +- ❌ Not a SaaS offering + +## Current State Assessment + +### Strengths +- ✅ Working core functionality +- ✅ Good test coverage (91 tests passing) +- ✅ Active GitHub Actions CI/CD +- ✅ Dependabot configured for dependency updates +- ✅ Clean, readable codebase +- ✅ Semantic versioning support +- ✅ MIT License (permissive) + +### Areas for Improvement +- ⚠️ Node.js requirement outdated (>=10, should be >=18 or >=20) +- ⚠️ Security vulnerabilities in dependencies (2 identified) +- ⚠️ Legacy testing framework (tape) +- ⚠️ No TypeScript support +- ⚠️ Missing documentation (CONTRIBUTING, CHANGELOG) +- ⚠️ Limited modern tool support (docker, kubectl, terraform, etc.) +- ⚠️ Limited modern package manager support (no bun, no volta) +- ⚠️ No pre-commit hooks +- ⚠️ Basic linting configuration + +--- + +## Modernization Recommendations + +### Phase 1: Foundation (Weeks 1-2) - HIGH Priority + +#### 1.1 Update Runtime & Dependencies + +**Priority:** HIGH | **Effort:** 2-3 days + +**Tasks:** +- Update minimum Node.js version to `>=18` (LTS) or `>=20` (current LTS) +- Fix security vulnerabilities via `npm audit fix` +- Update ESLint to latest version (v9.x with flat config) +- Update all dependencies to latest stable versions +- Replace `bluebird` with native async/await +- Consider replacing `colors` with `chalk` or native ANSI codes + +**Benefits:** +- Improved performance and security +- Access to modern JavaScript features +- Better developer experience +- Reduced technical debt + +--- + +#### 1.2 Security Enhancements + +**Priority:** HIGH | **Effort:** 1 day + +**Tasks:** +- Fix current vulnerabilities (brace-expansion, cross-spawn) +- Add npm audit check to CI/CD +- Add CodeQL workflow for static analysis +- Create SECURITY.md with vulnerability reporting process +- Configure Dependabot security alerts + +**Benefits:** +- Zero known vulnerabilities +- Proactive security monitoring +- Clear security policy + +--- + +#### 1.3 Documentation Improvements + +**Priority:** HIGH | **Effort:** 2-3 days + +**Tasks:** +- Create CONTRIBUTING.md with development guidelines +- Create CHANGELOG.md following Keep a Changelog format +- Add CODE_OF_CONDUCT.md +- Enhance README.md with: + - Better examples + - Troubleshooting section + - FAQ section + - Badges (build status, version, downloads) +- Add docs/ folder with: + - Architecture overview + - Adding new validators guide + - Integration examples for CI/CD + +**Benefits:** +- Better onboarding for contributors +- Clearer communication +- Professional appearance +- Easier to maintain and extend + +--- + +### Phase 2: Modernization (Weeks 3-4) - MEDIUM Priority + +#### 2.1 Testing Modernization + +**Priority:** MEDIUM | **Effort:** 2-4 days + +**Tasks:** +- Migrate from tape to Vitest or Jest +- Add test coverage reporting (>80% threshold) +- Add integration tests for CLI +- Set up coverage tracking (Codecov/Coveralls) +- Add test coverage badges to README + +**Framework Recommendation:** Vitest (faster, modern) or Jest (industry standard) + +**Benefits:** +- Better testing experience +- Visual coverage reports +- More comprehensive test coverage +- Easier to write and maintain tests + +--- + +#### 2.2 Code Quality Tooling + +**Priority:** MEDIUM | **Effort:** 1-2 days + +**Tasks:** +- Update ESLint to v9 with flat config +- Add Prettier for consistent formatting +- Add husky for git hooks +- Add lint-staged for pre-commit linting +- Add commitlint for conventional commits +- Configure EditorConfig + +**Benefits:** +- Consistent code style +- Prevent bad commits +- Better commit history +- Automated code quality checks + +--- + +#### 2.3 TypeScript Migration (Optional) + +**Priority:** MEDIUM | **Effort:** 3-5 days + +**Tasks:** +- Add TypeScript configuration (tsconfig.json) +- Convert to TypeScript or add JSDoc type annotations +- Provide type definitions for programmatic API +- Maintain backward compatibility with JavaScript consumers + +**Benefits:** +- Better IDE support and autocomplete +- Catch errors at compile time +- Improved documentation through types +- Easier refactoring + +--- + +#### 2.4 CI/CD Pipeline Enhancements + +**Priority:** MEDIUM | **Effort:** 2 days + +**Tasks:** +- Test on multiple Node.js versions (18, 20, 22) +- Test on multiple OS (Ubuntu, macOS, Windows) +- Add CodeQL security scanning +- Add automated release process (release-please) +- Add performance benchmarking + +**Benefits:** +- Multi-platform support verified +- Automated release process +- Better security posture +- Performance tracking + +--- + +### Phase 3: Feature Enhancement (Weeks 5-6) - MEDIUM Priority + +#### 3.1 Add Modern Tool Validators + +**Priority:** MEDIUM | **Effort:** 3-5 days + +**Focus:** Add validators for tools developers use to build/deploy containerized and cloud applications + +**New Validators to Add:** +- **Container Tools:** + - `docker` - Docker CLI for building containers + - `docker-compose` - Docker Compose for local development + - `podman` - Alternative container runtime + +- **Kubernetes Tools:** + - `kubectl` - Kubernetes CLI + - `helm` - Kubernetes package manager + - `minikube` - Local Kubernetes for development + - `kind` - Kubernetes in Docker + +- **Cloud Platform CLIs:** + - `aws` - AWS CLI + - `gcloud` - Google Cloud CLI + - `az` - Azure CLI + +- **Infrastructure as Code:** + - `terraform` - Infrastructure provisioning + - `pulumi` - Modern IaC tool + +- **Modern Package Managers:** + - `bun` - Fast all-in-one JavaScript runtime + - `volta` - JavaScript tool version manager + - `fnm` - Fast Node Manager + +- **Build Tools:** + - `make` - GNU Make + - `cmake` - Cross-platform build system + - `gradle` - Java/Android build tool + +**Benefits:** +- Support for modern development workflows +- Validate environments for container/cloud development +- Help teams ensure correct tool installation +- More comprehensive environment validation + +--- + +#### 3.2 API Modernization + +**Priority:** MEDIUM | **Effort:** 2-3 days + +**Tasks:** +- Convert to native async/await (remove Bluebird) +- Add ESM module support (maintain CJS compatibility) +- Improve error handling with custom error classes +- Add configuration options: + - Timeout settings + - Parallel execution + - Custom validators + - Output formatting +- Add event emitters for progress tracking + +**Benefits:** +- Modern JavaScript patterns +- Better error handling +- More flexible API +- Better performance options + +--- + +#### 3.3 Output & Reporting Enhancements + +**Priority:** LOW-MEDIUM | **Effort:** 1-2 days + +**Tasks:** +- Add multiple output formats: + - JSON (machine-readable) + - YAML + - JUnit XML (for CI/CD) + - Markdown +- Improve colored terminal output +- Add summary statistics +- Add quiet mode and verbose/debug mode +- Better exit codes for different scenarios + +**Benefits:** +- Better CI/CD integration +- More flexible reporting +- Easier debugging +- Better user experience + +--- + +### Phase 4: Polish & Extension (Ongoing) - LOW Priority + +#### 4.1 Developer Experience Improvements + +**Priority:** LOW | **Effort:** 1-2 days + +**Tasks:** +- Add VS Code configuration: + - Recommended extensions + - Debug configurations + - Tasks for common operations +- Improve CLI UX: + - Progress indicators + - Better error messages + - Helpful hints +- Add development scripts in package.json +- Add GitHub Codespaces configuration + +**Benefits:** +- Faster onboarding +- Better debugging +- More productive development + +--- + +#### 4.2 Extensibility + +**Priority:** LOW | **Effort:** 2-3 days + +**Tasks:** +- Allow custom validators via configuration +- Plugin system for external validators +- Validator marketplace/registry (future) +- Document validator API + +**Benefits:** +- Community can add validators +- Extensible architecture +- Support for niche tools + +--- + +## Implementation Timeline + +### Phase 1: Foundation (Weeks 1-2) +**Focus:** Security, dependencies, documentation + +**Deliverables:** +- ✅ Node.js 18+ support +- ✅ Zero security vulnerabilities +- ✅ Complete documentation (CONTRIBUTING, CHANGELOG, SECURITY, CODE_OF_CONDUCT) +- ✅ Enhanced README + +**Estimated Effort:** 5-7 days + +--- + +### Phase 2: Modernization (Weeks 3-4) +**Focus:** Testing, code quality, CI/CD + +**Deliverables:** +- ✅ Modern testing framework (Vitest/Jest) +- ✅ >80% test coverage +- ✅ Pre-commit hooks and linting +- ✅ TypeScript support (optional) +- ✅ Enhanced CI/CD + +**Estimated Effort:** 8-12 days + +--- + +### Phase 3: Feature Enhancement (Weeks 5-6) +**Focus:** New validators, modern API + +**Deliverables:** +- ✅ Modern tool validators (docker, kubectl, cloud CLIs, etc.) +- ✅ Modern API (async/await, ESM) +- ✅ Better output formats + +**Estimated Effort:** 6-10 days + +--- + +### Phase 4: Polish (Ongoing) +**Focus:** Developer experience, extensibility + +**Deliverables:** +- ✅ Better DX with VS Code config +- ✅ Plugin system +- ✅ Community contributions + +**Estimated Effort:** Variable + +--- + +## Technology Stack Recommendations + +### Current Stack +```json +{ + "runtime": "Node.js >=10", + "testing": "tape + tap-min", + "linting": "ESLint 8", + "mocking": "proxyquire", + "promises": "Bluebird", + "cli": "yargs", + "colors": "colors" +} +``` + +### Proposed Stack +```json +{ + "runtime": "Node.js >=18", + "testing": "Vitest (or Jest)", + "linting": "ESLint 9 + Prettier", + "typescript": "Optional but recommended", + "git-hooks": "Husky + lint-staged", + "commits": "commitlint", + "promises": "Native async/await", + "cli": "yargs (keep)", + "colors": "chalk", + "ci": "GitHub Actions (enhanced)" +} +``` + +--- + +## Success Metrics + +### After Phase 1 +- ✅ 0 security vulnerabilities +- ✅ Node.js 18+ supported +- ✅ Complete documentation set +- ✅ All tests passing + +### After Phase 2 +- ✅ >80% test coverage +- ✅ Modern testing framework +- ✅ Pre-commit hooks working +- ✅ Automated releases + +### After Phase 3 +- ✅ 10+ new modern tool validators +- ✅ Modern API with ESM support +- ✅ Multiple output formats +- ✅ Better CI/CD integration + +--- + +## Backward Compatibility + +### Must Maintain +- ✅ CLI interface and arguments +- ✅ Programmatic API (check function) +- ✅ Return value structure +- ✅ package.json engines format +- ✅ Exit codes + +### Can Change (with deprecation) +- ⚠️ Internal implementation +- ⚠️ Output formatting (with --legacy flag) + +### Breaking Changes (v2.0.0) +- 🔴 Minimum Node.js version (10 → 18) +- 🔴 Testing framework migration (internal) + +**Recommendation:** Release as v2.0.0 after Phase 1-2 completion + +--- + +## Risk Assessment + +### Low Risk +- Updating dependencies +- Adding documentation +- Adding new validators +- CI/CD enhancements + +### Medium Risk +- Testing framework migration +- ESLint configuration changes +- TypeScript migration +- API modernization + +### High Risk +- Breaking changes to public API +- Minimum Node.js version bump + +**Mitigation:** +- Comprehensive testing +- Beta releases for major changes +- Clear migration guides +- Semantic versioning + +--- + +## Use Cases to Support + +### 1. Manual Developer Usage +```bash +# Developer runs locally +check-engine +``` + +### 2. npm Scripts +```json +{ + "scripts": { + "preinstall": "check-engine" + } +} +``` + +### 3. CI/CD Pipelines +```yaml +# GitHub Actions +- name: Validate environment + run: npx check-engine +``` + +### 4. Pre-commit Hooks +```bash +# husky pre-commit +#!/bin/sh +check-engine || exit 1 +``` + +### 5. Docker Development Setup Validation +```bash +# Validate machine has Docker installed +check-engine # with docker in engines +``` + +### 6. Cloud Development Setup Validation +```bash +# Validate machine has kubectl, aws CLI, etc. +check-engine # with kubectl, aws in engines +``` + +--- + +## Examples of New Validators in Use + +### Example 1: Full-Stack JavaScript Developer +```json +{ + "engines": { + "node": ">=18", + "npm": ">=9", + "git": ">=2.30", + "docker": ">=20", + "docker-compose": ">=2.0" + } +} +``` + +### Example 2: Kubernetes Developer +```json +{ + "engines": { + "node": ">=18", + "kubectl": ">=1.25", + "helm": ">=3.10", + "docker": ">=20", + "minikube": ">=1.30" + } +} +``` + +### Example 3: Cloud Developer (AWS) +```json +{ + "engines": { + "node": ">=20", + "aws": ">=2.13", + "terraform": ">=1.5", + "docker": ">=24" + } +} +``` + +### Example 4: Modern JavaScript Developer +```json +{ + "engines": { + "node": ">=20", + "bun": ">=1.0", + "volta": ">=1.1" + } +} +``` + +--- + +## Next Steps + +1. ✅ Review this modernization plan +2. ⬜ Approve approach and priorities +3. ⬜ Create GitHub project board for tracking +4. ⬜ Begin Phase 1 implementation +5. ⬜ Regular progress reviews + +--- + +## Conclusion + +This modernization plan focuses on what check-engine is: a developer utility for validating local development environments. The plan includes: + +1. **Foundation updates** - Security, dependencies, documentation +2. **Modernization** - Testing, code quality, CI/CD +3. **Feature expansion** - New validators for modern tools (docker, kubectl, cloud CLIs) +4. **API improvements** - Modern JavaScript patterns + +The goal is to make check-engine the best tool for ensuring developers have the right tools installed for modern development workflows, including container and cloud development, without turning check-engine itself into a cloud service. + +--- + +**Status:** Planning Complete +**Total Estimated Time:** 19-29 days (4-6 weeks) for Phases 1-3 +**Next Phase:** Implementation (awaiting approval) diff --git a/MODERNIZATION_RECOMMENDATIONS.md b/MODERNIZATION_RECOMMENDATIONS.md deleted file mode 100644 index e040111..0000000 --- a/MODERNIZATION_RECOMMENDATIONS.md +++ /dev/null @@ -1,747 +0,0 @@ -# check-engine Modernization Recommendations - -**Document Version:** 1.0 -**Date:** 2025-11-08 -**Status:** Planning Phase - -## Executive Summary - -The `check-engine` project is a valuable Node.js utility for validating development environment dependencies. While the core functionality remains solid, the project would benefit from modernization to align with current best practices, improve maintainability, and expand its utility in modern development workflows including containerized and cloud-native environments. - -## Current State Assessment - -### Strengths -- ✅ Working core functionality -- ✅ Good test coverage (91 tests passing) -- ✅ Active GitHub Actions CI/CD -- ✅ Dependabot configured for dependency updates -- ✅ Clean, readable codebase -- ✅ Semantic versioning support -- ✅ MIT License (permissive) - -### Areas for Improvement -- ⚠️ Node.js requirement outdated (>=10, should be >=18 or >=20) -- ⚠️ Security vulnerabilities in dependencies (2 identified) -- ⚠️ Legacy testing framework (tape) -- ⚠️ No TypeScript support -- ⚠️ No containerization support -- ⚠️ Missing documentation (CONTRIBUTING, CHANGELOG) -- ⚠️ Limited modern package manager support (no bun support) -- ⚠️ No Kubernetes/cloud-native examples -- ⚠️ No pre-commit hooks -- ⚠️ Basic linting configuration - -## Modernization Recommendations - -### 1. Runtime & Dependency Updates - -#### Priority: HIGH - -**Recommendation:** Update Node.js requirements and dependencies - -**Details:** -- Update minimum Node.js version to `>=18` (LTS) or `>=20` (current LTS) -- Update ESLint to latest version (v9.x with flat config) -- Replace `tape` with more modern testing framework (Jest or Vitest) -- Update `bluebird` promises to native async/await -- Fix security vulnerabilities via `npm audit fix` -- Consider replacing outdated dependencies: - - `colors` → `chalk` or native ANSI codes - - Consider if `jsonfile` is still needed vs native JSON methods - -**Benefits:** -- Improved performance and security -- Access to modern JavaScript features -- Better developer experience -- Reduced technical debt - -**Effort:** Medium (2-3 days) - ---- - -### 2. TypeScript Migration - -#### Priority: MEDIUM - -**Recommendation:** Add TypeScript support with gradual migration path - -**Details:** -- Add TypeScript configuration (tsconfig.json) -- Convert to TypeScript or add JSDoc type annotations -- Provide type definitions for programmatic API -- Maintain backward compatibility with JavaScript consumers -- Use TypeScript for new code - -**Benefits:** -- Better IDE support and autocomplete -- Catch errors at compile time -- Improved documentation through types -- Easier refactoring -- More maintainable codebase - -**Effort:** Medium-High (3-5 days for full migration, 1-2 days for types only) - ---- - -### 3. Testing Modernization - -#### Priority: MEDIUM - -**Recommendation:** Migrate to modern testing framework and enhance test coverage - -**Details:** -- **Option A:** Migrate to Jest - - Industry standard - - Built-in coverage reports - - Snapshot testing - - Better mocking capabilities - -- **Option B:** Migrate to Vitest - - Faster than Jest - - ESM-first - - Compatible with Jest API - - Better for modern projects - -- Add test coverage reporting -- Add integration tests -- Add e2e tests for CLI -- Set up code coverage thresholds (>80%) -- Add test coverage badges to README - -**Benefits:** -- Better testing experience -- More comprehensive test coverage -- Easier to write and maintain tests -- Visual coverage reports - -**Effort:** Medium (2-4 days) - ---- - -### 4. Code Quality Tooling - -#### Priority: MEDIUM - -**Recommendation:** Implement comprehensive code quality tools - -**Details:** -- Update ESLint to v9 with flat config -- Add Prettier for consistent formatting -- Add husky for git hooks -- Add lint-staged for pre-commit linting -- Add commitlint for conventional commits -- Configure EditorConfig -- Add JSDoc or TypeScript for documentation -- Consider adding Biome as a faster alternative - -**Example Pre-commit Hook:** -```json -{ - "husky": { - "hooks": { - "pre-commit": "lint-staged", - "commit-msg": "commitlint -E HUSKY_GIT_PARAMS" - } - }, - "lint-staged": { - "*.js": ["eslint --fix", "prettier --write"] - } -} -``` - -**Benefits:** -- Consistent code style -- Prevent bad commits -- Better commit history -- Automated code quality checks - -**Effort:** Low-Medium (1-2 days) - ---- - -### 5. Containerization Support - -#### Priority: HIGH - -**Recommendation:** Add Docker support for consistent development and deployment - -**Details:** -- Create multi-stage Dockerfile for production -- Create docker-compose.yml for local development -- Add .dockerignore file -- Create container image with all validator tools pre-installed -- Publish to Docker Hub or GitHub Container Registry -- Add Dockerfile linting with hadolint -- Support multiple architectures (amd64, arm64) - -**Example Use Cases:** -```bash -# Run check-engine in container -docker run --rm -v $(pwd):/app check-engine - -# Run with docker-compose for CI -docker-compose run check-engine -``` - -**Benefits:** -- Consistent environment across machines -- Easy CI/CD integration -- Pre-installed validator tools -- Portable and reproducible builds -- No local installation needed - -**Effort:** Medium (2-3 days) - ---- - -### 6. Kubernetes & Cloud-Native Support - -#### Priority: MEDIUM - -**Recommendation:** Add Kubernetes manifests and cloud-native deployment examples - -**Details:** -- Create Kubernetes Job manifest for validation -- Create Helm chart for easy deployment -- Add examples for: - - InitContainer for environment validation - - Job for pre-deployment checks - - CronJob for periodic validation -- Add examples for cloud platforms: - - AWS ECS/EKS - - Google Cloud Run/GKE - - Azure Container Instances/AKS -- Document integration with CI/CD pipelines - -**Example Kubernetes Job:** -```yaml -apiVersion: batch/v1 -kind: Job -metadata: - name: check-engine-validation -spec: - template: - spec: - containers: - - name: check-engine - image: check-engine:latest - command: ["check-engine", "/config/package.json"] - restartPolicy: Never -``` - -**Benefits:** -- Easy integration with Kubernetes workflows -- Pre-deployment validation -- Cloud-native deployment patterns -- Infrastructure as Code - -**Effort:** Medium (2-3 days) - ---- - -### 7. Documentation Enhancements - -#### Priority: HIGH - -**Recommendation:** Comprehensive documentation overhaul - -**Details:** -- Add CONTRIBUTING.md with: - - Development setup - - Coding standards - - PR process - - Release process -- Add CHANGELOG.md following Keep a Changelog format -- Add CODE_OF_CONDUCT.md -- Add SECURITY.md for vulnerability reporting -- Enhance README.md with: - - Badges (coverage, downloads, version) - - Better examples - - Troubleshooting section - - FAQ section -- Add API documentation -- Create docs/ folder with: - - Architecture overview - - Adding new validators guide - - Integration examples - - Migration guides - -**Benefits:** -- Better onboarding for contributors -- Clearer communication -- Professional appearance -- Easier to maintain and extend - -**Effort:** Medium (2-3 days) - ---- - -### 8. CI/CD Pipeline Enhancements - -#### Priority: MEDIUM - -**Recommendation:** Expand GitHub Actions workflows - -**Details:** -- Add separate workflows for: - - Pull request validation - - Main branch protection - - Release automation - - Security scanning - - Container image building - - NPM package publishing -- Add CodeQL for security analysis -- Add dependency review -- Add automatic PR labeling -- Add release-please for automated releases -- Add version bumping automation -- Test on multiple OS (Ubuntu, macOS, Windows) -- Add performance benchmarking - -**Example Additional Workflows:** -- `security.yml` - SAST/dependency scanning -- `release.yml` - Automated releases -- `docker.yml` - Container image building -- `performance.yml` - Benchmark tests - -**Benefits:** -- Automated release process -- Better security posture -- Multi-platform support -- Consistent quality gates - -**Effort:** Medium (2-3 days) - ---- - -### 9. Package Manager Modernization - -#### Priority: LOW-MEDIUM - -**Recommendation:** Add support for modern package managers - -**Details:** -- Add validators for: - - `bun` (modern, fast package manager) - - `deno` (secure JavaScript runtime) - - `volta` (version management) -- Improve existing validators: - - Better version detection - - Support for version managers (nvm, fnm, volta) -- Add `.npmrc` configuration -- Consider pnpm workspace support -- Add package.json validation - -**Benefits:** -- Support for modern tooling -- Better developer experience -- More comprehensive validation - -**Effort:** Low-Medium (1-2 days per validator) - ---- - -### 10. Security Enhancements - -#### Priority: HIGH - -**Recommendation:** Implement comprehensive security practices - -**Details:** -- Fix existing security vulnerabilities -- Add npm audit check to CI/CD -- Add Snyk or Dependabot alerts -- Implement security.txt -- Add SECURITY.md policy -- Use npm provenance -- Sign releases with GPG -- Add supply chain security: - - Lock file integrity checks - - Dependency pinning strategy - - Regular security audits - -**Benefits:** -- Improved security posture -- User trust -- Compliance with best practices -- Reduced attack surface - -**Effort:** Low-Medium (1-2 days) - ---- - -### 11. Developer Experience Improvements - -#### Priority: MEDIUM - -**Recommendation:** Enhance developer experience and tooling - -**Details:** -- Add VS Code configuration: - - Recommended extensions - - Debug configurations - - Tasks for common operations -- Add development scripts in package.json: - - `dev` - watch mode - - `build` - production build - - `coverage` - test coverage - - `docs` - generate documentation -- Add GitHub Codespaces configuration -- Add Gitpod configuration -- Improve error messages and debugging -- Add verbose/debug mode -- Add progress indicators for long operations - -**Benefits:** -- Faster onboarding -- Better debugging -- More productive development -- Consistent development environment - -**Effort:** Low-Medium (1-2 days) - ---- - -### 12. API Modernization - -#### Priority: MEDIUM - -**Recommendation:** Modernize the programmatic API - -**Details:** -- Convert to native async/await (remove Bluebird) -- Add ESM module support (maintain CJS compatibility) -- Provide better error handling -- Add streaming API for large operations -- Add event emitters for progress -- Improve return types and structure -- Add configuration options: - - Timeout settings - - Parallel execution - - Custom validators - - Output formatting - -**Example Modern API:** -```javascript -import { checkEngine } from 'check-engine'; - -try { - const result = await checkEngine({ - packageJsonPath: './package.json', - parallel: true, - timeout: 30000, - onProgress: (pkg) => console.log(`Checking ${pkg.name}...`) - }); - - if (!result.success) { - console.error(result.errors); - } -} catch (error) { - console.error('Failed to validate:', error); -} -``` - -**Benefits:** -- Modern JavaScript patterns -- Better error handling -- More flexible API -- Better performance options - -**Effort:** Medium (2-3 days) - ---- - -### 13. Output & Reporting Enhancements - -#### Priority: LOW-MEDIUM - -**Recommendation:** Improve output formats and reporting - -**Details:** -- Add multiple output formats: - - JSON (machine-readable) - - YAML - - JUnit XML (for CI/CD) - - HTML report - - Markdown -- Add colored, formatted output (currently uses colors package) -- Add summary statistics -- Add exit codes for different scenarios -- Add quiet mode -- Add verbose/debug mode -- Support for custom formatters -- Add badges/shields generation - -**Benefits:** -- Better CI/CD integration -- More flexible reporting -- Easier debugging -- Better user experience - -**Effort:** Low-Medium (1-2 days) - ---- - -### 14. Platform & Tool Expansion - -#### Priority: LOW - -**Recommendation:** Add validators for modern development tools - -**Details:** -- Add validators for: - - **Container Tools:** Docker, Podman, Buildah - - **Cloud Tools:** kubectl, helm, terraform, aws-cli, gcloud, az - - **Build Tools:** Make, CMake, Gradle, Maven - - **Language Runtimes:** Python, Ruby, Go, Rust, Java - - **Version Managers:** nvm, fnm, volta, asdf, pyenv, rbenv - - **Development Tools:** VS Code, direnv - - **Database Tools:** psql, mysql, redis-cli, mongosh -- Make validators pluggable/extensible -- Allow custom validators via configuration - -**Benefits:** -- More comprehensive validation -- Support for diverse tech stacks -- Extensible architecture -- Wider adoption potential - -**Effort:** Low-Medium per validator (0.5-1 day each) - ---- - -### 15. Monitoring & Telemetry - -#### Priority: LOW - -**Recommendation:** Add optional telemetry and monitoring - -**Details:** -- Add optional anonymous usage statistics -- Track which validators are most used -- Monitor error rates -- Integration with monitoring tools: - - Prometheus metrics endpoint - - OpenTelemetry support - - StatsD support -- Add health check endpoint (for containerized deployments) -- Respect user privacy with opt-in telemetry - -**Benefits:** -- Understand usage patterns -- Identify common issues -- Improve popular validators -- Better monitoring in production - -**Effort:** Low-Medium (1-2 days) - ---- - -## Implementation Priority Matrix - -### Phase 1: Foundation (Weeks 1-2) -**Critical updates for stability and security** - -1. ✅ Runtime & Dependency Updates (HIGH) -2. ✅ Security Enhancements (HIGH) -3. ✅ Documentation Enhancements (HIGH) -4. ✅ Containerization Support (HIGH) - -**Estimated Effort:** 8-11 days - ---- - -### Phase 2: Modernization (Weeks 3-4) -**Improve development experience and code quality** - -5. ✅ Code Quality Tooling (MEDIUM) -6. ✅ Testing Modernization (MEDIUM) -7. ✅ TypeScript Migration (MEDIUM) -8. ✅ CI/CD Pipeline Enhancements (MEDIUM) - -**Estimated Effort:** 10-14 days - ---- - -### Phase 3: Enhancement (Weeks 5-6) -**Add modern features and improve API** - -9. ✅ API Modernization (MEDIUM) -10. ✅ Developer Experience Improvements (MEDIUM) -11. ✅ Kubernetes & Cloud-Native Support (MEDIUM) -12. ✅ Package Manager Modernization (LOW-MEDIUM) - -**Estimated Effort:** 7-10 days - ---- - -### Phase 4: Expansion (Weeks 7+) -**Optional enhancements and new features** - -13. ✅ Output & Reporting Enhancements (LOW-MEDIUM) -14. ✅ Platform & Tool Expansion (LOW) -15. ✅ Monitoring & Telemetry (LOW) - -**Estimated Effort:** Variable (ongoing) - ---- - -## Technology Stack Recommendations - -### Core Dependencies (Proposed) -```json -{ - "dependencies": { - "semver": "^7.6.0", - "chalk": "^5.3.0", - "yargs": "^17.7.2", - "commander": "^12.0.0" - }, - "devDependencies": { - "typescript": "^5.3.3", - "vitest": "^1.0.4", - "@types/node": "^20.10.0", - "eslint": "^9.0.0", - "prettier": "^3.1.0", - "husky": "^9.0.0", - "lint-staged": "^15.0.0", - "tsx": "^4.7.0" - } -} -``` - -### Modern Tooling Stack -- **Runtime:** Node.js 20.x LTS (minimum 18.x) -- **Testing:** Vitest or Jest -- **Linting:** ESLint v9 with flat config -- **Formatting:** Prettier -- **Type Checking:** TypeScript 5.x or JSDoc -- **Git Hooks:** Husky + lint-staged -- **Container:** Docker with multi-stage builds -- **CI/CD:** GitHub Actions with matrix testing -- **Package Manager:** npm (primary), with pnpm/yarn/bun support -- **Documentation:** Markdown + JSDoc/TSDoc - ---- - -## Backward Compatibility Considerations - -### Must Maintain -- ✅ CLI interface and command-line arguments -- ✅ Programmatic API (check function) -- ✅ Return value structure -- ✅ package.json engines format -- ✅ Exit codes - -### Can Change (with deprecation notice) -- ⚠️ Internal API structure -- ⚠️ Validator implementation details -- ⚠️ Output formatting (with --legacy flag) - -### Breaking Changes (Major Version) -- 🔴 Minimum Node.js version (10 → 18) -- 🔴 Testing framework migration -- 🔴 ESM as default module format - -**Recommendation:** Release as v2.0.0 after Phase 1-2 completion - ---- - -## Success Metrics - -### Code Quality -- ✅ 0 security vulnerabilities -- ✅ >90% test coverage -- ✅ <5 minutes CI/CD pipeline -- ✅ 100% passing tests on all supported platforms -- ✅ 0 ESLint errors/warnings - -### Documentation -- ✅ CONTRIBUTING.md present -- ✅ CHANGELOG.md maintained -- ✅ API documentation complete -- ✅ Examples for common use cases - -### Community -- ✅ <48 hour response time to issues -- ✅ Regular releases (monthly or as-needed) -- ✅ Active contributor base -- ✅ Good GitHub health metrics - -### Performance -- ✅ <500ms overhead for validation -- ✅ Parallel validator execution -- ✅ Efficient caching - ---- - -## Risk Assessment - -### Low Risk -- Updating dependencies -- Adding documentation -- Adding container support -- CI/CD enhancements - -### Medium Risk -- Testing framework migration -- ESLint configuration changes -- TypeScript migration -- API modernization - -### High Risk -- Breaking changes to public API -- Minimum Node.js version bump -- Module format changes (CJS → ESM) - -**Mitigation Strategy:** -- Comprehensive testing before releases -- Beta releases for major changes -- Clear migration guides -- Deprecation warnings before breaking changes -- Semantic versioning strictly followed - ---- - -## Resources & References - -### Best Practices -- [Node.js Best Practices](https://github.com/goldbergyoni/nodebestpractices) -- [12 Factor App](https://12factor.net/) -- [Semantic Versioning](https://semver.org/) -- [Keep a Changelog](https://keepachangelog.com/) -- [Conventional Commits](https://www.conventionalcommits.org/) - -### Tools -- [GitHub Actions Documentation](https://docs.github.com/en/actions) -- [Docker Best Practices](https://docs.docker.com/develop/dev-best-practices/) -- [TypeScript Handbook](https://www.typescriptlang.org/docs/) -- [Vitest Documentation](https://vitest.dev/) -- [ESLint v9 Migration](https://eslint.org/docs/latest/use/migrate-to-9.0.0) - ---- - -## Conclusion - -The check-engine project has a solid foundation and serves a valuable purpose. By implementing these modernization recommendations, the project will: - -1. **Stay Relevant:** Support modern tools and workflows -2. **Be More Secure:** Address vulnerabilities and follow security best practices -3. **Be Easier to Maintain:** Better tooling and documentation -4. **Be More Accessible:** Containerization and cloud-native support -5. **Be More Reliable:** Better testing and CI/CD -6. **Be More Extensible:** Modular architecture for custom validators - -The phased approach allows for incremental improvements while maintaining stability and backward compatibility where possible. The highest priority items (Phase 1) address critical security and usability concerns, while later phases add nice-to-have features that expand the tool's utility. - ---- - -**Next Steps:** -1. Review and prioritize recommendations based on project goals -2. Create detailed implementation plan for Phase 1 -3. Set up project board for tracking progress -4. Begin implementation with highest priority items -5. Engage community for feedback and contributions - -**Questions? Feedback?** -Please open an issue or discussion on GitHub to share your thoughts on these recommendations. diff --git a/MODERNIZATION_SUMMARY.md b/MODERNIZATION_SUMMARY.md deleted file mode 100644 index d7c94ed..0000000 --- a/MODERNIZATION_SUMMARY.md +++ /dev/null @@ -1,432 +0,0 @@ -# check-engine Modernization Planning Summary - -**Date:** 2025-11-08 -**Version:** 1.0 -**Status:** Planning Complete - -## Executive Summary - -This document provides a quick overview of the comprehensive modernization plan for the check-engine project. Five detailed planning documents have been created to guide the modernization effort, covering all aspects from security updates to cloud-native deployment. - ---- - -## Quick Links - -### Planning Documents -1. **[MODERNIZATION_RECOMMENDATIONS.md](./MODERNIZATION_RECOMMENDATIONS.md)** - High-level recommendations and priorities -2. **[IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md)** - Detailed step-by-step implementation guide -3. **[CONTAINERIZATION_STRATEGY.md](./CONTAINERIZATION_STRATEGY.md)** - Docker and container deployment strategy -4. **[CLOUD_NATIVE_DEPLOYMENT.md](./CLOUD_NATIVE_DEPLOYMENT.md)** - Kubernetes and cloud platform deployment -5. **[TESTING_STRATEGY.md](./TESTING_STRATEGY.md)** - Modern testing framework migration - ---- - -## At a Glance - -### Current State -- **Version:** 1.14.0 -- **Node.js:** >=10 (outdated) -- **Testing:** Tape (91 tests passing) -- **CI/CD:** Basic GitHub Actions -- **Container:** None -- **Cloud Support:** None -- **Security:** 2 vulnerabilities -- **Documentation:** Basic README only - -### Target State -- **Version:** 2.0.0 (after Phase 1-2) -- **Node.js:** >=18 (LTS) -- **Testing:** Vitest/Jest with >85% coverage -- **CI/CD:** Advanced automation with multiple workflows -- **Container:** Multi-arch images on GHCR/Docker Hub -- **Cloud Support:** K8s, AWS, GCP, Azure examples -- **Security:** 0 vulnerabilities, CodeQL scanning -- **Documentation:** Complete with CONTRIBUTING, CHANGELOG, etc. - ---- - -## Implementation Timeline - -### Phase 1: Foundation (Weeks 1-2) - HIGH Priority -**Focus:** Critical security and basic modernization - -**Deliverables:** -- ✅ Node.js 18+ support -- ✅ Security vulnerabilities fixed -- ✅ Docker images (base, standard, full) -- ✅ CONTRIBUTING.md, CHANGELOG.md, SECURITY.md, CODE_OF_CONDUCT.md -- ✅ Enhanced README with badges - -**Effort:** 8-11 days - ---- - -### Phase 2: Modernization (Weeks 3-4) - MEDIUM Priority -**Focus:** Developer experience and code quality - -**Deliverables:** -- ✅ Vitest/Jest testing framework -- ✅ TypeScript support (optional but recommended) -- ✅ ESLint 9 + Prettier + Husky -- ✅ Pre-commit hooks -- ✅ Enhanced CI/CD workflows -- ✅ Code coverage >85% - -**Effort:** 10-14 days - ---- - -### Phase 3: Enhancement (Weeks 5-6) - MEDIUM Priority -**Focus:** Modern features and cloud-native support - -**Deliverables:** -- ✅ Modern async/await API -- ✅ ESM module support -- ✅ Kubernetes manifests and Helm chart -- ✅ Cloud platform examples (AWS, GCP, Azure) -- ✅ VS Code/Codespaces configuration -- ✅ Improved CLI UX - -**Effort:** 7-10 days - ---- - -### Phase 4: Expansion (Weeks 7+) - LOW Priority -**Focus:** Optional enhancements and new features - -**Deliverables:** -- ✅ Multiple output formats (JSON, YAML, HTML, etc.) -- ✅ Extended validator library (Docker, kubectl, cloud CLIs) -- ✅ Plugin system for custom validators -- ✅ Optional telemetry and monitoring - -**Effort:** Ongoing, as needed - ---- - -## Key Recommendations - -### Top 5 Priorities - -1. **Update Node.js and Fix Security Issues** (Phase 1) - - Update to Node.js 18+ - - Fix 2 security vulnerabilities - - Immediate impact on security and maintenance - -2. **Add Container Support** (Phase 1) - - Create Docker images - - Enable consistent environments - - Critical for modern deployment - -3. **Improve Documentation** (Phase 1) - - Add CONTRIBUTING.md, CHANGELOG.md, SECURITY.md - - Enhance README - - Better onboarding and transparency - -4. **Modernize Testing** (Phase 2) - - Migrate to Vitest/Jest - - Add coverage reporting - - Improve test quality - -5. **Add Cloud-Native Support** (Phase 3) - - Kubernetes manifests - - Helm chart - - Cloud platform examples - - Expand use cases - ---- - -## Technology Stack - -### Current -``` -Runtime: Node.js >=10 -Testing: tape + tap-min -Linting: ESLint 8 -Mocking: proxyquire -Promises: Bluebird -CLI: yargs -Colors: colors -``` - -### Proposed -``` -Runtime: Node.js >=18 -Testing: Vitest (or Jest) -Linting: ESLint 9 + Prettier -TypeScript: Optional but recommended -Git Hooks: Husky + lint-staged -Commits: commitlint -Promises: Native async/await -CLI: yargs (keep) or commander -Colors: chalk -Container: Docker (multi-arch) -K8s: Helm charts -CI/CD: Enhanced GitHub Actions -``` - ---- - -## Document Overview - -### 1. MODERNIZATION_RECOMMENDATIONS.md (19KB) -**Audience:** Decision makers, project leads -**Content:** -- 15 detailed recommendations with priorities -- Effort estimates and benefits -- Risk assessment -- Success metrics -- Technology stack comparison - -**Use this when:** Planning the overall modernization strategy - ---- - -### 2. IMPLEMENTATION_PLAN.md (26KB) -**Audience:** Developers, implementers -**Content:** -- Step-by-step tasks for each recommendation -- Task dependencies -- Acceptance criteria -- Code examples -- Migration checklists - -**Use this when:** Actually implementing the changes - ---- - -### 3. CONTAINERIZATION_STRATEGY.md (17KB) -**Audience:** DevOps, infrastructure teams -**Content:** -- Multi-stage Dockerfile examples -- Image variants (base, standard, full) -- Multi-architecture builds -- Security best practices -- Distribution strategy - -**Use this when:** Building and distributing container images - ---- - -### 4. CLOUD_NATIVE_DEPLOYMENT.md (19KB) -**Audience:** Platform engineers, SREs -**Content:** -- Kubernetes patterns (Job, InitContainer, CronJob, DaemonSet) -- Helm chart structure -- AWS, GCP, Azure deployment examples -- CI/CD integration -- Monitoring and troubleshooting - -**Use this when:** Deploying to cloud platforms - ---- - -### 5. TESTING_STRATEGY.md (19KB) -**Audience:** QA engineers, developers -**Content:** -- Testing framework comparison -- Migration plan from tape -- Test organization structure -- Coverage requirements -- Example test code - -**Use this when:** Migrating tests or adding new test coverage - ---- - -## Quick Start Guide - -### For Project Maintainers - -1. **Review** MODERNIZATION_RECOMMENDATIONS.md -2. **Prioritize** which phases align with project goals -3. **Create** project board from IMPLEMENTATION_PLAN.md -4. **Assign** tasks to team members -5. **Track** progress and adjust as needed - -### For Contributors - -1. **Read** CONTRIBUTING.md (to be created in Phase 1) -2. **Check** IMPLEMENTATION_PLAN.md for available tasks -3. **Pick** a task matching your skills -4. **Follow** the implementation guide -5. **Submit** PR following the guidelines - -### For Users - -1. **Wait** for Phase 1 completion for stable Node 18+ support -2. **Try** Docker images once available (Phase 1) -3. **Explore** cloud-native examples (Phase 3) -4. **Provide** feedback via GitHub issues -5. **Contribute** validators for your favorite tools - ---- - -## Success Metrics - -### After Phase 1 -- ✅ 0 security vulnerabilities -- ✅ Node.js 18+ support -- ✅ Container images published -- ✅ Complete documentation set -- ✅ All tests passing - -### After Phase 2 -- ✅ >85% test coverage -- ✅ Modern testing framework -- ✅ Pre-commit hooks working -- ✅ Automated releases -- ✅ TypeScript support (optional) - -### After Phase 3 -- ✅ Kubernetes ready -- ✅ Cloud platform examples -- ✅ Modern API -- ✅ Enhanced developer experience -- ✅ Wide platform support - -### After Phase 4 -- ✅ Extended validator library -- ✅ Multiple output formats -- ✅ Plugin system -- ✅ Community contributions - ---- - -## Estimated Costs - -### Time Investment -- **Phase 1:** 8-11 days (1-2 weeks) -- **Phase 2:** 10-14 days (2-3 weeks) -- **Phase 3:** 7-10 days (1-2 weeks) -- **Phase 4:** Ongoing - -**Total for Phases 1-3:** 25-35 days (5-7 weeks) - -### Resource Requirements -- **Developer(s):** 1-2 full-time -- **Reviewer(s):** 1 part-time -- **Infrastructure:** GitHub Actions (free), GHCR (free), Codecov (free for open source) - -### Return on Investment -- **Improved Security:** Reduced vulnerability risk -- **Better Maintainability:** Easier to update and extend -- **Wider Adoption:** More platforms and use cases -- **Community Growth:** Better contributor experience -- **Professional Image:** Modern, well-maintained project - ---- - -## Risk Mitigation - -### Breaking Changes -**Risk:** Minimum Node version bump breaks existing users -**Mitigation:** -- Clear communication in CHANGELOG -- Deprecation warnings in v1.x -- Migration guide -- Maintain v1.x with security fixes for 6 months - -### Testing Migration -**Risk:** Test coverage might decrease during migration -**Mitigation:** -- Migrate tests incrementally -- Maintain parallel test runs during transition -- Block PRs that decrease coverage - -### Scope Creep -**Risk:** Project might expand beyond original goals -**Mitigation:** -- Stick to phased approach -- Mark Phase 4 as optional -- Regular scope reviews - ---- - -## Community Engagement - -### Communication Plan -1. **Announce** modernization plan in GitHub Discussions -2. **Create** project board for transparency -3. **Label** issues as "modernization" or "help wanted" -4. **Share** progress updates monthly -5. **Welcome** community contributions - -### Contribution Opportunities -- Documentation improvements -- New validators for different tools -- Testing on different platforms -- Cloud platform examples -- Translation to other languages - ---- - -## Questions & Feedback - -### Where to Ask Questions -- **GitHub Issues:** For bugs and feature requests -- **GitHub Discussions:** For questions and ideas -- **Pull Requests:** For specific implementation questions - -### How to Provide Feedback -1. Review the planning documents -2. Open a discussion or issue -3. Suggest changes or alternatives -4. Vote on proposals with 👍/👎 - ---- - -## Next Steps - -### Immediate Actions -1. ✅ Review all planning documents -2. ⬜ Discuss and approve modernization approach -3. ⬜ Create project board -4. ⬜ Set up milestones for each phase -5. ⬜ Begin Phase 1 implementation - -### This Week -- Set up project infrastructure -- Create initial issues -- Assign Phase 1 tasks -- Update README with modernization notice - -### This Month -- Complete Phase 1 -- Release v2.0.0-beta.1 -- Gather community feedback -- Begin Phase 2 - -### This Quarter -- Complete Phases 1-2 -- Release v2.0.0 -- Begin Phase 3 -- Grow contributor base - ---- - -## Conclusion - -This comprehensive modernization plan provides a clear path forward for check-engine. By following the phased approach, the project will evolve into a modern, secure, and widely-adopted tool for environment validation across multiple platforms and deployment scenarios. - -The planning phase is now complete. The next step is to begin implementation of Phase 1, starting with the highest priority items that will have the most immediate impact on security, usability, and maintainability. - ---- - -**Document Status:** ✅ Planning Complete -**Last Updated:** 2025-11-08 -**Next Review:** After Phase 1 completion - ---- - -## Appendix: Document Sizes - -| Document | Size | Focus Area | -|----------|------|------------| -| MODERNIZATION_RECOMMENDATIONS.md | 19KB | Strategy & Recommendations | -| IMPLEMENTATION_PLAN.md | 26KB | Execution & Tasks | -| CONTAINERIZATION_STRATEGY.md | 17KB | Docker & Containers | -| CLOUD_NATIVE_DEPLOYMENT.md | 19KB | Kubernetes & Cloud | -| TESTING_STRATEGY.md | 19KB | Testing & Quality | -| **Total** | **~100KB** | **Complete Modernization Guide** | - diff --git a/TESTING_STRATEGY.md b/TESTING_STRATEGY.md deleted file mode 100644 index 831c8a8..0000000 --- a/TESTING_STRATEGY.md +++ /dev/null @@ -1,853 +0,0 @@ -# check-engine Testing Strategy Modernization - -**Document Version:** 1.0 -**Date:** 2025-11-08 -**Status:** Planning Phase - -## Current State Analysis - -### Existing Test Infrastructure -- **Framework:** Tape (minimalist TAP-producing test harness) -- **Reporter:** tap-min (minimal TAP reporter) -- **Coverage:** 91 tests passing -- **Test Files:** - - `lib/checkSystem.spec.js` (141 lines) - - `lib/validatorRules.spec.js` (292 lines) -- **Mocking:** proxyquire (for stubbing module dependencies) - -### Strengths -- ✅ Good test coverage -- ✅ Tests are passing -- ✅ Basic mocking in place -- ✅ Tests run in CI - -### Weaknesses -- ⚠️ Old testing framework (tape) -- ⚠️ No coverage reporting/tracking -- ⚠️ No integration tests -- ⚠️ No E2E tests -- ⚠️ Limited test organization -- ⚠️ No test documentation -- ⚠️ No performance/benchmark tests - ---- - -## Recommended Modern Testing Stack - -### Option 1: Vitest (Recommended) -**Best for:** Modern, fast, ESM-first projects - -**Advantages:** -- ⚡ Extremely fast (uses Vite) -- 🔄 Watch mode with HMR -- 📊 Built-in coverage (via c8/v8) -- 🎯 Jest-compatible API -- 📦 ESM and TypeScript support -- 🔍 Better error messages -- 🌐 Browser mode support - -**Installation:** -```bash -npm install -D vitest @vitest/ui @vitest/coverage-v8 -``` - -**Configuration:** -```javascript -// vitest.config.js -import { defineConfig } from 'vitest/config'; - -export default defineConfig({ - test: { - globals: true, - environment: 'node', - coverage: { - provider: 'v8', - reporter: ['text', 'json', 'html', 'lcov'], - exclude: [ - 'node_modules/', - 'test/', - '**/*.spec.js', - '**/*.test.js', - ], - thresholds: { - lines: 80, - functions: 80, - branches: 80, - statements: 80, - }, - }, - }, -}); -``` - ---- - -### Option 2: Jest -**Best for:** Established ecosystem, extensive plugins - -**Advantages:** -- 🏆 Industry standard -- 📚 Extensive documentation -- 🔌 Large plugin ecosystem -- 💾 Snapshot testing -- 🎭 Built-in mocking -- 🔄 Watch mode - -**Installation:** -```bash -npm install -D jest @types/jest -``` - -**Configuration:** -```javascript -// jest.config.js -module.exports = { - testEnvironment: 'node', - coverageDirectory: 'coverage', - collectCoverageFrom: [ - 'lib/**/*.js', - 'bin/**/*.js', - '!**/*.spec.js', - '!**/*.test.js', - ], - coverageThreshold: { - global: { - branches: 80, - functions: 80, - lines: 80, - statements: 80, - }, - }, - testMatch: [ - '**/*.spec.js', - '**/*.test.js', - ], -}; -``` - ---- - -## Test Organization Structure - -### Proposed Directory Structure - -``` -check-engine/ -├── lib/ -│ ├── checkSystem.js -│ ├── validatorRules.js -│ └── promiseHelpers.js -├── test/ -│ ├── unit/ -│ │ ├── checkSystem.test.js -│ │ ├── validatorRules.test.js -│ │ └── promiseHelpers.test.js -│ ├── integration/ -│ │ ├── cli.integration.test.js -│ │ ├── programmatic-api.integration.test.js -│ │ └── validators.integration.test.js -│ ├── e2e/ -│ │ ├── basic-validation.e2e.test.js -│ │ ├── error-handling.e2e.test.js -│ │ └── real-projects.e2e.test.js -│ ├── fixtures/ -│ │ ├── package.json.examples/ -│ │ ├── mock-executables/ -│ │ └── test-environments/ -│ ├── helpers/ -│ │ ├── mock-validator.js -│ │ ├── test-utils.js -│ │ └── assertions.js -│ └── performance/ -│ ├── benchmark.test.js -│ └── load.test.js -├── coverage/ -└── vitest.config.js (or jest.config.js) -``` - ---- - -## Migration Plan from Tape to Vitest/Jest - -### Step 1: Setup New Framework - -**Install Dependencies:** -```bash -# For Vitest -npm install -D vitest @vitest/ui @vitest/coverage-v8 - -# For Jest -npm install -D jest @types/jest -``` - -**Create Configuration:** -```javascript -// vitest.config.js -export default { - test: { - globals: true, - environment: 'node', - }, -}; -``` - -### Step 2: Create Test Helpers - -**Create `test/helpers/test-utils.js`:** -```javascript -export function mockExec(command, output, exitCode = 0) { - return vi.fn().mockImplementation(() => { - if (exitCode !== 0) { - return Promise.reject(new Error(output)); - } - return Promise.resolve(output); - }); -} - -export function createMockPackageJson(engines) { - return { - name: 'test-package', - version: '1.0.0', - engines, - }; -} -``` - -### Step 3: Migrate Tests - -**Before (Tape):** -```javascript -const test = require('tape'); -const proxyquire = require('proxyquire'); - -test('should validate node version', (t) => { - const checkSystem = proxyquire('./checkSystem', { - 'child_process': { - exec: (cmd, cb) => cb(null, 'v20.0.0'), - }, - }); - - checkSystem('./package.json').then((result) => { - t.equal(result.status, 0); - t.end(); - }); -}); -``` - -**After (Vitest):** -```javascript -import { describe, it, expect, vi } from 'vitest'; -import { checkSystem } from './checkSystem.js'; -import * as cp from 'child_process'; - -vi.mock('child_process'); - -describe('checkSystem', () => { - it('should validate node version', async () => { - vi.spyOn(cp, 'exec').mockImplementation((cmd, cb) => { - cb(null, 'v20.0.0'); - }); - - const result = await checkSystem('./package.json'); - - expect(result.status).toBe(0); - expect(result.message.type).toBe('success'); - }); -}); -``` - -### Step 4: Update package.json Scripts - -```json -{ - "scripts": { - "test": "vitest run", - "test:watch": "vitest", - "test:ui": "vitest --ui", - "test:coverage": "vitest run --coverage", - "test:unit": "vitest run test/unit", - "test:integration": "vitest run test/integration", - "test:e2e": "vitest run test/e2e" - } -} -``` - -### Step 5: Update CI Configuration - -```yaml -# .github/workflows/test.yml -name: Tests - -on: [push, pull_request] - -jobs: - test: - runs-on: ubuntu-latest - strategy: - matrix: - node-version: [18, 20, 22] - - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-node@v4 - with: - node-version: ${{ matrix.node-version }} - - - run: npm ci - - run: npm run test:coverage - - - name: Upload coverage - uses: codecov/codecov-action@v3 - with: - files: ./coverage/lcov.info -``` - ---- - -## Test Types and Coverage - -### 1. Unit Tests - -**Purpose:** Test individual functions and modules in isolation - -**Coverage:** -- All functions in `checkSystem.js` -- All validators in `validatorRules.js` -- Helper functions in `promiseHelpers.js` -- Edge cases and error conditions - -**Example:** -```javascript -import { describe, it, expect, vi, beforeEach } from 'vitest'; -import { validatorRules } from '../lib/validatorRules.js'; -import * as semver from 'semver'; - -describe('validatorRules', () => { - describe('node validator', () => { - it('should validate correct node version', () => { - const result = validatorRules.node.versionValidate('v20.0.0', '>=18'); - expect(result).toBe(true); - }); - - it('should reject incorrect node version', () => { - const result = validatorRules.node.versionValidate('v16.0.0', '>=18'); - expect(result).toBe(false); - }); - - it('should handle version ranges', () => { - expect(validatorRules.node.versionValidate('v20.0.0', '^20.0.0')).toBe(true); - expect(validatorRules.node.versionValidate('v20.5.0', '^20.0.0')).toBe(true); - expect(validatorRules.node.versionValidate('v21.0.0', '^20.0.0')).toBe(false); - }); - }); - - describe('npm validator', () => { - it('should validate npm version', () => { - const result = validatorRules.npm.versionValidate('9.0.0', '>=8'); - expect(result).toBe(true); - }); - }); -}); -``` - -### 2. Integration Tests - -**Purpose:** Test interactions between modules and with real commands - -**Coverage:** -- CLI argument parsing -- Package.json reading and parsing -- Multiple validators working together -- Error propagation -- Output formatting - -**Example:** -```javascript -import { describe, it, expect } from 'vitest'; -import { checkSystem } from '../lib/checkSystem.js'; -import { writeFileSync, unlinkSync } from 'fs'; -import { join } from 'path'; - -describe('checkSystem integration', () => { - const testPkgPath = join(__dirname, '../fixtures/test-package.json'); - - it('should validate complete package.json', async () => { - const pkg = { - name: 'test', - engines: { - node: '>=18', - npm: '>=8', - }, - }; - - writeFileSync(testPkgPath, JSON.stringify(pkg)); - - const result = await checkSystem(testPkgPath); - - expect(result.status).toBe(0); - expect(result.packages).toHaveLength(2); - expect(result.packages[0].name).toBe('node'); - expect(result.packages[1].name).toBe('npm'); - - unlinkSync(testPkgPath); - }); - - it('should handle missing package.json', async () => { - const result = await checkSystem('./nonexistent.json'); - - expect(result.status).toBe(-1); - expect(result.message.type).toBe('error'); - expect(result.message.text).toContain('not found'); - }); -}); -``` - -### 3. End-to-End Tests - -**Purpose:** Test complete workflows as a user would experience them - -**Coverage:** -- CLI invocation with various arguments -- Real-world package.json configurations -- Error messages and exit codes -- Output formatting -- Container usage - -**Example:** -```javascript -import { describe, it, expect } from 'vitest'; -import { exec } from 'child_process'; -import { promisify } from 'util'; - -const execAsync = promisify(exec); - -describe('CLI E2E', () => { - it('should run successfully with valid environment', async () => { - const { stdout, stderr } = await execAsync( - 'node bin/check-engine.js test/fixtures/valid-package.json' - ); - - expect(stdout).toContain('Environment looks good'); - expect(stderr).toBe(''); - }); - - it('should fail with invalid environment', async () => { - try { - await execAsync( - 'node bin/check-engine.js test/fixtures/invalid-package.json' - ); - expect.fail('Should have thrown'); - } catch (error) { - expect(error.code).toBe(1); - expect(error.stdout).toContain('Environment is invalid'); - } - }); - - it('should show help with --help flag', async () => { - const { stdout } = await execAsync('node bin/check-engine.js --help'); - - expect(stdout).toContain('check-engine'); - expect(stdout).toContain('Usage:'); - }); - - it('should show version with --version flag', async () => { - const { stdout } = await execAsync('node bin/check-engine.js --version'); - - expect(stdout).toMatch(/\d+\.\d+\.\d+/); - }); -}); -``` - -### 4. Performance/Benchmark Tests - -**Purpose:** Track performance characteristics and prevent regressions - -**Coverage:** -- Validation speed -- Memory usage -- Parallel execution performance -- Large package.json handling - -**Example:** -```javascript -import { describe, it, expect, bench } from 'vitest'; -import { checkSystem } from '../lib/checkSystem.js'; - -describe('Performance', () => { - bench('validate small package.json', async () => { - await checkSystem('test/fixtures/small-package.json'); - }); - - bench('validate large package.json', async () => { - await checkSystem('test/fixtures/large-package.json'); - }); - - it('should complete validation in under 5 seconds', async () => { - const start = Date.now(); - await checkSystem('test/fixtures/standard-package.json'); - const duration = Date.now() - start; - - expect(duration).toBeLessThan(5000); - }); -}); -``` - ---- - -## Test Fixtures and Mocks - -### Test Fixtures - -Create reusable test data: - -```javascript -// test/fixtures/packages.js -export const validPackages = { - minimal: { - name: 'test-minimal', - engines: { node: '>=18' }, - }, - standard: { - name: 'test-standard', - engines: { - node: '>=18', - npm: '>=8', - git: '>=2.30', - }, - }, - complex: { - name: 'test-complex', - engines: { - node: '>=18', - npm: '>=8', - yarn: '>=3', - pnpm: '>=8', - python: '>=3.9', - }, - }, -}; - -export const invalidPackages = { - futureNode: { - name: 'test-future', - engines: { node: '>=99' }, - }, - noEngines: { - name: 'test-no-engines', - }, -}; -``` - -### Mock Executables - -Create test doubles for system commands: - -```javascript -// test/helpers/mock-validator.js -export function createMockValidator(name, version, shouldFail = false) { - return { - versionCheck: `mock-${name} --version`, - versionValidate: (result, expected) => { - if (shouldFail) return false; - return semver.satisfies(version, expected); - }, - }; -} - -export function mockSystemCommands(commands) { - const mocks = {}; - - for (const [cmd, output] of Object.entries(commands)) { - mocks[cmd] = vi.fn().mockResolvedValue(output); - } - - return mocks; -} -``` - ---- - -## Coverage Requirements - -### Minimum Coverage Thresholds - -```javascript -{ - coverage: { - thresholds: { - lines: 85, - functions: 85, - branches: 80, - statements: 85, - }, - }, -} -``` - -### Coverage Reports - -Generate multiple report formats: -- **HTML:** For local viewing -- **LCOV:** For CI integration -- **JSON:** For programmatic analysis -- **Text:** For terminal output - -### Coverage Badges - -Add to README: -```markdown -[![Coverage](https://codecov.io/gh/mohlsen/check-engine/branch/master/graph/badge.svg)](https://codecov.io/gh/mohlsen/check-engine) -``` - ---- - -## Continuous Integration - -### GitHub Actions Configuration - -```yaml -name: Test Suite - -on: - push: - branches: [master] - pull_request: - branches: [master] - -jobs: - unit-tests: - runs-on: ${{ matrix.os }} - strategy: - matrix: - os: [ubuntu-latest, macos-latest, windows-latest] - node-version: [18, 20, 22] - - steps: - - uses: actions/checkout@v4 - - - name: Use Node.js ${{ matrix.node-version }} - uses: actions/setup-node@v4 - with: - node-version: ${{ matrix.node-version }} - - - name: Install dependencies - run: npm ci - - - name: Run unit tests - run: npm run test:unit - - - name: Run integration tests - run: npm run test:integration - - e2e-tests: - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-node@v4 - with: - node-version: 20 - - - run: npm ci - - run: npm run test:e2e - - coverage: - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-node@v4 - with: - node-version: 20 - - - run: npm ci - - run: npm run test:coverage - - - name: Upload to Codecov - uses: codecov/codecov-action@v3 - with: - files: ./coverage/lcov.info - fail_ci_if_error: true - - quality-gate: - needs: [unit-tests, e2e-tests, coverage] - runs-on: ubuntu-latest - - steps: - - name: Check all tests passed - run: echo "All tests passed!" -``` - ---- - -## Test Documentation - -### Writing Good Tests - -**Best Practices:** - -1. **Descriptive Names:** -```javascript -// ❌ Bad -it('test 1', () => {}); - -// ✅ Good -it('should reject version when node is below minimum required', () => {}); -``` - -2. **Arrange-Act-Assert Pattern:** -```javascript -it('should validate correct version', () => { - // Arrange - const validator = validatorRules.node; - const version = 'v20.0.0'; - const requirement = '>=18'; - - // Act - const result = validator.versionValidate(version, requirement); - - // Assert - expect(result).toBe(true); -}); -``` - -3. **One Assertion Per Test (Generally):** -```javascript -// ❌ Testing multiple things -it('should work', () => { - expect(result.status).toBe(0); - expect(result.message).toBeDefined(); - expect(result.packages.length).toBeGreaterThan(0); -}); - -// ✅ Focused tests -it('should return success status', () => { - expect(result.status).toBe(0); -}); - -it('should include message in result', () => { - expect(result.message).toBeDefined(); -}); - -it('should include validated packages', () => { - expect(result.packages.length).toBeGreaterThan(0); -}); -``` - -4. **Test Both Happy and Sad Paths:** -```javascript -describe('checkSystem', () => { - it('should succeed with valid environment', async () => { - // ... - }); - - it('should fail with invalid environment', async () => { - // ... - }); - - it('should handle missing package.json', async () => { - // ... - }); - - it('should handle corrupted package.json', async () => { - // ... - }); -}); -``` - ---- - -## Testing Tools and Utilities - -### Recommended Additional Tools - -1. **Test Data Generators:** -```bash -npm install -D @faker-js/faker -``` - -2. **Snapshot Testing:** -```javascript -import { expect, it } from 'vitest'; - -it('should match snapshot', () => { - const output = formatOutput(result); - expect(output).toMatchSnapshot(); -}); -``` - -3. **Mock Server (for API testing):** -```bash -npm install -D msw -``` - -4. **Test Utilities:** -```bash -npm install -D @testing-library/jest-dom -``` - ---- - -## Migration Checklist - -### Pre-Migration -- [ ] Audit current test coverage -- [ ] Document test dependencies -- [ ] Backup current tests -- [ ] Choose new framework (Vitest recommended) - -### Migration Phase -- [ ] Install new testing framework -- [ ] Create configuration files -- [ ] Set up test helpers and utilities -- [ ] Migrate unit tests -- [ ] Migrate integration tests -- [ ] Add E2E tests -- [ ] Set up coverage reporting -- [ ] Update CI/CD pipelines - -### Post-Migration -- [ ] Verify all tests passing -- [ ] Check coverage meets thresholds -- [ ] Update documentation -- [ ] Remove old testing dependencies -- [ ] Train team on new framework - ---- - -## Success Criteria - -### Test Quality -- ✅ >85% code coverage -- ✅ All tests passing on all platforms -- ✅ Fast test execution (<30s for unit tests) -- ✅ Clear, descriptive test names -- ✅ Good test organization - -### Developer Experience -- ✅ Easy to run tests locally -- ✅ Fast feedback in watch mode -- ✅ Clear error messages -- ✅ Easy to write new tests -- ✅ Good documentation - -### CI/CD Integration -- ✅ Tests run on every PR -- ✅ Coverage tracked and reported -- ✅ Quality gates enforced -- ✅ Fast CI pipelines (<10 minutes) - ---- - -## Conclusion - -Modernizing the testing infrastructure for check-engine will significantly improve code quality, developer experience, and confidence in releases. The recommended migration to Vitest (or Jest) provides: - -1. **Better tooling** with modern features -2. **Improved coverage** tracking and reporting -3. **Faster feedback** loops for developers -4. **More comprehensive testing** with unit, integration, and E2E tests -5. **Better CI/CD integration** for automated quality gates - -By following this strategy, check-engine will have a robust, maintainable test suite that supports future development and ensures high quality releases. - From 568846a9113a4f7defb54a26647df221dd3110d9 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 8 Nov 2025 15:21:30 +0000 Subject: [PATCH 5/5] Reorder phases: foundation and modernization before new features Co-authored-by: mohlsen <3265497+mohlsen@users.noreply.github.com> --- MODERNIZATION_PLAN.md | 363 +++++++++++++++++++++++++++++------------- 1 file changed, 251 insertions(+), 112 deletions(-) diff --git a/MODERNIZATION_PLAN.md b/MODERNIZATION_PLAN.md index 8871cc0..1b129fc 100644 --- a/MODERNIZATION_PLAN.md +++ b/MODERNIZATION_PLAN.md @@ -1,13 +1,15 @@ # check-engine Modernization Plan -**Document Version:** 1.0 +**Document Version:** 2.0 **Date:** 2025-11-08 -**Status:** Planning Phase +**Status:** Planning Phase - Revised Phasing ## Executive Summary The `check-engine` project is a valuable Node.js utility that developers run manually or include in scripts/workflows to validate their development environment. This plan focuses on modernizing the tool itself to align with current best practices while expanding its ability to validate modern development tools and environments. +**Key Principle:** Build a solid foundation first, then add features. All modernization, testing improvements, tooling upgrades, TypeScript conversion, and API improvements happen BEFORE adding new validators and feature enhancements. This ensures a stable, well-tested base for future development. + ## What check-engine Is check-engine is a **command-line utility** and **programmatic library** that: @@ -47,10 +49,34 @@ check-engine is a **command-line utility** and **programmatic library** that: --- +## Phasing Strategy + +The modernization is structured in 6 phases, with a clear principle: **foundation before features**. + +**Phases 1-4** focus entirely on modernizing the existing codebase: +1. **Foundation** - Security, dependencies, documentation +2. **Testing** - Modern test framework and comprehensive coverage +3. **Tooling** - Code quality tools, CI/CD, TypeScript +4. **API** - Modernize code patterns (async/await, ESM, better APIs) + +**Phases 5-6** add new capabilities only after the foundation is solid: +5. **Features** - New validators and enhancements +6. **Extensibility** - Plugin system for community + +This approach ensures that: +- ✅ The codebase is stable and well-tested before changes +- ✅ Refactoring is easier with TypeScript and good tests +- ✅ New features are built on modern, maintainable code +- ✅ Risk is minimized by validating the foundation first + +--- + ## Modernization Recommendations ### Phase 1: Foundation (Weeks 1-2) - HIGH Priority +**Focus:** Establish solid foundation with security, dependencies, and documentation + #### 1.1 Update Runtime & Dependencies **Priority:** HIGH | **Effort:** 2-3 days @@ -58,15 +84,12 @@ check-engine is a **command-line utility** and **programmatic library** that: **Tasks:** - Update minimum Node.js version to `>=18` (LTS) or `>=20` (current LTS) - Fix security vulnerabilities via `npm audit fix` -- Update ESLint to latest version (v9.x with flat config) - Update all dependencies to latest stable versions -- Replace `bluebird` with native async/await -- Consider replacing `colors` with `chalk` or native ANSI codes +- Update ESLint to latest version (v9.x with flat config) **Benefits:** - Improved performance and security - Access to modern JavaScript features -- Better developer experience - Reduced technical debt --- @@ -115,14 +138,17 @@ check-engine is a **command-line utility** and **programmatic library** that: --- -### Phase 2: Modernization (Weeks 3-4) - MEDIUM Priority +### Phase 2: Testing Modernization (Weeks 3-4) - HIGH Priority -#### 2.1 Testing Modernization +**Focus:** Establish robust testing infrastructure before making changes -**Priority:** MEDIUM | **Effort:** 2-4 days +#### 2.1 Migrate Testing Framework + +**Priority:** HIGH | **Effort:** 2-4 days **Tasks:** - Migrate from tape to Vitest or Jest +- Maintain or improve existing test coverage (91 tests) - Add test coverage reporting (>80% threshold) - Add integration tests for CLI - Set up coverage tracking (Codecov/Coveralls) @@ -135,12 +161,17 @@ check-engine is a **command-line utility** and **programmatic library** that: - Visual coverage reports - More comprehensive test coverage - Easier to write and maintain tests +- Confidence for future refactoring --- -#### 2.2 Code Quality Tooling +### Phase 3: Code Quality & Tooling (Weeks 5-6) - HIGH Priority -**Priority:** MEDIUM | **Effort:** 1-2 days +**Focus:** Developer productivity improvements and modern tooling + +#### 3.1 Code Quality Tooling + +**Priority:** HIGH | **Effort:** 1-2 days **Tasks:** - Update ESLint to v9 with flat config @@ -158,7 +189,26 @@ check-engine is a **command-line utility** and **programmatic library** that: --- -#### 2.3 TypeScript Migration (Optional) +#### 3.2 CI/CD Pipeline Enhancements + +**Priority:** HIGH | **Effort:** 2 days + +**Tasks:** +- Test on multiple Node.js versions (18, 20, 22) +- Test on multiple OS (Ubuntu, macOS, Windows) +- Add CodeQL security scanning +- Add automated release process (release-please) +- Add performance benchmarking + +**Benefits:** +- Multi-platform support verified +- Automated release process +- Better security posture +- Performance tracking + +--- + +#### 3.3 TypeScript Migration **Priority:** MEDIUM | **Effort:** 3-5 days @@ -176,98 +226,68 @@ check-engine is a **command-line utility** and **programmatic library** that: --- -#### 2.4 CI/CD Pipeline Enhancements +### Phase 4: API Modernization (Weeks 7-8) - MEDIUM Priority + +**Focus:** Modernize the codebase and API without adding new features -**Priority:** MEDIUM | **Effort:** 2 days +#### 4.1 Async/Await Migration + +**Priority:** MEDIUM | **Effort:** 2-3 days **Tasks:** -- Test on multiple Node.js versions (18, 20, 22) -- Test on multiple OS (Ubuntu, macOS, Windows) -- Add CodeQL security scanning -- Add automated release process (release-please) -- Add performance benchmarking +- Convert to native async/await (remove Bluebird) +- Update promise handling throughout codebase +- Improve error handling with custom error classes +- Add proper error propagation **Benefits:** -- Multi-platform support verified -- Automated release process -- Better security posture -- Performance tracking +- Modern JavaScript patterns +- Better error handling +- Easier to understand and maintain +- No external promise library dependency --- -### Phase 3: Feature Enhancement (Weeks 5-6) - MEDIUM Priority - -#### 3.1 Add Modern Tool Validators +#### 4.2 Module System Modernization -**Priority:** MEDIUM | **Effort:** 3-5 days - -**Focus:** Add validators for tools developers use to build/deploy containerized and cloud applications +**Priority:** MEDIUM | **Effort:** 1-2 days -**New Validators to Add:** -- **Container Tools:** - - `docker` - Docker CLI for building containers - - `docker-compose` - Docker Compose for local development - - `podman` - Alternative container runtime - -- **Kubernetes Tools:** - - `kubectl` - Kubernetes CLI - - `helm` - Kubernetes package manager - - `minikube` - Local Kubernetes for development - - `kind` - Kubernetes in Docker - -- **Cloud Platform CLIs:** - - `aws` - AWS CLI - - `gcloud` - Google Cloud CLI - - `az` - Azure CLI - -- **Infrastructure as Code:** - - `terraform` - Infrastructure provisioning - - `pulumi` - Modern IaC tool - -- **Modern Package Managers:** - - `bun` - Fast all-in-one JavaScript runtime - - `volta` - JavaScript tool version manager - - `fnm` - Fast Node Manager - -- **Build Tools:** - - `make` - GNU Make - - `cmake` - Cross-platform build system - - `gradle` - Java/Android build tool +**Tasks:** +- Add ESM module support +- Maintain CJS compatibility for backward compatibility +- Update exports and imports +- Test both module formats **Benefits:** -- Support for modern development workflows -- Validate environments for container/cloud development -- Help teams ensure correct tool installation -- More comprehensive environment validation +- Modern module system support +- Future-proof codebase +- Better tree-shaking potential --- -#### 3.2 API Modernization +#### 4.3 API Configuration Options -**Priority:** MEDIUM | **Effort:** 2-3 days +**Priority:** MEDIUM | **Effort:** 1-2 days **Tasks:** -- Convert to native async/await (remove Bluebird) -- Add ESM module support (maintain CJS compatibility) -- Improve error handling with custom error classes - Add configuration options: - Timeout settings - Parallel execution - Custom validators - Output formatting - Add event emitters for progress tracking +- Improve programmatic API **Benefits:** -- Modern JavaScript patterns -- Better error handling - More flexible API - Better performance options +- Easier integration --- -#### 3.3 Output & Reporting Enhancements +#### 4.4 Output & Reporting Enhancements -**Priority:** LOW-MEDIUM | **Effort:** 1-2 days +**Priority:** MEDIUM | **Effort:** 1-2 days **Tasks:** - Add multiple output formats: @@ -288,11 +308,58 @@ check-engine is a **command-line utility** and **programmatic library** that: --- -### Phase 4: Polish & Extension (Ongoing) - LOW Priority +### Phase 5: New Validators & Features (Weeks 9-10) - MEDIUM Priority + +**Focus:** Add new validators now that foundation is solid + +#### 5.1 Add Modern Tool Validators + +**Priority:** MEDIUM | **Effort:** 3-5 days + +**Focus:** Add validators for tools developers use to build/deploy containerized and cloud applications + +**New Validators to Add:** +- **Container Tools:** + - `docker` - Docker CLI for building containers + - `docker-compose` - Docker Compose for local development + - `podman` - Alternative container runtime + +- **Kubernetes Tools:** + - `kubectl` - Kubernetes CLI + - `helm` - Kubernetes package manager + - `minikube` - Local Kubernetes for development + - `kind` - Kubernetes in Docker + +- **Cloud Platform CLIs:** + - `aws` - AWS CLI + - `gcloud` - Google Cloud CLI + - `az` - Azure CLI + +- **Infrastructure as Code:** + - `terraform` - Infrastructure provisioning + - `pulumi` - Modern IaC tool + +- **Modern Package Managers:** + - `bun` - Fast all-in-one JavaScript runtime + - `volta` - JavaScript tool version manager + - `fnm` - Fast Node Manager + +- **Build Tools:** + - `make` - GNU Make + - `cmake` - Cross-platform build system + - `gradle` - Java/Android build tool + +**Benefits:** +- Support for modern development workflows +- Validate environments for container/cloud development +- Help teams ensure correct tool installation +- More comprehensive environment validation -#### 4.1 Developer Experience Improvements +--- -**Priority:** LOW | **Effort:** 1-2 days +#### 5.2 Developer Experience Improvements + +**Priority:** MEDIUM | **Effort:** 1-2 days **Tasks:** - Add VS Code configuration: @@ -313,15 +380,19 @@ check-engine is a **command-line utility** and **programmatic library** that: --- -#### 4.2 Extensibility +### Phase 6: Extensibility (Ongoing) - LOW Priority + +**Focus:** Enable community contributions and custom validators + +#### 6.1 Plugin System **Priority:** LOW | **Effort:** 2-3 days **Tasks:** - Allow custom validators via configuration - Plugin system for external validators -- Validator marketplace/registry (future) - Document validator API +- Create examples for custom validators **Benefits:** - Community can add validators @@ -330,6 +401,21 @@ check-engine is a **command-line utility** and **programmatic library** that: --- +#### 6.2 Validator Marketplace (Future) + +**Priority:** LOW | **Effort:** TBD + +**Tasks:** +- Design validator registry +- Create validator publishing guidelines +- Build discovery mechanism + +**Benefits:** +- Easy discovery of community validators +- Ecosystem growth + +--- + ## Implementation Timeline ### Phase 1: Foundation (Weeks 1-2) @@ -345,41 +431,66 @@ check-engine is a **command-line utility** and **programmatic library** that: --- -### Phase 2: Modernization (Weeks 3-4) -**Focus:** Testing, code quality, CI/CD +### Phase 2: Testing Modernization (Weeks 3-4) +**Focus:** Establish robust testing before making changes **Deliverables:** - ✅ Modern testing framework (Vitest/Jest) -- ✅ >80% test coverage -- ✅ Pre-commit hooks and linting -- ✅ TypeScript support (optional) -- ✅ Enhanced CI/CD +- ✅ >80% test coverage maintained +- ✅ Integration tests for CLI +- ✅ Coverage tracking and badges -**Estimated Effort:** 8-12 days +**Estimated Effort:** 2-4 days --- -### Phase 3: Feature Enhancement (Weeks 5-6) -**Focus:** New validators, modern API +### Phase 3: Code Quality & Tooling (Weeks 5-6) +**Focus:** Developer productivity and modern tooling + +**Deliverables:** +- ✅ ESLint 9 + Prettier + pre-commit hooks +- ✅ Enhanced CI/CD (multi-platform, automated releases) +- ✅ TypeScript support +- ✅ Consistent code quality + +**Estimated Effort:** 6-9 days + +--- + +### Phase 4: API Modernization (Weeks 7-8) +**Focus:** Modernize codebase without adding features + +**Deliverables:** +- ✅ Native async/await (remove Bluebird) +- ✅ ESM module support +- ✅ Better configuration options +- ✅ Multiple output formats + +**Estimated Effort:** 5-7 days + +--- + +### Phase 5: New Validators & Features (Weeks 9-10) +**Focus:** Add new validators with solid foundation in place **Deliverables:** - ✅ Modern tool validators (docker, kubectl, cloud CLIs, etc.) -- ✅ Modern API (async/await, ESM) -- ✅ Better output formats +- ✅ Improved CLI UX +- ✅ VS Code configuration -**Estimated Effort:** 6-10 days +**Estimated Effort:** 4-7 days --- -### Phase 4: Polish (Ongoing) -**Focus:** Developer experience, extensibility +### Phase 6: Extensibility (Ongoing) +**Focus:** Plugin system and community contributions **Deliverables:** -- ✅ Better DX with VS Code config -- ✅ Plugin system -- ✅ Community contributions +- ✅ Plugin system for custom validators +- ✅ Validator API documentation +- ✅ Community ecosystem -**Estimated Effort:** Variable +**Estimated Effort:** Variable (2-3 days initial, ongoing) --- @@ -418,23 +529,39 @@ check-engine is a **command-line utility** and **programmatic library** that: ## Success Metrics -### After Phase 1 +### After Phase 1: Foundation - ✅ 0 security vulnerabilities - ✅ Node.js 18+ supported - ✅ Complete documentation set -- ✅ All tests passing +- ✅ All existing tests passing -### After Phase 2 -- ✅ >80% test coverage -- ✅ Modern testing framework +### After Phase 2: Testing +- ✅ >80% test coverage maintained +- ✅ Modern testing framework (Vitest/Jest) +- ✅ Integration tests in place +- ✅ Coverage tracking active + +### After Phase 3: Code Quality - ✅ Pre-commit hooks working -- ✅ Automated releases +- ✅ Automated releases configured +- ✅ TypeScript support added +- ✅ Multi-platform CI/CD -### After Phase 3 -- ✅ 10+ new modern tool validators -- ✅ Modern API with ESM support +### After Phase 4: API Modernization +- ✅ Native async/await throughout +- ✅ ESM module support - ✅ Multiple output formats -- ✅ Better CI/CD integration +- ✅ Better configuration options + +### After Phase 5: New Features +- ✅ 10+ new modern tool validators +- ✅ Improved CLI UX +- ✅ Better developer experience + +### After Phase 6: Extensibility +- ✅ Plugin system available +- ✅ Community can add validators +- ✅ Documented validator API --- @@ -595,17 +722,29 @@ check-engine # with kubectl, aws in engines ## Conclusion -This modernization plan focuses on what check-engine is: a developer utility for validating local development environments. The plan includes: +This modernization plan focuses on what check-engine is: a developer utility for validating local development environments. The plan follows a disciplined phased approach: + +**Phases 1-4: Foundation First (Weeks 1-8)** +1. **Foundation** - Security, dependencies, documentation +2. **Testing** - Modern test framework with strong coverage +3. **Tooling** - Code quality, CI/CD, TypeScript +4. **API** - Modernize code patterns (async/await, ESM) + +**Phases 5-6: Features Second (Weeks 9+)** +5. **Features** - New validators for modern tools (docker, kubectl, cloud CLIs) +6. **Extensibility** - Plugin system for community validators -1. **Foundation updates** - Security, dependencies, documentation -2. **Modernization** - Testing, code quality, CI/CD -3. **Feature expansion** - New validators for modern tools (docker, kubectl, cloud CLIs) -4. **API improvements** - Modern JavaScript patterns +By modernizing the foundation first, we ensure that: +- New features are built on stable, well-tested code +- Refactoring is easier with TypeScript and comprehensive tests +- The codebase is maintainable for the long term +- Risk is minimized by proving the foundation works before adding features The goal is to make check-engine the best tool for ensuring developers have the right tools installed for modern development workflows, including container and cloud development, without turning check-engine itself into a cloud service. --- -**Status:** Planning Complete -**Total Estimated Time:** 19-29 days (4-6 weeks) for Phases 1-3 +**Status:** Planning Complete - Revised Phasing +**Total Estimated Time:** 22-34 days (4-7 weeks) for Phases 1-5 +**Key Change:** All modernization before new features **Next Phase:** Implementation (awaiting approval)