@ts-for-gir/lib 4.0.0-beta.9 → 4.0.0-rc.10

package/src/types/package-data.ts

@@ -0,0 +1,24 @@
+import type { PackageSectionParsed } from "./index.ts";
+
+export interface PackageData {
+	/** Namespace of this package, e.g. Gtk */
+	namespace: string;
+	/** Version of this package, e.g. 4.0 */
+	version: string;
+	/** Description of this package */
+	description: string;
+	/** Gir package name with version string */
+	gir?: string;
+	/** URL to the homepage of this package */
+	home?: string;
+	/** URL to a gallery of widgets of this package */
+	gallery?: string;
+	/** URL to the source code of this package */
+	cDocs?: string;
+	/** True if this package is deprecated */
+	deprecated?: boolean;
+	/** Name of the Maintainer of this package */
+	maintainers?: string;
+	/** The section of this package */
+	section?: PackageSectionParsed;
+}

package/src/types/package-section-parsed.ts

@@ -0,0 +1,9 @@
+import type { PackageDataParsed } from "./index.ts";
+
+export interface PackageSectionParsed {
+	$: {
+		name: string;
+	};
+	package?: PackageDataParsed[];
+	section?: PackageSectionParsed[];
+}

package/src/types/parsed-gir.ts

@@ -0,0 +1,5 @@
+import type { GirRepository, GirXML } from "@gi.ts/parser";
+
+export interface ParsedGir extends GirXML {
+	repository: GirRepository[];
+}

package/src/types/parsed-package-data.ts

@@ -0,0 +1,7 @@
+import type { PackageSectionParsed } from "./index.ts";
+
+export interface ParsedPackageData {
+	packages: {
+		section: PackageSectionParsed[];
+	};
+}

package/src/types/property-case.ts

@@ -0,0 +1 @@
+export type PropertyCase = "both" | "camel" | "underscore";

package/src/types/resolve-type.ts

@@ -0,0 +1,4 @@
+export enum ResolveType {
+	DEPENDENCE,
+	BY_HAND,
+}

package/src/types/template-data.ts

@@ -0,0 +1,8 @@
+import type { Data } from "ejs";
+import type { GirModule } from "../gir-module.ts";
+import type { OptionsGeneration } from "./options-generation.ts";
+
+export interface TemplateData extends Data, Partial<OptionsGeneration> {
+	girModule?: GirModule;
+	importName?: string;
+}

package/src/types/template-options.ts

@@ -0,0 +1,33 @@
+import type ejs from "ejs";
+
+/**
+ * Configuration options for template rendering
+ */
+export interface TemplateRenderOptions {
+	/** EJS rendering options */
+	ejsOptions?: Partial<ejs.Options>;
+	/** Whether to include append templates */
+	includeAppend?: boolean;
+	/** Custom template directory override */
+	templateDir?: string;
+}
+
+/**
+ * Result of template loading operation
+ */
+export interface TemplateLoadResult {
+	/** Main template content */
+	prepend: string;
+	/** Append template content (if exists) */
+	append: string;
+}
+
+/**
+ * Template file processing result
+ */
+export interface TemplateFileResult {
+	/** The rendered template content */
+	content: string;
+	/** The output file path */
+	outputPath: string;
+}

package/src/types/transformation-case.ts

@@ -0,0 +1,9 @@
+export type TransformationCase =
+	| "original"
+	| "lowerCamelCase"
+	| "upperCamelCase"
+	| "upperCase"
+	| "lowerCase"
+	| "underscores"
+	| "snakeCase"
+	| "slugCase";

package/src/types/transformations.ts

@@ -0,0 +1,5 @@
+import type { TransformationCase } from "./transformation-case.ts";
+
+export interface Transformations {
+	[type: string]: TransformationCase;
+}

package/{lib/types/ts-doc-tag.d.ts → src/types/ts-doc-tag.ts}

@@ -6,16 +6,18 @@
  * Inspirited from https://github.com/TypeStrong/typedoc/blob/master/src/lib/models/comments/tag.ts
  */
 export interface TsDocTag {
-    /**
-     * The name of this tag.
-     */
-    tagName: string;
-    /**
-     * The name of the related parameter when this is a ```@param``` tag.
-     */
-    paramName: string;
-    /**
-     * The actual body text of this tag.
-     */
-    text: string;
+	/**
+	 * The name of this tag.
+	 */
+	tagName: string;
+
+	/**
+	 * The name of the related parameter when this is a ```@param``` tag.
+	 */
+	paramName: string;
+
+	/**
+	 * The actual body text of this tag.
+	 */
+	text: string;
 }

package/src/types/ts-doc.ts

@@ -0,0 +1,18 @@
+import type { TsDocTag } from "./ts-doc-tag.ts";
+
+/**
+ * A model that represents a comment.
+ *
+ * Inspirited from https://github.com/TypeStrong/typedoc/blob/master/src/lib/models/comments/comment.ts
+ */
+export interface TsDoc {
+	/**
+	 * The full body text of the comment..
+	 */
+	text: string;
+
+	/**
+	 * All associated tags.
+	 */
+	tags: TsDocTag[];
+}

package/{lib/types/type-gir-alias.d.ts → src/types/type-gir-alias.ts}

@@ -1,2 +1,2 @@
 /** All gir elements which can be a typescript `type` */
-export type TypeGirAlias = 'alias';
+export type TypeGirAlias = "alias";

package/src/types/type-gir-class.ts

@@ -0,0 +1,2 @@
+/** All gir elements which can be a typescript class */
+export type TypeGirClass = "class" | "record" | "interface" | "union";

package/src/types/type-gir-element.ts

@@ -0,0 +1,25 @@
+import type {
+	TypeGirAlias,
+	TypeGirClass,
+	TypeGirEnumeration,
+	TypeGirEnumerationMember,
+	TypeGirFunction,
+	TypeGirInterface,
+	TypeGirMethod,
+	TypeGirParameter,
+	TypeGirProperty,
+	TypeGirVariable,
+} from "./index.ts";
+
+/** Any gir element type */
+export type TypeGirElement =
+	| TypeGirClass
+	| TypeGirMethod
+	| TypeGirVariable
+	| TypeGirAlias
+	| TypeGirEnumeration
+	| TypeGirEnumerationMember
+	| TypeGirInterface
+	| TypeGirParameter
+	| TypeGirProperty
+	| TypeGirFunction;

package/src/types/type-gir-enumeration-member.ts

@@ -0,0 +1,2 @@
+/** All gir elements which can be a typescript enumeration */
+export type TypeGirEnumerationMember = "enum-member" | "bitfield-member";

package/{lib/types/type-gir-enumeration.d.ts → src/types/type-gir-enumeration.ts}

@@ -1,2 +1,2 @@
 /** All gir elements which can be a typescript enumeration */
-export type TypeGirEnumeration = 'enum' | 'bitfield';
+export type TypeGirEnumeration = "enum" | "bitfield";

package/src/types/type-gir-function.ts

@@ -0,0 +1,8 @@
+export type TypeGirFunction =
+	| "constructor"
+	| "function"
+	| "method"
+	| "static-function"
+	| "signal"
+	| "virtual"
+	| "callback";

package/{lib/types/type-gir-interface.d.ts → src/types/type-gir-interface.ts}

@@ -1,2 +1,2 @@
 /** All gir elements which can be a typescript interface */
-export type TypeGirInterface = 'callback';
+export type TypeGirInterface = "callback";

package/src/types/type-gir-method.ts

@@ -0,0 +1,2 @@
+/** All gir elements which can be a typescript method (or static function) of a class */
+export type TypeGirMethod = "virtual" | "signal" | "method" | "constructor" | "function" | "static";

package/src/types/type-gir-parameter.ts

@@ -0,0 +1 @@
+export type TypeGirParameter = "callable-param";

package/{lib/types/type-gir-property.d.ts → src/types/type-gir-property.ts}

@@ -1,2 +1,2 @@
 /** All gir elements which can be a typescript field / property */
-export type TypeGirProperty = 'property' | 'field' | 'constant';
+export type TypeGirProperty = "property" | "field" | "constant";

package/src/types/type-gir-variable.ts

@@ -0,0 +1 @@
+export type TypeGirVariable = "constant";

package/src/types/type-ts-element.ts

@@ -0,0 +1,13 @@
+import type { TypeTsFunction, TypeTsProperty } from "./index.ts";
+
+/** Any typescript element type */
+export type TypeTsElement =
+	| "class"
+	| "interface"
+	| "enum"
+	| "enum-member"
+	| "constant"
+	| "event-methods"
+	| "type"
+	| TypeTsFunction
+	| TypeTsProperty;

package/{lib/types/type-ts-enumeration-member.d.ts → src/types/type-ts-enumeration-member.ts}

@@ -1,2 +1,2 @@
 /** All gir elements which can be a typescript enumeration */
-export type TypeTsEnumerationMember = 'enum-member';
+export type TypeTsEnumerationMember = "enum-member";

package/src/types/type-ts-function.ts

@@ -0,0 +1 @@
+export type TypeTsFunction = "static-function" | "constructor" | "function" | "method" | "event-methods" | "interface";

package/src/types/type-ts-property.ts

@@ -0,0 +1 @@
+export type TypeTsProperty = "static-property" | "property" | "constructor-property";

package/src/types/user-config-load-result.ts

@@ -0,0 +1,6 @@
+import type { UserConfig } from "./user-config.ts";
+export interface UserConfigLoadResult {
+	config: Partial<UserConfig>;
+	filepath: string;
+	isEmpty?: boolean | undefined;
+}

package/src/types/user-config.ts

@@ -0,0 +1,100 @@
+/**
+ * Types for config file
+ */
+export interface UserConfig {
+	/** root / working directory of your project */
+	root: string;
+	/** directory to output to */
+	outdir: string | null;
+	/** GIR directories */
+	girDirectories: string[];
+	/** Switch on/off the verbose mode */
+	verbose: boolean;
+	/** Do not ask for package versions if multiple versions are found */
+	ignoreVersionConflicts: boolean;
+	/** print the output to console and create no files */
+	print: boolean;
+	/** GIR modules to load, e.g. 'Gio-2.0'. Accepts multiple modules */
+	modules: string[];
+	/** modules that should be ignored */
+	ignore?: string[];
+	/** Do not export all symbols for each module as a namespace */
+	noNamespace: boolean;
+	/** Do not generate documentation comments */
+	noComments: boolean;
+	/** Generate promisified functions for async/finish calls */
+	promisify: boolean;
+	/** Scope of the generated NPM packages */
+	npmScope: string;
+	/** Uses the workspace protocol for the generated packages which can be used with package managers like Yarn and PNPM */
+	workspace: boolean;
+	/**
+	 * Format used for dependency version specifiers in generated package.json files.
+	 * - `workspace`: emit `workspace:^` (yarn/pnpm; npm only when the ref matches a registered workspace)
+	 * - `caret`: emit `^<version>` (all managers, falls back to registry for dangling refs)
+	 * - `any`: emit `*` (all managers, most permissive)
+	 * - `exact`: emit `<version>` (all managers, no range)
+	 *
+	 * If unset, defaults to `workspace` when `workspace: true`, else `caret`.
+	 */
+	depVersionFormat?: "workspace" | "caret" | "any" | "exact";
+	/**
+	 * Only use the version prefix for the ambient module exports.
+	 * This is useful if, for whatever reason, you want to use different library versions of the same library in your project.
+	 *
+	 * @example
+	 * ```ts
+	 * declare module 'gi://Gtk?version=4.0' {...}
+	 * declare module 'gi://Gtk?version=3.0' {...}
+	 * ```
+	 */
+	onlyVersionPrefix: boolean;
+	/** Do not prettify the generated types */
+	noPrettyPrint: boolean;
+	/** Disable GLib.Variant class with string parsing */
+	noAdvancedVariants: boolean;
+	/**
+	 * Generate the typescript types with package.json support
+	 */
+	package: boolean;
+	/**
+	 * Enable generation problem reporter and create a detailed report file
+	 */
+	reporter: boolean;
+	/**
+	 * Output file path for the reporter
+	 */
+	reporterOutput: string;
+	/** Generate a single unified documentation for all modules instead of separate per-module docs */
+	combined?: boolean;
+	/** URL template for source links in generated documentation. Supports {path}, {line}, {gitRevision} placeholders */
+	sourceLinkTemplate?: string;
+	/** Theme for HTML documentation generation (default: "gi-docgen") */
+	theme?: string;
+	/** Path to a README file to use as the documentation index page (default: "none") */
+	readme?: string;
+	/** Use TypeDoc merge mode to generate HTML from pre-generated JSON files */
+	merge?: boolean;
+	/** Directory containing pre-generated TypeDoc JSON files for merge mode (from 'ts-for-gir json') */
+	jsonDir?: string;
+	/**
+	 * External-deps mode: emit `import` statements that reference dependency types from
+	 * already-installed npm packages (e.g. `@girs/glib-2.0`) instead of regenerating them.
+	 * Designed for project-local GIRs (Vala bridges etc.) where the surrounding `@girs/*`
+	 * ecosystem is already in node_modules.
+	 */
+	externalDeps: boolean;
+	/**
+	 * Allow `externalDeps` generation to proceed when some transitive dep GIRs are missing.
+	 * Default is strict: missing deps cause an error to prevent silent type-quality drift
+	 * between environments with and without system GIR -devel packages installed.
+	 */
+	allowMissingDeps: boolean;
+	/**
+	 * Override the default `<npmScope>/<importName>` mapping for individual namespaces when
+	 * resolving external dependency imports in `externalDeps` mode.
+	 *
+	 * Example: `{ Soup: '@girs/soup-3.0', GLib: '@girs/glib-2.0' }`
+	 */
+	externalPackages?: Record<string, string>;
+}

package/src/util.ts

@@ -0,0 +1,84 @@
+/**
+ * A simple two-key map.
+ */
+export class TwoKeyMap<K1, K2, V> {
+	private baseMap = new Map<K1, Map<K2, V>>();
+
+	forEach(op: (v: V) => void) {
+		this.baseMap.forEach((map) => {
+			map.forEach((v) => {
+				op(v);
+			});
+		});
+	}
+
+	has(key1: K1, key2: K2): boolean {
+		const obj = this.baseMap.get(key1);
+
+		if (!obj) {
+			return false;
+		}
+
+		return obj.has(key2);
+	}
+
+	getIfOnly(key1: K1): readonly [K2, V] | undefined {
+		const obj = this.baseMap.get(key1);
+
+		if (!obj) {
+			return undefined;
+		}
+
+		if (obj.size === 1) {
+			const [k2] = obj.keys();
+			const v = obj.get(k2);
+
+			if (!v) {
+				return undefined;
+			}
+
+			return [k2, v] as const;
+		}
+
+		return undefined;
+	}
+
+	get(key1: K1, key2: K2): V | undefined {
+		const obj = this.baseMap.get(key1);
+
+		if (!obj) {
+			return undefined;
+		}
+
+		return obj.get(key2);
+	}
+
+	set(key1: K1, key2: K2, value: V): void {
+		let obj = this.baseMap.get(key1);
+
+		if (!obj) {
+			obj = new Map<K2, V>();
+
+			this.baseMap.set(key1, obj);
+		}
+
+		obj.set(key2, value);
+	}
+}
+
+/**
+ * If the predicate returns a value other than undefined,
+ * that value is returned. It combines the .find() and
+ * .map() APIs for convenience.
+ *
+ * @param arr
+ * @param predicate
+ */
+export function findMap<T, K>(arr: T[], predicate: (p: T) => K | undefined): K | undefined {
+	for (const a of arr) {
+		const val = predicate(a);
+		if (val !== undefined) return val;
+	}
+
+	return undefined;
+}

package/src/utils/conflicts/conflict-resolver.ts

@@ -0,0 +1,122 @@
+import type { IntrospectedClassMember } from "../../gir/introspected-class-member.ts";
+import type { IntrospectedBaseClass, IntrospectedClassFunction } from "../../gir/introspected-classes.ts";
+import type { IntrospectedNamespace } from "../../gir/namespace.ts";
+import { IntrospectedProperty } from "../../gir/property.ts";
+import type { TypeIdentifier } from "../../gir.ts";
+import { ConflictType, TypeConflict } from "../../gir.ts";
+
+/**
+ * Detects what type of conflict a class member has, if any
+ */
+export function detectConflictType<
+	T extends IntrospectedClassMember | IntrospectedClassFunction | IntrospectedProperty,
+>(
+	namespace: IntrospectedNamespace,
+	clazz: IntrospectedBaseClass,
+	element: T,
+	thisType: TypeIdentifier,
+): ConflictType | undefined {
+	// Check field conflicts
+	const fieldConflict = checkFieldConflicts(clazz, element);
+	if (fieldConflict) {
+		return fieldConflict;
+	}
+
+	// Check property conflicts
+	const propertyConflict = checkPropertyConflicts(namespace, clazz, element, thisType);
+	if (propertyConflict) {
+		return propertyConflict;
+	}
+
+	// Check function name conflicts
+	return checkFunctionNameConflicts(namespace, clazz, element, thisType);
+}
+
+/**
+ * Creates a conflict element wrapper for the given element
+ */
+export function createConflictElement<
+	T extends IntrospectedClassMember | IntrospectedClassFunction | IntrospectedProperty,
+>(element: T, conflictType: ConflictType): T | null {
+	if (element instanceof IntrospectedProperty) {
+		const conflictProperty = element.copy();
+		conflictProperty.type = new TypeConflict(conflictProperty.type, conflictType);
+		return conflictProperty as T;
+	}
+
+	// For other types, we might need to implement specific conflict handling
+	// For now, return the original element
+	return element;
+}
+
+function checkFieldConflicts<T extends IntrospectedClassMember | IntrospectedClassFunction | IntrospectedProperty>(
+	clazz: IntrospectedBaseClass,
+	element: T,
+): ConflictType | undefined {
+	if (!element.name) {
+		return undefined;
+	}
+
+	const hasFieldConflict = clazz.fields.some((field) => field.name === element.name);
+
+	if (hasFieldConflict) {
+		if (element instanceof IntrospectedProperty) {
+			return ConflictType.PROPERTY_NAME_CONFLICT;
+		}
+		return ConflictType.FIELD_NAME_CONFLICT;
+	}
+
+	return undefined;
+}
+
+function checkPropertyConflicts<T extends IntrospectedClassMember | IntrospectedClassFunction | IntrospectedProperty>(
+	_namespace: IntrospectedNamespace,
+	clazz: IntrospectedBaseClass,
+	element: T,
+	_thisType: TypeIdentifier,
+): ConflictType | undefined {
+	if (!element.name) {
+		return undefined;
+	}
+
+	const hasPropertyConflict = clazz.props.some((property) => property.name === element.name && property !== element);
+
+	if (hasPropertyConflict) {
+		// Check if this is an accessor property conflict
+		if (isAccessorProperty(element)) {
+			return ConflictType.ACCESSOR_PROPERTY_CONFLICT;
+		}
+		return ConflictType.PROPERTY_ACCESSOR_CONFLICT;
+	}
+
+	return undefined;
+}
+
+function checkFunctionNameConflicts<
+	T extends IntrospectedClassMember | IntrospectedClassFunction | IntrospectedProperty,
+>(
+	_namespace: IntrospectedNamespace,
+	clazz: IntrospectedBaseClass,
+	element: T,
+	_thisType: TypeIdentifier,
+): ConflictType | undefined {
+	if (!element.name) {
+		return undefined;
+	}
+
+	const hasFunctionConflict = clazz.members.some((member) => member.name === element.name && member !== element);
+
+	if (hasFunctionConflict) {
+		return ConflictType.FUNCTION_NAME_CONFLICT;
+	}
+
+	return undefined;
+}
+
+function isAccessorProperty(
+	element: IntrospectedClassMember | IntrospectedClassFunction | IntrospectedProperty,
+): boolean {
+	// Check if the element is an accessor property
+	// This is a simplified check - in practice, you might need more sophisticated logic
+	return element instanceof IntrospectedProperty && element.readable && element.writable;
+}