New gate for stdlib API check

.github/workflows/engine-changed-files.yml

@@ -11,6 +11,9 @@ on:
       any_changed:
         description: "Returns `true` when any of the filenames have changed"
         value: ${{ jobs.engine-changed-files.outputs.any_changed }}
+      stdlib_api_any_changed:
+        description: "Returns `true` when any of the Standard library API filenames have changed"
+        value: ${{ jobs.stdlib-api-changed-files.outputs.any_changed }}
 
 jobs:
   engine-changed-files:
@@ -53,3 +56,29 @@ jobs:
           for file in ${ALL_CHANGED_FILES}; do
             echo "$file"
           done
+  stdlib-api-changed-files:
+    runs-on: ubuntu-latest
+    name: Changed Standard libs API docs files
+    outputs:
+      all_changed_files: ${{ steps.stdlib-api-changed-files.outputs.all_changed_files }}
+      any_changed: ${{ steps.stdlib-api-changed-files.outputs.any_changed }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      - name: Get changed files
+        id: stdlib-api-changed-files
+        uses: tj-actions/changed-files@v45
+        with:
+          files: |
+            distribution/lib/Standard/**/docs/api/**.md
+      - name: List all changed files
+        env:
+          ALL_CHANGED_FILES: ${{ steps.stdlib-api-changed-files.outputs.all_changed_files }}
+        run: |
+          if [[ "${{ steps.stdlib-api-changed-files.outputs.any_changed }}" == "true" ]]; then
+            echo "API docs files changed:"
+          fi
+          for file in ${ALL_CHANGED_FILES}; do
+            echo "$file"
+          done

.github/workflows/engine-checks.yml

@@ -237,6 +237,47 @@ jobs:
       GRAAL_EDITION: GraalVM CE
     permissions:
       checks: write
+  enso-build-ci-gen-job-standard-library-api-check-linux-amd64:
+    name: Standard Library API check (linux, amd64)
+    runs-on:
+      - self-hosted
+      - Linux
+    steps:
+      - if: runner.os == 'Windows'
+        name: Setup required bazel environment
+        run: "\n\"BAZEL_SH=C:\\Program Files\\Git\\bin\\bash.exe\" >> $env:GITHUB_ENV\n\"BAZEL_VC=C:\\BuildTools\\VC\" >> $env:GITHUB_ENV\n        "
+        shell: pwsh
+      - name: Setup bazel environment
+        uses: bazel-contrib/setup-bazel@0.13.0
+        with:
+          bazelrc: build --remote_cache=grpcs://${{ vars.ENSO_BAZEL_CACHE_URI }} --remote_cache_header="authorization=Basic ${{ secrets.ENSO_BAZEL_CACHE_TOKEN }}"
+          output-base: ${{ runner.os == 'Windows' && 'c:/_bazel' || '' }}
+      - name: Expose Artifact API and context information.
+        uses: actions/github-script@v7
+        with:
+          script: "\n    core.exportVariable(\"ACTIONS_RUNTIME_TOKEN\", process.env[\"ACTIONS_RUNTIME_TOKEN\"])\n    core.exportVariable(\"ACTIONS_RUNTIME_URL\", process.env[\"ACTIONS_RUNTIME_URL\"])\n    core.exportVariable(\"GITHUB_RETENTION_DAYS\", process.env[\"GITHUB_RETENTION_DAYS\"])\n    console.log(context)\n    "
+      - name: Checking out the repository
+        uses: actions/checkout@v4
+        with:
+          clean: false
+          submodules: recursive
+      - name: Build Script Setup
+        run: ./run --help || (git clean -ffdx && ./run --help)
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - if: "(contains(github.event.pull_request.labels.*.name, 'CI: Clean build required') || inputs.clean_build_required)"
+        name: Clean before
+        run: ./run git-clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - run: ./run backend stdlib-api-check
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - if: "(always()) && (contains(github.event.pull_request.labels.*.name, 'CI: Clean build required') || inputs.clean_build_required)"
+        name: Clean after
+        run: ./run git-clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
   enso-build-ci-gen-job-standard-library-tests-graal-vm-ce-linux-amd64:
     name: Standard Library Tests (GraalVM CE) (linux, amd64)
     runs-on:

.github/workflows/engine-pull-request.yml

@@ -14,6 +14,7 @@ concurrency:
 
 permissions:
   checks: write
+  pull-requests: write
 
 jobs:
   engine-changed-files:
@@ -35,10 +36,22 @@ jobs:
     if: needs.engine-changed-files.outputs.any_changed == 'true' || github.ref == 'refs/heads/develop'
     secrets: inherit
 
+  stdlib-api-changes-label:
+    name: 🏷 Append Standard library API change label
+    runs-on: ubuntu-latest
+    needs: [engine-changed-files]
+    if: needs.engine-changed-files.outputs.stdlib_api_any_changed == 'true'
+    steps:
+      - name: Add label to the PR
+        uses: actions-ecosystem/action-add-labels@v1
+        with:
+          labels: "-libs-API-change"
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
   required-checks:
     name: Engine Required Checks
     runs-on: ubuntu-latest
-    needs: [engine-checks]
+    needs: [engine-checks, stdlib-api-changes-label]
     if: always()
     steps:
       - name: Checks Summary

build_tools/build/src/ci_gen.rs

@@ -784,6 +784,7 @@ pub fn engine_checks() -> Result<Workflow> {
         ..default()
     };
     workflow.add(PRIMARY_TARGET, job::VerifyLicensePackages);
+    workflow.add(PRIMARY_TARGET, job::StandardLibraryApiCheck);
     for target in PR_REQUIRED_TARGETS {
         add_backend_checks(&mut workflow, target, graalvm::Edition::Community);
     }

build_tools/build/src/ci_gen/job.rs

@@ -344,6 +344,18 @@ impl JobArchetype for StandardLibraryTests {
     }
 }
 
+#[derive(Clone, Copy, Debug)]
+pub struct StandardLibraryApiCheck;
+
+impl JobArchetype for StandardLibraryApiCheck {
+    fn job(&self, target: Target) -> Job {
+        let job_name = "Standard Library API check";
+        let run_command = "backend stdlib-api-check";
+        let job = RunStepsBuilder::new(run_command).build_job(job_name, target);
+        job
+    }
+}
+
 /** This is a temporary workaround.
  *
  * The Cloud tests preparation requires `aws` CLI to be installed on the machine.

build_tools/build/src/engine.rs

@@ -247,6 +247,7 @@ pub struct BuildConfigurationFlags {
     pub test_java_generated_from_rust: bool,
     /// Verify License Packages in Distributions.
     pub verify_packages: bool,
+    pub stdlib_api_check: bool,
 }
 
 #[derive(Clone, Debug)]
@@ -294,6 +295,9 @@ impl BuildConfigurationResolved {
             config.generate_java_from_rust = true;
         }
 
+        if config.stdlib_api_check {
+            config.build_engine_package = true;
+        }
         Self(config)
     }
 }
@@ -352,6 +356,7 @@ impl Default for BuildConfigurationFlags {
             generate_java_from_rust: false,
             test_java_generated_from_rust: false,
             verify_packages: false,
+            stdlib_api_check: false,
         }
     }
 }

build_tools/build/src/engine/context.rs

@@ -380,6 +380,12 @@ impl RunContext {
 
         perhaps_test_java_generated_from_rust_job.await.transpose()?;
 
+        // === Stdlib API check ===
+        debug!("Running standard libraries API check.");
+        if self.config.stdlib_api_check {
+            self.stdlib_api_check(&enso).await?;
+        }
+
         // === Run benchmarks ===
         let build_benchmark_task = if self.config.build_benchmarks {
             let build_benchmark_task_names = [
@@ -564,6 +570,99 @@ impl RunContext {
 
         Ok(())
     }
+
+    /// Checks API for all the standard libraries that have non-empty `docs/api` directory.
+    async fn stdlib_api_check(&self, built_enso: &BuiltEnso) -> Result {
+        let libs_to_check = self.stdlibs_with_api()?;
+        debug!("Checking API for standard libraries: {:?}", libs_to_check);
+        for lib in self.stdlibs_with_api()? {
+            self.lib_api_check(built_enso, &lib).await?;
+        }
+        Ok(())
+    }
+
+    /// Returns list of all the standard libraries with non-empty `docs/api` directory.
+    fn stdlibs_with_api(&self) -> Result<Vec<StdLib>> {
+        let mut stdlibs: Vec<StdLib> = vec![];
+        let lib_root = self.repo_root.distribution.lib.join("Standard");
+        for dir in std::fs::read_dir(lib_root)? {
+            // The path to the library is of this form:
+            // distribution/lib/Standard/<lib_name>/0.0.0-dev
+            let dir = dir?;
+            let lib_dir = dir.path().join("0.0.0-dev");
+            assert!(lib_dir.exists(), "Directory {} does not exist", lib_dir.display());
+            let api_dir = lib_dir.join("docs").join("api");
+            if api_dir.exists() {
+                let libname = dir.file_name().to_string_lossy().to_string();
+                stdlibs.push(StdLib { name: libname.to_string(), path: lib_dir });
+            }
+        }
+        Ok(stdlibs)
+    }
+
+    /// Checks the API for a single library
+    /// #parameters
+    /// - `lib_path` Path to the library inside the `distribution` directory. The `docs/api`
+    ///   directory inside `lib_path` is expected to exist.
+    async fn lib_api_check(&self, built_enso: &BuiltEnso, lib: &StdLib) -> Result {
+        let old_api_dir = lib.path.join("docs").join("api");
+        assert!(old_api_dir.exists());
+        debug!(
+            "Checking API for library Standard.{}, its API dir is in {:?}",
+            lib.name, old_api_dir
+        );
+        // `lib_path_in_built_distribution` points to the lib in the `built-distribution`
+        // directory, which is not under VCS. We will regenerate the API in this directory
+        // and compare it to the one from `lib_path`.
+        let lib_path_in_built_distribution = self
+            .repo_root
+            .built_distribution
+            .enso_engine_triple
+            .engine_package
+            .lib
+            .join_iter(["Standard", lib.name.as_str()])
+            .join(self.paths.version().to_string());
+        let new_api_dir = lib_path_in_built_distribution.join("docs").join("api");
+        let mut cmd = built_enso
+            .cmd()?
+            .with_arg("--docs")
+            .with_arg("api")
+            .with_arg("--in-project")
+            .with_arg(lib_path_in_built_distribution);
+        cmd.run_ok().await?;
+        let diff = ide_ci::fs::diff_dirs(&old_api_dir, &new_api_dir).await;
+        match diff {
+            Ok(_) => Ok(()),
+            Err(err) => {
+                let suggested_cmd = built_enso
+                    .cmd()?
+                    .with_arg("--docs")
+                    .with_arg("api")
+                    .with_arg("--in-project")
+                    .with_arg(lib.path.clone());
+                error!("API check failed for library Standard.{}", lib.name);
+                error!("Current API vs Old API: {}", err);
+                error!("If you wish to overwrite the current API in the directory {}, run the following command {},
+                       and commit the modified files",
+                  old_api_dir.display(),
+                  suggested_cmd.describe()
+                );
+                bail!("API check failed for library Standard.{}", lib.name);
+            }
+        }
+    }
+}
+
+#[derive(Debug)]
+struct StdLib {
+    name: String,
+    path: PathBuf,
+}
+
+impl Display for StdLib {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        write!(f, "Standard.{}", self.name)
+    }
 }
 
 /// Upload the directory with Enso-generated test results.