leto-modelizer-plugin-core

Library that contains all models for modeling tools in Leto's projects.

This library is used to create your own plugin for the Leto Modelizer tool.

Get started

Requirements

• node - v18.4
• npm - v8.19.3

Install

npm install --save "git://github.com/ditrit/leto-modelizer-plugin-core.git"

Usage

Here are all imports you can use in your plugin:

import {
  Component,
  ComponentDefinition,
  ComponentAttributeDefinition,
  ComponentDrawOption,
  ComponentAttribute,
  ComponentLink,
  ComponentLinkDefinition,
  DefaultDrawer,
  DefaultMetadata,
  DefaultParser,
  DefaultRender,
  ParseError,
  FileInformation,
  FileInput,
  DefaultData,
  DefaultPlugin,
  DefaultConfiguration,
  Tag,
  Variable,
} from "leto-modelizer-plugin-core";

For more information about all imports please refer to technical documentation and project template.

You can use it in that way:

import { DefaultParser } from 'leto-modelizer-plugin-core';

class FruitParser extends DefaultParser {
  parse(inputs) {
    // Write your own parser here
    return {
      components: [/* ... */], // Generated components from parser
      links: [/* ... */]       // Generated component links from parser
    }
  }
}

export default FruitParser;

To see a complete example, please refer to iactor.

How to create your plugin

You can use this template repository to create your own plugin.

The project template leto-modelizer-plugin-template provides you the default structure of a plugin and all useful scripts to generate resources and other.

It is strongly recommended to use it and the following documentation will make references to it.

Furthermore, in this template there are code comments to explain how to override methods/classes and usages.

How to create your own models

You can read the template documentation to see how to create your own models.

Default Plugin structure

For your plugin to be used by Leto Modelizer, it needs to have this structure:

// src/index.js
export default new DefaultPlugin({
  pluginData: MyPluginData,         // MyPluginData has to extend DefaultData
  pluginDrawer: MyPluginDrawer,     // MyPluginDrawer has to extend DefaultDrawer
  pluginMetadata: MyPluginMetadata, // MyPluginMetadata has to extend DefaultMetadata
  pluginParser: MyPluginParser,     // MyPluginParser has to extend DefaultParser
  pluginRenderer: MyPluginRenderer, // MyPluginRenderer has to extend DefaultRender
});

How it works

Plugin lifecycle

This is the default lifecycle of plugin usage in Leto Modelizer.

Plugin creation

Create you plugin project from leto-modelizer-plugin-template and follow the readme section of the template project.

Plugin configuration

The configuration.md explains how you can configure your plugin.

Events

By default, the plugin sends events if you provide a next() function in DefaultData, like:

new DefaultPlugin({
  event: {
    next: () => {},
  }
})

If you do not, events are still stored in the DefaultData.eventLogs.

When you create your plugin, you can send events to Leto-modelizer to see the progression of your parsing or rendering action.

See EventLog in technical documentation for more information.

Technical documentation

Technical documentation can be found here.

Default commands

Explanation of usage of scripts in package.json.

build

Build this project in dist folder.

prepare:docs

Fix betterdocs template for jsdoc and make it work.

build:docs

Generate documentation with jsdoc.

demo

Start a sample integration vue dev server.

lint

Run eslint check on the project.

lint:fix

Apply default fix for eslint in project.

lint:report

Generate report of lint issues for sonar.

lint:watch

To use in development, to see current lint errors with auto-refresh.

test

Run all the unit tests.

test:coverage

Generate coverage report of the unit tests.

Development

Directory structure

This is the default directory structure we use for this project:

leto-modelizer-plugin-core
├ cypress              ⇨ Contains all the cypress related files
│ ├ e2e                ⇨ Contains all the e2e tests
│ └ support            ⇨ Contains all support files for e2e tests
│   └ step_definitions ⇨ Contains all step definitions for e2e tests
├ demo                 ⇨ Contains a vue demo application
├ dist                 ⇨ Contains the built application
├ docs                 ⇨ Contains all files generated by esdoc
├ public               ⇨ Contains all public files, like favicon
├ reports              ⇨ Contains all the report files for sonar
├ guides               ⇨ Contains all the guides
├ └  docs              ⇨ Contains all plugin-core documentation
│ └  migrations        ⇨ Contains all migration guides
│ └  svg               ⇨ Contains the guide to build a component svg
├ src                  ⇨ Contains all files for modeling tools
│ ├ assets             ⇨ Contains all the assets
│ ├ draw               ⇨ Contains all files related to the Class that draws components in a graphical representation
│ ├ error              ⇨ Contains all files related to the Class that represents a parsing error
│ ├ metadata           ⇨ Contains all files related to the Class that represents the metadata of a specific implementation
│ ├ models             ⇨ Contains all files related to the Class that represents default plugin structure
│ ├ parser             ⇨ Contains the Class used for parsing
│ └ render             ⇨ Contains the Class that compile components to data
└ tests                ⇨ Contains all files related to the tests

How to release

We use Semantic Versioning as guideline for the version management.

Steps to release:

• Checkout a branch release/vX.Y.Z from the latest dev.
• Increase your version number in package.json, package-lock.json and changelog.md.
• Verify the content of the changelog.md.
• Build the project
• Commit your modification (with the dist content) with this commit's name Release version X.Y.Z.
• Create a pull request on github to this branch in dev.
• After the previous PR is merged, create a pull request on github to dev in main.
• After the previous PR is merged, tag the main branch with vX.Y.Z
• After the tag is push, make the release on the tag in GitHub

Git: Default branches

The default branch is main, we can't commit on it and we can only make a pull request to add some code.

Release tags are only on the main branch.

Git: Branch naming policy

There is the branch naming policy: [BRANCH_TYPE]/[BRANCH_NAME]

• BRANCH_TYPE is a prefix to describe the purpose of the branch, accepted prefix are:
  • feature, used for feature development
  • bugfix, used for bug fix
  • improvement, used for refacto
  • library, used for updating library
  • prerelease, used for preparing the branch for the release
  • release, used for releasing project
  • hotfix, used for applying a hotfix on main
• BRANCH_NAME is managed by this regex: [a-z0-9_-] (_ is used as space character).

Examples:

# BAD
add_some_test
# GOOD
improvement/unit_test

# BAD
feature/adding-some-feature
# GOOD
feature/adding_some_feature