v1.3.0

.github/workflows/ci.yml

@@ -15,7 +15,7 @@ permissions:
 
 jobs:
   ci:
-    name: Build
+    name: Compile, Test, Build
     runs-on: ubuntu-latest
 
     steps:
@@ -37,5 +37,28 @@ jobs:
       - name: Prepare WXT types
         run: yarn exec wxt prepare
 
+      - name: Compile TypeScript
+        id: compile
+        continue-on-error: true
+        shell: bash
+        run: |
+          set -o pipefail
+          yarn compile --pretty false 2>&1 | tee compile.log
+
+      - name: Upload TypeScript diagnostics
+        if: steps.compile.outcome == 'failure'
+        uses: actions/upload-artifact@v5
+        with:
+          name: typescript-diagnostics
+          path: compile.log
+          if-no-files-found: error
+
+      - name: Fail on TypeScript errors
+        if: steps.compile.outcome == 'failure'
+        run: exit 1
+
+      - name: Run tests
+        run: yarn test
+
       - name: Build extension
         run: yarn build

.github/workflows/release.yml

@@ -1,4 +1,4 @@
-name: "Submit to Web Store"
+name: Submit to Web Store
 permissions:
   contents: write
 
@@ -7,10 +7,6 @@ on:
     tags:
       - "[0-9]+.[0-9]+.[0-9]+"
 
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
 jobs:
   build-and-release:
     name: Build and Release
@@ -27,32 +23,30 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v7
-
-      - name: Enable Corepack
-        run: corepack enable
+        uses: actions/checkout@v4
 
-      - name: Setup Node.js with Yarn cache
-        uses: actions/setup-node@v6
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
         with:
           node-version: 24.x
-          cache: "yarn"
+          cache: yarn
 
       - name: Install dependencies
-        run: yarn install --immutable --mode=skip-build
+        run: yarn install --frozen-lockfile
 
       - name: Prepare WXT types
-        run: yarn exec wxt prepare
+        run: yarn wxt prepare
+
+      - name: Run tests
+        run: yarn test
 
-      - name: Build the extension
+      - name: Build extension
         run: |
           yarn zip
-          yarn zip:firefox --mv3
-          yarn zip -b edge
-          yarn zip -b opera
+          yarn zip:firefox
 
       - name: Verify build outputs
-        run: ls -l .output/*.zip
+        run: ls -lh .output/*.zip
 
       - name: Update CHANGELOG
         id: changelog
@@ -69,19 +63,16 @@ jobs:
           file_pattern: CHANGELOG.md
 
       - name: Create GitHub Release
-        if: startsWith(github.ref, 'refs/tags/')
-        uses: softprops/action-gh-release@v3
+        uses: softprops/action-gh-release@v2
         with:
-          name: "v.${{ github.ref_name }}"
-          draft: true
+          name: "v${{ github.ref_name }}"
+          draft: false
           generate_release_notes: true
-          body_path: INSTALL.md
           files: .output/*.zip
 
       - name: Submit to stores
-        if: startsWith(github.ref, 'refs/tags/')
         run: |
-          yarn exec wxt submit \
+          yarn wxt submit \
             --chrome-zip .output/*-chrome.zip \
             --firefox-zip .output/*-firefox.zip \
             --firefox-sources-zip .output/*-sources.zip

.gitignore

@@ -11,6 +11,8 @@ lerna-debug.log*
 
 node_modules
 .output
+web/dist/
+*.tsbuildinfo
 stats.html
 stats-*.json
 .wxt

CHANGELOG.md

@@ -5,6 +5,44 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Fixed
+
+- Added comprehensive JSDoc comments to all functions and components to meet documentation standards
+- Fixed async/await anti-patterns by replacing `void` statements with proper `.catch()` error handlers
+- Improved variable declarations to use `const` where appropriate
+- Optimized JSX component nesting by extracting inline form input into a separate component
+- Resolved all DeepSource code quality warnings (24 issues)
+- Optimized alias filtering by normalizing search input once and using a set for favorites
+- Added regression coverage for plus-addressed Gmail validation and trimmed searches
+- Removed generated TypeScript build-info files from version control
+
+## [1.3.0] - 2026-07-13
+
+### Added
+
+- Added website-aware alias suggestions based on the current hostname
+- Added an email input helper with inline icons, suggestion popups, live previews, and explicit Use actions
+- Added previous-alias navigation and an information panel explaining supported rules and local-only storage
+- Added expanded statistics metrics and Russian and Turkish translations
+- Added a product landing page with automated GitHub Pages deployment
+
+### Changed
+
+- Enhanced the context menu with dynamic, website-specific alias suggestions
+- Updated the History tab to show aliases across websites and store history per email account
+- Improved popup navigation, layout, styling, and alias selection behavior
+- Reorganized the content script and colocated its email helper styles
+
+### Fixed
+
+- Preserved email input width and flex layout when injecting the helper icon
+- Improved helper popup positioning and hover behavior to prevent accidental closing
+- Hid the Tags statistics tab when there is not enough data for a useful chart
+- Hardened content rendering against client-side cross-site scripting
+- Resolved code quality, localization, and build workflow issues
+
 ## [1.2.0] - 2026-07-03
 
 ### Added

CLAUDE.md

@@ -0,0 +1,200 @@
+# Gmail Alias Toolkit Development Guide
+
+## Code Standards
+
+### JSDoc Comments (Required)
+
+All functions, arrow functions, and exported components must have a JSDoc comment. This prevents DeepSource (`JS-D1001`) documentation warnings.
+
+**Rule:** Every function declaration, arrow function, and exported component needs at minimum a one-line JSDoc comment describing its purpose.
+
+**Format:**
+
+```typescript
+/** Brief description of what this function does. */
+function myFunction() {
+  // ...
+}
+```
+
+**Examples:**
+
+- `/** Renders a bar chart comparing alias creation counts for today, week, and month. */`
+- `/** Loads active email account and fetches associated statistics from storage. */`
+- `/** Handles storage changes and reloads stats if relevant keys change. */`
+
+**Why:** DeepSource flags missing documentation as `JS-D1001` errors. Adding JSDoc prevents build/review failures and maintains code clarity.
+
+---
+
+## Project Structure
+
+- `entrypoints/` - Browser extension entry points
+- `src/` - Shared components and utilities
+- `lib/` - Core libraries (i18n, etc.)
+
+---
+
+## Phase 1: Website Detection & Auto-suggestions
+
+**Implemented:**
+
+- Auto-detect active tab website (hostname normalization)
+- Generate 5 alias suggestions per site
+- Save website → alias mapping (local storage)
+- Show "Previously used" alias in Statistics tab
+- Display suggestions in Statistics tab with one-click copy
+- Integrated into right-click context menu (3 suggestions)
+- Auto-save mapping when suggestion is used
+
+**Key Files:**
+
+- `src/utils/hostnameNormalizer.ts` — URL → clean keyword (shopee, github, etc.)
+- `src/services/websiteAliasService.ts` — Storage, retrieval, suggestion generation
+- `entrypoints/background.ts` — Messaging + dynamic context menu population
+- `entrypoints/popup/components/Statistics.tsx` — Website detection UI
+
+**Privacy Note:**
+
+Local-first: All mappings stored in browser.storage.local. No server or analytics.
+
+---
+
+## Phase 2: Email Input Helper UI
+
+**Implemented:**
+
+- Detect email inputs on any webpage
+- Inject blue icon next to each input (like Roboform)
+- Popup on icon click showing:
+  - Previous alias for current website (highlighted in yellow)
+  - 5 suggestion buttons
+- One-click fill + auto-save mapping
+- Supports controlled inputs (React, Vue, Angular)
+- Watch for dynamically added inputs (SPA support)
+- Dark mode styling
+
+**Key Files:**
+
+- `entrypoints/content/index.ts` — Content script entry point
+- `entrypoints/content/email-input-helper.ts` — Icon injection + popup logic
+- `entrypoints/content/email-input-helper.css` — UI styling
+
+**Detection Logic:**
+
+- Looks for: `input[type="email"]`, `input[name*="email"]`, `input[placeholder*="email"]`
+- Uses MutationObserver to catch dynamically added inputs
+- Skips hidden inputs (offsetParent === null)
+
+---
+
+## Testing & CI
+
+### Automated Code Quality Checks
+
+Code is checked by DeepSource for:
+
+- Documentation completeness (JS-D1001) — All functions and components require JSDoc
+- Unused imports/variables (JS-0356)
+- Array index keys (JS-0437)
+- Anti-patterns: void statements, improper variable declarations
+- Other code quality issues
+
+All issues must be resolved before merging to `main`.
+
+### Unit Testing with Vitest
+
+The project uses **Vitest** for unit testing. Tests are located in the `tests/` directory mirroring the source structure.
+
+**Test File Locations:**
+
+- `tests/services/` — Tests for service layer (websiteAliasService, etc.)
+- `tests/utils/` — Tests for utility functions (hostnameNormalizer, inlineSiteSettings, etc.)
+- `tests/popup/` — Tests for popup components and utilities
+- `tests/content/` — Tests for content script helper functions
+
+**Running Tests:**
+
+```bash
+npm test                    # Run all tests
+npm test -- [file]         # Run specific test file
+npm test -- --ui           # Run with UI dashboard
+npm test -- --coverage     # Generate coverage report
+```
+
+**Test Standards:**
+
+1. **Coverage Requirements:**
+   - Utility functions: 100% line coverage
+   - Service layer: 90%+ line coverage
+   - Components: 80%+ line coverage
+
+2. **Test Organization:**
+   - One test file per module
+   - Use `describe()` blocks to group related tests
+   - Test both success and error paths
+   - Mock external dependencies (browser APIs, storage)
+
+3. **Best Practices:**
+   - Use descriptive test names that explain what is being tested
+   - Test edge cases and boundary conditions
+   - Mock browser storage and extension APIs
+   - Arrange → Act → Assert pattern for test structure
+   - Use `beforeEach()` to reset state between tests
+
+**Example Test Structure:**
+
+```typescript
+import { describe, expect, it, beforeEach, vi } from "vitest";
+
+describe("functionName", () => {
+  beforeEach(() => {
+    // Reset state before each test
+    vi.clearAllMocks();
+  });
+
+  it("should do something specific", () => {
+    // Arrange: Set up test data
+    const input = "test";
+
+    // Act: Call the function
+    const result = functionName(input);
+
+    // Assert: Verify the result
+    expect(result).toBe("expected");
+  });
+});
+```
+
+### Test Coverage
+
+**Current Coverage Areas:**
+
+- ✅ Hostname normalization and URL parsing
+- ✅ Website alias storage and retrieval
+- ✅ Alias suggestion generation
+- ✅ Email address normalization
+- ✅ HTML escaping (XSS prevention)
+- ✅ Inline site settings management
+- ✅ Gmail tricks generation (dot tricks, plus tags, etc.)
+- ✅ Custom alias creation
+- ✅ Popup components (Button, Input, Toggle, etc.)
+
+**Add Tests For:**
+
+- New utility functions (100% line coverage)
+- Service layer changes (test both happy path and error cases)
+- Complex component logic (interaction testing)
+- Browser API integrations (with proper mocking)
+
+### Continuous Integration
+
+Pull requests to `main` require:
+
+1. ✅ All tests passing
+2. ✅ Code coverage maintained
+3. ✅ DeepSource checks passing (zero issues)
+4. ✅ TypeScript type checking strict mode
+5. ✅ Prettier formatting compliance
+
+See [CONTRIBUTING.md](CONTRIBUTING.md#publishing-to-extension-stores) for publishing and store submission procedures.