@elmeragroup/internal 0.1.1-canary.1

package/dist/dist-CcEC-Qb_.mjs

@@ -0,0 +1,558 @@
+
+import { n as ApiArtifactsError, r as ProblemLog, t as ApiArtifactsDriftError } from "./errors-ByXSCE94.mjs";
+import { t as ProjectExtractor } from "./dist-_NayZK35.mjs";
+import { Effect } from "effect";
+import path from "node:path";
+import { API, NodeBuilderFlags, SignatureKind, SymbolFlags } from "typescript/unstable/sync";
+import { isExpressionStatement, isStringLiteral } from "typescript/unstable/ast/is";
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+//#region ../api-artifacts/dist/checker.js
+/** Opens the configured project. Callers must close the result. */
+function openLibraryProject(tsconfigPath, projectRoot) {
+	const api = new API({ cwd: projectRoot });
+	try {
+		const project = api.updateSnapshot({ openProjects: [tsconfigPath] }).getProject(tsconfigPath);
+		if (project === void 0) throw new Error(`Could not open the project at ${tsconfigPath}`);
+		return {
+			projectRoot,
+			project,
+			checker: project.checker,
+			program: project.program,
+			close: () => api.close()
+		};
+	} catch (error) {
+		api.close();
+		throw error;
+	}
+}
+/**
+* A `"use client"` directive only counts as one when it leads the module, so a stray
+* string expression further down never flips the classification.
+*/
+function readRscStatus(sourceFile) {
+	for (const statement of sourceFile.statements) {
+		if (!isExpressionStatement(statement) || !isStringLiteral(statement.expression)) return "server";
+		const authored = statement.expression.getText(sourceFile);
+		if (authored === "\"use client\"" || authored === "'use client'") return "client";
+	}
+	return "server";
+}
+/** Package name a forwarded prop comes from, e.g. `@base-ui/react` or `react`. */
+function declaringPackage(declarationPath) {
+	const last = declarationPath.lastIndexOf("/node_modules/");
+	if (last === -1) return null;
+	const segments = declarationPath.slice(last + 14).split("/");
+	const first = segments[0];
+	if (first === void 0) return null;
+	if (first.startsWith("@")) {
+		const second = segments[1];
+		return second === void 0 ? first : `${first}/${second}`;
+	}
+	return first;
+}
+function isOwnProp(context, symbol) {
+	return symbol.declarations.some((declaration) => {
+		const relative = path.relative(context.projectRoot.toLowerCase(), declaration.path.toLowerCase()).replaceAll("\\", "/");
+		return relative !== ".." && !relative.startsWith("../") && !path.isAbsolute(relative) && !relative.split("/").includes("node_modules");
+	});
+}
+function isOptional(symbol) {
+	return (symbol.flags & SymbolFlags.Optional) !== 0;
+}
+function isRecipeAxisDeclaration(declarationPath) {
+	const normalized = declarationPath.replaceAll("\\", "/");
+	const file = normalized.slice(normalized.lastIndexOf("/") + 1);
+	return file.endsWith("-variants.ts") || file.endsWith("-variants.tsx");
+}
+/**
+* Classifies a prop from facts supplied by either checker.  Recipe axes are
+* checker-synthesized in the current model and are declared in `*-variants`
+* sources by the Effect model; neither case needs the consumer-facing JSDoc
+* policy applied to ordinary declared props.
+*/
+function propOrigin(declarationPaths, synthesized) {
+	return synthesized || declarationPaths.some(isRecipeAxisDeclaration) ? "recipe-axis" : "declared";
+}
+/**
+* Turns one source-inspection result into artifact source metadata. Unresolved
+* implementations become an actionable problem instead of React declaration paths.
+* A forwarded dependency value reads its metadata from the authored module that
+* forwards it: that module's directive decides `rsc`, and it has no defaults.
+*/
+function partSourceFromInspection(context, partName, result, problems) {
+	if (result.status === "unresolved") {
+		problems.add(`${partName}: could not recover the authored implementation (${result.reason})`);
+		return null;
+	}
+	const sourceFile = context.program.getSourceFile(result.filePath);
+	if (sourceFile === void 0) {
+		problems.add(`${partName}: could not load the authored implementation file (${result.filePath})`);
+		return null;
+	}
+	return {
+		sourcePath: path.relative(context.projectRoot, sourceFile.fileName).replaceAll("\\", "/"),
+		rsc: readRscStatus(sourceFile),
+		defaults: new Map(result.status === "resolved" ? result.defaults.map((entry) => [entry.name, entry.initializerText]) : [])
+	};
+}
+/**
+* A symbol declared in several union branches reports each branch's JSDoc in turn.
+* Identical paragraphs are the same sentence repeated, not two facts.
+*/
+function dedupeDocumentation(documentation) {
+	if (documentation === void 0) return "";
+	const seen = /* @__PURE__ */ new Set();
+	const kept = [];
+	for (const paragraph of documentation.split(/\n{2,}|\n/)) {
+		const trimmed = paragraph.trim();
+		if (trimmed === "" || seen.has(trimmed)) continue;
+		seen.add(trimmed);
+		kept.push(trimmed);
+	}
+	return kept.join(" ");
+}
+function printType(checker, type) {
+	if (type === void 0 || type.isErrorType()) return null;
+	const printed = checker.typeToString(type, void 0, NodeBuilderFlags.NoTruncation);
+	return printed === "" ? null : printed;
+}
+/**
+* The one-line type a closed reference row shows, or `null` when the printed type is
+* short enough to show in full.
+*
+* A plain-string heuristic on purpose: it decides what a *collapsed* row displays, and
+* the expanded panel always carries the real signature, so being approximate costs
+* nothing while parsing the printed type would cost a second type model.
+*
+* `on`/`get` must be followed by a capital to count as the handler/accessor convention —
+* a prop literally named `open` or `gettable` is not a function.
+*/
+function shortTypeOf(propName, printedType) {
+	if (/^(?:on|get)[A-Z]/.test(propName) || printedType.includes("=>")) return "function";
+	if (printedType.split("|").length - 1 >= 2 || printedType.length >= 30) return "Union";
+	return null;
+}
+function callSignature(checker, type) {
+	return checker.getSignaturesOfType(type, SignatureKind.Call)[0] ?? null;
+}
+function isForwardedProp(context, symbol) {
+	return propOrigin(symbol.declarations.map((declaration) => declaration.path), symbol.declarations.length === 0) !== "recipe-axis" && !isOwnProp(context, symbol);
+}
+const emptyForwarded = {
+	count: 0,
+	from: []
+};
+/** A forwarded value's own declaring package joins the packages its forwarded props come from. */
+function withForwardedValue(forwarded, result) {
+	if (result.status !== "forwarded" || forwarded.from.includes(result.packageName)) return forwarded;
+	const from = [...forwarded.from, result.packageName].sort((left, right) => left.localeCompare(right));
+	return {
+		count: forwarded.count,
+		from
+	};
+}
+/**
+* Counts props the part accepts that are neither library-declared nor recipe
+* axes — the same omitted set the published table drops.
+*/
+function forwardedOfProps(context, properties) {
+	const from = /* @__PURE__ */ new Set();
+	let count = 0;
+	for (const property of properties) {
+		if (!isForwardedProp(context, property)) continue;
+		count += 1;
+		for (const declaration of property.declarations) {
+			const packageName = declaringPackage(declaration.path);
+			if (packageName !== null) from.add(packageName);
+		}
+	}
+	return {
+		count,
+		from: [...from].sort((left, right) => left.localeCompare(right))
+	};
+}
+function addProblem(problems, message) {
+	problems?.add(message);
+}
+/**
+* Resolves the checker-backed part requests for one public component.  This is
+* the *only* walk of a component's entry: generation calls it once and
+* every downstream fact is read from the parts it returns.
+*/
+function componentPartRequests(context, request, problems) {
+	const { checker, program } = context;
+	const sourceFile = program.getSourceFile(request.entryFile);
+	if (sourceFile === void 0) {
+		addProblem(problems, `${request.entryFile}: entry module is not part of the library program`);
+		return [];
+	}
+	const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
+	if (moduleSymbol === void 0) {
+		addProblem(problems, `${request.entryFile}: entry module has no module symbol`);
+		return [];
+	}
+	const moduleExports = checker.getExportsOfModule(moduleSymbol);
+	const parts = [];
+	for (const exportName of request.exportNames) {
+		const rootSymbol = moduleExports.find((exported) => exported.name === exportName);
+		if (rootSymbol === void 0) {
+			addProblem(problems, `${request.entryFile}: does not export "${exportName}"`);
+			continue;
+		}
+		const rootType = checker.getTypeOfSymbol(rootSymbol);
+		if (rootType === void 0 || rootType.isErrorType()) {
+			addProblem(problems, `${exportName}: exported value has an unresolvable type`);
+			continue;
+		}
+		if (callSignature(checker, rootType) !== null) {
+			parts.push({
+				name: exportName,
+				exportName,
+				type: rootType
+			});
+			continue;
+		}
+		const start = parts.length;
+		for (const member of checker.getPropertiesOfType(rootType)) {
+			const memberType = checker.getTypeOfSymbol(member);
+			if (memberType === void 0 || callSignature(checker, memberType) === null) continue;
+			parts.push({
+				name: `${exportName}.${member.name}`,
+				exportName,
+				memberName: member.name,
+				type: memberType
+			});
+		}
+		if (parts.length === start) addProblem(problems, `${exportName}: no renderable parts were found on the exported namespace`);
+	}
+	return parts;
+}
+/**
+* Prints one accepted prop's checker facts.
+*
+* Printing a type is the single most expensive checker call in the pass, so it is
+* done per prop a consumer actually asks about — the dependency-enrichment merge
+* asks for the handful of Base UI props it selects, not for all ~300 React and DOM
+* props every part forwards.
+*/
+function readPartPropFact(context, part, propName) {
+	const property = part.props.get(propName);
+	if (property === void 0) return;
+	return {
+		type: printType(context.checker, context.checker.getTypeOfSymbol(property)),
+		required: !isOptional(property)
+	};
+}
+function describePart(context, request, signature, source, hasPropsParameter, propsResolved, props, forwarded, problems) {
+	const { checker } = context;
+	if (signature === null) {
+		problems.add(`${request.name}: no call signature — it does not look like a component`);
+		return null;
+	}
+	if (source === null) return null;
+	if (!hasPropsParameter) return {
+		name: request.name,
+		rsc: source.rsc,
+		sourcePath: source.sourcePath,
+		props: [],
+		forwardedFrom: forwarded.from,
+		forwardedCount: 0
+	};
+	if (!propsResolved) {
+		problems.add(`${request.name}: props type is unresolvable`);
+		return null;
+	}
+	const rows = [];
+	for (const property of props.values()) {
+		const isRecipeAxis = propOrigin(property.declarations.map((declaration) => declaration.path), property.declarations.length === 0) === "recipe-axis";
+		if (isForwardedProp(context, property)) continue;
+		const printed = printType(checker, checker.getTypeOfSymbol(property));
+		if (printed === null) {
+			problems.add(`${request.name}.${property.name}: type is unresolvable — the docs build cannot print it (${source.sourcePath})`);
+			continue;
+		}
+		const description = dedupeDocumentation(checker.getDocumentationCommentOfSymbol(property));
+		if (description === "" && !isRecipeAxis) {
+			problems.add(`${request.name}.${property.name}: public prop has no JSDoc description (${source.sourcePath})`);
+			continue;
+		}
+		rows.push({
+			name: property.name,
+			origin: isRecipeAxis ? "recipe-axis" : "declared",
+			type: printed,
+			shortType: shortTypeOf(property.name, printed),
+			defaultValue: source.defaults.get(property.name) ?? null,
+			description,
+			required: !isOptional(property)
+		});
+	}
+	rows.sort((left, right) => left.name.localeCompare(right.name));
+	return {
+		name: request.name,
+		rsc: source.rsc,
+		sourcePath: source.sourcePath,
+		props: rows,
+		forwardedFrom: forwarded.from,
+		forwardedCount: forwarded.count
+	};
+}
+/** Reads every fact one part yields, resolving its props type exactly once. */
+function extractPart(context, request, sourceResult, problems) {
+	const source = partSourceFromInspection(context, request.name, sourceResult, problems);
+	const { checker } = context;
+	const signature = callSignature(checker, request.type);
+	const declarationPaths = signature?.declaration === void 0 ? [] : [signature.declaration.path];
+	const parameter = signature?.getParameters()[0];
+	const declared = parameter === void 0 ? void 0 : checker.getTypeOfSymbol(parameter);
+	const propsType = declared === void 0 || declared.isErrorType() ? null : declared;
+	const props = /* @__PURE__ */ new Map();
+	if (propsType !== null) for (const property of checker.getPropertiesOfType(propsType)) props.set(property.name, property);
+	const forwarded = withForwardedValue(props.size === 0 ? emptyForwarded : forwardedOfProps(context, props.values()), sourceResult);
+	return {
+		name: request.name,
+		declarationPaths,
+		source,
+		forwarded,
+		props,
+		part: describePart(context, request, signature, source, parameter !== void 0, propsType !== null, props, forwarded, problems)
+	};
+}
+//#endregion
+//#region ../api-artifacts/dist/enrichment.js
+function propertiesOf(type) {
+	switch (type.kind) {
+		case "component": return type.props;
+		case "object": return type.properties;
+		case "intersection": return [...type.properties, ...type.types.flatMap(propertiesOf)];
+		case "union": return type.types.flatMap(propertiesOf);
+		default: return [];
+	}
+}
+function selectedProps(result, rootName, partName) {
+	let type = result.module.exports.find((entry) => entry.name === rootName)?.type;
+	const ownerPath = [rootName];
+	if (partName !== rootName) {
+		const memberName = partName.slice(rootName.length + 1);
+		type = type?.kind === "object" ? type.properties.find((entry) => entry.name === memberName)?.type : void 0;
+		ownerPath.push("properties", memberName);
+	}
+	if (type === void 0) return void 0;
+	if (type.kind === "function") {
+		const parameter = type.callSignatures[0]?.parameters[0];
+		if (parameter === void 0) return void 0;
+		return {
+			properties: propertiesOf(parameter.type),
+			ownerPath: [
+				...ownerPath,
+				"callSignatures",
+				"0",
+				"parameters",
+				parameter.name,
+				"properties"
+			]
+		};
+	}
+	return {
+		properties: propertiesOf(type),
+		ownerPath: [...ownerPath, "props"]
+	};
+}
+function enrichPart(context, component, current, result, roots, packages) {
+	const root = roots.find((name) => current.name === name || current.name.startsWith(`${name}.`));
+	const facts = component.partApis.find((part) => part.name === current.name);
+	if (root === void 0 || facts === void 0) return current;
+	const selected = selectedProps(result, root, current.name);
+	if (selected === void 0) return current;
+	const names = new Set(current.props.map((prop) => prop.name));
+	const additions = [];
+	for (const property of selected.properties) {
+		if (names.has(property.name)) continue;
+		const propPath = [...selected.ownerPath, property.name];
+		const provenance = result.provenance.find((entry) => entry.path.length === propPath.length && entry.path.every((segment, index) => segment === propPath[index]));
+		if (provenance?.synthesized === true || provenance?.declarations.some((declaration) => declaration.owner?.kind === "project")) continue;
+		const owners = [...new Set(provenance?.declarations.flatMap((declaration) => declaration.owner?.kind === "dependency" ? [declaration.owner.packageName] : []) ?? [])];
+		const packageName = owners.length === 1 ? owners[0] : void 0;
+		const description = dedupeDocumentation(property.documentation?.description);
+		if (packageName === void 0 || !packages.includes(packageName) || description === "") continue;
+		const fact = readPartPropFact(context, facts, property.name);
+		if (fact === void 0) continue;
+		if (fact.type === null) throw new Error(`${current.name}.${property.name}: selected dependency prop has an unresolvable type`);
+		additions.push({
+			name: property.name,
+			origin: { packageName },
+			type: fact.type,
+			shortType: shortTypeOf(property.name, fact.type),
+			defaultValue: facts.source?.defaults.get(property.name) ?? property.documentation?.defaultValue ?? null,
+			description,
+			required: fact.required
+		});
+		names.add(property.name);
+	}
+	additions.sort((left, right) => left.name.localeCompare(right.name));
+	if (additions.length > current.forwardedCount) throw new Error(`${current.name}: selected props exceed forwarded prop count`);
+	return {
+		...current,
+		props: [...current.props, ...additions],
+		forwardedCount: current.forwardedCount - additions.length
+	};
+}
+function enrichComponents(context, results, model, packages) {
+	const diagnostics = [];
+	return {
+		components: model.map((component, index) => {
+			const result = results[index];
+			if (result === void 0) throw new Error(`Missing extraction for ${component.slug}`);
+			diagnostics.push(...result.warnings.map((warning) => ({
+				component: component.slug,
+				warning
+			})));
+			return {
+				...component,
+				parts: component.parts.map((part) => enrichPart(context, component, part, result, component.exportNames, packages))
+			};
+		}),
+		diagnostics
+	};
+}
+//#endregion
+//#region ../api-artifacts/dist/generate.js
+function requestsFor(options) {
+	const slugs = /* @__PURE__ */ new Set();
+	const outputs = /* @__PURE__ */ new Set();
+	return options.components.map((component) => {
+		const entryFile = path.resolve(options.projectRoot, component.entryFile);
+		const outputFile = path.resolve(options.projectRoot, component.outputFile);
+		if (!component.slug.trim() || slugs.has(component.slug)) throw new ApiArtifactsError([`Empty or duplicate component slug: ${component.slug}`]);
+		if (outputFile === path.resolve(options.projectRoot, options.tsconfigPath)) throw new ApiArtifactsError(["The tsconfig cannot be an artifact output"]);
+		if (outputs.has(outputFile) || !outputFile.endsWith(".json")) throw new ApiArtifactsError([`Duplicate or non-JSON output: ${outputFile}`]);
+		if (component.exportNames.length === 0 || new Set(component.exportNames).size !== component.exportNames.length || component.exportNames.some((name) => !name.trim())) throw new ApiArtifactsError([`${component.slug}: provide unique, non-empty export names`]);
+		slugs.add(component.slug);
+		outputs.add(outputFile);
+		return {
+			...component,
+			entryFile,
+			outputFile
+		};
+	});
+}
+async function existingText(file) {
+	try {
+		return await readFile(file, "utf8");
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return void 0;
+		throw error;
+	}
+}
+/** Replaces complete files; a reader never sees a partially written JSON document. */
+async function writeArtifact(file, text) {
+	await mkdir(path.dirname(file), { recursive: true });
+	const temporary = `${file}.${randomUUID()}.tmp`;
+	try {
+		await writeFile(temporary, text, { flag: "wx" });
+		await rename(temporary, file);
+	} finally {
+		await rm(temporary, { force: true });
+	}
+}
+function describeComponent(context, request, parts, inspected, problems) {
+	if (inspected.length !== parts.length) throw new ApiArtifactsError([`${request.slug}: source inspection returned ${inspected.length} results for ${parts.length} parts`]);
+	const partApis = parts.map((part, index) => {
+		const source = inspected[index];
+		if (source === void 0) throw new ApiArtifactsError([`${part.name}: missing source inspection result`]);
+		return extractPart(context, part, source, problems);
+	});
+	return {
+		slug: request.slug,
+		exportNames: request.exportNames,
+		parts: partApis.flatMap((entry) => entry.part === null ? [] : [entry.part]),
+		partApis
+	};
+}
+/** Extracts and validates the entire inventory before writing any artifact. */
+async function generateApiArtifacts(options) {
+	const projectRoot = path.resolve(options.projectRoot);
+	const tsconfigPath = path.resolve(projectRoot, options.tsconfigPath);
+	const requests = requestsFor({
+		...options,
+		projectRoot
+	});
+	if (requests.length === 0) return {
+		components: [],
+		diagnostics: []
+	};
+	const context = openLibraryProject(tsconfigPath, projectRoot);
+	const problems = new ProblemLog();
+	let model;
+	let diagnostics = [];
+	try {
+		const generated = await Effect.runPromise(Effect.scoped(Effect.gen(function* () {
+			const extractor = yield* ProjectExtractor;
+			const described = yield* Effect.forEach(requests, (request) => Effect.gen(function* () {
+				const parts = componentPartRequests(context, request, problems);
+				const inspected = yield* extractor.inspectComponentSources(request.entryFile, parts);
+				return describeComponent(context, request, parts, inspected, problems);
+			}));
+			if (problems.problems.length > 0) return yield* Effect.fail(new ApiArtifactsError(problems.problems));
+			const packages = options.includeExternalTypes ?? [];
+			if (packages.length === 0) return {
+				components: described,
+				diagnostics: []
+			};
+			const extracted = yield* Effect.forEach(requests, (entry) => extractor.extractModule(entry.entryFile, { includeExternalTypes: packages }));
+			const enriched = enrichComponents(context, extracted, described, packages);
+			const rejected = enriched.diagnostics.filter((diagnostic) => !options.allowedWarningCodes?.includes(diagnostic.warning.code));
+			if (rejected.length > 0) return yield* Effect.fail(new ApiArtifactsError(rejected.map(({ component, warning }) => `${component}: ${warning.code}: ${warning.message}`)));
+			return enriched;
+		}).pipe(Effect.provide(ProjectExtractor.live({
+			tsconfigPath,
+			cwd: projectRoot
+		})))));
+		model = generated.components;
+		diagnostics = generated.diagnostics;
+	} finally {
+		context.close();
+	}
+	const components = [];
+	for (const [index, component] of model.entries()) {
+		const request = requests[index];
+		if (request === void 0) throw new Error(`Missing output for ${component.slug}`);
+		const artifact = {
+			$generated: options.generatedBy ?? "Generated from TypeScript types and JSDoc by @elmeragroup/api-artifacts. Do not edit.",
+			slug: component.slug,
+			parts: component.parts.map((part) => ({
+				name: part.name,
+				rsc: part.rsc,
+				sourcePath: part.sourcePath,
+				forwardedFrom: part.forwardedFrom,
+				forwardedCount: part.forwardedCount,
+				props: part.props.map((prop) => ({
+					name: prop.name,
+					origin: prop.origin,
+					type: prop.type,
+					shortType: prop.shortType,
+					defaultValue: prop.defaultValue,
+					description: prop.description,
+					required: prop.required
+				}))
+			}))
+		};
+		const text = `${JSON.stringify(artifact, null, 2)}\n`;
+		components.push({
+			...artifact,
+			outputFile: request.outputFile,
+			text,
+			changed: await existingText(request.outputFile) !== text
+		});
+	}
+	const changed = components.filter((component) => component.changed);
+	if (options.mode === "check") {
+		if (changed.length > 0) throw new ApiArtifactsDriftError(changed.map((component) => component.outputFile));
+	} else for (const component of changed) await writeArtifact(component.outputFile, component.text);
+	return {
+		components,
+		diagnostics
+	};
+}
+//#endregion
+export { generateApiArtifacts };