Add @internal JSDoc annotations and CI lint to enforce export boundaries

[parthban-db]

🥞 Stacked PR

Use this link to review incremental changes.

• stack/mark-internal-internal [Files changed]

---

Summary

Adds @internal JSDoc tags to exported symbols that are not part of the public API and introduces a CI lint script to enforce the convention going forward.

Why

Source files use export for cross-file usage within a package, but only a subset of those exports are re-exported from index.ts barrel files (the actual public API). Today, there is no way to tell at a glance whether an exported symbol is public or package-internal — you have to cross-reference the barrel file manually. This makes it easy to accidentally treat an internal symbol as public, or to forget marking a new internal export.

What changed

Interface changes

None. No new public API surface. The @internal tag is a documentation-only annotation that signals "this export exists for intra-package use and is not part of the public contract."

Behavioral changes

None. Existing consumers are unaffected.

Internal changes

• @internal annotations added to three non-public exports:
  • toCode() in packages/databricks/src/apierror/apierror.ts
  • parseErrorDetails() in packages/databricks/src/apierror/details.ts
  • rand in packages/databricks/src/api/retrier.ts
• scripts/check-internal-exports.ts — new lint script that uses the TypeScript compiler API to:
  1. Read each package's exports field to discover barrel files.
  2. Collect the set of publicly re-exported symbol names.
  3. Walk source files and verify that non-public exports have /** @internal */ and public exports do not.
• package.json — added check:internal script (node --experimental-strip-types; no new dependencies).
• .github/workflows/ci.yml — added check:internal step to the lint job.

How is this tested?

• npm run check:internal passes clean on the current codebase.
• Verified that removing @internal from a non-public export (toCode) causes the script to fail with an actionable error message.
• Verified that adding @internal to a public export (APIError) causes the script to fail.