@cssdoc/config 0.6.1 → 0.7.0

package/cssdoc.schema.json

@@ -130,6 +130,25 @@
       "description": "How a /* … */ comment on a member's rule combines with its tag prose: append (default), prepend, replace, or ignore.",
       "enum": ["append", "prepend", "replace", "ignore"]
     },
+    "providers": {
+      "description": "Upstream cssdoc providers this config consumes, so their components resolve in this scope's lint/hover/docs. Each points at a provider's model.json or a source stylesheet.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Path to the provider's model.json or a source stylesheet — relative (starts with .) or a package specifier."
+          },
+          "baseHref": {
+            "type": "string",
+            "description": "URL prefix for links to the provider's rendered doc pages."
+          }
+        }
+      }
+    },
     "rules": {
       "description": "Per-rule severity overrides (off/warn/error).",
       "type": "object",

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { CssDocConfiguration, CssDocTagDefinition, InlineCommentMode, ModifierConventionInput } from "@cssdoc/core";
+import { CssDocConfiguration, CssDocEntry, CssDocTagDefinition, InlineCommentMode, ModifierConventionInput } from "@cssdoc/core";
 
 //#region src/CssDocConfigFile.d.ts
 /** A per-rule severity override, as spelled in `cssdoc.json`. */
@@ -20,6 +20,16 @@ interface RenderConfig {
   /** Which Structure representation(s) to emit: `"text"`, `"diagram"`, or `"both"` (default). */
   structureView?: "text" | "diagram" | "both";
 }
+/**
+ * An upstream cssdoc provider this config consumes. `path` points at the provider's published model
+ * (`model.json`, the JSON emitter's output) or a source stylesheet (`.css`/`.scss`/…) — resolved
+ * relative to this file for `.`-paths, else via Node resolution (so a package specifier works).
+ * `baseHref` prefixes links to the provider's rendered doc pages (`<baseHref><name>.md`).
+ */
+interface ProviderRef {
+  path: string;
+  baseHref?: 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.
@@ -47,6 +57,11 @@ declare class CssDocConfigFile {
   readonly modifierConvention?: ModifierConventionInput;
   /** How inline `/* … *\/` comments combine with tag prose, if declared by this file. */
   readonly inlineComments?: InlineCommentMode;
+  /**
+   * Upstream cssdoc providers this file consumes (this file's own — NOT inherited via `extends`, which
+   * carries configuration, not components). Resolve with {@link resolveProviders}.
+   */
+  readonly providers: readonly ProviderRef[];
   /**
    * The per-rule severity overrides, merged across the `extends` chain (this file wins). Not the
    * resolved severities — pass these to `resolveRuleSeverities` in `@cssdoc/providers`.
@@ -104,6 +119,23 @@ declare class CssDocConfigFile {
   private static _loadFile;
 }
 //#endregion
+//#region src/providers.d.ts
+/** The upstream components a config consumes, plus a resolver for links to their rendered pages. */
+interface ResolvedProviders {
+  /** Every component/record the declared providers document. */
+  entries: CssDocEntry[];
+  /** The doc-page URL for a class, from the owning provider's `baseHref` (`undefined` if none). */
+  href: (className: string) => string | undefined;
+  /** Resolution problems (missing file, parse/JSON error), one per provider that failed. */
+  messages: string[];
+}
+/**
+ * Resolve every provider a config declares. `.json` paths load a published model; other paths are
+ * parsed as stylesheets. Paths starting with `.` resolve relative to the config file; the rest go
+ * through Node resolution (so a package specifier works), mirroring `extends`.
+ */
+declare function resolveProviders(configFile: CssDocConfigFile): ResolvedProviders;
+//#endregion
 //#region src/schema.d.ts
 /**
  * The JSON Schema for a `cssdoc.json` file — the single source of truth used to validate config files
@@ -236,6 +268,25 @@ declare const cssDocSchema: {
       readonly description: "How a /* … */ comment on a member's rule combines with its tag prose: append (default), prepend, replace, or ignore.";
       readonly enum: readonly ["append", "prepend", "replace", "ignore"];
     };
+    readonly providers: {
+      readonly description: "Upstream cssdoc providers this config consumes, so their components resolve in this scope's lint/hover/docs. Each points at a provider's model.json or a source stylesheet.";
+      readonly type: "array";
+      readonly items: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["path"];
+        readonly properties: {
+          readonly path: {
+            readonly type: "string";
+            readonly description: "Path to the provider's model.json or a source stylesheet — relative (starts with .) or a package specifier.";
+          };
+          readonly baseHref: {
+            readonly type: "string";
+            readonly description: "URL prefix for links to the provider's rendered doc pages.";
+          };
+        };
+      };
+    };
     readonly rules: {
       readonly description: "Per-rule severity overrides (off/warn/error).";
       readonly type: "object";
@@ -292,4 +343,4 @@ declare const cssDocSchema: {
   };
 };
 //#endregion
-export { CSSDOC_CONFIG_FILENAME, CSSDOC_CONFIG_FILENAMES, CssDocConfigFile, cssDocSchema };
+export { CSSDOC_CONFIG_FILENAME, CSSDOC_CONFIG_FILENAMES, CssDocConfigFile, type ProviderRef, type ResolvedProviders, cssDocSchema, resolveProviders };

package/dist/index.mjs

@@ -3,7 +3,7 @@ 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";
+import { CssDocConfiguration, CssDocTagDefinition, parseCssDocs } 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
@@ -121,6 +121,25 @@ const cssDocSchema = {
 				"ignore"
 			]
 		},
+		providers: {
+			description: "Upstream cssdoc providers this config consumes, so their components resolve in this scope's lint/hover/docs. Each points at a provider's model.json or a source stylesheet.",
+			type: "array",
+			items: {
+				type: "object",
+				additionalProperties: false,
+				required: ["path"],
+				properties: {
+					path: {
+						type: "string",
+						description: "Path to the provider's model.json or a source stylesheet — relative (starts with .) or a package specifier."
+					},
+					baseHref: {
+						type: "string",
+						description: "URL prefix for links to the provider's rendered doc pages."
+					}
+				}
+			}
+		},
 		rules: {
 			description: "Per-rule severity overrides (off/warn/error).",
 			type: "object",
@@ -234,6 +253,11 @@ var CssDocConfigFile = class CssDocConfigFile {
 	/** How inline `/* … *\/` comments combine with tag prose, if declared by this file. */
 	inlineComments;
 	/**
+	* Upstream cssdoc providers this file consumes (this file's own — NOT inherited via `extends`, which
+	* carries configuration, not components). Resolve with {@link resolveProviders}.
+	*/
+	providers;
+	/**
 	* The per-rule severity overrides, merged across the `extends` chain (this file wins). Not the
 	* resolved severities — pass these to `resolveRuleSeverities` in `@cssdoc/providers`.
 	*/
@@ -264,6 +288,7 @@ var CssDocConfigFile = class CssDocConfigFile {
 		this.extendsFiles = init.extendsFiles;
 		this.modifierConvention = init.modifierConvention;
 		this.inlineComments = init.inlineComments;
+		this.providers = init.providers;
 		const severities = {};
 		const naming = {};
 		const render = {};
@@ -353,6 +378,7 @@ var CssDocConfigFile = class CssDocConfigFile {
 			tagDefinitions: [],
 			supportForTags: /* @__PURE__ */ new Map(),
 			extendsFiles: [],
+			providers: [],
 			rules: {},
 			naming: {},
 			structureIgnore: [],
@@ -369,6 +395,7 @@ var CssDocConfigFile = class CssDocConfigFile {
 			tagDefinitions: [],
 			supportForTags: /* @__PURE__ */ new Map(),
 			extendsFiles: [],
+			providers: [],
 			rules: {},
 			naming: {},
 			structureIgnore: [],
@@ -419,6 +446,7 @@ var CssDocConfigFile = class CssDocConfigFile {
 			extendsFiles,
 			modifierConvention: raw.modifierConvention,
 			inlineComments: raw.inlineComments,
+			providers: raw.providers ?? [],
 			rules: raw.rules ?? {},
 			naming: raw.naming ?? {},
 			structureIgnore: raw.structureIgnore ?? [],
@@ -427,4 +455,72 @@ var CssDocConfigFile = class CssDocConfigFile {
 	}
 };
 //#endregion
-export { CSSDOC_CONFIG_FILENAME, CSSDOC_CONFIG_FILENAMES, CssDocConfigFile, cssDocSchema };
+//#region src/providers.ts
+/**
+* Resolve the upstream cssdoc **providers** a `cssdoc.json` declares (its `providers` field) into a flat
+* set of {@link CssDocEntry} plus a cross-link resolver. This is how a consumer scope learns another
+* provider's documented components — so the consumer's lint, hover, and docs recognize (and link to)
+* vendor classes it composes, without a `structureIgnore` escape hatch.
+*
+* A provider is consumed via its published model (`model.json`, the JSON emitter's `CssDocEntry[]`
+* output) or a source stylesheet parsed on the spot with the provider's own convention. `extends`
+* carries configuration; `providers` carries components — the two are orthogonal.
+*
+* @module
+*/
+const stripDot = (name) => name.replace(/^\./u, "");
+/** Read a provider's `model.json` — a `CssDocEntry[]` or a `{ entries }` manifest wrapper. */
+function loadModel(file) {
+	const data = JSON.parse(readFileSync(file, "utf8"));
+	if (Array.isArray(data)) return data;
+	if (data && typeof data === "object" && Array.isArray(data.entries)) return data.entries;
+	throw new Error("expected a CssDocEntry[] or a { entries } manifest");
+}
+/** Parse a provider source stylesheet with its own governing `cssdoc.json` convention. */
+function loadStylesheet(file) {
+	const configuration = CssDocConfigFile.loadForFolder(dirname(file)).toConfiguration();
+	return parseCssDocs(readFileSync(file, "utf8"), {
+		configuration,
+		fileName: file
+	});
+}
+/**
+* Resolve every provider a config declares. `.json` paths load a published model; other paths are
+* parsed as stylesheets. Paths starting with `.` resolve relative to the config file; the rest go
+* through Node resolution (so a package specifier works), mirroring `extends`.
+*/
+function resolveProviders(configFile) {
+	const entries = [];
+	const messages = [];
+	const hrefByClass = /* @__PURE__ */ new Map();
+	const requireFrom = createRequire(configFile.filePath);
+	const from = dirname(configFile.filePath);
+	for (const provider of configFile.providers) {
+		let resolved;
+		try {
+			resolved = provider.path.startsWith(".") ? resolve(from, provider.path) : requireFrom.resolve(provider.path);
+		} catch (error) {
+			messages.push(`Cannot resolve provider "${provider.path}": ${error.message}`);
+			continue;
+		}
+		let loaded;
+		try {
+			loaded = resolved.endsWith(".json") ? loadModel(resolved) : loadStylesheet(resolved);
+		} catch (error) {
+			messages.push(`Cannot load provider "${provider.path}": ${error.message}`);
+			continue;
+		}
+		const base = provider.baseHref?.replace(/\/?$/u, "/");
+		for (const entry of loaded) {
+			entries.push(entry);
+			if (base && entry.className) hrefByClass.set(stripDot(entry.className), `${base}${entry.name}.md`);
+		}
+	}
+	return {
+		entries,
+		messages,
+		href: (className) => hrefByClass.get(stripDot(className))
+	};
+}
+//#endregion
+export { CSSDOC_CONFIG_FILENAME, CSSDOC_CONFIG_FILENAMES, CssDocConfigFile, cssDocSchema, resolveProviders };

package/package.json

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