Redmineの設定

🎯 概要¶

インフラヘルパーサービスの型安全性を向上させ、開発効率と品質を改善する。JSDocによる型定義の追加とTypeScript導入の検討を行う。

📋 実装内容¶

1. JSDoc型定義の追加

utils/compatibility.js¶

/**
 * @typedef {Object} MemoryInfo
 * @property {string} total - Total memory in human-readable format
 * @property {string} used - Used memory in human-readable format
 * @property {string} free - Free memory in human-readable format
 * @property {string} available - Available memory in human-readable format
 * @property {string} buffers - Buffer memory in human-readable format
 * @property {string} cached - Cached memory in human-readable format
 * @property {string} percentage - Memory usage percentage
 */

/**
 * @typedef {Object} SystemStatus
 * @property {number} containers - Number of running containers
 * @property {number} totalContainers - Total number of containers
 * @property {number} domains - Number of Nginx domains
 * @property {string} uptime - System uptime
 * @property {string} memory - Memory usage (used/total)
 * @property {string} memoryPercentage - Memory usage percentage
 * @property {string} lastCheck - ISO timestamp of last check
 * @property {string} status - System status
 * @property {string} user - Username who requested the status
 */

/**
 * Check if running in BusyBox environment
 * @returns {Promise<boolean>} True if BusyBox environment
 */
async function isBusyBoxEnvironment() {
    // 実装
}

/**
 * Get system uptime in human-readable format
 * @returns {Promise<string>} Uptime string (e.g., "up 2 days, 3 hours")
 * @throws {Error} If unable to determine uptime
 */
async function getSystemUptime() {
    // 実装
}

/**
 * Get memory information
 * @returns {Promise<MemoryInfo>} Memory usage information
 * @throws {Error} If unable to read memory info
 */
async function getMemoryInfo() {
    // 実装
}

2. API レスポンス型定義

types/api.js¶

/**
 * @typedef {Object} ApiResponse
 * @property {boolean} success - Whether the request was successful
 * @property {*} [data] - Response data (optional)
 * @property {string} [error] - Error message (optional)
 * @property {string} [message] - Success message (optional)
 */

/**
 * @typedef {Object} AuthResponse
 * @property {boolean} success
 * @property {string} token - JWT token
 * @property {UserInfo} user - User information
 */

/**
 * @typedef {Object} UserInfo
 * @property {number} id - User ID
 * @property {string} login - Username
 * @property {boolean} admin - Admin status
 * @property {string} email - Email address
 * @property {string} [firstname] - First name
 * @property {string} [lastname] - Last name
 */

/**
 * @typedef {Object} ContainerInfo
 * @property {string} name - Container name
 * @property {string} image - Image name
 * @property {string} status - Container status
 * @property {string} state - Container state
 * @property {number} created - Creation timestamp
 * @property {Array<PortInfo>} ports - Port mappings
 */

/**
 * @typedef {Object} PortInfo
 * @property {number} [PrivatePort] - Container port
 * @property {number} [PublicPort] - Host port
 * @property {string} [Type] - Protocol type
 */

3. エラー型定義

types/errors.js¶

/**
 * @typedef {Object} ApiError
 * @property {string} code - Error code
 * @property {string} message - Error message
 * @property {number} statusCode - HTTP status code
 * @property {Object} [details] - Additional error details
 */

class InfraHelperError extends Error {
    /**
     * @param {string} message
     * @param {string} code
     * @param {number} statusCode
     * @param {Object} [details]
     */
    constructor(message, code, statusCode = 500, details = null) {
        super(message);
        this.name = 'InfraHelperError';
        this.code = code;
        this.statusCode = statusCode;
        this.details = details;
    }
}

class AuthenticationError extends InfraHelperError {
    constructor(message = 'Authentication failed') {
        super(message, 'AUTH_ERROR', 401);
    }
}

class ValidationError extends InfraHelperError {
    constructor(message, details) {
        super(message, 'VALIDATION_ERROR', 400, details);
    }
}

4. VS Code設定

.vscode/settings.json¶

{
    "javascript.implicitProjectConfig.checkJs": true,
    "javascript.suggest.completeFunctionCalls": true,
    "editor.quickSuggestions": {
        "strings": true
    }
}

jsconfig.json¶

{
    "compilerOptions": {
        "module": "commonjs",
        "target": "es2020",
        "checkJs": true,
        "allowJs": true,
        "lib": ["es2020"],
        "strict": true,
        "esModuleInterop": true,
        "skipLibCheck": true,
        "forceConsistentCasingInFileNames": true
    },
    "include": [
        "backend/**/*"
    ],
    "exclude": [
        "node_modules",
        "dist"
    ]
}

5. TypeScript導入準備（将来的な移行）

tsconfig.json (案)¶

{
    "compilerOptions": {
        "target": "ES2020",
        "module": "commonjs",
        "lib": ["ES2020"],
        "allowJs": true,
        "checkJs": false,
        "outDir": "./dist",
        "rootDir": "./src",
        "strict": true,
        "esModuleInterop": true,
        "skipLibCheck": true,
        "forceConsistentCasingInFileNames": true,
        "resolveJsonModule": true,
        "declaration": true,
        "declarationMap": true,
        "sourceMap": true
    },
    "include": ["src/**/*"],
    "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

📊 期待される効果¶

1. 開発効率の向上

   • IDEの自動補完機能の活用
   • 型エラーの早期発見
   • リファクタリングの安全性向上

2. コード品質の向上

   • 型の不一致によるバグの削減
   • APIドキュメントの自動生成
   • コードの可読性向上

3. メンテナンス性の向上

   • 新規開発者の学習曲線の緩和
   • APIの仕様変更時の影響範囲の明確化

🔧 実装計画¶

1. JSDoc型定義の追加（2日）
2. VS Code設定の追加（0.5日）
3. 既存コードへの型注釈追加（2日）
4. 型チェックエラーの修正（1日）
5. ドキュメント生成設定（0.5日）

✅ 完了条件¶

• すべての公開関数にJSDoc型定義を追加
• VS Codeでの型チェックが有効化
• 型エラーが0件
• APIドキュメントの自動生成が可能