@form8ion/javascript 15.6.0 → 15.6.1

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

@@ -0,0 +1,28 @@
+import {describe, expect, it} from 'vitest';
+import any from '@travi/any';
+
+import test from './tester.js';
+
+describe('package project-type tester', () => {
+  it('should return `true` if the project defines `exports`', async () => {
+    expect(await test({packageDetails: {...any.simpleObject(), exports: any.word()}})).toBe(true);
+  });
+
+  it('should return `true` if the project defines `publishConfig`', async () => {
+    expect(await test({packageDetails: {...any.simpleObject(), publishConfig: any.simpleObject()}})).toBe(true);
+  });
+
+  it('should return `false` if the project defines `bin` in addition to `publishConfig`', async () => {
+    expect(await test({
+      packageDetails: {...any.simpleObject(), publishConfig: any.simpleObject(), bin: any.simpleObject()}
+    })).toBe(false);
+  });
+
+  it('should return `false` when there are no indicators that the project is a package type', async () => {
+    expect(await test({packageDetails: any.simpleObject()})).toBe(false);
+  });
+
+  it('should return `false` when `private` is set to `true`', async () => {
+    expect(await test({packageDetails: {...any.simpleObject(), private: true, exports: any.word()}})).toBe(false);
+  });
+});

package/src/project-type/publishable/access-level.js

@@ -0,0 +1,3 @@
+export default function mapProjectVisibility({projectVisibility}) {
+  return 'Public' === projectVisibility ? 'public' : 'restricted';
+}

package/src/project-type/publishable/access-level.test.js

@@ -0,0 +1,13 @@
+import {describe, expect, it} from 'vitest';
+
+import determinePackageAccessLevelFromProjectVisibility from './access-level.js';
+
+describe('package access level', () => {
+  it('should return `public` when project visibility is `Public`', () => {
+    expect(determinePackageAccessLevelFromProjectVisibility({projectVisibility: 'Public'})).toEqual('public');
+  });
+
+  it('should return `restricted` when the project visibility is `Private`', () => {
+    expect(determinePackageAccessLevelFromProjectVisibility({projectVisibility: 'Private'})).toEqual('restricted');
+  });
+});

package/src/project-type/publishable/badges.js

@@ -0,0 +1,20 @@
+function buildNpmBadgeImageUrl(packageName, customRegistry) {
+  const params = new URLSearchParams({logo: 'npm', ...customRegistry && {registry_uri: customRegistry}});
+
+  return `https://img.shields.io/npm/v/${packageName}?${params}`;
+}
+
+export default function scaffoldPublishableBadges({packageName, accessLevel, customRegistry}) {
+  return {
+    consumer: {
+      ...'public' === accessLevel && {
+        npm: {
+          img: buildNpmBadgeImageUrl(packageName, customRegistry),
+          text: 'npm',
+          link: `https://www.npmjs.com/package/${packageName}`
+        }
+      }
+    },
+    status: {}
+  };
+}

package/src/project-type/publishable/badges.test.js

@@ -0,0 +1,29 @@
+import {describe, it, expect} from 'vitest';
+import any from '@travi/any';
+
+import defineBadges from './badges.js';
+
+describe('badges for publishable project types', async () => {
+  const packageName = any.word();
+  const npmBadgeDetails = {
+    img: `https://img.shields.io/npm/v/${packageName}?logo=npm`,
+    text: 'npm',
+    link: `https://www.npmjs.com/package/${packageName}`
+  };
+
+  it('should define the badges when the access level is not public', () => {
+    expect(defineBadges(packageName)).toEqual({consumer: {}, status: {}});
+  });
+
+  it('should return the npm badge for packages with a public access level', () => {
+    expect(defineBadges({packageName, accessLevel: 'public'}).consumer).toEqual({npm: npmBadgeDetails});
+  });
+
+  it('should include the registry_uri in the npm badge when a custom registry is provided', () => {
+    const customRegistry = any.url();
+
+    const {searchParams} = new URL(defineBadges({packageName, accessLevel: 'public', customRegistry}).consumer.npm.img);
+
+    expect(searchParams.get('registry_uri')).toEqual(customRegistry);
+  });
+});

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

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

package/src/project-type/publishable/bundler/prompt.js

@@ -0,0 +1,16 @@
+import {prompt} from '@form8ion/overridable-prompts';
+
+import {questionNames} from '../../../prompts/question-names.js';
+
+export default async function gatherBundlerInput({bundlers, decisions}) {
+  if (!Object.keys(bundlers).length) return 'Other';
+
+  const answers = await prompt([{
+    name: questionNames.PACKAGE_BUNDLER,
+    type: 'list',
+    message: 'Which bundler should be used?',
+    choices: [...Object.keys(bundlers), 'Other']
+  }], decisions);
+
+  return answers[questionNames.PACKAGE_BUNDLER];
+}

package/src/project-type/publishable/bundler/prompt.test.js

@@ -0,0 +1,35 @@
+import * as prompts from '@form8ion/overridable-prompts';
+
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import any from '@travi/any';
+import {when} from 'vitest-when';
+
+import {questionNames} from '../../../prompts/question-names.js';
+import prompt from './prompt.js';
+
+vi.mock('@form8ion/overridable-prompts');
+
+describe('bundler prompt', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should present the choice of package bundlers', async () => {
+    const chosenType = any.word();
+    const decisions = any.simpleObject();
+    const answers = {...any.simpleObject(), [questionNames.PACKAGE_BUNDLER]: chosenType};
+    const bundlers = any.simpleObject();
+    when(prompts.prompt).calledWith([{
+      name: questionNames.PACKAGE_BUNDLER,
+      type: 'list',
+      message: 'Which bundler should be used?',
+      choices: [...Object.keys(bundlers), 'Other']
+    }], decisions).thenResolve(answers);
+
+    expect(await prompt({bundlers, decisions})).toEqual(chosenType);
+  });
+
+  it('should skip the prompt and return `Other` when no options are provided', async () => {
+    expect(await prompt({bundlers: {}})).toEqual('Other');
+  });
+});

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

@@ -0,0 +1,8 @@
+import {scaffoldChoice as scaffoldChosenBundler} from '@form8ion/javascript-core';
+import chooseBundler from './prompt.js';
+
+export default async function scaffoldBundler({projectRoot, projectType, bundlers, dialect, decisions}) {
+  const chosenBundler = await chooseBundler({bundlers, decisions});
+
+  return scaffoldChosenBundler(bundlers, chosenBundler, {projectRoot, projectType, dialect});
+}

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

@@ -0,0 +1,33 @@
+import {scaffoldChoice as scaffoldChosenBundler} from '@form8ion/javascript-core';
+
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import {when} from 'vitest-when';
+import any from '@travi/any';
+
+import chooseBundler from './prompt.js';
+import scaffoldBundler from './scaffolder.js';
+
+vi.mock('@form8ion/javascript-core');
+vi.mock('./prompt');
+
+describe('package bundler scaffolder', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should enable choosing from the available bundlers and scaffold the chosen one', async () => {
+    const projectRoot = any.string();
+    const dialect = any.word();
+    const projectType = any.word();
+    const bundlers = any.simpleObject();
+    const decisions = any.simpleObject();
+    const bundlerResults = any.simpleObject();
+    const chosenBundler = any.word();
+    when(chooseBundler).calledWith({bundlers, decisions}).thenResolve(chosenBundler);
+    when(scaffoldChosenBundler)
+      .calledWith(bundlers, chosenBundler, {projectRoot, dialect, projectType})
+      .thenResolve(bundlerResults);
+
+    expect(await scaffoldBundler({bundlers, projectRoot, projectType, dialect, decisions})).toEqual(bundlerResults);
+  });
+});

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

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

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

@@ -0,0 +1,24 @@
+import deepmerge from 'deepmerge';
+import {mergeIntoExistingPackageJson} from '@form8ion/javascript-core';
+
+import resolveRegistry from './registry-resolver.js';
+import defineBadges from './badges.js';
+import {lift as liftProvenance} from './provenance/index.js';
+
+export default async function liftPublishable({projectRoot, packageDetails, configs}) {
+  const {name: packageName, publishConfig: {access: packageAccessLevel}} = packageDetails;
+  const homepage = `https://npm.im/${packageName}`;
+  const customRegistry = resolveRegistry(packageName, configs.registries);
+
+  await mergeIntoExistingPackageJson({projectRoot, config: {homepage}});
+
+  return deepmerge(
+    await liftProvenance({packageDetails, projectRoot, customRegistry}),
+    {
+      homepage,
+      dependencies: {javascript: {development: ['publint']}},
+      scripts: {'lint:publish': 'publint --strict'},
+      badges: defineBadges({packageName, accessLevel: packageAccessLevel, customRegistry})
+    }
+  );
+}

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

@@ -0,0 +1,49 @@
+import deepmerge from 'deepmerge';
+import {mergeIntoExistingPackageJson} from '@form8ion/javascript-core';
+
+import {describe, expect, it, vi} from 'vitest';
+import any from '@travi/any';
+import {when} from 'vitest-when';
+
+import resolveRegistry from './registry-resolver.js';
+import defineBadges from './badges.js';
+import {lift as liftProvenance} from './provenance/index.js';
+import lift from './lifter.js';
+
+vi.mock('deepmerge');
+vi.mock('@form8ion/javascript-core');
+vi.mock('./provenance');
+vi.mock('./badges');
+vi.mock('./registry-resolver.js');
+
+describe('publishable project-type lifter', () => {
+  it('should lift the details of the package project', async () => {
+    const projectRoot = any.string();
+    const packageName = any.word();
+    const packageAccessLevel = any.word();
+    const registries = any.simpleObject();
+    const customRegistry = any.url();
+    const packageDetails = {...any.simpleObject(), name: packageName, publishConfig: {access: packageAccessLevel}};
+    const provenanceResults = any.simpleObject();
+    const mergedResults = any.simpleObject();
+    const badgesResults = any.simpleObject();
+    const homepage = `https://npm.im/${packageName}`;
+    when(resolveRegistry).calledWith(packageName, registries).thenReturn(customRegistry);
+    when(liftProvenance).calledWith({packageDetails, projectRoot, customRegistry}).thenResolve(provenanceResults);
+    when(defineBadges)
+      .calledWith({packageName, accessLevel: packageAccessLevel, customRegistry})
+      .thenReturn(badgesResults);
+    when(deepmerge).calledWith(
+      provenanceResults,
+      {
+        scripts: {'lint:publish': 'publint --strict'},
+        dependencies: {javascript: {development: ['publint']}},
+        badges: badgesResults,
+        homepage
+      }
+    ).thenReturn(mergedResults);
+
+    expect(await lift({projectRoot, packageDetails, configs: {registries}})).toEqual(mergedResults);
+    expect(mergeIntoExistingPackageJson).toHaveBeenCalledWith({projectRoot, config: {homepage}});
+  });
+});

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

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

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

@@ -0,0 +1,15 @@
+import {mergeIntoExistingPackageJson} from '@form8ion/javascript-core';
+
+import enhanceSlsa from './slsa.js';
+
+export default async function liftProvenance({projectRoot, packageDetails, customRegistry}) {
+  const {publishConfig: {access} = {}} = packageDetails;
+
+  if ('public' === access && !customRegistry) {
+    await mergeIntoExistingPackageJson({projectRoot, config: {publishConfig: {provenance: true}}});
+
+    return enhanceSlsa({provenance: true});
+  }
+
+  return {};
+}

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

@@ -0,0 +1,56 @@
+import {mergeIntoExistingPackageJson} from '@form8ion/javascript-core';
+
+import {describe, vi, it, expect, afterEach} from 'vitest';
+import any from '@travi/any';
+import {when} from 'vitest-when';
+
+import enhanceSlsa from './slsa.js';
+import lift from './lifter.js';
+
+vi.mock('@form8ion/javascript-core');
+vi.mock('./slsa.js');
+
+describe('provenance lifter', () => {
+  const projectRoot = any.string();
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should configure provenance for a public package published to the official registry', async () => {
+    const packageDetails = {...any.simpleObject(), publishConfig: {access: 'public'}};
+    const slsaResults = any.simpleObject();
+    when(enhanceSlsa).calledWith({provenance: true}).thenReturn(slsaResults);
+
+    expect(await lift({packageDetails, projectRoot})).toEqual(slsaResults);
+    expect(mergeIntoExistingPackageJson).toHaveBeenCalledWith({
+      projectRoot,
+      config: {publishConfig: {provenance: true}}
+    });
+  });
+
+  it('should not configure provenance for a public package published to an alternative registry', async () => {
+    const packageDetails = {...any.simpleObject(), publishConfig: {access: 'public'}};
+    const customRegistry = any.url();
+
+    expect(await lift({packageDetails, projectRoot, customRegistry})).toEqual({});
+    expect(enhanceSlsa).not.toHaveBeenCalled();
+    expect(mergeIntoExistingPackageJson).not.toHaveBeenCalled();
+  });
+
+  it('should not configure provenance for a restricted package', async () => {
+    const packageDetails = {...any.simpleObject(), publishConfig: {access: 'restricted'}};
+
+    expect(await lift({packageDetails, projectRoot})).toEqual({});
+    expect(enhanceSlsa).not.toHaveBeenCalled();
+    expect(mergeIntoExistingPackageJson).not.toHaveBeenCalled();
+  });
+
+  it('should not configure provenance for a package without `publishConfig`', async () => {
+    const packageDetails = any.simpleObject();
+
+    expect(await lift({packageDetails, projectRoot})).toEqual({});
+    expect(enhanceSlsa).not.toHaveBeenCalled();
+    expect(mergeIntoExistingPackageJson).not.toHaveBeenCalled();
+  });
+});

package/src/project-type/publishable/provenance/slsa.js

@@ -0,0 +1,17 @@
+export default function scaffoldSlsa({provenance}) {
+  if (provenance) {
+    return {
+      badges: {
+        status: {
+          slsa: {
+            img: 'https://slsa.dev/images/gh-badge-level2.svg',
+            url: 'https://slsa.dev',
+            text: 'SLSA Level 2'
+          }
+        }
+      }
+    };
+  }
+
+  return {};
+}

package/src/project-type/publishable/provenance/slsa.test.js

@@ -0,0 +1,21 @@
+import {describe, expect, it} from 'vitest';
+
+import determineSlsaLevel from './slsa.js';
+
+describe('SLSA badge', () => {
+  it('should return the SLSA Level 2 badge for public publishable projects that publish with provenance', () => {
+    const {badges} = determineSlsaLevel({provenance: true});
+
+    expect(badges.status.slsa).toEqual({
+      img: 'https://slsa.dev/images/gh-badge-level2.svg',
+      url: 'https://slsa.dev',
+      text: 'SLSA Level 2'
+    });
+  });
+
+  it('should not return a badge if the package is not published with provenance', () => {
+    const {badges} = determineSlsaLevel({});
+
+    expect(badges).toBe(undefined);
+  });
+});

package/src/project-type/publishable/registry-resolver.js

@@ -0,0 +1,15 @@
+function isScope(firstPart) {
+  return firstPart.startsWith('@');
+}
+
+export default function resolveRegistry(packageName, registries = {}) {
+  if (registries.publish) return registries.publish;
+
+  const [firstPart] = packageName.split('/');
+  if (isScope(firstPart)) {
+    const scopedRegistry = registries[firstPart.slice(1)];
+    if (scopedRegistry) return scopedRegistry;
+  }
+
+  return registries.registry;
+}

package/src/project-type/publishable/registry-resolver.test.js

@@ -0,0 +1,60 @@
+import {describe, it, expect} from 'vitest';
+import any from '@travi/any';
+
+import resolveRegistry from './registry-resolver.js';
+
+describe('registry resolver', () => {
+  const scope = any.word();
+  const scopedRegistry = any.url();
+  const registry = any.url();
+
+  it('should return undefined when no registries are defined', () => {
+    expect(resolveRegistry(any.word())).toBeUndefined();
+  });
+
+  it('should return the main registry override when defined', () => {
+    expect(resolveRegistry(any.word(), {registry})).toEqual(registry);
+  });
+
+  it('should return the publish registry when defined', () => {
+    const publishRegistry = any.url();
+
+    expect(resolveRegistry(any.word(), {publish: publishRegistry})).toEqual(publishRegistry);
+  });
+
+  it('should prefer the publish registry over the main registry override', () => {
+    const publishRegistry = any.url();
+
+    expect(resolveRegistry(any.word(), {registry, publish: publishRegistry})).toEqual(publishRegistry);
+  });
+
+  it('should prefer the publish registry over the scoped registry', () => {
+    const publishRegistry = any.url();
+
+    expect(resolveRegistry(`@${scope}/${any.word()}`, {[scope]: scopedRegistry, publish: publishRegistry}))
+      .toEqual(publishRegistry);
+  });
+
+  it('should return the scoped registry when the package is under a scope with a defined registry', () => {
+    expect(resolveRegistry(`@${scope}/${any.word()}`, {[scope]: scopedRegistry})).toEqual(scopedRegistry);
+  });
+
+  it('should prefer the scoped registry over the main registry override', () => {
+    expect(resolveRegistry(
+      `@${scope}/${any.word()}`,
+      {registry: any.url(), [scope]: scopedRegistry}
+    )).toEqual(scopedRegistry);
+  });
+
+  it('should return undefined when no registry matches the package scope', () => {
+    expect(resolveRegistry(`@${scope}/${any.word()}`, {[any.word()]: any.url()})).toBeUndefined();
+  });
+
+  it('should fall back to the main registry when the package is scoped but has no matching scope registry', () => {
+    expect(resolveRegistry(`@${scope}/${any.word()}`, {registry})).toEqual(registry);
+  });
+
+  it('should return undefined when the package has no scope and no main registry is defined', () => {
+    expect(resolveRegistry(any.word(), {[any.word()]: any.url()})).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,7 @@
+import defineBadges from './badges.js';
+
+export default async function scaffoldPublishable({packageName, packageAccessLevel}) {
+  return {
+    badges: await defineBadges(packageName, packageAccessLevel)
+  };
+}

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

@@ -0,0 +1,23 @@
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import any from '@travi/any';
+import {when} from 'vitest-when';
+
+import scaffoldBadges from './badges.js';
+import scaffoldPublishable from './scaffolder.js';
+
+vi.mock('./badges');
+
+describe('publishable project-type scaffolder', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should scaffold common details of a package project', async () => {
+    const packageName = any.word();
+    const packageAccessLevel = any.word();
+    const badgesResults = any.simpleObject();
+    when(scaffoldBadges).calledWith(packageName, packageAccessLevel).thenReturn(badgesResults);
+
+    expect(await scaffoldPublishable({packageName, packageAccessLevel})).toEqual({badges: badgesResults});
+  });
+});

package/src/project-type/scaffolder.js

@@ -0,0 +1,56 @@
+import {projectTypes} from '@form8ion/javascript-core';
+
+import {scaffold as scaffoldPackageType} from './package/index.js';
+import {scaffold as scaffoldApplicationType} from './application/index.js';
+import {scaffold as scaffoldMonorepoType} from './monorepo/index.js';
+import {scaffold as scaffoldCliType} from './cli/index.js';
+
+export default async function scaffoldProjectType({
+  projectType,
+  projectRoot,
+  projectName,
+  packageName,
+  packageManager,
+  visibility,
+  packageBundlers,
+  scope,
+  decisions,
+  dialect,
+  provideExample,
+  publishRegistry
+}) {
+  switch (projectType) {
+    case projectTypes.PACKAGE:
+      return scaffoldPackageType({
+        projectRoot,
+        projectName,
+        packageName,
+        packageManager,
+        visibility,
+        scope,
+        packageBundlers,
+        decisions,
+        dialect,
+        provideExample,
+        publishRegistry
+      });
+    case projectTypes.APPLICATION:
+      return scaffoldApplicationType({projectRoot});
+    case projectTypes.CLI:
+      return scaffoldCliType({
+        packageName,
+        visibility,
+        projectRoot,
+        dialect,
+        publishRegistry,
+        decisions,
+        packageBundlers
+      });
+    case projectTypes.MONOREPO:
+      return scaffoldMonorepoType({projectRoot});
+    case 'Other':
+      return {};
+    default:
+      throw new Error(`The project-type of ${projectType} is invalid`);
+  }
+}