Skip to content

Add a stable rule ID to the issue API #35

Description

@nawforce

Add a stable identifier to the issue API so consumers can refer to a specific kind of
diagnostic, rather than only its broad category.

Today Rule carries a name() and a priority(). name() is documented as "does need to be
unique but recommended it is", and in practice apex-ls supplies the DiagnosticCategory name —
Syntax, Error, Missing, Warning, Unused. Five values across every diagnostic apex-ls
produces, so there is nothing fine-grained enough to reference an individual issue type.

This blocks apex-dev-tools/apex-ls#322, which wants config-driven exclusion by issue ID
(e.g. missing-type). The identifier has to exist on the API before apex-ls can populate it.

Scope

Extend Rule with an id, in both cross-built sources:

  • jvm/src/main/java/io/github/apexdevtools/api/Rule.java
  • js/src/main/scala/io/github/apexdevtools/api/Rule.scala

Points to settle:

  • Name and form. id() returning a String. Suggested convention is lowercase kebab-case,
    stable across releases once published, since it becomes part of users' config files.
  • Relationship to name(). Whether name() stays as the human-readable label with id() as
    the machine key, or whether name() is eventually deprecated in favour of id().
  • Default implementation. Rule is a published interface, so adding an abstract method is
    source- and binary-breaking for any external implementor. A default method on the Java side
    (returning name(), or an empty string) avoids that. Note the Scala.js side is a trait, so
    the two need to stay behaviourally aligned.

Issue.asString() currently formats as rule().name() + ": " + ... — worth deciding whether that
output changes, as apex-ls's CheckForIssues text/pmd output depends on it.

Why here and not in apex-ls

io.github.apexdevtools.api.{Issue, IssueLocation, Rule} is published from this repo, not apex-ls;
apex-ls consumes it transitively via outline-parser and shims onto it with DiagnosticRule.

The external analysis SPI that Rule was originally built for has been withdrawn — apex-ls-pmd is
deprecated and apex-ls#439 reduced getExternalAnalysis/setExternalAnalysis/
setExternalAnalysisMode to deprecated no-op stubs. In-tree, Rule is now consumed only by
apex-ls's CheckForIssues. It remains a published interface that third parties may implement,
though, so extending it is the safe move; removing it is not.

Downstream

Once released, apex-ls bumps outline-parser in build.sbt and assigns IDs at its ~106
diagnostic creation sites. Tracked in apex-dev-tools/apex-ls#322.

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