@jakubmazanec/carson 0.1.0-9029e49

package/src/template/readCarsonTemplate.ts

@@ -0,0 +1,46 @@
+import {Template} from '@jakubmazanec/template';
+import {readFile} from '@jakubmazanec/zod-utils';
+import glob from 'fast-glob';
+import fs from 'fs-extra';
+import path from 'node:path';
+
+import {type CarsonTemplate} from './CarsonTemplate.js';
+import {carsonTemplateConfigSchema} from './CarsonTemplateConfig.js';
+import {parseTemplateId} from './parseTemplateId.js';
+import {resolveTemplateModule} from './resolveTemplateModule.js';
+import {templateAttributesSchema} from './TemplateAttributes.js';
+import {TEMPLATES_PATH, TEMPLATE_CONFIG_FILENAME} from '../constants.js';
+
+export async function readCarsonTemplate(templateId: string): Promise<CarsonTemplate> {
+  let [moduleId, templateName] = parseTemplateId(templateId);
+  let modulePath = await resolveTemplateModule(moduleId);
+  let carsonTemplatePath = path.join(modulePath, TEMPLATES_PATH, templateName);
+
+  if (await fs.pathExists(carsonTemplatePath)) {
+    let templateConfigPath = path.join(carsonTemplatePath, TEMPLATE_CONFIG_FILENAME);
+    let templateConfig = await readFile(templateConfigPath, carsonTemplateConfigSchema, {
+      throwOnZodError: true,
+    });
+    let templateFilePaths = await glob('**/*.ejs', {
+      cwd: carsonTemplatePath,
+      dot: true,
+    });
+    let carsonTemplate: CarsonTemplate = {
+      name: templateName,
+      config: templateConfig,
+      files: [],
+    };
+
+    for (let templateFilePath of templateFilePaths) {
+      carsonTemplate.files.push(
+        await Template.read(path.join(carsonTemplatePath, templateFilePath), {
+          attributesSchema: templateAttributesSchema,
+        }),
+      );
+    }
+
+    return carsonTemplate;
+  }
+
+  throw new Error(`Template ${templateId} was not found in module ${moduleId}!`);
+}

package/src/template/renderTemplate.ts

@@ -0,0 +1,30 @@
+import {importCarsonTemplate} from './importCarsonTemplate.js';
+import {readCarsonTemplate} from './readCarsonTemplate.js';
+import {type TemplateData} from './TemplateData.js';
+import {type TemplateRenders} from './TemplateRenders.js';
+
+export type RenderTemplateOptions = {
+  templateId: string;
+  templateData: TemplateData;
+};
+
+export async function renderTemplate(options: RenderTemplateOptions) {
+  let template = await readCarsonTemplate(options.templateId);
+  let templateModule = await importCarsonTemplate(options.templateId);
+  let templateRenders: TemplateRenders = [];
+
+  for (let file of template.files) {
+    templateRenders.push(
+      ...(await file.render(
+        {
+          ...templateModule,
+          ...options.templateData,
+          templateConfig: template.config,
+        },
+        {disablePrettier: true},
+      )),
+    );
+  }
+
+  return templateRenders;
+}

package/src/template/resolveTemplateModule.ts

@@ -0,0 +1,9 @@
+import {createRequire} from 'node:module';
+import path from 'node:path';
+
+export async function resolveTemplateModule(moduleId: string) {
+  let require = createRequire(import.meta.url);
+  let modulePath = path.dirname(require.resolve(`${moduleId}/package.json`));
+
+  return modulePath;
+}

package/src/template/saveTemplateRenderSnapshots.ts

@@ -0,0 +1,34 @@
+import {deflateSync, strToU8} from 'fflate';
+import fs from 'fs-extra';
+
+import {type TemplateRenders} from './TemplateRenders.js';
+import {type TemplateRenderSnapshots} from './TemplateRenderSnapshots.js';
+
+export async function saveTemplateRenderSnapshots(
+  templateRenders: TemplateRenders,
+  templateRenderSnapshotsPath: string,
+) {
+  let templateRendersSnapshots: TemplateRenderSnapshots = [];
+
+  for (let templateRender of templateRenders) {
+    if (
+      templateRender.attributes.strategy === 'overwrite' ||
+      templateRender.attributes.strategy === 'merge' ||
+      templateRender.attributes.strategy[0] === 'insert'
+    ) {
+      templateRendersSnapshots.push({
+        attributes: {
+          to: templateRender.attributes.to,
+          strategy: templateRender.attributes.strategy,
+        },
+        content: templateRender.content,
+      });
+    }
+  }
+  let uncompressedSnapshots = JSON.stringify(templateRendersSnapshots);
+
+  await fs.writeFile(
+    templateRenderSnapshotsPath,
+    deflateSync(strToU8(uncompressedSnapshots), {level: 1, mem: 0}),
+  );
+}

package/src/template/uninsertUsingTemplateRender.ts

@@ -0,0 +1,36 @@
+import fs from 'fs-extra';
+import _ from 'lodash';
+import path from 'node:path';
+
+import {prettify} from './internals.js';
+import {type TemplateRenderSnapshot} from './TemplateRenderSnapshot.js';
+
+export async function uninsertUsingTemplateRender(
+  render: TemplateRenderSnapshot,
+  basePath: string,
+) {
+  let to = path.join(basePath, render.attributes.to);
+  let extension = path.extname(to);
+
+  switch (extension) {
+    case '.md': {
+      let targetFile = await fs.readFile(to, {encoding: 'utf8'});
+      let newContent = `<!-- ${render.attributes.strategy[1]} --><!-- ${render.attributes.strategy[1]} -->`;
+      let oldContentRegexp = new RegExp(
+        `<!--\\s*${_.escapeRegExp(
+          render.attributes.strategy[1],
+        )}\\s-->[\\s\\S]*<!--\\s*${_.escapeRegExp(render.attributes.strategy[1])}\\s-->`,
+        'u',
+      );
+      let newFile = targetFile.replace(oldContentRegexp, newContent);
+
+      await fs.writeFile(to, await prettify(newFile, to), {encoding: 'utf8'});
+
+      break;
+    }
+
+    default: {
+      throw new Error(`File extension "${extension}" is not supported!`);
+    }
+  }
+}

package/src/template/unmergeFileUsingTemplateRender.ts

@@ -0,0 +1,42 @@
+import {type Json} from '@jakubmazanec/zod-utils';
+import fs from 'fs-extra';
+import json from 'json5';
+import path from 'node:path';
+import yaml from 'yaml';
+
+import {unmerge, prettify} from './internals.js';
+import {type TemplateRenderSnapshot} from './TemplateRenderSnapshot.js';
+
+export async function unmergeFileUsingTemplateRender(
+  render: TemplateRenderSnapshot,
+  outputPath: string,
+) {
+  let to = path.join(outputPath, render.attributes.to);
+  let extension = path.extname(to);
+
+  switch (extension) {
+    case '.json': {
+      let targetFile = (await fs.readJson(to)) as Json;
+      let fileToMerge = json.parse<Json>(render.content);
+      let newFile = JSON.stringify(unmerge(targetFile, fileToMerge));
+
+      await fs.writeFile(to, await prettify(newFile, to), {encoding: 'utf8'});
+
+      break;
+    }
+
+    case '.yaml': {
+      let targetFile = yaml.parse(await fs.readFile(to, {encoding: 'utf8'})) as unknown;
+      let fileToMerge = yaml.parse(render.content) as unknown;
+      let newFile = yaml.stringify(unmerge(targetFile, fileToMerge));
+
+      await fs.writeFile(to, await prettify(newFile, to), {encoding: 'utf8'});
+
+      break;
+    }
+
+    default: {
+      throw new Error(`File extension "${extension}" is not supported!`);
+    }
+  }
+}

package/src/template.ts

@@ -0,0 +1,20 @@
+export * from './template/applyTemplateRenders.js';
+export * from './template/CarsonTemplate.js';
+export * from './template/CarsonTemplateConfig.js';
+export * from './template/createFileUsingTemplateRender.js';
+export * from './template/deleteFileUsingTemplateRender.js';
+export * from './template/loadTemplateRenderSnapshots.js';
+export * from './template/mergeFileUsingTemplateRender.js';
+export * from './template/overwriteFileUsingTemplateRender.js';
+export * from './template/parseTemplateId.js';
+export * from './template/readCarsonTemplate.js';
+export * from './template/renderTemplate.js';
+export * from './template/resolveTemplateModule.js';
+export * from './template/saveTemplateRenderSnapshots.js';
+export * from './template/TemplateAttributes.js';
+export * from './template/TemplateData.js';
+export * from './template/TemplateRender.js';
+export * from './template/TemplateRenders.js';
+export * from './template/TemplateRenderSnapshot.js';
+export * from './template/TemplateRenderSnapshots.js';
+export * from './template/unmergeFileUsingTemplateRender.js';

package/src/workspace/Project.ts

@@ -0,0 +1,246 @@
+import {ensureEmptyDirectory, pathToPosixPath} from '@jakubmazanec/fs-utils';
+import {readFile, packageJsonSchema, type PackageJson} from '@jakubmazanec/zod-utils';
+import fs from 'fs-extra';
+import json5 from 'json5';
+import path from 'node:path';
+import {z} from 'zod';
+
+import {type ProjectConfig, projectConfigSchema} from './ProjectConfig.js';
+import {type ProjectCreateOptions} from './ProjectCreateOptions.js';
+import {ProjectError} from './ProjectError.js';
+import {type ProjectOptions} from './ProjectOptions.js';
+import {type ProjectUpdateOptions} from './ProjectUpdateOptions.js';
+import {saveProjectConfig} from './saveProjectConfig.js';
+import {type Workspace} from './Workspace.js';
+import {CARSON_CONFIG_DIRECTORY, PROJECT_CONFIG_FILENAME} from '../constants.js';
+import {applyTemplateRenders} from '../template/applyTemplateRenders.js';
+import {renderTemplate} from '../template/renderTemplate.js';
+
+/**
+ * Project represent a self-contained piece of software (e.g. a package, or an app) that is part of a {@linkcode Workspace}. Currently only Node.js projects are supported.
+ *
+ * @typeParam M If true, the project belongs to a multi-project workspace.
+ */
+export class Project<M extends boolean = true> {
+  /** Project name. */
+  name?: string;
+
+  /** Project path. */
+  path: string;
+
+  /** Project path relative to workspace path. */
+  relativePath: string;
+
+  /** Project configuration; if it's not found, the default is an empty object. */
+  config: ProjectConfig;
+
+  /** Parsed project `package.json` file; if it's not found, the default is an empty object. */
+  packageJson: PackageJson;
+
+  /** Parent {@linkcode Workspace} instance. */
+  workspace: Workspace<M>;
+
+  /** Errors found during reading from the file system. */
+  errors: Array<InstanceType<typeof ProjectError>> = [];
+
+  constructor({
+    path: projectPath,
+    name,
+    config,
+    packageJson,
+    workspace,
+    errors,
+  }: ProjectOptions<M>) {
+    // TODO: check that this path and workspace path are correct, i.e. project path must always be inside of workspace path
+    this.path = projectPath;
+
+    if (name) {
+      this.name = name;
+    }
+
+    if (config) {
+      this.config = config;
+    } else {
+      this.config = {};
+    }
+
+    if (packageJson) {
+      this.packageJson = packageJson;
+    } else {
+      this.packageJson = {};
+    }
+
+    this.workspace = workspace;
+
+    if (errors) {
+      this.errors = errors;
+    }
+
+    if (this.packageJson.name?.length) {
+      this.name = this.packageJson.name;
+    }
+
+    this.relativePath = pathToPosixPath(path.relative(this.workspace.path, this.path));
+  }
+
+  static async create<M extends boolean>({
+    templateId,
+    workspace,
+    projectPath,
+    projectName,
+    args,
+  }: ProjectCreateOptions<M>): Promise<Project<M>> {
+    let project = new this({
+      path: projectPath,
+      name: projectName,
+      config: {
+        template: templateId,
+      },
+      workspace,
+    });
+
+    await ensureEmptyDirectory(project.path);
+    await saveProjectConfig({projectPath: project.path, projectConfig: {template: templateId}});
+
+    let templateRenders = await renderTemplate({
+      templateId,
+      templateData: {
+        workspace,
+        project,
+        args,
+      },
+    });
+
+    await applyTemplateRenders({
+      templateRenders,
+      path: project.path,
+      ignoreCreateStrategies: false,
+      ignoreCheckStrategies: true,
+    });
+
+    await project.read();
+
+    return project;
+  }
+
+  static async read<M extends boolean>(
+    projectPath: string,
+    workspace: Workspace<M>,
+  ): Promise<Project<M>> {
+    let project = new this({
+      path: projectPath,
+      workspace,
+    });
+
+    await project.read();
+
+    return project;
+  }
+
+  async read() {
+    if (!(await fs.pathExists(this.path))) {
+      throw new ProjectError('NO_SUCH_PROJECT_PATH', {
+        messageParameters: [this.path],
+        data: {
+          path: this.path,
+        },
+      });
+    }
+
+    let errors: Array<InstanceType<typeof ProjectError>> = [];
+
+    // load project config
+    let projectConfigPath = path.join(this.path, CARSON_CONFIG_DIRECTORY, PROJECT_CONFIG_FILENAME);
+    let doesProjectConfigExist = await fs.pathExists(projectConfigPath);
+    let projectConfig: ProjectConfig | z.ZodError;
+
+    if (doesProjectConfigExist) {
+      projectConfig = await readFile(projectConfigPath, projectConfigSchema, {
+        parser: (rawString: string) => json5.parse<unknown>(rawString),
+      });
+    } else {
+      projectConfig = {};
+    }
+
+    if (projectConfig instanceof z.ZodError) {
+      let zodError = projectConfig;
+
+      errors.push(
+        new ProjectError('INVALID_PROJECT_CONFIG', {
+          messageParameters: [projectConfigPath],
+          data: {
+            path: projectConfigPath,
+            zodIssues: zodError.issues,
+          },
+        }),
+      );
+
+      projectConfig = {};
+    }
+
+    // load package.json
+    let packageJsonPath = path.join(this.path, 'package.json');
+    let doesPackageJsonExist = await fs.pathExists(packageJsonPath);
+    let packageJson: PackageJson | z.ZodError;
+
+    if (doesPackageJsonExist) {
+      packageJson = await readFile(packageJsonPath, packageJsonSchema, {
+        parser: (rawString: string) => json5.parse<unknown>(rawString),
+      });
+    } else {
+      packageJson = {};
+    }
+
+    if (packageJson instanceof z.ZodError) {
+      let zodError = packageJson;
+
+      errors.push(
+        new ProjectError('INVALID_PACKAGE_JSON', {
+          messageParameters: [packageJsonPath],
+          data: {
+            path: packageJsonPath,
+            zodIssues: zodError.issues,
+          },
+        }),
+      );
+
+      packageJson = {};
+    }
+
+    if (packageJson.name?.length) {
+      this.name = packageJson.name;
+    }
+
+    this.config = projectConfig;
+    this.packageJson = packageJson;
+    this.errors = errors;
+
+    return this;
+  }
+
+  async update({args}: ProjectUpdateOptions): Promise<this> {
+    if (!this.config.template) {
+      throw new Error('Template ID is missing in the project config!');
+    }
+
+    let templateRenders = await renderTemplate({
+      templateId: this.config.template,
+      templateData: {
+        workspace: this.workspace,
+        project: this,
+        args,
+      },
+    });
+
+    await applyTemplateRenders({
+      templateRenders,
+      path: this.path,
+      ignoreCreateStrategies: true,
+      ignoreCheckStrategies: false,
+    });
+
+    await this.read();
+
+    return this;
+  }
+}

package/src/workspace/ProjectConfig.ts

@@ -0,0 +1,9 @@
+import {z} from 'zod';
+
+export const projectConfigSchema = z
+  .object({
+    template: z.string().optional(),
+  })
+  .catchall(z.unknown());
+
+export type ProjectConfig = z.infer<typeof projectConfigSchema>;

package/src/workspace/ProjectCreateOptions.ts

@@ -0,0 +1,9 @@
+import {type Workspace} from './Workspace.js';
+
+export type ProjectCreateOptions<M extends boolean> = {
+  templateId: string;
+  workspace: Workspace<M>;
+  projectPath: string;
+  projectName: string;
+  args: Record<string, unknown>;
+};

package/src/workspace/ProjectError.ts

@@ -0,0 +1,15 @@
+import {createCustomErrorWithData} from '@jakubmazanec/error';
+import {type ZodIssue} from 'zod';
+
+export const ProjectError = createCustomErrorWithData(
+  'ProjectError',
+  {
+    INVALID_PACKAGE_JSON: 'Invalid package.json file "{0}".',
+    INVALID_PROJECT_CONFIG: 'Invalid project config file "{0}".',
+    NO_SUCH_PROJECT_PATH: 'Project path "{0}" doesn\'t exist.',
+  },
+  class ProjectErrorData {
+    path?: string;
+    zodIssues?: ZodIssue[];
+  },
+);

package/src/workspace/ProjectOptions.ts

@@ -0,0 +1,17 @@
+import {type PackageJson} from '@jakubmazanec/zod-utils';
+
+import {type ProjectConfig} from './ProjectConfig.js';
+import {type ProjectError} from './ProjectError.js';
+import {type Workspace} from './Workspace.js';
+
+/**
+ * New project options.
+ */
+export type ProjectOptions<M extends boolean> = {
+  path: string;
+  name?: string;
+  config?: ProjectConfig;
+  packageJson?: PackageJson;
+  workspace: Workspace<M>;
+  errors?: Array<InstanceType<typeof ProjectError>>;
+};

package/src/workspace/ProjectUpdateOptions.ts

@@ -0,0 +1,3 @@
+export type ProjectUpdateOptions = {
+  args: Record<string, unknown>;
+};