refactor: complete Node.js to Deno migration (#147)

Author: jaypatrick

.github/workflows/gatsby.yml

@@ -1,4 +1,7 @@
-# Sample workflow for building and deploying a Gatsby site to GitHub Pages
+# Workflow for building and deploying the Gatsby website to GitHub Pages
+#
+# Note: The website (src/website/) is a Gatsby/React application that requires Node.js.
+# This is separate from the TypeScript projects which use Deno.
 #
 # To get started with Gatsby see: https://www.gatsbyjs.com/docs/quick-start/
 #

.github/workflows/typescript.yml

@@ -1,5 +1,5 @@
-# This workflow will build and test TypeScript/Deno projects
-name: Deno Build
+# This workflow will build and test TypeScript projects using Deno
+name: Deno TypeScript Build
 
 on:
   push:
@@ -94,28 +94,3 @@ jobs:
 
     - name: Format check
       run: deno fmt --check src/
-
-  build-website:
-    name: Build Website (Node.js)
-    runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: ./src/website
-
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Setup Node.js
-      uses: actions/setup-node@v4
-      with:
-        node-version: '22'
-        cache: 'npm'
-        cache-dependency-path: './src/website/package-lock.json'
-
-    - name: Install dependencies
-      run: npm ci
-
-    - name: Build Gatsby site
-      run: npm run build
-      env:
-        NODE_ENV: production

CLAUDE.md

@@ -28,7 +28,7 @@ This repository is a comprehensive multi-language toolkit for ad-blocking, netwo
 - **Linear Import Tool** (`src/linear/`) - TypeScript tool with Deno support
 
 ### Website
-- **Gatsby Site** (`src/website/`) - Portfolio site deployed to GitHub Pages (Node.js)
+- **Gatsby Site** (`src/website/`) - Portfolio site deployed to GitHub Pages (requires Node.js)
 
 ### Configuration Support
 All compilers support JSON, YAML, and TOML configuration formats with full @adguard/hostlist-compiler compatibility.
@@ -41,7 +41,7 @@ A fully-featured Docker environment with all compilers and tools:
 # Dockerfile.warp
 FROM mcr.microsoft.com/dotnet/sdk:10.0-noble
 # Includes: .NET 10 SDK, Deno 2.x, Python 3.12, Rust stable, PowerShell 7
-# Pre-installed: hostlist-compiler, yq, pytest, ruff, clippy, Pester
+# Pre-installed: hostlist-compiler (via Deno), yq, pytest, ruff, clippy, Pester
 ```
 
 Build and run:
@@ -214,6 +214,7 @@ deno task check            # Type check
 
 ### Gatsby Website (`src/website/`)
 ```bash
+# Note: Website still uses Node.js/npm (Gatsby is a Node.js framework)
 cd src/website
 npm ci
 npm run develop    # Dev server at localhost:8000
@@ -443,8 +444,8 @@ RemoveComments, Compress, RemoveModifiers, Validate, ValidateAllowIp, Deduplicat
 
 GitHub Actions workflows validate:
 - `.github/workflows/dotnet.yml` - Builds/tests .NET projects (API client and rules compiler) with .NET 10
-- `.github/workflows/typescript.yml` - Deno 2.x for TypeScript projects, Node.js 22 for website
-- `.github/workflows/gatsby.yml` - Builds website and deploys to GitHub Pages
+- `.github/workflows/typescript.yml` - Deno 2.x for all TypeScript projects
+- `.github/workflows/gatsby.yml` - Builds website (Node.js) and deploys to GitHub Pages
 - `.github/workflows/security.yml` - Consolidated security scanning (CodeQL, DevSkim, PSScriptAnalyzer)
 - `.github/workflows/release.yml` - Builds and publishes release binaries (.NET, Rust, Python)
 - `.github/workflows/claude.yml` - Claude AI integration for @claude mentions
@@ -456,11 +457,11 @@ GitHub Actions workflows validate:
 |-------------|---------|--------------|
 | .NET SDK | 10.0+ | .NET compiler, API client |
 | Deno | 2.0+ | TypeScript projects (rules compiler, API client, linear) |
-| Node.js | 22.x LTS | Website (Gatsby) |
+| Node.js | 22.x LTS | Website only (Gatsby) |
 | PowerShell | 7+ | PowerShell scripts |
 | Python | 3.9+ | Python compiler |
 | Rust | 1.85+ | Rust compiler (install via rustup) |
-| hostlist-compiler | Latest | All compilers (`npm install -g @adguard/hostlist-compiler`) |
+| hostlist-compiler | Latest | All compilers (via Deno: `deno run npm:@adguard/hostlist-compiler`) |
 | Docker | 24.0+ | Container development (optional but recommended) |
 
 ## Key File Locations

Dockerfile.warp

@@ -1,12 +1,12 @@
 # =============================================================================
 # Docker Development Environment for ad-blocking toolkit
-# Includes: .NET 10, Node.js 22 LTS, Python 3.12, Rust, PowerShell 7
+# Includes: .NET 10, Deno 2.x, Python 3.12, Rust, PowerShell 7
 # =============================================================================
 
 FROM mcr.microsoft.com/dotnet/sdk:10.0-noble
 
 # Build arguments for version control
-ARG NODE_VERSION=22
+ARG DENO_VERSION=2.x
 ARG PYTHON_VERSION=3.12
 ARG RUST_VERSION=stable
 
@@ -15,12 +15,12 @@ ENV DEBIAN_FRONTEND=noninteractive \
     DOTNET_CLI_TELEMETRY_OPTOUT=1 \
     DOTNET_NOLOGO=1 \
     DOTNET_SKIP_FIRST_TIME_EXPERIENCE=1 \
-    NODE_ENV=development \
+    DENO_DIR=/root/.deno \
     PYTHONDONTWRITEBYTECODE=1 \
     PYTHONUNBUFFERED=1 \
     CARGO_HOME=/root/.cargo \
     RUSTUP_HOME=/root/.rustup \
-    PATH="/root/.cargo/bin:${PATH}"
+    PATH="/root/.deno/bin:/root/.cargo/bin:${PATH}"
 
 # =============================================================================
 # Base dependencies
@@ -43,15 +43,16 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     && apt-get clean && rm -rf /var/lib/apt/lists/*
 
 # =============================================================================
-# Node.js 22.x LTS via NodeSource
+# Deno 2.x
 # =============================================================================
-RUN curl -fsSL https://deb.nodesource.com/setup_${NODE_VERSION}.x | bash - && \
-    apt-get install -y --no-install-recommends nodejs && \
-    npm install -g npm@latest && \
-    apt-get clean && rm -rf /var/lib/apt/lists/*
+RUN curl -fsSL https://deno.land/install.sh | sh && \
+    ln -s /root/.deno/bin/deno /usr/local/bin/deno
 
-# Install global npm packages
-RUN npm install -g @adguard/hostlist-compiler typescript ts-node
+# Install hostlist-compiler via Deno's npm compatibility
+# Create a wrapper script for hostlist-compiler
+RUN echo '#!/bin/sh\ndeno run --allow-read --allow-write --allow-env --allow-net --allow-run npm:@adguard/hostlist-compiler "$@"' > /usr/local/bin/hostlist-compiler && \
+    chmod +x /usr/local/bin/hostlist-compiler && \
+    deno cache npm:@adguard/hostlist-compiler
 
 # =============================================================================
 # Python 3.12
@@ -107,16 +108,15 @@ RUN curl -sL https://github.com/mikefarah/yq/releases/latest/download/yq_linux_a
 # =============================================================================
 RUN echo "=== Installed Versions ===" && \
     echo "dotnet: $(dotnet --version)" && \
-    echo "node: $(node --version)" && \
-    echo "npm: $(npm --version)" && \
+    echo "deno: $(deno --version | head -1)" && \
     echo "python: $(python --version)" && \
     echo "pip: $(pip --version)" && \
     echo "rustc: $(rustc --version)" && \
     echo "cargo: $(cargo --version)" && \
     echo "pwsh: $(pwsh --version)" && \
     echo "git: $(git --version)" && \
     echo "yq: $(yq --version)" && \
-    echo "hostlist-compiler: $(hostlist-compiler --version)" && \
+    echo "hostlist-compiler: available via deno" && \
     echo "=========================="
 
 # =============================================================================

docker-compose.yml

@@ -11,15 +11,14 @@ services:
       context: .
       dockerfile: Dockerfile.warp
       args:
-        NODE_VERSION: 22
+        DENO_VERSION: 2.x
         RUST_VERSION: stable
     image: ad-blocking-dev:latest
     container_name: ad-blocking-dev
     volumes:
       - .:/workspace
       # Named volumes for dependency caching
-      - node_modules_ts:/workspace/src/rules-compiler-typescript/node_modules
-      - node_modules_web:/workspace/src/website/node_modules
+      - deno_cache:/root/.deno
       - cargo_registry:/root/.cargo/registry
       - cargo_git:/root/.cargo/git
       - nuget_packages:/root/.nuget/packages
@@ -44,9 +43,9 @@ services:
     container_name: ad-blocking-typescript
     volumes:
       - .:/workspace
-      - node_modules_ts:/workspace/src/rules-compiler-typescript/node_modules
+      - deno_cache:/root/.deno
     working_dir: /workspace/src/rules-compiler-typescript
-    command: npm run compile
+    command: deno task compile
     depends_on:
       - dev
     profiles:
@@ -118,23 +117,18 @@ services:
       - ad-blocking-net
 
   # ---------------------------------------------------------------------------
-  # Gatsby Website development server
+  # Gatsby Website development server (requires Node.js - uses separate image)
   # ---------------------------------------------------------------------------
   website:
-    build:
-      context: .
-      dockerfile: Dockerfile.warp
-    image: ad-blocking-dev:latest
+    image: node:22-slim
     container_name: ad-blocking-website
     volumes:
       - .:/workspace
       - node_modules_web:/workspace/src/website/node_modules
     ports:
       - "8000:8000"
     working_dir: /workspace/src/website
-    command: npm run develop -- --host 0.0.0.0
-    depends_on:
-      - dev
+    command: sh -c "npm ci && npm run develop -- --host 0.0.0.0"
     profiles:
       - website
     networks:
@@ -151,15 +145,15 @@ services:
     container_name: ad-blocking-test
     volumes:
       - .:/workspace
-      - node_modules_ts:/workspace/src/rules-compiler-typescript/node_modules
+      - deno_cache:/root/.deno
       - nuget_packages:/root/.nuget/packages
       - cargo_registry:/root/.cargo/registry
       - cargo_git:/root/.cargo/git
     working_dir: /workspace
     command: >
       bash -c "
         echo '=== Running TypeScript Tests ===' &&
-        cd /workspace/src/rules-compiler-typescript && npm test &&
+        cd /workspace/src/rules-compiler-typescript && deno task test &&
         echo '=== Running .NET Tests ===' &&
         cd /workspace/src/rules-compiler-dotnet && dotnet test RulesCompiler.slnx &&
         echo '=== Running Python Tests ===' &&
@@ -206,8 +200,8 @@ services:
 # Named volumes for dependency caching
 # =============================================================================
 volumes:
-  node_modules_ts:
-    name: ad-blocking-node-ts
+  deno_cache:
+    name: ad-blocking-deno-cache
   node_modules_web:
     name: ad-blocking-node-web
   cargo_registry:

docs/LINEAR_DOCUMENTATION.md

@@ -68,8 +68,8 @@ A comprehensive, multi-component ad-blocking solution designed for network-level
 **Technology Stack:**
 - TypeScript 5.4.5
 - @adguard/hostlist-compiler v1.0.39
-- Jest 29.7.0 (testing)
-- Node.js 20
+- Deno test (testing)
+- Deno 2.0+
 
 **Key Files:**
 | File | Description |
@@ -234,8 +234,8 @@ ad-blocking/
 |------------|---------|---------|
 | TypeScript | 5.4.5 | Strongly-typed JavaScript |
 | @adguard/hostlist-compiler | 1.0.39 | Core compilation engine |
-| Node.js | 20 | JavaScript runtime |
-| Jest | 29.7.0 | Testing framework |
+| Deno | 2.0+ | TypeScript/JavaScript runtime |
+| Deno test | built-in | Testing framework |
 
 ### Frontend
 | Technology | Version | Purpose |
@@ -285,16 +285,14 @@ Full API documentation available in `/docs/api/`.
 ## Quick Start
 
 ### Prerequisites
-- Node.js 20+
+- Deno 2.0+
 - .NET 10 SDK
 - PowerShell 7+
 
 ### Filter Compiler
 ```bash
-cd src/filter-compiler
-npm install
-npm run build
-npm run compile
+cd src/rules-compiler-typescript
+deno task compile
 ```
 
 ### API Client
@@ -308,7 +306,7 @@ dotnet test
 ### Website
 ```bash
 cd src/website
-npm install
+npm install  # Website still uses Node.js/Gatsby
 npm run develop
 ```
 
@@ -318,8 +316,8 @@ npm run develop
 
 ### TypeScript Tests
 ```bash
-cd src/filter-compiler
-npm test
+cd src/rules-compiler-typescript
+deno task test
 ```
 
 ### .NET Tests