cargo_atelier 0.2.0

Cargo integration for the AWS Smithy IDL.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

# Atelier: crate cargo_atelier

A cargo command for using [Smithy](https://github.com/awslabs/smithy) models as a part of a build process.

[![crates.io](https://img.shields.io/crates/v/cargo_atelier.svg)](https://crates.io/crates/cargo_atelier)
[![docs.rs](https://docs.rs/cargo_atelier/badge.svg)](https://docs.rs/cargo_atelier)

# Usage

```bash
> cargo atelier --help
cargo-atelier 0.1.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
    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.

# Example Lint

For the following badly formatted Smithy file,

```text
namespace org.example.smithy

@ThisIsNotAGoodName
structure thisIsMyStructure {
    lower: String,
    Upper: String,
    someJSONThing: someUnknownShape,
    OK: Boolean
}
```

The following issues will be output when the linter is run.

```bash
> cargo atelier lint -i test-models/lint-test.smithy -r 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,

```text
namespace org.example.smithy

@unknownTrait
structure MyStructure {
    known: String,
    unknown: NotString,
    wrongType: SomeOperation,
}

operation SomeOperation {
    input: SomeService
}

service SomeService {
    operations: [MyStructure]
```

The following issues will be output when the validation is run.

```bash
> cargo atelier validate -i test-models/validation-test.smithy -r smithy

[error] Shape, or member, has a trait that refers to an unknown identifier: unknownTrait
	Reported by NoOrphanedReferences on/for element `MyStructure`.

[error] Shape, or member, refers to an unknown identifier: NotString
	Reported by NoOrphanedReferences on/for element `MyStructure$unknown`.

[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`.
```

## Changes

**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

1. Validator.
1. Code generator.