@apitree.cz/cli 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apitree.cz/cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Command line interface for ApiTree projects",
   "repository": {
     "type": "git",
@@ -15,7 +15,8 @@
   },
   "files": [
     "bin",
-    "dist"
+    "dist",
+    "src"
   ],
   "dependencies": {
     "@commander-js/extra-typings": "^13.1.0",
@@ -25,12 +26,12 @@
     "path-exists": "^5.0.0",
     "ts-toolbelt": "^9.6.0",
     "zod": "^3.24.1",
-    "@apitree.cz/ts-utils": "0.1.5"
+    "@apitree.cz/ts-utils": "0.1.6"
   },
   "devDependencies": {
     "typedoc": "^0.27.6",
     "typescript": "^5.7.3",
-    "@apitree.cz/typedoc-config": "0.1.7"
+    "@apitree.cz/typedoc-config": "0.1.8"
   },
   "scripts": {
     "prebuild": "del dist tsconfig.build.tsbuildinfo",

package/src/cli.ts

@@ -0,0 +1,13 @@
+import { Command } from '@commander-js/extra-typings';
+
+const cli = async () => {
+  const program = new Command();
+  program.name('apitree-cli');
+  const commands = await import('./commands/index.js');
+  for (const command of Object.values(commands)) {
+    program.addCommand(command);
+  }
+  return program.parseAsync(process.argv);
+};
+
+await cli();

package/src/commands/index.ts

@@ -0,0 +1 @@
+export { syncProjectReferences } from './sync-project-references/index.js';

package/src/commands/sync-project-references/action.ts

@@ -0,0 +1,35 @@
+import path from 'node:path';
+
+import { logger } from '../../utils.js';
+
+import type { GetConfigProps } from './get-config.js';
+import { getConfig } from './get-config.js';
+import { getReferences } from './get-references.js';
+import { getWorkspaces } from './get-workspaces.js';
+import { runHooks } from './run-hooks.js';
+import { updateTsConfigs } from './update-ts-configs.js';
+
+export type ActionProps = Pick<GetConfigProps, 'config'>;
+
+export const action = async ({ config }: ActionProps) => {
+  const { workspaces, rootDir } = await getWorkspaces();
+  const { hooks, tsConfigs } = await getConfig({ config, rootDir });
+  const sync = workspaces.flatMap(async (workspacePackage) => {
+    logger.info(`Syncing project references for ./${path.relative(rootDir, workspacePackage.dir)}`);
+    return updateTsConfigs({
+      references: await getReferences({
+        tsConfigs,
+        workspacePackage,
+        workspaces,
+      }),
+      tsConfigs,
+      workspacePackage,
+    });
+  });
+  if (sync.length === 0) {
+    logger.warn('No project references to sync.');
+    return;
+  }
+  const paths = await Promise.all(sync);
+  await runHooks(hooks, paths.flat());
+};

package/src/commands/sync-project-references/command.ts

@@ -0,0 +1,13 @@
+import { Command } from '@commander-js/extra-typings';
+
+import { run } from '../../utils.js';
+
+import { config } from './options.js';
+
+export const command = new Command('sync-project-references')
+  .description('sync TS project references in monorepo')
+  .addOption(config)
+  .action(async ({ config }) => {
+    const { action } = await import('./action.js');
+    await run(action({ config }));
+  });

package/src/commands/sync-project-references/config-schema.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+
+import type { SyncProjectReferencesConfig } from './types.js';
+
+export const configSchema = z
+  .object({
+    hooks: z
+      .object({
+        afterSync: z.array(z.string()).optional(),
+      })
+      .optional(),
+    tsConfigs: z
+      .object({
+        build: z.string().optional(),
+        default: z.string().optional(),
+      })
+      .optional(),
+  })
+  .strict() satisfies z.ZodType<SyncProjectReferencesConfig>;

package/src/commands/sync-project-references/default-config.ts

@@ -0,0 +1,13 @@
+import type { SyncProjectReferencesConfig } from './types.js';
+
+const defaultConfig = {
+  tsConfigs: {
+    default: 'tsconfig.json',
+    build: 'tsconfig.build.json',
+  },
+  hooks: {
+    afterSync: ['prettier --write'],
+  },
+} satisfies SyncProjectReferencesConfig;
+
+export default defaultConfig;

package/src/commands/sync-project-references/get-config.ts

@@ -0,0 +1,68 @@
+import path from 'node:path';
+
+import { isNil } from '@apitree.cz/ts-utils';
+import deepmerge from 'deepmerge';
+import { pathExists } from 'path-exists';
+import { ZodError } from 'zod';
+
+import { configSchema } from './config-schema.js';
+import * as defaultConfig from './default-config.js';
+
+export interface GetConfigProps {
+  /**
+   * Path to config file (e.g. `./sync-project-references.config.js`).
+   */
+  config?: string | undefined;
+  /**
+   * Root directory to search for the config file.
+   */
+  rootDir: string;
+}
+
+const getPath = async ({ config, rootDir }: GetConfigProps) => {
+  if (config) {
+    const configPath = path.isAbsolute(config) ? config : path.join(rootDir, config);
+    if (await pathExists(configPath)) {
+      return configPath;
+    }
+    throw new Error(`Config '${configPath}' does not exist.`);
+  }
+  const fallback = path.join(rootDir, 'sync-project-references.config.js');
+  if (await pathExists(fallback)) {
+    return fallback;
+  }
+};
+
+const validate = async (config: unknown, path: string) => {
+  try {
+    await configSchema.parseAsync(config);
+  } catch (error) {
+    if (error instanceof ZodError) {
+      throw new TypeError(
+        `Config '${path}' is invalid:\n${error.errors
+          .map((error) => `- ${error.path.join('.')}: ${error.message}`)
+          .join('\n')}`,
+      );
+    }
+    throw error;
+  }
+};
+
+/**
+ * Returns config object from a provided path.
+ * If the config file does not exist, returns default config.
+ */
+export const getConfig = async (props: GetConfigProps) => {
+  const configPath = await getPath(props);
+  if (configPath) {
+    const config = (await import(configPath)) as typeof defaultConfig;
+    if (isNil(config.default)) {
+      throw new Error(`Config '${configPath}' does not have a default export.`);
+    }
+    await validate(config.default, configPath);
+    return deepmerge(defaultConfig.default, config.default, {
+      arrayMerge: (_, source: unknown[]) => source,
+    });
+  }
+  return defaultConfig.default;
+};

package/src/commands/sync-project-references/get-existing-ts-config-path.ts

@@ -0,0 +1,21 @@
+import path from 'node:path';
+
+import { pathExists } from 'path-exists';
+
+import type { WorkspacePackageProps } from './types.js';
+
+export interface GetExistingTsConfigPathProps extends WorkspacePackageProps {
+  /**
+   * TS config file name (e.g. `tsconfig.json`).
+   */
+  tsConfig: string;
+}
+
+/**
+ * Returns path to TS config file of a provided name if it exists.
+ */
+export const getExistingTsConfigPath = async ({ tsConfig, workspacePackage }: GetExistingTsConfigPathProps) => {
+  const configPath = path.join(workspacePackage.dir, tsConfig);
+  const exists = await pathExists(configPath);
+  return exists ? configPath : undefined;
+};

package/src/commands/sync-project-references/get-references.ts

@@ -0,0 +1,49 @@
+import path from 'node:path';
+
+import { notNil } from '@apitree.cz/ts-utils';
+import type { Package } from '@manypkg/get-packages';
+
+import type { GetTargetBuildConfigProps } from './get-target-build-configs.js';
+import { getTargetBuildConfigs } from './get-target-build-configs.js';
+import { getWorkspaceDependencies } from './get-workspace-dependencies.js';
+import { normalizePath } from './normalize-path.js';
+
+export interface GetReferencesProps extends Pick<GetTargetBuildConfigProps, 'tsConfigs'> {
+  /**
+   * Workspace package to check and update references for.
+   */
+  workspacePackage: Package;
+  /**
+   * List of workspaces to search for package references.
+   */
+  workspaces: Package[];
+}
+
+/**
+ * Returns list of package references to be added to its TS config.
+ */
+export const getReferences = async ({ tsConfigs, workspacePackage, workspaces }: GetReferencesProps) => {
+  const { dependencies } = await getWorkspaceDependencies({ workspacePackage, workspaces });
+  const references = await Promise.all(
+    dependencies.map(async (dependency) => {
+      const workspace = workspaces.find(({ packageJson }) => packageJson.name === dependency);
+      if (workspace) {
+        const { default: defaultConfig, build: buildConfig } = await getTargetBuildConfigs({
+          tsConfigs,
+          workspacePackage: workspace,
+        });
+        return {
+          default: {
+            path: normalizePath(
+              path.join(path.relative(workspacePackage.dir, workspace.dir), buildConfig ?? defaultConfig),
+            ),
+          },
+          build: buildConfig
+            ? { path: normalizePath(path.join(path.relative(workspacePackage.dir, workspace.dir), buildConfig)) }
+            : undefined,
+        };
+      }
+    }),
+  );
+  return references.filter(notNil).sort((a, b) => a.default.path.localeCompare(b.default.path));
+};

package/src/commands/sync-project-references/get-target-build-configs.ts

@@ -0,0 +1,24 @@
+import path from 'node:path';
+
+import { pathExists } from 'path-exists';
+import type { Object } from 'ts-toolbelt';
+
+import type { SyncProjectReferencesTsConfigs, WorkspacePackageProps } from './types.js';
+
+export interface GetTargetBuildConfigProps extends WorkspacePackageProps {
+  /**
+   * Configured package TS config names.
+   */
+  tsConfigs: Object.NonNullable<Required<SyncProjectReferencesTsConfigs>>;
+}
+
+/**
+ * Returns target TS build config path relative to workspace root.
+ */
+export const getTargetBuildConfigs = async ({ tsConfigs, workspacePackage: { dir } }: GetTargetBuildConfigProps) => {
+  const buildPath = path.join(dir, tsConfigs.build);
+  return {
+    default: tsConfigs.default,
+    build: (await pathExists(buildPath)) ? tsConfigs.build : undefined,
+  };
+};

package/src/commands/sync-project-references/get-workspace-dependencies.ts

@@ -0,0 +1,34 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import type { Package } from '@manypkg/get-packages';
+
+import type { WorkspacePackageProps } from './types.js';
+
+export interface GetPackageDependenciesProps extends WorkspacePackageProps {
+  /**
+   * List of workspaces to search for package dependencies.
+   */
+  workspaces: Package[];
+}
+
+/**
+ * Returns object containing package type and list of its internal (scoped) dependencies.
+ */
+export const getWorkspaceDependencies = async ({ workspacePackage, workspaces }: GetPackageDependenciesProps) => {
+  const {
+    dependencies = {},
+    devDependencies = {},
+    type = 'module',
+  } = JSON.parse(await readFile(path.join(workspacePackage.dir, 'package.json'), 'utf8')) as {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    type?: string;
+  };
+  return {
+    type,
+    dependencies: [...Object.keys(dependencies), ...Object.keys(devDependencies)].filter((dependency) =>
+      workspaces.some(({ packageJson }) => packageJson.name === dependency),
+    ),
+  };
+};

package/src/commands/sync-project-references/get-workspaces.ts

@@ -0,0 +1,9 @@
+import { getPackages } from '@manypkg/get-packages';
+
+/**
+ * Returns list of workspaces and their root directory.
+ */
+export const getWorkspaces = async () => {
+  const { packages: workspaces, rootDir } = await getPackages(process.cwd());
+  return { workspaces, rootDir };
+};

package/src/commands/sync-project-references/index.ts

@@ -0,0 +1 @@
+export { command as syncProjectReferences } from './command.js';

package/src/commands/sync-project-references/normalize-path.ts

@@ -0,0 +1,4 @@
+/**
+ * Normalize path to use forward slashes on all platforms.
+ */
+export const normalizePath = (path: string) => path.replaceAll('\\', '/');

package/src/commands/sync-project-references/options.ts

@@ -0,0 +1,3 @@
+import { Option } from '@commander-js/extra-typings';
+
+export const config = new Option('-c, --config <config>', 'path to config file');

package/src/commands/sync-project-references/run-hooks.ts

@@ -0,0 +1,10 @@
+import type { Object } from 'ts-toolbelt';
+
+import { exec } from '../../utils.js';
+
+import type { SyncProjectReferencesHooks } from './types.js';
+
+export const runHooks = async (hooks: Object.NonNullable<Required<SyncProjectReferencesHooks>>, paths: string[]) => {
+  const { afterSync } = hooks;
+  await Promise.all(afterSync.map((hook) => exec(`pnpm ${hook} ${paths.join(' ')}`)));
+};

package/src/commands/sync-project-references/types.ts

@@ -0,0 +1,40 @@
+import type { Package } from '@manypkg/get-packages';
+
+export interface SyncProjectReferencesHooks {
+  /**
+   * Hook called after the project references are synced.
+   * @defaultValue `['prettier --write']`
+   */
+  afterSync?: string[] | undefined;
+}
+
+export interface SyncProjectReferencesTsConfigs {
+  /**
+   * Name of the main TS config file.
+   * @defaultValue `'tsconfig.json'`
+   */
+  default?: string | undefined;
+  /**
+   * Name of the TS config file for build.
+   * @defaultValue `'tsconfig.build.json'`
+   */
+  build?: string | undefined;
+}
+
+export interface SyncProjectReferencesConfig {
+  /**
+   * Custom hooks to run as parts of the sync process.
+   */
+  hooks?: SyncProjectReferencesHooks | undefined;
+  /**
+   * Custom names for TS config files.
+   */
+  tsConfigs?: SyncProjectReferencesTsConfigs | undefined;
+}
+
+export interface WorkspacePackageProps {
+  /**
+   * Workspace package.
+   */
+  workspacePackage: Package;
+}

package/src/commands/sync-project-references/update-ts-configs.ts

@@ -0,0 +1,56 @@
+import { readFile, writeFile } from 'node:fs/promises';
+
+import { notNil } from '@apitree.cz/ts-utils';
+import type { Object as ObjectType } from 'ts-toolbelt';
+
+import { logger } from '../../utils.js';
+
+import { getExistingTsConfigPath } from './get-existing-ts-config-path.js';
+import type { getReferences } from './get-references.js';
+import type { SyncProjectReferencesTsConfigs, WorkspacePackageProps } from './types.js';
+
+export interface UpdateTsConfigsProps extends WorkspacePackageProps {
+  /**
+   * List of workspace package references.
+   */
+  references: Awaited<ReturnType<typeof getReferences>>;
+  /**
+   * List of configured TS config names to use for updating references.
+   */
+  tsConfigs: ObjectType.NonNullable<Required<SyncProjectReferencesTsConfigs>>;
+}
+
+/**
+ * Updates references in all configured TS configs. Returns list of updated TS config paths.
+ */
+export const updateTsConfigs = async ({ references, tsConfigs, workspacePackage }: UpdateTsConfigsProps) => {
+  const entries = Object.entries(tsConfigs) as [keyof typeof tsConfigs, string][];
+  const paths = await Promise.all(
+    entries.map(async ([configType, configFile]) => {
+      const tsConfigPath = await getExistingTsConfigPath({
+        tsConfig: configFile,
+        workspacePackage,
+      });
+
+      if (tsConfigPath) {
+        let tsConfigJson = {} as { references?: { path: string }[] };
+
+        try {
+          tsConfigJson = JSON.parse(await readFile(tsConfigPath, 'utf8')) as typeof tsConfigJson;
+        } catch (error) {
+          logger.error(`Error reading TS config file: ${tsConfigPath}`, error);
+          return;
+        }
+
+        tsConfigJson.references = references.map(
+          (reference) => reference[configType] ?? reference.build ?? reference.default,
+        );
+
+        await writeFile(tsConfigPath, JSON.stringify(tsConfigJson).replaceAll('\r\n', '\n'));
+        return tsConfigPath;
+      }
+    }),
+  );
+
+  return paths.filter(notNil);
+};

package/src/index.ts

@@ -0,0 +1 @@
+export type * from './commands/sync-project-references/types.js';

package/src/utils.ts

@@ -0,0 +1,22 @@
+import childProcess from 'node:child_process';
+import { promisify } from 'node:util';
+
+import { program } from '@commander-js/extra-typings';
+
+export const exec = promisify(childProcess.exec);
+
+/* eslint-disable no-console */
+export const logger = {
+  error: console.error,
+  info: console.info,
+  warn: console.warn,
+};
+/* eslint-enable no-console */
+
+export const run = async (action: Promise<void>) => {
+  try {
+    await action;
+  } catch (error) {
+    program.error(String(error));
+  }
+};