11 releases
0.2.7 | Jul 13, 2021 |
---|---|
0.2.6 | Jul 12, 2021 |
0.2.5 | Jun 25, 2021 |
0.2.4 | Apr 30, 2021 |
0.1.0 | Jun 22, 2020 |
#249 in Cargo plugins
106 downloads per month
Used in weld-bin
85KB
510 lines
Atelier: crate cargo_atelier
A cargo command for using Smithy models as a part of a build process.
Usage
> cargo atelier --help
cargo-atelier 0.2.2
Tools for the Smithy IDL.
USAGE:
cargo-atelier [FLAGS] <SUBCOMMAND>
FLAGS:
-h, --help Prints help information
-n, --no-color Turn off color in the output
-V, --version Prints version information
-v, --verbose The level of logging to perform; from off to trace
SUBCOMMANDS:
convert Convert model from one representation to another
document Create human-readable documentation from a model
help Prints this message or the help of the given subcommand(s)
lint Run standard linter rules on a model file
validate Run standard validators on a model file
Both the lint and validate commands use a common mechanism for printing results and will by default print using a colorized output. As different linter and validation rules can be used the reported by row informs you which rule-set has determined the error.
The document command creates documentation from the model, relying on specific traits for text and the prelude traits for some semantic properties. It used the somedoc crate to do the formatting and so the output format specified in this tool can select any of the formats supported by somedoc.
Example Lint
For the following badly formatted Smithy file, in test-models/lint-test.smithy
.
namespace org.example.smithy
@ThisIsNotAGoodName
structure thisIsMyStructure {
lower: String,
Upper: String,
someJSONThing: someUnknownShape,
OK: Boolean
}
string someUnknownShape
@trait
structure ThisIsNotAGoodName {}
The following issues will be output when the linter runs.
> cargo atelier lint -i test-models/lint-test.smithy
[info] Shape names should conform to UpperCamelCase, i.e. ThisIsMyStructure
Reported by NamingConventions on/for element `thisIsMyStructure`.
[info] Trait names should conform to lowerCamelCase, i.e. thisIsNotAGoodName
Reported by NamingConventions on/for element `ThisIsNotAGoodName`.
[info] Member names should conform to lowerCamelCase, i.e. ok
Reported by NamingConventions on/for element `thisIsMyStructure$OK`.
[info] Member name 'OK' appears to contain a known acronym, consider renaming i.e. ok
Reported by NamingConventions on/for element `thisIsMyStructure`.
[info] Member names should conform to lowerCamelCase, i.e. someJsonThing
Reported by NamingConventions on/for element `thisIsMyStructure$someJSONThing`.
[info] Member name 'someJSONThing' appears to contain a known acronym, consider renaming i.e. Json
Reported by NamingConventions on/for element `thisIsMyStructure`.
[info] Shape names should conform to UpperCamelCase, i.e. SomeUnknownShape
Reported by NamingConventions on/for element `someUnknownShape`.
[info] Member names should conform to lowerCamelCase, i.e. upper
Reported by NamingConventions on/for element `thisIsMyStructure$Upper`.
Example Validate
For the following erroneous Smithy file, in test-models/validation-test.smithy
.
namespace org.example.smithy
structure MyStructure {
known: String,
wrongType: SomeOperation,
}
operation SomeOperation {
input: SomeService
}
service SomeService {
version: "1.0",
operations: [MyStructure]
}
The following issues will be output when the validation runs.
> cargo atelier validate -i test-models/validation-test.smithy
[error] Structure member may not refer to a service, operation, resource or apply.
Reported by CorrectTypeReferences on/for element `MyStructure$wrongType`.
[warning] Structure member's type (smithy.api#NotString) cannot be resolved to a shape in this model.
Reported by CorrectTypeReferences on/for element `MyStructure$unknown`.
[error] Service operation must be an operation.
Reported by CorrectTypeReferences on/for element `SomeService`.
[error] Operation input may not refer to a service, operation, resource or apply.
Reported by CorrectTypeReferences on/for element `SomeOperation`.
Example Documentation
> cargo atelier document -i test-models/lint-test.smithy -w xwiki
{{comment}}
title: Smithy Model
{{/comment}}
Smith Version: 1.0
= Namespace org.example.smithy =
(% id="shape:ThisIsNotAGoodName" %) == ThisIsNotAGoodName (structure) ==
|=Trait|=Value|
|Is Trait|##true##|
(% id="shape:someUnknownShape" %) == someUnknownShape (string) ==
(% id="shape:thisIsMyStructure" %) == thisIsMyStructure (structure) ==
=== Members ===
* ##Upper##: ##smithy.api#String##
* ##lower##: ##smithy.api#String##
* ##OK##: ##smithy.api#Boolean##
* ##someJSONThing##: [[someUnknownShape>>.||anchor=shape:someUnknownShape]]
Parameters
Common parameters that may be included with any command.
-V
,--version
; prints version information (and exits).-h
,--help
; prints help information (and exits).-v
,--verbose
; turn on more logging, the more times you add the parameter the more logging you get.--no-color
; turn off color support.
The following parameters are supported for all file input. File input uses the
atelier_assembler
crate to read multiple files and
support multiple file representations. By default, the model assembler does not use a search path to load files. However,
this can be changed with either the -d
flag which will load any files found in the search path in the environment
variable $SMITHY_PATH
. Alternatively the -s
parameter provides the name of an environment variable to use instead
of $SMITHY_PATH
.
-d
,--default-search-env
; if set, the standardSMITHY_PATH
environment variable will be used as a search path.-i
,--in-file <in-file>
;the name of a file to read, multiple files can be specified.-s
,--search-env <search-env>
; the name of an environment variable to use as a search path.
The following parameters are supported for all file output.
-n
,--namespace <namespace>
;a namespace to write, if the output format requires one.-o
,--out-file <out-file>
; the name of a file to write to or stdout.-w
,--write-format <write-format>
; the representation of the output file, the default is dependent on the command.
Changes
Version 0.2.7
- Added argument check to run correctly under cargo.
Version 0.2.6
- Added parameters 'default_search_env' and 'search_env' to control the model assembler.
Version 0.2.5
- Implemented cargo-atelier's lint and validate should work on models built from multiple namespace
files using the model assembler.
- Updated all commands to take a list of file paths as input, the assembler will figure out the file types.
- Updated error reporting.
Version 0.2.4
- Change to lib API.
Version 0.2.3
- Fixed: bumped somedoc dependency version.
Version 0.2.2
- Made new command for documentation writer; this takes the
somedoc::write::OutputFormat
to select format.
Version 0.2.1
- Changes based on new core traits
HasIdentity
andHasTraits
. - Added documentation writer.
Version 0.1.3
- Supporting colorized output.
- Added example files for lint/validate tests.
- Added examples here.
Version 0.1.2
- Updated library dependency to get the latest Smithy reader.
Version 0.1.1
- Linter and Validator commands working
- Convert from json/smithy to json/smithy/uml
Version 0.1.0
- Placeholder release.
TODO
- Validator.
- Code generator.
Dependencies
~8–21MB
~245K SLoC