spec - distribution.rq

Idea	File	Summary
deployment_flow	reqlan rq/distribution/distribution.rq	On push to main, if pending changesets remain, the release workflow applies them with `pnpm changeset version`. This bumps package. json for each affected package and writes changelogs. The workflow commits the result, creates annotated tags for every bumped publishable package, and pushes the commit and tags back to main. Release tags use `site/v{version}`, `ext/v{version}`, `language/v{version}`, `analytical/v{version}`, and `cli/v{version}` where `{version}` is the semver from that package's package. json. Deployment is tag-driven for every channel per ["./distribution.rq".release_tagging]; the release workflow only versions and tags. GitHub Actions pushes with the default `GITHUB_TOKEN` do not trigger other workflows, so site and npm deploy are also invoked directly from the release workflow. Optional `RELEASE_PAT` allows tag pushes to trigger downstream workflows for manual reruns and external CI. Recursive runs are prevented by skipping the release workflow for release commits. Tag patterns and downstream deploy workflows follow ["./distribution.rq".release_tagging]. The implementation lives in ["../../.github/workflows/release.yml"].
extension_distribution	reqlan rq/distribution/distribution.rq	Azure DevOps builds, tests, packages, and publishes the VS Code extension only for tags matching `ext/v*`. Tags are created by ["./distribution.rq".deployment_flow]. The extension version comes from packages / extension / package. json at the tag; the pipeline must not overwrite it from the tag suffix. The implementation lives in ["../../azure-pipelines.yml"]. VSIX packaging follows ["./distribution.rq".vsix_export]. Marketplace publish is complemented by Open VSX per ["./distribution.rq".openvsx_registry].
extension_package	reqlan rq/distribution/distribution.rq	The VS Code extension lives in packages / extension with npm package name `reqlan-extension` ( Marketplace / Open VSX id `reqlan.reqlan-extension` ). Its package. json version is the authoritative Marketplace and Open VSX release version.
extension_readme	reqlan rq/distribution/distribution.rq	The VSIX package must include a README for the Marketplace and Open VSX listings. Contact and repository links come from [phonebook_reqs.phonebook] via ["../../scripts/phonebook.ts"] per [phonebook_reqs.extension_readme_links]. Release notes are appended from ["../../packages/extension/CHANGELOG.md"], which Changesets maintains per [version_management]. Generated during extension build from ["../../packages/extension/README.template.md"] by ["../../packages/extension/scripts/generate-readme.ts"] per ["../development/build.rq".extension_readme_build].
grammar_linguist	reqlan rq/distribution/distribution.rq	The grammar should be updated to use https: / / github. com / github-linguist / linguist Acceptance is dependent on maturity and usage.
npm_distribution	reqlan rq/distribution/distribution.rq	npm publishing runs only when a `language/v`, `analytical/v`, or `cli/v*` tag is pushed. Tags are created by ["./distribution.rq".deployment_flow]; the npm workflow does not publish on ordinary commits. The deploy workflow builds language / analytical / cli once, then publishes each package in sequence via `pnpm --filter <pkg> publish --access public --no-git-checks` ( language, then analytical, then cli ). Before each package publishes, ["../../scripts/skip-already-published.mjs"] with `--filter <pkg>` checks the public npm registry and skips that step when the version is already published ( sets `should_publish=false` ). That avoids re-attempting already-published versions under OIDC. Auth uses npm trusted publishing ( OIDC ) from GitHub Actions — no long-lived `NPM_TOKEN`. Workflow requirements: `permissions.id-token: write`, Node ≥ 22. 14 with npm ≥ 11. 5. 1, registry `https://registry.npmjs.org`. Each of `@reqlan/language`, `@reqlan/analytical`, and `@reqlan/cli` must have a Trusted Publisher on npmjs. com for GitHub Actions with org / user `littletuna4`, repository `reqlan`, workflow filename `deploy-npm.yml`, allowed action `npm publish`. Package `repository.url` must match `https://github.com/littletuna4/reqlan.git`. Provenance attestations are generated automatically for public packages from this public repo. Bootstrap: first publish of each scoped package can be done locally ( you must be logged in to npm as an `@reqlan` org member ) with `pnpm --filter @reqlan/language publish --access public --no-git-checks`, then analytical, then cli — or wait for the trusted-publisher CI path after packages exist and Trusted Publisher is configured. Note: Changesets `ignore` only skips version bumps; packages must be `private: true` to skip local `changeset publish` ( `pnpm run release:npm` ) as with `reqlan-mcp` and `reqlan-extension`. CI publishes per-package and does not use `changeset publish`. Published packages declare `publishConfig.access: public`. Implementation: ["../../.github/workflows/deploy-npm.yml"], ["../../scripts/skip-already-published.mjs"], and root `release:npm` in ["../../package.json"] for local changeset-based publish. Docs: ["https://docs.npmjs.com/trusted-publishers"].
npm_package_readme	reqlan rq/distribution/distribution.rq	Publishable npm packages ( `@reqlan/language`, `@reqlan/analytical`, `@reqlan/cli` ) ship README. md generated from each package's `README.template.md`. Pattern matches [extension_readme]: centered logo, package name, description, features, phonebook links, and Changesets changelog body. Generated by ["../../scripts/generate-npm-package-readmes.ts"] via root `pnpm run build:readme`. Contact and repository links come from [phonebook_reqs.phonebook] via ["../../scripts/phonebook.ts"] per [phonebook_reqs.npm_package_readme_links].
openvsx_registry	reqlan rq/distribution/distribution.rq	The extension should be published to the Open VSX registry at https: / / open-vsx. org so it is installable in editors that use Open VSX instead of the Visual Studio Marketplace. Publishing should use the same tag-driven `ext/v*` releases as ["./distribution.rq".extension_distribution]. The packaged VSIX from ["./distribution.rq".vsix_export] is the artifact published to Open VSX. Azure DevOps is the authoritative publish workflow; Open VSX publish belongs in ["../../azure-pipelines.yml"] alongside marketplace deploy.
release_tagging	reqlan rq/distribution/distribution.rq	Deployment is tag-driven rather than commit-driven for every publishable channel. Tags are created automatically by ["./distribution.rq".deployment_flow], not manually. Site deployments are triggered by Git tags matching `site/v` via ["./distribution.rq".site_distribution]. VS Code extension publishing is triggered by Azure DevOps tags matching `ext/v` via ["./distribution.rq".extension_distribution] and ["./distribution.rq".openvsx_registry]. npm publishing is triggered by Git tags matching `language/v`, `analytical/v`, or `cli/v*` via ["./distribution.rq".npm_distribution]. The tag suffix after the channel prefix ( `site/v`, `ext/v`, `language/v`, `analytical/v`, `cli/v` ) equals the package. json version at that tag.
root_readme	reqlan rq/distribution/distribution.rq	The GitHub repository README is the primary repo lander per ["./landers.rq".landers]. Site, marketplace, repository, and contact links come from [phonebook_reqs.phonebook] via ["../../scripts/phonebook.ts"] per [phonebook_reqs.root_readme_links]. Generated from ["../../README.template.md"] by ["../../scripts/generate-root-readme.ts"].
site_distribution	reqlan rq/distribution/distribution.rq	GitHub Pages deployment runs only when an `site/v*` tag is pushed. Tags are created by ["./distribution.rq".deployment_flow]; the site workflow does not deploy on ordinary commits. The implementation lives in ["../../.github/workflows/deploy-site.yml"].
site_package	reqlan rq/distribution/distribution.rq	The static site lives in site / with npm package name `site`. Its package. json version identifies site releases for tagging.
stopgap	reqlan rq/distribution/distribution.rq	Stopgap distribution is at https: / / marketplace. visualstudio. com / manage / publishers / reqlan
version_management	reqlan rq/distribution/distribution.rq	Package versions are managed with Changesets via ["../../.changeset/config.json"]. Publishable channels ( each tag-driven ): - Marketplace / Open VSX: ["./distribution.rq".extension_package] ( private npm package; tagged `ext/v` ) - GitHub Pages: ["./distribution.rq".site_package] ( tagged `site/v` ) - npm: `@reqlan/language`, `@reqlan/analytical`, and `@reqlan/cli` ( tagged `language/v`, `analytical/v`, `cli/v*` ) Internal tool `reqlan-mcp` is ignored by Changesets and marked `private` so it is never published to npm ( distributed with the extension / local MCP config instead ). Contributors record release intent by adding a changeset file when a publishable package changes.
vsix_export	reqlan rq/distribution/distribution.rq	The VSIX includes logo assets from the extension media build: PNG for marketplace icon, language file icon, activity bar, and README; WebP as a raster fallback.
workflow_deduplication	reqlan rq/distribution/distribution.rq	Extension publish automation should have a single authoritative workflow to avoid duplicate marketplace releases. Azure DevOps is the authoritative extension publishing workflow per ["./distribution.rq".extension_distribution] and ["./distribution.rq".openvsx_registry]. The site remains deployed by GitHub Actions per ["./distribution.rq".site_distribution]. npm packages are published by GitHub Actions per ["./distribution.rq".npm_distribution]. Versioning and tag creation are owned by GitHub Actions per ["./distribution.rq".deployment_flow].

Initialising graph…

Members

Cluster graph