Contributing to jev-notion

September 20, 2026 · View on GitHub

Thank you for your interest in contributing to jev-notion! Whether you are reporting an issue, proposing an improvement, fixing a bug, or contributing translations, your help is welcome.

Table of Contents

Code of Conduct

All contributors and participants are expected to uphold our Code of Conduct. Please report unacceptable behavior following the instructions in that document.

Development Setup

Prerequisites

  • Node.js: v20.0.0 or higher
  • npm: v10.0.0 or higher
  • macOS (for the native desktop app): macOS 13.0 (Ventura) or newer
  • Xcode / Swift: Swift 5.0+ / Swift 6.0 compatible toolchain (xcode-select --install or Xcode from App Store)

Clone & Install

git clone https://github.com/jeffloo886/jev-notion.git
cd jev-notion
npm install

Project Architecture

jev-notion consists of two deeply coordinated layers:

jev-notion/
├── src/                  # TypeScript Core & Engine
│   ├── cli.ts            # Command-line interface (scan, apply, watch, login, etc.)
│   ├── engine.ts         # Central poll & synchronization orchestrator
│   ├── decide.ts         # Jev inference & confidence decision model
│   ├── scan.ts           # Read-only database scanning & suggestion engine
│   ├── apply.ts          # Approved changes writer with schema safety
│   ├── calibration.ts   # Property rubric calibration
│   ├── oauth.ts          # Local HTTP server OAuth PKCE login flow
│   └── notion/           # Notion API schema, evidence gathering, and writes
├── app/                  # Native macOS Desktop Client (SwiftUI)
│   ├── Sources/JevNotion/
│   │   ├── main.swift         # Entry point & CLI launcher
│   │   ├── AppDelegate.swift  # Menu bar status item & window manager
│   │   ├── NotionTheme.swift  # Notion 9-color palette & custom UI components
│   │   ├── Localization.swift # 8-language dynamic localization manager (L10n)
│   │   ├── ScanView.swift     # Main inspection & review split-view
│   │   ├── SettingsView.swift # Keychain credentials & settings modal
│   │   └── ScanSession.swift  # Subprocess bridge to engine.mjs
│   └── build.sh          # Self-contained zero-churn release bundle assembler
└── tests/                # Vitest automated test suites (260+ tests)

Building & Testing

Node.js / TypeScript Core

  1. Type Checking: 
    npm run typecheck
  2. Run Unit Tests: 
    npm test
    Or run tests in watch mode: 
    npm run test:watch
  3. Compile Library: 
    npm run build
  4. Bundle Standalone Node Engine (for the macOS app): 
    npm run bundle

Native macOS App (SwiftUI)

The macOS app is compiled and packaged directly using Swift Package Manager and app/build.sh (avoiding Xcode project file churn):

# Compile and build JevNotion.app in dist/
./app/build.sh

# Open the app
open dist/JevNotion.app

Translations (Localization)

We support 8 languages:

  1. 🇨🇳 简体中文 (zh-Hans)
  2. 🇺🇸 English (en)
  3. 🇭🇰 繁體中文 (zh-Hant)
  4. 🇯🇵 日本語 (ja)
  5. 🇰🇷 한국어 (ko)
  6. 🇫🇷 Français (fr)
  7. 🇩🇪 Deutsch (de)
  8. 🇪🇸 Español (es)

To add or improve translations:

  1. Open app/Sources/JevNotion/Localization.swift.
  2. Add or refine keys in the L10nKey enum and the strings dictionary.
  3. Test the language in the app by selecting it from the top toolbar 🌐 menu or the Settings grid.

Pull Request Guidelines

  1. Keep Changes Focused: One PR should address one bug, feature, or translation improvement.
  2. Ensure Tests Pass:
    • npm run typecheck must pass without errors.
    • npm test must be 100% green.
    • ./app/build.sh must build cleanly.
  3. Add Tests: When fixing a bug or adding an engine feature, include test cases under tests/.
  4. Documentation: Update README.md and README.zh-CN.md if user-facing behavior changes.

Security & Credentials

  • NEVER commit real API keys, tokens, .env files, or production database IDs.
  • Secrets must be loaded through environment variables or the macOS Keychain.
  • See SECURITY.md for vulnerability reporting.