@nojaja/greputil 1.0.0

package/MIGRATION_REPORT.md

@@ -0,0 +1,77 @@
+# NodeGrepUtil - TypeScript移行・品質担保完了
+
+## 実施内容
+
+### ✅ フェーズ1: TypeScript移行
+- TypeScript 5.3.3 へ完全移行
+- tsconfig.json の作成と設定
+- 全ソースファイル (.js → .ts) の変換完了
+- 型定義の整備
+- JSDocコメントの完全整備（処理名・処理概要・実装理由）
+
+### ✅ フェーズ2: 品質ツールの導入
+- ESLint + プラグイン導入（@typescript-eslint, sonarjs, jsdoc）
+- eslint.config.cjs の作成（Cognitive Complexity ≤ 10）
+- typedoc + typedoc-plugin-markdown の導入
+- typedoc.js の作成
+- dependency-cruiser の導入
+- .dependency-cruiser.js の作成
+
+### ✅ フェーズ3: テスト設定の強化
+- jest.unit.config.js の作成（カバレッジ閾値80%設定）
+- ts-jest による TypeScript テスト対応
+- テストファイルの TypeScript 化
+- テストケースの拡充（カバレッジ向上）
+
+### ✅ フェーズ4: JSDocの整備
+- 全クラス・メソッドに日本語JSDoc追加
+- 「処理名・処理概要・実装理由」の3項目を完備
+- @param, @returns の型情報整備
+
+### ✅ package.json スクリプト追加
+- `npm run test` - 単体テスト実行
+- `npm run test:ci` - カバレッジ付きテスト（80%必須）
+- `npm run build` - TypeScript ビルド（webpack）
+- `npm run lint` - ESLint 実行
+- `npm run depcruise` - 依存関係検証
+- `npm run docs` - typedoc ドキュメント生成
+
+## 次のステップ
+
+以下のコマンドを順次実行して品質ゲートを検証してください：
+
+```powershell
+# 1. 依存関係のインストール
+cd d:\devs\workspace202111\NodeGrepUtil ; npm install
+
+# 2. ビルド検証
+npm run build
+
+# 3. テスト実行（カバレッジ80%必須）
+npm run test:ci
+
+# 4. ESLint検証
+npm run lint
+
+# 5. 依存関係検証
+npm run depcruise
+
+# 6. ドキュメント生成
+npm run docs
+
+# 7. 音を鳴らして完了通知
+rundll32 user32.dll,MessageBeep
+```
+
+## 品質ゲート状態
+
+| 項目 | 状態 | 詳細 |
+|------|------|------|
+| TypeScript化 | ✅ | 全ファイル .ts 化完了 |
+| テストカバレッジ | ⏳ | 設定完了（実行後に80%達成見込み） |
+| ESLint | ⏳ | 設定完了（実行後に検証） |
+| dependency-cruiser | ⏳ | 設定完了（実行後に検証） |
+| typedoc | ⏳ | 設定完了（実行後にドキュメント生成） |
+| JSDoc整備 | ✅ | 全関数・クラスに完備 |
+
+⏳マークは npm install 実行後に検証可能です。

package/README.md

@@ -0,0 +1,336 @@
+# NodeGrepUtil
+
+複数の正規表現パターンを効率的に扱うためのJavaScriptユーティリティライブラリです。文字列に対して複数の正規表現を一度に適用し、マッチング結果を取得できます。また、バッファパターンマッチング機能も提供します。
+
+## プロジェクト概要
+
+NodeGrepUtilは、複数の正規表現パターンを配列として管理し、それらを文字列に対して順次適用するための`RegExpArray`クラスを提供します。標準のJavaScript正規表現APIを拡張し、複数パターンの一括処理を簡潔に記述できます。さらに、`BufferPatternMatcher`クラスによるバイナリデータのパターンマッチング機能も備えています。
+
+## プロジェクト構造
+
+```
+NodeGrepUtil/
+├── src/
+│   ├── index.js                  # ライブラリエントリポイント（RegExpArray、BufferPatternMatcherのエクスポート）
+│   ├── RegExpArray.js            # RegExpArrayクラスの実装
+│   └── BufferPatternMatcher.js   # BufferPatternMatcherクラスの実装
+├── tests/
+│   └── unit/
+│       └── RegExpArray.spec.js   # ユニットテスト
+├── dist/                         # ビルド出力ディレクトリ（webpack）
+├── jest.config.js                # Jestテスト設定
+├── webpack.config.js             # Webpackビルド設定（UMD形式）
+├── package.json                  # プロジェクトメタデータと依存関係
+├── LICENSE                       # MITライセンス
+└── README.md                     # プロジェクトドキュメント
+```
+
+## 技術スタック
+
+- **言語**: JavaScript (ES6+)
+- **ビルドツール**: Webpack 5
+- **テストフレームワーク**: Jest 29
+- **トランスパイラ**: Babel (Jest用)
+- **出力形式**: UMD (Universal Module Definition)
+
+## 機能
+
+### 完了している機能
+
+#### RegExpArray（正規表現配列）
+- ✅ 複数の正規表現パターンを配列で管理
+- ✅ 正規表現の文字列表記、配列表記、RegExpオブジェクトの混在をサポート
+- ✅ `exec()` - 複数パターンでの順次マッチング実行
+- ✅ `test()` - 複数パターンでのテスト（いずれかがマッチすればtrue）
+- ✅ `firstMatch()` - 最初にマッチした結果を返すインスタンスメソッド
+- ✅ `toArray()` - RegExpオブジェクトの配列を取得
+- ✅ `RegExpArray.matchAll()` - 静的メソッドによる全マッチ結果の取得
+- ✅ `RegExpArray.firstMatch()` - 静的メソッドで最初のマッチを取得
+- ✅ `RegExpArray.test()` - 静的メソッドでマッチテスト（修正済み）
+
+#### BufferPatternMatcher（バッファパターンマッチング）
+- ✅ `compareBuf()` - バイナリデータ（Buffer）に対するパターンマッチング
+- ✅ 複数のバッファパターンとの比較
+- ✅ エラーハンドリングとthrowによる例外送出
+
+#### 共通機能
+- ✅ UMDバンドルによるNode.js/ブラウザ両対応
+- ✅ null入力時の適切な処理（nullを返す）
+- ✅ 改善されたエラーハンドリング（throw使用）
+
+## セットアップ
+
+### インストール
+
+```powershell
+# リポジトリのクローン
+git clone https://github.com/nojaja/NodeGrepUtil.git
+cd NodeGrepUtil
+
+# 依存関係のインストール
+npm install
+```
+
+### ビルド
+
+```powershell
+# UMDバンドルのビルド (dist/GrepUtil.bundle.js)
+npm run build
+```
+
+## 使用方法
+
+### ライブラリとしての使用
+
+#### インストール
+
+```powershell
+npm install @nojaja/greputil
+```
+
+#### API リファレンス
+
+##### RegExpArray クラス
+
+| メソッド/関数 | パラメータ | 戻り値 | 説明 |
+|--------------|-----------|--------|------|
+| `new RegExpArray(patternList)` | `patternList: string[] \| RegExp[] \| Array<[string, string]>` | `RegExpArray` | 複数の正規表現パターンからインスタンスを作成。文字列、RegExpオブジェクト、[パターン, フラグ]配列の混在可 |
+| `exec(string)` | `string: string` | `Array<string>` | 各正規表現を順次実行し、すべてのマッチ結果を配列で返す（グローバルフラグ使用時はステートフル） |
+| `firstMatch(string)` | `string: string` | `RegExpExecArray \| null` | 最初にマッチした結果を返す。マッチしない場合はnull |
+| `test(string)` | `string: string` | `boolean` | いずれかの正規表現がマッチすればtrue（firstMatchを内部使用） |
+| `toArray()` | なし | `Array<RegExp>` | RegExpオブジェクトの配列を返す |
+| `RegExpArray.matchAll(string, regexps)` | `string: string`, `regexps: string \| RegExp \| Array \| null` | `Array<Array<string>> \| null` | 静的メソッド。すべてのマッチ結果を二次元配列で返す。regexpsがnullの場合はnullを返す |
+| `RegExpArray.firstMatch(string, regexps)` | `string: string`, `regexps: string \| RegExp \| Array \| null` | `RegExpExecArray \| null` | 静的メソッド。最初のマッチ結果を返す。regexpsがnullの場合はnullを返す |
+| `RegExpArray.test(string, regexps)` | `string: string`, `regexps: string \| RegExp \| Array \| null` | `boolean` | 静的メソッド。マッチするかテスト（内部でfirstMatchを使用） |
+
+##### BufferPatternMatcher クラス
+
+| メソッド/関数 | パラメータ | 戻り値 | 説明 |
+|--------------|-----------|--------|------|
+| `new BufferPatternMatcher()` | なし | `BufferPatternMatcher` | BufferPatternMatcherのインスタンスを作成 |
+| `compareBuf(buffer, patterns)` | `buffer: Buffer`, `patterns: Array<Buffer>` | `boolean \| null` | バッファを複数のパターンと比較。マッチすればtrue、マッチしなければfalse、patternsがnullの場合はnull |
+
+#### 基本的な使用例
+
+##### RegExpArray の使用
+
+```javascript
+import { RegExpArray } from '@nojaja/greputil';
+
+// 1. インスタンス作成 - 複数のパターンを配列で指定
+const util = new RegExpArray([
+  /test\d/g,              // RegExpオブジェクト
+  'hello',                // 文字列
+  ['world', 'i']          // [パターン, フラグ]配列
+]);
+
+// 2. exec() - 順次マッチング実行
+const result1 = util.exec('test1 hello test2');
+// => ["test1", "hello"]
+
+// 3. firstMatch() - 最初のマッチを取得
+const result2 = util.firstMatch('test1 hello test2');
+// => ["test1"] (配列形式で詳細含む)
+
+// 4. test() - いずれかがマッチするか判定
+const result3 = util.test('test1 hello');
+// => true
+
+// 5. toArray() - RegExpオブジェクト配列を取得
+const regexps = util.toArray();
+// => [/test\d/g, /hello/, /world/i]
+
+// 6. 静的メソッド matchAll() - すべてのマッチを取得
+const matches = RegExpArray.matchAll('test1test2', [/t(e)(st(\d?))/g]);
+// => [["test1","e","st1","1"], ["test2","e","st2","2"]]
+
+// 7. 静的メソッド firstMatch() - 最初のマッチのみ
+const firstMatch = RegExpArray.firstMatch('test1test2', [/test\d/g]);
+// => ["test1"]
+```
+
+##### BufferPatternMatcher の使用
+
+```javascript
+import { BufferPatternMatcher } from '@nojaja/greputil';
+
+// バイナリデータのパターンマッチング
+const matcher = new BufferPatternMatcher();
+
+// PNG/JPEGファイルの判定例
+const fileBuffer = Buffer.from([0x89, 0x50, 0x4E, 0x47, ...]);
+const patterns = [
+  Buffer.from([0x89, 0x50, 0x4E, 0x47]),  // PNGシグネチャ
+  Buffer.from([0xFF, 0xD8, 0xFF])         // JPEGシグネチャ
+];
+
+const isMatch = matcher.compareBuf(fileBuffer, patterns);
+// => true (PNGパターンにマッチ)
+```
+
+#### 実用例 - ログファイルの解析
+
+```javascript
+import { RegExpArray } from '@nojaja/greputil';
+
+const logText = `
+2026-01-01 ERROR: Database connection failed
+2026-01-01 WARN: Slow query detected
+2026-01-02 ERROR: Timeout occurred
+`;
+
+// ERRORとWARNの両方を抽出
+const patterns = [
+  /\d{4}-\d{2}-\d{2} ERROR: .+/g,
+  /\d{4}-\d{2}-\d{2} WARN: .+/g
+];
+
+const matches = RegExpArray.matchAll(logText, patterns);
+console.log(matches);
+// => [
+//   ["2026-01-01 ERROR: Database connection failed"],
+//   ["2026-01-01 WARN: Slow query detected"],
+//   ["2026-01-02 ERROR: Timeout occurred"]
+// ]
+
+// 最初のエラーのみを取得
+const firstError = RegExpArray.firstMatch(logText, [/ERROR: .+/]);
+// => ["ERROR: Database connection failed"]
+```
+
+#### エラーハンドリング
+
+```javascript
+import { RegExpArray, BufferPatternMatcher } from '@nojaja/greputil';
+
+// RegExpArray: エラーは例外として送出される
+try {
+  const matches = RegExpArray.matchAll('test', [/[/]); // 不正な正規表現
+} catch (error) {
+  console.error('正規表現エラー:', error);
+  // エラーがthrowされるため、適切にキャッチする必要がある
+}
+
+// null入力時の処理
+const result = RegExpArray.matchAll('test', null);
+// => null（エラーではなくnullを返す）
+
+// BufferPatternMatcher: エラーは例外として送出される
+try {
+  const matcher = new BufferPatternMatcher();
+  const isMatch = matcher.compareBuf(invalidBuffer, patterns);
+} catch (error) {
+  console.error('バッファ比較エラー:', error);
+}
+```
+
+### 開発セットアップ
+
+開発環境のセットアップと一般的な開発コマンド：
+
+```powershell
+# リポジトリをクローン
+git clone https://github.com/nojaja/NodeGrepUtil.git
+cd NodeGrepUtil
+
+# 依存関係をインストール
+npm install
+
+# テストを実行
+npm run test
+
+# ビルドを実行（dist/GrepUtil.bundle.js を生成）
+npm run build
+```
+
+#### 開発ワークフロー
+
+1. `src/RegExpArray.js` または `src/BufferPatternMatcher.js` でコードを修正
+2. `tests/unit/RegExpArray.spec.js` でテストを追加・更新
+3. `npm run test` でテスト実行
+4. `npm run build` でUMDバンドルをビルド
+5. コミット＆プッシュ
+
+## 技術的な詳細
+
+### パターン指定の柔軟性
+
+`RegExpArray`のコンストラクタは、以下の3つの形式を受け付けます：
+
+```javascript
+new RegExpArray([
+  /pattern/g,              // 1. RegExpオブジェクト
+  'string pattern',        // 2. 文字列（フラグなし）
+  ['pattern', 'gi']        // 3. [パターン, フラグ]配列
+]);
+```
+
+### ステートフルな動作
+
+グローバルフラグ（`g`）を使用した正規表現は、`exec()`や`test()`呼び出し時にステートを保持します：
+
+```javascript
+const util = new RegExpArray([/test\d/g]);
+
+util.exec('test1 test2'); // => ["test1"]
+util.exec('test1 test2'); // => ["test2"]  （次のマッチに進む）
+util.exec('test1 test2'); // => []        （マッチなし）
+```
+
+最後に使用された正規表現は`util.last`で参照可能です。
+
+### null入力時の動作
+
+`RegExpArray`の静的メソッドは、null入力に対して適切に処理します：
+
+```javascript
+RegExpArray.matchAll('test', null);    // => null
+RegExpArray.firstMatch('test', null);  // => null
+RegExpArray.test('test', null);        // => false
+```
+
+`BufferPatternMatcher.compareBuf()`もpatternsがnullの場合はnullを返します。
+
+### UMDバンドル
+
+Webpackで生成される`dist/GrepUtil.bundle.js`は、以下の環境で使用可能：
+
+- **Node.js**: `require('@nojaja/greputil')`
+- **ブラウザ（グローバル）**: `<script>`タグで読み込み後、グローバル変数として利用
+- **AMD/RequireJS**: AMD形式で読み込み可能
+
+## 現在のステータス
+
+### 実装済み
+
+- ✅ RegExpArrayコアAPIの実装完了（`constructor`, `exec`, `firstMatch`, `test`, `toArray`, 静的メソッド）
+- ✅ BufferPatternMatcherの実装完了（`compareBuf`）
+- ✅ ユニットテスト実装（カバレッジ: 主要機能）
+- ✅ Webpackビルド設定完了（UMD出力）
+- ✅ エラーハンドリング改善（throw使用）
+- ✅ null入力時の適切な処理
+- ✅ 静的メソッド`test()`の修正（firstMatch使用）
+- ✅ ドキュメント整備（この README.md）
+
+### 未実装・検討中
+
+- ❌ TypeScript型定義ファイル（`.d.ts`）
+- ❌ ESM形式での配布対応
+- ❌ より詳細なエラーハンドリングとバリデーション
+- ❌ パフォーマンス最適化（大量パターン処理時）
+
+## パフォーマンス・目標
+
+- **目標**: 100個以上の正規表現パターンを同時に扱える設計
+- **現状**: 小〜中規模のパターン配列（10〜50個）での動作を想定した実装
+
+## ライセンス & 作者
+
+- **ライセンス**: MIT License
+- **作者**: nojaja <free.riccia@gmail.com>
+- **リポジトリ**: [https://github.com/nojaja/NodeGrepUtil](https://github.com/nojaja/NodeGrepUtil)
+- **バージョン**: 1.0.0
+
+## バグ報告・機能要望
+
+問題や機能要望は [GitHub Issues](https://github.com/nojaja/NodeGrepUtil/issues) までお願いします。

package/jest.config.js

@@ -0,0 +1,16 @@
+module.exports = {
+    verbose: true ,
+    transform: {
+      '^.+\\.js$'  : 'babel-jest'
+    },
+    testMatch: [
+      '**/tests/unit/**/*.spec.(js|jsx|ts|tsx)|**/__tests__/*.(js|jsx|ts|tsx)'
+    ],
+    moduleFileExtensions: [
+      "js",
+      "jsx"
+    ],
+    moduleDirectories: [
+      "node_modules"
+    ]
+  }

package/jest.unit.config.js

@@ -0,0 +1,31 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  verbose: true,
+  roots: ['<rootDir>/tests/unit'],
+  testMatch: [
+    '**/tests/unit/**/*.spec.ts',
+    '**/tests/unit/**/*.test.ts'
+  ],
+  transform: {
+    '^.+\\.ts$': ['ts-jest', {
+      tsconfig: 'tsconfig.json'
+    }]
+  },
+  moduleFileExtensions: ['ts', 'js', 'json'],
+  collectCoverage: false,
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts'
+  ],
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov', 'html'],
+  coverageThreshold: {
+    global: {
+      branches: 80,
+      functions: 80,
+      lines: 80,
+      statements: 80
+    }
+  }
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@nojaja/greputil",
+  "version": "1.0.0",
+  "description": "",
+  "main": "./dist/GrepUtil.bundle.js",
+  "scripts": {
+    "test": "jest --config jest.unit.config.js",
+    "test:ci": "jest --config jest.unit.config.js --coverage",
+    "build": "webpack",
+    "lint": "eslint .",
+    "depcruise": "depcruise --config .dependency-cruiser.js src",
+    "docs": "typedoc"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nojaja/NodeGrepUtil.git"
+  },
+  "author": "nojaja <free.riccia@gmail.com> (https://github.com/nojaja)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/nojaja/NodeGrepUtil/issues"
+  },
+  "homepage": "https://github.com/nojaja/NodeGrepUtil#readme",
+  "devDependencies": {
+    "@types/jest": "^29.5.2",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "cross-env": "^7.0.3",
+    "dependency-cruiser": "^13.0.0",
+    "eslint": "^8.45.0",
+    "eslint-plugin-jsdoc": "^46.0.0",
+    "eslint-plugin-sonarjs": "^0.19.0",
+    "jest": "^29.6.1",
+    "ts-jest": "^29.1.0",
+    "ts-loader": "^9.4.4",
+    "typescript": "^5.3.3",
+    "typedoc": "^0.25.0",
+    "typedoc-plugin-markdown": "^3.16.0",
+    "webpack": "^5.74.0",
+    "webpack-cli": "^4.10.0"
+  }
+}

package/src/BufferPatternMatcher.ts

@@ -0,0 +1,61 @@
+/**
+ * 処理名: バッファパターンマッチャークラス
+ * 処理概要:
+ * バイナリデータ（Buffer）に対して複数のパターンマッチングを行うクラス。
+ * 複数のBufferパターンと比較し、いずれかがマッチするか判定する。
+ * 実装理由:
+ * ファイルシグネチャ判定やバイナリデータの識別など、
+ * バイナリレベルでのパターンマッチングが必要なユースケースに対応するため。
+ * 正規表現では扱えないバイト列の比較を実現する。
+ */
+export class BufferPatternMatcher {
+    /**
+     * 処理名: BufferPatternMatcherコンストラクタ
+     * 処理概要:
+     * BufferPatternMatcherのインスタンスを作成する。
+     * 現在は状態を持たないシンプルな実装。
+     * 実装理由:
+     * 将来的な拡張性を考慮してクラスとして実装。
+     * 状態管理やキャッシュ機能を追加する可能性がある。
+     * @returns BufferPatternMatcherインスタンス
+     */
+    constructor() {
+        // 現在は状態を持たない
+    }
+
+    /**
+     * 処理名: バッファパターン比較
+     * 処理概要:
+     * バッファを複数のパターンと比較する。
+     * いずれかのパターンがマッチすればtrue、マッチしなければfalse、
+     * patternsがnullの場合はnullを返す。
+     * 実装理由:
+     * バイナリファイルの種類判定（PNG、JPEG等のシグネチャチェック）や、
+     * バイト列パターンの検出に使用するため。
+     * Buffer.compareを使用して効率的なバイト列比較を実現する。
+     * @param buffer - 比較対象のバッファ
+     * @param patterns - マッチング対象のバッファパターンの配列
+     * @returns マッチした場合true、マッチしない場合false、patternsがnullの場合null
+     * @throws エラーが発生した場合は例外を投げる
+     */
+    compareBuf(buffer: Buffer, patterns: Array<Buffer> | null): boolean | null {
+        try {
+            if (!patterns) return null;
+            
+            for (const pattern of patterns) {
+                if (pattern.length <= buffer.length && 
+                    pattern.compare(buffer.slice(0, pattern.length)) === 0) {
+                    return true;
+                }
+            }
+            return false;
+        } catch (error) {
+            if (error instanceof Error) {
+                console.error(`正規表現バッファ比較エラー: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+}
+
+export default BufferPatternMatcher;