modscape 0.1.2 → 0.3.0

package/README.md

@@ -1,4 +1,10 @@
-# <img src="./visualizer-dist/favicon.svg" width="32" height="32" align="center" /> Modscape
+# <img src="./visualizer/public/favicon.svg" width="32" height="32" align="center" /> Modscape
+
+[![npm version](https://img.shields.io/npm/v/modscape.svg?style=flat-square)](https://www.npmjs.com/package/modscape)
+[![npm downloads](https://img.shields.io/npm/dm/modscape.svg?style=flat-square)](https://www.npmjs.com/package/modscape)
+[![Deploy Demo](https://github.com/yujikawa/modscape/actions/workflows/deploy.yml/badge.svg)](https://github.com/yujikawa/modscape/actions/workflows/deploy.yml)
+[![Publish to NPM](https://github.com/yujikawa/modscape/actions/workflows/publish.yml/badge.svg)](https://github.com/yujikawa/modscape/actions/workflows/publish.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 
 Modscape is a YAML-driven data modeling visualizer. It helps data engineers and architects bridge the gap between conceptual, logical, and physical data models while maintaining sample data "stories".
 
@@ -11,6 +17,7 @@ Modscape is a YAML-driven data modeling visualizer. It helps data engineers and
 - **Sample Data "Stories"**: Attach sample data to entities to explain the data's purpose.
 - **Interactive Layout**: Arrange entities via drag-and-drop; positions are saved directly back to your YAML.
 - **Multi-file Support**: Manage multiple models in a single directory and switch between them seamlessly.
+- **Documentation Export**: Generate Mermaid-compatible Markdown documentation including ER diagrams and domain catalogs.
 - **AI-Agent Ready**: Scaffolding for Gemini, Claude, and Codex to help you model via AI.
 
 ## Installation
@@ -21,29 +28,79 @@ Install Modscape globally via npm:
 npm install -g modscape
 ```
 
-## Quick Start in 3 Steps
-
-### 1. Initialize your project
-Create the necessary configuration and modeling rules for your project (and AI agents).
-
-```bash
-modscape init
+---
+
+## Getting Started
+
+Choose the path that fits your workflow.
+
+### Path A: AI-Driven Modeling (Recommended)
+Best if you use AI coding assistants (Gemini CLI, Claude Code, Cursor/Codex).
+
+1.  **Initialize**: Scaffold modeling rules and AI agent instructions.
+    ```bash
+    modscape init
+    ```
+2.  **Start Dev**: Launch the visualizer on your model.
+    ```bash
+    modscape dev model.yaml
+    ```
+3.  **Prompt Your AI**: Tell your agent to use the rules in `.modscape/rules.md` to add tables or columns to your `model.yaml`.
+
+### Path B: Manual Modeling
+Best for direct YAML editing and architectural control.
+
+1.  **Create YAML**: Create a file named `model.yaml` (see [Defining Your Model](#defining-your-model-yaml)).
+2.  **Start Dev**: Launch the visualizer.
+    ```bash
+    modscape dev model.yaml
+    ```
+3.  **Explore Samples**: Try it out with our built-in samples:
+    ```bash
+    # Clone the repo or download the samples directory
+    modscape dev samples/
+    ```
+
+---
+
+## Defining Your Model (YAML)
+
+Modscape uses a human-readable YAML schema. While you can write it manually, we **highly recommend using an AI coding assistant** (like Gemini, Claude, or Cursor) to handle the boilerplate.
+
+### Manual Definition Reference
+Here is the basic structure for your `model.yaml`:
+
+```yaml
+tables:
+  - id: users
+    name: USERS
+    appearance:
+      type: dimension # dimension | fact | hub | link | satellite
+      icon: 👤
+    columns:
+      - id: user_id
+        logical: { name: USER_ID, type: UUID, isPrimaryKey: true }
+      - id: email
+        logical: { name: EMAIL, type: String }
+
+  # Data Vault Example
+  - id: hub_customer
+    name: HUB_CUSTOMER
+    appearance: { type: hub, icon: 🔑 }
+    columns:
+      - id: hk_customer
+        logical: { name: HK_CUSTOMER, type: Binary, isPrimaryKey: true }
+      - id: customer_id
+        logical: { name: CUSTOMER_ID, type: String }
 ```
 
-### 2. Explore Samples
-Try Modscape immediately using the built-in sample models.
+- **Appearance Types**: 
+  - `dimension` / `fact`: For Star Schema / Dimensional modeling.
+  - `hub` / `link` / `satellite`: For Data Vault 2.0 modeling.
+- **IDs**: Use lowercase, snake_case for `id` fields (used for internal linking).
+- **Layout**: Don't worry about the `layout:` section. Modscape will automatically add and update coordinates when you drag entities in the browser.
 
-```bash
-# Clone the repo or download the samples directory to try this:
-modscape dev samples/
-```
-
-### 3. Start Modeling
-Create a `model.yaml` and launch the interactive visualizer.
-
-```bash
-modscape dev model.yaml
-```
+---
 
 ## Usage
 
@@ -68,6 +125,17 @@ Generate a standalone static website to share your documentation (perfect for Gi
 modscape build models/ -o dist-site
 ```
 
+### Export Mode (Static Documentation)
+Generate a comprehensive Markdown document with embedded Mermaid diagrams.
+
+```bash
+# Print to stdout
+modscape export models/ecommerce.yaml
+
+# Save to a file
+modscape export models/ -o docs/
+```
+
 ## AI Agent Integration
 
 Modscape is designed to work alongside AI coding assistants. By running `modscape init`, you get:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modscape",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Modscape: A YAML-driven data modeling visualizer CLI",
   "repository": {
     "type": "git",
@@ -13,6 +13,7 @@
   "files": [
     "src",
     "visualizer-dist",
+    "visualizer/public/favicon.svg",
     "package.json",
     "README.md"
   ],

package/src/export.js

@@ -0,0 +1,193 @@
+import fs from 'fs';
+import yaml from 'js-yaml';
+import path from 'path';
+
+/**
+ * Normalizes the schema data to ensure it's in a consistent format.
+ * Similar to visualizer/src/lib/parser.ts but for the CLI side.
+ */
+function normalizeSchema(data) {
+  if (!data || typeof data !== 'object') {
+    throw new Error('Invalid YAML: Root must be an object');
+  }
+
+  const schema = {
+    tables: Array.isArray(data.tables) ? data.tables : [],
+    relationships: Array.isArray(data.relationships) ? data.relationships : [],
+    domains: Array.isArray(data.domains) ? data.domains : [],
+    layout: data.layout || {}
+  };
+
+  schema.tables = schema.tables.map(table => ({
+    ...table,
+    id: table.id || 'unknown',
+    name: table.name || table.id || 'Unnamed Table',
+    columns: Array.isArray(table.columns) ? table.columns : []
+  }));
+
+  return schema;
+}
+
+/**
+ * Sanitizes a string for use as a Mermaid entity name.
+ * Spaces and hyphens are replaced with underscores.
+ */
+function sanitize(str) {
+  return str.replace(/[^a-zA-Z0-9_]/g, '_');
+}
+
+/**
+ * Generates Mermaid ER diagram syntax.
+ */
+function generateMermaidER(schema) {
+  let mermaid = 'erDiagram\n';
+
+  // Tables (Entities)
+  schema.tables.forEach(table => {
+    const tableName = sanitize(table.name);
+    mermaid += `    ${tableName} {\n`;
+    table.columns.forEach(col => {
+      const colName = sanitize(col.logical?.name || col.id);
+      const colType = sanitize(col.logical?.type || 'string');
+      let markers = '';
+      if (col.logical?.isPrimaryKey) markers += ' PK';
+      if (col.logical?.isForeignKey) markers += ' FK';
+      mermaid += `        ${colType} ${colName}${markers}\n`;
+    });
+    mermaid += '    }\n';
+  });
+
+  // Relationships
+  schema.relationships.forEach(rel => {
+    const fromTable = sanitize(schema.tables.find(t => t.id === rel.from.table)?.name || rel.from.table);
+    const toTable = sanitize(schema.tables.find(t => t.id === rel.to.table)?.name || rel.to.table);
+    
+    // Default to one-to-many if type is missing
+    let connector = '||--o{';
+    if (rel.type === 'one-to-one') connector = '||--||';
+    if (rel.type === 'many-to-many') connector = '}|--|{';
+    if (rel.type === 'one-to-many') connector = '||--o{';
+
+    mermaid += `    ${fromTable} ${connector} ${toTable} : ""\n`;
+  });
+
+  return mermaid;
+}
+
+/**
+ * Generates the full Markdown document.
+ */
+export function generateMarkdown(schema, modelName) {
+  let md = `# ${modelName} Data Model Definition\n\n`;
+
+  // Mermaid ER Diagram
+  md += '## ER Diagram\n\n';
+  md += '```mermaid\n';
+  md += generateMermaidER(schema);
+  md += '```\n\n';
+
+  // Domains
+  if (schema.domains && schema.domains.length > 0) {
+    md += '## Domains\n\n';
+    schema.domains.forEach(domain => {
+      md += `### ${domain.name}\n`;
+      if (domain.description) md += `${domain.description}\n\n`;
+      md += 'Associated Tables:\n';
+      domain.tables.forEach(tableId => {
+        const table = schema.tables.find(t => t.id === tableId);
+        md += `- ${table?.name || tableId}\n`;
+      });
+      md += '\n';
+    });
+  }
+
+  // Table Catalog
+  md += '## Table Catalog\n\n';
+  schema.tables.forEach(table => {
+    md += `### ${table.name} ${table.appearance?.icon || ''}\n`;
+    if (table.conceptual?.description) {
+      md += `**Description**: ${table.conceptual.description}\n\n`;
+    }
+    if (table.appearance?.type) {
+      md += `**Type**: ${table.appearance.type}\n\n`;
+    }
+
+    // Columns Table
+    if (table.columns && table.columns.length > 0) {
+      md += '#### Column Definitions\n\n';
+      md += '| ID | Logical Name | Type | Key | Description |\n';
+      md += '| --- | --- | --- | --- | --- |\n';
+      table.columns.forEach(col => {
+        const key = [
+          col.logical?.isPrimaryKey ? 'PK' : '',
+          col.logical?.isForeignKey ? 'FK' : ''
+        ].filter(Boolean).join(', ');
+        md += `| ${col.id} | ${col.logical?.name || '-'} | ${col.logical?.type || '-'} | ${key || '-'} | ${col.logical?.description || '-'} |\n`;
+      });
+      md += '\n';
+    }
+
+    // Sample Data
+    if (table.sampleData && table.sampleData.rows && table.sampleData.rows.length > 0) {
+      md += '#### Sample Data\n\n';
+      md += '| ' + table.sampleData.columns.join(' | ') + ' |\n';
+      md += '| ' + table.sampleData.columns.map(() => '---').join(' | ') + ' |\n';
+      table.sampleData.rows.slice(0, 5).forEach(row => {
+        md += '| ' + row.join(' | ') + ' |\n';
+      });
+      if (table.sampleData.rows.length > 5) {
+        md += `\n*(Showing 5 of ${table.sampleData.rows.length} rows)*\n`;
+      }
+      md += '\n';
+    }
+  });
+
+  return md;
+}
+
+/**
+ * Main export function called by the CLI
+ */
+export async function exportModel(paths, options) {
+  for (const inputPath of paths) {
+    const absolutePath = path.resolve(process.cwd(), inputPath);
+    if (!fs.existsSync(absolutePath)) {
+      console.warn(`  ⚠️ Warning: Path not found: ${inputPath}`);
+      continue;
+    }
+
+    const stats = fs.statSync(absolutePath);
+    const files = stats.isDirectory()
+      ? fs.readdirSync(absolutePath).filter(f => f.endsWith('.yaml') || f.endsWith('.yml')).map(f => path.join(absolutePath, f))
+      : [absolutePath];
+
+    for (const file of files) {
+      try {
+        const content = fs.readFileSync(file, 'utf8');
+        const data = yaml.load(content);
+        const schema = normalizeSchema(data);
+        const modelName = path.parse(file).name.charAt(0).toUpperCase() + path.parse(file).name.slice(1).replace(/[-_]/g, ' ');
+        const markdown = generateMarkdown(schema, modelName);
+
+        if (options.output) {
+          // If output is specified, we either append or use it as a directory/base
+          // For now, let's just write to the specified output file if it's one file, 
+          // or treat as a directory if multiple.
+          let outputPath = options.output;
+          if (files.length > 1 || stats.isDirectory()) {
+             // ensure directory exists
+             if (!fs.existsSync(outputPath)) fs.mkdirSync(outputPath, { recursive: true });
+             outputPath = path.join(outputPath, `${path.parse(file).name}.md`);
+          }
+          
+          fs.writeFileSync(outputPath, markdown, 'utf8');
+          console.log(`  ✅ Exported: ${path.relative(process.cwd(), file)} -> ${outputPath}`);
+        } else {
+          process.stdout.write(markdown + '\n');
+        }
+      } catch (e) {
+        console.error(`  ❌ Error exporting ${file}: ${e.message}`);
+      }
+    }
+  }
+}

package/src/index.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'url';
 import { startDevServer } from './dev.js';
 import { build } from './build.js';
 import { initProject } from './init.js';
+import { exportModel } from './export.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const VISUALIZER_PATH = path.resolve(__dirname, '../visualizer');
@@ -14,7 +15,7 @@ const program = new Command();
 program
   .name('modscape')
   .description('A YAML-driven data modeling visualizer CLI')
-  .version('0.1.2');
+  .version('0.3.0');
 
 program
   .command('init')
@@ -44,4 +45,13 @@ program
     build(paths, VISUALIZER_PATH, options.output);
   });
 
+program
+  .command('export')
+  .description('Export YAML models to Mermaid-compatible Markdown documentation')
+  .argument('<paths...>', 'paths to YAML model files or directories')
+  .option('-o, --output <path>', 'output file or directory')
+  .action((paths, options) => {
+    exportModel(paths, options);
+  });
+
 program.parse();

package/visualizer/README.md

@@ -0,0 +1,73 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+
+      // Remove tseslint.configs.recommended and replace with this
+      tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      tseslint.configs.stylisticTypeChecked,
+
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```

package/visualizer/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "visualizer",
+  "private": true,
+  "version": "0.3.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@radix-ui/react-scroll-area": "^1.2.10",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@radix-ui/react-tabs": "^1.1.13",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "js-yaml": "^4.1.1",
+    "lucide-react": "^0.575.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "reactflow": "^11.11.4",
+    "tailwind-merge": "^3.5.0",
+    "zustand": "^5.0.11"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "autoprefixer": "^10.4.27",
+    "eslint": "^9.39.1",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "globals": "^16.5.0",
+    "postcss": "^8.5.6",
+    "tailwindcss": "^3.4.19",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.48.0",
+    "vite": "^7.3.1"
+  }
+}

package/visualizer/public/favicon.svg

@@ -0,0 +1,24 @@
+<svg width="512" height="512" viewBox="0 0 512 512" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <!-- Background Round Rect -->
+  <rect width="512" height="512" rx="112" fill="#FFFFFF"/>
+  
+  <!-- Relationship Lines (Connecting in M-shape) -->
+  <path d="M120 350 L120 160 L256 310 L392 160 L392 350" 
+        stroke="#CBD5E1" stroke-width="24" stroke-linecap="round" stroke-linejoin="round"/>
+  
+  <!-- Colorful Rounded Rect Nodes -->
+  <!-- Left Bottom (Satellite) -->
+  <rect x="80" y="310" width="80" height="80" rx="16" fill="#8b5cf6"/>
+  
+  <!-- Left Top (Hub) -->
+  <rect x="80" y="120" width="80" height="80" rx="16" fill="#f59e0b"/>
+  
+  <!-- Center "V" (Fact) -->
+  <rect x="216" y="270" width="80" height="80" rx="16" fill="#ef4444"/>
+  
+  <!-- Right Top (Link) -->
+  <rect x="352" y="120" width="80" height="80" rx="16" fill="#10b981"/>
+  
+  <!-- Right Bottom (Dimension) -->
+  <rect x="352" y="310" width="80" height="80" rx="16" fill="#3b82f6"/>
+</svg>