From d9e5815dfe5e800c362df0e99d969526015e0f84 Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Wed, 28 Oct 2026 23:17:16 +0700 Subject: [PATCH] ci: SonarCloud CI analysis with coverage, and a release that never installs while holding a write token MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SonarCloud ran Automatic Analysis: no coverage, and a scan of the repo rather than of what CI builds. sonarcloud.yml replaces it — full-history checkout, the coverage run, then the scan with the package version as the new-code baseline. It is its own workflow so a Sonar outage or gate opinion can never turn CI red, the scan action is pinned to a commit because it holds SONAR_TOKEN, the token reaches only the two steps that use it, and runs without secrets (Dependabot, forks) skip with a notice instead of failing. Coverage now measures every src/**/*.ts module and emits lcov, but the CI gate is unchanged: a glob threshold applies the docs/11 §1 numbers to src/lib/core/** only (verified to still fail a run below them). Hardening, from SonarCloud's findings and the scripts/config audit: - npm ci --ignore-scripts everywhere, with `wxt prepare` run explicitly; - checkouts drop persisted credentials; - release.yml is split: gates and zip run with a read-only token; only a job that installs nothing and runs no repo code creates the Release; the store submit uses the local wxt binary, never `npx` with secrets in scope; - reusables get named secrets instead of `inherit`. The announce job could never have worked: this repo stores RELEASES_WEBHOOK/REPO_WEBHOOK, the reusable reads DISCORD_*, and inherit passed neither; - CI runs `npm audit --omit=dev`, which docs/09 already claimed it did; - a non-required Windows smoke job (guard + unit tests). serializeMarkdown's trailing-newline trim used /\n+$/, which backtracks quadratically over a long newline run that is not at the end (S8786); it is now a single backward scan, with a 20k-newline regression test. docs/12 no longer copies the workflow YAML — the copies drifted three times, and under docs-win a stale copy invites reverting a pinned action. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 50 ++- .github/workflows/notify-ci-failure.yml | 5 +- .github/workflows/release.yml | 133 ++++--- .github/workflows/sonarcloud.yml | 79 +++++ docs/11_TESTING.md | 11 +- docs/12_CI_CD.md | 393 ++++++++------------- docs/15_ROADMAP.md | 4 + sonar-project.properties | 28 ++ src/lib/core/serialize/markdown.ts | 16 +- tests/unit/core/serialize/markdown.test.ts | 17 + vitest.config.ts | 14 +- 11 files changed, 451 insertions(+), 299 deletions(-) create mode 100644 .github/workflows/sonarcloud.yml create mode 100644 sonar-project.properties diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e795874..d9f4a1a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,7 +2,8 @@ # # The `quality` job is local because the ops reusable runs NO quality gates at # all: its entire surface is install → build → assert manifest_version == 3 → -# zip → upload. Lint, type-check, knip, coverage and the grep gate are ours. +# zip → upload. Lint, type-check, knip, coverage, audit and the grep gate are +# ours. name: CI on: @@ -26,16 +27,29 @@ jobs: contents: read steps: - uses: actions/checkout@v7 + with: + persist-credentials: false - uses: actions/setup-node@v7 with: - node-version: '24' + node-version-file: .nvmrc cache: npm - - run: npm ci + + # --ignore-scripts: no dependency runs code at install time. `wxt prepare` + # (our postinstall) generates .wxt/tsconfig.json, which tsconfig.json + # extends, so it runs explicitly from the local binary. + - run: npm ci --ignore-scripts + - run: npx --no-install wxt prepare + - run: npm run lint # biome check . - - run: npm run check # svelte-check + tsc --noEmit + - run: npm run check # svelte-check (TS 6 API) + tsc (TS 7) - run: npm run knip - run: npm run coverage # vitest --coverage, thresholds per docs/11 §1 - - run: npm run guard # the canonical grep gate, docs/08 §3 + - run: npm run guard # the zero-network / no-raw-HTML gate, docs/08 §3 + + # Zero runtime dependencies is a public claim (README, docs/09 T5); this + # is the check that keeps it true. Dev-only advisories are tracked by + # Dependabot and docs/09 §3.1, not here. + - run: npm audit --omit=dev --audit-level=low # The unit test proves what wxt.config.ts ASKS for. Only this proves what # WXT actually emitted — a dev build of the same config carries @@ -43,6 +57,28 @@ jobs: - run: npm run build - run: npm run check:manifest + windows: + # Not a required check. The owner develops on Windows, and the paths that + # only break there — drive letters and percent-encoding in script paths, + # CRLF in a checkout — had no CI coverage at all. + name: Windows smoke (guard + unit tests) + runs-on: windows-latest + timeout-minutes: 20 + permissions: + contents: read + steps: + - uses: actions/checkout@v7 + with: + persist-credentials: false + - uses: actions/setup-node@v7 + with: + node-version-file: .nvmrc + cache: npm + - run: npm ci --ignore-scripts + - run: npx --no-install wxt prepare + - run: npm run guard + - run: npm test + build: name: Build + package needs: quality @@ -66,7 +102,9 @@ jobs: # 'none' default skips install and build, then fails on # `test -f ./manifest.json` — a file WXT never writes to the repo root. package-manager: 'npm' - node-version: '24' + # A string input, so it cannot read .nvmrc — keep it equal by hand + # (docs/01 §2). + node-version: '26' build-command: 'npm run build' source-dir: '.output/chrome-mv3' release: false diff --git a/.github/workflows/notify-ci-failure.yml b/.github/workflows/notify-ci-failure.yml index c678d29..d16df55 100644 --- a/.github/workflows/notify-ci-failure.yml +++ b/.github/workflows/notify-ci-failure.yml @@ -39,4 +39,7 @@ jobs: permissions: contents: read actions: read - secrets: inherit + # Named, not `inherit`: the reusable is pinned to a moving branch, so it gets + # the one secret it declares and nothing else. + secrets: + DISCORD_CI_WEBHOOK: ${{ secrets.DISCORD_CI_WEBHOOK }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index e5f21de..6fbe515 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -4,6 +4,12 @@ # runs `gh release create --generate-notes`. It produces no SHA256SUMS.txt # (required by docs/09 §5), performs no store submission, and exposes no # `outputs:`, so a caller cannot reference the zip it built. +# +# Three jobs, least privilege first. `build` installs, runs every gate and +# packages with a READ-ONLY token; only `publish`, which installs nothing and +# runs no repository code, ever holds `contents: write`. Before this split one +# job ran `npm ci` — every dependency's install script plus our own tests — +# while holding a write token that checkout had also left in .git/config. name: Release on: @@ -14,18 +20,22 @@ permissions: contents: read jobs: - release: + build: + name: Gate + package runs-on: ubuntu-latest timeout-minutes: 20 permissions: - contents: write # create the GitHub Release + contents: read steps: - uses: actions/checkout@v7 + with: + persist-credentials: false - uses: actions/setup-node@v7 with: - node-version: '24' + node-version-file: .nvmrc cache: npm - - run: npm ci + - run: npm ci --ignore-scripts + - run: npx --no-install wxt prepare # The same gates as CI. A tag must never ship what a PR would have # blocked — pushing a tag skips the CI workflow's branch triggers. @@ -34,6 +44,7 @@ jobs: - run: npm run knip - run: npm run coverage - run: npm run guard + - run: npm audit --omit=dev --audit-level=low - run: npm run zip # wxt zip → .output/--chrome.zip @@ -53,67 +64,109 @@ jobs: working-directory: .output run: sha256sum *-chrome.zip > SHA256SUMS.txt + - uses: actions/upload-artifact@v7 + with: + name: release-${{ github.ref_name }} + path: | + .output/*-chrome.zip + .output/SHA256SUMS.txt + if-no-files-found: error + retention-days: 90 + + publish: + name: GitHub Release + needs: build + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: write # create the GitHub Release — the only write in this file + steps: + - uses: actions/download-artifact@v8 + with: + name: release-${{ github.ref_name }} + path: dist + + # The bytes about to be published are the bytes the build job hashed. + - name: Re-verify checksums + working-directory: dist + run: sha256sum -c SHA256SUMS.txt + # Idempotent on purpose. `gh release create` fails outright if a Release # for the tag already exists, so any failure AFTER this step — realistically - # the CWS publish below, once CWS_AUTOPUBLISH is on — used to strand the - # tag: re-running the workflow could not get past this line, and the only - # recovery was deleting the Release and the tag by hand (docs/13 §7). - - name: GitHub Release + # the store job below, once CWS_AUTOPUBLISH is on — used to strand the tag: + # re-running could not get past this line (docs/13 §7). + - name: Create or update the Release env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GH_REPO: ${{ github.repository }} run: | set -euo pipefail if gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then echo "Release $GITHUB_REF_NAME exists — re-uploading assets." - gh release upload "$GITHUB_REF_NAME" \ - .output/*-chrome.zip .output/SHA256SUMS.txt --clobber + gh release upload "$GITHUB_REF_NAME" dist/*-chrome.zip dist/SHA256SUMS.txt --clobber else - gh release create "$GITHUB_REF_NAME" \ - .output/*-chrome.zip .output/SHA256SUMS.txt --generate-notes + gh release create "$GITHUB_REF_NAME" dist/*-chrome.zip dist/SHA256SUMS.txt \ + --verify-tag --generate-notes fi - # v1.0.x is published by hand (docs/12 §3) — first store reviews often - # ask questions and want a human in the loop. Flipping the repo variable - # CWS_AUTOPUBLISH to 'true' turns this on for v1.1+. - - name: Publish to Chrome Web Store - if: vars.CWS_AUTOPUBLISH == 'true' + store: + # v1.0.x/v1.1.x are published by hand (docs/12 §3). Flipping the repo + # variable CWS_AUTOPUBLISH to 'true' turns this on once the four CHROME_* + # secrets exist. A variable, not a secret: only variables are allowed here. + name: Publish to Chrome Web Store + needs: publish + if: vars.CWS_AUTOPUBLISH == 'true' + runs-on: ubuntu-latest + timeout-minutes: 15 + permissions: + contents: read + steps: + - uses: actions/checkout@v7 + with: + persist-credentials: false + - uses: actions/setup-node@v7 + with: + node-version-file: .nvmrc + cache: npm + - run: npm ci --ignore-scripts + - uses: actions/download-artifact@v8 + with: + name: release-${{ github.ref_name }} + path: dist + - name: Submit the Release asset env: CHROME_EXTENSION_ID: ${{ secrets.CHROME_EXTENSION_ID }} CHROME_CLIENT_ID: ${{ secrets.CHROME_CLIENT_ID }} CHROME_CLIENT_SECRET: ${{ secrets.CHROME_CLIENT_SECRET }} CHROME_REFRESH_TOKEN: ${{ secrets.CHROME_REFRESH_TOKEN }} - run: npx wxt submit --chrome-zip .output/*-chrome.zip + # The locally installed wxt, never `npx wxt`: npx may fetch and run an + # unpinned package with these four secrets in its environment. + run: ./node_modules/.bin/wxt submit --chrome-zip dist/*-chrome.zip # A job INSIDE this workflow, not an `on: release: [published]` caller. # A Release created by `gh release create` under the default GITHUB_TOKEN # emits no event that starts new workflow runs, so an event-driven caller # would silently never fire. announce: - needs: release - # A Discord notification is not part of the release. The reusable exits 1 on - # "No webhooks configured" when DISCORD_RELEASES_WEBHOOK and - # DISCORD_REPO_WEBHOOK are both unset (docs/12 §5 lists them as optional), - # which turned the v1.0.0 run red even though the Release, the zip and - # SHA256SUMS.txt had all published correctly. A red run on a good release is - # worse than a missing announcement: it trains you to ignore the colour. - # - # ⚠️ This used to say `continue-on-error: true`, which GitHub REJECTS on a - # job that calls a reusable workflow — "Property continue-on-error is not - # allowed". The whole file is then invalid and the run is a startup_failure - # with zero jobs and no log, exactly like the `contents: write` mistake in - # 2c8fba9. It was never caught because that fix landed after the v1.0.0 tag - # and no tag has been pushed since, so the first v1.0.1 tag would have been - # its first execution. Gate on a repo VARIABLE instead — allowed in `if:`, - # unlike a secret, and the same idiom as CWS_AUTOPUBLISH above. + needs: publish + # A Discord notification is not part of the release, so it can never turn a + # good release red (docs/12 §2.3). Gated on a repo VARIABLE — GitHub REJECTS + # `continue-on-error` on a job that calls a reusable workflow, which makes + # the whole file a startup_failure with zero jobs and no log. if: vars.DISCORD_ANNOUNCE == 'true' uses: poli0981/.github/.github/workflows/announce-release.yml@main permissions: contents: read with: - # REQUIRED here, and only because of the comment above. The reusable - # resolves `TAG="${INPUT_TAG:-$EVENT_TAG}"` with EVENT_TAG = - # github.event.release.tag_name — which is empty under `on: push: tags`, - # so without this the job exits 1 on "No release tag available" and the - # announcement never fires for any release. + # REQUIRED here: the reusable resolves `TAG="${INPUT_TAG:-$EVENT_TAG}"` + # with EVENT_TAG = github.event.release.tag_name — empty under + # `on: push: tags` — so without this the job exits 1 and never announces. tag_override: ${{ github.ref_name }} - secrets: inherit + # Named, not `inherit`: the reusable is pinned to a moving branch, so it gets + # only the two webhooks it reads — never the CHROME_* or SONAR secrets. The + # names also differ: this repo stores RELEASES_WEBHOOK / REPO_WEBHOOK, while + # the reusable reads DISCORD_* — with `inherit` it received neither and would + # have failed on "No webhooks configured" the day DISCORD_ANNOUNCE was set. + secrets: + DISCORD_RELEASES_WEBHOOK: ${{ secrets.RELEASES_WEBHOOK }} + DISCORD_REPO_WEBHOOK: ${{ secrets.REPO_WEBHOOK }} diff --git a/.github/workflows/sonarcloud.yml b/.github/workflows/sonarcloud.yml new file mode 100644 index 0000000..28e4d1e --- /dev/null +++ b/.github/workflows/sonarcloud.yml @@ -0,0 +1,79 @@ +# SonarCloud — docs/12 §2.5. +# +# A separate workflow on purpose, not a job in ci.yml: a SonarCloud outage or a +# quality-gate opinion must never change the colour of CI, which is what branch +# protection reads ("Quality gates", "Build + package / build"). The verdict +# reaches the PR through the SonarCloud GitHub App's own check. +# +# ⚠️ Prerequisite: Automatic Analysis is OFF in the SonarCloud project +# (Administration → Analysis Method). With it on, the scanner refuses to run. +name: SonarCloud + +on: + push: + branches: [main] + pull_request: + +permissions: + contents: read + +concurrency: + group: sonarcloud-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + analyze: + name: SonarCloud analysis + runs-on: ubuntu-latest + timeout-minutes: 15 + permissions: + contents: read + steps: + - uses: actions/checkout@v7 + with: + # Full history: Sonar's new-code detection and blame need it. + fetch-depth: 0 + persist-credentials: false + - uses: actions/setup-node@v7 + with: + node-version-file: .nvmrc + cache: npm + + # --ignore-scripts: no dependency gets to run code at install time. Our own + # postinstall (`wxt prepare`) is the one script we need, so it runs + # explicitly — from the local binary, never fetched on demand. + - run: npm ci --ignore-scripts + - run: npx --no-install wxt prepare + + # lcov for Sonar; the docs/11 §1 thresholds still gate core here too. + - run: npm run coverage + + - name: Read the package version + id: pkg + run: echo "version=$(node -p "require('./package.json').version")" >> "$GITHUB_OUTPUT" + + # The token is scoped to the two steps that need it, so the install and + # the test run above never see it. Dependabot and fork PRs get no repo + # secrets at all: they skip the scan with a notice instead of failing. + - name: Check for SONAR_TOKEN + id: token + env: + SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }} + run: | + if [ -n "$SONAR_TOKEN" ]; then + echo "present=true" >> "$GITHUB_OUTPUT" + else + echo "present=false" >> "$GITHUB_OUTPUT" + echo "::notice::SonarCloud scan skipped — SONAR_TOKEN is not available to this run (Dependabot or fork PR)." + fi + + - name: SonarCloud scan + if: steps.token.outputs.present == 'true' + # Pinned to a commit, not a moving tag: this step holds a token. Dependabot + # proposes updates (with the repo's 7-day cooldown). + uses: SonarSource/sonarqube-scan-action@d209202bc7d53ff1cc128f7f907dac145c9d6ae9 # v8.3.0 + env: + SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }} + with: + args: > + -Dsonar.projectVersion=${{ steps.pkg.outputs.version }} diff --git a/docs/11_TESTING.md b/docs/11_TESTING.md index 51affa3..c715f29 100644 --- a/docs/11_TESTING.md +++ b/docs/11_TESTING.md @@ -9,10 +9,13 @@ | Components/UI | Manual QA checklist (§5) | No component-test framework in v1 (cost/benefit) | | End-to-end | Out of scope v1 (Roadmap: Playwright + `--load-extension`) | — | -`vitest.config.ts`: `plugins: [WxtVitest()]` (WXT aliases/auto-imports resolve -in tests), `environment: 'jsdom'`, `coverage.provider: 'v8'`, -`coverage.thresholds: { lines: 90, functions: 90, branches: 85 }` scoped to -`src/lib/core/**`. +`vitest.config.ts`: `plugins: [svelte(), WxtVitest()]` (the svelte plugin +compiles runes in `.svelte.ts` stores; WXT's resolves aliases and auto-imports), +`environment: 'jsdom'`, `coverage.provider: 'v8'`. Coverage **measures** every +`src/**/*.ts` module and writes `text` + `lcov` (SonarCloud reads the lcov, +`12 §2.5`), but only core is **gated**: a glob threshold +`'src/lib/core/**': { lines: 90, functions: 90, branches: 85 }`, so widening +what is measured cannot change what is enforced. **Environment canary.** Add one test asserting that a Chrome fixture parses to a `
` nested *inside* its `
` (`dl.querySelector('dt').querySelector(':scope > dl') !== null`). diff --git a/docs/12_CI_CD.md b/docs/12_CI_CD.md index 4dd88f2..2d2812f 100644 --- a/docs/12_CI_CD.md +++ b/docs/12_CI_CD.md @@ -27,72 +27,55 @@ workflows use the `reusable-*` naming family. There is **no ## 2. Workflows (caller stubs in this repo) -⚠️ **The YAML below is a copy of live files, and copies drift.** It has already -happened twice: a Dependabot bump moved `actions/setup-node` from v6 to v7 in -`.github/workflows/` and never touched this doc, and the `check:manifest` step -added to the release job in `674ac34` was missing here. Because docs win over -code in this project, someone reconciling in the wrong direction would have -downgraded a pinned action and deleted a security gate. Both are corrected -below (2026-08-03). **When these disagree again, read the workflow file first -and fix this doc — that is the one place the docs-win rule inverts, because the -running pipeline is the ground truth about itself.** +**This chapter no longer copies the workflow YAML** (decided 2026-10-28). It +used to, and the copies drifted three times: a Dependabot bump moved +`actions/setup-node` v6 → v7 in `.github/workflows/` and never touched this doc, +the `check:manifest` step added to the release job in `674ac34` was missing +here, and a copy kept `continue-on-error` after the file had dropped it. +Because docs win over code in this project, a stale copy is a standing +invitation to "reconcile" a pinned action backwards or delete a security gate. +**The workflow files are the ground truth about themselves.** What follows is +what a YAML file cannot say: why each job exists, what it must keep doing, and +the traps already stepped in. -### 2.1 `.github/workflows/ci.yml` — every push/PR to `main` +Common to every job since v1.1.0: -The local `quality` job exists because the ops reusable workflow performs none -of it (§1). The `build` job delegates packaging. +- `actions/checkout` with `persist-credentials: false` — no job pushes, so no + job leaves a token in `.git/config`. +- `actions/setup-node` with `node-version-file: .nvmrc` (Node 26, `01 §2`). + The ops reusable takes a string input and cannot read the file, so `ci.yml` + passes it `'26'` — keep the two equal by hand. +- `npm ci --ignore-scripts`, then `npx --no-install wxt prepare`. No dependency + gets to run code at install time (SonarCloud S6505); our own `postinstall` is + the one script we need, so it runs explicitly, from the local binary, never + fetched. A local `npm ci` still runs `postinstall` normally. +- Reusable workflows get **named** secrets, never `secrets: inherit`: they are + pinned to the ops repo's moving `main`, so each one receives only what it + declares. -```yaml -name: CI +### 2.1 `ci.yml` — every push/PR to `main` -on: - push: { branches: [main] } - pull_request: +Three jobs. The two whose names branch protection requires (§5) are +`Quality gates` and `Build + package / build`. -permissions: - contents: read - -concurrency: - group: ci-${{ github.ref }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} - -jobs: - quality: - name: Quality gates - runs-on: ubuntu-latest - timeout-minutes: 15 - permissions: - contents: read - steps: - - uses: actions/checkout@v7 - - uses: actions/setup-node@v7 - with: { node-version: '24', cache: npm } - - run: npm ci - - run: npm run lint # biome check . - - run: npm run check # svelte-check + tsc --noEmit - - run: npm run knip - - run: npm run coverage # vitest --coverage, thresholds per 11 §1 - - run: npm run guard # canonical grep gate, 08_MV3 §3 - - run: npm run build - - run: npm run check:manifest # the BUILT artifact, not just the config - - build: - name: Build + package - needs: quality - uses: poli0981/.github/.github/workflows/reusable-chrome-extension.yml@main - permissions: - contents: write # see the warning below — `read` fails at startup - with: - package-manager: 'npm' # 01 §6 commits package-lock.json - node-version: '24' - build-command: 'npm run build' - source-dir: '.output/chrome-mv3' # WXT emits the manifest here - release: false -``` - -All four `with:` values are required. Omitting `package-manager` defaults it to -`'none'`, which skips install/build entirely and then fails on -`test -f ./manifest.json` — a file WXT never writes to the repo root. +- **`quality` — "Quality gates".** Local, because the ops reusable runs no + quality gates at all (§1). In order: `lint`, `check` (svelte-check on the + TS 6 API, then the TS 7 `tsc`), `knip`, `coverage` (`11 §1` thresholds), + `guard` (`08 §3`), `npm audit --omit=dev --audit-level=low` (the + zero-runtime-dependencies claim, `09 T5`), `build`, `check:manifest`. The last + two exist because the unit test over `wxt.config.ts` proves what we *asked* + for and only the built manifest proves what WXT *emitted* — a dev build of + the same config carries `tabs`/`scripting`/`host_permissions`. +- **`windows` — "Windows smoke (guard + unit tests)".** Not required. The owner + develops on Windows, and the failures that only happen there — drive letters + and percent-encoding in script paths, CRLF checkouts — had no CI coverage. +- **`build` — "Build + package".** Delegates packaging to + `reusable-chrome-extension.yml` with `package-manager: 'npm'`, + `node-version: '26'`, `build-command: 'npm run build'`, + `source-dir: '.output/chrome-mv3'`, `release: false`. All four are required in + practice: leaving `package-manager` at its `'none'` default skips install and + build, then fails on `test -f ./manifest.json`, a file WXT never writes to the + repo root. ⚠️ **`contents: write` on the `build` job is not a mistake.** The reusable declares two mutually exclusive jobs — `build` (`contents: read`, @@ -105,210 +88,123 @@ likely failed because of a workflow file issue" in the UI. Verified 2026-07-26 on the first real run of this workflow. `npm run guard` runs the same script locally and in CI, so the gate cannot -drift between the two (`10 §3`). It is the single canonical pattern defined in -`08_MV3_COMPLIANCE.md §3`; do not restate the pattern here or anywhere else. +drift between the two (`10 §3`). -### 2.2 `.github/workflows/codeql.yml` +### 2.2 `codeql.yml` -Use the current reusable (`reusable-codeql.yml`, CodeQL Action v4). Its input is -`languages` — a **JSON array encoded as a string**, not the singular `language` -of the older `codeql.yml`. - -```yaml -name: CodeQL - -on: - push: { branches: [main] } - pull_request: { branches: [main] } - schedule: - - cron: '0 14 * * 1' # weekly, Monday - -permissions: - security-events: write - actions: read - contents: read - packages: read - -jobs: - analyze: - uses: poli0981/.github/.github/workflows/reusable-codeql.yml@main - permissions: - security-events: write - actions: read - contents: read - packages: read - with: - languages: '["javascript-typescript"]' -``` +Calls the current reusable, `reusable-codeql.yml` (CodeQL Action v4). Its input +is `languages` — a **JSON array encoded as a string** +(`'["javascript-typescript"]'`), not the singular `language` of the older +`codeql.yml`. Weekly schedule plus push/PR to `main`; the permission block +(`security-events: write`, `actions: read`, `contents: read`, `packages: read`) +is repeated on the job because reusable workflows do not inherit it. ⚠️ **Prerequisite:** repo Settings → Advanced Security → CodeQL **"Default setup" must be DISABLED**, or this advanced-setup workflow is rejected at SARIF upload time. -### 2.3 `.github/workflows/release.yml` — on tag `v*` +### 2.3 `release.yml` — on tag `v*` Standalone, **not** the ops reusable: the reusable's `release` job only does -`gh release create --generate-notes`. It produces no `SHA256SUMS.txt` -(required by `09 §5`), performs no store submission, and exposes no `outputs:`, -so a caller cannot reference the zip it built. +`gh release create --generate-notes`. It produces no `SHA256SUMS.txt` (required +by `09 §5`), performs no store submission, and exposes no `outputs:`, so a +caller cannot reference the zip it built. -```yaml -name: Release +Four jobs, least privilege first (split 2026-10-28): -on: - push: - tags: ['v*'] +| Job | Token | Does | +|---|---|---| +| `build` "Gate + package" | `contents: read` | install, **every CI gate again** (a tag skips the branch triggers, and must never ship what a PR would have blocked), `zip`, `check:manifest`, the tag ↔ manifest version check, `SHA256SUMS.txt`; uploads both files as the artifact `release-` | +| `publish` "GitHub Release" | `contents: write` | downloads the artifact, `sha256sum -c` it, creates the Release with `--verify-tag` (or re-uploads to an existing one). Installs nothing and runs no repository code — the only job that ever holds a write token | +| `store` "Publish to Chrome Web Store" | `contents: read` | only when the repo variable `CWS_AUTOPUBLISH` is `'true'`: `./node_modules/.bin/wxt submit` with the Release asset — the local binary, never `npx wxt`, which may fetch an unpinned package into an environment holding the four `CHROME_*` secrets (SonarCloud S6505/S8543) | +| `announce` | `contents: read` | Discord, only when `DISCORD_ANNOUNCE` is `'true'` | -permissions: - contents: read - -jobs: - release: - runs-on: ubuntu-latest - timeout-minutes: 20 - permissions: - contents: write # create the GitHub Release - steps: - - uses: actions/checkout@v7 - - uses: actions/setup-node@v7 - with: { node-version: '24', cache: npm } - - run: npm ci - - # Same gates as CI — a tag must never ship what a PR would have blocked. - - run: npm run lint - - run: npm run check - - run: npm run knip - - run: npm run coverage - - run: npm run guard - - - run: npm run zip # wxt zip → .output/--chrome.zip - - run: npm run check:manifest # gate the artifact, not the config it came from - - - name: Verify tag matches manifest version - run: | - set -euo pipefail - MANIFEST_VERSION=$(jq -r '.version' .output/chrome-mv3/manifest.json) - TAG_VERSION="${GITHUB_REF_NAME#v}" - test "$MANIFEST_VERSION" = "$TAG_VERSION" \ - || { echo "::error::tag $TAG_VERSION != manifest $MANIFEST_VERSION"; exit 1; } - - - name: SHA256SUMS - working-directory: .output - run: sha256sum *-chrome.zip > SHA256SUMS.txt - - - name: GitHub Release # idempotent — see below - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - set -euo pipefail - if gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then - gh release upload "$GITHUB_REF_NAME" \ - .output/*-chrome.zip .output/SHA256SUMS.txt --clobber - else - gh release create "$GITHUB_REF_NAME" \ - .output/*-chrome.zip .output/SHA256SUMS.txt --generate-notes - fi - - - name: Publish to Chrome Web Store - if: vars.CWS_AUTOPUBLISH == 'true' - env: - CHROME_EXTENSION_ID: ${{ secrets.CHROME_EXTENSION_ID }} - CHROME_CLIENT_ID: ${{ secrets.CHROME_CLIENT_ID }} - CHROME_CLIENT_SECRET: ${{ secrets.CHROME_CLIENT_SECRET }} - CHROME_REFRESH_TOKEN: ${{ secrets.CHROME_REFRESH_TOKEN }} - run: npx wxt submit --chrome-zip .output/*-chrome.zip - - announce: - needs: release - if: vars.DISCORD_ANNOUNCE == 'true' # see below — NOT continue-on-error - uses: poli0981/.github/.github/workflows/announce-release.yml@main - permissions: - contents: read - with: - tag_override: ${{ github.ref_name }} - secrets: inherit -``` +Before the split, one job ran `npm ci` — every dependency's install script plus +our own tests — while holding `contents: write`, with the token also left in +`.git/config` by checkout. **The Release step is idempotent deliberately.** `gh release create` fails outright when a Release for the tag already exists, so any failure *after* it — -realistically the CWS publish step, once `CWS_AUTOPUBLISH` is on — stranded the -tag: a re-run could not get past that line, and recovery meant deleting the -Release and the tag by hand. `docs/13 §7` documents the manual escape; this -removes the need for it in the common case. +realistically the store job, once `CWS_AUTOPUBLISH` is on — stranded the tag: a +re-run could not get past that line, and recovery meant deleting the Release +and the tag by hand. `docs/13 §7` documents the manual escape; this removes the +need for it in the common case. The announcement is gated because the reusable exits 1 on "No webhooks -configured" when both Discord secrets are unset — which §5 lists as optional. On -the real v1.0.0 run the Release, the zip and `SHA256SUMS.txt` all published -correctly and the run still showed red. A red run on a good release trains you -to ignore the colour, so the notification must not be able to fail the release. +configured". On the real v1.0.0 run the Release, the zip and `SHA256SUMS.txt` +all published correctly and the run still showed red. A red run on a good +release trains you to ignore the colour, so the notification must not be able +to fail the release. ⚠️ **It is gated with `if:` on a repo VARIABLE, not with `continue-on-error`.** -GitHub **rejects** `continue-on-error` on a job that calls a reusable workflow — -`Property continue-on-error is not allowed` — and a rejected file does not fail -one job, it makes the whole run a `startup_failure` with zero jobs and no log. -That is the same silent shape as the `contents: write` mistake in §2.1, and it -sat undetected in this repo from `5f4c6e7` until 2026-08-03 precisely because -that commit landed *after* the `v1.0.0` tag and no tag was pushed in between — -the first v1.0.1 tag would have been its first execution. +GitHub **rejects** `continue-on-error` on a job that calls a reusable workflow +(`Property continue-on-error is not allowed`), and a rejected file does not +fail one job — the whole run is a `startup_failure` with zero jobs and no log. +That sat undetected from `5f4c6e7` until 2026-08-03 because the commit landed +after the `v1.0.0` tag and no tag was pushed in between. A variable and not a +secret: secrets cannot be referenced in a job-level `if:`. -A **variable** and not a secret: secrets cannot be referenced in a job-level -`if:`. `vars.DISCORD_ANNOUNCE` defaults to unset, so the announcement is skipped -and the release stays green until the owner opts in — the same idiom as -`CWS_AUTOPUBLISH`. Set the variable only once the webhook secrets exist. +⚠️ **The webhook secrets are mapped by name.** This repo stores +`RELEASES_WEBHOOK` and `REPO_WEBHOOK`; the reusable reads +`DISCORD_RELEASES_WEBHOOK` and `DISCORD_REPO_WEBHOOK`. Under the old +`secrets: inherit` the reusable received neither, so the day `DISCORD_ANNOUNCE` +was set the job would have failed on "No webhooks configured". It now passes +each one explicitly under the name the reusable reads — found 2026-10-28 by +comparing the repo's secret list with the reusable's `workflow_call` block. -`tag_override` is **required here**, and for the same reason the announcement -is a job rather than a caller. The reusable resolves -`TAG="${INPUT_TAG:-$EVENT_TAG}"` with `EVENT_TAG = github.event.release.tag_name` -— empty under `on: push: tags` — so omitting it makes the job exit 1 on -"No release tag available" and the announcement never fires for any release. +`tag_override` is **required**: the reusable resolves +`TAG="${INPUT_TAG:-$EVENT_TAG}"` with `EVENT_TAG = github.event.release.tag_name`, +which is empty under `on: push: tags`, so without it the job exits 1 on "No +release tag available". The announcement is a **job inside this workflow**, not +a separate `on: release: [published]` caller, because a Release created by +`gh release create` under the default `GITHUB_TOKEN` emits no event that starts +new workflow runs. -The announcement is a **job inside this workflow**, not a separate -`on: release: [published]` caller. A Release created by `gh release create` -under the default `GITHUB_TOKEN` does not emit an event that starts new -workflow runs, so an event-driven caller would silently never fire. +### 2.4 `notify-ci-failure.yml` -### 2.4 `.github/workflows/notify-ci-failure.yml` +Runs on `workflow_run` of CI, gated on +`conclusion == 'failure' && vars.DISCORD_CI_NOTIFY == 'true'`, and passes the +one secret the reusable declares (`DISCORD_CI_WEBHOOK`) by name. The reusable +declares that secret `required: true` and GitHub validates it before any of the +reusable's own logic, so without the gate this caller failed on **every** CI +completion, success included. `DISCORD_CI_WEBHOOK` exists (set 2026-07-26); the +variable is still unset, so notifications stay off until the owner opts in. A +notification must never be able to change the colour of the thing it reports +on. -```yaml -name: Notify CI failure +### 2.5 `sonarcloud.yml` — SonarCloud CI analysis -on: - workflow_run: - workflows: ['CI'] - types: [completed] +Added 2026-10-28, replacing SonarCloud's Automatic Analysis so the project gets +**coverage** and a scan of exactly what CI builds. Project +`poli0981_bookmarkmagic`, organisation `poli0981`; settings live in +`sonar-project.properties`. -permissions: - contents: read - actions: read +- **A separate workflow, not a job in `ci.yml`:** a Sonar outage or a + quality-gate opinion must never turn CI red. The verdict reaches PRs as the + SonarCloud GitHub App's own check. It is not a required check. +- Steps: full-history checkout (`fetch-depth: 0`, for new-code detection), the + common install, `npm run coverage` (which writes `coverage/lcov.info`), then the + scan with `-Dsonar.projectVersion=`, so "new code" means + "since the last release". +- The scan action is **pinned to a commit** (`v8.3.0`): it is the step that + holds `SONAR_TOKEN`, and the token is scoped to the two steps that need it. + Dependabot and fork PRs get no repository secrets, so the scan is skipped with + a notice instead of failing. +- Coverage: `vitest.config.ts` measures every `src/**/*.ts` module and reports + `text` + `lcov`; the CI *gate* is still the core-only glob threshold of + `11 §1`. `sonar.coverage.exclusions` drops components, entrypoints and + scripts — the same split as `11 §1`, where those are covered by the manual + pass and the script tests. The three locale files are excluded from + duplication detection: they are parallel by design. +- No `sonar.qualitygate.wait`: an unreviewed Security Hotspot can only be + cleared by a person in the Sonar UI, and a CI step that waits on a human is a + step that is red for a reason nobody can fix from the repo. -jobs: - notify: - if: github.event.workflow_run.conclusion == 'failure' && vars.DISCORD_CI_NOTIFY == 'true' - uses: poli0981/.github/.github/workflows/notify-ci-failure.yml@main - permissions: - contents: read - actions: read - secrets: inherit -``` +⚠️ **Prerequisite:** Automatic Analysis must be **off** in the SonarCloud project +(Administration → Analysis Method). With it on, the scanner refuses to run. -The reusable filters to `conclusion == 'failure'` on the default branch -internally, so the caller's `if:` is redundant *for behaviour* — but not for -cost, and not for the failure below. - -⚠️ **The reusable declares `DISCORD_CI_WEBHOOK` as `required: true`**, which -GitHub validates before any of the reusable's own logic runs. With the secret -unset (`00 §10.6`), the caller therefore failed on **every** CI completion — -success or failure — from the first push after this file landed. - -Both halves of the condition earn their place: the conclusion check stops it -running on green CI at all, and `vars.DISCORD_CI_NOTIFY` keeps it off entirely -until the secret actually exists. **Not `continue-on-error`** — see §2.3: GitHub -rejects that keyword on a reusable-workflow caller and invalidates the file. - -Same reasoning as §2.3's announce gate, learned the same way: a notification -must never be able to change the colour of the thing it is reporting on, because -a run that is red for a reason nobody acts on teaches everyone to stop reading -the colour. +Snyk is connected only as a GitHub App (the `security/snyk (poli0981)` PR +check); there is no `SNYK_TOKEN` and no Snyk step in any workflow. ## 3. Chrome Web Store publishing automation @@ -371,17 +267,24 @@ means "unknown", not "not done". - [ ] ⚠️ Actions secrets: the four `CHROME_*` values (after `wxt submit init`). `CHROME_EXTENSION_ID` is already known — it is the published item id in `00 §9`. Required before `CWS_AUTOPUBLISH` can be flipped for v1.1. -- [ ] ⚠️ Actions secrets for Discord notifications. **`DISCORD_CI_WEBHOOK` is - not optional in practice** — see §2.4. The rest are: - `DISCORD_RELEASES_WEBHOOK`, `DISCORD_REPO_WEBHOOK`, `DISCORD_PING_ROLE_ID`. +- [x] Actions secrets for Discord notifications — **present as of 2026-10-28:** + `DISCORD_CI_WEBHOOK`, `RELEASES_WEBHOOK`, `REPO_WEBHOOK` (the last two under + names the reusable does not read; `release.yml` maps them, §2.3). + `DISCORD_PING_ROLE_ID` is optional and unset. +- [x] `SONAR_TOKEN` — set 2026-10-28, used only by `sonarcloud.yml` (§2.5). +- [ ] ⚠️ SonarCloud **Automatic Analysis OFF** (SonarCloud → bookmarkmagic → + Administration → Analysis Method). Required for §2.5; with it on, the CI + scan errors out. The owner agreed to switch it off on 2026-10-28. +- [x] Private vulnerability reporting **enabled** (verified 2026-10-28 via the + API) — `SECURITY.md` and the issue chooser send reporters there first. - [ ] ⚠️ Repo variable `CWS_AUTOPUBLISH=false` initially. Note that when the variable does not exist the expression is simply false, so "not configured" and "configured off" are indistinguishable from a run's output. -- [ ] ⚠️ Repo variables `DISCORD_ANNOUNCE` and `DISCORD_CI_NOTIFY`. Leave both - unset until the matching webhook secrets exist — the reusables declare - those secrets required, so calling them without one fails the job, and a - reusable-workflow caller cannot use `continue-on-error` to absorb it - (§2.3). Unset means skipped, which is the safe default. +- [ ] ⚠️ Repo variables `DISCORD_ANNOUNCE` and `DISCORD_CI_NOTIFY` — both still + unset (2026-10-28), so no notification fires. The webhook secrets now + exist, so either can be flipped to `true` whenever the owner wants the + posts. Unset means skipped; a reusable-workflow caller cannot use + `continue-on-error` to absorb a failure (§2.3). - [x] Dependabot: npm weekly, grouped dev minor+patch, `github-actions` too — `.github/dependabot.yml`. Both ecosystems have a 7-day `cooldown` (matching `.npmrc` `min-release-age=7`, `09 §3.1`); WXT is excluded from diff --git a/docs/15_ROADMAP.md b/docs/15_ROADMAP.md index 015862e..ef2433b 100644 --- a/docs/15_ROADMAP.md +++ b/docs/15_ROADMAP.md @@ -216,3 +216,7 @@ independently of the package (`13 §5`), though the copy should still go through | 2026-10-28 | **The `overrides` block is deleted.** All six pinned packages had left the tree (WXT 0.21 dropped `web-ext-run`; Vite 8 uses rolldown, not esbuild). `npm audit` 13 → 3 low, all one unfixable `deepmerge` advisory inside vite-plugin-svelte, accepted and documented; `--omit=dev` stays 0 | 09 §3.1 | | 2026-10-28 | **WXT 0.21.3 → 0.21.4 accepted after the built-manifest diff** the 2026-08-03 rule requires: identical key set and values (only the deliberate `minimum_chrome_version`), identical file inventory, chunk sizes within ±1.1 kB from the Svelte 5.57 runtime. Vitest 4 → 5 and jsdom 30.0 → 30.1 passed the whole suite unchanged, the `dom-environment` canary first | 01 §2 | | 2026-10-28 | **Biome ignores Markdown and YAML.** 2.6 began formatting both and flagged 35 hand-laid docs and workflows; formatting prose is not what the gate is for | 10 §3 | +| 2026-10-28 | **SonarCloud moves from Automatic Analysis to a CI scan** (`sonarcloud.yml`, `sonar-project.properties`): coverage at last, and a scan of what CI actually builds. Its own workflow so it never colours CI; the scan action pinned to a commit because it holds `SONAR_TOKEN`; skipped, not failed, where secrets are absent | 12 §2.5 | +| 2026-10-28 | **Coverage measures all of `src/**/*.ts`, but the gate stays core-only** via a glob threshold — verified to still fail a run below `src/lib/core/**`'s numbers, so widening what is measured cannot loosen what is enforced | 11 §1, 12 §2.5 | +| 2026-10-28 | **CI installs with `--ignore-scripts` and runs `wxt prepare` explicitly; reusables get named secrets; checkouts drop credentials; the release's write token moves to a job that installs nothing.** The old release job ran every dependency's install script and our tests while holding `contents: write`. The announce job's `secrets: inherit` also passed nothing it could use — this repo's webhook secrets have different names than the reusable reads | 12 §2 | +| 2026-10-28 | **docs/12 stops copying workflow YAML.** The copies drifted three times; with docs-win, a stale copy invites reverting a pinned action or deleting a gate. The chapter now records why each job exists and the traps already hit; the files are the ground truth about themselves | 12 §2 | diff --git a/sonar-project.properties b/sonar-project.properties new file mode 100644 index 0000000..25f9f69 --- /dev/null +++ b/sonar-project.properties @@ -0,0 +1,28 @@ +# SonarCloud — CI-based analysis (docs/12 §2.5). Read by +# .github/workflows/sonarcloud.yml; Automatic Analysis must stay OFF in the +# SonarCloud project (Administration → Analysis Method), or the scan errors out. +sonar.projectKey=poli0981_bookmarkmagic +sonar.organization=poli0981 +sonar.projectName=BookmarkMagic +sonar.sourceEncoding=UTF-8 + +# What ships, plus the repo tooling that guards it. +sonar.sources=src,scripts +# Icons and the _locales message catalogues are data, not code. +sonar.exclusions=src/public/** + +sonar.tests=tests +sonar.test.inclusions=tests/**/*.ts +# Fixtures are byte-exact samples of what browsers emit — malformed on purpose +# (a no-doctype HTML file is a test case, not a bug), never something to "fix". +sonar.test.exclusions=tests/fixtures/** + +# Coverage scope mirrors docs/11 §1: components, entrypoints and repo scripts +# are verified by the manual QA pass and their own script tests, not by line +# coverage. Everything else in src/ is unit-tested and counted. +sonar.javascript.lcov.reportPaths=coverage/lcov.info +sonar.coverage.exclusions=src/entrypoints/**,src/lib/components/**,**/*.svelte,scripts/** + +# The three locale dictionaries are parallel by design (en is the schema, vi/ja +# `satisfies Dict`); their "duplication" is the i18n contract working. +sonar.cpd.exclusions=src/lib/i18n/locales/** diff --git a/src/lib/core/serialize/markdown.ts b/src/lib/core/serialize/markdown.ts index 0b69626..1a6a7c0 100644 --- a/src/lib/core/serialize/markdown.ts +++ b/src/lib/core/serialize/markdown.ts @@ -77,6 +77,20 @@ function writeFlat(roots: readonly BookmarkNode[], out: string[]): void { } } +/** + * Drop trailing line feeds in one backward pass. + * + * Replaces `.replace(/\n+$/, '')`, which backtracks: for every newline in a + * long run that is NOT at the end (a title holding thousands of them, say), the + * engine re-scans the rest of the run before failing at `$` — quadratic in the + * run length (SonarCloud S8786). + */ +function trimTrailingNewlines(text: string): string { + let end = text.length; + while (end > 0 && text.charCodeAt(end - 1) === 0x0a) end--; + return text.slice(0, end); +} + /** Serialize a tree to Markdown. */ export function serializeMarkdown( roots: readonly BookmarkNode[], @@ -85,5 +99,5 @@ export function serializeMarkdown( const out: string[] = [`# Bookmarks — ${options.date}`, '']; if ((options.style ?? 'nested') === 'flat') writeFlat(roots, out); else writeNested(roots, 0, out); - return `${out.join('\n').replace(/\n+$/, '')}\n`; + return `${trimTrailingNewlines(out.join('\n'))}\n`; } diff --git a/tests/unit/core/serialize/markdown.test.ts b/tests/unit/core/serialize/markdown.test.ts index 720c4d8..f4ac3c2 100644 --- a/tests/unit/core/serialize/markdown.test.ts +++ b/tests/unit/core/serialize/markdown.test.ts @@ -82,4 +82,21 @@ describe('markdown escaping', () => { }); expect(md).toContain('- [\\[x\\]\\(y\\)]()'); }); + + it('ends with exactly one newline, however the tree ends', () => { + for (const style of ['nested', 'flat'] as const) { + expect(serializeMarkdown([], { date: 'd', style })).toBe('# Bookmarks — d\n'); + const md = serializeMarkdown([{ title: 'Empty', children: [] }], { date: 'd', style }); + expect(md.endsWith('\n')).toBe(true); + expect(md.endsWith('\n\n')).toBe(false); + } + }); + + it('keeps a long newline run that is not at the end (no backtracking trim)', () => { + // The old `/\n+$/` re-scanned this run once per newline before failing. + const run = '\n'.repeat(20_000); + const md = serializeMarkdown([{ title: `a${run}b`, children: [] }], { date: 'd' }); + expect(md).toContain(`- **a${run}b**`); + expect(md.endsWith('**\n')).toBe(true); + }); }); diff --git a/vitest.config.ts b/vitest.config.ts index 6336477..583cdaa 100644 --- a/vitest.config.ts +++ b/vitest.config.ts @@ -18,8 +18,18 @@ export default defineConfig({ include: ['tests/unit/**/*.test.ts'], coverage: { provider: 'v8', - include: ['src/lib/core/**'], - thresholds: { lines: 90, functions: 90, branches: 85 }, + // Every TypeScript module is MEASURED, so SonarCloud sees real numbers + // for the browser layer, stores and edit logic too (docs/12 §2.5). + // Components and entrypoints are excluded on Sonar's side, matching the + // docs/11 §1 split: they are covered by the manual QA pass. + include: ['src/**/*.ts'], + reporter: ['text', 'lcov'], + // Only core is GATED, and with a glob threshold rather than a global one, + // so widening `include` cannot loosen or tighten the CI gate: the numbers + // below apply to src/lib/core/** alone, exactly as before (docs/11 §1). + thresholds: { + 'src/lib/core/**': { lines: 90, functions: 90, branches: 85 }, + }, }, }, });