@form8ion/javascript 15.6.0 → 15.6.1

package/src/project-type/package/build-details.js

@@ -0,0 +1,56 @@
+import {promises as fs} from 'node:fs';
+import deepmerge from 'deepmerge';
+import touch from 'touch';
+import {dialects, projectTypes} from '@form8ion/javascript-core';
+import {scaffold as scaffoldBundler} from '../publishable/bundler/index.js';
+
+const defaultBuildDirectory = 'lib';
+
+async function createExample(projectRoot) {
+  return fs.writeFile(`${projectRoot}/example.js`, "import {} from './lib/index.js';\n");
+}
+
+async function buildDetailsForCommonJsProject({projectRoot, provideExample}) {
+  await Promise.all([
+    touch(`${projectRoot}/index.js`),
+    provideExample
+      ? fs.writeFile(`${projectRoot}/example.js`, "const {} = require('.');\n")
+      : Promise.resolve()
+  ]);
+
+  return {};
+}
+
+export default async function buildDetails({
+  projectRoot,
+  projectName,
+  packageBundlers,
+  dialect,
+  provideExample,
+  decisions
+}) {
+  if (dialects.COMMON_JS === dialect) return buildDetailsForCommonJsProject({projectRoot, provideExample});
+
+  await fs.mkdir(`${projectRoot}/src`, {recursive: true});
+  const [bundlerResults] = await Promise.all([
+    scaffoldBundler({bundlers: packageBundlers, projectRoot, dialect, decisions, projectType: projectTypes.PACKAGE}),
+    provideExample ? await createExample(projectRoot, projectName, dialect) : Promise.resolve,
+    touch(`${projectRoot}/src/index.js`)
+  ]);
+
+  return deepmerge(
+    bundlerResults,
+    {
+      dependencies: {javascript: {development: ['rimraf']}},
+      scripts: {
+        clean: `rimraf ./${defaultBuildDirectory}`,
+        prebuild: 'run-s clean',
+        build: 'npm-run-all --print-label --parallel build:*',
+        prepack: 'run-s build',
+        ...provideExample && {'pregenerate:md': 'run-s build'}
+      },
+      vcsIgnore: {directories: [`/${defaultBuildDirectory}/`]},
+      buildDirectory: defaultBuildDirectory
+    }
+  );
+}

package/src/project-type/package/build-details.test.js

@@ -0,0 +1,111 @@
+import {promises as fs} from 'node:fs';
+import touch from 'touch';
+import {dialects, projectTypes} from '@form8ion/javascript-core';
+
+import {describe, expect, it, vi} from 'vitest';
+import any from '@travi/any';
+import {when} from 'vitest-when';
+
+import {scaffold as scaffoldBundler} from '../publishable/bundler/index.js';
+import buildDetails from './build-details.js';
+
+vi.mock('node:fs');
+vi.mock('make-dir');
+vi.mock('touch');
+vi.mock('../publishable/bundler');
+
+describe('package build details', () => {
+  const projectRoot = any.string();
+  const projectName = any.word();
+  const pathToExample = `${projectRoot}/example.js`;
+  const bundlerResults = any.simpleObject();
+  const packageBundlers = any.simpleObject();
+  const decisions = any.simpleObject();
+
+  it('should correctly define a common-js project', async () => {
+    const results = await buildDetails({
+      dialect: dialects.COMMON_JS,
+      projectRoot,
+      projectName,
+      provideExample: true
+    });
+
+    expect(results).toEqual({});
+    expect(fs.writeFile).toHaveBeenCalledWith(pathToExample, "const {} = require('.');\n");
+    expect(touch).toHaveBeenCalledWith(`${projectRoot}/index.js`);
+  });
+
+  it('should not create the example file for a common-js project if `provideExample` is `false`', async () => {
+    await buildDetails({
+      dialect: dialects.COMMON_JS,
+      projectRoot,
+      projectName,
+      provideExample: false
+    });
+
+    expect(fs.writeFile).not.toHaveBeenCalled();
+  });
+
+  it('should define a modern-js project correctly', async () => {
+    const dialect = dialects.BABEL;
+    when(scaffoldBundler)
+      .calledWith({bundlers: packageBundlers, decisions, projectRoot, dialect, projectType: projectTypes.PACKAGE})
+      .thenResolve(bundlerResults);
+
+    const results = await buildDetails({
+      dialect,
+      projectRoot,
+      projectName,
+      packageBundlers,
+      decisions,
+      provideExample: true
+    });
+
+    expect(results).toEqual({
+      ...bundlerResults,
+      dependencies: {javascript: {development: ['rimraf']}},
+      scripts: {
+        clean: 'rimraf ./lib',
+        prebuild: 'run-s clean',
+        build: 'npm-run-all --print-label --parallel build:*',
+        prepack: 'run-s build',
+        'pregenerate:md': 'run-s build'
+      },
+      vcsIgnore: {directories: ['/lib/']},
+      buildDirectory: 'lib'
+    });
+    expect(fs.mkdir).toHaveBeenCalledWith(`${projectRoot}/src`, {recursive: true});
+    expect(touch).toHaveBeenCalledWith(`${projectRoot}/src/index.js`);
+    expect(fs.writeFile).toHaveBeenCalledWith(pathToExample, "import {} from './lib/index.js';\n");
+  });
+
+  it('should not create the example file for a modern-js project when `provideExample` is `false`', async () => {
+    const dialect = dialects.BABEL;
+    when(scaffoldBundler)
+      .calledWith({bundlers: packageBundlers, decisions, projectRoot, dialect, projectType: projectTypes.PACKAGE})
+      .thenResolve(bundlerResults);
+
+    const results = await buildDetails({
+      dialect,
+      projectRoot,
+      projectName,
+      packageBundlers,
+      decisions,
+      provideExample: false
+    });
+
+    expect(results).toEqual({
+      ...bundlerResults,
+      dependencies: {javascript: {development: ['rimraf']}},
+      scripts: {
+        clean: 'rimraf ./lib',
+        prebuild: 'run-s clean',
+        build: 'npm-run-all --print-label --parallel build:*',
+        prepack: 'run-s build'
+      },
+      vcsIgnore: {directories: ['/lib/']},
+      buildDirectory: 'lib'
+    });
+    expect(fs.writeFile).not.toHaveBeenCalled();
+  });
+});

package/src/project-type/package/documentation.js

@@ -0,0 +1,34 @@
+import {packageManagers} from '@form8ion/javascript-core';
+
+import buildGenerationCommand from '../../documentation/generation-command.js';
+
+function getInstallationCommand(packageManager) {
+  if (packageManagers.NPM === packageManager) return 'npm install';
+  if (packageManagers.YARN === packageManager) return 'yarn add';
+
+  throw new Error(
+    `The ${packageManager} package manager is currently not supported. `
+    + `Only ${Object.values(packageManagers).join(' and ')} are currently supported.`
+  );
+}
+
+export default function scaffoldPackageDocumentation({scope, packageName, packageManager, visibility, provideExample}) {
+  return {
+    usage: `### Installation
+${'Private' === visibility ? `
+:warning: this is a private package, so you will need to use an npm token with
+access to private packages under \`@${scope}\`
+` : ''
+}
+\`\`\`sh
+$ ${getInstallationCommand(packageManager)} ${packageName}
+\`\`\`${provideExample
+    ? `
+
+### Example
+
+run \`${buildGenerationCommand(packageManager)}\` to inject the usage example`
+    : ''
+}`
+  };
+}

package/src/project-type/package/documentation.test.js

@@ -0,0 +1,106 @@
+import {packageManagers} from '@form8ion/javascript-core';
+
+import any from '@travi/any';
+import {describe, expect, it, vi} from 'vitest';
+import {when} from 'vitest-when';
+
+import buildDocumentationCommand from '../../documentation/generation-command.js';
+import scaffoldDocumentation from './documentation.js';
+
+vi.mock('../../documentation/generation-command.js');
+
+describe('package documentation', () => {
+  const packageName = any.string();
+  const documentationGenerationCommand = any.string();
+
+  it('should provide `npm install` instructions for packages when the package manager is npm', () => {
+    when(buildDocumentationCommand).calledWith(packageManagers.NPM).thenReturn(documentationGenerationCommand);
+
+    const documentation = scaffoldDocumentation({
+      packageName,
+      packageManager: packageManagers.NPM,
+      provideExample: true
+    });
+
+    expect(documentation.usage).toEqual(`### Installation
+
+\`\`\`sh
+$ npm install ${packageName}
+\`\`\`
+
+### Example
+
+run \`${documentationGenerationCommand}\` to inject the usage example`);
+  });
+
+  it('should not include the example section when `provideExample` is `false`', () => {
+    when(buildDocumentationCommand).calledWith(packageManagers.NPM).thenReturn(documentationGenerationCommand);
+
+    const documentation = scaffoldDocumentation({
+      packageName,
+      packageManager: packageManagers.NPM,
+      provideExample: false
+    });
+
+    expect(documentation.usage).toEqual(`### Installation
+
+\`\`\`sh
+$ npm install ${packageName}
+\`\`\``);
+  });
+
+  it('should provide `yarn add` instructions for packages when the package manager is yarn', () => {
+    when(buildDocumentationCommand).calledWith(packageManagers.YARN).thenReturn(documentationGenerationCommand);
+
+    const documentation = scaffoldDocumentation({
+      packageName,
+      packageManager: packageManagers.YARN,
+      provideExample: true
+    });
+
+    expect(documentation.usage).toEqual(`### Installation
+
+\`\`\`sh
+$ yarn add ${packageName}
+\`\`\`
+
+### Example
+
+run \`${documentationGenerationCommand}\` to inject the usage example`);
+  });
+
+  it('should throw an error for unsupported package managers', () => {
+    const packageManager = any.word();
+
+    expect(() => scaffoldDocumentation({packageName, packageManager})).toThrowError(
+      `The ${packageManager} package manager is currently not supported. `
+      + `Only ${Object.values(packageManagers).join(' and ')} are currently supported.`
+    );
+  });
+
+  it('should provide an access note for private packages', () => {
+    const scope = any.word();
+    when(buildDocumentationCommand).calledWith(packageManagers.NPM).thenReturn(documentationGenerationCommand);
+
+    const documentation = scaffoldDocumentation({
+      packageName,
+      packageManager: packageManagers.NPM,
+      visibility: 'Private',
+      scope,
+      provideExample: true
+    });
+
+    expect(documentation.usage).toEqual(`### Installation
+
+:warning: this is a private package, so you will need to use an npm token with
+access to private packages under \`@${scope}\`
+
+\`\`\`sh
+$ npm install ${packageName}
+\`\`\`
+
+### Example
+
+run \`${documentationGenerationCommand}\` to inject the usage example`);
+  });
+});

package/src/project-type/package/index.js

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

package/src/project-type/package/lifter.js

@@ -0,0 +1,5 @@
+import {lift as liftPublishable} from '../publishable/index.js';
+
+export default function liftPackage({projectRoot, packageDetails, configs}) {
+  return liftPublishable({projectRoot, packageDetails, configs});
+}

package/src/project-type/package/lifter.test.js

@@ -0,0 +1,20 @@
+import {describe, expect, it, vi} from 'vitest';
+import any from '@travi/any';
+import {when} from 'vitest-when';
+
+import {lift as liftPublishable} from '../publishable/index.js';
+import lift from './lifter.js';
+
+vi.mock('../publishable/lifter');
+
+describe('package project-type lifter', () => {
+  it('should leverage the publishable lifter', async () => {
+    const projectRoot = any.string();
+    const packageDetails = any.simpleObject();
+    const configs = any.simpleObject();
+    const publishableResults = any.simpleObject();
+    when(liftPublishable).calledWith({projectRoot, packageDetails, configs}).thenResolve(publishableResults);
+
+    expect(await lift({projectRoot, packageDetails, configs})).toEqual(publishableResults);
+  });
+});

package/src/project-type/package/scaffolder.js

@@ -0,0 +1,84 @@
+import deepmerge from 'deepmerge';
+import {info} from '@travi/cli-messages';
+import {dialects, mergeIntoExistingPackageJson} from '@form8ion/javascript-core';
+
+import determinePackageAccessLevelFromProjectVisibility from '../publishable/access-level.js';
+import {scaffold as scaffoldPublishable} from '../publishable/index.js';
+import scaffoldPackageDocumentation from './documentation.js';
+import buildDetails from './build-details.js';
+
+export default async function scaffoldPackageProjectType({
+  projectRoot,
+  projectName,
+  packageName,
+  packageManager,
+  visibility,
+  scope,
+  packageBundlers,
+  decisions,
+  dialect,
+  provideExample,
+  publishRegistry
+}) {
+  info('Scaffolding Package Details');
+
+  const packageAccessLevel = determinePackageAccessLevelFromProjectVisibility({projectVisibility: visibility});
+  const [detailsForBuild, publishableResults] = await Promise.all([
+    buildDetails({
+      projectRoot,
+      projectName,
+      packageBundlers,
+      dialect,
+      provideExample,
+      decisions
+    }),
+    scaffoldPublishable({packageName, packageAccessLevel}),
+    mergeIntoExistingPackageJson({
+      projectRoot,
+      config: {
+        files: ['example.js', ...dialects.COMMON_JS === dialect ? ['index.js'] : ['lib/', 'src/']],
+        publishConfig: {
+          access: packageAccessLevel,
+          ...publishRegistry && {registry: publishRegistry}
+        },
+        sideEffects: false,
+        ...dialects.BABEL === dialect && {
+          main: './lib/index.js',
+          module: './lib/index.mjs',
+          exports: {
+            module: './lib/index.mjs',
+            require: './lib/index.js',
+            import: './lib/index.mjs'
+          }
+        },
+        ...dialects.ESM === dialect && {
+          main: './lib/index.js',
+          exports: './lib/index.js'
+        },
+        ...dialects.TYPESCRIPT === dialect && {
+          main: './lib/index.js',
+          module: './lib/index.mjs',
+          types: './lib/index.d.ts',
+          exports: {
+            types: './lib/index.d.ts',
+            require: './lib/index.js',
+            import: './lib/index.mjs'
+          }
+        }
+      }
+    })
+  ]);
+
+  return deepmerge.all([
+    publishableResults,
+    {
+      documentation: scaffoldPackageDocumentation({packageName, visibility, scope, packageManager, provideExample}),
+      nextSteps: [
+        {summary: 'Add the appropriate `save` flag to the installation instructions in the README'},
+        {summary: 'Define supported node.js versions as `engines.node` in the `package.json` file'},
+        {summary: 'Publish pre-release versions to npm until package is stable enough to publish v1.0.0'}
+      ]
+    },
+    detailsForBuild
+  ]);
+}

package/src/project-type/package/scaffolder.test.js

@@ -0,0 +1,267 @@
+import {dialects, mergeIntoExistingPackageJson} from '@form8ion/javascript-core';
+
+import {beforeEach, describe, expect, it, vi} from 'vitest';
+import any from '@travi/any';
+import {when} from 'vitest-when';
+
+import determinePackageAccessLevelFromProjectVisibility from '../publishable/access-level.js';
+import {scaffold as scaffoldPublishable} from '../publishable/index.js';
+import * as buildDetails from './build-details.js';
+import * as documentationScaffolder from './documentation.js';
+import scaffoldPackage from './scaffolder.js';
+
+vi.mock('@form8ion/javascript-core');
+vi.mock('../publishable/access-level.js');
+vi.mock('../publishable/index.js');
+vi.mock('./build-details.js');
+vi.mock('./documentation.js');
+
+describe('package project-type scaffolder', () => {
+  const projectRoot = any.string();
+  const packageBundlers = any.simpleObject();
+  const projectName = any.word();
+  const packageName = any.word();
+  const packageManager = any.word();
+  const visibility = any.word();
+  const packageAccessLevel = any.word();
+  const scope = any.word();
+  const provideExample = any.boolean();
+  const publishableResults = any.simpleObject();
+  const commonNextSteps = [
+    {summary: 'Add the appropriate `save` flag to the installation instructions in the README'},
+    {summary: 'Define supported node.js versions as `engines.node` in the `package.json` file'},
+    {summary: 'Publish pre-release versions to npm until package is stable enough to publish v1.0.0'}
+  ];
+  const documentation = any.simpleObject();
+  const decisions = any.simpleObject();
+  const buildDetailsResults = any.simpleObject();
+
+  beforeEach(() => {
+    when(documentationScaffolder.default)
+      .calledWith({scope, packageName, visibility, packageManager, provideExample})
+      .thenReturn(documentation);
+    when(determinePackageAccessLevelFromProjectVisibility)
+      .calledWith({projectVisibility: visibility})
+      .thenReturn(packageAccessLevel);
+  });
+
+  it('should scaffold details specific to a modern-js package', async () => {
+    const dialect = dialects.BABEL;
+    when(scaffoldPublishable).calledWith({packageName, packageAccessLevel}).thenReturn(publishableResults);
+    when(buildDetails.default).calledWith({
+      projectRoot,
+      projectName,
+      packageBundlers,
+      dialect,
+      provideExample,
+      decisions
+    }).thenResolve(buildDetailsResults);
+
+    expect(await scaffoldPackage({
+      projectRoot,
+      projectName,
+      packageName,
+      packageManager,
+      visibility,
+      scope,
+      packageBundlers,
+      decisions,
+      dialect,
+      provideExample
+    })).toEqual({
+      ...publishableResults,
+      ...buildDetailsResults,
+      documentation,
+      nextSteps: commonNextSteps
+    });
+    expect(mergeIntoExistingPackageJson).toHaveBeenCalledWith({
+      projectRoot,
+      config: {
+        sideEffects: false,
+        main: './lib/index.js',
+        module: './lib/index.mjs',
+        exports: {
+          module: './lib/index.mjs',
+          require: './lib/index.js',
+          import: './lib/index.mjs'
+        },
+        files: ['example.js', 'lib/', 'src/'],
+        publishConfig: {access: packageAccessLevel}
+      }
+    });
+  });
+
+  it('should scaffold details specific to an esm-only package', async () => {
+    const dialect = dialects.ESM;
+    when(scaffoldPublishable).calledWith({packageName, packageAccessLevel}).thenReturn(publishableResults);
+    when(buildDetails.default).calledWith({
+      projectRoot,
+      projectName,
+      packageBundlers,
+      dialect,
+      provideExample,
+      decisions
+    }).thenResolve(buildDetailsResults);
+
+    expect(await scaffoldPackage({
+      projectRoot,
+      projectName,
+      packageName,
+      visibility,
+      dialect,
+      scope,
+      packageManager,
+      packageBundlers,
+      decisions,
+      provideExample
+    })).toEqual({
+      ...publishableResults,
+      ...buildDetailsResults,
+      documentation,
+      nextSteps: commonNextSteps
+    });
+    expect(mergeIntoExistingPackageJson).toHaveBeenCalledWith({
+      projectRoot,
+      config: {
+        main: './lib/index.js',
+        exports: './lib/index.js',
+        files: ['example.js', 'lib/', 'src/'],
+        sideEffects: false,
+        publishConfig: {access: packageAccessLevel}
+      }
+    });
+  });
+
+  it('should scaffold details specific to a typescript package', async () => {
+    const dialect = dialects.TYPESCRIPT;
+    when(scaffoldPublishable).calledWith({packageName, packageAccessLevel}).thenReturn(publishableResults);
+    when(buildDetails.default).calledWith({
+      projectRoot,
+      projectName,
+      packageBundlers,
+      dialect,
+      provideExample,
+      decisions
+    }).thenResolve(buildDetailsResults);
+
+    expect(await scaffoldPackage({
+      projectRoot,
+      projectName,
+      packageName,
+      packageManager,
+      visibility,
+      scope,
+      packageBundlers,
+      decisions,
+      dialect,
+      provideExample
+    })).toEqual({
+      ...publishableResults,
+      ...buildDetailsResults,
+      documentation,
+      nextSteps: commonNextSteps
+    });
+    expect(mergeIntoExistingPackageJson).toHaveBeenCalledWith({
+      projectRoot,
+      config: {
+        sideEffects: false,
+        main: './lib/index.js',
+        module: './lib/index.mjs',
+        types: './lib/index.d.ts',
+        exports: {
+          types: './lib/index.d.ts',
+          require: './lib/index.js',
+          import: './lib/index.mjs'
+        },
+        files: ['example.js', 'lib/', 'src/'],
+        publishConfig: {access: packageAccessLevel}
+      }
+    });
+  });
+
+  it('should not include build details when the project will not be scaffolded', async () => {
+    const dialect = dialects.COMMON_JS;
+    when(scaffoldPublishable).calledWith({packageName, packageAccessLevel}).thenReturn(publishableResults);
+    when(buildDetails.default).calledWith({
+      projectRoot,
+      projectName,
+      packageBundlers,
+      dialect,
+      provideExample,
+      decisions
+    }).thenResolve(buildDetailsResults);
+
+    expect(await scaffoldPackage({
+      projectRoot,
+      packageName,
+      projectName,
+      packageManager,
+      visibility,
+      scope,
+      decisions,
+      packageBundlers,
+      dialect,
+      provideExample
+    })).toEqual({
+      ...publishableResults,
+      ...buildDetailsResults,
+      documentation,
+      nextSteps: commonNextSteps
+    });
+    expect(mergeIntoExistingPackageJson).toHaveBeenCalledWith({
+      projectRoot,
+      config: {
+        files: ['example.js', 'index.js'],
+        publishConfig: {access: packageAccessLevel},
+        sideEffects: false
+      }
+    });
+  });
+
+  it('should define the registry to publish to when provided', async () => {
+    const publishRegistry = any.url();
+    const dialect = dialects.BABEL;
+    when(scaffoldPublishable).calledWith({packageName, packageAccessLevel}).thenReturn(publishableResults);
+    when(buildDetails.default).calledWith({
+      projectRoot,
+      projectName,
+      packageBundlers,
+      dialect,
+      provideExample,
+      decisions
+    }).thenResolve(buildDetailsResults);
+
+    await scaffoldPackage({
+      projectRoot,
+      packageName,
+      projectName,
+      packageManager,
+      visibility,
+      scope,
+      decisions,
+      publishRegistry,
+      dialect,
+      provideExample,
+      packageBundlers
+    });
+
+    expect(mergeIntoExistingPackageJson).toHaveBeenCalledWith({
+      projectRoot,
+      config: {
+        sideEffects: false,
+        main: './lib/index.js',
+        module: './lib/index.mjs',
+        exports: {
+          module: './lib/index.mjs',
+          require: './lib/index.js',
+          import: './lib/index.mjs'
+        },
+        files: ['example.js', 'lib/', 'src/'],
+        publishConfig: {
+          access: packageAccessLevel,
+          registry: publishRegistry
+        }
+      }
+    });
+  });
+});

package/src/project-type/package/tester.js

@@ -0,0 +1,5 @@
+export default async function projectIsPackage({
+  packageDetails: {exports, publishConfig, bin, private: projectMarkedPrivate}
+}) {
+  return !projectMarkedPrivate && (!!exports || (!!publishConfig && !bin));
+}