@xylabs/ts-scripts-common 7.5.0

package/dist/index.d.ts

@@ -0,0 +1,564 @@
+import { Options } from 'tsup';
+import { CompilerOptions } from 'typescript';
+import { PathLike, WriteFileOptions } from 'node:fs';
+import { SpawnSyncOptionsWithBufferEncoding } from 'node:child_process';
+import { PackageJson } from 'types-package-json';
+import { Argv } from 'yargs';
+
+interface BuildParams {
+    incremental?: boolean;
+    jobs?: number;
+    pkg?: string;
+    target?: 'esm' | 'cjs';
+    verbose?: boolean;
+}
+declare const build: ({ incremental, jobs, target, verbose, pkg, }: BuildParams) => Promise<number>;
+
+declare function claudeClean(): number;
+
+declare const claudeCommands: () => number;
+
+declare const claudeRules: ({ force }?: {
+    force?: boolean;
+}) => number;
+
+declare function claudeSettings(): Promise<number>;
+
+declare const claudeSkills: () => number;
+
+interface CleanParams {
+    pkg?: string;
+    verbose?: boolean;
+}
+interface CleanPackageParams {
+    pkg: string;
+    verbose?: boolean;
+}
+declare const clean: ({ verbose, pkg }: CleanParams) => Promise<number>;
+declare const cleanPackage: ({ pkg }: CleanPackageParams) => Promise<number>;
+declare const cleanAll: ({ verbose }: CleanParams) => Promise<number>;
+
+declare const cleanDocs: () => number;
+
+declare const cleanESLint: () => number;
+
+interface CompileParams {
+    incremental?: boolean;
+    jobs?: number;
+    pkg?: string;
+    publint?: boolean;
+    target?: 'esm' | 'cjs';
+    verbose?: boolean;
+}
+interface CompilePackageParams {
+    pkg: string;
+    publint?: boolean;
+    target?: 'esm' | 'cjs';
+    verbose?: boolean;
+}
+declare const compile: ({ verbose, target, pkg, incremental, publint, jobs, }: CompileParams) => number;
+declare const compilePackage: ({ target, pkg }: CompilePackageParams) => number;
+declare const compileAll: ({ jobs, verbose, target, incremental, }: CompileParams) => number;
+
+interface CopyAssetsParams {
+    pkg?: string;
+    target?: 'esm' | 'cjs';
+}
+declare const copyAssets: ({ target, pkg }: CopyAssetsParams) => Promise<0 | 1>;
+
+interface CycleParams {
+    incremental?: boolean;
+    jobs?: number;
+    pkg?: string;
+    verbose?: boolean;
+}
+interface CyclePackageParams {
+    pkg: string;
+    verbose?: boolean;
+}
+declare const cycle: ({ verbose, pkg }?: CycleParams) => Promise<number>;
+declare const cyclePackage: ({ pkg, verbose }: CyclePackageParams) => number;
+declare const cycleAll: ({ verbose }: {
+    verbose?: boolean;
+}) => Promise<number>;
+
+declare const dead: () => number;
+
+type PackageManagerName = 'pnpm' | 'yarn';
+declare function detectPackageManager(): PackageManagerName;
+
+interface Workspace {
+    location: string;
+    name: string;
+}
+type ScriptStep = [/* command */ string, /* arg */ /* arg */ string | string[]] | [/* command */ string, /* arg */ /* arg */ string | string[], /* config */ SpawnSyncOptionsWithBufferEncoding];
+interface WorkspaceForeachOptions {
+    incremental?: boolean;
+    jobs?: number;
+    topological?: boolean;
+    verbose?: boolean;
+}
+interface PackageManager {
+    /** The shell command to invoke this package manager (e.g., 'yarn', 'pnpm') */
+    command: string;
+    /** The lockfile name (e.g., 'yarn.lock', 'pnpm-lock.yaml') */
+    lockfile: string;
+    /** Package manager identifier */
+    name: 'pnpm' | 'yarn';
+    /** Remove duplicate dependencies */
+    dedupe(): ScriptStep;
+    /** Find a single workspace by name */
+    findWorkspace(name: string): Workspace | undefined;
+    /** Run a foreach command across all workspaces */
+    foreachWorkspace(script: string, args?: string[], options?: WorkspaceForeachOptions): ScriptStep;
+    /** Install dependencies */
+    install(): ScriptStep;
+    /** List all workspaces */
+    listWorkspaces(): Workspace[];
+    /** Show outdated dependencies */
+    outdated(): ScriptStep;
+    /** Run a script in a specific workspace */
+    runInWorkspace(pkg: string, script: string, args?: string[]): ScriptStep;
+    /** Run the xy CLI command */
+    runXy(args: string[]): ScriptStep;
+    /** Apply version changes */
+    versionApply(): ScriptStep;
+    /** Bump versions across workspaces */
+    versionBump(type: 'major' | 'minor' | 'patch' | 'prerelease'): ScriptStep[];
+}
+
+declare function registerPackageManager(pm: PackageManager): void;
+declare function getPackageManager(name?: PackageManagerName): PackageManager;
+
+interface CheckPackageOptions {
+    deps?: boolean;
+    devDeps?: boolean;
+    /**
+     * Set of package names to exclude from unused-dependency checks.
+     * Loaded from xy.config's deplint.exclude field.
+     */
+    exclude?: Set<string>;
+    peerDeps?: boolean;
+    verbose?: boolean;
+}
+
+interface DepLintOptions extends CheckPackageOptions {
+    /** Package names to exclude, passed via --exclude on the command line */
+    cliExclude?: string[];
+    pkg?: string;
+}
+declare const deplint: ({ pkg, deps, devDeps, peerDeps, verbose, cliExclude, }: DepLintOptions) => Promise<1 | 0>;
+
+declare const dupdeps: () => number;
+
+interface LintParams {
+    cache?: boolean;
+    fix?: boolean;
+    incremental?: boolean;
+    pkg?: string;
+    verbose?: boolean;
+}
+interface LintPackageParams {
+    pkg: string;
+    verbose?: boolean;
+}
+declare const lintPackage: ({ pkg, fix, verbose, }: LintParams & Required<Pick<LintParams, "pkg">>) => number;
+declare const lint: ({ pkg, verbose, incremental, fix, }?: LintParams) => number;
+declare const lintAllPackages: ({ fix }?: LintParams) => number;
+
+declare const fix: (params?: LintParams) => number;
+
+interface GenDocsParams {
+    incremental?: boolean;
+    pkg?: string;
+}
+interface GenDocsPackageParams {
+    pkg: string;
+}
+declare const genDocs: ({ pkg, incremental }: GenDocsParams) => number;
+declare const genDocsPackage: ({ pkg }: GenDocsPackageParams) => number;
+declare const genDocsAll: ({ incremental }: GenDocsParams) => number;
+
+/** @deprecated Use gitignore instead */
+declare const gitignoreGen: typeof gitignore;
+declare function gitignore(): number;
+
+declare const gitlint: () => 1 | 0;
+
+declare const gitlintFix: () => number;
+
+declare const knip: () => number;
+
+declare const license: (pkg?: string) => Promise<number>;
+
+interface LintlintParams {
+    fix?: boolean;
+    verbose?: boolean;
+}
+declare function lintlint({ fix, verbose }?: LintlintParams): Promise<number>;
+
+declare const npmignoreGen: (pkg?: string) => 1 | 0;
+
+declare const packageClean: () => Promise<number>;
+
+declare const packageCleanOutputs: () => number;
+
+declare const packageCleanTypescript: () => number;
+
+type EntryMode = 'all' | 'single' | 'auto' | 'platform' | 'custom';
+/**
+ * Configuration for specifying which paths are targeted.
+ */
+interface PathConfig {
+    /**
+     * Glob patterns to exclude (takes precedence over include).
+     */
+    exclude?: string[];
+    /**
+     * Glob patterns to include.
+     */
+    include?: string[];
+}
+/**
+ * Configuration for Dynamic Share.
+ */
+interface DynamicShareConfig extends PathConfig {
+}
+/**
+ * Configuration for Live Share.
+ */
+interface LiveShareConfig extends PathConfig {
+}
+interface CompileConfig {
+    bundleTypes?: boolean;
+    /** @param entryMode all, single, custom, platform, or auto */
+    entryMode?: EntryMode;
+    /** @param when building types with tsc, should it use the outDir to write to? */
+    outDirAsBuildDir?: boolean;
+}
+type PackageCompileTsupConfig = CompileConfig & {
+    browser?: Record<string, Options | boolean>;
+    neutral?: Record<string, Options | boolean>;
+    node?: Record<string, Options | boolean>;
+    tsup?: {
+        options?: Options;
+    };
+    verbose?: boolean;
+};
+type PackageCompileTscConfig = CompileConfig & {
+    mode: 'tsc';
+};
+/**
+ * Configuration for deplint (dependency linting).
+ */
+interface DeplintConfig {
+    /**
+     * Package names to exclude from unused-dependency checks.
+     * Packages listed here will never be reported as "unused" by deplint,
+     * even if no import for them is detected in source or dist files.
+     * Useful for packages that are used implicitly (e.g. runtime plugins,
+     * CSS-in-JS themes, or polyfills that have side effects on import).
+     */
+    exclude?: string[];
+}
+/**
+ * Configuration for readme generation.
+ */
+interface ReadmeConfig {
+    /**
+     * URL that the logo links to when clicked.
+     * Replaces the placeholder in the template's [![logo][]](url) link.
+     */
+    logoLinkUrl?: string;
+    /**
+     * Public URL for the logo image displayed at the top of generated READMEs.
+     * Replaces the placeholder in the template's [logo] reference link.
+     */
+    logoUrl?: string;
+}
+interface XyConfigBase {
+    compile?: CompileConfig;
+    deplint?: DeplintConfig;
+    dynamicShare?: DynamicShareConfig;
+    liveShare?: LiveShareConfig;
+    /** @deprecated */
+    publint?: boolean;
+    readme?: ReadmeConfig;
+    verbose?: boolean;
+}
+interface XyTsupConfig extends XyConfigBase {
+    compile?: PackageCompileTsupConfig;
+}
+interface XyTscConfig extends XyConfigBase {
+    compile?: PackageCompileTscConfig;
+}
+type XyConfigLegacy = XyTsupConfig | XyTscConfig;
+type XyConfig = XyConfigLegacy & {
+    dev?: {
+        build?: {
+            clean?: boolean;
+            compile?: boolean;
+            deplint?: boolean;
+            gendocs?: boolean;
+            gitlint?: boolean;
+            knip?: boolean;
+            license?: boolean;
+            lint?: boolean;
+            publint?: boolean;
+            statics?: boolean;
+            verbose?: boolean;
+        };
+        compile?: PackageCompileTsupConfig;
+        verbose?: boolean;
+    };
+    verbose?: boolean;
+};
+
+declare const packageCompile: (inConfig?: XyConfig) => Promise<number>;
+
+declare const packageCompileTsc: (platform: "browser" | "neutral" | "node", entries: string[], srcDir?: string, outDir?: string, compilerOptionsParam?: CompilerOptions, verbose?: boolean) => number;
+
+declare const tsupOptions: (options?: Options[]) => Options;
+declare const packageCompileTsup: (config?: XyTsupConfig) => Promise<number>;
+
+interface PackageCopyAssetsParams {
+    target?: 'esm' | 'cjs';
+}
+declare const packageCopyAssets: ({ target }: PackageCopyAssetsParams) => Promise<1 | 0>;
+
+declare const packageCycle: () => Promise<number>;
+
+declare const packageGenDocs: () => Promise<number | undefined>;
+
+declare const packageLint: (fix?: boolean, verbose?: boolean, cache?: boolean) => Promise<number>;
+
+interface PackagePublintParams {
+    strict?: boolean;
+    verbose?: boolean;
+}
+declare const packagePublint: ({ strict, verbose }?: PackagePublintParams) => Promise<number>;
+
+declare const packageRecompile: () => Promise<number>;
+
+declare function packageLintMonorepo(fix?: boolean): number;
+
+interface ConvertParams {
+    target: string;
+    verbose?: boolean;
+}
+declare function convert({ target, verbose }: ConvertParams): number;
+
+type Direction = 'pnpm-to-yarn' | 'yarn-to-pnpm';
+declare function rewriteScript(script: string, direction: Direction): string;
+declare function rewriteScriptsInPackageJson(pkg: Record<string, unknown>, direction: Direction): Record<string, unknown>;
+
+interface PublintParams {
+    pkg?: string;
+    verbose?: boolean;
+}
+interface PublintPackageParams {
+    pkg: string;
+    verbose?: boolean;
+}
+declare const publint: ({ verbose, pkg }: PublintParams) => Promise<number>;
+declare const publintPackage: ({ pkg }: PublintPackageParams) => Promise<number>;
+declare const publintAll: ({ verbose }: PublintParams) => number;
+
+interface ReadmeGenParams {
+    pkg?: string;
+    templatePath?: string;
+    typedoc?: boolean;
+    verbose?: boolean;
+}
+declare function readmeGen({ pkg, templatePath, typedoc, verbose, }: ReadmeGenParams): Promise<number>;
+
+interface ReadmeInitParams {
+    templatePath?: string;
+    verbose?: boolean;
+}
+declare function readmeInit({ templatePath }: ReadmeInitParams): Promise<number>;
+
+interface RebuildParams {
+    pkg?: string;
+    target?: 'esm' | 'cjs';
+}
+declare const rebuild: ({ target }: RebuildParams) => number;
+
+interface RecompileParams {
+    incremental?: boolean;
+    jobs?: number;
+    pkg?: string;
+    target?: 'esm' | 'cjs';
+    verbose?: boolean;
+}
+interface RecompilePackageParams {
+    pkg: string;
+    target?: 'esm' | 'cjs';
+    verbose?: boolean;
+}
+declare const recompile: ({ verbose, target, pkg, incremental, }: RecompileParams) => Promise<number>;
+declare const recompilePackage: ({ target, pkg }: RecompilePackageParams) => Promise<number>;
+declare const recompileAll: ({ jobs, verbose, target, incremental, }: RecompileParams) => Promise<number>;
+
+interface RelintParams {
+    cache?: boolean;
+    fix?: boolean;
+    incremental?: boolean;
+    pkg?: string;
+    verbose?: boolean;
+}
+interface RelintPackageParams {
+    pkg: string;
+    verbose?: boolean;
+}
+declare const relintPackage: ({ pkg, fix, verbose, }: RelintParams & Required<Pick<RelintParams, "pkg">>) => number;
+declare const relint: ({ pkg, verbose, incremental, fix, }?: RelintParams) => number;
+declare const relintAllPackages: ({ fix }?: RelintParams) => number;
+
+interface RetestParams {
+    target?: string;
+}
+declare const retest: ({ target }?: RetestParams) => number;
+
+declare const sonar: () => number;
+
+declare const statics: () => number;
+
+interface TestParams {
+    target?: string;
+}
+declare const test: ({ target }?: TestParams) => number;
+
+declare const checkResult: (name: string, result: number, level?: "error" | "warn", exitOnFail?: boolean) => void;
+
+declare const XYLABS_RULES_PREFIX = "xylabs-";
+declare const XYLABS_COMMANDS_PREFIX = "xy-";
+declare const LEGACY_COMMANDS_PREFIX = "xylabs-";
+declare const XYLABS_SKILLS_PREFIX = "xylabs-";
+declare const claudeMdRuleTemplates: () => Record<string, string>;
+declare const claudeCommandTemplates: () => Record<string, string>;
+declare const claudeSkillTemplates: () => Record<string, Record<string, string>>;
+declare const claudeMdProjectTemplate: () => string;
+declare const claudeMdLocalTemplate: () => string;
+
+declare const createBuildConfig: (location: string, module: "ESNext" | "CommonJS", target: "ESNext" | "ES6", outDirSuffix: string) => Record<string, unknown> | undefined;
+
+declare const defaultBuildConfig: {
+    compilerOptions: {
+        rootDir: string;
+        rootDirs: string[];
+    };
+    exclude: string[];
+    include: string[];
+};
+
+declare const deleteGlob: (globPath: string) => void;
+
+declare const detectDuplicateDependencies: (depsFromPackageJSON?: string[], DefaultDependencies?: string[]) => number;
+
+declare class DuplicateDetector {
+    private dependency;
+    private dependencyEntries;
+    constructor(output: string, dependency: string);
+    detect(): 1 | 0;
+    private detectReducer;
+    private resultsFactory;
+}
+
+declare const WINDOWS_NEWLINE_REGEX: RegExp;
+declare const CROSS_PLATFORM_NEWLINE = "\n";
+
+type ReadFileSyncOptions = BufferEncoding | {
+    encoding: BufferEncoding;
+    flags?: string;
+};
+declare const defaultReadFileSyncOptions: ReadFileSyncOptions;
+
+declare const readLines: (uri: PathLike, options?: ReadFileSyncOptions) => string[];
+declare const readNonEmptyLines: (uri: PathLike, options?: ReadFileSyncOptions) => string[];
+declare const writeLines: (uri: PathLike, lines: string[], options?: WriteFileOptions) => void;
+
+declare const tryReadFileSync: (uri: PathLike, options?: ReadFileSyncOptions) => string | undefined;
+
+declare const generateIgnoreFiles: (filename: string, pkg?: string) => 1 | 0;
+
+interface GenerateReadmeFilesParams {
+    logoLinkUrl?: string;
+    logoUrl?: string;
+    pkg?: string;
+    templatePath?: string;
+    typedoc?: boolean;
+    verbose?: boolean;
+}
+declare const DEFAULT_README_TEMPLATE: string;
+declare const DEFAULT_README_BODY: string;
+declare function applyLogoConfig(template: string, logoUrl?: string, logoLinkUrl?: string): string;
+declare function resolveTemplatePath(templatePath: string | undefined): string;
+declare function scaffoldTemplate(resolvedTemplatePath: string, template: string): Promise<void>;
+declare function generateReadmeFiles({ logoLinkUrl, logoUrl, pkg, templatePath, typedoc, verbose, }: GenerateReadmeFilesParams): Promise<number>;
+
+declare const gitignoreTemplate: () => string;
+
+declare function INIT_CWD(): string | undefined;
+
+declare const multiLineToJSONArray: (output: string) => any;
+
+declare const loadConfig: <T extends object>(params?: T) => Promise<T>;
+
+declare const parsedPackageJSON: (path?: string) => any;
+
+declare const processEx: (ex: unknown) => never;
+
+declare const runSteps: (name: string, steps: ScriptStep[], exitOnFail?: boolean, messages?: string[]) => number;
+
+declare const runStepAsync: (name: string, step: ScriptStep, exitOnFail?: boolean, message?: string) => Promise<number>;
+declare const runStepsAsync: (name: string, steps: ScriptStep[], exitOnFail?: boolean, messages?: string[]) => Promise<number>;
+
+declare const runXy: (command: string) => number;
+
+declare const runXyWithWarning: (command: string) => number;
+
+/** Catch child process a crash and returns the code */
+declare const safeExit: (func: () => number, exitOnFail?: boolean) => number;
+declare const safeExitAsync: (func: () => Promise<number>, exitOnFail?: boolean) => Promise<number>;
+
+declare const empty: (value?: string | undefined) => boolean;
+declare const notEmpty: (value?: string | undefined) => boolean;
+
+declare const union: (a: string[], b: string[]) => Set<string>;
+
+/**
+ * Attempts to run a local root package.json script instead of the built-in
+ * xy command. Returns the exit code if the override ran, or undefined if
+ * no override applies (no matching script or recursion guard).
+ */
+declare function tryRunLocalScript(commandName: string): number | undefined;
+
+declare const withErrnoException: <T extends NodeJS.ErrnoException = NodeJS.ErrnoException>(ex: unknown, closure: (error: T) => number) => number | undefined;
+
+declare const withError: <T extends Error = Error>(ex: any, closure: (error: T) => number, predicate?: (ex: T) => boolean) => number | undefined;
+
+type PackageJsonEx = PackageJson & {
+    type: 'module' | 'commonjs';
+};
+declare const loadPackageConfig: () => Promise<PackageJsonEx>;
+
+declare const xyBuildCommands: (args: Argv) => Argv<{}>;
+
+declare const xyCommonCommands: (args: Argv) => Argv<{}>;
+
+declare const xyLintCommands: (args: Argv) => Argv<{}>;
+
+declare const xyBase: (plugins?: (args: Argv) => Argv) => Promise<{
+    [x: string]: unknown;
+    _: (string | number)[];
+    $0: string;
+} | {
+    [x: string]: unknown;
+    _: (string | number)[];
+    $0: string;
+}>;
+
+declare const xyParseOptions: () => Argv;
+
+export { type BuildParams, CROSS_PLATFORM_NEWLINE, type CleanPackageParams, type CleanParams, type CompileConfig, type CompileParams, type ConvertParams, type CopyAssetsParams, type CycleParams, DEFAULT_README_BODY, DEFAULT_README_TEMPLATE, type DepLintOptions, type DeplintConfig, DuplicateDetector, type DynamicShareConfig, type EntryMode, type GenDocsPackageParams, type GenDocsParams, INIT_CWD, LEGACY_COMMANDS_PREFIX, type LintPackageParams, type LintParams, type LiveShareConfig, type PackageCompileTscConfig, type PackageCompileTsupConfig, type PackageCopyAssetsParams, type PackageJsonEx, type PackageManager, type PackageManagerName, type PackagePublintParams, type PathConfig, type PublintPackageParams, type PublintParams, type ReadFileSyncOptions, type ReadmeConfig, type ReadmeGenParams, type ReadmeInitParams, type RebuildParams, type RecompilePackageParams, type RecompileParams, type RelintPackageParams, type RelintParams, type RetestParams, type ScriptStep, type TestParams, WINDOWS_NEWLINE_REGEX, type Workspace, type WorkspaceForeachOptions, XYLABS_COMMANDS_PREFIX, XYLABS_RULES_PREFIX, XYLABS_SKILLS_PREFIX, type XyConfig, type XyConfigBase, type XyConfigLegacy, type XyTscConfig, type XyTsupConfig, applyLogoConfig, build, checkResult, claudeClean, claudeCommandTemplates, claudeCommands, claudeMdLocalTemplate, claudeMdProjectTemplate, claudeMdRuleTemplates, claudeRules, claudeSettings, claudeSkillTemplates, claudeSkills, clean, cleanAll, cleanDocs, cleanESLint, cleanPackage, compile, compileAll, compilePackage, convert, copyAssets, createBuildConfig, cycle, cycleAll, cyclePackage, dead, defaultBuildConfig, defaultReadFileSyncOptions, deleteGlob, deplint, detectDuplicateDependencies, detectPackageManager, dupdeps, empty, fix, genDocs, genDocsAll, genDocsPackage, generateIgnoreFiles, generateReadmeFiles, getPackageManager, gitignore, gitignoreGen, gitignoreTemplate, gitlint, gitlintFix, knip, license, lint, lintAllPackages, lintPackage, lintlint, loadConfig, loadPackageConfig, multiLineToJSONArray, notEmpty, npmignoreGen, packageClean, packageCleanOutputs, packageCleanTypescript, packageCompile, packageCompileTsc, packageCompileTsup, packageCopyAssets, packageCycle, packageGenDocs, packageLint, packageLintMonorepo, packagePublint, packageRecompile, parsedPackageJSON, processEx, publint, publintAll, publintPackage, readLines, readNonEmptyLines, readmeGen, readmeInit, rebuild, recompile, recompileAll, recompilePackage, registerPackageManager, relint, relintAllPackages, relintPackage, resolveTemplatePath, retest, rewriteScript, rewriteScriptsInPackageJson, runStepAsync, runSteps, runStepsAsync, runXy, runXyWithWarning, safeExit, safeExitAsync, scaffoldTemplate, sonar, statics, test, tryReadFileSync, tryRunLocalScript, tsupOptions, union, withErrnoException, withError, writeLines, xyBase, xyBuildCommands, xyCommonCommands, xyLintCommands, xyParseOptions };