tools: add validation for internal bindings

Author: dario-piotrowicz

.github/workflows/internal-bindings-validation.yml

@@ -0,0 +1,43 @@
+name: Internal Bindings Validation
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - src/**
+      - lib/**
+      - test/**
+  push:
+    branches:
+      - main
+      - canary
+      - v[0-9]+.x-staging
+      - v[0-9]+.x
+      - dario/58162/internal-bindings-validation
+    paths:
+      - src/**
+      - lib/**
+      - test/**
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test-internal-binding-validation:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+        with:
+          persist-credentials: false
+          path: node
+      - name: Validate internal binding functions typing
+        run: |
+          node ./tools/internal-bindings-functions-validation/typings.mjs
+      - name: Validate internal binding functions usage
+        run: |
+          node ./tools/internal-bindings-functions-validation/usage.mjs

tools/internal-bindings-functions-validation/README.md

@@ -0,0 +1,6 @@
+When a function is defined in the C++ layer, it can be registered to an internal binding, making it accessible from the JavaScript layer. The scripts in this directory provide automated validation for this process. Specifically, there are two scripts:
+
+- `typings.mjs`: Ensures that every function registered to an internal binding has a corresponding type defined in the [typings directory](../../typings).
+- `usage.mjs`: Verifies that every function registered to an internal binding is utilized in at least one JavaScript file, either in the [lib directory](../../lib) or the [test directory](../../test).
+
+Note: This validation is a best-effort approach that relies on reading file contents and using regular expressions for the checks. It can be enhanced over time if necessary.

tools/internal-bindings-functions-validation/_shared.mjs

@@ -0,0 +1,34 @@
+import { globSync, readFileSync } from 'node:fs';
+import { relative, dirname } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
+export const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const srcFiles = globSync(`${__dirname}/../../src/**/*.cc`);
+
+export const declaredSrcFunctions = (
+  await Promise.all(
+    srcFiles.map(async (srcFile) => {
+      const srcFilePath = relative(`${__dirname}/../..`, srcFile);
+
+      const srcFileContents = await readFile(srcFile, 'utf8');
+      const matches = srcFileContents.matchAll(
+        /\b(SetMethod|SetMethodNoSideEffect)\([^,]*,\s+[^,]*,\s+"(?<functionName>.*?)",\s+[^)]*?\);/g
+      );
+      return [...matches].map((match) => {
+        const { functionName } = match.groups;
+        return { srcFilePath, functionName };
+      });
+    })
+  )
+)
+  .filter((declarations) => declarations.length)
+  .flat();
+
+export function functionPresentInJsFiles(files, functionName) {
+  return files.some((file) => {
+    const fileContents = readFileSync(file);
+    return new RegExp(`\\b${functionName}\\b`).test(fileContents);
+  });
+}