Merge pull request #2272 from hypothesis/add-boot-config-types

Enable typechecking for src/boot

src/boot/boot.js

 import { requiredPolyfillSets } from '../shared/polyfills';
 
+/**
+ * @typedef Config
+ * @prop {string} assetRoot - The root URL to which URLs in `manifest` are relative
+ * @prop {string} sidebarAppUrl - The URL of the sidebar's HTML page
+ * @prop {Object.<string,string>} manifest -
+ *   A mapping from canonical asset path to cache-busted asset path
+ */
+
+/**
+ * @param {Document} doc
+ * @param {string} href
+ */
 function injectStylesheet(doc, href) {
   const link = doc.createElement('link');
   link.rel = 'stylesheet';
@@ -8,6 +20,10 @@ function injectStylesheet(doc, href) {
   doc.head.appendChild(link);
 }
 
+/**
+ * @param {Document} doc
+ * @param {string} src - The script URL
+ */
 function injectScript(doc, src) {
   const script = doc.createElement('script');
   script.type = 'text/javascript';
@@ -19,6 +35,11 @@ function injectScript(doc, src) {
   doc.head.appendChild(script);
 }
 
+/**
+ * @param {Document} doc
+ * @param {Config} config
+ * @param {string[]} assets
+ */
 function injectAssets(doc, config, assets) {
   assets.forEach(function (path) {
     const url = config.assetRoot + 'build/' + config.manifest[path];
@@ -40,6 +61,9 @@ function polyfillBundles(needed) {
  * Bootstrap the Hypothesis client.
  *
  * This triggers loading of the necessary resources for the client
+ *
+ * @param {Document} doc
+ * @param {Config} config
  */
 function bootHypothesisClient(doc, config) {
   // Detect presence of Hypothesis in the page
@@ -91,6 +115,9 @@ function bootHypothesisClient(doc, config) {
 
 /**
  * Bootstrap the sidebar application which displays annotations.
+ *
+ * @param {Document} doc
+ * @param {Config} config
  */
 function bootSidebarApp(doc, config) {
   const polyfills = polyfillBundles([
@@ -122,6 +149,13 @@ function bootSidebarApp(doc, config) {
   ]);
 }
 
+/**
+ * Initialize the "sidebar" application if run in the sidebar's stub HTML
+ * page or the "annotator" application otherwise.
+ *
+ * @param {Document} document_
+ * @param {Config} config
+ */
 export default function boot(document_, config) {
   if (document_.querySelector('hypothesis-app')) {
     bootSidebarApp(document_, config);

src/boot/index.js

@@ -18,6 +18,7 @@ const settings = jsonConfigsFrom(document);
 
 boot(document, {
   assetRoot: processUrlTemplate(settings.assetRoot || '__ASSET_ROOT__'),
+  // @ts-ignore - `__MANIFEST__` is injected by the build script
   manifest: __MANIFEST__,
   sidebarAppUrl: processUrlTemplate(
     settings.sidebarAppUrl || '__SIDEBAR_APP_URL__'

src/boot/url-template.js

@@ -15,7 +15,7 @@ function extractOrigin(url) {
 
 function currentScriptOrigin(document_ = document) {
   try {
-    let scriptEl = document_.currentScript;
+    let scriptEl = /** @type {HTMLScriptElement} */ (document_.currentScript);
 
     if (!scriptEl) {
       // Fallback for IE 11.
@@ -37,6 +37,9 @@ function currentScriptOrigin(document_ = document) {
  * from a device or VM that is not the system where the development server is
  * running. In that case, all references to `localhost` need to be replaced
  * with the IP/hostname of the dev server.
+ *
+ * @param {string} url
+ * @param {Document} document_
  */
 export default function processUrlTemplate(url, document_ = document) {
   if (url.indexOf('{') === -1) {

src/tsconfig.json

@@ -11,6 +11,7 @@
     "target": "ES2020"
   },
   "include": [
+    "boot/*.js",
     "shared/*.js",
     "sidebar/util/*.js"
   ]