@foxglove/schemas 0.1.2

package/src/generateRos.ts

@@ -0,0 +1,219 @@
+import type { RosMsgDefinition, RosMsgField } from "@foxglove/rosmsg";
+import { definitions as rosCommonDefs } from "@foxglove/rosmsg-msgs-common";
+
+import { FoxgloveMessageSchema, FoxglovePrimitive } from "./types";
+
+type RosMsgFieldWithDescription = RosMsgField & {
+  description?: string;
+};
+type RosMsgDefinitionWithDescription = {
+  originalName: string;
+  description?: string;
+  qualifiedRosName: string;
+  fields: RosMsgFieldWithDescription[];
+};
+
+function primitiveToRos(
+  type: Exclude<FoxglovePrimitive, "uint32" | "bytes">,
+  { rosVersion }: { rosVersion: 1 | 2 },
+) {
+  switch (type) {
+    case "string":
+      return "string";
+    case "boolean":
+      return "bool";
+    case "float64":
+      return "float64";
+    case "time":
+      return rosVersion === 2 ? "builtin_interfaces/Time" : "time";
+    case "duration":
+      return rosVersion === 2 ? "builtin_interfaces/Duration" : "duration";
+  }
+}
+
+export function generateRosMsg(def: RosMsgDefinitionWithDescription): string {
+  let source = "";
+  source += `# Generated from ${def.originalName} by @foxglove/schemas\n`;
+  if (def.description != undefined) {
+    source += `# ${def.description}\n`;
+  }
+  let prevFieldHadComment = true; // start true because of top-of-file comment
+  for (const field of def.fields) {
+    if (prevFieldHadComment || field.description != undefined) {
+      source += "\n";
+    }
+    prevFieldHadComment = false;
+    if (field.description != undefined) {
+      source += field.description
+        .trim()
+        .split("\n")
+        .map((line) => `# ${line}\n`)
+        .join("");
+      prevFieldHadComment = true;
+    }
+    let constant = "";
+    if (field.isConstant === true) {
+      if (field.valueText == undefined) {
+        throw new Error(`Constant ${field.name} has no valueText`);
+      }
+      constant = `=${field.valueText}`;
+    }
+    source += `${field.type}${field.isArray === true ? `[${field.arrayLength ?? ""}]` : ""} ${
+      field.name
+    }${constant}\n`;
+  }
+  return source;
+}
+
+type Dependency =
+  | { type: "ros"; name: keyof typeof rosCommonDefs }
+  | { type: "foxglove"; schema: FoxgloveMessageSchema };
+
+function dependenciesEqual(a: Dependency, b: Dependency) {
+  return (
+    (a.type === "foxglove" && b.type === "foxglove" && a.schema.name === b.schema.name) ||
+    (a.type === "ros" && b.type === "ros" && a.name === b.name)
+  );
+}
+
+function* getSchemaDependencies(schema: FoxgloveMessageSchema): Iterable<Dependency> {
+  for (const field of schema.fields) {
+    if (field.type.type === "nested") {
+      if (field.type.schema.rosEquivalent != undefined) {
+        yield { type: "ros", name: field.type.schema.rosEquivalent };
+        yield* getRosDependencies(rosCommonDefs[field.type.schema.rosEquivalent]);
+      } else {
+        yield { type: "foxglove", schema: field.type.schema };
+        yield* getSchemaDependencies(field.type.schema);
+      }
+    }
+  }
+}
+function* getRosDependencies(schema: RosMsgDefinition): Iterable<Dependency> {
+  for (const field of schema.definitions) {
+    if (field.isComplex === true) {
+      yield { type: "ros", name: field.type as keyof typeof rosCommonDefs };
+      yield* getRosDependencies(rosCommonDefs[field.type as keyof typeof rosCommonDefs]!);
+    }
+  }
+}
+
+export function generateRosMsgDefinition(
+  schema: FoxgloveMessageSchema,
+  { rosVersion }: { rosVersion: 1 | 2 },
+): RosMsgDefinitionWithDescription {
+  const enumFieldNames = new Set<string>();
+  const seenEnumNames = new Set<string>();
+
+  const fields: RosMsgFieldWithDescription[] = [];
+  for (const field of schema.fields) {
+    let isArray = field.array != undefined;
+    const arrayLength = typeof field.array === "number" ? field.array : undefined;
+    let fieldType: string;
+    switch (field.type.type) {
+      case "enum": {
+        // Add enum constants preceding the field so that Studio can pick them up:
+        // https://foxglove.dev/docs/studio/annotating-data
+        const enumName = field.type.enum.name;
+        const valueType = "uint8";
+        fieldType = valueType;
+        if (seenEnumNames.has(enumName)) {
+          break;
+        }
+        const enumFields: RosMsgFieldWithDescription[] = [];
+        for (const { name, value, description } of field.type.enum.values) {
+          if (enumFieldNames.has(name)) {
+            throw new Error(
+              `Enum value ${name} occurs in more than one enum referenced by ${schema.name}, this is not supported in ROS msg files`,
+            );
+          }
+          if (value < 0 || value > 255 || !Number.isInteger(value)) {
+            throw new Error(
+              `Only uint8 enums are currently supported; value ${name}=${value} is out of range`,
+            );
+          }
+          enumFieldNames.add(name);
+          enumFields.push({
+            name,
+            value,
+            isConstant: true,
+            valueText: value.toString(),
+            type: valueType,
+            description,
+          });
+        }
+        fields.push(...enumFields);
+        seenEnumNames.add(enumName);
+        break;
+      }
+
+      case "nested":
+        if (field.type.schema.rosEquivalent != undefined) {
+          fieldType = field.type.schema.rosEquivalent;
+        } else {
+          fieldType = `foxglove_msgs/${field.type.schema.name}`;
+        }
+        break;
+
+      case "primitive":
+        if (field.type.name === "bytes") {
+          fieldType = "uint8";
+          if (isArray) {
+            throw new Error("Array of bytes is not supported in ROS msg");
+          }
+          isArray = true;
+        } else if (field.type.name === "uint32") {
+          fieldType = "uint32";
+        } else {
+          fieldType = primitiveToRos(field.type.name, { rosVersion });
+        }
+        break;
+    }
+    fields.push({
+      name: rosVersion === 2 ? field.name.toLowerCase() : field.name,
+      type: fieldType,
+      isComplex: field.type.type === "nested",
+      isArray,
+      arrayLength,
+      description: field.description,
+    });
+  }
+
+  return {
+    originalName: schema.name,
+    qualifiedRosName: `foxglove_msgs/${schema.name}`,
+    fields,
+  };
+}
+
+export function generateRosMsgMergedSchema(
+  schema: FoxgloveMessageSchema,
+  { rosVersion }: { rosVersion: 1 | 2 },
+): string {
+  const dependencies: Dependency[] = [];
+  for (const dep of getSchemaDependencies(schema)) {
+    if (!dependencies.some((existing) => dependenciesEqual(existing, dep))) {
+      dependencies.push(dep);
+    }
+  }
+
+  let result = generateRosMsg(generateRosMsgDefinition(schema, { rosVersion }));
+  for (const dep of dependencies) {
+    let name: string;
+    let source: string;
+    if (dep.type === "ros") {
+      name = dep.name;
+      source = generateRosMsg({
+        originalName: dep.name,
+        qualifiedRosName: dep.name,
+        fields: rosCommonDefs[dep.name].definitions,
+      });
+    } else {
+      const definition = generateRosMsgDefinition(dep.schema, { rosVersion });
+      name = definition.qualifiedRosName;
+      source = generateRosMsg(definition);
+    }
+    result += `================================================================================\nMSG: ${name}\n${source}`;
+  }
+  return result;
+}

package/src/generateTypeScript.test.ts

@@ -0,0 +1,118 @@
+import { generateTypeScript } from "./generateTypeScript";
+import { exampleEnum, exampleMessage } from "./testFixtures";
+
+describe("generateTypeScript", () => {
+  it("generates .d.ts files", () => {
+    expect(generateTypeScript(exampleEnum)).toMatchInlineSnapshot(`
+      "// Generated from ExampleEnum by @foxglove/schemas
+
+      /** An example enum */
+      export enum ExampleEnum {
+        /** Value A */
+        A = 1,
+
+        /** Value B */
+        B = 2,
+      }
+      "
+    `);
+    expect(generateTypeScript(exampleMessage)).toMatchInlineSnapshot(`
+      "// Generated from ExampleMessage by @foxglove/schemas
+
+      import { Duration } from \\"./Duration\\";
+      import { ExampleEnum } from \\"./ExampleEnum\\";
+      import { NestedMessage } from \\"./NestedMessage\\";
+      import { Time } from \\"./Time\\";
+
+      /** An example type */
+      export type ExampleMessage = {
+        /** duration field */
+        field_duration: Duration;
+
+        /** time field */
+        field_time: Time;
+
+        /** boolean field */
+        field_boolean: boolean;
+
+        /** bytes field */
+        field_bytes: Uint8Array;
+
+        /** float64 field */
+        field_float64: number;
+
+        /** uint32 field */
+        field_uint32: number;
+
+        /** string field */
+        field_string: string;
+
+        /** duration array field */
+        field_duration_array: Duration[];
+
+        /** time array field */
+        field_time_array: Time[];
+
+        /** boolean array field */
+        field_boolean_array: boolean[];
+
+        /** bytes array field */
+        field_bytes_array: Uint8Array[];
+
+        /** float64 array field */
+        field_float64_array: number[];
+
+        /** uint32 array field */
+        field_uint32_array: number[];
+
+        /** string array field */
+        field_string_array: string[];
+
+        /** duration fixed-length array field */
+        field_duration_fixed_array: [Duration, Duration, Duration];
+
+        /** time fixed-length array field */
+        field_time_fixed_array: [Time, Time, Time];
+
+        /** boolean fixed-length array field */
+        field_boolean_fixed_array: [boolean, boolean, boolean];
+
+        /** bytes fixed-length array field */
+        field_bytes_fixed_array: [Uint8Array, Uint8Array, Uint8Array];
+
+        /** float64 fixed-length array field */
+        field_float64_fixed_array: [number, number, number];
+
+        /** uint32 fixed-length array field */
+        field_uint32_fixed_array: [number, number, number];
+
+        /** string fixed-length array field */
+        field_string_fixed_array: [string, string, string];
+
+        /** An enum field */
+        field_enum: ExampleEnum;
+
+        /** An enum array field */
+        field_enum_array: ExampleEnum[];
+
+        /** A nested field */
+        field_nested: NestedMessage;
+
+        /**
+         * A nested array field
+         * With
+         * a
+         * very
+         * long
+         * description
+         */
+        field_nested_array: NestedMessage[];
+      };
+      "
+    `);
+  });
+
+  it("generates parseable .ts files", async () => {
+    await expect(import("../schemas/typescript")).resolves.not.toThrow();
+  });
+});

package/src/generateTypeScript.ts

@@ -0,0 +1,106 @@
+import { FoxglovePrimitive, FoxgloveSchema } from "./types";
+
+function primitiveToTypeScript(type: Exclude<FoxglovePrimitive, "time" | "duration">) {
+  switch (type) {
+    case "bytes":
+      return "Uint8Array";
+    case "string":
+      return "string";
+    case "boolean":
+      return "boolean";
+    case "float64":
+    case "uint32":
+      return "number";
+  }
+}
+
+export const TIME_TS = `export type Time = {
+  sec: number;
+  nsec: number;
+};
+`;
+
+export const DURATION_TS = `export type Duration = {
+  sec: number;
+  nsec: number;
+};
+`;
+
+export function generateTypeScript(schema: FoxgloveSchema): string {
+  const imports = new Set<string>();
+
+  let definition: string;
+  switch (schema.type) {
+    case "enum": {
+      const fields = schema.values.map(({ name, value, description }) => {
+        if (description != undefined) {
+          return `/** ${description} */\n  ${name} = ${value},`;
+        } else {
+          return `${name} = ${value},`;
+        }
+      });
+      definition = `/** ${schema.description} */\nexport enum ${schema.name} {\n  ${fields.join(
+        "\n\n  ",
+      )}\n}`;
+      break;
+    }
+
+    case "message": {
+      const fields = schema.fields.map((field) => {
+        let fieldType: string;
+        switch (field.type.type) {
+          case "enum":
+            fieldType = field.type.enum.name;
+            imports.add(field.type.enum.name);
+            break;
+          case "nested":
+            fieldType = field.type.schema.name;
+            imports.add(field.type.schema.name);
+            break;
+          case "primitive":
+            if (field.type.name === "time") {
+              fieldType = "Time";
+              imports.add("Time");
+            } else if (field.type.name === "duration") {
+              fieldType = "Duration";
+              imports.add("Duration");
+            } else {
+              fieldType = primitiveToTypeScript(field.type.name);
+            }
+            break;
+        }
+        if (typeof field.array === "number") {
+          fieldType = `[${new Array(field.array).fill(fieldType).join(", ")}]`;
+        } else if (field.array != undefined) {
+          fieldType = `${fieldType}[]`;
+        }
+        let comment: string;
+        const descriptionLines = field.description.trim().split("\n");
+        if (descriptionLines.length === 1) {
+          comment = `/** ${field.description} */`;
+        } else {
+          comment = `/**\n  ${descriptionLines.map((line) => ` * ${line}`).join("\n  ")}\n   */`;
+        }
+        return `${comment}\n  ${field.name}: ${fieldType};`;
+      });
+
+      definition = `/** ${schema.description} */\nexport type ${schema.name} = {\n  ${fields.join(
+        "\n\n  ",
+      )}\n};`;
+      break;
+    }
+  }
+
+  const outputSections = [
+    `// Generated from ${schema.name} by @foxglove/schemas`,
+
+    Array.from(imports)
+      .sort()
+      .map((name) => `import { ${name} } from "./${name}";`)
+      .join("\n"),
+
+    definition,
+  ].filter(Boolean);
+
+  return outputSections.join("\n\n") + "\n";
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./schemas";
+export * from "./types";
+export * from "./generateRos";
+export * from "./generateProto";
+export * from "./generateJsonSchema";

package/src/schemas.test.ts

@@ -0,0 +1,23 @@
+import { foxgloveEnumSchemas, foxgloveMessageSchemas } from "./schemas";
+
+describe("schemas", () => {
+  it("has matching names", () => {
+    for (const [key, value] of Object.entries(foxgloveMessageSchemas)) {
+      expect(key).toEqual(value.name);
+    }
+    for (const [key, value] of Object.entries(foxgloveEnumSchemas)) {
+      expect(key).toEqual(value.name);
+      expect(value.protobufParentMessageName in foxgloveMessageSchemas).toBe(true);
+    }
+  });
+
+  it("has valid descriptions", () => {
+    for (const schema of Object.values(foxgloveMessageSchemas)) {
+      // Multi-line descriptions are supported for fields, but not currently for schemas
+      expect(schema.description.includes("\n")).toBe(false);
+      for (const field of schema.fields) {
+        expect(field.description.includes("*/")).toBe(false);
+      }
+    }
+  });
+});