penframe

# LLM開発者向けガイドこのファイルは、PenframeプロジェクトでLLM（AI）が開発を行う際のノウハウと手順をまとめたものです。 ## プロジェクト概要 PenframeはDSL形式でワイヤーフレームやUI構造を記述・可視化できる軽量ツールです。 - 入力：Penframe DSL（`.pengent`ファイル） - 出力：SVG形式のワイヤーフレーム ## プロジェクト構造 ``` penframe/ ├── src/ │ ├── parser/ │ │ └── grammar.pegjs # PEG.js文法定義ファイル │ ├── svg/ │ │ └── astToSvg.js # AST→SVG変換 │ └── cli.js # CLI エントリーポイント ├── dist/ │ └── parser.js # ビルド済みパーサー ├── tests/ │ ├── parser.test.js # パーサーのテスト │ └── __snapshots__/ # Jestスナップショット ├── examples/ │ ├── *.pengent # DSLサンプルファイル │ ├── ast_*.json # ASTサンプルファイル │ └── *.svg # 生成されたSVGファイル └── docs/ # ドキュメント ``` ## 新しい要素を追加する開発フロー ### 1. 文法定義の追加 (`src/parser/grammar.pegjs`) ```pegjs // Statementに新しい要素を追加 Statement = Headline / Paragraph / Button / FormControl / List / Image / Table / HR // ← 新しい要素を追加 / Container / AppConfig // 新しい要素のルールを定義 HR = "@hr" { return { type: "hr" }; } ``` **重要ポイント：** - `Statement`の上から順番に評価されるため、順序に注意 - `Container`と`AppConfig`は最後に配置する - ASTノードは必ず`type`フィールドを持つ ### 2. パーサーのビルド ```bash npm run build ``` 文法ファイルを変更したら必ずビルドが必要です。 ### 3. テストケースの追加 (`tests/parser.test.js`) ```javascript const testCases = [ // ... 既存のテストケース '@hr' // ← 新しいテストケースを追加 ]; ``` ### 4. テストの実行 ```bash npm test ``` スナップショットが自動生成され、ASTの構造が確認できます。 ### 5. SVG生成器の実装 (`src/svg/astToSvg.js`) #### a) renderElements関数に条件分岐を追加 ```javascript if (node.type === 'hr') { const y = node.y ?? defaultY; if (node.y === undefined) { defaultY += 20; // 要素の高さ分を追加 } return renderHR(node, parent, y); } ``` #### b) 専用のレンダリング関数を作成 ```javascript function renderHR(node, parent, y) { const x = node.x ?? 20; const width = node.width ?? (parent.width - x * 2); const color = node.color || '#cccccc'; const strokeWidth = node.strokeWidth || 1; return ` <line x1="${x}" y1="${y}" x2="${x + width}" y2="${y}" stroke="${escapeXml(color)}" stroke-width="${strokeWidth}" /> `; } ``` ### 6. サンプルASTファイルの作成 (`examples/ast_*.json`) ```json [ { "type": "config", "name": "app", "platform": "pc", "width": 800, "height": 600, "title": "Test" }, { "type": "hr" }, { "type": "hr", "color": "#ff0000", "strokeWidth": 3 } ] ``` ### 7. SVG生成テスト ```bash node src/svg/ast2svg.js examples/ast_hr_test.json output_hr_test.svg ``` ## 開発時の注意点とコツ ### ファイル探索のコツ 1. **パーサー関連**: `src/parser/grammar.pegjs` 2. **SVG生成関連**: `src/svg/astToSvg.js` 3. **テスト**: `tests/parser.test.js` 4. **サンプル**: `examples/`ディレクトリ ### よくある躓きポイント 1. **文法ファイルを変更後にビルドを忘れる** - 必ず`npm run build`を実行 2. **renderElements関数の位置** - 新しい要素の条件分岐は適切な位置に挿入 - 特に`Container`や`AppConfig`より前に配置 3. **defaultYの管理** - 要素の高さ分だけdefaultYを増加させる - SVGでは上から下に要素が配置される 4. **escapeXml関数の使用** - ユーザー入力やカラーコードなどはescapeXmlを通す ### レンダリング関数の設計パターン ```javascript function renderNewElement(node, parent, y) { // 1. デフォルト値の設定 const x = node.x ?? defaultValue; const width = node.width ?? calculatedValue; // 2. プロパティの取得 const color = node.color || defaultColor; // 3. SVG要素の生成 return `<svg-element>${escapeXml(content)}</svg-element>`; } ``` ## テストとデバッグ ### パーサーテスト ```bash npm test ``` ### SVG生成テスト ```bash node src/svg/ast2svg.js examples/ast_sample.json output.svg ``` ### デバッグ方法 1. **ASTの確認**: スナップショットファイルでAST構造を確認 2. **SVG出力の確認**: 生成されたSVGファイルをブラウザで開く 3. **段階的実装**: まず最小限の実装から始めて徐々に機能追加 ## 実装例：@hr要素実際の実装例として、`@hr`要素の実装過程を参考にしてください： 1. `grammar.pegjs`に`HR`ルールを追加 2. `parser.test.js`に`'@hr'`テストケースを追加 3. `astToSvg.js`に`renderHR`関数を実装 4. `examples/ast_hr_test.json`でサンプル作成 5. SVG生成テストで動作確認この手順により、完全に動作する新機能を追加できました。 ## パフォーマンスとベストプラクティス - レンダリング関数は軽量に保つ - 複雑な計算は事前に行う - エラーハンドリングを適切に実装 - ユーザー入力は必ずエスケープする ## 参考ファイル - `docs/tech-parser.md` - パーサー技術詳細 - `docs/design.md` - 設計思想 - `examples/` - 実装サンプル集