@markuplint/rules 4.11.2 → 5.0.0-alpha.0

package/lib/no-unsupported-features/compat-data.js

@@ -0,0 +1,204 @@
+/**
+ * Mapping from browserslist browser names to BCD browser names.
+ */
+const BROWSERSLIST_TO_BCD = new Map([
+    ['chrome', 'chrome'],
+    ['firefox', 'firefox'],
+    ['safari', 'safari'],
+    ['edge', 'edge'],
+    ['ie', 'ie'],
+    ['opera', 'opera'],
+    ['and_chr', 'chrome_android'],
+    ['and_ff', 'firefox_android'],
+    ['ios_saf', 'safari_ios'],
+    ['samsung', 'samsunginternet_android'],
+    ['op_mob', 'opera_android'],
+    ['android', 'webview_android'],
+]);
+let bcdPromise;
+/**
+ * Dynamically import @mdn/browser-compat-data.
+ *
+ * This uses dynamic import because BCD's main entry points to a ~70MB JSON
+ * file. Static import would force every markuplint user to parse that JSON
+ * at startup, even when this rule is disabled. Dynamic import defers the
+ * cost until the rule actually runs.
+ *
+ * Uses a Promise-based cache to prevent race conditions when multiple
+ * concurrent calls trigger the import simultaneously.
+ */
+function loadBcd() {
+    if (!bcdPromise) {
+        bcdPromise = import('@mdn/browser-compat-data').then(mod => mod.default ?? mod);
+    }
+    return bcdPromise;
+}
+/**
+ * Convert a browserslist browser name to a BCD browser name.
+ *
+ * @param browserslistName - The browser name from browserslist (e.g., "and_chr")
+ * @returns The corresponding BCD browser name, or null if unknown
+ */
+export function toBcdBrowserId(browserslistName) {
+    return BROWSERSLIST_TO_BCD.get(browserslistName) ?? null;
+}
+/**
+ * Parse a version string into a comparable numeric tuple.
+ *
+ * Handles BCD version prefixes like "≤37" by stripping the prefix.
+ *
+ * @param version - Version string (e.g., "16.4", "≤37", "preview")
+ * @returns Tuple of [major, minor, patch]
+ */
+export function parseVersion(version) {
+    const cleaned = version.replace(/^≤/, '');
+    const parts = cleaned.split('.').map(Number);
+    return [parts[0] ?? Number.NaN, parts[1] ?? 0, parts[2] ?? 0];
+}
+/**
+ * Check if the target browser version satisfies the required version.
+ *
+ * Returns true if the target version is greater than or equal to the
+ * version the feature was added in.
+ *
+ * @param targetVersion - The browser version the user targets
+ * @param addedVersion - The version the feature was added in
+ * @returns Whether the target version supports the feature
+ */
+export function isVersionSatisfied(targetVersion, addedVersion) {
+    const [tMajor, tMinor, tPatch] = parseVersion(targetVersion);
+    const [aMajor, aMinor, aPatch] = parseVersion(addedVersion);
+    if (Number.isNaN(tMajor) || Number.isNaN(aMajor)) {
+        return true;
+    }
+    if (tMajor !== aMajor) {
+        return tMajor > aMajor;
+    }
+    if (tMinor !== aMinor) {
+        return tMinor > aMinor;
+    }
+    return tPatch >= aPatch;
+}
+/**
+ * Get the standard (non-flagged, non-prefixed) support statement
+ * from a SupportStatement which may be an array.
+ */
+function getStandardSupport(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+support) {
+    if (Array.isArray(support)) {
+        const standard = support.find(s => !s.flags && !s.prefix && !s.alternative_name);
+        return standard ?? null;
+    }
+    if (support.flags || support.prefix || support.alternative_name) {
+        return null;
+    }
+    return support;
+}
+/**
+ * Check if a feature is supported by a specific browser version.
+ *
+ * @param support - The BCD support statement for the feature
+ * @param target - The target browser to check
+ * @returns null if supported or unknown, UnsupportedResult if not supported
+ */
+export function checkSupport(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+support, target) {
+    if (!support) {
+        return null;
+    }
+    const stmt = getStandardSupport(support);
+    if (!stmt) {
+        return null;
+    }
+    const { version_added, version_removed } = stmt;
+    if (version_added === false) {
+        return {
+            browser: target.browser,
+            displayName: target.displayName,
+            targetVersion: target.version,
+            addedVersion: false,
+        };
+    }
+    if (!isVersionSatisfied(target.version, version_added)) {
+        return {
+            browser: target.browser,
+            displayName: target.displayName,
+            targetVersion: target.version,
+            addedVersion: version_added,
+        };
+    }
+    // Feature was added but later removed
+    if (version_removed != null && isVersionSatisfied(target.version, version_removed)) {
+        return {
+            browser: target.browser,
+            displayName: target.displayName,
+            targetVersion: target.version,
+            addedVersion: false,
+            removedVersion: version_removed,
+        };
+    }
+    return null;
+}
+/**
+ * Look up the BCD identifier for an HTML element.
+ */
+async function getElementIdentifier(elementName) {
+    const bcd = await loadBcd();
+    const elements = bcd.html.elements;
+    if (!elements) {
+        return null;
+    }
+    const el = elements[elementName];
+    return el ?? null;
+}
+/**
+ * Check browser support for an HTML element.
+ *
+ * @param elementName - The HTML element name (e.g., "dialog")
+ * @param targets - Array of target browsers to check
+ * @returns Array of unsupported results (empty if all supported)
+ */
+export async function checkElementSupport(elementName, targets) {
+    const identifier = await getElementIdentifier(elementName);
+    if (!identifier?.__compat) {
+        return [];
+    }
+    const results = [];
+    for (const target of targets) {
+        const support = identifier.__compat.support[target.browser];
+        const result = checkSupport(support, target);
+        if (result) {
+            results.push(result);
+        }
+    }
+    return results;
+}
+/**
+ * Check browser support for an HTML attribute on a specific element.
+ *
+ * @param elementName - The HTML element name (e.g., "input")
+ * @param attrName - The attribute name (e.g., "list")
+ * @param targets - Array of target browsers to check
+ * @returns Array of unsupported results (empty if all supported)
+ */
+export async function checkAttributeSupport(elementName, attrName, targets) {
+    const identifier = await getElementIdentifier(elementName);
+    if (!identifier) {
+        return [];
+    }
+    const attrIdentifier = identifier[attrName];
+    if (!attrIdentifier?.__compat) {
+        return [];
+    }
+    const results = [];
+    for (const target of targets) {
+        const support = attrIdentifier.__compat.support[target.browser];
+        const result = checkSupport(support, target);
+        if (result) {
+            results.push(result);
+        }
+    }
+    return results;
+}

package/lib/no-unsupported-features/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Options for the `no-unsupported-features` rule.
+ */
+type Options = {
+    /** A browserslist query to override project configuration. */
+    readonly browserslist?: string | readonly string[];
+    /** Explicit path to a browserslist configuration file. */
+    readonly browserslistConfig?: string;
+    /** Browserslist environment name (e.g., "production"). */
+    readonly browserslistEnv?: string;
+    /** Features to ignore. Element name ("dialog") or attribute pattern ("input[list]"). */
+    readonly ignoreFeatures?: readonly string[];
+    /** Whether to warn about experimental elements and attributes. */
+    readonly checkExperimental?: boolean;
+    /** Whether to warn about non-standard elements and attributes. */
+    readonly checkNonStandard?: boolean;
+};
+/**
+ * Rule that warns when using HTML elements or attributes that are not
+ * supported by the project's target browsers (via browserslist),
+ * or that are experimental/non-standard.
+ */
+declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, Options>>;
+export default _default;

package/lib/no-unsupported-features/index.js

@@ -0,0 +1,139 @@
+import { createRule, getAttrSpecs, getSpec } from '@markuplint/ml-core';
+import { checkAttributeSupport, checkElementSupport } from './compat-data.js';
+import meta from './meta.js';
+import { clearBrowserslistCache, resolveTargetBrowsers } from './resolve-browsers.js';
+/**
+ * Rule that warns when using HTML elements or attributes that are not
+ * supported by the project's target browsers (via browserslist),
+ * or that are experimental/non-standard.
+ */
+export default createRule({
+    meta: meta,
+    defaultSeverity: 'warning',
+    defaultOptions: {
+        checkExperimental: false,
+        checkNonStandard: false,
+    },
+    async verify({ document, report, t }) {
+        const options = document.rule.options;
+        const targetBrowsers = resolveTargetBrowsers(document.filename, {
+            browserslist: options.browserslist,
+            browserslistConfig: options.browserslistConfig,
+            browserslistEnv: options.browserslistEnv,
+        });
+        const hasTargetBrowsers = targetBrowsers != null && targetBrowsers.length > 0;
+        const checkExperimental = options.checkExperimental ?? false;
+        const checkNonStandard = options.checkNonStandard ?? false;
+        // If no browserslist config and no experimental/nonStandard check, rule is no-op
+        if (!hasTargetBrowsers && !checkExperimental && !checkNonStandard) {
+            return;
+        }
+        const ignoreFeatures = new Set(options.ignoreFeatures);
+        await document.walkOn('Element', async (el) => {
+            // Only check HTML elements
+            if (el.namespaceURI !== 'http://www.w3.org/1999/xhtml' || el.elementType !== 'html') {
+                return;
+            }
+            const elName = el.localName;
+            const elOptions = el.rule.options;
+            const elIgnoreFeatures = new Set(elOptions.ignoreFeatures ?? ignoreFeatures);
+            // Check element itself
+            if (!elIgnoreFeatures.has(elName)) {
+                // Experimental check (spec-based, no BCD needed)
+                if (elOptions.checkExperimental ?? checkExperimental) {
+                    const spec = getSpec(el, document.specs.specs);
+                    if (spec?.experimental) {
+                        report({
+                            scope: el,
+                            message: t('{0} is {1:c}', t('the "{0*}" {1}', elName, 'element'), 'experimental'),
+                        });
+                    }
+                }
+                // NonStandard check (spec-based, no BCD needed)
+                if (elOptions.checkNonStandard ?? checkNonStandard) {
+                    const spec = getSpec(el, document.specs.specs);
+                    if (spec?.nonStandard) {
+                        report({
+                            scope: el,
+                            message: t('{0} is {1:c}', t('the "{0*}" {1}', elName, 'element'), 'non-standard'),
+                        });
+                    }
+                }
+                // Browser support check (BCD-based)
+                if (hasTargetBrowsers) {
+                    const unsupported = await checkElementSupport(elName, targetBrowsers);
+                    if (unsupported.length > 0) {
+                        report({
+                            scope: el,
+                            message: formatUnsupportedMessage(t, elName, 'element', unsupported),
+                        });
+                    }
+                }
+            }
+            // Check attributes
+            const attrSpecs = getAttrSpecs(el, document.specs);
+            for (const attr of el.attributes) {
+                if (attr.isDirective) {
+                    continue;
+                }
+                const attrName = attr.name;
+                const ignoreKey = `${elName}[${attrName}]`;
+                if (elIgnoreFeatures.has(ignoreKey)) {
+                    continue;
+                }
+                const attrSpec = attrSpecs?.find(s => s.name === attrName);
+                // Experimental attribute check
+                if ((elOptions.checkExperimental ?? checkExperimental) && attrSpec?.experimental) {
+                    report({
+                        scope: attr,
+                        line: attr.nameNode?.startLine,
+                        col: attr.nameNode?.startCol,
+                        raw: attr.nameNode?.raw,
+                        message: t('{0} is {1:c}', t('the "{0*}" {1}', attrName, 'attribute'), 'experimental'),
+                    });
+                }
+                // NonStandard attribute check
+                if ((elOptions.checkNonStandard ?? checkNonStandard) && attrSpec?.nonStandard) {
+                    report({
+                        scope: attr,
+                        line: attr.nameNode?.startLine,
+                        col: attr.nameNode?.startCol,
+                        raw: attr.nameNode?.raw,
+                        message: t('{0} is {1:c}', t('the "{0*}" {1}', attrName, 'attribute'), 'non-standard'),
+                    });
+                }
+                // Browser support attribute check
+                if (hasTargetBrowsers) {
+                    const unsupported = await checkAttributeSupport(elName, attrName, targetBrowsers);
+                    if (unsupported.length > 0) {
+                        report({
+                            scope: attr,
+                            line: attr.nameNode?.startLine,
+                            col: attr.nameNode?.startCol,
+                            raw: attr.nameNode?.raw,
+                            message: formatUnsupportedMessage(t, attrName, 'attribute', unsupported),
+                        });
+                    }
+                }
+            }
+        });
+        clearBrowserslistCache();
+    },
+});
+/**
+ * Format an unsupported feature message listing affected browsers.
+ */
+function formatUnsupportedMessage(t, featureName, featureType, unsupported) {
+    const browserDetails = unsupported
+        .map(u => {
+        if (u.addedVersion === false) {
+            if (u.removedVersion) {
+                return `${u.displayName} (removed in ${u.removedVersion})`;
+            }
+            return `${u.displayName} (not supported)`;
+        }
+        return `${u.displayName} (added in ${u.addedVersion}, target: ${u.targetVersion})`;
+    })
+        .join(', ');
+    return t('{0} is not supported in {1}', t('the "{0*}" {1}', featureName, featureType), browserDetails);
+}

package/lib/no-unsupported-features/meta.d.ts

@@ -0,0 +1,5 @@
+/** Rule metadata for `no-unsupported-features`: categorized as a validation rule. */
+declare const _default: {
+    readonly category: "validation";
+};
+export default _default;

package/lib/no-unsupported-features/meta.js

@@ -0,0 +1,4 @@
+/** Rule metadata for `no-unsupported-features`: categorized as a validation rule. */
+export default {
+    category: 'validation',
+};

package/lib/no-unsupported-features/resolve-browsers.d.ts

@@ -0,0 +1,30 @@
+import type { TargetBrowser } from './compat-data.js';
+/**
+ * Options for resolving target browsers.
+ */
+export interface BrowserslistOptions {
+    readonly browserslist?: string | readonly string[];
+    readonly browserslistConfig?: string;
+    readonly browserslistEnv?: string;
+}
+/**
+ * Resolve target browsers from browserslist configuration.
+ *
+ * Priority:
+ * 1. `options.browserslist` (explicit query)
+ * 2. `options.browserslistConfig` (explicit config file path)
+ * 3. Auto-detect from `filename` path
+ *
+ * When no configuration is found, returns null (rule becomes no-op).
+ * For duplicate browsers, the minimum version is kept.
+ *
+ * @param filename - The document filename for auto-detection
+ * @param options - Browserslist resolution options
+ * @returns Array of target browsers, or null if no config found
+ */
+export declare function resolveTargetBrowsers(filename: string | undefined, options: BrowserslistOptions): readonly TargetBrowser[] | null;
+/**
+ * Clear the internal browserslist config cache.
+ * Useful for testing.
+ */
+export declare function clearBrowserslistCache(): void;

package/lib/no-unsupported-features/resolve-browsers.js

@@ -0,0 +1,125 @@
+import browserslist from 'browserslist';
+import { isVersionSatisfied, parseVersion, toBcdBrowserId } from './compat-data.js';
+/**
+ * Display names for BCD browser identifiers.
+ */
+const BROWSER_DISPLAY_NAMES = new Map([
+    ['chrome', 'Chrome'],
+    ['chrome_android', 'Chrome Android'],
+    ['edge', 'Edge'],
+    ['firefox', 'Firefox'],
+    ['firefox_android', 'Firefox Android'],
+    ['ie', 'Internet Explorer'],
+    ['opera', 'Opera'],
+    ['opera_android', 'Opera Android'],
+    ['safari', 'Safari'],
+    ['safari_ios', 'Safari iOS'],
+    ['samsunginternet_android', 'Samsung Internet'],
+    ['webview_android', 'WebView Android'],
+]);
+const configCache = new Map();
+/**
+ * Resolve target browsers from browserslist configuration.
+ *
+ * Priority:
+ * 1. `options.browserslist` (explicit query)
+ * 2. `options.browserslistConfig` (explicit config file path)
+ * 3. Auto-detect from `filename` path
+ *
+ * When no configuration is found, returns null (rule becomes no-op).
+ * For duplicate browsers, the minimum version is kept.
+ *
+ * @param filename - The document filename for auto-detection
+ * @param options - Browserslist resolution options
+ * @returns Array of target browsers, or null if no config found
+ */
+export function resolveTargetBrowsers(filename, options) {
+    if (options.browserslist != null) {
+        const queries = Array.isArray(options.browserslist) ? options.browserslist : [options.browserslist];
+        const cacheKey = `query:${queries.join(',')}`;
+        if (configCache.has(cacheKey)) {
+            return configCache.get(cacheKey) ?? null;
+        }
+        const result = parseBrowsersList(browserslist(queries));
+        configCache.set(cacheKey, result);
+        return result;
+    }
+    const configPath = options.browserslistConfig ?? filename;
+    if (!configPath) {
+        return null;
+    }
+    const env = options.browserslistEnv;
+    const cacheKey = `path:${configPath}:${env ?? ''}`;
+    if (configCache.has(cacheKey)) {
+        return configCache.get(cacheKey) ?? null;
+    }
+    const config = browserslist.loadConfig({
+        path: configPath,
+        env,
+        ...(options.browserslistConfig ? { config: options.browserslistConfig } : {}),
+    });
+    if (!config) {
+        configCache.set(cacheKey, null);
+        return null;
+    }
+    const result = parseBrowsersList(browserslist(config));
+    configCache.set(cacheKey, result);
+    return result;
+}
+/**
+ * Parse browserslist output into TargetBrowser array.
+ *
+ * For duplicate browsers, keeps the minimum version to ensure
+ * compatibility with the widest range of target browsers.
+ */
+function parseBrowsersList(browsers) {
+    const browserMap = new Map();
+    for (const entry of browsers) {
+        const parts = entry.split(' ');
+        if (parts.length < 2) {
+            continue;
+        }
+        const [name, rawVersion] = parts;
+        if (!name || !rawVersion) {
+            continue;
+        }
+        // Handle hyphenated version ranges (e.g., "16.3-16.4") by taking the minimum
+        const version = rawVersion.includes('-') ? rawVersion.split('-')[0] : rawVersion;
+        const bcdId = toBcdBrowserId(name);
+        if (!bcdId) {
+            continue;
+        }
+        const existing = browserMap.get(bcdId);
+        const displayName = BROWSER_DISPLAY_NAMES.get(bcdId) ?? name;
+        if (existing) {
+            // Keep minimum version — treat "preview" (NaN) as the highest possible version
+            const [newMajor] = parseVersion(version);
+            if (!Number.isNaN(newMajor)) {
+                // New version is concrete — replace if existing is "preview" or new < existing
+                const [existingMajor] = parseVersion(existing.version);
+                if (Number.isNaN(existingMajor) || !isVersionSatisfied(version, existing.version)) {
+                    browserMap.set(bcdId, { version, displayName });
+                }
+            }
+            // If new version is "preview", never replace (preview is the highest)
+        }
+        else {
+            browserMap.set(bcdId, { version, displayName });
+        }
+    }
+    if (browserMap.size === 0) {
+        return null;
+    }
+    const result = [];
+    for (const [browser, { version, displayName }] of browserMap) {
+        result.push({ browser, version, displayName });
+    }
+    return result;
+}
+/**
+ * Clear the internal browserslist config cache.
+ * Useful for testing.
+ */
+export function clearBrowserslistCache() {
+    configCache.clear();
+}

package/lib/no-use-event-handler-attr/index.d.ts

@@ -1,5 +1,15 @@
+/** Configuration options for the `no-use-event-handler-attr` rule. */
 type Options = {
+    /** Attribute name pattern(s) to exclude from the check. */
     ignore?: string | string[];
 };
+/**
+ * Rule that disallows inline event handler attributes (e.g., `onclick`,
+ * `onchange`).
+ *
+ * Reports any attribute on an HTML element whose name starts with `on`,
+ * indicating an inline event handler. An `ignore` option allows specific
+ * attribute names or patterns to be excluded from the check.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, Options>>;
 export default _default;

package/lib/no-use-event-handler-attr/index.js

@@ -1,6 +1,14 @@
 import { createRule } from '@markuplint/ml-core';
 import { match } from '../helpers.js';
 import meta from './meta.js';
+/**
+ * Rule that disallows inline event handler attributes (e.g., `onclick`,
+ * `onchange`).
+ *
+ * Reports any attribute on an HTML element whose name starts with `on`,
+ * indicating an inline event handler. An `ignore` option allows specific
+ * attribute names or patterns to be excluded from the check.
+ */
 export default createRule({
     meta: meta,
     defaultSeverity: 'warning',

package/lib/no-use-event-handler-attr/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for `no-use-event-handler-attr`: categorized as a maintainability rule. */
 declare const _default: {
     readonly category: "maintainability";
 };

package/lib/no-use-event-handler-attr/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for `no-use-event-handler-attr`: categorized as a maintainability rule. */
 export default {
     category: 'maintainability',
 };

package/lib/permitted-contents/choice.d.ts

@@ -1,4 +1,21 @@
 import type { ChildNode, Options, Result, Specs } from './types.js';
 import type { PermittedContentChoice } from '@markuplint/ml-spec';
 import type { ReadonlyDeep } from 'type-fest';
+/**
+ * Evaluates a choice (alternation) pattern against a list of child nodes.
+ * Tries each branch of the choice in order and returns the first successful match.
+ * If no branch fully matches, selects the "barely matched" result that consumed
+ * the most nodes, preferring `UNEXPECTED_EXTRA_NODE` results (which indicate
+ * partial progress) over missing-node results.
+ *
+ * This implements the alternation (`|`) semantics found in content model definitions,
+ * e.g., "either flow content or phrasing content".
+ *
+ * @param pattern - The choice pattern containing multiple alternative content model branches.
+ * @param childNodes - The child nodes to validate against the choice branches.
+ * @param specs - The resolved spec data for content model lookups.
+ * @param options - Validation behavior options.
+ * @param depth - The current recursion depth, used for debug logging and nested evaluation.
+ * @returns A result from the best-matching branch, or the branch that came closest to matching.
+ */
 export declare function choice(pattern: ReadonlyDeep<PermittedContentChoice>, childNodes: readonly ChildNode[], specs: Specs, options: Options, depth: number): Result;

package/lib/permitted-contents/choice.js

@@ -1,7 +1,28 @@
 import { bgBlue, bgGreen, cmLog } from './debug.js';
 import { order } from './order.js';
 import { Collection, modelLog } from './utils.js';
+/**
+ * WeakMap that tracks which choice branch index produced each result,
+ * used for debug logging to identify the best-matching branch.
+ */
 const indexes = new WeakMap();
+/**
+ * Evaluates a choice (alternation) pattern against a list of child nodes.
+ * Tries each branch of the choice in order and returns the first successful match.
+ * If no branch fully matches, selects the "barely matched" result that consumed
+ * the most nodes, preferring `UNEXPECTED_EXTRA_NODE` results (which indicate
+ * partial progress) over missing-node results.
+ *
+ * This implements the alternation (`|`) semantics found in content model definitions,
+ * e.g., "either flow content or phrasing content".
+ *
+ * @param pattern - The choice pattern containing multiple alternative content model branches.
+ * @param childNodes - The child nodes to validate against the choice branches.
+ * @param specs - The resolved spec data for content model lookups.
+ * @param options - Validation behavior options.
+ * @param depth - The current recursion depth, used for debug logging and nested evaluation.
+ * @returns A result from the best-matching branch, or the branch that came closest to matching.
+ */
 export function choice(pattern, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 childNodes, specs, options, depth) {
@@ -30,7 +51,7 @@ childNodes, specs, options, depth) {
         indexes.set(result, i);
         i++;
     }
-    const barelyMatchedResult = unmatchedResults.sort((a, b) => {
+    const barelyMatchedResult = unmatchedResults.toSorted((a, b) => {
         if (a.type !== b.type) {
             if (a.type === 'UNEXPECTED_EXTRA_NODE') {
                 return -1;
@@ -64,6 +85,15 @@ childNodes, specs, options, depth) {
         hint: barelyMatchedResult.hint,
     };
 }
+/**
+ * Formats a debug log string for a choice pattern, highlighting the selected
+ * branch index with a color (green for a full match, blue for a barely-matched fallback).
+ *
+ * @param choice - The array of choice branches from the pattern.
+ * @param index - The index of the selected branch.
+ * @param barely - Whether this is a barely-matched fallback (uses blue) or a full match (uses green).
+ * @returns A formatted string showing all branches with the selected one highlighted.
+ */
 function choiceLogString(choice, index, barely = false) {
     const colorFn = barely ? bgBlue : bgGreen;
     return choice