@cssdoc/config 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danny Wahl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# @cssdoc/config
+
+Load a `cssdoc.json` file into an [`@cssdoc/core`](../core) `CssDocConfiguration` — TSDoc-config, for
+CSS. Model on `@microsoft/tsdoc-config`: a separate package (it needs Node and ajv) that reads the
+config, validates it against a JSON schema, resolves `extends`, and applies it to a parser.
+
+## Install
+
+```sh
+npm i -D @cssdoc/config @cssdoc/core
+```
+
+## Usage
+
+```ts
+import { CssDocConfigFile } from "@cssdoc/config";
+import { parseCssDocs } from "@cssdoc/core";
+
+const configFile = CssDocConfigFile.loadForFolder(process.cwd());
+if (configFile.hasErrors) console.warn(configFile.getErrorSummary());
+
+const model = parseCssDocs(css, { configuration: configFile.toConfiguration() });
+```
+
+## cssdoc.json
+
+```jsonc
+{
+  "$schema": "https://cssdoc.dev/cssdoc.schema.json",
+  "extends": ["./base.cssdoc.json"],
+  "noStandardTags": false,
+  "tagDefinitions": [
+    { "tagName": "@token", "syntaxKind": "block", "allowMultiple": true },
+    { "tagName": "@pattern", "syntaxKind": "record", "recordKind": "component" },
+  ],
+  "supportForTags": {
+    "@privateRemarks": false,
+  },
+}
+```
+
+| Field            | Meaning                                                                                                                    |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `extends`        | Paths (local `./…` or package specifiers) to other `cssdoc.json` files to inherit from.                                    |
+| `noStandardTags` | Disable every built-in standard tag; only `tagDefinitions` stay supported.                                                 |
+| `tagDefinitions` | Custom tags: `tagName`, `syntaxKind` (`record`/`block`/`modifier`/`inline`), `allowMultiple?`, `recordKind?`, `aliasFor?`. |
+| `supportForTags` | Enable/disable specific tags by name.                                                                                      |
+
+`loadForFolder` walks up from a folder to the nearest `cssdoc.json`. A missing file yields a
+`fileNotFound` instance (not an error); a malformed one collects messages on `getErrorSummary()`
+instead of throwing.
+
+## License
+
+MIT

package/cssdoc.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://cssdoc.dev/cssdoc.schema.json",
+  "title": "cssdoc.json",
+  "description": "Configuration for @cssdoc/core: custom tags and inherited configs.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "extends": {
+      "description": "Paths to other cssdoc.json files (or packages) to inherit tag definitions from.",
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "noStandardTags": {
+      "description": "Disable every built-in standard tag; only tagDefinitions remain supported.",
+      "type": "boolean"
+    },
+    "tagDefinitions": {
+      "description": "Custom tags to register.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "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" }
+        }
+      }
+    },
+    "supportForTags": {
+      "description": "Enable or disable specific tags by name.",
+      "type": "object",
+      "additionalProperties": { "type": "boolean" }
+    }
+  }
+}

package/dist/index.d.mts

@@ -0,0 +1,126 @@
+import { CssDocConfiguration, CssDocTagDefinition } from "@cssdoc/core";
+
+//#region src/CssDocConfigFile.d.ts
+/** The conventional file name loaders look for. */
+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). */
+  readonly filePath: string;
+  /** Whether the file was absent. */
+  readonly fileNotFound: boolean;
+  /** Parse/validation/resolution messages collected while loading (this file only). */
+  readonly messages: readonly string[];
+  /** Whether the file disables the standard tags. */
+  readonly noStandardTags: boolean;
+  /** The custom tag definitions declared by this file. */
+  readonly tagDefinitions: readonly CssDocTagDefinition[];
+  /** Per-tag support overrides declared by this file. */
+  readonly supportForTags: ReadonlyMap<string, boolean>;
+  /** The resolved files this one `extends`, in declaration order. */
+  readonly extendsFiles: readonly CssDocConfigFile[];
+  private constructor();
+  /** Whether this file — or any file it extends — reported an error. */
+  get hasErrors(): boolean;
+  /** A newline-joined summary of every message from this file and its `extends` chain. */
+  getErrorSummary(): string;
+  /**
+   * Apply this file (and its `extends` chain) onto a {@link CssDocConfiguration}. Extended files are
+   * applied first so this file's settings win.
+   *
+   * @param configuration - The configuration to mutate.
+   */
+  configureParser(configuration: CssDocConfiguration): void;
+  /**
+   * Build a {@link CssDocConfiguration} from this file. Convenience for the common case.
+   *
+   * @returns A fresh configuration with this file applied.
+   */
+  toConfiguration(): CssDocConfiguration;
+  /**
+   * Load a `cssdoc.json` from an exact path. Missing files yield a `fileNotFound` instance (not an
+   * error); malformed ones collect messages.
+   *
+   * @param filePath - The config file path (resolved to absolute).
+   * @returns The loaded config file.
+   */
+  static loadFile(filePath: string): CssDocConfigFile;
+  /**
+   * Find and load the nearest `cssdoc.json`, walking upward from `folderPath` to the filesystem root.
+   *
+   * @param folderPath - The folder to start from.
+   * @returns The nearest config file, or a `fileNotFound` instance rooted at `folderPath`.
+   */
+  static loadForFolder(folderPath: string): CssDocConfigFile;
+  private static _loadFile;
+}
+//#endregion
+//#region src/schema.d.ts
+/**
+ * The JSON Schema for a `cssdoc.json` file — the single source of truth used to validate config files
+ * via ajv. A byte-identical copy is shipped at the package root as `cssdoc.schema.json` for editor
+ * `$schema` references.
+ *
+ * @module
+ */
+/** The JSON Schema (draft-07) describing a valid `cssdoc.json`. */
+declare const cssDocSchema: {
+  readonly $schema: "http://json-schema.org/draft-07/schema#";
+  readonly $id: "https://cssdoc.dev/cssdoc.schema.json";
+  readonly title: "cssdoc.json";
+  readonly description: "Configuration for @cssdoc/core: custom tags and inherited configs.";
+  readonly type: "object";
+  readonly additionalProperties: false;
+  readonly properties: {
+    readonly $schema: {
+      readonly type: "string";
+    };
+    readonly extends: {
+      readonly description: "Paths to other cssdoc.json files (or packages) to inherit tag definitions from.";
+      readonly type: "array";
+      readonly items: {
+        readonly type: "string";
+      };
+    };
+    readonly noStandardTags: {
+      readonly description: "Disable every built-in standard tag; only tagDefinitions remain supported.";
+      readonly type: "boolean";
+    };
+    readonly tagDefinitions: {
+      readonly description: "Custom tags to register.";
+      readonly type: "array";
+      readonly items: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["tagName", "syntaxKind"];
+        readonly properties: {
+          readonly tagName: {
+            readonly type: "string";
+            readonly pattern: "^@?[a-zA-Z][a-zA-Z0-9-]*$";
+          };
+          readonly syntaxKind: {
+            readonly enum: readonly ["record", "block", "modifier", "inline"];
+          };
+          readonly allowMultiple: {
+            readonly type: "boolean";
+          };
+          readonly recordKind: {
+            readonly enum: readonly ["component", "utility", "rule", "declaration"];
+          };
+          readonly aliasFor: {
+            readonly type: "string";
+          };
+        };
+      };
+    };
+    readonly supportForTags: {
+      readonly description: "Enable or disable specific tags by name.";
+      readonly type: "object";
+      readonly additionalProperties: {
+        readonly type: "boolean";
+      };
+    };
+  };
+};
+//#endregion
+export { CSSDOC_CONFIG_FILENAME, CssDocConfigFile, cssDocSchema };

package/dist/index.mjs

@@ -0,0 +1,234 @@
+import { createRequire } from "node:module";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, parse, resolve } from "node:path";
+import { Ajv } from "ajv";
+import { CssDocConfiguration, CssDocTagDefinition } from "@cssdoc/core";
+//#region src/schema.ts
+/**
+* The JSON Schema for a `cssdoc.json` file — the single source of truth used to validate config files
+* via ajv. A byte-identical copy is shipped at the package root as `cssdoc.schema.json` for editor
+* `$schema` references.
+*
+* @module
+*/
+/** The JSON Schema (draft-07) describing a valid `cssdoc.json`. */
+const cssDocSchema = {
+	$schema: "http://json-schema.org/draft-07/schema#",
+	$id: "https://cssdoc.dev/cssdoc.schema.json",
+	title: "cssdoc.json",
+	description: "Configuration for @cssdoc/core: custom tags and inherited configs.",
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		$schema: { type: "string" },
+		extends: {
+			description: "Paths to other cssdoc.json files (or packages) to inherit tag definitions from.",
+			type: "array",
+			items: { type: "string" }
+		},
+		noStandardTags: {
+			description: "Disable every built-in standard tag; only tagDefinitions remain supported.",
+			type: "boolean"
+		},
+		tagDefinitions: {
+			description: "Custom tags to register.",
+			type: "array",
+			items: {
+				type: "object",
+				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" }
+				}
+			}
+		},
+		supportForTags: {
+			description: "Enable or disable specific tags by name.",
+			type: "object",
+			additionalProperties: { type: "boolean" }
+		}
+	}
+};
+//#endregion
+//#region src/CssDocConfigFile.ts
+/**
+* Load a `cssdoc.json` file into an `@cssdoc/core` {@link CssDocConfiguration} — cssdoc's analog to
+* `@microsoft/tsdoc-config`'s `TSDocConfigFile`. It reads the file, validates it against the JSON
+* schema (via ajv), resolves `extends` chains, and applies the result onto a configuration through
+* {@link CssDocConfigFile.configureParser}. Errors are collected on the instance rather than thrown, so
+* a malformed config degrades gracefully.
+*
+* @module
+*/
+const validateSchema = new Ajv({ allErrors: true }).compile(cssDocSchema);
+/** The conventional file name loaders look for. */
+const CSSDOC_CONFIG_FILENAME = "cssdoc.json";
+/** 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). */
+	filePath;
+	/** Whether the file was absent. */
+	fileNotFound;
+	/** Parse/validation/resolution messages collected while loading (this file only). */
+	messages;
+	/** Whether the file disables the standard tags. */
+	noStandardTags;
+	/** The custom tag definitions declared by this file. */
+	tagDefinitions;
+	/** Per-tag support overrides declared by this file. */
+	supportForTags;
+	/** The resolved files this one `extends`, in declaration order. */
+	extendsFiles;
+	constructor(init) {
+		this.filePath = init.filePath;
+		this.fileNotFound = init.fileNotFound;
+		this.messages = init.messages;
+		this.noStandardTags = init.noStandardTags;
+		this.tagDefinitions = init.tagDefinitions;
+		this.supportForTags = init.supportForTags;
+		this.extendsFiles = init.extendsFiles;
+	}
+	/** Whether this file — or any file it extends — reported an error. */
+	get hasErrors() {
+		return this.messages.length > 0 || this.extendsFiles.some((f) => f.hasErrors);
+	}
+	/** A newline-joined summary of every message from this file and its `extends` chain. */
+	getErrorSummary() {
+		return [...this.messages.map((m) => `${this.filePath}: ${m}`), ...this.extendsFiles.map((f) => f.getErrorSummary())].filter(Boolean).join("\n");
+	}
+	/**
+	* Apply this file (and its `extends` chain) onto a {@link CssDocConfiguration}. Extended files are
+	* applied first so this file's settings win.
+	*
+	* @param configuration - The configuration to mutate.
+	*/
+	configureParser(configuration) {
+		for (const extended of this.extendsFiles) extended.configureParser(configuration);
+		if (this.noStandardTags) configuration.setNoStandardTags();
+		configuration.addTagDefinitions(this.tagDefinitions, true);
+		for (const [tagName, supported] of this.supportForTags) {
+			const definition = configuration.tryGetTagDefinition(tagName);
+			if (definition) configuration.setSupportForTag(definition, supported);
+		}
+	}
+	/**
+	* Build a {@link CssDocConfiguration} from this file. Convenience for the common case.
+	*
+	* @returns A fresh configuration with this file applied.
+	*/
+	toConfiguration() {
+		const configuration = new CssDocConfiguration();
+		this.configureParser(configuration);
+		return configuration;
+	}
+	/**
+	* Load a `cssdoc.json` from an exact path. Missing files yield a `fileNotFound` instance (not an
+	* error); malformed ones collect messages.
+	*
+	* @param filePath - The config file path (resolved to absolute).
+	* @returns The loaded config file.
+	*/
+	static loadFile(filePath) {
+		return CssDocConfigFile._loadFile(resolve(filePath), /* @__PURE__ */ new Set());
+	}
+	/**
+	* Find and load the nearest `cssdoc.json`, walking upward from `folderPath` to the filesystem root.
+	*
+	* @param folderPath - The folder to start from.
+	* @returns The nearest config file, or a `fileNotFound` instance rooted at `folderPath`.
+	*/
+	static loadForFolder(folderPath) {
+		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());
+			if (current === root) break;
+			current = dirname(current);
+		}
+		return new CssDocConfigFile({
+			filePath: resolve(folderPath, CSSDOC_CONFIG_FILENAME),
+			fileNotFound: true,
+			messages: [],
+			noStandardTags: false,
+			tagDefinitions: [],
+			supportForTags: /* @__PURE__ */ new Map(),
+			extendsFiles: []
+		});
+	}
+	static _loadFile(filePath, visited) {
+		const messages = [];
+		const empty = (fileNotFound) => new CssDocConfigFile({
+			filePath,
+			fileNotFound,
+			messages,
+			noStandardTags: false,
+			tagDefinitions: [],
+			supportForTags: /* @__PURE__ */ new Map(),
+			extendsFiles: []
+		});
+		if (visited.has(filePath)) {
+			messages.push("Circular extends reference; skipped.");
+			return empty(false);
+		}
+		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}`);
+			return empty(false);
+		}
+		if (!validateSchema(raw)) {
+			for (const err of validateSchema.errors ?? []) messages.push(`Schema error at ${err.instancePath || "/"}: ${err.message ?? "invalid"}`);
+			return empty(false);
+		}
+		const requireFrom = createRequire(filePath);
+		const extendsFiles = [];
+		for (const ref of raw.extends ?? []) {
+			let resolved;
+			try {
+				resolved = ref.startsWith(".") ? resolve(dirname(filePath), ref) : requireFrom.resolve(ref);
+			} catch (error) {
+				messages.push(`Cannot resolve extends "${ref}": ${error.message}`);
+				continue;
+			}
+			extendsFiles.push(CssDocConfigFile._loadFile(resolved, visited));
+		}
+		const tagDefinitions = [];
+		for (const raw_ of raw.tagDefinitions ?? []) try {
+			tagDefinitions.push(new CssDocTagDefinition(raw_));
+		} catch (error) {
+			messages.push(error.message);
+		}
+		return new CssDocConfigFile({
+			filePath,
+			fileNotFound: false,
+			messages,
+			noStandardTags: raw.noStandardTags ?? false,
+			tagDefinitions,
+			supportForTags: new Map(Object.entries(raw.supportForTags ?? {})),
+			extendsFiles
+		});
+	}
+};
+//#endregion
+export { CSSDOC_CONFIG_FILENAME, CssDocConfigFile, cssDocSchema };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@cssdoc/config",
+  "version": "0.1.0",
+  "description": "Load a cssdoc.json configuration file (custom tags, extends) into an @cssdoc/core CssDocConfiguration — TSDoc-config, for CSS.",
+  "keywords": [
+    "config",
+    "css",
+    "cssdoc",
+    "documentation",
+    "tsdoc"
+  ],
+  "homepage": "https://cssdoc.dev",
+  "bugs": "https://github.com/thedannywahl/cssdoc/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thedannywahl/cssdoc.git",
+    "directory": "packages/config"
+  },
+  "files": [
+    "dist",
+    "cssdoc.schema.json"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "@cssdoc/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "publint": "^0.3.21",
+    "typescript": "^6.0.3",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.4",
+    "vite-plus": "0.2.4"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "publint": "publint"
+  }
+}