Skip to content

[Compatibility] Add support for @exclude-match #1714

Description

@cyfung1031

The Problem You Want to Solve

The current ScriptCat userscript metadata parser preserves unknown metadata keys, but the URL-matching path only recognizes @match, @include, and @exclude. As a result, @exclude-match is not converted into an active exclusion rule and its match-pattern semantics are not applied when deciding whether a script should run.

This matters for userscript compatibility:

  • @exclude-match is the strict match-pattern counterpart to @match.
  • It is intended for excluding specific match-pattern URLs while retaining broader @match entries.
  • Replacing it with @exclude changes the accepted syntax and can change the intended matching behavior.
  • A script author may not discover that the directive is ineffective until after installation or after inspecting the editor diagnostics.

Required Behavior

A URL matching any @exclude-match entry must not run the script, even when the same URL also matches an @match entry. The result must not depend on the declaration order of the metadata lines.

@exclude-match should use match-pattern semantics, not the broader glob/regular-expression semantics supported by ScriptCat's existing @exclude handling. Invalid patterns must not be silently broadened or reinterpreted as a different exclusion type.

Existing @exclude behavior must remain unchanged.

This issue covers support in the metadata-to-URL-rule and script-registration paths that actually consume these rules. It does not prescribe a particular internal representation or require a particular installation UI. Installation-time diagnostics are tracked separately in #1713.

Implementation Guidance

The following are investigation pointers from the current codebase, not a demand to preserve a specific design:

  • src/pkg/utils/script.ts uses a generic metadata map, so the main missing behavior is downstream consumption rather than necessarily a new metadata storage type.
  • src/pkg/utils/url_matcher.ts currently extracts only @match, @include, and @exclude. It already has a MATCH_EXCLUDE rule type and match-pattern handling that can be evaluated for reuse.
  • src/app/service/service_worker/utils.ts builds the effective and original URL-rule lists and creates chrome.userScripts registration data. Any projections that currently select only match/include/exclude must be reviewed so that exclude-match is not lost when building effective rules, restoring original rules, or applying self metadata.
  • The existing registration path already maps MATCH_EXCLUDE rules to excludeMatches; the PR should verify that the new metadata directive reaches this path instead of creating a parallel registration mechanism.
  • The PR should inspect the non-native matching paths as well as native registration. In particular, early-start and unwrap-related code can perform additional URL checks or embed URL rules before injection.
  • Review cache and compiled-resource invalidation. For example, the page-load cache key currently serializes selected match/include/exclude metadata; a metadata change must not leave an old compiled URL-rule set active.
  • Review user overrides, original-metadata restoration, popup/site-scope operations, and import/backup round trips wherever they explicitly enumerate URL metadata keys. Do not silently drop exclude-match in one of these paths.
  • Keep this feature separate from changing the semantics of @exclude, @include, @noframes, or top-level-page exclusion.

Acceptance Criteria

  • One or multiple @exclude-match entries are parsed into the same effective URL-rule pipeline used by the script runtime.
  • A URL matching @match runs when it does not match @exclude-match.
  • A URL matching @exclude-match does not run when it also matches @match, with both metadata declaration orders covered.
  • Match-pattern wildcard and scheme behavior is covered, and malformed @exclude-match values do not fall back to @exclude glob/regex behavior.
  • Native registration and every additional URL-checking consumer touched by the PR produce the same result.
  • Self-metadata overrides, clearing, restoration of original metadata, script updates, extension restart, and compiled-resource reuse do not resurrect stale URL rules.
  • Existing @exclude match, glob, and regular-expression tests continue to pass.
  • The PR identifies the affected execution consumers and adds focused regression tests for each material path.

Additional Information

Related compatibility tracking issue: #931

The request was raised in #931 comment. That comment also describes the discoverability problem observed while editing scripts and references #1255.

Metadata

Metadata

Assignees

No one assigned

    Labels

    compatibility其它管理器可以运行,脚本猫不能运行userscriptIssues related to userscripts and userscript compatibility

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions