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.
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
Rulecarries aname()and apriority().name()is documented as "does need to beunique but recommended it is", and in practice apex-ls supplies the
DiagnosticCategoryname —Syntax,Error,Missing,Warning,Unused. Five values across every diagnostic apex-lsproduces, 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
Rulewith an id, in both cross-built sources:jvm/src/main/java/io/github/apexdevtools/api/Rule.javajs/src/main/scala/io/github/apexdevtools/api/Rule.scalaPoints to settle:
id()returning aString. Suggested convention is lowercase kebab-case,stable across releases once published, since it becomes part of users' config files.
name(). Whethername()stays as the human-readable label withid()asthe machine key, or whether
name()is eventually deprecated in favour ofid().Ruleis a published interface, so adding an abstract method issource- and binary-breaking for any external implementor. A
defaultmethod on the Java side(returning
name(), or an empty string) avoids that. Note the Scala.js side is atrait, sothe two need to stay behaviourally aligned.
Issue.asString()currently formats asrule().name() + ": " + ...— worth deciding whether thatoutput changes, as apex-ls's
CheckForIssuestext/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-parserand shims onto it withDiagnosticRule.The external analysis SPI that
Rulewas originally built for has been withdrawn — apex-ls-pmd isdeprecated and apex-ls#439 reduced
getExternalAnalysis/setExternalAnalysis/setExternalAnalysisModeto deprecated no-op stubs. In-tree,Ruleis now consumed only byapex-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-parserinbuild.sbtand assigns IDs at its ~106diagnostic creation sites. Tracked in apex-dev-tools/apex-ls#322.