url-sanitize 0.1.2__tar.gz

url_sanitize-0.1.2/.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

url_sanitize-0.1.2/.github/ISSUE_TEMPLATE/broken-url.yml

@@ -0,0 +1,34 @@
+name: Broken URL / bad cleanup
+description: A URL produces wrong output (over-strips, under-strips, garbles)
+title: '[broken-url] '
+labels: [bug, broken-url]
+body:
+  - type: input
+    id: input-url
+    attributes:
+      label: Input URL
+      description: Paste the URL fed to url-sanitize.
+    validations:
+      required: true
+  - type: input
+    id: expected
+    attributes:
+      label: Expected output URL
+    validations:
+      required: true
+  - type: input
+    id: actual
+    attributes:
+      label: Actual output URL
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: '@url-sanitize/clearurls version (from metadata.json)'
+    validations:
+      required: true
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes

url_sanitize-0.1.2/.github/ISSUE_TEMPLATE/rule-source-request.yml

@@ -0,0 +1,25 @@
+name: Rule source request
+description: Request support for a non-ClearURLs rule source (AdGuard, Brave, Firefox, custom)
+title: '[source] '
+labels: [enhancement, rule-source]
+body:
+  - type: input
+    id: source
+    attributes:
+      label: Source name
+      description: e.g. AdGuard URL Tracking Protection, Brave Debouncer
+    validations:
+      required: true
+  - type: input
+    id: source-url
+    attributes:
+      label: Upstream URL
+    validations:
+      required: true
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use case
+      description: What does this source cover that ClearURLs doesn't?
+    validations:
+      required: true

url_sanitize-0.1.2/.github/workflows/auto-tag.yml

@@ -0,0 +1,35 @@
+name: auto-tag
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'packages/core/package.json'
+
+permissions:
+  actions: write
+  contents: write
+
+jobs:
+  tag:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Read version
+        id: version
+        run: echo "version=$(node -p "require('./packages/core/package.json').version")" >> "$GITHUB_OUTPUT"
+
+      - name: Create and push tag if missing
+        env:
+          TAG: v${{ steps.version.outputs.version }}
+        run: |
+          if git ls-remote --tags origin "$TAG" | grep -q "$TAG"; then
+            echo "Tag $TAG already exists — skipping"
+          else
+            git config user.name "github-actions[bot]"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+            git tag -a "$TAG" -m "release $TAG"
+            git push origin "$TAG"
+            gh workflow run release.yml --ref "$TAG"
+          fi

url_sanitize-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - '**/*.md'
+      - 'docs/**'
+      - 'AGENTS.md'
+      - 'LICENSE'
+      - 'NOTICE'
+  pull_request:
+    paths-ignore:
+      - '**/*.md'
+      - 'docs/**'
+      - 'AGENTS.md'
+      - 'LICENSE'
+      - 'NOTICE'
+
+jobs:
+  ts:
+    name: TypeScript engine + conformance
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - name: Verify generated catalog matches checked-in catalog
+        run: |
+          pnpm build:catalog
+          git diff --exit-code catalog/clearurls.json \
+            || (echo "catalog/clearurls.json is stale — run \`pnpm build:catalog\` and commit" && exit 1)
+      - name: Verify generated conformance corpus matches checked-in files
+        run: |
+          pnpm build:conformance
+          git diff --exit-code conformance/vectors.jsonl conformance/clearurls-corpus.jsonl conformance/manifest.json \
+            || (echo "conformance corpus is stale — run \`pnpm build:conformance\` and commit" && exit 1)
+      - run: pnpm typecheck
+      - run: pnpm test
+      - run: pnpm lint
+
+  rust:
+    name: Rust engine + conformance
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo build --workspace --all-targets
+      - run: cargo test --workspace
+      - name: Release binary size check
+        run: |
+          cargo build --release -p url-sanitize
+          ls -lh target/release/url-sanitize
+          size=$(stat -c%s target/release/url-sanitize)
+          echo "release binary size: $size bytes"
+          # M1 soft cap: 1.5 MB. M3 target: < 1 MB.
+          test "$size" -lt 1572864 || (echo "binary exceeded 1.5 MB soft cap" && exit 1)

url_sanitize-0.1.2/.github/workflows/release.yml

@@ -0,0 +1,203 @@
+name: release
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+          registry-url: 'https://registry.npmjs.org'
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - run: pnpm typecheck
+      - run: pnpm test
+      - run: pnpm lint
+      - run: cargo build --workspace --all-targets
+      - run: cargo test --workspace
+      - run: cargo package -p url-sanitize-core
+
+  build-native:
+    needs: verify
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+            archive: url-sanitize-x86_64-unknown-linux-gnu.tar.gz
+            binary: url-sanitize
+          - os: ubuntu-24.04-arm
+            target: aarch64-unknown-linux-gnu
+            archive: url-sanitize-aarch64-unknown-linux-gnu.tar.gz
+            binary: url-sanitize
+          - os: macos-14
+            target: aarch64-apple-darwin
+            archive: url-sanitize-aarch64-apple-darwin.tar.gz
+            binary: url-sanitize
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+            archive: url-sanitize-x86_64-pc-windows-msvc.zip
+            binary: url-sanitize.exe
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+      - uses: Swatinem/rust-cache@v2
+      - name: Build native binary
+        run: cargo build --release -p url-sanitize --target "${{ matrix.target }}"
+        shell: bash
+      - name: Stage binary
+        run: |
+          set -euo pipefail
+          src="target/${{ matrix.target }}/release/${{ matrix.binary }}"
+          mkdir -p "dist/${{ matrix.target }}"
+          cp "$src" "dist/${{ matrix.target }}/${{ matrix.binary }}"
+          chmod +x "dist/${{ matrix.target }}/${{ matrix.binary }}" || true
+        shell: bash
+      - name: Smoke native binary
+        run: |
+          set -euo pipefail
+          "dist/${{ matrix.target }}/${{ matrix.binary }}" --version
+          "dist/${{ matrix.target }}/${{ matrix.binary }}" --json "https://example.com/?utm_source=x"
+          printf '%s\n' "https://example.com/?utm_source=x" | "dist/${{ matrix.target }}/${{ matrix.binary }}" -
+        shell: bash
+      - name: Build release archive
+        run: |
+          set -euo pipefail
+          mkdir -p release-assets
+          if [[ "${{ matrix.archive }}" == *.zip ]]; then
+            powershell -NoProfile -Command "Compress-Archive -Path 'dist/${{ matrix.target }}/*' -DestinationPath 'release-assets/${{ matrix.archive }}'"
+          else
+            tar -czf "release-assets/${{ matrix.archive }}" -C "dist/${{ matrix.target }}" .
+          fi
+        shell: bash
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-${{ matrix.target }}
+          path: release-assets/*
+  github-release:
+    needs: build-native
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: release-*
+          path: release-assets
+          merge-multiple: true
+      - name: Add installer scripts and checksums
+        run: |
+          cp scripts/install.sh release-assets/url-sanitize-installer.sh
+          cp scripts/install.ps1 release-assets/url-sanitize-installer.ps1
+          chmod +x release-assets/url-sanitize-installer.sh
+          (cd release-assets && sha256sum * > SHA256SUMS)
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: release-assets/*
+          generate_release_notes: true
+
+  publish-npm:
+    needs: verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22.14'
+          cache: 'pnpm'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm install -g 'npm@^11.5.1'
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - name: Publish TypeScript npm packages
+        run: |
+          set -euo pipefail
+          VERSION="$(node -p "require('./packages/core/package.json').version")"
+          mkdir -p npm-packages
+
+          publish_pkg() {
+            pkg="$1"
+            filter="$2"
+            if npm view "$pkg@$VERSION" version >/dev/null 2>&1; then
+              echo "$pkg@$VERSION already published; skipping"
+              return
+            fi
+            rm -f npm-packages/*.tgz
+            pnpm --filter "$filter" pack --pack-destination "$PWD/npm-packages"
+            npm publish "$PWD"/npm-packages/*.tgz --access public
+          }
+
+          publish_pkg "@url-sanitize/core" "@url-sanitize/core"
+          publish_pkg "@url-sanitize/clearurls" "@url-sanitize/clearurls"
+          publish_pkg "@url-sanitize/cli" "@url-sanitize/cli"
+
+  publish-crates:
+    needs: verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - uses: rust-lang/crates-io-auth-action@v1
+        id: auth
+      - name: Read crate version
+        id: version
+        run: |
+          version="$(python3 -c 'import json, subprocess; data=json.loads(subprocess.check_output(["cargo", "metadata", "--no-deps", "--format-version=1"])); print(next(p["version"] for p in data["packages"] if p["name"] == "url-sanitize-core"))')"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+      - name: Publish url-sanitize-core to crates.io
+        run: |
+          if curl -fsSA "url-sanitize-release" "https://crates.io/api/v1/crates/url-sanitize-core/${{ steps.version.outputs.version }}" >/dev/null; then
+            echo "url-sanitize-core ${{ steps.version.outputs.version }} already published; skipping"
+          else
+            cargo publish -p url-sanitize-core
+          fi
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ steps.auth.outputs.token }}
+      - name: Wait for crates.io index propagation
+        run: sleep 30
+      - name: Publish url-sanitize to crates.io
+        run: |
+          if curl -fsSA "url-sanitize-release" "https://crates.io/api/v1/crates/url-sanitize/${{ steps.version.outputs.version }}" >/dev/null; then
+            echo "url-sanitize ${{ steps.version.outputs.version }} already published; skipping"
+          else
+            cargo publish -p url-sanitize
+          fi
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ steps.auth.outputs.token }}
+
+  publish-pypi:
+    needs: verify
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      - name: Build Python package
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

url_sanitize-0.1.2/.github/workflows/sync-clearurls.yml

@@ -0,0 +1,64 @@
+name: sync-clearurls
+
+on:
+  schedule:
+    - cron: '17 4 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile
+
+      - name: Fetch and verify upstream rules
+        run: pnpm sync:clearurls
+
+      - name: Detect changes
+        id: diff
+        run: |
+          if git diff --quiet packages/clearurls/data; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Bump patch version
+        if: steps.diff.outputs.changed == 'true'
+        run: |
+          CURRENT=$(node -p "require('./packages/core/package.json').version")
+          IFS='.' read -r major minor patch <<< "$CURRENT"
+          NEW_VERSION="$major.$minor.$((patch + 1))"
+          node scripts/bump-version.mjs "$NEW_VERSION"
+          echo "new_version=$NEW_VERSION" >> "$GITHUB_OUTPUT"
+        id: bump
+
+      - name: Open PR
+        if: steps.diff.outputs.changed == 'true'
+        id: cpr
+        uses: peter-evans/create-pull-request@22a9089034f40e5a961c8808d113e2c98fb63676 # v7
+        with:
+          commit-message: 'release: v${{ steps.bump.outputs.new_version }}'
+          title: 'chore(clearurls): sync upstream rules → v${{ steps.bump.outputs.new_version }}'
+          body: |
+            Automated daily sync of ClearURLs rule catalog from
+            https://rules2.clearurls.xyz/data.minify.json.
+            SHA256 verified against rules.minify.hash.
+          branch: clearurls-sync
+          delete-branch: true
+
+      - name: Enable auto-merge
+        if: steps.diff.outputs.changed == 'true' && steps.cpr.outputs.pull-request-number != ''
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh pr merge --auto --squash "${{ steps.cpr.outputs.pull-request-number }}"

url_sanitize-0.1.2/.gitignore

@@ -0,0 +1,23 @@
+node_modules/
+dist/
+*.tsbuildinfo
+.turbo/
+coverage/
+.DS_Store
+*.log
+.env
+.env.local
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+
+.idea/
+.vscode/*
+!.vscode/extensions.json
+
+# Rust
+target/
+Cargo.lock.bak
+**/*.rs.bk

url_sanitize-0.1.2/.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+set -eu
+
+pnpm lint

url_sanitize-0.1.2/.husky/pre-push

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+set -eu
+
+sh scripts/pre-push.sh

url_sanitize-0.1.2/.npmrc

@@ -0,0 +1 @@
+confirm-modules-purge=false

url_sanitize-0.1.2/AGENTS.md

@@ -0,0 +1,95 @@
+# url-sanitize — agent context
+
+ClearURLs-compatible URL tracking cleanup toolkit. Removes tracking parameters and unwraps tracking redirects from TypeScript, Rust, npm CLI, native binaries, and Python wrapper surfaces.
+
+## Package layout
+
+```
+packages/
+  core/        @url-sanitize/core        pure algorithm, zero deps, MIT
+  clearurls/   @url-sanitize/clearurls   ClearURLs catalog + pre-compiled sanitize(), LGPL-3.0 data
+  cli/         @url-sanitize/cli         pure TypeScript npm CLI, MIT
+crates/
+  url-sanitize-core/                    Rust implementation
+  url-sanitize/                         native CLI with embedded catalog
+python/
+  url_sanitize/                         PyPI wrapper around native CLI / PATH binary
+sources/
+  clearurls/   upstream sync script (pnpm sync:clearurls)
+docs/          threat model, license model, roadmap, compat notes
+```
+
+## Common workflows
+
+```bash
+pnpm install                  # install all workspace deps
+pnpm sync:clearurls           # fetch + SHA256-verify upstream rules → packages/clearurls/data/
+pnpm build                    # tsup build all packages (must run before typecheck)
+pnpm test                     # vitest run
+pnpm lint                     # biome check . (also enforces import order)
+pnpm format                   # biome format --write .
+pnpm typecheck                # tsc --noEmit across all packages
+cargo fmt --all --check       # Rust formatting check
+cargo clippy --workspace --all-targets -- -D warnings
+cargo test --workspace        # Rust conformance + unit tests
+cargo package -p url-sanitize-core
+cargo package -p url-sanitize
+```
+
+Pre-push hook runs: `pnpm build && pnpm lint && pnpm test`
+
+## Key conventions
+
+- **Linter/formatter**: Biome — not ESLint/Prettier. Run `pnpm lint` to check, `pnpm format` to fix.
+- **Build**: tsup (ESM only, `.d.ts` emitted). `dist/` is gitignored, included in npm via `"files"`.
+- **Test runner**: vitest. Single test file: `bunx vitest run packages/core/test/sanitize.test.ts`
+- **Imports**: must be alphabetically ordered (Biome enforces). Use `.js` extensions in source imports.
+- **Versions**: npm packages, Rust workspace, and PyPI wrapper version-bump together on every release.
+- **Roadmap**: `docs/roadmap.md` is canonical. Do not recreate `PLAN.md`.
+- **npm native packages**: intentionally not used in v0.2. They create one package/trusted-publisher setup per platform. Keep npm CLI pure TypeScript unless this tradeoff is explicitly reopened.
+
+## Publishing
+
+Publish is fully automated from `v*` tags:
+
+- npm packages use npm trusted publishing (OIDC).
+- crates.io uses `rust-lang/crates-io-auth-action` trusted publishing.
+- PyPI uses trusted publishing with the `pypi` GitHub environment.
+- GitHub Releases receive native archives, SHA256SUMS, and installer scripts.
+
+No long-lived registry token should be required after trusted publishers are configured.
+
+```bash
+# bump versions in packages/*/package.json, Cargo.toml, pyproject.toml
+git commit -m "release: vX.Y.Z"
+git tag -a vX.Y.Z -m "release X.Y.Z"
+git push --follow-tags
+# .github/workflows/release.yml publishes npm, crates, PyPI, and native assets
+```
+
+## Architecture
+
+`compileSanitizer(catalog, opts?) → Sanitizer` — factory pattern. Compiles all RegExp at factory time. Call once at module init, reuse the returned function.
+
+`@url-sanitize/clearurls` exports `sanitize` (pre-compiled with default options) for one-import usage:
+```ts
+import { sanitize } from '@url-sanitize/clearurls';
+```
+
+Result is a discriminated union: `{ kind: 'unchanged' } | { kind: 'cleaned', strippedParams, matchedRules } | { kind: 'redirected', via } | { kind: 'blocked', via }`
+
+## Daily sync
+
+`.github/workflows/sync-clearurls.yml` runs at 04:17 UTC, opens a PR on change, auto-merges via squash. No manual action needed.
+
+## Adding a new package
+
+1. Create `packages/<name>/` with `package.json` (`"name": "@url-sanitize/<name>"`, `"publishConfig": { "access": "public" }`)
+2. Add `tsconfig.json` extending `../../tsconfig.base.json`
+3. Add `"build"` script using tsup
+4. Add `"files": ["dist"]`
+5. `pnpm install` to link workspace
+
+## Non-goals
+
+No browser extension UI, HTTP interception, DNS blocking, or telemetry. See `docs/non-goals.md`.

url_sanitize-0.1.2/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

url_sanitize-0.1.2/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing
+
+## Dev setup
+
+```sh
+pnpm install
+pnpm sync:clearurls   # populate packages/clearurls/data/
+pnpm build
+pnpm test
+```
+
+## Layout
+
+This is a pnpm + changesets monorepo.
+
+```
+packages/
+  core/        @url-sanitize/core         pure algorithm, zero deps
+  clearurls/   @url-sanitize/clearurls    ClearURLs catalog adapter + bundled data
+  cli/         @url-sanitize/cli          command-line tool
+sources/
+  clearurls/   sync script + test fixtures
+docs/          public docs (threat model, license, roadmap)
+```
+
+## Workflow
+
+1. Open an issue first for non-trivial changes.
+2. Branch from `main`.
+3. Run `pnpm changeset` to declare a version bump for any package you change.
+4. Open PR. CI must pass (typecheck + lint + test + build).
+
+## Adding a rule fixture
+
+ClearURLs ruleset changes upstream. To pin a behavior:
+
+1. Add a fixture under `sources/clearurls/fixtures/<provider>.json` with input + expected output URLs
+2. Reference it in `packages/core/test/sanitize.test.ts`
+3. PR
+
+## Reporting a broken URL
+
+Use the `broken-url.yml` issue template. Include: input URL, expected output, actual output, `@url-sanitize/clearurls` version (from `metadata.json`).
+
+## Scope
+
+See [docs/non-goals.md](docs/non-goals.md). PRs that add browser-extension UI, HTTP interception, DNS blocking, or telemetry will be closed.