V2: Support buf.gen.yaml in connect-migrate

packages/connect-migrate/package.json

@@ -23,7 +23,8 @@
   "dependencies": {
     "fast-glob": "3.3.2",
     "jscodeshift": "0.16.1",
-    "semver": "^7.6.2"
+    "semver": "^7.6.2",
+    "yaml": "^2.4.5"
   },
   "devDependencies": {
     "@types/jscodeshift": "0.11.11",

packages/connect-migrate/src/lib/bufgenyaml.spec.ts

@@ -0,0 +1,76 @@
+// Copyright 2021-2024 The Connect Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { BufGenYaml, parseBufGenYaml, stringifyBufGenYaml } from "./bufgenyaml";
+
+const goldenV1 = `# buf.gen.yaml defines a local generation template.
+# For details, see https://docs.buf.build/configuration/v1/buf-gen-yaml
+version: v1
+plugins:
+  - plugin: es
+    opt: target=ts
+    out: src/gen
+  - plugin: connect-es
+    opt: target=ts
+    out: src/gen
+`;
+
+const goldenV2 = `# Learn more: https://buf.build/docs/configuration/v2/buf-gen-yaml
+version: v2
+inputs:
+  - directory: proto
+plugins:
+  # The code generator is installed with \`npm install @bufbuild/protoc-gen-es\`.
+  - local: protoc-gen-es
+    opt: target=ts
+    out: src/gen
+  - local: protoc-gen-connect-es
+    opt: target=ts
+    out: src/gen
+  - local: protoc-gen-foo
+    out: src/gen
+  - local: protoc-gen-connect-es
+    opt: target=ts
+    out: src/gen
+`;
+
+describe("parseBufGenYaml()", () => {
+  it("should parse golden v1", () => {
+    const y: BufGenYaml = parseBufGenYaml(goldenV1);
+    expect(y).toBeDefined();
+    expect(y.get("version")).toBe("v1");
+  });
+  it("should parse golden v2", () => {
+    const y: BufGenYaml = parseBufGenYaml(goldenV2);
+    expect(y).toBeDefined();
+    expect(y.get("version")).toBe("v2");
+  });
+  it("raises error for unknown version", () => {
+    expect(() => parseBufGenYaml(`version: true`)).toThrowError(
+      "Failed to parse: not a valid buf.gen.yaml file: unknown version: true",
+    );
+  });
+  it("raises error for plugins not a yaml list", () => {
+    expect(() => parseBufGenYaml(`version: v1\nplugins: true`)).toThrowError(
+      'Failed to parse: not a valid buf.gen.yaml file: expected "plugins" to be a yaml list',
+    );
+  });
+});
+
+describe("stringifyBufGenYaml()", () => {
+  it("should keep comments", () => {
+    const str = stringifyBufGenYaml(parseBufGenYaml(goldenV2));
+    expect(str).toEqual(goldenV2);
+  });
+});

packages/connect-migrate/src/lib/bufgenyaml.ts

@@ -0,0 +1,72 @@
+// Copyright 2021-2024 The Connect Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { Document, isSeq, parseDocument, stringify } from "yaml";
+import { readFileSync, writeFileSync } from "node:fs";
+
+export type BufGenYaml = Document.Parsed & {
+  _bufGenYaml: true;
+};
+
+export function readBufGenYamlFile(path: string): BufGenYaml {
+  let content: string;
+  try {
+    content = readFileSync(path, "utf-8");
+  } catch (e) {
+    throw new Error(
+      `Failed to parse ${path}: ${e instanceof Error ? e.message : String(e)}`,
+    );
+  }
+  return parseBufGenYaml(content);
+}
+
+export function parseBufGenYaml(content: string, path?: string): BufGenYaml {
+  try {
+    const doc = parseDocument(content, {
+      logLevel: "silent",
+    });
+    assertValid(doc);
+    return doc;
+  } catch (e) {
+    const inner = e instanceof Error ? e.message : String(e);
+    throw new Error(
+      path === undefined
+        ? `Failed to parse: ${inner}`
+        : `Failed to parse ${path}: ${inner}`,
+    );
+  }
+}
+
+export function stringifyBufGenYaml(bufGenYaml: BufGenYaml) {
+  return stringify(bufGenYaml);
+}
+
+export function writeBufGenYamlFile(path: string, bufGenYaml: BufGenYaml) {
+  writeFileSync(path, stringifyBufGenYaml(bufGenYaml), "utf-8");
+}
+
+function assertValid(arg: Document.Parsed): asserts arg is BufGenYaml {
+  const version = arg.get("version");
+  if (version !== "v1" && version !== "v2") {
+    throw new Error(
+      `not a valid buf.gen.yaml file: unknown version: ${String(version)}`,
+    );
+  }
+  const plugins = arg.get("plugins");
+  if (!isSeq(plugins)) {
+    throw new Error(
+      `not a valid buf.gen.yaml file: expected "plugins" to be a yaml list`,
+    );
+  }
+}

packages/connect-migrate/src/lib/migrate-bufgenyaml.spec.ts

@@ -0,0 +1,187 @@
+// Copyright 2021-2024 The Connect Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { parseBufGenYaml, stringifyBufGenYaml } from "./bufgenyaml";
+import { migrateBufGenYaml } from "./migrate-bufgenyaml";
+import type { BufGenYamlMigration } from "./migrate-bufgenyaml";
+
+describe("migrateBufGenYaml()", () => {
+  describe("BufGenYamlPluginUpdate", () => {
+    const migration: BufGenYamlMigration = {
+      updatePlugin: {
+        remote: "buf.build/bufbuild/es",
+        from: "^1.0.0",
+        to: "2.0.0",
+      },
+    };
+    it("should update plugin in v2", () => {
+      const input = `# comment
+version: v2
+inputs:
+  - directory: proto
+plugins:
+  # keep
+  - remote: buf.build/bufbuild/es
+    out: src/gen
+  # update
+  - remote: buf.build/bufbuild/es:v1.10.0
+    out: src/gen
+`;
+      const expected = `# comment
+version: v2
+inputs:
+  - directory: proto
+plugins:
+  # keep
+  - remote: buf.build/bufbuild/es
+    out: src/gen
+  # update
+  - remote: buf.build/bufbuild/es:v2.0.0
+    out: src/gen
+`;
+      const yaml = parseBufGenYaml(input);
+      const updated = migrateBufGenYaml(yaml, [migration]);
+      expect(updated).toBeDefined();
+      expect(stringifyBufGenYaml(updated ?? yaml)).toBe(expected);
+    });
+    it("should update plugin in v1", () => {
+      const input = `# comment
+version: v1
+plugins:
+  # keep
+  - plugin: buf.build/bufbuild/es
+    out: src/gen
+  # update
+  - plugin: buf.build/bufbuild/es:v1.10.0
+    out: src/gen
+`;
+      const expected = `# comment
+version: v1
+plugins:
+  # keep
+  - plugin: buf.build/bufbuild/es
+    out: src/gen
+  # update
+  - plugin: buf.build/bufbuild/es:v2.0.0
+    out: src/gen
+`;
+      const yaml = parseBufGenYaml(input);
+      const updated = migrateBufGenYaml(yaml, [migration]);
+      expect(updated).toBeDefined();
+      expect(stringifyBufGenYaml(updated ?? yaml)).toBe(expected);
+    });
+    it("should not update up-to-date plugin in v1", () => {
+      const input = `version: v1
+plugins:
+  - plugin: buf.build/bufbuild/es:v2.99.0
+    out: src/gen
+`;
+      const yaml = parseBufGenYaml(input);
+      const updated = migrateBufGenYaml(yaml, [migration]);
+      expect(updated).toBeNull();
+    });
+    it("should not update up-to-date plugin in v2", () => {
+      const input = `version: v2
+plugins:
+  - remote: buf.build/bufbuild/es:v2.99.0
+    out: src/gen
+`;
+      const yaml = parseBufGenYaml(input);
+      const updated = migrateBufGenYaml(yaml, [migration]);
+      expect(updated).toBeNull();
+    });
+  });
+  describe("BufGenYamlPluginRemoval", () => {
+    const migration: BufGenYamlMigration = {
+      removePlugin: {
+        local: "protoc-gen-connect-es",
+        remote: "buf.build/connectrpc/es",
+      },
+    };
+    it("should remove plugin from v2", () => {
+      const input = `# comment
+version: v2
+inputs:
+  - directory: proto
+plugins:
+  # keep
+  - local: protoc-gen-es
+    out: src/gen
+  # remove
+  - local: protoc-gen-connect-es
+    out: src/gen
+  # keep
+  - local: protoc-gen-foo
+    out: src/gen
+  # remove
+  - remote: buf.build/connectrpc/es
+    out: src/gen
+  # remove
+  - remote: buf.build/connectrpc/es:v1.4.0
+    out: src/gen
+`;
+      const expected = `# comment
+version: v2
+inputs:
+  - directory: proto
+plugins:
+  # keep
+  - local: protoc-gen-es
+    out: src/gen
+  # keep
+  - local: protoc-gen-foo
+    out: src/gen
+`;
+      const yaml = parseBufGenYaml(input);
+      const updated = migrateBufGenYaml(yaml, [migration]);
+      expect(updated).toBeDefined();
+      expect(stringifyBufGenYaml(updated ?? yaml)).toBe(expected);
+    });
+    it("should remove plugin from v1", () => {
+      const input = `# comment
+version: v1
+plugins:
+  # keep
+  - plugin: es
+    out: src/gen
+  # remove
+  - plugin: connect-es
+    out: src/gen
+  # keep
+  - plugin: foo
+    out: src/gen
+  # remove
+  - plugin: buf.build/connectrpc/es
+    out: src/gen
+  # remove
+  - plugin: buf.build/connectrpc/es:v1.4.0
+    out: src/gen
+`;
+      const expected = `# comment
+version: v1
+plugins:
+  # keep
+  - plugin: es
+    out: src/gen
+  # keep
+  - plugin: foo
+    out: src/gen
+`;
+      const yaml = parseBufGenYaml(input);
+      const updated = migrateBufGenYaml(yaml, [migration]);
+      expect(updated).toBeDefined();
+      expect(stringifyBufGenYaml(updated ?? yaml)).toBe(expected);
+    });
+  });
+});