Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/polina-c/layerlens

Last synced: about 2 months ago
JSON representation

Host: GitHub
URL: https://github.com/polina-c/layerlens
Owner: polina-c
License: apache-2.0
Created: 2023-01-14T03:35:25.000Z (almost 2 years ago)
Default Branch: main
Last Pushed: 2024-09-13T01:12:58.000Z (3 months ago)
Last Synced: 2024-10-22T15:59:27.178Z (2 months ago)
Language: Dart
Size: 101 KB
Stars: 19
Watchers: 2
Forks: 3
Open Issues: 3
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE

Awesome Lists containing this project

README

        # LayerLens

[![pub package](https://img.shields.io/pub/v/layerlens.svg)](https://pub.dev/packages/layerlens)

Generates a dependency diagram in every folder of your Dart or Flutter

package as [Mermaid `flowchart`](https://mermaid.js.org/syntax/flowchart.html) documents.

Alerts on cyclic dependencies.

NOTE: LayerLens shows inside-package dependencies. For cross-package dependencies use `flutter pub deps`.



## Configure layerlens

### Configure command globally

1. Run `dart pub global activate layerlens`

2. Verify you can run `layerlens`. If you get `command not found`, make sure

   your path [contains pub cache](https://dart.dev/tools/pub/cmd/pub-global#running-a-script-from-your-path).

### Configure command for a package

1. Add `layerlens: ` to the section `dev_dependencies` in the package's pubspec.yaml.

2. Run `dart pub get` or `flutter pub get` for the package.

### Configure IDE

To see the diagrams in your IDE:

- **VSCode**: install `Markdown Preview Mermaid Support` extension

- **Android Studio**: enable the "Mermaid" extension in the

  [Markdown language settings](https://www.jetbrains.com/help/idea/markdown-reference.html)

## Generate diagrams

1. Run command:

- With global configuration: `layerlens --path `

- With package configuration: `dart run layerlens` in the package root

2. Find the generated file DEPENDENCIES.md in each source folder, where

   libraries or folders depend on each other.

3. In VSCode, right click DEPENDENCIES.md and select 'Open Preview'

## CI: re-generate on every GitHub push

1. Add a `dev_dependency` to https://pub.dev/packages/layerlens

2. Copy the content of [run-layerlens.yaml](https://github.com/polina-c/layerlens/blob/main/.github/workflows/run-layerlens.yaml)

   to `.github/workflows`.

## Alert on circular references

You may want to avoid circular references, because without circles:

1. Code is easier to maintain

2. Chance of memory leaks is smaller

3. Treeshaking (i.e. not including non-used code into build) is more efficient

4. Incremental build is faster

LayerLens marks inverted dependencies (dependencies that create circles) with '!'.

Also you can add command `dart run layerlens --fail-on-cycles` to the repo's pre-submit bots.

## Build filters

If you want to generate the `DEPENDENCIES.md` only for a specific folders, you can use `--build-filter` option and you should use [glob](https://pub.dev/packages/glob) syntax. For example, to generate the diagram only for the root `lib/` folder, you run following `dart run layerlens --build-filter "lib"`.

You can specify multiple build filters . The mechanism is inspired by `--build-filter` in Dart's [`build_runner`](https://github.com/dart-lang/build/blob/master/docs/partial_builds.md). For example, to run the layerlens for root `lib/` and it's subfolder `lib/subfolder1` run `layerlens --build-filter "lib" --build-filter "lib/subfolder1"`. To generate the entire subtree for a given subfolder you can run following: `layerlens --build-filter "lib/subfolder1" --build-filter "lib/subfolder1/**"`

## Supported languages

While layerlens concepts are language agnostic, for now only `dart` is supported.

Please [submit an issue](https://github.com/polina-c/layerlens/issues/new), if you want other language to be added.

## Contribute to layerlens

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for details.

## License

Apache 2.0; see [`LICENSE`](LICENSE) for details.

## Disclaimer

This project is not an official Google project. It is not supported by

Google and Google specifically disclaims all warranties as to its quality,

merchantability, or fitness for a particular purpose.