cc-codeconductor 1.7.1 → 1.7.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -5
- package/dist/index.d.ts +1 -0
- package/dist/index.js +2689 -528
- package/dist/library.js +859 -715
- package/dist/validation/schemas.d.ts +784 -138
- package/dist/validation/scoped-context-schemas.d.ts +1074 -0
- package/package.json +3 -2
- package/presets/agy/skills/database-migrations/SKILL.md +64 -0
- package/presets/agy/skills/rust-async/SKILL.md +64 -0
- package/presets/agy/skills/rust-engineering/SKILL.md +69 -0
- package/presets/agy/skills/rust-sqlx/SKILL.md +64 -0
- package/presets/claude/settings.json +1 -8
- package/presets/claude/skills/database-migrations/SKILL.md +64 -0
- package/presets/claude/skills/rust-async/SKILL.md +64 -0
- package/presets/claude/skills/rust-engineering/SKILL.md +69 -0
- package/presets/claude/skills/rust-sqlx/SKILL.md +64 -0
- package/presets/codex/skills/database-migrations/SKILL.md +64 -0
- package/presets/codex/skills/rust-async/SKILL.md +64 -0
- package/presets/codex/skills/rust-engineering/SKILL.md +69 -0
- package/presets/codex/skills/rust-sqlx/SKILL.md +64 -0
- package/presets/cursor/skills/database-migrations/SKILL.md +64 -0
- package/presets/cursor/skills/rust-async/SKILL.md +64 -0
- package/presets/cursor/skills/rust-engineering/SKILL.md +69 -0
- package/presets/cursor/skills/rust-sqlx/SKILL.md +64 -0
- package/presets/opencode/skills/database-migrations/SKILL.md +64 -0
- package/presets/opencode/skills/rust-async/SKILL.md +64 -0
- package/presets/opencode/skills/rust-engineering/SKILL.md +69 -0
- package/presets/opencode/skills/rust-sqlx/SKILL.md +64 -0
- package/src/presets/shared-skills.yml +8 -0
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: rust-async
|
|
3
|
+
name: rust-async
|
|
4
|
+
description: >
|
|
5
|
+
Rust async with tokio or async-std: guards across await, detached tasks,
|
|
6
|
+
blocking work, cancellation and shutdown.
|
|
7
|
+
Trigger: When writing or reviewing async Rust in a package that declares tokio or async-std.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Rust async
|
|
11
|
+
|
|
12
|
+
## Activation
|
|
13
|
+
|
|
14
|
+
Apply when the owning package declares `tokio` or `async-std` as a normal
|
|
15
|
+
dependency and the change touches `async fn`, `.await`, `spawn` or channels.
|
|
16
|
+
|
|
17
|
+
## Inputs
|
|
18
|
+
|
|
19
|
+
- Declared runtime, its features (`rt`, `rt-multi-thread`, `sync`, `time`).
|
|
20
|
+
- Existing shutdown path (`CancellationToken`, signal handler, `JoinSet`).
|
|
21
|
+
|
|
22
|
+
## Procedure
|
|
23
|
+
|
|
24
|
+
1. **Guards across await** (`rust.guard-across-await`). Condition: a
|
|
25
|
+
`std::sync::MutexGuard`/`RwLock` guard or `RefCell` borrow is live at an
|
|
26
|
+
`.await`. Action: scope the guard in a block that ends before the await, or
|
|
27
|
+
copy out the data. Use `tokio::sync::Mutex` only when the lock must be held
|
|
28
|
+
across the await. Exception: none for std guards (the future becomes `!Send`
|
|
29
|
+
or can deadlock). Verify: `cargo check`; a `Send` bound compile error on
|
|
30
|
+
`spawn` is the signal.
|
|
31
|
+
2. **Detached tasks** (`rust.detached-task`). Condition: `spawn` result is
|
|
32
|
+
dropped. Action: dropping a `JoinHandle` detaches the task; keep the handle
|
|
33
|
+
or use a `JoinSet`, and decide who observes panics and errors. Exception:
|
|
34
|
+
fire-and-forget with logged failure and no shutdown dependency. Verify: each
|
|
35
|
+
`spawn` has an owner that is awaited or aborted at shutdown.
|
|
36
|
+
3. **Blocking work.** Condition: CPU-heavy or blocking I/O inside async code.
|
|
37
|
+
Action: `tokio::task::spawn_blocking`. Exception: work shorter than a
|
|
38
|
+
scheduling quantum. Verify: no `std::thread::sleep` or blocking
|
|
39
|
+
`std::fs`/`std::net` call in an `async fn`.
|
|
40
|
+
4. **Cancellation.** Condition: a future may be dropped at any `.await`. Action:
|
|
41
|
+
keep state consistent at every await; use cancel-safe operations in
|
|
42
|
+
`select!`. `abort()` does not stop a `spawn_blocking` task that already
|
|
43
|
+
started. Exception: none. Verify: a test that drops the future mid-operation.
|
|
44
|
+
5. **Shutdown.** Condition: the service owns tasks. Action: signal, then await
|
|
45
|
+
handles with a timeout. Started `spawn_blocking` tasks run to completion, so
|
|
46
|
+
bound their runtime. Verify: a test or run that shuts down without hanging.
|
|
47
|
+
|
|
48
|
+
## Decisions and exceptions
|
|
49
|
+
|
|
50
|
+
- Do not change runtime flavor or add features without a Task Card line.
|
|
51
|
+
- `async-std` and `tokio` APIs differ; follow the declared runtime only.
|
|
52
|
+
- Unbounded channels need a stated reason; default to bounded.
|
|
53
|
+
|
|
54
|
+
## Evidence
|
|
55
|
+
|
|
56
|
+
`cargo test -p <package>` with the exit code, plus the named test that drops
|
|
57
|
+
or aborts the future. Report unverified cancellation paths as unverified.
|
|
58
|
+
|
|
59
|
+
## References
|
|
60
|
+
|
|
61
|
+
- https://docs.rs/tokio/latest/tokio/task/fn.spawn_blocking.html
|
|
62
|
+
- https://docs.rs/tokio/latest/tokio/task/struct.JoinHandle.html
|
|
63
|
+
- https://docs.rs/tokio/latest/tokio/sync/struct.Mutex.html
|
|
64
|
+
- https://tokio.rs/tokio/topics/shutdown
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: rust-engineering
|
|
3
|
+
name: rust-engineering
|
|
4
|
+
description: >
|
|
5
|
+
Rust engineering baseline: Cargo workspaces and features, error types,
|
|
6
|
+
unsafe, public API, lints and verification.
|
|
7
|
+
Trigger: When editing .rs files, Cargo.toml or Cargo.lock in a Rust package.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Rust engineering
|
|
11
|
+
|
|
12
|
+
## Activation
|
|
13
|
+
|
|
14
|
+
Apply to any `.rs`, `Cargo.toml` or `Cargo.lock` change. Rules are defaults;
|
|
15
|
+
a repository rule with the same id wins over this skill.
|
|
16
|
+
|
|
17
|
+
## Inputs
|
|
18
|
+
|
|
19
|
+
- Nearest `Cargo.toml` (package, `[features]`, `[lints]`) and workspace root.
|
|
20
|
+
- `rust-toolchain.toml`, `clippy.toml`, `rustfmt.toml` when present.
|
|
21
|
+
- The repository's existing error type and module layout.
|
|
22
|
+
|
|
23
|
+
## Procedure
|
|
24
|
+
|
|
25
|
+
1. **Locate the package.** Condition: a change spans crates. Action: resolve the
|
|
26
|
+
owning package per file and run checks with `-p <package>`. Exception: a
|
|
27
|
+
workspace-wide refactor named in the Task Card. Verify: `cargo metadata
|
|
28
|
+
--no-deps --format-version 1` lists the package.
|
|
29
|
+
2. **Errors.** Condition: a function can fail. Action: return `Result` with the
|
|
30
|
+
crate's existing error type; add context where the error crosses a module
|
|
31
|
+
boundary. Exception: tests and examples may `unwrap`/`expect`. Verify:
|
|
32
|
+
`cargo clippy -- -D clippy::unwrap_used` on touched non-test code, or a grep
|
|
33
|
+
of the diff.
|
|
34
|
+
3. **Public API.** Condition: a `pub` item changes. Action: treat as a breaking
|
|
35
|
+
change unless it only adds; update docs and CHANGELOG. Exception: crate is
|
|
36
|
+
`publish = false` and private to the workspace. Verify: `cargo doc --no-deps`
|
|
37
|
+
and, for published crates, `cargo semver-checks` if installed.
|
|
38
|
+
4. **unsafe.** Condition: `unsafe` is needed. Action: smallest block, a `// SAFETY:`
|
|
39
|
+
comment stating the invariant, a safe wrapper. Exception: none for new
|
|
40
|
+
`unsafe` without an owner approval in the Task Card. Verify: Miri when the
|
|
41
|
+
toolchain has it, else a test of the invariant.
|
|
42
|
+
5. **Features** (`cargo.feature-unification`). Condition: a dependency or
|
|
43
|
+
feature changes. Action: remember Cargo unifies features across the build;
|
|
44
|
+
never rely on a feature being off. Features must be additive. Exception:
|
|
45
|
+
mutually exclusive features guarded by `compile_error!`. Verify: `cargo check
|
|
46
|
+
-p <package>` and `cargo check --workspace --all-targets`.
|
|
47
|
+
6. **Lockfile.** Condition: a dependency changes. Action: commit `Cargo.lock` for
|
|
48
|
+
binaries; justify each new dependency. Exception: libraries that gitignore
|
|
49
|
+
the lockfile. Verify: `cargo check --locked`.
|
|
50
|
+
|
|
51
|
+
## Decisions and exceptions
|
|
52
|
+
|
|
53
|
+
- Match the repository's formatting, naming and error style; do not import
|
|
54
|
+
personal preferences. Edition and MSRV come from `Cargo.toml`, not this skill.
|
|
55
|
+
- Do not add `anyhow`/`thiserror` unless already used or approved.
|
|
56
|
+
- Dependency added "just in case": reject; prefer `std`.
|
|
57
|
+
|
|
58
|
+
## Evidence
|
|
59
|
+
|
|
60
|
+
Report each command run with its exit code, per package: `cargo fmt --check`,
|
|
61
|
+
`cargo clippy --all-targets -- -D warnings`, `cargo test -p <package>`. A
|
|
62
|
+
check that was not run is reported as not run, never as passed.
|
|
63
|
+
|
|
64
|
+
## References
|
|
65
|
+
|
|
66
|
+
- Cargo features: https://doc.rust-lang.org/cargo/reference/features.html
|
|
67
|
+
- Cargo workspaces: https://doc.rust-lang.org/cargo/reference/workspaces.html
|
|
68
|
+
- Rust API Guidelines: https://rust-lang.github.io/api-guidelines/
|
|
69
|
+
- Unsafe code guidelines: https://doc.rust-lang.org/nomicon/
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: rust-sqlx
|
|
3
|
+
name: rust-sqlx
|
|
4
|
+
description: >
|
|
5
|
+
sqlx in Rust: query macros and offline metadata, pool acquisition,
|
|
6
|
+
transactions and migrations.
|
|
7
|
+
Trigger: When touching sqlx queries, pools, transactions, .sqlx metadata or migrations in a Rust package.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Rust sqlx
|
|
11
|
+
|
|
12
|
+
## Activation
|
|
13
|
+
|
|
14
|
+
Apply when the owning package declares `sqlx` (normal dependency) and the
|
|
15
|
+
change touches queries, pool/transaction code, `.sqlx/` or `migrations/`. For a
|
|
16
|
+
dev-only `sqlx`, apply to tests only.
|
|
17
|
+
|
|
18
|
+
## Inputs
|
|
19
|
+
|
|
20
|
+
- `sqlx` features (database driver, `migrate`, `offline`, runtime).
|
|
21
|
+
- `DATABASE_URL` source, `.sqlx/` directory, `migrations/` directory.
|
|
22
|
+
|
|
23
|
+
## Procedure
|
|
24
|
+
|
|
25
|
+
1. **Query macros.** Condition: `query!`/`query_as!` are used. Action: they check
|
|
26
|
+
against `DATABASE_URL` or the `.sqlx` metadata at build time. Any query or
|
|
27
|
+
schema change requires regenerating metadata. Exception: queries built with
|
|
28
|
+
non-macro `query()` are not checked at build. Verify: `cargo sqlx prepare
|
|
29
|
+
--check` (add `--workspace` in a workspace).
|
|
30
|
+
2. **Stale metadata** (`sqlx.metadata-stale`). Condition: queries or migrations
|
|
31
|
+
changed. Action: run `cargo sqlx prepare` against a database migrated to the
|
|
32
|
+
current schema and commit `.sqlx/`. Exception: repository builds only online.
|
|
33
|
+
Verify: `cargo sqlx prepare --check` exits 0; CI builds with `DATABASE_URL`
|
|
34
|
+
unset.
|
|
35
|
+
3. **Nested acquisition** (`sqlx.nested-acquisition`). Condition: code holds a
|
|
36
|
+
pooled connection or transaction and calls something that acquires another.
|
|
37
|
+
Action: pass the held `&mut` connection/transaction down; never acquire from
|
|
38
|
+
the pool while holding one. Exception: a pool sized above the maximum nesting,
|
|
39
|
+
documented. Verify: a test with `max_connections(1)` that does not time out
|
|
40
|
+
(`acquire_timeout` bounds the wait).
|
|
41
|
+
4. **Transactions.** Condition: several statements must succeed together.
|
|
42
|
+
Action: one transaction, explicit `commit()`; drop without commit rolls
|
|
43
|
+
back. Exception: independent idempotent statements. Verify: a test forcing
|
|
44
|
+
an error between statements and asserting no partial write.
|
|
45
|
+
5. **Migrations.** Apply `database-migrations` for content; here only: embed
|
|
46
|
+
with `sqlx::migrate!` and run once at startup or deploy, not per request.
|
|
47
|
+
|
|
48
|
+
## Decisions and exceptions
|
|
49
|
+
|
|
50
|
+
- Do not edit an applied migration; add a new one (checksums are validated).
|
|
51
|
+
- Do not widen pool size to hide a nested-acquisition bug.
|
|
52
|
+
- Unknown boundary (is this a data-access layer?): ask or report it; do not guess.
|
|
53
|
+
|
|
54
|
+
## Evidence
|
|
55
|
+
|
|
56
|
+
Exit code of `cargo sqlx prepare --check` and of `cargo test -p <package>`
|
|
57
|
+
with a database available. Without a database, report macros as unverified.
|
|
58
|
+
|
|
59
|
+
## References
|
|
60
|
+
|
|
61
|
+
- https://docs.rs/sqlx/latest/sqlx/macro.query.html (offline mode)
|
|
62
|
+
- https://github.com/launchbadge/sqlx/blob/main/sqlx-cli/README.md
|
|
63
|
+
- https://docs.rs/sqlx/latest/sqlx/macro.migrate.html
|
|
64
|
+
- https://docs.rs/sqlx/latest/sqlx/pool/struct.PoolOptions.html
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: database-migrations
|
|
3
|
+
name: database-migrations
|
|
4
|
+
description: >
|
|
5
|
+
Safe schema and data migrations: ordering, immutability, locks, backfills,
|
|
6
|
+
persisted enums and rollback.
|
|
7
|
+
Trigger: When creating or editing files under migrations/, db/migrate or any .sql file.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Database migrations
|
|
11
|
+
|
|
12
|
+
## Activation
|
|
13
|
+
|
|
14
|
+
Apply to any file under `migrations/` or `db/migrate/` and to `.sql` files,
|
|
15
|
+
in any language or ORM. Migration paths are high risk; do not lower it.
|
|
16
|
+
|
|
17
|
+
## Inputs
|
|
18
|
+
|
|
19
|
+
- The migration tool and its ordering/checksum rules.
|
|
20
|
+
- Target engine and version; table size and traffic when known.
|
|
21
|
+
- Code that reads or writes the changed columns.
|
|
22
|
+
|
|
23
|
+
## Procedure
|
|
24
|
+
|
|
25
|
+
1. **Immutability.** Condition: a migration was already applied anywhere
|
|
26
|
+
shared. Action: add a new migration; never edit the old one. Exception:
|
|
27
|
+
unmerged local migration. Verify: `git diff` shows only new files in
|
|
28
|
+
`migrations/`.
|
|
29
|
+
2. **Unique on existing data** (`migration.unique-existing-data`). Condition:
|
|
30
|
+
adding a unique index or constraint. Action: first query for duplicates,
|
|
31
|
+
deduplicate or fail with a clear message, then add the constraint. Exception:
|
|
32
|
+
table is provably empty in every environment. Verify: a test migrating a
|
|
33
|
+
fixture with duplicates.
|
|
34
|
+
3. **Persisted enums** (`data.persisted-enum`). Condition: an enum is stored.
|
|
35
|
+
Action: store a stable code, not an ordinal or a name that may be
|
|
36
|
+
renamed; additions are additive, removals need a data migration. Exception:
|
|
37
|
+
none for stored values. Verify: a test reading a row written by the previous
|
|
38
|
+
version.
|
|
39
|
+
4. **Locks and backfills.** Condition: large table. Action: split into add
|
|
40
|
+
nullable column, batched backfill, then constraint; use the engine's
|
|
41
|
+
non-blocking index option where available. Exception: small tables. Verify:
|
|
42
|
+
state the lock taken and the expected duration in the Evidence.
|
|
43
|
+
5. **Rollback.** Condition: every migration. Action: write the down step or
|
|
44
|
+
state that the change is forward-only and why. Verify: apply, roll back
|
|
45
|
+
(or restore) and re-apply on a scratch database.
|
|
46
|
+
6. **Code compatibility.** Condition: a column is dropped or renamed. Action:
|
|
47
|
+
deploy code that stops using it first (expand/contract). Verify: grep shows
|
|
48
|
+
no remaining reader.
|
|
49
|
+
|
|
50
|
+
## Decisions and exceptions
|
|
51
|
+
|
|
52
|
+
- Mixing schema change and large data change in one migration: split.
|
|
53
|
+
- Destructive statements (`DROP`, `TRUNCATE`) need explicit Task Card approval.
|
|
54
|
+
|
|
55
|
+
## Evidence
|
|
56
|
+
|
|
57
|
+
The command that applied the migration on a scratch database, its exit code,
|
|
58
|
+
and the rollback result. Without a database, report the migration as unrun.
|
|
59
|
+
|
|
60
|
+
## References
|
|
61
|
+
|
|
62
|
+
- https://martinfowler.com/articles/evodb.html
|
|
63
|
+
- https://www.postgresql.org/docs/current/sql-altertable.html
|
|
64
|
+
- https://docs.rs/sqlx/latest/sqlx/macro.migrate.html
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: rust-async
|
|
3
|
+
name: rust-async
|
|
4
|
+
description: >
|
|
5
|
+
Rust async with tokio or async-std: guards across await, detached tasks,
|
|
6
|
+
blocking work, cancellation and shutdown.
|
|
7
|
+
Trigger: When writing or reviewing async Rust in a package that declares tokio or async-std.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Rust async
|
|
11
|
+
|
|
12
|
+
## Activation
|
|
13
|
+
|
|
14
|
+
Apply when the owning package declares `tokio` or `async-std` as a normal
|
|
15
|
+
dependency and the change touches `async fn`, `.await`, `spawn` or channels.
|
|
16
|
+
|
|
17
|
+
## Inputs
|
|
18
|
+
|
|
19
|
+
- Declared runtime, its features (`rt`, `rt-multi-thread`, `sync`, `time`).
|
|
20
|
+
- Existing shutdown path (`CancellationToken`, signal handler, `JoinSet`).
|
|
21
|
+
|
|
22
|
+
## Procedure
|
|
23
|
+
|
|
24
|
+
1. **Guards across await** (`rust.guard-across-await`). Condition: a
|
|
25
|
+
`std::sync::MutexGuard`/`RwLock` guard or `RefCell` borrow is live at an
|
|
26
|
+
`.await`. Action: scope the guard in a block that ends before the await, or
|
|
27
|
+
copy out the data. Use `tokio::sync::Mutex` only when the lock must be held
|
|
28
|
+
across the await. Exception: none for std guards (the future becomes `!Send`
|
|
29
|
+
or can deadlock). Verify: `cargo check`; a `Send` bound compile error on
|
|
30
|
+
`spawn` is the signal.
|
|
31
|
+
2. **Detached tasks** (`rust.detached-task`). Condition: `spawn` result is
|
|
32
|
+
dropped. Action: dropping a `JoinHandle` detaches the task; keep the handle
|
|
33
|
+
or use a `JoinSet`, and decide who observes panics and errors. Exception:
|
|
34
|
+
fire-and-forget with logged failure and no shutdown dependency. Verify: each
|
|
35
|
+
`spawn` has an owner that is awaited or aborted at shutdown.
|
|
36
|
+
3. **Blocking work.** Condition: CPU-heavy or blocking I/O inside async code.
|
|
37
|
+
Action: `tokio::task::spawn_blocking`. Exception: work shorter than a
|
|
38
|
+
scheduling quantum. Verify: no `std::thread::sleep` or blocking
|
|
39
|
+
`std::fs`/`std::net` call in an `async fn`.
|
|
40
|
+
4. **Cancellation.** Condition: a future may be dropped at any `.await`. Action:
|
|
41
|
+
keep state consistent at every await; use cancel-safe operations in
|
|
42
|
+
`select!`. `abort()` does not stop a `spawn_blocking` task that already
|
|
43
|
+
started. Exception: none. Verify: a test that drops the future mid-operation.
|
|
44
|
+
5. **Shutdown.** Condition: the service owns tasks. Action: signal, then await
|
|
45
|
+
handles with a timeout. Started `spawn_blocking` tasks run to completion, so
|
|
46
|
+
bound their runtime. Verify: a test or run that shuts down without hanging.
|
|
47
|
+
|
|
48
|
+
## Decisions and exceptions
|
|
49
|
+
|
|
50
|
+
- Do not change runtime flavor or add features without a Task Card line.
|
|
51
|
+
- `async-std` and `tokio` APIs differ; follow the declared runtime only.
|
|
52
|
+
- Unbounded channels need a stated reason; default to bounded.
|
|
53
|
+
|
|
54
|
+
## Evidence
|
|
55
|
+
|
|
56
|
+
`cargo test -p <package>` with the exit code, plus the named test that drops
|
|
57
|
+
or aborts the future. Report unverified cancellation paths as unverified.
|
|
58
|
+
|
|
59
|
+
## References
|
|
60
|
+
|
|
61
|
+
- https://docs.rs/tokio/latest/tokio/task/fn.spawn_blocking.html
|
|
62
|
+
- https://docs.rs/tokio/latest/tokio/task/struct.JoinHandle.html
|
|
63
|
+
- https://docs.rs/tokio/latest/tokio/sync/struct.Mutex.html
|
|
64
|
+
- https://tokio.rs/tokio/topics/shutdown
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: rust-engineering
|
|
3
|
+
name: rust-engineering
|
|
4
|
+
description: >
|
|
5
|
+
Rust engineering baseline: Cargo workspaces and features, error types,
|
|
6
|
+
unsafe, public API, lints and verification.
|
|
7
|
+
Trigger: When editing .rs files, Cargo.toml or Cargo.lock in a Rust package.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Rust engineering
|
|
11
|
+
|
|
12
|
+
## Activation
|
|
13
|
+
|
|
14
|
+
Apply to any `.rs`, `Cargo.toml` or `Cargo.lock` change. Rules are defaults;
|
|
15
|
+
a repository rule with the same id wins over this skill.
|
|
16
|
+
|
|
17
|
+
## Inputs
|
|
18
|
+
|
|
19
|
+
- Nearest `Cargo.toml` (package, `[features]`, `[lints]`) and workspace root.
|
|
20
|
+
- `rust-toolchain.toml`, `clippy.toml`, `rustfmt.toml` when present.
|
|
21
|
+
- The repository's existing error type and module layout.
|
|
22
|
+
|
|
23
|
+
## Procedure
|
|
24
|
+
|
|
25
|
+
1. **Locate the package.** Condition: a change spans crates. Action: resolve the
|
|
26
|
+
owning package per file and run checks with `-p <package>`. Exception: a
|
|
27
|
+
workspace-wide refactor named in the Task Card. Verify: `cargo metadata
|
|
28
|
+
--no-deps --format-version 1` lists the package.
|
|
29
|
+
2. **Errors.** Condition: a function can fail. Action: return `Result` with the
|
|
30
|
+
crate's existing error type; add context where the error crosses a module
|
|
31
|
+
boundary. Exception: tests and examples may `unwrap`/`expect`. Verify:
|
|
32
|
+
`cargo clippy -- -D clippy::unwrap_used` on touched non-test code, or a grep
|
|
33
|
+
of the diff.
|
|
34
|
+
3. **Public API.** Condition: a `pub` item changes. Action: treat as a breaking
|
|
35
|
+
change unless it only adds; update docs and CHANGELOG. Exception: crate is
|
|
36
|
+
`publish = false` and private to the workspace. Verify: `cargo doc --no-deps`
|
|
37
|
+
and, for published crates, `cargo semver-checks` if installed.
|
|
38
|
+
4. **unsafe.** Condition: `unsafe` is needed. Action: smallest block, a `// SAFETY:`
|
|
39
|
+
comment stating the invariant, a safe wrapper. Exception: none for new
|
|
40
|
+
`unsafe` without an owner approval in the Task Card. Verify: Miri when the
|
|
41
|
+
toolchain has it, else a test of the invariant.
|
|
42
|
+
5. **Features** (`cargo.feature-unification`). Condition: a dependency or
|
|
43
|
+
feature changes. Action: remember Cargo unifies features across the build;
|
|
44
|
+
never rely on a feature being off. Features must be additive. Exception:
|
|
45
|
+
mutually exclusive features guarded by `compile_error!`. Verify: `cargo check
|
|
46
|
+
-p <package>` and `cargo check --workspace --all-targets`.
|
|
47
|
+
6. **Lockfile.** Condition: a dependency changes. Action: commit `Cargo.lock` for
|
|
48
|
+
binaries; justify each new dependency. Exception: libraries that gitignore
|
|
49
|
+
the lockfile. Verify: `cargo check --locked`.
|
|
50
|
+
|
|
51
|
+
## Decisions and exceptions
|
|
52
|
+
|
|
53
|
+
- Match the repository's formatting, naming and error style; do not import
|
|
54
|
+
personal preferences. Edition and MSRV come from `Cargo.toml`, not this skill.
|
|
55
|
+
- Do not add `anyhow`/`thiserror` unless already used or approved.
|
|
56
|
+
- Dependency added "just in case": reject; prefer `std`.
|
|
57
|
+
|
|
58
|
+
## Evidence
|
|
59
|
+
|
|
60
|
+
Report each command run with its exit code, per package: `cargo fmt --check`,
|
|
61
|
+
`cargo clippy --all-targets -- -D warnings`, `cargo test -p <package>`. A
|
|
62
|
+
check that was not run is reported as not run, never as passed.
|
|
63
|
+
|
|
64
|
+
## References
|
|
65
|
+
|
|
66
|
+
- Cargo features: https://doc.rust-lang.org/cargo/reference/features.html
|
|
67
|
+
- Cargo workspaces: https://doc.rust-lang.org/cargo/reference/workspaces.html
|
|
68
|
+
- Rust API Guidelines: https://rust-lang.github.io/api-guidelines/
|
|
69
|
+
- Unsafe code guidelines: https://doc.rust-lang.org/nomicon/
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: rust-sqlx
|
|
3
|
+
name: rust-sqlx
|
|
4
|
+
description: >
|
|
5
|
+
sqlx in Rust: query macros and offline metadata, pool acquisition,
|
|
6
|
+
transactions and migrations.
|
|
7
|
+
Trigger: When touching sqlx queries, pools, transactions, .sqlx metadata or migrations in a Rust package.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Rust sqlx
|
|
11
|
+
|
|
12
|
+
## Activation
|
|
13
|
+
|
|
14
|
+
Apply when the owning package declares `sqlx` (normal dependency) and the
|
|
15
|
+
change touches queries, pool/transaction code, `.sqlx/` or `migrations/`. For a
|
|
16
|
+
dev-only `sqlx`, apply to tests only.
|
|
17
|
+
|
|
18
|
+
## Inputs
|
|
19
|
+
|
|
20
|
+
- `sqlx` features (database driver, `migrate`, `offline`, runtime).
|
|
21
|
+
- `DATABASE_URL` source, `.sqlx/` directory, `migrations/` directory.
|
|
22
|
+
|
|
23
|
+
## Procedure
|
|
24
|
+
|
|
25
|
+
1. **Query macros.** Condition: `query!`/`query_as!` are used. Action: they check
|
|
26
|
+
against `DATABASE_URL` or the `.sqlx` metadata at build time. Any query or
|
|
27
|
+
schema change requires regenerating metadata. Exception: queries built with
|
|
28
|
+
non-macro `query()` are not checked at build. Verify: `cargo sqlx prepare
|
|
29
|
+
--check` (add `--workspace` in a workspace).
|
|
30
|
+
2. **Stale metadata** (`sqlx.metadata-stale`). Condition: queries or migrations
|
|
31
|
+
changed. Action: run `cargo sqlx prepare` against a database migrated to the
|
|
32
|
+
current schema and commit `.sqlx/`. Exception: repository builds only online.
|
|
33
|
+
Verify: `cargo sqlx prepare --check` exits 0; CI builds with `DATABASE_URL`
|
|
34
|
+
unset.
|
|
35
|
+
3. **Nested acquisition** (`sqlx.nested-acquisition`). Condition: code holds a
|
|
36
|
+
pooled connection or transaction and calls something that acquires another.
|
|
37
|
+
Action: pass the held `&mut` connection/transaction down; never acquire from
|
|
38
|
+
the pool while holding one. Exception: a pool sized above the maximum nesting,
|
|
39
|
+
documented. Verify: a test with `max_connections(1)` that does not time out
|
|
40
|
+
(`acquire_timeout` bounds the wait).
|
|
41
|
+
4. **Transactions.** Condition: several statements must succeed together.
|
|
42
|
+
Action: one transaction, explicit `commit()`; drop without commit rolls
|
|
43
|
+
back. Exception: independent idempotent statements. Verify: a test forcing
|
|
44
|
+
an error between statements and asserting no partial write.
|
|
45
|
+
5. **Migrations.** Apply `database-migrations` for content; here only: embed
|
|
46
|
+
with `sqlx::migrate!` and run once at startup or deploy, not per request.
|
|
47
|
+
|
|
48
|
+
## Decisions and exceptions
|
|
49
|
+
|
|
50
|
+
- Do not edit an applied migration; add a new one (checksums are validated).
|
|
51
|
+
- Do not widen pool size to hide a nested-acquisition bug.
|
|
52
|
+
- Unknown boundary (is this a data-access layer?): ask or report it; do not guess.
|
|
53
|
+
|
|
54
|
+
## Evidence
|
|
55
|
+
|
|
56
|
+
Exit code of `cargo sqlx prepare --check` and of `cargo test -p <package>`
|
|
57
|
+
with a database available. Without a database, report macros as unverified.
|
|
58
|
+
|
|
59
|
+
## References
|
|
60
|
+
|
|
61
|
+
- https://docs.rs/sqlx/latest/sqlx/macro.query.html (offline mode)
|
|
62
|
+
- https://github.com/launchbadge/sqlx/blob/main/sqlx-cli/README.md
|
|
63
|
+
- https://docs.rs/sqlx/latest/sqlx/macro.migrate.html
|
|
64
|
+
- https://docs.rs/sqlx/latest/sqlx/pool/struct.PoolOptions.html
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: database-migrations
|
|
3
|
+
name: database-migrations
|
|
4
|
+
description: >
|
|
5
|
+
Safe schema and data migrations: ordering, immutability, locks, backfills,
|
|
6
|
+
persisted enums and rollback.
|
|
7
|
+
Trigger: When creating or editing files under migrations/, db/migrate or any .sql file.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Database migrations
|
|
11
|
+
|
|
12
|
+
## Activation
|
|
13
|
+
|
|
14
|
+
Apply to any file under `migrations/` or `db/migrate/` and to `.sql` files,
|
|
15
|
+
in any language or ORM. Migration paths are high risk; do not lower it.
|
|
16
|
+
|
|
17
|
+
## Inputs
|
|
18
|
+
|
|
19
|
+
- The migration tool and its ordering/checksum rules.
|
|
20
|
+
- Target engine and version; table size and traffic when known.
|
|
21
|
+
- Code that reads or writes the changed columns.
|
|
22
|
+
|
|
23
|
+
## Procedure
|
|
24
|
+
|
|
25
|
+
1. **Immutability.** Condition: a migration was already applied anywhere
|
|
26
|
+
shared. Action: add a new migration; never edit the old one. Exception:
|
|
27
|
+
unmerged local migration. Verify: `git diff` shows only new files in
|
|
28
|
+
`migrations/`.
|
|
29
|
+
2. **Unique on existing data** (`migration.unique-existing-data`). Condition:
|
|
30
|
+
adding a unique index or constraint. Action: first query for duplicates,
|
|
31
|
+
deduplicate or fail with a clear message, then add the constraint. Exception:
|
|
32
|
+
table is provably empty in every environment. Verify: a test migrating a
|
|
33
|
+
fixture with duplicates.
|
|
34
|
+
3. **Persisted enums** (`data.persisted-enum`). Condition: an enum is stored.
|
|
35
|
+
Action: store a stable code, not an ordinal or a name that may be
|
|
36
|
+
renamed; additions are additive, removals need a data migration. Exception:
|
|
37
|
+
none for stored values. Verify: a test reading a row written by the previous
|
|
38
|
+
version.
|
|
39
|
+
4. **Locks and backfills.** Condition: large table. Action: split into add
|
|
40
|
+
nullable column, batched backfill, then constraint; use the engine's
|
|
41
|
+
non-blocking index option where available. Exception: small tables. Verify:
|
|
42
|
+
state the lock taken and the expected duration in the Evidence.
|
|
43
|
+
5. **Rollback.** Condition: every migration. Action: write the down step or
|
|
44
|
+
state that the change is forward-only and why. Verify: apply, roll back
|
|
45
|
+
(or restore) and re-apply on a scratch database.
|
|
46
|
+
6. **Code compatibility.** Condition: a column is dropped or renamed. Action:
|
|
47
|
+
deploy code that stops using it first (expand/contract). Verify: grep shows
|
|
48
|
+
no remaining reader.
|
|
49
|
+
|
|
50
|
+
## Decisions and exceptions
|
|
51
|
+
|
|
52
|
+
- Mixing schema change and large data change in one migration: split.
|
|
53
|
+
- Destructive statements (`DROP`, `TRUNCATE`) need explicit Task Card approval.
|
|
54
|
+
|
|
55
|
+
## Evidence
|
|
56
|
+
|
|
57
|
+
The command that applied the migration on a scratch database, its exit code,
|
|
58
|
+
and the rollback result. Without a database, report the migration as unrun.
|
|
59
|
+
|
|
60
|
+
## References
|
|
61
|
+
|
|
62
|
+
- https://martinfowler.com/articles/evodb.html
|
|
63
|
+
- https://www.postgresql.org/docs/current/sql-altertable.html
|
|
64
|
+
- https://docs.rs/sqlx/latest/sqlx/macro.migrate.html
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: rust-async
|
|
3
|
+
name: rust-async
|
|
4
|
+
description: >
|
|
5
|
+
Rust async with tokio or async-std: guards across await, detached tasks,
|
|
6
|
+
blocking work, cancellation and shutdown.
|
|
7
|
+
Trigger: When writing or reviewing async Rust in a package that declares tokio or async-std.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Rust async
|
|
11
|
+
|
|
12
|
+
## Activation
|
|
13
|
+
|
|
14
|
+
Apply when the owning package declares `tokio` or `async-std` as a normal
|
|
15
|
+
dependency and the change touches `async fn`, `.await`, `spawn` or channels.
|
|
16
|
+
|
|
17
|
+
## Inputs
|
|
18
|
+
|
|
19
|
+
- Declared runtime, its features (`rt`, `rt-multi-thread`, `sync`, `time`).
|
|
20
|
+
- Existing shutdown path (`CancellationToken`, signal handler, `JoinSet`).
|
|
21
|
+
|
|
22
|
+
## Procedure
|
|
23
|
+
|
|
24
|
+
1. **Guards across await** (`rust.guard-across-await`). Condition: a
|
|
25
|
+
`std::sync::MutexGuard`/`RwLock` guard or `RefCell` borrow is live at an
|
|
26
|
+
`.await`. Action: scope the guard in a block that ends before the await, or
|
|
27
|
+
copy out the data. Use `tokio::sync::Mutex` only when the lock must be held
|
|
28
|
+
across the await. Exception: none for std guards (the future becomes `!Send`
|
|
29
|
+
or can deadlock). Verify: `cargo check`; a `Send` bound compile error on
|
|
30
|
+
`spawn` is the signal.
|
|
31
|
+
2. **Detached tasks** (`rust.detached-task`). Condition: `spawn` result is
|
|
32
|
+
dropped. Action: dropping a `JoinHandle` detaches the task; keep the handle
|
|
33
|
+
or use a `JoinSet`, and decide who observes panics and errors. Exception:
|
|
34
|
+
fire-and-forget with logged failure and no shutdown dependency. Verify: each
|
|
35
|
+
`spawn` has an owner that is awaited or aborted at shutdown.
|
|
36
|
+
3. **Blocking work.** Condition: CPU-heavy or blocking I/O inside async code.
|
|
37
|
+
Action: `tokio::task::spawn_blocking`. Exception: work shorter than a
|
|
38
|
+
scheduling quantum. Verify: no `std::thread::sleep` or blocking
|
|
39
|
+
`std::fs`/`std::net` call in an `async fn`.
|
|
40
|
+
4. **Cancellation.** Condition: a future may be dropped at any `.await`. Action:
|
|
41
|
+
keep state consistent at every await; use cancel-safe operations in
|
|
42
|
+
`select!`. `abort()` does not stop a `spawn_blocking` task that already
|
|
43
|
+
started. Exception: none. Verify: a test that drops the future mid-operation.
|
|
44
|
+
5. **Shutdown.** Condition: the service owns tasks. Action: signal, then await
|
|
45
|
+
handles with a timeout. Started `spawn_blocking` tasks run to completion, so
|
|
46
|
+
bound their runtime. Verify: a test or run that shuts down without hanging.
|
|
47
|
+
|
|
48
|
+
## Decisions and exceptions
|
|
49
|
+
|
|
50
|
+
- Do not change runtime flavor or add features without a Task Card line.
|
|
51
|
+
- `async-std` and `tokio` APIs differ; follow the declared runtime only.
|
|
52
|
+
- Unbounded channels need a stated reason; default to bounded.
|
|
53
|
+
|
|
54
|
+
## Evidence
|
|
55
|
+
|
|
56
|
+
`cargo test -p <package>` with the exit code, plus the named test that drops
|
|
57
|
+
or aborts the future. Report unverified cancellation paths as unverified.
|
|
58
|
+
|
|
59
|
+
## References
|
|
60
|
+
|
|
61
|
+
- https://docs.rs/tokio/latest/tokio/task/fn.spawn_blocking.html
|
|
62
|
+
- https://docs.rs/tokio/latest/tokio/task/struct.JoinHandle.html
|
|
63
|
+
- https://docs.rs/tokio/latest/tokio/sync/struct.Mutex.html
|
|
64
|
+
- https://tokio.rs/tokio/topics/shutdown
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: rust-engineering
|
|
3
|
+
name: rust-engineering
|
|
4
|
+
description: >
|
|
5
|
+
Rust engineering baseline: Cargo workspaces and features, error types,
|
|
6
|
+
unsafe, public API, lints and verification.
|
|
7
|
+
Trigger: When editing .rs files, Cargo.toml or Cargo.lock in a Rust package.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Rust engineering
|
|
11
|
+
|
|
12
|
+
## Activation
|
|
13
|
+
|
|
14
|
+
Apply to any `.rs`, `Cargo.toml` or `Cargo.lock` change. Rules are defaults;
|
|
15
|
+
a repository rule with the same id wins over this skill.
|
|
16
|
+
|
|
17
|
+
## Inputs
|
|
18
|
+
|
|
19
|
+
- Nearest `Cargo.toml` (package, `[features]`, `[lints]`) and workspace root.
|
|
20
|
+
- `rust-toolchain.toml`, `clippy.toml`, `rustfmt.toml` when present.
|
|
21
|
+
- The repository's existing error type and module layout.
|
|
22
|
+
|
|
23
|
+
## Procedure
|
|
24
|
+
|
|
25
|
+
1. **Locate the package.** Condition: a change spans crates. Action: resolve the
|
|
26
|
+
owning package per file and run checks with `-p <package>`. Exception: a
|
|
27
|
+
workspace-wide refactor named in the Task Card. Verify: `cargo metadata
|
|
28
|
+
--no-deps --format-version 1` lists the package.
|
|
29
|
+
2. **Errors.** Condition: a function can fail. Action: return `Result` with the
|
|
30
|
+
crate's existing error type; add context where the error crosses a module
|
|
31
|
+
boundary. Exception: tests and examples may `unwrap`/`expect`. Verify:
|
|
32
|
+
`cargo clippy -- -D clippy::unwrap_used` on touched non-test code, or a grep
|
|
33
|
+
of the diff.
|
|
34
|
+
3. **Public API.** Condition: a `pub` item changes. Action: treat as a breaking
|
|
35
|
+
change unless it only adds; update docs and CHANGELOG. Exception: crate is
|
|
36
|
+
`publish = false` and private to the workspace. Verify: `cargo doc --no-deps`
|
|
37
|
+
and, for published crates, `cargo semver-checks` if installed.
|
|
38
|
+
4. **unsafe.** Condition: `unsafe` is needed. Action: smallest block, a `// SAFETY:`
|
|
39
|
+
comment stating the invariant, a safe wrapper. Exception: none for new
|
|
40
|
+
`unsafe` without an owner approval in the Task Card. Verify: Miri when the
|
|
41
|
+
toolchain has it, else a test of the invariant.
|
|
42
|
+
5. **Features** (`cargo.feature-unification`). Condition: a dependency or
|
|
43
|
+
feature changes. Action: remember Cargo unifies features across the build;
|
|
44
|
+
never rely on a feature being off. Features must be additive. Exception:
|
|
45
|
+
mutually exclusive features guarded by `compile_error!`. Verify: `cargo check
|
|
46
|
+
-p <package>` and `cargo check --workspace --all-targets`.
|
|
47
|
+
6. **Lockfile.** Condition: a dependency changes. Action: commit `Cargo.lock` for
|
|
48
|
+
binaries; justify each new dependency. Exception: libraries that gitignore
|
|
49
|
+
the lockfile. Verify: `cargo check --locked`.
|
|
50
|
+
|
|
51
|
+
## Decisions and exceptions
|
|
52
|
+
|
|
53
|
+
- Match the repository's formatting, naming and error style; do not import
|
|
54
|
+
personal preferences. Edition and MSRV come from `Cargo.toml`, not this skill.
|
|
55
|
+
- Do not add `anyhow`/`thiserror` unless already used or approved.
|
|
56
|
+
- Dependency added "just in case": reject; prefer `std`.
|
|
57
|
+
|
|
58
|
+
## Evidence
|
|
59
|
+
|
|
60
|
+
Report each command run with its exit code, per package: `cargo fmt --check`,
|
|
61
|
+
`cargo clippy --all-targets -- -D warnings`, `cargo test -p <package>`. A
|
|
62
|
+
check that was not run is reported as not run, never as passed.
|
|
63
|
+
|
|
64
|
+
## References
|
|
65
|
+
|
|
66
|
+
- Cargo features: https://doc.rust-lang.org/cargo/reference/features.html
|
|
67
|
+
- Cargo workspaces: https://doc.rust-lang.org/cargo/reference/workspaces.html
|
|
68
|
+
- Rust API Guidelines: https://rust-lang.github.io/api-guidelines/
|
|
69
|
+
- Unsafe code guidelines: https://doc.rust-lang.org/nomicon/
|