@fuzdev/fuz_util 0.42.0

package/dist/source_json.d.ts

@@ -0,0 +1,375 @@
+/**
+ * Metadata types for library source code analysis.
+ *
+ * These types represent the structure of `src/lib/` exports,
+ * extracted at build time via TypeScript compiler analysis.
+ * Used for generating API documentation and enabling code search.
+ *
+ * Hierarchy: SourceJson → ModuleJson → DeclarationJson
+ */
+import { z } from 'zod';
+/**
+ * The kind of exported declaration.
+ */
+export declare const DeclarationKind: z.ZodEnum<{
+    function: "function";
+    type: "type";
+    json: "json";
+    variable: "variable";
+    class: "class";
+    constructor: "constructor";
+    component: "component";
+    css: "css";
+}>;
+export type DeclarationKind = z.infer<typeof DeclarationKind>;
+/**
+ * Generic type parameter information.
+ */
+export declare const GenericParamInfo: z.ZodObject<{
+    /** Parameter name like `T`. */
+    name: z.ZodString;
+    /** Constraint like `string` from `T extends string`. */
+    constraint: z.ZodOptional<z.ZodString>;
+    /** Default type like `unknown` from `T = unknown`. */
+    default_type: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type GenericParamInfo = z.infer<typeof GenericParamInfo>;
+/**
+ * Parameter information for functions and methods.
+ *
+ * Kept distinct from ComponentPropInfo despite structural similarity.
+ * Function parameters form a tuple with positional semantics:
+ * calling order matters (`fn(a, b)` vs `fn(b, a)`),
+ * may include rest parameters and destructuring patterns.
+ */
+export declare const ParameterInfo: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodString;
+    optional: z.ZodOptional<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodString>;
+    default_value: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type ParameterInfo = z.infer<typeof ParameterInfo>;
+/**
+ * Component prop information for Svelte components.
+ *
+ * Kept distinct from ParameterInfo despite structural similarity.
+ * Component props are named attributes with different semantics:
+ * no positional order when passing (`<Foo {a} {b} />` = `<Foo {b} {a} />`),
+ * support two-way binding via `$bindable` rune.
+ */
+export declare const ComponentPropInfo: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodString;
+    optional: z.ZodOptional<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodString>;
+    default_value: z.ZodOptional<z.ZodString>;
+    bindable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+export type ComponentPropInfo = z.infer<typeof ComponentPropInfo>;
+/**
+ * Metadata for an exported declaration (function, type, class, component, etc.).
+ *
+ * Extracted from TypeScript source and JSDoc/TSDoc comments at build time.
+ */
+export declare const DeclarationJson: z.ZodObject<{
+    /** The exported name. */
+    name: z.ZodString;
+    kind: z.ZodEnum<{
+        function: "function";
+        type: "type";
+        json: "json";
+        variable: "variable";
+        class: "class";
+        constructor: "constructor";
+        component: "component";
+        css: "css";
+    }>;
+    /** JSDoc/TSDoc comment in mdz format. */
+    doc_comment: z.ZodOptional<z.ZodString>;
+    /** Full TypeScript type signature. */
+    type_signature: z.ZodOptional<z.ZodString>;
+    /** TypeScript modifiers like `readonly`, `private`, or `static`. */
+    modifiers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    /** 1-indexed line number in source file. */
+    source_line: z.ZodOptional<z.ZodNumber>;
+    /** Function/method parameters. */
+    parameters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodString;
+        optional: z.ZodOptional<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodString>;
+        default_value: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    /** Function/method return type. */
+    return_type: z.ZodOptional<z.ZodString>;
+    /** Return value description from `@returns` tag. */
+    return_description: z.ZodOptional<z.ZodString>;
+    /** Generic type parameters like `<T, U>`. */
+    generic_params: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        /** Parameter name like `T`. */
+        name: z.ZodString;
+        /** Constraint like `string` from `T extends string`. */
+        constraint: z.ZodOptional<z.ZodString>;
+        /** Default type like `unknown` from `T = unknown`. */
+        default_type: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    /** Code examples from `@example` tags. */
+    examples: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    /** Deprecation message from `@deprecated` tag. */
+    deprecated_message: z.ZodOptional<z.ZodString>;
+    /** Related items from `@see` tags, in mdz format. */
+    see_also: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    /** Exceptions from `@throws` tags. */
+    throws: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodOptional<z.ZodString>;
+        description: z.ZodString;
+    }, z.core.$loose>>>;
+    /** Version introduced, from `@since` tag. */
+    since: z.ZodOptional<z.ZodString>;
+    /** Extended classes/interfaces. */
+    extends: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    /** Implemented interfaces. */
+    implements: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    /** Class or interface members (recursive). */
+    readonly members: z.ZodOptional<z.ZodArray<z.ZodObject</*elided*/ any, z.core.$loose>>>;
+    /** Type/interface properties (recursive). */
+    readonly properties: z.ZodOptional<z.ZodArray<z.ZodObject</*elided*/ any, z.core.$loose>>>;
+    /** Svelte component props. */
+    props: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodString;
+        optional: z.ZodOptional<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodString>;
+        default_value: z.ZodOptional<z.ZodString>;
+        bindable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>>;
+    /**
+     * Module paths (relative to src/lib) that re-export this declaration.
+     * The canonical location is this module's `declarations` array.
+     */
+    also_exported_from: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    /**
+     * For renamed re-exports (`export {foo as bar}`), the original declaration.
+     */
+    alias_of: z.ZodOptional<z.ZodObject<{
+        module: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$loose>;
+export type DeclarationJson = z.infer<typeof DeclarationJson>;
+/**
+ * A source file in `src/lib/` with its exported declarations.
+ */
+export declare const ModuleJson: z.ZodObject<{
+    /** Path relative to src/lib (e.g., `helpers.ts`). */
+    path: z.ZodString;
+    declarations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        /** The exported name. */
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            function: "function";
+            type: "type";
+            json: "json";
+            variable: "variable";
+            class: "class";
+            constructor: "constructor";
+            component: "component";
+            css: "css";
+        }>;
+        /** JSDoc/TSDoc comment in mdz format. */
+        doc_comment: z.ZodOptional<z.ZodString>;
+        /** Full TypeScript type signature. */
+        type_signature: z.ZodOptional<z.ZodString>;
+        /** TypeScript modifiers like `readonly`, `private`, or `static`. */
+        modifiers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        /** 1-indexed line number in source file. */
+        source_line: z.ZodOptional<z.ZodNumber>;
+        /** Function/method parameters. */
+        parameters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodString;
+            optional: z.ZodOptional<z.ZodBoolean>;
+            description: z.ZodOptional<z.ZodString>;
+            default_value: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+        /** Function/method return type. */
+        return_type: z.ZodOptional<z.ZodString>;
+        /** Return value description from `@returns` tag. */
+        return_description: z.ZodOptional<z.ZodString>;
+        /** Generic type parameters like `<T, U>`. */
+        generic_params: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            /** Parameter name like `T`. */
+            name: z.ZodString;
+            /** Constraint like `string` from `T extends string`. */
+            constraint: z.ZodOptional<z.ZodString>;
+            /** Default type like `unknown` from `T = unknown`. */
+            default_type: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+        /** Code examples from `@example` tags. */
+        examples: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        /** Deprecation message from `@deprecated` tag. */
+        deprecated_message: z.ZodOptional<z.ZodString>;
+        /** Related items from `@see` tags, in mdz format. */
+        see_also: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        /** Exceptions from `@throws` tags. */
+        throws: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            type: z.ZodOptional<z.ZodString>;
+            description: z.ZodString;
+        }, z.core.$loose>>>;
+        /** Version introduced, from `@since` tag. */
+        since: z.ZodOptional<z.ZodString>;
+        /** Extended classes/interfaces. */
+        extends: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        /** Implemented interfaces. */
+        implements: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        /** Class or interface members (recursive). */
+        readonly members: z.ZodOptional<z.ZodArray<z.ZodObject</*elided*/ any, z.core.$loose>>>;
+        /** Type/interface properties (recursive). */
+        readonly properties: z.ZodOptional<z.ZodArray<z.ZodObject</*elided*/ any, z.core.$loose>>>;
+        /** Svelte component props. */
+        props: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodString;
+            optional: z.ZodOptional<z.ZodBoolean>;
+            description: z.ZodOptional<z.ZodString>;
+            default_value: z.ZodOptional<z.ZodString>;
+            bindable: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>>;
+        /**
+         * Module paths (relative to src/lib) that re-export this declaration.
+         * The canonical location is this module's `declarations` array.
+         */
+        also_exported_from: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        /**
+         * For renamed re-exports (`export {foo as bar}`), the original declaration.
+         */
+        alias_of: z.ZodOptional<z.ZodObject<{
+            module: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$loose>>>;
+    /** File-level JSDoc comment. */
+    module_comment: z.ZodOptional<z.ZodString>;
+    /** Modules this imports (paths relative to src/lib). */
+    dependencies: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    /** Modules that import this (paths relative to src/lib). */
+    dependents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+export type ModuleJson = z.infer<typeof ModuleJson>;
+/**
+ * Metadata for a library's `src/lib/` exports.
+ */
+export declare const SourceJson: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    modules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        /** Path relative to src/lib (e.g., `helpers.ts`). */
+        path: z.ZodString;
+        declarations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            /** The exported name. */
+            name: z.ZodString;
+            kind: z.ZodEnum<{
+                function: "function";
+                type: "type";
+                json: "json";
+                variable: "variable";
+                class: "class";
+                constructor: "constructor";
+                component: "component";
+                css: "css";
+            }>;
+            /** JSDoc/TSDoc comment in mdz format. */
+            doc_comment: z.ZodOptional<z.ZodString>;
+            /** Full TypeScript type signature. */
+            type_signature: z.ZodOptional<z.ZodString>;
+            /** TypeScript modifiers like `readonly`, `private`, or `static`. */
+            modifiers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            /** 1-indexed line number in source file. */
+            source_line: z.ZodOptional<z.ZodNumber>;
+            /** Function/method parameters. */
+            parameters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                type: z.ZodString;
+                optional: z.ZodOptional<z.ZodBoolean>;
+                description: z.ZodOptional<z.ZodString>;
+                default_value: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>>;
+            /** Function/method return type. */
+            return_type: z.ZodOptional<z.ZodString>;
+            /** Return value description from `@returns` tag. */
+            return_description: z.ZodOptional<z.ZodString>;
+            /** Generic type parameters like `<T, U>`. */
+            generic_params: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                /** Parameter name like `T`. */
+                name: z.ZodString;
+                /** Constraint like `string` from `T extends string`. */
+                constraint: z.ZodOptional<z.ZodString>;
+                /** Default type like `unknown` from `T = unknown`. */
+                default_type: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>>;
+            /** Code examples from `@example` tags. */
+            examples: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            /** Deprecation message from `@deprecated` tag. */
+            deprecated_message: z.ZodOptional<z.ZodString>;
+            /** Related items from `@see` tags, in mdz format. */
+            see_also: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            /** Exceptions from `@throws` tags. */
+            throws: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                type: z.ZodOptional<z.ZodString>;
+                description: z.ZodString;
+            }, z.core.$loose>>>;
+            /** Version introduced, from `@since` tag. */
+            since: z.ZodOptional<z.ZodString>;
+            /** Extended classes/interfaces. */
+            extends: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            /** Implemented interfaces. */
+            implements: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            /** Class or interface members (recursive). */
+            readonly members: z.ZodOptional<z.ZodArray<z.ZodObject</*elided*/ any, z.core.$loose>>>;
+            /** Type/interface properties (recursive). */
+            readonly properties: z.ZodOptional<z.ZodArray<z.ZodObject</*elided*/ any, z.core.$loose>>>;
+            /** Svelte component props. */
+            props: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                type: z.ZodString;
+                optional: z.ZodOptional<z.ZodBoolean>;
+                description: z.ZodOptional<z.ZodString>;
+                default_value: z.ZodOptional<z.ZodString>;
+                bindable: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$loose>>>;
+            /**
+             * Module paths (relative to src/lib) that re-export this declaration.
+             * The canonical location is this module's `declarations` array.
+             */
+            also_exported_from: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            /**
+             * For renamed re-exports (`export {foo as bar}`), the original declaration.
+             */
+            alias_of: z.ZodOptional<z.ZodObject<{
+                module: z.ZodString;
+                name: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$loose>>>;
+        /** File-level JSDoc comment. */
+        module_comment: z.ZodOptional<z.ZodString>;
+        /** Modules this imports (paths relative to src/lib). */
+        dependencies: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        /** Modules that import this (paths relative to src/lib). */
+        dependents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export type SourceJson = z.infer<typeof SourceJson>;
+/**
+ * Format declaration name with generic parameters for display.
+ * @example declaration_get_display_name({name: 'Map', kind: 'type', generic_params: [{name: 'K'}, {name: 'V'}]})
+ * // => 'Map<K, V>'
+ */
+export declare const declaration_get_display_name: (declaration: DeclarationJson) => string;
+/**
+ * Generate TypeScript import statement for a declaration.
+ * @example declaration_generate_import({name: 'Foo', kind: 'type'}, 'foo.ts', '@pkg/lib')
+ * // => "import type {Foo} from '@pkg/lib/foo.js';"
+ */
+export declare const declaration_generate_import: (declaration: DeclarationJson, module_path: string, library_name: string) => string;
+//# sourceMappingURL=source_json.d.ts.map

package/dist/source_json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source_json.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/source_json.ts"],"names":[],"mappings":"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"}

package/dist/source_json.js

@@ -0,0 +1,189 @@
+/**
+ * Metadata types for library source code analysis.
+ *
+ * These types represent the structure of `src/lib/` exports,
+ * extracted at build time via TypeScript compiler analysis.
+ * Used for generating API documentation and enabling code search.
+ *
+ * Hierarchy: SourceJson → ModuleJson → DeclarationJson
+ */
+import { z } from 'zod';
+/**
+ * The kind of exported declaration.
+ */
+export const DeclarationKind = z.enum([
+    'type',
+    'function',
+    'variable',
+    'class',
+    'constructor',
+    'component',
+    'json',
+    'css',
+]);
+/**
+ * Generic type parameter information.
+ */
+export const GenericParamInfo = z.looseObject({
+    /** Parameter name like `T`. */
+    name: z.string(),
+    /** Constraint like `string` from `T extends string`. */
+    constraint: z.string().optional(),
+    /** Default type like `unknown` from `T = unknown`. */
+    default_type: z.string().optional(),
+});
+/**
+ * Parameter information for functions and methods.
+ *
+ * Kept distinct from ComponentPropInfo despite structural similarity.
+ * Function parameters form a tuple with positional semantics:
+ * calling order matters (`fn(a, b)` vs `fn(b, a)`),
+ * may include rest parameters and destructuring patterns.
+ */
+export const ParameterInfo = z.looseObject({
+    name: z.string(),
+    type: z.string(),
+    optional: z.boolean().optional(),
+    description: z.string().optional(),
+    default_value: z.string().optional(),
+});
+/**
+ * Component prop information for Svelte components.
+ *
+ * Kept distinct from ParameterInfo despite structural similarity.
+ * Component props are named attributes with different semantics:
+ * no positional order when passing (`<Foo {a} {b} />` = `<Foo {b} {a} />`),
+ * support two-way binding via `$bindable` rune.
+ */
+export const ComponentPropInfo = z.looseObject({
+    name: z.string(),
+    type: z.string(),
+    optional: z.boolean().optional(),
+    description: z.string().optional(),
+    default_value: z.string().optional(),
+    bindable: z.boolean().optional(),
+});
+/**
+ * Metadata for an exported declaration (function, type, class, component, etc.).
+ *
+ * Extracted from TypeScript source and JSDoc/TSDoc comments at build time.
+ */
+export const DeclarationJson = z.looseObject({
+    /** The exported name. */
+    name: z.string(),
+    kind: DeclarationKind,
+    /** JSDoc/TSDoc comment in mdz format. */
+    doc_comment: z.string().optional(),
+    /** Full TypeScript type signature. */
+    type_signature: z.string().optional(),
+    /** TypeScript modifiers like `readonly`, `private`, or `static`. */
+    modifiers: z.array(z.string()).optional(),
+    /** 1-indexed line number in source file. */
+    source_line: z.number().optional(),
+    /** Function/method parameters. */
+    parameters: z.array(ParameterInfo).optional(),
+    /** Function/method return type. */
+    return_type: z.string().optional(),
+    /** Return value description from `@returns` tag. */
+    return_description: z.string().optional(),
+    /** Generic type parameters like `<T, U>`. */
+    generic_params: z.array(GenericParamInfo).optional(),
+    /** Code examples from `@example` tags. */
+    examples: z.array(z.string()).optional(),
+    /** Deprecation message from `@deprecated` tag. */
+    deprecated_message: z.string().optional(),
+    /** Related items from `@see` tags, in mdz format. */
+    see_also: z.array(z.string()).optional(),
+    /** Exceptions from `@throws` tags. */
+    throws: z.array(z.looseObject({ type: z.string().optional(), description: z.string() })).optional(),
+    /** Version introduced, from `@since` tag. */
+    since: z.string().optional(),
+    /** Extended classes/interfaces. */
+    extends: z.array(z.string()).optional(),
+    /** Implemented interfaces. */
+    implements: z.array(z.string()).optional(),
+    /** Class or interface members (recursive). */
+    get members() {
+        return z.array(DeclarationJson).optional();
+    },
+    /** Type/interface properties (recursive). */
+    get properties() {
+        return z.array(DeclarationJson).optional();
+    },
+    /** Svelte component props. */
+    props: z.array(ComponentPropInfo).optional(),
+    /**
+     * Module paths (relative to src/lib) that re-export this declaration.
+     * The canonical location is this module's `declarations` array.
+     */
+    also_exported_from: z.array(z.string()).optional(),
+    /**
+     * For renamed re-exports (`export {foo as bar}`), the original declaration.
+     */
+    alias_of: z
+        .object({
+        module: z.string(),
+        name: z.string(),
+    })
+        .optional(),
+});
+/**
+ * A source file in `src/lib/` with its exported declarations.
+ */
+export const ModuleJson = z.looseObject({
+    /** Path relative to src/lib (e.g., `helpers.ts`). */
+    path: z.string(),
+    declarations: z.array(DeclarationJson).optional(),
+    /** File-level JSDoc comment. */
+    module_comment: z.string().optional(),
+    /** Modules this imports (paths relative to src/lib). */
+    dependencies: z.array(z.string()).optional(),
+    /** Modules that import this (paths relative to src/lib). */
+    dependents: z.array(z.string()).optional(),
+});
+/**
+ * Metadata for a library's `src/lib/` exports.
+ */
+export const SourceJson = z.looseObject({
+    name: z.string(),
+    version: z.string(),
+    modules: z.array(ModuleJson).optional(),
+});
+/**
+ * Format declaration name with generic parameters for display.
+ * @example declaration_get_display_name({name: 'Map', kind: 'type', generic_params: [{name: 'K'}, {name: 'V'}]})
+ * // => 'Map<K, V>'
+ */
+export const declaration_get_display_name = (declaration) => {
+    if (!declaration.generic_params?.length)
+        return declaration.name;
+    const params = declaration.generic_params.map((p) => {
+        let param = p.name;
+        if (p.constraint)
+            param += ` extends ${p.constraint}`;
+        if (p.default_type)
+            param += ` = ${p.default_type}`;
+        return param;
+    });
+    return `${declaration.name}<${params.join(', ')}>`;
+};
+/**
+ * Generate TypeScript import statement for a declaration.
+ * @example declaration_generate_import({name: 'Foo', kind: 'type'}, 'foo.ts', '@pkg/lib')
+ * // => "import type {Foo} from '@pkg/lib/foo.js';"
+ */
+export const declaration_generate_import = (declaration, module_path, library_name) => {
+    const js_path = module_path.replace(/\.ts$/, '.js');
+    const specifier = `${library_name}/${js_path}`;
+    // Handle default exports by converting module name to PascalCase
+    if (declaration.name === 'default') {
+        const module_name = module_path.replace(/\.(js|ts|svelte)$/, '');
+        const pascal_case = module_name
+            .split(/[-_]/)
+            .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+            .join('');
+        return `import ${pascal_case} from '${specifier}';`;
+    }
+    const import_keyword = declaration.kind === 'type' ? 'import type' : 'import';
+    return `${import_keyword} {${declaration.name}} from '${specifier}';`;
+};

package/dist/string.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Truncates a string to a maximum length, adding a suffix if needed that defaults to `...`.
+ */
+export declare const truncate: (str: string, maxLength: number, suffix?: string) => string;
+/**
+ * Removes characters inclusive of `stripped`.
+ */
+export declare const strip_start: (source: string, stripped: string) => string;
+/**
+ * Removes characters inclusive of `stripped`.
+ */
+export declare const strip_end: (source: string, stripped: string) => string;
+/**
+ * Removes characters inclusive of `stripped`.
+ */
+export declare const strip_after: (source: string, stripped: string) => string;
+/**
+ * Removes characters inclusive of `stripped`.
+ */
+export declare const strip_before: (source: string, stripped: string) => string;
+/**
+ * Adds the substring `ensured` to the start of the `source` string if it's not already present.
+ */
+export declare const ensure_start: (source: string, ensured: string) => string;
+/**
+ * Adds the substring `ensured` to the end of the `source` string if it's not already present.
+ */
+export declare const ensure_end: (source: string, ensured: string) => string;
+/**
+ * Removes leading and trailing spaces from each line of a string.
+ */
+export declare const deindent: (str: string) => string;
+/**
+ * Returns a plural suffix based on a count.
+ */
+export declare const plural: (count: number | undefined | null, suffix?: string) => string;
+/**
+ * Returns the count of graphemes in a string, the individually rendered characters.
+ */
+export declare const count_graphemes: (str: string) => number;
+/**
+ * Strips ANSI escape sequences from a string
+ */
+export declare const strip_ansi: (str: string) => string;
+/**
+ * Stringifies a value like `JSON.stringify` but with some corner cases handled better.
+ *
+ * @source https://2ality.com/2025/04/stringification-javascript.html
+ */
+export declare const stringify: (value: unknown) => string;
+//# sourceMappingURL=string.d.ts.map

package/dist/string.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/string.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,MAAM,EAAE,WAAW,MAAM,EAAE,eAAc,KAAG,MAMzE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAG9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAG5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAK9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAK/D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,MAG9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,MAG5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,MAAM,KAAG,MAK1B,CAAC;AAEd;;GAEG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,eAAY,KAAG,MAC9C,CAAC;AAE3B;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,KAAG,MACI,CAAC;AAEnD;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,KAAG,MAAsD,CAAC;AAEhG;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,MACwC,CAAC"}