From 88b7d2a678158017a95982e277815e1e6670a52f Mon Sep 17 00:00:00 2001 From: Vanessa Cobis Date: Mon, 13 Dec 2021 09:37:28 -0500 Subject: [PATCH] add/update README.md on some projects --- README.md | 196 +++++++++++++++++++++-------- mule-linter-maven-plugin/README.md | 9 +- mule-linter-spi/README.md | 59 +++++++++ 3 files changed, 211 insertions(+), 53 deletions(-) create mode 100644 mule-linter-spi/README.md diff --git a/README.md b/README.md index a97efa68..136f5261 100644 --- a/README.md +++ b/README.md @@ -49,58 +49,150 @@ Make sure to import the rules and helper classes you intend to use. Sample configuration: ```groovy -import com.avioconsulting.mule.linter.model.rule.RuleSet -import com.avioconsulting.mule.linter.model.CaseNaming -import com.avioconsulting.mule.linter.rule.cicd.* -import com.avioconsulting.mule.linter.rule.configuration.* -import com.avioconsulting.mule.linter.rule.git.* -import com.avioconsulting.mule.linter.rule.muleartifact.* -import com.avioconsulting.mule.linter.rule.pom.* -import com.avioconsulting.mule.linter.rule.property.* - -class AVIOCustomRuleConfiguration { - static final List ENVIRONMENTS = ['dev','test','prod'] - static final String GLOBALS_FILENAME = 'globals.xml' - - static RuleSet getRules() { - RuleSet rules = new RuleSet() - - //cicd - rules.addRule(new JenkinsFileExistsRule()) - - //configuration - rules.addRule(new ConfigFileNamingRule(CaseNaming.CaseFormat.KEBAB_CASE)) - rules.addRule(new FlowSubflowNamingRule(CaseNaming.CaseFormat.KEBAB_CASE)) - rules.addRule(new GlobalConfigNoFlowsRule(GLOBALS_FILENAME)) - rules.addRule(new GlobalConfigRule(GLOBALS_FILENAME)) - rules.addRule(new LoggerCategoryExistsRule()) - rules.addRule(new LoggerMessageExistsRule()) - rules.addRule(new OnErrorLogExceptionRule()) - rules.addRule(new UnusedFlowRule()) - - //git - rules.addRule(new GitIgnoreRule()) - - //muleArtifact - rules.addRule(new MuleArtifactHasSecurePropertiesRule()) - rules.addRule(new MuleArtifactMinMuleVersionRule()) - - //pom - rules.addRule(new MuleMavenPluginVersionRule('3.3.5')) - rules.addRule(new MuleRuntimeVersionRule('4.2.1')) - rules.addRule(new MunitMavenPluginAttributesRule()) - rules.addRule(new MunitVersionRule('2.2.1')) - rules.addRule(new PomExistsRule()) - - //property - rules.addRule(new EncryptedPasswordRule()) - rules.addRule(new PropertyExistsRule('db.user', ENVIRONMENTS)) - rules.addRule(new PropertyFileNamingRule(ENVIRONMENTS)) - rules.addRule(new PropertyFilePropertyCountRule(ENVIRONMENTS)) - - return rules - } - +mule_linter { + rules { + /* CICD */ + AZURE_PIPELINES_EXISTS {} + JENKINS_EXISTS {} + + /* CONFIGURATION */ + API_CONSOLE_DISABLED{} + COMMENTED_CODE {} + COMPONENT_ATTRIBUTE_VALUE { + component = 'flow-ref' + namespace = 'http://www.mulesoft.org/schema/mule/core' + requiredAttributes = ['name'] + } + COMPONENT_COUNT { + component = 'flow-ref' + namespace = 'http://www.mulesoft.org/schema/mule/core' + maxCount = 5 + } + CONFIG_FILE_NAMING {} + CONFIG_PLACEHOLDER { + placeholderAttributes = ['key', 'password', 'keyPassword', 'username', 'host'] + } + DISPLAY_NAME { + components = [ + [name: 'set-payload', namespace: "http://www.mulesoft.org/schema/mule/core", displayName: 'Set Payload'], + [name: 'set-variable', namespace: "http://www.mulesoft.org/schema/mule/core", displayName: 'Set Variable'], + [name: 'transform', namespace: "http://www.mulesoft.org/schema/mule/ee/core", displayName: 'Transform Message'], + [name: 'flow-ref', namespace: "http://www.mulesoft.org/schema/mule/core", displayName: 'Flow Reference'] + ] + } + EXCESSIVE_LOGGERS { + excessiveLoggers = [ + 'INFO':3, + 'DEBUG':2 + ] + } + EXCESSIVE_LOGGERS { + excessiveLoggers = 2 + } + FLOW_SUBFLOW_NAMING { + format = 'KEBAB_CASE' + } + GLOBAL_CONFIG_NO_FLOWS { + globalFileName = 'globals.xml' + } + GLOBAL_CONFIG_NO_FLOWS {} + GLOBAL_CONFIG { + globalFileName = 'global-config.xml' + } + LOGGER_ATTRIBUTES_RULE { + requiredAttributes = ['category'] + } + LOGGER_CATEGORY_HASVALUE {} + LOGGER_MESSAGE_CONTENTS { + pattern = '[0-9]*' + } + LOGGER_MESSAGE_HASVALUE {} + MULE_CONFIG_SIZE { + flowLimit = 2 + } + ON_ERROR_LOG_EXCEPTION {} + UNTIL_SUCCESSFUL {} + UNUSED_FLOW {} + + /* GIT */ + GIT_IGNORE {} + GIT_IGNORE { + ignoredFiles = ['*.jar', '*.class', 'target/', '.project', '.classpath', '.idea', 'build'] + } + + /* MULE ARTIFACT */ + MULE_ARTIFACT_SECURE_PROPERTIES { + properties = [ + 'anypoint.platform.db.password' + ] + includeDefaults = false + } + MULE_ARTIFACT_MIN_MULE_VERSION {} + + /* POM */ + MULE_MAVEN_PLUGIN { + version = '3.3.5' + } + MULE_RUNTIME { + version = '4.3.0' + } + MUNIT_MAVEN_PLUGIN_ATTRIBUTES { + coverageAttributeMap =[ + 'runCoverage':'true', + 'failBuild':'true', + 'requiredApplicationCoverage':'80', + 'requiredResourceCoverage':'80', + 'requiredFlowCoverage':'80' + ] + includeDefaults = false + } + MUNIT_PLUGIN_VERSION { + version = '2.2.1' + } + MUNIT_VERSION { + version = '2.3.6' + } + POM_DEPENDENCY_VERSION { + groupId = 'com.mulesoft.connectors' + artifactId = 'mule-amazon-sqs-connector' + artifactVersion = '5.11.0' + versionOperator = 'GREATER_THAN' + } + POM_EXISTS {} + POM_PLUGIN_ATTRIBUTE { + groupId = 'org.mule.tools.maven' + artifactId = 'mule-maven-plugin' + attributes = [ + extensions: true + ] + } + MAVEN_PROPERTY { + propertyName = 'cloudhubWorkers' + propertyValue = '2' + } + + /* PROPERTY */ + ENCRYPTED_VALUE {} + HOSTNAME_PROPERTY { + exemptions = [] + } + PROPERTY_EXISTS { + environments = ['dev', 'test', 'prod'] + propertyName = 'db.user' + } + PROPERTY_FILE_NAMING { + environments = ['dev', 'test', 'prod'] + pattern = '${appname}-${env}.properties' + } + PROPERTY_FILE_COUNT_MISMATCH { + environments = ['dev', 'test', 'prod'] + pattern = '${appname}-${env}.properties' + } + + /* README */ + README {} + + } } ``` For a full breakdown on the available rules, [check here](docs/available_rules.md). diff --git a/mule-linter-maven-plugin/README.md b/mule-linter-maven-plugin/README.md index d9d53792..b0ad64ce 100644 --- a/mule-linter-maven-plugin/README.md +++ b/mule-linter-maven-plugin/README.md @@ -2,6 +2,8 @@ The mule linter can be run as mvn plugin. The maven plugin is located in module `mule-linter-maven-plugin`. +Plugin goal is by default attached to validate which is the first phase of maven lifecycle. + ## Parameters - appDir: Defaults to `${basedir}` - ruleConfiguration: Defaults to `${basedir}/muleLinter.groovy` @@ -83,5 +85,10 @@ Adding this library to plugin to use new rule, we can configure it like below - Once you add required dependencies, you can add new rule in the rules configuration file - ```groovy - rules.addRule(new com.avioconsulting.mule.linter.extension.rules.HttpListenerPathRule()) + MULE_ARTIFACT_SECURE_PROPERTIES { + properties = [ + 'anypoint.platform.db.password' + ] + includeDefaults = false + } ``` diff --git a/mule-linter-spi/README.md b/mule-linter-spi/README.md new file mode 100644 index 00000000..6a2f4251 --- /dev/null +++ b/mule-linter-spi/README.md @@ -0,0 +1,59 @@ +#Mule Linter Service Provider Interface + +Mule Linter contains two configurable components for core that other libraries can extend. + + * Mule Components: Core Library supports identifying Flow/Subflow and Logger components with attributes specific to those. All other components are just treated as generic MuleComponents. + + * Rule: Rules are the core of linter processing. Core library is shipped with many useful rules. + +Mule linter provides a service provider interface (SPI) library to allow extending these two components. + +To extend the mule linter capabilities, add following dependency to your custom library project +```xml +// For Gradle based builds +implementation 'com.avioconsulting.mule:mule-linter-spi:${mule-linter-version}' + + +// For Maven based builds + + com.avioconsulting.mule + mule-linter-spi + ${mule-linter-version} + +``` + +## Adding Mule Components +Mule linter is shipped with three components: + + * MuleComponent: The base of all components and used as a generic component + * FlowComponent: Identifies the instances of Flow or Subflows + * LoggerComponent: Identifies the mule logger component instances + + +### Component Identifiers +All components have a ComponentIdentifier that contains name and namespaceURI of that component. For example, below is the definition of HTTP Listener Component Identifier - + +`ComponentIdentifier IDENTIFIER_LISTENER = new ComponentIdentifier("listener", "http://www.mulesoft.org/schema/mule/http")` + +### Custom Components +Components are loaded using Java ServiceLoader mechanism. Example implementation is mule-linter-spi-test module. + + 1. Add mule-linter-spi dependency to your project. + 2. Creating new components (See example of HTTP Component in mule-linter-spi-test module) + - Add new Components in your project by extending MuleComponent class from SPI library. + - It is advised to add a static method static boolean accepts(ComponentIdentifier identifier) on the component. This should validate the accepted identifiers. This is not needed by SPI but can help you cleanly identify components in the factory. + - Add component specific methods + + 3. Making components discoverable for Service loader (See example of AVIOComponentsFactory.groovy in mule-linter-spi-test module) - + + - Create a Factory class implementing com.avioconsulting.mule.linter.spi.ComponentsFactory. + - Core library calls following method so implement these as applicable to your library - + - hasComponentFor - to define which Component’s are handled by this factory and instantiate them + - getComponentFor - to create and return the component for provided method arguments. + - Create a directory META-INF/services in your src/main/resources + - Add a text file named same as SPI com.avioconsulting.mule.linter.spi.ComponentsFactory. The content of the file should be the fully qualified class name for your factory. Following is an example content from SPI test module. + +```` +❯ cat src/main/resources/META-INF/services/com.avioconsulting.mule.linter.spi.ComponentsFactory +com.avioconsulting.mule.linter.extension.components.AVIOComponentsFactory% +```` \ No newline at end of file