Inherited Stoplight/SmartBear references: a classified inventory, because most of them must not be touched

[kinlane]

grep -rli 'stoplight\|smartbear' matches 574 files in this repository. That number is the reason this needs an inventory before it needs a sweep: most of those matches are correct and must stay. A well-meaning find-and-replace across them would break schema resolution and the dependency tree, and would strip attribution the Apache licence requires.

This issue classifies them so the cleanup can proceed a category at a time, safely, over however long it takes.

Category A — legitimate dependencies. Do not touch.

This build depends on ten separately-published @stoplight/* npm packages that are not part of this fork:

Package	Files
@stoplight/types	239
@stoplight/path	72
@stoplight/json	71
@stoplight/yaml	19
@stoplight/json-ref-resolver	18
@stoplight/ordered-object-literal	12
@stoplight/better-ajv-errors	12
@stoplight/yaml-ast-parser	6
@stoplight/json-ref-readers	6

This is the single most important line in this issue: you can fork the linter, but installing it still pulls ten packages published by the organization you forked away from. Forking the CLI did not fork the supply chain. Whether that is acceptable, vendorable, or replaceable is a real question and it belongs in #15 — but it is not "baggage," it is a dependency, and it does not get swept.

Category B — internal schema $id values. Do not touch.

https://stoplight.io/json-schema/draft/2020-12 and .../meta/validation appear as $id and $ref in bundled local schema files under packages/rulesets/src/{oas,arazzo}/schemas/. These are identifiers, not addresses — the schemas are compiled in and never fetched. Rewriting them would break AJV's internal $ref resolution while looking like a harmless string change. Leave them.

Category C — self-references, gated on #8

331 files contain @stoplight/spectral-*, which are this monorepo's own package names. These change if and only if #8 decides to rename the packages, and then they change mechanically and all at once. Nothing to do here until that call is made.

Category D — actual baggage. This is the work.

• Broken rule documentation links — three documentationUrl values pointing at 404s on meta.stoplight.io. Split out as Every rule this build emits links to a 404 on Stoplight's docs site #20, and it is the best candidate to go first.
• docs/ — 15 files with links into meta.stoplight.io and stoplight.io/p/docs/gh/stoplightio/spectral, plus references to Stoplight Studio.
• CONTRIBUTING.md — mentions Stoplight 13 times and describes a review process and expectations that are not this project's. Tracked as Rewrite the inherited CONTRIBUTING.md #6; a stopgap note has been added inline pending that rewrite.
• CHANGELOG.md — upstream's history, which is correct and should be kept, but needs a clear marker for where this fork's history begins.
• Test fixtures — spectral.stoplight.io/ruleset appears in packages/ruleset-migrator/src/__tests__/, but only as a mocked fetch URL. Cosmetic, lowest priority, and safe to leave for a long time.
• staging.stoplight.io / prod.stoplight.io — appear in test fixtures. Same category.

Category E — attribution. Must stay, by licence.

LICENSE, the Spectral credit in README.md, and the copyright headers. Apache-2.0 §4 requires retaining these, and the project would want to anyway. The new NOTICE (#5) states the lineage explicitly and says who does not maintain this build.

Already done

The org-level references that routed real people to the wrong place — CODEOWNERS naming an unresolvable Stoplight team plus three AsyncAPI maintainers, the Stoplight Code of Conduct, upstream's FUNDING listing, and the Jira workflow calling stoplightio/.github@master with secrets: inherit — are handled in #16.

How this proceeds

One category at a time, one issue per category, one pull request per issue. D is the whole job. A, B, C and E are here so that nobody — including a future contributor with a regex and good intentions — mistakes them for it.

[kinlane]

Additions from an independent recount, and a duplicate closed.

I ran this inventory separately and opened #26 before seeing this issue. #26 is closed as a duplicate — this one is better, and it caught two things mine missed: Category B, the schema $id values, which look like harmless string replacements and would break AJV's internal $ref resolution, and @stoplight/yaml-ast-parser, which makes it ten packages rather than the seven declared directly in the manifests.

Four things from that recount that are additive here:

release-docker.yml pushes to Stoplight's Docker Hub namespace

Not in any category above, and worse than cosmetic — this is release infrastructure that would misfire on first use:

docker build . --tag stoplight/spectral:${GIT_SHA}
docker tag stoplight/spectral:${GIT_SHA} stoplight/spectral:${FULL_VERSION}
docker tag stoplight/spectral:${GIT_SHA} stoplight/spectral:${MINOR_VERSION}
docker tag stoplight/spectral:${GIT_SHA} stoplight/spectral:${MAJOR_VERSION}
docker tag stoplight/spectral:${GIT_SHA} stoplight/spectral:latest
docker push stoplight/spectral:latest

It would fail on credentials, which is the good outcome. It belongs with #11, which already proposes ghcr.io/api-commons/spotlight-tools.

Category A has a version-sprawl problem independent of the vendoring question

Whatever gets decided in #15, these ranges need reconciling regardless:

• @stoplight/types — pinned simultaneously at ^13.6.0, ~13.6.0, ^13.15.0 and ^14.1.1 across the workspace
• @stoplight/json — four different ranges: ^3.17.0, ^3.17.1, ^3.20.1, ~3.21.0
• @stoplight/path — 1.3.2 and ^1.3.2
• @stoplight/yaml — ^4.2.2, ~4.2.3, ~4.3.0

A major-version split across the workspace on the type package everything imports is a real hazard, not a tidiness issue.

Category C reaches into .github/actions/

The five composite actions — build-binary, cached-dependencies, install-ldid, test-harness-linux, test-harness-windows — invoke workspace names directly (yarn workspace @stoplight/spectral-cli pkg …). They move with #8 along with the source imports, and are easy to miss because they are not under packages/.

On CHANGELOG.md, one thing worth stating explicitly

Counted by line rather than by file, 516 lines link to the upstream repository, and the overwhelming majority are changelog entries of the form [#1615](https://github.com/stoplightio/spectral/issues/1615). Those links are correct. That work happened, in that repository, at those numbers, and rewriting them would be falsifying a changelog — which is the opposite of the argument this project makes. Agreed on adding a marker for where this fork's history begins; the entries above it should not be touched.

On the counts

This recount was line-level over tracked files: 3,791 occurrences across 578 files, versus the 574 here. The four-file difference is NOTICE, GOVERNANCE.md, SECURITY.md and CODE_OF_CONDUCT.md — files added after this issue was written, which mention Stoplight and SmartBear deliberately, to say they do not maintain this build. Category E growing is the system working.