modscape 1.1.8 → 1.3.0

package/README.ja.md

@@ -8,7 +8,13 @@
 
 **Modscape** は、モダンなデータ基盤（Modern Data Stack）に特化した、YAML駆動のデータモデリング・ビジュアライザーです。物理的なスキーマとビジネスロジックのギャップを埋め、データチームがデータを通じた「ストーリー」を設計、文書化、共有することを可能にします。
 
-[ライブデモ](https://yujikawa.github.io/modscape/)
+
+🌐 **Live Demo:**
+https://yujikawa.github.io/modscape/
+
+
+![Modscape Screenshot](https://raw.githubusercontent.com/yujikawa/modscape/main/docs/assets/modscape.png)
+
 
 ## なぜ Modscape なのか？
 
@@ -26,7 +32,7 @@
 - **刷新されたモデリング・ノード**: 左上に突き出した「インデックス・タブ」で種類（FACT, DIM, HUB等）を明示。長い物理名は自動省略され、プロフェッショナルな外観を維持。
 - **インタラクティブなビジュアルキャンバス**: 
   - **ドラッグで接続**: カラム間のリレーションを直感的に作成。吸着機能で快適な操作感。
-  - **意味的なエッジバッジ**: 接続点に `( 1 )` や `[ M ]` バッジを表示し、カーディナリティ（多重度）を視覚化。
+  - **意味的なエッジバッジ**: 接続点に `( 1 )` や `[ N ]` バッジを表示し、カーディナリティ（多重度）を視覚化。
   - **データリネージ・モード**: データの流れをアニメーション付きの点線矢印で可視化。
   - **ドメイン階層ナビゲーション**: テーブルをビジネスドメインごとに整理し、構造化されたサイドバーから素早くアクセス。
 - **統合 Undo/Redo & オートセーブ**: 
@@ -34,7 +40,7 @@
   - オートセーブにより、ローカルのYAMLを常に最新の状態に維持。
 - **ダーク/ライトモード対応**: 利用環境やドキュメント作成の用途に合わせて、ワンクリックでテーマを切り替え可能。
 - **データ分析特化のモデリング**: `fact`, `dimension`, `mart`, `hub`, `link`, `satellite` に加え、汎用的な `table` タイプを標準サポート。
-- **AIエージェント対応**: **Gemini, Claude, Codex** 用の雛形を内蔵。LLMを活用してモデリング作業を劇的に加速。
+- **AIエージェント対応**: **Gemini CLI, Claude Code, Codex** 用の雛形を内蔵。モデリング（`/modscape:modeling`）と実装コード生成（`/modscape:codegen`）の両方でLLMを活用できます。
 
 ## インストール
 
@@ -47,15 +53,27 @@ npm install -g modscape
 ## はじめに
 
 ### A: AI駆動のモデリング（推奨）
-1.  **初期化**: 使用するAIエージェントに合わせてモデリングルールを生成します。
+1.  **初期化**: 使用するAIエージェントに合わせてルールファイルとコマンドを生成します。
     ```bash
-    modscape init --gemini  # または --claude, --codex
+    modscape init --gemini   # Gemini CLI
+    modscape init --claude   # Claude Code
+    modscape init --codex    # Codex
+    modscape init --all      # 3つすべて
     ```
+    `.modscape/rules.md`（YAMLスキーマのルール）と `.modscape/codegen-rules.md`（実装コード生成のルール）、および各エージェント用のコマンドファイルが生成されます。
+
 2.  **起動**: ビジュアライザーを起動します。
     ```bash
     modscape dev model.yaml
     ```
-3.  **AIに指示**: AIにこう伝えてください： *" .modscape/rules.md のルールに従って、model.yaml に新しい 'Marketing' ドメインを追加して。"*
+
+3.  **データモデルの設計** — `/modscape:modeling` でモデルを作成・編集します。
+    > *".modscape/rules.md のルールに従って、model.yaml に新しい 'Marketing' ドメインを追加して。"*
+
+4.  **実装コードの生成** — `/modscape:codegen` でYAMLをdbt / SQLMesh / Spark SQLに変換します。
+    > *".modscape/codegen-rules.md に従って、model.yaml からdbtモデルを生成して。"*
+
+    エージェントは `lineage.upstream` を元に依存関係の順でモデルを生成し、YAMLで定義しきれない箇所には `-- TODO:` コメントを残します。
 
 ### B: 手動モデリング
 1.  **YAML作成**: `model.yaml` ファイルを作成します。
@@ -68,39 +86,157 @@ npm install -g modscape
 
 ## モデルの定義 (YAML)
 
+YAMLのルートレベル構造は以下の通りです：
+
+```
+domains      – 関連テーブルをまとめるビジュアルコンテナ
+tables       – 3階層メタデータを持つエンティティ定義
+relationships – テーブル間のERカーディナリティ
+annotations  – キャンバス上のスティッキーノート・吹き出し
+layout       – 全座標データ（tables/domains の中に x/y を書いてはいけない）
+```
+
+### Domains（ドメイン）
+
 ```yaml
-# 1. Domains: 関連するテーブルをグループ化するコンテナ
 domains:
   - id: core_sales
-    name: 主要売上
-    color: "rgba(59, 130, 246, 0.1)"
-    tables: [orders]
+    name: "主要売上"
+    description: "営業チームのトランザクションデータ。"  # 任意
+    color: "rgba(59, 130, 246, 0.1)"  # 背景色
+    tables: [orders, dim_customers]
+    isLocked: false  # true にするとキャンバスでの誤ドラッグを防止
+```
+
+### Tables（テーブル）
 
-# 2. Tables: エンティティ定義
+```yaml
 tables:
   - id: orders
-    name: 注文           # 概念名（大）
-    logical_name: "顧客注文履歴" # 論理名（中）
-    physical_name: "fct_retail_sales" # 物理名（小）
+    name: 注文                           # 概念名（大）
+    logical_name: "顧客注文履歴"          # 論理名（中）
+    physical_name: "fct_retail_sales"   # 物理名（小）
+
     appearance:
-      type: fact    # fact | dimension | mart | hub | link | satellite | table
-      sub_type: transaction
-      icon: 💰
+      type: fact        # fact | dimension | mart | hub | link | satellite | table
+      sub_type: transaction  # transaction | periodic | accumulating など
+      scd: type2        # ディメンション用 SCD タイプ: type0〜type6
+      icon: "💰"
+      color: "#e0f2fe"  # 任意のヘッダーカラー
+
+    conceptual:  # 任意 – AIエージェント向けビジネスコンテキスト
+      description: "1行 = 1注文明細。"
+      tags: [WHO, WHAT, WHEN]  # BEAM* タグ
+      businessDefinitions:
+        revenue: "割引・返品後の純売上"
+
+    lineage:  # mart/集計テーブルのみに定義
+      upstream:
+        - fct_sales
+        - dim_dates
+
+    implementation:  # 任意 – AIコード生成へのヒント
+      materialization: incremental  # table | view | incremental | ephemeral
+      incremental_strategy: merge   # merge | append | delete+insert
+      unique_key: order_id
+      partition_by:
+        field: order_date       # DATE/TIMESTAMP型カラムを指定（サロゲートキーは不可）
+        granularity: day        # day | month | year | hour
+      cluster_by: [customer_id]
+      grain: [month_key]        # GROUP BY カラム（martのみ）
+      measures:                 # 集計定義（martのみ）
+        - column: total_revenue
+          agg: sum              # sum | count | count_distinct | avg | min | max
+          source_column: fct_sales.amount
+
     columns:
       - id: order_id
         logical:
-          name: ORDER_ID
+          name: "注文ID"
+          type: Int         # Int | String | Decimal | Date | Timestamp | Boolean など
+          description: "サロゲートキー。"
           isPrimaryKey: true
-          additivity: fully
-    sampleData:
+          isForeignKey: false
+          isPartitionKey: false
+          isMetadata: false  # 監査カラム(load_date, record_source)は true
+          additivity: fully  # fully | semi | non
+        physical:  # 任意 – ウェアハウスの物理定義を上書き
+          name: order_id
+          type: "BIGINT"
+          constraints: [NOT NULL]
+
+    sampleData:  # 2次元配列。先頭行 = カラムID
       - [order_id, amount, status]
       - [1001, 50.0, "COMPLETED"]
+      - [1002, 120.5, "PENDING"]
+```
+
+**テーブルタイプと `appearance.type` の使い分け：**
+
+| type | 用途 |
+|------|------|
+| `fact` | 取引・イベント・測定値 |
+| `dimension` | エンティティ・マスタ・参照リスト |
+| `mart` | 集計・消費者向けテーブル（`lineage.upstream` を必ず定義） |
+| `hub` | Data Vault のビジネスキー |
+| `link` | Data Vault のハブ間結合・トランザクション |
+| `satellite` | Data Vault のハブに紐づく履歴属性 |
+| `table` | 汎用 |
 
-# 3. Relationships: カーディナリティの定義
+### Relationships（リレーションシップ）
+
+```yaml
 relationships:
-  - from: { table: customers, column: customer_id }
-    to: { table: orders, column: customer_id }
-    type: one-to-many
+  - from:
+      table: dim_customers   # テーブル ID
+      column: customer_id    # カラム ID（任意）
+    to:
+      table: fct_orders
+      column: customer_id
+    type: one-to-many  # one-to-one | one-to-many | many-to-one | many-to-many
+```
+
+> **データリネージ**は `lineage.upstream` で定義し、リネージモードでアニメーション矢印として表示されます。`relationships` に重複して記載しないでください。
+
+### Annotations（アノテーション）
+
+```yaml
+annotations:
+  - id: note_001
+    type: sticky   # sticky | callout
+    text: "粒度：1行 = 1注文明細"
+    color: "#fef9c3"          # 任意の背景色
+    targetId: fct_orders      # 貼り付け先のオブジェクト ID（任意）
+    targetType: table         # table | domain | relationship | column
+    offset:
+      x: 100    # 対象の左上からのオフセット（targetId 未指定時は絶対座標）
+      y: -80
+```
+
+### Layout（レイアウト）
+
+全座標データはオブジェクト ID をキーとして `layout` に記述します。**`tables` や `domains` の中に `x`/`y` を書いてはいけません。**
+
+```yaml
+layout:
+  # ドメイン – width と height が必要
+  core_sales:
+    x: 0
+    y: 0
+    width: 880
+    height: 480
+    isLocked: false  # true でキャンバスのドラッグを防止
+
+  # ドメイン内のテーブル – 座標はドメインの原点からの相対値
+  orders:
+    x: 280
+    y: 200
+    parentId: core_sales  # ドメインへの所属を宣言
+
+  # スタンドアロンテーブル – キャンバス絶対座標
+  mart_summary:
+    x: 1060
+    y: 200
 ```
 
 ---

package/README.md

@@ -8,7 +8,10 @@
 
 **Modscape** is a YAML-driven data modeling visualizer specialized for **Modern Data Stack** architectures. It bridges the gap between raw physical schemas and high-level business logic, empowering data teams to design, document, and share their data stories.
 
-[Live Demo](https://yujikawa.github.io/modscape/)
+🌐 **Live Demo:**
+https://yujikawa.github.io/modscape/
+
+![Modscape Screenshot](https://raw.githubusercontent.com/yujikawa/modscape/main/docs/assets/modscape.png)
 
 ## Why Modscape?
 
@@ -26,7 +29,7 @@ In modern data analysis platforms, data modeling is no longer just about drawing
 - **Redesigned Modeling Nodes**: Protruding "Index Tabs" for entity types (FACT, DIM, HUB, LINK, etc.) and auto-truncating physical names for a professional look.
 - **Interactive Visual Canvas**: 
   - **Drag-to-Connect**: Create relationships between columns intuitively with "Magnetic Snapping".
-  - **Semantic Edge Badges**: Visually identify cardinality with `( 1 )` and `[ M ]` badges at the connection points.
+  - **Semantic Edge Badges**: Visually identify cardinality with `( 1 )` and `[ N ]` badges at the connection points.
   - **Data Lineage Mode**: Visualize data flow with animated dashed arrows.
   - **Domain-Grouped Navigation**: Organize tables into visual business domains and navigate them via a structured sidebar.
 - **Unified Undo/Redo & Auto-save**: 
@@ -34,7 +37,7 @@ In modern data analysis platforms, data modeling is no longer just about drawing
   - Optional **Auto-save** ensures your local YAML is always up-to-date.
 - **Dark/Light Mode Support**: Switch between themes seamlessly for better eye comfort or documentation exports.
 - **Specialized Modeling Types**: Native support for entity types like `fact`, `dimension`, `mart`, `hub`, `link`, `satellite`, and generic `table`.
-- **AI-Agent Ready**: Built-in scaffolding for **Gemini, Claude, and Codex** to accelerate your modeling workflow using LLMs.
+- **AI-Agent Ready**: Built-in scaffolding for **Gemini CLI, Claude Code, and Codex** — both for modeling (`/modscape:modeling`) and implementation code generation (`/modscape:codegen`).
 
 ## Installation
 
@@ -51,22 +54,27 @@ npm install -g modscape
 ### Path A: AI-Driven Modeling (Recommended)
 Leverage AI coding assistants (**Gemini CLI, Claude Code, or Codex**) to build your models.
 
-1.  **Initialize**: Scaffold modeling rules and instructions for your preferred agent.
+1.  **Initialize**: Scaffold modeling rules and commands for your preferred agent.
     ```bash
-    # For Gemini CLI
-    modscape init --gemini
-
-    # For Claude Code
-    modscape init --claude
-
-    # For Codex
-    modscape init --codex
+    modscape init --gemini   # Gemini CLI
+    modscape init --claude   # Claude Code
+    modscape init --codex    # Codex
+    modscape init --all      # all three
     ```
+    This creates `.modscape/rules.md` (YAML schema rules) and `.modscape/codegen-rules.md` (code generation rules), plus agent-specific command files.
+
 2.  **Start Dev**: Launch the visualizer.
     ```bash
     modscape dev model.yaml
     ```
-3.  **Prompt Your AI**: Tell your agent: *"Use the rules in .modscape/rules.md to add a new 'Marketing' domain with a 'campaign_performance' fact table to my model.yaml."*
+
+3.  **Model with AI** — use `/modscape:modeling` to design your data model:
+    > *"Use the rules in .modscape/rules.md to add a new 'Marketing' domain with a 'campaign_performance' fact table."*
+
+4.  **Generate implementation code** — use `/modscape:codegen` to turn your YAML into dbt / SQLMesh / Spark SQL:
+    > *"Follow .modscape/codegen-rules.md and generate dbt models from model.yaml."*
+
+    The agent generates models in the correct dependency order and adds `-- TODO:` comments wherever the YAML doesn't fully specify the logic.
 
 ### Path B: Manual Modeling
 Best for direct architectural control.
@@ -81,42 +89,145 @@ Best for direct architectural control.
 
 ## Defining Your Model (YAML)
 
-Modscape uses a schema designed for data analysis contexts.
+Modscape uses a schema designed for data analysis contexts. The full YAML structure is:
+
+```
+domains      – visual containers grouping related tables
+tables       – entity definitions with tri-layer metadata
+relationships – ER cardinality between tables
+annotations  – sticky notes / callouts on the canvas
+layout       – ALL coordinate data (never put x/y inside tables or domains)
+```
+
+### Domains
 
 ```yaml
-# 1. Domains: Visual containers for grouping business logic
 domains:
   - id: core_sales
-    name: Core Sales
-    color: "rgba(59, 130, 246, 0.1)"
-    tables: [orders]
+    name: "Core Sales"
+    description: "Transactional data for the sales team."  # optional
+    color: "rgba(59, 130, 246, 0.1)"  # background fill
+    tables: [orders, dim_customers]
+    isLocked: false  # prevent accidental drag when true
+```
 
-# 2. Tables: Entity definitions with tri-layer metadata
+### Tables
+
+```yaml
 tables:
   - id: orders
-    name: Orders           # Conceptual (Big)
-    logical_name: "Customer Purchase Record" # Logical (Medium)
-    physical_name: "fct_retail_sales"        # Physical (Small)
+    name: Orders                          # Conceptual name (large)
+    logical_name: "Customer Purchase Record"  # Logical name (medium)
+    physical_name: "fct_retail_sales"         # Physical table name (small)
+
     appearance:
-      type: fact    # fact | dimension | mart | hub | link | satellite | table
-      sub_type: transaction 
-      icon: 💰
+      type: fact        # fact | dimension | mart | hub | link | satellite | table
+      sub_type: transaction  # transaction | periodic | accumulating | etc.
+      scd: type2        # SCD type for dimensions: type0–type6
+      icon: "💰"
+      color: "#e0f2fe"  # optional custom header color
+
+    conceptual:  # optional – business context for AI agents
+      description: "One row per order line item."
+      tags: [WHO, WHAT, WHEN]  # BEAM* tags
+      businessDefinitions:
+        revenue: "Net revenue after discounts"
+
+    lineage:  # for mart/aggregated tables only
+      upstream:
+        - fct_sales
+        - dim_dates
+
+    implementation:  # optional – hints for AI code generation
+      materialization: incremental  # table | view | incremental | ephemeral
+      incremental_strategy: merge   # merge | append | delete+insert
+      unique_key: order_id
+      partition_by:
+        field: order_date       # use a DATE/TIMESTAMP column, not a surrogate key
+        granularity: day        # day | month | year | hour
+      cluster_by: [customer_id]
+      grain: [month_key]        # GROUP BY columns (mart only)
+      measures:                 # aggregation definitions (mart only)
+        - column: total_revenue
+          agg: sum              # sum | count | count_distinct | avg | min | max
+          source_column: fct_sales.amount
+
     columns:
       - id: order_id
         logical:
-          name: ORDER_ID
-          type: Int
+          name: "Order ID"
+          type: Int         # Int | String | Decimal | Date | Timestamp | Boolean | ...
+          description: "Surrogate key."
           isPrimaryKey: true
-          additivity: fully
-    sampleData:
+          isForeignKey: false
+          isPartitionKey: false
+          isMetadata: false  # true for audit cols (load_date, record_source)
+          additivity: fully  # fully | semi | non
+        physical:  # optional warehouse overrides
+          name: order_id
+          type: "BIGINT"
+          constraints: [NOT NULL]
+
+    sampleData:  # 2D array; first row = column IDs
       - [order_id, amount, status]
       - [1001, 50.0, "COMPLETED"]
+      - [1002, 120.5, "PENDING"]
+```
 
-# 3. Relationships: Define ER cardinality
+### Relationships
+
+```yaml
 relationships:
-  - from: { table: customers, column: customer_id }
-    to: { table: orders, column: customer_id }
-    type: one-to-many
+  - from:
+      table: dim_customers   # table ID
+      column: customer_id    # column ID (optional)
+    to:
+      table: fct_orders
+      column: customer_id
+    type: one-to-many  # one-to-one | one-to-many | many-to-one | many-to-many
+```
+
+> **Data Lineage** connections are driven by `lineage.upstream` and rendered as animated arrows in Lineage Mode. Do **not** duplicate them as `relationships` entries.
+
+### Annotations
+
+```yaml
+annotations:
+  - id: note_001
+    type: sticky   # sticky | callout
+    text: "Grain: one row per invoice line item."
+    color: "#fef9c3"          # optional background color
+    targetId: fct_orders      # ID of the attached object (optional)
+    targetType: table         # table | domain | relationship | column
+    offset:
+      x: 100    # offset from target's top-left (or absolute if no target)
+      y: -80
+```
+
+### Layout
+
+All coordinate data lives in `layout`, keyed by object ID. **Never** place `x`/`y` inside `tables` or `domains`.
+
+```yaml
+layout:
+  # Domain – requires width and height
+  core_sales:
+    x: 0
+    y: 0
+    width: 880
+    height: 480
+    isLocked: false  # prevent drag in canvas
+
+  # Table inside a domain – coordinates are relative to domain origin
+  orders:
+    x: 280
+    y: 200
+    parentId: core_sales  # declare domain membership
+
+  # Standalone table – absolute canvas coordinates
+  mart_summary:
+    x: 1060
+    y: 200
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modscape",
-  "version": "1.1.8",
+  "version": "1.3.0",
   "description": "Modscape: A YAML-driven data modeling visualizer CLI",
   "repository": {
     "type": "git",
@@ -20,9 +20,10 @@
   "scripts": {
     "build-ui": "cd visualizer && npm run build && rm -rf ../visualizer-dist && mv dist ../visualizer-dist",
     "dev": "node src/index.js dev",
-    "test:e2e": "playwright test",
-    "test:all": "npm run build-ui && npm run test:e2e",
-    "test:update": "npm run build-ui && npm run test:e2e -- --update-snapshots"
+    "test:cli": "playwright test tests/import-dbt.spec.ts",
+    "test:e2e": "cp tests/fixtures/test-model.yaml tests/fixtures/test-model-runtime.yaml && playwright test",
+    "test:all": "npm run build-ui && npm run test:cli",
+    "test:update": "npm run build-ui && sleep 1 && npm run test:e2e -- --update-snapshots"
   },
   "dependencies": {
     "@inquirer/prompts": "^8.3.0",

package/src/export.js

@@ -180,11 +180,67 @@ export function generateMarkdown(schema, modelName) {
   md += '## Table Catalog\n\n';
   schema.tables.forEach(table => {
     md += `### ${table.name} ${table.appearance?.icon || ''}\n`;
+    if (table.logical_name) md += `*${table.logical_name}*\n\n`;
     if (table.conceptual?.description) {
       md += `**Description**: ${table.conceptual.description}\n\n`;
     }
+
+    // Type + SCD
     if (table.appearance?.type) {
-      md += `**Type**: ${table.appearance.type.toUpperCase()}\n\n`;
+      const scd = table.appearance.scd ? ` · SCD ${table.appearance.scd}` : '';
+      md += `**Type**: \`${table.appearance.type.toUpperCase()}\`${scd}\n\n`;
+    }
+
+    // Physical name
+    if (table.physical_name) {
+      md += `**Physical Name**: \`${table.physical_name}\`\n\n`;
+    }
+
+    // Lineage
+    if (table.lineage?.upstream?.length > 0) {
+      const upstreamNames = table.lineage.upstream.map(upId => {
+        const t = schema.tables.find(t => t.id === upId);
+        return t ? t.name : upId;
+      });
+      md += `**Upstream**: ${upstreamNames.map(n => `\`${n}\``).join(' → ')}\n\n`;
+    }
+
+    // Implementation
+    if (table.implementation) {
+      const impl = table.implementation;
+      md += '#### Implementation\n\n';
+      md += '| Property | Value |\n| --- | --- |\n';
+      if (impl.materialization) md += `| Materialization | \`${impl.materialization}\` |\n`;
+      if (impl.incremental_strategy) md += `| Incremental Strategy | \`${impl.incremental_strategy}\` |\n`;
+      if (impl.unique_key) {
+        const uk = Array.isArray(impl.unique_key) ? impl.unique_key.join(', ') : impl.unique_key;
+        md += `| Unique Key | \`${uk}\` |\n`;
+      }
+      if (impl.partition_by) {
+        const pb = impl.partition_by;
+        const field = pb.field || pb[0]?.field;
+        const gran = pb.granularity || pb[0]?.granularity;
+        md += `| Partition By | \`${field}\`${gran ? ` (${gran})` : ''} |\n`;
+      }
+      if (impl.cluster_by) {
+        const cb = Array.isArray(impl.cluster_by) ? impl.cluster_by.join(', ') : impl.cluster_by;
+        md += `| Cluster By | \`${cb}\` |\n`;
+      }
+      if (impl.grain) {
+        const grain = Array.isArray(impl.grain) ? impl.grain.join(', ') : impl.grain;
+        md += `| Grain (GROUP BY) | \`${grain}\` |\n`;
+      }
+      md += '\n';
+
+      // Measures
+      if (impl.measures?.length > 0) {
+        md += '#### Measures\n\n';
+        md += '| Column | Aggregation | Source Column |\n| --- | --- | --- |\n';
+        impl.measures.forEach(m => {
+          md += `| \`${m.column}\` | \`${m.agg}\` | ${m.source_column ? `\`${m.source_column}\`` : '-'} |\n`;
+        });
+        md += '\n';
+      }
     }
 
     // Columns Table (Enhanced with Physical info)