Merge branch 'main' into patch-1

Author: atsansone

.github/workflows/codeql-analysis.yml

@@ -33,7 +33,7 @@ jobs:
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@e8893c57a1f3a2b659b6b55564fdfdbbd2982911
+        uses: github/codeql-action/init@05963f47d870e2cb19a537396c1f668a348c7d8f
         with:
           languages: ${{ matrix.language }}
           # If you wish to specify custom queries, you can do so here or in a config file.
@@ -44,7 +44,7 @@ jobs:
       # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
       # If this step fails, then you should remove it and run the build manually (see below)
       - name: Autobuild
-        uses: github/codeql-action/autobuild@e8893c57a1f3a2b659b6b55564fdfdbbd2982911
+        uses: github/codeql-action/autobuild@05963f47d870e2cb19a537396c1f668a348c7d8f
 
       # ℹ️ Command-line programs to run using the OS shell.
       # 📚 https://git.io/JvXDl
@@ -58,4 +58,4 @@ jobs:
       #   make release
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@e8893c57a1f3a2b659b6b55564fdfdbbd2982911
+        uses: github/codeql-action/analyze@05963f47d870e2cb19a537396c1f668a348c7d8f

.github/workflows/scorecards-analysis.yml

@@ -49,6 +49,6 @@ jobs:
 
       # Upload the results to GitHub's code scanning dashboard.
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@e8893c57a1f3a2b659b6b55564fdfdbbd2982911
+        uses: github/codeql-action/upload-sarif@05963f47d870e2cb19a537396c1f668a348c7d8f
         with:
           sarif_file: results.sarif

.github/workflows/test.yml

@@ -25,7 +25,7 @@ env:
 
 jobs:
   test:
-    name: Check excerpts and run tests
+    name: Analyze and test code examples
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -51,6 +51,19 @@ jobs:
         run: dart run dart_site analyze-dart
       - name: Run Dart tests
         run: dart run dart_site test-dart
+
+  excerpts:
+    name: Check if code excerpts are up to date
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+        with:
+          submodules: recursive
+      - uses: dart-lang/setup-dart@fedb1266e91cf51be2fdb382869461a434b920a3
+        with:
+          sdk: stable
+      - name: Fetch Dart packages
+        run: dart pub get
       - name: Check if excerpts are up to date
         run: dart run dart_site refresh-excerpts --fail-on-update
 

README.md

@@ -61,14 +61,15 @@ dart --version
 
 #### Node.js
 
-The latest stable LTS release of Node.js is required to build the site.
+The **latest** stable LTS release of Node.js is required to build the site.
 If you don't have Node.js or need to update, download your
 computer's corresponding version and follow the instructions
 from the [Node.js download archive][].
-If you prefer, you can use a version manager such as [nvm][].
+If you prefer, you can use a version manager such as [nvm][],
+and run `nvm install` from the repository's root directory.
 
 If you already have Node installed, verify it's available on your path
-and already the latest stable version _(`20` or later)_:
+and already the latest stable version _(currently `20.10` or later)_:
 
 ```terminal
 node --version
@@ -137,60 +138,72 @@ following the instructions in [Get the prerequisites](#get-the-prerequisites).
    dart pub get
    ```
 
-3. From the root directory of the repository,
-   enable [`corepack`][] to set up [`pnpm`][].
-   `corepack` comes bundled with Node and `pnpm`
-   is an alternative, efficient package manager for npm packages.
-   If you already have `pnpm` installed or installed it a different way,
-   you can skip the `corepack` commands.
+3. Install [`pnpm`][] using your preferred [installation method][pnpm-install].
+   `pnpm` is an alternative, efficient package manager for npm packages.
+   If you already have `pnpm`, verify you have the latest stable version.
+   We recommend using [`corepack`][] to install and manage `pnpm` versions,
+   since it is bundled with most installations of Node.
+   
+   If you haven't used `corepack` before, you'll need to
+   first enable it with `corepack enable`.
+   Then, to install the correct `pnpm` version, from the
+   root directory of the repository, run `corepack install`:
 
    ```terminal
    corepack enable
    corepack install
    ```
 
 4. Once you have `pnpm` installed and setup,
-   fetch the site's npm dependencies.
-   We recommend you use `pnpm`, but you can also use `npm`.
+   fetch the site's npm dependencies using `pnpm install`.
+   We highly recommend you use `pnpm`, but you can also use `npm`.
 
    ```terminal
    pnpm install
    ```
 
-5. From the root directory, serve the site locally.
+5. From the root directory, run the `dash_site` tool to
+   validate your setup and learn about the available commands.
+
+   ```terminal
+   ./dash_site --help
+   ```
+
+6. From the root directory, serve the site locally.
 
    ```terminal
-   dart run dart_site serve
+   ./dash_site serve
    ```
 
    This command generates and serves the site on a
    local port that's printed to your terminal.
 
-6. View your changes in the browser by navigating to <http://localhost:4000>.
+7. View your changes in the browser by navigating to <http://localhost:4000>.
 
    Note the port might be different if `4000` is taken.
 
-   To instead view the source of generated site files,
-   check the `_site` directory.
+   If you want to check the raw, generated HTML output and structure,
+   view the `_site` directory in a file explorer or an IDE.
 
-7. Make your changes to the local repo.
+8. Make your changes to the local repo.
 
    The site should automatically rebuild on most changes, but if
    something doesn't update, exit the process and rerun the command.
    Improvements to this functionality are planned.
    Please open a new issue to track the issue if this occurs.
 
-8. Commit your changes to the branch and submit your PR.
+9. Commit your changes to the branch and submit your PR.
 
    If your change is large, or you'd like to test it,
    consider [validating your changes](#validate-your-changes).
 
 > [!TIP]
 > To find additional commands that you can run,
-> run `dart run dart_site --help` from the repository's root directory.
+> run `./dash_site --help` from the repository's root directory.
 
 [`corepack`]: https://nodejs.org/api/corepack.html
 [`pnpm`]: https://pnpm.io/
+[pnpm-install]: https://pnpm.io/installation
 
 ## Validate your changes
 
@@ -201,7 +214,7 @@ commit your work, then run the following command to
 verify it is up to date and matches the site standards.
 
 ```terminal
-dart run dart_site check-all
+./dash_site check-all
 ```
 
 If this script reports any errors or warnings,
@@ -241,7 +254,7 @@ you can build a full version and upload it to Firebase.
 2. From the root directory of the repository, build the site:
 
    ```terminal
-   dart run dart_site build
+   ./dash_site build
    ```
 
    This will build the site and copy it to your local `_site` directory.

analysis_options.yaml

@@ -1,2 +1,2 @@
 analyzer:
-  exclude: [_site, site-shared, src, tmp, tool/dartpad_picker, tool/get_dart]
+  exclude: [_site, site-shared, src, tmp, tool/get_dart]

dash_site

@@ -0,0 +1,104 @@
+#!/bin/bash
+
+REQUIRED_DART_VERSION="3.3"
+REQUIRED_NODE_VERSION="20.10"
+REQUIRED_PNPM_VERSION="8.14"
+
+# Check that the 'dart' command is available on the user's path.
+if ! command -v dart &> /dev/null; then
+  echo "Dart not found. To learn how to setup Dart, follow the instructions at https://dart.dev/get-dart."
+  exit 1
+fi
+
+# Check that the current version of a tool is the same or
+# newer than a required version.
+version_is_new_enough() {
+  required_version="$1"
+  current_version="$2"
+
+  # Split the version strings into lists based on the dot separators.
+  IFS='.' read -ra required_list <<< "$required_version"
+  IFS='.' read -ra current_list <<< "$current_version"
+
+  # Compare each portion of the version number.
+  for ((i = 0; i < ${#required_list[@]}; i += 1)); do
+    required_segment="${required_list[i]:-0}"
+    current_segment="${current_list[i]:-0}"
+
+    if [[ "$required_segment" -gt "$current_segment" ]]; then
+      # The current version is too low.
+      return 0
+    elif [[ "$required_segment" -lt "$current_segment" ]]; then
+      # The current version is higher, which is ok.
+      return 1
+    fi
+  done
+
+  # The current version is (mostly) the same as the required version.
+  return 1
+}
+
+
+# Determine the available Dart SDK version.
+dart_version=$(dart --version | grep -oE 'Dart SDK version: [0-9.]+' | cut -d ' ' -f 4)
+
+# Validate the version of the installed Dart SDK.
+if version_is_new_enough "$REQUIRED_DART_VERSION" "$dart_version"; then
+  echo "Dart version $dart_version is too low. Version $REQUIRED_DART_VERSION or later is required."
+  exit 1
+fi
+
+# Check that the 'node' command is available on the user's path.
+if ! command -v node &> /dev/null; then
+  echo "'node' command not found. To learn how to install and setup Node, reference the repository README."
+  exit 1
+fi
+
+# Determine the available Node version.
+node_version=$(node --version | cut -d 'v' -f 2)
+
+# Validate the version of the Node installation.
+if version_is_new_enough "$REQUIRED_NODE_VERSION" "$node_version"; then
+  echo "Node version $node_version is too low. Version $REQUIRED_NODE_VERSION or later is required."
+  exit 1
+fi
+
+# Check that the 'npx' command is available on the user's path.
+if ! command -v npx &> /dev/null; then
+  echo "'npx' command from Node not found. Check your Node installation."
+  exit 1
+fi
+
+# Run extra logic if the 'pnpm' command is available on the user's path.
+if command -v pnpm &> /dev/null; then
+  # Determine the available pnpm version.
+  pnpm_version=$(pnpm --version)
+
+  # Validate the version of the pnpm installation.
+  if version_is_new_enough "$REQUIRED_PNPM_VERSION" "$pnpm_version"; then
+    echo "pnpm version $pnpm_version is too low. Version $REQUIRED_PNPM_VERSION or later is required."
+    exit 1
+  fi
+fi
+
+# Verify that Node packages have been installed.
+if [[ ! -d "node_modules" ]]; then
+  if command -v pnpm &> /dev/null; then
+    echo "Node packages not found. Installing with 'pnpm install'..."
+    pnpm install
+  elif command -v npm &> /dev/null; then
+    echo "Node packages not found. Installing with 'npm install'..."
+    npm install
+  else
+    echo "Neither 'pnpm' nor 'npm' found. To learn how to setup pnpm, reference the repository README."
+    exit 1
+  fi
+fi
+
+# Verify that Dart dependencies have been retrieved.
+if [[ ! -d ".dart_tool" ]]; then
+  dart pub get
+fi
+
+# Run the Dart site tool and pass through all arguments.
+dart run dart_site "$@"

eleventy.config.js

@@ -91,6 +91,7 @@ export default function (eleventyConfig) {
 
   eleventyConfig.addPassthroughCopy('src/content/assets/dash');
   eleventyConfig.addPassthroughCopy('src/content/assets/js');
+  eleventyConfig.addPassthroughCopy({'site-shared/packages/inject_dartpad/lib/inject_dartpad.js': 'assets/js/inject_dartpad.js'});
   eleventyConfig.addPassthroughCopy('src/content/assets/img', { expand: true });
   eleventyConfig.addPassthroughCopy('src/content/f', {
     expand: true,

examples/analysis/pubspec.yaml

@@ -2,7 +2,7 @@ name: examples
 description: dart.dev example code.
 
 environment:
-  sdk: ^3.2.0
+  sdk: ^3.3.0
 
 dependencies:
   examples_util: {path: ../util}

examples/analysis_alt/pubspec.yaml

@@ -2,7 +2,7 @@ name: examples
 description: dart.dev example code.
 
 environment:
-  sdk: ^3.2.0
+  sdk: ^3.3.0
 
 dev_dependencies:
   lints: ^3.0.0

examples/async_await/bin/futures_intro.dart

@@ -7,13 +7,16 @@ Future<void> fetchUserOrder() {
 
 // #docregion error
 Future<void> fetchUserOrderError() {
-// Imagine that this function is fetching user info but encounters a bug
-  return Future.delayed(const Duration(seconds: 2),
-      () => throw Exception('Logout failed: user ID is invalid'));
+  // Imagine that this function is fetching user info but encounters a bug.
+  return Future.delayed(
+    const Duration(seconds: 2),
+    () => throw Exception('Logout failed: user ID is invalid'),
+  );
 }
 // #docregion ''
 
 void main() {
   fetchUserOrder();
   print('Fetching user order...');
 }
+// #enddocregion error

examples/async_await/bin/get_order_sync_bad.dart

@@ -19,3 +19,4 @@ void main() {
   print('Fetching user order...');
   print(createOrderMessage());
 }
+// #enddocregion no-warning

examples/async_await/pubspec.yaml

@@ -2,11 +2,11 @@ name: async_await
 description: dart.dev example code.
 
 environment:
-  sdk: ^3.2.0
+  sdk: ^3.3.0
 
 dependencies:
   examples_util: {path: ../util}
 
 dev_dependencies:
   lints: ^3.0.0
-  test: ^1.24.6
+  test: ^1.25.2

examples/build_runner_usage/pubspec.yaml

@@ -2,10 +2,10 @@ name: build_runner_usage
 description: dart.dev build_runner example code.
 
 environment:
-  sdk: ^3.2.0
+  sdk: ^3.3.0
 
 dev_dependencies:
   args: ^2.4.0
-  build_runner: ^2.4.6
-  build_test: ^2.2.0
+  build_runner: ^2.4.8
+  build_test: ^2.2.2
   lints: ^3.0.0

examples/cli/bin/dcat.dart

@@ -43,12 +43,12 @@ Future<void> dcat(List<String> paths, {bool showLineNumbers = false}) async {
           .transform(const LineSplitter());
       try {
         await for (final line in lines) {
-          // #docregion showLineNumbers
+          // #docregion show-line-numbers
           if (showLineNumbers) {
             stdout.write('${lineNumber++} ');
           }
           stdout.writeln(line);
-          // #enddocregion showLineNumbers
+          // #enddocregion show-line-numbers
         }
       } catch (_) {
         await _handleError(path);