@form8ion/javascript 15.6.0 → 15.6.1

package/src/options/schemas.test.js

@@ -0,0 +1,147 @@
+import {validateOptions} from '@form8ion/core';
+
+import {describe, expect, it} from 'vitest';
+import any from '@travi/any';
+
+import {
+  nameBasedConfigSchema,
+  projectNameSchema,
+  registriesSchema,
+  scopeBasedConfigSchema,
+  visibilitySchema
+} from './schemas.js';
+
+describe('options schemas', () => {
+  describe('scope-based configs', () => {
+    it('should require a provided config to be an object', () => {
+      expect(() => validateOptions(scopeBasedConfigSchema, any.word())).toThrowError('"value" must be of type object');
+    });
+
+    it('should require a provided config to have a `scope` property', () => {
+      expect(() => validateOptions(scopeBasedConfigSchema, {})).toThrowError('"scope" is required');
+    });
+
+    it('should require the `scope` to be a string', () => {
+      expect(() => validateOptions(scopeBasedConfigSchema, {scope: any.simpleObject()}))
+        .toThrowError('"scope" must be a string');
+    });
+
+    it('should require the `scope` to start with `@`', () => {
+      const scope = any.word();
+
+      expect(() => validateOptions(scopeBasedConfigSchema, {scope}))
+        .toThrowError(`"scope" with value "${scope}" fails to match the scope pattern`);
+    });
+
+    it('should not allow the `scope` to contain a `/`', () => {
+      const scope = `@${any.word()}/${any.word()}`;
+
+      expect(() => validateOptions(scopeBasedConfigSchema, {scope}))
+        .toThrowError(`"scope" with value "${scope}" fails to match the scope pattern`);
+    });
+
+    it('should allow `scope` to contain `-`', () => {
+      const scope = `@${any.word()}-${any.word()}`;
+
+      expect(validateOptions(scopeBasedConfigSchema, {scope})).toEqual({scope});
+    });
+  });
+
+  describe('name-based configs', () => {
+    it('should require a provided config to be an object', () => {
+      expect(() => validateOptions(nameBasedConfigSchema, any.word())).toThrowError('"value" must be of type object');
+    });
+
+    it('should require a provided config to have a `packageName` property', () => {
+      expect(() => validateOptions(nameBasedConfigSchema, {})).toThrowError('"packageName" is required');
+    });
+
+    it('should require the `packageName` to be a string', () => {
+      expect(() => validateOptions(nameBasedConfigSchema, {packageName: any.simpleObject()}))
+        .toThrowError('"packageName" must be a string');
+    });
+
+    it('should require a provided config to have a `name` property', () => {
+      expect(() => validateOptions(nameBasedConfigSchema, {packageName: any.word()}))
+        .toThrowError('"name" is required');
+    });
+
+    it('should require the `name` to be a string', () => {
+      expect(() => validateOptions(nameBasedConfigSchema, {packageName: any.word(), name: any.simpleObject()}))
+        .toThrowError('"name" must be a string');
+    });
+  });
+
+  describe('registries', () => {
+    const key = any.word();
+
+    it('should return an empty object when no registries are provided', () => {
+      expect(validateOptions(registriesSchema)).toEqual({});
+    });
+
+    it('should return the validated registries when valid', () => {
+      const registries = {[any.word()]: any.url()};
+
+      expect(validateOptions(registriesSchema, registries)).toEqual(registries);
+    });
+
+    it('should require the `registries` definition to be an object', () => {
+      expect(() => validateOptions(registriesSchema, any.word())).toThrowError('"value" must be of type object');
+    });
+
+    it('should require the values to be strings', () => {
+      expect(() => validateOptions(registriesSchema, {[key]: any.integer()})).toThrowError(`"${key}" must be a string`);
+    });
+
+    it('should require the values to be URIs', () => {
+      expect(() => validateOptions(registriesSchema, {[key]: any.string()}))
+        .toThrowError(`"${key}" must be a valid uri`);
+    });
+  });
+
+  describe('visibility', () => {
+    it('should require a value to be provided', () => {
+      expect(() => validateOptions(visibilitySchema)).toThrowError('"value" is required');
+    });
+
+    it('should allow `Public` as a valid value', () => {
+      const visibility = 'Public';
+
+      expect(validateOptions(visibilitySchema, visibility)).toEqual(visibility);
+    });
+
+    it('should allow `Private` as a valid value', () => {
+      const visibility = 'Private';
+
+      expect(validateOptions(visibilitySchema, visibility)).toEqual(visibility);
+    });
+
+    it('should consider values other than `Public` and `Private` as invalid', () => {
+      expect(() => validateOptions(visibilitySchema, any.word()))
+        .toThrowError('"value" must be one of [Public, Private]');
+    });
+  });
+
+  describe('project name', () => {
+    it('should return the validated name', () => {
+      const projectName = any.word();
+
+      expect(validateOptions(projectNameSchema, projectName)).toEqual(projectName);
+    });
+
+    it('should require a value to be provided', () => {
+      expect(() => validateOptions(projectNameSchema)).toThrowError('"value" is required');
+    });
+
+    it('should require a value to be a string', () => {
+      expect(() => validateOptions(projectNameSchema, any.simpleObject())).toThrowError('"value" must be a string');
+    });
+
+    it('should prevent the project name from including a scope', () => {
+      const projectName = `@${any.word()}/${any.word()}`;
+
+      expect(() => validateOptions(projectNameSchema, projectName))
+        .toThrowError(`"value" with value "${projectName}" matches the inverted pattern: /^@\\w*\\//`);
+    });
+  });
+});

package/src/options/validator.js

@@ -0,0 +1,45 @@
+import joi from 'joi';
+import {validateOptions} from '@form8ion/core';
+
+import {pluginsSchema} from '../plugins-schemas.js';
+import {
+  nameBasedConfigSchema,
+  projectNameSchema,
+  registriesSchema,
+  scopeBasedConfigSchema,
+  visibilitySchema
+} from './schemas.js';
+import {vcsSchema} from '../vcs/schema.js';
+
+export function validate(options) {
+  const schema = joi.object({
+    projectRoot: joi.string().required(),
+    projectName: projectNameSchema,
+    visibility: visibilitySchema,
+    license: joi.string().required(),
+    description: joi.string(),
+    pathWithinParent: joi.string(),
+    decisions: joi.object(),
+    vcs: vcsSchema,
+    configs: joi.object({
+      eslint: scopeBasedConfigSchema,
+      typescript: scopeBasedConfigSchema,
+      prettier: scopeBasedConfigSchema,
+      commitlint: nameBasedConfigSchema,
+      babelPreset: nameBasedConfigSchema,
+      remark: joi.string(),
+      registries: registriesSchema
+    }).default({registries: {}}),
+    plugins: {
+      unitTestFrameworks: pluginsSchema,
+      packageBundlers: pluginsSchema,
+      applicationTypes: pluginsSchema,
+      packageTypes: pluginsSchema,
+      monorepoTypes: pluginsSchema,
+      hosts: pluginsSchema,
+      ciServices: pluginsSchema
+    }
+  }).required();
+
+  return validateOptions(schema, options);
+}

package/src/options/validator.test.js

@@ -0,0 +1,79 @@
+import joi from 'joi';
+import {validateOptions} from '@form8ion/core';
+
+import {beforeEach, describe, expect, it, vi} from 'vitest';
+import {when} from 'vitest-when';
+import any from '@travi/any';
+
+import {
+  nameBasedConfigSchema, projectNameSchema,
+  registriesSchema,
+  scopeBasedConfigSchema,
+  visibilitySchema
+} from './schemas.js';
+import {pluginsSchema} from '../plugins-schemas.js';
+import {validate} from './validator.js';
+import {vcsSchema} from '../vcs/schema.js';
+
+vi.mock('@form8ion/core');
+
+describe('options validator', () => {
+  beforeEach(() => {
+    vi.spyOn(joi, 'object');
+    vi.spyOn(joi, 'string');
+  });
+
+  it('should validate the provided options against the js-plugin schema', () => {
+    const options = any.simpleObject();
+    const validatedOptions = any.simpleObject();
+    const schema = any.simpleObject();
+    const joiRequiredObject = vi.fn();
+    const joiRequiredString = vi.fn();
+    const requiredString = any.simpleObject();
+    const joiString = {required: joiRequiredString};
+    const joiObject = any.simpleObject();
+    const configsDefault = vi.fn();
+    const configs = any.simpleObject();
+    when(joi.string).calledWith().thenReturn(joiString);
+    when(joiRequiredString).calledWith().thenReturn(requiredString);
+    when(joi.object).calledWith().thenReturn(joiObject);
+    when(joi.object)
+      .calledWith({
+        eslint: scopeBasedConfigSchema,
+        typescript: scopeBasedConfigSchema,
+        prettier: scopeBasedConfigSchema,
+        commitlint: nameBasedConfigSchema,
+        babelPreset: nameBasedConfigSchema,
+        remark: joiString,
+        registries: registriesSchema
+      })
+      .thenReturn({default: configsDefault});
+    when(configsDefault).calledWith({registries: {}}).thenReturn(configs);
+    when(joi.object)
+      .calledWith({
+        projectRoot: requiredString,
+        projectName: projectNameSchema,
+        license: requiredString,
+        visibility: visibilitySchema,
+        description: joiString,
+        pathWithinParent: joiString,
+        decisions: joiObject,
+        vcs: vcsSchema,
+        configs,
+        plugins: {
+          unitTestFrameworks: pluginsSchema,
+          packageBundlers: pluginsSchema,
+          applicationTypes: pluginsSchema,
+          packageTypes: pluginsSchema,
+          monorepoTypes: pluginsSchema,
+          hosts: pluginsSchema,
+          ciServices: pluginsSchema
+        }
+      })
+      .thenReturn({required: joiRequiredObject});
+    when(joiRequiredObject).calledWith().thenReturn(schema);
+    when(validateOptions).calledWith(schema, options).thenReturn(validatedOptions);
+
+    expect(validate(options)).toEqual(validatedOptions);
+  });
+});

package/src/package/details.js

@@ -0,0 +1,18 @@
+import {dialects} from '@form8ion/javascript-core';
+
+export default function scaffoldPackageJsonDetails({
+  packageName,
+  dialect,
+  license,
+  author,
+  description
+}) {
+  return {
+    name: packageName,
+    description,
+    license,
+    type: dialects.ESM === dialect ? 'module' : 'commonjs',
+    author: `${author.name}${author.email ? ` <${author.email}>` : ''}${author.url ? ` (${author.url})` : ''}`,
+    scripts: {}
+  };
+}

package/src/package/details.test.js

@@ -0,0 +1,51 @@
+import {dialects} from '@form8ion/javascript-core';
+
+import {describe, it, expect} from 'vitest';
+import any from '@travi/any';
+
+import defineDetails from './details.js';
+
+describe('package details builder', () => {
+  const authorName = `${any.word()} ${any.word()}`;
+  const authorEmail = any.email();
+  const authorWebsite = any.url();
+
+  it('should define the initial details for the package.json file', () => {
+    const packageName = any.word();
+    const license = any.word();
+    const description = any.sentence();
+
+    expect(defineDetails({packageName, description, license, author: {name: authorName}})).toEqual({
+      name: packageName,
+      description,
+      license,
+      type: 'commonjs',
+      author: authorName,
+      scripts: {}
+    });
+  });
+
+  it('should define `type` as `module` when the dialect is esm', () => {
+    const {type} = defineDetails({author: {}, dialect: dialects.ESM});
+
+    expect(type).toEqual('module');
+  });
+
+  it('should include author email when defined', () => {
+    const {author} = defineDetails({author: {name: authorName, email: authorEmail}});
+
+    expect(author).toEqual(`${authorName} <${authorEmail}>`);
+  });
+
+  it('should include author website when defined', () => {
+    const {author} = defineDetails({author: {name: authorName, url: authorWebsite}});
+
+    expect(author).toEqual(`${authorName} (${authorWebsite})`);
+  });
+
+  it('should include author email and website when both are defined', () => {
+    const {author} = defineDetails({author: {name: authorName, email: authorEmail, url: authorWebsite}});
+
+    expect(author).toEqual(`${authorName} <${authorEmail}> (${authorWebsite})`);
+  });
+});

package/src/package/index.js

@@ -0,0 +1,2 @@
+export {default as scaffold} from './scaffolder.js';
+export {default as lift} from './lifter.js';

package/src/package/lifter.js

@@ -0,0 +1,47 @@
+import {promises as fs} from 'node:fs';
+import deepmerge from 'deepmerge';
+import {info} from '@travi/cli-messages';
+import {writePackageJson} from '@form8ion/javascript-core';
+
+import sortPackageProperties from './property-sorter.js';
+import defineVcsHostDetails from './vcs-host-details.js';
+import {process as processDependencies} from '../dependencies/index.js';
+import {lift as liftScripts} from './scripts/index.js';
+
+export default async function liftPackageJson({
+  projectRoot,
+  scripts,
+  tags,
+  dependencies,
+  devDependencies,
+  packageManager,
+  vcs,
+  pathWithinParent
+}) {
+  info('Updating `package.json`', {level: 'secondary'});
+
+  const existingPackageJsonContents = JSON.parse(await fs.readFile(`${projectRoot}/package.json`, 'utf-8'));
+  const {scripts: liftedScripts, dependencies: scriptDependencies} = liftScripts({
+    existingScripts: existingPackageJsonContents.scripts,
+    scripts
+  });
+
+  await writePackageJson({
+    projectRoot,
+    config: sortPackageProperties({
+      ...existingPackageJsonContents,
+      ...defineVcsHostDetails(vcs, pathWithinParent),
+      scripts: liftedScripts,
+      ...tags && {
+        keywords: existingPackageJsonContents.keywords ? [...existingPackageJsonContents.keywords, ...tags] : tags
+      }
+    })
+  });
+
+  await processDependencies({
+    dependencies: deepmerge(dependencies, scriptDependencies),
+    devDependencies,
+    projectRoot,
+    packageManager
+  });
+}

package/src/package/lifter.test.js

@@ -0,0 +1,100 @@
+import {promises as fs} from 'node:fs';
+import deepmerge from 'deepmerge';
+import {writePackageJson} from '@form8ion/javascript-core';
+
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import any from '@travi/any';
+import {when} from 'vitest-when';
+
+import {process as processDependencies} from '../dependencies/index.js';
+import {lift as liftScripts} from './scripts/index.js';
+import defineVcsHostDetails from './vcs-host-details.js';
+import sortPackageProperties from './property-sorter.js';
+import liftPackage from './lifter.js';
+
+vi.mock('node:fs');
+vi.mock('deepmerge');
+vi.mock('@form8ion/javascript-core');
+vi.mock('../dependencies/index.js');
+vi.mock('./scripts/index.js');
+vi.mock('./vcs-host-details.js');
+vi.mock('./property-sorter.js');
+
+describe('package.json lifter', () => {
+  const projectRoot = any.string();
+  const dependencies = any.simpleObject();
+  const mergedDependencies = any.simpleObject();
+  const packageManager = any.word();
+  const vcs = any.simpleObject();
+  const pathWithinParent = any.string();
+  const scripts = any.simpleObject();
+  const existingScripts = any.simpleObject();
+  const liftedScripts = any.simpleObject();
+  const vcsDetails = any.simpleObject();
+  const config = any.simpleObject();
+  const tags = any.listOf(any.word);
+  const scriptDependencies = any.simpleObject();
+
+  beforeEach(() => {
+    when(defineVcsHostDetails).calledWith(vcs, pathWithinParent).thenReturn(vcsDetails);
+    when(liftScripts)
+      .calledWith({existingScripts, scripts})
+      .thenReturn({scripts: liftedScripts, dependencies: scriptDependencies});
+    when(deepmerge).calledWith(dependencies, scriptDependencies).thenReturn(mergedDependencies);
+  });
+
+  it('should update package.json properties and process dependencies', async () => {
+    const existingPackageContents = {...any.simpleObject(), scripts: existingScripts};
+    const devDependencies = any.listOf(any.word);
+    when(fs.readFile)
+      .calledWith(`${projectRoot}/package.json`, 'utf-8')
+      .thenResolve(JSON.stringify(existingPackageContents));
+    when(sortPackageProperties)
+      .calledWith({...existingPackageContents, ...vcsDetails, scripts: liftedScripts})
+      .thenReturn(config);
+
+    await liftPackage({dependencies, devDependencies, projectRoot, packageManager, vcs, pathWithinParent, scripts});
+
+    expect(writePackageJson).toHaveBeenCalledWith({projectRoot, config});
+    expect(processDependencies).toHaveBeenCalledWith({
+      dependencies: mergedDependencies,
+      devDependencies,
+      projectRoot,
+      packageManager
+    });
+  });
+
+  it('should update keywords if tags are provided', async () => {
+    const existingPackageContents = {...any.simpleObject(), scripts: existingScripts};
+    when(fs.readFile)
+      .calledWith(`${projectRoot}/package.json`, 'utf-8')
+      .thenResolve(JSON.stringify(existingPackageContents));
+    when(sortPackageProperties)
+      .calledWith({...existingPackageContents, ...vcsDetails, scripts: liftedScripts, keywords: tags})
+      .thenReturn(config);
+
+    await liftPackage({dependencies, projectRoot, packageManager, vcs, pathWithinParent, scripts, tags});
+
+    expect(writePackageJson).toHaveBeenCalledWith({projectRoot, config});
+  });
+
+  it('should append the provided tags to existing keywords', async () => {
+    const existingKeywords = any.listOf(any.word);
+    const existingPackageContents = {...any.simpleObject(), scripts: existingScripts, keywords: existingKeywords};
+    when(fs.readFile)
+      .calledWith(`${projectRoot}/package.json`, 'utf-8')
+      .thenResolve(JSON.stringify(existingPackageContents));
+    when(sortPackageProperties)
+      .calledWith({
+        ...existingPackageContents,
+        ...vcsDetails,
+        scripts: liftedScripts,
+        keywords: [...existingKeywords, ...tags]
+      })
+      .thenReturn(config);
+
+    await liftPackage({dependencies, projectRoot, packageManager, vcs, pathWithinParent, scripts, tags});
+
+    expect(writePackageJson).toHaveBeenCalledWith({projectRoot, config});
+  });
+});

package/src/package/package-name.js

@@ -0,0 +1,13 @@
+import {EOL} from 'os';
+import validatePackageName from '../../thirdparty-wrappers/validate-npm-package-name.js';
+
+export default function determinePackageName(projectName, scope) {
+  const name = `${scope ? `@${scope}/` : ''}${projectName}`;
+
+  const {validForNewPackages, errors} = validatePackageName(name);
+
+  if (validForNewPackages) return name;
+  if (1 === errors.length && errors.includes('name cannot start with a period')) return projectName.slice(1);
+
+  throw new Error(`The package name ${name} is invalid:${EOL}\t* ${errors.join(`${EOL}\t* `)}`);
+}

package/src/package/package-name.test.js

@@ -0,0 +1,52 @@
+import {EOL} from 'os';
+
+import any from '@travi/any';
+import {describe, it, expect, vi} from 'vitest';
+import {when} from 'vitest-when';
+
+import validatePackageName from '../../thirdparty-wrappers/validate-npm-package-name.js';
+import packageName from './package-name.js';
+
+vi.mock('../../thirdparty-wrappers/validate-npm-package-name.js');
+
+describe('package name', () => {
+  const projectName = any.word();
+
+  it('should return the project name if no scope is provided', () => {
+    when(validatePackageName).calledWith(projectName).thenReturn({validForNewPackages: true});
+
+    expect(packageName(projectName)).toEqual(projectName);
+  });
+
+  it('should include the scope in the name when provided', () => {
+    const scope = any.word();
+    const scopedName = `@${scope}/${projectName}`;
+    when(validatePackageName).calledWith(scopedName).thenReturn({validForNewPackages: true});
+
+    expect(packageName(projectName, scope)).toEqual(scopedName);
+  });
+
+  it('should throw and error when the value is not valid for npm', () => {
+    const errors = any.listOf(any.sentence);
+    when(validatePackageName).calledWith(projectName).thenReturn({validForNewPackages: false, errors});
+
+    expect(() => packageName(projectName))
+      .toThrowError(`The package name ${projectName} is invalid:${EOL}\t* ${errors.join(`${EOL}\t* `)}`);
+  });
+
+  it('should strip a leading dot from the package name', () => {
+    when(validatePackageName)
+      .calledWith(`.${projectName}`)
+      .thenReturn({validForNewPackages: false, errors: ['name cannot start with a period']});
+
+    expect(packageName(`.${projectName}`)).toEqual(projectName);
+  });
+
+  it('should throw an error if more validation erros than a leading dot exist', () => {
+    const errors = [...any.listOf(any.sentence), 'name cannot start with a period'];
+    when(validatePackageName).calledWith(projectName).thenReturn({validForNewPackages: false, errors});
+
+    expect(() => packageName(projectName))
+      .toThrowError(`The package name ${projectName} is invalid:${EOL}\t* ${errors.join(`${EOL}\t* `)}`);
+  });
+});

package/src/package/property-sorter.js

@@ -0,0 +1,38 @@
+import sortObjectKeys from 'sort-object-keys';
+
+export default function sortProperties(packageContents) {
+  return sortObjectKeys(
+    packageContents,
+    [
+      'name',
+      'description',
+      'license',
+      'version',
+      'private',
+      'type',
+      'engines',
+      'author',
+      'contributors',
+      'repository',
+      'bugs',
+      'homepage',
+      'funding',
+      'keywords',
+      'runkitExampleFilename',
+      'exports',
+      'bin',
+      'main',
+      'module',
+      'types',
+      'sideEffects',
+      'scripts',
+      'files',
+      'publishConfig',
+      'packageManager',
+      'config',
+      'dependencies',
+      'devDependencies',
+      'peerDependencies'
+    ]
+  );
+}

package/src/package/property-sorter.test.js

@@ -0,0 +1,56 @@
+import sortObjectKeys from 'sort-object-keys';
+
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import any from '@travi/any';
+import {when} from 'vitest-when';
+
+import sortProperties from './property-sorter.js';
+
+vi.mock('sort-object-keys');
+
+describe('package.json property sorter', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should sort the package properties based on the defined order', () => {
+    const packageContents = any.simpleObject();
+    const sortedPackageContents = any.simpleObject();
+    when(sortObjectKeys).calledWith(
+      packageContents,
+      [
+        'name',
+        'description',
+        'license',
+        'version',
+        'private',
+        'type',
+        'engines',
+        'author',
+        'contributors',
+        'repository',
+        'bugs',
+        'homepage',
+        'funding',
+        'keywords',
+        'runkitExampleFilename',
+        'exports',
+        'bin',
+        'main',
+        'module',
+        'types',
+        'sideEffects',
+        'scripts',
+        'files',
+        'publishConfig',
+        'packageManager',
+        'config',
+        'dependencies',
+        'devDependencies',
+        'peerDependencies'
+      ]
+    ).thenReturn(sortedPackageContents);
+
+    expect(sortProperties(packageContents)).toEqual(sortedPackageContents);
+  });
+});