Migrate code-excerpts tooling to npm package version (#9638)

Author: chalin

.cspell.yml

@@ -91,6 +91,7 @@ words:
   - desaturate
   - Docsy
   - errorf
+  - excerpter
   - favicons
   - Goldmark
   - htmltest

.github/workflows/test.yml

@@ -23,6 +23,7 @@ jobs:
         with:
           node-version-file: .nvmrc
 
-      - run: npm install --ignore-scripts --omit=optional
+      # Don't --ignore-scripts: code-excerpter needs submodules
+      - run: npm install --omit=optional
 
       - run: npm run test:compound-tests

content/en/docs/languages/java/getting-started.md

@@ -4,7 +4,6 @@ description: Get telemetry for your app in less than 5 minutes!
 weight: 10
 ---
 
-<!-- markdownlint-disable blanks-around-fences -->
 <?code-excerpt path-base="examples/java/getting-started"?>
 
 This page will show you how to get started with OpenTelemetry in Java.
@@ -62,8 +61,8 @@ dependencies {
 In that same folder, create a file called `DiceApplication.java` and add the
 following code to the file:
 
-<!-- prettier-ignore-start -->
 <?code-excerpt "src/main/java/otel/DiceApplication.java"?>
+
 ```java
 package otel;
 
@@ -80,13 +79,12 @@ public class DiceApplication {
   }
 }
 ```
-<!-- prettier-ignore-end -->
 
 Create another file called `RollController.java` and add the following code to
 the file:
 
-<!-- prettier-ignore-start -->
 <?code-excerpt "src/main/java/otel/RollController.java"?>
+
 ```java
 package otel;
 
@@ -118,7 +116,6 @@ public class RollController {
   }
 }
 ```
-<!-- prettier-ignore-end -->
 
 Build and run the application with the following command, then open
 <http://localhost:8080/rolldice> in your web browser to ensure it is working.

content/en/site/build/npm-scripts.md

@@ -39,6 +39,7 @@ are internal helpers and are not intended to be run directly.
 | ---------------------- | ----------------------------------------------------------- |
 | `check`                | Run the most commonly needed check scripts in sequence.     |
 | `check:all`            | Run all check scripts in sequence.                          |
+| `check:code-excerpts`  | Check code excerpts, fail if updates needed.                |
 | `check:format`         | Prettier and prose-wrap checks.                             |
 | `check:i18n`           | Validate localization front matter (`default_lang_commit`). |
 | `check:links`          | Run HTML link checker.                                      |
@@ -57,6 +58,7 @@ are internal helpers and are not intended to be run directly.
 | Script                    | Description                                                    |
 | ------------------------- | -------------------------------------------------------------- |
 | `fix`                     | Run the most commonly needed fix scripts.                      |
+| `fix:code-excerpts`       | Refresh code excerpts.                                         |
 | `fix:all`                 | Run all fix scripts.                                           |
 | `fix:format`              | Apply Prettier and trim trailing spaces.                       |
 | `fix:format:staged`       | Format only staged files.                                      |
@@ -74,14 +76,14 @@ are internal helpers and are not intended to be run directly.
 
 ## Submodules and content
 
-| Script             | Description                                        |
-| ------------------ | -------------------------------------------------- |
-| `get:submodule`    | Init/update git submodules (set `GET=no` to skip). |
-| `update:submodule` | Update submodules to latest remote and fetch tags. |
-| `pin:submodule`    | Pin submodule revisions (optional `PIN_SKIP`).     |
-| `cp:spec`          | Copy spec content (content-modules).               |
-| `schemas:update`   | Update OpenTelemetry spec submodule and content.   |
-| `code-excerpts`    | Rebuild code excerpts and update docs.             |
+| Script             | Description                                                                          |
+| ------------------ | ------------------------------------------------------------------------------------ |
+| `code-excerpts`    | Refresh code excerpts. DEPRECATED: use `fix:code-excerpts` or `check:code-excerpts`. |
+| `cp:spec`          | Copy spec content (content-modules).                                                 |
+| `get:submodule`    | Init/update git submodules (set `GET=no` to skip).                                   |
+| `pin:submodule`    | Pin submodule revisions (optional `PIN_SKIP`).                                       |
+| `schemas:update`   | Update OpenTelemetry spec submodule and content.                                     |
+| `update:submodule` | Update submodules to latest remote and fetch tags.                                   |
 
 ## Test and CI
 

package.json

@@ -18,6 +18,7 @@
     "_check:markdown": "npx gulp lint-md",
     "_check:registry": "npx gulp validate-registry",
     "_check:text": "npx textlint content data `ls *.md`",
+    "_code-excerpter-over-en": "code-excerpter content/en",
     "_commit:public": "HASH=$(git rev-parse --short main); cd public && git add -A && git commit -m \"Site at $HASH\"",
     "_diff:check": "git diff --name-only --exit-code",
     "_diff:fail": "git diff --name-only --exit-code || exit 1",
@@ -62,6 +63,7 @@
     "build": "npm run _build --",
     "cd:public": "cd public &&",
     "check:all": "npm run seq -- $(npm run -s _list:check:*)",
+    "check:code-excerpts": "npm run _code-excerpter-over-en -- --dry-run --fail-on-update",
     "check:collector-sync:lint": "cd scripts/collector-sync && uv run ruff check src/",
     "check:collector-sync:types": "cd scripts/collector-sync && uv run mypy src/",
     "check:collector-sync": "cd scripts/collector-sync && uv run pytest",
@@ -78,13 +80,12 @@
     "check:text": "npm run _check:text -- ",
     "check": "CMD_SKIP=collector-sync npm run check:all",
     "clean": "make clean",
-    "code-excerpts:get": "cd tools && dart run build_runner build --delete-conflicting-outputs --output ../tmp/excerpts",
-    "code-excerpts:update-docs": "cd tools && dart run code_excerpt_updater --fragment-dir-path ../tmp/excerpts --src-dir-path examples --yaml --write-in-place content",
-    "code-excerpts": "rm -Rf tmp/excerpts/* && npm run seq -- code-excerpts:get code-excerpts:update-docs",
+    "code-excerpts": "node -e 'console.error(\"\\x1b[31mWARNING: THIS IS A DEPRECATED ALIAS, instead use: `fix:code-excerpts` or `check:code-excerpts`\\x1b[0m\")' && npm run fix:code-excerpts --",
     "cp:spec": "scripts/content-modules/cp-pages.sh",
     "diff:check": "npm run _diff:check || (echo; echo 'WARNING: the files above have not been committed'; echo)",
     "diff:fail": "npm run _diff:check || (echo; echo 'ERROR: the files above have changed. Locally rerun `npm run test-and-fix` and commit changes'; echo; exit 1)",
     "fix:all": "npm run all -- $(npm -s run _list:fix:*)",
+    "fix:code-excerpts": "npm run _code-excerpter-over-en",
     "fix:collector-sync:lint": "cd scripts/collector-sync && uv run ruff check --fix src/",
     "fix:dict": "scripts/sort-cspell-words.pl .cspell/*.txt && npm run _fix:dict",
     "fix:expired": "npm run -s check:expired -- -q | xargs -r -I {} sh -c 'echo \"Deleting expired file: {}\" && rm {}'",
@@ -135,7 +136,7 @@
     "test:all": "npm run test:base && npm run test:compound-tests",
     "test:base": "npm run check",
     "test:collector-sync": "npm run check:collector-sync && npm run check:collector-sync:types && npm run check:collector-sync:lint",
-    "test:compound-tests": "npm run seq -- $(CMD_SKIP=collector-sync npm -s run _list:test:compound-tests)",
+    "test:compound-tests": "npm run seq -- check:code-excerpts $(CMD_SKIP=collector-sync npm -s run _list:test:compound-tests)",
     "test:edge-functions:live": "npm run _test:ef:live --",
     "test:edge-functions": "node --test \"netlify/edge-functions/**/*.test.ts\"",
     "test:redirects:live": "npm run _test:redirects:live --",
@@ -156,6 +157,7 @@
     "ajv-errors": "^3.0.0",
     "ajv-formats": "^3.0.1",
     "autoprefixer": "^10.4.27",
+    "code-excerpter": "^0.1.0",
     "cspell": "^10.0.0",
     "gulp": "^5.0.1",
     "hugo-extended": "0.157.0",