[FEATURE] Add support for generating "elk" layout diagrams.

README.md

@@ -27,17 +27,17 @@ Specifically, LayerLens:
 1. Restricts each diagram to the content of a single directory,
 so that every directory has its own diagram.
 
-3. For each directory treats immediate sub-directories and files as equal elements,
+1. For each directory treats immediate sub-directories and files as equal elements,
 and shows dependencies between these elements as a directed graph.
 
 As result:
 
 1. Each directory diagram is simple. It does not contain (1) any internal details of directories or files, and (2)
 any details of code outside the directory.
 
-2. All diagrams together are enough to detect cycles in application.
+1. All diagrams together are enough to detect cycles in application.
 
-<img width="536" alt="Screenshot 2023-01-14 at 9 45 33 PM" src="https://user-images.githubusercontent.com/12115586/212524921-5221785f-692d-4464-a230-0f620434e2c5.png">
+<img width="536" alt="Example output" src="./screenshots/DEPENDENCIES.png">
 
 ## Configure layerlens
 
@@ -85,8 +85,8 @@ To see the diagrams in your IDE:
 
 Make your pre-submit bots failing in case of issues, using flags:
 
-* `--fail-on-cycles`: fail if there are dependency cycles
-* `--fail-if-changed`: fail if the generated diagrams has changed
+- `--fail-on-cycles`: fail if there are dependency cycles
+- `--fail-if-changed`: fail if the generated diagrams has changed
 
 ### Re-generate on every GitHub push
 
@@ -102,11 +102,21 @@ formatted as [glob](https://pub.dev/packages/glob) syntax.
 
 For example, to generate the diagrams:
 
-* only for the root `lib/` folder: `dart run layerlens --only "lib"`
-* only for the root `lib/` folder: `dart run layerlens --only "lib"`
-* for all folders except `l10n/`: `dart run layerlens --except "l10n"`
-* only for root `lib/` and it's subfolder: run `layerlens --only "lib" --only "lib/subfolder1"`
-* for the entire subtree for a given subfolder: `layerlens --only "lib/subfolder1" --only "lib/subfolder1/**"`
+- only for the root `lib/` folder: `dart run layerlens --only "lib"`
+- only for the root `lib/` folder: `dart run layerlens --only "lib"`
+- for all folders except `l10n/`: `dart run layerlens --except "l10n"`
+- only for root `lib/` and it's subfolder: run `layerlens --only "lib" --only "lib/subfolder1"`
+- for the entire subtree for a given subfolder: `layerlens --only "lib/subfolder1" --only "lib/subfolder1/**"`
+
+## Alternative layout engines
+
+For more complex dependency graphs, you may want to use the [`elk` layout engine](https://mermaid.js.org/syntax/flowchart.html#renderer) in your Mermaid diagrams:
+
+|`--layout=dagre` (default)|`--layout=elk`|
+|:---:|:---:|
+|![Dagre layout engine](./screenshots/DEFAULT%20LAYOUT.png)|![Elk Layout Engine](./screenshots/ELK%20LAYOUT.png)|
+
+>*Note: Some VSCode Markdown plugins do not support the `elk` engine yet, and will not produce different outputs to the default!.*
 
 ## Supported languages
 

bin/layerlens.dart

@@ -16,11 +16,15 @@ import 'package:args/args.dart';
 import 'package:glob/glob.dart';
 import 'package:layerlens/layerlens.dart';
 import 'package:layerlens/src/cli.dart';
+import 'package:layerlens/src/generator.dart';
 import 'package:layerlens/src/model.dart';
 
 const _filterDocLink =
     'https://github.com/polina-c/layerlens/blob/main/README.md#filter';
 
+const _mermaidLayoutDocLink =
+    'https://mermaid.js.org/syntax/flowchart.html#renderer';
+
 void main(List<String> args) async {
   final parser = ArgParser()
     ..addFlag(
@@ -66,6 +70,18 @@ void main(List<String> args) async {
       CliOptions.except.name,
       help: 'Which folders to exclude from diagram generation. Use glob syntax.'
           '\n$_filterDocLink',
+    )
+    ..addOption(
+      CliOptions.layout.name,
+      help: 'Layout engine to use for Mermaid diagrams.'
+          '\nCertain markdown preview plugins may not support all layout engines.'
+          '\n$_mermaidLayoutDocLink.',
+      defaultsTo: 'dagre',
+      allowed: ['elk', 'dagre'],
+      allowedHelp: {
+        'dagre': 'Mermaid\'s default layout engine.',
+        'elk': 'ELK layout engine (experimental).',
+      },
     );
 
   late final ArgResults parsedArgs;
@@ -96,12 +112,20 @@ void main(List<String> args) async {
     );
   }
 
+  // Prepare Mermaid options, extendable.
+  List<MermaidOption> mermaidOptions() {
+    return [
+      (key: 'layout', value: parsedArgs[CliOptions.layout.name]),
+    ];
+  }
+
   final generatedDiagrams = await generateLayering(
     rootDir: parsedArgs[CliOptions.path.name],
     packageName: parsedArgs[CliOptions.package.name],
     failOnCycles: parsedArgs[CliOptions.failOnCycles.name] as bool,
     failIfChanged: parsedArgs[CliOptions.failIfChanged.name] as bool,
     filter: filter(),
+    mermaidOptions: mermaidOptions(),
   );
   print(
     'Generated $generatedDiagrams diagrams. Check files DEPS.md in source folders.',

lib/layerlens.dart

@@ -30,6 +30,7 @@ Future<int> generateLayering({
   required bool failOnCycles,
   required bool failIfChanged,
   required Filter filter,
+  required List<MermaidOption> mermaidOptions,
   ExitCallback exitFn = exit,
 }) async {
   final deps = await collectDeps(
@@ -43,5 +44,6 @@ Future<int> generateLayering({
     filter: filter,
     failIfChanged: failIfChanged,
     failOnCycles: failOnCycles,
+    mermaidOptions: mermaidOptions,
   ).generateFiles();
 }

lib/src/analyzer.dart

@@ -49,7 +49,7 @@ class Analyzer {
 
   /// Recursively adds file, and folders for the file path, to the
   /// source tree.
-  _propagateFileToFolder(
+  void _propagateFileToFolder(
     SourceFolder folder,
     SourceFile file,
     List<String> path,

lib/src/cli.dart

@@ -23,6 +23,7 @@ enum CliOptions {
   help('help'),
   failOnCycles('fail-on-cycles'),
   failIfChanged('fail-if-changed'),
+  layout('layout'),
   ;
 
   const CliOptions(this.name);

lib/src/code_parser.dart

@@ -94,7 +94,7 @@ class _DepsCollector extends RecursiveAstVisitor
     return super.visitExportDirective(node);
   }
 
-  _collectDep(Dependency? dependency) {
+  void _collectDep(Dependency? dependency) {
     if (dependency == null) return;
 
     if (!collectedDeps.containsKey(dependency.consumer)) {

lib/src/generator.dart

@@ -19,23 +19,32 @@ import 'package:path/path.dart' as path;
 import 'cli.dart';
 import 'model.dart';
 
+typedef MermaidOption = ({String key, String value});
+
 class MdGenerator {
   final String rootDir;
   final SourceFolder sourceFolder;
   final Filter filter;
   final bool failIfChanged;
   final bool failOnCycles;
   final ExitCallback? exitFn;
+  final List<MermaidOption> mermaidOptions;
 
   MdGenerator({
     required this.rootDir,
     required this.sourceFolder,
     required this.filter,
     required this.failIfChanged,
     required this.failOnCycles,
+    required this.mermaidOptions,
     this.exitFn,
   });
 
+  /// Default Mermaid options, filtered before content is generated.
+  static const List<MermaidOption> _defaultMermaidOptions = [
+    (key: 'layout', value: 'dagre'),
+  ];
+
   Future<int> generateFiles() async {
     return await _generateRecursive(sourceFolder);
   }
@@ -69,7 +78,7 @@ class MdGenerator {
       return false;
     }
 
-    final diagram = content(folder);
+    final diagram = content(folder, mermaidOptions);
     if (diagram == null) {
       await deleteDiagramFile(path: filePath, failIfExists: failIfChanged);
       return false;
@@ -86,7 +95,10 @@ class MdGenerator {
     return true;
   }
 
-  static String? content(SourceFolder folder) {
+  static String? content(
+    SourceFolder folder,
+    List<MermaidOption> mermaidOptions,
+  ) {
     final items = <String>[];
     for (final consumer in folder.children.values) {
       for (final dependency in consumer.siblingDependencies) {
@@ -100,6 +112,9 @@ class MdGenerator {
 
     items.sort();
     final result = StringBuffer();
+    final filteredOptions = mermaidOptions
+        .where((option) => !_defaultMermaidOptions.contains(option))
+        .toList();
 
     result.writeln('<!---');
     result.writeln('Generated by https://github.com/polina-c/layerlens');
@@ -109,6 +124,16 @@ class MdGenerator {
     result.writeln('-->');
     result.writeln('');
     result.writeln('```mermaid');
+
+    if (filteredOptions.isNotEmpty) {
+      result.writeln('---');
+      result.writeln('config:');
+      for (final option in filteredOptions) {
+        result.writeln('  ${option.key}: ${option.value}');
+      }
+      result.writeln('---');
+    }
+
     result.writeln('flowchart TD;');
     result.writeln(items.join('\n'));
     result.writeln('```');

lib/src/layering.dart

@@ -34,13 +34,7 @@ void assignLayers(SourceFolder folder) {
   folder.totalInversions = folder.localInversions + inversionsInSubfolders;
 }
 
-// TODO(polina-c): convert to record.
-class _NodesAndValue {
-  final Set<SourceNode> nodes;
-  final int value;
-
-  _NodesAndValue(this.nodes, this.value);
-}
+typedef _NodesAndValue = ({Set<SourceNode> nodes, int value});
 
 void _assignLocalLayerToChildren(SourceFolder folder) {
   // Items without layer.
@@ -98,10 +92,7 @@ _NodesAndValue _withMinConsumersWl(Set<SourceNode> nodes) {
 
   final minNumber = byNumberOfConsumersWl.keys.reduce((v, e) => min(v, e));
 
-  return _NodesAndValue(
-    byNumberOfConsumersWl[minNumber]!,
-    minNumber,
-  );
+  return (nodes: byNumberOfConsumersWl[minNumber]!, value: minNumber);
 }
 
 _NodesAndValue _withMaxDependenciesWl(Set<SourceNode> nodes) {
@@ -124,8 +115,5 @@ _NodesAndValue _withMaxDependenciesWl(Set<SourceNode> nodes) {
 
   final maxNumber = byNumberOfDependenciesWl.keys.reduce((v, e) => max(v, e));
 
-  return _NodesAndValue(
-    byNumberOfDependenciesWl[maxNumber]!,
-    maxNumber,
-  );
+  return (nodes: byNumberOfDependenciesWl[maxNumber]!, value: maxNumber);
 }

lib/src/model.dart

@@ -73,7 +73,7 @@ class SourceFolder extends SourceNode {
 }
 
 class SourceFile extends SourceNode {
-  SourceFile(FullName fullName) : super.parse(fullName);
+  SourceFile(super.fullName) : super.parse();
 
   final Set<SourceFile> dependencies = {};
 }

pubspec.yaml

@@ -1,5 +1,5 @@
 name: layerlens
-version: 3.0.4
+version: 3.1.0
 description: Generate a dependency diagram in every folder of your source code.
 repository: https://github.com/polina-c/layerlens
 
@@ -20,5 +20,5 @@ dependencies:
 
 dev_dependencies:
   file: ^7.0.0
-  lints: ^2.0.0
+  lints: ^6.0.0
   test: ^1.21.0