ronce-racine 0.5.0
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/AGENTS.md +90 -0
- package/LICENSE +21 -0
- package/README.md +281 -0
- package/agents/code-reviewer.md +33 -0
- package/agents/qa-tester.md +28 -0
- package/dist/hooks/README.md +182 -0
- package/dist/hooks/bash-npm-silent.mjs +81 -0
- package/dist/hooks/session-inject.mjs +53 -0
- package/dist/hooks/session-precompact.mjs +36 -0
- package/dist/hooks/session-writer.mjs +142 -0
- package/dist/hooks/skill-reminder.mjs +89 -0
- package/dist/hooks/truncate-bash-output.mjs +46 -0
- package/dist/hooks/truncate-output.mjs +88 -0
- package/dist/hooks/worktree-env-setup.mjs +123 -0
- package/dist/install.js +962 -0
- package/docs/adopting-a-repo.md +80 -0
- package/docs/architecture.md +76 -0
- package/docs/decisions.md +72 -0
- package/docs/developing.md +143 -0
- package/docs/evaluating-skills.md +41 -0
- package/docs/git-worktrees.md +62 -0
- package/docs/rules/clean-architecture-deps.md +66 -0
- package/docs/rules/commits.md +59 -0
- package/docs/rules/detection-gap-protocol.md +55 -0
- package/docs/rules/error-handling-discipline.md +62 -0
- package/docs/rules/minimal-code.md +58 -0
- package/docs/rules/no-raw-sql-interpolation.md +57 -0
- package/docs/rules/pre-commit-secret-detection.md +54 -0
- package/docs/rules/secure-logging.md +53 -0
- package/docs/rules/sql-migrations-discipline.md +58 -0
- package/docs/rules/subscription-cleanup.md +63 -0
- package/docs/rules/test-discipline.md +66 -0
- package/docs/rules/ui-states-complete.md +52 -0
- package/docs/templates/SKILL.template.md +66 -0
- package/docs/templates/rule.template.md +16 -0
- package/docs/writing-a-rule.md +43 -0
- package/docs/writing-a-skill.md +118 -0
- package/package.json +45 -0
- package/rules/clean-architecture-deps.md +20 -0
- package/rules/commits.md +16 -0
- package/rules/detection-gap-protocol.md +35 -0
- package/rules/error-handling-discipline.md +23 -0
- package/rules/minimal-code.md +32 -0
- package/rules/no-raw-sql-interpolation.md +20 -0
- package/rules/pre-commit-secret-detection.md +14 -0
- package/rules/secure-logging.md +16 -0
- package/rules/sql-migrations-discipline.md +18 -0
- package/rules/subscription-cleanup.md +22 -0
- package/rules/test-discipline.md +20 -0
- package/rules/ui-states-complete.md +23 -0
- package/scripts/subscription-leak-scan.ts +53 -0
- package/skills/adversarial-feature-challenge/README.md +65 -0
- package/skills/adversarial-feature-challenge/SKILL.md +96 -0
- package/skills/adversarial-feature-challenge/assets/fuzz-payloads.txt +60 -0
- package/skills/adversarial-feature-challenge/templates/challenge-report.md +42 -0
- package/skills/api-contract-versioning/README.md +62 -0
- package/skills/api-contract-versioning/SKILL.md +76 -0
- package/skills/api-contract-versioning/templates/consumer-inventory.md +29 -0
- package/skills/audit-architecture/README.md +56 -0
- package/skills/audit-architecture/SKILL.md +97 -0
- package/skills/audit-architecture/reference/ar-architecture.md +275 -0
- package/skills/audit-architecture/reference/di-disponibilite.md +252 -0
- package/skills/audit-architecture/reference/im-incidents.md +217 -0
- package/skills/audit-architecture/reference/pa-pannes.md +362 -0
- package/skills/audit-architecture/reference/re-recuperation.md +300 -0
- package/skills/audit-architecture/reference/sc-scalabilite.md +173 -0
- package/skills/audit-architecture/reference/su-support.md +180 -0
- package/skills/audit-ci-cd/README.md +54 -0
- package/skills/audit-ci-cd/SKILL.md +124 -0
- package/skills/audit-ci-cd/reference/artefacts.md +39 -0
- package/skills/audit-ci-cd/reference/deploiement.md +100 -0
- package/skills/audit-ci-cd/reference/dora.md +94 -0
- package/skills/audit-ci-cd/reference/iac.md +40 -0
- package/skills/audit-ci-cd/reference/pipeline-ci.md +36 -0
- package/skills/audit-ci-cd/reference/supply-chain.md +44 -0
- package/skills/audit-compliance/README.md +69 -0
- package/skills/audit-compliance/SKILL.md +176 -0
- package/skills/audit-compliance/reference/conformite-rgpd.md +295 -0
- package/skills/audit-compliance/reference/finops.md +318 -0
- package/skills/audit-compliance/reference/gouvernance-donnees.md +238 -0
- package/skills/audit-industrialisation/README.md +53 -0
- package/skills/audit-industrialisation/SKILL.md +251 -0
- package/skills/audit-observability/README.md +64 -0
- package/skills/audit-observability/SKILL.md +134 -0
- package/skills/audit-observability/reference/alerting.md +214 -0
- package/skills/audit-observability/reference/logging.md +114 -0
- package/skills/audit-observability/reference/metriques.md +166 -0
- package/skills/audit-observability/reference/traces-dashboards.md +90 -0
- package/skills/audit-performance-frontend/README.md +91 -0
- package/skills/audit-performance-frontend/SKILL.md +194 -0
- package/skills/audit-performance-frontend/reference/assets-cache-network.md +129 -0
- package/skills/audit-performance-frontend/reference/css-rendering-pipeline.md +154 -0
- package/skills/audit-performance-frontend/reference/html-critical-path.md +128 -0
- package/skills/audit-performance-frontend/reference/js-engine-runtime.md +280 -0
- package/skills/audit-performance-frontend/reference/memory-gc.md +126 -0
- package/skills/audit-performance-frontend/reference/profiling-tooling.md +98 -0
- package/skills/audit-quality/README.md +85 -0
- package/skills/audit-quality/SKILL.md +126 -0
- package/skills/audit-quality/reference/qa-devops.md +539 -0
- package/skills/audit-quality/reference/qu-qualite-donnees.md +402 -0
- package/skills/audit-report/README.md +72 -0
- package/skills/audit-report/SKILL.md +241 -0
- package/skills/audit-report/reference/scoring-model.md +45 -0
- package/skills/audit-security/README.md +72 -0
- package/skills/audit-security/SKILL.md +140 -0
- package/skills/audit-security/reference/auth-identite.md +98 -0
- package/skills/audit-security/reference/autorisation.md +66 -0
- package/skills/audit-security/reference/chiffrement-tls.md +97 -0
- package/skills/audit-security/reference/detection-patching.md +67 -0
- package/skills/audit-security/reference/incident-response.md +98 -0
- package/skills/audit-security/reference/reseau-conteneurs.md +72 -0
- package/skills/audit-security/reference/secrets.md +36 -0
- package/skills/audit-testing/README.md +82 -0
- package/skills/audit-testing/SKILL.md +131 -0
- package/skills/audit-testing/reference/golden-dataset.md +65 -0
- package/skills/audit-testing/reference/resilience-chaos.md +93 -0
- package/skills/audit-testing/reference/tests-contractuels.md +65 -0
- package/skills/audit-testing/reference/tests-e2e-flaky.md +67 -0
- package/skills/audit-testing/reference/tests-unit-integ-ci.md +125 -0
- package/skills/bug-ticket-root-cause/README.md +67 -0
- package/skills/bug-ticket-root-cause/SKILL.md +86 -0
- package/skills/bug-ticket-root-cause/templates/bug-ticket.md +43 -0
- package/skills/bug-triage-structured/README.md +63 -0
- package/skills/bug-triage-structured/SKILL.md +104 -0
- package/skills/bug-triage-structured/templates/bug-triage.md +38 -0
- package/skills/ci-pipeline-orchestration/README.md +55 -0
- package/skills/ci-pipeline-orchestration/SKILL.md +110 -0
- package/skills/commit-readiness-review/README.md +66 -0
- package/skills/commit-readiness-review/SKILL.md +82 -0
- package/skills/commit-readiness-review/scripts/precommit-scan.ts +81 -0
- package/skills/comprehensive-test-strategy/README.md +64 -0
- package/skills/comprehensive-test-strategy/SKILL.md +108 -0
- package/skills/comprehensive-test-strategy/reference/testing-advanced.md +85 -0
- package/skills/daily-workflow-optimization/README.md +56 -0
- package/skills/daily-workflow-optimization/SKILL.md +80 -0
- package/skills/database-schema-evolution/README.md +54 -0
- package/skills/database-schema-evolution/SKILL.md +107 -0
- package/skills/ddd-backend-implementation/README.md +63 -0
- package/skills/ddd-backend-implementation/SKILL.md +95 -0
- package/skills/design-system-component-lifecycle/README.md +56 -0
- package/skills/design-system-component-lifecycle/SKILL.md +97 -0
- package/skills/design-system-component-lifecycle/templates/component-contract.md +43 -0
- package/skills/detection-sweep/README.md +58 -0
- package/skills/detection-sweep/SKILL.md +93 -0
- package/skills/detection-sweep/scripts/sweep.ts +80 -0
- package/skills/domain-modeling-design/README.md +57 -0
- package/skills/domain-modeling-design/SKILL.md +83 -0
- package/skills/frontend-fullstack-implementation/README.md +60 -0
- package/skills/frontend-fullstack-implementation/SKILL.md +133 -0
- package/skills/frontend-spec-call-site-audit/README.md +66 -0
- package/skills/frontend-spec-call-site-audit/SKILL.md +82 -0
- package/skills/frontend-spec-call-site-audit/scripts/audit-entry-points.ts +79 -0
- package/skills/frontend-spec-call-site-audit/templates/ticket-frontend.md +32 -0
- package/skills/merge-request-review/README.md +60 -0
- package/skills/merge-request-review/SKILL.md +77 -0
- package/skills/merge-request-review/templates/mr-review-report.md +29 -0
- package/skills/production-incident-diagnostic/README.md +63 -0
- package/skills/production-incident-diagnostic/SKILL.md +103 -0
- package/skills/production-incident-diagnostic/templates/incident-report.md +33 -0
- package/skills/qa-session-intake/README.md +56 -0
- package/skills/qa-session-intake/SKILL.md +78 -0
- package/skills/recording-decisions/README.md +91 -0
- package/skills/recording-decisions/SKILL.md +84 -0
- package/skills/recurring-bug-root-cause/README.md +64 -0
- package/skills/recurring-bug-root-cause/SKILL.md +93 -0
- package/skills/recurring-bug-root-cause/scripts/detect-recurring-fixes.ts +46 -0
- package/skills/recurring-bug-root-cause/templates/postmortem-recidive.md +37 -0
- package/skills/refactoring-shared-component-api/README.md +50 -0
- package/skills/refactoring-shared-component-api/SKILL.md +84 -0
- package/skills/refactoring-shared-component-api/scripts/sweep-call-sites.ts +85 -0
- package/skills/refactoring-shared-component-api/templates/migration-checklist.md +19 -0
- package/skills/validating-features-end-to-end/README.md +50 -0
- package/skills/validating-features-end-to-end/SKILL.md +90 -0
- package/skills/visual-regression-check/README.md +51 -0
- package/skills/visual-regression-check/SKILL.md +89 -0
- package/skills/writing-robust-tests/README.md +53 -0
- package/skills/writing-robust-tests/SKILL.md +88 -0
- package/templates/.adopted.example +8 -0
- package/templates/anti-drift.gitlab-ci.yml +23 -0
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Rule - `detection-gap-protocol`
|
|
2
|
+
|
|
3
|
+
> If a user finds a P0 before your automation does, the bug is only half the problem - the missing detection is the other half.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Rule (path-scoped) |
|
|
8
|
+
| **Scope (`paths`)** | `docs/postmortems/**` |
|
|
9
|
+
| **Version** | 1.0.0 |
|
|
10
|
+
| **Artifact** | [`rules/detection-gap-protocol.md`](../../rules/detection-gap-protocol.md) |
|
|
11
|
+
| **Paired skills** | [`production-incident-diagnostic`](../../skills/production-incident-diagnostic/), [`detection-sweep`](../../skills/detection-sweep/), [`recurring-bug-root-cause`](../../skills/recurring-bug-root-cause/) |
|
|
12
|
+
|
|
13
|
+
## What it enforces
|
|
14
|
+
|
|
15
|
+
When a **P0 regression is reported by a user** - not by CI, E2E, smoke tests, or monitoring - the postmortem must treat the missing detection as a first-class failure. The rule mandates:
|
|
16
|
+
|
|
17
|
+
1. A postmortem using the dedicated **"detection gap" template**, not the standard one.
|
|
18
|
+
2. A **"Detection gap" section** analyzing every level that should have caught it.
|
|
19
|
+
3. A **regression test that would actually have caught the bug**, written at the right level (SPA navigation, mobile, deployed environment).
|
|
20
|
+
4. A **`detection-gap` label** on the originating ticket.
|
|
21
|
+
5. A **blocking lint** that rejects a user-reported postmortem lacking the "Detection gap" section.
|
|
22
|
+
|
|
23
|
+
## Why it matters
|
|
24
|
+
|
|
25
|
+
A fix removes one bug. Understanding **why every automated layer let it through** removes the whole class of bugs. If the response to a user-reported incident is only "we fixed it", the next regression of the same shape reaches users too - the safety net still has the same hole.
|
|
26
|
+
|
|
27
|
+
Making the user the discoverer of a P0 is itself the defect: it means CI, tests, smoke, and monitoring all passed on broken behavior. The protocol forces the team to name which layer failed and to close that layer, so the automation - not the customer - catches the next one. Aggregating the `detection-gap` label over time reveals **families of holes** and tells you where coverage investment pays off most.
|
|
28
|
+
|
|
29
|
+
## How to apply it
|
|
30
|
+
|
|
31
|
+
### Analyze every coverage level
|
|
32
|
+
|
|
33
|
+
| Level | Question to answer in the postmortem |
|
|
34
|
+
|-------|--------------------------------------|
|
|
35
|
+
| CI compile/lint | Did the code pass typecheck / lint / clippy? |
|
|
36
|
+
| Unit tests | Did a UT cover the broken invariant? |
|
|
37
|
+
| E2E tests | Did a scenario reproduce the user flow? |
|
|
38
|
+
| Post-deploy smoke | Did the smoke test hit this route? |
|
|
39
|
+
| Synthetic monitoring | Did a probe watch this endpoint in prod? |
|
|
40
|
+
|
|
41
|
+
For each level, state whether it *could* have caught the bug and why it did not.
|
|
42
|
+
|
|
43
|
+
### Write the test at the level that failed
|
|
44
|
+
|
|
45
|
+
If the bug only manifests after SPA client-side navigation, a unit test that passes in isolation does not close the gap - the regression test must reproduce the real flow that broke.
|
|
46
|
+
|
|
47
|
+
### Feed the recurring review
|
|
48
|
+
|
|
49
|
+
Label the ticket `detection-gap` so periodic reviews can cluster incidents and prioritize E2E / smoke / monitoring work against the biggest gap families.
|
|
50
|
+
|
|
51
|
+
## Related
|
|
52
|
+
|
|
53
|
+
- [`production-incident-diagnostic`](../../skills/production-incident-diagnostic/) drives the incident analysis that feeds the postmortem.
|
|
54
|
+
- [`detection-sweep`](../../skills/detection-sweep/) proactively hunts for the gaps before a user does.
|
|
55
|
+
- [`recurring-bug-root-cause`](../../skills/recurring-bug-root-cause/) handles the case where the same class of bug keeps returning.
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# Rule - `error-handling-discipline`
|
|
2
|
+
|
|
3
|
+
> No error is ever swallowed and no fallible call ever crashes production. Every failure is either propagated or handled - explicitly, with context.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Rule (path-scoped) |
|
|
8
|
+
| **Scope (`paths`)** | `**/*.ts`, `**/*.tsx`, `**/*.js`, `**/*.vue`, `**/*.py`, `**/*.go`, `**/*.rs`, `**/*.php`, `**/*.java` |
|
|
9
|
+
| **Version** | 1.0.0 |
|
|
10
|
+
| **Artifact** | [`rules/error-handling-discipline.md`](../../rules/error-handling-discipline.md) |
|
|
11
|
+
| **Paired rule** | [`secure-logging`](secure-logging.md) |
|
|
12
|
+
|
|
13
|
+
## What it enforces
|
|
14
|
+
|
|
15
|
+
Disciplined failure handling across every backend and frontend language in scope:
|
|
16
|
+
|
|
17
|
+
- **No swallowed error**: no empty `catch {}`, no log-and-continue as if nothing happened, no `except: pass`, no ignored `_ = err`.
|
|
18
|
+
- **No crash on a fallible op in prod**: no `unwrap()` / `expect()` / `panic!`, no unguaranteed `!!` / `!`, no forced cast on a value that can fail - return or propagate a typed error. (Tolerated in tests.)
|
|
19
|
+
- **Propagate or handle - pick one**: surface it (`Result` / `throw` / `raise`) or deal with it (fallback, bounded retry, user message). Never in between.
|
|
20
|
+
- **Enrich context before propagating**: which operation, which non-sensitive identifier - not a bare message.
|
|
21
|
+
- **Distinguish expected vs unexpected**: business errors handled locally; unexpected ones bubble to a boundary that decides and alerts.
|
|
22
|
+
|
|
23
|
+
## Why it matters
|
|
24
|
+
|
|
25
|
+
A swallowed error is the most expensive kind of bug: the system keeps running on corrupt state, and the failure surfaces far from its cause - often as a mysterious downstream symptom that costs hours to trace. A `.unwrap()` on a value that can be absent turns a recoverable condition into a full crash.
|
|
26
|
+
|
|
27
|
+
The middle ground - logging an error and continuing anyway - is the worst of both: you neither recover cleanly nor stop the damage. Forcing an **explicit** choice between propagating and handling makes the failure path a designed part of the code, not an afterthought. Enriching context at each boundary means the log line that finally reaches you says *which operation on which entity failed*, turning a debugging session into a glance.
|
|
28
|
+
|
|
29
|
+
## How to apply it
|
|
30
|
+
|
|
31
|
+
### Swallowing vs propagating
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
// Bad - swallowed, state now inconsistent
|
|
35
|
+
try { await save(order); } catch (e) { console.log(e); }
|
|
36
|
+
|
|
37
|
+
// Good - enrich and propagate
|
|
38
|
+
try {
|
|
39
|
+
await save(order);
|
|
40
|
+
} catch (cause) {
|
|
41
|
+
throw new Error(`persisting order ${order.id} failed`, { cause });
|
|
42
|
+
}
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### Fallible operations in Rust
|
|
46
|
+
|
|
47
|
+
```rust
|
|
48
|
+
// Bad - crashes prod if the row is missing
|
|
49
|
+
let user = repo.find(id).unwrap();
|
|
50
|
+
|
|
51
|
+
// Good - propagate a typed error
|
|
52
|
+
let user = repo.find(id)?;
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### Expected vs unexpected
|
|
56
|
+
|
|
57
|
+
Handle an expected business error (e.g. "email already taken") right where the use case can react. Let an unexpected error (DB down, invariant violated) bubble to a boundary - an HTTP error handler, a job supervisor - that maps it to a response and alerts.
|
|
58
|
+
|
|
59
|
+
## Related
|
|
60
|
+
|
|
61
|
+
- [`secure-logging`](secure-logging.md) - enrich context with **non-sensitive** identifiers only; never log the payload.
|
|
62
|
+
- Companion rule: [`clean-architecture-deps`](clean-architecture-deps.md) - errors cross layer boundaries as typed values.
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# Rule - `minimal-code`
|
|
2
|
+
|
|
3
|
+
> The best code is the code you don't write - but "less code" means less surface to maintain, never fewer characters at the cost of clarity.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Rule (path-scoped) |
|
|
8
|
+
| **Scope (`paths`)** | `**/*.rs`, `**/*.ts`, `**/*.tsx`, `**/*.vue`, `**/*.py`, `**/*.go` |
|
|
9
|
+
| **Version** | 1.0.0 |
|
|
10
|
+
| **Artifact** | [`rules/minimal-code.md`](../../rules/minimal-code.md) |
|
|
11
|
+
|
|
12
|
+
## What it enforces
|
|
13
|
+
|
|
14
|
+
Before adding code, walk down a hierarchy and stop at the first level that meets the need:
|
|
15
|
+
|
|
16
|
+
1. **Is the need real?** No speculation (YAGNI) - code only what is asked or proven necessary.
|
|
17
|
+
2. **Does the stdlib / language already do it?**
|
|
18
|
+
3. **Does an already-installed dependency do it?** Check the manifest before adding a lib or reimplementing.
|
|
19
|
+
4. **Does an existing component / module / function in the project do it?** Reuse before duplicating.
|
|
20
|
+
5. **Otherwise, write the simplest solution** that covers exactly the case at hand.
|
|
21
|
+
|
|
22
|
+
And a hard guardrail: **readability beats brevity**. Minimizing code is not minimizing lines. Cryptic one-liners, nested operator chains, and stripped-out intermediate names are failures, not wins.
|
|
23
|
+
|
|
24
|
+
## Why it matters
|
|
25
|
+
|
|
26
|
+
Every line is a liability: it must be read, tested, reviewed, and maintained forever. Code you avoid writing - because the stdlib, a dependency, or an existing helper already covers it - has zero maintenance cost and zero bug surface. Speculative generality (the "we might need it later" abstraction) is pure cost against a benefit that usually never arrives.
|
|
27
|
+
|
|
28
|
+
But the goal is often misread as "shortest code wins", which produces dense, unreadable expressions that are *harder* to maintain than the verbose version - the opposite of the intent. The rule draws the line explicitly: delete **superfluous** code (premature abstractions, empty wrappers, unused options), never **compress useful** code. A well-named intermediate variable and an early return are worth more than a saved line.
|
|
29
|
+
|
|
30
|
+
## How to apply it
|
|
31
|
+
|
|
32
|
+
### Reuse before reimplementing
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
// Before writing a dedupe loop - the language already does it
|
|
36
|
+
const unique = [...new Set(items)];
|
|
37
|
+
|
|
38
|
+
// Before adding a date lib - check package.json for one already present
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### Delete surface, don't compress it
|
|
42
|
+
|
|
43
|
+
```ts
|
|
44
|
+
// Bad - "one line" at the cost of readability
|
|
45
|
+
const r = xs.filter(x=>x.a&&x.b).map(x=>x.a*x.b).reduce((s,v)=>s+v,0)||0;
|
|
46
|
+
|
|
47
|
+
// Good - same behavior, named steps, early clarity
|
|
48
|
+
const eligible = xs.filter((x) => x.a && x.b);
|
|
49
|
+
const products = eligible.map((x) => x.a * x.b);
|
|
50
|
+
const total = products.reduce((sum, v) => sum + v, 0);
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
> Arbitration rule: if the shortest code is less clear than slightly longer code, choose the clearer one. The target is *less surface to maintain*, not *fewer characters*.
|
|
54
|
+
|
|
55
|
+
## Related
|
|
56
|
+
|
|
57
|
+
- Companion rule: [`clean-architecture-deps`](clean-architecture-deps.md) - reuse across layers instead of duplicating logic.
|
|
58
|
+
- Companion rule: [`error-handling-discipline`](error-handling-discipline.md) - the simplest solution still handles failure explicitly.
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# Rule - `no-raw-sql-interpolation`
|
|
2
|
+
|
|
3
|
+
> A query is code; a value is data. Never stitch the two together by hand - parameterize, always.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Rule (path-scoped) |
|
|
8
|
+
| **Scope (`paths`)** | `**/*.ts`, `**/*.js`, `**/*.py`, `**/*.go`, `**/*.rs`, `**/*.php`, `**/*.java` |
|
|
9
|
+
| **Version** | 1.0.0 |
|
|
10
|
+
| **Artifact** | [`rules/no-raw-sql-interpolation.md`](../../rules/no-raw-sql-interpolation.md) |
|
|
11
|
+
| **Paired skill** | [`audit-security`](../../skills/audit-security/) |
|
|
12
|
+
|
|
13
|
+
## What it enforces
|
|
14
|
+
|
|
15
|
+
- **Never build a query by interpolation/concatenation** of an input: no `format!`, template string, f-string, or `+` injecting a value into SQL.
|
|
16
|
+
- **Parameterized queries only**: bound placeholders (`$1`, `?`, `:name`) with values passed separately, or a query builder / ORM that parameterizes for you.
|
|
17
|
+
- **Dynamic identifiers** (table/column names, which cannot be parameterized): validate against an **explicit allowlist**, never interpolate raw input.
|
|
18
|
+
- Same principle for neighboring interpreters: NoSQL, LDAP, shell commands - separate code from data.
|
|
19
|
+
|
|
20
|
+
## Why it matters
|
|
21
|
+
|
|
22
|
+
String-interpolated SQL is the root cause of injection, still one of the most damaging and common vulnerabilities. When a value is concatenated into query text, a crafted input like `'; DROP TABLE users; --` is parsed as *code* rather than *data*. Parameterized queries close this entirely: the driver sends the query structure and the values over separate channels, so a value can never change the query's meaning - no amount of escaping cleverness is needed, and none can be forgotten.
|
|
23
|
+
|
|
24
|
+
Dynamic identifiers are the trap: placeholders bind values, not table or column names, so developers reach for interpolation there. An allowlist keeps that path safe - only known-good identifiers are ever spliced in, and arbitrary input is rejected outright.
|
|
25
|
+
|
|
26
|
+
## How to apply it
|
|
27
|
+
|
|
28
|
+
### Parameterize values
|
|
29
|
+
|
|
30
|
+
```ts
|
|
31
|
+
// Bad - injectable
|
|
32
|
+
db.query(`SELECT * FROM users WHERE email = '${email}'`);
|
|
33
|
+
|
|
34
|
+
// Good - bound placeholder, value sent separately
|
|
35
|
+
db.query('SELECT * FROM users WHERE email = $1', [email]);
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
```python
|
|
39
|
+
# Bad
|
|
40
|
+
cur.execute(f"SELECT * FROM users WHERE id = {user_id}")
|
|
41
|
+
# Good
|
|
42
|
+
cur.execute("SELECT * FROM users WHERE id = %s", (user_id,))
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### Allowlist dynamic identifiers
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
const SORTABLE = new Set(['created_at', 'name', 'total']);
|
|
49
|
+
if (!SORTABLE.has(sortColumn)) throw new Error('invalid sort column');
|
|
50
|
+
db.query(`SELECT * FROM orders ORDER BY ${sortColumn}`); // safe: value came from the allowlist
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Related
|
|
54
|
+
|
|
55
|
+
- [`audit-security`](../../skills/audit-security/) reviews injection surfaces as part of a security audit.
|
|
56
|
+
- Companion rule: [`sql-migrations-discipline`](sql-migrations-discipline.md) (the other half of safe database work).
|
|
57
|
+
- Companion rule: [`secure-logging`](secure-logging.md) (don't log the injected value either).
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Rule - `pre-commit-secret-detection`
|
|
2
|
+
|
|
3
|
+
> No secret ever reaches a commit. Scan the staged diff every time; treat any pushed secret as compromised.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Rule (always-on) |
|
|
8
|
+
| **Scope (`paths`)** | always active |
|
|
9
|
+
| **Version** | 1.0.0 |
|
|
10
|
+
| **Artifact** | [`rules/pre-commit-secret-detection.md`](../../rules/pre-commit-secret-detection.md) |
|
|
11
|
+
| **Paired skill** | [`commit-readiness-review`](../../skills/commit-readiness-review/) |
|
|
12
|
+
|
|
13
|
+
## What it enforces
|
|
14
|
+
|
|
15
|
+
A hard gate: **no credential of any kind is ever committed** - API keys, tokens, passwords, private keys, connection strings. The rule is always active because a leak can happen in any file type, at any commit.
|
|
16
|
+
|
|
17
|
+
## Why it matters
|
|
18
|
+
|
|
19
|
+
A secret is not "removed" by a later commit. Once it exists in git history - and especially once it is pushed - it must be considered **compromised**: anyone with repo access (now or via a future clone/fork/backup) can recover it. That is why the response to a pushed secret is **rotation on the provider side + history purge**, never a plain `git revert` (which leaves the value in history).
|
|
20
|
+
|
|
21
|
+
The rule is layered so it fails safe:
|
|
22
|
+
|
|
23
|
+
- **Local, tool present** - `gitleaks protect --staged` blocks the commit before the secret lands.
|
|
24
|
+
- **Local, no tool** - a grep fallback on common patterns warns; it does not block, so it never wedges a commit, but it flags the obvious cases.
|
|
25
|
+
- **CI** - `gitleaks detect` over the full repo and history is the backstop that catches anything local checks missed. This CI must never be disabled.
|
|
26
|
+
|
|
27
|
+
## How to apply it
|
|
28
|
+
|
|
29
|
+
### Scanning
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
# Preferred: dedicated scanner on the staged diff
|
|
33
|
+
gitleaks protect --staged
|
|
34
|
+
|
|
35
|
+
# Fallback when gitleaks is unavailable
|
|
36
|
+
git diff --cached | grep -nE 'AKIA|BEGIN .* PRIVATE KEY|sk_live_|glpat-|ghp_|(password|secret|token)\s*[:=]'
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
### Handling a false positive
|
|
40
|
+
|
|
41
|
+
- **One-off**: add a `gitleaks:allow` comment on the offending line.
|
|
42
|
+
- **Systemic**: add an allowlist entry to `.gitleaks.toml` (by path or by value regex).
|
|
43
|
+
- **Never** silence a finding by disabling the scan.
|
|
44
|
+
|
|
45
|
+
### Handling a real secret
|
|
46
|
+
|
|
47
|
+
1. Do **not** commit. Move the value to an environment variable or a secret manager (in a gitignored file).
|
|
48
|
+
2. If already committed locally but **not pushed**: `git reset --soft HEAD~1`, then remove the value.
|
|
49
|
+
3. If already **pushed**: rotate the credential immediately on the provider side, then purge history with `git filter-repo`.
|
|
50
|
+
|
|
51
|
+
## Related
|
|
52
|
+
|
|
53
|
+
- [`commit-readiness-review`](../../skills/commit-readiness-review/) orchestrates this check as its secret-scan step before a commit.
|
|
54
|
+
- Companion rule: `secure-logging` (never log sensitive data).
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# Rule - `secure-logging`
|
|
2
|
+
|
|
3
|
+
> Logs are forever and widely read. Personal data and secrets never belong in them - log an identifier, not the thing itself.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Rule (path-scoped) |
|
|
8
|
+
| **Scope (`paths`)** | `**/*.rs`, `**/*.ts` |
|
|
9
|
+
| **Version** | 1.0.0 |
|
|
10
|
+
| **Artifact** | [`rules/secure-logging.md`](../../rules/secure-logging.md) |
|
|
11
|
+
| **Paired skills** | [`audit-security`](../../skills/audit-security/), [`audit-compliance`](../../skills/audit-compliance/) |
|
|
12
|
+
|
|
13
|
+
## What it enforces
|
|
14
|
+
|
|
15
|
+
- **Absolute rule**: never log an email, IP, token, hash, or secret in logs or traces (`warn!`, `error!`, `info!`, `console.log`, application logger…).
|
|
16
|
+
- Use **non-personal identifiers** (`user_id`, `org_id`, `*_id`) in place of the data itself.
|
|
17
|
+
- Every new database field must be **classified** (Public / Internal / Confidential).
|
|
18
|
+
|
|
19
|
+
## Why it matters
|
|
20
|
+
|
|
21
|
+
Logs flow to places production data never should: aggregation platforms, third-party observability vendors, developer laptops, long-lived archives, and support tooling. Anything written to a log is effectively distributed and retained beyond the app's own access controls. Logging an email or IP therefore turns an ordinary log line into a GDPR-relevant personal-data processing - and logging a token or secret hands an attacker with log access a live credential.
|
|
22
|
+
|
|
23
|
+
Referencing a stable `user_id` instead of the email gives you the same debuggability (you can still correlate, trace, and support) with none of the exposure. Classifying every new field at design time makes the "can this be logged?" question answerable by construction rather than discovered during an incident.
|
|
24
|
+
|
|
25
|
+
## How to apply it
|
|
26
|
+
|
|
27
|
+
### Log the identifier, not the data
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
// Bad - leaks PII / a live secret into the log sink
|
|
31
|
+
logger.info(`login for ${email} with token ${accessToken}`);
|
|
32
|
+
|
|
33
|
+
// Good - correlate by non-personal id
|
|
34
|
+
logger.info('login', { user_id: user.id });
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
```rust
|
|
38
|
+
// Bad
|
|
39
|
+
tracing::warn!("rate limit hit for {}", client_ip);
|
|
40
|
+
// Good
|
|
41
|
+
tracing::warn!(org_id = %org.id, "rate limit hit");
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### Classify new fields
|
|
45
|
+
|
|
46
|
+
When adding a column, tag it Public / Internal / Confidential in the schema or data catalog, and let that classification decide whether it may ever appear in a log or trace.
|
|
47
|
+
|
|
48
|
+
> The rule intentionally leaves project-specific identifiers, the CI lint, and the full classification policy to a project-level rule and `docs/security`.
|
|
49
|
+
|
|
50
|
+
## Related
|
|
51
|
+
|
|
52
|
+
- [`audit-security`](../../skills/audit-security/) and [`audit-compliance`](../../skills/audit-compliance/) review logging exposure and data governance.
|
|
53
|
+
- Companion rule: [`error-handling-discipline`](error-handling-discipline.md) - enrich error context with ids, never with the sensitive payload.
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# Rule - `sql-migrations-discipline`
|
|
2
|
+
|
|
3
|
+
> Migrations are append-only history. Never rewrite an applied one, and never block production with a single destructive step.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Rule (path-scoped) |
|
|
8
|
+
| **Scope (`paths`)** | `**/migrations/**/*.sql`, `**/migrate/**/*.sql`, `**/db/migrate/**/*` |
|
|
9
|
+
| **Version** | 1.0.0 |
|
|
10
|
+
| **Artifact** | [`rules/sql-migrations-discipline.md`](../../rules/sql-migrations-discipline.md) |
|
|
11
|
+
| **Paired skill** | [`database-schema-evolution`](../../skills/database-schema-evolution/) |
|
|
12
|
+
|
|
13
|
+
## What it enforces
|
|
14
|
+
|
|
15
|
+
- **Never modify an already-applied migration**: most tools (SQLx, Flyway, Liquibase, Alembic, Knex…) store a checksum; editing breaks validation. Fix forward with a **new** migration.
|
|
16
|
+
- **Idempotence**: `IF NOT EXISTS` / `IF EXISTS` on DDL, conditional logic in a block (`DO $$ … $$` in PostgreSQL).
|
|
17
|
+
- **Table with production data → two-step (expand-contract)**: add *nullable* → backfill → add the constraint. Never a single blocking step.
|
|
18
|
+
- **Risky operations** (drop, rename, type change, `NOT NULL` on a populated table): route through expand-contract and a backward-compatible change.
|
|
19
|
+
- **Validate from a clean state**: replay all migrations on a fresh database before pushing, not just the last one.
|
|
20
|
+
- Regenerate compiled query artifacts (prepared queries, generated types) after any change touching queries.
|
|
21
|
+
|
|
22
|
+
## Why it matters
|
|
23
|
+
|
|
24
|
+
Migration tools trust their checksums to know what has run. Editing an applied migration desynchronizes every environment that already ran the old version - teammates and production diverge silently, and the tool refuses to proceed or, worse, skips the change. Forward-only migrations keep every environment on the same deterministic path.
|
|
25
|
+
|
|
26
|
+
The two-step / expand-contract discipline exists because a single destructive change on a live table can lock it, break the currently-deployed code, or fail halfway with no clean rollback. Adding a column as nullable, backfilling, then tightening the constraint keeps the old and new code both working during the deploy window - the essence of a zero-downtime schema change. Replaying from a clean database catches migrations that only "work" because of accumulated local state.
|
|
27
|
+
|
|
28
|
+
## How to apply it
|
|
29
|
+
|
|
30
|
+
### Idempotent DDL
|
|
31
|
+
|
|
32
|
+
```sql
|
|
33
|
+
CREATE TABLE IF NOT EXISTS invoices (id uuid PRIMARY KEY);
|
|
34
|
+
ALTER TABLE invoices ADD COLUMN IF NOT EXISTS status text;
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
### Expand-contract for a NOT NULL column on a populated table
|
|
38
|
+
|
|
39
|
+
```sql
|
|
40
|
+
-- Migration N: expand (nullable, non-blocking)
|
|
41
|
+
ALTER TABLE users ADD COLUMN country text;
|
|
42
|
+
|
|
43
|
+
-- App deploy backfills / starts writing country
|
|
44
|
+
|
|
45
|
+
-- Migration N+2: contract (now safe to constrain)
|
|
46
|
+
ALTER TABLE users ALTER COLUMN country SET NOT NULL;
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
### Validate from scratch before pushing
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
# Drop + recreate a throwaway DB, then replay every migration in order
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## Related
|
|
56
|
+
|
|
57
|
+
- [`database-schema-evolution`](../../skills/database-schema-evolution/) plans and reviews schema changes end to end.
|
|
58
|
+
- Companion rule: [`no-raw-sql-interpolation`](no-raw-sql-interpolation.md) (safe queries against the evolved schema).
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Rule - `subscription-cleanup`
|
|
2
|
+
|
|
3
|
+
> Anything that subscribes or registers must have a matching teardown - or it leaks memory, fires ghost handlers, and runs twice.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Rule (path-scoped) |
|
|
8
|
+
| **Scope (`paths`)** | `**/*.ts`, `**/*.tsx`, `**/*.js`, `**/*.jsx`, `**/*.vue` |
|
|
9
|
+
| **Version** | 1.0.0 |
|
|
10
|
+
| **Artifact** | [`rules/subscription-cleanup.md`](../../rules/subscription-cleanup.md) |
|
|
11
|
+
| **Paired skill** | [`refactoring-shared-component-api`](../../skills/refactoring-shared-component-api/) |
|
|
12
|
+
|
|
13
|
+
## What it enforces
|
|
14
|
+
|
|
15
|
+
Every resource that subscribes or registers is explicitly torn down:
|
|
16
|
+
|
|
17
|
+
- **Observables / streams**: `unsubscribe()`, a completion operator (`takeUntil(destroy$)`, `takeUntilDestroyed()`, `take(1)`), or the `async` pipe / lifecycle-managed binding. Never a bare `.subscribe(`.
|
|
18
|
+
- **Listeners**: every `addEventListener` / `on(...)` has a matching `removeEventListener` / `off(...)` on teardown.
|
|
19
|
+
- **Timers**: every recurring `setInterval` / `setTimeout` is cancelled.
|
|
20
|
+
- **Watchers / reactive effects**: keep the handle and stop it, or use a self-managing lifecycle API (`watchEffect`, effect scope).
|
|
21
|
+
- **Cancellable requests**: `AbortController` aborted on teardown or dependency change.
|
|
22
|
+
- Cleanup lives in the end-of-life hook (`onUnmounted`, `ngOnDestroy`, `useEffect` cleanup, `Drop`…), never "later".
|
|
23
|
+
|
|
24
|
+
## Why it matters
|
|
25
|
+
|
|
26
|
+
A subscription without teardown is a slow-motion outage. Each time a component mounts, it registers another listener or stream; when it unmounts without cleanup, that registration survives - holding references (a memory leak) and still reacting to events (a ghost handler). Navigate back and forth a few times and the same callback fires three, five, ten times, causing duplicated network calls, doubled state updates, and bugs that only appear after a while and are miserable to reproduce.
|
|
27
|
+
|
|
28
|
+
Binding cleanup to the component's own lifecycle hook makes teardown deterministic: it happens exactly when the thing that created the subscription goes away, not on a hopeful "later" that never comes. This is the single most common source of leaks in long-lived SPA sessions.
|
|
29
|
+
|
|
30
|
+
## How to apply it
|
|
31
|
+
|
|
32
|
+
### Never a bare subscribe
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
// Bad - leaks on every re-render / re-navigation
|
|
36
|
+
source$.subscribe((v) => this.value = v);
|
|
37
|
+
|
|
38
|
+
// Good - completes with the component
|
|
39
|
+
source$.pipe(takeUntilDestroyed()).subscribe((v) => this.value = v);
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### Match every registration
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
// React
|
|
46
|
+
useEffect(() => {
|
|
47
|
+
const onResize = () => measure();
|
|
48
|
+
window.addEventListener('resize', onResize);
|
|
49
|
+
const id = setInterval(poll, 5000);
|
|
50
|
+
const ctrl = new AbortController();
|
|
51
|
+
fetch(url, { signal: ctrl.signal });
|
|
52
|
+
return () => {
|
|
53
|
+
window.removeEventListener('resize', onResize);
|
|
54
|
+
clearInterval(id);
|
|
55
|
+
ctrl.abort();
|
|
56
|
+
};
|
|
57
|
+
}, []);
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Related
|
|
61
|
+
|
|
62
|
+
- [`refactoring-shared-component-api`](../../skills/refactoring-shared-component-api/) - when reworking a shared component, audit its teardown paths.
|
|
63
|
+
- Companion rule: [`ui-states-complete`](ui-states-complete.md) (the other half of robust async UI).
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# Rule - `test-discipline`
|
|
2
|
+
|
|
3
|
+
> Tests wait for state, not for the clock; select by intent, not by fragile markup; and every feature and bug ships with the tests that prove it.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Rule (path-scoped) |
|
|
8
|
+
| **Scope (`paths`)** | `**/*.spec.ts`, `**/*.test.ts` |
|
|
9
|
+
| **Version** | 1.0.0 |
|
|
10
|
+
| **Artifact** | [`rules/test-discipline.md`](../../rules/test-discipline.md) |
|
|
11
|
+
| **Paired skills** | [`writing-robust-tests`](../../skills/writing-robust-tests/), [`comprehensive-test-strategy`](../../skills/comprehensive-test-strategy/) |
|
|
12
|
+
|
|
13
|
+
## What it enforces
|
|
14
|
+
|
|
15
|
+
- **Zero `waitForTimeout`** - wait for a state/locator, never an arbitrary delay.
|
|
16
|
+
- **`data-testid` selectors only** - no bare `text=` nor fragile CSS selector.
|
|
17
|
+
- **Scoped locators** (`parent.getByTestId('child')`) - no ambiguous global locator.
|
|
18
|
+
- **Page objects** for E2E - no selectors scattered across specs.
|
|
19
|
+
- **FIRST** principles: Fast, Isolated, Repeatable, Self-validating, Timely.
|
|
20
|
+
- Every feature/fix → **UT + E2E + API** tests (deterministic golden dataset).
|
|
21
|
+
- Every bug → one UT + one E2E confirmation test written **with** the fix.
|
|
22
|
+
|
|
23
|
+
## Why it matters
|
|
24
|
+
|
|
25
|
+
Arbitrary sleeps are the number-one source of flaky E2E suites: too short and the test races the app, too long and the suite crawls - and either way the timeout says nothing about the actual condition you care about. Waiting for a state or locator makes the test both faster and deterministic.
|
|
26
|
+
|
|
27
|
+
Selecting by visible text or CSS couples the test to wording and styling that change for reasons unrelated to behavior, so refactors break green tests and teams learn to distrust the suite. A stable `data-testid` expresses *what* element matters, decoupled from *how* it looks. Scoping the locator and centralizing selectors in page objects keeps that intent unambiguous and maintainable as the UI grows.
|
|
28
|
+
|
|
29
|
+
Shipping the confirming tests **with** each feature and each fix is what makes coverage real: a bug that arrives with a failing-then-passing test can never silently regress again.
|
|
30
|
+
|
|
31
|
+
## How to apply it
|
|
32
|
+
|
|
33
|
+
### Wait for state, not time
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
// Bad - flaky and slow
|
|
37
|
+
await page.waitForTimeout(2000);
|
|
38
|
+
expect(await page.locator('.result').count()).toBe(1);
|
|
39
|
+
|
|
40
|
+
// Good - deterministic
|
|
41
|
+
await expect(page.getByTestId('result')).toBeVisible();
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### Scoped, intent-based selectors via a page object
|
|
45
|
+
|
|
46
|
+
```ts
|
|
47
|
+
class OrdersPage {
|
|
48
|
+
constructor(private page: Page) {}
|
|
49
|
+
row(id: string) {
|
|
50
|
+
return this.page.getByTestId(`order-row-${id}`);
|
|
51
|
+
}
|
|
52
|
+
status(id: string) {
|
|
53
|
+
return this.row(id).getByTestId('status'); // scoped, not global
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### Bug → regression test with the fix
|
|
59
|
+
|
|
60
|
+
Write a unit test reproducing the bug and an E2E test reproducing the user flow, commit them alongside the fix so the pair proves the fix and guards against recurrence.
|
|
61
|
+
|
|
62
|
+
## Related
|
|
63
|
+
|
|
64
|
+
- [`writing-robust-tests`](../../skills/writing-robust-tests/) turns uncovered code into resilient tests.
|
|
65
|
+
- [`comprehensive-test-strategy`](../../skills/comprehensive-test-strategy/) plans the UT/E2E/API layering for a feature.
|
|
66
|
+
- Companion rule: [`detection-gap-protocol`](detection-gap-protocol.md) (the test that *would have* caught a user-found bug).
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# Rule - `ui-states-complete`
|
|
2
|
+
|
|
3
|
+
> Every async view answers four questions - loading, error, empty, success - and never leaves the user staring at an ambiguous blank or an eternal spinner.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Rule (path-scoped) |
|
|
8
|
+
| **Scope (`paths`)** | `**/*.tsx`, `**/*.jsx`, `**/*.vue`, `**/*.svelte` |
|
|
9
|
+
| **Version** | 1.0.0 |
|
|
10
|
+
| **Artifact** | [`rules/ui-states-complete.md`](../../rules/ui-states-complete.md) |
|
|
11
|
+
| **Paired skills** | [`frontend-fullstack-implementation`](../../skills/frontend-fullstack-implementation/), [`design-system-component-lifecycle`](../../skills/design-system-component-lifecycle/) |
|
|
12
|
+
|
|
13
|
+
## What it enforces
|
|
14
|
+
|
|
15
|
+
Any view fed by an async operation handles all four states, each distinguishable (ideally a distinct `data-testid`):
|
|
16
|
+
|
|
17
|
+
- **loading**: visual feedback while waiting - never a frozen screen.
|
|
18
|
+
- **error**: actionable message + retry when possible - never a silent failure or an infinite spinner.
|
|
19
|
+
- **empty**: explicit "0 results" state, distinct from loading - not an ambiguous blank page.
|
|
20
|
+
- **success**: the nominal content.
|
|
21
|
+
|
|
22
|
+
Plus the invariants: a failed promise must **end** the loading state; states must not overlap (no "loading + error" together); and this applies to *any* async block - page, list, form submission, request-fed widget.
|
|
23
|
+
|
|
24
|
+
## Why it matters
|
|
25
|
+
|
|
26
|
+
The success path is the one developers naturally build; the other three are where real users spend a surprising amount of their time - on slow networks, on empty accounts, and when things fail. A view that only models success degrades badly at exactly those moments: a spinner that never resolves because the promise rejected, a blank page that could mean "loading", "no data", or "broken" with no way to tell, an error that vanishes silently and leaves the user stuck.
|
|
27
|
+
|
|
28
|
+
Treating the four states as a required set turns these from afterthoughts into designed behavior. Making each state distinguishable (a dedicated `data-testid`) also makes them **testable** - the E2E suite can assert that a failed request shows the error state and stops the spinner, closing the most common class of frontend "it just hangs" bugs.
|
|
29
|
+
|
|
30
|
+
## How to apply it
|
|
31
|
+
|
|
32
|
+
### Model the states explicitly
|
|
33
|
+
|
|
34
|
+
```tsx
|
|
35
|
+
function OrderList() {
|
|
36
|
+
const { status, data, error, refetch } = useOrders();
|
|
37
|
+
|
|
38
|
+
if (status === 'loading') return <Spinner data-testid="orders-loading" />;
|
|
39
|
+
if (status === 'error')
|
|
40
|
+
return <ErrorBox data-testid="orders-error" onRetry={refetch}>{error.message}</ErrorBox>;
|
|
41
|
+
if (data.length === 0) return <Empty data-testid="orders-empty" />;
|
|
42
|
+
return <ul data-testid="orders-success">{data.map(/* ... */)}</ul>;
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Key points: the error branch ends the loading state and offers `retry`; `empty` is a separate branch from `loading`; each state carries its own `data-testid` so the four are never confused - by a user or by a test.
|
|
47
|
+
|
|
48
|
+
## Related
|
|
49
|
+
|
|
50
|
+
- [`frontend-fullstack-implementation`](../../skills/frontend-fullstack-implementation/) builds views that satisfy this contract.
|
|
51
|
+
- [`design-system-component-lifecycle`](../../skills/design-system-component-lifecycle/) standardizes the four-state components.
|
|
52
|
+
- Companion rule: [`subscription-cleanup`](subscription-cleanup.md) (the other half of robust async UI).
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: name-in-kebab-case
|
|
3
|
+
description: Use when <concrete third-person triggers - symptoms, situations, user verbatims>. Triggers on "<english trigger>", "<another english trigger>", "<french trigger>", "<another french trigger>". <Describe WHEN, not HOW - never summarize the workflow here.>
|
|
4
|
+
version: 1.0.0
|
|
5
|
+
metadata:
|
|
6
|
+
last-reviewed: YYYY-MM-DD
|
|
7
|
+
category: audit | feature | bug | frontend | test | process
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Readable title - the principle in one line
|
|
11
|
+
|
|
12
|
+
> If the current repo has an equivalent skill (e.g. acme-app -> `<project-skill>`), it wins - it knows the paths, the tracker and the project commands.
|
|
13
|
+
|
|
14
|
+
## When ME and not X
|
|
15
|
+
|
|
16
|
+
- **ME** when: <precise use case>
|
|
17
|
+
- **<neighbour-skill>** instead if: <boundary>
|
|
18
|
+
|
|
19
|
+
## Principle
|
|
20
|
+
|
|
21
|
+
<1-2 sentences: the central insight, the expected output. What separates a good result from a bad one.>
|
|
22
|
+
|
|
23
|
+
## Context to gather (before acting)
|
|
24
|
+
|
|
25
|
+
- Framework + commands: read `package.json` / `Cargo.toml` / `Makefile` / CI config
|
|
26
|
+
- Read an existing neighbour and copy its conventions before inventing
|
|
27
|
+
- <project reference data / fixtures / locations>
|
|
28
|
+
|
|
29
|
+
## Protocol
|
|
30
|
+
|
|
31
|
+
1. <step>
|
|
32
|
+
2. <step>
|
|
33
|
+
3. <step>
|
|
34
|
+
|
|
35
|
+
<For a complex workflow, provide a copyable checklist:>
|
|
36
|
+
```
|
|
37
|
+
- [ ] Step 1
|
|
38
|
+
- [ ] Step 2
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Templates
|
|
42
|
+
|
|
43
|
+
- `templates/<x>.md` - <expected output to fill in>
|
|
44
|
+
|
|
45
|
+
## Pitfalls & rationalizations
|
|
46
|
+
|
|
47
|
+
| Excuse | Reality |
|
|
48
|
+
|--------|---------|
|
|
49
|
+
| "<common excuse>" | <why it is wrong> |
|
|
50
|
+
|
|
51
|
+
## Exit condition
|
|
52
|
+
|
|
53
|
+
Written as observable outcomes, because this section is what the evaluation
|
|
54
|
+
harness gates on (see `eval.yaml` below).
|
|
55
|
+
|
|
56
|
+
- [ ] <measurable proof the skill reached its goal>
|
|
57
|
+
- [ ] <verification run, output pasted - never "it should pass">
|
|
58
|
+
|
|
59
|
+
## Tooling
|
|
60
|
+
|
|
61
|
+
- `scripts/<x>.ts` - <runnable static detection: "Run scripts/x.ts">
|
|
62
|
+
- `reference/<x>.md` - <heavy grid / reference loaded on demand>
|
|
63
|
+
|
|
64
|
+
## Changelog
|
|
65
|
+
|
|
66
|
+
- 1.0.0 (YYYY-MM-DD) - initial versioned release
|