kenaz 0.3.18 → 0.3.19

package/core/dev/scripts/matrix/src/cli/commands/validate.ts

@@ -1,275 +0,0 @@
-/**
- * Validate command - 驗證 .matrix 文件語法並提供修復建議
- */
-
-import * as fs from 'fs';
-import { MatrixValidator } from '../../validator';
-import { MatrixParser } from '../../parser';
-import { MatrixSerializer } from '../../serializer';
-import { log, error as logError, success } from '../utils/logger';
-import type { ParseError } from '../../../types';
-
-interface ValidateOptions {
-  fix?: boolean;
-}
-
-/**
- * Validate command handler
- */
-export async function validateCommand(file: string, options: ValidateOptions): Promise<void> {
-  try {
-    // 確保文件有 .matrix 擴展名
-    const filePath = file.endsWith('.matrix') ? file : `${file}.matrix`;
-
-    // 檢查文件是否存在
-    if (!fs.existsSync(filePath)) {
-      throw new Error(`File not found: ${filePath}`);
-    }
-
-    // 讀取文件
-    const content = fs.readFileSync(filePath, 'utf-8');
-
-    // 執行驗證
-    const validator = new MatrixValidator();
-    const result = validator.validate(content);
-
-    // 顯示結果
-    displayValidationResults(result.errors, result.warnings, filePath);
-
-    // 如果有錯誤，提供修復建議
-    if (!result.valid && result.errors.length > 0) {
-      log('\n💡 Fix Suggestions:\n');
-      provideFixSuggestions(result.errors, content, filePath);
-
-      // 如果啟用了 --fix 選項，嘗試自動修復
-      if (options.fix) {
-        log('\n🔧 Attempting auto-fix...\n');
-        const fixed = attemptAutoFix(content, result.errors, filePath);
-        if (fixed) {
-          success(`✅ File fixed successfully: ${filePath}`);
-        } else {
-          logError('⚠️  Some errors could not be auto-fixed. Please fix manually.');
-        }
-      }
-    } else if (result.warnings.length > 0) {
-      log('\n⚠️  File is valid but has warnings. Consider addressing them.\n');
-    } else {
-      success(`\n✅ File is valid: ${filePath}\n`);
-    }
-
-  } catch (err) {
-    logError((err as Error).message);
-    throw err;
-  }
-}
-
-/**
- * 顯示驗證結果
- */
-function displayValidationResults(errors: ParseError[], warnings: ParseError[], filePath: string): void {
-  log(`\n📋 Validation Report for: ${filePath}\n`);
-  log('─'.repeat(80));
-
-  // 顯示錯誤
-  if (errors.length > 0) {
-    log(`\n❌ Errors (${errors.length}):\n`);
-    for (const error of errors) {
-      const location = error.line ? ` at line ${error.line}` : '';
-      log(`  [${error.code}] ${error.message}${location}`);
-      if (error.expected) {
-        log(`      Expected: ${error.expected}`);
-      }
-      if (error.got) {
-        log(`      Got: ${error.got}`);
-      }
-    }
-  }
-
-  // 顯示警告
-  if (warnings.length > 0) {
-    log(`\n⚠️  Warnings (${warnings.length}):\n`);
-    for (const warning of warnings) {
-      const location = warning.line ? ` at line ${warning.line}` : '';
-      log(`  [${warning.code}] ${warning.message}${location}`);
-    }
-  }
-
-  log('\n' + '─'.repeat(80));
-}
-
-/**
- * 提供修復建議
- */
-function provideFixSuggestions(errors: ParseError[], content: string, filePath: string): void {
-  const lines = content.split(/\r?\n/);
-  const suggestions: string[] = [];
-
-  for (const error of errors) {
-    const suggestion = getSuggestionForError(error, lines);
-    if (suggestion && !suggestions.includes(suggestion)) {
-      suggestions.push(suggestion);
-    }
-  }
-
-  for (let i = 0; i < suggestions.length; i++) {
-    log(`  ${i + 1}. ${suggestions[i]}`);
-  }
-
-  log('');
-}
-
-/**
- * 根據錯誤代碼生成具體的修復建議
- */
-function getSuggestionForError(error: ParseError, lines: string[]): string {
-  switch (error.code) {
-    case 'E000':
-      return '文件為空。請添加至少包含 @meta 和 @index 的內容。\n     範例：\n     # .matrix v1.0\n     @meta |v=1.0|c=T|\n     @index |tot=0|';
-
-    case 'E001':
-      if (error.message.includes('@meta')) {
-        return '缺少 @meta 層。請在文件開頭加入：\n     @meta |v=1.0|c=T|  (v=版本號, c=分類)';
-      }
-      if (error.message.includes('@index')) {
-        return '缺少 @index 層。請在 @meta 之後加入：\n     @index |tot=0|  (tot=總數)';
-      }
-      return '缺少必要的層級。請確保文件包含 @meta 和 @index。';
-
-    case 'E002':
-      if (error.message.includes('Duplicate')) {
-        return `刪除重複的 ${error.message.includes('@meta') ? '@meta' : '@index'} 層，每個文件只能有一個。`;
-      }
-      if (error.message.includes('order')) {
-        return '調整層級順序：@meta 必須在最前面，接著是 @index，最後是 @data（可選）。';
-      }
-      return '檢查層級順序和重複性。';
-
-    case 'E003':
-      if (error.line && lines[error.line - 1]) {
-        const line = lines[error.line - 1].trim();
-        return `第 ${error.line} 行格式錯誤。正確格式應為：\n     ${error.expected || '|field=value|...|}'}`;
-      }
-      return '檢查分隔符 | 是否正確。每行應以 | 開始和結束。';
-
-    case 'E004':
-      return '欄位格式錯誤。每個欄位應為 key=value 格式，使用 | 分隔。\n     範例：|field1=value1|field2=value2|';
-
-    case 'E005':
-      if (error.message.includes('v')) {
-        return '@meta 必須包含 v (version) 欄位。請加入：v=1.0';
-      }
-      if (error.message.includes('c')) {
-        return '@meta 必須包含 c (category) 欄位。請加入：c=T (T/M/R/P 或自訂)';
-      }
-      return '@meta 必須包含 v (version) 和 c (category) 欄位。';
-
-    case 'E006':
-      return '時間戳格式錯誤。應使用 YYMMDD-HHMM 格式，例如：260207-1430';
-
-    case 'E007':
-      return '偵測到重複的記錄 ID。每個記錄的 ID 必須唯一。請檢查 @data 層的 ID。';
-
-    case 'E008':
-      return '未知的欄位鍵名。請確認欄位名稱是否正確或是否為自訂欄位。';
-
-    case 'E009':
-      return '值類型錯誤。請檢查欄位值是否符合預期類型（數字、布林、字串等）。';
-
-    case 'E010':
-      return '版本號格式錯誤。應使用語意化版本號，例如：1.0.0 或 2.1.3';
-
-    default:
-      return `錯誤代碼 ${error.code}: ${error.message}`;
-  }
-}
-
-/**
- * 嘗試自動修復常見錯誤
- */
-function attemptAutoFix(content: string, errors: ParseError[], filePath: string): boolean {
-  let fixedContent = content;
-  let hasChanges = false;
-
-  // 修復 E000: 空文件
-  if (errors.some(e => e.code === 'E000')) {
-    fixedContent = `# .matrix v1.0\n@meta |v=1.0|c=T|\n@index |tot=0|\n@data\n`;
-    hasChanges = true;
-  }
-
-  // 修復 E001: 缺少 @meta
-  if (errors.some(e => e.code === 'E001' && e.message.includes('@meta'))) {
-    const lines = fixedContent.split(/\r?\n/);
-    // 在第一個非註釋行之前插入 @meta
-    let insertIndex = 0;
-    while (insertIndex < lines.length && lines[insertIndex].trim().startsWith('#')) {
-      insertIndex++;
-    }
-    lines.splice(insertIndex, 0, '@meta |v=1.0|c=T|');
-    fixedContent = lines.join('\n');
-    hasChanges = true;
-  }
-
-  // 修復 E001: 缺少 @index
-  if (errors.some(e => e.code === 'E001' && e.message.includes('@index'))) {
-    const lines = fixedContent.split(/\r?\n/);
-    // 在 @meta 之後插入 @index
-    const metaIndex = lines.findIndex(l => l.trim().startsWith('@meta'));
-    if (metaIndex >= 0) {
-      lines.splice(metaIndex + 1, 0, '@index |tot=0|');
-      fixedContent = lines.join('\n');
-      hasChanges = true;
-    }
-  }
-
-  // 修復 E003: 分隔符錯誤（簡單情況）
-  const delimiterErrors = errors.filter(e => e.code === 'E003');
-  if (delimiterErrors.length > 0) {
-    const lines = fixedContent.split(/\r?\n/);
-    for (const error of delimiterErrors) {
-      if (error.line && error.line <= lines.length) {
-        const lineIndex = error.line - 1;
-        let line = lines[lineIndex].trim();
-
-        // 如果缺少開頭或結尾的 |
-        if (line.startsWith('@meta') || line.startsWith('@index')) {
-          const match = line.match(/^(@\w+)\s+(.+)$/);
-          if (match) {
-            const section = match[1];
-            let content = match[2];
-            if (!content.startsWith('|')) content = '|' + content;
-            if (!content.endsWith('|')) content = content + '|';
-            lines[lineIndex] = `${section} ${content}`;
-            hasChanges = true;
-          }
-        }
-      }
-    }
-    fixedContent = lines.join('\n');
-  }
-
-  // 如果有修改，保存文件
-  if (hasChanges) {
-    // 備份原文件
-    const backupPath = `${filePath}.backup`;
-    fs.writeFileSync(backupPath, content, 'utf-8');
-    log(`  📦 Original file backed up to: ${backupPath}`);
-
-    // 寫入修復後的內容
-    fs.writeFileSync(filePath, fixedContent, 'utf-8');
-    log(`  ✅ Fixed ${errors.length} error(s)`);
-
-    // 重新驗證
-    const validator = new MatrixValidator();
-    const revalidateResult = validator.validate(fixedContent);
-
-    if (revalidateResult.valid) {
-      log(`  ✅ File is now valid!`);
-      return true;
-    } else {
-      log(`  ⚠️  Some errors remain (${revalidateResult.errors.length}). Manual fix may be required.`);
-      return false;
-    }
-  }
-
-  return false;
-}

package/core/dev/scripts/matrix/src/cli/index.ts

@@ -1,350 +0,0 @@
-#!/usr/bin/env node
-/**
- * matrix CLI - Command line tool for .matrix file operations
- * @version 1.0.0
- */
-
-import { Command } from 'commander';
-import { createCommand } from './commands/create';
-import { readCommand } from './commands/read';
-import { updateCommand } from './commands/update';
-import { deleteCommand } from './commands/delete';
-import { queryCommand } from './commands/query';
-import { convertCommand } from './commands/convert';
-import { validateCommand } from './commands/validate';
-// TODO: Import new commands after fixing parser adaptation
-// import { statsCommand } from './commands/stats';
-// import { tokensCommand } from './commands/tokens';
-// import { listTagsCommand } from './commands/list-tags';
-// import { addTagCommand, removeTagCommand, showRuleTagsCommand } from './commands/manage-tags';
-
-const program = new Command();
-
-program
-  .name('matrix')
-  .description('CLI tool for managing .matrix format files')
-  .version('1.1.0');
-
-// CREATE command
-program
-  .command('create <file>')
-  .description('Create a new .matrix file')
-  .option('-v, --version <version>', 'Version number (e.g., 1.0.0)')
-  .option('-c, --category <category>', 'Category (T/M/R/P or custom)')
-  .option('-i, --interactive', 'Use interactive mode', false)
-  .action(async (file, options) => {
-    try {
-      await createCommand(file, options);
-    } catch (error) {
-      console.error('Error:', (error as Error).message);
-      process.exit(1);
-    }
-  })
-  .addHelpText(
-    'after',
-    `
-Examples:
-  $ matrix create tasks.matrix -v 1.0.0 -c T
-  $ matrix create memory -i
-  $ matrix create project_status --version 2.0.0 --category P
-  `
-  );
-
-// READ command
-program
-  .command('read <file>')
-  .description('Read and display .matrix file content')
-  .option('-l, --level <level>', 'Display level (1=overview, 2=recent 10, 3=all)', '3')
-  .action((file, options) => {
-    try {
-      const level = parseInt(options.level, 10);
-      if (isNaN(level) || level < 1 || level > 3) {
-        console.error('Error: Level must be 1, 2, or 3');
-        process.exit(1);
-      }
-      readCommand(file, { level });
-    } catch (error) {
-      console.error('Error:', (error as Error).message);
-      process.exit(1);
-    }
-  })
-  .addHelpText(
-    'after',
-    `
-Examples:
-  $ matrix read tasks.matrix
-  $ matrix read tasks.matrix --level 1
-  $ matrix read memory.matrix -l 2
-  `
-  );
-
-// UPDATE command
-program
-  .command('update <file> <rule-id>')
-  .description('Update a specific rule in .matrix file')
-  .option('-f, --field <field>', 'Field name to update')
-  .option('-v, --value <value>', 'New value for the field')
-  .option('-i, --interactive', 'Use interactive mode', false)
-  .action(async (file, ruleId, options) => {
-    try {
-      await updateCommand(file, ruleId, options);
-    } catch (error) {
-      console.error('Error:', (error as Error).message);
-      process.exit(1);
-    }
-  })
-  .addHelpText(
-    'after',
-    `
-Examples:
-  $ matrix update tasks.matrix TASK_001 -f status -v completed
-  $ matrix update tasks.matrix TASK_002 -i
-  $ matrix update memory.matrix MEM_005 --field priority --value high
-  `
-  );
-
-// DELETE command
-program
-  .command('delete <file> <rule-id>')
-  .description('Delete a rule from .matrix file')
-  .option('-f, --force', 'Skip confirmation prompt', false)
-  .action(async (file, ruleId, options) => {
-    try {
-      await deleteCommand(file, ruleId, options);
-    } catch (error) {
-      console.error('Error:', (error as Error).message);
-      process.exit(1);
-    }
-  })
-  .addHelpText(
-    'after',
-    `
-Examples:
-  $ matrix delete tasks.matrix TASK_001
-  $ matrix delete tasks.matrix TASK_002 -f
-  $ matrix delete memory.matrix MEM_OLD --force
-  `
-  );
-
-// QUERY command
-program
-  .command('query <file>')
-  .description('Query .matrix file with filters')
-  .option('-t, --tag <tag>', 'Filter by tag')
-  .option('-p, --priority <priority>', 'Filter by priority (P0/P1/P2/P3)')
-  .option('-s, --status <status>', 'Filter by status (pending/in_progress/completed/blocked)')
-  .option('-k, --keyword <keyword>', 'Search by keyword (in all fields)')
-  .option('-f, --format <format>', 'Output format (table/json/compact)', 'table')
-  .action(async (file, options) => {
-    try {
-      await queryCommand(file, options);
-    } catch (error) {
-      console.error('Error:', (error as Error).message);
-      process.exit(1);
-    }
-  })
-  .addHelpText(
-    'after',
-    `
-Examples:
-  $ matrix query tasks.matrix --status pending
-  $ matrix query tasks.matrix -s completed -p P0
-  $ matrix query tasks.matrix --tag feature --format json
-  $ matrix query tasks.matrix -k "authentication" -f compact
-  `
-  );
-
-// CONVERT command
-program
-  .command('convert <input> <output>')
-  .description('Convert between .matrix and JSON formats')
-  .option('--from <format>', 'Input format (json/matrix, auto-detected if not specified)')
-  .option('--to <format>', 'Output format (json/matrix, auto-detected if not specified)')
-  .action(async (input, output, options) => {
-    try {
-      await convertCommand(input, output, options);
-    } catch (error) {
-      console.error('Error:', (error as Error).message);
-      process.exit(1);
-    }
-  })
-  .addHelpText(
-    'after',
-    `
-Examples:
-  $ matrix convert tasks.matrix tasks.json
-  $ matrix convert tasks.json tasks.matrix
-  $ matrix convert input.matrix output.json --from matrix --to json
-  `
-  );
-
-// VALIDATE command
-program
-  .command('validate <file>')
-  .description('Validate .matrix file syntax and provide fix suggestions')
-  .option('--fix', 'Attempt to auto-fix simple errors', false)
-  .action(async (file, options) => {
-    try {
-      await validateCommand(file, options);
-    } catch (error) {
-      console.error('Error:', (error as Error).message);
-      process.exit(1);
-    }
-  })
-  .addHelpText(
-    'after',
-    `
-Examples:
-  $ matrix validate tasks.matrix
-  $ matrix validate tasks.matrix --fix
-  $ matrix validate memory.matrix
-  `
-  );
-
-// TODO: New commands (WIP - parser adaptation needed)
-/*
-// STATS command
-program
-  .command('stats <file>')
-  .description('Display statistics about .matrix file')
-  .option('-v, --verbose', 'Show detailed statistics', false)
-  .action(async (file, options) => {
-    try {
-      await statsCommand(file, options);
-    } catch (error) {
-      console.error('Error:', (error as Error).message);
-      process.exit(1);
-    }
-  })
-  .addHelpText(
-    'after',
-    `
-Examples:
-  $ matrix stats tasks.matrix
-  $ matrix stats tasks.matrix --verbose
-  $ matrix stats .rule/INDEX.matrix -v
-  `
-  );
-
-// TOKENS command
-program
-  .command('tokens <file>')
-  .description('Calculate token count and compression ratio')
-  .option('-v, --verbose', 'Show detailed token analysis', false)
-  .action(async (file, options) => {
-    try {
-      await tokensCommand(file, options);
-    } catch (error) {
-      console.error('Error:', (error as Error).message);
-      process.exit(1);
-    }
-  })
-  .addHelpText(
-    'after',
-    `
-Examples:
-  $ matrix tokens tasks.matrix
-  $ matrix tokens tasks.matrix --verbose
-  $ matrix tokens .rule/INDEX.matrix
-  `
-  );
-
-// LIST-TAGS command
-program
-  .command('list-tags <file>')
-  .description('List all tags and their usage counts')
-  .option('-t, --type <type>', 'Filter by tag type (source/category/priority/domain/custom)')
-  .option('-s, --sort <sort>', 'Sort by name or count (default: count)', 'count')
-  .action(async (file, options) => {
-    try {
-      await listTagsCommand(file, options);
-    } catch (error) {
-      console.error('Error:', (error as Error).message);
-      process.exit(1);
-    }
-  })
-  .addHelpText(
-    'after',
-    `
-Examples:
-  $ matrix list-tags tasks.matrix
-  $ matrix list-tags tasks.matrix --type priority
-  $ matrix list-tags tasks.matrix -t custom --sort name
-  `
-  );
-
-// ADD-TAG command
-program
-  .command('add-tag <file> <rule-id> <tag>')
-  .description('Add a tag to a rule')
-  .option('-f, --force', 'Skip confirmation', false)
-  .action(async (file, ruleId, tag, options) => {
-    try {
-      await addTagCommand(file, ruleId, tag, options);
-    } catch (error) {
-      console.error('Error:', (error as Error).message);
-      process.exit(1);
-    }
-  })
-  .addHelpText(
-    'after',
-    `
-Examples:
-  $ matrix add-tag tasks.matrix TASK_001 feature
-  $ matrix add-tag tasks.matrix TASK_002 "#urgent"
-  $ matrix add-tag memory.matrix MEM_005 archived -f
-  `
-  );
-
-// REMOVE-TAG command
-program
-  .command('remove-tag <file> <rule-id> <tag>')
-  .description('Remove a tag from a rule')
-  .option('-f, --force', 'Skip confirmation', false)
-  .action(async (file, ruleId, tag, options) => {
-    try {
-      await removeTagCommand(file, ruleId, tag, options);
-    } catch (error) {
-      console.error('Error:', (error as Error).message);
-      process.exit(1);
-    }
-  })
-  .addHelpText(
-    'after',
-    `
-Examples:
-  $ matrix remove-tag tasks.matrix TASK_001 feature
-  $ matrix remove-tag tasks.matrix TASK_002 "#urgent"
-  $ matrix remove-tag memory.matrix MEM_005 archived -f
-  `
-  );
-
-// SHOW-RULE-TAGS command
-program
-  .command('show-tags <file> <rule-id>')
-  .description('Show all tags for a specific rule')
-  .action(async (file, ruleId) => {
-    try {
-      await showRuleTagsCommand(file, ruleId);
-    } catch (error) {
-      console.error('Error:', (error as Error).message);
-      process.exit(1);
-    }
-  })
-  .addHelpText(
-    'after',
-    `
-Examples:
-  $ matrix show-tags tasks.matrix TASK_001
-  $ matrix show-tags memory.matrix MEM_005
-  `
-  );
-*/
-
-// Parse arguments
-program.parse(process.argv);
-
-// Show help if no command provided
-if (!process.argv.slice(2).length) {
-  program.outputHelp();
-}

package/core/dev/scripts/matrix/src/cli/utils/file-handler.ts

@@ -1,72 +0,0 @@
-/**
- * File Handler Utility
- * Handles file I/O operations with error handling
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { Logger } from './logger';
-
-export class FileHandler {
-  /**
-   * Read .matrix file content
-   * @param filePath Path to .matrix file
-   * @returns File content or null if error
-   */
-  static read(filePath: string): string | null {
-    try {
-      if (!fs.existsSync(filePath)) {
-        Logger.error(`File not found: ${filePath}`);
-        return null;
-      }
-
-      return fs.readFileSync(filePath, 'utf-8');
-    } catch (error) {
-      Logger.error(`Failed to read file: ${(error as Error).message}`);
-      return null;
-    }
-  }
-
-  /**
-   * Write content to .matrix file
-   * @param filePath Path to .matrix file
-   * @param content File content
-   * @returns Success status
-   */
-  static write(filePath: string, content: string): boolean {
-    try {
-      // Ensure directory exists
-      const dir = path.dirname(filePath);
-      if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
-      }
-
-      fs.writeFileSync(filePath, content, 'utf-8');
-      return true;
-    } catch (error) {
-      Logger.error(`Failed to write file: ${(error as Error).message}`);
-      return false;
-    }
-  }
-
-  /**
-   * Check if file exists
-   * @param filePath Path to file
-   * @returns True if exists
-   */
-  static exists(filePath: string): boolean {
-    return fs.existsSync(filePath);
-  }
-
-  /**
-   * Ensure file has .matrix extension
-   * @param filePath Original file path
-   * @returns File path with .matrix extension
-   */
-  static ensureExtension(filePath: string): string {
-    if (!filePath.endsWith('.matrix')) {
-      return `${filePath}.matrix`;
-    }
-    return filePath;
-  }
-}