modscape 1.0.2 → 1.0.4

package/README.ja.md

@@ -21,20 +21,19 @@
 ## 主な機能
 
 - **YAML-as-Code**: データアーキテクチャ全体を単一のYAMLファイルで定義。Gitによる変更管理が可能。
-- **統合プロフェッショナル・エディタ**: **CodeMirror 6** を内蔵。シンタックスハイライト対応のエディタをサイドバーで直接利用可能。
-- **統合 Undo/Redo & オートセーブ**: 
-  - ビジュアル操作（ドラッグ、リサイズ、編集）がエディタの履歴と同期。 `Ctrl+Z` で直前の操作を元に戻せます。
-  - **オートセーブ**をONにすれば、キャンバス上の変更が即座にローカルファイルに反映されます。
-- **ダーク/ライトモード対応**: 利用環境やドキュメント作成の用途に合わせて、ワンクリックでテーマを切り替え可能。
-- **データ分析特化のモデリング**: `fact`, `dimension`, `mart`, `hub`, `link`, `satellite` などのエンティティタイプを標準サポート。
+- **3階層ネーミングシステム**: エンティティを **概念名**（ビジュアル）、**論理名**（ビジネス定義）、**物理名**（実際のテーブル名）の3段階でドキュメント化。
+- **自動レイアウト調整**: インテリジェントな階層型レイアウトエンジンにより、リレーションに基づいてテーブルとドメインを自動的に整列（※モデルの複雑さによっては手動での微調整が必要な場合があります）。
+- **刷新されたモデリング・ノード**: 左上に突き出した「インデックス・タブ」で種類（FACT, DIM, HUB等）を明示。長い物理名は自動省略され、プロフェッショナルな外観を維持。
 - **インタラクティブなビジュアルキャンバス**: 
-  - **ドラッグで接続**: カラム間のリレーションを直感的に作成。吸着（Snapping）機能で快適な操作感。
+  - **ドラッグで接続**: カラム間のリレーションを直感的に作成。吸着機能で快適な操作感。
+  - **意味的なエッジバッジ**: 接続点に `( 1 )` や `[ M ]` バッジを表示し、カーディナリティ（多重度）を視覚化。
   - **データリネージ・モード**: データの流れをアニメーション付きの点線矢印で可視化。
   - **ドメイン階層ナビゲーション**: テーブルをビジネスドメインごとに整理し、構造化されたサイドバーから素早くアクセス。
-- **分析メタデータ**: 
-  - **ファクトテーブル・タイプ**: `transaction`, `periodic`, `accumulating`, `factless` といったデータの性質を定義。
-  - **SCD管理**: `SCD Type 2` などの履歴管理方式を可視化。
-  - **加算規則（Additivity）**: カラムが合計可能か（`fully`, `semi`, `non`）を明示 (Σ アイコン)。
+- **統合 Undo/Redo & オートセーブ**: 
+  - ドラッグや自動整列、編集などの操作が内蔵エディタの履歴と同期。
+  - オートセーブにより、ローカルのYAMLを常に最新の状態に維持。
+- **ダーク/ライトモード対応**: 利用環境やドキュメント作成の用途に合わせて、ワンクリックでテーマを切り替え可能。
+- **データ分析特化のモデリング**: `fact`, `dimension`, `mart`, `hub`, `link`, `satellite` に加え、汎用的な `table` タイプを標準サポート。
 - **AIエージェント対応**: **Gemini, Claude, Codex** 用の雛形を内蔵。LLMを活用してモデリング作業を劇的に加速。
 
 ## インストール
@@ -74,25 +73,34 @@ npm install -g modscape
 domains:
   - id: core_sales
     name: 主要売上
-    color: "#3b82f6"
-    tables: [orders, products]
+    color: "rgba(59, 130, 246, 0.1)"
+    tables: [orders]
 
 # 2. Tables: エンティティ定義
 tables:
   - id: orders
-    name: ORDERS
+    name: 注文           # 概念名（大）
+    logical_name: "顧客注文履歴" # 論理名（中）
+    physical_name: "fct_retail_sales" # 物理名（小）
     appearance:
-      type: fact    # fact | dimension | mart | hub | link | satellite
+      type: fact    # fact | dimension | mart | hub | link | satellite | table
       sub_type: transaction
-      scd: type2
-      icon: 📦
+      icon: 💰
     columns:
       - id: order_id
         logical:
           name: ORDER_ID
           isPrimaryKey: true
-          additivity: fully # fully | semi | non (Σ アイコン)
-          isMetadata: false # 監査用カラム等 (🕒 アイコン)
+          additivity: fully
+    sampleData:
+      - [order_id, amount, status]
+      - [1001, 50.0, "COMPLETED"]
+
+# 3. Relationships: カーディナリティの定義
+relationships:
+  - from: { table: customers, column: customer_id }
+    to: { table: orders, column: customer_id }
+    type: one-to-many
 ```
 
 ---
@@ -121,11 +129,10 @@ Modscape は以下の素晴らしいオープンソースプロジェクトに
 
 - [React Flow](https://reactflow.dev/) - インタラクティブなグラフ UI フレームワーク。
 - [CodeMirror 6](https://codemirror.net/) - 次世代のウェブベース・コードエディタ。
+- [Dagre](https://github.com/dagrejs/dagre) - 階層型グラフ・レイアウトエンジン。
 - [Lucide React](https://lucide.dev/) - シンプルで美しいアイコンセット。
 - [Zustand](https://github.com/pmndrs/zustand) - React 用の状態管理ライブラリ。
-- [Express](https://expressjs.com/) - Node.js 用のウェブフレームワーク。
 - [js-yaml](https://github.com/nodeca/js-yaml) - JavaScript 用 YAML パーサー。
-- [Commander.js](https://github.com/tj/commander.js) - CLI フレームワーク。
 
 ## ライセンス
 MIT

package/README.md

@@ -21,21 +21,19 @@ In modern data analysis platforms, data modeling is no longer just about drawing
 ## Key Features
 
 - **YAML-as-Code**: Define your entire data architecture in a single, human-readable YAML file. Track changes via Git.
-- **Instant Local Visualization**: Visualize your YAML models instantly on your machine. No database connections or cloud infrastructure required—just point to your file and start exploring.
-- **Integrated Professional Editor**: Powered by **CodeMirror 6**, providing syntax highlighting and a rich YAML editing experience directly in the sidebar.
-- **Unified Undo/Redo & Auto-save**: 
-  - Visual actions (dragging, resizing, metadata edits) are synchronized with the editor's history. Undo your last action with `Ctrl+Z`.
-  - Optional **Auto-save** ensures your local YAML is always up-to-date with your visual changes.
-- **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`, and `satellite`.
+- **Tri-Layer Naming System**: Document entities across three levels of abstraction: **Conceptual** (Visual name), **Logical** (Formal business name), and **Physical** (Actual database table name).
+- **Auto-Format Layout**: Automatically arrange tables and domains based on their relationships using an intelligent hierarchical layout engine (Note: manual adjustment may be required for complex models).
+- **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.
   - **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.
-- **Analytics Metadata**: 
-  - **Fact Table Types**: Define `transaction`, `periodic`, `accumulating`, or `factless` grains.
-  - **SCD Management**: Visualize `SCD Type 2` and other history-tracking dimensions.
-  - **Additivity Rules**: Mark columns as `fully`, `semi`, or `non-additive` (Σ icon).
+- **Unified Undo/Redo & Auto-save**: 
+  - Visual actions (dragging, formatting, editing) are synchronized with the built-in CodeMirror editor's history.
+  - 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.
 
 ## Installation
@@ -90,26 +88,35 @@ Modscape uses a schema designed for data analysis contexts.
 domains:
   - id: core_sales
     name: Core Sales
-    color: "#3b82f6"
-    tables: [orders, products]
+    color: "rgba(59, 130, 246, 0.1)"
+    tables: [orders]
 
-# 2. Tables: Entity definitions with multi-layer metadata
+# 2. Tables: Entity definitions with tri-layer metadata
 tables:
   - id: orders
-    name: ORDERS
+    name: Orders           # Conceptual (Big)
+    logical_name: "Customer Purchase Record" # Logical (Medium)
+    physical_name: "fct_retail_sales"        # Physical (Small)
     appearance:
-      type: fact    # fact | dimension | mart | hub | link | satellite
+      type: fact    # fact | dimension | mart | hub | link | satellite | table
       sub_type: transaction 
-      scd: type2
-      icon: 📦
+      icon: 💰
     columns:
       - id: order_id
         logical:
           name: ORDER_ID
           type: Int
           isPrimaryKey: true
-          additivity: fully # fully | semi | non (Σ icon)
-          isMetadata: false # audit column (🕒 icon)
+          additivity: fully
+    sampleData:
+      - [order_id, amount, status]
+      - [1001, 50.0, "COMPLETED"]
+
+# 3. Relationships: Define ER cardinality
+relationships:
+  - from: { table: customers, column: customer_id }
+    to: { table: orders, column: customer_id }
+    type: one-to-many
 ```
 
 ---
@@ -138,11 +145,10 @@ Modscape is made possible by these incredible open-source projects:
 
 - [React Flow](https://reactflow.dev/) - Interactive node-based UI framework.
 - [CodeMirror 6](https://codemirror.net/) - Next-generation code editor for the web.
+- [Dagre](https://github.com/dagrejs/dagre) - Directed graph layout engine.
 - [Lucide React](https://lucide.dev/) - Beautifully simple pixel-perfect icons.
 - [Zustand](https://github.com/pmndrs/zustand) - Bear necessities for state management.
-- [Express](https://expressjs.com/) - Fast, unopinionated web framework for Node.js.
 - [js-yaml](https://github.com/nodeca/js-yaml) - JavaScript YAML parser and dumper.
-- [Commander.js](https://github.com/tj/commander.js) - CLI framework.
 
 ## License
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modscape",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Modscape: A YAML-driven data modeling visualizer CLI",
   "repository": {
     "type": "git",

package/src/index.js

@@ -15,7 +15,7 @@ const program = new Command();
 program
   .name('modscape')
   .description('Modscape: A YAML-driven data modeling visualizer CLI')
-  .version('1.0.2');
+  .version('1.0.4');
 
 program
   .command('init')

package/src/templates/rules.md

@@ -1,92 +1,120 @@
 # Data Modeling Rules for this Project
 
 ## 1. Modeling Strategy
-<!-- Define your modeling methodology here. Example: Data Vault 2.0, Star Schema, 3NF -->
 - **Dimensional Modeling (Star Schema)**: Recommended for most analytical use cases. 
   - Use `appearance.type: fact` for central measurement tables.
   - Use `appearance.type: dimension` for descriptive attribute tables.
   - Use `appearance.type: mart` for downstream reporting-ready tables (Data Marts).
 - **Data Vault 2.0**: For highly scalable enterprise data warehouses.
   - Use `appearance.type: hub`, `link`, or `satellite`.
+- **Generic Modeling**: For all other physical tables.
+  - Use `appearance.type: table` for raw mirror tables, simple RDB exports, or utility tables.
 
-## 2. Analytics Metadata
-Modscape supports attributes to communicate the "Story" and "Grain" of your data to humans and AI agents.
+## 2. Table Naming Hierarchy
+Modscape supports three levels of naming to bridge the gap between business and technology.
 
-### Fact Table Types / Dimension History (`appearance.sub_type` and `appearance.scd`)
-Modscape separates a table's core nature from its history tracking method.
+1.  **Conceptual Name (`name`)**: The primary title on the canvas (e.g., "Customers"). Largest font.
+2.  **Logical Name (`logical_name`)**: Formal business name (e.g., "Customer Master"). Hidden on canvas if identical to Conceptual Name.
+3.  **Physical Name (`physical_name`)**: Actual database table name (e.g., `dim_customers`). Defaults to the technical `id` if empty.
 
+## 3. Analytics & Visual Metadata
+Modscape supports attributes to communicate the "Story" and "Grain" of your data.
+
+### Grain & History (`appearance.sub_type` and `appearance.scd`)
 - **`sub_type` (The "What")**:
   - **For Fact Tables**: `transaction` (atomic event), `periodic` (state interval), `accumulating` (milestones), `factless` (occurrence only).
   - **For Dimension Tables**: `conformed` (shared), `junk` (flags), `degenerate` (in-fact).
 - **`scd` (The "How it changes")**:
   `type0` (fixed), `type1` (overwrite), `type2` (history row), `type3` (history col), `type4` (history table), `type5` (1+4), `type6` (1+2+3), `type7` (1+2).
 
+### Visual Semantics (`appearance.icon` and `appearance.color`)
+Categorize entities visually to make the canvas intuitive:
+- **`icon`**: Use a single Emoji (e.g., 🛒, 👥, 📋) to represent the business concept.
+- **`color`**: Use Hex or RGBA codes for specific table highlighting (optional).
+
 ### Data Lineage (`lineage.upstream`)
-Explicitly define dependencies to communicate the data flow:
+Define dependencies to communicate data flow:
 - Use `lineage.upstream: [table_id1, table_id2]` to list source tables.
 
-### Column Additivity (`logical.additivity`)
-- `fully`: Can be summed across all dimensions (e.g., sales amount). Displays as `Σ`.
-- `semi`: Summing is valid only across some dimensions (e.g., bank balance - can't sum across time). Displays as `Σ~`.
-- `non`: Summing is never valid (e.g., unit price, ratios). Displays as `⊘`.
+## 4. Sample Data Stories
+**Every table must include realistic sample data** to explain the context without requiring SQL queries.
+- **Format**: A 2D array where the first row is headers.
+- **Rule**: Provide at least 3 rows of high-quality, representative data.
+```yaml
+sampleData:
+  - [header1, header2]
+  - [value1, value2]
+```
 
-### Metadata Columns (`logical.isMetadata`)
-Mark technical or audit columns (like `created_at`, `dbt_updated_at`) with `isMetadata: true` to display a `🕒` icon.
+## 5. Physical Modeling Rules
+Provide physical mapping metadata to ensure the model is implementation-ready.
 
-## 3. Naming Conventions
-- **Casing**: [Select one: snake_case / UPPER_SNAKE_CASE / camelCase]
-- **Prefixes**: (e.g., `f_` for facts, `d_` for dimensions, `m_` for marts)
-- **Suffixes**: (e.g., `_id` for primary keys, `_h` for history tables)
+- **Physical Naming**: All names (tables, schemas, columns) must use `snake_case`.
+- **Schema Standards**: `raw`, `staging`, `analytics`, or `mart`.
+- **Data Types**: Use standard SQL types (e.g., `VARCHAR`, `BIGINT`, `NUMBER(38,2)`, `DATE`, `TIMESTAMP_NTZ`).
 
-## 4. Standard Data Types
-- String: Varchar, Text
-- Numeric: Integer, Decimal, Float
-- Date/Time: Timestamp, Date
+## 6. Logical Column Rules
+- **Key Flags**: Mark `isPrimaryKey: true`, `isForeignKey: true`, or `isPartitionKey: true` (for performance).
+- **Metadata Columns**: Mark technical columns (e.g., `updated_at`) with `isMetadata: true` (🕒 icon).
+- **Additivity**:
+  - `fully`: Can be summed across all dimensions (Σ icon).
+  - `semi`: Summing is restricted (e.g., bank balance) (Σ~ icon).
+  - `non`: Summing is never valid (e.g., unit price) (⊘ icon).
 
-## 5. YAML Schema Reference
+## 7. Relationship Cardinality
+Explicitly define the nature of ER connections using `type`:
+- Options: `one-to-one`, `one-to-many`, `many-to-one`, `many-to-many`.
+
+## 8. Domain Organization
+Group tables into business domains to manage complexity.
+- Assign a unique `color` to each domain container.
+- Use `description` to explain the domain's business purpose.
+
+## 9. YAML Schema Reference (Hero Example)
 ```yaml
+domains:
+  - id: sales
+    name: Sales Intelligence
+    color: "rgba(59, 130, 246, 0.1)"
+    tables: [fct_orders]
+
 tables:
   - id: fct_orders
     name: Orders Fact
+    logical_name: "Sales Transaction Record"
+    physical_name: "fct_orders"
     appearance:
       type: fact
       sub_type: transaction
-      scd: type2 
-    conceptual:
-      description: "Records of customer purchases"
+      icon: "🛒"
+    physical:
+      name: fct_orders
+      schema: analytics
     columns:
       - id: order_id
         logical: { name: ID, type: Int, isPrimaryKey: true }
+        physical: { name: order_id, type: BIGINT }
       - id: amount
-        logical: { name: Amount, type: Decimal, additivity: fully } 
+        logical: { name: Amount, type: Decimal, additivity: fully }
+        physical: { name: total_amount, type: NUMBER(18,2) }
+    sampleData:
+      - [order_id, amount, status]
+      - [1001, 50.0, "COMPLETED"]
+      - [1002, 120.5, "PENDING"]
 
-  - id: dim_customers
-    name: Customers Dim
-    appearance:
-      type: dimension
-      sub_type: conformed
-      scd: type2
-    columns:
-      - id: customer_id
-        logical: { name: ID, type: Int, isPrimaryKey: true }
-
-  - id: mart_daily_revenue
-    name: Daily Revenue Mart
-    appearance:
-      type: mart
-      sub_type: periodic
-    columns:
-      - id: report_date
-        logical: { name: Date, type: Date, isPrimaryKey: true }
-      - id: daily_amount
-        logical: { name: Revenue, type: Decimal, additivity: fully }
+relationships:
+  - from: { table: dim_customers, column: customer_id }
+    to: { table: fct_orders, column: customer_id }
+    type: one-to-many
 ```
 
-## 6. Layout Management
+## 10. Layout Management
 - **Visualizer Priority**: The GUI handles layout through drag-and-drop.
 - **AI Agent Responsibility**: When creating new entities, assign initial (x, y) coordinates to place them near related tables.
 
-## 7. The Golden Rules
+## 11. The Golden Rules
 - When updating `model.yaml`, always self-audit against these rules.
-- Set appropriate `appearance.type`, `sub_type`, and `scd` for new tables.
-- Use `additivity` for numeric measures to inform BI tools and analysts.
+- **Utilize the 3-layer naming (Conceptual, Logical, Physical) for clarity.**
+- **Generate realistic `sampleData` for every new entity.**
+- **Provide `physical` mappings to make the model implementation-ready.**
+- Use `isPartitionKey` for large tables to inform performance design.

package/visualizer/package.json

@@ -1,7 +1,7 @@
 {
   "name": "visualizer",
   "private": true,
-  "version": "1.0.2",
+  "version": "1.0.4",
   "type": "module",
   "scripts": {
     "dev": "vite",