modscape 2.0.3 → 2.1.0

package/README.ja.md

@@ -62,6 +62,8 @@ npm install -g modscape
     ```
     `.modscape/rules.md`（YAMLスキーマのルール）と `.modscape/codegen-rules.md`（実装コード生成のルール）、および各エージェント用のコマンドファイルが生成されます。
 
+    > **ルールの更新**: Modscape をアップグレードした後は、`modscape init` を再実行することで `.modscape/rules.md` と `.modscape/codegen-rules.md` を最新版に上書きできます。
+
 2.  **起動**: ビジュアライザーを起動します。
     ```bash
     modscape dev model.yaml
@@ -73,10 +75,12 @@ npm install -g modscape
 4.  **実装コードの生成** — `/modscape:codegen` でYAMLをdbt / SQLMesh / Spark SQLに変換します。
     > *".modscape/codegen-rules.md に従って、model.yaml からdbtモデルを生成して。"*
 
-    エージェントは `lineage.upstream` を元に依存関係の順でモデルを生成し、YAMLで定義しきれない箇所には `-- TODO:` コメントを残します。
+    エージェントは `lineage` セクションを元に依存関係の順でモデルを生成し、YAMLで定義しきれない箇所には `-- TODO:` コメントを残します。
 
 ### B: 手動モデリング
-1.  **YAML作成**: `model.yaml` ファイルを作成します。
+アーキテクチャを直接コントロールしたい場合に最適です。
+
+1.  **YAML作成**: `model.yaml` ファイルを作成します（[YAMLリファレンス](#モデルの定義-yaml) を参照）。
 2.  **起動**: ビジュアライザーを起動します。
     ```bash
     modscape dev model.yaml
@@ -95,6 +99,7 @@ relationships – テーブル間のERカーディナリティ
 lineage      – データの流れ / 変換パス
 annotations  – キャンバス上のスティッキーノート・吹き出し
 layout       – 全座標データ（tables/domains の中に x/y を書いてはいけない）
+consumers    – データの下流消費者（BIダッシュボード・MLモデル・アプリケーション等）
 ```
 
 ### Domains（ドメイン）
@@ -105,8 +110,7 @@ domains:
     name: "主要売上"
     description: "営業チームのトランザクションデータ。"  # 任意
     color: "rgba(59, 130, 246, 0.1)"  # 背景色
-    tables: [orders, dim_customers]   # 論理的な所属リスト
-    isLocked: false  # true にするとキャンバスでの誤ドラッグを防止
+    members: [orders, dim_customers]   # 論理的な所属リスト
 ```
 
 ### Tables（テーブル）
@@ -193,6 +197,31 @@ relationships:
 
 > **ER関係** vs **リネージ**: 構造的な結合（外部キーなど）には `relationships` を、データの加工・変換の流れには `lineage` を使用してください。両方に同じ接続を記述しないでください。
 
+### Consumers（コンシューマー）
+
+コンシューマーはデータモデルの下流消費者を表します。BIダッシュボード、MLモデル、アプリケーションなど、データを利用するあらゆるシステムを定義できます。キャンバス上に独自のノードとして表示され、リネージ矢印で接続されます。
+
+```yaml
+consumers:
+  - id: revenue_dashboard       # 一意のID — lineageやlayoutで使用
+    name: "Revenue Dashboard"   # 表示名
+    description: "財務チーム向け月次KPIダッシュボード"  # 任意
+    appearance:
+      icon: "📊"                # 任意（デフォルト: 📊）
+      color: "#e0f2fe"          # 任意のアクセントカラー
+    url: "https://bi.example.com/revenue"  # 任意のリンク
+```
+
+コンシューマーへのリネージは `lineage.to` にコンシューマーIDを指定します：
+
+```yaml
+lineage:
+  - from: mart_monthly_revenue
+    to: revenue_dashboard   # コンシューマーID
+```
+
+テーブルと同様に、ドメインの `members` リストにも追加できます。
+
 ### Annotations（アノテーション）
 
 ```yaml
@@ -220,7 +249,6 @@ layout:
     y: 0
     width: 880
     height: 480
-    isLocked: false  # true でキャンバスのドラッグを防止
 
   # ドメイン内のテーブル – 座標はドメインの原点からの相対値
   orders:
@@ -261,6 +289,162 @@ modscape build ./models -o docs-site
 modscape export ./models -o docs/ARCHITECTURE.md
 ```
 
+---
+
+## dbt連携
+
+既存のdbtプロジェクトを `manifest.json` から直接インポートできます。
+
+### 事前準備
+
+コマンドを実行する前に、dbtプロジェクトで `dbt parse`（または `target/manifest.json` を生成する任意のdbtコマンド）を実行してください。
+
+### dbtプロジェクトのインポート
+
+```bash
+modscape dbt import [project-dir] [オプション]
+```
+
+| オプション | 説明 |
+|-----------|------|
+| `-o, --output <dir>` | 出力ディレクトリ（デフォルト: `modscape-<プロジェクト名>`） |
+| `--split-by <key>` | `schema`、`tag`、`folder` のいずれかでYAMLファイルを分割 |
+
+**使用例:**
+
+```bash
+# カレントディレクトリからインポート
+modscape dbt import
+
+# 特定のdbtプロジェクトパスを指定
+modscape dbt import ./my_dbt_project
+
+# スキーマ別にYAMLファイルを分割して出力
+modscape dbt import --split-by schema
+
+# dbtタグ別に分割し、出力先ディレクトリを指定
+modscape dbt import --split-by tag -o ./modscape-models
+```
+
+インポート後は以下でビジュアライザーを起動できます：
+```bash
+modscape dev modscape-my_project
+```
+
+> **インポートされる内容:** `manifest.json` 内の `model`、`seed`、`snapshot`、`source` ノード（カラム、説明文、`depends_on` によるリネージ含む）。
+> **分割モード:** `--split-by` 指定時はグループごとに別YAMLファイルへ出力されます。自己完結率（self-contained rate）が80%未満のファイルは、クロスファイルのリネージ参照が単体では表示されないため注意してください。
+
+### dbt変更の同期
+
+dbtプロジェクトを更新した後、既存のModscape YAMLファイルへ差分を反映できます。手動で追加したレイアウト・外観・アノテーション・リレーションシップは保持されます。
+
+```bash
+modscape dbt sync [project-dir] [オプション]
+```
+
+| オプション | 説明 |
+|-----------|------|
+| `-o, --output <dir>` | 同期対象のModscape YAMLが置かれたディレクトリ（デフォルト: `modscape-<プロジェクト名>`） |
+
+```bash
+# カレントディレクトリのdbtプロジェクトを同期
+modscape dbt sync
+
+# パスを指定して同期
+modscape dbt sync ./my_dbt_project -o ./modscape-models
+```
+
+> **sync と import の違い:** `import` はYAMLをゼロから生成します。`sync` は既存ファイルを更新するため、手動で加えたテーブル種別・ビジネス定義・サンプルデータなどの情報が失われません。
+
+---
+
+## モデルファイル操作
+
+### YAMLファイルのマージ
+
+複数のYAMLモデルを1ファイルに統合します。テーブル/ドメインIDが重複した場合は先勝ちで処理されます。
+
+```bash
+modscape merge model-a.yaml model-b.yaml -o merged.yaml
+
+# ディレクトリ内のすべてのYAMLをマージ
+modscape merge ./models -o merged.yaml
+```
+
+### テーブルの抽出
+
+特定のテーブル（関連するリレーションシップ・リネージも含む）を新しいYAMLファイルへ切り出します。
+
+```bash
+modscape extract model.yaml --tables orders,dim_customers -o subset.yaml
+
+# 複数ファイルから抽出
+modscape extract ./models --tables fct_sales,dim_dates -o extracted.yaml
+```
+
+### 自動レイアウト
+
+テーブルのリレーションシップをもとに、座標を自動計算してYAMLに書き込みます。
+
+```bash
+modscape layout model.yaml
+
+# 別ファイルに出力
+modscape layout model.yaml -o model-with-layout.yaml
+```
+
+---
+
+## アトミックモデル操作コマンド
+
+AIエージェントやスクリプトから、YAMLモデルファイルに対して精確な変更を加えるためのコマンドです。すべてのコマンドで `--json` オプションによる機械可読な出力が利用できます。
+
+### テーブルコマンド
+
+```bash
+modscape table list <file>               # テーブルID一覧を表示
+modscape table get <file> --id <id>      # 指定テーブルをJSONで取得
+modscape table add <file> --data <json>  # テーブルを追加
+modscape table update <file> --id <id> --data <json>  # テーブルを更新
+modscape table remove <file> --id <id>  # テーブルを削除
+```
+
+### カラムコマンド
+
+```bash
+modscape column add <file> --table <id> --data <json>
+modscape column update <file> --table <id> --id <col-id> --data <json>
+modscape column remove <file> --table <id> --id <col-id>
+```
+
+### リレーションシップコマンド
+
+```bash
+modscape relationship list <file>
+modscape relationship add <file> --data <json>
+modscape relationship remove <file> --index <n>
+```
+
+### リネージコマンド
+
+```bash
+modscape lineage list <file>
+modscape lineage add <file> --from <table-id> --to <table-id>
+modscape lineage remove <file> --from <table-id> --to <table-id>
+```
+
+### ドメインコマンド
+
+```bash
+modscape domain list <file>
+modscape domain get <file> --id <id>
+modscape domain add <file> --data <json>
+modscape domain update <file> --id <id> --data <json>
+modscape domain remove <file> --id <id>
+modscape domain member add <file> --domain <id> --table <table-id>
+modscape domain member remove <file> --domain <id> --table <table-id>
+```
+
 ## クレジット
 
 Modscape は以下の素晴らしいオープンソースプロジェクトによって支えられています：

package/README.md

@@ -63,6 +63,8 @@ Leverage AI coding assistants (**Gemini CLI, Claude Code, or Codex**) to build y
     ```
     This creates `.modscape/rules.md` (YAML schema rules) and `.modscape/codegen-rules.md` (code generation rules), plus agent-specific command files.
 
+    > **Updating rules**: After upgrading Modscape, re-run `modscape init` to overwrite `.modscape/rules.md` and `.modscape/codegen-rules.md` with the latest bundled version.
+
 2.  **Start Dev**: Launch the visualizer.
     ```bash
     modscape dev model.yaml
@@ -98,6 +100,7 @@ relationships – ER cardinality between tables
 lineage      – data flow / transformation paths
 annotations  – sticky notes / callouts on the canvas
 layout       – ALL coordinate data (never put x/y inside tables or domains)
+consumers    – downstream consumers (BI dashboards, ML models, applications)
 ```
 
 ### Domains
@@ -108,8 +111,7 @@ domains:
     name: "Core Sales"
     description: "Transactional data for the sales team."  # optional
     color: "rgba(59, 130, 246, 0.1)"  # background fill
-    tables: [orders, dim_customers]   # logical membership
-    isLocked: false  # prevent accidental drag when true
+    members: [orders, dim_customers]   # logical membership
 ```
 
 ### Tables
@@ -196,6 +198,31 @@ relationships:
 
 > **ER Relationships** vs **Lineage**: Use `relationships` for structural joins (FKs) and `lineage` for data flow (transformations). Do not duplicate them.
 
+### Consumers
+
+Consumers represent the downstream users of your data model — BI dashboards, ML models, applications, or any other system that consumes the data. They appear as distinct nodes on the canvas and can receive lineage edges.
+
+```yaml
+consumers:
+  - id: revenue_dashboard       # unique ID — used in lineage and layout
+    name: "Revenue Dashboard"   # display name
+    description: "Monthly KPI dashboard for the finance team."  # optional
+    appearance:
+      icon: "📊"                # optional (defaults to 📊)
+      color: "#e0f2fe"          # optional accent color
+    url: "https://bi.example.com/revenue"  # optional link
+```
+
+Connect a consumer with lineage by using its `id` as the `to` field:
+
+```yaml
+lineage:
+  - from: mart_monthly_revenue
+    to: revenue_dashboard   # consumer ID
+```
+
+Consumers can also be added to domain `members` lists just like tables.
+
 ### Annotations
 
 ```yaml
@@ -223,7 +250,6 @@ layout:
     y: 0
     width: 880
     height: 480
-    isLocked: false  # prevent drag in canvas
 
   # Table inside a domain – coordinates are relative to domain origin
   orders:
@@ -264,6 +290,162 @@ modscape build ./models -o docs-site
 modscape export ./models -o docs/ARCHITECTURE.md
 ```
 
+---
+
+## dbt Integration
+
+Modscape can import your existing dbt project directly from its compiled `manifest.json`.
+
+### Prerequisites
+
+Run `dbt parse` (or any dbt command that produces `target/manifest.json`) in your dbt project before using these commands.
+
+### Import dbt Project
+
+```bash
+modscape dbt import [project-dir] [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `-o, --output <dir>` | Output directory (default: `modscape-<project-name>`) |
+| `--split-by <key>` | Split output files by `schema`, `tag`, or `folder` |
+
+**Examples:**
+
+```bash
+# Import from current directory, output to modscape-my_project/
+modscape dbt import
+
+# Import from a specific dbt project path
+modscape dbt import ./my_dbt_project
+
+# Split into separate YAML files by schema
+modscape dbt import --split-by schema
+
+# Split by dbt tag, with custom output directory
+modscape dbt import --split-by tag -o ./modscape-models
+```
+
+After import, visualize with:
+```bash
+modscape dev modscape-my_project
+```
+
+> **What gets imported:** All `model`, `seed`, `snapshot`, and `source` nodes from `manifest.json`, including columns, descriptions, and lineage (`depends_on`).
+> **Split mode:** When `--split-by` is used, each group is written to a separate YAML file. A self-containment score is shown — files below 80% have cross-file lineage edges that won't render in isolation.
+
+### Sync dbt Changes
+
+After modifying your dbt project, sync the changes into existing Modscape YAML files without losing any manual edits (layout, appearance, annotations, relationships):
+
+```bash
+modscape dbt sync [project-dir] [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `-o, --output <dir>` | Target directory containing existing Modscape YAML files (default: `modscape-<project-name>`) |
+
+```bash
+# Sync changes from current dbt project
+modscape dbt sync
+
+# Sync from a specific path
+modscape dbt sync ./my_dbt_project -o ./modscape-models
+```
+
+> **sync vs import:** `import` creates YAML files from scratch; `sync` updates existing files, preserving your manual enrichments (table types, business definitions, sample data, etc.).
+
+---
+
+## Model File Operations
+
+### Merge YAML Files
+
+Combine multiple YAML models into one. Duplicate table/domain IDs are resolved with first-wins semantics.
+
+```bash
+modscape merge model-a.yaml model-b.yaml -o merged.yaml
+
+# Merge all YAMLs in a directory
+modscape merge ./models -o merged.yaml
+```
+
+### Extract Tables
+
+Extract a subset of tables (and their relationships/lineage) into a new YAML file.
+
+```bash
+modscape extract model.yaml --tables orders,dim_customers -o subset.yaml
+
+# Extract from multiple files
+modscape extract ./models --tables fct_sales,dim_dates -o extracted.yaml
+```
+
+### Auto-Layout
+
+Automatically calculate and write layout coordinates based on table relationships.
+
+```bash
+modscape layout model.yaml
+
+# Write to a separate output file
+modscape layout model.yaml -o model-with-layout.yaml
+```
+
+---
+
+## Atomic Model Mutation Commands
+
+These commands let AI agents (or scripts) make precise, targeted changes to a YAML model file. All commands support `--json` for machine-readable output.
+
+### Table Commands
+
+```bash
+modscape table list <file>               # List all table IDs
+modscape table get <file> --id <id>      # Get a single table as JSON
+modscape table add <file> --data <json>  # Add a new table
+modscape table update <file> --id <id> --data <json>  # Update a table
+modscape table remove <file> --id <id>  # Remove a table
+```
+
+### Column Commands
+
+```bash
+modscape column add <file> --table <id> --data <json>
+modscape column update <file> --table <id> --id <col-id> --data <json>
+modscape column remove <file> --table <id> --id <col-id>
+```
+
+### Relationship Commands
+
+```bash
+modscape relationship list <file>
+modscape relationship add <file> --data <json>
+modscape relationship remove <file> --index <n>
+```
+
+### Lineage Commands
+
+```bash
+modscape lineage list <file>
+modscape lineage add <file> --from <table-id> --to <table-id>
+modscape lineage remove <file> --from <table-id> --to <table-id>
+```
+
+### Domain Commands
+
+```bash
+modscape domain list <file>
+modscape domain get <file> --id <id>
+modscape domain add <file> --data <json>
+modscape domain update <file> --id <id> --data <json>
+modscape domain remove <file> --id <id>
+modscape domain member add <file> --domain <id> --table <table-id>
+modscape domain member remove <file> --domain <id> --table <table-id>
+```
+
 ## Credits
 
 Modscape is made possible by these incredible open-source projects:

package/package.json

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

package/src/layout.js

@@ -28,7 +28,15 @@ export function applyLayout(inputPath, options = {}) {
     return;
   }
 
-  console.log(`  🏗️  Calculating layout for ${schema.tables.length} tables...`);
+  const consumers = Array.isArray(schema.consumers) ? schema.consumers : [];
+  const totalNodes = schema.tables.length + consumers.length;
+  console.log(`  🏗️  Calculating layout for ${schema.tables.length} tables and ${consumers.length} consumers...`);
+
+  // Normalize domain members: support both `members` (new) and `tables` (legacy)
+  const domains = (schema.domains || []).map(d => ({
+    ...d,
+    members: Array.isArray(d.members) ? d.members : (Array.isArray(d.tables) ? d.tables : []),
+  }));
 
   // Initialize Dagre Graph
   const g = new dagre.graphlib.Graph({ compound: true });
@@ -43,11 +51,15 @@ export function applyLayout(inputPath, options = {}) {
 
   // 1. Add Tables
   schema.tables.forEach((table) => {
-    // Standard table size in canvas units
     g.setNode(table.id, { width: 280, height: 160 });
   });
 
-  // 2. Add Lineage Edges
+  // 2. Add Consumer nodes
+  consumers.forEach((uc) => {
+    g.setNode(uc.id, { width: 160, height: 60 });
+  });
+
+  // 3. Add Lineage Edges (tables and consumers)
   if (schema.lineage) {
     schema.lineage.forEach((edge) => {
       if (g.hasNode(edge.from) && g.hasNode(edge.to)) {
@@ -56,7 +68,7 @@ export function applyLayout(inputPath, options = {}) {
     });
   }
 
-  // 3. Add ER Relationships
+  // 4. Add ER Relationships
   if (schema.relationships) {
     schema.relationships.forEach((rel) => {
       if (g.hasNode(rel.from.table) && g.hasNode(rel.to.table)) {
@@ -65,34 +77,32 @@ export function applyLayout(inputPath, options = {}) {
     });
   }
 
-  // 4. Setup Domains
-  const domainTableMap = new Map();
-  if (schema.domains) {
-    schema.domains.forEach((domain) => {
+  // 5. Setup Domains (members can be tables or consumers)
+  if (domains.length > 0) {
+    domains.forEach((domain) => {
       g.setNode(domain.id, { label: domain.name, cluster: true });
-      domain.tables.forEach((tableId) => {
-        if (g.hasNode(tableId)) {
-          g.setParent(tableId, domain.id);
+      domain.members.forEach((memberId) => {
+        if (g.hasNode(memberId)) {
+          g.setParent(memberId, domain.id);
         }
       });
-      domainTableMap.set(domain.id, domain.tables);
     });
   }
 
   // Execute Layout Calculation
   dagre.layout(g);
 
-  // 5. Post-process: Convert Dagre results to Modscape Layout format
+  // 6. Post-process: Convert Dagre results to Modscape Layout format
   const newLayout = {};
   const PAD = 48;
   const TABLE_W = 280;
-  const TABLE_H = 160; // Default height for layout estimation
+  const TABLE_H = 160;
   const GAP = 40;
 
   // Process Domains (Grid packing)
-  if (schema.domains) {
-    schema.domains.forEach(domain => {
-      const members = domain.tables.filter(tid => g.hasNode(tid));
+  if (domains.length > 0) {
+    domains.forEach(domain => {
+      const members = domain.members.filter(mid => g.hasNode(mid));
       if (members.length === 0) return;
 
       // Sort by dagre rank (left -> right)
@@ -104,18 +114,17 @@ export function applyLayout(inputPath, options = {}) {
       const gridW = cols * (TABLE_W + GAP) - GAP;
       const gridH = rowCount * (TABLE_H + GAP) - GAP;
 
-      // Anchor grid to dagre centroid
-      const cx = members.reduce((s, tid) => s + g.node(tid).x, 0) / members.length;
-      const cy = members.reduce((s, tid) => s + g.node(tid).y, 0) / members.length;
+      const cx = members.reduce((s, mid) => s + g.node(mid).x, 0) / members.length;
+      const cy = members.reduce((s, mid) => s + g.node(mid).y, 0) / members.length;
       const originX = cx - gridW / 2;
       const originY = cy - gridH / 2;
 
-      members.forEach((tid, idx) => {
+      members.forEach((mid, idx) => {
         const col = idx % cols;
         const row = Math.floor(idx / cols);
         const xOff = col * (TABLE_W + GAP) + TABLE_W / 2;
         const yOff = row * (TABLE_H + GAP) + TABLE_H / 2;
-        newLayout[tid] = {
+        newLayout[mid] = {
           x: Math.round(originX + xOff),
           y: Math.round(originY + yOff),
           parentId: domain.id
@@ -134,18 +143,30 @@ export function applyLayout(inputPath, options = {}) {
   }
 
   // Standalone Tables
-  const domainTableIds = new Set(schema.domains?.flatMap(d => d.tables) ?? []);
+  const domainMemberIds = new Set(domains.flatMap(d => d.members));
   schema.tables.forEach(t => {
-    if (!domainTableIds.has(t.id)) {
+    if (!domainMemberIds.has(t.id)) {
       const pos = g.node(t.id);
       newLayout[t.id] = { x: Math.round(pos.x), y: Math.round(pos.y) };
     }
   });
 
-  // 6. Save back to YAML
+  // Standalone Usecases
+  consumers.forEach(uc => {
+    if (!domainMemberIds.has(uc.id)) {
+      const pos = g.node(uc.id);
+      if (pos) newLayout[uc.id] = { x: Math.round(pos.x), y: Math.round(pos.y) };
+    }
+  });
+
+  // 7. Save back to YAML (write members, not tables, for domains)
+  schema.domains = domains.map(d => {
+    const { members, ...rest } = d;
+    return { ...rest, members };
+  });
   schema.layout = newLayout;
   const outputPath = options.output ? path.resolve(process.cwd(), options.output) : absolutePath;
-  
+
   fs.writeFileSync(outputPath, yaml.dump(schema, { indent: 2, lineWidth: -1, noRefs: true }), 'utf8');
   console.log(`  ✅ Layout complete! Saved to: ${path.relative(process.cwd(), outputPath)}`);
 }