Metadata-Version: 2.1
Name: aws-prototyping-sdk.cdk-graph-plugin-diagram
Version: 0.12.19
Summary: @aws-prototyping-sdk/cdk-graph-plugin-diagram
Home-page: https://github.com/aws/aws-prototyping-sdk
Author: AWS APJ COPE<apj-cope@amazon.com>
License: Apache-2.0
Project-URL: Source, https://github.com/aws/aws-prototyping-sdk
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: JavaScript
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Typing :: Typed
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved
Requires-Python: ~=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aws-cdk-lib (<3.0.0,>=2.50.0)
Requires-Dist: aws-prototyping-sdk.aws-arch (<1.0.0)
Requires-Dist: aws-prototyping-sdk.cdk-graph (<1.0.0)
Requires-Dist: constructs (<11.0.0,>=10.1.162)
Requires-Dist: jsii (<2.0.0,>=1.71.0)
Requires-Dist: projen (<0.66.0,>=0.65.26)
Requires-Dist: publication (>=0.0.3)
Requires-Dist: typeguard (~=2.13.3)

## Diagram Plugin - Cdk Graph

`@aws-prototyping-skd/cdk-graph-plugin-diagram`

![experimental](https://img.shields.io/badge/stability-experimental-orange.svg)
![alpha](https://img.shields.io/badge/version-alpha-red.svg) \
[![API Documentation](https://img.shields.io/badge/view-API_Documentation-blue.svg)](https://aws.github.io/aws-prototyping-sdk/typescript/cdk-graph-plugin-diagram/index.html)
[![Source Code](https://img.shields.io/badge/view-Source_Code-blue.svg)](https://github.com/aws/aws-prototyping-sdk/tree/mainline/packages/cdk-graph-plugin-diagram)

This plugin generates diagrams utilizing the [cdk-graph](https://aws.github.io/aws-prototyping-sdk/typescript/cdk-graph/index.html) framework.

> More comprehensive documentation to come as this package stabilizes.

> **Disclaimer:** This is the first **cdk graph** plugin, it is highly *experimental*, and subject to major refactors as we gain feedback from the community.

| | |
| --- | --- |
| <img src="docs/examples/default.png" width="300" /> | <img src="docs/examples/dark.png" width="300" /> |

### Quick Start

```python
// bin/app.ts

// Must wrap cdk app with async IIFE function to enable async cdk-graph report
(async () => {
  const app = new App();
  // ... add stacks, etc
  const graph = new CdkGraph(app, {
    plugins: [new CdkGraphDiagramPlugin()],
  });

  app.synth();

  // async cdk-graph reporting hook
  await graph.report();
})

// => cdk.out/diagram.dot
// => cdk.out/diagram.svg
// => cdk.out/diagram.png
```

> This plugin currently only supports `async report()` generation following the above example. **Make sure to wrap the cdk app with *async IIFE*.**

### Supported Formats

| Format | Status | Extends | Provider |
| --- | --- | --- | --- |
| [DOT](https://graphviz.org/docs/outputs/canon/) | ![beta](https://img.shields.io/badge/status-beta-cyan.svg) | - | [Graphviz](docs/graphviz/README.md)
| [SVG](https://graphviz.org/docs/outputs/svg/) | ![beta](https://img.shields.io/badge/status-beta-cyan.svg) | [DOT](https://graphviz.org/docs/outputs/canon/) | [Graphviz](docs/graphviz/README.md)
| [PNG](https://graphviz.org/docs/outputs/png/) | ![beta](https://img.shields.io/badge/status-beta-cyan.svg) | [SVG](https://graphviz.org/docs/outputs/canon/) | [Graphviz](docs/graphviz/README.md)

---


### Diagram Providers

| Provider | Status | Formats |
| --- | --- | --- |
| [Graphviz](docs/graphviz/README.md) | ![alpha](https://img.shields.io/badge/status-alpha-orange.svg) | [DOT](https://graphviz.org/docs/outputs/canon/), [SVG](https://graphviz.org/docs/outputs/svg/), [PNG](https://graphviz.org/docs/outputs/png/) |
| [Drawio](docs/drawio/README.md) | ![design](https://img.shields.io/badge/status-design-tan.svg) | *TBD: very early stage design and development* |

---


### Configuration

See [API Documentation](https://aws.github.io/aws-prototyping-sdk/typescript/cdk-graph-plugin-diagram/index.html) for details, and look in [unit tests](https://github.com/aws/aws-prototyping-sdk/tree/mainline/packages/cdk-graph-plugin-diagram/test/graphviz) for more examples.

#### Example Configurations (expand below)

##### **Presets**

<details>
<summary>Preset: compact</summary>

[<img src="docs/examples/compact.png" height="200" />](docs/examples/compact.png)

```python
{
  name: "compact",
  title: "Compact Diagram",
  filterPlan: {
    preset: FilterPreset.COMPACT,
  },
},
```

</details><details>
<summary>Preset: verbose</summary>

[<img src="docs/examples/verbose.png" height="200" />](docs/examples/verbose.png)

```python
{
  name: "verbose",
  title: "Verbose Diagram",
  format: DiagramFormat.PNG,
  ignoreDefaults: true,
},
```

</details>

##### **Focus**

<details>
<summary>Focus: hoist</summary>

[<img src="docs/examples/focus.png" height="200" />](docs/examples/focus.png)

```python
{
  name: "focus",
  title: "Focus Lambda Diagram (non-extraneous)",
  filterPlan: {
    focus: (store) =>
      store.getNode(getConstructUUID(app.stack.lambda)),
    preset: FilterPreset.NON_EXTRANEOUS,
  },
  ignoreDefaults: true,
},
```

</details><details>
<summary>Focus: no hoist</summary>

[<img src="docs/examples/focus-nohoist.png" height="200" />](docs/examples/focus-nohoist.png)

```python
{
  name: "focus-nohoist",
  title: "Focus WebServer Diagram (noHoist, verbose)",
  filterPlan: {
    focus: {
      node: (store) =>
        store.getNode(getConstructUUID(app.stack.webServer)),
      noHoist: true,
    },
  },
  ignoreDefaults: true,
},
```

</details>

##### **Filters**

<details>
<summary>Filter: Include specific cfn resource types</summary>

[<img src="docs/examples/filter-cfntype-include.png" height="200" />](docs/examples/filter-cfntype-include.png)

```python
{
  name: "includeCfnType",
  title: "Include CfnType Diagram (filter)",
  filterPlan: {
    filters: [
      Filters.includeCfnType([
        aws_arch.CfnSpec.ServiceResourceDictionary.EC2.Instance,
        /AWS::Lambda::Function.*/,
        "AWS::IAM::Role",
      ]),
      Filters.compact(),
    ],
  },
},
```

</details><details>
<summary>Filter: Exclude specific cfn resource types</summary>

[<img src="docs/examples/filter-cfntype-exclude.png" height="200" />](docs/examples/filter-cfntype-exclude.png)

```python
{
  name: "excludeCfnType",
  title: "Exclude CfnType Diagram (filter)",
  filterPlan: {
    filters: [
      Filters.excludeCfnType([
        /AWS::EC2::VPC.*/,
        aws_arch.CfnSpec.ServiceResourceDictionary.IAM.Role,
      ]),
      Filters.compact(),
    ],
  },
},
```

</details><details>
<summary>Filter: Include specific graph node types</summary>

[<img src="docs/examples/filter-nodetype-include.png" height="200" />](docs/examples/filter-nodetype-include.png)

```python
{
  name: "includeNodeType",
  title: "Include NodeType Diagram (filter)",
  filterPlan: {
    filters: [
      Filters.includeNodeType([
        NodeTypeEnum.STACK,
        NodeTypeEnum.RESOURCE,
      ]),
      Filters.compact(),
    ],
  },
},
```

</details><details>
<summary>Filter: Include specific graph node types</summary>

[<img src="docs/examples/filter-nodetype-include.png" height="200" />](docs/examples/filter-nodetype-include.png)

```python
{
  name: "includeNodeType",
  title: "Include NodeType Diagram (filter)",
  filterPlan: {
    filters: [
      Filters.includeNodeType([
        NodeTypeEnum.STACK,
        NodeTypeEnum.RESOURCE,
      ]),
      Filters.compact(),
    ],
  },
},
```

</details><details>
<summary>Filter: Exclude specific graph node types</summary>

[<img src="docs/examples/filter-nodetype-exclude.png" height="200" />](docs/examples/filter-nodetype-exclude.png)

```python
{
  name: "excludeNodeType",
  title: "Exclude NodeType Diagram (filter)",
  filterPlan: {
    filters: [
      Filters.excludeNodeType([
        NodeTypeEnum.NESTED_STACK,
        NodeTypeEnum.CFN_RESOURCE,
        NodeTypeEnum.OUTPUT,
        NodeTypeEnum.PARAMETER,
      ]),
      Filters.compact(),
    ],
  },
},
```

</details>

##### **Themes**

<details>
<summary>Theme: Dark</summary>

[<img src="docs/examples/dark.png" height="200" />](docs/examples/dark.png)

```python
{
  name: "Dark",
  title: "Dark Theme Diagram",
  theme: theme,
},
```

</details><details>
<summary>Theme: Dark - render service icons</summary>

[<img src="docs/examples/dark-services.png" height="200" />](docs/examples/dark-services.png)

```python
{
  name: "dark-services",
  title: "Dark Theme Custom Diagram",
  theme: {
    theme: theme,
    rendering: {
      resourceIconMin: GraphThemeRenderingIconTarget.SERVICE,
      resourceIconMax: GraphThemeRenderingIconTarget.CATEGORY,
      cfnResourceIconMin: GraphThemeRenderingIconTarget.DATA,
      cfnResourceIconMax: GraphThemeRenderingIconTarget.RESOURCE,
    },
  },
},
```

</details>
<details>
<summary>Theme: Dark - verbose</summary>

[<img src="docs/examples/dark-verbose.png" height="200" />](docs/examples/dark-verbose.png)

```python
{
  name: "dark-verbose",
  title: "Dark Theme Verbose Diagram",
  ignoreDefaults: true,
  theme: theme,
},
```

</details>---


### Next Steps

* [ ] Battle test in the wild and get community feedback
* [ ] Improve image coverage and non-image node rendering
* [ ] Add drawio support
* [ ] Add common filter patterns and helpers
* [ ] Enable generating diagrams outside of synthesis process (maybe CLI)
* [ ] Implement interactive diagram, with potential for dynamic filtering and config generation
* [ ] Support using interactive diagram as config generator for other plugins (or as separate plugin that depends on this)

---


Inspired by [cdk-dia](https://github.com/pistazie/cdk-dia) and [cfn-dia](https://github.com/mhlabs/cfn-diagram) with ❤️


