@cssdoc/config 0.1.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,18 +28,123 @@
         "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"]
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["structure", "separator"],
+          "properties": {
+            "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"
+            }
+          }
+        }
+      ]
+    },
+    "rules": {
+      "description": "Per-rule severity overrides (off/warn/error).",
+      "type": "object",
+      "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

@@ -1,8 +1,20 @@
-import { CssDocConfiguration, CssDocTagDefinition } from "@cssdoc/core";
+import { CssDocConfiguration, CssDocTagDefinition, ModifierConventionInput } from "@cssdoc/core";
 
 //#region src/CssDocConfigFile.d.ts
-/** The conventional file name loaders look for. */
-declare const CSSDOC_CONFIG_FILENAME = "cssdoc.json";
+/** A per-rule severity override, as spelled in `cssdoc.json`. */
+type RuleSeverityOverride = "off" | "warn" | "error";
+/** 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). */
@@ -19,6 +31,23 @@ declare class CssDocConfigFile {
   readonly supportForTags: ReadonlyMap<string, boolean>;
   /** The resolved files this one `extends`, in declaration order. */
   readonly extendsFiles: readonly CssDocConfigFile[];
+  /** The modifier convention declared by this file, if any. */
+  readonly modifierConvention?: ModifierConventionInput;
+  /**
+   * The per-rule severity overrides, merged across the `extends` chain (this file wins). Not the
+   * 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;
@@ -120,7 +149,90 @@ declare const cssDocSchema: {
         readonly type: "boolean";
       };
     };
+    readonly modifierConvention: {
+      readonly description: "How modifier classes are spelled: a preset name (bem, rscss, bare) or a custom convention.";
+      readonly oneOf: readonly [{
+        readonly enum: readonly ["bem", "rscss", "bare"];
+      }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["structure", "separator"];
+        readonly properties: {
+          readonly structure: {
+            readonly enum: readonly ["chained", "suffix", "attribute"];
+          };
+          readonly separator: {
+            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";
+          };
+          readonly propValueSeparator: {
+            readonly type: "string";
+          };
+        };
+      }];
+    };
+    readonly rules: {
+      readonly description: "Per-rule severity overrides (off/warn/error).";
+      readonly type: "object";
+      readonly additionalProperties: {
+        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
 /**
@@ -63,6 +64,71 @@ const cssDocSchema = {
 			description: "Enable or disable specific tags by name.",
 			type: "object",
 			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"
+			] }, {
+				type: "object",
+				additionalProperties: false,
+				required: ["structure", "separator"],
+				properties: {
+					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" }
+				}
+			}]
+		},
+		rules: {
+			description: "Per-rule severity overrides (off/warn/error).",
+			type: "object",
+			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" }
 		}
 	}
 };
@@ -78,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). */
@@ -96,6 +167,23 @@ var CssDocConfigFile = class CssDocConfigFile {
 	supportForTags;
 	/** The resolved files this one `extends`, in declaration order. */
 	extendsFiles;
+	/** The modifier convention declared by this file, if any. */
+	modifierConvention;
+	/**
+	* The per-rule severity overrides, merged across the `extends` chain (this file wins). Not the
+	* 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;
@@ -104,6 +192,21 @@ var CssDocConfigFile = class CssDocConfigFile {
 		this.tagDefinitions = init.tagDefinitions;
 		this.supportForTags = init.supportForTags;
 		this.extendsFiles = init.extendsFiles;
+		this.modifierConvention = init.modifierConvention;
+		const severities = {};
+		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() {
@@ -127,6 +230,7 @@ var CssDocConfigFile = class CssDocConfigFile {
 			const definition = configuration.tryGetTagDefinition(tagName);
 			if (definition) configuration.setSupportForTag(definition, supported);
 		}
+		if (this.modifierConvention !== void 0) configuration.setModifierConvention(this.modifierConvention);
 	}
 	/**
 	* Build a {@link CssDocConfiguration} from this file. Convenience for the common case.
@@ -158,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);
 		}
@@ -170,7 +276,10 @@ var CssDocConfigFile = class CssDocConfigFile {
 			noStandardTags: false,
 			tagDefinitions: [],
 			supportForTags: /* @__PURE__ */ new Map(),
-			extendsFiles: []
+			extendsFiles: [],
+			rules: {},
+			naming: {},
+			structureIgnore: []
 		});
 	}
 	static _loadFile(filePath, visited) {
@@ -182,7 +291,10 @@ var CssDocConfigFile = class CssDocConfigFile {
 			noStandardTags: false,
 			tagDefinitions: [],
 			supportForTags: /* @__PURE__ */ new Map(),
-			extendsFiles: []
+			extendsFiles: [],
+			rules: {},
+			naming: {},
+			structureIgnore: []
 		});
 		if (visited.has(filePath)) {
 			messages.push("Circular extends reference; skipped.");
@@ -190,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)) {
@@ -226,9 +338,13 @@ var CssDocConfigFile = class CssDocConfigFile {
 			noStandardTags: raw.noStandardTags ?? false,
 			tagDefinitions,
 			supportForTags: new Map(Object.entries(raw.supportForTags ?? {})),
-			extendsFiles
+			extendsFiles,
+			modifierConvention: raw.modifierConvention,
+			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.1.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.1.0"
+    "jsonc-parser": "^3.3.1",
+    "@cssdoc/core": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",