qenv/.serena/memories/code_style_conventions.md

Code Style and Conventions

TypeScript Conventions

• Use TypeScript with ES modules (type: "module" in package.json)
• All files use .js extensions in imports (even for .ts files)
• Interfaces prefixed with I (e.g., IUserData)
• Types prefixed with T (e.g., TEnvVarRef)
• Filenames must be lowercase
• Avoid ENUMs when possible

File Organization

• Source code in ts/ directory
• Tests in test/ directory
• Plugin imports in ts/qenv.plugins.ts
• Main exports in ts/index.ts
• Class files named as qenv.classes.<classname>.ts

Import Style

• Import all dependencies in plugins file
• Reference as plugins.moduleName.method()
• Use full import paths with .js extension
• Group imports: external packages, then internal modules

Testing

• Use @git.zone/tstest framework
• Import expect from tapbundle: import { tap, expect } from '@git.zone/tstest/tapbundle'
• Test files end with export default tap.start() (tstest pattern)
• Test file naming: *.both.ts, *.node.ts, or *.browser.ts

Documentation

• Keep comments minimal unless specifically requested
• README should be lowercase: readme.md
• Documentation should be engaging and use emojis where appropriate

Git Conventions

• Small, focused commits
• Use git mv for file operations
• Never commit without running tests and type checks