Skip to content

AGENTS.md

Latest commit

 

History

History
90 lines (71 loc) · 8.73 KB

AGENTS.md

File metadata and controls

90 lines (71 loc) · 8.73 KB
Raw

AGENTS.md

This handbook briefs AI coding assistants on the vChewing (唯音) macOS repository. Use only English or zh-Hant-TW for docs/comments/reviews; zh-Hans is allowed only in filename stems ending with -CHS.

1. Project Snapshot

  • Purpose: Native Zhuyin / Bopomofo input method for macOS with optional phonetic and stroke keyboards, simplified ↔ traditional isolation, and sandboxed distribution installers.
  • Implementation: Pure Swift modules layered on AppKit/IMK. C(++)/ObjC(++) bridges exist only where Swift cannot interface directly with legacy assets.
  • Primary packages:
    • vChewing_MainAssembly4Darwin: IMK front-end (SessionCtl, InputSession, UI bridges, sandbox glue).
    • vChewing_Typewriter: Typing FSM, session core protocol (SessionCoreProtocol), Tekkon integration, user preference wiring, cassette/stroke handling.
    • vChewing_Homa: DAG-DP assembler (sentence assembler) with candidate override, consolidation, revolver, and perception hooks.
    • vChewing_Tekkon: Keyboard parsers, Zhuyin/Bopomofo composer, stroke cassette parser, phonabet utilities.
    • vChewing_LangModelAssembly: LM instantiation facade, user phrase memory, perception override, associated phrases.
    • Shared dependencies (vChewing_Shared, vChewing_SwiftExtension, vChewing_OSFrameworkImpl, etc.) supply utilities, result-builder UI DSL, notifications, and AppKit wrappers.
  • Lexicon assets: Provided by remote Swift Package plugin VanguardTextMapPlugin (from vChewing-VanguardLexicon repository). Compiled factory lexicons (.txtMap + .revlookup pairs) are injected into vChewing_MainAssembly4Darwin during build-time. The runtime backend is VanguardTrie.TextMapTrie (sorted-array key index with binary search, on-demand VALUES parsing, bounded parsed-entry cache).

2. Environment & Build Paths

  • Authoritative toolchain: macOS 14.7+ (Sonoma recommended), Xcode 15.3+ with bundled Swift 5.10 or newer.
  • Runtime target: macOS 12 Monterey and newer. Older macOS support lives in another repo.
  • Build system: Swift Package Manager (SwiftPM) 6.2.4+ via Package.swift root manifest. App bundle assembly and universal binary scripting via Makefile with BundleApps CommandPlugin.
  • CLI builds:
    • Universal binary release: make release (builds arm64 + x86_64, creates signed .app bundles in Build/Products/Release/).
    • Archive with dSYMs: make archive (creates .xcarchive in Xcode Archives folder).
    • Debug native build: make debug (single-arch, target output in .build/debug/).
    • Package-only tests: cd Packages/vChewing_Typewriter && swift build && swift test.
  • First-time setup: make update (fetches/generates lexicons) then make release. Ensure Xcode DerivedData location is set to "Relative to Workspace" to satisfy make recipes.

3. Repository Layout (quick map)

  • Packages/vChewing_MainAssembly4Darwin/.../SessionController/SessionCtl.swift: IMK entry point. All NSEvent handling funnels through InputSession* files.
  • Packages/vChewing_Typewriter/Sources/Typewriter/InputHandler/: FSM split across triage, composition, candidate handling, and commissions.
  • Packages/vChewing_Typewriter/Sources/Typewriter/Session/: SessionCoreProtocol — shared session base protocol with switchState()/resetInputHandler() default implementations.
  • Packages/vChewing_Homa/Sources/Homa/: Assembler core (Homa_Assembler.swift, Homa_PathFinder.swift, candidate/consolidation APIs, etc.).
  • Packages/vChewing_Tekkon/Sources/Tekkon/: Keyboard parsers, composer, Zhuyin constants.
  • Packages/vChewing_LangModelAssembly/Sources/LangModelAssembly/: LM instantiators, perception override, associated phrase derivation.
  • Packages/vChewing_OSFrameworkImpl/: AppKit result-builder DSL for SettingsCocoa window, etc.
  • Packages/vChewing_CandidateWindow/: The Candidate window.
  • Plugins/BundleApps/: CommandPlugin that assembles .app bundles and optional .xcarchive archives (codesigning, entitlements, SPM bundle filtering).
  • Makefile: Root-level automation for universal binary builds (swift build --arch arm64/x86_64, lipo merge), lexicon toolchain integration, and CommandPlugin invocation.
  • Installer/: SwiftUI installer app + pkg resources.

4. Runtime Flow & Key Concepts

  1. Event capture: IMK SessionCtl receives NSEvents and marshals them into KBEvent structures.
  2. FSM triage: InputHandler in Typewriter interprets events, orchestrates Tekkon composer, updates the Homa assembler, and switches IMEState instances.
  3. Composer: Tekkon manages Zhuyin/phonetic/stroke buffers, auto-correction, cassette mode, and exposes inline display strings.
  4. Assembler: Homa Assembler builds DAG segments, snapshots perception intelligences, exposes candidate / consolidation / revolver APIs, and emits assembledSentence for UI rendering.
  5. Language Models: LMAssembly merges factory lexicons (via FactoryTextMapLexicon backed by Vanguard TextMap format), user phrases, exclusion lists, associated phrase suggestions, and perception override data, etc.
  6. UI update: SessionCtl refreshes candidate window, composition buffer, tooltips, notifications, symbol menu.

Reference algorithm.md for the deep algorithm write-up (zh-Hant).

5. Development Guardrails

  • Language: Code comments, docs, and commit messages in English or zh-Hant. (zh-Hans only in files if filenamestem ends with -CHS.)
  • UI: AppKit only. No Interface Builder nibs/storyboards. Keep UI work on the main actor. Most AppKit Window views are implemented using AppKit Result Builder DSL.
  • Preferences: Extend UserDef, PrefMgrProtocol, and PrefMgr together. Avoid naked UserDefaults.standard access except in constrained scenarios.
  • User data paths: Avoid hard-coded user data paths except where necessary in package test targets.
  • State machine: Prefer new IMEState enum cases and explicit transition APIs over boolean shortcuts. SessionCoreProtocol (Typewriter) provides switchState()/resetInputHandler() default implementations shared by mock tests and production; extend InputHandlerProtocol for per-event triage logic.
  • Conditional APIs: Guard platform-specific code (#if canImport(Darwin)) as needed; keep Linux compatibility in Typewriter package and its local dependencies.
  • Bundle resources: SPM #bundle macro expands to Bundle.module from the auto-generated accessor. For packages with runtime resource lookup (e.g., LangModelAssembly), use custom Bundle.currentSPM accessor that checks resourceURL first, then falls back to bundleURL. This avoids codesign sand­box violations from files at .app/ root.
  • ObjC(++)/C(+=) style: Follow Google Style Guide formatting for Objective-C(++) and C(++).
  • Licensing: Preserve MIT-NTL banners. Respect LGPL for Homa, Megrez legacy sources (if exists), and Tekkon; avoid mixing incompatible license assets.
  • Lexicon tooling: Factory lexicons are compiled by remote VanguardTextMapPlugin (Swift Package plugin from vChewing-VanguardLexicon repository) and injected into vChewing_MainAssembly4Darwin at build-time via SPM build plugins. The runtime backend is VanguardTrie.TextMapTrie (sorted-array key index with binary search, on-demand VALUES parsing, bounded parsed-entry cache). Do not modify or commit generated lexicon assets; they are transient build artifacts.

6. Testing Expectations

  • Unit tests live alongside each Swift package (swift test). Focus on deterministic cases that mirror reported issues.
  • Typewriter and MainAssembly packages host end-to-end style tests; consider snapshotting PrefMgr state before/after.
  • When touching Tekkon or Homa, craft stress tests covering multi-syllable input, perception overrides, cursor edge cases.
  • Use swift test --filter to run targeted suites when debugging CI regressions.

7. Contribution Workflow

  • Commit format: ModuleName // SubModuleName: Change. (Conventional Commit semantics kept terse.) Example: Typewriter // FSM: Fix cursor guard.
  • Reviews: Highlight functional impact, state machine ramifications, and test coverage. Mention regression risk if tests are missing.
  • Dependencies: Prefer SwiftPM-targeted adjustments. When external patches are unavoidable, document rationale in code comments and PR description.
  • Installer: Keep pkg scripts idempotent. pkgPreInstall.sh / pkgPostInstall.sh must remain sandbox safe.

8. Quick Reference Checklist

  • Honor language restrictions in new text.
  • Update .strings when adding user-visible strings.
  • Gate new APIs through protocols as needed.
  • Run relevant swift test targets.
  • Align new keyboard layouts with Tekkon parsers and symbol tables.

Questions from contributors should reference this file first; escalate only when guidance is missing or conflicting.