@ts-for-gir/lib 4.0.0-beta.4 → 4.0.0-beta.40

package/src/utils/files.ts

@@ -0,0 +1,71 @@
+import { constants } from "node:fs";
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { glob } from "glob";
+
+import type { FileInfo } from "../types/index.ts";
+
+export { inspect } from "node:util";
+
+/**
+ * Asynchronously checks if a file exists
+ * @param filePath The path to the file
+ * @returns A promise that resolves to true if the file exists, false otherwise
+ */
+export const fileExists = async (filePath: string): Promise<boolean> => {
+	try {
+		await access(filePath, constants.F_OK);
+		return true;
+	} catch {
+		return false;
+	}
+};
+
+/**
+ * Find a file in a list of directories
+ * @param dirs The directories to search in
+ * @param filename The filename to search for
+ * @returns The file info
+ */
+export const findFilesInDirs = async (dirs: string[], filename: string): Promise<FileInfo[]> => {
+	const filesInfo: FileInfo[] = [];
+
+	const pattern = dirs.map((dir) => join(dir, filename));
+	const _files = await glob(pattern);
+
+	// Remove duplicates
+	const files = [...new Set(_files)];
+
+	for (const filePath of files) {
+		const fileInfo: FileInfo = {
+			path: null,
+			filename,
+			exists: false,
+		};
+		fileInfo.exists = await fileExists(filePath);
+		if (fileInfo.exists) {
+			fileInfo.path = filePath;
+			filesInfo.push(fileInfo);
+		}
+	}
+
+	if (filesInfo.length === 0) {
+		filesInfo.push({
+			path: null,
+			filename,
+			exists: false,
+		});
+	}
+
+	return filesInfo;
+};
+
+/**
+ * Read a JSON file
+ * @param filePath The path to the JSON file
+ * @returns The parsed JSON
+ */
+export const readJsonFile = async <T = unknown>(filePath: string): Promise<T> => {
+	const fileContent = await readFile(filePath, "utf8");
+	return JSON.parse(fileContent) as T;
+};

package/src/utils/function-type-guards.ts

@@ -0,0 +1,61 @@
+import type { IntrospectedClassFunction } from "../gir/introspected-classes.ts";
+import type { ClassFunctionLike, FunctionTypeKind } from "../types/class-function-types.ts";
+
+/**
+ * Type guard to check if an object is a class function-like
+ */
+export function isClassFunctionLike(obj: unknown): obj is ClassFunctionLike {
+	return obj != null && typeof obj === "object" && "__functionTypeKind" in obj;
+}
+
+/**
+ * Type guard to check if an object is a specific function type
+ */
+export function isFunctionOfType(obj: unknown, type: FunctionTypeKind): boolean {
+	return isClassFunctionLike(obj) && obj.__functionTypeKind === type;
+}
+
+/**
+ * Type guard specifically for class functions
+ */
+export function isClassFunction(obj: unknown): boolean {
+	return isFunctionOfType(obj, "CLASS_FUNCTION");
+}
+
+/**
+ * Type guard specifically for virtual class functions
+ */
+export function isVirtualClassFunction(obj: unknown): boolean {
+	return isFunctionOfType(obj, "VIRTUAL_CLASS_FUNCTION");
+}
+
+/**
+ * Type guard specifically for static class functions
+ */
+export function isStaticClassFunction(fn: IntrospectedClassFunction): boolean {
+	// Check if the function has the static class function characteristics
+	// IntrospectedStaticClassFunction extends IntrospectedClassFunction but doesn't add unique properties
+	// We can identify it by checking the constructor name or other characteristics
+	return fn.constructor.name === "IntrospectedStaticClassFunction";
+}
+
+/**
+ * Type guard specifically for constructors
+ */
+export function isConstructorFunction(obj: unknown): boolean {
+	return isFunctionOfType(obj, "CONSTRUCTOR");
+}
+
+/**
+ * Helper to get the function type kind from an object
+ */
+export function getFunctionTypeKind(obj: unknown): FunctionTypeKind | null {
+	return isClassFunctionLike(obj) ? obj.__functionTypeKind : null;
+}
+
+/**
+ * Helper to check if object has namespace property (common pattern in the codebase)
+ */
+export function hasNamespace(obj: unknown): obj is { namespace: unknown } {
+	return obj != null && typeof obj === "object" && "namespace" in obj;
+}

package/src/utils/generation.ts

@@ -0,0 +1,69 @@
+import { type IntrospectedConstant, IntrospectedField, IntrospectedProperty } from "../gir/index.ts";
+import { isInvalid } from "./naming.ts";
+import { generateIndent } from "./strings.ts";
+
+/**
+ * Generates a TypeScript member name for properties, constants, and fields
+ * Handles computed properties and invalid names
+ */
+export function generateMemberName(tsVar: IntrospectedProperty | IntrospectedConstant | IntrospectedField): string {
+	const name = tsVar.name;
+	const invalid = isInvalid(name);
+	const hasInvalidName = invalid && (tsVar instanceof IntrospectedProperty || tsVar instanceof IntrospectedField);
+	const Name = hasInvalidName ? `"${name}"` : name;
+
+	if (!Name) {
+		throw new Error('[generateMemberName] "name" not set!');
+	}
+
+	const ComputedName = "computed" in tsVar && tsVar.computed ? `[${name}]` : Name;
+
+	return `${ComputedName}`;
+}
+
+/**
+ * Adds TSDoc comment lines with proper formatting
+ * @see https://github.com/microsoft/tsdoc
+ */
+export function addTSDocCommentLines(lines: string[], indentCount = 0): string[] {
+	const def: string[] = [];
+	const indent = generateIndent(indentCount);
+	def.push(`${indent}/**`);
+	for (const line of lines) {
+		def.push(`${indent} * ${line}`);
+	}
+	def.push(`${indent} */`);
+	return def;
+}
+
+/**
+ * Adds an info comment, is used for debugging the generated types
+ */
+export function addInfoComment(comment?: string, indentCount = 0): string[] {
+	const def: string[] = [];
+	const indent = generateIndent(indentCount);
+	if (comment) {
+		def.push("");
+		def.push(`${indent}// ${comment}`);
+		def.push("");
+	}
+	return def;
+}
+
+/**
+ * Merges multiple description arrays with proper indentation and comment
+ */
+export function mergeDescs(descs: string[], comment?: string, indentCount = 1): string[] {
+	const def: string[] = [];
+	const indent = generateIndent(indentCount);
+
+	for (const desc of descs) {
+		def.push(`${indent}${desc}`);
+	}
+
+	if (def.length > 0) {
+		def.unshift(...addInfoComment(comment, indentCount));
+	}
+
+	return def;
+}

package/src/utils/gir-parsing.ts

@@ -0,0 +1,243 @@
+import type {
+	GirCallableParamElement,
+	GirCallableReturn,
+	GirConstantElement,
+	GirDocElement,
+	GirFieldElement,
+	GirFunctionElement,
+	GirInfoAttrs,
+	GirMethodElement,
+} from "@gi.ts/parser";
+import { GirDirection } from "@gi.ts/parser";
+import type { IntrospectedNamespace } from "../gir/namespace.ts";
+import {
+	ArrayType,
+	ClosureType,
+	GenerifiedTypeIdentifier,
+	NativeType,
+	NullableType,
+	type TypeExpression,
+	TypeIdentifier,
+	VoidType,
+} from "../gir.ts";
+import type { IntrospectedMetadata } from "../types/introspected.ts";
+import { deprecatedVersion, introducedVersion, isDeprecated } from "./girs.ts";
+import { isPrimitiveType, parseTypeExpression, resolvePrimitiveArrayType } from "./types.ts";
+
+/**
+ * Parse documentation from a GIR element
+ */
+export function parseDoc(element: GirDocElement): string | null {
+	const el = element.doc?.[0]?._;
+
+	return el ? `${el}` : null;
+}
+
+/**
+ * Parse deprecated documentation from a GIR element
+ */
+export function parseDeprecatedDoc(element: GirDocElement): string | null {
+	return element["doc-deprecated"]?.[0]?._ ?? null;
+}
+
+/**
+ * Parse metadata from a GIR element
+ */
+export function parseMetadata(element: { $: GirInfoAttrs } & GirDocElement): IntrospectedMetadata | undefined {
+	const version = introducedVersion(element);
+	const deprecatedIn = deprecatedVersion(element);
+	const deprecated = isDeprecated(element);
+	const doc = parseDeprecatedDoc(element);
+
+	if (!version && !deprecated && !deprecatedIn && !doc) {
+		return undefined;
+	}
+
+	return {
+		...(deprecated ? { deprecated } : {}),
+		...(doc ? { deprecatedDoc: doc } : {}),
+		...(deprecatedIn ? { deprecatedVersion: deprecatedIn } : {}),
+		...(version ? { introducedVersion: version } : {}),
+	};
+}
+
+/**
+ * This function determines whether a given type is a "pointer type"...
+ * Any type where the c:type ends with *
+ */
+function isPointerType(types: import("@gi.ts/parser").GirType[] | undefined) {
+	const type = types?.[0];
+	if (!type) return false;
+
+	const ctype = type.$["c:type"];
+	if (!ctype) return false;
+
+	const typeName = type.$.name;
+	if (!typeName) return false;
+
+	if (isPrimitiveType(typeName)) return false;
+
+	return ctype.endsWith("*");
+}
+
+/**
+ * Decode the type from GIR elements
+ */
+export function getType(
+	ns: IntrospectedNamespace,
+	param?: GirConstantElement | GirCallableReturn | GirFieldElement,
+): TypeExpression {
+	const modName = ns.namespace;
+
+	if (!param) return VoidType;
+
+	let name = "";
+	let arrayDepth: number | null = null;
+	let length: number | null = null;
+	let isPointer = false;
+
+	const parameter = param as GirCallableParamElement;
+	if (parameter.array?.[0]) {
+		arrayDepth = 1;
+
+		const [array] = parameter.array;
+
+		if (array.$ && array.$.length != null) {
+			length = array.$.length;
+		}
+
+		if (array.type?.[0].$?.name) {
+			name = array.type[0].$.name;
+		} else if (array.array) {
+			let arr = array;
+			let depth = 1;
+
+			while (Array.isArray(arr.array)) {
+				arr = arr.array[0];
+				depth++;
+			}
+
+			const possibleName = arr.type?.[0].$.name;
+			if (possibleName) {
+				name = possibleName;
+			} else {
+				name = "unknown";
+				console.log(
+					`Failed to find array type in ${ns.packageName}: `,
+					JSON.stringify(parameter.$, null, 4),
+					"\nMarking as unknown!",
+				);
+			}
+			arrayDepth = depth;
+			isPointer = isPointerType(array.type);
+		} else {
+			name = "unknown";
+		}
+	} else if (parameter.type?.[0]?.$) {
+		const possibleName = parameter.type[0].$.name;
+		if (possibleName) {
+			name = possibleName;
+		} else {
+			name = "unknown";
+			console.log(
+				`Failed to find type in ${modName}: `,
+				JSON.stringify(parameter.type[0].$, null, 4),
+				"\nMarking as unknown!",
+			);
+		}
+		isPointer = isPointerType(parameter.type);
+	} else if (parameter.varargs || (parameter.$ && parameter.$.name === "...")) {
+		arrayDepth = 1;
+		name = "any";
+	} else {
+		name = "unknown";
+		console.log(`Unknown varargs type in ${modName}: `, JSON.stringify(parameter.$, null, 4), "\nMarking as unknown!");
+	}
+
+	let closure = null as null | number;
+
+	if (parameter.$?.closure) {
+		closure = parameter.$.closure;
+	}
+
+	const nullable = parameter.$ && parameter.$.nullable === "1";
+	const allowNone = parameter.$ && parameter.$["allow-none"] === "1";
+
+	const x = name.split(" ");
+	if (x.length === 1) {
+		name = x[0];
+	} else {
+		name = x[1];
+	}
+
+	let variableType: TypeExpression = parseTypeExpression(ns.namespace, name);
+
+	if (variableType instanceof TypeIdentifier) {
+		if (variableType.is("GLib", "List") || variableType.is("GLib", "SList")) {
+			// TODO: $?.name was not necessary in gi.ts, but TelepathyLogger
+			// fails to generate now.
+			const listType = parameter?.type?.[0].type?.[0]?.$?.name;
+
+			if (listType) {
+				name = listType;
+				variableType = parseTypeExpression(ns.namespace, name);
+
+				arrayDepth = 1;
+			}
+		} else if (variableType.is("GLib", "HashTable")) {
+			const keyType = parameter?.type?.[0]?.type?.[0]?.$.name;
+			const valueType = parameter?.type?.[0]?.type?.[1]?.$.name;
+
+			if (keyType && valueType) {
+				const key = parseTypeExpression(ns.namespace, keyType);
+				const value = parseTypeExpression(ns.namespace, valueType);
+
+				variableType = new GenerifiedTypeIdentifier("HashTable", "GLib", [key, value]);
+			}
+		}
+	}
+
+	if (arrayDepth != null) {
+		const primitiveArrayType = resolvePrimitiveArrayType(name, arrayDepth);
+
+		if (primitiveArrayType) {
+			const [primitiveName, primitiveArrayDepth] = primitiveArrayType;
+
+			variableType = ArrayType.new({
+				type: primitiveName,
+				arrayDepth: primitiveArrayDepth,
+				length,
+			});
+		} else {
+			variableType = ArrayType.new({ type: variableType, arrayDepth, length });
+		}
+	} else if (closure != null) {
+		variableType = ClosureType.new({ type: variableType, user_data: closure });
+	}
+
+	if (
+		parameter.$ &&
+		(parameter.$.direction === GirDirection.Inout || parameter.$.direction === GirDirection.Out) &&
+		(nullable || allowNone) &&
+		!(variableType instanceof NativeType)
+	) {
+		return new NullableType(variableType);
+	}
+
+	if ((!parameter.$?.direction || parameter.$.direction === GirDirection.In) && nullable) {
+		return new NullableType(variableType);
+	}
+
+	variableType.isPointer = isPointer;
+
+	return variableType;
+}
+
+/**
+ * Check if a function/method element has a shadow attribute
+ */
+export function hasShadow(
+	obj: GirFunctionElement | GirMethodElement,
+): obj is GirFunctionElement & { $: { shadows: string } } {
+	return obj.$.shadows != null;
+}

package/src/utils/girs.ts

@@ -0,0 +1,113 @@
+import type { GirInfoAttrs } from "@gi.ts/parser";
+import type { TsDoc } from "../types/index.ts";
+
+/**
+ * Split a package name into namespace and version
+ */
+export const splitModuleName = (packageName: string): { packageName: string; namespace: string; version: string } => {
+	// Workaround for Vte-4-2.91
+	if (packageName.startsWith("Vte-4")) {
+		return {
+			packageName,
+			namespace: "Vte",
+			version: packageName.replace("Vte-", ""),
+		};
+	}
+	if (!packageName.includes("-")) {
+		return {
+			packageName,
+			namespace: packageName,
+			version: "",
+		};
+	}
+	// There are modules that use multiple hyphens like 'GUPnP-DLNA-1.0'
+	const splits = packageName.split("-");
+	const version = splits.splice(-1, 1)[0];
+	const namespace = splits.join("");
+
+	return {
+		packageName,
+		namespace,
+		version,
+	};
+};
+
+/** Remove namespace prefix */
+export const removeNamespace = (type: string, namespace: string) => {
+	if (type.startsWith(`${namespace}.`)) {
+		type = type.substring(namespace.length + 1);
+	}
+	return type;
+};
+
+/** Remove class module name prefix */
+export const removeClassModule = removeNamespace;
+
+/**
+ * Add namespace prefix
+ */
+export const addNamespace = (type: string, namespace: string) => {
+	if (!type.startsWith(`${namespace}.`)) {
+		type = `${namespace}.${type}`;
+	}
+	return type;
+};
+
+/**
+ * Check if a line is a comment line
+ * @param line The line to check
+ * @returns Whether the line is a comment line or not
+ */
+export const isCommentLine = (line: string) => {
+	const lineTrim = line.trim();
+	return lineTrim.startsWith("//") || (lineTrim.startsWith("/*") && lineTrim.endsWith("*/"));
+};
+
+/**
+ * Convert a GirBoolean to a boolean
+ * @param boolStr The GirBoolean string
+ * @param defaultVal The default value
+ * @returns The boolean value
+ */
+export const girBool = (boolStr: string | undefined, defaultVal = false): boolean => {
+	if (boolStr) {
+		if (parseInt(boolStr, 10) === 0) return false;
+		return true;
+	}
+	return defaultVal;
+};
+
+export const printGirDocComment = (tsDoc: TsDoc, config: { noComments: boolean }) => {
+	const desc: string[] = [];
+	if (config.noComments) {
+		return desc.join("\n");
+	}
+
+	const text = tsDoc.text;
+
+	if (text) {
+		if (text) {
+			const lines = text.split("\n");
+			if (lines.length) {
+				for (const line of lines) {
+					desc.push(`${line}`);
+				}
+			}
+		}
+
+		for (const tag of tsDoc.tags) {
+			if (tag.paramName) {
+				desc.push(`@${tag.tagName} ${tag.paramName} ${tag.text}`);
+			} else {
+				desc.push(`@${tag.tagName} ${tag.text}`);
+			}
+		}
+	}
+	return desc.join("\n");
+};
+
+export const isIntrospectable = (e: { $?: GirInfoAttrs }) =>
+	!e || !e.$ || !e.$.introspectable || e.$.introspectable === "1";
+export const isDeprecated = (e: { $: GirInfoAttrs }) => e?.$ && e.$.deprecated === "1";
+export const deprecatedVersion = (e: { $: GirInfoAttrs }) => e?.$?.["deprecated-version"];
+export const introducedVersion = (e: { $: GirInfoAttrs }) => e?.$?.version;

package/src/utils/index.ts

@@ -0,0 +1,14 @@
+export * from "./conflicts.ts";
+export * from "./documentation.ts";
+export * from "./files.ts";
+export * from "./generation.ts";
+export * from "./gir-parsing.ts";
+export * from "./girs.ts";
+export * from "./naming.ts";
+export * from "./numbers.ts";
+export * from "./objects.ts";
+export * from "./path.ts";
+export * from "./registry.ts";
+export * from "./strings.ts";
+export * from "./type-resolution.ts";
+export * from "./types.ts";