@typespec/tspd 0.70.0-dev.2 → 0.70.0

package/dist/src/ref-doc/emitters/markdown.js

@@ -1,339 +1,290 @@
-import { getEntityName, isType, resolvePath, } from "@typespec/compiler";
+import { getEntityName, isType, resolvePath } from "@typespec/compiler";
 import { readFile } from "fs/promises";
 import { stringify } from "yaml";
-import { codeblock, inlinecode, link, renderMarkdowDoc, section, table, } from "../utils/markdown.js";
+import { codeblock, inlinecode, link, renderMarkdowDoc, section, table } from "../utils/markdown.js";
 async function loadTemplate(projectRoot, name) {
-    try {
-        const content = await readFile(resolvePath(projectRoot, `.tspd/docs/${name}.md`));
-        return content.toString();
-    }
-    catch (e) {
-        if (typeof e === "object" && e?.code === "ENOENT") {
-            return undefined;
-        }
-        throw e;
-    }
+  try {
+    const content = await readFile(resolvePath(projectRoot, `.tspd/docs/${name}.md`));
+    return content.toString();
+  } catch (e) {
+    if (typeof e === "object" && e?.code === "ENOENT") {
+      return undefined;
+    }
+    throw e;
+  }
 }
 export async function renderReadme(refDoc, projectRoot) {
-    const content = [];
-    const renderer = new MarkdownRenderer(refDoc);
-    const headerTemplate = await loadTemplate(projectRoot, "header");
-    if (headerTemplate) {
-        content.push(headerTemplate);
-    }
-    if (refDoc.description) {
-        content.push(refDoc.description);
-    }
-    content.push(renderer.install(refDoc));
-    const usageTemplate = await loadTemplate(projectRoot, "usage");
-    if (usageTemplate) {
-        content.push(section("Usage", [usageTemplate]));
-    }
-    if (refDoc.emitter?.options) {
-        content.push(renderer.emitterUsage(refDoc));
-    }
-    if (refDoc.linter) {
-        content.push(renderer.linterUsage(refDoc));
-    }
-    if (refDoc.namespaces.some((x) => x.decorators.length > 0)) {
-        content.push(section("Decorators", renderer.decoratorsSection(refDoc, { includeToc: true })));
-    }
-    const footerTemplate = await loadTemplate(projectRoot, "footer");
-    if (footerTemplate) {
-        content.push(footerTemplate);
-    }
-    return renderMarkdowDoc(section(refDoc.name, content));
+  const content = [];
+  const renderer = new MarkdownRenderer(refDoc);
+  const headerTemplate = await loadTemplate(projectRoot, "header");
+  if (headerTemplate) {
+    content.push(headerTemplate);
+  }
+  if (refDoc.description) {
+    content.push(refDoc.description);
+  }
+  content.push(renderer.install(refDoc));
+  const usageTemplate = await loadTemplate(projectRoot, "usage");
+  if (usageTemplate) {
+    content.push(section("Usage", [usageTemplate]));
+  }
+  if (refDoc.emitter?.options) {
+    content.push(renderer.emitterUsage(refDoc));
+  }
+  if (refDoc.linter) {
+    content.push(renderer.linterUsage(refDoc));
+  }
+  if (refDoc.namespaces.some(x => x.decorators.length > 0)) {
+    content.push(section("Decorators", renderer.decoratorsSection(refDoc, {
+      includeToc: true
+    })));
+  }
+  const footerTemplate = await loadTemplate(projectRoot, "footer");
+  if (footerTemplate) {
+    content.push(footerTemplate);
+  }
+  return renderMarkdowDoc(section(refDoc.name, content));
 }
 export function groupByNamespace(namespaces, callback) {
-    const content = [];
-    for (const namespace of namespaces) {
-        const contentForNamespace = callback(namespace);
-        if (contentForNamespace) {
-            content.push(section(namespace.id, contentForNamespace));
-        }
-    }
-    return content;
+  const content = [];
+  for (const namespace of namespaces) {
+    const contentForNamespace = callback(namespace);
+    if (contentForNamespace) {
+      content.push(section(namespace.id, contentForNamespace));
+    }
+  }
+  return content;
 }
+
 /**
  * Github flavored markdown renderer.
  */
 export class MarkdownRenderer {
-    refDoc;
-    constructor(refDoc) {
-        this.refDoc = refDoc;
-    }
-    headingTitle(item) {
-        return inlinecode(item.name);
-    }
-    anchorId(item) {
-        return `${item.name.toLowerCase().replace(/ /g, "-")}`;
-    }
-    deprecationNotice(notice) {
-        return `_Deprecated: ${notice.message}_`;
-    }
-    typeSection(type, content) {
-        const deprecated = type.deprecated ? this.deprecationNotice(type.deprecated) : [];
-        return section(this.headingTitle(type), [deprecated, content]);
-    }
-    //#region TypeSpec types
-    operation(op) {
-        const content = ["", op.doc, codeblock(op.signature, "typespec"), ""];
-        if (op.templateParameters) {
-            content.push(this.templateParameters(op.templateParameters));
-        }
-        content.push(this.examples(op.examples));
-        return this.typeSection(op, content);
-    }
-    interface(iface) {
-        const content = ["", iface.doc, codeblock(iface.signature, "typespec"), ""];
-        if (iface.templateParameters) {
-            content.push(this.templateParameters(iface.templateParameters));
-        }
-        if (iface.interfaceOperations.length > 0) {
-            for (const op of iface.interfaceOperations) {
-                content.push(this.operation(op));
-            }
-        }
-        content.push(this.examples(iface.examples));
-        return this.typeSection(iface, content);
-    }
-    model(model) {
-        const content = ["", model.doc, codeblock(model.signature, "typespec"), ""];
-        if (model.templateParameters) {
-            content.push(this.templateParameters(model.templateParameters));
-        }
-        content.push(this.examples(model.examples));
-        content.push(this.modelProperties(model));
-        return this.typeSection(model, content);
-    }
-    modelProperties(model) {
-        const content = [];
-        if (model.properties.size === 0 && model.type.indexer === undefined) {
-            return section("Properties", "None");
-        }
-        const rows = [
-            { name: "Name", type: "Type", doc: "Description" },
-        ];
-        for (const prop of model.properties.values()) {
-            const propRows = this.modelPropertyRows(prop);
-            for (const row of propRows) {
-                rows.push(row);
-            }
-        }
-        if (model.type.indexer) {
-            rows.push({
-                name: "",
-                type: this.ref(model.type.indexer.value),
-                doc: "Additional properties",
-            });
-        }
-        content.push(table(rows.map((x) => [x.name, x.type, x.doc])));
-        return section("Properties", content);
-    }
-    modelPropertyRows(prop) {
-        const name = `${prop.name}${prop.type.optional ? "?" : ""}`;
-        const base = {
-            name: prop.deprecated ? `~~${name}~~ _DEPRECATED_` : name,
-            type: this.ref(prop.type.type),
-            doc: prop.doc,
-        };
-        if (prop.type.type.kind === "Model" && prop.type.type.name === "") {
-            return [
-                base,
-                ...[...prop.type.type.properties.values()].map((x) => ({
-                    name: `${prop.name}.${x.name}${x.optional ? "?" : ""}`,
-                    type: this.ref(x.type),
-                    doc: "",
-                })),
-            ];
-        }
-        return [base];
-    }
-    ref(type, prefix = "") {
-        const namedType = isType(type) && this.refDoc.getNamedTypeRefDoc(type);
-        if (namedType) {
-            return link(prefix + inlinecode(namedType.name), `${this.filename(namedType)}#${this.anchorId(namedType)}`);
-        }
-        // So we don't show (anonymous model) until this gets improved.
-        if ("kind" in type && type.kind === "Model" && type.name === "" && type.properties.size > 0) {
-            return inlinecode(prefix + "{...}");
-        }
-        return inlinecode(prefix +
-            getEntityName(type, {
-                namespaceFilter: (ns) => !this.refDoc.namespaces.some((x) => x.name === ns.name),
-            }));
-    }
-    enum(e) {
-        const content = [
-            "",
-            e.doc,
-            codeblock(e.signature, "typespec"),
-            "",
-            this.enumMembers(e),
-            this.examples(e.examples),
-        ];
-        return this.typeSection(e, content);
-    }
-    enumMembers(e) {
-        const rows = [...e.members.values()].map((x) => {
-            return [
-                x.name,
-                x.type.value
-                    ? inlinecode(typeof x.type.value === "string" ? `"${x.type.value}"` : x.type.value.toString())
-                    : "",
-                x.doc,
-            ];
-        });
-        return table([["Name", "Value", "Description"], ...rows]);
-    }
-    union(union) {
-        const content = ["", union.doc, codeblock(union.signature, "typespec"), ""];
-        if (union.templateParameters) {
-            content.push(this.templateParameters(union.templateParameters));
-        }
-        content.push(this.examples(union.examples));
-        return this.typeSection(union, content);
-    }
-    scalar(scalar) {
-        const content = ["", scalar.doc, codeblock(scalar.signature, "typespec"), ""];
-        if (scalar.templateParameters) {
-            content.push(this.templateParameters(scalar.templateParameters));
-        }
-        content.push(this.examples(scalar.examples));
-        return this.typeSection(scalar, content);
-    }
-    templateParameters(templateParameters) {
-        const paramTable = [["Name", "Description"]];
-        for (const param of templateParameters) {
-            paramTable.push([param.name, param.doc]);
-        }
-        return section("Template Parameters", [table(paramTable), ""]);
-    }
-    decorator(dec) {
-        const content = ["", dec.doc, codeblock(dec.signature, "typespec"), ""];
-        content.push(section("Target", [dec.target.doc, this.ref(dec.target.type.type), ""]));
-        if (dec.parameters.length > 0) {
-            const paramTable = [["Name", "Type", "Description"]];
-            for (const param of dec.parameters) {
-                paramTable.push([param.name, this.MixedParameterConstraint(param.type.type), param.doc]);
-            }
-            content.push(section("Parameters", [table(paramTable), ""]));
-        }
-        else {
-            content.push(section("Parameters", ["None", ""]));
-        }
-        content.push(this.examples(dec.examples));
-        return this.typeSection(dec, content);
-    }
-    MixedParameterConstraint(constraint) {
-        return [
-            ...(constraint.type ? [this.ref(constraint.type)] : []),
-            ...(constraint.valueType ? [this.ref(constraint.valueType, "valueof ")] : []),
-        ].join(" | ");
-    }
-    examples(examples) {
-        const content = [];
-        if (examples.length === 0) {
-            return "";
-        }
-        for (const example of examples) {
-            const exampleContent = ["", example.content, ""];
-            if (example.title) {
-                content.push(section(example.title, exampleContent));
-            }
-            else {
-                content.push(exampleContent);
-            }
-        }
-        return section("Examples", content);
-    }
-    // #endregion TypeSpec types
-    /** Render all decorators */
-    decoratorsSection(refDoc, options = {}) {
-        return groupByNamespace(refDoc.namespaces, (namespace) => {
-            if (namespace.decorators.length === 0) {
-                return undefined;
-            }
-            return [
-                options.includeToc ? this.toc(namespace.decorators) : [],
-                namespace.decorators.map((x) => [this.decorator(x), ""]),
-            ];
-        });
-    }
-    toc(items) {
-        return items.map((item) => ` - [${inlinecode(item.name)}](${this.filename(item)}#${this.anchorId(item)})`);
-    }
-    filename(type) {
-        return "";
-    }
-    install(refDoc) {
-        return section("Install", [codeblock(`npm install ${refDoc.name}`, "bash")]);
-    }
-    emitterUsage(refDoc) {
-        if (refDoc.emitter?.options === undefined) {
-            return [];
-        }
-        return [
-            section("Usage", [
-                "1. Via the command line",
-                codeblock(`tsp compile . --emit=${refDoc.name}`, "bash"),
-                "2. Via the config",
-                codeblock(`emit:\n  - "${refDoc.name}" `, "yaml"),
-                "The config can be extended with options as follows:",
-                codeblock(`emit:\n  - "${refDoc.name}"\noptions:\n  "${refDoc.name}":\n    option: value`, "yaml"),
-            ]),
-            this.emitterOptions(refDoc.emitter.options),
-        ];
-    }
-    emitterOptions(options) {
-        const content = [];
-        content.push(section(`${inlinecode("emitter-output-dir")}`, [
-            `**Type:** ${inlinecode("absolutePath")}`,
-            "",
-            `Defines the emitter output directory. Defaults to \`{output-dir}/${this.refDoc.name}\``,
-            `See [Configuring output directory for more info](https://typespec.io/docs/handbook/configuration/configuration/#configuring-output-directory)`,
-        ]));
-        for (const option of options) {
-            content.push(section(`${inlinecode(option.name)}`, [
-                `**Type:** ${inlinecode(option.type)}`,
-                "",
-                option.doc,
-            ]));
-        }
-        return section("Emitter options", content);
-    }
-    linterUsage(refDoc) {
-        if (refDoc.linter === undefined) {
-            return [];
-        }
-        const setupExample = stringify({
-            linter: refDoc.linter.ruleSets
-                ? { extends: [refDoc.linter.ruleSets[0].name] }
-                : { rules: {} },
-        });
-        return [
-            section("Usage", ["Add the following in `tspconfig.yaml`:", codeblock(setupExample, "yaml")]),
-            refDoc.linter.ruleSets
-                ? section("RuleSets", [
-                    "Available ruleSets:",
-                    refDoc.linter.ruleSets.map((item) => ` - ${inlinecode(item.name)}`),
-                ])
-                : [],
-            section("Rules", this.linterRuleToc(refDoc.linter.rules)),
-        ];
-    }
-    linterRuleToc(rules) {
-        return table([
-            ["Name", "Description"],
-            ...rules.map((rule) => {
-                const name = inlinecode(rule.name);
-                const nameCell = rule.rule.url ? link(name, this.linterRuleLink(rule.rule.url)) : name;
-                return [nameCell, rule.rule.description];
-            }),
-        ]);
-    }
-    linterRuleLink(url) {
-        return url;
-    }
-}
-//# sourceMappingURL=markdown.js.map
+  constructor(refDoc) {
+    this.refDoc = refDoc;
+  }
+  headingTitle(item) {
+    return inlinecode(item.name);
+  }
+  anchorId(item) {
+    return `${item.name.toLowerCase().replace(/ /g, "-")}`;
+  }
+  deprecationNotice(notice) {
+    return `_Deprecated: ${notice.message}_`;
+  }
+  typeSection(type, content) {
+    const deprecated = type.deprecated ? this.deprecationNotice(type.deprecated) : [];
+    return section(this.headingTitle(type), [deprecated, content]);
+  }
+
+  //#region TypeSpec types
+  operation(op) {
+    const content = ["", op.doc, codeblock(op.signature, "typespec"), ""];
+    if (op.templateParameters) {
+      content.push(this.templateParameters(op.templateParameters));
+    }
+    content.push(this.examples(op.examples));
+    return this.typeSection(op, content);
+  }
+  interface(iface) {
+    const content = ["", iface.doc, codeblock(iface.signature, "typespec"), ""];
+    if (iface.templateParameters) {
+      content.push(this.templateParameters(iface.templateParameters));
+    }
+    if (iface.interfaceOperations.length > 0) {
+      for (const op of iface.interfaceOperations) {
+        content.push(this.operation(op));
+      }
+    }
+    content.push(this.examples(iface.examples));
+    return this.typeSection(iface, content);
+  }
+  model(model) {
+    const content = ["", model.doc, codeblock(model.signature, "typespec"), ""];
+    if (model.templateParameters) {
+      content.push(this.templateParameters(model.templateParameters));
+    }
+    content.push(this.examples(model.examples));
+    content.push(this.modelProperties(model));
+    return this.typeSection(model, content);
+  }
+  modelProperties(model) {
+    const content = [];
+    if (model.properties.size === 0 && model.type.indexer === undefined) {
+      return section("Properties", "None");
+    }
+    const rows = [{
+      name: "Name",
+      type: "Type",
+      doc: "Description"
+    }];
+    for (const prop of model.properties.values()) {
+      const propRows = this.modelPropertyRows(prop);
+      for (const row of propRows) {
+        rows.push(row);
+      }
+    }
+    if (model.type.indexer) {
+      rows.push({
+        name: "",
+        type: this.ref(model.type.indexer.value),
+        doc: "Additional properties"
+      });
+    }
+    content.push(table(rows.map(x => [x.name, x.type, x.doc])));
+    return section("Properties", content);
+  }
+  modelPropertyRows(prop) {
+    const name = `${prop.name}${prop.type.optional ? "?" : ""}`;
+    const base = {
+      name: prop.deprecated ? `~~${name}~~ _DEPRECATED_` : name,
+      type: this.ref(prop.type.type),
+      doc: prop.doc
+    };
+    if (prop.type.type.kind === "Model" && prop.type.type.name === "") {
+      return [base, ...[...prop.type.type.properties.values()].map(x => ({
+        name: `${prop.name}.${x.name}${x.optional ? "?" : ""}`,
+        type: this.ref(x.type),
+        doc: ""
+      }))];
+    }
+    return [base];
+  }
+  ref(type, prefix = "") {
+    const namedType = isType(type) && this.refDoc.getNamedTypeRefDoc(type);
+    if (namedType) {
+      return link(prefix + inlinecode(namedType.name), `${this.filename(namedType)}#${this.anchorId(namedType)}`);
+    }
+
+    // So we don't show (anonymous model) until this gets improved.
+    if ("kind" in type && type.kind === "Model" && type.name === "" && type.properties.size > 0) {
+      return inlinecode(prefix + "{...}");
+    }
+    return inlinecode(prefix + getEntityName(type, {
+      namespaceFilter: ns => !this.refDoc.namespaces.some(x => x.name === ns.name)
+    }));
+  }
+  enum(e) {
+    const content = ["", e.doc, codeblock(e.signature, "typespec"), "", this.enumMembers(e), this.examples(e.examples)];
+    return this.typeSection(e, content);
+  }
+  enumMembers(e) {
+    const rows = [...e.members.values()].map(x => {
+      return [x.name, x.type.value ? inlinecode(typeof x.type.value === "string" ? `"${x.type.value}"` : x.type.value.toString()) : "", x.doc];
+    });
+    return table([["Name", "Value", "Description"], ...rows]);
+  }
+  union(union) {
+    const content = ["", union.doc, codeblock(union.signature, "typespec"), ""];
+    if (union.templateParameters) {
+      content.push(this.templateParameters(union.templateParameters));
+    }
+    content.push(this.examples(union.examples));
+    return this.typeSection(union, content);
+  }
+  scalar(scalar) {
+    const content = ["", scalar.doc, codeblock(scalar.signature, "typespec"), ""];
+    if (scalar.templateParameters) {
+      content.push(this.templateParameters(scalar.templateParameters));
+    }
+    content.push(this.examples(scalar.examples));
+    return this.typeSection(scalar, content);
+  }
+  templateParameters(templateParameters) {
+    const paramTable = [["Name", "Description"]];
+    for (const param of templateParameters) {
+      paramTable.push([param.name, param.doc]);
+    }
+    return section("Template Parameters", [table(paramTable), ""]);
+  }
+  decorator(dec) {
+    const content = ["", dec.doc, codeblock(dec.signature, "typespec"), ""];
+    content.push(section("Target", [dec.target.doc, this.ref(dec.target.type.type), ""]));
+    if (dec.parameters.length > 0) {
+      const paramTable = [["Name", "Type", "Description"]];
+      for (const param of dec.parameters) {
+        paramTable.push([param.name, this.MixedParameterConstraint(param.type.type), param.doc]);
+      }
+      content.push(section("Parameters", [table(paramTable), ""]));
+    } else {
+      content.push(section("Parameters", ["None", ""]));
+    }
+    content.push(this.examples(dec.examples));
+    return this.typeSection(dec, content);
+  }
+  MixedParameterConstraint(constraint) {
+    return [...(constraint.type ? [this.ref(constraint.type)] : []), ...(constraint.valueType ? [this.ref(constraint.valueType, "valueof ")] : [])].join(" | ");
+  }
+  examples(examples) {
+    const content = [];
+    if (examples.length === 0) {
+      return "";
+    }
+    for (const example of examples) {
+      const exampleContent = ["", example.content, ""];
+      if (example.title) {
+        content.push(section(example.title, exampleContent));
+      } else {
+        content.push(exampleContent);
+      }
+    }
+    return section("Examples", content);
+  }
+  // #endregion TypeSpec types
+
+  /** Render all decorators */
+  decoratorsSection(refDoc, options = {}) {
+    return groupByNamespace(refDoc.namespaces, namespace => {
+      if (namespace.decorators.length === 0) {
+        return undefined;
+      }
+      return [options.includeToc ? this.toc(namespace.decorators) : [], namespace.decorators.map(x => [this.decorator(x), ""])];
+    });
+  }
+  toc(items) {
+    return items.map(item => ` - [${inlinecode(item.name)}](${this.filename(item)}#${this.anchorId(item)})`);
+  }
+  filename(type) {
+    return "";
+  }
+  install(refDoc) {
+    return section("Install", [codeblock(`npm install ${refDoc.name}`, "bash")]);
+  }
+  emitterUsage(refDoc) {
+    if (refDoc.emitter?.options === undefined) {
+      return [];
+    }
+    return [section("Usage", ["1. Via the command line", codeblock(`tsp compile . --emit=${refDoc.name}`, "bash"), "2. Via the config", codeblock(`emit:\n  - "${refDoc.name}" `, "yaml"), "The config can be extended with options as follows:", codeblock(`emit:\n  - "${refDoc.name}"\noptions:\n  "${refDoc.name}":\n    option: value`, "yaml")]), this.emitterOptions(refDoc.emitter.options)];
+  }
+  emitterOptions(options) {
+    const content = [];
+    content.push(section(`${inlinecode("emitter-output-dir")}`, [`**Type:** ${inlinecode("absolutePath")}`, "", `Defines the emitter output directory. Defaults to \`{output-dir}/${this.refDoc.name}\``, `See [Configuring output directory for more info](https://typespec.io/docs/handbook/configuration/configuration/#configuring-output-directory)`]));
+    for (const option of options) {
+      content.push(section(`${inlinecode(option.name)}`, [`**Type:** ${inlinecode(option.type)}`, "", option.doc]));
+    }
+    return section("Emitter options", content);
+  }
+  linterUsage(refDoc) {
+    if (refDoc.linter === undefined) {
+      return [];
+    }
+    const setupExample = stringify({
+      linter: refDoc.linter.ruleSets ? {
+        extends: [refDoc.linter.ruleSets[0].name]
+      } : {
+        rules: {}
+      }
+    });
+    return [section("Usage", ["Add the following in `tspconfig.yaml`:", codeblock(setupExample, "yaml")]), refDoc.linter.ruleSets ? section("RuleSets", ["Available ruleSets:", refDoc.linter.ruleSets.map(item => ` - ${inlinecode(item.name)}`)]) : [], section("Rules", this.linterRuleToc(refDoc.linter.rules))];
+  }
+  linterRuleToc(rules) {
+    return table([["Name", "Description"], ...rules.map(rule => {
+      const name = inlinecode(rule.name);
+      const nameCell = rule.rule.url ? link(name, this.linterRuleLink(rule.rule.url)) : name;
+      return [nameCell, rule.rule.description];
+    })]);
+  }
+  linterRuleLink(url) {
+    return url;
+  }
+}