Compare commits

...
Author SHA1 Message Date
poli0981andClaude Opus 5.5 098beeabff fix(qodana): act on the first run, and read the report where it really is
The first scan found 27 issues and no defect:
- two regular expressions that could be simpler, fixed: the sanitizer's
  [\p{Extended_Pictographic}] class and wxt.config.ts's split(/[/]/). A third
  is in src/ and waits for the 1.3.0 change, so this branch still builds
  byte-for-byte what v1.2.1 shipped;
- 24 that contradict a rule of this repository, switched off in
  qodana.yaml with the reason beside each: JSDoc completeness (doc comments
  here are prose, docs/10 §6), bitwise operators in the PNG CRC-32 of
  gen-icons.mjs, and the deliberately doubled dark palette in tokens.css.

`publish` failed: the qodana-report artifact holds a zip whose entries have
absolute names, so a glob for the SARIF found nothing. It now extracts the
one entry /qodana.sarif.json by name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 20:56:19 +07:00
poli0981andClaude Opus 5.5 6650453521 docs: GO for Firefox and Edge as v1.3; the roadmap under maintenance mode
Recorded now rather than with the port, because the maintenance
announcement names it (docs/15, docs/00 §7). Settled with the owner: gecko
id bookmarkmagic@poli0981.dev, desktop only (Firefox for Android has no
bookmarks API), MV3 everywhere, and Firefox separators shown, protected and
warned about rather than stored in a file format.

The roadmap is pruned to what MAINTENANCE.md allows: scheduled snapshots
need the alarms permission and leave it; the permission rule joins the never
list; the fflate zip export, the duplicate auto-merge assistant and
bookmarklet notes are not planned; the old v1.3 "resilience" becomes v1.4.

MAINTENANCE.md no longer lists "a dependency advisory" as a release trigger
on its own: with no runtime dependencies, an advisory against the build
tools needs a release only if it changed what ships.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 20:49:28 +07:00
poli0981andClaude Opus 5.5 1b79712d0f ci: Qodana for JS, and a harder triage workflow
qodana.yml runs qodana-js (Ultimate, QODANA_TOKEN) on pushes to main, pull
requests, a weekly schedule and by hand, in two jobs (docs/12 §2.7):

- `scan` installs the dev dependencies with scripts off — qodana-js resolves
  types through them — and holds only a read-only GITHUB_TOKEN; PR comments
  and annotations are off, the SARIF report is kept as an artifact;
- `publish` installs nothing and uploads that SARIF to code scanning
  (category qodana), so the findings sit beside CodeQL's.

The action is pinned to the commit of v2026.2.2 (the newest tag is younger
than the 7-day cooldown). Sharing a runner with dependency code is recorded
as an exception to the Sonar rule: the token can only upload reports.

triage.yml, from review of the first draft:
- comment and close first, label last — the label is what a re-run reads as
  done, so it must not exist before the work;
- an `enhancement` issue with no answer to the form is closed only when the
  owner added the label; otherwise it goes to needs-triage;
- checkout and setup-node pinned to commits, no cache: this workflow runs
  them with a write token on events anyone can trigger.

README gains the Qodana badge.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 20:49:26 +07:00
poli0981andClaude Opus 5.5 b384711978 feat(repo): maintenance mode, with triage that closes out-of-policy requests
MAINTENANCE.md is the policy: dependency updates on a schedule, high and
critical advisories fixed as soon as a fix exists, major platform upgrades,
bug/UI/UX/accessibility/translation fixes, and features only when they are
on docs/15's roadmap or genuinely needed.

- The feature form asks one required question — on the roadmap, needed for
  a fix, or something new — and links the policy and Discussions › Ideas.
- scripts/triage.mjs decides what happens, as a pure, unit-tested function;
  .github/workflows/triage.yml carries it out with `gh` alone. Something new
  is labelled maintenance-mode, commented and closed as not planned; the two
  in-policy answers get needs-triage; an outside `feat…` pull request is
  closed the same way. Owner, members, collaborators, bots and `roadmap` are
  exempt.
- pull_request_target checks out the base branch only, runs nothing from the
  pull request, and never interpolates a title or body into the shell.
- README gains a status badge and a "Project status" section; CONTRIBUTING,
  the PR template and the issue chooser say what is accepted.
- docs: 00 status, 11 inventory, 12 §2.6 and §5 (labels), 13 §6, 15 (a
  pointer to the policy, not a copy, and the decision-log rows); CLAUDE.md
  Phase 10.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 20:42:13 +07:00
poli0981andClaude Opus 5.5 a9cbc772bf build: a licence gate over every package in the lockfile
scripts/check-licenses.mjs reads package-lock.json, where npm records each
package's own `license` field, and fails on anything outside two lists
(docs/09 §3.2):

- what the build compiles into the extension (svelte, clsx, wxt,
  @wxt-dev/browser) must be permissive and GPL-3.0-compatible;
- everything else is build tooling that never ships, so file-level copyleft
  (MPL-2.0, lightningcss) is also accepted; AGPL, source-available terms and
  missing or custom licences are not.

SPDX expressions are evaluated, nothing is installed or fetched, and the
tests call the functions directly rather than spawning the script. It runs
in `verify`, CI's quality job and the release build.

The shipped list moves out of wxt.config.ts into
scripts/credited-packages.mjs, so the build gate, the notices test and the
licence gate read one list instead of two copies and a regex.

legal/THIRD_PARTY_NOTICES.md said the tooling was all MIT/Apache-2.0/ISC; the
lockfile also has BSD, 0BSD, MIT-0, BlueOak, CC0 and MPL-2.0. Corrected — a
description of tooling that never ships, so no LEGAL_VERSION bump (14 §3.1).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 20:36:56 +07:00
poli0981andClaude Opus 5.5 3cc91272d0 chore(deps): finish the Dependabot bumps and record the picomatch advisory
Dependabot's #39-#41 moved the packages and left the rest behind, as
docs/15 (2026-11-10) says it always does:

- biome.json and docs/10 name the schema of Biome 2.6.6;
- docs/01 records Biome 2.6.6, knip 6.44.2 and jsdom ^31.0;
- docs/12 §2.5 names the scan action's new pin, v8.4.1;
- docs/11 §6 gains a jsdom 31 column for the 100k parse (median of three
  runs, 2 484 ms) instead of overwriting the jsdom 29 figure.

docs/09 §3.1: npm audit now reports 14 high findings with one root cause,
picomatch GHSA-fc5q-39xc-vjpf, for which no fixed version exists. It is the
toolchain's glob engine, matching patterns this repository writes, and
never ships (--omit=dev stays 0). The deepmerge row goes: GitHub withdrew
that advisory on 2026-11-16.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 20:36:43 +07:00
35 changed files with 1657 additions and 83 deletions

No files matched your search

+7
View File
@@ -6,6 +6,13 @@
blank_issues_enabled: false
contact_links:
- name: An idea, to talk through first
url: https://github.com/poli0981/bookmarkmagic/discussions/categories/ideas
about: >-
BookmarkMagic is in maintenance mode (MAINTENANCE.md). A new idea is
welcome here, where it can be discussed without an issue that has to be
accepted or refused.
- name: Security vulnerability
url: https://github.com/poli0981/bookmarkmagic/security/advisories/new
about: Report privately, never as a public issue. See SECURITY.md.
+41 -11
View File
@@ -1,20 +1,50 @@
name: Suggest a feature
description: An idea for something BookmarkMagic should do.
description: BookmarkMagic is in maintenance mode — read what that means before asking for something new.
title: '[feature] '
labels: [enhancement]
body:
- type: markdown
attributes:
value: |
Before writing: this project has a short, deliberate
[never list](https://github.com/poli0981/bookmarkmagic/blob/main/docs/15_ROADMAP.md).
Cloud sync, accounts, analytics of any kind, and anything that would
require new browser permissions are out of scope permanently — not
because they are hard, but because "offline, two permissions, no
network" is the entire point of the extension.
**BookmarkMagic is in maintenance mode**
([MAINTENANCE.md](https://github.com/poli0981/bookmarkmagic/blob/main/MAINTENANCE.md)).
A feature is added only when it is already on the
[roadmap](https://github.com/poli0981/bookmarkmagic/blob/main/docs/15_ROADMAP.md),
or when it is genuinely needed to fix a defect or remove a barrier.
Everything else is genuinely open. The roadmap in that same file lists
what is already planned.
**The first question below decides what happens to this issue.** A
request for something new is closed automatically and labelled
`maintenance-mode` — not deleted, and read; the
[Ideas discussions](https://github.com/poli0981/bookmarkmagic/discussions/categories/ideas)
are the place to talk one through. The other two answers keep the issue
open for the maintainer.
Out of scope permanently, whatever the mode: cloud sync, accounts,
analytics of any kind, and anything that would need a new browser
permission. "Offline, two permissions, no network" is the point of the
extension.
- type: dropdown
id: kind
attributes:
label: Which kind of change is this?
description: See MAINTENANCE.md. Please answer honestly — a mislabelled request is closed by hand.
options:
- Something already on the roadmap (docs/15)
- Needed to fix a bug, a UI/UX defect or an accessibility barrier
- Something new — not on the roadmap
validations:
required: true
- type: input
id: reference
attributes:
label: Which roadmap item, or which defect?
description: >-
The line in docs/15, or the issue or behaviour it fixes. Leave empty
for something new.
validations:
required: false
- type: textarea
id: problem
@@ -52,5 +82,5 @@ body:
permission, and does not involve a server, an account, or sending
data anywhere.
required: true
- label: I checked the roadmap and the never list.
required: false
- label: I read MAINTENANCE.md and checked the roadmap and the never list.
required: true
+7
View File
@@ -7,6 +7,13 @@ a translation fix does not need the parser section, and vice versa.
<!-- What changes, and what problem it solves. Link the issue if there is one. -->
**Kind of change** ([MAINTENANCE.md](https://github.com/poli0981/bookmarkmagic/blob/main/MAINTENANCE.md) — the project
is in maintenance mode): <!-- bug fix · UI/UX fix · accessibility · translation
· dependency or security update · roadmap item (which?) -->
A pull request titled `feat…` from outside the project is closed automatically
unless its feature is on the roadmap — open a feature request first.
## Checklist
- [ ] `npm run verify` is green. (Release-bearing? `npm run verify:full` —
+3
View File
@@ -45,6 +45,9 @@ jobs:
- run: npm run knip
- run: npm run coverage # vitest --coverage, thresholds per docs/11 §1
- run: npm run guard # the zero-network / no-raw-HTML gate, docs/08 §3
# Every licence in the lockfile, shipped packages held to the stricter
# list (docs/09 §3.2). Reads package-lock.json only — no network.
- run: npm run check:licenses
# 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
+126
View File
@@ -0,0 +1,126 @@
# Qodana — docs/12 §2.7.
#
# A separate workflow, like SonarCloud's: a Qodana outage or opinion must never
# change the colour of CI, which is what branch protection reads. Not a
# required check.
#
# Two jobs, least privilege first:
# - `scan` runs the analysis. qodana-js resolves types through node_modules,
# so the dev dependencies are installed here (install scripts off) — which
# means they share a runner with QODANA_TOKEN. That is the documented
# exception to docs/12 §2.5's "a token job installs nothing": the token
# only uploads reports to one Qodana Cloud project (rotate it in
# qodana.cloud if a dependency is ever found compromised), and this job's
# GITHUB_TOKEN is read-only — no PR comments, no check runs from here.
# - `publish` installs and runs nothing: it takes the SARIF report from
# `scan` and uploads it to GitHub code scanning, where the findings appear
# beside CodeQL's under "Security and quality" and on pull requests.
name: Qodana
on:
push:
branches: [main]
pull_request:
workflow_dispatch:
schedule:
- cron: '0 15 * * 1' # weekly, Monday — an hour after CodeQL
permissions:
contents: read
concurrency:
group: qodana-${{ github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
jobs:
scan:
name: Qodana for JS
runs-on: ubuntu-latest
timeout-minutes: 30
permissions:
contents: read
outputs:
ran: ${{ steps.token.outputs.present }}
steps:
# Dependabot and fork pull requests get no repository secrets: skip with
# a notice instead of failing, before installing anything.
- name: Check for QODANA_TOKEN
id: token
env:
QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}
run: |
if [ -n "$QODANA_TOKEN" ]; then
echo "present=true" >> "$GITHUB_OUTPUT"
else
echo "present=false" >> "$GITHUB_OUTPUT"
echo "::notice::Qodana skipped — QODANA_TOKEN is not available to this run (Dependabot or fork PR)."
fi
# The default ref — on a pull request, its merge commit — which is the
# commit code scanning attributes an upload from this run to.
- uses: actions/checkout@v7
if: steps.token.outputs.present == 'true'
with:
fetch-depth: 0
persist-credentials: false
- uses: actions/setup-node@v7
if: steps.token.outputs.present == 'true'
with:
node-version-file: .nvmrc
cache: npm
# --ignore-scripts: no dependency runs code at install time (docs/12 §2).
- if: steps.token.outputs.present == 'true'
run: npm ci --ignore-scripts
- if: steps.token.outputs.present == 'true'
run: npx --no-install wxt prepare
- name: Qodana scan
if: steps.token.outputs.present == 'true'
# Pinned to a commit, not the moving `v2026.2` branch the vendor's
# snippet uses: this step holds a token. v2026.2.2 rather than the
# newest tag, which is younger than the repo's 7-day cooldown.
uses: JetBrains/qodana-action@3e8d76ff0e0241618abd808682f426afe84bab3f # v2026.2.2
with:
# Whole project every time — it is small, and a PR that touches only
# docs would otherwise scan nothing.
pr-mode: false
# Both need write permissions this job deliberately does not have;
# `publish` reports the findings through code scanning instead.
post-pr-comment: false
use-annotations: false
# The SARIF report as the `qodana-report` artifact.
upload-result: true
env:
QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}
QODANA_ENDPOINT: 'https://qodana.cloud'
publish:
name: Findings to code scanning
needs: scan
if: needs.scan.outputs.ran == 'true'
runs-on: ubuntu-latest
timeout-minutes: 10
permissions:
contents: read
security-events: write
steps:
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: qodana-report
path: qodana-report
# The artifact holds one zip, qodana-report.zip, whose entries carry
# absolute names ("/qodana.sarif.json"). Take only the report, by its
# exact name, to a fixed path — nothing else is unpacked.
- name: Extract the SARIF report
run: |
set -euo pipefail
unzip -p qodana-report/qodana-report.zip /qodana.sarif.json > qodana.sarif.json
test -s qodana.sarif.json || { echo "::error::no qodana.sarif.json in the report"; exit 1; }
- uses: github/codeql-action/upload-sarif@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3
with:
sarif_file: qodana.sarif.json
category: qodana
+1
View File
@@ -44,6 +44,7 @@ jobs:
- run: npm run knip
- run: npm run coverage
- run: npm run guard
- run: npm run check:licenses
- run: npm audit --omit=dev --audit-level=low
- run: npm run zip # wxt zip → .output/<name>-<version>-chrome.zip
+94
View File
@@ -0,0 +1,94 @@
# Maintenance-mode triage — MAINTENANCE.md, docs/12 §2.6.
#
# scripts/triage.mjs decides (a pure, unit-tested function of the event); this
# file only carries the decision out with the `gh` CLI the runner ships. No
# third-party action holds the write token.
#
# Security, because `pull_request_target` runs with a write token even for a
# pull request from a fork:
# - the checkout is the DEFAULT BRANCH (what pull_request_target checks out
# unless told otherwise) — never the pull request's head, and nothing from
# the pull request is executed;
# - the payload reaches the script as the runner's event FILE; no title, body
# or label is ever interpolated into a shell line with `${{ }}`;
# - the decision the shell reads back is constants: an action from a fixed
# set, an integer, a label from a fixed list, a comment the script wrote.
name: Triage
on:
issues:
types: [opened, labeled]
pull_request_target:
types: [opened]
permissions: {}
# A new issue from the feature form fires `opened` and `labeled` together; one
# at a time per number, and the second re-reads the live state before acting.
concurrency:
group: triage-${{ github.event.issue.number || github.event.pull_request.number }}
cancel-in-progress: false
jobs:
triage:
name: Maintenance-mode triage
runs-on: ubuntu-latest
timeout-minutes: 5
permissions:
contents: read
issues: write
pull-requests: write
steps:
# Pinned to commits, unlike the other workflows: these two run with a
# write token on events anyone can trigger, fork pull requests included.
# No `cache:` on setup-node — a cache written here could be read back by
# a job that trusts it.
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version-file: .nvmrc
- name: Decide
run: node scripts/triage.mjs > "$RUNNER_TEMP/decision.json"
- name: Act
env:
GH_TOKEN: ${{ github.token }}
GH_REPO: ${{ github.repository }}
run: |
set -euo pipefail
decision="$RUNNER_TEMP/decision.json"
action=$(jq -r '.action' "$decision")
echo "triage: $action — $(jq -r '.reason' "$decision")"
[ "$action" = none ] && exit 0
kind=$(jq -r '.kind' "$decision")
number=$(jq -r '.number' "$decision")
label=$(jq -r '.label' "$decision")
case "$kind" in issue|pr) ;; *) echo "::error::unexpected kind"; exit 1 ;; esac
[[ "$number" =~ ^[0-9]+$ ]] || { echo "::error::unexpected number"; exit 1; }
# Re-read the live state: the second of two events for one issue
# finds the first one's label and does nothing.
live=$(gh "$kind" view "$number" --json state,labels \
--jq '[.state] + [.labels[].name] | join(" ")')
case " $live " in
*" maintenance-mode "*|*" needs-triage "*|*" roadmap "*)
echo "already triaged: $live"; exit 0 ;;
esac
case "$live" in OPEN*) ;; *) echo "not open: $live"; exit 0 ;; esac
# Comment and close FIRST, label last: the label is what a re-run
# reads as "done", so it must not exist before the work it stands for.
if [ "$action" = close ]; then
jq -r '.comment' "$decision" > "$RUNNER_TEMP/comment.md"
gh "$kind" comment "$number" --body-file "$RUNNER_TEMP/comment.md"
if [ "$kind" = issue ]; then
gh issue close "$number" --reason "not planned"
else
gh pr close "$number"
fi
fi
gh "$kind" edit "$number" --add-label "$label"
+21 -1
View File
@@ -11,9 +11,14 @@ This file is the entry point; the `docs/` suite is the specification.
> 2026-10-28; v1.1.0 live, confirmed on the listing 2026-11-06; v1.2.0 live,
> confirmed on the listing 2026-11-10; v1.2.1 released on GitHub 2026-11-10,
> ⚠️ not yet submitted).
> Phases 0–9 are complete; the project is in **maintenance**.
> Phases 0–9 are complete; since 2026-11-18 the project is in **maintenance
> mode** — `/MAINTENANCE.md` is the policy (Phase 10 below).
> That changes the rules of the game:
>
> - **New work must fit `/MAINTENANCE.md`**: dependency and security updates,
> major platform upgrades, bug/UI/UX/accessibility/translation fixes, and
> features only when they are on `docs/15`'s roadmap or genuinely needed. A
> feature that is not on the roadmap needs a decision-log row before code.
> - Every change now reaches installed users through a store review. It needs a
> semver bump, a `CHANGELOG.md` entry and an update submission — `13 §1b`.
> - Breaking something is no longer a local cost. The 1.0.0 → 1.0.x **upgrade
@@ -203,6 +208,21 @@ checksum-verified zip). Human-only ⚠️: the `11 §5` pass with the
theme and a screen-reader pass over Alt+↑/↓, the zip upload, and the native
review of the two new strings.
### Phase 10 — maintenance mode; Firefox and Edge → v1.3.0
The owner put the project into maintenance mode and asked for the last
roadmap item, the other two stores. In order: Dependabot #39–#41 and the
hand sync they always need → the `picomatch` advisory recorded (no fix
exists) → a licence gate over the lockfile (`check:licenses`) → the policy
(`/MAINTENANCE.md`, a feature form that asks which kind of change it is, and
`triage.yml`, which closes requests for something new) → Qodana (`qodana-js`,
Ultimate) beside SonarCloud → then Firefox (AMO) and Edge: the docs first,
then the port, then CI, review and 1.3.0.
One thing to carry forward: **`triage.yml` runs on `pull_request_target`,
with a write token, for pull requests from forks.** It checks out the base
branch and only compares event text with constants. Never add a checkout of
the pull request's head, a step that runs its code, or a `${{ }}` of a title
or body inside a `run:` line to that file.
## Working style
- Small commits per module; tests land with (or before) implementation.
+12 -1
View File
@@ -7,6 +7,16 @@ stop reading here — the forms ask for what is needed.
Security problems go through [`SECURITY.md`](SECURITY.md), never a public issue.
**The project is in maintenance mode** ([`MAINTENANCE.md`](MAINTENANCE.md)).
What it takes: bug, UI/UX and accessibility fixes; translation fixes (wording
wrong for a language or region, misleading spelling); dependency and security
updates; major platform upgrades; and features that are already on the
roadmap or genuinely needed. A feature request for something new, or a pull
request titled `feat…` from outside the project, is closed automatically and
labelled `maintenance-mode` — read, not deleted, and reopened if it fits.
Ideas belong in
[Discussions › Ideas](https://github.com/poli0981/bookmarkmagic/discussions/categories/ideas).
If something is hard or impossible to use — with a keyboard, a screen reader, a
contrast theme, zoom — that is a defect, and it has its own form.
[`ACCESSIBILITY.md`](ACCESSIBILITY.md) says what is already known and how a
@@ -86,7 +96,8 @@ which does not exist until it has run.
Then `npm run dev` and load `.output/chrome-mv3` at `chrome://extensions` with
Developer mode on.
`npm run verify` runs lint, type-check, knip, the grep gate and the tests. It
`npm run verify` runs lint, type-check, knip, the grep gate, the licence gate
(`npm run check:licenses`) and the tests. It
must be green before every commit. For anything release-bearing use
`npm run verify:full`, which additionally runs coverage, the build, and the gate
that inspects the *built* manifest — `verify` alone is weaker than what CI and a
+89
View File
@@ -0,0 +1,89 @@
# Maintenance
**Status: maintenance mode, since 2026-11-18.**
BookmarkMagic does what it set out to do: import, export and edit bookmarks
between browsers — offline, with two permissions and no network access. From
here the project is **maintained, not extended**. That is not abandonment: it
means keeping the extension correct, safe and current matters more than adding
to it, and every change still reaches people through a store review.
This file is the policy. The reasoning behind it is in the decision log of
[`docs/15_ROADMAP.md`](docs/15_ROADMAP.md).
## What is still done
1. **Dependencies, on a schedule.** Dependabot proposes updates weekly, for npm
and for the GitHub Actions the workflows use, and only for releases that
have been public for at least seven days. Each is merged after CI and the
follow-up the docs ask for ([`docs/01 §6`](docs/01_TECH_STACK.md)).
2. **Security, urgently.** An advisory rated **high or critical** against any
dependency — or a serious security problem in the toolchain itself, Node.js
for example — is fixed as soon as a fixed version exists. While none exists,
[`docs/09 §3.1`](docs/09_SECURITY_PRIVACY.md) records the advisory and why it
cannot reach a user, until the fix lands. To report a vulnerability, follow
[`SECURITY.md`](SECURITY.md).
3. **Major upgrades of the platform.** A new major of the language, runtime or
framework — Node.js 24 → 26, TypeScript 6 → 7, a major of WXT or Svelte — is
adopted on purpose, in its own pull request, with the docs updated first.
4. **Defects.** Bugs, UI/UX defects and accessibility barriers
([`ACCESSIBILITY.md`](ACCESSIBILITY.md)). A bookmark file that will not
import is the most useful report there is
([`CONTRIBUTING.md`](CONTRIBUTING.md)).
5. **Language.** Translation fixes: wording that is wrong for a language, or
for a region's culture or usage, and spelling mistakes that could mislead
someone. The translation form is the way in.
6. **Roadmap features, and necessary ones.** A feature that is already on the
roadmap ([`docs/15`](docs/15_ROADMAP.md)) can still land, and so can a change
that is genuinely needed — to fix a defect, to remove a barrier, or to keep
the extension working in a browser it is published for.
## What is not
**New features outside the roadmap.** Requests for them are closed
automatically, by [`.github/workflows/triage.yml`](.github/workflows/triage.yml):
- An issue opened with the **Suggest a feature** form whose first answer is
"Something new — not on the roadmap" is labelled `maintenance-mode`, gets a
comment that links here, and is closed as *not planned*. The form's other two
answers — on the roadmap, or needed for a fix — keep the issue open, labelled
`needs-triage`, for the maintainer to read.
- A pull request from outside the project whose title starts with `feat`
(Conventional Commits) is labelled and closed the same way. Open a feature
request first.
- The maintainer can label any issue `enhancement` to close it the same way.
Nothing is deleted. Every closed request is read, and one that fits this
policy is reopened and labelled `roadmap`, which the automation leaves alone.
**Ideas** are welcome in
[Discussions › Ideas](https://github.com/poli0981/bookmarkmagic/discussions/categories/ideas),
where they can be talked through without an issue that has to be accepted or
refused.
Out of scope permanently, maintenance mode or not: cloud sync, accounts,
analytics of any kind, and anything that would need a new browser permission —
the never list in [`docs/15`](docs/15_ROADMAP.md).
## Releases
A **patch** ships when there is something to fix: a file that will not import,
a data-integrity defect or a dead end, an accessibility barrier, a batch of
translation fixes, or a security problem that reaches what ships. (The
extension has no runtime dependencies, so an advisory against the build tools
is fixed in the repository and needs no release unless it changed the
built extension.) A **minor** carries a roadmap
feature, a new UI language or a change to the permissions
([`docs/12 §4`](docs/12_CI_CD.md)). There is no fixed schedule.
Your browser updates the extension by itself once a new version passes store
review; there is nothing to do.
## Supported versions
The latest version published on each store. See [`SECURITY.md`](SECURITY.md).
## Changing this policy
Through a pull request like any other, recorded in `docs/15`'s decision log
and announced in Discussions.
+19 -6
View File
@@ -1,8 +1,10 @@
# BookmarkMagic
[![Status: maintenance mode](https://img.shields.io/badge/status-maintenance%20mode-yellow.svg)](MAINTENANCE.md)
[![License: GPL-3.0-or-later](https://img.shields.io/badge/license-GPL--3.0--or--later-blue.svg)](LICENSE)
[![CI](https://github.com/poli0981/bookmarkmagic/actions/workflows/ci.yml/badge.svg)](https://github.com/poli0981/bookmarkmagic/actions/workflows/ci.yml)
[![CodeQL](https://github.com/poli0981/bookmarkmagic/actions/workflows/codeql.yml/badge.svg)](https://github.com/poli0981/bookmarkmagic/actions/workflows/codeql.yml)
[![Qodana](https://github.com/poli0981/bookmarkmagic/actions/workflows/qodana.yml/badge.svg)](https://github.com/poli0981/bookmarkmagic/actions/workflows/qodana.yml)
[![Quality gate](https://sonarcloud.io/api/project_badges/measure?project=poli0981_bookmarkmagic&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=poli0981_bookmarkmagic)
[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=poli0981_bookmarkmagic&metric=coverage)](https://sonarcloud.io/summary/new_code?id=poli0981_bookmarkmagic)
[![Chrome Web Store](https://img.shields.io/chrome-web-store/v/eghnciphhegekmnofffpgbdfefckdhmg?label=Chrome%20Web%20Store)](https://chromewebstore.google.com/detail/bookmarkmagic/eghnciphhegekmnofffpgbdfefckdhmg)
@@ -14,6 +16,14 @@ no cloud sync, 100% offline.
A Chrome (MV3) extension for importing, exporting and editing bookmarks and
folder trees. English · Tiếng Việt · 日本語 · 简体中文 · Română.
## Project status
**Maintenance mode** since 2026-11-18 — see [`MAINTENANCE.md`](MAINTENANCE.md).
Bug, UI/UX, accessibility and translation fixes, dependency and security
updates, and features already on the roadmap still land; requests for new
features beyond that are closed automatically. Ideas are welcome in
[Discussions › Ideas](https://github.com/poli0981/bookmarkmagic/discussions/categories/ideas).
## Screenshots
| Import | Edit |
@@ -117,8 +127,8 @@ npm run dev
```
`npm run verify` is the gate everything else answers to — lint, type-check
(svelte-check on the TypeScript 6 API, then `tsc` 7), knip, the grep gate and
the test suite, in that order. It must be green before every commit;
(svelte-check on the TypeScript 6 API, then `tsc` 7), knip, the grep gate, the
licence gate and the test suite, in that order. It must be green before every commit;
`npm run verify:full` adds coverage, the build and the built-manifest check,
and must be green before anything release-bearing.
@@ -134,7 +144,9 @@ code and docs disagree, the docs win. Start with [`CLAUDE.md`](CLAUDE.md), then
Bug reports and translation fixes are welcome —
[the issue forms](https://github.com/poli0981/bookmarkmagic/issues/new/choose)
ask for what is needed, and none of them requires you to write code.
ask for what is needed, and none of them requires you to write code. The
project is in maintenance mode, so a request for a feature that is not on the
roadmap is closed automatically ([`MAINTENANCE.md`](MAINTENANCE.md)).
If a bookmark file will not import, that is the most useful report there is,
because the sample becomes a permanent test. Sanitize it first:
@@ -167,9 +179,10 @@ a public issue.
| Contributing and code of conduct | code@poli0981.dev |
| Sponsorship · collaboration · press | sponsor@ · collab@ · press@poli0981.dev |
Bugs and feature ideas are best as
[issues](https://github.com/poli0981/bookmarkmagic/issues) — they help the next
person too. The extension itself never shows or uses any of these addresses.
Bugs are best as
[issues](https://github.com/poli0981/bookmarkmagic/issues) and ideas as
[Discussions](https://github.com/poli0981/bookmarkmagic/discussions/categories/ideas)
— they help the next person too. The extension itself never shows or uses any of these addresses.
## Support development
+1 -1
View File
@@ -1,5 +1,5 @@
{
"$schema": "https://biomejs.dev/schemas/2.6.4/schema.json",
"$schema": "https://biomejs.dev/schemas/2.6.6/schema.json",
"vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
"files": {
"ignoreUnknown": true,
+9 -1
View File
@@ -37,7 +37,13 @@
> here reaches installed users through a store review, so it needs a version
> bump, a CHANGELOG entry and an update submission (`13 §1b`). Sequencing lives
> in `/CLAUDE.md`; what is still open is in §10 below.
> **Doc suite version:** 1.11 (2026-11-10 — v1.2.1 released on GitHub)
>
> **Since 2026-11-18 that is a written policy: maintenance mode**
> (`/MAINTENANCE.md`). Dependency and security updates, major platform
> upgrades, bug/UI/UX/accessibility/translation fixes, and features only when
> they are on `15`'s roadmap or genuinely needed; requests for anything else
> are closed by `triage.yml` (`12 §2.6`).
> **Doc suite version:** 1.12 (2026-11-18 — maintenance mode)
---
@@ -132,6 +138,8 @@ not shipped; a Traditional Chinese browser on "Automatic" gets English.
`ICON` attributes are tolerated on parse and dropped — documented limitation).
- ❌ Dead-link checking (requires host permissions — deferred, see Roadmap).
- ❌ Firefox/Safari *store* releases (WXT keeps the door open; see Roadmap).
*Firefox and Edge became goals on 2026-11-18 (v1.3, `15`); Safari stays
out.*
- ❌ Editing browser-native root folders themselves (Bookmarks Bar / Other
Bookmarks cannot be deleted/renamed — enforced by API anyway).
+6 -5
View File
@@ -1,6 +1,6 @@
# 01 — Tech Stack
> Versions verified against npm/official sources on **2026-11-10** (first pass
> Versions verified against npm/official sources on **2026-11-18** (first pass
> 2026-07-25).
> Rule: latest stable or LTS only, with any deliberate exception stated inline.
> Re-verify minor/patch at scaffold time (`npm outdated`), but do NOT jump
@@ -25,11 +25,11 @@
| **Svelte** | **^5.57.3** | UI, runes mode only (`$state`, `$derived`, `$effect`, `$props`). The compiled runtime ships in the bundle (MIT — `legal/THIRD_PARTY_NOTICES.md`). |
| @sveltejs/vite-plugin-svelte | ^7.3.1 | Compiles `.svelte` and the runes in `.svelte.ts` stores for Vitest (`vitest.config.ts`). Its `deepmerge` dependency carries the one advisory with no fix (`09 §3.1`). |
| @wxt-dev/module-svelte | ^2.0.5 | WXT ↔ Svelte integration. |
| **Biome** | **2.6.4 (pinned exact)** | Lint + format (replaces ESLint + Prettier). Install with `npm i -D -E @biomejs/biome` per Biome guidance. 2.6 started formatting Markdown and YAML; both are excluded in `biome.json` so docs and workflows keep their hand layout (`10 §3`). The `$schema` URL in `biome.json` names the same version and moves with the pin — Dependabot bumps the package and leaves the URL behind. |
| **Biome** | **2.6.6 (pinned exact)** | Lint + format (replaces ESLint + Prettier). Install with `npm i -D -E @biomejs/biome` per Biome guidance. 2.6 started formatting Markdown and YAML; both are excluded in `biome.json` so docs and workflows keep their hand layout (`10 §3`). The `$schema` URL in `biome.json` names the same version and moves with the pin — Dependabot bumps the package and leaves the URL behind. |
| svelte-check | ^4.7.8 | Type/template authority for `.svelte` files. Runs on the TS 6 API (see TypeScript above). |
| **@types/node** | **^26** (matches the Node major) | Types for `node:fs`, `node:path`, `node:child_process` and `process`, which the test suite and `scripts/*.mjs` genuinely use. **Declared explicitly since 2026-08-03** — it used to arrive transitively, and WXT 0.21 stopped providing it. Types only: erased at build, so hard rule 2 (zero *runtime* dependencies) is untouched. |
| jsdom | **^30.1** (was ^29 through v1.0.0) | Test DOM. Not interchangeable — `02 §3` picks jsdom over happy-dom because the Netscape walk depends on parse5's implied-end-tag behaviour. A major bump runs `tests/unit/dom-environment.test.ts` first; if that canary fails, pin rather than loosen the test. |
| **Knip** | **^6** (6.44.1 as of 2026-11) | Dead code: unused files, exports, dependencies. Requires Node ≥ 20.19. v6 swapped the TypeScript backend for oxc-parser — confirm `compilers.svelte` is still the supported `.svelte` hook before scaffold (`10 §4`). |
| jsdom | **^31.0** (was ^30 through v1.2.1, ^29 through v1.0.0) | Test DOM. Not interchangeable — `02 §3` picks jsdom over happy-dom because the Netscape walk depends on parse5's implied-end-tag behaviour. A major bump runs `tests/unit/dom-environment.test.ts` first; if that canary fails, pin rather than loosen the test. |
| **Knip** | **^6** (6.44.2 as of 2026-11-18) | Dead code: unused files, exports, dependencies. Requires Node ≥ 20.19. v6 swapped the TypeScript backend for oxc-parser — confirm `compilers.svelte` is still the supported `.svelte` hook before scaffold (`10 §4`). |
| **Vitest** | **^5.1.0** (was ^4 through v1.0.1) | Unit tests. 5.0 changed `clearMocks` to default `true`, requires `vi.mock` at top level and fails unawaited async assertions; the suite needed no changes. Requires Node ≥ 22.12. |
| @vitest/coverage-v8 | match Vitest | Coverage reporting (`text` + `lcov` for SonarCloud, `12 §2.5`). |
@@ -70,11 +70,12 @@
"knip": "knip",
"guard": "node scripts/guard.mjs", // the source gate, 08 §3
"check:manifest": "node scripts/check-manifest.mjs", // the built-artifact gate, 08 §3
"check:licenses": "node scripts/check-licenses.mjs", // every lockfile licence, 09 §3.2
"icons": "node scripts/gen-icons.mjs", // regenerates the shipped icons (source of truth)
"test": "vitest run",
"test:watch": "vitest",
"coverage": "vitest run --coverage",
"verify": "npm run lint && npm run check && npm run knip && npm run guard && npm run test",
"verify": "npm run lint && npm run check && npm run knip && npm run guard && npm run check:licenses && npm run test",
"verify:full": "npm run verify && npm run coverage && npm run build && npm run check:manifest"
}
}
+33 -2
View File
@@ -114,12 +114,19 @@ four of them sat under, and Vite 8 bundles with rolldown rather than esbuild.
None of the six packages was in the lockfile — and a stale override is worse
than none, because the day the package returns it silently pins it.
State after the v1.1.0 toolchain pass (Node 26, Vitest 5, Vite 8.3, WXT 0.21.4):
State on 2026-11-18 (Node 26, Vitest 5.1, Vite 8.3, WXT 0.21.5):
| Check | Result |
|---|---|
| `npm audit --omit=dev` | **0** — nothing third-party is a runtime dependency (CI runs this, `12 §2.1`) |
| `npm audit` (dev included) | 3 low, one root cause: **`deepmerge`** (GHSA-gcqx-w48m-w2h4, prototype poisoning in `mergeObject`), reached through `@sveltejs/vite-plugin-svelte`. **No fixed version exists.** It merges the build's own plugin options at dev/build time — never user data, never in the shipped extension — so it is accepted and recorded rather than overridden. Re-check when the plugin drops or bumps it. |
| `npm audit` (dev included) | **14 high, one root cause: `picomatch`** — GHSA-fc5q-39xc-vjpf (CVE-2026-112366), a ReDoS through single-branch repeated extglobs. **Every version up to 4.0.7 is affected and no fixed version exists**, so there is nothing to upgrade or override to. It is the glob engine of the whole toolchain (WXT, Vite, Vitest, knip, svelte-check, unplugin, tinyglobby, fdir — the other 13 entries are those parents), and it matches patterns this repository writes into its own config files, at build and test time only: never user data, never in the shipped extension. Recorded rather than worked around. Dependabot opens a security PR the day a fixed release exists, and `MAINTENANCE.md` makes that PR urgent. |
| Retired | The `deepmerge` advisory recorded here until v1.2.1 (GHSA-gcqx-w48m-w2h4, low, via `@sveltejs/vite-plugin-svelte`) was **withdrawn** by GitHub on 2026-11-16. `deepmerge` 4.3.1 is still in the tree; nothing else needs doing. |
The maintenance policy's rule for advisories (`MAINTENANCE.md`): a **high or
critical** one is fixed as soon as a fixed version exists — through the
Dependabot security PR, or a lockfile update when a parent's range already
allows the fix. When no fix exists, the advisory goes in the table above with
why it cannot reach a user, and the row stays until the fix lands.
How new advisories are kept out:
@@ -132,6 +139,30 @@ How new advisories are kept out:
- Dependabot *security* PRs bypass `cooldown`; one for a version younger than
a week may fail to resolve until it ages. That is the intended trade-off.
### 3.2 Licence gate — `npm run check:licenses`
Added 2026-11-18. `scripts/check-licenses.mjs` reads every entry of
`package-lock.json` (lockfile v3 records each package's `license` field, and every
entry carries one) and fails the run on any licence outside two lists:
| Packages | Accepted | Why |
|---|---|---|
| What the build compiles into the extension — `CREDITED_PACKAGES` in `scripts/credited-packages.mjs`, the same list the build gate and the notices test read (`14 §5`) | `MIT`, `ISC`, `BSD-2-Clause`, `BSD-3-Clause`, `Apache-2.0`, `0BSD`, `MIT-0` | This code travels inside a GPL-3.0-or-later extension; only permissive licences that combine with it cleanly |
| Everything else — all of it build and test tooling, since there are no runtime dependencies | the above, plus `MPL-2.0`, `BlueOak-1.0.0`, `CC0-1.0`, `CC-BY-4.0`, `Python-2.0`, `Unlicense`, `Zlib` | Tools never ship. File-level copyleft (MPL-2.0 — `lightningcss`, under Vite) is fine for a tool; network copyleft, source-available terms and missing or custom licences are not |
SPDX expressions are evaluated (`OR` needs either side, `AND` both). An entry
with no `license`, `UNLICENSED` or `SEE LICENSE IN …` fails. A new licence
enters the tree through a reviewed change to the lists — or one `EXCEPTIONS`
entry with its reason and a `15` decision-log row — never unnoticed inside a
Dependabot bump. The gate trusts each package's own declaration, as any
lockfile-based check must, and needs neither `node_modules` nor the network.
It runs in `verify`, in CI's `quality` job and in the release build.
Considered and not used: `actions/dependency-review-action`. It sees only
what a pull request changes, reads licences from ClearlyDefined rather than
the lockfile, checks only runtime-scoped packages unless told otherwise, and
cannot run locally — a second, weaker opinion beside this one.
## 4. Permissions posture
`bookmarks` + `storage`, nothing else (justifications in `08 §2`). Any PR
+1 -1
View File
@@ -50,7 +50,7 @@ rather than assign `undefined`. Build nodes with conditional spreads
```jsonc
{
"$schema": "https://biomejs.dev/schemas/2.6.4/schema.json",
"$schema": "https://biomejs.dev/schemas/2.6.6/schema.json",
"vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
// Svelte, CSS, Markdown and YAML are excluded on purpose — see the notes below.
"files": {
+18 -9
View File
@@ -260,7 +260,12 @@ them is tested where it lives:
v1.1.0: `guard.test.ts` (`08 §3`), `check-manifest.test.ts` (a correct build
passes, one without the CSP fails) and `sanitize-formats.test.ts` (the
browser JSON formats and the audit's HTML leaks, beside the older
`sanitize-bookmarks.test.ts` — `09 §6`).
`sanitize-bookmarks.test.ts` — `09 §6`). New in Phase 10:
`check-licenses.test.ts` (SPDX expressions, the shipped list held stricter
than the toolchain's, a missing or custom licence refused, the repository's
own lockfile passing — `09 §3.2`) and `triage.test.ts` (every branch of the
maintenance-mode decision, the feature form's dropdown wording, and no event
text interpolated into the workflow's shell — `12 §2.6`).
## 5. Manual QA checklist (run before every store submission)
@@ -450,15 +455,19 @@ failure mode that would hit every installed user at once.
### Measured 2026-07-26 — Phase 5
A generated 100 000-node Netscape file (11.2 MB, 99 000 bookmarks in 1 000
folders), timed **under jsdom 29**:
folders), timed under jsdom — one column per jsdom major, never overwritten:
| Stage | Time |
|---|---|
| `detectFormat` | 0 ms |
| `parseNetscapeHtml` | **2 869 ms** |
| `buildUrlIndex` | 42 ms |
| `diffAgainstBrowser` | 53 ms |
| `serializeNetscapeHtml` | 72 ms |
| Stage | jsdom 29 (2026-07-26) | jsdom 31 (2026-11-18) |
|---|---|---|
| `detectFormat` (now `sniffFormat`) | 0 ms | 0 ms |
| `parseNetscapeHtml` | **2 869 ms** | **2 484 ms** (median of 3 runs, 2 416–2 733) |
| `buildUrlIndex` | 42 ms | not re-run (pure JS) |
| `diffAgainstBrowser` | 53 ms | not re-run (pure JS) |
| `serializeNetscapeHtml` | 72 ms | not re-run (pure JS) |
The jsdom 31 column: Node 26.13, Windows 11, Intel i7-14700KF, the file from
`gen-fixture.mjs --nodes 100000`. The jsdom 30 bump (2026-08-03) added no
column, so there is no jsdom 30 figure.
⚠️ **This does not settle the 2 s budget either way.** Everything except the
parse is pure JS and comfortably fast; the parse is dominated by `DOMParser`,
+86 -2
View File
@@ -66,7 +66,8 @@ Three jobs. The two whose names branch protection requires (§5) are
quality gates at all (§1). In order: `lint`, `check` (svelte-check on the
TS 6 API — failing on warnings too since v1.2.1, which is what makes Svelte's
`a11y_*` checks a gate, `10 §3` — then the TS 7 `tsc`), `knip`, `coverage` (`11 §1` thresholds),
`guard` (`08 §3`), `npm audit --omit=dev --audit-level=low` (the
`guard` (`08 §3`), `check:licenses` (every licence in the lockfile, `09 §3.2`),
`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
@@ -200,7 +201,7 @@ Added 2026-10-28, replacing SonarCloud's Automatic Analysis so the project gets
- The price of that isolation: the scan job has no `node_modules`, so Sonar's
type-aware rules resolve our own modules (through `.wxt/`) but not the
dependencies' types.
- The scan action is **pinned to a commit** (`v8.4.0`): it is the step that
- The scan action is **pinned to a commit** (`v8.4.1`): it is the step that
holds `SONAR_TOKEN`. 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
@@ -219,6 +220,83 @@ Added 2026-10-28, replacing SonarCloud's Automatic Analysis so the project gets
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.
### 2.6 `triage.yml` — maintenance-mode triage
Added 2026-11-18 with `/MAINTENANCE.md`. On `issues: [opened, labeled]` and
`pull_request_target: [opened]` it runs `scripts/triage.mjs`, which reads the
runner's event file and prints a decision, then carries it out with the `gh`
CLI the runner ships — no third-party action ever holds its write token
(`issues: write`, `pull-requests: write`, `contents: read`).
- **The decision is code with tests**, not shell: `decide()` is a pure
function (`tests/unit/scripts/triage.test.ts`) — a feature-form issue
answering "Something new" is labelled `maintenance-mode`, commented and
closed *not planned*; the two in-policy answers get `needs-triage`; an
`enhancement` label the owner adds by hand closes the issue the same way; an outside
pull request titled `feat…` is closed. The owner's own issues, members,
collaborators, bots and anything labelled `roadmap` are exempt. The test also
pins the dropdown's wording against `feature_request.yml`, which is the only
thing the decision parses.
- ⚠️ **`pull_request_target` holds a write token for fork pull requests.** The
checkout is the base branch — the event's default — and nothing from the
pull request runs. Titles and bodies reach the script as the event file and
are only compared with constants; the shell reads back an action from a fixed
set, an integer, a label from a fixed list and a comment the script wrote, and
validates the first two before using them.
- **Idempotent.** The feature form fires `opened` and `labeled` for one new
issue. `concurrency` runs them one at a time per number and the second
re-reads the live labels and state before acting.
- The labels must exist (`§5`); `gh … --add-label` fails on a missing one.
- **Order: comment and close first, label last.** The label is what a re-run
reads as "done", so it must not exist before the work it stands for.
- **A hand label closes only when the owner adds it.** An `enhancement` issue
with no answer to the form's question is the owner's one-touch close when
the owner labelled it; from anyone else, or on `opened`, it goes to
`needs-triage` instead of being closed on a guess.
- `actions/checkout` and `actions/setup-node` are **pinned to commits here**,
unlike the other workflows, because this one runs them with a write token
on events anyone can trigger; and setup-node has no `cache:`.
### 2.7 `qodana.yml` — Qodana for JS
Added 2026-11-18. `qodana-js` (JetBrains' JavaScript/TypeScript linter,
which needs the Ultimate licence `QODANA_TOKEN` carries) on push to `main`,
pull requests, a weekly schedule and `workflow_dispatch`. Configuration is
`qodana.yaml`: native mode (`withinDocker: false`), profile
`qodana.recommended`, fixtures and generated output excluded.
- **Its own workflow, never required**, for the reason Sonar has one (§2.5).
- **Two jobs.** `scan` has a read-only `GITHUB_TOKEN`, installs the dev
dependencies (install scripts off) because `qodana-js` resolves types
through `node_modules`, runs the action with PR comments and annotations
off, and keeps the SARIF report as the `qodana-report` artifact.
`publish` installs and runs nothing: it uploads that SARIF to code
scanning (`category: qodana`), so the findings sit beside CodeQL's under
Security and quality and on pull requests.
- ⚠️ **The documented exception to §2.5.** Sonar's token never shares a
runner with dependency code; Qodana's cannot avoid it, since the analysis
needs the dependencies. The token only uploads reports to one Qodana
Cloud project. If a dependency is ever found compromised, rotate it in
qodana.cloud.
- The action is **pinned to the commit of v2026.2.2**, not the vendor's
moving `v2026.2` branch: it holds a token, and the newest tag was younger
than the 7-day cooldown when it was added. Dependabot proposes updates.
- `pr-mode: false`: the whole project every time. It is small, and a pull
request that touches only docs would otherwise scan nothing.
- Dependabot and fork pull requests have no secrets; the scan is skipped
with a notice and `publish` does not run.
- The report artifact is a zip inside the artifact, with absolute entry
names; `publish` extracts the one entry `/qodana.sarif.json` by name. A
glob for the file found nothing on the first run.
- **First run (2026-11-18): 27 findings, none a defect.** Three regular
expressions that could be simpler — fixed — and 24 that contradict a rule
of this repository, switched off in `qodana.yaml` with the reason beside
each: JSDoc completeness (doc comments here are prose, `10 §6`), bitwise
operators in the PNG CRC-32 of `gen-icons.mjs`, and the deliberately
doubled dark palette in `tokens.css`. A finding is fixed when it is a
defect and switched off, with its reason, when it is a convention; it is
never left standing to be ignored.
## 3. Chrome Web Store publishing automation
WXT ships publishing built-in: **`wxt submit`** (wrapping
@@ -289,6 +367,8 @@ means "unknown", not "not done".
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).
- [x] `QODANA_TOKEN` — set by the owner 2026-11-18 (the Qodana Cloud project
token, Ultimate), used only by `qodana.yml`'s `scan` job (§2.7).
- [ ] ⚠️ 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.
@@ -307,6 +387,10 @@ means "unknown", not "not done".
(matching `.npmrc` `min-release-age=7`, `09 §3.1`); WXT is excluded from
the group so every WXT bump arrives alone and gets its built-manifest
diff; majors of the TypeScript pair and `@types/node` are ignored.
- [x] Labels the forms and `triage.yml` apply — `maintenance-mode`,
`needs-triage`, `roadmap` (new with `MAINTENANCE.md`) and `parser`, `i18n`
(named by the parser and translation forms since 2026-08-03, and missing
until 2026-11-18: a form silently drops a label that does not exist).
- [x] Issue templates: `.github/ISSUE_TEMPLATE/` — bug, parser report (requires
a sanitized sample), translation, feature, plus a `config.yml` chooser.
Landed 2026-08-03; `13 §6` had asserted they existed since before launch.
+5 -1
View File
@@ -189,7 +189,11 @@ actually shows and correct the files, not the dashboard.
that is not fixed at once goes into its Known limitations.
- Discord servers (`#support` in the OSS server) — pin an FAQ post.
⚠️ The invite URL is not recorded anywhere in the repo.
- Review flow for feature requests: label → roadmap doc PR → milestone.
- Feature requests, in maintenance mode (`/MAINTENANCE.md`): `triage.yml`
closes a request for something new and labels the two in-policy answers
`needs-triage` (`12 §2.6`). Read every `needs-triage` issue and every closed
one; one that fits goes into `15` by pull request and gets the `roadmap`
label, which the automation leaves alone. Ideas live in Discussions › Ideas.
The three recurring questions are already answered in prose and make the FAQ
seed: favicons cannot be imported; imported bookmarks carry today's date (the
+3 -1
View File
@@ -117,7 +117,9 @@ same value in `package.json#license` (`01 §5`).
MIT-licensed pieces into the package: the Svelte runtime, `clsx` (which the
Svelte runtime imports) and WXT's one-line `browser` shim (`wxt` +
`@wxt-dev/browser`). `wxt.config.ts` fails the build when any other package
would ship (`CREDITED_PACKAGES`). Through v1.0.x the About tab said "None"
would ship (`CREDITED_PACKAGES` — since 2026-11-18 in
`scripts/credited-packages.mjs`, the one list the build gate, the notices
test and the licence gate of `09 §3.2` all read). Through v1.0.x the About tab said "None"
and THIRD_PARTY_NOTICES said "no third-party code" — both wrong, corrected in
v1.1.0. The notices ship as `THIRD_PARTY_NOTICES.txt` (from `src/public/`),
which `check:manifest` requires in every build; `legal/THIRD_PARTY_NOTICES.md`
+40 -16
View File
@@ -1,5 +1,10 @@
# 15 — Roadmap
> **Maintenance mode since 2026-11-18.** What the project still takes, and how
> requests outside that are handled, is [`/MAINTENANCE.md`](../MAINTENANCE.md) —
> the policy, not restated here. Every feature that can still land is on this
> page; anything not on it needs a decision-log row first.
## v1.0 — MVP (store launch) — ✔ SHIPPED
Everything in `00_PROJECT_OVERVIEW.md §6`. Definition of done was
@@ -139,7 +144,7 @@ patch: it is a minor (`12 §4`).
| Automated CWS publishing | Flip `CWS_AUTOPUBLISH=true`; `wxt submit` in release workflow (`12 §3`). |
| ✔ Import Chrome's internal `Bookmarks` JSON file | **Shipped in v1.1.0** (`04 §2a`). |
| ✔ Import Firefox `.json` backup | **Shipped in v1.1.0** (`04 §2b`). The compressed automatic backups (`.jsonlz4`) are a separate item: a ~80-line pure-TS LZ4 block decoder, no dependency. |
| "Export all formats as .zip" | First runtime dep decision: `fflate` (gated, `01 §4`; About/THIRD_PARTY updates per `14 §5`). |
| "Export all formats as .zip" | First runtime dep decision: `fflate` (gated, `01 §4`; About/THIRD_PARTY updates per `14 §5`). **Not planned in maintenance mode** (2026-11-18): it would end "zero runtime dependencies" for a convenience. |
| Aggressive-dedupe toggle | Optional `www.`/`utm_*` stripping in normalize (off by default). |
| ✔ Sort folder A→Z action | **Shipped in v1.1.0** — a row action and a toolbar button, planned first and confirmed with a count (`03 §3`). |
@@ -153,14 +158,14 @@ patch: it is a minor (`12 §4`).
block decoder, no dependency. Also: capture a real Chrome HTML + `Bookmarks`
pair to sit beside the hand-built `chrome-156-*` fixtures, and the JA native
review.
3. **v1.3 — the aggressive-dedupe toggle** (deferred this round), a
3. **v1.4 — the aggressive-dedupe toggle** (deferred this round), a
session-scoped import undo, Biome linting of `.svelte` files, and true
virtualization of the edit tree if 500-row chunks prove too coarse. These
were the v1.2 plan until 2026-11-06, when real installs in Chinese and
Romanian made two languages the next minor instead (see below).
4. **v1.3+ — automated CWS publishing** once the owner creates the `CHROME_*`
secrets; Edge Add-ons and Firefox AMO listings through WXT's multi-target
build (each a separate go/no-go).
Romanian made two languages the next minor instead (see below), and the
v1.3 plan until 2026-11-18, when Firefox and Edge took that number.
4. **v1.3 — Firefox (AMO) and Edge Add-ons, and automated publishing to all
three stores** — **GO 2026-11-18** (decision log; the section below).
### Backlog carried from the v1.1.0 audit
@@ -244,13 +249,21 @@ the same dashboard evidence. Russian, Polish and Arabic also need plural forms
beyond `few`; the guard test in `dictionaries.test.ts` fails first if one is
attempted.
## v1.3 — resilience (was v1.2 until 2026-11-06)
## v1.3 — Firefox and Edge (GO 2026-11-18)
- **Scheduled local snapshots**: periodic JSON backup. ⚠️ Requires `alarms`
permission + a background service worker + `downloads` (or OPFS storage)
→ permission-story change ⇒ minor version, docs 08/09 update, privacy tab
re-review. Decide deliberately; OPFS-based silent snapshots may avoid
`downloads`.
The last "reach" item, taken out of the v2.0 table below on the owner's
decision the day maintenance mode began (decision log). The roadmap's own
wording was right: it is not "the same zip" for Firefox — the bookmark roots,
separators and the move index all differ — so it is a minor, built docs-first.
Edge takes the Chromium package unchanged. Scope and status live in the
decision log and `CLAUDE.md` Phase 10.
## v1.4 — resilience (was v1.3 until 2026-11-18, v1.2 until 2026-11-06)
- ~~**Scheduled local snapshots**~~ — **not planned in maintenance mode**
(2026-11-18). It needs the `alarms` permission and a background service
worker, and `/MAINTENANCE.md` puts anything that needs a new permission out
of scope, as `CLAUDE.md` hard rule 1 always did.
- Import "undo" (session-scoped): remember created ids → one-click revert.
- Virtualized tree rendering if >100k real-world demand appears.
@@ -258,11 +271,11 @@ attempted.
| Candidate | Consideration |
|---|---|
| Firefox Add-ons (AMO) release | WXT multi-target already builds it (`wxt -b firefox`); needs AMO listing, `browser_specific_settings.gecko.id`, separate signing flow. |
| Edge Add-ons store | Same zip usually passes; Partner Center account needed. |
| ~~Firefox Add-ons (AMO) release~~ | **GO 2026-11-18 → v1.3** (above). |
| ~~Edge Add-ons store~~ | **GO 2026-11-18 → v1.3** (above). |
| Dead-link checker | Needs `host_permissions: <all_urls>` → destroys the minimal-permission story. If ever done: **separate companion extension**, not this one. |
| Duplicate auto-merge assistant | Merge metadata (keep oldest addDate) + folder-aware suggestions. |
| Bookmarklet/notes fields | Only if a lossless place exists in Chrome's model (likely not — avoid schema lies). |
| Duplicate auto-merge assistant | Merge metadata (keep oldest addDate) + folder-aware suggestions. **Not planned in maintenance mode.** |
| Bookmarklet/notes fields | Only if a lossless place exists in Chrome's model (likely not — avoid schema lies). **Not planned in maintenance mode.** |
## Explicit "never" list (re-affirm before any pivot)
@@ -271,6 +284,9 @@ attempted.
- Analytics/telemetry of any kind.
- Ads, sponsored bookmarks, affiliate link rewriting.
- Collecting or transmitting bookmark content.
- Any permission beyond `bookmarks` and `storage` (`CLAUDE.md` hard rule 1),
which is what keeps the dead-link checker a separate extension and the
scheduled snapshots off the roadmap.
## Decision log
@@ -395,3 +411,11 @@ attempted.
| 2026-11-10 | **Alt+↑ / Alt+↓ reorders, and it is a patch.** It reuses `planDrop` and `moveTo`, so a keyboard move and a drag cannot disagree about what is legal, and there is no second write path to test. One place at a time, among the siblings on screen, like a drag. It ships in a patch because it closes a barrier to something the product already did rather than adding a capability; `12 §4` now says so. Rejected: "Move up / Move down" row buttons (two more on a row that already hides up to five), and a position field in "Move to…" (a new dialog flow for the same result) — though a click-only route is still owed (WCAG 2.5.7, backlog) | 05 §10, 12 §4 |
| 2026-11-10 | **Focus after a route change goes to `<main>`, not to the tree.** "Open in Edit" removes the button that was clicked. Focusing the tree when `#edit` mounts would also have fired on every first load, highlighting a row nobody chose and changing every screenshot; a route change with focus lost is the narrower condition and covers every tab | 06 §5 |
| 2026-11-10 | **Dependabot's bumps are not the whole bump.** #31 and #36 moved Biome twice and left `biome.json`'s `$schema` behind both times, and left `vitest`'s declared range a minor behind the coverage plugin's, which must match it (the lockfile had both at 5.1.0); `01 §2` drifted with them. The sync is a human step after each Dependabot merge, and WXT still gets the built-manifest diff — 0.21.5 produced a manifest byte-identical to the 1.2.0 release asset | 01 §2, §6 |
| 2026-11-18 | **Maintenance mode, as a written policy.** The project had been "in maintenance" since launch in the loose sense; the owner made it explicit: dependency updates on a schedule, high/critical advisories fixed as soon as a fix exists, major platform upgrades, bug/UI/UX/accessibility/translation fixes, and features only when on this roadmap or genuinely needed. **`/MAINTENANCE.md` is the policy and this file does not restate it** — the lesson of `12 §2`: a copy in two places drifts. The roadmap below stays valid; it is now the whole list of features that can still land | `MAINTENANCE.md` |
| 2026-11-18 | **Out-of-policy requests are closed by a workflow, not by hand.** The feature form asks one required question (on the roadmap / needed for a fix / something new); `scripts/triage.mjs` decides, as a pure and unit-tested function, and `triage.yml` acts with `gh` only — labelled `maintenance-mode` and closed *not planned*, or labelled `needs-triage`. `pull_request_target` checks out the base branch only and never interpolates a title or body into a shell line. Outside `feat…` pull requests are closed the same way; the owner, members, collaborators, bots and anything labelled `roadmap` are exempt. Rejected: removing the feature form (requests would arrive through the bug form, where nothing can detect them) and closing every request unread (the two in-policy answers deserve a human) | `12 §2.6`, `MAINTENANCE.md` |
| 2026-11-18 | **A high advisory with no fix is recorded, not worked around.** `npm audit` reports 14 high findings, all `picomatch` GHSA-fc5q-39xc-vjpf, every version affected, nothing to upgrade to. It is the toolchain's glob engine, matching patterns this repository writes, and never ships. The `deepmerge` row left: GitHub withdrew that advisory on 2026-11-16 | `09 §3.1` |
| 2026-11-18 | **A licence gate over the whole lockfile** (`scripts/check-licenses.mjs`): shipped packages must be permissive and GPL-3.0-compatible, tooling may also be MPL-2.0 and a few other non-copyleft licences; anything else fails until a person adds it on purpose. One shared `CREDITED_PACKAGES` list (`scripts/credited-packages.mjs`) now feeds the build gate, the notices test and this gate. `dependency-review-action` was considered and not used: PR-only, ClearlyDefined rather than the lockfile, runtime scope by default, not runnable locally. `legal/THIRD_PARTY_NOTICES.md` had called the tooling all MIT/Apache-2.0/ISC; corrected, **not a `LEGAL_VERSION` bump** — it describes tooling that never ships | `09 §3.2`, `14 §3.1` |
| 2026-11-18 | **Dependabot #39–#41 merged and synced by hand**, as the 2026-11-10 row requires: `biome.json`'s `$schema` to 2.6.6, `01 §2`, the scan action's pin in `12 §2.5`, and for the jsdom 31 major a new column in `11 §6` (2 484 ms median) beside the jsdom 29 figure | `01 §2`, `11 §6` |
| 2026-11-18 | **GO for Firefox (AMO) and Microsoft Edge Add-ons, as v1.3.** The owner's decision, recorded here before any code because the maintenance announcement names it. Settled with the owner: gecko id `bookmarkmagic@poli0981.dev` — permanent after the first AMO upload, an id and not a mailbox, shown nowhere in the UI; desktop only, because Firefox for Android has no `bookmarks` API; MV3 everywhere (WXT defaults Firefox to MV2); and Firefox separators shown, protected and warned about rather than written into any file format. An audit found why it is a minor and not a CI change: Firefox's roots are GUIDs with a fourth (Bookmarks Menu) root, so `getRoots`' position fallback maps the Menu to the toolbar; separators come back as `data:` bookmarks; and a same-folder `move` counts its index after removal | `00 §7`, `15 §v1.3` |
| 2026-11-18 | **Qodana beside SonarCloud**, at the owner's request (Ultimate licence, `QODANA_TOKEN`). Its own, never-required workflow, in two jobs: `scan` installs the dev dependencies — `qodana-js` needs them — with a read-only `GITHUB_TOKEN`; `publish` installs nothing and uploads the SARIF to code scanning, instead of the PR comments and annotations the vendor's snippet asks `contents: write` for. Sharing a runner with dependency code is a recorded exception to the Sonar rule, accepted because the token can only upload reports | `12 §2.7` |
| 2026-11-18 | **The roadmap pruned to what maintenance mode allows.** Scheduled snapshots need `alarms` and are off the roadmap; the permission rule joins the never list, where the feature form had already put it. The `fflate` zip export (a runtime dependency), the duplicate auto-merge assistant and bookmarklet notes are not planned. The old v1.3 "resilience" becomes v1.4 | `15` |
+10 -6
View File
@@ -1,6 +1,6 @@
# Third-Party Notices — BookmarkMagic
Last updated: 2026-10-29
Last updated: 2026-11-18
**No runtime dependencies are installed** — `package.json` has an empty
`dependencies` list (`docs/01 §4`). A few small MIT-licensed pieces are,
@@ -14,14 +14,18 @@ notices travel with it in `THIRD_PARTY_NOTICES.txt` at the root of the package:
| [wxt](https://github.com/wxt-dev/wxt) + [@wxt-dev/browser](https://github.com/wxt-dev/wxt) | The one-line `browser` export: `globalThis.browser` when it exists, else `globalThis.chrome` | MIT |
The build enforces this list: `wxt.config.ts` fails the build when code from any
other npm package would ship (`CREDITED_PACKAGES`), and
`tests/unit/third-party.test.ts` checks that this file and the shipped `.txt`
name every package on it. None of these contains network code; the
other npm package would ship (`CREDITED_PACKAGES`, kept in
`scripts/credited-packages.mjs`), `tests/unit/third-party.test.ts` checks that
this file and the shipped `.txt` name every package on it, and
`npm run check:licenses` holds each of them to a permissive licence. None of these contains network code; the
extension's Content-Security-Policy forbids it anyway (`docs/08 §3`).
Build-time tooling (WXT's CLI, Vite, TypeScript, Biome, Knip, Vitest,
svelte-check) is not distributed with the extension and is not listed here.
All of it is MIT/Apache-2.0/ISC licensed and compatible with GPL-3.0-or-later.
svelte-check and what they depend on) is not distributed with the extension and
is not listed here. Its licences are checked on every build by
`npm run check:licenses`: permissive (MIT, Apache-2.0, ISC, BSD, 0BSD, MIT-0,
BlueOak, CC0) or, for one CSS tool under Vite (`lightningcss`), the
file-level copyleft MPL-2.0 — none of which reaches the extension.
Licensing questions: **copyright@poli0981.dev**.
+2 -1
View File
@@ -29,11 +29,12 @@
"knip": "knip",
"guard": "node scripts/guard.mjs",
"check:manifest": "node scripts/check-manifest.mjs",
"check:licenses": "node scripts/check-licenses.mjs",
"icons": "node scripts/gen-icons.mjs",
"test": "vitest run",
"test:watch": "vitest",
"coverage": "vitest run --coverage",
"verify": "npm run lint && npm run check && npm run knip && npm run guard && npm run test",
"verify": "npm run lint && npm run check && npm run knip && npm run guard && npm run check:licenses && npm run test",
"verify:full": "npm run verify && npm run coverage && npm run build && npm run check:manifest"
},
"devDependencies": {
+42
View File
@@ -0,0 +1,42 @@
# Qodana — docs/12 §2.7. Read by .github/workflows/qodana.yml.
#
# qodana-js is JetBrains' JavaScript/TypeScript linter; it needs the Ultimate
# licence that QODANA_TOKEN carries. Native mode (no Docker image): the
# workflow installs node_modules on the runner first, with install scripts
# off, and the analysis reads them from there.
version: "1.0"
linter: qodana-js
withinDocker: false
profile:
name: qodana.recommended
# What is not code, or not ours: byte-exact browser samples (malformed on
# purpose), build and coverage output, screenshots, store copy, prose.
exclude:
- name: All
paths:
- tests/fixtures
- .output
- .wxt
- coverage
- capture
- store
- docs
- legal
# Inspections switched off after the first run (2026-11-18), each because it
# contradicts a rule of this repository rather than finding a defect:
#
# Doc comments here are prose (docs/10 §6). `@param` tags appear only where a
# `// @ts-check` script needs a type, so "every parameter described" is not
# the convention — 22 of the first run's 27 findings.
- name: JSCommentMatchesSignature
# A CRC-32 table for PNG chunks is bitwise by definition.
- name: JSBitwiseOperatorUsage
paths:
- scripts/gen-icons.mjs
# The dark palette is declared twice on purpose: once under the
# prefers-color-scheme query, once for the explicit theme switch (docs/06 §1).
- name: DuplicatedCode
paths:
- src/styles/tokens.css
+14
View File
@@ -0,0 +1,14 @@
/**
* Types for scripts/check-licenses.mjs, so its tests can call it directly.
* The script itself is plain JavaScript checked with `// @ts-check`.
*/
export const SHIPPED_LICENSES: readonly string[];
export const TOOLCHAIN_LICENSES: readonly string[];
export const EXCEPTIONS: Readonly<Record<string, string>>;
export function satisfies(expression: string, allowed: readonly string[]): boolean;
export function packageNameOf(key: string): string;
export function checkLockfile(lock: unknown): {
problems: string[];
checked: number;
counts: Map<string, number>;
};
+227
View File
@@ -0,0 +1,227 @@
// @ts-check
/**
* Licence gate — docs/09 §3.2, docs/12 §2.1.
*
* Reads `package-lock.json` (lockfile v3), where npm records each installed
* package's `license` field, and checks every entry against one of two lists:
*
* - SHIPPED — the packages the build compiles into the extension
* (`CREDITED_PACKAGES`, scripts/credited-packages.mjs). Their code travels
* inside a GPL-3.0-or-later extension, so only permissive licences that
* combine with it cleanly are accepted.
* - TOOLCHAIN — everything else. The extension has no runtime dependencies,
* so all of these are build and test tools that never ship. Permissive
* licences and weak, file-level copyleft (MPL-2.0) are fine; network
* copyleft (AGPL), source-available terms (SSPL, BUSL, Commons Clause),
* a missing or custom licence (`UNLICENSED`, `SEE LICENSE IN …`) are not.
*
* Anything outside the lists fails the run until a person looks at it — the
* point is that a new licence enters the tree through a reviewed change to
* this file, never unnoticed through a Dependabot bump. `EXCEPTIONS` is that
* reviewed change for one package, with its reason.
*
* The `license` value is self-declared by each package and copied verbatim by
* npm; this gate trusts it, as every lockfile-based checker must. It needs no
* `node_modules` and no network, so it runs before anything is installed.
*
* Usage: node scripts/check-licenses.mjs — reads <repo>/package-lock.json,
* resolved from this file. Its tests call `checkLockfile(lock)` directly.
*/
import { readFileSync } from 'node:fs';
import { resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { CREDITED_PACKAGES } from './credited-packages.mjs';
/** Permissive licences that may ship inside a GPL-3.0-or-later extension. */
export const SHIPPED_LICENSES = Object.freeze([
'0BSD',
'Apache-2.0',
'BSD-2-Clause',
'BSD-3-Clause',
'ISC',
'MIT',
'MIT-0',
]);
/** Licences accepted for build and test tooling, which never ships. */
export const TOOLCHAIN_LICENSES = Object.freeze([
...SHIPPED_LICENSES,
'BlueOak-1.0.0',
'CC-BY-4.0',
'CC0-1.0',
'MPL-2.0',
'Python-2.0',
'Unlicense',
'Zlib',
]);
/**
* Packages accepted despite the lists above: `name → reason`. Empty on
* purpose; an entry is a decision, recorded in docs/15's decision log.
* @type {Readonly<Record<string, string>>}
*/
export const EXCEPTIONS = Object.freeze({});
/**
* Whether an SPDX licence expression is satisfied by the allowed identifiers.
* `A OR B` needs either side, `A AND B` both; parentheses group; `A WITH X`
* (a licence exception) is judged by `A`. Anything unparseable is refused.
*
* @param {string} expression
* @param {readonly string[]} allowed
* @returns {boolean}
*/
export function satisfies(expression, allowed) {
const tokens = expression.match(/\(|\)|[^\s()]+/g) ?? [];
let at = 0;
/** @returns {boolean} */
const parseOr = () => {
let ok = parseAnd();
while (tokens[at] === 'OR') {
at++;
const right = parseAnd();
ok = ok || right;
}
return ok;
};
/** @returns {boolean} */
const parseAnd = () => {
let ok = parseTerm();
while (tokens[at] === 'AND') {
at++;
const right = parseTerm();
ok = ok && right;
}
return ok;
};
/** @returns {boolean} */
const parseTerm = () => {
const token = tokens[at++];
if (token === '(') {
const ok = parseOr();
if (tokens[at++] !== ')') throw new SyntaxError('unbalanced parentheses');
return ok;
}
if (token === undefined || token === ')' || token === 'AND' || token === 'OR') {
throw new SyntaxError('expected a licence identifier');
}
if (tokens[at] === 'WITH') at += 2;
return allowed.includes(token);
};
try {
const ok = parseOr();
return at === tokens.length && tokens.length > 0 && ok;
} catch {
return false;
}
}
/**
* The package name a lockfile key installs: the part after the last
* `node_modules/`, scope included.
* @param {string} key
*/
export function packageNameOf(key) {
const at = key.lastIndexOf('node_modules/');
return at === -1 ? key : key.slice(at + 'node_modules/'.length);
}
/**
* Lockfile text is our own committed file, but it is still file content: keep
* what reaches the log to the characters package names and SPDX ids use.
* @param {unknown} value
*/
function printable(value) {
return String(value)
.replaceAll(/[^\w@/.+() -]/g, '?')
.slice(0, 120);
}
/**
* Check every installed package of a v2/v3 lockfile.
*
* @param {unknown} lock — the parsed `package-lock.json`
* @returns {{ problems: string[], checked: number, counts: Map<string, number> }}
*/
export function checkLockfile(lock) {
/** @type {string[]} */
const problems = [];
/** @type {Map<string, number>} */
const counts = new Map();
const packages =
typeof lock === 'object' && lock !== null && 'packages' in lock ? lock.packages : undefined;
if (typeof packages !== 'object' || packages === null) {
return { problems: ['no "packages" map — lockfile v2 or v3 expected'], checked: 0, counts };
}
const shippedSeen = new Set();
let checked = 0;
for (const [key, raw] of Object.entries(packages)) {
// The root project (key "") and workspace links carry no install of their own.
if (key === '' || !key.includes('node_modules/')) continue;
if (typeof raw === 'object' && raw !== null && 'link' in raw && raw.link === true) continue;
checked++;
const name = packageNameOf(key);
const license =
typeof raw === 'object' && raw !== null && 'license' in raw ? raw.license : undefined;
const label = typeof license === 'string' ? license : '(none)';
counts.set(label, (counts.get(label) ?? 0) + 1);
const shipped = CREDITED_PACKAGES.includes(name);
if (shipped) shippedSeen.add(name);
if (Object.hasOwn(EXCEPTIONS, name)) continue;
const allowed = shipped ? SHIPPED_LICENSES : TOOLCHAIN_LICENSES;
if (typeof license !== 'string' || !satisfies(license, allowed)) {
problems.push(
`${printable(key)}: licence "${printable(label)}" is not accepted for ` +
(shipped ? 'code that ships in the extension' : 'build tooling'),
);
}
}
for (const name of CREDITED_PACKAGES) {
if (!shippedSeen.has(name)) {
problems.push(`${printable(name)}: credited as shipping, but not in the lockfile`);
}
}
return { problems, checked, counts };
}
/** @returns {number} exit code */
function main() {
const lockPath = resolve(fileURLToPath(import.meta.url), '..', '..', 'package-lock.json');
/** @type {unknown} */
let lock;
try {
lock = JSON.parse(readFileSync(lockPath, 'utf8'));
} catch (cause) {
console.error(`::error::check-licenses: cannot read package-lock.json (${String(cause)})`);
return 1;
}
const { problems, checked, counts } = checkLockfile(lock);
if (problems.length > 0) {
for (const problem of problems) console.error(`::error::check-licenses: ${problem}`);
console.error(
'\nSee docs/09 §3.2: add the licence to a list, or an EXCEPTIONS entry, on purpose.',
);
return 1;
}
const summary = [...counts]
.sort((a, b) => b[1] - a[1])
.map(([license, n]) => `${printable(license)} ${n}`)
.join(', ');
console.warn(`check-licenses: clean — ${checked} packages (${summary}).`);
return 0;
}
// Run only as the entry point (same guard as check-manifest.mjs).
const isEntry =
import.meta.url.startsWith('file:') &&
process.argv[1] !== undefined &&
resolve(process.argv[1]) === fileURLToPath(import.meta.url);
if (isEntry) {
// exitCode, not exit(): exit() can cut off piped stderr before CI reads it.
process.exitCode = main();
}
+5
View File
@@ -0,0 +1,5 @@
/**
* Types for scripts/credited-packages.mjs, so `wxt.config.ts` and the tests can
* import the list. The script itself is plain JavaScript checked with `// @ts-check`.
*/
export const CREDITED_PACKAGES: readonly string[];
+17
View File
@@ -0,0 +1,17 @@
// @ts-check
/**
* The npm packages whose code the build compiles into the extension — docs/14 §5.
*
* One list behind three gates, so none of them can drift from the others:
* - `wxt.config.ts` fails the build when code from any other package ships;
* - `tests/unit/third-party.test.ts` requires both notices files to credit
* every package named here;
* - `scripts/check-licenses.mjs` holds each of them to the licences that may
* travel inside a GPL-3.0-or-later extension.
*
* Through v1.0.x the notices said "none" while three of these shipped. Adding
* a name here is the first step of shipping a new package, never the last:
* its licence text goes into `legal/THIRD_PARTY_NOTICES.md` and
* `src/public/THIRD_PARTY_NOTICES.txt` in the same pull request.
*/
export const CREDITED_PACKAGES = Object.freeze(['svelte', 'clsx', '@wxt-dev/browser', 'wxt']);
+1 -1
View File
@@ -107,7 +107,7 @@ export function makeTitleMapper() {
const SCRIPTS = [
[/[一-鿿぀-ヿ]/, '文字'],
[/[֐-ࣿ]/, 'شيء'],
[/[\p{Extended_Pictographic}]/u, '🌸'],
[/\p{Extended_Pictographic}/u, '🌸'],
];
return (raw) => {
+22
View File
@@ -0,0 +1,22 @@
/**
* Types for scripts/triage.mjs, so its tests can call it directly.
* The script itself is plain JavaScript checked with `// @ts-check`.
*/
export interface Decision {
action: 'close' | 'label' | 'none';
reason: string;
kind?: 'issue' | 'pr';
number?: number;
label?: string;
comment?: string;
}
export const POLICY_URL: string;
export const IDEAS_URL: string;
export const KIND_QUESTION: string;
export const KIND: Readonly<{ roadmap: string; needed: string; fresh: string }>;
export const LABEL: Readonly<{ feature: string; closed: string; triage: string; exempt: string }>;
export const ISSUE_COMMENT: string;
export const PR_COMMENT: string;
export function kindOf(body: unknown): string | undefined;
export function decide(eventName: string | undefined, payload: unknown): Decision;
+261
View File
@@ -0,0 +1,261 @@
// @ts-check
/**
* Maintenance-mode triage — MAINTENANCE.md, docs/12 §2.6.
*
* Decides what `.github/workflows/triage.yml` does with a new issue or pull
* request; the workflow then carries the decision out with `gh`. The decision
* is a pure function of the event payload, so every branch is unit-tested
* (tests/unit/scripts/triage.test.ts) instead of living in shell `if`s.
*
* - An issue labelled `enhancement` (the feature form applies it) whose
* "kind of change" answer is "something new" — or that has no answer at
* all, i.e. the maintainer labelled it by hand — is labelled
* `maintenance-mode`, gets a comment and is closed as not planned.
* - The other two answers (on the roadmap; needed for a fix) keep it open,
* labelled `needs-triage`, for the maintainer to read.
* - A pull request from outside the project titled `feat…` (Conventional
* Commits) is labelled and closed the same way.
* - Exempt: the owner's own issues, project members and collaborators, bots
* (Dependabot), anything labelled `roadmap`, anything already triaged.
*
* Nothing here runs code from the event: titles and bodies are only compared
* with constants, and the workflow passes the payload by file, never through
* shell interpolation.
*
* Usage (in CI): node scripts/triage.mjs — reads GITHUB_EVENT_NAME and
* GITHUB_EVENT_PATH from the environment the runner sets, prints a JSON
* decision on stdout. It takes no arguments.
*/
import { readFileSync } from 'node:fs';
import { resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
const REPO = 'https://github.com/poli0981/bookmarkmagic';
export const POLICY_URL = `${REPO}/blob/main/MAINTENANCE.md`;
export const IDEAS_URL = `${REPO}/discussions/categories/ideas`;
/** The feature form's dropdown, word for word (`.github/ISSUE_TEMPLATE/feature_request.yml`). */
export const KIND_QUESTION = 'Which kind of change is this?';
export const KIND = Object.freeze({
roadmap: 'Something already on the roadmap (docs/15)',
needed: 'Needed to fix a bug, a UI/UX defect or an accessibility barrier',
fresh: 'Something new — not on the roadmap',
});
export const LABEL = Object.freeze({
feature: 'enhancement',
closed: 'maintenance-mode',
triage: 'needs-triage',
exempt: 'roadmap',
});
/** Associations that mean "part of the project", per GitHub's author_association. */
const INSIDERS = new Set(['OWNER', 'MEMBER', 'COLLABORATOR']);
const BOT_NOTE = '<sub>Posted automatically by the triage workflow.</sub>';
export const ISSUE_COMMENT = [
'Thank you for the suggestion.',
'',
`BookmarkMagic is in **maintenance mode** ([MAINTENANCE.md](${POLICY_URL})): it takes bug, UI/UX and accessibility fixes, translation fixes, dependency and security updates, and features that are already on the roadmap. This request is for something new, so it has been labelled \`${LABEL.closed}\` and closed.`,
'',
'It has not been deleted, and it will be read. If it is on the roadmap, or it is needed to fix a defect or remove a barrier, it will be reopened. Ideas are welcome in [Discussions › Ideas](' +
`${IDEAS_URL}).`,
'',
BOT_NOTE,
].join('\n');
export const PR_COMMENT = [
'Thank you for the pull request.',
'',
`BookmarkMagic is in **maintenance mode** ([MAINTENANCE.md](${POLICY_URL})). A pull request that adds a feature — its title starts with \`feat\` — is closed automatically unless the feature is already on the roadmap, so this one has been labelled \`${LABEL.closed}\` and closed.`,
'',
'Please open a feature request first; if it is accepted (label `roadmap`), this pull request will be reopened. If it is a fix rather than a feature, say so in a comment — a `fix:` title is what the maintainer expects.',
'',
BOT_NOTE,
].join('\n');
/**
* @typedef {{
* action: 'close' | 'label' | 'none',
* reason: string,
* kind?: 'issue' | 'pr',
* number?: number,
* label?: string,
* comment?: string,
* }} Decision
*/
/**
* The answer to the feature form's dropdown, or undefined when the body has
* none (an issue from another form, labelled by hand). Issue forms render each
* field as `### <label>` followed by the answer.
* @param {unknown} body
* @returns {string | undefined}
*/
export function kindOf(body) {
if (typeof body !== 'string') return undefined;
const lines = body.split(/\r?\n/);
const at = lines.findIndex((line) => line.trim() === `### ${KIND_QUESTION}`);
if (at === -1) return undefined;
for (const line of lines.slice(at + 1)) {
const text = line.trim();
if (text.startsWith('### ')) return undefined;
if (text !== '') return text;
}
return undefined;
}
/** @param {unknown} value @returns {Record<string, unknown>} */
function record(value) {
return typeof value === 'object' && value !== null
? /** @type {Record<string, unknown>} */ (value)
: {};
}
/** @param {unknown} labels @returns {string[]} */
function labelNames(labels) {
if (!Array.isArray(labels)) return [];
return labels.map((label) => record(label).name).filter((name) => typeof name === 'string');
}
/** @param {unknown} value @returns {number | undefined} */
function positiveInt(value) {
return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : undefined;
}
/**
* Whether this event is the repository owner adding a label by hand.
* @param {Record<string, unknown>} payload
*/
function addedByOwner(payload) {
const sender = record(payload.sender).login;
const owner = record(record(payload.repository).owner).login;
return (
payload.action === 'labeled' && typeof sender === 'string' && sender !== '' && sender === owner
);
}
/**
* @param {Record<string, unknown>} payload
* @returns {Decision}
*/
function decideIssue(payload) {
const issue = record(payload.issue);
const number = positiveInt(issue.number);
if (number === undefined) return { action: 'none', reason: 'no issue number' };
if (payload.action !== 'opened' && payload.action !== 'labeled') {
return { action: 'none', reason: `issue action ${String(payload.action)}` };
}
if (payload.action === 'labeled' && record(payload.label).name !== LABEL.feature) {
return { action: 'none', reason: 'a different label was added' };
}
if (issue.state !== 'open') return { action: 'none', reason: 'issue is not open' };
const labels = labelNames(issue.labels);
if (!labels.includes(LABEL.feature)) return { action: 'none', reason: 'not a feature request' };
for (const done of [LABEL.exempt, LABEL.closed, LABEL.triage]) {
if (labels.includes(done)) return { action: 'none', reason: `already labelled ${done}` };
}
if (issue.author_association === 'OWNER')
return { action: 'none', reason: "the owner's own issue" };
const kind = kindOf(issue.body);
const forTriage = /** @type {Decision} */ ({
action: 'label',
reason: 'in policy — for the maintainer',
kind: 'issue',
number,
label: LABEL.triage,
});
if (kind === KIND.roadmap || kind === KIND.needed) return forTriage;
// No answer at all means the form was not used. Closing on that is the
// owner's one-touch close, so it needs the owner's own `enhancement` label;
// anything else (an edited body, an answer the form never offered) goes to
// a human rather than being closed on a guess.
if (kind !== KIND.fresh && !addedByOwner(payload)) {
return { ...forTriage, reason: 'no answer to the form, not labelled by the owner' };
}
return {
action: 'close',
reason:
kind === KIND.fresh ? 'a new feature outside the roadmap' : 'labelled enhancement by hand',
kind: 'issue',
number,
label: LABEL.closed,
comment: ISSUE_COMMENT,
};
}
/** Conventional Commits `feat`, with an optional scope and breaking-change mark. */
const FEAT_TITLE = /^feat(\([^)]*\))?!?:/i;
/**
* @param {Record<string, unknown>} payload
* @returns {Decision}
*/
function decidePullRequest(payload) {
const pr = record(payload.pull_request);
const number = positiveInt(pr.number);
if (number === undefined) return { action: 'none', reason: 'no pull request number' };
if (payload.action !== 'opened')
return { action: 'none', reason: `pull request action ${String(payload.action)}` };
if (pr.state !== 'open') return { action: 'none', reason: 'pull request is not open' };
if (record(pr.user).type === 'Bot') return { action: 'none', reason: 'opened by a bot' };
if (INSIDERS.has(String(pr.author_association)))
return { action: 'none', reason: 'opened from inside the project' };
if (labelNames(pr.labels).includes(LABEL.exempt))
return { action: 'none', reason: 'labelled roadmap' };
if (typeof pr.title !== 'string' || !FEAT_TITLE.test(pr.title.trim())) {
return { action: 'none', reason: 'not a feature pull request' };
}
return {
action: 'close',
reason: 'a feature pull request from outside the project',
kind: 'pr',
number,
label: LABEL.closed,
comment: PR_COMMENT,
};
}
/**
* What to do with one event.
* @param {string | undefined} eventName — GITHUB_EVENT_NAME
* @param {unknown} payload — the parsed GITHUB_EVENT_PATH file
* @returns {Decision}
*/
export function decide(eventName, payload) {
const event = record(payload);
if (eventName === 'issues') return decideIssue(event);
if (eventName === 'pull_request_target') return decidePullRequest(event);
return { action: 'none', reason: `event ${String(eventName)} is not triaged` };
}
/** @returns {number} exit code */
function main() {
const eventPath = process.env.GITHUB_EVENT_PATH;
if (eventPath === undefined || eventPath === '') {
console.error('triage: GITHUB_EVENT_PATH is not set — this runs inside GitHub Actions only');
return 1;
}
/** @type {unknown} */
let payload;
try {
payload = JSON.parse(readFileSync(eventPath, 'utf8'));
} catch (cause) {
console.error(`triage: cannot read the event payload (${String(cause)})`);
return 1;
}
process.stdout.write(`${JSON.stringify(decide(process.env.GITHUB_EVENT_NAME, payload))}\n`);
return 0;
}
// Run only as the entry point (same guard as check-manifest.mjs).
const isEntry =
import.meta.url.startsWith('file:') &&
process.argv[1] !== undefined &&
resolve(process.argv[1]) === fileURLToPath(import.meta.url);
if (isEntry) {
// exitCode, not exit(): exit() can cut off piped output before CI reads it.
process.exitCode = main();
}
+181
View File
@@ -0,0 +1,181 @@
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { describe, expect, it } from 'vitest';
import {
checkLockfile,
EXCEPTIONS,
packageNameOf,
SHIPPED_LICENSES,
satisfies,
TOOLCHAIN_LICENSES,
} from '../../../scripts/check-licenses.mjs';
/**
* scripts/check-licenses.mjs — the licence gate (docs/09 §3.2).
*
* Called as functions, never spawned: the process-spawning script tests are
* the ones that time out under load on Windows (CLAUDE.md, Phase 8).
*/
/** A lockfile with the four shipped packages plus whatever a case adds. */
function lockWith(extra: Record<string, object> = {}): object {
return {
lockfileVersion: 3,
packages: {
'': { name: 'bookmarkmagic', license: 'GPL-3.0-or-later' },
'node_modules/svelte': { version: '5.0.0', license: 'MIT', dev: true },
'node_modules/clsx': { version: '2.0.0', license: 'MIT', dev: true },
'node_modules/wxt': { version: '0.21.5', license: 'MIT', dev: true },
'node_modules/@wxt-dev/browser': { version: '0.1.0', license: 'MIT', dev: true },
...extra,
},
};
}
describe('satisfies — SPDX expressions', () => {
const allowed = ['MIT', 'Apache-2.0', 'ISC'];
it.each([
['MIT', true],
['GPL-3.0-only', false],
['MIT OR GPL-3.0-only', true],
['GPL-3.0-only OR MIT', true],
['MIT AND ISC', true],
['MIT AND GPL-3.0-only', false],
['(MIT OR GPL-3.0-only) AND ISC', true],
['(MIT AND GPL-3.0-only) OR Apache-2.0', true],
['(MIT AND GPL-3.0-only) OR AGPL-3.0-only', false],
['Apache-2.0 WITH LLVM-exception', true],
])('%s → %s', (expression, expected) => {
expect(satisfies(expression, allowed)).toBe(expected);
});
it.each([
'',
'UNLICENSED',
'SEE LICENSE IN LICENSE.md',
'(MIT',
'MIT)',
'MIT OR',
'AND MIT',
'MIT WITH',
'Apache 2.0',
])('refuses %j', (expression) => {
expect(satisfies(expression, allowed)).toBe(false);
});
});
describe('packageNameOf', () => {
it.each([
['node_modules/vite', 'vite'],
['node_modules/@wxt-dev/browser', '@wxt-dev/browser'],
['node_modules/a/node_modules/@scope/b', '@scope/b'],
['node_modules/a/node_modules/picomatch', 'picomatch'],
])('%s → %s', (key, name) => {
expect(packageNameOf(key)).toBe(name);
});
});
describe('checkLockfile', () => {
it('passes a tree of accepted licences and counts them', () => {
const result = checkLockfile(
lockWith({
'node_modules/lightningcss': { license: 'MPL-2.0', dev: true },
'node_modules/x/node_modules/y': { license: 'MIT OR Apache-2.0', dev: true },
}),
);
expect(result.problems).toEqual([]);
expect(result.checked).toBe(6);
expect(result.counts.get('MIT')).toBe(4);
expect(result.counts.get('MPL-2.0')).toBe(1);
});
it('holds shipped packages to the stricter list', () => {
// MPL-2.0 is fine for a build tool and not for code inside the extension.
const lock = lockWith({ 'node_modules/svelte': { license: 'MPL-2.0', dev: true } });
const { problems } = checkLockfile(lock);
expect(problems).toHaveLength(1);
expect(problems[0]).toContain('node_modules/svelte');
expect(problems[0]).toContain('ships in the extension');
});
it('applies the shipped list to a nested copy of a shipped package too', () => {
const lock = lockWith({ 'node_modules/a/node_modules/clsx': { license: 'CC0-1.0' } });
expect(checkLockfile(lock).problems).toHaveLength(1);
});
it.each([
['AGPL-3.0-only'],
['SSPL-1.0'],
['BUSL-1.1'],
['UNLICENSED'],
['SEE LICENSE IN EULA.txt'],
])('fails a toolchain package licensed %s', (license) => {
const { problems } = checkLockfile(lockWith({ 'node_modules/bad': { license } }));
expect(problems).toHaveLength(1);
expect(problems[0]).toContain('build tooling');
});
it('fails a package with no licence field at all', () => {
const { problems, counts } = checkLockfile(
lockWith({ 'node_modules/bare': { version: '1.0.0' } }),
);
expect(problems).toHaveLength(1);
expect(problems[0]).toContain('(none)');
expect(counts.get('(none)')).toBe(1);
});
it('fails when a credited package is missing from the lockfile', () => {
const { 'node_modules/clsx': _gone, ...rest } = (lockWith() as { packages: object })
.packages as Record<string, object>;
const lock = { lockfileVersion: 3, packages: rest };
expect(checkLockfile(lock).problems).toEqual([
'clsx: credited as shipping, but not in the lockfile',
]);
});
it('skips the root project and workspace links', () => {
const lock = lockWith({
'packages/local': { link: true },
'node_modules/local': { link: true },
});
expect(checkLockfile(lock).problems).toEqual([]);
});
it('refuses something that is not a v2/v3 lockfile', () => {
expect(checkLockfile({ lockfileVersion: 1, dependencies: {} }).problems).toHaveLength(1);
expect(checkLockfile(null).problems).toHaveLength(1);
});
it('keeps log output to safe characters', () => {
const { problems } = checkLockfile(
lockWith({ 'node_modules/evil': { license: 'MIT\n::error::injected' } }),
);
expect(problems).toHaveLength(1);
expect(problems[0]).not.toContain('\n');
expect(problems[0]).not.toContain('::error::injected');
});
});
describe('the policy itself', () => {
it('ships nothing under a copyleft licence', () => {
for (const id of SHIPPED_LICENSES) expect(id).not.toMatch(/GPL|MPL|EPL|CDDL|SSPL|BUSL/);
});
it('accepts everything shipped for tooling too', () => {
for (const id of SHIPPED_LICENSES) expect(TOOLCHAIN_LICENSES).toContain(id);
});
it('starts with no exceptions — each one is a recorded decision', () => {
expect(Object.keys(EXCEPTIONS)).toEqual([]);
});
it('passes the repository lockfile', () => {
const lock: unknown = JSON.parse(
readFileSync(join(process.cwd(), 'package-lock.json'), 'utf8'),
);
const { problems, checked } = checkLockfile(lock);
expect(problems).toEqual([]);
expect(checked).toBeGreaterThan(100);
});
});
+233
View File
@@ -0,0 +1,233 @@
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { describe, expect, it } from 'vitest';
import {
decide,
IDEAS_URL,
ISSUE_COMMENT,
KIND,
KIND_QUESTION,
kindOf,
LABEL,
POLICY_URL,
PR_COMMENT,
} from '../../../scripts/triage.mjs';
/**
* scripts/triage.mjs — what the maintenance-mode triage workflow does with an
* issue or a pull request (MAINTENANCE.md, docs/12 §2.6).
*/
const read = (path: string): string => readFileSync(join(process.cwd(), path), 'utf8');
/** An issue body as GitHub renders the feature form. */
function formBody(kind: string): string {
return [
`### ${KIND_QUESTION}`,
'',
kind,
'',
'### What are you trying to do?',
'',
'Something.',
].join('\n');
}
function issueEvent(
overrides: {
action?: string;
label?: string;
labels?: string[];
body?: unknown;
association?: string;
state?: string;
} = {},
): unknown {
return {
action: overrides.action ?? 'opened',
...(overrides.label !== undefined && { label: { name: overrides.label } }),
issue: {
number: 7,
state: overrides.state ?? 'open',
author_association: overrides.association ?? 'NONE',
labels: (overrides.labels ?? [LABEL.feature]).map((name) => ({ name })),
body: overrides.body ?? formBody(KIND.fresh),
},
};
}
function prEvent(
overrides: {
action?: string;
title?: string;
association?: string;
userType?: string;
labels?: string[];
} = {},
): unknown {
return {
action: overrides.action ?? 'opened',
pull_request: {
number: 12,
state: 'open',
title: overrides.title ?? 'feat(export): add a PDF format',
author_association: overrides.association ?? 'FIRST_TIME_CONTRIBUTOR',
user: { type: overrides.userType ?? 'User' },
labels: (overrides.labels ?? []).map((name) => ({ name })),
},
};
}
describe('kindOf — the feature form dropdown', () => {
it.each(Object.values(KIND))('reads %j', (kind) => {
expect(kindOf(formBody(kind))).toBe(kind);
});
it('reads a CRLF body', () => {
expect(kindOf(formBody(KIND.needed).replaceAll('\n', '\r\n'))).toBe(KIND.needed);
});
it('is undefined without the question, with an empty answer, or for a non-string', () => {
expect(kindOf('### What happened?\n\nIt broke.')).toBeUndefined();
expect(kindOf(`### ${KIND_QUESTION}\n\n### Next\n\nx`)).toBeUndefined();
expect(kindOf(null)).toBeUndefined();
});
});
describe('decide — issues', () => {
it('closes a request for something new, with the policy comment', () => {
expect(decide('issues', issueEvent())).toEqual({
action: 'close',
reason: 'a new feature outside the roadmap',
kind: 'issue',
number: 7,
label: LABEL.closed,
comment: ISSUE_COMMENT,
});
});
it.each([KIND.roadmap, KIND.needed])('keeps %j open for the maintainer', (kind) => {
expect(decide('issues', issueEvent({ body: formBody(kind) }))).toMatchObject({
action: 'label',
label: LABEL.triage,
number: 7,
});
});
it('closes an issue the owner labelled enhancement by hand', () => {
const event = {
...(issueEvent({
action: 'labeled',
label: LABEL.feature,
body: '### What happened?\n\nx',
}) as object),
sender: { login: 'poli0981' },
repository: { owner: { login: 'poli0981' } },
};
expect(decide('issues', event)).toMatchObject({
action: 'close',
reason: 'labelled enhancement by hand',
});
});
it.each([
['labelled by someone else', 'labeled', 'someone'],
['opened with the label but no answer', 'opened', 'poli0981'],
])('sends an issue with no answer to a human when %s', (_case, action, sender) => {
const event = {
...(issueEvent({ action, label: LABEL.feature, body: 'edited away' }) as object),
sender: { login: sender },
repository: { owner: { login: 'poli0981' } },
};
expect(decide('issues', event)).toMatchObject({ action: 'label', label: LABEL.triage });
});
it.each([
['another label was added', issueEvent({ action: 'labeled', label: 'bug' })],
['not a feature request', issueEvent({ labels: ['bug'] })],
['the roadmap exemption', issueEvent({ labels: [LABEL.feature, LABEL.exempt] })],
['already closed by the bot', issueEvent({ labels: [LABEL.feature, LABEL.closed] })],
['already sent to triage', issueEvent({ labels: [LABEL.feature, LABEL.triage] })],
["the owner's own issue", issueEvent({ association: 'OWNER' })],
['a closed issue', issueEvent({ state: 'closed' })],
['an edit', issueEvent({ action: 'edited' })],
])('does nothing for %s', (_case, event) => {
expect(decide('issues', event).action).toBe('none');
});
it('does nothing without a usable issue number', () => {
expect(decide('issues', { action: 'opened', issue: { number: '7; rm -rf /' } }).action).toBe(
'none',
);
expect(decide('issues', null).action).toBe('none');
});
});
describe('decide — pull requests', () => {
it.each([
'feat: add a PDF export',
'feat(export): add a PDF export',
'feat!: drop CSV',
'FEAT(edit)!: new panel',
])('closes %j from outside the project', (title) => {
expect(decide('pull_request_target', prEvent({ title }))).toEqual({
action: 'close',
reason: 'a feature pull request from outside the project',
kind: 'pr',
number: 12,
label: LABEL.closed,
comment: PR_COMMENT,
});
});
it.each([
'fix(import): read a BOM',
'feature: something',
'docs: feat is not a prefix here',
'chore(deps): bump vite',
])('leaves %j alone', (title) => {
expect(decide('pull_request_target', prEvent({ title })).action).toBe('none');
});
it.each([
['the owner', prEvent({ association: 'OWNER' })],
['a collaborator', prEvent({ association: 'COLLABORATOR' })],
['a member', prEvent({ association: 'MEMBER' })],
['Dependabot', prEvent({ userType: 'Bot' })],
['a roadmap pull request', prEvent({ labels: [LABEL.exempt] })],
['a reopened pull request', prEvent({ action: 'reopened' })],
])('exempts %s', (_case, event) => {
expect(decide('pull_request_target', event).action).toBe('none');
});
});
describe('decide — other events', () => {
it('ignores events it does not triage', () => {
expect(decide('push', {}).action).toBe('none');
expect(decide(undefined, {}).action).toBe('none');
});
});
describe('the pieces the script shares with other files', () => {
it('matches the feature form word for word', () => {
const form = read('.github/ISSUE_TEMPLATE/feature_request.yml');
expect(form).toContain(`label: ${KIND_QUESTION}`);
for (const kind of Object.values(KIND)) expect(form).toContain(`- ${kind}`);
expect(form).toContain(`labels: [${LABEL.feature}]`);
});
it('links the policy and the ideas board, which exist', () => {
for (const comment of [ISSUE_COMMENT, PR_COMMENT]) expect(comment).toContain(POLICY_URL);
expect(ISSUE_COMMENT).toContain(IDEAS_URL);
expect(read('MAINTENANCE.md')).toContain(`\`${LABEL.closed}\``);
});
it('is what the workflow runs, with the labels the workflow re-checks', () => {
const workflow = read('.github/workflows/triage.yml');
expect(workflow).toContain('node scripts/triage.mjs');
for (const label of [LABEL.closed, LABEL.triage, LABEL.exempt])
expect(workflow).toContain(` ${label} `);
// Nothing from the event payload is interpolated into a shell line.
expect(workflow).not.toMatch(/\$\{\{\s*github\.event\.(issue|pull_request)\.(title|body)/);
});
});
+12 -5
View File
@@ -1,6 +1,7 @@
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { describe, expect, it } from 'vitest';
import { CREDITED_PACKAGES } from '../../scripts/credited-packages.mjs';
/**
* Every package the build may compile in is credited — docs/14 §5.
@@ -11,16 +12,22 @@ import { describe, expect, it } from 'vitest';
* "none" while three packages shipped.
*/
const read = (path: string): string => readFileSync(join(process.cwd(), path), 'utf8');
const CONFIG = read('wxt.config.ts');
const credited = [
...(/const CREDITED_PACKAGES = \[([^\]]*)\]/.exec(CONFIG)?.[1] ?? '').matchAll(/'([^']+)'/g),
].map((m) => m[1] ?? '');
const credited = [...CREDITED_PACKAGES];
describe('third-party notices', () => {
it('reads a non-empty credited list from wxt.config.ts', () => {
it('reads a non-empty credited list', () => {
expect(credited).toEqual(expect.arrayContaining(['svelte', 'clsx']));
});
it('is the list the build gate in wxt.config.ts enforces', () => {
// A second, local list in the config would let the build gate and this
// test disagree about what ships — the shape this file used to guard by
// parsing the config's own source.
const config = read('wxt.config.ts');
expect(config).toContain("from './scripts/credited-packages.mjs'");
expect(config).not.toMatch(/const CREDITED_PACKAGES\s*=/);
});
it.each(['legal/THIRD_PARTY_NOTICES.md', 'src/public/THIRD_PARTY_NOTICES.txt'])(
'%s names every credited package and carries an MIT notice for it',
(path) => {
+8 -12
View File
@@ -1,4 +1,5 @@
import { defineConfig } from 'wxt';
import { CREDITED_PACKAGES } from './scripts/credited-packages.mjs';
/**
* WXT configuration.
@@ -51,20 +52,11 @@ const EXTENSION_PAGE_CSP = [
"base-uri 'none'",
].join('; ');
/**
* Every npm package the build compiles into the extension, each credited in
* `legal/THIRD_PARTY_NOTICES.md` and the shipped `THIRD_PARTY_NOTICES.txt`
* (docs/14 §5). `tests/unit/third-party.test.ts` checks both files name each
* one. Until v1.1.0 the notices said "none" while Svelte's runtime, its `clsx`
* dependency and WXT's browser shim all shipped — nothing could notice.
*/
const CREDITED_PACKAGES = ['svelte', 'clsx', '@wxt-dev/browser', 'wxt'];
/** The npm package a module id lives in, or undefined for our own code. */
function packageOf(id: string): string | undefined {
const at = id.lastIndexOf('node_modules');
if (at === -1) return undefined;
const parts = id.slice(at + 'node_modules'.length + 1).split(/[/]/);
const parts = id.slice(at + 'node_modules'.length + 1).split('/');
return parts[0]?.startsWith('@') === true ? `${parts[0]}/${parts[1] ?? ''}` : parts[0];
}
@@ -76,7 +68,10 @@ interface BundleLike {
/**
* Fail the build when code from an uncredited package ships. Only modules that
* actually render count — a package imported and then tree-shaken away is not
* in the extension and needs no notice.
* in the extension and needs no notice. The list is `CREDITED_PACKAGES` in
* `scripts/credited-packages.mjs`, shared with the notices test and the licence
* gate (docs/14 §5). Until v1.1.0 the notices said "none" while Svelte's
* runtime, its `clsx` dependency and WXT's browser shim all shipped.
*/
const thirdPartyGate = {
name: 'bookmarkmagic:third-party-gate',
@@ -97,7 +92,8 @@ const thirdPartyGate = {
if (uncredited.length > 0) {
this.error(
`third-party code ships without a notice: ${uncredited.join(', ')} — add it to ` +
'CREDITED_PACKAGES, legal/THIRD_PARTY_NOTICES.md and src/public/THIRD_PARTY_NOTICES.txt',
'CREDITED_PACKAGES (scripts/credited-packages.mjs), legal/THIRD_PARTY_NOTICES.md ' +
'and src/public/THIRD_PARTY_NOTICES.txt',
);
}
},