Setup api extractor for xml library (#4335)

Ideally we can connect that to api view to report changes to the api
without having to commit extra files to the repo.

But for now this at least enforce the good pattern for api extractor

.chronus/changes/api-extractor-trial-2024-8-4-15-12-5.md

@@ -0,0 +1,8 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: internal
+packages:
+  - "@typespec/xml"
+---
+
+Setup api extractor for xml library

.gitignore

@@ -198,7 +198,8 @@ obj/
 *.vsix
 *.zip
 
-
+# Api extractor
+packages/*/etc/
 docs/**/js-api/
 
 # csharp emitter

api-extractor.base.json

@@ -0,0 +1,51 @@
+/**
+ * Config file for API Extractor.  For more info, please visit: https://api-extractor.com
+ */
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "mainEntryPointFilePath": "<projectFolder>/dist/src/index.d.ts",
+  "apiReport": {
+    "enabled": true,
+    "reportFolder": "<projectFolder>/temp"
+  },
+  "docModel": {
+    "enabled": true
+  },
+  "dtsRollup": {
+    "enabled": false
+  },
+  "messages": {
+    "compilerMessageReporting": {
+      "default": {
+        "logLevel": "error"
+      }
+    },
+
+    "extractorMessageReporting": {
+      "default": {
+        "logLevel": "error"
+      },
+      "ae-undocumented": {
+        "logLevel": "error"
+      },
+      "ae-forgotten-export": {
+        "logLevel": "none", // False positive with decorators functions.
+        "addToApiReportFile": false
+      },
+      "ae-missing-release-tag": {
+        "logLevel": "none", // This is just extra verbosity. Should rely on api view to see if we exported something by mistake
+        "addToApiReportFile": false
+      }
+    },
+
+    "tsdocMessageReporting": {
+      "default": {
+        "logLevel": "error"
+      },
+      "tsdoc-param-tag-missing-hyphen": {
+        "logLevel": "none",
+        "addToApiReportFile": false
+      }
+    }
+  }
+}

package.json

@@ -39,6 +39,7 @@
     "@chronus/chronus": "^0.11.0",
     "@chronus/github": "^0.4.1",
     "@eslint/js": "^8.57.0",
+    "@microsoft/api-extractor": "^7.47.7",
     "@octokit/core": "^6.1.2",
     "@octokit/plugin-paginate-graphql": "^5.2.2",
     "@octokit/plugin-rest-endpoint-methods": "^13.2.4",

packages/xml/api-extractor.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "extends": "../../api-extractor.base.json"
+}

packages/xml/package.json

@@ -28,7 +28,7 @@
   },
   "scripts": {
     "clean": "rimraf ./dist ./temp",
-    "build": "npm run gen-extern-signature && tsc -p . && npm run lint-typespec-library",
+    "build": "npm run gen-extern-signature && tsc -p . && npm run lint-typespec-library && pnpm api-extractor",
     "watch": "tsc -p . --watch",
     "gen-extern-signature": "tspd --enable-experimental gen-extern-signature .",
     "lint-typespec-library": "tsp compile . --warn-as-error --import @typespec/library-linter --no-emit",
@@ -38,7 +38,8 @@
     "test-official": "vitest run --coverage --reporter=junit --reporter=default --no-file-parallelism",
     "lint": "eslint . --ext .ts --max-warnings=0",
     "lint:fix": "eslint . --fix --ext .ts",
-    "regen-docs": "tspd doc .  --enable-experimental  --output-dir ../../docs/libraries/xml/reference"
+    "regen-docs": "tspd doc .  --enable-experimental  --output-dir ../../docs/libraries/xml/reference",
+    "api-extractor": "api-extractor run --local --verbose"
   },
   "files": [
     "lib/*.tsp",

packages/xml/src/decorators.ts

@@ -19,10 +19,12 @@ import type { XmlNamespace } from "./types.js";
 /** @internal */
 export const namespace = "TypeSpec.Xml";
 
+/** {@inheritDoc NameDecorator}  */
 export const $name: NameDecorator = (context, target, name) => {
   context.call($encodedName, target, "application/xml", name);
 };
 
+/** {@inheritDoc AttributeDecorator} */
 export const $attribute: AttributeDecorator = (context, target) => {
   context.program.stateSet(XmlStateKeys.attribute).add(target);
 };
@@ -34,6 +36,7 @@ export function isAttribute(program: Program, target: ModelProperty): boolean {
   return program.stateSet(XmlStateKeys.attribute).has(target);
 }
 
+/** {@inheritdoc UnwrappedDecorator} */
 export const $unwrapped: UnwrappedDecorator = (context, target) => {
   context.program.stateSet(XmlStateKeys.unwrapped).add(target);
 };
@@ -45,6 +48,7 @@ export function isUnwrapped(program: Program, target: ModelProperty): boolean {
   return program.stateSet(XmlStateKeys.unwrapped).has(target);
 }
 
+/** {@inheritdoc NsDeclarationsDecorator} */
 export const $nsDeclarations: NsDeclarationsDecorator = (context, target) => {
   context.program.stateSet(XmlStateKeys.nsDeclaration).add(target);
 };
@@ -53,6 +57,7 @@ function isNsDeclarationsEnum(program: Program, target: Enum): boolean {
   return program.stateSet(XmlStateKeys.nsDeclaration).has(target);
 }
 
+/** {@inheritdoc NsDecorator} */
 export const $ns: NsDecorator = (context, target, namespace: Type, prefix?: string) => {
   const data = getData(context, namespace, prefix);
   if (data) {

packages/xml/src/index.ts

@@ -1,3 +1,10 @@
+export type {
+  AttributeDecorator,
+  NameDecorator,
+  NsDeclarationsDecorator,
+  NsDecorator,
+  UnwrappedDecorator,
+} from "../generated-defs/TypeSpec.Xml.js";
 export {
   $attribute,
   $name,
@@ -8,6 +15,7 @@ export {
   isAttribute,
   isUnwrapped,
 } from "./decorators.js";
+
 export { getXmlEncoding } from "./encoding.js";
 export { $lib } from "./lib.js";
 export type { XmlEncodeData, XmlEncoding, XmlNamespace } from "./types.js";

packages/xml/src/lib.ts

@@ -1,5 +1,6 @@
 import { createTypeSpecLibrary, paramMessage } from "@typespec/compiler";
 
+/** TypeSpec Xml Library Definition */
 export const $lib = createTypeSpecLibrary({
   name: "@typespec/xml",
   diagnostics: {

packages/xml/src/types.ts

@@ -1,7 +1,12 @@
 import type { EncodeData, Scalar } from "@typespec/compiler";
 
+/**
+ * Represents an XML namespace.
+ */
 export interface XmlNamespace {
+  /** Namespace name */
   readonly namespace: string;
+  /** Namespace prefix */
   readonly prefix: string;
 }
 
@@ -20,7 +25,12 @@ export type XmlEncoding =
   /** Corespond to a field of schema 	xs:base64Binary */
   | "TypeSpec.Xml.Encoding.xmlBase64Binary";
 
+/**
+ * Xml Encoding information.
+ */
 export interface XmlEncodeData extends EncodeData {
+  /** Encoding */
   encoding?: XmlEncoding | EncodeData["encoding"];
+  /** Encoding target type.(e.g. string) */
   type: Scalar;
 }