aws-samples / aws-samples/serverless-full-stack-webapp-starter-kit
refactor(cdk): awscdk-lint (strict) を全ルール適用する(既存 stack name は disable コメントで例外化)
- Dominant language
- TypeScript
- Stars
- 229
- Forks
- 45
- Avg merge
- 1m
- Merged PRs (30d)
- 4
Description
## 背景
[awscdk-lint](https://github.com/ren-yamanashi/awscdk-lint)(`oxlint-plugin-awscdk`)を
`apps/cdk` に適用する。strict 構成を全ルール有効で導入し、検出された指摘に対応する。
唯一リソース置換を伴う `no-construct-stack-suffix` は、既存の 2 つの stack name に対してのみ
inline disable コメントで例外化し、破壊的変更を回避する(新規コードには引き続き適用される)。
検証は type-aware モードで実施(`--type-aware` 必須。付けないと型情報必須ルールが
黙ってスキップされ false negative になる)。
## 方針
- `oxlint-plugin-awscdk` の `strict` 構成を全ルール有効で適用する。
- 検出された非破壊的な指摘(型注釈・readonly・未使用 Props 削除・コンストラクタ引数名・JSDoc)を修正する。
- **既存 stack name のみ例外化**: `bin/cdk.ts` の 2 箇所は disable コメントで抑制する。
## 対応する指摘(strict / type-aware、いずれも synth 出力不変)
| ルール | 件数 | 主な箇所 |
| ---------------------------------------------- | ---- | ----------------------------------------------------------------------------------------------- |
| `require-jsdoc` | 28 | 各 construct / props |
| `no-mutable-property-of-props-interface` | 27 | `webapp.ts`, `service.ts`, `bin/cdk.ts`, `us-east-1-stack.ts` ほか |
| `no-construct-in-public-property-of-construct` | 4 | `service.ts`(`urlParameter`), `event-bus/index.ts`(`api`), `auth/index.ts`(`userPool`,`client`) |
| `no-construct-in-interface` | 3 | `webapp.ts`(`accessLogBucket`), `service.ts`(`handler`,`accessLogBucket`) |
| `no-unused-props` | 2 | `service.ts`(`basicAuthUsername`,`basicAuthPassword`) |
| `require-props-default-doc` | 1 | オプショナル Props |
| `construct-constructor-property` | 1 | `database.ts` / `event-bus/index.ts` |
(`pascal-case-construct-id` / `no-parent-name-construct-id-match` /
`no-variable-construct-id` / `prevent-construct-id-collision` / `require-passing-this` は検出 0 件)
## 例外化する指摘(リソース置換を伴うため disable)
| ルール | 件数 | 箇所 | 対応 |
| --------------------------- | ---- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `no-construct-stack-suffix` | 2 | `bin/cdk.ts`(`ServerlessWebappStarterKitStack`, `ServerlessWebappStarterKitUsEast1Stack`) | 直上に `// oxlint-disable-next-line awscdk/no-construct-stack-suffix` + 理由コメント。stack ID 変更 = スタックごと再作成(RETAIN の DSQL/Cognito が孤立)のため既存名を維持 |
## 完了条件
- [ ] `strict` 構成を全ルール有効で導入する
- [ ] 上記「対応する指摘」をすべて解消する
- [ ] `bin/cdk.ts` の 2 箇所を disable コメント + 理由コメントで例外化する
- [ ] `cdk synth` の diff がゼロ(logical ID・テンプレート不変)であることをスナップショットテストで確認
- [ ] `pnpm --filter @repo/cdk run lint:ci`(type-aware 前提)が pass する
## 補足
- 型情報必須ルールは素の `oxlint` ではスキップされる。CI 組込みには
`oxlint-tsgolint` + `--type-aware` が前提。既存の `lint:ci` スクリプトの更新が必要。
- プラグイン peer 依存は `oxlint >= 1.70`。現状リポジトリは `oxlint ^1`(要バージョン確認)。
- disable コメントが type-aware モードの JS プラグイン規則に効くことは検証済み。
Contributor guide
Research direction
Start in apps/cdk and inspect the existing lint:ci script, then review bin/cdk.ts and the listed construct files such as webapp.ts, service.ts, database.ts, and event-bus/index.ts. Run the type-aware lint command and CDK snapshot checks first. Done means all non-destructive findings are fixed, the two stack-name exceptions retain reasons, lint passes, and cdk synth shows no diff.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, nodejs, typescript
- Domain
- ci-cd, infrastructure, testing, tooling
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 55/100