diff --git a/.chronus/changes/api-extractor-trial-2024-8-4-15-12-5.md b/.chronus/changes/api-extractor-trial-2024-8-4-15-12-5.md new file mode 100644 index 000000000..b288acc18 --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore index d2f4ee28a..2f1a8df12 100644 --- a/.gitignore +++ b/.gitignore @@ -198,7 +198,8 @@ obj/ *.vsix *.zip - +# Api extractor +packages/*/etc/ docs/**/js-api/ # csharp emitter diff --git a/api-extractor.base.json b/api-extractor.base.json new file mode 100644 index 000000000..35ca8d61a --- /dev/null +++ b/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": "/dist/src/index.d.ts", + "apiReport": { + "enabled": true, + "reportFolder": "/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 + } + } + } +} diff --git a/package.json b/package.json index 2cc1e0cd7..9efc889da 100644 --- a/package.json +++ b/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", diff --git a/packages/xml/api-extractor.json b/packages/xml/api-extractor.json new file mode 100644 index 000000000..2069b8ac3 --- /dev/null +++ b/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" +} diff --git a/packages/xml/package.json b/packages/xml/package.json index 3eaf0b060..68ac7d7a0 100644 --- a/packages/xml/package.json +++ b/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", diff --git a/packages/xml/src/decorators.ts b/packages/xml/src/decorators.ts index 081016170..7980a7fd8 100644 --- a/packages/xml/src/decorators.ts +++ b/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) { diff --git a/packages/xml/src/index.ts b/packages/xml/src/index.ts index 14f3728a5..b673a0a7f 100644 --- a/packages/xml/src/index.ts +++ b/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"; diff --git a/packages/xml/src/lib.ts b/packages/xml/src/lib.ts index d8381d7c1..6548d856a 100644 --- a/packages/xml/src/lib.ts +++ b/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: { diff --git a/packages/xml/src/types.ts b/packages/xml/src/types.ts index 93e027a24..2dfa563f5 100644 --- a/packages/xml/src/types.ts +++ b/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; } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 8df8197e4..25ae74ed3 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -20,6 +20,9 @@ importers: '@eslint/js': specifier: ^8.57.0 version: 8.57.0 + '@microsoft/api-extractor': + specifier: ^7.47.7 + version: 7.47.7(@types/node@18.11.19) '@octokit/core': specifier: ^6.1.2 version: 6.1.2 @@ -3667,6 +3670,7 @@ packages: '@humanwhocodes/config-array@0.11.14': resolution: {integrity: sha512-3T8LkOmg45BV5FICb15QQMsyUSWrQ8AygVfC7ZG32zOalnqrilm018ZVCw0eapXux8FtA33q8PSRSstjee3jSg==} engines: {node: '>=10.10.0'} + deprecated: Use @eslint/config-array instead '@humanwhocodes/module-importer@1.0.1': resolution: {integrity: sha512-bxveV4V8v5Yb4ncFTT3rPSgZBOpCkjfK0y4oVVVJwIuDVBRMDXrPyXRL988i5ap9m9bnyEEjWfm5WkBmtffLfA==} @@ -3678,6 +3682,7 @@ packages: '@humanwhocodes/object-schema@2.0.3': resolution: {integrity: sha512-93zYdMES/c1D69yZiKDBj0V24vqNzB/koF26KPaagAfd3P/4gUlh3Dys5ogAK+Exi9QyzlD8x/08Zt7wIKcDcA==} + deprecated: Use @eslint/object-schema instead '@isaacs/cliui@8.0.2': resolution: {integrity: sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA==} @@ -3746,10 +3751,17 @@ packages: '@microsoft/api-extractor-model@7.29.3': resolution: {integrity: sha512-kEWjLr2ygL3ku9EGyjeTnL2S5IxyH9NaF1k1UoI0Nzwr4xEJBSWCVsWuF2+0lPUrRPA6mTY95fR264SJ5ETKQA==} + '@microsoft/api-extractor-model@7.29.6': + resolution: {integrity: sha512-gC0KGtrZvxzf/Rt9oMYD2dHvtN/1KPEYsrQPyMKhLHnlVuO/f4AFN3E4toqZzD2pt4LhkKoYmL2H9tX3yCOyRw==} + '@microsoft/api-extractor@7.47.2': resolution: {integrity: sha512-YWE2HGrSTZaPPSr7xiNizSuViZpC7Jsa7+DwRW5rYVgrMXNbfX/PpBOoSkl5uaz9I2sv2JKLJ75kVNt64BvS3g==} hasBin: true + '@microsoft/api-extractor@7.47.7': + resolution: {integrity: sha512-fNiD3G55ZJGhPOBPMKD/enozj8yxJSYyVJWxRWdcUtw842rvthDHJgUWq9gXQTensFlMHv2wGuCjjivPv53j0A==} + hasBin: true + '@microsoft/tsdoc-config@0.17.0': resolution: {integrity: sha512-v/EYRXnCAIHxOHW+Plb6OWuUoMotxTN0GLatnpOb1xq0KuTNw/WI3pamJx/UbsoJP5k9MCw1QxvvhPcF9pH3Zg==} @@ -4285,9 +4297,20 @@ packages: '@types/node': optional: true + '@rushstack/node-core-library@5.7.0': + resolution: {integrity: sha512-Ff9Cz/YlWu9ce4dmqNBZpA45AEya04XaBFIjV7xTVeEf+y/kTjEasmozqFELXlNG4ROdevss75JrrZ5WgufDkQ==} + peerDependencies: + '@types/node': '*' + peerDependenciesMeta: + '@types/node': + optional: true + '@rushstack/rig-package@0.5.2': resolution: {integrity: sha512-mUDecIJeH3yYGZs2a48k+pbhM6JYwWlgjs2Ca5f2n1G2/kgdgP9D/07oglEGf6mRyXEnazhEENeYTSNDRCwdqA==} + '@rushstack/rig-package@0.5.3': + resolution: {integrity: sha512-olzSSjYrvCNxUFZowevC3uz8gvKr3WTpHQ7BkpjtRpA3wK+T0ybep/SRUMfr195gBzJm5gaXw0ZMgjIyHqJUow==} + '@rushstack/terminal@0.13.2': resolution: {integrity: sha512-t8i0PsGvBHmFBY8pryO3badqFlxQsm2rw3KYrzjcmVkG/WGklKg1qVkr9beAS1Oe8XWDRgj6SkoHkpNjs7aaNw==} peerDependencies: @@ -4296,9 +4319,20 @@ packages: '@types/node': optional: true + '@rushstack/terminal@0.14.0': + resolution: {integrity: sha512-juTKMAMpTIJKudeFkG5slD8Z/LHwNwGZLtU441l/u82XdTBfsP+LbGKJLCNwP5se+DMCT55GB8x9p6+C4UL7jw==} + peerDependencies: + '@types/node': '*' + peerDependenciesMeta: + '@types/node': + optional: true + '@rushstack/ts-command-line@4.22.2': resolution: {integrity: sha512-xkvrGd6D9dPlI3I401Thc640WNsEPB1sGEmy12a2VJaPQPwhE6Ik0gEVPZJ/2G1w213eaCAdxUY1xpiTulsmpA==} + '@rushstack/ts-command-line@4.22.6': + resolution: {integrity: sha512-QSRqHT/IfoC5nk9zn6+fgyqOPXHME0BfchII9EUPR19pocsNp/xSbeBCbD3PIR2Lg+Q5qk7OFqk1VhWPMdKHJg==} + '@shikijs/core@1.10.1': resolution: {integrity: sha512-qdiJS5a/QGCff7VUFIqd0hDdWly9rDp8lhVmXVrS11aazX8LOTRLHAXkkEeONNsS43EcCd7gax9LLoOz4vlFQA==} @@ -7709,6 +7743,7 @@ packages: inflight@1.0.6: resolution: {integrity: sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==} + deprecated: This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful. inherits@2.0.3: resolution: {integrity: sha512-x00IRNXNy63jwGkJmzPigoySHbaqpNuzKbBOmzK+g2OdZpQ9w+sxCN+VSB3ja7IAge2OP2qpfxTjeNcyjmW1uw==} @@ -10103,6 +10138,7 @@ packages: right-pad@1.0.1: resolution: {integrity: sha512-bYBjgxmkvTAfgIYy328fmkwhp39v8lwVgWhhrzxPV3yHtcSqyYKe9/XOhvW48UFjATg3VuJbpsp5822ACNvkmw==} engines: {node: '>= 0.10'} + deprecated: Please use String.prototype.padEnd() over this package. rimraf@2.6.3: resolution: {integrity: sha512-mwqeW5XsA2qAejG46gYdENaxXjx9onRNCfn7L0duuP4hCuTIi/QO7PDK07KJfp1d+izWPrzEJDcSqBa0OZQriA==} @@ -15068,6 +15104,14 @@ snapshots: transitivePeerDependencies: - '@types/node' + '@microsoft/api-extractor-model@7.29.6(@types/node@18.11.19)': + dependencies: + '@microsoft/tsdoc': 0.15.0 + '@microsoft/tsdoc-config': 0.17.0 + '@rushstack/node-core-library': 5.7.0(@types/node@18.11.19) + transitivePeerDependencies: + - '@types/node' + '@microsoft/api-extractor@7.47.2(@types/node@18.11.19)': dependencies: '@microsoft/api-extractor-model': 7.29.3(@types/node@18.11.19) @@ -15086,6 +15130,24 @@ snapshots: transitivePeerDependencies: - '@types/node' + '@microsoft/api-extractor@7.47.7(@types/node@18.11.19)': + dependencies: + '@microsoft/api-extractor-model': 7.29.6(@types/node@18.11.19) + '@microsoft/tsdoc': 0.15.0 + '@microsoft/tsdoc-config': 0.17.0 + '@rushstack/node-core-library': 5.7.0(@types/node@18.11.19) + '@rushstack/rig-package': 0.5.3 + '@rushstack/terminal': 0.14.0(@types/node@18.11.19) + '@rushstack/ts-command-line': 4.22.6(@types/node@18.11.19) + lodash: 4.17.21 + minimatch: 3.0.8 + resolve: 1.22.8 + semver: 7.5.4 + source-map: 0.6.1 + typescript: 5.4.2 + transitivePeerDependencies: + - '@types/node' + '@microsoft/tsdoc-config@0.17.0': dependencies: '@microsoft/tsdoc': 0.15.0 @@ -15757,11 +15819,29 @@ snapshots: optionalDependencies: '@types/node': 18.11.19 + '@rushstack/node-core-library@5.7.0(@types/node@18.11.19)': + dependencies: + ajv: 8.13.0 + ajv-draft-04: 1.0.0(ajv@8.13.0) + ajv-formats: 3.0.1(ajv@8.13.0) + fs-extra: 7.0.1 + import-lazy: 4.0.0 + jju: 1.4.0 + resolve: 1.22.8 + semver: 7.5.4 + optionalDependencies: + '@types/node': 18.11.19 + '@rushstack/rig-package@0.5.2': dependencies: resolve: 1.22.8 strip-json-comments: 3.1.1 + '@rushstack/rig-package@0.5.3': + dependencies: + resolve: 1.22.8 + strip-json-comments: 3.1.1 + '@rushstack/terminal@0.13.2(@types/node@18.11.19)': dependencies: '@rushstack/node-core-library': 5.5.0(@types/node@18.11.19) @@ -15769,6 +15849,13 @@ snapshots: optionalDependencies: '@types/node': 18.11.19 + '@rushstack/terminal@0.14.0(@types/node@18.11.19)': + dependencies: + '@rushstack/node-core-library': 5.7.0(@types/node@18.11.19) + supports-color: 8.1.1 + optionalDependencies: + '@types/node': 18.11.19 + '@rushstack/ts-command-line@4.22.2(@types/node@18.11.19)': dependencies: '@rushstack/terminal': 0.13.2(@types/node@18.11.19) @@ -15778,6 +15865,15 @@ snapshots: transitivePeerDependencies: - '@types/node' + '@rushstack/ts-command-line@4.22.6(@types/node@18.11.19)': + dependencies: + '@rushstack/terminal': 0.14.0(@types/node@18.11.19) + '@types/argparse': 1.0.38 + argparse: 1.0.10 + string-argv: 0.3.2 + transitivePeerDependencies: + - '@types/node' + '@shikijs/core@1.10.1': {} '@sideway/address@4.1.5':