Generate TypeScript declaration for Configuration object from JSON schema (refs #1004, refs #1014).

demo/markdownlint-browser.js

@@ -2106,6 +2106,7 @@ function getEffectiveConfig(ruleList, config, aliasToRuleNames) {
     return key.toUpperCase() === "DEFAULT";
   });
   var ruleDefault = defaultKey.length === 0 || !!config[defaultKey[0]];
+  /** @type {Configuration} */
   var effectiveConfig = {};
   var _iterator14 = _createForOfIteratorHelper(ruleList),
     _step14;
@@ -3191,10 +3192,10 @@ module.exports = markdownlint;
  */
 
 /**
- * Configuration object for linting rules. For a detailed schema, see
+ * Configuration object for linting rules. For the JSON schema, see
  * {@link ../schema/markdownlint-config-schema.json}.
  *
- * @typedef {Object.<string, RuleConfiguration>} Configuration
+ * @typedef {import("./configuration").Configuration} Configuration
  */
 
 /**

lib/markdownlint.d.ts

@@ -358,12 +358,10 @@ type FixInfo = {
  */
 type LintContentCallback = (error: Error | null, result?: LintError[]) => void;
 /**
- * Configuration object for linting rules. For a detailed schema, see
+ * Configuration object for linting rules. For the JSON schema, see
  * {@link  ../schema/markdownlint-config-schema.json}.
  */
-type Configuration = {
-    [x: string]: RuleConfiguration;
-};
+type Configuration = import("./configuration").Configuration;
 /**
  * Rule configuration.
  */

lib/markdownlint.js

@@ -317,6 +317,7 @@ function getEffectiveConfig(ruleList, config, aliasToRuleNames) {
     (key) => key.toUpperCase() === "DEFAULT"
   );
   const ruleDefault = (defaultKey.length === 0) || !!config[defaultKey[0]];
+  /** @type {Configuration} */
   const effectiveConfig = {};
   for (const rule of ruleList) {
     const ruleName = rule.names[0].toUpperCase();
@@ -1436,10 +1437,10 @@ module.exports = markdownlint;
  */
 
 /**
- * Configuration object for linting rules. For a detailed schema, see
+ * Configuration object for linting rules. For the JSON schema, see
  * {@link ../schema/markdownlint-config-schema.json}.
  *
- * @typedef {Object.<string, RuleConfiguration>} Configuration
+ * @typedef {import("./configuration").Configuration} Configuration
  */
 
 /**

package.json

@@ -26,7 +26,7 @@
     "build-config": "npm run build-config-schema && npm run build-config-example",
     "build-config-example": "node schema/build-config-example.js",
     "build-config-schema": "node schema/build-config-schema.js",
-    "build-declaration": "tsc --allowJs --declaration --emitDeclarationOnly --module commonjs --resolveJsonModule --target es2015 lib/markdownlint.js && node scripts delete 'lib/{c,md,r}*.d.ts' 'micromark/*.d.cts' 'helpers/*.d.{cts,ts}'",
+    "build-declaration": "tsc --allowJs --declaration --emitDeclarationOnly --module commonjs --resolveJsonModule --target es2015 lib/markdownlint.js && node scripts delete 'lib/{cache,constants,md,r}*.d.ts' 'micromark/*.d.cts' 'helpers/*.d.{cts,ts}'",
     "build-demo": "node scripts copy node_modules/markdown-it/dist/markdown-it.min.js demo/markdown-it.min.js && node scripts copy node_modules/markdownlint-micromark/micromark-browser.js demo/micromark-browser.js && node scripts copy node_modules/markdownlint-micromark/micromark-html-browser.js demo/micromark-html-browser.js && cd demo && webpack --no-stats",
     "build-docs": "node doc-build/build-rules.mjs",
     "build-example": "npm install --no-save --ignore-scripts grunt grunt-cli gulp through2",
@@ -85,6 +85,7 @@
     "gemoji": "8.1.0",
     "globby": "13.2.2",
     "js-yaml": "4.1.0",
+    "json-schema-to-typescript": "13.1.1",
     "markdown-it-for-inline": "0.1.1",
     "markdown-it-sub": "1.0.0",
     "markdown-it-sup": "1.0.0",

schema/build-config-schema.js

@@ -4,7 +4,9 @@
 
 const fs = require("node:fs");
 const path = require("node:path");
+/** @type {import("../lib/markdownlint").Rule[]} */
 const rules = require("../lib/rules");
+const jsonSchemaToTypeScript = require("json-schema-to-typescript");
 
 // Schema scaffolding
 const schema = {
@@ -548,10 +550,12 @@ for (const rule of rules) {
     scheme.type = [ "boolean", "object" ];
     scheme.additionalProperties = false;
   }
-  for (const [ index, name ] of rule.names.entries()) {
-    schema.properties[name] = (index === 0) ? scheme : {
-      "$ref": `#/properties/${rule.names[0]}`
-    };
+  for (const name of rule.names) {
+    schema.properties[name] = scheme;
+    // Using $ref causes rule aliases not to get JSDoc comments
+    // schema.properties[name] = (index === 0) ? scheme : {
+    //   "$ref": `#/properties/${rule.names[0]}`
+    // };
   }
 }
 
@@ -568,3 +572,18 @@ for (const [ tag, tagTags ] of Object.entries(tags)) {
 // Write schema
 const schemaFile = path.join(__dirname, "markdownlint-config-schema.json");
 fs.writeFileSync(schemaFile, JSON.stringify(schema, null, "  "));
+
+// Write TypeScript declaration
+// See https://github.com/bcherny/json-schema-to-typescript/issues/356 for why
+// additionalProperties is deleted
+const schemaDeclaration =
+  path.join(__dirname, "..", "lib", "configuration.d.ts");
+// @ts-ignore
+delete schema.additionalProperties;
+schema.title = "Configuration";
+jsonSchemaToTypeScript.compile(
+  // @ts-ignore
+  schema,
+  "UNUSED"
+  // eslint-disable-next-line unicorn/prefer-top-level-await
+).then((declaration) => fs.writeFileSync(schemaDeclaration, declaration));