Add improvements to the XSD tool

README.md

@@ -1,2 +1,147 @@
-# xsd-tools
-This is the source code of the XSD tool which converts XSD files into Ballerina records
+# Ballerina XSD Tool  
+
+[![Build](https://github.com/ballerina-platform/xsd-tools/actions/workflows/build-timestamped-master.yml/badge.svg)](https://github.com/ballerina-platform/xsd-tools/actions/workflows/build-timestamped-master.yml)
+[![codecov](https://codecov.io/gh/ballerina-platform/xsd-tools/branch/master/graph/badge.svg)](https://codecov.io/gh/ballerina-platform/xsd-tools)
+[![GitHub Last Commit](https://img.shields.io/github/last-commit/ballerina-platform/xsd-tools.svg)](https://github.com/ballerina-platform/xsd-tools/commits/master)
+[![GitHub issues](https://img.shields.io/github/issues/ballerina-platform/ballerina-standard-library/module/xsd-tools.svg?label=Open%20Issues)](https://github.com/ballerina-platform/ballerina-library/labels/module%2Fxsd-tools)
+
+`XSD` (XML Schema Definition) is an approach to define the structure, elements, and constraints of XML documents. It is widely used for validating the content and structure of XML files.
+
+The Ballerina XSD Tool simplifies the generation of Ballerina record types from an XSD specification, improving the user experience when integrating with XML-based operations in Ballerina.
+
+### Installation
+
+Execute the command below to pull the XSD tool from Ballerina Central.
+
+```bash
+$ bal tool pull xsd
+```
+
+### Usage
+
+The XSD tool allows you to generate Ballerina record types from an XSD specification.
+
+To generate Ballerina types, use the following command. It is mandatory to run the command inside a Ballerina project.
+
+```bash
+$ bal xsd <xsd-file-path> 
+          [--module <output-module-name>]
+```
+
+#### Command options  
+
+| Option | Description | Mandatory/Optional |
+|--------|-------------|--------------------|
+| `<xsd-file-path>` | (Required) The path to the XSD file | Mandatory |
+| `-m`, `--module`   | The name of the module in which the Ballerina record types are generated | Optional |
+
+### Generate types for the given XSD file
+
+Use the following command to generate Ballerina record types for all elements defined in the specified XSD file. By default, the generated `types.bal` file will be placed in the default module of the current Ballerina project.
+
+```bash
+$ bal xsd <source-file-path>
+```
+
+For example,
+
+```bash
+$ bal xsd sample.xsd
+```
+
+If successful, you will see the following output.
+
+```bash
+The 'types.bal' file is written to the default module
+```
+
+#### Generate types in a specific module
+
+To generate the Ballerina record types in a specific module, use the `--module` option.
+
+```bash
+$ bal xsd <source-file-path> --module <output-module-name>
+```
+
+For example,
+
+```bash
+$ bal xsd sample.xsd --module custom
+```
+
+This will generate a `types.bal` file inside the `custom` submodule within the Ballerina project.
+
+The following output will be displayed.
+
+```bash
+The 'types.bal' file is written to 'modules/custom'
+```
+
+Upon successful execution, the generated files will include,
+
+```bash
+modules/
+└── custom/
+        └── types.bal
+```
+
+## Building from the Source
+
+### Setting Up the Prerequisites
+
+1. OpenJDK 21 ([Adopt OpenJDK](https://adoptopenjdk.net/) or any other OpenJDK distribution)
+
+   >**Info:** You can also use [Oracle JDK](https://www.oracle.com/java/technologies/javase-downloads.html). Set the JAVA_HOME environment variable to the pathname of the directory into which you installed JDK.
+
+2. Export GitHub Personal access token with read package permissions as follows,
+   ```
+   export packageUser=<Username>
+   export packagePAT=<Personal access token>
+   ```
+
+### Building the Source
+
+Execute the commands below to build from the source.
+
+1. To build the library:
+
+        ./gradlew clean build
+
+2. To run the integration tests:
+
+        ./gradlew clean test
+
+3. To build the module without the tests:
+
+        ./gradlew clean build -x test
+
+4. To publish to maven local:
+
+        ./gradlew clean build publishToMavenLocal
+
+5. Publish the generated artifacts to the local Ballerina central repository:
+
+        ./gradlew clean build -PpublishToLocalCentral=true
+
+6. Publish the generated artifacts to the Ballerina central repository:
+
+        ./gradlew clean build -PpublishToCentral=true
+
+## Contributing to Ballerina
+
+As an open-source project, Ballerina welcomes contributions from the community.
+
+You can also check for [open issues](https://github.com/ballerina-platform/xsd-tools/issues) that
+interest you. We look forward to receiving your contributions.
+
+For more information, go to the [contribution guidelines](https://github.com/ballerina-platform/ballerina-lang/blob/master/CONTRIBUTING.md).
+
+## Code of Conduct
+
+All contributors are encouraged to read the [Ballerina Code of Conduct](https://ballerina.io/code-of-conduct).
+
+## Useful Links
+
+* Chat live with us via our [Discord server](https://discord.gg/ballerinalang).
+* Post all technical questions on Stack Overflow with the [#ballerina](https://stackoverflow.com/questions/tagged/ballerina) tag.
+* View the [Ballerina performance test results](https://github.com/ballerina-platform/ballerina-lang/blob/master/performance/benchmarks/summary.md).

build-config/checkstyle/build.gradle

@@ -14,13 +14,16 @@
  * limitations under the License.
  *
  */
+import groovy.xml.XmlParser
+import groovy.xml.XmlUtil
 
 plugins {
     id "de.undercouch.download"
 }
 
 apply plugin: 'java'
 
+// Task to download the Checkstyle rule files
 task downloadCheckstyleRuleFiles(type: Download) {
     src([
             'https://raw.githubusercontent.com/wso2/code-quality-tools/v1.4/checkstyle/jdk-17/checkstyle.xml',
@@ -31,14 +34,17 @@ task downloadCheckstyleRuleFiles(type: Download) {
     dest buildDir
 }
 
+// Disable jar task
 jar {
     enabled = false
 }
 
+// Disable clean task
 clean {
     enabled = false
 }
 
+// Add modified checkstyle.xml and suppressions.xml as artifacts
 artifacts.add('default', file("$project.buildDir/checkstyle.xml")) {
     builtBy('downloadCheckstyleRuleFiles')
 }

build-config/spotbugs-exclude.xml

@@ -0,0 +1,92 @@
+<!--
+  ~ Copyright (c) 2025, WSO2 LLC. (http://www.wso2.com).
+  ~
+  ~ WSO2 LLC. licenses this file to you under the Apache License,
+  ~ Version 2.0 (the "License"); you may not use this file except
+  ~ in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~    http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing,
+  ~ software distributed under the License is distributed on an
+  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  ~ KIND, either express or implied. See the License for the
+  ~ specific language governing permissions and limitations
+  ~ under the License.
+  -->
+<FindBugsFilter>
+    <Match>
+        <Class name="io.ballerina.lib.avro.Utils" />
+        <Method name = "getMutableType" />
+        <Bug pattern="BC_UNCONFIRMED_CAST" />
+    </Match>
+    <Match>
+        <Class name="io.ballerina.xsd.core.XSDToRecord" />
+        <Bug pattern="EI_EXPOSE_REP" />
+    </Match>
+    <Match>
+        <Class name="io.ballerina.wsdl.core.handler.model.WsdlOperation$Builder" />
+        <Bug pattern="EI_EXPOSE_REP" />
+    </Match>
+    <Match>
+        <Class name="io.ballerina.wsdl.core.handler.model.WsdlOperation" />
+        <Bug pattern="EI_EXPOSE_REP" />
+    </Match>
+    <Match>
+        <Class name="io.ballerina.xsd.core.Response" />
+        <Bug pattern="EI_EXPOSE_REP" />
+    </Match>
+    <Match>
+        <Class name="io.ballerina.wsdl.core.WsdlToBallerina" />
+        <Bug pattern="EI_EXPOSE_REP" />
+    </Match>
+    <Match>
+        <Class name="io.ballerina.xsd.core.component.ComplexType" />
+        <Bug pattern="EI_EXPOSE_REP" />
+    </Match>
+    <Match>
+        <Class name="io.ballerina.xsd.core.component.Element" />
+        <Bug pattern="EI_EXPOSE_REP" />
+    </Match>
+    <Match>
+        <Class name="io.ballerina.xsd.core.component.SimpleType" />
+        <Bug pattern="EI_EXPOSE_REP" />
+    </Match>
+    <Match>
+        <Class name="io.ballerina.xsd.core.visitor.XSDVisitorImpl" />
+        <Bug pattern="EI_EXPOSE_REP" />
+    </Match>
+    <Match>
+        <Class name="io.ballerina.wsdl.core.WsdlToBallerina" />
+        <Bug pattern="EI_EXPOSE_REP2" />
+    </Match>
+    <Match>
+        <Class name="io.ballerina.wsdl.core.WsdlToBallerinaResponse" />
+        <Bug pattern="EI_EXPOSE_REP2" />
+    </Match>
+    <Match>
+        <Class name="io.ballerina.wsdl.core.handler.SchemaHandler" />
+        <Bug pattern="EI_EXPOSE_REP2" />
+    </Match>
+    <Match>
+        <Class name="io.ballerina.xsd.core.Response" />
+        <Bug pattern="EI_EXPOSE_REP2" />
+    </Match>
+    <Match>
+        <Class name="io.ballerina.wsdl.core.handler.model.WsdlOperation$Builder" />
+        <Bug pattern="EI_EXPOSE_REP2" />
+    </Match>
+    <Match>
+        <Class name="io.ballerina.xsd.core.component.ComplexType" />
+        <Bug pattern="EI_EXPOSE_REP2" />
+    </Match>
+    <Match>
+        <Class name="io.ballerina.xsd.core.component.Element" />
+        <Bug pattern="EI_EXPOSE_REP2" />
+    </Match>
+    <Match>
+        <Class name="io.ballerina.xsd.core.component.SimpleType" />
+        <Bug pattern="EI_EXPOSE_REP2" />
+    </Match>
+</FindBugsFilter>

build.gradle

@@ -87,7 +87,7 @@ tasks.register('clean') {
 }
 
 tasks.register('build') {
-     dependsOn(":module-ballerina-xsd:build")
+    dependsOn(":module-ballerina-xsd:build")
 }
 
 tasks.register('test') {

gradle.properties

@@ -3,9 +3,9 @@ group=io.ballerina
 version=0.1.0-SNAPSHOT
 
 # Dependencies
-ballerinaLangVersion=2201.10.0
+ballerinaLangVersion=2201.11.0
 checkstylePluginVersion=10.12.0
-spotbugsPluginVersion=5.0.14
+spotbugsPluginVersion=6.0.18
 shadowJarPluginVersion=8.1.1
 downloadPluginVersion=5.4.0
 releasePluginVersion=2.8.0

module-ballerina-xsd/Dependencies.toml

@@ -5,7 +5,7 @@
 
 [ballerina]
 dependencies-toml-version = "2"
-distribution-version = "2201.10.0"
+distribution-version = "2201.11.0"
 
 [[package]]
 org = "ballerina"

module-ballerina-xsd/Module.md

@@ -1 +1,81 @@
-## Module Overview
+## Overview
+
+`XSD` (XML Schema Definition) is an approach to define the structure, elements, and constraints of XML documents. It is widely used for validating the content and structure of XML files.
+
+The Ballerina XSD Tool simplifies the generation of Ballerina record types from an XSD specification, improving the user experience when integrating with XML-based operations in Ballerina.
+
+### Installation
+
+Execute the command below to pull the XSD tool from Ballerina Central.
+
+```bash
+$ bal tool pull xsd
+```
+
+### Usage
+
+The XSD tool allows you to generate Ballerina record types from an XSD specification.
+
+To generate Ballerina types, use the following command. It is mandatory to run the command inside a Ballerina project.
+
+```bash
+$ bal xsd <xsd-file-path> 
+          [--module <output-module-name>]
+```
+
+#### Command options  
+
+| Option | Description | Mandatory/Optional |
+|--------|-------------|--------------------|
+| `<xsd-file-path>` | The path to the XSD file | Mandatory |
+| `-m`, `--module`   | The name of the module in which the Ballerina record types are generated | Optional |
+
+### Generate types for the given XSD file
+
+Use the following command to generate Ballerina record types for all elements defined in the specified XSD file. By default, the generated `types.bal` file will be placed in the default module of the current Ballerina project.
+
+```bash
+$ bal xsd <source-file-path>
+```
+
+For example,
+
+```bash
+$ bal xsd sample.xsd
+```
+
+If successful, you will see the following output.
+
+```bash
+The 'types.bal' file is written to the default module
+```
+
+#### Generate types in a specific module
+
+To generate the Ballerina record types in a specific module, use the `--module` option.
+
+```bash
+$ bal xsd <source-file-path> --module <output-module-name>
+```
+
+For example,
+
+```bash
+$ bal xsd sample.xsd --module custom
+```
+
+This will generate a `types.bal` file inside the `custom` submodule within the Ballerina project.
+
+The following output will be displayed.
+
+```bash
+The 'types.bal' file is written to 'modules/custom'
+```
+
+Upon successful execution, the generated files will include,
+
+```bash
+modules/
+└── custom/
+        └── types.bal
+```