Repository navigation
Simplify the tooling now that it is not a studio product with a CLI attached #65
Description
Work out what can be simplified now that this is no longer a studio product with a CLI tacked on the side.
From the investigations list in the working document, office hours 2026-08-14 (api-commons/spotlight-spec#19):
Investigating simplifications that can be made to the tooling based on this not primarily being used for Stoplight Studio with some CLI tacked on.
The premise
A lot of the shape of this codebase is a consequence of a product that no longer exists here. The linter's primary consumer was a desktop editor: it needed to run incrementally as someone typed, to report positions back into an editor surface, to be embeddable in an application's lifecycle, and to be configurable through that application's UI. The CLI was the secondary surface.
That relationship is now reversed, permanently. The primary consumers are the CLI, CI pipelines, and library use by people wiring linting into their own systems. Nobody here is building a studio.
Which means some amount of the architecture is paying rent for a tenant who moved out — and some of it absolutely is not, because the same machinery serves browser-based and in-editor use that is still very real (api-commons/spotlight-spec#11 makes runtime portability normative, and at least one government programme depends on it).
The actual task
Separate those two categories, carefully and with evidence:
- Editor-driven complexity that no longer serves anyone — candidates for removal.
- Editor-driven complexity that turned out to be the thing that makes browser and embedded use possible — keep, and document why, so nobody deletes it in a later cleanup.
Acceptance criteria
- A written inventory of the architectural decisions traceable to the studio, and which category each falls into
- Removals proposed individually, so each can be argued with, rather than as one sweeping refactor
- Nothing removed that runtime portability depends on
Activity
kinlane commentedon Aug 21, 2026
From office hours, 2026-08-21. Agreement in the room on sequencing, and an insider account of
where the debt came from.
Sequencing. Clean the tool first; ruleset and specification work runs in parallel, not
behind it. The two do not block each other and should not be scheduled as if they do.
Two distinct kinds of debt, and this issue currently blurs them:
Shape debt — the codebase is shaped by a product that is no longer the product. That is
what this issue was filed about.
Dependency debt — vendored forks and transitive dependencies that nobody maintains. From
the person who created a good deal of it:
The forking was "the quickest way to ship things," which is an honest and familiar reason, and
it is why Replace the vendored JSON Ref bundler — stabilise rather than fork #64 (replace the vendored JSON Ref bundler — stabilise rather than fork) is the
pattern rather than the exception.
Worth an inventory of the vendored and unmaintained dependencies before any of it is touched,
because it also bears on
spotlight-tools#15(supply chain) — an unmaintained transitivedependency is a supply-chain exposure, not only a maintenance annoyance.
Accepted consequence, stated on the call: doing this housekeeping makes the fork divergent
from upstream, deliberately. Consistent with the standing posture. Upstream has resumed merging
pull requests in the last few weeks; that does not change the plan.
Filed from the office hours of 2026-08-21. Full notes: #34.
kinlane commentedon Aug 28, 2026
From the Spotlight Rules office hours on 28 August 2026 (api-commons/spotlight-spec#40) — the inherited rules got classified on the call, by the person who wrote a lot of them.
That is two distinct categories, and they have different fates:
The second category is the more interesting finding, because it is a governance point rather than a cleanup point: the default ruleset that thousands of pipelines run unmodified (api-evangelist/roadmap#87) contains rules whose purpose is to make documents look good in one company's product. That is worth saying plainly when the new default ruleset ships.
Both feed #62 directly — the classification above is roughly the sorting rule for what stays in the new default, what moves to a compatibility layer, and what is dropped. And the person who can date most of these was on the call and is willing to be asked, so the provenance pass should happen while that is true.
Related: #62 · #21 · api-commons/spotlight-spec#41 · api-evangelist/roadmap#87.