@cssdoc/config 0.2.0 → 0.3.0

package/cssdoc.schema.json

@@ -6,11 +6,15 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "$schema": { "type": "string" },
+    "$schema": {
+      "type": "string"
+    },
     "extends": {
       "description": "Paths to other cssdoc.json files (or packages) to inherit tag definitions from.",
       "type": "array",
-      "items": { "type": "string" }
+      "items": {
+        "type": "string"
+      }
     },
     "noStandardTags": {
       "description": "Disable every built-in standard tag; only tagDefinitions remain supported.",
@@ -24,32 +28,93 @@
         "additionalProperties": false,
         "required": ["tagName", "syntaxKind"],
         "properties": {
-          "tagName": { "type": "string", "pattern": "^@?[a-zA-Z][a-zA-Z0-9-]*$" },
-          "syntaxKind": { "enum": ["record", "block", "modifier", "inline"] },
-          "allowMultiple": { "type": "boolean" },
-          "recordKind": { "enum": ["component", "utility", "rule", "declaration"] },
-          "aliasFor": { "type": "string" }
+          "tagName": {
+            "type": "string",
+            "pattern": "^@?[a-zA-Z][a-zA-Z0-9-]*$"
+          },
+          "syntaxKind": {
+            "enum": ["record", "block", "modifier", "inline"]
+          },
+          "allowMultiple": {
+            "type": "boolean"
+          },
+          "recordKind": {
+            "enum": ["component", "utility", "rule", "declaration"]
+          },
+          "aliasFor": {
+            "type": "string"
+          }
         }
       }
     },
     "supportForTags": {
       "description": "Enable or disable specific tags by name.",
       "type": "object",
-      "additionalProperties": { "type": "boolean" }
+      "additionalProperties": {
+        "type": "boolean"
+      }
     },
     "modifierConvention": {
       "description": "How modifier classes are spelled: a preset name (bem, rscss, bare) or a custom convention.",
       "oneOf": [
-        { "enum": ["bem", "rscss", "bare"] },
+        {
+          "enum": ["bem", "rscss", "bare"]
+        },
         {
           "type": "object",
           "additionalProperties": false,
           "required": ["structure", "separator"],
           "properties": {
-            "structure": { "enum": ["chained", "suffix", "attribute"] },
-            "separator": { "type": "string" },
-            "propValue": { "type": "boolean" },
-            "propValueSeparator": { "type": "string" }
+            "structure": {
+              "enum": ["chained", "suffix", "attribute"]
+            },
+            "separator": {
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              ]
+            },
+            "elementSeparator": {
+              "description": "BEM-style element delimiter (e.g. \"__\"); matched classes become parts.",
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              ]
+            },
+            "statePrefixes": {
+              "description": "Class prefixes that mark a state (e.g. [\"is-\",\"has-\"]).",
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "statePseudoClasses": {
+              "description": "Native pseudo-classes (without the colon) recognized as states, e.g. [\"disabled\",\"checked\"]. Overrides the built-in default set.",
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "propValue": {
+              "type": "boolean"
+            },
+            "propValueSeparator": {
+              "type": "string"
+            }
           }
         }
       ]
@@ -57,7 +122,29 @@
     "rules": {
       "description": "Per-rule severity overrides (off/warn/error).",
       "type": "object",
-      "additionalProperties": { "enum": ["off", "warn", "error"] }
+      "additionalProperties": {
+        "enum": ["off", "warn", "error"]
+      }
+    },
+    "naming": {
+      "description": "Enforce a name case on class names: a preset (pascalCase, camelCase, lowercase) or a custom regex.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "component": {
+          "type": "string"
+        },
+        "part": {
+          "type": "string"
+        }
+      }
+    },
+    "structureIgnore": {
+      "description": "Class names to exempt from the structure-unknown-selector rule — legitimately-external classes (utilities, cross-component refs) referenced in @structure. Literal names or simple globs where * matches any run of characters (e.g. util-*).",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
     }
   }
 }

package/dist/index.d.mts

@@ -3,8 +3,18 @@ import { CssDocConfiguration, CssDocTagDefinition, ModifierConventionInput } fro
 //#region src/CssDocConfigFile.d.ts
 /** A per-rule severity override, as spelled in `cssdoc.json`. */
 type RuleSeverityOverride = "off" | "warn" | "error";
-/** The conventional file name loaders look for. */
-declare const CSSDOC_CONFIG_FILENAME = "cssdoc.json";
+/** The `naming` block: a name case (preset or custom regex) per class kind, as spelled in `cssdoc.json`. */
+interface NamingOverride {
+  component?: string;
+  part?: string;
+}
+/**
+ * The conventional file names loaders look for, in preference order. Both are parsed the same way
+ * (JSON with comments); `.jsonc` just makes the comments explicit.
+ */
+declare const CSSDOC_CONFIG_FILENAMES: readonly ["cssdoc.json", "cssdoc.jsonc"];
+/** The primary config file name (`cssdoc.json`). See {@link CSSDOC_CONFIG_FILENAMES} for all names. */
+declare const CSSDOC_CONFIG_FILENAME: "cssdoc.json";
 /** A loaded `cssdoc.json` (plus the files it `extends`), ready to configure a parser. */
 declare class CssDocConfigFile {
   /** The absolute path the file was loaded from (or would be, when not found). */
@@ -28,6 +38,16 @@ declare class CssDocConfigFile {
    * resolved severities — pass these to `resolveRuleSeverities` in `@cssdoc/providers`.
    */
   readonly ruleSeverities: Readonly<Record<string, RuleSeverityOverride>>;
+  /**
+   * The name-case conventions, merged across the `extends` chain (this file wins). Pass to
+   * `resolveNaming` in `@cssdoc/providers`.
+   */
+  readonly naming: Readonly<NamingOverride>;
+  /**
+   * Class names exempt from the `structure-unknown-selector` rule, merged (union) across the `extends`
+   * chain. Pass to `lintModel` in `@cssdoc/providers`.
+   */
+  readonly structureIgnore: readonly string[];
   private constructor();
   /** Whether this file — or any file it extends — reported an error. */
   get hasErrors(): boolean;
@@ -142,7 +162,39 @@ declare const cssDocSchema: {
             readonly enum: readonly ["chained", "suffix", "attribute"];
           };
           readonly separator: {
-            readonly type: "string";
+            readonly oneOf: readonly [{
+              readonly type: "string";
+            }, {
+              readonly type: "array";
+              readonly items: {
+                readonly type: "string";
+              };
+            }];
+          };
+          readonly elementSeparator: {
+            readonly description: "BEM-style element delimiter (e.g. \"__\"); matched classes become parts.";
+            readonly oneOf: readonly [{
+              readonly type: "string";
+            }, {
+              readonly type: "array";
+              readonly items: {
+                readonly type: "string";
+              };
+            }];
+          };
+          readonly statePrefixes: {
+            readonly description: "Class prefixes that mark a state (e.g. [\"is-\",\"has-\"]).";
+            readonly type: "array";
+            readonly items: {
+              readonly type: "string";
+            };
+          };
+          readonly statePseudoClasses: {
+            readonly description: "Native pseudo-classes (without the colon) recognized as states, e.g. [\"disabled\",\"checked\"]. Overrides the built-in default set.";
+            readonly type: "array";
+            readonly items: {
+              readonly type: "string";
+            };
           };
           readonly propValue: {
             readonly type: "boolean";
@@ -160,7 +212,27 @@ declare const cssDocSchema: {
         readonly enum: readonly ["off", "warn", "error"];
       };
     };
+    readonly naming: {
+      readonly description: "Enforce a name case on class names: a preset (pascalCase, camelCase, lowercase) or a custom regex.";
+      readonly type: "object";
+      readonly additionalProperties: false;
+      readonly properties: {
+        readonly component: {
+          readonly type: "string";
+        };
+        readonly part: {
+          readonly type: "string";
+        };
+      };
+    };
+    readonly structureIgnore: {
+      readonly description: "Class names to exempt from the structure-unknown-selector rule — legitimately-external classes (utilities, cross-component refs) referenced in @structure. Literal names or simple globs where * matches any run of characters (e.g. util-*).";
+      readonly type: "array";
+      readonly items: {
+        readonly type: "string";
+      };
+    };
   };
 };
 //#endregion
-export { CSSDOC_CONFIG_FILENAME, CssDocConfigFile, cssDocSchema };
+export { CSSDOC_CONFIG_FILENAME, CSSDOC_CONFIG_FILENAMES, CssDocConfigFile, cssDocSchema };

package/dist/index.mjs

@@ -2,6 +2,7 @@ import { createRequire } from "node:module";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, parse, resolve } from "node:path";
 import { Ajv } from "ajv";
+import { parse as parse$1, printParseErrorCode } from "jsonc-parser";
 import { CssDocConfiguration, CssDocTagDefinition } from "@cssdoc/core";
 //#region src/schema.ts
 /**
@@ -80,7 +81,27 @@ const cssDocSchema = {
 						"suffix",
 						"attribute"
 					] },
-					separator: { type: "string" },
+					separator: { oneOf: [{ type: "string" }, {
+						type: "array",
+						items: { type: "string" }
+					}] },
+					elementSeparator: {
+						description: "BEM-style element delimiter (e.g. \"__\"); matched classes become parts.",
+						oneOf: [{ type: "string" }, {
+							type: "array",
+							items: { type: "string" }
+						}]
+					},
+					statePrefixes: {
+						description: "Class prefixes that mark a state (e.g. [\"is-\",\"has-\"]).",
+						type: "array",
+						items: { type: "string" }
+					},
+					statePseudoClasses: {
+						description: "Native pseudo-classes (without the colon) recognized as states, e.g. [\"disabled\",\"checked\"]. Overrides the built-in default set.",
+						type: "array",
+						items: { type: "string" }
+					},
 					propValue: { type: "boolean" },
 					propValueSeparator: { type: "string" }
 				}
@@ -94,6 +115,20 @@ const cssDocSchema = {
 				"warn",
 				"error"
 			] }
+		},
+		naming: {
+			description: "Enforce a name case on class names: a preset (pascalCase, camelCase, lowercase) or a custom regex.",
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				component: { type: "string" },
+				part: { type: "string" }
+			}
+		},
+		structureIgnore: {
+			description: "Class names to exempt from the structure-unknown-selector rule — legitimately-external classes (utilities, cross-component refs) referenced in @structure. Literal names or simple globs where * matches any run of characters (e.g. util-*).",
+			type: "array",
+			items: { type: "string" }
 		}
 	}
 };
@@ -109,8 +144,13 @@ const cssDocSchema = {
 * @module
 */
 const validateSchema = new Ajv({ allErrors: true }).compile(cssDocSchema);
-/** The conventional file name loaders look for. */
-const CSSDOC_CONFIG_FILENAME = "cssdoc.json";
+/**
+* The conventional file names loaders look for, in preference order. Both are parsed the same way
+* (JSON with comments); `.jsonc` just makes the comments explicit.
+*/
+const CSSDOC_CONFIG_FILENAMES = ["cssdoc.json", "cssdoc.jsonc"];
+/** The primary config file name (`cssdoc.json`). See {@link CSSDOC_CONFIG_FILENAMES} for all names. */
+const CSSDOC_CONFIG_FILENAME = CSSDOC_CONFIG_FILENAMES[0];
 /** A loaded `cssdoc.json` (plus the files it `extends`), ready to configure a parser. */
 var CssDocConfigFile = class CssDocConfigFile {
 	/** The absolute path the file was loaded from (or would be, when not found). */
@@ -134,6 +174,16 @@ var CssDocConfigFile = class CssDocConfigFile {
 	* resolved severities — pass these to `resolveRuleSeverities` in `@cssdoc/providers`.
 	*/
 	ruleSeverities;
+	/**
+	* The name-case conventions, merged across the `extends` chain (this file wins). Pass to
+	* `resolveNaming` in `@cssdoc/providers`.
+	*/
+	naming;
+	/**
+	* Class names exempt from the `structure-unknown-selector` rule, merged (union) across the `extends`
+	* chain. Pass to `lintModel` in `@cssdoc/providers`.
+	*/
+	structureIgnore;
 	constructor(init) {
 		this.filePath = init.filePath;
 		this.fileNotFound = init.fileNotFound;
@@ -144,9 +194,19 @@ var CssDocConfigFile = class CssDocConfigFile {
 		this.extendsFiles = init.extendsFiles;
 		this.modifierConvention = init.modifierConvention;
 		const severities = {};
-		for (const extended of init.extendsFiles) Object.assign(severities, extended.ruleSeverities);
+		const naming = {};
+		const structureIgnore = /* @__PURE__ */ new Set();
+		for (const extended of init.extendsFiles) {
+			Object.assign(severities, extended.ruleSeverities);
+			Object.assign(naming, extended.naming);
+			for (const g of extended.structureIgnore) structureIgnore.add(g);
+		}
 		Object.assign(severities, init.rules);
+		Object.assign(naming, init.naming);
+		for (const g of init.structureIgnore) structureIgnore.add(g);
 		this.ruleSeverities = severities;
+		this.naming = naming;
+		this.structureIgnore = [...structureIgnore];
 	}
 	/** Whether this file — or any file it extends — reported an error. */
 	get hasErrors() {
@@ -202,8 +262,10 @@ var CssDocConfigFile = class CssDocConfigFile {
 		let current = resolve(folderPath);
 		const root = parse(current).root;
 		for (;;) {
-			const candidate = resolve(current, CSSDOC_CONFIG_FILENAME);
-			if (existsSync(candidate)) return CssDocConfigFile._loadFile(candidate, /* @__PURE__ */ new Set());
+			for (const name of CSSDOC_CONFIG_FILENAMES) {
+				const candidate = resolve(current, name);
+				if (existsSync(candidate)) return CssDocConfigFile._loadFile(candidate, /* @__PURE__ */ new Set());
+			}
 			if (current === root) break;
 			current = dirname(current);
 		}
@@ -215,7 +277,9 @@ var CssDocConfigFile = class CssDocConfigFile {
 			tagDefinitions: [],
 			supportForTags: /* @__PURE__ */ new Map(),
 			extendsFiles: [],
-			rules: {}
+			rules: {},
+			naming: {},
+			structureIgnore: []
 		});
 	}
 	static _loadFile(filePath, visited) {
@@ -228,7 +292,9 @@ var CssDocConfigFile = class CssDocConfigFile {
 			tagDefinitions: [],
 			supportForTags: /* @__PURE__ */ new Map(),
 			extendsFiles: [],
-			rules: {}
+			rules: {},
+			naming: {},
+			structureIgnore: []
 		});
 		if (visited.has(filePath)) {
 			messages.push("Circular extends reference; skipped.");
@@ -236,11 +302,11 @@ var CssDocConfigFile = class CssDocConfigFile {
 		}
 		visited.add(filePath);
 		if (!existsSync(filePath)) return empty(true);
-		let raw;
-		try {
-			raw = JSON.parse(readFileSync(filePath, "utf8"));
-		} catch (error) {
-			messages.push(`Invalid JSON: ${error.message}`);
+		const parseErrors = [];
+		const raw = parse$1(readFileSync(filePath, "utf8"), parseErrors, { allowTrailingComma: true });
+		if (parseErrors.length > 0 || raw === void 0) {
+			for (const err of parseErrors) messages.push(`Invalid JSON at offset ${err.offset}: ${printParseErrorCode(err.error)}`);
+			if (parseErrors.length === 0) messages.push("Invalid JSON: empty or unparseable config.");
 			return empty(false);
 		}
 		if (!validateSchema(raw)) {
@@ -274,9 +340,11 @@ var CssDocConfigFile = class CssDocConfigFile {
 			supportForTags: new Map(Object.entries(raw.supportForTags ?? {})),
 			extendsFiles,
 			modifierConvention: raw.modifierConvention,
-			rules: raw.rules ?? {}
+			rules: raw.rules ?? {},
+			naming: raw.naming ?? {},
+			structureIgnore: raw.structureIgnore ?? []
 		});
 	}
 };
 //#endregion
-export { CSSDOC_CONFIG_FILENAME, CssDocConfigFile, cssDocSchema };
+export { CSSDOC_CONFIG_FILENAME, CSSDOC_CONFIG_FILENAMES, CssDocConfigFile, cssDocSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cssdoc/config",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Load a cssdoc.json configuration file (custom tags, extends) into an @cssdoc/core CssDocConfiguration — TSDoc-config, for CSS.",
   "keywords": [
     "config",
@@ -31,7 +31,8 @@
   },
   "dependencies": {
     "ajv": "^8.20.0",
-    "@cssdoc/core": "0.2.0"
+    "jsonc-parser": "^3.3.1",
+    "@cssdoc/core": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",