@atlaskit/adf-utils 16.0.0 → 17.0.0

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # @atlaskit/adf-utils
 
+## 17.0.0
+
+### Major Changes
+
+- [`844b8278b4d`](https://bitbucket.org/atlassian/atlassian-frontend/commits/844b8278b4d) - ED-14608: Migrate adf-utils to modern child entry points, remove default entry point, add codemods to enforce migration.
+
+  As we will no longer support the default entry point, imports such as the example below:
+
+  ```
+  import { breakout, scrubAdf, map } from '@atlaskit/adf-utils';
+  ```
+
+  would need to become:
+
+  ```
+  import { breakout } from '@atlaskit/adf-utils/builders';
+  import { scrubADF } from '@atlaskit/adf-utils/scrub';
+  import { map } from '@atlaskit/adf-utils/traverse';
+  ```
+
+  **The new (and only) @atlaskit/adf-utils entry points supported now are listed below:**
+
+  @atlaskit/adf-utils/builders for:
+
+  - breakout, code, em, link, link, strike, strong, strong, subsup, text-color, underline, underline, alignment, indentation, data-consumer fragment, blockquote, bodied-extension, block-card, bullet-list, bullet-list, code-block, date, decision-item, decision-list, doc, emoji, extension, expand, nested-expand, hard-break, hard-break, heading, inline-extension, inline-card, layout-column, layout-section, list-item, list-item, media-group, media-single, media, mention, ordered-list, ordered-list, panel, paragraph, paragraph, placeholder, rule, rule, status, table-cell, table-cell, table-header, table-header, table-row, table-row, table, task-item, task-list, text, embed-card,
+
+  @atlaskit/adf-utils/empty-adf for:
+
+  - getEmptyADF
+
+  @atlaskit/adf-utils/scrub for:
+
+  - scrubAdf
+
+  @atlaskit/adf-utils/transforms for:
+
+  - transformMediaLinkMarks, transformTextLinkCodeMarks, transformDedupeMarks, transformNodesMissingContent, transformIndentationMarks
+
+  @atlaskit/adf-utils/traverse for:
+
+  - traverse, map, reduce, filter
+
+  @atlaskit/adf-utils/validator for:
+
+  - validateAttrs, validator
+
+  @atlaskit/adf-utils/types for:
+
+  - ADFEntityMark, ADFEntity, Visitor, VisitorCollection, EntityParent
+
+  @atlaskit/adf-utils/validatorTypes for:
+
+  - MarkValidationResult, Output, NodeValidationResult, ValidatorContent, AttributesSpec, ValidatorSpec, ValidationErrorMap, RequiredContentLength, Content, ValidationErrorType, ValidationError, ErrorCallback, ValidationMode, ValidationOptions, SpecValidatorResult, Err, ErrorCallbackOptions, Validate
+
+  **Since there are significant changes (including the breaking change of dropping the default entry point to @atlaskit/adf-utils), we will be providing a codemod to help consumers upgrade their usage of adf-utils**
+
+  Once you've upgraded `@atlaskit/adf-utils`, use the Atlaskit codemod CLI.
+
+  `npx @atlaskit/codemod-cli /path/to/target/directory`
+
+  See [documentation on DAC](https://developer.atlassian.com/cloud/framework/atlassian-frontend/codemods/01-atlassian-codemods/) for general codemod guidance.
+
+### Patch Changes
+
+- [`8300a668772`](https://bitbucket.org/atlassian/atlassian-frontend/commits/8300a668772) - [ux] ED-14488: Extend ADF sanitising coverage to prevent Prosemirror failing validation checks on adf that can be repaired
+- Updated dependencies
+
+## 16.0.2
+
+### Patch Changes
+
+- [`cb2392f6d33`](https://bitbucket.org/atlassian/atlassian-frontend/commits/cb2392f6d33) - Upgrade to TypeScript 4.2.4
+
+## 16.0.1
+
+### Patch Changes
+
+- Updated dependencies
+
 ## 16.0.0
 
 ### Major Changes

package/builders/package.json

@@ -3,5 +3,6 @@
   "main": "../dist/cjs/builders.js",
   "module": "../dist/esm/builders.js",
   "module:es2019": "../dist/es2019/builders.js",
+  "sideEffects": false,
   "types": "../dist/types/builders.d.ts"
 }

package/codemods/17.0.0-update-imports-to-new-entry-points.ts

@@ -0,0 +1,175 @@
+import { createTransformer } from '@atlaskit/codemod-utils';
+import { createMigratesFromEntryPointChangeRequests } from './helpers/entry-points';
+import type { EntryPointChangeRequest } from './types/entry-points';
+
+const DEFAULT_ADF_UTILS_IMPORT = '@atlaskit/adf-utils';
+
+const types: EntryPointChangeRequest = {
+  importSpecifiers: [
+    'ADFEntity',
+    'ADFEntityMark',
+    'Visitor',
+    'VisitorCollection',
+  ],
+  oldEntryPointsToRemove: [DEFAULT_ADF_UTILS_IMPORT],
+  newEntryPoint: `${DEFAULT_ADF_UTILS_IMPORT}/types`,
+  shouldBeTypeImport: true,
+};
+
+const validatorTypes: EntryPointChangeRequest = {
+  importSpecifiers: [
+    'Content',
+    'ErrorCallback',
+    'Output',
+    'ValidationError',
+    'ValidationErrorMap',
+    'ValidationErrorType',
+    'ValidationMode',
+    'ValidationOptions',
+    'ErrorCallbackOptions',
+    'Validate',
+    'NodeValidationResult',
+    'ValidatorSpec',
+    'AttributesSpec',
+    'ValidatorContent',
+    'MarkValidationResult',
+    'SpecValidatorResult',
+    'Err',
+  ],
+  oldEntryPointsToRemove: [
+    DEFAULT_ADF_UTILS_IMPORT,
+    `${DEFAULT_ADF_UTILS_IMPORT}/validator`,
+  ],
+  newEntryPoint: `${DEFAULT_ADF_UTILS_IMPORT}/validatorTypes`,
+  shouldBeTypeImport: true,
+};
+
+const transforms: EntryPointChangeRequest = {
+  importSpecifiers: [
+    'transformMediaLinkMarks',
+    'transformTextLinkCodeMarks',
+    'transformDedupeMarks',
+    'transformNodesMissingContent',
+    'transformIndentationMarks',
+  ],
+  oldEntryPointsToRemove: [DEFAULT_ADF_UTILS_IMPORT],
+  newEntryPoint: `${DEFAULT_ADF_UTILS_IMPORT}/transforms`,
+  shouldBeTypeImport: false,
+};
+
+const traverse: EntryPointChangeRequest = {
+  importSpecifiers: ['traverse', 'map', 'reduce', 'filter'],
+  oldEntryPointsToRemove: [DEFAULT_ADF_UTILS_IMPORT],
+  newEntryPoint: `${DEFAULT_ADF_UTILS_IMPORT}/traverse`,
+  shouldBeTypeImport: false,
+};
+
+const builders: EntryPointChangeRequest = {
+  importSpecifiers: [
+    'a',
+    'alignment',
+    'b',
+    'blockCard',
+    'blockQuote',
+    'bodiedExtension',
+    'br',
+    'breakout',
+    'bulletList',
+    'code',
+    'codeBlock',
+    'date',
+    'decisionItem',
+    'decisionList',
+    'doc',
+    'em',
+    'embedCard',
+    'emoji',
+    'expand',
+    'extension',
+    'hardBreak',
+    'heading',
+    'hr',
+    'indentation',
+    'inlineCard',
+    'inlineExtension',
+    'layoutColumn',
+    'layoutSection',
+    'li',
+    'link',
+    'listItem',
+    'media',
+    'mediaGroup',
+    'mediaSingle',
+    'mention',
+    'nestedExpand',
+    'ol',
+    'orderedList',
+    'p',
+    'panel',
+    'paragraph',
+    'placeholder',
+    'rule',
+    'status',
+    'strike',
+    'strong',
+    'subsup',
+    'table',
+    'tableCell',
+    'tableHeader',
+    'tableRow',
+    'taskItem',
+    'taskList',
+    'td',
+    'text',
+    'textColor',
+    'th',
+    'tr',
+    'u',
+    'ul',
+    'underline',
+    'dataConsumer',
+  ],
+  oldEntryPointsToRemove: [DEFAULT_ADF_UTILS_IMPORT],
+  newEntryPoint: `${DEFAULT_ADF_UTILS_IMPORT}/builders`,
+  shouldBeTypeImport: false,
+};
+
+const emptyAdf: EntryPointChangeRequest = {
+  importSpecifiers: ['getEmptyADF'],
+  oldEntryPointsToRemove: [DEFAULT_ADF_UTILS_IMPORT],
+  newEntryPoint: `${DEFAULT_ADF_UTILS_IMPORT}/empty-adf`,
+  shouldBeTypeImport: false,
+};
+
+const validator: EntryPointChangeRequest = {
+  importSpecifiers: ['validator', 'validateAttrs'],
+  oldEntryPointsToRemove: [DEFAULT_ADF_UTILS_IMPORT],
+  newEntryPoint: `${DEFAULT_ADF_UTILS_IMPORT}/validator`,
+  shouldBeTypeImport: false,
+};
+
+const scrub: EntryPointChangeRequest = {
+  importSpecifiers: ['scrubAdf'],
+  oldEntryPointsToRemove: [DEFAULT_ADF_UTILS_IMPORT],
+  newEntryPoint: `${DEFAULT_ADF_UTILS_IMPORT}/scrub`,
+  shouldBeTypeImport: false,
+};
+
+const entryPointChangeRequests: EntryPointChangeRequest[] = [
+  transforms,
+  validatorTypes,
+  types,
+  traverse,
+  builders,
+  validator,
+  emptyAdf,
+  scrub,
+];
+
+export const entryPointChangeMigrates = createMigratesFromEntryPointChangeRequests(
+  entryPointChangeRequests,
+);
+
+const transformer = createTransformer(entryPointChangeMigrates);
+
+export default transformer;

package/codemods/__tests__/next-update-imports-to-new-entry-points.ts

@@ -0,0 +1,175 @@
+import transformer from '../17.0.0-update-imports-to-new-entry-points';
+
+const defineInlineTest = require('jscodeshift/dist/testUtils').defineInlineTest;
+
+describe('updates adf-util imports to new child entry points', () => {
+  defineInlineTest(
+    { default: transformer, parser: 'tsx' },
+    {},
+    `
+    import { traverse } from "@atlaskit/adf-utils";
+    import { ADFEntity, ADFEntityMark } from "@atlaskit/adf-utils";
+    import { validateAttrs, validator, ValidationErrorMap } from '@atlaskit/adf-utils';
+    import type { NodeValidationResult } from '@atlaskit/adf-utils';
+    import { type ValidationMode } from '@atlaskit/adf-utils';
+
+    export default () => (
+      <div>
+        hello
+      </div>
+    );
+    `,
+    `
+    import type { ValidationErrorMap, ValidationMode, NodeValidationResult } from "@atlaskit/adf-utils/validatorTypes";
+    import type { ADFEntity, ADFEntityMark } from "@atlaskit/adf-utils/types";
+    import { traverse } from "@atlaskit/adf-utils/traverse";
+    import { validator, validateAttrs } from "@atlaskit/adf-utils/validator";
+
+    export default () => (
+      <div>
+        hello
+      </div>
+    );
+    `,
+    'should handle migrating any combination of old entry points (including type imports and imports with type modifiers) to new child entry points',
+  );
+
+  defineInlineTest(
+    { default: transformer, parser: 'tsx' },
+    {},
+    `
+    import { traverse, teamRocketAndMeowth, scrubAdf } from "@atlaskit/adf-utils";
+    import { Pokemon, ADFEntityMark, AshKetchum } from "@atlaskit/adf-utils";
+    import type { PsyDuck } from "@atlaskit/adf-utils/pokemon-types";
+    import Boogeyman from "@deep/the-mariana-trench";
+
+    export default () => (
+      <div>
+        hello
+      </div>
+    );
+    `,
+    `
+    import type { ADFEntityMark } from "@atlaskit/adf-utils/types";
+    import { traverse } from "@atlaskit/adf-utils/traverse";
+    import { scrubAdf } from "@atlaskit/adf-utils/scrub";
+    import { teamRocketAndMeowth } from "@atlaskit/adf-utils";
+    import { Pokemon, AshKetchum } from "@atlaskit/adf-utils";
+    import type { PsyDuck } from "@atlaskit/adf-utils/pokemon-types";
+    import Boogeyman from "@deep/the-mariana-trench";
+
+    export default () => (
+      <div>
+        hello
+      </div>
+    );
+    `,
+    'should leave unknown entry points or import specifiers untouched (and unmerged if initially unmerged)',
+  );
+
+  defineInlineTest(
+    { default: transformer, parser: 'tsx' },
+    {},
+    `
+    import { VisitorCollection } from "@atlaskit/adf-utils/types";
+    import type { Visitor } from "@atlaskit/adf-utils";
+
+    export default () => (
+      <div>
+        hello
+      </div>
+    );
+    `,
+    `
+    import type { VisitorCollection, Visitor } from "@atlaskit/adf-utils/types";
+
+    export default () => (
+      <div>
+        hello
+      </div>
+    );
+    `,
+    'should handle migrating new child entry points with mismatched importKinds (e.g. non-type when should be type import)',
+  );
+
+  defineInlineTest(
+    { default: transformer, parser: 'tsx' },
+    {},
+    `
+      import { scrubAdf, doc, p, link } from "@atlaskit/adf-utils";
+      import { blockCard, paragraph } from "@atlaskit/adf-utils/builders";
+      import { placeholder, transformDedupeMarks } from "@atlaskit/adf-utils";
+      import { VisitorCollection } from "@atlaskit/adf-utils/types";
+      import type { Visitor } from "@atlaskit/adf-utils";
+      import { getEmptyADF } from "@atlaskit/adf-utils";
+
+      export default () => (
+        <div>
+          hello
+        </div>
+      );
+      `,
+    `
+      import { transformDedupeMarks } from "@atlaskit/adf-utils/transforms";
+      import { getEmptyADF } from "@atlaskit/adf-utils/empty-adf";
+      import { scrubAdf } from "@atlaskit/adf-utils/scrub";
+      import { blockCard, paragraph, doc, link, p, placeholder } from "@atlaskit/adf-utils/builders";
+      import type { VisitorCollection, Visitor } from "@atlaskit/adf-utils/types";
+
+      export default () => (
+        <div>
+          hello
+        </div>
+      );
+      `,
+    'should handle migrating any combination of old and new entry points to new child entry points',
+  );
+
+  defineInlineTest(
+    { default: transformer, parser: 'tsx' },
+    {},
+    `
+    const { scrubAdf } = require("@atlaskit/adf-utils");
+    import * as adfUtils from "@atlaskit/adf-utils";
+
+    export default () => {
+        if (shouldFetchModule) {
+            import("@atlaskit/adf-utils").then(module => ({
+                something: "else"
+            }));
+            import("@atlaskit/adf-utils/traverse").then(module => {
+                const traverse = module.traverse;
+                traverse();
+            });
+        }
+        return (
+            <div>
+                hello
+            </div>
+        )
+      }
+    `,
+    `
+    const { scrubAdf } = require("@atlaskit/adf-utils");
+    import * as adfUtils from "@atlaskit/adf-utils";
+
+    export default () => {
+        if (shouldFetchModule) {
+            import("@atlaskit/adf-utils").then(module => ({
+                something: "else"
+            }));
+            import("@atlaskit/adf-utils/traverse").then(module => {
+                const traverse = module.traverse;
+                traverse();
+            });
+        }
+        return (
+            <div>
+                hello
+            </div>
+        )
+      }
+    `,
+    'should skip migrating other import syntaxes (namespace imports, CJS, dyamic imports)',
+  );
+});

package/codemods/helpers/entry-points.ts

@@ -0,0 +1,33 @@
+import { changeImportEntryPoint } from '@atlaskit/codemod-utils';
+import type {
+  EntryPointChangeRequest,
+  EntryPointChangeMigrates,
+} from '../types/entry-points';
+
+export const createMigratesFromEntryPointChangeRequests = (
+  changeRequests: EntryPointChangeRequest[],
+) => {
+  const entryPointChangeMigrates: EntryPointChangeMigrates = [];
+  changeRequests.forEach(
+    ({
+      importSpecifiers,
+      oldEntryPointsToRemove,
+      newEntryPoint,
+      shouldBeTypeImport,
+    }) => {
+      oldEntryPointsToRemove.forEach((oldEntryPoint) => {
+        importSpecifiers.forEach((importSpecifier) => {
+          entryPointChangeMigrates.push(
+            changeImportEntryPoint(
+              oldEntryPoint,
+              importSpecifier,
+              newEntryPoint,
+              shouldBeTypeImport,
+            ),
+          );
+        });
+      });
+    },
+  );
+  return entryPointChangeMigrates;
+};

package/codemods/types/entry-points.ts

@@ -0,0 +1,12 @@
+import type { changeImportEntryPoint } from '@atlaskit/codemod-utils';
+
+export type EntryPointChangeRequest = {
+  importSpecifiers: string[];
+  oldEntryPointsToRemove: string[];
+  newEntryPoint: string;
+  shouldBeTypeImport: boolean;
+};
+
+export type EntryPointChange = ReturnType<typeof changeImportEntryPoint>;
+
+export type EntryPointChangeMigrates = EntryPointChange[];