Skip to content

[Feature] Highlight incompatible APIs in the installation UI #1713

Description

@cyfung1031

The Problem You Want to Solve

The installation page currently shows script identity, requested permissions, risk warnings, and a code preview. For updates whose code changed, the preview can also show an inline diff; a new installation or an update with identical code does not have a diff.

The installation flow does not currently provide a dedicated, user-visible compatibility diagnostic for unsupported or partially supported userscript metadata and statically recognizable userscript/GM API usage. Users can therefore confirm installation without noticing that a feature used by the script is not supported by ScriptCat. Discovering the problem later in the editor or by manually reading the compatibility documentation is too late and too easy to miss.

The motivating example is @exclude-match: before #1714 is implemented, the installation page should make its incompatibility visible rather than leaving the user to discover it after installation.

Proposed Solution

Add compatibility diagnostics to the installation UI alongside the existing code preview and, when applicable, its update diff.

The first implementation should:

  • Reuse an existing authoritative compatibility data source where possible, or document and test the new rule source if one is required.
  • Document which metadata directives and API rules are covered, and distinguish supported, partially supported, unsupported, and unknown/unanalysed cases where those states are meaningful.
  • Detect metadata directives and statically recognizable userscript/GM API usage before the user confirms installation. “API usage” here means analyzable source/metadata patterns, not arbitrary runtime behavior.
  • Highlight the relevant metadata or source lines when an exact location is available. If a diagnostic has no exact location, keep it visible in the diagnostics summary instead of dropping it.
  • Show a concise explanation for each diagnostic and link to the relevant compatibility documentation or reference.
  • Keep the existing update diff available; compatibility diagnostics are additional information, not a replacement for the diff.
  • Make diagnostics visible for both new installations and updates, including updates with no code diff.
  • Keep the normal install action available by default. Diagnostics must not block installation unless maintainers introduce and document a separate blocking policy.

This issue is about detection and presentation during installation. It does not add support for an otherwise unsupported feature; support for @exclude-match is tracked separately in #1714.

Implementation Guidance

The following code locations describe the current seams that a PR should account for:

  • src/pages/install/useInstallData.ts assembles the InstallView from parsed metadata, permissions, old code, and the new code. This is the natural data boundary for passing diagnostics into the page.
  • src/pages/install/App.tsx currently renders PermissionCard, InstallWarning, and CodePreview; the new UI should have a clear place in this layout and remain usable on narrow viewports.
  • src/pages/install/components/CodePreview.tsx passes diffCode only when an update has different old and new code. Do not use the presence of a diff as the condition for running compatibility analysis.
  • src/pages/components/CodeEditor/index.tsx and src/linter.worker.ts contain the existing editor ESLint worker/marker path. The install preview can use a different Monaco mode for diff views, so a PR must verify whether the existing lint lifecycle actually runs for the install-page instance before attempting to reuse it unchanged.
  • The editor's metadata markers and ESLint markers have different owners and data paths. A PR should define how compatibility diagnostics are normalized, how rule identifiers and documentation links are retained, and how markers are cleared when the analyzed code changes.
  • The current metadata parser returns metadata values but not source locations. If metadata lines are to be highlighted, the PR should add or reuse a location-aware analysis step rather than guessing line numbers from normalized metadata.
  • Use i18n keys and follow the repository's localization conventions for all user-visible diagnostic text. The UI should remain accessible, keyboard-usable, and legible in the supported light/dark and mobile layouts.

Acceptance Criteria

  • A known unsupported metadata directive produces a visible diagnostic before installation confirmation.
  • A statically recognizable unsupported API produces a visible diagnostic and a source location when available.
  • Partial support is distinguishable from unsupported behavior when the compatibility source provides that distinction.
  • Diagnostics without an exact source location remain visible in a summary.
  • Supported features do not produce false incompatibility warnings.
  • A new installation, an update with changed code, and an update with unchanged code all show the correct diagnostics; changed updates still show the existing diff.
  • Diagnostics update or clear when the analyzed code changes and do not leak between installation sessions.
  • The default install action remains available, including when diagnostics are present.
  • User-visible text is localized and the diagnostics are accessible on desktop and mobile layouts.
  • The PR adds focused model/component tests and, where marker or worker behavior is involved, an integration or browser-level check for the install flow.
  • The PR documents the compatibility rule/data source and the exact diagnostic coverage, including known limitations.

Additional Information

Related compatibility tracking issue: #931

This request was raised in #931 comment, which notes that some compatibility warnings are already visible while editing scripts.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions