sdk-lockfiles
=============

This CLI tool audits the `Cargo.lock` files in the `smithy-rs` repository. These lockfiles are used to ensure
reproducible builds during our release process for both `smithy-rs` and `aws-sdk-rust`. When a crate dependency is not
pinned to a fixed version, it risks being affected by newer versions of that dependency published to crates.io, which
could potentially break the build.

We track the following lockfiles in the `smithy-rs` repository:
1. The [lockfile](https://github.com/smithy-lang/smithy-rs/blob/main/rust-runtime/Cargo.lock) for Smithy runtime crates
2. The [lockfile](https://github.com/smithy-lang/smithy-rs/blob/main/aws/rust-runtime/Cargo.lock) for AWS runtime crates
3. The [lockfile](https://github.com/smithy-lang/smithy-rs/blob/main/aws/rust-runtime/aws-config/Cargo.lock) for the `aws-config` crate
4. The [lockfile](https://github.com/smithy-lang/smithy-rs/blob/main/aws/sdk/Cargo.lock) for the workspace containing code-generated AWS SDK crates

The first three lockfiles can be easily updated during development with a `cargo` command. However, the fourth lockfile
, known as the SDK lockfile, is generated by the code generator and is not checked into to the `smithy-rs` repository as
frequently as the first three runtime lockfiles. As a result, new dependencies added to any of the runtime lockfiles may
not be reflected in the SDK lockfile.

The `sdk-lockfiles` tool ensures that the SDK lockfile is a superset containing all dependencies listed in the three
runtime lockfiles. If it detects a new dependency in the AWS SDK crates introduced by any of the runtime lockfiles it
will output a message similar to the following (unless the dependency is introduced by a server specific runtime crate):
```
$ sdk-lockfiles audit
2024-09-10T16:48:38.460518Z  INFO sdk_lockfiles::audit: checking whether `rust-runtime/Cargo.lock` is covered by the SDK lockfile...
2024-09-10T16:48:38.489879Z  INFO sdk_lockfiles::audit: checking whether `aws/rust-runtime/Cargo.lock` is covered by the SDK lockfile...
2024-09-10T16:48:38.490306Z  INFO sdk_lockfiles::audit: checking whether `aws/rust-runtime/aws-config/Cargo.lock` is covered by the SDK lockfile...
`minicbor` (0.24.2), used by `rust-runtime/Cargo.lock`, is not contained in the SDK lockfile!
Error: there are lockfile audit failures
```

This tool is intended for automated use.

## Limitations
### Unable to audit dependencies in `CargoDependency.kt`
The `sdk-lockfiles` tool does not verify whether new dependencies introduced in [CargoDependency.kt](https://github.com/smithy-lang/smithy-rs/blob/main/codegen-core/src/main/kotlin/software/amazon/smithy/rust/codegen/core/rustlang/CargoDependency.kt)
are included in the SDK lockfile. This is because dependencies in `CargoDependency.kt` are represented as a Kotlin data
class. Consequently, dependencies added via the code generator, `inlineable`, or `aws-inlineable` are not considered by
`sdk-lockfiles`.

This limitation is acceptable for our operational purposes. Our release script [always executes
`./gradlew aws:sdk:syncAwsSdkLockfile`](https://github.com/smithy-lang/smithy-rs/blob/b62000e4d733ca06bc98fd9b57c91468718b8f9f/tools/ci-scripts/generate-smithy-rs-release#L36), which ensures that any dependencies added in `CargoDependency.kt` are properly
reflected in the SDK lockfile.

### False positives
The `sdk-lockfiles` tool may report false positives based on the contents of a lockfile. For example, if a section of
the lockfile appears as follows
```
  pin-project v1.1.5
  ├── tower v0.4.13
  │   ├── aws-smithy-experimental v0.1.4
  │   ├── aws-smithy-http-server v0.63.3
  │   │   └── aws-smithy-http-server-python v0.63.2
  │   ├── aws-smithy-http-server-python v0.63.2
  ...
```
the tool cannot identify which dependent crate of `tower` enables `tower`'s Cargo feature to include `pin-project`.
In the case above, `aws-smithy-experimental` does not enable this feature, while `aws-smithy-http-server` does.
Among the Smithy runtime crates above, only `aws-smithy-experimental` is used by SDKs. When `aws-smithy-experimental`
is compiled for a generated SDK without server-related Smithy runtime crates, `pin-project` will not appear in the
SDK lockfile. Therefore, while it may appear that `aws-smithy-experimental` depends on `pin-project`, it is a false
positive for the audit.

To address this limitation, we maintain a list of known false positives in `false-positives.txt`. Any dependency
included in this file will not be flagged as an audit error.
