ArchLens 0.2__tar.gz

archlens-0.2/ArchLens.egg-info/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: ArchLens
+Version: 0.2
+Summary: Designed for visualizing package dependencies and highlighting differences between branches in GitHub pull requests. It offers customization options to tailor package views.
+Home-page: https://github.com/archlens/ArchLens
+Author: The ArchLens Team
+Author-email: mlun@itu.dk
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.9
+Requires-Dist: plantuml
+Requires-Dist: typer
+Requires-Dist: astroid
+Requires-Dist: six
+Requires-Dist: requests
+Requires-Dist: jsonschema
+Requires-Dist: gitpython
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: summary
+
+This is the long description

archlens-0.2/ArchLens.egg-info/SOURCES.txt

@@ -0,0 +1,33 @@
+README.md
+setup.cfg
+setup.py
+ArchLens.egg-info/PKG-INFO
+ArchLens.egg-info/SOURCES.txt
+ArchLens.egg-info/dependency_links.txt
+ArchLens.egg-info/entry_points.txt
+ArchLens.egg-info/requires.txt
+ArchLens.egg-info/top_level.txt
+src/__init__.py
+src/cli_interface.py
+src/config.schema.json
+src/config.template.json
+src/main.py
+src/core/__init__.py
+src/core/bt_file.py
+src/core/bt_graph.py
+src/core/bt_module.py
+src/git_integration/__init__.py
+src/git_integration/fetch_git.py
+src/providers/__init__.py
+src/providers/json/__init__.py
+src/providers/json/json_render.py
+src/providers/plantuml/__init__.py
+src/providers/plantuml/pu_render.py
+src/utils/__init__.py
+src/utils/config_manager_singleton.py
+src/utils/functions.py
+src/utils/path_manager_singleton.py
+src/views/__init__.py
+src/views/utils.py
+src/views/view_entities.py
+src/views/view_manager.py

archlens-0.2/ArchLens.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

archlens-0.2/ArchLens.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+archlens = src.cli_interface:main

archlens-0.2/ArchLens.egg-info/requires.txt

@@ -0,0 +1,7 @@
+plantuml
+typer
+astroid
+six
+requests
+jsonschema
+gitpython

archlens-0.2/ArchLens.egg-info/top_level.txt

@@ -0,0 +1 @@
+src

archlens-0.2/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: ArchLens
+Version: 0.2
+Summary: Designed for visualizing package dependencies and highlighting differences between branches in GitHub pull requests. It offers customization options to tailor package views.
+Home-page: https://github.com/archlens/ArchLens
+Author: The ArchLens Team
+Author-email: mlun@itu.dk
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.9
+Requires-Dist: plantuml
+Requires-Dist: typer
+Requires-Dist: astroid
+Requires-Dist: six
+Requires-Dist: requests
+Requires-Dist: jsonschema
+Requires-Dist: gitpython
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: summary
+
+This is the long description

archlens-0.2/README.md

@@ -0,0 +1,269 @@
+# Architectural Lens
+### This project was originally forked from [Architectural Lens](https://github.com/Perlten/Architectural-Lens), all credit for the groundwork goes to the original authors
+(Fork was detached after work on the original project was discontinued, development continued by the ArchLens organization)
+
+##
+ArchLens is a Python software tool that generates customizable visual package views, showcasing the packages in your system and their dependencies. It offers the flexibility to include or exclude specific packages to suit your requirements for comprehensible views.
+
+Moreover, ArchLens can highlight the differences between your working branch and a specified remote branch, including added or removed dependencies and created or deleted packages, by using green and red highlighting.
+
+Lastly, ArchLens can display the highlighted differences in the system views when a pull request is created on GitHub. It automatically generates the views specified in your config, highlights the differences, and displays them in your pull request, simplifying the review process.
+
+To help you get started, this readme includes various options in combination with the setup of a config file.
+
+### ArchLens runs is compatible with 3.9 <= Python version <= 3.12.0
+
+## Installation
+
+To install ArchLens, simply use the pip package manager by running the following command:
+
+`pip install archlens-preview` (You need administrative right to perform the operation)
+
+This will download and install the necessary files and dependencies needed for ArchLens to run properly.
+
+## Commands
+
+All commands must be run from the project's root folder
+
+<b>The system has 4 commands:</b>
+
+
+-`archlens init`- Creates the config template
+
+-`archlens render` - Renders the views specified in the config
+
+-`archlens render-diff` - Renders the differences in the views between your working branch and a specified branch
+
+-`archlens create-action` Creates the github action which will automatically add the difference views to pull requests.
+
+# Using the system
+
+In this section, we will guide you through using the ArchLens system by explaining the commands and output with the example of an API project called 'zeeguu-api' that can be found at https://github.com/zeeguu/api.
+
+Although the project is not large, understanding the system even for this project size of roughly 40 packages can be challenging. To begin generating views, you need to be in the root of your project and run the following command:
+
+- `archlens init`
+
+This will create an "archlens.json" file in your root folder, where you can edit your desired views. This is the initial config:
+
+```json
+ {
+    "$schema": "https://raw.githubusercontent.com/archlens/ArchLens/master/src/config.schema.json",
+    "name": "",
+    "rootFolder": "",
+    "github": {
+        "url": "",
+        "branch": "main"
+    },
+    "saveLocation": "./diagrams/",
+    "views": {
+        "completeView": {
+            "packages": [],
+            "ignorePackages": []
+        }
+    }
+}
+
+```
+
+Here are two views of the 'zeeguu-api' project that we will be using as examples:
+
+- A complete view of the system
+
+![Zeeguu view](.github/readme/zeeguu-completeView.png)
+
+Hard to grasp? ArchLens agrees with you, which is why this tool exists.
+
+- A view of the system where everything except "core" and its sub-packages has been scraped away:
+
+![Zeeguu core view](.github/readme/zeeguu-coreViewxx.png)
+
+Here is an edited version of the "archlens.json" file for the 'zeeguu-api' project, which represents the first two views we created earlier, along with comments explaining each field briefly:
+
+The "views" field in the "archlens.json" file allows you to define as many views as you need for your project. Simply add a new object with a unique name for each view you want to create. For example, if you wanted to create a view that showed only the "utils" package in the "api" folder, you could add the following to the "views" field:
+
+```json
+{
+    "$schema": "https://raw.githubusercontent.com/archlens/ArchLens/master/src/config.schema.json",
+    "name": "zeeguu", # Name of project
+    "rootFolder": "zeeguu", # Name of source folder containing the root package (Usually a folder called src)
+    "github": {
+        "url": "https://github.com/zeeguu/api", # Link to project's Github
+        "branch": "master" # Name of main/master branch of project
+    },
+    "saveLocation": "./diagrams/", # Location to store generated diagrams
+    "views": { # Define each view
+        "completeView": { # Name of first view, you may add more
+            "packages": [], # Select packages to see in view, if left empty, see entire system view
+            "ignorePackages": [] # Specify packages not to include in diagram
+        }, "coreView":{ # Create view containing specific packages
+            "packages": [
+                "core" # In this case, we only allow packages starting with the name 'core'
+            ],
+            "ignorePackages": []
+        }
+    }
+}
+
+```
+
+### You can render the views specified in your "archlens.json" file by running the command:
+- `archlens render`
+
+This will generate the diagrams for all the views defined in your configuration file and save them in the location specified in the "saveLocation" field of your configuration.
+
+## Further Filtering of packages
+
+If you find the core view to be too large, you can create a new view that further filters the packages. Instead of giving a path to the package "core", you can limit it further by specifying that you want to see "core" and only its sub-packages that are 1 layer down.
+
+To achieve this, you can create an object instead of a string path for the package, with two fields: "depth" and "path". In the "depth" field, you specify the number of sub-packages you want to include, and in the "path" field, you specify the package to start with.
+
+For example, the following configuration file defines a view for the "core" package and its immediate sub-packages:
+
+![Zeeguu core view](.github/readme/zeeguu-coreViewDepthFiltered.png)
+
+This will create a view that shows only the "core" package and its immediate sub-packages.
+
+Here is an example of the archlens.json file used to generate the filtered view:
+
+```json
+{
+    "$schema": "https://raw.githubusercontent.com/archlens/ArchLens/master/src/config.schema.json",
+    "name": "zeeguu",
+    "rootFolder": "zeeguu",
+    "github": {
+        "url": "https://github.com/zeeguu/api",
+        "branch": "master"
+    },
+    "saveLocation": "./diagrams/",
+    "views": {
+         "coreView":{
+            "packages": [
+                #We create an object instead of a path
+                 {
+                    "depth": 1, #We only want 1 layer of sub packages from core
+                    "path": "core" #Just like before, we give the path
+                }
+            ],
+            "ignorePackages": []
+        }
+    }
+}
+
+```
+
+You can combine both strings and objects when defining packages in the packages array in the configuration file. For example, you can include all packages starting with "api/utils" along with packages in the "core" directory up to a depth of 1 using the following syntax:
+
+```json
+
+"packages": [
+    "api/utils",
+    {
+    "path": "core",
+    "depth": 1
+    }
+ ]
+
+```
+
+## Arrows
+Each arrow in the system diagram represents a dependency between two packages, and the number on the arrow indicates the number of dependencies going in that direction. If you prefer not to see these arrows, you can use the optional "showDependencyCount" setting, which is a boolean. When set to "false", the dependency count will be hidden in all views. Here is an example of how to set this option in your archlens.json file:
+
+```json
+{
+    "$schema": "https://raw.githubusercontent.com/archlens/ArchLens/master/src/config.schema.json",
+    "name": "zeeguu", # Name of project
+    "rootFolder": "zeeguu", # Name of source folder
+    "github": {
+        "url": "https://github.com/zeeguu/api", # Link to project's Github
+        "branch": "master" # Name of main/master branch of project
+    },
+    "showDependencyCount": false, <------ here we remove the arrows.
+    "saveLocation": "./diagrams/", # Location to store generated diagrams
+}
+```
+In this ArchLens config file, the dependency count would be gone. This setting is applied to all of the views.
+
+## Ignore packages
+In addition to selecting which packages you want in your diagram, you can also select which packages you want removed from your diagram.
+
+This can be done in two different ways:
+
+```json
+"ignorePackages": [
+"*test*" #Removes any package which contains the word test
+"api/test" #Removes the package api/test and all of its sub packages
+]
+```
+
+To clarify, the first method using an asterisk (*) will remove any package containing the specified keyword, while the second method will remove only the specified package and all of its sub-packages. This can be useful for cleaning up clutter in the diagram or for excluding certain packages that are not relevant to the analysis.
+
+## The difference views
+To generate a difference view using ArchLens, you need to be on a branch other than the one specified in the configuration file. Usually, you would compare your current branch with the main/master branch, but you have the flexibility to choose any branch you desire. For the following example, I have narrowed down the view by filtering out only the "core/model" package.
+
+```json
+{
+    "$schema": "https://raw.githubusercontent.com/archlens/ArchLens/master/src/config.schema.json",
+    "name": "zeeguu",
+    "rootFolder": "zeeguu",
+    "github": {
+        "url": "https://github.com/zeeguu/api",
+        "branch": "master"
+    },
+    "saveLocation": "./diagrams/",
+    "views": {
+         "coreView":{
+            "packages": [
+                "core/model" #Looking at core/model, using the path instead of object, because i want to see the entire sub system
+            ],
+            "ignorePackages": []
+        }
+    }
+}
+```
+For the next example, the core view is further filtered to show only "core/model". Three changes were made in comparison to the main branch: the package "smart_watch" was deleted, a new package called "smart_watch_two" was added, and a dependency from "word_knowledge" to "model" was removed.
+
+To render this new view displaying the changes, a new command must be run:
+
+- `archlens render-diff`
+
+![Zeeguu core view](.github/readme/zeeguu-modelViewdiffView.png)
+
+If there are no diffrences, a diagram without diffrences will still be generated.
+
+
+## Github action - Pull request
+
+To display the difference views in your pull requests, run the command:
+
+- `archlens create-action`
+
+This command generates the necessary files in the .github folder, creating it if it doesn't already exist. Once this is done, you can create a pull request, and the difference view will be visible to the reviewer, as shown in the image below. If there are no diffrences, a diagram without diffrences will still be generated.
+
+![Zeeguu core view](.github/readme/zeeguu-modelViewDiffGithub.png)
+
+## Contributing
+
+Further development on ArchLens is welcomed. To contribute to developing further on ArchLens, we welcome you to fork the repository and propose your additions.
+
+Before you start developing, ensure you have a compatible Python version for running ArchLens. ArchLens have been tested for versions after, including, 3.9, up until, and excluding, version 3.12. There are known issues related to running ArchLens with a version after and including version 3.11.
+
+After ensuring that the current Python version is compatible with ArchLens, we recommend installing the required packages from the files _requirements.txt_ and _dev-requirements.txt_. This will ensure that the necessary packages to run and test your contributions to ArchLens are in your development environment and that they uphold the minimum version requirements. The installing process has been tested using _pip_, and can be done using the following commands:
+
+```
+python -m pip install -r requirements.txt
+python -m pip install -r dev-requirements.txt
+```
+(What you use to install pip packages might differ)
+
+Next, to continue setting up your development environment, run the following command:
+```
+python setup.py develop
+```
+
+After following these steps, one can use the commando below to run the commands locally:
+```
+python ./src/cli_interface.py [cli_command]
+```
+
+For an overview of CLI-commands, look [here](https://github.com/archlens/ArchLens/edit/master/README.md#commands).

archlens-0.2/setup.cfg

@@ -0,0 +1,8 @@
+[flake8]
+extend-ignore = E266
+max-line-length = 120
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

archlens-0.2/setup.py

@@ -0,0 +1,34 @@
+from setuptools import setup, find_packages, glob
+
+
+setup(
+    name="ArchLens",
+    version="0.2",
+    description="Designed for visualizing package dependencies and highlighting differences between"
+    " branches in GitHub pull requests. It offers customization options to tailor package views.",
+    author="The ArchLens Team",
+    author_email="mlun@itu.dk",
+    url="https://github.com/archlens/ArchLens",
+    packages=find_packages(),
+    long_description="This is the long description",
+    data_files=glob.glob("src/config.**.json"),
+    include_package_data=True,
+    install_requires=[
+        "plantuml",
+        "typer",
+        "astroid",
+        "six",
+        "requests",
+        "jsonschema",
+        "gitpython",
+    ],
+    classifiers=[
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.9",
+    ],
+    entry_points={
+        "console_scripts": [
+            "archlens=src.cli_interface:main",
+        ],
+    },
+)

archlens-0.2/src/__init__.py

@@ -0,0 +1,4 @@
+import sys
+import os
+
+sys.path.insert(0, os.path.abspath(".."))

archlens-0.2/src/cli_interface.py

@@ -0,0 +1,176 @@
+import typer
+import json
+import os
+import requests
+import jsonschema
+import tempfile
+import shutil
+from pathlib import Path
+from src.providers.json.json_render import save_json, save_json_diff
+from src.providers.plantuml.pu_render import save_plant_uml, save_plant_uml_diff
+from src.utils.path_manager_singleton import PathManagerSingleton
+
+# from src.utils.functions import verify_config_options
+from src.utils.config_manager_singleton import ConfigManagerSingleton
+
+from src.views.view_manager import render_views, render_diff_views
+
+from src.core.bt_graph import BTGraph
+
+from src.git_integration.fetch_git import fetch_git_repo
+
+from astroid.manager import AstroidManager
+
+import astroid
+
+astroid.MANAGER = None
+
+app = typer.Typer(add_completion=True)
+
+
+@app.command()
+def render(config_path: str = "archlens.json"):
+    config = read_config_file(config_path)
+
+    mt_path_manager = PathManagerSingleton()
+    mt_path_manager.setup(config)
+
+    am = _create_astroid()
+    g = BTGraph(am)
+    g.build_graph(config)
+
+    render_views(g, config, save_plant_uml)
+
+
+@app.command()
+def render_json(config_path: str = "archlens.json"):
+    config = read_config_file(config_path)
+
+    mt_path_manager = PathManagerSingleton()
+    mt_path_manager.setup(config)
+
+    am = _create_astroid()
+    g = BTGraph(am)
+    g.build_graph(config)
+
+    render_views(g, config, save_json)
+
+
+def _create_astroid():
+    am = AstroidManager()
+    am.brain["astroid_cache"] = {}
+    return am
+
+
+@app.command()
+def render_diff(config_path: str = "archlens.json"):
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        print("Created temporary directory:", tmp_dir)
+        config = read_config_file(config_path)
+
+        fetch_git_repo(tmp_dir, config["github"]["url"], config["github"]["branch"])
+
+        shutil.copyfile(config_path, os.path.join(tmp_dir, "archlens.json"))
+
+        config_git = read_config_file(os.path.join(tmp_dir, "archlens.json"))
+
+        path_manager = PathManagerSingleton()
+        path_manager.setup(config, config_git)
+
+        local_am = _create_astroid()
+        local_graph = BTGraph(local_am)
+        local_graph.build_graph(config)
+        # verify_config_options(config, g)
+
+        remote_am = _create_astroid()
+        remote_graph = BTGraph(remote_am)
+        remote_graph.build_graph(config_git)
+        # verify_config_options(config_git, g_git)
+
+        render_diff_views(local_graph, remote_graph, config, save_plant_uml_diff)
+
+
+@app.command()
+def render_diff_json(config_path: str = "archlens.json"):
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        print("Created temporary directory:", tmp_dir)
+        config = read_config_file(config_path)
+
+        fetch_git_repo(tmp_dir, config["github"]["url"], config["github"]["branch"])
+
+        shutil.copyfile(config_path, os.path.join(tmp_dir, "archlens.json"))
+
+        config_git = read_config_file(os.path.join(tmp_dir, "archlens.json"))
+
+        path_manager = PathManagerSingleton()
+        path_manager.setup(config, config_git)
+
+        local_am = _create_astroid()
+        local_graph = BTGraph(local_am)
+        local_graph.build_graph(config)
+        # verify_config_options(config, g)
+
+        remote_am = _create_astroid()
+        remote_graph = BTGraph(remote_am)
+        remote_graph.build_graph(config_git)
+        # verify_config_options(config_git, g_git)
+
+        render_diff_views(local_graph, remote_graph, config, save_json_diff)
+
+
+@app.command()
+def init(config_path="./archlens.json"):
+    os.makedirs(os.path.dirname(config_path), exist_ok=True)
+    template_path = os.path.join(os.path.dirname(__file__), "config.template.json")
+    schema = None
+    with open(template_path, "r") as f:
+        schema = json.load(f)
+
+    schema["name"] = os.path.basename(os.getcwd())
+    with open(config_path, "w") as outfile:
+        json.dump(schema, outfile, indent=4)
+
+
+@app.command()
+def create_action():
+    action_url = "https://raw.githubusercontent.com/archlens/ArchLens/master/.github/workflows/render-diff-on-pr.yml"
+    action_path = Path(".github/workflows/render-diff-on-pr.yml")
+    typer.secho(f"Creating the action at {action_path}", fg="green")
+    action_path.parent.mkdir(parents=True, exist_ok=True)
+    action = requests.get(action_url).text
+
+    with open(action_path, "w") as f:
+        f.write(action)
+
+
+def read_config_file(config_path):
+    config = None
+    with open(config_path, "r") as f:
+        config = json.load(f)
+
+    config_schema = None
+    schema_path = os.path.join(os.path.dirname(__file__), "config.schema.json")
+    with open(schema_path) as fp:
+        config_schema = json.load(fp)
+
+    if not os.getenv("MT_DEBUG"):
+        jsonschema.validate(instance=config, schema=config_schema)
+
+    config["_config_path"] = os.path.dirname(os.path.abspath(config_path))
+
+    config["saveLocation"] = os.path.normpath(
+        os.path.join(config["_config_path"], config["saveLocation"])
+    )
+
+    config_manager = ConfigManagerSingleton()
+    config_manager.setup(config)
+
+    return config
+
+
+def main():
+    app()
+
+
+if __name__ == "__main__":
+    main()