diff --git a/.github/workflows/package-ci.yml b/.github/workflows/package-ci.yml index 0e78a2ab5..fe08f391a 100644 --- a/.github/workflows/package-ci.yml +++ b/.github/workflows/package-ci.yml @@ -37,6 +37,8 @@ jobs: run: yarn build - name: Build docs run: yarn docs + - name: Test documentation publication boundaries + run: yarn test:docs-publishing - id: test name: Test the project run: yarn test:ci diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 6bf5ee371..6fb6f5519 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -40,26 +40,39 @@ jobs: commit: Version Packages env: GITHUB_TOKEN: ${{ secrets.CHANGESETS_BOT_TOKEN }} - - name: Build docs + - name: Select released SDK documentation if: steps.changesets.outputs.published == 'true' + id: docs + env: + PUBLISHED_PACKAGES: ${{ steps.changesets.outputs.publishedPackages }} + run: node scripts/docs-release-plan.mjs "$RUNNER_TEMP/sdk-docs-plan.json" + - name: Build docs + if: steps.docs.outputs.has_docs == 'true' run: yarn docs - name: Checkout docs with SSH - if: steps.changesets.outputs.published == 'true' - uses: actions/checkout@v3 + if: steps.docs.outputs.has_docs == 'true' + uses: actions/checkout@v4 with: repository: reflagcom/docs ssh-key: ${{ secrets.DOCS_DEPLOY_KEY }} path: reflag-docs - - name: Copy generated docs to docs repo - if: steps.changesets.outputs.published == 'true' - run: | - rm -rf reflag-docs/sdk - cp -R dist/docs reflag-docs/sdk + # Land the docs repository's SDK importer before enabling this workflow. + # That repository owns public paths/banners; SDK sources remain here. + - name: Sync only released packages and majors + if: steps.docs.outputs.has_docs == 'true' + run: node reflag-docs/.github/scripts/sdk-docs.mjs release --source . --destination reflag-docs --plan "$RUNNER_TEMP/sdk-docs-plan.json" + - name: Check generated documentation + if: steps.docs.outputs.has_docs == 'true' + working-directory: reflag-docs + run: node .github/scripts/check-sdk-docs.mjs - name: Commit and push changes - if: steps.changesets.outputs.published == 'true' + if: steps.docs.outputs.has_docs == 'true' + working-directory: reflag-docs run: | - cd reflag-docs git config user.name "github-actions[bot]" git config user.email "github-actions[bot]@reflag.com" - git add sdk - git commit -m "Update documentation" && git push || echo "No docs changes to commit" + git add supported-languages legacy api sdk .generated/sdk-docs + if ! git diff --cached --quiet; then + git commit -m "Update released SDK documentation" + git push + fi diff --git a/package.json b/package.json index f322f1b86..d145a8ce1 100644 --- a/package.json +++ b/package.json @@ -24,6 +24,7 @@ "release-packages": "yarn build && yarn release", "release": "changeset publish", "docs": "./docs.sh", + "test:docs-publishing": "node --test scripts/docs-release-plan.test.mjs", "lint:fix": "yarn oxlint --fix .", "fmt": "yarn oxfmt --check .", "fmt:fix": "yarn oxfmt --write .", diff --git a/scripts/docs-release-plan.mjs b/scripts/docs-release-plan.mjs new file mode 100644 index 000000000..2cfc840be --- /dev/null +++ b/scripts/docs-release-plan.mjs @@ -0,0 +1,99 @@ +import assert from "node:assert/strict"; +import { execFileSync } from "node:child_process"; +import fs from "node:fs"; +import path from "node:path"; +import { pathToFileURL } from "node:url"; + +const documented = new Set([ + "browser-sdk", + "react-sdk", + "vue-sdk", + "node-sdk", + "react-native-sdk", + "management-sdk", + "cli", +]); +const versionPattern = + /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-[\da-zA-Z.-]+)?(?:\+[\da-zA-Z.-]+)?$/; +const git = (source, ...args) => + execFileSync("git", ["-C", source, ...args], { encoding: "utf8" }).trim(); + +export function selectReleases(source, published) { + assert(Array.isArray(published), "publishedPackages must be an array"); + const seen = new Set(); + const releases = []; + for (const release of published) { + assert( + release && /^@reflag\/[a-z][a-z0-9-]*$/.test(release.name), + "Invalid published package", + ); + assert( + typeof release.version === "string" && + versionPattern.test(release.version), + "Invalid published version", + ); + assert(!seen.has(release.name), "Duplicate published package"); + seen.add(release.name); + const name = release.name.slice("@reflag/".length); + if (!documented.has(name)) continue; + const pkg = JSON.parse( + fs.readFileSync( + path.join(source, "packages", name, "package.json"), + "utf8", + ), + ); + assert.equal(pkg.name, release.name); + assert.equal( + pkg.version, + release.version, + "Published/source version mismatch", + ); + assert(!pkg.private, "Private published package"); + // A prerelease must not change stable documentation or default navigation. + if (!versionPattern.exec(release.version)[4]) + releases.push({ name: release.name, version: release.version }); + } + return releases; +} + +export function releasePlan(source, published) { + assert.equal( + git(source, "status", "--porcelain", "--untracked-files=no"), + "", + "SDK source must be clean", + ); + const sourceCommit = git(source, "rev-parse", "HEAD"); + const releases = selectReleases(source, published); + for (const release of releases) + assert.equal( + git( + source, + "rev-parse", + `refs/tags/${release.name}@${release.version}^{commit}`, + ), + sourceCommit, + "Release tag/source mismatch", + ); + return { sourceCommit, releases }; +} + +if ( + process.argv[1] && + import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href +) { + const destination = process.argv[2]; + assert(destination, "Pass the release-plan output filename"); + const plan = releasePlan( + process.cwd(), + JSON.parse(process.env.PUBLISHED_PACKAGES), + ); + fs.writeFileSync(destination, `${JSON.stringify(plan, null, 2)}\n`); + if (process.env.GITHUB_OUTPUT) + fs.appendFileSync( + process.env.GITHUB_OUTPUT, + `has_docs=${plan.releases.length > 0}\n`, + ); + console.log( + `Selected ${plan.releases.length} stable package releases for documentation.`, + ); +} diff --git a/scripts/docs-release-plan.test.mjs b/scripts/docs-release-plan.test.mjs new file mode 100644 index 000000000..22ac4b835 --- /dev/null +++ b/scripts/docs-release-plan.test.mjs @@ -0,0 +1,90 @@ +import assert from "node:assert/strict"; +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; +import test from "node:test"; + +import { selectReleases } from "./docs-release-plan.mjs"; + +function fixture(t) { + const root = fs.mkdtempSync( + path.join(os.tmpdir(), "reflag-docs-release-test-"), + ); + t.after(() => fs.rmSync(root, { recursive: true, force: true })); + for (const [name, version] of [ + ["node-sdk", "2.0.0"], + ["react-sdk", "2.0.0-next.0"], + ["management-sdk", "1.9.0"], + ["cli", "1.0.4"], + ]) { + const dir = path.join(root, "packages", name); + fs.mkdirSync(dir, { recursive: true }); + fs.writeFileSync( + path.join(dir, "package.json"), + JSON.stringify({ name: `@reflag/${name}`, version }), + ); + } + return root; +} + +test("only stable, actually published SDK/tooling packages enter the plan", (t) => { + const root = fixture(t); + assert.deepEqual( + selectReleases(root, [ + { name: "@reflag/node-sdk", version: "2.0.0" }, + { name: "@reflag/react-sdk", version: "2.0.0-next.0" }, + { name: "@reflag/flag-evaluation", version: "2.0.0" }, + ]), + [{ name: "@reflag/node-sdk", version: "2.0.0" }], + ); +}); + +test("an independent or CLI-v1 release cannot select unreleased web SDKs", (t) => { + const root = fixture(t); + for (const release of [ + { name: "@reflag/management-sdk", version: "1.9.0" }, + { name: "@reflag/cli", version: "1.0.4" }, + ]) + assert.deepEqual(selectReleases(root, [release]), [release]); + assert.deepEqual(selectReleases(root, []), []); +}); + +test("source mismatches, malformed inputs and duplicates fail closed", (t) => { + const root = fixture(t); + assert.throws(() => selectReleases(root, {}), /array/); + assert.throws( + () => selectReleases(root, [{ name: "../../escape", version: "2.0.0" }]), + /Invalid published package/, + ); + assert.throws( + () => selectReleases(root, [{ name: "@reflag/node-sdk", version: "main" }]), + /Invalid published version/, + ); + assert.throws( + () => + selectReleases(root, [{ name: "@reflag/node-sdk", version: "2.0.1" }]), + /version mismatch/, + ); + const item = { name: "@reflag/node-sdk", version: "2.0.0" }; + assert.throws(() => selectReleases(root, [item, item]), /Duplicate/); +}); + +test("workflow scopes documentation by release and delegates version routing to the docs importer", () => { + const release = fs.readFileSync( + new URL("../.github/workflows/publish.yml", import.meta.url), + "utf8", + ); + assert.doesNotMatch(release, /rm -rf|cp -R dist\/docs|echo "No docs changes/); + assert.match(release, /steps\.changesets\.outputs\.publishedPackages/); + assert.match(release, /steps\.docs\.outputs\.has_docs == 'true'/); + assert.match( + release, + /sdk-docs\.mjs release --source \. --destination reflag-docs --plan/, + ); + assert.match(release, /node \.github\/scripts\/check-sdk-docs\.mjs/); + const ci = fs.readFileSync( + new URL("../.github/workflows/package-ci.yml", import.meta.url), + "utf8", + ); + assert.match(ci, /yarn test:docs-publishing/); +});