Address TypeScript SDK docs review feedback

Keeps selective-checks accurate for the new ts-sdk docs build (tsconfig.json
and package.json changes now trigger it, and docs-only package.json/lock
changes no longer trigger the unrelated supervisor-schema check), fixes the
alphabetical ordering of the new run-ts-sdk-docs row, simplifies the
@msgpack/msgpack path mapping to resolve through its package.json instead of
a hardcoded internal path, wraps the long tsconfig.json comment, and aligns
the README's cancellation section wording with task.ts's TSDoc.

Author: jason810496

dev/breeze/doc/ci/04_selective_checks.md

@@ -595,8 +595,8 @@ GitHub Actions to pass the list of parameters to a command to execute
 | run-mypy                                                | Whether mypy check is supposed to run in this build                                                     | true                                     |      |
 | run-system-tests                                        | Whether system tests should be run ("true"/"false")                                                     | true                                     |      |
 | run-task-sdk-tests                                      | Whether Task SDK tests should be run ("true"/"false")                                                   | true                                     |      |
-| run-ts-sdk-e2e-tests                                    | Whether TypeScript SDK e2e tests should be run — on `ts-sdk/`, TS e2e test, or Node coordinator changes ("true"/"false")          | true                                     |      |
 | run-ts-sdk-docs                                         | Whether the TypeScript SDK API reference should be built — on `ts-sdk/docs/` or `ts-sdk/src/` changes, including Markdown ("true"/"false")          | true                                     |      |
+| run-ts-sdk-e2e-tests                                    | Whether TypeScript SDK e2e tests should be run — on `ts-sdk/`, TS e2e test, or Node coordinator changes ("true"/"false")          | true                                     |      |
 | run-ui-tests                                            | Whether UI tests should be run ("true"/"false")                                                         | true                                     |      |
 | run-unit-tests                                          | Whether unit tests should be run ("true"/"false")                                                       | true                                     |      |
 | run-www-tests                                           | Whether Legacy WWW tests should be run ("true"/"false")                                                 | true                                     |      |

dev/breeze/src/airflow_breeze/utils/selective_checks.py

@@ -487,13 +487,19 @@ def __hash__(self):
         ],
         FileGroupForCi.TS_SDK_DOCS_FILES: [
             # TypeDoc renders the reference from the SDK sources, and the landing page is
-            # authored in ts-sdk/docs — unlike TS_SDK_FILES, `.md` counts here.
+            # authored in ts-sdk/docs — unlike TS_SDK_FILES, `.md` counts here. tsconfig.json
+            # and package.json are included too: docs/tsconfig.json `extends` the former, and
+            # the latter pins the `@msgpack/msgpack` version the checked program depends on.
             r"^ts-sdk/docs/.*",
             r"^ts-sdk/src/.*",
+            r"^ts-sdk/tsconfig\.json$",
+            r"^ts-sdk/package\.json$",
         ],
         FileGroupForCi.TS_SDK_FILES: [
             # `.md` excluded — doc-only edits do not affect the generated supervisor schema.
-            r"^ts-sdk/(?!.*\.md$).*",
+            # `ts-sdk/docs/package.json` and its lock file excluded too — they pin the docs
+            # toolchain's own dependencies and do not affect the SDK build.
+            r"^ts-sdk/(?!.*\.md$)(?!docs/package(-lock)?\.json$).*",
         ],
         FileGroupForCi.ASSET_FILES: [
             r"^airflow-core/src/airflow/assets/",

dev/breeze/tests/test_selective_checks.py

@@ -1509,6 +1509,20 @@ def assert_outputs_are_printed(expected_outputs: dict[str, str], stderr: str):
             },
             id="Build ts-sdk docs for a docs-only Markdown change that skips ts-sdk tests",
         ),
+        pytest.param(
+            ("ts-sdk/tsconfig.json",),
+            {
+                "run-ts-sdk-docs": "true",
+            },
+            id="Build ts-sdk docs when tsconfig.json changes since docs/tsconfig.json extends it",
+        ),
+        pytest.param(
+            ("ts-sdk/package.json",),
+            {
+                "run-ts-sdk-docs": "true",
+            },
+            id="Build ts-sdk docs when package.json changes since it pins @msgpack/msgpack",
+        ),
         pytest.param(
             ("ts-sdk/README.md",),
             {
@@ -1849,6 +1863,16 @@ def test_ktlint_hook_only_runs_for_java_sdk_changes(files: tuple[str, ...], ktli
             True,
             id="skipped when only nested ts-sdk docs change",
         ),
+        pytest.param(
+            ("ts-sdk/docs/package.json",),
+            True,
+            id="skipped when only the docs toolchain's package.json changes",
+        ),
+        pytest.param(
+            ("ts-sdk/docs/package-lock.json",),
+            True,
+            id="skipped when only the docs toolchain's lock file changes",
+        ),
     ],
 )
 def test_check_ts_sdk_supervisor_schema_hook_only_runs_for_relevant_changes(

ts-sdk/README.md

@@ -189,8 +189,9 @@ current task context when omitted.
 ## Cancellation
 
 `ctx.signal` is an `AbortSignal` controlled by the active runtime. Pass it to
-`fetch()`, timers, database clients, child processes, or other abortable APIs
-so tasks can clean up cooperatively when Airflow terminates the task attempt.
+`fetch()`, timers, database clients, child processes, or any other API that
+accepts an abort signal so tasks can clean up cooperatively when Airflow
+terminates the task subprocess with SIGTERM or SIGINT.
 
 ## Development
 

ts-sdk/docs/tsconfig.json

@@ -1,9 +1,20 @@
 {
-  "//": "Docs-only tsconfig for the TypeDoc analysis pass. It inherits the SDK's compiler settings verbatim and roots the program at the public entry point only: TypeScript pulls in whatever that entry point transitively imports, but a glob like `../src/**/*.ts` would also root unreachable internal modules (e.g. the `cli/` bin, which needs the optional `esbuild` peer dependency) that the docs toolchain has no reason to install. `paths` below redirects `@msgpack/msgpack`, a real transitive dependency of the checked program (coordinator/frames.ts, reachable from the public startCoordinator export): Node module resolution walks up node_modules from the *importing file* (ts-sdk/src/coordinator/), never sideways into this package's own node_modules, so the bare specifier would otherwise never resolve here.",
+  "//": [
+    "Docs-only tsconfig for the TypeDoc analysis pass. It inherits the SDK's compiler",
+    "settings verbatim and roots the program at the public entry point only: TypeScript",
+    "pulls in whatever that entry point transitively imports, but a glob like",
+    "`../src/**/*.ts` would also root unreachable internal modules (e.g. the `cli/` bin,",
+    "which needs the optional `esbuild` peer dependency) that the docs toolchain has no",
+    "reason to install. `paths` below redirects `@msgpack/msgpack`, a real transitive",
+    "dependency of the checked program (coordinator/frames.ts, reachable from the public",
+    "startCoordinator export): Node module resolution walks up node_modules from the",
+    "*importing file* (ts-sdk/src/coordinator/), never sideways into this package's own",
+    "node_modules, so the bare specifier would otherwise never resolve here."
+  ],
   "extends": "../tsconfig.json",
   "compilerOptions": {
     "paths": {
-      "@msgpack/msgpack": ["./node_modules/@msgpack/msgpack/dist.esm/index.d.ts"]
+      "@msgpack/msgpack": ["./node_modules/@msgpack/msgpack"]
     }
   },
   "include": ["../src/index.ts"]