@carlos_patino-uniandes/angular-architecture-validator

Angular Architecture Validator

What is it?

The Angular Architecture Validator provides the developers with a tool that allows them create issues in github repository using the API provided by Github.

The tool will use the architecture defined by the developer to validate the code that is being written, the interactions between components, and other rules that the developer determines as relevant and wishes to maintain during the complete development cycle of the project.

How does it work?

This tool test pre-defined by developer rules in project and creates a Github issue for each one rule that fail in project.

The tool uses a personal access token setted by developer in evironment variables using ghToken name as authentication method to create issues in github repository.

Workflow

The first thing you need is a project based in Angular 2+ Framework which you want test on and a Github repository that contains this project.

• Generate a Github personal access token.

• Save this token in an environment variable called ghToken.

• Define and save locally in json format a set of rules to follow the desired project's architecture. The structure of the architecture rules should be as follows.

{
	"entity": {
		"components": {
			"actions": ["create", "delete", "detail", "list"],
			"files": {
				"styles": true,
				"html": true,
				"spec": true
			}
		},
		"module": true,
		"dto": true,
		"dto.spec": true,
		"service": true,
		"service.spec": true
	},
	"app": {
		"routing": true,
		"module": true,
		"component": {
			"spec": true,
			"html": true,
			"styles": true
		},
		"styles": "css"
	},
	"documentation": {
		"attributes": true,
		"functions": true
	}
}

• run npx angular-architecture-validator arg1 arg1 replacing arg1 with location of file that contains above defined rules arg2 with location of your project folder.
  (e.g. npx angular-architecture-validator ./arc.config.json ../test_project).

Rules definition

Here you can find the definition for each rule that you can set and test in this tool.

entity

In the Java programing language, an entity is a lightweight persistence domain object. Typically, an entity represents a table in a relational database, and each entity instance corresponds to a row in that table. In Angular projects, take for example the Australian Department of Home Affairs website (build with Angular). On this website, you can view all the available visas, navigate to the details of a specific visa, or apply for a visa through a registration form. In this simple example, a visa could be an entity. In our Angular project, it would be a module, with components such as visa-list, visa-detail, visa-create, etc.

• components of an Angular project module might be defined to represent some CRUD actions, and -based on the scope of the project- each component could require a style (styles), a template (html), and testing (spec) files.

  • actions: An array of strings defines how the naming of a module's components is going to be handled. In the previous example, for the visa module, the expected components would be visa-create, visa-delete, visa-detail, and visa-list.

  • files: A true/false boolean value defines the required files for each component. Said files are: a styling file (.css, .sass, etc), a template file (.html), and a testing file (.spec.ts).

• module: A true/false boolean value that indicates if an entity requires a .module.ts file. For our previous example, a visa.module.ts file.

• dto: A true/false boolean value that indicates if an entity requires a .dto.ts file. This file is very commonly used as an interface or Data Type Object that represents an entity. For our example, the visa module would require a visa.dto.ts file where the visa interface would be a data structure with some properties: a name, an expiry date, an ID, etc.

• dto.spec: A true/false boolean value used to indicate if the module requires a .dto.spec.ts file. This file could be used while testing the Angular project.

• service: A true/false boolean value that indicates if the module requires a .service.ts file. This file is commonly used as a singleton object that gets instantiated only once during the lifetime of an application. Services files contain methods that maintain data throughout the life of an application, i.e. data does not get refreshed and is available all the time. The main purpose of a service is to organize and share business logic, models, or data and functions with different components of an Angular application.

• service.spec: A true/false boolean value which, similarly to the dto.spec rule, indicates if a module requires a .service.spec.ts file. This file could be helpful when testing the Angular application.

app

This set of rules are defined to establish the structure of the root (main) module of the Angular application. This is the app module by default when an Angular application is instantiated.

• routing: A true/false boolean value that indicates whether an app-routing.module.ts file is required or not. This file is used as a scaffold to define the routing and navigation throughout the application.

• module: A true/false boolean value that indicates if the app.module.ts is required.

• component defines the required files for the app module's component. Said files are: a styling file (.css, .sass, etc), a template file (.html), and a testing file (.spec.ts).

• styles: This string-value rule is used to define the styling to be used in the Angular application. The expected values would be "css" for .css format styling files, "sass" for .sass files, "less" for .less files, etc.

documentation

For a programmer reliable documentation is always a must. The presence of documentation helps keep track of all aspects of an application and it improves the quality of a software product. See The Importance of Documentation in Software Development

• attributes: A true/false boolean value used to define if documentation is required for each attribute or property of a class or interface. It also defines if said attributes must indicate its visibility, via the keywords: public, private, or protected.

• functions: A true/false boolean value used to define if documentation is required for each function/method of a class.

Contribute

We are happy to see suggestions on how to improve the extension (feature requests) or code suggestions. Everything is welcome through the repository's issues site.

License

Licensed under the MIT License.