hana-developer-cli-tool-example: Instructions file for GitHub Copilot

TypeScript Configuration Guidelines

Use this guide when creating or modifying TypeScript configuration files (tsconfig.json) in the project.

Scope and Purpose

This guide applies to TypeScript configuration in:

• Root tsconfig.json - Type generation from JavaScript sources
• mcp-server/tsconfig.json - TypeScript source compilation
• Subdirectory-specific TypeScript configs
• Build-specific TypeScript configs (e.g., tsconfig.build.json)

Critical Principles

1. Dual Config Strategy: Root config for type generation, subproject configs for compilation
2. ESM Compatibility: Use Node16/NodeNext module resolution for ESM projects
3. Strict Mode: Enable strict type checking for maximum safety
4. Declaration Files: Generate .d.ts files for external consumption
5. Source Maps: Enable source maps for debugging compiled code
6. Incremental Builds: Use incremental compilation for faster rebuilds
7. Path Mappings: Configure path aliases for clean imports
8. Type-Only Imports: Use "importsNotUsedAsValues": "error" to enforce type-only imports

Root Configuration Pattern (Type Generation from JS)

Pattern: Generate Types from JavaScript Sources

This project uses JavaScript with JSDoc comments for the main CLI. TypeScript is configured to extract type definitions:

{
  "compilerOptions": {
    // Enable type checking and declaration generation from JS
    "allowJs": true,                    // Process .js files
    "checkJs": true,                    // Type-check .js files
    "declaration": true,                // Generate .d.ts files
    "emitDeclarationOnly": true,        // ONLY generate declarations
    
    // Module system
    "module": "ESNext",                 // Use latest ECMAScript modules
    "moduleResolution": "node",         // Node.js style resolution
    "target": "ES2022",                 // Modern JavaScript features
    
    // Output configuration
    "outDir": "./types",                // Type declarations go here
    "rootDir": ".",                     // Source root
    
    // Type checking strictness
    "strict": false,                    // Lenient for JS sources
    "noImplicitAny": false,             // Allow implicit any in JS
    "strictNullChecks": false,          // No null checks for JS
    
    // Other options
    "esModuleInterop": true,            // CommonJS/ESM interop
    "skipLibCheck": true,               // Skip library type checks
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true           // Import JSON files
  },
  
  "include": [
    "bin/**/*.js",
    "routes/**/*.js",
    "utils/**/*.js",
    "index.js"
  ],
  
  "exclude": [
    "node_modules",
    "tests",
    "coverage",
    "types",
    "**/*.test.js",
    "**/*.Test.js"
  ]
}