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

package/README.md

@@ -18,4 +18,16 @@
 
 # Library
 
-Node.js library to generate Typescript Type Definition files for Gjs and node-gtk.
+Core library to generate TypeScript type definitions from GObject Introspection Repository (GIR) data. This package provides the foundation for processing, transforming, and generating TypeScript interfaces based on GIR definitions.
+
+## Features
+
+- Complete type system for representing GObject types in TypeScript
+- Dependency management for GIR modules and their relationships
+- Transformation engine to convert GIR introspection data to TypeScript types
+- Support for type generics, promises, and complex type expressions
+- Type conflict resolution and validation
+- Extensible architecture with visitor pattern support
+- Customizable code generation through formatters and generators
+
+This library serves as the core engine for the `ts-for-gir` toolchain, handling the translation of GObject types to their TypeScript equivalents.

package/package.json

@@ -1,35 +1,26 @@
 {
   "name": "@ts-for-gir/lib",
-  "version": "4.0.0-beta.4",
+  "version": "4.0.0-beta.41",
   "description": "Typescript .d.ts generator from GIR for gjs",
-  "module": "lib/index.js",
-  "main": "lib/index.js",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
   "type": "module",
   "engines": {
     "node": ">=18"
   },
   "exports": {
-    ".": {
-      "types": "./lib/index.d.ts",
-      "import": "./lib/index.js"
-    }
+    ".": "./src/index.ts"
   },
   "scripts": {
-    "build": "yarn lint && yarn build:ts",
-    "build:ts": "tsc",
-    "clear": "yarn clear:build",
-    "clear:build": "rimraf ./lib",
-    "watch": "yarn build:ts --watch",
-    "lint": "eslint . --ext .ts,.tsx --fix",
-    "update-package-descriptions": "wget https://raw.githubusercontent.com/vala-lang/valadoc-org/master/documentation/packages.xml"
+    "check": "tsc --noEmit"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/gjsify/ts-for-gir.git"
   },
-  "author": "Pascal Garber <pascal@artandcode.studio>",
+  "author": "Pascal Garber <pascal@mailfreun.de>",
   "files": [
-    "lib"
+    "src"
   ],
   "license": "Apache-2.0",
   "bugs": {
@@ -50,24 +41,20 @@
     "type definitions"
   ],
   "devDependencies": {
+    "@ts-for-gir/tsconfig": "^4.0.0-beta.41",
     "@types/ejs": "^3.1.5",
-    "@types/eslint": "8.56.10",
-    "@types/lodash": "^4.17.1",
-    "@types/node": "^20.12.8",
-    "@typescript-eslint/eslint-plugin": "^7.8.0",
-    "@typescript-eslint/parser": "^7.8.0",
-    "eslint": "^8.57.0",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-prettier": "^5.1.3",
-    "prettier": "^3.2.5",
-    "rimraf": "^5.0.5",
-    "typescript": "^5.4.5"
+    "@types/lodash": "^4.17.24",
+    "@types/node": "^24.12.0",
+    "rimraf": "^6.1.3",
+    "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@gi.ts/parser": "^2.0.0",
+    "@gi.ts/parser": "^4.0.0-beta.41",
+    "@ts-for-gir/reporter": "^4.0.0-beta.41",
+    "@ts-for-gir/templates": "^4.0.0-beta.41",
     "colorette": "^2.0.20",
-    "ejs": "^3.1.10",
-    "glob": "^10.3.12",
-    "lodash": "^4.17.21"
+    "ejs": "^5.0.1",
+    "glob": "^13.0.6",
+    "lodash": "^4.17.23"
   }
 }

package/src/constants.ts

@@ -0,0 +1,152 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { LibraryVersion } from "./library-version.ts";
+
+export const COMMENT_REG_EXP = /\/\*.*\*\//g;
+export const PARAM_REG_EXP = /[0-9a-zA-Z_]*:/g;
+export const OPT_PARAM_REG_EXP = /[0-9a-zA-Z_]*\?:/g;
+export const NEW_LINE_REG_EXP = /[\n\r]+/g;
+
+/**
+ * Package information interface for package.json
+ */
+interface Package {
+	name: string;
+	version: string;
+	description: string;
+	license: string;
+	homepage: string;
+	author: string;
+}
+
+/**
+ * Resolves the current package's package.json path
+ * Uses import.meta.url for ES Module compatibility
+ * Works both in workspace and after publishing
+ */
+function resolvePackageJson(): string {
+	try {
+		// Get the directory of the current module
+		const currentModulePath = fileURLToPath(import.meta.url);
+		const currentDir = dirname(currentModulePath);
+
+		// Go up to the package root (src/ -> package root)
+		const packageRoot = join(currentDir, "..");
+		const packageJsonPath = join(packageRoot, "package.json");
+
+		return packageJsonPath;
+	} catch (error) {
+		throw new Error(`Unable to resolve package.json path: ${error instanceof Error ? error.message : "Unknown error"}`);
+	}
+}
+
+/**
+ * Reads and parses the current package's package.json file synchronously
+ * Contains version and metadata for this specific package
+ */
+function readPackageSync(): Package {
+	try {
+		const packagePath = resolvePackageJson();
+		const content = readFileSync(packagePath, "utf-8");
+		return JSON.parse(content) as Package;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : "Unknown error";
+		throw new Error(`Failed to read package.json: ${message}`);
+	}
+}
+
+// Read package information once at module load
+export const PACKAGE = readPackageSync();
+
+export const APP_NAME = "ts-for-gir";
+export const APP_USAGE = "TypeScript type definition generator for GObject introspection GIR files";
+export const APP_SOURCE = "https://github.com/gjsify/ts-for-gir";
+export const APP_VERSION = PACKAGE.version;
+
+export const PACKAGE_DESC = (packageName: string, libraryVersion?: LibraryVersion) => {
+	if (libraryVersion) {
+		return `GJS TypeScript type definitions for ${packageName}, generated from library version ${libraryVersion.toString()}`;
+	}
+	return `GJS TypeScript type definitions for ${packageName}`;
+};
+export const PACKAGE_KEYWORDS = (packageName: string) => {
+	return `"Gir", "TypeScript", "types", "GObject-Introspection", "GJS", "${packageName}"`;
+};
+
+/** The reserved variable names listed here cannot be resolved simply by quotation marks */
+export const RESERVED_QUOTE_VARIABLE_NAMES = ["constructor"];
+
+export const RESERVED_VARIABLE_NAMES = [
+	"in",
+	"function",
+	"true",
+	"false",
+	"break",
+	"arguments",
+	"eval",
+	"default",
+	"new",
+	"extends",
+	"with",
+	"var",
+	"class",
+	"delete",
+	"return",
+	"constructor",
+	"this", // TODO check if this is used as we would use this in javascript, if so, this is only allowed as the first parameter
+];
+
+export const RESERVED_CLASS_NAMES = [
+	"break",
+	"boolean",
+	"case",
+	"catch",
+	"class",
+	"const",
+	"continue",
+	"debugger",
+	"default",
+	"delete",
+	"do",
+	"else",
+	"enum",
+	"export",
+	"extends",
+	"false",
+	"finally",
+	"for",
+	"function",
+	"if",
+	"implements",
+	"import",
+	"in",
+	"instanceof",
+	"interface",
+	"let",
+	"new",
+	"number",
+	"package",
+	"private",
+	"protected",
+	"public",
+	"return",
+	"static",
+	"super",
+	"switch",
+	"string",
+	"this",
+	"throw",
+	"true",
+	"try",
+	"typeof",
+	"var",
+	"void",
+	"while",
+	"with",
+	"yield",
+];
+
+export const RESERVED_FUNCTION_NAMES = ["false", "true", "break"];
+
+export const RESERVED_NAMESPACE_NAMES: Record<string, boolean> = {};

package/src/dependency-manager.ts

@@ -0,0 +1,445 @@
+import { readFile } from "node:fs/promises";
+import { type GirInclude, type GirNamespace, type GirRepository, type GirXML, parser } from "@gi.ts/parser";
+import { APP_VERSION } from "./constants.ts";
+import type { GirModule } from "./gir-module.ts";
+import { LibraryVersion } from "./library-version.ts";
+import { Logger } from "./logger.ts";
+import type { Dependency, FileInfo, OptionsGeneration } from "./types/index.ts";
+import { findFilesInDirs } from "./utils/files.ts";
+import { splitModuleName } from "./utils/girs.ts";
+import { sanitizeNamespace, transformImportName, transformModuleNamespaceName } from "./utils/naming.ts";
+import { pascalCase } from "./utils/strings.ts";
+
+export class DependencyManager {
+	protected log: Logger;
+	protected readonly config: OptionsGeneration;
+	protected _cache: { [packageName: string]: Dependency } = {};
+
+	static instances: { [key: string]: DependencyManager } = {};
+
+	protected constructor(config: OptionsGeneration) {
+		this.config = config;
+		this.log = new Logger(config.verbose, "DependencyManager");
+	}
+
+	/**
+	 * Get the DependencyManager singleton instance
+	 */
+	static getInstance(config?: OptionsGeneration): DependencyManager {
+		const configKey = config ? JSON.stringify(config) : Object.keys(DependencyManager.instances)[0];
+
+		if (DependencyManager.instances[configKey]) {
+			return DependencyManager.instances[configKey];
+		}
+
+		if (!config) {
+			throw new Error("config parameter is required to initialize DependencyManager");
+		}
+
+		const instance = new DependencyManager(config);
+		DependencyManager.instances[configKey] = instance;
+		return instance;
+	}
+
+	protected parsePackageName(namespaceOrPackageName: string, version?: string) {
+		let packageName: string;
+		let namespace: string;
+		if (version) {
+			namespace = namespaceOrPackageName;
+			packageName = `${namespace}-${version}`;
+		} else {
+			packageName = namespaceOrPackageName;
+			const { namespace: _namespace, version: _version } = splitModuleName(packageName);
+			namespace = _namespace;
+			version = _version;
+		}
+		return { packageName, namespace, version };
+	}
+
+	protected parseArgs(namespaceOrPackageNameOrRepo: string | GirRepository, version?: string, noOverride?: boolean) {
+		let packageName: string;
+		let namespace: string;
+		let repo: GirRepository | null = null;
+
+		if (typeof namespaceOrPackageNameOrRepo === "string") {
+			// Special case for Gjs
+			if (!noOverride && namespaceOrPackageNameOrRepo === "Gjs") {
+				return { ...this.getGjs(), repo: null };
+			}
+
+			const args = this.parsePackageName(namespaceOrPackageNameOrRepo, version);
+			version = args.version;
+			packageName = args.packageName;
+			namespace = args.namespace;
+		} else {
+			repo = namespaceOrPackageNameOrRepo;
+			const ns = repo.namespace?.[0];
+			if (!ns) {
+				throw new Error("Invalid GirRepository");
+			}
+			version = ns.$.version;
+			namespace = ns.$.name;
+			packageName = `${namespace}-${version}`;
+		}
+
+		return { packageName, namespace, version, repo };
+	}
+
+	/**
+	 * Get all dependencies in the cache
+	 * @returns All dependencies in the cache
+	 */
+	all(): Dependency[] {
+		return Object.values(this._cache);
+	}
+
+	getAllPackageNames(): string[] {
+		return Object.keys(this._cache);
+	}
+
+	/**
+	 * Get the core dependencies
+	 * @returns
+	 */
+	async core(): Promise<Dependency[]> {
+		return [
+			await this.get("GObject", "2.0"),
+			await this.get("GLib", "2.0"),
+			await this.get("Gio", "2.0"),
+			await this.get("cairo", "1.0"),
+		];
+	}
+
+	createImportProperties(namespace: string, packageName: string, version: string, libraryVersion?: LibraryVersion) {
+		const importPath = this.createImportPath(packageName, namespace, version);
+		const importDef = this.createImportDef(namespace, importPath);
+
+		// For GObject and Gio, use GLib's library version if available
+		let effectiveLibraryVersion = libraryVersion;
+		if ((namespace === "GObject" || namespace === "Gio") && this._cache["GLib-2.0"]) {
+			const glibDep = this._cache["GLib-2.0"];
+			if (glibDep.libraryVersion.toString() !== "0.0.0") {
+				effectiveLibraryVersion = glibDep.libraryVersion;
+			}
+		}
+
+		const packageJsonImport = this.createPackageJsonImport(importPath, effectiveLibraryVersion);
+		return {
+			importPath,
+			importDef,
+			packageJsonImport,
+		};
+	}
+
+	createImportPath(packageName: string, namespace: string, version: string): string {
+		if (!this.config.package) {
+			return `gi://${namespace}?version=${version}`;
+		}
+		const importName = transformImportName(packageName);
+		const importPath = `${this.config.npmScope}/${importName}`;
+		return importPath;
+	}
+
+	createImportDef(namespace: string, importPath: string): string {
+		return this.config.noNamespace
+			? `import type * as ${namespace} from '${importPath}'`
+			: `import type ${namespace} from '${importPath}';`;
+	}
+
+	createPackageJsonImport(importPath: string, libraryVersion?: LibraryVersion): string {
+		let depVersion: string;
+		if (this.config.workspace) {
+			depVersion = "workspace:^";
+		} else if (libraryVersion) {
+			depVersion = `${libraryVersion.toString()}-${APP_VERSION}`;
+		} else {
+			depVersion = APP_VERSION;
+		}
+		return `"${importPath}": "${depVersion}"`;
+	}
+
+	protected async parseGir(path: string) {
+		const girXML = parser.parseGir(await readFile(path, "utf8"));
+		const repo = girXML.repository[0];
+		const ns = repo?.namespace?.[0];
+		const version = ns?.$.version;
+		return { girXML, repo, ns, version };
+	}
+
+	protected async parseGirAndReturnLatestVersion(filesInfo: FileInfo[]) {
+		const libraryVersions: { libraryVersion: LibraryVersion; girXML: GirXML; fileInfo: FileInfo }[] = [];
+
+		if (filesInfo.length > 1) {
+			this.log.warn(`Multiple paths found for ${filesInfo[0].filename}`);
+		}
+
+		for (const fileInfo of filesInfo) {
+			if (!fileInfo.exists || !fileInfo.path) {
+				continue;
+			}
+			const { girXML, ns, version } = await this.parseGir(fileInfo.path);
+			if (!version || !ns) {
+				continue;
+			}
+
+			const libraryVersion = new LibraryVersion(ns?.constant, version);
+
+			if (filesInfo.length > 1) {
+				this.log.muted(` - ${fileInfo.path} (${libraryVersion.toString()})`);
+			}
+
+			libraryVersions.push({
+				libraryVersion,
+				girXML,
+				fileInfo,
+			});
+		}
+		// Compare all library versions and return the latest version
+		const latestLibraryVersion = libraryVersions.sort((a, b) => a.libraryVersion.compare(b.libraryVersion))[0];
+
+		if (!latestLibraryVersion) {
+			this.log.warn("No latest library version found", {
+				libraryVersions,
+				filesInfo,
+			});
+			return {
+				libraryVersion: new LibraryVersion(),
+				girXML: null,
+				fileInfo: filesInfo[0],
+			};
+		}
+
+		if (filesInfo.length > 1) {
+			this.log.muted(
+				`Use latest version ${latestLibraryVersion.libraryVersion.toString()} from ${latestLibraryVersion.fileInfo.path}`,
+			);
+		}
+
+		return latestLibraryVersion;
+	}
+
+	/**
+	 * Get the dependency object by packageName
+	 * @param packageName The package name (with version affix) of the dependency
+	 * @returns The dependency object
+	 */
+	async get(packageName: string): Promise<Dependency>;
+	/**
+	 * Get the dependency object by namespace and version
+	 * @param namespace The namespace of the dependency
+	 * @param version The version of the dependency
+	 * @returns The dependency object
+	 */
+	async get(namespace: string, version: string, noOverride?: boolean): Promise<Dependency>;
+	/**
+	 * Get the dependency object by {@link GirRepository}
+	 * @param namespace The namespace of the dependency
+	 * @param version The version of the dependency
+	 * @returns The dependency object
+	 */
+	async get(repo: GirRepository, version?: string, noOverride?: boolean): Promise<Dependency>;
+	async get(
+		namespaceOrPackageNameOrRepo: string | GirRepository,
+		_version?: string,
+		noOverride?: boolean,
+	): Promise<Dependency> {
+		const parsedArgs = this.parseArgs(namespaceOrPackageNameOrRepo, _version, noOverride);
+		const { packageName, repo } = parsedArgs;
+		let { namespace, version } = parsedArgs;
+		namespace = sanitizeNamespace(namespace);
+
+		if (this._cache[packageName]) {
+			const dep = this._cache[packageName];
+			return dep;
+		}
+		const filename = `${packageName}.gir`;
+		const filesInfo = await findFilesInDirs(this.config.girDirectories, filename);
+
+		const { libraryVersion, girXML, fileInfo } = await this.parseGirAndReturnLatestVersion(filesInfo);
+
+		const ns = (girXML?.repository[0]?.namespace?.[0] || repo?.namespace?.[0] || null) as GirNamespace | null;
+
+		// Use the version from the gir file if it exists
+		if (ns?.$.version) {
+			version = ns?.$.version;
+		}
+		if (ns?.$.name) {
+			namespace = ns?.$.name;
+		}
+
+		const dependency: Dependency = {
+			...fileInfo,
+			namespace,
+			packageName,
+			importName: transformImportName(packageName),
+			importNamespace: transformModuleNamespaceName(packageName),
+			version,
+			libraryVersion,
+			girXML,
+			...this.createImportProperties(namespace, packageName, version, libraryVersion),
+		};
+
+		// Special case for Cairo
+		// This is a special case for Cairo because Cairo in GJS is provided as a built-in module that doesn't
+		// follow the standard GI repository pattern.
+		// So we need to special case it and redirect to the 'cairo' package.
+		// This changes the typescript import definition to use the internal 'cairo' package instead of the 'cairo-1.0' Gir package.
+		if (!noOverride && namespace === "cairo" && version === "1.0") {
+			dependency.importDef = this.createImportDef("cairo", "cairo");
+		}
+
+		this._cache[packageName] = dependency;
+
+		return dependency;
+	}
+
+	/**
+	 * Get all dependencies with the given namespace
+	 * @param namespace The namespace of the dependency
+	 * @returns All dependencies with the given namespace
+	 */
+	list(namespace: string): Dependency[] {
+		const packageNames = this.all();
+		const candidates = packageNames.filter((dep) => {
+			return dep.namespace === namespace && dep.exists;
+		});
+		return candidates;
+	}
+
+	/**
+	 * Get girModule for dependency
+	 * @param girModules
+	 * @param packageName
+	 */
+	getModule(girModules: GirModule[], dep: Dependency): GirModule | undefined {
+		return girModules.find(
+			(m) => m.packageName === dep.packageName && m.namespace === dep.namespace && m.version === dep.version,
+		);
+	}
+
+	/**
+	 * Add all dependencies from an array of gir modules
+	 * @param girModules
+	 */
+	async addAll(girModules: GirModule[]): Promise<Dependency[]> {
+		for (const girModule of girModules) {
+			await this.get(girModule.namespace, girModule.version || "0.0");
+		}
+		return this.all();
+	}
+
+	/**
+	 * Transforms a gir include object array to a dependency object array
+	 * @param girIncludes - Array of gir includes
+	 * @returns Array of dependencies
+	 */
+	async fromGirIncludes(girIncludes: GirInclude[]): Promise<Dependency[]> {
+		const dependencies: Dependency[] = [];
+		for (const i of girIncludes) {
+			dependencies.unshift(await this.get(i.$.name, i.$.version || "0.0"));
+		}
+		return dependencies;
+	}
+
+	/**
+	 * Check if multiple dependencies with the given namespace exist in the cache
+	 * @param namespace The namespace of the dependency
+	 * @returns
+	 */
+	hasConflict(namespace: string): boolean {
+		const packageNames = this.getAllPackageNames();
+		const candidates = packageNames.filter((packageName) => {
+			return packageName.startsWith(`${namespace}-`) && this._cache[packageName].namespace === namespace;
+		});
+
+		return candidates.length > 1;
+	}
+
+	/**
+	 * get the latest version of the dependency with the given namespace
+	 * @param namespace The namespace of the dependency
+	 * @returns The latest version of the dependency
+	 */
+	getLatestVersion(namespace: string): Dependency | undefined {
+		const candidates = this.list(namespace);
+		const latestVersion = candidates
+			.sort((a, b) => {
+				return a.version.localeCompare(b.version);
+			})
+			.pop();
+		return latestVersion;
+	}
+
+	/**
+	 * Check if the given version is the latest version of the dependency
+	 * @param namespace The namespace of the dependency
+	 * @param version The version of the dependency
+	 * @returns
+	 */
+	isLatestVersion(namespace: string, version: string): boolean {
+		const latestVersion = this.getLatestVersion(namespace);
+		return latestVersion?.version === version;
+	}
+
+	/**
+	 * Find a dependency by it's namespace from the cache, if multiple versions are found, the latest version is returned
+	 * @param namespace The namespace of the dependency
+	 * @returns The dependency object or null if not found
+	 */
+	find(namespace: string): Dependency | null {
+		// Special case for Gjs
+		if (namespace === "Gjs") {
+			return this.getGjs();
+		}
+
+		const packageNames = this.getAllPackageNames();
+		const candidates = packageNames.filter((packageName) => {
+			return packageName.startsWith(`${namespace}-`) && this._cache[packageName].namespace === namespace;
+		});
+
+		if (candidates.length > 1) {
+			this.log.warn(`Found multiple versions of ${namespace}: ${candidates.join(", ")}`);
+		}
+
+		const latestVersion = candidates.sort().pop();
+
+		if (latestVersion && this._cache[latestVersion]) {
+			const dep = this._cache[latestVersion];
+			return dep;
+		}
+
+		return null;
+	}
+
+	protected getPseudoPackage(
+		packageName: string,
+		namespace: string = pascalCase(packageName),
+		version = "2.0",
+	): Dependency {
+		if (this._cache[`${packageName}_pseudo`]) {
+			return this._cache[`${packageName}_pseudo`];
+		}
+
+		const dep: Dependency = {
+			namespace,
+			exists: true,
+			filename: "",
+			path: "",
+			packageName: packageName,
+			importName: transformImportName(packageName),
+			importNamespace: transformModuleNamespaceName(packageName),
+			version,
+			libraryVersion: new LibraryVersion(),
+			girXML: null,
+			...this.createImportProperties(packageName, packageName, version),
+		};
+
+		this._cache[`${packageName}_pseudo`] = dep;
+
+		return dep;
+	}
+
+	getGjs(): Dependency {
+		return this.getPseudoPackage("Gjs");
+	}
+}

package/src/formatters/default.ts

@@ -0,0 +1,7 @@
+import { Formatter } from "./formatter.ts";
+
+export class DefaultFormatter extends Formatter {
+	format(source: string): Promise<string> {
+		return Promise.resolve(source);
+	}
+}