diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 327f2b6..aa56fb2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -6,8 +6,9 @@ on: pull_request: branches: [main] -# Least privilege. The job only reads the repo — it publishes nothing, comments -# nowhere. Declaring it explicitly also silences CodeQL's +# Least privilege. The jobs only read the repo — they publish nothing on +# GitHub and comment nowhere (SonarCloud's own GitHub app reports on PRs, with +# its own permissions). Declaring it explicitly also silences CodeQL's # `actions/missing-workflow-permissions`, which otherwise flags the implicit # (and much wider) default token scope. permissions: @@ -61,6 +62,14 @@ jobs: # Coverage thresholds for src/engine and worker live in vitest.config.ts. - name: Test (with coverage thresholds) run: npm run test:coverage + # The LCOV report the `sonarcloud` job hands to SonarCloud. + - name: Keep the coverage report for SonarCloud + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: coverage + path: coverage/lcov.info + if-no-files-found: error + retention-days: 1 # --- consistency ------------------------------------------------------ - name: Check formatting @@ -104,3 +113,49 @@ jobs: # Builds will — without deploying anything. - name: Dry-run the Cloudflare deploy run: npm run cf:check + + # SonarCloud, CI-based: issues, duplication and the coverage from `check`, + # judged by the quality gate (settings in sonar-project.properties). + # Automatic Analysis is off in the project's settings, so this is the only + # analysis. A job of its own so that SONAR_TOKEN never shares a job with + # npm packages: it only checks out, takes the coverage report and runs the + # scanner. + # + # PRs from forks and from Dependabot get no repository secrets (Dependabot + # PRs get the Dependabot secrets, which hold no SONAR_TOKEN), so they skip + # it and main is analysed once they merge. The PR author, not + # `github.actor`, decides — the actor can be spoofed (zizmor: bot-conditions). + sonarcloud: + needs: check + if: >- + github.event_name == 'push' || + (github.event.pull_request.head.repo.full_name == github.repository && + github.event.pull_request.user.login != 'dependabot[bot]') + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + # Full history: SonarCloud tells new code from old by git blame. + fetch-depth: 0 + persist-credentials: false + - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + with: + name: coverage + path: coverage + # New code is "since the previous version": each release starts a new + # period, and SonarCloud learns the version from here. + - name: Read the app version + id: version + run: | + version="$(jq -r .version package.json)" + if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + echo "::error::package.json version \"$version\" is not X.Y.Z" + exit 1 + fi + echo "version=$version" >> "$GITHUB_OUTPUT" + - name: SonarCloud scan + uses: SonarSource/sonarqube-scan-action@d209202bc7d53ff1cc128f7f907dac145c9d6ae9 # v8.3.0 + env: + SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }} + with: + args: -Dsonar.projectVersion=${{ steps.version.outputs.version }} diff --git a/CLAUDE.md b/CLAUDE.md index 04202aa..c81c8aa 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,19 +11,19 @@ ## Tech Stack -| Layer | Technology | -| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| UI | React 19, TypeScript 7 (strict), Radix primitives (`radix-ui`), Motion (LazyMotion), cmdk, sonner, lucide-react + simple-icons | -| Build | Vite 8 (Rolldown); config imports need `.ts` extensions; Node 26 (`.node-version`) | -| Type checking | TypeScript 7 `tsc` (`@typescript/native`); `typescript` is an npm alias for `@typescript/typescript6`, the 6.0 API typescript-eslint loads | -| Styling | Tailwind CSS 4, CSS-first `@theme` tokens in `src/styles/globals.css` | -| State | Zustand 5 + `persist` (localStorage) — the only store on every platform | -| Routing | React Router 7 — `BrowserRouter` on the web, `HashRouter` in Tauri | -| i18n | i18next + react-i18next, 8 locales (en, vi, ja, es, ko, zh, pt-BR, id); `en` bundled, others lazy | -| Desktop / Android | Tauri 2 (Rust) — see `src-tauri/` | -| Web hosting | Cloudflare Workers (`worker/`, `wrangler.jsonc`), Turnstile, Web Analytics | -| Tests | Vitest (node environment; Worker tests included) | -| Quality | ESLint, Prettier, knip, coverage thresholds, bundle budget, licence allow-list, copyright years, REUSE, actionlint/zizmor, cargo fmt/clippy/deny | +| Layer | Technology | +| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| UI | React 19, TypeScript 7 (strict), Radix primitives (`radix-ui`), Motion (LazyMotion), cmdk, sonner, lucide-react + simple-icons | +| Build | Vite 8 (Rolldown); config imports need `.ts` extensions; Node 26 (`.node-version`) | +| Type checking | TypeScript 7 `tsc` (`@typescript/native`); `typescript` is an npm alias for `@typescript/typescript6`, the 6.0 API typescript-eslint loads | +| Styling | Tailwind CSS 4, CSS-first `@theme` tokens in `src/styles/globals.css` | +| State | Zustand 5 + `persist` (localStorage) — the only store on every platform | +| Routing | React Router 7 — `BrowserRouter` on the web, `HashRouter` in Tauri | +| i18n | i18next + react-i18next, 8 locales (en, vi, ja, es, ko, zh, pt-BR, id); `en` bundled, others lazy | +| Desktop / Android | Tauri 2 (Rust) — see `src-tauri/` | +| Web hosting | Cloudflare Workers (`worker/`, `wrangler.jsonc`), Turnstile, Web Analytics | +| Tests | Vitest (node environment; Worker tests included) | +| Quality | ESLint, Prettier, knip, coverage thresholds, bundle budget, licence allow-list, copyright years, REUSE, actionlint/zizmor, cargo fmt/clippy/deny, SonarCloud (CI-based) | ## Project Structure @@ -179,6 +179,6 @@ npm run generate:brand # favicon, PWA icons, link-preview card from assets/ - New content warning / tech note: the id in `CONTENT_WARNINGS` / `TECH_NOTES` (`src/engine/types.ts`), a group in `src/config/content-warning-groups.ts` / `tech-note-groups.ts`, the editor label (`ui.json`) and description line (`templates.json`) in all 8 locales and `_schema.json` — tests fail on any gap — and the row in `docs/CONTENT-INVENTORY.md` (+ vi). Don't repeat a fact that has its own field (language patch, game version, difficulty, the Video settings upscaler). - New store platform: `src/config/platforms.ts` (URL pattern, `tagName`), optionally a name extractor in `src/utils/url-extractors.ts`. - Never commit `note.txt`, `warning.txt` or `__pycache__/`; never put real secrets in files (`.dev.vars` holds Cloudflare's public Turnstile test keys only). -- SonarCloud (Automatic Analysis, project `poli0981_youtube-generator`) analyses every PR and `main`; keep it at 0 open issues. Check a PR with `https://sonarcloud.io/api/issues/search?componentKeys=poli0981_youtube-generator&pullRequest=&resolved=false`. Workflows install with `npm ci --ignore-scripts` and call local binaries (`npm run …`), never `npx` for a package that isn't installed. +- SonarCloud (project `poli0981_youtube-generator`) is CI-based: the `sonarcloud` job in `ci.yml` scans every PR from this repository and every push to `main`, with the coverage from `check`; settings in `sonar-project.properties`; Automatic Analysis is off. Keep it at 0 open issues and the quality gate (Sonar way: A ratings, reviewed hotspots, ≤ 3 % duplication, ≥ 80 % coverage on new code) green — the job fails with the gate. Coverage covers what `coverage.include` in `vitest.config.ts` lists (the logic layers); everything else is in `sonar.coverage.exclusions`, because a file missing from the LCOV report counts as 0 % — a new source folder goes into one list or the other. The version passed to the scanner starts each release's new-code period. Fork and Dependabot PRs skip the scan (no `SONAR_TOKEN`). Check a PR with `https://sonarcloud.io/api/issues/search?componentKeys=poli0981_youtube-generator&pullRequest=&resolved=false` and its gate with `https://sonarcloud.io/api/qualitygates/project_status?projectKey=poli0981_youtube-generator&pullRequest=`. Workflows install with `npm ci --ignore-scripts` and call local binaries (`npm run …`), never `npx` for a package that isn't installed. - TypeScript bumps may be manual: `@typescript/native` (`npm:typescript@^7`) and `typescript` (`npm:@typescript/typescript6@^6`) are npm aliases Dependabot may not follow. Stop the dev server before `npm ci` on Windows — it locks native modules (EPERM). - The Cloudflare dashboard, publishing releases and repository settings are the maintainer's; ask before touching them. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 06fcd86..5f43c7d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,7 +38,7 @@ Use the templates in `.github/ISSUE_TEMPLATE/`: - Branch from `main` (`feat/…`, `fix/…`, `docs/…`) and open the PR against `main`. Every merge to `main` deploys the web app, so `main` stays releasable. - Commit format and **PR title**: `type(scope): message` — e.g. `feat(engine): add Spanish template support`. Types: `feat`, `fix`, `refactor`, `docs`, `test`, `ci`, `chore`. CI checks the PR title. -- Required checks: `check`, `dependency-review`, `workflow-lint`, `reuse`, `pr-title`. When `src-tauri/` changes, the Rust workflow's `lint-and-test` and `cargo-deny` run too, and GitHub's CodeQL code scanning runs on every PR. Commits on `main` are signed. +- Required checks: `check`, `dependency-review`, `workflow-lint`, `reuse`, `pr-title`. When `src-tauri/` changes, the Rust workflow's `lint-and-test` and `cargo-deny` run too, and GitHub's CodeQL code scanning runs on every PR. SonarCloud analyses PRs opened from this repository — its quality gate wants A ratings, reviewed security hotspots, at most 3 % duplication and at least 80 % test coverage on new code in the layers Vitest measures (PRs from forks get no secrets and skip it; the maintainer's merge runs it on `main`). Commits on `main` are signed. - PR titles start with a lower-case letter after the colon (`feat(editor): add …`, not `feat(editor): Add …`). - One logical change per PR. Don't bundle unrelated refactors. - All locale files must stay in lock-step — see the i18n section below. diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index a1f208e..0298bc9 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -86,6 +86,7 @@ The dev server is the app alone: no Turnstile gate and no analytics. To run the - Branch from `main` (`feat/…`, `fix/…`, `docs/…`, `chore/…`) and open the pull request against `main`. There is no other long-lived branch, and every merge to `main` deploys the web app. - PR titles use the commit format `type(scope): message`; CI checks them. - Every PR runs the `check` job (below), `dependency-review`, `workflow-lint`, `reuse` and `pr-title`; the Rust jobs `lint-and-test` and `cargo-deny` run when `src-tauri/` changes. +- After `check`, the `sonarcloud` job sends the code and the coverage report to [SonarCloud](https://sonarcloud.io/project/overview?id=poli0981_youtube-generator) (settings in `sonar-project.properties`) and fails when its quality gate does: new code needs A ratings, reviewed security hotspots, at most 3 % duplication and at least 80 % coverage. PRs from forks and from Dependabot skip it — they get no `SONAR_TOKEN` — and `main` is analysed after every merge. Full rules: [CONTRIBUTING.md](../CONTRIBUTING.md). @@ -104,24 +105,24 @@ Full rules: [CONTRIBUTING.md](../CONTRIBUTING.md). ### Check -| Command | What it does | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `npm run typecheck` | `tsc --noEmit` over `src/` — what Vite actually builds. | -| `npm run typecheck:all` | Same, plus `tests/`, `scripts/`, `worker/` and `build-plugins/` (`tsconfig.check.json`), which the base config deliberately excludes. Added in v0.35.0 after it turned out tests and scripts had **never** been type-checked — and immediately found three fields silently missing from the editor→engine parity fixture. | -| `npm run lint` | ESLint over `src/`, `tests/`, `scripts/`, `worker/` and `build-plugins/`. Use `npm run lint:fix` to autofix. | -| `npm run format` | Prettier write across `src/`, `tests/`, `scripts/`, `worker/` and `build-plugins/` (`.ts`, `.tsx`, `.css`). | -| `npm run format:check` | Same, read-only. CI gate. Markdown and the locale JSON are deliberately out of scope. | -| `npm run knip` | Dead-code / unused-dependency check. CI gate. | -| `npm run validate:locales` | Enforces all 8 locales match `_schema.json` exactly. **Must pass before any locale-touching PR merges.** | -| `npm run test` | Vitest watch mode. | -| `npm run test:run` | Vitest single-run. | -| `npm run test:coverage` | Single run with a coverage report into `coverage/`; fails below the thresholds for `src/engine/` and `worker/` set in `vitest.config.ts`. This is what CI runs. | -| `npm run check:version` | Asserts all **six** version fields agree (`package.json`, both `package-lock.json` entries, `tauri.conf.json`, `Cargo.toml`, `Cargo.lock`). The only thing that notices a missed one. | -| `npm run check:tauri` | The `@tauri-apps/*` npm packages and the Tauri crates must share major.minor. The Tauri CLI refuses to build otherwise, and CI never runs a Tauri build. | -| `npm run check:licenses` | Every bundled package has an allowed license, and `THIRD_PARTY_NOTICES.md` matches what is installed. | -| `npm run check:copyright` | NOTICE, REUSE.toml and the installers' copyright string (`tauri.conf.json`) state the copyright years for the year of HEAD's commit — "2026", then "2026-2027" from the first commit of 2027. CI gate (v1.1.0). | -| `npm run check:bundle` | Run after `npm run build`: the initial load must stay ≤ 280 KB gzip and no JS chunk over 500 KB raw. | -| `npm run cf:check` | `wrangler deploy --dry-run`: validates `wrangler.jsonc` and bundles the Worker the way Workers Builds will, without deploying. | +| Command | What it does | +| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `npm run typecheck` | `tsc --noEmit` over `src/` — what Vite actually builds. | +| `npm run typecheck:all` | Same, plus `tests/`, `scripts/`, `worker/` and `build-plugins/` (`tsconfig.check.json`), which the base config deliberately excludes. Added in v0.35.0 after it turned out tests and scripts had **never** been type-checked — and immediately found three fields silently missing from the editor→engine parity fixture. | +| `npm run lint` | ESLint over `src/`, `tests/`, `scripts/`, `worker/` and `build-plugins/`. Use `npm run lint:fix` to autofix. | +| `npm run format` | Prettier write across `src/`, `tests/`, `scripts/`, `worker/` and `build-plugins/` (`.ts`, `.tsx`, `.css`). | +| `npm run format:check` | Same, read-only. CI gate. Markdown and the locale JSON are deliberately out of scope. | +| `npm run knip` | Dead-code / unused-dependency check. CI gate. | +| `npm run validate:locales` | Enforces all 8 locales match `_schema.json` exactly. **Must pass before any locale-touching PR merges.** | +| `npm run test` | Vitest watch mode. | +| `npm run test:run` | Vitest single-run. | +| `npm run test:coverage` | Single run with a coverage report into `coverage/` (`lcov.info` is what SonarCloud reads); fails below the thresholds for `src/engine/` and `worker/` set in `vitest.config.ts`. It measures the logic layers — `src/engine`, `src/config`, `src/store`, `src/utils`, `worker/`, `build-plugins/`; `sonar-project.properties` excludes everything else from SonarCloud's coverage, so a new source folder goes into one list or the other. This is what CI runs. | +| `npm run check:version` | Asserts all **six** version fields agree (`package.json`, both `package-lock.json` entries, `tauri.conf.json`, `Cargo.toml`, `Cargo.lock`). The only thing that notices a missed one. | +| `npm run check:tauri` | The `@tauri-apps/*` npm packages and the Tauri crates must share major.minor. The Tauri CLI refuses to build otherwise, and CI never runs a Tauri build. | +| `npm run check:licenses` | Every bundled package has an allowed license, and `THIRD_PARTY_NOTICES.md` matches what is installed. | +| `npm run check:copyright` | NOTICE, REUSE.toml and the installers' copyright string (`tauri.conf.json`) state the copyright years for the year of HEAD's commit — "2026", then "2026-2027" from the first commit of 2027. CI gate (v1.1.0). | +| `npm run check:bundle` | Run after `npm run build`: the initial load must stay ≤ 280 KB gzip and no JS chunk over 500 KB raw. | +| `npm run cf:check` | `wrangler deploy --dry-run`: validates `wrangler.jsonc` and bundles the Worker the way Workers Builds will, without deploying. | ### Generate diff --git a/docs/TECH-SPEC.md b/docs/TECH-SPEC.md index 96fcba8..b2dfa1e 100644 --- a/docs/TECH-SPEC.md +++ b/docs/TECH-SPEC.md @@ -582,7 +582,7 @@ An unknown version is read as 0: every migration step is idempotent, so running | Workflow | Runs on | Jobs | | ------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `ci.yml` (CI) | PRs to and pushes on `main` | `check` — the required status on `main` | +| `ci.yml` (CI) | PRs to and pushes on `main` | `check` — the required status on `main`; `sonarcloud` — the SonarCloud scan with `check`'s coverage (pushes on `main`, PRs from this repository except Dependabot's) | | `security.yml` (Security) | PRs, pushes on `main`, weekly, manual | `dependency-review` (PRs: fails on a newly added high/critical advisory), `workflow-lint` (actionlint + zizmor, `.github/zizmor.yml`), `scorecard` (OpenSSF Scorecard, informational; not on PRs) | | `compliance.yml` (Compliance) | PRs, pushes on `main` | `reuse` (REUSE licensing via `REUSE.toml`), `pr-title` (Conventional-Commit PR titles with a lower-case subject) | | `rust.yml` (Rust) | Changes under `src-tauri/`, weekly, manual | `lint-and-test` (`cargo fmt --all -- --check`, `cargo clippy --all-targets --locked -- -D warnings`, `cargo test --locked`, after `npm run build` because `generate_context!` embeds `dist/`), `cargo-deny` (`check advisories licenses sources`, `src-tauri/deny.toml`) | @@ -594,13 +594,14 @@ An unknown version is read as 0: every migration step is idempotent, so running The `check` job, in order: ```yaml -- run: npm ci +- run: npm ci --ignore-scripts # correctness - run: npm run typecheck # src/ - run: npm run typecheck:all # + tests/, scripts/, worker/, build-plugins/ - run: npm run lint - run: npm run validate:locales - run: npm run test:coverage # thresholds in vitest.config.ts +- uses: actions/upload-artifact # coverage/lcov.info, for the sonarcloud job # consistency - run: npm run format:check - run: npm run knip @@ -615,13 +616,23 @@ The `check` job, in order: # build - run: npm run build - run: npm run check:bundle # initial load ≤ 280 KB gzip, no JS chunk > 500 KB raw -- run: npx wrangler deploy --dry-run --outdir .wrangler/dry-run +- run: npm run cf:check # wrangler deploy --dry-run +``` + +Then `sonarcloud` (after `check` succeeds): + +```yaml +- uses: actions/checkout # fetch-depth: 0 — new code is told from old by git blame +- uses: actions/download-artifact # the coverage report from check +- run: jq -r .version package.json # → sonar.projectVersion +- uses: SonarSource/sonarqube-scan-action # SONAR_TOKEN, sonar-project.properties ``` - **Bundle budget** (`scripts/check-bundle-size.ts`): the initial load is every script, modulepreload and stylesheet `dist/index.html` references, summed gzip — lazy chunks (pages, locales, legal documents) are excluded. The result is printed as a table and added to the job summary. - **Licences** (`scripts/lib/third-party.ts`): every package bundled into the app must carry an allowed licence (MIT, ISC, Apache-2.0, BSD-2/3-Clause, 0BSD, CC0-1.0, Unlicense, BlueOak-1.0.0, OFL-1.1, Zlib, MPL-2.0), and `THIRD_PARTY_NOTICES.md` is generated (`npm run generate:third-party`) and checked, not hand-written. - **Copyright years** (`scripts/lib/copyright.ts`, v1.1.0): NOTICE, REUSE.toml and `bundle.copyright` in `tauri.conf.json` must state `copyrightYears()` from `src/config/brand.ts` — "2026", then "2026-2027" from the first commit of 2027. The commit year rather than the clock keeps old commits green; `npm run update:copyright` rewrites the three files. The `/legal` pages' footer uses the same helper at build time. - **Wrangler dry run** validates `wrangler.jsonc` and bundles the Worker exactly as Workers Builds will, without deploying. +- **SonarCloud** (CI-based; Automatic Analysis is off in the project's settings): `sonar-project.properties` makes the whole repository main code except the tests (`tests/**` and any `src/**/*.test.ts(x)`, analysed as tests), imports `coverage/lcov.info` and excludes from coverage everything Vitest does not measure (see [Testing Strategy](#6-testing-strategy)). The scan waits for the quality gate — Sonar way: A security, reliability and maintainability ratings, every security hotspot reviewed, ≤ 3 % duplication and ≥ 80 % coverage on new code — and fails the job when it fails. New code is "since the previous version": the job reads `package.json`'s version into `sonar.projectVersion`, so every release starts a new period. The scan runs in a job of its own so that `SONAR_TOKEN` never shares a job with npm packages. PRs from forks and from Dependabot get no repository secrets and skip it; the condition checks the PR author, not `github.actor` (zizmor's `bot-conditions`). - Every workflow declares least-privilege `permissions`, checks out with `persist-credentials: false`, and pins actions by commit SHA (Dependabot keeps the SHAs and version comments current). The exceptions are the actionlint Docker image (pinned by version tag) and the maintainer's own `poli0981/.github` reusable workflows (tracked at `main`, allowed in `.github/zizmor.yml`). CI, Security, Compliance and Rust cancel superseded runs through a `concurrency` group, except on `main`, where each commit's result is a record the release process reads back. **Web deployment is not a GitHub workflow.** Cloudflare Workers Builds builds and deploys the Worker and `dist/` on every push to `main` (preview versions for other branches). The old `deploy-web.yml` (GitHub Pages) is gone; `pages-migration.yml` only serves the moving notice, which hands visitors the data their browser saved on the old address as a `_format: 2` backup file. See [HOSTING.md](HOSTING.md). @@ -672,7 +683,7 @@ describe("buildTitle", () => { }); ``` -`npm run test:coverage` (what CI runs) measures `src/engine/**`, `worker/**` and `build-plugins/**` with V8 and fails below these thresholds — the engine is what the whole app trusts, the Worker is what guards the site: +`npm run test:coverage` (what CI runs) measures the logic layers with V8 — `src/engine/**`, `src/config/**`, `src/store/**`, `src/utils/**`, `worker/**` (except `worker/index.ts`, the runtime wiring) and `build-plugins/**` — and writes `coverage/lcov.info` for SonarCloud. Components, pages and hooks are checked in the running app, `src/i18n` is i18next set-up and `scripts/` is tooling; SonarCloud would count a file missing from the report as 0 % covered, so `sonar.coverage.exclusions` lists all of them, and a new source folder goes into one list or the other. The run fails below these thresholds — the engine is what the whole app trusts, the Worker is what guards the site: | Scope | Statements | Branches | Functions | Lines | | ----------------------------------------- | ---------- | -------- | --------- | ----- | diff --git a/docs/i18n/vi/DEVELOPMENT.md b/docs/i18n/vi/DEVELOPMENT.md index c1dd5b9..cb8571f 100644 --- a/docs/i18n/vi/DEVELOPMENT.md +++ b/docs/i18n/vi/DEVELOPMENT.md @@ -88,6 +88,7 @@ Dev server chỉ chạy riêng app: không có cổng Turnstile, không có anal - Tạo nhánh từ `main` (`feat/…`, `fix/…`, `docs/…`, `chore/…`) và mở pull request vào `main`. Không có nhánh dài hạn nào khác, và mỗi lần merge vào `main` đều deploy bản web. - Tiêu đề PR theo định dạng commit `type(scope): message`; CI có kiểm tra. - Mỗi PR đều chạy job `check` (xem bên dưới), `dependency-review`, `workflow-lint`, `reuse` và `pr-title`; hai job Rust `lint-and-test` và `cargo-deny` chạy khi có thay đổi trong `src-tauri/`. +- Sau `check`, job `sonarcloud` gửi mã nguồn và báo cáo coverage lên [SonarCloud](https://sonarcloud.io/project/overview?id=poli0981_youtube-generator) (cấu hình trong `sonar-project.properties`) và fail khi quality gate fail: code mới phải đạt hạng A, mọi security hotspot đã được review, trùng lặp tối đa 3 % và coverage tối thiểu 80 %. PR từ fork và từ Dependabot bỏ qua job này — chúng không có `SONAR_TOKEN` — còn `main` được phân tích sau mỗi lần merge. Quy định đầy đủ: [CONTRIBUTING.md](../../../CONTRIBUTING.md). @@ -106,24 +107,24 @@ Quy định đầy đủ: [CONTRIBUTING.md](../../../CONTRIBUTING.md). ### Kiểm tra -| Lệnh | Tác dụng | -| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `npm run typecheck` | `tsc --noEmit` trên `src/` — đúng phần Vite build. | -| `npm run typecheck:all` | Như trên, thêm `tests/`, `scripts/`, `worker/` và `build-plugins/` (`tsconfig.check.json`) — những thư mục config gốc cố ý bỏ qua. Có từ v0.35.0, khi phát hiện tests và scripts **chưa từng** được type-check — và lần chạy đầu đã tìm ra ba field bị thiếu âm thầm trong fixture parity editor→engine. | -| `npm run lint` | ESLint trên `src/`, `tests/`, `scripts/`, `worker/` và `build-plugins/`. Dùng `npm run lint:fix` để tự sửa. | -| `npm run format` | Chạy Prettier (ghi file) trên `src/`, `tests/`, `scripts/`, `worker/` và `build-plugins/` (`.ts`, `.tsx`, `.css`). | -| `npm run format:check` | Như trên nhưng chỉ kiểm tra. Là cổng CI. Markdown và JSON locale cố ý nằm ngoài phạm vi. | -| `npm run knip` | Tìm code chết / dependency không dùng. Là cổng CI. | -| `npm run validate:locales` | Bắt buộc cả 8 locale khớp chính xác với `_schema.json`. **Phải pass trước khi merge PR động đến locale.** | -| `npm run test` | Vitest chế độ watch. | -| `npm run test:run` | Vitest chạy một lần. | -| `npm run test:coverage` | Chạy một lần kèm báo cáo coverage vào `coverage/`; fail nếu thấp hơn ngưỡng đặt cho `src/engine/` và `worker/` trong `vitest.config.ts`. CI chạy lệnh này. | -| `npm run check:version` | Kiểm tra cả **sáu** trường version khớp nhau (`package.json`, hai chỗ trong `package-lock.json`, `tauri.conf.json`, `Cargo.toml`, `Cargo.lock`). Đây là thứ duy nhất phát hiện khi bỏ sót một chỗ. | -| `npm run check:tauri` | Các package npm `@tauri-apps/*` và các crate Tauri phải cùng major.minor. Tauri CLI sẽ từ chối build nếu lệch, mà CI thì không chạy build Tauri. | -| `npm run check:licenses` | Mọi package được bundle đều có license nằm trong danh sách cho phép, và `THIRD_PARTY_NOTICES.md` khớp với những gì đang cài. | -| `npm run check:copyright` | NOTICE, REUSE.toml và chuỗi copyright của bộ cài (`tauri.conf.json`) phải ghi đúng năm theo năm của commit HEAD — "2026", rồi "2026-2027" từ commit đầu tiên của năm 2027. Gate của CI (v1.1.0). | -| `npm run check:bundle` | Chạy sau `npm run build`: lần tải đầu phải ≤ 280 KB gzip và không chunk JS nào vượt 500 KB (chưa nén). | -| `npm run cf:check` | `wrangler deploy --dry-run`: kiểm tra `wrangler.jsonc` và bundle Worker y như Workers Builds sẽ làm, nhưng không deploy. | +| Lệnh | Tác dụng | +| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `npm run typecheck` | `tsc --noEmit` trên `src/` — đúng phần Vite build. | +| `npm run typecheck:all` | Như trên, thêm `tests/`, `scripts/`, `worker/` và `build-plugins/` (`tsconfig.check.json`) — những thư mục config gốc cố ý bỏ qua. Có từ v0.35.0, khi phát hiện tests và scripts **chưa từng** được type-check — và lần chạy đầu đã tìm ra ba field bị thiếu âm thầm trong fixture parity editor→engine. | +| `npm run lint` | ESLint trên `src/`, `tests/`, `scripts/`, `worker/` và `build-plugins/`. Dùng `npm run lint:fix` để tự sửa. | +| `npm run format` | Chạy Prettier (ghi file) trên `src/`, `tests/`, `scripts/`, `worker/` và `build-plugins/` (`.ts`, `.tsx`, `.css`). | +| `npm run format:check` | Như trên nhưng chỉ kiểm tra. Là cổng CI. Markdown và JSON locale cố ý nằm ngoài phạm vi. | +| `npm run knip` | Tìm code chết / dependency không dùng. Là cổng CI. | +| `npm run validate:locales` | Bắt buộc cả 8 locale khớp chính xác với `_schema.json`. **Phải pass trước khi merge PR động đến locale.** | +| `npm run test` | Vitest chế độ watch. | +| `npm run test:run` | Vitest chạy một lần. | +| `npm run test:coverage` | Chạy một lần kèm báo cáo coverage vào `coverage/` (SonarCloud đọc `lcov.info`); fail nếu thấp hơn ngưỡng đặt cho `src/engine/` và `worker/` trong `vitest.config.ts`. Lệnh đo các tầng logic — `src/engine`, `src/config`, `src/store`, `src/utils`, `worker/`, `build-plugins/`; `sonar-project.properties` loại mọi phần còn lại khỏi coverage của SonarCloud, nên một thư mục mã nguồn mới phải vào danh sách này hoặc danh sách kia. CI chạy lệnh này. | +| `npm run check:version` | Kiểm tra cả **sáu** trường version khớp nhau (`package.json`, hai chỗ trong `package-lock.json`, `tauri.conf.json`, `Cargo.toml`, `Cargo.lock`). Đây là thứ duy nhất phát hiện khi bỏ sót một chỗ. | +| `npm run check:tauri` | Các package npm `@tauri-apps/*` và các crate Tauri phải cùng major.minor. Tauri CLI sẽ từ chối build nếu lệch, mà CI thì không chạy build Tauri. | +| `npm run check:licenses` | Mọi package được bundle đều có license nằm trong danh sách cho phép, và `THIRD_PARTY_NOTICES.md` khớp với những gì đang cài. | +| `npm run check:copyright` | NOTICE, REUSE.toml và chuỗi copyright của bộ cài (`tauri.conf.json`) phải ghi đúng năm theo năm của commit HEAD — "2026", rồi "2026-2027" từ commit đầu tiên của năm 2027. Gate của CI (v1.1.0). | +| `npm run check:bundle` | Chạy sau `npm run build`: lần tải đầu phải ≤ 280 KB gzip và không chunk JS nào vượt 500 KB (chưa nén). | +| `npm run cf:check` | `wrangler deploy --dry-run`: kiểm tra `wrangler.jsonc` và bundle Worker y như Workers Builds sẽ làm, nhưng không deploy. | ### Sinh file diff --git a/sonar-project.properties b/sonar-project.properties new file mode 100644 index 0000000..6169757 --- /dev/null +++ b/sonar-project.properties @@ -0,0 +1,48 @@ +# SonarCloud, CI-based analysis. Automatic Analysis is off in the project's +# settings: the scanner runs in the `sonarcloud` job of +# .github/workflows/ci.yml, on every PR and every push to main, and reads this +# file. The version (package.json) is passed on the command line there. +sonar.organization=poli0981 +sonar.projectKey=poli0981_youtube-generator +sonar.sourceEncoding=UTF-8 + +# Main code is the whole repository: the app, the Worker, the build plugins, +# the scripts, the Tauri shell (Rust, and the Android project, which is +# committed and edited), the migration page and the workflows. The tests are +# analysed as tests: the same files Vitest runs (vitest.config.ts) plus +# tests/helpers. Files git ignores are left out on their own. +sonar.sources=. +sonar.exclusions=tests/**,src/**/*.test.ts,src/**/*.test.tsx +sonar.tests=. +sonar.test.inclusions=tests/**,src/**/*.test.ts,src/**/*.test.tsx + +# Coverage is Vitest's LCOV report (`npm run test:coverage` in the `check` +# job), which measures the logic layers: src/engine, src/config, src/store, +# src/utils, worker/ and build-plugins/. SonarCloud would count a file missing +# from the report as 0 % covered, so everything else is excluded here. Keep +# this list in step with `coverage.include` in vitest.config.ts. +# - No test renders a component or page (there is no DOM environment); the +# hooks and i18n are React and i18next glue, checked in the running app. +# - worker/index.ts only wires the router to the Workers runtime. +# - scripts/ and the config files are tooling; the migration page and +# public/theme-init.js are static pages' scripts. +# - The Rust and Android code have no coverage tooling. +sonar.javascript.lcov.reportPaths=coverage/lcov.info +sonar.coverage.exclusions=\ + src/App.tsx,\ + src/main.tsx,\ + src/components/**,\ + src/pages/**,\ + src/hooks/**,\ + src/i18n/**,\ + worker/index.ts,\ + scripts/**,\ + *.config.js,\ + *.config.ts,\ + migration-page/**,\ + public/**,\ + src-tauri/** + +# The scan waits for the quality gate and fails the job when it fails, so the +# result is in CI as well as in SonarCloud's own check on the PR. +sonar.qualitygate.wait=true diff --git a/vitest.config.ts b/vitest.config.ts index 0014c3e..44d89f2 100644 --- a/vitest.config.ts +++ b/vitest.config.ts @@ -32,15 +32,30 @@ export default defineConfig({ // default environment is node — a test that renders needs an explicit // `// @vitest-environment jsdom` docblock (and jsdom installed). include: ["tests/**/*.test.{ts,tsx}", "src/**/*.test.{ts,tsx}"], - // `npm run test:coverage` (what CI runs). Thresholds sit just under the - // measured coverage so they catch regressions without blocking work; raise - // them as tests are added. The engine is the part the whole app trusts, - // the worker is the part that guards the site. + // `npm run test:coverage` (what CI runs). It measures the logic layers — + // what the unit tests are for. Components, pages and hooks are checked in + // the running app (no test renders one), i18n is i18next set-up, and + // scripts/ is CI tooling. SonarCloud reads the LCOV file (the `sonarcloud` + // job in ci.yml) and counts a file missing from it as 0 % covered, so + // `sonar.coverage.exclusions` in sonar-project.properties lists everything + // outside this scope — keep the two in step. + // + // Thresholds sit just under the measured coverage so they catch + // regressions without blocking work; raise them as tests are added. The + // engine is the part the whole app trusts, the worker is the part that + // guards the site. coverage: { provider: "v8", - include: ["src/engine/**", "worker/**", "build-plugins/**"], + include: [ + "src/engine/**", + "src/config/**", + "src/store/**", + "src/utils/**", + "worker/**", + "build-plugins/**", + ], exclude: ["worker/index.ts"], - reporter: ["text-summary", "json-summary"], + reporter: ["text-summary", "json-summary", "lcovonly"], thresholds: { "src/engine/**": { statements: 88, branches: 85, functions: 60, lines: 88 }, "worker/**": { statements: 95, branches: 85, functions: 95, lines: 95 },