@markuplint/spec-generator 4.8.0 → 4.8.2

package/lib/read-json.js

@@ -2,6 +2,14 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { glob } from 'glob';
 import strip from 'strip-json-comments';
+/**
+ * Reads and parses a single JSON file (with support for JSON comments) from an absolute file path.
+ *
+ * @template T - The expected shape of the parsed JSON data
+ * @param filePath - The absolute file path to the JSON file
+ * @returns The parsed JSON content
+ * @throws If the provided path is not absolute
+ */
 export function readJson(filePath) {
     if (!path.isAbsolute(filePath)) {
         throw new Error(`The path must be absolute path: ${filePath}`);
@@ -10,6 +18,16 @@ export function readJson(filePath) {
     json = strip(json);
     return JSON.parse(json);
 }
+/**
+ * Reads multiple JSON files matching a glob pattern and optionally transforms each result.
+ * All matched files are read and parsed in parallel.
+ *
+ * @template T - The expected shape of each parsed JSON file
+ * @param pattern - An absolute glob pattern to match JSON files
+ * @param hook - An optional transformation function called with each file path and its parsed body
+ * @returns An array of parsed (and optionally transformed) JSON objects
+ * @throws If the provided pattern is not an absolute path
+ */
 export async function readJsons(pattern, hook = (_, body) => body) {
     if (!path.isAbsolute(pattern)) {
         throw new Error(`The pattern must be absolute path: ${pattern}`);

package/lib/scraping.d.ts

@@ -1,3 +1,18 @@
 import type { ExtendedElementSpec } from '@markuplint/ml-spec';
+/**
+ * Generates minimal element specification stubs for obsolete/deprecated elements
+ * that do not already exist in the provided specs array.
+ *
+ * @param obsoleteList - A list of element names considered obsolete or deprecated
+ * @param specs - The existing element specifications to check against for duplicates
+ * @returns An array of element spec stubs for elements not already present in `specs`
+ */
 export declare function fetchObsoleteElements(obsoleteList: readonly string[], specs: readonly ExtendedElementSpec[]): ExtendedElementSpec[];
+/**
+ * Scrapes an MDN element reference page to extract metadata about an HTML or SVG element.
+ * Gathers description, compatibility status flags, content categories, and attributes.
+ *
+ * @param link - The MDN URL for the element (e.g., `https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a`)
+ * @returns An extended element specification object populated with scraped MDN data
+ */
 export declare function fetchHTMLElement(link: string): Promise<ExtendedElementSpec>;

package/lib/scraping.js

@@ -1,6 +1,17 @@
 import { fetch } from './fetch.js';
 import { sortObjectByKey } from './utils.js';
+/**
+ * CSS selector for the main content area on MDN pages.
+ */
 const MAIN_ARTICLE_SELECTOR = 'main#content';
+/**
+ * Generates minimal element specification stubs for obsolete/deprecated elements
+ * that do not already exist in the provided specs array.
+ *
+ * @param obsoleteList - A list of element names considered obsolete or deprecated
+ * @param specs - The existing element specifications to check against for duplicates
+ * @returns An array of element spec stubs for elements not already present in `specs`
+ */
 export function fetchObsoleteElements(obsoleteList, specs) {
     return obsoleteList
         .map(name => {
@@ -27,6 +38,13 @@ export function fetchObsoleteElements(obsoleteList, specs) {
     })
         .filter((e) => !!e);
 }
+/**
+ * Scrapes an MDN element reference page to extract metadata about an HTML or SVG element.
+ * Gathers description, compatibility status flags, content categories, and attributes.
+ *
+ * @param link - The MDN URL for the element (e.g., `https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a`)
+ * @returns An extended element specification object populated with scraped MDN data
+ */
 export async function fetchHTMLElement(link) {
     const $ = await fetch(link);
     const name = link.replace(/.+\/([\w-]+)$/, '$1').toLowerCase();
@@ -116,6 +134,13 @@ export async function fetchHTMLElement(link) {
     };
     return spec;
 }
+/**
+ * Extracts the text value of a specific property from the MDN technical summary table.
+ *
+ * @param $ - The Cheerio API instance for the page
+ * @param prop - The property name to look for in the table header cells (matched case-insensitively)
+ * @returns The trimmed text content of the corresponding table cell
+ */
 function getProperty(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 $, prop) {
@@ -126,6 +151,15 @@ $, prop) {
         .filter(el => new RegExp(prop, 'i').test($(el).text())));
     return $th.siblings('td').text().trim().replaceAll(/\s+/g, ' ');
 }
+/**
+ * Extracts element attributes from an MDN page section identified by its `aria-labelledby` ID.
+ * Parses each `<dt>` entry in the section's definition list to gather attribute name,
+ * description, and status flags (experimental, obsolete, deprecated, non-standard).
+ *
+ * @param $ - The Cheerio API instance for the page
+ * @param id - The `aria-labelledby` ID of the section containing the attributes
+ * @returns An object containing a record of parsed attribute definitions keyed by attribute name
+ */
 function getAttributes(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 $, id) {
@@ -185,6 +219,12 @@ $, id) {
     }
     return { attributes };
 }
+/**
+ * Traverses the DOM upward from a starting element to find its nearest preceding heading element.
+ *
+ * @param $start - The Cheerio element from which to begin the upward search
+ * @returns The heading element if found, or `null` if no heading is encountered
+ */
 function getItsHeading(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 $start) {
@@ -197,6 +237,12 @@ $start) {
     }
     return null;
 }
+/**
+ * Moves to the previous sibling of the given element, or to its parent if no previous sibling exists.
+ *
+ * @param $start - The Cheerio element from which to navigate
+ * @returns The previous sibling or parent element
+ */
 function upToPrevOrParent(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 $start) {
@@ -206,6 +252,12 @@ $start) {
     }
     return $needle;
 }
+/**
+ * Checks whether a Cheerio element is an HTML heading element (`<h1>` through `<h6>`).
+ *
+ * @param $el - The Cheerio element to test
+ * @returns `true` if the element is a heading, `false` otherwise
+ */
 function isHeading(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 $el) {

package/lib/svg.d.ts

@@ -1 +1,8 @@
+/**
+ * Fetches the MDN SVG element index page and extracts the list of
+ * obsolete and deprecated SVG element names.
+ * Each name is prefixed with `"svg_"` to distinguish it from HTML elements.
+ *
+ * @returns An array of deprecated/obsolete SVG element names (e.g., `["svg_altGlyph", ...]`)
+ */
 export declare function getSVGElementList(): Promise<string[]>;

package/lib/svg.js

@@ -1,5 +1,12 @@
 import { fetch } from './fetch.js';
 import { getThisOutline } from './utils.js';
+/**
+ * Fetches the MDN SVG element index page and extracts the list of
+ * obsolete and deprecated SVG element names.
+ * Each name is prefixed with `"svg_"` to distinguish it from HTML elements.
+ *
+ * @returns An array of deprecated/obsolete SVG element names (e.g., `["svg_altGlyph", ...]`)
+ */
 export async function getSVGElementList() {
     const index = 'https://developer.mozilla.org/en-US/docs/Web/SVG/Element';
     const $ = await fetch(index);

package/lib/utils.d.ts

@@ -1,14 +1,73 @@
 import type * as cheerio from 'cheerio';
 import type { AnyNode } from 'domhandler';
+/**
+ * Represents an object that has a `name` property.
+ */
 type HasName = {
     readonly name: string;
 };
+/**
+ * Compares two items by their name property (or string value) in a case-insensitive manner.
+ * Suitable for use as a comparator function in `Array.prototype.sort`.
+ *
+ * @param a - The first item to compare, either a string or an object with a `name` property
+ * @param b - The second item to compare, either a string or an object with a `name` property
+ * @returns A negative number if `a` comes before `b`, positive if after, or zero if equal
+ */
 export declare function nameCompare(a: HasName | string, b: HasName | string): 1 | 0 | -1;
+/**
+ * Creates a new object with the same key-value pairs, sorted alphabetically by key.
+ *
+ * @template T - The type of the object
+ * @param o - The object whose keys should be sorted
+ * @returns A new object with keys in sorted alphabetical order
+ */
 export declare function sortObjectByKey<T>(o: T): T;
+/**
+ * Removes duplicate items from an array based on their `name` property,
+ * keeping only the first occurrence.
+ *
+ * @template T - The type of array items, must have a `name` property
+ * @param array - The array to deduplicate
+ * @returns A new array with unique items by name
+ */
 export declare function arrayUnique<T extends HasName>(array: readonly T[]): T[];
+/**
+ * Collects all sibling elements following a starting element until the next `<h2>` heading
+ * (or end of siblings) and wraps them in a container `<div>`.
+ * Useful for extracting a section of content defined by a heading.
+ *
+ * @param $ - The Cheerio API instance for DOM manipulation
+ * @param $start - The starting element (typically a heading) from which to collect siblings
+ * @returns A Cheerio wrapper around a `<div>` containing cloned elements of the section
+ */
 export declare function getThisOutline($: cheerio.CheerioAPI, $start: cheerio.Cheerio<AnyNode>): cheerio.Cheerio<AnyNode>;
+/**
+ * Merges two attribute objects, with values from `fromJSON` taking precedence
+ * over values from `fromDocs` when keys overlap.
+ *
+ * @template T - The type of the attribute objects
+ * @param fromDocs - Attribute data sourced from documentation
+ * @param fromJSON - Attribute data sourced from JSON specification files
+ * @returns A merged object combining both sources
+ */
 export declare function mergeAttributes<T>(fromDocs: T, fromJSON: T): T;
+/**
+ * Returns the keys of an object with a custom type cast.
+ *
+ * @template T - The type of the input object
+ * @template K - The desired key type (defaults to `keyof T`)
+ * @param object - The object whose keys to extract
+ * @returns An array of the object's keys cast to the specified type
+ */
 export declare function keys<T, K = keyof T>(object: T): K[];
+/**
+ * Parses an element name string to extract the local name, namespace, and markup language type.
+ * Handles SVG-prefixed names (e.g., `"svg_circle"`) and plain HTML names.
+ *
+ * @param origin - The raw element name, optionally prefixed with `"svg_"` for SVG elements
+ * @returns An object containing the `localName`, optional SVG `namespace` URI, and `ml` type (`"SVG"` or `"HTML"`)
+ */
 export declare function getName(origin: string): {
     localName: string;
     namespace: "http://www.w3.org/2000/svg" | undefined;

package/lib/utils.js

@@ -1,3 +1,11 @@
+/**
+ * Compares two items by their name property (or string value) in a case-insensitive manner.
+ * Suitable for use as a comparator function in `Array.prototype.sort`.
+ *
+ * @param a - The first item to compare, either a string or an object with a `name` property
+ * @param b - The second item to compare, either a string or an object with a `name` property
+ * @returns A negative number if `a` comes before `b`, positive if after, or zero if equal
+ */
 export function nameCompare(a, b) {
     const nameA = typeof a === 'string' ? a : (a.name?.toUpperCase() ?? String(a));
     const nameB = typeof b === 'string' ? b : (b.name?.toUpperCase() ?? String(b));
@@ -9,6 +17,13 @@ export function nameCompare(a, b) {
     }
     return 0;
 }
+/**
+ * Creates a new object with the same key-value pairs, sorted alphabetically by key.
+ *
+ * @template T - The type of the object
+ * @param o - The object whose keys should be sorted
+ * @returns A new object with keys in sorted alphabetical order
+ */
 export function sortObjectByKey(o) {
     // @ts-ignore
     const keys = Object.keys(o);
@@ -21,6 +36,14 @@ export function sortObjectByKey(o) {
     }
     return newObj;
 }
+/**
+ * Removes duplicate items from an array based on their `name` property,
+ * keeping only the first occurrence.
+ *
+ * @template T - The type of array items, must have a `name` property
+ * @param array - The array to deduplicate
+ * @returns A new array with unique items by name
+ */
 export function arrayUnique(array) {
     const nameStack = [];
     const result = [];
@@ -33,6 +56,15 @@ export function arrayUnique(array) {
     }
     return result;
 }
+/**
+ * Collects all sibling elements following a starting element until the next `<h2>` heading
+ * (or end of siblings) and wraps them in a container `<div>`.
+ * Useful for extracting a section of content defined by a heading.
+ *
+ * @param $ - The Cheerio API instance for DOM manipulation
+ * @param $start - The starting element (typically a heading) from which to collect siblings
+ * @returns A Cheerio wrapper around a `<div>` containing cloned elements of the section
+ */
 export function getThisOutline(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 $, 
@@ -49,16 +81,40 @@ $start) {
         $container.append(el);
     return $container;
 }
+/**
+ * Merges two attribute objects, with values from `fromJSON` taking precedence
+ * over values from `fromDocs` when keys overlap.
+ *
+ * @template T - The type of the attribute objects
+ * @param fromDocs - Attribute data sourced from documentation
+ * @param fromJSON - Attribute data sourced from JSON specification files
+ * @returns A merged object combining both sources
+ */
 export function mergeAttributes(fromDocs, fromJSON) {
     return {
         ...fromDocs,
         ...fromJSON,
     };
 }
+/**
+ * Returns the keys of an object with a custom type cast.
+ *
+ * @template T - The type of the input object
+ * @template K - The desired key type (defaults to `keyof T`)
+ * @param object - The object whose keys to extract
+ * @returns An array of the object's keys cast to the specified type
+ */
 export function keys(object) {
     // @ts-ignore
     return Object.keys(object);
 }
+/**
+ * Parses an element name string to extract the local name, namespace, and markup language type.
+ * Handles SVG-prefixed names (e.g., `"svg_circle"`) and plain HTML names.
+ *
+ * @param origin - The raw element name, optionally prefixed with `"svg_"` for SVG elements
+ * @returns An object containing the `localName`, optional SVG `namespace` URI, and `ml` type (`"SVG"` or `"HTML"`)
+ */
 export function getName(origin) {
     const [, ns, localName] = origin.match(/^(?:(svg)_)?(\w+)/i) ?? [];
     const name = localName ?? origin;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/spec-generator",
-	"version": "4.8.0",
+	"version": "4.8.2",
 	"description": "Generates @markuplint/html-spec",
 	"repository": "git@github.com:markuplint/markuplint.git",
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
@@ -23,17 +23,17 @@
 	"dependencies": {
 		"@types/cheerio": "1.0.0",
 		"ajv": "8.17.1",
-		"cheerio": "1.1.2",
+		"cheerio": "1.2.0",
 		"cli-progress": "3.12.0",
-		"fast-xml-parser": "5.2.5",
-		"glob": "11.0.3",
+		"fast-xml-parser": "5.3.5",
+		"glob": "13.0.1",
 		"strip-json-comments": "5.0.3"
 	},
 	"devDependencies": {
-		"@markuplint/ml-spec": "4.10.0",
-		"@markuplint/test-tools": "4.5.21",
+		"@markuplint/ml-spec": "4.10.2",
+		"@markuplint/test-tools": "4.5.23",
 		"@types/cli-progress": "3.11.6",
 		"type-fest": "4.41.0"
 	},
-	"gitHead": "ae97eb2d31ecedf4f0800fbbf18588aad4ebca04"
+	"gitHead": "193ee7c1262bbed95424e38efdf1a8e56ff049f4"
 }