Merge pull request #32 from ts-graphviz/improve-architecture-and-design-principles

Improve architecture and design principles

Author: kamiazya

docs/ts-graphviz/02-core-features/index.md renamed to docs/ts-graphviz/01-getting-started/04-core-features.md

@@ -26,7 +26,7 @@ Ensure that [Graphviz](https://graphviz.org/download/) is installed on your syst
 ### Converting DOT to an Image Stream
 
 ```typescript
-import { toStream } from '@ts-graphviz/adapter';
+import { toStream } from 'ts-graphviz/adapter';
 
 const dot = `
   digraph example {
@@ -46,7 +46,7 @@ await stream.pipeTo(Deno.stdout.writable);
 ### Writing DOT to an Image File
 
 ```typescript
-import { toFile } from '@ts-graphviz/adapter';
+import { toFile } from 'ts-graphviz/adapter';
 
 const dot = `
   digraph example {
@@ -63,7 +63,7 @@ await toFile(dot, './result.svg', { format: 'svg' });
 - **Output Formats**: Specify the desired output format (e.g., `svg`, `png`) through the options.
 - **Runtime Compatibility**: Designed to work seamlessly in both Node.js and Deno environments.
 
-## When to Use `@ts-graphviz/adapter`
+## When to Use `ts-graphviz/adapter` module
 
 - When you need to render your graphs into image files for visualization.
 - If you want to generate images dynamically within your application.

docs/ts-graphviz/01-getting-started/04-glossary.md renamed to docs/ts-graphviz/01-getting-started/09-glossary.md

@@ -1,9 +1,9 @@
 ---
-description: How to extend ts-graphviz with custom classes.
+description: How to extend ts-graphviz for advanced use cases.
 ---
 # Extending ts-graphviz
 
-`ts-graphviz` is designed to be extensible, allowing advanced users to customize and enhance the library's functionality to meet specific needs. This section covers how to extend the type system and create custom implementations.
+`ts-graphviz` is designed to be extensible, allowing intermediate users to customize and enhance the library's functionality to meet specific needs. This section covers how to extend the type system and create custom implementations.
 
 ## Creating Custom Classes
 
@@ -172,3 +172,58 @@ console.log(
   ),
 );
 ```
+
+---
+
+
+## Internal Package Overview
+
+For users interested in extending or customizing `ts-graphviz`, understanding the internal packages can be valuable. Below is an overview of the internal packages and how they can be used in advanced scenarios.
+
+
+### `@ts-graphviz/adapter`
+
+**Purpose**: Provides interfaces to execute Graphviz commands and convert DOT language strings into various output formats.
+
+**Usage**:
+
+- Convert DOT strings to streams or files.
+- Use in environments where you need to render graphs to images or other formats.
+
+:::note
+You can use either `@ts-graphviz/adapter` or `ts-graphviz/adapter` imports. The latter is maintained for backward compatibility.
+:::
+
+
+### `@ts-graphviz/ast`
+
+**Purpose**: Allows manipulation of the DOT language at the Abstract Syntax Tree (AST) level.
+
+**Usage**:
+
+- Parse DOT strings into AST nodes.
+- Manipulate and transform the AST programmatically.
+- Useful for advanced analysis or transformations of existing DOT code.
+
+:::note
+You can use either `@ts-graphviz/ast` or `ts-graphviz/ast` imports. The latter is maintained for backward compatibility.
+:::
+
+### `@ts-graphviz/common`
+
+**Purpose**: Centralizes Graphviz domain knowledge, providing type definitions, constants, and utilities. It is designed to handle use cases such as extending types.
+
+**Usage**:
+
+- Extend or customize types and attributes.
+- Ensure type safety when working with custom attributes.
+- Aggregate domain knowledge of Graphviz for consistent usage across packages.
+
+### `@ts-graphviz/core`
+
+**Purpose**: Contains the core implementations of the models and functions provided to users.
+
+**Usage**:
+
+- Use object-oriented APIs for fine-grained control over graph elements.
+- Extend classes for custom behaviors or attributes.

docs/ts-graphviz/03-practical-tutorials/01-flowchart.md renamed to docs/ts-graphviz/02-practical-tutorials/01-flowchart.md

@@ -3,11 +3,10 @@ description: Manipulate DOT graphs at the AST level with @ts-graphviz/ast.
 ---
 # Using Abstract Syntax Tree (AST)
 
-For advanced use cases, `@ts-graphviz/ast` provides an API to handle Abstract Syntax Trees (ASTs) of DOT language graphs.
+For advanced use cases, `ts-graphviz/ast` module provides an API to handle Abstract Syntax Trees (ASTs) of DOT language graphs.
 
 ## Available Functions
 
-
 The following functions are provided:
 
 - `fromModel`: Converts a **Model** to an **AST**.
@@ -27,7 +26,7 @@ The `toDot` function provided by the `ts-graphviz` package is a composition of `
 
 
 ```typescript
-import { parse } from '@ts-graphviz/ast';
+import { parse } from 'ts-graphviz/ast';
 
 const ast = parse(`
   digraph example {

docs/ts-graphviz/03-practical-tutorials/02-organization.md renamed to docs/ts-graphviz/02-practical-tutorials/02-organization.md

@@ -0,0 +1,7 @@
+{
+  "label": "Guides",
+  "link": {
+    "type": "generated-index",
+    "description": "Guides to help you understand ts-graphviz."
+  }
+}

docs/ts-graphviz/03-practical-tutorials/_category_.json renamed to docs/ts-graphviz/02-practical-tutorials/_category_.json

@@ -0,0 +1,34 @@
+---
+description: Design principles of ts-graphviz.
+---
+# Design Principles
+
+**ts-graphviz** is built around several key concepts that make it modular, extensible, and easy to use:
+
+1. **TypeScript-First Design & Type Definitions**
+
+    **ts-graphviz** is designed primarily with TypeScript in mind, offering strong typing and seamless integration with TypeScript projects. Comprehensive type definitions for DOT language elements enable type-safe interactions, enhancing development efficiency and reducing errors.
+
+1. **Object-Oriented API**
+
+    The library provides an object-oriented API for creating and manipulating graph elements such as graphs, nodes, and edges. This approach makes working with complex graph structures intuitive and efficient, leveraging familiar programming paradigms.
+
+1. **Modular Design**
+
+    **ts-graphviz** adopts a modular architecture, split into multiple packages, each serving a specific purpose. This modularity allows users to include only the functionality they need, improving maintainability, flexibility, and reducing unnecessary dependencies.
+
+1. **AST Support**
+
+    The library includes support for Abstract Syntax Trees (AST) for processing the DOT language. This enables parsing and generating DOT language while preserving its structure, facilitating programmatic manipulation and transformation of graphs.
+
+1. **Runtime Adapter**
+
+    To ensure compatibility across different runtime environments, **ts-graphviz** provides adapter functions for environments like Node.js and Deno. These adapters serve as a wrapper, enabling seamless execution of Graphviz commands regardless of the underlying platform.
+
+1. **Extensibility**
+
+    Designed with extensibility in mind, **ts-graphviz** allows users to extend its functionality with custom implementations for specific use cases. This flexibility supports a wide range of applications and integration scenarios.
+
+1. **Multi-Paradigm Support**
+
+    The library accommodates various programming paradigms, including Object-Oriented Programming and Declarative Programming. Users can choose the style that best suits their needs, making the library versatile and adaptable.

docs/ts-graphviz/03-practical-tutorials/imgs/Flowchart.svg renamed to docs/ts-graphviz/02-practical-tutorials/imgs/Flowchart.svg

@@ -0,0 +1,60 @@
+---
+description: Package architecture of ts-graphviz.
+---
+# Package Architecture
+
+**ts-graphviz** consists of several packages, each with a specific role:
+
+- **`ts-graphviz`** (Main Package): Provides high-level APIs for creating and manipulating graphs, suitable for most users.
+
+- **`@ts-graphviz/core`**: Contains core implementations of models and functions, used internally and available for advanced use.
+
+- **`@ts-graphviz/common`**: Aggregates Graphviz domain knowledge, providing type definitions, constants, and utilities. Supports use cases like extending custom types and attributes.
+
+- **`@ts-graphviz/ast`**: Offers tools for parsing, manipulating, and generating DOT language graphs at the AST level.
+
+- **`@ts-graphviz/adapter`**: Executes Graphviz commands in various runtime environments (Node.js, Deno) and converts DOT strings to images.
+
+- **`@ts-graphviz/react`**: Allows defining graphs using React's declarative UI paradigm, expressing DOT language models with JSX.
+
+## Exposing Internal Modules as Submodules
+
+**ts-graphviz** publishes some of its internal modules as submodules within the main package. Specifically, the following import paths are available to access these internal modules:
+
+- **`ts-graphviz/ast`** or **`@ts-graphviz/ast`**
+- **`ts-graphviz/adapter`** or **`@ts-graphviz/adapter`**
+
+This allows users to choose the module import style that best fits their project's needs. By using the `ts-graphviz/<module-name>` style, you can limit your dependencies to the `ts-graphviz` library itself, with internal packages (e.g., `@ts-graphviz/adapter`, `@ts-graphviz/ast`) being managed centrally by the `ts-graphviz` package. On the other hand, using the `@ts-graphviz/<module-name>` style enables you to manage dependencies on a per-module basis, allowing you to selectively install specific modules as needed.
+
+:::tip Managing Dependencies When Choosing Import Paths
+
+When using package managers that enforce strict dependency management (e.g., pnpm), the choice of import path can significantly impact how dependencies are handled. Consider the following points:
+
+- **Using `ts-graphviz/<module-name>` Style**:
+  - **Advantages**: Limits dependencies to the `ts-graphviz` library itself, with internal packages (e.g., `@ts-graphviz/adapter`, `@ts-graphviz/ast`) being managed centrally by the `ts-graphviz` package. This prevents dependency conflicts and ensures that stable versions recommended by the library are used.
+  - **Recommended Scenarios**: When you want to minimize dependencies or when the internal packages managed by `ts-graphviz` do not have specific version requirements.
+
+- **Using `@ts-graphviz/<module-name>` Style**:
+  - **Advantages**: Allows you to manage dependencies on a per-module basis, installing only the specific modules you need, which can help keep your application lightweight.
+  - **Caveats**: Requires you to manage internal dependencies (e.g., `@ts-graphviz/adapter`, `@ts-graphviz/ast`) separately within your package manager. This can complicate version management.
+  - **Recommended Scenarios**: When you need to use specific modules only or require detailed control over your dependencies.
+
+**Summary**:
+- If you prefer **simple dependency management**, use the `ts-graphviz/<module-name>` style.
+- If you require **fine-grained control over dependencies** or only need specific modules, opt for the `@ts-graphviz/<module-name>` style.
+
+This approach allows you to manage dependencies in a way that best suits your project's requirements.
+:::
+
+
+The relationships between packages can be visualized as follows:
+
+![Package dependency graph showing relationships between ts-graphviz packages and their dependencies](./img/dependency-graph.svg)
+
+This modular architecture ensures:
+
+- **Maintainability**: Individual packages can be maintained and updated without affecting others.
+
+- **Flexibility**: Users can select only the packages needed for their specific use cases.
+
+- **Extensibility**: Facilitates the addition of new features or packages as the library evolves.

docs/ts-graphviz/03-practical-tutorials/imgs/Organization.svg renamed to docs/ts-graphviz/02-practical-tutorials/imgs/Organization.svg

@@ -0,0 +1,49 @@
+---
+description: Versioning policy for ts-graphviz.
+---
+# Versioning Policy
+
+## Overview
+
+**ts-graphviz** follows [**Semantic Versioning 2.0**](https://semver.org/) to ensure consistency and predictability. This policy clarifies how we manage breaking changes, especially those related to runtime support, and what users can expect when using **ts-graphviz**.
+
+## Semantic Versioning
+
+Version numbers are formatted as **MAJOR.MINOR.PATCH**, with changes classified as follows:
+
+- **MAJOR**: Introduces backward-incompatible changes.
+- **MINOR**: Adds functionality in a backward-compatible manner.
+- **PATCH**: Fixes bugs in a backward-compatible manner.
+
+---
+
+## Exceptions: TypeScript Version Updates
+
+There are scenarios where **ts-graphviz** may deviate from strict Semantic Versioning:
+
+- **TypeScript Definitions**: Breaking changes to TypeScript type definitions may occur between minor versions due to:
+  - TypeScript introducing breaking changes in its own minor updates.
+  - Adopting features available only in newer TypeScript versions, which may raise the minimum required TypeScript version.
+
+:::tip
+For TypeScript projects, we recommend pinning the **ts-graphviz** minor version to control upgrade timing and compatibility testing.
+:::
+
+---
+
+## Information Sharing
+
+We are committed to transparent communication regarding our versioning and support policies:
+
+- **Documentation and Release Notes**: All changes to the versioning policy and support levels will be documented in our official documentation and detailed in release notes.
+- **Community Engagement**: Users are encouraged to subscribe to updates or follow our repositories to stay informed about the latest developments.
+
+---
+
+## Migration Support
+
+To assist users in transitioning between versions, especially when breaking changes occur:
+
+- **Migration Guides**: We provide comprehensive migration guides outlining steps to upgrade to new major versions.
+- **Code Examples**: Examples are included to demonstrate how to adapt code to accommodate changes.
+- **Support Channels**: Users can seek assistance through community forums, issue trackers, or other support channels if they encounter difficulties during migration.

docs/ts-graphviz/04-intermediate-topics/01-rendering-graphs-to-images.md renamed to docs/ts-graphviz/03-guides/01-rendering-graphs-to-images.md

@@ -0,0 +1,44 @@
+---
+description: Supported environments for ts-graphviz.
+draft: true
+---
+# Supported Environments
+
+To provide clarity on the environments in which **ts-graphviz** operates, we have categorized support levels:
+
+## Support Levels
+
+### Tier 1: Full Support
+
+- **Definition**: Environments that are fully supported, with comprehensive automated testing and maintenance.
+- **Environments**:
+  - **Node.js**: All active Long-Term Support (LTS) versions.
+- **Details**:
+  - We run automated tests on all LTS versions of Node.js.
+  - Full compatibility and performance are ensured.
+  - Critical issues are prioritized for fixes.
+
+### Tier 2: Active Support
+
+- **Definition**: Environments that receive active support with limited automated testing.
+- **Environments**:
+  - **Deno**: Latest stable version.
+  - **Node.js Current Release**: The latest Node.js release outside the LTS schedule.
+- **Details**:
+  - Automated tests are conducted on the latest version of Deno to confirm functionality.
+  - Compatibility is maintained, and issues are addressed.
+
+### Tier 3: Community Support
+
+- **Definition**: Environments that are not officially tested but are supported on a best-effort basis.
+- **Environments**:
+  - **Modern Browsers**: Latest versions of major browsers, including:
+    - Google Chrome
+    - Mozilla Firefox
+    - Microsoft Edge
+    - Apple Safari
+- **Details**:
+  - Installation methods are provided.
+  - No automated testing is performed.
+  - Issues reported by users will be addressed.
+  - Targeting the latest versions ensures compatibility with modern web standards.

docs/ts-graphviz/04-intermediate-topics/02-using-with-react.md renamed to docs/ts-graphviz/03-guides/02-using-with-react.md

@@ -0,0 +1,34 @@
+---
+description: Security policies for ts-graphviz.
+---
+# Security Policies
+
+## Purpose and Importance
+
+In today's software development landscape, **Open Source Software (OSS)** plays an indispensable role in building applications. According to the **Open Source Security Foundation (OpenSSF)**, **70% to 90%** of modern applications consist of OSS components[^1], and the complexity of their dependencies is increasing daily.
+
+[^1]: Behlendorf, B. (2022, May 11). *Brian Behlendorf Testifies to Congress on Open Source Software Security* (original in English). The Linux Foundation. Retrieved from [https://www.linuxfoundation.org/blog/blog/lf/brian-behlendorf-testifies-open-source-software-security](https://www.linuxfoundation.org/blog/blog/lf/brian-behlendorf-testifies-open-source-software-security)
+
+### The Impact and Responsibility of ts-graphviz
+
+**ts-graphviz** is a widely used library with over 2 million downloads per month, impacting a broad range of applications. Even users who do not directly interact with ts-graphviz are affected through software that depends on it.
+
+> ![Dependency](https://imgs.xkcd.com/comics/dependency.png)
+>
+> *An illustration of software dependencies (Source: [xkcd.com/2347](https://xkcd.com/2347/))*
+
+This illustration highlights how modern software relies on numerous underlying components.
+
+**Ensuring the security of ts-graphviz is crucial because vulnerabilities can cascade through dependencies, potentially affecting countless applications.**
+
+## Commitment to Security
+
+ts-graphviz is committed to more than just providing secure source code. We implement **comprehensive security measures** that consider the **entire software supply chain**. This dedication ensures that users can confidently adopt ts-graphviz, knowing it contributes to building secure and reliable applications.
+
+## Software Supply Chain Security
+
+Recognizing that modern applications are heavily dependent on open-source software, we implement practices that safeguard against vulnerabilities throughout the dependency chain.
+
+## Reporting Vulnerabilities
+
+We encourage users and security researchers to report any vulnerabilities or security concerns. Prompt reporting allows us to address issues swiftly, maintaining the integrity and security of the library.

docs/ts-graphviz/11-advanced-usage/02-extending-ts-graphviz.md renamed to docs/ts-graphviz/03-guides/03-extending-ts-graphviz.md

@@ -1,8 +1,7 @@
 {
-  "label": "Advanced Usage",
+  "label": "Advanced Topics",
   "link": {
     "type": "generated-index",
     "description": "Advanced topics to help you understand the inner workings of ts-graphviz."
   }
 }
-