Add document/public.js to export public apis, remove internal utils (…

…prettier#14456)

.eslintrc.cjs

@@ -356,7 +356,7 @@ module.exports = {
       rules: {
         "prettier-internal-rules/flat-ast-path-call": "error",
         "prettier-internal-rules/no-conflicting-comment-check-flags": "error",
-        "prettier-internal-rules/no-doc-index-import": "error",
+        "prettier-internal-rules/no-doc-public-import": "error",
         "prettier-internal-rules/no-empty-flat-contents-for-if-break": "error",
         "prettier-internal-rules/no-unnecessary-ast-path-call": "error",
         "prettier-internal-rules/prefer-ast-path-each": "error",

changelog_unreleased/api/13203.md

@@ -1,3 +1,11 @@
-#### [BREAKING] `prettier.doc.builders.concat` has been removed (#13203 by @fisker)
+#### [BREAKING] Update `prettier.doc` (#13203, #14456 by @fisker)
 
 `prettier.doc.builders.concat` [was deprecated in v2.3.0](https://prettier.io/blog/2021/05/09/2.3.0.html#use-arrays-instead-of-concat-9733httpsgithubcomprettierprettierpull9733-by-fiskerhttpsgithubcomfisker-thorn0httpsgithubcomthorn0), now it's removed.
+
+The following apis are never documented, they mean to only use internally, now they are removed.
+
+- `prettier.doc.utils.getDocParts`
+- `prettier.doc.utils.propagateBreaks`
+- `prettier.doc.utils.cleanDoc`
+- `prettier.doc.utils.getDocType`
+- `prettier.doc.debug.printDocToDebug`

jest.config.mjs

@@ -43,7 +43,9 @@ if (isProduction) {
 if (SKIP_TESTS_WITH_NEW_SYNTAX) {
   testPathIgnorePatterns.push(
     "<rootDir>/tests/integration/__tests__/help-options.js",
-    "<rootDir>/tests/integration/__tests__/plugin-parsers.js"
+    "<rootDir>/tests/integration/__tests__/plugin-parsers.js",
+    "<rootDir>/tests/integration/__tests__/normalize-doc.js",
+    "<rootDir>/tests/integration/__tests__/doc-utils-clean-doc.js"
   );
 }
 

scripts/build/config.mjs

@@ -13,7 +13,6 @@ import buildJavascriptModule from "./build-javascript-module.js";
 import buildPackageJson from "./build-package-json.js";
 import buildLicense from "./build-license.js";
 import modifyTypescriptModule from "./modify-typescript-module.mjs";
-import reuseDocumentModule from "./reuse-document-module.js";
 import { getPackageFile } from "./utils.js";
 
 const {
@@ -41,7 +40,7 @@ async function typesFileBuilder({ file }) {
   ];
   /** @type {ReplacementMap} */
   const pathReplacementMap = {
-    "src/index.d.ts": [{ from: "./document/index.js", to: "./doc.js" }],
+    "src/index.d.ts": [{ from: "./document/public.js", to: "./doc.js" }],
     "src/language-js/parse/acorn-and-espree.d.ts": jsParsersImportReplacement,
     "src/language-js/parse/angular.d.ts": jsParsersImportReplacement,
     "src/language-js/parse/babel.d.ts": jsParsersImportReplacement,
@@ -402,7 +401,7 @@ const pluginFiles = [
 
 const nonPluginUniversalFiles = [
   {
-    input: "src/document/index.js",
+    input: "src/document/public.js",
     outputBaseName: "doc",
     umdVariableName: "doc",
     minify: false,
@@ -497,7 +496,6 @@ const nodejsFiles = [
         replacement: "const readBuffer = Buffer.alloc(this.options.readChunk);",
       },
       replaceDiffPackageEntry("lib/diff/array.js"),
-      ...reuseDocumentModule(),
     ],
   },
   {

scripts/tools/eslint-plugin-prettier-internal-rules/index.js

@@ -8,7 +8,7 @@ module.exports = {
     "flat-ast-path-call": require("./flat-ast-path-call.js"),
     "jsx-identifier-case": require("./jsx-identifier-case.js"),
     "no-conflicting-comment-check-flags": require("./no-conflicting-comment-check-flags.js"),
-    "no-doc-index-import": require("./no-doc-index-import.js"),
+    "no-doc-public-import": require("./no-doc-public-import.js"),
     "no-empty-flat-contents-for-if-break": require("./no-empty-flat-contents-for-if-break.js"),
     "no-identifier-n": require("./no-identifier-n.js"),
     "no-legacy-format-test-fixtures": require("./no-legacy-format-test-fixtures.js"),

scripts/tools/eslint-plugin-prettier-internal-rules/no-doc-index-import.js → scripts/tools/eslint-plugin-prettier-internal-rules/no-doc-public-import.js

@@ -7,8 +7,8 @@ const selector = [
   "Literal.source",
 ].join("");
 
-const messageId = "no-doc-index-import";
-const docIndexFile = path.join(__dirname, "../../../src/document/index.js");
+const messageId = "no-doc-public-import";
+const docIndexFile = path.join(__dirname, "../../../src/document/public.js");
 const ignored = new Set([
   path.join(__dirname, "../../../src/index.js"),
   path.join(__dirname, "../../../src/standalone.js"),
@@ -17,7 +17,7 @@ const ignored = new Set([
 const docProperties = new Set(["builders", "debug", "printer", "utils"]);
 
 function fix(source, context) {
-  // only fix `import doc from './document/index.js'`
+  // only fix `import doc from './document/public.js'`
   if (
     !(
       source.parent.type === "ImportDeclaration" &&
@@ -73,7 +73,7 @@ function fix(source, context) {
         return `import ${sourceCode.getText(
           property.value
         )} from "${source.value.replace(
-          "/document/index.js",
+          "/document/public.js",
           `/document/${propertyName}.js`
         )}";`;
       })
@@ -88,10 +88,10 @@ module.exports = {
   meta: {
     type: "suggestion",
     docs: {
-      url: "https://github.com/prettier/prettier/blob/main/scripts/tools/eslint-plugin-prettier-internal-rules/no-doc-index-import.js",
+      url: "https://github.com/prettier/prettier/blob/main/scripts/tools/eslint-plugin-prettier-internal-rules/no-doc-public-import.js",
     },
     messages: {
-      [messageId]: "Do not {{type}} document/index.js file",
+      [messageId]: "Do not {{type}} document/public.js file",
     },
     fixable: "code",
   },
@@ -109,7 +109,7 @@ module.exports = {
 
         if (
           !value.startsWith(".") ||
-          !value.endsWith("/document/index.js") ||
+          !value.endsWith("/document/public.js") ||
           path.join(dir, value) !== docIndexFile
         ) {
           return;

src/document/builders.js

@@ -232,9 +232,6 @@ function label(label, contents) {
   return label ? { type: DOC_TYPE_LABEL, label, contents } : contents;
 }
 
-// TODO: Remove this in v4
-export const concat = (parts) => parts;
-
 export {
   join,
   line,

src/document/index.d.ts → src/document/public.d.ts

@@ -1,4 +1,4 @@
-// https://github.com/prettier/prettier/blob/next/src/document/index.js
+// https://github.com/prettier/prettier/blob/next/src/document/public.js
 export namespace builders {
   type DocCommand =
     | Align
@@ -183,10 +183,6 @@ export namespace builders {
   const cursor: Cursor;
 }
 
-export namespace debug {
-  function printDocToDebug(doc: builders.Doc): string;
-}
-
 export namespace printer {
   function printDocToString(
     doc: builders.Doc,
@@ -218,7 +214,6 @@ export namespace printer {
 }
 
 export namespace utils {
-  function getDocParts(doc: builders.Doc): builders.Doc;
   function willBreak(doc: builders.Doc): boolean;
   function traverseDoc(
     doc: builders.Doc,
@@ -235,14 +230,11 @@ export namespace utils {
     doc: builders.Doc,
     callback: (doc: builders.Doc) => T
   ): T;
-  function propagateBreaks(doc: builders.Doc): void;
   function removeLines(doc: builders.Doc): builders.Doc;
   function stripTrailingHardline(doc: builders.Doc): builders.Doc;
-  function cleanDoc(doc: builders.Doc): builders.Doc;
   function replaceEndOfLine(
     doc: builders.Doc,
     replacement?: builders.Doc
   ): builders.Doc;
   function canBreak(doc: builders.Doc): boolean;
-  function getDocType(doc: builders.Doc): string;
 }

src/document/public.js

@@ -0,0 +1,77 @@
+import {
+  join,
+  line,
+  softline,
+  hardline,
+  literalline,
+  group,
+  conditionalGroup,
+  fill,
+  lineSuffix,
+  lineSuffixBoundary,
+  cursor,
+  breakParent,
+  ifBreak,
+  trim,
+  indent,
+  indentIfBreak,
+  align,
+  addAlignmentToDoc,
+  markAsRoot,
+  dedentToRoot,
+  dedent,
+  hardlineWithoutBreakParent,
+  literallineWithoutBreakParent,
+  label,
+} from "./builders.js";
+import { printDocToString } from "./printer.js";
+import {
+  willBreak,
+  traverseDoc,
+  findInDoc,
+  mapDoc,
+  removeLines,
+  stripTrailingHardline,
+  replaceEndOfLine,
+  canBreak,
+} from "./utils.js";
+
+export const builders = {
+  join,
+  line,
+  softline,
+  hardline,
+  literalline,
+  group,
+  conditionalGroup,
+  fill,
+  lineSuffix,
+  lineSuffixBoundary,
+  cursor,
+  breakParent,
+  ifBreak,
+  trim,
+  indent,
+  indentIfBreak,
+  align,
+  addAlignmentToDoc,
+  markAsRoot,
+  dedentToRoot,
+  dedent,
+  hardlineWithoutBreakParent,
+  literallineWithoutBreakParent,
+  label,
+  // TODO: Remove this in v4
+  concat: (parts) => parts,
+};
+export const printer = { printDocToString };
+export const utils = {
+  willBreak,
+  traverseDoc,
+  findInDoc,
+  mapDoc,
+  removeLines,
+  stripTrailingHardline,
+  replaceEndOfLine,
+  canBreak,
+};

src/index.cjs

@@ -40,7 +40,7 @@ prettier.__debug = debugApis;
 
 if (process.env.NODE_ENV === "production") {
   prettier.util = require("./utils/public.js");
-  prettier.doc = require("./document/index.js");
+  prettier.doc = require("./document/public.js");
 } else {
   Object.defineProperties(prettier, {
     util: {

src/index.d.ts

@@ -8,10 +8,10 @@
 // exported module.
 export {};
 
-import { builders, debug, printer, utils } from "./document/index.js";
+import { builders, printer, utils } from "./document/public.js";
 
 export namespace doc {
-  export { builders, debug, printer, utils };
+  export { builders, printer, utils };
 }
 
 // This utility is here to handle the case where you have an explicit union

src/index.js

@@ -111,5 +111,5 @@ export {
   debugApis as __debug,
 };
 export * as util from "./utils/public.js";
-export * as doc from "./document/index.js";
+export * as doc from "./document/public.js";
 export { default as version } from "./main/version.evaluate.cjs";

src/language-js/print/array.js

@@ -1,6 +1,5 @@
 import { printDanglingComments } from "../../main/comments/print.js";
 import {
-  concat,
   line,
   softline,
   hardline,

src/language-js/print/call-arguments.js

@@ -25,7 +25,6 @@ import {
 } from "../utils/index.js";
 
 import {
-  concat,
   line,
   hardline,
   softline,

src/language-js/printer-estree.js

@@ -5,7 +5,6 @@ import hasNewline from "../utils/has-newline.js";
 import * as customizations from "../_customizations/index.js";
 import { capitalize, flatten } from "../_customizations/utils.js";
 import {
-  concat,
   join,
   line,
   hardline,

src/standalone.js

@@ -58,5 +58,5 @@ export {
   debugApis as __debug,
 };
 export * as util from "./utils/public.js";
-export * as doc from "./document/index.js";
+export * as doc from "./document/public.js";
 export { default as version } from "./main/version.evaluate.cjs";

tests/dts/unit/cases/doc.ts

@@ -1,5 +1,5 @@
-import * as doc from "../../../../src/document";
+import * as doc from "../../../../src/document/public.js";
 
 doc.builders.dedent;
 doc.printer.printDocToString;
-doc.debug.printDocToDebug;
+doc.utils.mapDoc;

tests/integration/__tests__/debug-api.js

@@ -3,10 +3,7 @@ import prettier from "../../config/prettier-entry.js";
 
 const {
   __debug: { parse, formatAST, formatDoc, printToDoc, printDocToString },
-  doc: {
-    builders,
-    utils: { cleanDoc },
-  },
+  doc: { builders },
 } = prettier;
 
 const code = outdent`
@@ -74,6 +71,11 @@ describe("API", () => {
       await formatDoc(fill(["foo", hardline, "bar", literalline, "baz"]))
     ).toBe('fill(["foo", hardline, "bar", literalline, "baz"])');
 
+    /*
+    This is not really `cleanDoc` from `src/document/utils.js`
+    But if we pass array to it, it will flat array
+    */
+    const cleanDoc = (parts) => parts.flat();
     expect(
       await formatDoc(
         // The argument of fill must not be passed to cleanDoc because it's not a doc

tests/integration/__tests__/doc-utils-clean-doc.js

@@ -1,9 +1,12 @@
-import prettier from "../../config/prettier-entry.js";
-const docBuilders = prettier.doc.builders;
-const docUtils = prettier.doc.utils;
-
-const { cleanDoc } = docUtils;
-const { group, align, indent, lineSuffix, ifBreak, fill } = docBuilders;
+import {
+  group,
+  align,
+  indent,
+  lineSuffix,
+  ifBreak,
+  fill,
+} from "../../../src/document/builders.js";
+import { cleanDoc } from "../../../src/document/utils.js";
 
 describe("cleanDoc", () => {
   test.each([