Use arrays instead of CSV strings for config file types (#300)

Author: bmish

lib/cli.ts

@@ -12,11 +12,30 @@ import {
 } from './types.js';
 import { getCurrentPackageVersion } from './package-json.js';
 
-/** Used for collecting repeated CLI options into an array. */
-function collect(value: string, previous: string[]) {
+/**
+ * Used for collecting repeated CLI options into an array.
+ * Example: --foo bar --foo baz => ['bar', 'baz']
+ */
+function collect(value: string, previous: string[]): string[] {
   return [...previous, value];
 }
 
+/**
+ * Used for collecting CSV CLI options into an array.
+ * Example: --foo bar,baz,buz => ['bar', 'baz', 'buz']
+ * */
+function collectCSV(value: string, previous: string[]): string[] {
+  return [...previous, ...value.split(',')];
+}
+
+/**
+ * Used for collecting repeated, nested CSV CLI options into an array of arrays.
+ * Example: --foo baz,bar --foo biz,buz => [['baz', 'bar'], ['biz', 'buz']]
+ * */
+function collectCSVNested(value: string, previous: string[][]): string[][] {
+  return [...previous, value.split(',')];
+}
+
 function parseBoolean(value: string | undefined): boolean {
   return ['true', undefined].includes(value);
 }
@@ -39,21 +58,42 @@ async function loadConfigFileOptions(): Promise<GenerateOptions> {
         minLength: 1,
       },
     };
+
+    const schemaConfigEmoji = {
+      // Top-level array.
+      type: 'array',
+      uniqueItems: true,
+      minItems: 1,
+      items: {
+        // Nested array (config/emoji tuple).
+        type: 'array',
+        uniqueItems: true,
+        minItems: 1, // Allowed to pass only config name to remove default emoji.
+        maxItems: 2, // Normally, two items will be passed.
+        items: {
+          type: 'string',
+          minLength: 1,
+        },
+      },
+    };
+
     const properties: { [key in OPTION_TYPE]: unknown } = {
       check: { type: 'boolean' },
-      configEmoji: schemaStringArray,
+      configEmoji: schemaConfigEmoji,
       ignoreConfig: schemaStringArray,
       ignoreDeprecatedRules: { type: 'boolean' },
       initRuleDocs: { type: 'boolean' },
       pathRuleDoc: { type: 'string' },
       pathRuleList: { anyOf: [{ type: 'string' }, schemaStringArray] },
-      postprocess: {},
-      ruleDocNotices: { type: 'string' },
+      postprocess: {
+        /* JSON Schema can't validate functions so check this later */
+      },
+      ruleDocNotices: schemaStringArray,
       ruleDocSectionExclude: schemaStringArray,
       ruleDocSectionInclude: schemaStringArray,
       ruleDocSectionOptions: { type: 'boolean' },
       ruleDocTitleFormat: { type: 'string' },
-      ruleListColumns: { type: 'string' },
+      ruleListColumns: schemaStringArray,
       splitBy: { type: 'string' },
       urlConfigs: { type: 'string' },
       urlRuleDoc: { type: 'string' },
@@ -116,7 +156,7 @@ export async function run(
     .option(
       '--config-emoji <config-emoji>',
       '(optional) Custom emoji to use for a config. Format is `config-name,emoji`. Default emojis are provided for common configs. To remove a default emoji and rely on a badge instead, provide the config name without an emoji. Option can be repeated.',
-      collect,
+      collectCSVNested,
       []
     )
     .option(
@@ -159,7 +199,9 @@ export async function run(
         NOTICE_TYPE
       ).join('", "')}") (default: ${
         OPTION_DEFAULTS[OPTION_TYPE.RULE_DOC_NOTICES]
-      })`
+      })`,
+      collectCSV,
+      []
     )
     .option(
       '--rule-doc-section-exclude <section>',
@@ -194,7 +236,9 @@ export async function run(
         COLUMN_TYPE
       ).join('", "')})" (default: ${
         OPTION_DEFAULTS[OPTION_TYPE.RULE_LIST_COLUMNS]
-      })`
+      })`,
+      collectCSV,
+      []
     )
     .option(
       '--split-by <property>',

lib/generator.ts

@@ -119,6 +119,8 @@ export async function generate(path: string, options?: GenerateOptions) {
     options?.pathRuleList,
     OPTION_DEFAULTS[OPTION_TYPE.PATH_RULE_LIST]
   );
+  const postprocess =
+    options?.postprocess ?? OPTION_DEFAULTS[OPTION_TYPE.POSTPROCESS];
   const ruleDocNotices = parseRuleDocNoticesOption(options?.ruleDocNotices);
   const ruleDocSectionExclude = stringOrArrayWithFallback(
     options?.ruleDocSectionExclude,
@@ -140,8 +142,6 @@ export async function generate(path: string, options?: GenerateOptions) {
     options?.urlConfigs ?? OPTION_DEFAULTS[OPTION_TYPE.URL_CONFIGS];
   const urlRuleDoc =
     options?.urlRuleDoc ?? OPTION_DEFAULTS[OPTION_TYPE.URL_RULE_DOC];
-  const postprocess =
-    options?.postprocess ?? OPTION_DEFAULTS[OPTION_TYPE.POSTPROCESS];
 
   // Gather details about rules.
   const details: RuleDetails[] = Object.entries(plugin.rules)

lib/option-parsers.ts

@@ -15,13 +15,13 @@ import type { Plugin, ConfigEmojis } from './types.js';
  */
 export function parseConfigEmojiOptions(
   plugin: Plugin,
-  configEmoji?: string[]
+  configEmoji?: string[][]
 ): ConfigEmojis {
   const configsSeen = new Set<string>();
   const configsWithDefaultEmojiRemoved: string[] = [];
   const configEmojis =
     configEmoji?.flatMap((configEmojiItem) => {
-      const [config, emoji, ...extra] = configEmojiItem.split(',');
+      const [config, emoji, ...extra] = configEmojiItem;
 
       // Check for duplicate configs.
       if (configsSeen.has(config)) {
@@ -75,9 +75,9 @@ export function parseConfigEmojiOptions(
  * Parse the option, check for errors, and set defaults.
  */
 export function parseRuleListColumnsOption(
-  ruleListColumns: string | undefined
+  ruleListColumns: string[] | undefined
 ): COLUMN_TYPE[] {
-  const values = ruleListColumns ? ruleListColumns.split(',') : [];
+  const values = ruleListColumns ?? [];
   const VALUES_OF_TYPE = new Set(Object.values(COLUMN_TYPE).map(String));
 
   // Check for invalid.
@@ -105,9 +105,9 @@ export function parseRuleListColumnsOption(
  * Parse the option, check for errors, and set defaults.
  */
 export function parseRuleDocNoticesOption(
-  ruleDocNotices: string | undefined
+  ruleDocNotices: string[] | undefined
 ): NOTICE_TYPE[] {
-  const values = ruleDocNotices ? ruleDocNotices.split(',') : [];
+  const values = ruleDocNotices ?? [];
   const VALUES_OF_TYPE = new Set(Object.values(NOTICE_TYPE).map(String));
 
   // Check for invalid.

lib/options.ts

@@ -47,12 +47,12 @@ export const OPTION_DEFAULTS = {
   [OPTION_TYPE.INIT_RULE_DOCS]: false,
   [OPTION_TYPE.PATH_RULE_DOC]: join('docs', 'rules', '{name}.md'),
   [OPTION_TYPE.PATH_RULE_LIST]: 'README.md',
+  [OPTION_TYPE.POSTPROCESS]: (content: string) => content,
   [OPTION_TYPE.RULE_DOC_NOTICES]: Object.entries(
     NOTICE_TYPE_DEFAULT_PRESENCE_AND_ORDERING
   )
     .filter(([_col, enabled]) => enabled)
-    .map(([col]) => col)
-    .join(','),
+    .map(([col]) => col),
   [OPTION_TYPE.RULE_DOC_SECTION_EXCLUDE]: [],
   [OPTION_TYPE.RULE_DOC_SECTION_INCLUDE]: [],
   [OPTION_TYPE.RULE_DOC_SECTION_OPTIONS]: true,
@@ -61,10 +61,8 @@ export const OPTION_DEFAULTS = {
     COLUMN_TYPE_DEFAULT_PRESENCE_AND_ORDERING
   )
     .filter(([_col, enabled]) => enabled)
-    .map(([col]) => col)
-    .join(','),
+    .map(([col]) => col),
   [OPTION_TYPE.SPLIT_BY]: undefined,
   [OPTION_TYPE.URL_CONFIGS]: undefined,
   [OPTION_TYPE.URL_RULE_DOC]: undefined,
-  [OPTION_TYPE.POSTPROCESS]: (content: string) => content,
 } satisfies Record<OPTION_TYPE, unknown>; // Satisfies is used to ensure all options are included, but without losing type information.

lib/types.ts

@@ -91,6 +91,7 @@ export enum OPTION_TYPE {
   INIT_RULE_DOCS = 'initRuleDocs',
   PATH_RULE_DOC = 'pathRuleDoc',
   PATH_RULE_LIST = 'pathRuleList',
+  POSTPROCESS = 'postprocess',
   RULE_DOC_NOTICES = 'ruleDocNotices',
   RULE_DOC_SECTION_EXCLUDE = 'ruleDocSectionExclude',
   RULE_DOC_SECTION_INCLUDE = 'ruleDocSectionInclude',
@@ -100,7 +101,6 @@ export enum OPTION_TYPE {
   SPLIT_BY = 'splitBy',
   URL_CONFIGS = 'urlConfigs',
   URL_RULE_DOC = 'urlRuleDoc',
-  POSTPROCESS = 'postprocess',
 }
 
 // JSDocs for options should be kept in sync with README.md and the CLI runner in cli.ts.
@@ -111,11 +111,11 @@ export type GenerateOptions = {
   check?: boolean;
   /**
    * List of configs and their associated emojis.
-   * Format is `config-name,emoji`.
+   * Array of `[configName, emoji]`.
    * Default emojis are provided for common configs.
    * To remove a default emoji and rely on a badge instead, provide the config name without an emoji.
    */
-  configEmoji?: string[];
+  configEmoji?: string[][];
   /** Configs to ignore from being displayed. Often used for an `all` config. */
   ignoreConfig?: string[];
   /** Whether to ignore deprecated rules from being checked, displayed, or updated. Default: `false`. */
@@ -135,12 +135,12 @@ export type GenerateOptions = {
     pathToFile: string
   ) => string | Promise<string>;
   /**
-   * Ordered, comma-separated list of notices to display in rule doc.
+   * Ordered list of notices to display in rule doc.
    * Non-applicable notices will be hidden.
    * Choices: `configs`, `deprecated`, `fixable` (off by default), `fixableAndHasSuggestions`, `hasSuggestions` (off by default), `options` (off by default), `requiresTypeChecking`, `type` (off by default).
-   * Default: `deprecated,configs,fixableAndHasSuggestions,requiresTypeChecking`.
+   * Default: `['deprecated', 'configs', 'fixableAndHasSuggestions', 'requiresTypeChecking']`.
    */
-  ruleDocNotices?: string;
+  ruleDocNotices?: NOTICE_TYPE[];
   /** Disallowed sections in each rule doc. Exit with failure if present. */
   ruleDocSectionExclude?: string[];
   /** Required sections in each rule doc. Exit with failure if missing. */
@@ -150,12 +150,12 @@ export type GenerateOptions = {
   /** The format to use for rule doc titles. Default: `desc-parens-prefix-name`. */
   ruleDocTitleFormat?: RuleDocTitleFormat;
   /**
-   * Ordered, comma-separated list of columns to display in rule list.
+   * Ordered list of columns to display in rule list.
    * Empty columns will be hidden.
    * Choices: `configsError`, `configsOff`, `configsWarn`, `deprecated`, `description`, `fixable`, `fixableAndHasSuggestions` (off by default), `hasSuggestions`, `name`, `options` (off by default), `requiresTypeChecking`, `type` (off by default).
-   * Default: `name,description,configsError,configsWarn,configsOff,fixable,hasSuggestions,requiresTypeChecking,deprecated`.
+   * Default: `['name', 'description', 'configsError', 'configsWarn', 'configsOff', 'fixable', 'hasSuggestions', 'requiresTypeChecking', 'deprecated']`.
    */
-  ruleListColumns?: string;
+  ruleListColumns?: COLUMN_TYPE[];
   /**
    * Rule property to split the rules list by.
    * A separate list and header will be created for each value.