kenaz 0.3.18 → 0.3.20

package/core/dev/scripts/matrix/src/serializer.ts

@@ -1,151 +0,0 @@
-/**
- * .matrix 格式序列化器
- * @version 1.0.0
- */
-
-import type { MatrixFile, SerializeOptions } from '../types';
-import { abbreviateField, encodeValue, shortenTimestamp } from './abbreviations';
-
-export class MatrixSerializer {
-  private options: Required<SerializeOptions>;
-
-  constructor(options: SerializeOptions = {}) {
-    this.options = {
-      pretty: options.pretty ?? false,
-      includeComment: options.includeComment ?? true,
-      comment: options.comment ?? '.matrix v1.0',
-    };
-  }
-
-  /**
-   * 序列化 MatrixFile 為 .matrix 格式
-   * @param data MatrixFile 物件
-   * @returns .matrix 文件內容
-   */
-  serialize(data: MatrixFile): string {
-    const lines: string[] = [];
-
-    // 註釋行
-    if (this.options.includeComment) {
-      lines.push(`# ${this.options.comment}`);
-    }
-
-    // @meta 層
-    lines.push(this.serializeMeta(data.meta));
-
-    // @index 層
-    lines.push(this.serializeIndex(data.index));
-
-    // @data 層（如果存在）
-    if (data.data && data.data.records.length > 0) {
-      lines.push('@data');
-      for (const record of data.data.records) {
-        lines.push(this.serializeDataRecord(record));
-      }
-    }
-
-    return lines.join('\n') + '\n';
-  }
-
-  /**
-   * 序列化 @meta 層
-   */
-  private serializeMeta(meta: Record<string, any>): string {
-    const fields: string[] = [];
-
-    for (const [key, value] of Object.entries(meta)) {
-      if (value !== undefined && value !== null) {
-        const abbr = abbreviateField(key);
-        const encoded = this.encodeFieldValue(key, value);
-        fields.push(`${abbr}=${encoded}`);
-      }
-    }
-
-    return `@meta |${fields.join('|')}|`;
-  }
-
-  /**
-   * 序列化 @index 層
-   */
-  private serializeIndex(index: Record<string, any>): string {
-    const fields: string[] = [];
-
-    for (const [key, value] of Object.entries(index)) {
-      if (value !== undefined && value !== null) {
-        const abbr = abbreviateField(key);
-        const encoded = this.encodeFieldValue(key, value);
-        fields.push(`${abbr}=${encoded}`);
-      }
-    }
-
-    return `@index |${fields.join('|')}|`;
-  }
-
-  /**
-   * 序列化 @data 記錄
-   */
-  private serializeDataRecord(record: { id: string; fields: Record<string, any> }): string {
-    const fields: string[] = [];
-
-    for (const [key, value] of Object.entries(record.fields)) {
-      if (value !== undefined && value !== null) {
-        const abbr = abbreviateField(key);
-        const encoded = this.encodeFieldValue(key, value);
-        fields.push(`${abbr}=${encoded}`);
-      }
-    }
-
-    return `${record.id}|${fields.join('|')}|`;
-  }
-
-  /**
-   * 編碼欄位值
-   */
-  private encodeFieldValue(fieldKey: string, value: any): string {
-    // 布林值
-    if (typeof value === 'boolean') {
-      return value ? '1' : '0';
-    }
-
-    // 數字
-    if (typeof value === 'number') {
-      return String(value);
-    }
-
-    // 陣列（列表）
-    if (Array.isArray(value)) {
-      // 任務組（包含子欄位）
-      if (value.length > 0 && typeof value[0] === 'object' && 'id' in value[0]) {
-        return value
-          .map(item => {
-            const { id, ...subFields } = item;
-            const subFieldsStr = Object.entries(subFields)
-              .map(([k, v]) => {
-                const abbr = abbreviateField(k);
-                const encoded = encodeValue(k, v);
-                return `${abbr}=${encoded}`;
-              })
-              .join(',');
-            return `${id},${subFieldsStr}`;
-          })
-          .join(';');
-      }
-      // 一般列表
-      return value.join(',');
-    }
-
-    // 時間戳（ISO 8601 → YYMMDD-HHMM）
-    if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(value)) {
-      return shortenTimestamp(value);
-    }
-
-    // 值代碼化
-    const encoded = encodeValue(fieldKey, value);
-    if (encoded !== String(value)) {
-      return encoded;
-    }
-
-    // 純文本
-    return String(value);
-  }
-}

package/core/dev/scripts/matrix/src/validator.ts

@@ -1,301 +0,0 @@
-/**
- * .matrix 格式驗證器
- * @version 1.0.0
- */
-
-import type { ValidationResult, ParseError } from '../types';
-
-export class MatrixValidator {
-  /**
-   * 驗證 .matrix 文件語法
-   * @param content .matrix 文件內容
-   * @returns 驗證結果
-   */
-  validate(content: string): ValidationResult {
-    const errors: ParseError[] = [];
-    const warnings: ParseError[] = [];
-
-    const lines = content.split(/\r?\n/);
-    let lineNum = 0;
-    let hasMeta = false;
-    let hasIndex = false;
-    let metaLineNum = -1;
-    let indexLineNum = -1;
-
-    // E000: 空文件
-    if (!content.trim()) {
-      errors.push({
-        code: 'E000',
-        message: 'Empty file',
-        line: 1,
-        column: 1,
-      });
-      return { valid: false, errors, warnings };
-    }
-
-    // 逐行檢查
-    for (const line of lines) {
-      lineNum++;
-      const trimmed = line.trim();
-
-      // 跳過空行
-      if (!trimmed) continue;
-
-      // 跳過註釋行
-      if (trimmed.startsWith('#')) continue;
-
-      // 檢查 @meta
-      if (trimmed.startsWith('@meta')) {
-        if (hasMeta) {
-          errors.push({
-            code: 'E002',
-            message: 'Duplicate @meta section',
-            line: lineNum,
-            column: 1,
-          });
-        }
-        hasMeta = true;
-        metaLineNum = lineNum;
-
-        // 驗證 @meta 格式
-        const metaError = this.validateMeta(trimmed, lineNum);
-        if (metaError) errors.push(metaError);
-
-        continue;
-      }
-
-      // 檢查 @index
-      if (trimmed.startsWith('@index')) {
-        if (hasIndex) {
-          errors.push({
-            code: 'E002',
-            message: 'Duplicate @index section',
-            line: lineNum,
-            column: 1,
-          });
-        }
-        hasIndex = true;
-        indexLineNum = lineNum;
-
-        // 驗證順序
-        if (!hasMeta) {
-          errors.push({
-            code: 'E002',
-            message: '@index must come after @meta',
-            line: lineNum,
-            column: 1,
-          });
-        }
-
-        // 驗證 @index 格式
-        const indexError = this.validateIndex(trimmed, lineNum);
-        if (indexError) errors.push(indexError);
-
-        continue;
-      }
-
-      // 檢查 @data
-      if (trimmed.startsWith('@data')) {
-        if (!hasMeta || !hasIndex) {
-          errors.push({
-            code: 'E002',
-            message: '@data must come after @meta and @index',
-            line: lineNum,
-            column: 1,
-          });
-        }
-        continue;
-      }
-
-      // 數據行（必須在 @data 之後）
-      if (hasMeta && hasIndex && lineNum > indexLineNum) {
-        const dataError = this.validateDataLine(trimmed, lineNum);
-        if (dataError) {
-          if (dataError.code.startsWith('W')) {
-            warnings.push(dataError);
-          } else {
-            errors.push(dataError);
-          }
-        }
-      }
-    }
-
-    // E001: 缺少必要層級
-    if (!hasMeta) {
-      errors.push({
-        code: 'E001',
-        message: 'Missing required section @meta',
-        line: 1,
-        column: 1,
-        expected: '@meta |v=1.0|c=...|',
-      });
-    }
-
-    if (!hasIndex) {
-      errors.push({
-        code: 'E001',
-        message: 'Missing required section @index',
-        line: metaLineNum + 1,
-        column: 1,
-        expected: '@index |tot=...|',
-      });
-    }
-
-    return {
-      valid: errors.length === 0,
-      errors,
-      warnings,
-    };
-  }
-
-  /**
-   * 驗證 @meta 層格式
-   */
-  private validateMeta(line: string, lineNum: number): ParseError | null {
-    // E003: 分隔符錯誤
-    if (!line.match(/^@meta\s+\|.+\|$/)) {
-      return {
-        code: 'E003',
-        message: 'Invalid @meta format - missing delimiters',
-        line: lineNum,
-        column: 1,
-        expected: '@meta |field=value|...|',
-        got: line,
-      };
-    }
-
-    // 檢查必要欄位
-    if (!line.includes('v=')) {
-      return {
-        code: 'E005',
-        message: '@meta must contain "v" (version) field',
-        line: lineNum,
-        column: 1,
-      };
-    }
-
-    if (!line.includes('c=')) {
-      return {
-        code: 'E005',
-        message: '@meta must contain "c" (category) field',
-        line: lineNum,
-        column: 1,
-      };
-    }
-
-    // E004: 欄位格式錯誤
-    const fieldsMatch = line.match(/\|(.+)\|$/);
-    if (fieldsMatch) {
-      const fields = fieldsMatch[1].split('|').filter(f => f.trim());
-      for (const field of fields) {
-        if (!field.includes('=')) {
-          return {
-            code: 'E004',
-            message: `Invalid field format: "${field}" (should be key=value)`,
-            line: lineNum,
-            column: line.indexOf(field),
-          };
-        }
-      }
-    }
-
-    return null;
-  }
-
-  /**
-   * 驗證 @index 層格式
-   */
-  private validateIndex(line: string, lineNum: number): ParseError | null {
-    // E003: 分隔符錯誤
-    if (!line.match(/^@index\s+\|.+\|$/)) {
-      return {
-        code: 'E003',
-        message: 'Invalid @index format - missing delimiters',
-        line: lineNum,
-        column: 1,
-        expected: '@index |field=value|...|',
-        got: line,
-      };
-    }
-
-    // E004: 欄位格式錯誤
-    const fieldsMatch = line.match(/\|(.+)\|$/);
-    if (fieldsMatch) {
-      const fields = fieldsMatch[1].split('|').filter(f => f.trim());
-      for (const field of fields) {
-        if (!field.includes('=')) {
-          return {
-            code: 'E004',
-            message: `Invalid field format: "${field}" (should be key=value)`,
-            line: lineNum,
-            column: line.indexOf(field),
-          };
-        }
-      }
-    }
-
-    return null;
-  }
-
-  /**
-   * 驗證 @data 數據行格式
-   */
-  private validateDataLine(line: string, lineNum: number): ParseError | null {
-    // E003: 分隔符錯誤
-    if (!line.match(/^[^|]+\|.+\|$/)) {
-      return {
-        code: 'E003',
-        message: 'Invalid data line format',
-        line: lineNum,
-        column: 1,
-        expected: 'id|field=value|...|',
-        got: line,
-      };
-    }
-
-    // E004: 欄位格式錯誤
-    const match = line.match(/\|(.+)\|$/);
-    if (match) {
-      const fields = match[1].split('|').filter(f => f.trim());
-      for (const field of fields) {
-        // 跳過任務組格式（包含分號）
-        if (field.includes(';')) continue;
-
-        if (!field.includes('=')) {
-          return {
-            code: 'E004',
-            message: `Invalid field format: "${field}" (should be key=value)`,
-            line: lineNum,
-            column: line.indexOf(field),
-          };
-        }
-      }
-    }
-
-    // W008: 未知欄位鍵名（警告）
-    // 這裡可以加入欄位名驗證邏輯
-
-    return null;
-  }
-
-  /**
-   * 檢測至少 10 種語法錯誤
-   */
-  getErrorTypes(): string[] {
-    return [
-      'E000 - Empty file',
-      'E001 - Missing required section (@meta or @index)',
-      'E002 - Invalid section order or duplicate sections',
-      'E003 - Missing delimiters (|)',
-      'E004 - Invalid field format (should be key=value)',
-      'E005 - Missing required field (@meta must have v and c)',
-      'E006 - Invalid timestamp format',
-      'E007 - Duplicate record_id',
-      'E008 - Unknown field key',
-      'E009 - Invalid value type',
-      'E010 - Invalid version number',
-      'W001 - Warning: Deprecated field',
-      'W008 - Warning: Unknown field key (preserved)',
-    ];
-  }
-}

package/core/dev/scripts/matrix/tests/abbreviations.test.ts

@@ -1,122 +0,0 @@
-/**
- * Abbreviations 模組單元測試
- */
-
-import {
-  abbreviateField,
-  expandField,
-  encodeValue,
-  decodeValue,
-  shortenTimestamp,
-  expandTimestamp,
-  FIELD_ABBREVIATIONS,
-  VALUE_CODES,
-} from '../src/abbreviations';
-
-describe('Abbreviations', () => {
-  describe('欄位名縮寫', () => {
-    it('應該正確縮寫常用欄位', () => {
-      expect(abbreviateField('status')).toBe('st');
-      expect(abbreviateField('priority')).toBe('p');
-      expect(abbreviateField('created_at')).toBe('ct');
-      expect(abbreviateField('updated_at')).toBe('ut');
-      expect(abbreviateField('duration')).toBe('dur');
-    });
-
-    it('應該保留未知欄位', () => {
-      expect(abbreviateField('unknown_field')).toBe('unknown_field');
-    });
-
-    it('應該正確展開縮寫', () => {
-      expect(expandField('st')).toBe('status');
-      expect(expandField('p')).toBe('priority');
-      expect(expandField('ct')).toBe('created_at');
-      expect(expandField('ut')).toBe('updated_at');
-      expect(expandField('dur')).toBe('duration');
-    });
-
-    it('應該保留未知縮寫', () => {
-      expect(expandField('xyz')).toBe('xyz');
-    });
-
-    it('應該包含至少 30 個欄位縮寫', () => {
-      const count = Object.keys(FIELD_ABBREVIATIONS).length;
-      expect(count).toBeGreaterThanOrEqual(30);
-    });
-  });
-
-  describe('值代碼化', () => {
-    it('應該正確編碼狀態值', () => {
-      expect(encodeValue('status', 'completed')).toBe('C');
-      expect(encodeValue('status', 'in_progress')).toBe('P');
-      expect(encodeValue('status', 'pending')).toBe('D');
-      expect(encodeValue('status', 'blocked')).toBe('B');
-    });
-
-    it('應該正確編碼優先級', () => {
-      expect(encodeValue('priority', 'P0')).toBe('0');
-      expect(encodeValue('priority', 'P1')).toBe('1');
-      expect(encodeValue('priority', 'P2')).toBe('2');
-      expect(encodeValue('priority', 'P3')).toBe('3');
-    });
-
-    it('應該正確編碼 Agent 類型', () => {
-      expect(encodeValue('agent_type', 'developer')).toBe('dev');
-      expect(encodeValue('agent_type', 'backend_engineer')).toBe('be');
-      expect(encodeValue('agent_type', 'frontend_engineer')).toBe('fe');
-    });
-
-    it('應該保留未知值', () => {
-      expect(encodeValue('unknown_field', 'unknown_value')).toBe('unknown_value');
-    });
-
-    it('應該正確解碼狀態值', () => {
-      expect(decodeValue('status', 'C')).toBe('completed');
-      expect(decodeValue('status', 'P')).toBe('in_progress');
-      expect(decodeValue('status', 'D')).toBe('pending');
-      expect(decodeValue('status', 'B')).toBe('blocked');
-    });
-
-    it('應該正確解碼優先級', () => {
-      expect(decodeValue('priority', '0')).toBe('P0');
-      expect(decodeValue('priority', '1')).toBe('P1');
-      expect(decodeValue('priority', '2')).toBe('P2');
-      expect(decodeValue('priority', '3')).toBe('P3');
-    });
-
-    it('應該包含至少 20 個值代碼', () => {
-      let totalCodes = 0;
-      for (const field in VALUE_CODES) {
-        totalCodes += Object.keys(VALUE_CODES[field as keyof typeof VALUE_CODES]).length;
-      }
-      expect(totalCodes).toBeGreaterThanOrEqual(20);
-    });
-  });
-
-  describe('時間戳轉換', () => {
-    it('應該正確縮短時間戳', () => {
-      expect(shortenTimestamp('2026-02-07T05:30:00Z')).toBe('260207-0530');
-      expect(shortenTimestamp('2026-12-31T23:59:00Z')).toBe('261231-2359');
-      expect(shortenTimestamp('2025-01-01T00:00:00Z')).toBe('250101-0000');
-    });
-
-    it('應該正確展開時間戳', () => {
-      expect(expandTimestamp('260207-0530')).toBe('2026-02-07T05:30:00Z');
-      expect(expandTimestamp('261231-2359')).toBe('2026-12-31T23:59:00Z');
-      expect(expandTimestamp('250101-0000')).toBe('2025-01-01T00:00:00Z');
-    });
-
-    it('應該正確處理僅日期格式', () => {
-      expect(expandTimestamp('260207')).toBe('2026-02-07');
-      expect(expandTimestamp('261231')).toBe('2026-12-31');
-    });
-
-    it('時間戳轉換應該往返無損', () => {
-      const original = '2026-02-07T05:30:00Z';
-      const shortened = shortenTimestamp(original);
-      const expanded = expandTimestamp(shortened);
-
-      expect(expanded).toBe(original);
-    });
-  });
-});