From fe79cd89556cee50f92ea1c74676ebb703c65c3f Mon Sep 17 00:00:00 2001
From: Peter Hedenskog <phedenskog@wikimedia.org>
Date: Sun, 31 May 2026 16:41:02 +0200
Subject: [PATCH]  Type the sitespeed.io context and queue message in JSDoc
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

  Plugin authors writing against this base class have no IDE help for the
  shape of context (the messageMaker/getLogger/filterRegistry/storageManager/
  resultUrls hub) or for the queue messages they receive — the only way to
  discover the shape today is to read sitespeed.io's source. This change adds
  JSDoc typedefs for those objects so that editors offering JSDoc support can
  autocomplete context.storageManager, message.runIndex, and the rest
  without changing any runtime behaviour. Also drops the stale "UNRELEASED"
  marker on the 1.0.2 entry in CHANGELOG.

  Co-authored-by: Claude Opus 4.7 (1M context) noreply@anthropic.com
---
 CHANGELOG.md |  2 +-
 plugin.js    | 50 ++++++++++++++++++++++++++++++++++++++++++++++----
 2 files changed, 47 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c6b9648..c9f20c1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,6 @@
 # CHANGELOG - sitespeed.io/plugin  (we use [semantic versioning](https://semver.org))
 
-## 1.0.2 - UNRELEASED
+## 1.0.2 - 2026-05-16
 ### Fixed
 * Relaxed the config validation introduced in 1.0.1 so that `queue` is no
   longer required at construction time. Existing plugins like `pagexray`
diff --git a/plugin.js b/plugin.js
index fd78228..e55819a 100644
--- a/plugin.js
+++ b/plugin.js
@@ -1,3 +1,45 @@
+/**
+ * @typedef {Object} Logger
+ * @property {Function} trace
+ * @property {Function} verbose
+ * @property {Function} debug
+ * @property {Function} info
+ * @property {Function} warn
+ * @property {Function} error
+ * @property {Function} critical
+ */
+
+/**
+ * @typedef {Object} MessageMaker
+ * @property {Function} make - Build a message tagged with the maker's plugin name. Signature: `make(type, data?, extras?)`.
+ */
+
+/**
+ * A message on the sitespeed.io queue. Produced by `context.messageMaker(name).make(...)`.
+ *
+ * @typedef {Object} QueueMessage
+ * @property {string}  type        - Message type (e.g. 'browsertime.run', 'sitespeedio.render').
+ * @property {*}       [data]      - Message payload.
+ * @property {*}       [extras]    - Optional extras carried alongside the message.
+ * @property {string}  [url]       - URL this message relates to, if any.
+ * @property {number}  [runIndex]  - Run index, if the message belongs to a specific run.
+ * @property {string}  [source]    - Name of the plugin that produced the message.
+ * @property {string}  [uuid]      - Set by the queue handler when the message is enqueued.
+ */
+
+/**
+ * The sitespeed.io context object, passed to your plugin's constructor and to
+ * `open()`. Provides framework services: logging, storage, filter/metrics
+ * registry, and the URL helpers used to build links into the result folder.
+ *
+ * @typedef {Object} SitespeedioContext
+ * @property {function(string): MessageMaker} messageMaker - Factory that returns a maker tagged with the given plugin name.
+ * @property {function(string): Logger}       getLogger    - Factory for a named logger.
+ * @property {Object} filterRegistry  - Registry that lets plugins declare which metrics to forward to TimeSeries databases.
+ * @property {Object} storageManager  - Used to write files (HTML report, JSON dumps, …) under the result folder.
+ * @property {Object} resultUrls      - Helpers for building URLs that point into the result folder.
+ */
+
 /**
  * Base class that you can extend when you build a sitespeed.io plugin.
  * Your class will be instantiated by sitespeed.io.
@@ -90,8 +132,8 @@ export class SitespeedioPlugin {
    * sitespeed.io invokes it with `(context, options)` — the same objects passed to
    * the constructor. They are passed again for backwards compatibility; you can
    * also read them via `this.context` / `this.options`.
-   * @param {Object} [context] - sitespeed.io context (same as constructor `context`).
-   * @param {Object} [options] - sitespeed.io options (same as constructor `options`).
+   * @param {SitespeedioContext} [context] - sitespeed.io context (same as constructor `context`).
+   * @param {Object}             [options] - sitespeed.io options (same as constructor `options`).
    */
   // eslint-disable-next-line no-unused-vars
   async open(context, options) {}
@@ -108,8 +150,8 @@ export class SitespeedioPlugin {
    *   - 'sitespeedio.prepareToRender' — about to render output
    *   - 'sitespeedio.render'          — write final output to storage
    *
-   * @param {Object} message - Message from the queue (has `type`, optional `data`, `url`, `runIndex`, …).
-   * @param {Object} [queue] - The queue handler (same as `this.queue`).
+   * @param {QueueMessage} message - Message from the queue.
+   * @param {Object}       [queue] - The queue handler (same as `this.queue`).
    */
   // eslint-disable-next-line no-unused-vars
   async processMessage(message, queue) {