@form8ion/javascript 15.5.0 → 15.6.1

package/src/dialects/prompt-choices.js

@@ -0,0 +1,10 @@
+import {dialects} from '@form8ion/javascript-core';
+
+export default function gatherDialectInput({babelPreset, typescript}) {
+  return [
+    {name: 'Common JS (no transpilation)', value: dialects.COMMON_JS, short: 'cjs'},
+    ...babelPreset ? [{name: 'Modern JavaScript (transpiled)', value: dialects.BABEL, short: 'modern'}] : [],
+    {name: 'ESM-only (no transpilation)', value: dialects.ESM, short: 'esm'},
+    ...typescript ? [{name: 'TypeScript', value: dialects.TYPESCRIPT, short: 'ts'}] : []
+  ];
+}

package/src/dialects/prompt-choices.test.js

@@ -0,0 +1,28 @@
+import {dialects} from '@form8ion/javascript-core';
+
+import any from '@travi/any';
+import {describe, expect, it} from 'vitest';
+
+import buildDialectChoices from './prompt-choices.js';
+
+describe('dialect prompt questions', () => {
+  it('should list available dialects', () => {
+    expect(buildDialectChoices({
+      ...any.simpleObject(),
+      babelPreset: any.simpleObject(),
+      typescript: any.simpleObject()
+    })).toEqual([
+      {name: 'Common JS (no transpilation)', value: dialects.COMMON_JS, short: 'cjs'},
+      {name: 'Modern JavaScript (transpiled)', value: dialects.BABEL, short: 'modern'},
+      {name: 'ESM-only (no transpilation)', value: dialects.ESM, short: 'esm'},
+      {name: 'TypeScript', value: dialects.TYPESCRIPT, short: 'ts'}
+    ]);
+  });
+
+  it('should not include babel or typescript in the choices list when configs are not provided', () => {
+    expect(buildDialectChoices(any.simpleObject())).toEqual([
+      {name: 'Common JS (no transpilation)', value: dialects.COMMON_JS, short: 'cjs'},
+      {name: 'ESM-only (no transpilation)', value: dialects.ESM, short: 'esm'}
+    ]);
+  });
+});

package/src/dialects/scaffolder.js

@@ -0,0 +1,15 @@
+import {dialects} from '@form8ion/javascript-core';
+
+import {scaffold as scaffoldBabel} from './babel/index.js';
+import {scaffold as scaffoldTypescript} from './typescript/index.js';
+
+export default function scaffoldDialect({dialect, projectType, projectRoot, configs, testFilenamePattern}) {
+  switch (dialect) {
+    case dialects.BABEL:
+      return scaffoldBabel({preset: configs.babelPreset, projectRoot});
+    case dialects.TYPESCRIPT:
+      return scaffoldTypescript({config: configs.typescript, projectType, projectRoot, testFilenamePattern});
+    default:
+      return {};
+  }
+}

package/src/dialects/scaffolder.test.js

@@ -0,0 +1,49 @@
+import {dialects} from '@form8ion/javascript-core';
+
+import any from '@travi/any';
+import {describe, expect, it, vi} from 'vitest';
+import {when} from 'vitest-when';
+
+import {scaffold as scaffoldBabel} from './babel/index.js';
+import {scaffold as scaffoldTypescript} from './typescript/index.js';
+import scaffoldDialect from './scaffolder.js';
+
+vi.mock('./babel/index.js');
+vi.mock('./typescript/index.js');
+
+describe('dialect scaffolder', () => {
+  const projectRoot = any.string();
+
+  it('should not scaffold babel or typescript when not chosen', async () => {
+    expect(await scaffoldDialect({dialect: any.word()})).toEqual({});
+    expect(scaffoldBabel).not.toHaveBeenCalled();
+    expect(scaffoldTypescript).not.toHaveBeenCalled();
+  });
+
+  it('should scaffold babel when chosen', async () => {
+    const babelPreset = any.word();
+    const babelResults = any.simpleObject();
+    when(scaffoldBabel).calledWith({preset: babelPreset, projectRoot}).thenResolve(babelResults);
+
+    expect(await scaffoldDialect({dialect: dialects.BABEL, configs: {babelPreset}, projectRoot}))
+      .toEqual(babelResults);
+  });
+
+  it('should scaffold typescript when chosen', async () => {
+    const typescriptConfigs = any.simpleObject();
+    const typescriptResults = any.simpleObject();
+    const testFilenamePattern = any.string();
+    const projectType = any.word();
+    when(scaffoldTypescript)
+      .calledWith({config: typescriptConfigs, projectType, projectRoot, testFilenamePattern})
+      .thenResolve(typescriptResults);
+
+    expect(await scaffoldDialect({
+      dialect: dialects.TYPESCRIPT,
+      projectType,
+      configs: {typescript: typescriptConfigs},
+      projectRoot,
+      testFilenamePattern
+    })).toEqual(typescriptResults);
+  });
+});

package/src/dialects/typescript/index.js

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

package/src/dialects/typescript/scaffolder.js

@@ -0,0 +1,31 @@
+import {fileTypes, writeConfigFile} from '@form8ion/core';
+import {projectTypes} from '@form8ion/javascript-core';
+
+export default async function scaffoldTypescript({config, projectType, projectRoot, testFilenamePattern}) {
+  const shareableTsConfigPackage = `${config.scope}/tsconfig`;
+
+  await writeConfigFile({
+    path: projectRoot,
+    name: 'tsconfig',
+    format: fileTypes.JSON,
+    config: {
+      $schema: 'https://json.schemastore.org/tsconfig',
+      extends: shareableTsConfigPackage,
+      compilerOptions: {
+        rootDir: 'src',
+        ...projectTypes.PACKAGE === projectType && {
+          outDir: 'lib',
+          declaration: true
+        }
+      },
+      include: ['src/**/*.ts'],
+      ...testFilenamePattern && {exclude: [testFilenamePattern]}
+    }
+  });
+
+  return {
+    eslint: {configs: ['typescript']},
+    dependencies: {javascript: {development: ['typescript', shareableTsConfigPackage]}},
+    vcsIgnore: {files: ['tsconfig.tsbuildinfo']}
+  };
+}

package/src/dialects/typescript/scaffolder.test.js

@@ -0,0 +1,95 @@
+import {fileTypes, writeConfigFile} from '@form8ion/core';
+import {projectTypes} from '@form8ion/javascript-core';
+
+import {describe, vi, afterEach, it, expect} from 'vitest';
+import any from '@travi/any';
+
+import scaffoldTypescriptDialect from './scaffolder.js';
+
+vi.mock('@form8ion/core');
+
+describe('typescript dialect scaffolder', () => {
+  const scope = `@${any.word()}`;
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should define the eslint config', async () => {
+    const {eslint: {configs}} = await scaffoldTypescriptDialect({config: {}});
+
+    expect(configs).toEqual(['typescript']);
+  });
+
+  it('should extend the scoped package in the tsconfig', async () => {
+    const projectRoot = any.string();
+
+    await scaffoldTypescriptDialect({config: {scope}, projectRoot});
+
+    expect(writeConfigFile).toHaveBeenCalledWith({
+      path: projectRoot,
+      name: 'tsconfig',
+      format: fileTypes.JSON,
+      config: {
+        $schema: 'https://json.schemastore.org/tsconfig',
+        extends: `${scope}/tsconfig`,
+        compilerOptions: {rootDir: 'src'},
+        include: ['src/**/*.ts']
+      }
+    });
+  });
+
+  it('should define package specific details when the project is a package', async () => {
+    const projectRoot = any.string();
+
+    await scaffoldTypescriptDialect({config: {scope}, projectType: projectTypes.PACKAGE, projectRoot});
+
+    expect(writeConfigFile).toHaveBeenCalledWith({
+      path: projectRoot,
+      name: 'tsconfig',
+      format: fileTypes.JSON,
+      config: {
+        $schema: 'https://json.schemastore.org/tsconfig',
+        extends: `${scope}/tsconfig`,
+        compilerOptions: {
+          rootDir: 'src',
+          outDir: 'lib',
+          declaration: true
+        },
+        include: ['src/**/*.ts']
+      }
+    });
+  });
+
+  it('should include the testFilenamePattern as an `exclude` when provided', async () => {
+    const projectRoot = any.string();
+    const testFilenamePattern = any.string();
+
+    await scaffoldTypescriptDialect({config: {scope}, projectRoot, testFilenamePattern});
+
+    expect(writeConfigFile).toHaveBeenCalledWith({
+      path: projectRoot,
+      name: 'tsconfig',
+      format: fileTypes.JSON,
+      config: {
+        $schema: 'https://json.schemastore.org/tsconfig',
+        extends: `${scope}/tsconfig`,
+        compilerOptions: {rootDir: 'src'},
+        include: ['src/**/*.ts'],
+        exclude: [testFilenamePattern]
+      }
+    });
+  });
+
+  it('should define dev dependencies', async () => {
+    const {dependencies} = await scaffoldTypescriptDialect({config: {scope}});
+
+    expect(dependencies.javascript.development).toEqual(['typescript', `${scope}/tsconfig`]);
+  });
+
+  it('should ignore files from version control', async () => {
+    const {vcsIgnore: {files}} = await scaffoldTypescriptDialect({config: {}});
+
+    expect(files).toEqual(['tsconfig.tsbuildinfo']);
+  });
+});

package/src/documentation/generation-command.js

@@ -0,0 +1,11 @@
+import {packageManagers} from '@form8ion/javascript-core';
+
+export default function scaffoldGenerationCommand(packageManager) {
+  if (packageManagers.NPM === packageManager) return 'npm run generate:md';
+  if (packageManagers.YARN === packageManager) return 'yarn generate:md';
+
+  throw new Error(
+    `The ${packageManager} package manager is currently not supported. `
+    + `Only ${Object.values(packageManagers).join(' and ')} are currently supported.`
+  );
+}

package/src/documentation/generation-command.test.js

@@ -0,0 +1,25 @@
+import {packageManagers} from '@form8ion/javascript-core';
+
+import {describe, expect, it} from 'vitest';
+import any from '@travi/any';
+
+import buildCommand from './generation-command.js';
+
+describe('documentation generation command', () => {
+  it('should return the npm variation of the command', () => {
+    expect(buildCommand(packageManagers.NPM)).toEqual('npm run generate:md');
+  });
+
+  it('should return the yarn variation of the command', () => {
+    expect(buildCommand(packageManagers.YARN)).toEqual('yarn generate:md');
+  });
+
+  it('should throw an error for unsupported package managers', () => {
+    const packageManager = any.word();
+
+    expect(() => buildCommand(packageManager)).toThrowError(
+      `The ${packageManager} package manager is currently not supported. `
+      + `Only ${Object.values(packageManagers).join(' and ')} are currently supported.`
+    );
+  });
+});

package/src/documentation/index.js

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

package/src/documentation/scaffolder.js

@@ -0,0 +1,20 @@
+import buildGenerationCommand from './generation-command.js';
+
+export default function scaffoldDocumentation({projectTypeResults, packageManager}) {
+  return {
+    toc: `Run \`${buildGenerationCommand(packageManager)}\` to generate a table of contents`,
+    ...projectTypeResults.documentation,
+    contributing: `### Dependencies
+
+\`\`\`sh
+$ nvm install
+$ ${packageManager} install
+\`\`\`
+
+### Verification
+
+\`\`\`sh
+$ ${packageManager} test
+\`\`\``
+  };
+}

package/src/documentation/scaffolder.test.js

@@ -0,0 +1,49 @@
+import any from '@travi/any';
+import {beforeEach, describe, expect, it, vi} from 'vitest';
+import {when} from 'vitest-when';
+
+import buildDocumentationCommand from './generation-command.js';
+import scaffoldDocumentation from './scaffolder.js';
+
+vi.mock('./generation-command.js');
+
+describe('documentation scaffolder', () => {
+  const packageManager = any.word();
+  const documentationGenerationCommand = any.string();
+  const tocMessage = `Run \`${documentationGenerationCommand}\` to generate a table of contents`;
+  const contributionDocumentation = `### Dependencies
+
+\`\`\`sh
+$ nvm install
+$ ${packageManager} install
+\`\`\`
+
+### Verification
+
+\`\`\`sh
+$ ${packageManager} test
+\`\`\``;
+
+  beforeEach(() => {
+    when(buildDocumentationCommand).calledWith(packageManager).thenReturn(documentationGenerationCommand);
+  });
+
+  it('should provide project-type documentation and contribution details', () => {
+    const projectTypeResults = {documentation: any.simpleObject()};
+
+    expect(scaffoldDocumentation({projectTypeResults, packageManager})).toEqual({
+      toc: tocMessage,
+      ...projectTypeResults.documentation,
+      contributing: contributionDocumentation
+    });
+  });
+
+  it('should not include project-type documentation when not provided', () => {
+    const projectTypeResults = {documentation: undefined};
+
+    expect(scaffoldDocumentation({projectTypeResults, packageManager})).toEqual({
+      toc: tocMessage,
+      contributing: contributionDocumentation
+    });
+  });
+});

package/src/engines/index.js

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

package/src/engines/lifter.js

@@ -0,0 +1,7 @@
+export default async function liftEngines({packageDetails: {name}}) {
+  return {
+    dependencies: {javascript: {development: ['ls-engines']}},
+    scripts: {'lint:engines': 'ls-engines'},
+    badges: {consumer: {node: {img: `https://img.shields.io/node/v/${name}?logo=node.js`, text: 'node'}}}
+  };
+}

package/src/engines/lifter.test.js

@@ -0,0 +1,18 @@
+import {describe, it, expect} from 'vitest';
+import any from '@travi/any';
+
+import liftEngines from './lifter.js';
+
+describe('engines lifter', () => {
+  it('should return the details for linting and communicating engines restrictions', async () => {
+    const packageName = any.word();
+    const packageDetails = {...any.simpleObject(), name: packageName};
+
+    const {scripts, badges, dependencies} = await liftEngines({packageDetails});
+
+    expect(scripts['lint:engines']).toEqual('ls-engines');
+    expect(dependencies.javascript.development).toEqual(['ls-engines']);
+    expect(badges.consumer.node)
+      .toEqual({img: `https://img.shields.io/node/v/${packageName}?logo=node.js`, text: 'node'});
+  });
+});

package/src/engines/tester.js

@@ -0,0 +1,7 @@
+import {promises as fs} from 'fs';
+
+export default async function testEngines({projectRoot}) {
+  const {engines} = JSON.parse(await fs.readFile(`${projectRoot}/package.json`, 'utf8'));
+
+  return !!engines?.node;
+}

package/src/engines/tester.test.js

@@ -0,0 +1,37 @@
+import {promises as fs} from 'node:fs';
+
+import {describe, it, expect, vi, afterEach} from 'vitest';
+import any from '@travi/any';
+import {when} from 'vitest-when';
+
+import testEngines from './tester.js';
+
+vi.mock('node:fs');
+
+describe('engines tester', () => {
+  const projectRoot = any.string();
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should return `true` when `engines.node` is defined', async () => {
+    when(fs.readFile)
+      .calledWith(`${projectRoot}/package.json`, 'utf8')
+      .thenResolve(JSON.stringify({engines: {node: any.word()}}));
+
+    expect(await testEngines({projectRoot})).toBe(true);
+  });
+
+  it('should return `false` when `engines.node` is not defined', async () => {
+    when(fs.readFile).calledWith(`${projectRoot}/package.json`, 'utf8').thenReturn(JSON.stringify({engines: {}}));
+
+    expect(await testEngines({projectRoot})).toBe(false);
+  });
+
+  it('should return `false` when `engines` is not defined', async () => {
+    when(fs.readFile).calledWith(`${projectRoot}/package.json`, 'utf8').thenReturn(JSON.stringify({}));
+
+    expect(await testEngines({projectRoot})).toBe(false);
+  });
+});

package/src/index.js

@@ -0,0 +1,9 @@
+import {questionNames as languageScaffolderPromptsQuestionNames} from '@travi/language-scaffolder-prompts';
+
+import {questionNames as jsScaffolderQuestionNames} from './prompts/question-names.js';
+
+export {scaffold as scaffoldUnitTesting} from './testing/unit/index.js';
+export {default as scaffold} from './scaffolder.js';
+export {default as lift} from './lifter.js';
+export {default as test} from './tester.js';
+export const questionNames = {...languageScaffolderPromptsQuestionNames, ...jsScaffolderQuestionNames};

package/src/lifter.js

@@ -0,0 +1,55 @@
+import {promises as fs} from 'node:fs';
+import deepmerge from 'deepmerge';
+import {info} from '@travi/cli-messages';
+import {applyEnhancers} from '@form8ion/core';
+import * as huskyPlugin from '@form8ion/husky';
+import * as commitConventionPlugin from '@form8ion/commit-convention';
+
+import * as registriesPlugin from './registries/index.js';
+import * as coveragePlugin from './coverage/index.js';
+import * as codeStylePlugin from './code-style/index.js';
+import * as npmConfigPlugin from './npm-config/index.js';
+import * as enginesEnhancer from './engines/index.js';
+import * as projectTypes from './project-type/index.js';
+import * as dialects from './dialects/index.js';
+import {lift as liftPackage} from './package/index.js';
+import * as packageManagers from './package-managers/index.js';
+import {determineCurrent as resolvePackageManager} from './package-managers/index.js';
+
+export default async function liftJavaScript({
+  projectRoot,
+  vcs,
+  results,
+  pathWithinParent,
+  enhancers = {},
+  configs = {}
+}) {
+  info('Lifting JavaScript-specific details');
+
+  const [packageManager, packageContents] = await Promise.all([
+    resolvePackageManager({projectRoot, packageManager: results.packageManager}),
+    fs.readFile(`${projectRoot}/package.json`, 'utf8')
+  ]);
+
+  const enhancerResults = await applyEnhancers({
+    results,
+    enhancers: {
+      ...enhancers,
+      huskyPlugin,
+      enginesEnhancer,
+      coveragePlugin,
+      commitConventionPlugin,
+      dialects,
+      codeStylePlugin,
+      npmConfigPlugin,
+      projectTypes,
+      packageManagers,
+      registriesPlugin
+    },
+    options: {packageManager, projectRoot, vcs, packageDetails: JSON.parse(packageContents), configs}
+  });
+
+  await liftPackage(deepmerge.all([{projectRoot, packageManager, vcs, pathWithinParent}, enhancerResults]));
+
+  return enhancerResults;
+}

package/src/lifter.test.js

@@ -0,0 +1,96 @@
+import {promises as fs} from 'node:fs';
+import deepmerge from 'deepmerge';
+import * as core from '@form8ion/core';
+import * as huskyPlugin from '@form8ion/husky';
+import * as commitConventionPlugin from '@form8ion/commit-convention';
+
+import {beforeEach, describe, expect, it, vi} from 'vitest';
+import any from '@travi/any';
+import {when} from 'vitest-when';
+
+import * as registriesPlugin from './registries/index.js';
+import * as coveragePlugin from './coverage/index.js';
+import * as codeStylePlugin from './code-style/index.js';
+import * as npmConfigPlugin from './npm-config/index.js';
+import * as enginesEnhancer from './engines/index.js';
+import * as projectTypes from './project-type/index.js';
+import * as dialects from './dialects/index.js';
+import liftPackage from './package/lifter.js';
+import * as packageManagers from './package-managers/index.js';
+import {determineCurrent as packageManagerResolver} from './package-managers/index.js';
+import lift from './lifter.js';
+
+vi.mock('node:fs');
+vi.mock('@form8ion/core');
+vi.mock('./package/lifter.js');
+vi.mock('./package-managers/index.js');
+
+describe('lift', () => {
+  const projectRoot = any.string();
+  const scripts = any.simpleObject();
+  const tags = any.listOf(any.word);
+  const dependencies = any.simpleObject();
+  const devDependencies = any.simpleObject();
+  const packageManager = any.word();
+  const manager = any.word();
+  const enhancerResults = any.simpleObject();
+  const vcsDetails = any.simpleObject();
+  const results = {...any.simpleObject(), scripts, tags, dependencies, devDependencies, packageManager: manager};
+  const pathWithinParent = any.string();
+  const packageDetails = any.simpleObject();
+  const internalEnhancers = {
+    huskyPlugin,
+    enginesEnhancer,
+    coveragePlugin,
+    commitConventionPlugin,
+    dialects,
+    codeStylePlugin,
+    npmConfigPlugin,
+    projectTypes,
+    packageManagers,
+    registriesPlugin
+  };
+
+  beforeEach(() => {
+    when(packageManagerResolver)
+      .calledWith({projectRoot, packageManager: manager})
+      .thenResolve(packageManager);
+    when(fs.readFile)
+      .calledWith(`${projectRoot}/package.json`, 'utf8')
+      .thenResolve(JSON.stringify(packageDetails));
+  });
+
+  it('should lift results that are specific to js projects', async () => {
+    const configs = any.simpleObject();
+    when(core.applyEnhancers)
+      .calledWith({
+        results,
+        enhancers: internalEnhancers,
+        options: {projectRoot, packageManager, vcs: vcsDetails, packageDetails, configs}
+      })
+      .thenResolve(enhancerResults);
+
+    const liftResults = await lift({projectRoot, vcs: vcsDetails, results, pathWithinParent, configs});
+
+    expect(liftResults).toEqual(enhancerResults);
+    expect(liftPackage).toHaveBeenCalledWith(deepmerge.all([
+      {projectRoot, packageManager, vcs: vcsDetails, pathWithinParent},
+      enhancerResults
+    ]));
+  });
+
+  it('should apply provided enhancers', async () => {
+    const enhancers = any.simpleObject();
+    when(core.applyEnhancers)
+      .calledWith({
+        results,
+        enhancers: {...enhancers, ...internalEnhancers},
+        options: {projectRoot, packageManager, vcs: vcsDetails, packageDetails, configs: {}}
+      })
+      .thenResolve(enhancerResults);
+
+    const liftResults = await lift({projectRoot, vcs: vcsDetails, results, pathWithinParent, enhancers});
+
+    expect(liftResults).toEqual(enhancerResults);
+  });
+});

package/src/linting/index.js

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

package/src/linting/scaffolder.js

@@ -0,0 +1,5 @@
+import {scaffold as scaffoldLockfileLint} from '../lockfile-lint/index.js';
+
+export default async function scaffoldLinting({projectRoot, packageManager, registries}) {
+  return scaffoldLockfileLint({projectRoot, packageManager, registries});
+}

package/src/linting/scaffolder.test.js

@@ -0,0 +1,31 @@
+import {describe, expect, it, vi} from 'vitest';
+import any from '@travi/any';
+import {when} from 'vitest-when';
+
+import {scaffold as scaffoldLockfileLint} from '../lockfile-lint/index.js';
+import {scaffold} from './index.js';
+
+vi.mock('../lockfile-lint');
+
+describe('linting scaffolder', () => {
+  const pathWithinParent = any.string();
+  const projectRoot = any.string();
+  const packageManager = any.word();
+  const vcs = any.simpleObject();
+  const registries = any.simpleObject();
+
+  it('should configure linters when config definitions are provided', async () => {
+    const lockfileLintResults = any.simpleObject();
+    when(scaffoldLockfileLint)
+      .calledWith({projectRoot, packageManager, registries})
+      .thenResolve(lockfileLintResults);
+
+    expect(await scaffold({
+      projectRoot,
+      vcs,
+      packageManager,
+      pathWithinParent,
+      registries
+    })).toEqual(lockfileLintResults);
+  });
+});

package/src/lockfile-lint/allowed-hosts-builder.js

@@ -0,0 +1,6 @@
+export default function buildAllowedHosts({packageManager, registries = {}}) {
+  return [
+    ...!registries.registry ? [packageManager] : [],
+    ...Object.values(Object.fromEntries(Object.entries(registries).filter(([scope]) => 'publish' !== scope)))
+  ];
+}