feat: build the intake the v1.0.x plan has always assumed
docs/13 §6 stated as present-tense fact that "GitHub issues — templates route bug reports with sample files", and docs/12 §5 carried the same as an unticked box. Neither was true: .github/ held only FUNDING.yml, dependabot.yml and workflows. Meanwhile the entire v1.0.x roadmap is "fixture + test per report", which cannot happen if reports arrive without the file that broke. Five issue forms plus a chooser, blank issues disabled. parser_report.yml is the one that matters: it requires the sanitized sample, asks which browser *version* produced the file, and asks explicitly for consent to commit the sample as a GPL-3.0 fixture — it lives in a public repo forever, and nothing previously asked. scripts/sanitize-bookmarks.mjs makes "attach a sanitized sample" something a reporter can actually do. It works by span replacement rather than by reparsing, so every byte outside a replaced address or title is provably untouched: BOM, doctype, line endings, tag and attribute case, quoting, indentation and every timestamp survive, and so do the properties a parser branches on — port, path depth, trailing slash, query-parameter count and order, percent-escapes, HTML entities, and the distinctness of hosts that dedupe depends on. Its test asserts the promise rather than the implementation: for every fixture in the repo, the sanitized file must detect as the same format, parse to the same stats, warnings and topology — or fail with the same error code — and leak no original hostname. Writing it immediately found three real defects: a data: URL containing markup broke the title regex and left that bookmark's title unsanitized; an & in an HREF came back as a bare &, silently repairing the escaping of the file being reported; and Firefox's ICON_URI leaked a full hostname past every other check. The last one is why URL-valued attributes are now swept by value shape instead of by an enumerated list. scripts/gen-fixture.mjs is the generator docs/11 §2 named, .gitignore has always reserved a directory for, and the 2 s parse budget needed in order to be measurable at all. CONTRIBUTING.md collects the five-file ritual for turning a user's file into a regression test, which was previously spread across CLAUDE.md, docs/04 and docs/11 with no single entry point — including the .gitattributes rule that stops EOL normalization destroying the bytes a bug depends on. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
12 files changed
+1414
-3
No files matched your search
@@ -0,0 +1,100 @@
|
||||
name: Something else is broken
|
||||
description: Anything that is not a bookmark file failing to import.
|
||||
title: '[bug] '
|
||||
labels: [bug]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
If a **bookmark file** will not import correctly, please use the
|
||||
"A bookmark file will not import correctly" form instead — it asks for
|
||||
the one thing that makes those fixable.
|
||||
|
||||
If this is a **security** problem, do not file it here. See
|
||||
[SECURITY.md](https://github.com/poli0981/bookmarkmagic/blob/main/SECURITY.md).
|
||||
|
||||
- type: input
|
||||
id: version
|
||||
attributes:
|
||||
label: BookmarkMagic version
|
||||
description: Shown in the About tab and at the bottom of the window.
|
||||
placeholder: '1.0.0'
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: input
|
||||
id: browser
|
||||
attributes:
|
||||
label: Browser and version
|
||||
placeholder: Chrome 138, or Brave 1.79, or Edge 138
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: dropdown
|
||||
id: os
|
||||
attributes:
|
||||
label: Operating system
|
||||
options:
|
||||
- Windows
|
||||
- macOS
|
||||
- Linux
|
||||
- ChromeOS
|
||||
- Other
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: dropdown
|
||||
id: area
|
||||
attributes:
|
||||
label: Where does it happen?
|
||||
options:
|
||||
- Import
|
||||
- Export
|
||||
- Edit
|
||||
- Settings
|
||||
- About / legal gate
|
||||
- The toolbar popup
|
||||
- Somewhere else
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: steps
|
||||
attributes:
|
||||
label: Steps to reproduce
|
||||
placeholder: |
|
||||
1. Open the manager
|
||||
2. …
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: expected-actual
|
||||
attributes:
|
||||
label: What did you expect, and what happened instead?
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: console
|
||||
attributes:
|
||||
label: Console output
|
||||
description: >-
|
||||
Go to `chrome://extensions`, turn on Developer mode, and check whether
|
||||
BookmarkMagic shows an "Errors" button. If it does, paste what is
|
||||
there. Blank is a perfectly good answer.
|
||||
render: shell
|
||||
validations:
|
||||
required: false
|
||||
|
||||
- type: checkboxes
|
||||
id: confirmations
|
||||
attributes:
|
||||
label: Before submitting
|
||||
options:
|
||||
- label: >-
|
||||
Anything I attached contains no real addresses, titles or personal
|
||||
data.
|
||||
required: true
|
||||
- label: I searched the existing issues first.
|
||||
required: false
|
||||
@@ -0,0 +1,21 @@
|
||||
# Issue chooser — docs/12 §5, docs/13 §6.
|
||||
#
|
||||
# Blank issues are disabled on purpose. The whole v1.0.x plan is "fixture +
|
||||
# test per report" (docs/15), and that only works if a parser report arrives
|
||||
# with a sanitized sample. A blank issue is the path that skips that ask.
|
||||
blank_issues_enabled: false
|
||||
|
||||
contact_links:
|
||||
- name: Security vulnerability
|
||||
url: https://github.com/poli0981/bookmarkmagic/security/advisories/new
|
||||
about: Report privately, never as a public issue. See SECURITY.md.
|
||||
|
||||
- name: Rate or review on the Chrome Web Store
|
||||
url: https://chromewebstore.google.com/detail/bookmarkmagic/eghnciphhegekmnofffpgbdfefckdhmg
|
||||
about: Reviews are read, but a bug reported here gets fixed faster.
|
||||
|
||||
- name: Question, or no GitHub account
|
||||
url: mailto:contact@poli0981.dev
|
||||
about: >-
|
||||
Email works. Please do not attach your real bookmarks file — see the
|
||||
privacy policy for what happens to anything you send.
|
||||
@@ -0,0 +1,56 @@
|
||||
name: Suggest a feature
|
||||
description: An idea for something BookmarkMagic should do.
|
||||
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.
|
||||
|
||||
Everything else is genuinely open. The roadmap in that same file lists
|
||||
what is already planned.
|
||||
|
||||
- type: textarea
|
||||
id: problem
|
||||
attributes:
|
||||
label: What are you trying to do?
|
||||
description: >-
|
||||
The situation, not the solution. "I move between four machines and
|
||||
cannot tell which export is newest" tells us more than "add a
|
||||
timestamp column".
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: proposal
|
||||
attributes:
|
||||
label: What would you like it to do?
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: workaround
|
||||
attributes:
|
||||
label: How do you handle it today?
|
||||
description: Including "I don't" — that is useful signal about severity.
|
||||
validations:
|
||||
required: false
|
||||
|
||||
- type: checkboxes
|
||||
id: confirmations
|
||||
attributes:
|
||||
label: Before submitting
|
||||
options:
|
||||
- label: >-
|
||||
As far as I can tell, this would not need any new browser
|
||||
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
|
||||
@@ -0,0 +1,116 @@
|
||||
name: A bookmark file will not import correctly
|
||||
description: A file was rejected, or imported with the wrong structure, titles or dates.
|
||||
title: '[parser] '
|
||||
labels: [bug, parser]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Thank you — this is the most useful kind of report this project gets.
|
||||
A sanitized sample of the file becomes a permanent test, so the same
|
||||
bug can never come back.
|
||||
|
||||
**Please sanitize the file first.** From a clone of this repository:
|
||||
|
||||
```bash
|
||||
node scripts/sanitize-bookmarks.mjs your-file.html
|
||||
```
|
||||
|
||||
It replaces every address and title but keeps the structure, encoding
|
||||
and date format the bug actually depends on — so the sanitized file
|
||||
still reproduces the problem, without telling us where you browse.
|
||||
|
||||
- type: input
|
||||
id: source-browser
|
||||
attributes:
|
||||
label: Which browser produced the file, and which version?
|
||||
description: >-
|
||||
The exact version matters more than you would expect — export formats
|
||||
differ between browsers and change between versions.
|
||||
placeholder: Firefox 145, or Safari 18.2 on macOS, or "no idea, it is old"
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: dropdown
|
||||
id: format
|
||||
attributes:
|
||||
label: File format
|
||||
options:
|
||||
- HTML (the usual "bookmarks.html" export)
|
||||
- JSON
|
||||
- CSV
|
||||
- Not sure
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: dropdown
|
||||
id: symptom
|
||||
attributes:
|
||||
label: What went wrong?
|
||||
options:
|
||||
- The whole file was rejected
|
||||
- It imported, but folders are missing
|
||||
- It imported, but the nesting is wrong
|
||||
- It imported, but titles are mangled or empty
|
||||
- It imported, but the dates are wrong
|
||||
- Duplicates were detected wrongly (too many, or not at all)
|
||||
- Something else
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: message
|
||||
attributes:
|
||||
label: The exact message the extension showed
|
||||
description: Copy it as shown, including the technical detail block if there was one.
|
||||
render: text
|
||||
validations:
|
||||
required: false
|
||||
|
||||
- type: textarea
|
||||
id: expected
|
||||
attributes:
|
||||
label: What did you expect instead?
|
||||
description: >-
|
||||
For a structure problem, describing the shape you expected — "these
|
||||
three folders should be inside Bookmarks Bar" — is usually enough.
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: sample
|
||||
attributes:
|
||||
label: Sanitized sample file
|
||||
description: >-
|
||||
Drag the sanitized file into this box to attach it. If the file is
|
||||
large, a trimmed sanitized version that still reproduces the problem is
|
||||
better than a complete one.
|
||||
placeholder: Attach the file here.
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: input
|
||||
id: version
|
||||
attributes:
|
||||
label: BookmarkMagic version
|
||||
description: Shown in the About tab and at the bottom of the window.
|
||||
placeholder: '1.0.0'
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: checkboxes
|
||||
id: confirmations
|
||||
attributes:
|
||||
label: Before submitting
|
||||
options:
|
||||
- label: >-
|
||||
I ran the sanitizer, or I checked the file by hand and it contains
|
||||
no real addresses, titles or personal data.
|
||||
required: true
|
||||
- label: >-
|
||||
I agree that this sanitized sample may be committed to this
|
||||
repository as a test fixture under GPL-3.0, where it will stay
|
||||
permanently and publicly.
|
||||
required: true
|
||||
- label: I searched the existing issues first.
|
||||
required: false
|
||||
@@ -0,0 +1,73 @@
|
||||
name: A translation is wrong or awkward
|
||||
description: Vietnamese or Japanese wording that is incorrect, unnatural, or untranslated.
|
||||
title: '[i18n] '
|
||||
labels: [i18n]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Native speakers are the only people who can catch this. English is the
|
||||
source language; Vietnamese is reviewed by the maintainer and Japanese
|
||||
is best-effort until a native pass, so JA reports are especially
|
||||
welcome.
|
||||
|
||||
You do **not** need to open a pull request or install anything — just
|
||||
tell us the wording. If you would rather send the change yourself,
|
||||
[CONTRIBUTING.md](https://github.com/poli0981/bookmarkmagic/blob/main/CONTRIBUTING.md)
|
||||
has the whole path.
|
||||
|
||||
- type: dropdown
|
||||
id: locale
|
||||
attributes:
|
||||
label: Language
|
||||
options:
|
||||
- Tiếng Việt (vi)
|
||||
- 日本語 (ja)
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: input
|
||||
id: location
|
||||
attributes:
|
||||
label: Where does the text appear?
|
||||
description: >-
|
||||
A tab name and a description is plenty — "the Export tab, on the CSV
|
||||
format card". If you happen to know the key path from
|
||||
`src/lib/i18n/locales/`, even better.
|
||||
placeholder: Settings tab, the theme row — or export.formats.csv.hint
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: current
|
||||
attributes:
|
||||
label: Current text
|
||||
description: Copy it exactly as it appears.
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: proposed
|
||||
attributes:
|
||||
label: Suggested text
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: why
|
||||
attributes:
|
||||
label: Why is the current wording wrong?
|
||||
description: >-
|
||||
Grammar, register, an unnatural loanword, a term inconsistent with the
|
||||
rest of the UI — whatever it is. This is the part that makes the change
|
||||
reviewable by someone who does not speak the language.
|
||||
validations:
|
||||
required: false
|
||||
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
**One constraint worth knowing:** placeholders like `{n}` or `{name}`
|
||||
must appear in the translation exactly as they do in English — same
|
||||
names, same count. A build gate enforces it, so a suggestion that drops
|
||||
one cannot be merged as-is.
|
||||
@@ -0,0 +1,47 @@
|
||||
<!--
|
||||
Thank you for sending a patch. Delete anything below that does not apply —
|
||||
a translation fix does not need the parser section, and vice versa.
|
||||
-->
|
||||
|
||||
## What and why
|
||||
|
||||
<!-- What changes, and what problem it solves. Link the issue if there is one. -->
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] `npm run verify` is green. (Release-bearing? `npm run verify:full` —
|
||||
`verify` does not run coverage, build or the built-manifest gate.)
|
||||
- [ ] Conventional Commits title (`fix(import): …`, `feat(edit): …`, `docs: …`).
|
||||
- [ ] `CHANGELOG.md` `[Unreleased]` updated, if a user would notice this.
|
||||
|
||||
### If it changes behaviour
|
||||
|
||||
- [ ] The relevant `docs/` chapter is updated. **The docs are the specification
|
||||
here** — when code and docs disagree, the docs win, so a behaviour change
|
||||
that skips the doc leaves the spec lying.
|
||||
|
||||
### If it touches user-visible text
|
||||
|
||||
- [ ] The key exists in **all three** locales — `en`, `vi`, `ja`. `en.ts` is the
|
||||
schema; `vi`/`ja` use `satisfies Dict`, so a missing key fails the type
|
||||
check. Never add `as const` to a locale file.
|
||||
- [ ] Interpolation tokens (`{n}`, `{name}`) match across all three.
|
||||
|
||||
### If it is a parser fix
|
||||
|
||||
- [ ] A fixture is committed under `tests/fixtures/`, sanitized, with the
|
||||
reporter's consent recorded in the issue.
|
||||
- [ ] A regression test lands **in this same PR** — a fixture with no test is
|
||||
just a file.
|
||||
- [ ] The quirk is noted in the parser source **and** in `docs/04 §1.2`.
|
||||
- [ ] `docs/11 §2`'s inventory lists the new fixture.
|
||||
|
||||
### Things that are never OK
|
||||
|
||||
- [ ] No new runtime dependency. (Zero is the number, and it is a public claim
|
||||
in the store listing and the README. A new dep needs approval first —
|
||||
`docs/01 §4`.)
|
||||
- [ ] No new permission. The manifest is exactly `["bookmarks", "storage"]`, and
|
||||
changing that is a minor-version event that also requires re-certifying
|
||||
the Chrome Web Store privacy answers.
|
||||
- [ ] No `fetch`, `eval`, `{@html}` or `innerHTML`. `npm run guard` enforces it.
|
||||
@@ -0,0 +1,71 @@
|
||||
# Code of Conduct
|
||||
|
||||
## Our pledge
|
||||
|
||||
We as members, contributors, and leaders pledge to make participation in our
|
||||
community a harassment-free experience for everyone, regardless of age, body
|
||||
size, visible or invisible disability, ethnicity, sex characteristics, gender
|
||||
identity and expression, level of experience, education, socio-economic status,
|
||||
nationality, personal appearance, race, caste, color, religion, or sexual
|
||||
identity and orientation.
|
||||
|
||||
We pledge to act and interact in ways that contribute to an open, welcoming,
|
||||
diverse, inclusive, and healthy community.
|
||||
|
||||
## Our standards
|
||||
|
||||
Examples of behavior that contributes to a positive environment:
|
||||
|
||||
- Demonstrating empathy and kindness toward other people
|
||||
- Being respectful of differing opinions, viewpoints, and experiences
|
||||
- Giving and gracefully accepting constructive feedback
|
||||
- Accepting responsibility and apologizing to those affected by our mistakes,
|
||||
and learning from the experience
|
||||
- Focusing on what is best not just for us as individuals, but for the overall
|
||||
community
|
||||
|
||||
Examples of unacceptable behavior:
|
||||
|
||||
- The use of sexualized language or imagery, and sexual attention or advances of
|
||||
any kind
|
||||
- Trolling, insulting or derogatory comments, and personal or political attacks
|
||||
- Public or private harassment
|
||||
- Publishing others' private information, such as a physical or email address,
|
||||
without their explicit permission
|
||||
- Other conduct which could reasonably be considered inappropriate in a
|
||||
professional setting
|
||||
|
||||
## Enforcement responsibilities
|
||||
|
||||
Project maintainers are responsible for clarifying and enforcing these standards
|
||||
and will take appropriate and fair corrective action in response to any behavior
|
||||
that they deem inappropriate, threatening, offensive, or harmful.
|
||||
|
||||
Maintainers have the right and responsibility to remove, edit, or reject
|
||||
comments, commits, code, issues, and other contributions that are not aligned to
|
||||
this Code of Conduct, and will communicate reasons for moderation decisions when
|
||||
appropriate.
|
||||
|
||||
## Scope
|
||||
|
||||
This Code of Conduct applies within all community spaces — the issue tracker,
|
||||
pull requests, discussions and any project communication channel — and also
|
||||
applies when an individual is officially representing the project in public
|
||||
spaces.
|
||||
|
||||
## Enforcement
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be
|
||||
reported to the maintainers at **contact@poli0981.dev**. All complaints will be
|
||||
reviewed and investigated promptly and fairly.
|
||||
|
||||
Maintainers are obligated to respect the privacy and security of the reporter of
|
||||
any incident.
|
||||
|
||||
## Attribution
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
|
||||
version 2.1, available at
|
||||
<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.
|
||||
|
||||
[homepage]: https://www.contributor-covenant.org
|
||||
+146
@@ -0,0 +1,146 @@
|
||||
# Contributing to BookmarkMagic
|
||||
|
||||
Bug reports, parser samples and translation fixes are all genuinely useful, and
|
||||
none of them requires you to write code. If you only want to report something,
|
||||
[open an issue](https://github.com/poli0981/bookmarkmagic/issues/new/choose) and
|
||||
stop reading here — the forms ask for what is needed.
|
||||
|
||||
Security problems go through [`SECURITY.md`](SECURITY.md), never a public issue.
|
||||
|
||||
## Reporting a bookmark file that will not import
|
||||
|
||||
This is the most valuable report this project gets, because a sample becomes a
|
||||
permanent test and the bug can then never come back.
|
||||
|
||||
**Sanitize the file first.** From a clone of this repository:
|
||||
|
||||
```bash
|
||||
node scripts/sanitize-bookmarks.mjs your-bookmarks.html
|
||||
```
|
||||
|
||||
It needs nothing installed — plain Node. It writes
|
||||
`your-bookmarks.sanitized.html` next to the original, and prints what it found.
|
||||
|
||||
What it **destroys**: every hostname, path, query value and fragment; every
|
||||
bookmark and folder title; Firefox keywords and tags; favicon data.
|
||||
|
||||
What it **keeps**, because this is where the bug lives: the byte order mark, the
|
||||
doctype, the `<META>` line, comments, line endings, indentation, tag and
|
||||
attribute **case**, quoting style, attribute order, the tree's shape and depth,
|
||||
every timestamp exactly as written, whether a URL had a port, how deep its path
|
||||
was, whether it ended in a slash, how many query parameters it had, whether
|
||||
there was a fragment, any percent-escapes, and any HTML entities in a title.
|
||||
Distinct hosts stay distinct, so duplicate-detection bugs survive too.
|
||||
|
||||
That combination is the point: the sanitized file still reproduces the problem,
|
||||
without telling us where you browse. A test in `tests/unit/scripts/` asserts
|
||||
exactly that against every fixture in the repo.
|
||||
|
||||
Please do not send a real bookmarks file — an export is a browsing history.
|
||||
Anything you attach to a GitHub issue is public and permanent; see
|
||||
[`legal/PRIVACY.md`](legal/PRIVACY.md) for what happens to anything you email.
|
||||
|
||||
## Suggesting a translation fix
|
||||
|
||||
You do not need to clone anything. Use the translation issue form: the language,
|
||||
where the text appears, what it says now, and what it should say. Vietnamese is
|
||||
reviewed by the maintainer; **Japanese is best-effort until a native pass**, so
|
||||
JA corrections are especially welcome.
|
||||
|
||||
One constraint if you send the change yourself: placeholders like `{n}` or
|
||||
`{name}` must appear in the translation exactly as in English — same names, same
|
||||
count. A build gate enforces it.
|
||||
|
||||
## Setting up to write code
|
||||
|
||||
Node **24 or newer** (see `.nvmrc`).
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
npx wxt prepare
|
||||
npm run verify
|
||||
```
|
||||
|
||||
`wxt prepare` is not optional: `tsconfig.json` extends `./.wxt/tsconfig.json`,
|
||||
which does not exist until it has run.
|
||||
|
||||
> **Using a git worktree?** It needs its own `npm ci` *and* `npx wxt prepare`.
|
||||
> With an empty `node_modules/` the packages resolve upward from the parent
|
||||
> checkout and almost everything appears to work — but knip then reports every
|
||||
> devDependency as unused and `verify` fails in a way that looks like your
|
||||
> change broke something.
|
||||
|
||||
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
|
||||
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
|
||||
release tag enforce.
|
||||
|
||||
## The rules that are not negotiable
|
||||
|
||||
These are what the extension promises in its store listing and privacy policy,
|
||||
so they are not style preferences:
|
||||
|
||||
- **Zero runtime dependencies.** Not "few". A new one needs discussion first.
|
||||
- **Exactly two permissions**, `bookmarks` and `storage`. Changing that list is
|
||||
a minor-version event that also requires re-certifying the store's privacy
|
||||
answers.
|
||||
- **No network access of any kind** — no `fetch`, `XMLHttpRequest`, `WebSocket`,
|
||||
`EventSource` or `sendBeacon`. `npm run guard` fails the build on any of them.
|
||||
- **No `eval`, `{@html}` or `innerHTML`.** File content reaches the DOM as text.
|
||||
- `src/lib/core/` is pure: it imports nothing from `browser/`, `stores/`, Svelte
|
||||
or `chrome.*`.
|
||||
- Files stay under 300 lines (hard limit 500), functions under 50 (hard 80).
|
||||
- Every user-visible string is an i18n key present in **all three** locales.
|
||||
|
||||
[`CLAUDE.md`](CLAUDE.md) is the entry point and [`docs/`](docs/) is the binding
|
||||
specification — **where code and docs disagree, the docs win.** A behaviour
|
||||
change that skips its doc leaves the spec lying, which is why the PR checklist
|
||||
asks about it.
|
||||
|
||||
## Turning a reported file into a regression test
|
||||
|
||||
The full ritual, in order, because it is easy to do four fifths of it:
|
||||
|
||||
1. **Commit the sanitized sample** to `tests/fixtures/` (or `weird/`, or
|
||||
`malformed/`). Note that `.gitattributes` sets `tests/fixtures/** -text`, so
|
||||
line-ending normalization cannot rewrite the CRLF or BOM bytes the bug may
|
||||
depend on — do not "fix" that.
|
||||
2. **Add the regression test** to `tests/unit/core/fixtures.test.ts`, the only
|
||||
fixture-driven suite. A browser export goes in its `BROWSER_EXPORTS` array,
|
||||
which drives a shared set of assertions; anything else gets its own case.
|
||||
There is no shared fixture-loading helper — that file has its own loader.
|
||||
3. **Fix the parser** in `src/lib/core/parse/`. The test and the fix land in the
|
||||
**same** pull request; a fixture with no test is just a file.
|
||||
4. **Write the quirk down** in the parser source *and* in `docs/04 §1.2`. The
|
||||
format chapter is where the next person looks to understand why the code is
|
||||
shaped oddly.
|
||||
5. **Update** `docs/11 §2`'s inventory and `CHANGELOG.md`'s `[Unreleased]`.
|
||||
|
||||
If the fix changes what a format is able to preserve, that is a specification
|
||||
change: update `docs/04` first, then `tests/helpers/tree.ts`'s `project()` — it
|
||||
models each format's documented lossiness, and widening it without the doc turns
|
||||
a real regression into a passing test.
|
||||
|
||||
## Translations, in code
|
||||
|
||||
`src/lib/i18n/locales/en.ts` is the schema; `vi.ts` and `ja.ts` are typed
|
||||
`satisfies Dict` against it, so a missing key is a compile error.
|
||||
|
||||
**Never add `as const` to `en.ts`.** It would make `Dict` a tree of string
|
||||
*literal* types, and every correct translation would become a type error — the
|
||||
only way to make the build pass would be leaving VI and JA in English.
|
||||
|
||||
Four gates run on every change: identical key paths across the three locales,
|
||||
identical interpolation tokens per string, no empty leaves, and plural keys
|
||||
carrying exactly `{one, other}` everywhere. See `docs/07` for register and tone
|
||||
(VI: neutral-friendly, "bạn"; JA: です/ます with katakana loanwords).
|
||||
|
||||
## Commits and pull requests
|
||||
|
||||
Conventional Commits (`fix(import): …`, `feat(edit): …`, `docs: …`,
|
||||
`chore(deps): …`). Small commits, one concern each; tests land with or before
|
||||
the implementation. The PR template lists the rest.
|
||||
@@ -88,9 +88,23 @@ code and docs disagree, the docs win. Start with [`CLAUDE.md`](CLAUDE.md), then
|
||||
|
||||
## Contributing
|
||||
|
||||
Bug reports and translation fixes are welcome via
|
||||
[issues](https://github.com/poli0981/bookmarkmagic/issues). A bug report about
|
||||
parsing is far more useful with a sanitized sample of the file that broke.
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
node scripts/sanitize-bookmarks.mjs your-bookmarks.html
|
||||
```
|
||||
|
||||
That strips every address and title but keeps the structure, encoding and
|
||||
timestamps a parser bug depends on — so the sanitized file still reproduces the
|
||||
problem without handing over your browsing history.
|
||||
|
||||
[`CONTRIBUTING.md`](CONTRIBUTING.md) has the rest: the setup, the rules that are
|
||||
not negotiable, and how a reported file becomes a regression test.
|
||||
|
||||
Security issues: please follow [`SECURITY.md`](SECURITY.md) rather than opening
|
||||
a public issue.
|
||||
|
||||
@@ -0,0 +1,126 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Generate a large Netscape bookmark file on demand.
|
||||
*
|
||||
* Purpose: make the two measurements docs/11 asks for actually runnable — the
|
||||
* 10 000-node responsiveness item in §5, and the 100 000-node parse budget in
|
||||
* §6 that has only ever been measured under jsdom.
|
||||
* Inputs: a node count and an output path.
|
||||
* Guarantees: exactly `--nodes` nodes (folders + bookmarks), valid Netscape
|
||||
* HTML, deterministic for a given seed — so two runs are comparable.
|
||||
*
|
||||
* docs/11 §2 named a `generate-huge.ts` for this and `.gitignore` has always
|
||||
* reserved `tests/fixtures/generated/` for its output, but the script itself was
|
||||
* never written, which is why the 2 s budget stayed unmeasured (docs/00 §10.8).
|
||||
*
|
||||
* Usage:
|
||||
* node scripts/gen-fixture.mjs --nodes 10000 --out tests/fixtures/generated/big.html
|
||||
* node scripts/gen-fixture.mjs --nodes 100000 --per-folder 100 --seed 7 --out …
|
||||
*/
|
||||
import { mkdirSync, writeFileSync } from 'node:fs';
|
||||
import { dirname } from 'node:path';
|
||||
|
||||
/** Mulberry32 — small, seeded, and good enough for shaping test data. */
|
||||
function rng(seed) {
|
||||
let a = seed >>> 0;
|
||||
return () => {
|
||||
a = (a + 0x6d2b79f5) >>> 0;
|
||||
let t = Math.imul(a ^ (a >>> 15), 1 | a);
|
||||
t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
|
||||
return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
|
||||
};
|
||||
}
|
||||
|
||||
function parseArgs(argv) {
|
||||
const out = { nodes: 10_000, perFolder: 50, seed: 1, out: undefined };
|
||||
for (let i = 0; i < argv.length; i += 2) {
|
||||
const key = argv[i];
|
||||
const value = argv[i + 1];
|
||||
if (key === '--nodes') out.nodes = Number(value);
|
||||
else if (key === '--per-folder') out.perFolder = Number(value);
|
||||
else if (key === '--seed') out.seed = Number(value);
|
||||
else if (key === '--out') out.out = value;
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
/**
|
||||
* Titles that exercise the escaping path, not just ASCII.
|
||||
*
|
||||
* A 100k file of `Bookmark 1..n` would measure string concatenation and nothing
|
||||
* else; entities, CJK and emoji are what the parser actually spends time on.
|
||||
*/
|
||||
const TITLE_POOL = [
|
||||
'Example bookmark',
|
||||
'Quotes "here"',
|
||||
'Ampersand & more',
|
||||
'Angle <brackets>',
|
||||
'ブックマーク',
|
||||
'Thư mục quan trọng',
|
||||
'🌸 emoji title',
|
||||
'A rather long bookmark title that wraps in most reasonable window widths',
|
||||
];
|
||||
|
||||
function build({ nodes, perFolder, seed }) {
|
||||
const rand = rng(seed);
|
||||
const lines = [
|
||||
'<!DOCTYPE NETSCAPE-Bookmark-file-1>',
|
||||
'<!-- Generated by scripts/gen-fixture.mjs — not a real export. -->',
|
||||
'<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8">',
|
||||
'<TITLE>Bookmarks</TITLE>',
|
||||
'<H1>Bookmarks</H1>',
|
||||
'<DL><p>',
|
||||
];
|
||||
|
||||
let written = 0;
|
||||
let folderIndex = 0;
|
||||
const indent = (depth) => ' '.repeat(depth);
|
||||
|
||||
// Depth 3 so the walk is exercised, but nowhere near the 200 cap — this file
|
||||
// is for measuring the common case, not the limit.
|
||||
const emitFolder = (depth) => {
|
||||
if (written >= nodes) return;
|
||||
folderIndex++;
|
||||
const stamp = 1700000000 + folderIndex;
|
||||
lines.push(
|
||||
`${indent(depth)}<DT><H3 ADD_DATE="${stamp}" LAST_MODIFIED="${stamp + 1}"${
|
||||
folderIndex === 1 ? ' PERSONAL_TOOLBAR_FOLDER="true"' : ''
|
||||
}>Folder ${folderIndex}</H3>`,
|
||||
`${indent(depth)}<DL><p>`,
|
||||
);
|
||||
written++;
|
||||
|
||||
const count = Math.min(perFolder, nodes - written);
|
||||
for (let i = 0; i < count; i++) {
|
||||
const title = TITLE_POOL[Math.floor(rand() * TITLE_POOL.length)];
|
||||
const stampB = 1700000000 + written;
|
||||
lines.push(
|
||||
`${indent(depth + 1)}<DT><A HREF="https://host${written % 997}.example/p${written}?q=${written}" ` +
|
||||
`ADD_DATE="${stampB}">${title}</A>`,
|
||||
);
|
||||
written++;
|
||||
}
|
||||
|
||||
if (depth < 3 && written < nodes) emitFolder(depth + 1);
|
||||
lines.push(`${indent(depth)}</DL><p>`);
|
||||
};
|
||||
|
||||
while (written < nodes) emitFolder(1);
|
||||
lines.push('</DL><p>', '');
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
const options = parseArgs(process.argv.slice(2));
|
||||
|
||||
if (options.out === undefined || !Number.isFinite(options.nodes) || options.nodes < 1) {
|
||||
console.error(
|
||||
'usage: node scripts/gen-fixture.mjs --nodes <n> --out <path> [--per-folder <n>] [--seed <n>]',
|
||||
);
|
||||
process.exitCode = 1;
|
||||
} else {
|
||||
const html = build(options);
|
||||
mkdirSync(dirname(options.out), { recursive: true });
|
||||
writeFileSync(options.out, html);
|
||||
const mb = (Buffer.byteLength(html) / 1024 / 1024).toFixed(1);
|
||||
console.error(`wrote ${options.out} — ${options.nodes} nodes, ${mb} MB`);
|
||||
}
|
||||
@@ -0,0 +1,476 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Strip personal data from a bookmark file, keeping the bug.
|
||||
*
|
||||
* Purpose: make "attach a sanitized sample" (SECURITY.md, the parser issue
|
||||
* form) something a reporter can actually do, instead of an instruction they
|
||||
* have to interpret.
|
||||
* Inputs: a Netscape HTML, BookmarkMagic JSON, or CSV bookmark file.
|
||||
* Guarantees: every byte outside a replaced address or title is untouched —
|
||||
* including the BOM, the doctype, line endings, tag and attribute case,
|
||||
* quoting style, indentation, and every timestamp. Replacements are stable
|
||||
* per distinct input value, so "how many distinct hosts" and "which two
|
||||
* bookmarks are duplicates" survive.
|
||||
*
|
||||
* Zero dependencies, Node stdlib only, no network. It has to run from a fresh
|
||||
* clone with nothing installed, which is also why it re-implements a three-line
|
||||
* format sniff rather than importing `src/lib/core/detect-format.ts`.
|
||||
*
|
||||
* Usage:
|
||||
* node scripts/sanitize-bookmarks.mjs <input> [output]
|
||||
* node scripts/sanitize-bookmarks.mjs <input> --stdout
|
||||
* node scripts/sanitize-bookmarks.mjs <input> --check # report, write nothing
|
||||
*/
|
||||
import { readFileSync, writeFileSync } from 'node:fs';
|
||||
import { basename, extname } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
/** Matches docs/09's parse cap. A 25 MB attachment helps nobody anyway. */
|
||||
const MAX_BYTES = 25 * 1024 * 1024;
|
||||
|
||||
/** 1×1 transparent PNG. Keeps ICON= present, which is what the parser reacts to. */
|
||||
const BLANK_ICON =
|
||||
'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=';
|
||||
|
||||
// ---------------------------------------------------------------- format sniff
|
||||
|
||||
/** @param {string} text */
|
||||
export function detectKind(text) {
|
||||
const body = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
|
||||
if (/NETSCAPE-Bookmark-file-1/i.test(body.slice(0, 512))) return 'html';
|
||||
const trimmed = body.trimStart();
|
||||
if (trimmed.startsWith('{')) {
|
||||
try {
|
||||
JSON.parse(trimmed);
|
||||
return 'json';
|
||||
} catch {
|
||||
// Not JSON after all; fall through.
|
||||
}
|
||||
}
|
||||
if (/<\s*dl[\s>]/i.test(body)) return 'html';
|
||||
return 'csv';
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------- mappers
|
||||
|
||||
/**
|
||||
* Replace addresses while preserving everything a parser branches on: the
|
||||
* scheme, whether there is a port, how deep the path is, whether it ends in a
|
||||
* slash, how many query parameters there are and in what order, and whether
|
||||
* there is a fragment. Percent-escapes are carried across literally, so a
|
||||
* decoding bug still reproduces.
|
||||
*/
|
||||
function makeUrlMapper() {
|
||||
const seen = new Map();
|
||||
const hosts = new Map();
|
||||
|
||||
const hostAlias = (host) => {
|
||||
let alias = hosts.get(host);
|
||||
if (alias === undefined) {
|
||||
const n = hosts.size;
|
||||
// a.example … z.example, then a1.example, a2.example …
|
||||
const letter = String.fromCharCode(97 + (n % 26));
|
||||
const round = Math.floor(n / 26);
|
||||
alias = round === 0 ? `${letter}.example` : `${letter}${round}.example`;
|
||||
hosts.set(host, alias);
|
||||
}
|
||||
return alias;
|
||||
};
|
||||
|
||||
const escapesIn = (segment) => (segment.match(/%[0-9a-fA-F]{2}/g) ?? []).join('');
|
||||
|
||||
const mapPath = (pathname) => {
|
||||
if (pathname === '' || pathname === '/') return pathname;
|
||||
const trailing = pathname.endsWith('/');
|
||||
const parts = pathname.replace(/^\//, '').replace(/\/$/, '').split('/');
|
||||
const mapped = parts.map((p, i) => (p === '' ? '' : `p${i + 1}${escapesIn(p)}`));
|
||||
return `/${mapped.join('/')}${trailing ? '/' : ''}`;
|
||||
};
|
||||
|
||||
const mapQuery = (search) => {
|
||||
if (search === '') return '';
|
||||
return `?${search
|
||||
.slice(1)
|
||||
.split('&')
|
||||
.map((pair, i) => (pair.includes('=') ? `q${i + 1}=v${i + 1}` : `q${i + 1}`))
|
||||
.join('&')}`;
|
||||
};
|
||||
|
||||
return (raw) => {
|
||||
if (raw === '') return raw;
|
||||
const cached = seen.get(raw);
|
||||
if (cached !== undefined) return cached;
|
||||
|
||||
let out;
|
||||
let url;
|
||||
try {
|
||||
url = new URL(raw);
|
||||
} catch {
|
||||
url = undefined;
|
||||
}
|
||||
|
||||
if (url === undefined) {
|
||||
// Keep it unparseable, and keep distinct values distinct — the dedupe
|
||||
// path treats an unparseable URL as its own trimmed self.
|
||||
out = `not-a-url-${seen.size + 1}`;
|
||||
} else if (url.host === '') {
|
||||
// Opaque scheme (javascript:, data:, mailto:). The scheme is the whole
|
||||
// point for the T1/T3 threat cases; the payload is not ours to keep.
|
||||
out = `${url.protocol}sanitized-${seen.size + 1}`;
|
||||
} else {
|
||||
// Credentials are never round-tripped, not even as placeholders.
|
||||
const port = url.port === '' ? '' : `:${url.port}`;
|
||||
const hash = url.hash === '' ? '' : '#frag';
|
||||
out = `${url.protocol}//${hostAlias(url.host.replace(/:\d+$/, ''))}${port}${mapPath(url.pathname)}${mapQuery(url.search)}${hash}`;
|
||||
}
|
||||
|
||||
seen.set(raw, out);
|
||||
return out;
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Replace titles while preserving what encoding bugs live in: emptiness, the
|
||||
* scripts present (so a CJK or RTL or emoji bug still reproduces), and any HTML
|
||||
* entity references, which are carried across verbatim.
|
||||
*/
|
||||
function makeTitleMapper() {
|
||||
const seen = new Map();
|
||||
const SCRIPTS = [
|
||||
[/[一-鿿-ヿ]/, '文字'],
|
||||
[/[-ࣿ]/, 'شيء'],
|
||||
[/[\p{Extended_Pictographic}]/u, '🌸'],
|
||||
];
|
||||
|
||||
return (raw) => {
|
||||
if (raw.trim() === '') return raw;
|
||||
const cached = seen.get(raw);
|
||||
if (cached !== undefined) return cached;
|
||||
|
||||
const entities = (raw.match(/&(?:#\d+|#x[0-9a-fA-F]+|[a-zA-Z]+);/g) ?? []).join('');
|
||||
const extras = SCRIPTS.filter(([re]) => re.test(raw))
|
||||
.map(([, sample]) => sample)
|
||||
.join('');
|
||||
const out = `Title ${seen.size + 1}${extras === '' ? '' : ` ${extras}`}${entities}`;
|
||||
seen.set(raw, out);
|
||||
return out;
|
||||
};
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------ span rewriting
|
||||
|
||||
/**
|
||||
* Apply replacements by character span, right to left.
|
||||
*
|
||||
* Everything this tool does is expressed as spans so that the bytes between
|
||||
* them are provably untouched — that is the property the whole exercise rests
|
||||
* on, and rebuilding the file from a parsed model would quietly lose it.
|
||||
*
|
||||
* @param {string} text
|
||||
* @param {{start: number, end: number, value: string}[]} spans
|
||||
*/
|
||||
function replaceSpans(text, spans) {
|
||||
let out = text;
|
||||
for (const span of [...spans].sort((a, b) => b.start - a.start)) {
|
||||
out = out.slice(0, span.start) + span.value + out.slice(span.end);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
/**
|
||||
* Collect spans for one capture group of a global regex. `map` receives the
|
||||
* captured text.
|
||||
*
|
||||
* The group's offset is computed by re-scanning the match, so the regex must
|
||||
* capture a span that appears only once within it — true for every pattern
|
||||
* here, since each captures an attribute value or an element's text.
|
||||
*
|
||||
* @param {string} text
|
||||
* @param {RegExp} re
|
||||
* @param {(captured: string) => string} map
|
||||
* @param {number} [group]
|
||||
*/
|
||||
function spansFrom(text, re, map, group = 1) {
|
||||
const spans = [];
|
||||
for (const m of text.matchAll(re)) {
|
||||
const captured = m[group] ?? '';
|
||||
if (captured === '') continue;
|
||||
const start = m.index + m[0].lastIndexOf(captured);
|
||||
spans.push({ start, end: start + captured.length, value: map(captured) });
|
||||
}
|
||||
return spans;
|
||||
}
|
||||
|
||||
/**
|
||||
* The inside of an opening tag, tolerating `>` within quoted attribute values.
|
||||
*
|
||||
* `data:text/html,<h1>hi</h1>` is a legal HREF and appears in the T1/T3
|
||||
* fixtures. A naive `[^>]*` stops inside it, silently leaving that bookmark's
|
||||
* title unsanitized — which is the one failure mode this tool must not have.
|
||||
*/
|
||||
const TAG_INNARDS = '(?:"[^"]*"|\'[^\']*\'|[^>"\'])*';
|
||||
|
||||
// ------------------------------------------------------------------ formats
|
||||
|
||||
/**
|
||||
* Decode an HTML attribute value, then re-encode the result the way the source
|
||||
* file encoded it.
|
||||
*
|
||||
* Netscape exports write `&` inside HREF, but not all of them do, and
|
||||
* whether a parser unescapes attribute values is itself something people report
|
||||
* bugs about. Emitting a bare `&` where the source had `&` would silently
|
||||
* repair the file being reported.
|
||||
*/
|
||||
function attrRewriter(map) {
|
||||
return (captured) => {
|
||||
const decoded = captured
|
||||
.replace(/&/gi, '&')
|
||||
.replace(/</gi, '<')
|
||||
.replace(/>/gi, '>')
|
||||
.replace(/"/gi, '"');
|
||||
const mapped = map(decoded);
|
||||
const escapesAmp = /&/i.test(captured) || !captured.includes('&');
|
||||
return escapesAmp ? mapped.replace(/&/g, '&') : mapped;
|
||||
};
|
||||
}
|
||||
|
||||
/** Attributes handled explicitly; the generic URL sweep must not touch them. */
|
||||
const HANDLED_ATTRS = new Set(['href', 'icon']);
|
||||
|
||||
/**
|
||||
* Scrub any *other* attribute whose value is a URL with a host.
|
||||
*
|
||||
* Firefox alone writes `ICON_URI`, and `FEEDURL` and friends exist in the wild.
|
||||
* Enumerating them was already wrong once — `ICON_URI` leaked a real hostname
|
||||
* through a file that had passed every other check — so this sweeps by value
|
||||
* shape instead, and covers attributes nobody has thought of yet.
|
||||
*/
|
||||
function urlAttrSpans(text, mapUrl) {
|
||||
const spans = [];
|
||||
const rewrite = attrRewriter(mapUrl);
|
||||
for (const m of text.matchAll(/\b([a-z_][a-z0-9_-]*)\s*=\s*"([^"]*)"/gi)) {
|
||||
const name = (m[1] ?? '').toLowerCase();
|
||||
const value = m[2] ?? '';
|
||||
if (HANDLED_ATTRS.has(name) || value === '') continue;
|
||||
try {
|
||||
if (new URL(value).host === '') continue;
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
const start = m.index + m[0].lastIndexOf(value);
|
||||
spans.push({ start, end: start + value.length, value: rewrite(value) });
|
||||
}
|
||||
return spans;
|
||||
}
|
||||
|
||||
function sanitizeHtml(text, mapUrl, mapTitle) {
|
||||
let descriptions = 0;
|
||||
let keywords = 0;
|
||||
const spans = [
|
||||
// HREF="…" and ICON="…" — attribute name case is left exactly as found.
|
||||
...spansFrom(text, /\bhref\s*=\s*"([^"]*)"/gi, attrRewriter(mapUrl)),
|
||||
...spansFrom(text, /\bicon\s*=\s*"([^"]*)"/gi, () => BLANK_ICON),
|
||||
...urlAttrSpans(text, mapUrl),
|
||||
// Firefox keywords and tags are user-authored text, so they are personal
|
||||
// too. Tag count is preserved because it is the only part a parser sees.
|
||||
...spansFrom(text, /\bshortcuturl\s*=\s*"([^"]*)"/gi, () => `kw${++keywords}`),
|
||||
...spansFrom(text, /\btags\s*=\s*"([^"]*)"/gi, (v) =>
|
||||
v
|
||||
.split(',')
|
||||
.map((_, i) => `tag${i + 1}`)
|
||||
.join(','),
|
||||
),
|
||||
// Bookmark titles: the text between <A …> and </A>.
|
||||
...spansFrom(text, new RegExp(`<a\\b${TAG_INNARDS}>([^<]*)</a>`, 'gi'), mapTitle),
|
||||
// Folder titles.
|
||||
...spansFrom(text, new RegExp(`<h3\\b${TAG_INNARDS}>([^<]*)</h3>`, 'gi'), mapTitle),
|
||||
// Folder/bookmark descriptions.
|
||||
...spansFrom(text, /<dd>([^\n<]*)/gi, () => `Description ${++descriptions}`),
|
||||
];
|
||||
return replaceSpans(text, spans);
|
||||
}
|
||||
|
||||
/**
|
||||
* Rewrite only the *values* of `url` and `title` string properties, by walking
|
||||
* the raw text. Parsing and re-stringifying would normalize the indentation and
|
||||
* line endings, which is exactly what a whitespace-sensitive report needs kept.
|
||||
*/
|
||||
function sanitizeJson(text, mapUrl, mapTitle) {
|
||||
const spans = [];
|
||||
const re = /"(url|title)"\s*:\s*"((?:[^"\\]|\\.)*)"/g;
|
||||
for (const m of text.matchAll(re)) {
|
||||
const key = m[1];
|
||||
const rawValue = m[2] ?? '';
|
||||
const start = m.index + m[0].length - 1 - rawValue.length;
|
||||
let decoded;
|
||||
try {
|
||||
decoded = JSON.parse(`"${rawValue}"`);
|
||||
} catch {
|
||||
decoded = rawValue;
|
||||
}
|
||||
const mapped = key === 'url' ? mapUrl(decoded) : mapTitle(decoded);
|
||||
spans.push({ start, end: start + rawValue.length, value: JSON.stringify(mapped).slice(1, -1) });
|
||||
}
|
||||
return replaceSpans(text, spans);
|
||||
}
|
||||
|
||||
/**
|
||||
* Walk the CSV with a minimal RFC 4180 reader that records the span of each
|
||||
* field's *content* (inside the quotes, when quoted). Replacements never
|
||||
* contain a delimiter, quote or newline, so the original quoting survives
|
||||
* untouched — which matters, because CSV quoting is itself a common bug.
|
||||
*/
|
||||
function sanitizeCsv(text, mapUrl, mapTitle) {
|
||||
const delimiter = (text.split('\n', 1)[0] ?? '').includes(';') ? ';' : ',';
|
||||
const fields = [];
|
||||
let row = 0;
|
||||
let col = 0;
|
||||
let i = 0;
|
||||
|
||||
while (i < text.length) {
|
||||
const quoted = text[i] === '"';
|
||||
if (quoted) i++;
|
||||
const start = i;
|
||||
while (i < text.length) {
|
||||
const ch = text[i];
|
||||
if (quoted) {
|
||||
if (ch === '"') {
|
||||
if (text[i + 1] === '"') {
|
||||
i += 2;
|
||||
continue;
|
||||
}
|
||||
break;
|
||||
}
|
||||
i++;
|
||||
continue;
|
||||
}
|
||||
if (ch === delimiter || ch === '\n' || ch === '\r') break;
|
||||
i++;
|
||||
}
|
||||
fields.push({ row, col, start, end: i, quoted });
|
||||
if (quoted && text[i] === '"') i++;
|
||||
|
||||
if (text[i] === delimiter) {
|
||||
col++;
|
||||
i++;
|
||||
} else {
|
||||
if (text[i] === '\r') i++;
|
||||
if (text[i] === '\n') i++;
|
||||
row++;
|
||||
col = 0;
|
||||
}
|
||||
}
|
||||
|
||||
// Column names per docs/04 §3 — `folder_path`, not `folder`.
|
||||
const header = fields.filter((f) => f.row === 0).map((f) => text.slice(f.start, f.end).trim());
|
||||
const at = (name) => header.findIndex((h) => h.toLowerCase().replace(/^/, '') === name);
|
||||
const [folderCol, titleCol, urlCol] = [at('folder_path'), at('title'), at('url')];
|
||||
|
||||
const spans = [];
|
||||
for (const f of fields) {
|
||||
if (f.row === 0 || f.start === f.end) continue;
|
||||
const raw = text.slice(f.start, f.end);
|
||||
const value = raw.replace(/""/g, '"');
|
||||
let mapped;
|
||||
if (f.col === urlCol) mapped = mapUrl(value);
|
||||
else if (f.col === titleCol) mapped = mapTitle(value);
|
||||
else if (f.col === folderCol) mapped = mapFolderPath(value, mapTitle);
|
||||
else continue;
|
||||
spans.push({ start: f.start, end: f.end, value: mapped.replace(/"/g, '""') });
|
||||
}
|
||||
return replaceSpans(text, spans);
|
||||
}
|
||||
|
||||
/**
|
||||
* Map each path segment separately so `\/` and `\\` escapes keep their meaning.
|
||||
*
|
||||
* A segment that contained a literal slash or backslash keeps one, so the
|
||||
* escape survives into the output. Without that, `Escaped\/slash` sanitizes to
|
||||
* a plain name and the escape branch of the CSV path parser — a real reason
|
||||
* someone would file a report — stops being exercised by the sample.
|
||||
*/
|
||||
function mapFolderPath(path, mapTitle) {
|
||||
const segments = [];
|
||||
let current = '';
|
||||
for (let i = 0; i < path.length; i++) {
|
||||
const ch = path[i];
|
||||
if (ch === '\\' && (path[i + 1] === '/' || path[i + 1] === '\\')) {
|
||||
current += path[i + 1];
|
||||
i++;
|
||||
continue;
|
||||
}
|
||||
if (ch === '/') {
|
||||
segments.push(current);
|
||||
current = '';
|
||||
continue;
|
||||
}
|
||||
current += ch;
|
||||
}
|
||||
segments.push(current);
|
||||
return segments
|
||||
.map((s) => {
|
||||
if (s === '') return '';
|
||||
const kept = `${s.includes('/') ? '/' : ''}${s.includes('\\') ? '\\' : ''}`;
|
||||
return `${mapTitle(s)}${kept}`.replace(/\\/g, '\\\\').replace(/\//g, '\\/');
|
||||
})
|
||||
.join('/');
|
||||
}
|
||||
|
||||
// -------------------------------------------------------------- entry points
|
||||
|
||||
/**
|
||||
* Sanitize a bookmark file's text.
|
||||
*
|
||||
* @param {string} text
|
||||
* @returns {{ text: string, kind: 'html' | 'json' | 'csv' }}
|
||||
*/
|
||||
export function sanitize(text) {
|
||||
const kind = detectKind(text);
|
||||
const mapUrl = makeUrlMapper();
|
||||
const mapTitle = makeTitleMapper();
|
||||
if (kind === 'html') return { text: sanitizeHtml(text, mapUrl, mapTitle), kind };
|
||||
if (kind === 'json') return { text: sanitizeJson(text, mapUrl, mapTitle), kind };
|
||||
return { text: sanitizeCsv(text, mapUrl, mapTitle), kind };
|
||||
}
|
||||
|
||||
function main(argv) {
|
||||
const flags = argv.filter((a) => a.startsWith('--'));
|
||||
const [input, maybeOutput] = argv.filter((a) => !a.startsWith('--'));
|
||||
|
||||
if (input === undefined) {
|
||||
console.error('usage: node scripts/sanitize-bookmarks.mjs <input> [output] [--stdout|--check]');
|
||||
return 1;
|
||||
}
|
||||
|
||||
const raw = readFileSync(input);
|
||||
if (raw.byteLength > MAX_BYTES) {
|
||||
console.error(
|
||||
`${input} is ${(raw.byteLength / 1024 / 1024).toFixed(1)} MB. The extension itself refuses ` +
|
||||
'anything over 25 MB, and a smaller file that still reproduces the bug is more useful. ' +
|
||||
'Please trim it first.',
|
||||
);
|
||||
return 1;
|
||||
}
|
||||
|
||||
const text = raw.toString('utf8');
|
||||
const { text: out, kind } = sanitize(text);
|
||||
const eol = text.includes('\r\n') ? 'CRLF' : 'LF';
|
||||
const bom = text.charCodeAt(0) === 0xfeff ? ', BOM' : '';
|
||||
console.error(`${basename(input)}: ${kind}, ${eol}${bom} — ${out.length} bytes out`);
|
||||
|
||||
if (flags.includes('--check')) return 0;
|
||||
if (flags.includes('--stdout')) {
|
||||
process.stdout.write(out);
|
||||
return 0;
|
||||
}
|
||||
|
||||
const ext = extname(input);
|
||||
const target = maybeOutput ?? `${input.slice(0, input.length - ext.length)}.sanitized${ext}`;
|
||||
writeFileSync(target, out);
|
||||
console.error(`wrote ${target}`);
|
||||
return 0;
|
||||
}
|
||||
|
||||
if (process.argv[1] !== undefined && process.argv[1] === fileURLToPath(import.meta.url)) {
|
||||
process.exitCode = main(process.argv.slice(2));
|
||||
}
|
||||
@@ -0,0 +1,165 @@
|
||||
import { execFileSync } from 'node:child_process';
|
||||
import { readdirSync, readFileSync } from 'node:fs';
|
||||
import { join, relative } from 'node:path';
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { detectFormat } from '@/lib/core/detect-format';
|
||||
import { type BookmarkNode, computeStats, type ParseResult, walkTree } from '@/lib/core/model';
|
||||
import { parseBmJson } from '@/lib/core/parse/bm-json';
|
||||
import { parseCsv } from '@/lib/core/parse/csv';
|
||||
import { parseNetscapeHtml } from '@/lib/core/parse/netscape-html';
|
||||
|
||||
/**
|
||||
* `scripts/sanitize-bookmarks.mjs` — docs/11 §2, docs/09 §6.
|
||||
*
|
||||
* The script makes exactly one promise: after sanitizing, the bug still
|
||||
* reproduces. That is directly assertable against the committed corpus — parse
|
||||
* both versions and require the parser to see the same thing — so this suite
|
||||
* asserts the promise rather than the implementation.
|
||||
*
|
||||
* The script is invoked as a subprocess rather than imported. It is a `.mjs`
|
||||
* with no type declarations, and it has to keep running from a fresh clone with
|
||||
* nothing installed; spawning it also exercises the real entry point, argument
|
||||
* parsing included.
|
||||
*/
|
||||
const root = process.cwd();
|
||||
const script = join(root, 'scripts', 'sanitize-bookmarks.mjs');
|
||||
const fixtures = join(root, 'tests', 'fixtures');
|
||||
|
||||
const sanitize = (absPath: string): string =>
|
||||
execFileSync(process.execPath, [script, absPath, '--stdout'], {
|
||||
encoding: 'utf8',
|
||||
stdio: ['ignore', 'pipe', 'ignore'],
|
||||
});
|
||||
|
||||
/**
|
||||
* Every committed fixture file, as paths relative to `tests/fixtures/`.
|
||||
*
|
||||
* Discovered rather than listed, so a fixture added by a future bug report is
|
||||
* covered without anyone remembering to add it here. `generated/` is skipped:
|
||||
* it is git-ignored `gen-fixture.mjs` output, so it exists on some machines and
|
||||
* not others, and a suite whose corpus depends on that is not reproducible.
|
||||
*/
|
||||
function corpus(): string[] {
|
||||
const out: string[] = [];
|
||||
const walk = (dir: string): void => {
|
||||
for (const entry of readdirSync(dir, { withFileTypes: true })) {
|
||||
if (entry.name === 'generated') continue;
|
||||
const full = join(dir, entry.name);
|
||||
if (entry.isDirectory()) walk(full);
|
||||
else if (/\.(html|json|csv)$/.test(entry.name)) out.push(relative(fixtures, full));
|
||||
}
|
||||
};
|
||||
walk(fixtures);
|
||||
return out.sort();
|
||||
}
|
||||
|
||||
const FIXTURES = corpus();
|
||||
|
||||
/** Parse with whichever parser the sniffed format selects. */
|
||||
function parseAny(text: string): ParseResult {
|
||||
const format = detectFormat(text);
|
||||
if (format === 'netscape-html') return parseNetscapeHtml(text);
|
||||
if (format === 'bm-json') return parseBmJson(text);
|
||||
return parseCsv(text);
|
||||
}
|
||||
|
||||
/** Structure only: folder/bookmark shape and nesting, with no titles or URLs. */
|
||||
function topology(roots: readonly BookmarkNode[]): string {
|
||||
const render = (nodes: readonly BookmarkNode[]): string =>
|
||||
nodes.map((n) => (n.url === undefined ? `F(${render(n.children ?? [])})` : 'B')).join(',');
|
||||
return render(roots);
|
||||
}
|
||||
|
||||
const hostsIn = (roots: readonly BookmarkNode[]): string[] => {
|
||||
const out: string[] = [];
|
||||
for (const { node } of walkTree(roots)) {
|
||||
if (node.url === undefined) continue;
|
||||
try {
|
||||
const { host } = new URL(node.url);
|
||||
if (host !== '') out.push(host);
|
||||
} catch {
|
||||
// Unparseable URLs carry no host to leak.
|
||||
}
|
||||
}
|
||||
return out;
|
||||
};
|
||||
|
||||
it('the corpus is non-empty, so a broken walk cannot pass vacuously', () => {
|
||||
expect(FIXTURES.length).toBeGreaterThan(10);
|
||||
});
|
||||
|
||||
describe.each(FIXTURES)('sanitize %s', (name) => {
|
||||
const original = readFileSync(join(fixtures, name), 'utf8');
|
||||
const cleaned = sanitize(join(fixtures, name));
|
||||
|
||||
it('keeps the file recognisable as the same format', () => {
|
||||
let before: string;
|
||||
try {
|
||||
before = detectFormat(original);
|
||||
} catch {
|
||||
// A fixture that is deliberately unrecognisable must stay unrecognisable.
|
||||
expect(() => detectFormat(cleaned)).toThrow();
|
||||
return;
|
||||
}
|
||||
expect(detectFormat(cleaned)).toBe(before);
|
||||
});
|
||||
|
||||
it('parses to the same stats, warnings and structure — or fails the same way', () => {
|
||||
let before: ParseResult;
|
||||
try {
|
||||
before = parseAny(original);
|
||||
} catch (err) {
|
||||
// The interesting half: a fixture that reproduces a parse *failure* must
|
||||
// still reproduce it, with the same code, after sanitizing.
|
||||
const code = (err as { code?: string }).code;
|
||||
expect(() => parseAny(cleaned)).toThrowError(expect.objectContaining({ code }));
|
||||
return;
|
||||
}
|
||||
|
||||
const after = parseAny(cleaned);
|
||||
expect(after.stats).toEqual(before.stats);
|
||||
expect(computeStats(after.roots)).toEqual(computeStats(before.roots));
|
||||
expect(topology(after.roots)).toBe(topology(before.roots));
|
||||
expect(after.warnings.map((w) => w.code).sort()).toEqual(
|
||||
before.warnings.map((w) => w.code).sort(),
|
||||
);
|
||||
});
|
||||
|
||||
it('preserves byte-level shape: BOM, line endings and length of the untouched parts', () => {
|
||||
expect(cleaned.charCodeAt(0) === 0xfeff).toBe(original.charCodeAt(0) === 0xfeff);
|
||||
expect(cleaned.includes('\r\n')).toBe(original.includes('\r\n'));
|
||||
expect(cleaned.split('\n').length).toBe(original.split('\n').length);
|
||||
});
|
||||
|
||||
it('preserves every timestamp exactly', () => {
|
||||
const stamps = (text: string): string[] =>
|
||||
(text.match(/(?:ADD_DATE|LAST_MODIFIED)="(\d*)"/gi) ?? []).sort();
|
||||
expect(stamps(cleaned)).toEqual(stamps(original));
|
||||
});
|
||||
|
||||
it('leaks no hostname from the original', () => {
|
||||
let before: ParseResult;
|
||||
try {
|
||||
before = parseAny(original);
|
||||
} catch {
|
||||
return;
|
||||
}
|
||||
const leaked = hostsIn(before.roots).filter((h) => cleaned.includes(h));
|
||||
expect(leaked).toEqual([]);
|
||||
});
|
||||
|
||||
it('keeps distinct URLs distinct, so dedupe behaviour is unchanged', () => {
|
||||
let before: ParseResult;
|
||||
try {
|
||||
before = parseAny(original);
|
||||
} catch {
|
||||
return;
|
||||
}
|
||||
const urls = (r: ParseResult): number => {
|
||||
const set = new Set<string>();
|
||||
for (const { node } of walkTree(r.roots)) if (node.url !== undefined) set.add(node.url);
|
||||
return set.size;
|
||||
};
|
||||
expect(urls(parseAny(cleaned))).toBe(urls(before));
|
||||
});
|
||||
});
|
||||
Reference in new issue
Block a user