ol-stac 0.0.0

package/config/jsdoc/info/publish.js

@@ -0,0 +1,175 @@
+/* eslint-disable import/no-commonjs */
+
+/**
+ * @fileoverview Generates JSON output based on exportable symbols.
+ */
+const assert = require('assert');
+const path = require('path');
+
+/**
+ * Publish hook for the JSDoc template.  Writes to JSON stdout.
+ * @param {Function} data The root of the Taffy DB containing doclet records.
+ * @param {Object} opts Options.
+ * @return {Promise} A promise that resolves when writing is complete.
+ */
+exports.publish = function (data, opts) {
+  function getTypes(data) {
+    return data.map((name) => name.replace(/^function$/, 'Function'));
+  }
+
+  // get all doclets that have exports
+  const classes = {};
+  const docs = data(function () {
+    if (this.kind == 'class') {
+      classes[this.longname] = this;
+      return true;
+    }
+    return (
+      !['file', 'event', 'module'].includes(this.kind) &&
+      this.meta &&
+      this.meta.path &&
+      !this.longname.startsWith('<anonymous>') &&
+      this.longname !== 'module:ol'
+    );
+  }).get();
+
+  // get symbols data, filter out those that are members of private classes
+  const symbols = [];
+  const defines = [];
+  const typedefs = [];
+  const externs = [];
+  let base = [];
+  const augments = {};
+  const symbolsByName = {};
+  docs
+    .filter(function (doc) {
+      let include = true;
+      const constructor = doc.memberof;
+      if (
+        constructor &&
+        constructor.substr(-1) === '_' &&
+        !constructor.includes('module:')
+      ) {
+        assert.strictEqual(
+          doc.inherited,
+          true,
+          'Unexpected export on private class: ' + doc.longname
+        );
+        include = false;
+      }
+      return include;
+    })
+    .forEach(function (doc) {
+      const isExterns = /[\\\/]externs$/.test(doc.meta.path);
+      if (doc.define) {
+        defines.push({
+          name: doc.longname,
+          description: doc.description,
+          path: path.join(doc.meta.path, doc.meta.filename),
+          default: doc.define.default,
+        });
+      } else if (doc.type && (doc.kind == 'typedef' || doc.isEnum === true)) {
+        typedefs.push({
+          name: doc.longname,
+          types: getTypes(doc.type.names),
+        });
+      } else {
+        const symbol = {
+          name: doc.longname,
+          kind: doc.kind,
+          description: doc.classdesc || doc.description,
+          path: path.join(doc.meta.path, doc.meta.filename),
+        };
+        if (doc.augments) {
+          symbol.extends = doc.augments[0];
+        }
+        if (doc.virtual) {
+          symbol.virtual = true;
+        }
+        if (doc.type) {
+          symbol.types = getTypes(doc.type.names);
+        }
+        if (doc.params) {
+          const params = [];
+          doc.params.forEach(function (param) {
+            const paramInfo = {
+              name: param.name,
+            };
+            params.push(paramInfo);
+            paramInfo.types = getTypes(param.type.names);
+            if (typeof param.variable == 'boolean') {
+              paramInfo.variable = param.variable;
+            }
+            if (typeof param.optional == 'boolean') {
+              paramInfo.optional = param.optional;
+            }
+            if (typeof param.nullable == 'boolean') {
+              paramInfo.nullable = param.nullable;
+            }
+          });
+          symbol.params = params;
+        }
+        if (doc.returns) {
+          symbol.returns = {
+            types: getTypes(doc.returns[0].type.names),
+          };
+          if (typeof doc.returns[0].nullable == 'boolean') {
+            symbol.returns.nullable = doc.returns[0].nullable;
+          }
+        }
+        if (doc.tags) {
+          doc.tags.every(function (tag) {
+            if (tag.title == 'template') {
+              symbol.template = tag.value;
+              return false;
+            }
+            return true;
+          });
+        }
+        if (doc.isDefaultExport) {
+          symbol.isDefaultExport = true;
+        }
+
+        const target = isExterns ? externs : symbols;
+        const existingSymbol = symbolsByName[symbol.name];
+        if (existingSymbol) {
+          const idx = target.indexOf(existingSymbol);
+          target.splice(idx, 1);
+        }
+        target.push(symbol);
+        symbolsByName[symbol.name] = symbol;
+
+        if (symbol.extends) {
+          while (
+            symbol.extends in classes &&
+            classes[symbol.extends].augments
+          ) {
+            symbol.extends = classes[symbol.extends].augments[0];
+          }
+          if (symbol.extends) {
+            augments[symbol.extends] = true;
+          }
+        }
+      }
+    });
+
+  base = base.filter(function (symbol) {
+    return symbol.name in augments || symbol.virtual;
+  });
+
+  return new Promise(function (resolve, reject) {
+    process.stdout.write(
+      JSON.stringify(
+        {
+          symbols: symbols,
+          defines: defines,
+          typedefs: typedefs,
+          externs: externs,
+          base: base,
+        },
+        null,
+        2
+      )
+    );
+  });
+};

package/config/jsdoc/package.json

@@ -0,0 +1,4 @@
+{
+  "description": "JSDoc loads publish.js files with require(), so we need to configure everything under this path as a CommonJS module.",
+  "type": "commonjs"
+}

package/config/jsdoc/plugins/api.cjs

@@ -0,0 +1,181 @@
+/* eslint-disable import/no-commonjs */
+
+/**
+ * Define an @api tag
+ * @param {Object} dictionary The tag dictionary.
+ */
+exports.defineTags = function (dictionary) {
+  dictionary.defineTag('api', {
+    mustNotHaveValue: true,
+    canHaveType: false,
+    canHaveName: false,
+    onTagged: function (doclet, tag) {
+      includeTypes(doclet);
+      doclet.stability = 'stable';
+    },
+  });
+};
+
+/*
+ * Based on @api annotations, and assuming that items with no @api annotation
+ * should not be documented, this plugin removes undocumented symbols
+ * from the documentation.
+ */
+
+const api = {};
+const classes = {};
+const types = {};
+const modules = {};
+
+function includeAugments(doclet) {
+  // Make sure that `observables` and `fires` are taken from an already processed `class` doclet.
+  // This is necessary because JSDoc generates multiple doclets with the same longname.
+  const cls = classes[doclet.longname];
+  if (cls.observables && !doclet.observables) {
+    doclet.observables = cls.observables;
+  }
+  if (doclet.fires && cls.fires) {
+    for (let i = 0, ii = cls.fires.length; i < ii; ++i) {
+      const fires = cls.fires[i];
+      if (!doclet.fires.includes(fires)) {
+        doclet.fires.push(fires);
+      }
+    }
+  }
+  if (cls.fires && !doclet.fires) {
+    doclet.fires = cls.fires;
+  }
+
+  const augments = doclet.augments;
+  if (augments) {
+    let cls;
+    for (let i = augments.length - 1; i >= 0; --i) {
+      cls = classes[augments[i]];
+      if (cls) {
+        includeAugments(cls);
+        if (cls.fires) {
+          if (!doclet.fires) {
+            doclet.fires = [];
+          }
+          cls.fires.forEach(function (f) {
+            if (!doclet.fires.includes(f)) {
+              doclet.fires.push(f);
+            }
+          });
+        }
+        if (cls.observables) {
+          if (!doclet.observables) {
+            doclet.observables = [];
+          }
+          cls.observables.forEach(function (f) {
+            if (!doclet.observables.includes(f)) {
+              doclet.observables.push(f);
+            }
+          });
+        }
+        cls._hideConstructor = true;
+      }
+    }
+  }
+}
+
+function extractTypes(item) {
+  item.type.names.forEach(function (type) {
+    const match = type.match(/^(?:.*<)?([^>]*)>?$/);
+    if (match) {
+      modules[match[1]] = true;
+      types[match[1]] = true;
+    }
+  });
+}
+
+function includeTypes(doclet) {
+  if (doclet.params) {
+    doclet.params.forEach(extractTypes);
+  }
+  if (doclet.returns) {
+    doclet.returns.forEach(extractTypes);
+  }
+  if (doclet.properties) {
+    doclet.properties.forEach(extractTypes);
+  }
+  if (doclet.type && doclet.meta.code.type == 'MemberExpression') {
+    extractTypes(doclet);
+  }
+}
+
+function sortOtherMembers(doclet) {
+  if (doclet.fires) {
+    doclet.fires.sort(function (a, b) {
+      return a.split(/#?event:/)[1] < b.split(/#?event:/)[1] ? -1 : 1;
+    });
+  }
+  if (doclet.observables) {
+    doclet.observables.sort(function (a, b) {
+      return a.name < b.name ? -1 : 1;
+    });
+  }
+}
+
+exports.handlers = {
+  newDoclet: function (e) {
+    const doclet = e.doclet;
+    if (doclet.stability) {
+      modules[doclet.longname.split(/[~\.]/).shift()] = true;
+      api[doclet.longname.split('#')[0]] = true;
+    }
+    if (doclet.kind == 'class') {
+      if (!(doclet.longname in classes)) {
+        classes[doclet.longname] = doclet;
+      } else if ('augments' in doclet) {
+        classes[doclet.longname].augments = doclet.augments;
+      }
+    }
+    if (doclet.name === doclet.longname && !doclet.memberof) {
+      // Make sure anonymous default exports are documented
+      doclet.setMemberof(doclet.longname);
+    }
+  },
+
+  parseComplete: function (e) {
+    const doclets = e.doclets;
+    const byLongname = doclets.index.longname;
+    for (let i = doclets.length - 1; i >= 0; --i) {
+      const doclet = doclets[i];
+      if (doclet.stability) {
+        if (doclet.kind == 'class') {
+          includeAugments(doclet);
+        }
+        sortOtherMembers(doclet);
+        // Always document namespaces and items with stability annotation
+        continue;
+      }
+      if (doclet.kind == 'module' && doclet.longname in modules) {
+        // Document all modules that are referenced by the API
+        continue;
+      }
+      if (doclet.isEnum || doclet.kind == 'typedef') {
+        continue;
+      }
+      if (doclet.kind == 'class' && doclet.longname in api) {
+        // Mark undocumented classes with documented members as unexported.
+        // This is used in ../template/tmpl/container.tmpl to hide the
+        // constructor from the docs.
+        doclet._hideConstructor = true;
+        includeAugments(doclet);
+        sortOtherMembers(doclet);
+      } else if (!doclet._hideConstructor) {
+        // Remove all other undocumented symbols
+        doclet.undocumented = true;
+      }
+      if (
+        doclet.memberof &&
+        byLongname[doclet.memberof] &&
+        byLongname[doclet.memberof][0].isEnum &&
+        !byLongname[doclet.memberof][0].properties.some((p) => p.stability)
+      ) {
+        byLongname[doclet.memberof][0].undocumented = true;
+      }
+    }
+  },
+};

package/config/jsdoc/plugins/default-export.cjs

@@ -0,0 +1,35 @@
+const defaultExports = {};
+const path = require('path');
+const moduleRoot = path.join(process.cwd(), 'src');
+
+// Tag default exported Identifiers because their name should be the same as the module name.
+exports.astNodeVisitor = {
+  visitNode: function (node, e, parser, currentSourceName) {
+    if (node.parent && node.parent.type === 'ExportDefaultDeclaration') {
+      const modulePath = path
+        .relative(moduleRoot, currentSourceName)
+        .replace(/\.js$/, '');
+      const exportName =
+        'module:' +
+        modulePath.replace(/\\/g, '/') +
+        (node.name ? '~' + node.name : '');
+      defaultExports[exportName] = true;
+    }
+  },
+};
+
+exports.handlers = {
+  processingComplete(e) {
+    const byLongname = e.doclets.index.longname;
+    for (const name in defaultExports) {
+      if (!(name in byLongname)) {
+        throw new Error(
+          `missing ${name} in doclet index, did you forget a @module tag?`
+        );
+      }
+      byLongname[name].forEach(function (doclet) {
+        doclet.isDefaultExport = true;
+      });
+    }
+  },
+};

package/config/jsdoc/plugins/define-plugin.cjs

@@ -0,0 +1,33 @@
+/* eslint-disable import/no-commonjs */
+
+/**
+ * @fileoverview  This plugin extracts info from boolean defines.  This only
+ * handles boolean defines with the default value in the description.  Default
+ * is assumed to be provided with something like "default is `true`" (case
+ * insensitive, with or without ticks).
+ */
+
+const DEFAULT_VALUE = /default\s+is\s+`?(true|false)`?/i;
+
+/**
+ * Hook to define new tags.
+ * @param {Object} dictionary The tag dictionary.
+ */
+exports.defineTags = function (dictionary) {
+  dictionary.defineTag('define', {
+    canHaveType: true,
+    mustHaveValue: true,
+    onTagged: function (doclet, tag) {
+      const types = tag.value.type.names;
+      if (types.length === 1 && types[0] === 'boolean') {
+        const match = tag.value.description.match(DEFAULT_VALUE);
+        if (match) {
+          doclet.define = {
+            default: match[1] === 'true',
+          };
+          doclet.description = tag.value.description;
+        }
+      }
+    },
+  });
+};

package/config/jsdoc/plugins/events.cjs

@@ -0,0 +1,39 @@
+/* eslint-disable import/no-commonjs */
+
+const events = {};
+
+exports.handlers = {
+  newDoclet: function (e) {
+    const doclet = e.doclet;
+    if (doclet.kind !== 'event') {
+      return;
+    }
+
+    const cls = doclet.longname.split('#')[0];
+    if (!(cls in events)) {
+      events[cls] = [];
+    }
+    events[cls].push(doclet.longname);
+  },
+
+  parseComplete: function (e) {
+    const doclets = e.doclets;
+    for (let i = 0, ii = doclets.length - 1; i < ii; ++i) {
+      const doclet = doclets[i];
+      if (doclet.fires) {
+        if (doclet.kind == 'class') {
+          const fires = [];
+          for (let j = 0, jj = doclet.fires.length; j < jj; ++j) {
+            const event = doclet.fires[j].replace('event:', '');
+            if (events[event]) {
+              fires.push.apply(fires, events[event]);
+            } else if (doclet.fires[j] !== 'event:ObjectEvent') {
+              fires.push(doclet.fires[j]);
+            }
+          }
+          doclet.fires = fires;
+        }
+      }
+    }
+  },
+};

package/config/jsdoc/plugins/inline-options.cjs

@@ -0,0 +1,102 @@
+/* eslint-disable import/no-commonjs */
+
+/**
+ * @fileoverview
+ * Inlines option params from typedefs
+ */
+
+const properties = {};
+
+/**
+ * This parses the comment for `@template` annotations and returns an object with name / type pairs for all template
+ * values
+ * @param {string} comment a jsdoc comment to parse
+ * @return {Object<string, string>} results
+ */
+function parseCommentForTemplates(comment) {
+  let remainingText = comment;
+  const results = {};
+  while (true) {
+    const templateMatch = remainingText.match(/\* @template\s*([\s\S]*)/);
+
+    if (!templateMatch) {
+      return results;
+    }
+
+    remainingText = templateMatch[1];
+
+    if (remainingText[0] !== '{') {
+      continue;
+    }
+
+    let index = 1;
+    let openParenthesis = 1;
+    while (openParenthesis > 0) {
+      if (remainingText[index] === '{') {
+        openParenthesis++;
+      } else if (remainingText[index] === '}') {
+        openParenthesis--;
+      }
+      index++;
+    }
+    const type = remainingText.slice(1, index - 1);
+    remainingText = remainingText.slice(index);
+
+    const name = remainingText.match(/\s*(\S*)/)[1];
+
+    results[name] = type;
+  }
+}
+
+exports.handlers = {
+  /**
+   * Collects all typedefs, keyed by longname
+   * @param {Object} e Event object.
+   */
+  newDoclet: function (e) {
+    if (e.doclet.kind == 'typedef' && e.doclet.properties) {
+      properties[e.doclet.longname] = e.doclet.properties;
+    }
+  },
+
+  /**
+   * Adds `options.*` params for options that match the longname of one of the
+   * collected typedefs.
+   * @param {Object} e Event object.
+   */
+  parseComplete: function (e) {
+    const doclets = e.doclets;
+
+    for (let i = 0, ii = doclets.length; i < ii; ++i) {
+      const doclet = doclets[i];
+      if (doclet.params) {
+        const params = doclet.params;
+        for (let j = 0, jj = params.length; j < jj; ++j) {
+          const param = params[j];
+          if (param.type && param.type.names) {
+            let type = param.type.names[0];
+            const genericMatches = type.match(/(^.*?)\.?<.*>/);
+            if (genericMatches) {
+              type = genericMatches[1];
+            }
+            if (type in properties) {
+              const templateInfo = parseCommentForTemplates(doclet.comment);
+              params.push.apply(
+                params,
+                properties[type].map((p) => {
+                  const property = Object.assign({}, p);
+                  property.name = `${param.name}.${property.name}`;
+                  if (property.type.names[0] in templateInfo) {
+                    property.type.names[0] =
+                      templateInfo[property.type.names[0]];
+                  }
+                  return property;
+                })
+              );
+            }
+          }
+        }
+      }
+    }
+  },
+};

package/config/jsdoc/plugins/markdown.cjs

@@ -0,0 +1,119 @@
+/* eslint-disable import/no-commonjs */
+
+/**
+ * Modified from JSDoc's plugins/markdown and lib/jsdoc/util/markdown modules
+ * (see https://github.com/jsdoc3/jsdoc/), which are licensed under the Apache 2
+ * license (see https://www.apache.org/licenses/LICENSE-2.0).
+ *
+ * This version does not protect http(s) urls from being turned into links, and
+ * works around an issue with `~` characters in module paths by escaping them.
+ */
+
+const {marked} = require('marked');
+const format = require('util').format;
+
+const tags = [
+  'author',
+  'classdesc',
+  'description',
+  'exceptions',
+  'params',
+  'properties',
+  'returns',
+  'see',
+  'summary',
+];
+
+const hasOwnProp = Object.prototype.hasOwnProperty;
+
+const markedRenderer = new marked.Renderer();
+
+// Allow prettyprint to work on inline code samples
+markedRenderer.code = function (code, language) {
+  const langClass = language ? ' lang-' + language : '';
+
+  return format(
+    '<pre class="prettyprint source%s"><code>%s</code></pre>',
+    langClass,
+    escapeCode(code)
+  );
+};
+
+function escapeCode(source) {
+  return source
+    .replace(/</g, '&lt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function escapeUnderscoresAndTildes(source) {
+  return source.replace(/\{@[^}\r\n]+\}/g, function (wholeMatch) {
+    return wholeMatch.replace(/(^|[^\\])_/g, '$1\\_').replace('~', '&tilde;');
+  });
+}
+
+function unencodeQuotesAndTildes(source) {
+  return source.replace(/\{@[^}\r\n]+\}/g, function (wholeMatch) {
+    return wholeMatch.replace(/&quot;/g, '"').replace(/&tilde;/g, '~');
+  });
+}
+
+function parse(source) {
+  let result;
+
+  source = escapeUnderscoresAndTildes(source);
+
+  result = marked(source, {
+    renderer: markedRenderer,
+    headerIds: false,
+    mangle: false,
+  })
+    .replace(/\s+$/, '')
+    .replace(/&#39;/g, "'");
+
+  result = unencodeQuotesAndTildes(result);
+
+  return result;
+}
+
+function shouldProcessString(tagName, text) {
+  let shouldProcess = true;
+
+  // we only want to process `@author` and `@see` tags that contain Markdown links
+  if ((tagName === 'author' || tagName === 'see') && !text.includes('[')) {
+    shouldProcess = false;
+  }
+
+  return shouldProcess;
+}
+
+function process(doclet) {
+  tags.forEach(function (tag) {
+    if (!hasOwnProp.call(doclet, tag)) {
+      return;
+    }
+
+    if (
+      typeof doclet[tag] === 'string' &&
+      shouldProcessString(tag, doclet[tag])
+    ) {
+      doclet[tag] = parse(doclet[tag]);
+    } else if (Array.isArray(doclet[tag])) {
+      doclet[tag].forEach(function (value, index, original) {
+        const inner = {};
+
+        inner[tag] = value;
+        process(inner);
+        original[index] = inner[tag];
+      });
+    } else if (doclet[tag]) {
+      process(doclet[tag]);
+    }
+  });
+}
+
+exports.handlers = {
+  newDoclet: function (e) {
+    process(e.doclet);
+  },
+};