@microsoft/api-extractor - npm Package Compare versions

Comparing version 7.47.2 to 7.47.3

dist/rollup.d.ts

@@ -709,17 +709,16 @@ /**
     /**
-     * The base component of API report filenames.
+     * The base filename for the API report files, to be combined with {@link IConfigApiReport.reportFolder} or
+     * {@link IConfigApiReport.reportTempFolder} to produce the full file path.
      *
      * @remarks
-     * It will be combined with the specified {@link IConfigApiReport.reportVariants}, and {@link IConfigApiReport.reportFolder} and {@link IConfigApiReport.reportTempFolder} to
-     * produce a full output filenames in the form `<folder><reportFileName>.<variant>.api.md`.
+     * The `reportFileName` should not include any path separators such as `\` or `/`.  The `reportFileName` should
+     * not include a file extension, since API Extractor will automatically append an appropriate file extension such
+     * as `.api.md`.  If the {@link IConfigApiReport.reportVariants} setting is used, then the file extension includes
+     * the variant name, for example `my-report.public.api.md` or `my-report.beta.api.md`. The `complete` variant always
+     * uses the simple extension `my-report.api.md`.
      *
-     * The string should not contain a file extension.
-     * Note: previous guidance noted that this should be specified in a form including the `.api.md` extension.
-     * This is no longer recommended, and support for this will be removed in a future release.
-     * For example, if you were previously specifying `Foo.api.md`, you should now specify `Foo`.
-     * The `.api.md` extension will be added automatically to the resulting filename.
+     * Previous versions of API Extractor required `reportFileName` to include the `.api.md` extension explicitly;
+     * for backwards compatibility, that is still accepted but will be discarded before applying the above rules.
      *
-     * The string must not contain a path separator such as `\` or `/`.
-     *
-     * @defaultValue `<unscopedPackageName>.api.md` will be used if this argument is not specified or if it is empty.
+     * @defaultValue `<unscopedPackageName>`
      */
@@ -731,12 +730,11 @@ reportFileName?: string;
      * @remarks
-     * Each variant corresponds to a minimal release level, denoted by release tag in the TSDoc comment for each API item.
-     * E.g., the `beta` report variant will include all API items tagged `@beta` or higher (i.e. `@beta` and `@public`).
+     * To support different approval requirements for different API levels, multiple "variants" of the API report can
+     * be generated.  The `reportVariants` setting specifies a list of variants to be generated.  If omitted,
+     * by default only the `complete` variant will be generated, which includes all `@internal`, `@alpha`, `@beta`,
+     * and `@public` items.  Other possible variants are `alpha` (`@alpha` + `@beta` + `@public`),
+     * `beta` (`@beta` + `@public`), and `public` (`@public only`).
      *
      * The resulting API report file names will be derived from the {@link IConfigApiReport.reportFileName}.
-     * E.g., `foo.beta.api.md`.
-     * The only exception to this is the `complete` variant.
-     * This variant name will not be contained in the corresponding file name.
-     * I.e., `foo.api.md`.
      *
-     * @defaultValue `['complete']`
+     * @defaultValue `[ "complete" ]`
      */
@@ -743,0 +741,0 @@ reportVariants?: ApiReportVariant[];

lib/api/ExtractorConfig.js

@@ -497,4 +497,3 @@ "use strict";
                     }
-                    const suffixIndex = apiReportConfig.reportFileName.indexOf(reportFileNameSuffix);
-                    if (suffixIndex < 0) {
+                    if (!apiReportConfig.reportFileName.endsWith(reportFileNameSuffix)) {
                         // `.api.md` extension was not specified. Use provided file name base as is.
@@ -509,3 +508,3 @@ reportFileNameBase = apiReportConfig.reportFileName;
                         // migrate their configs.
-                        reportFileNameBase = apiReportConfig.reportFileName.slice(0, suffixIndex);
+                        reportFileNameBase = apiReportConfig.reportFileName.slice(0, -reportFileNameSuffix.length);
                     }
@@ -512,0 +511,0 @@ }

lib/api/IConfigFile.d.ts

@@ -64,17 +64,16 @@ import type { EnumMemberOrder } from '@microsoft/api-extractor-model';
     /**
-     * The base component of API report filenames.
+     * The base filename for the API report files, to be combined with {@link IConfigApiReport.reportFolder} or
+     * {@link IConfigApiReport.reportTempFolder} to produce the full file path.
      *
      * @remarks
-     * It will be combined with the specified {@link IConfigApiReport.reportVariants}, and {@link IConfigApiReport.reportFolder} and {@link IConfigApiReport.reportTempFolder} to
-     * produce a full output filenames in the form `<folder><reportFileName>.<variant>.api.md`.
+     * The `reportFileName` should not include any path separators such as `\` or `/`.  The `reportFileName` should
+     * not include a file extension, since API Extractor will automatically append an appropriate file extension such
+     * as `.api.md`.  If the {@link IConfigApiReport.reportVariants} setting is used, then the file extension includes
+     * the variant name, for example `my-report.public.api.md` or `my-report.beta.api.md`. The `complete` variant always
+     * uses the simple extension `my-report.api.md`.
      *
-     * The string should not contain a file extension.
-     * Note: previous guidance noted that this should be specified in a form including the `.api.md` extension.
-     * This is no longer recommended, and support for this will be removed in a future release.
-     * For example, if you were previously specifying `Foo.api.md`, you should now specify `Foo`.
-     * The `.api.md` extension will be added automatically to the resulting filename.
+     * Previous versions of API Extractor required `reportFileName` to include the `.api.md` extension explicitly;
+     * for backwards compatibility, that is still accepted but will be discarded before applying the above rules.
      *
-     * The string must not contain a path separator such as `\` or `/`.
-     *
-     * @defaultValue `<unscopedPackageName>.api.md` will be used if this argument is not specified or if it is empty.
+     * @defaultValue `<unscopedPackageName>`
      */
@@ -86,12 +85,11 @@ reportFileName?: string;
      * @remarks
-     * Each variant corresponds to a minimal release level, denoted by release tag in the TSDoc comment for each API item.
-     * E.g., the `beta` report variant will include all API items tagged `@beta` or higher (i.e. `@beta` and `@public`).
+     * To support different approval requirements for different API levels, multiple "variants" of the API report can
+     * be generated.  The `reportVariants` setting specifies a list of variants to be generated.  If omitted,
+     * by default only the `complete` variant will be generated, which includes all `@internal`, `@alpha`, `@beta`,
+     * and `@public` items.  Other possible variants are `alpha` (`@alpha` + `@beta` + `@public`),
+     * `beta` (`@beta` + `@public`), and `public` (`@public only`).
      *
      * The resulting API report file names will be derived from the {@link IConfigApiReport.reportFileName}.
-     * E.g., `foo.beta.api.md`.
-     * The only exception to this is the `complete` variant.
-     * This variant name will not be contained in the corresponding file name.
-     * I.e., `foo.api.md`.
      *
-     * @defaultValue `['complete']`
+     * @defaultValue `[ "complete" ]`
      */
@@ -98,0 +96,0 @@ reportVariants?: ApiReportVariant[];

lib/schemas/api-extractor-template.json

@@ -82,10 +82,2 @@ /**
   /**
-   * Set to true when invoking API Extractor's test harness. When `testMode` is true, the `toolVersion` field in the
-   * .api.json file is assigned an empty string to prevent spurious diffs in output files tracked for tests.
-   *
-   * DEFAULT VALUE: "false"
-   */
-  // "testMode": false,
-
-  /**
    * Specifies how API Extractor sorts members of an enum when generating the .api.json file. By default, the output
@@ -100,2 +92,10 @@ * files will be sorted alphabetically, which is "by-name". To keep the ordering in the source code, specify
   /**
+   * Set to true when invoking API Extractor's test harness. When `testMode` is true, the `toolVersion` field in the
+   * .api.json file is assigned an empty string to prevent spurious diffs in output files tracked for tests.
+   *
+   * DEFAULT VALUE: "false"
+   */
+  // "testMode": false,
+
+  /**
    * Determines how the TypeScript compiler engine will be invoked by API Extractor.
@@ -150,13 +150,29 @@ */
     /**
-     * The filename for the API report files.  It will be combined with "reportFolder" or "reportTempFolder" to produce
-     * a full file path.
+     * The base filename for the API report files, to be combined with "reportFolder" or "reportTempFolder"
+     * to produce the full file path.  The "reportFileName" should not include any path separators such as
+     * "\" or "/".  The "reportFileName" should not include a file extension, since API Extractor will automatically
+     * append an appropriate file extension such as ".api.md".  If the "reportVariants" setting is used, then the
+     * file extension includes the variant name, for example "my-report.public.api.md" or "my-report.beta.api.md".
+     * The "complete" variant always uses the simple extension "my-report.api.md".
      *
-     * The file extension should be ".api.md", and the string should not contain a path separator such as "\" or "/".
+     * Previous versions of API Extractor required "reportFileName" to include the ".api.md" extension explicitly;
+     * for backwards compatibility, that is still accepted but will be discarded before applying the above rules.
      *
      * SUPPORTED TOKENS: <packageName>, <unscopedPackageName>
-     * DEFAULT VALUE: "<unscopedPackageName>.api.md"
+     * DEFAULT VALUE: "<unscopedPackageName>"
      */
-    // "reportFileName": "<unscopedPackageName>.api.md",
+    // "reportFileName": "<unscopedPackageName>",
 
     /**
+     * To support different approval requirements for different API levels, multiple "variants" of the API report can
+     * be generated.  The "reportVariants" setting specifies a list of variants to be generated.  If omitted,
+     * by default only the "complete" variant will be generated, which includes all @internal, @alpha, @beta,
+     * and @public items.  Other possible variants are "alpha" (@alpha + @beta + @public), "beta" (@beta + @public),
+     * and "public" (@public only).
+     *
+     * DEFAULT VALUE: [ "complete" ]
+     */
+    // "reportVariants": ["public", "beta"],
+
+    /**
      * Specifies the folder where the API report file is written.  The file name portion is determined by
@@ -172,5 +188,5 @@ * the "reportFileName" setting.
      * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
-     * DEFAULT VALUE: "<projectFolder>/temp/"
+     * DEFAULT VALUE: "<projectFolder>/etc/"
      */
-    // "reportFolder": "<projectFolder>/temp/",
+    // "reportFolder": "<projectFolder>/etc/",
 
@@ -240,3 +256,3 @@ /**
      *
-     * Can be omitted if you don't need source code links in your API documentation reference.
+     * This setting can be omitted if you don't need source code links in your API documentation reference.
      *
@@ -276,2 +292,4 @@ * SUPPORTED TOKENS: none
      *
+     * If the path is an empty string, then this file will not be written.
+     *
      * The path is resolved relative to the folder of the config file that contains the setting; to change this,
@@ -289,2 +307,4 @@ * prepend a folder token such as "<projectFolder>".
      *
+     * If the path is an empty string, then this file will not be written.
+     *
      * The path is resolved relative to the folder of the config file that contains the setting; to change this,
@@ -291,0 +311,0 @@ * prepend a folder token such as "<projectFolder>".

lib/schemas/api-extractor.schema.json

@@ -34,2 +34,9 @@ {
 
+    "newlineKind": {
+      "description": "Specifies what type of newlines API Extractor should use when writing output files.  By default, the output files will be written with Windows-style newlines.  To use POSIX-style newlines, specify \"lf\" instead. To use the OS's default newline kind, specify \"os\".",
+      "type": "string",
+      "enum": ["crlf", "lf", "os"],
+      "default": "crlf"
+    },
+
     "enumMemberOrder": {
@@ -42,2 +49,7 @@ "description": "Specifies how API Extractor sorts the members of an enum when generating the .api.json doc model. \n 'by-name': sort the items according to the enum member name \n 'preserve': keep the original order that items appear in the source code",
 
+    "testMode": {
+      "description": "Set to true invoking API Extractor's test harness. When \"testMode\" is true, the \"toolVersion\" field in the .api.json file is assigned an empty string to prevent spurious diffs in output files tracked for tests.",
+      "type": "boolean"
+    },
+
     "compiler": {
@@ -73,3 +85,3 @@ "description": "Determines how the TypeScript compiler engine will be invoked by API Extractor.",
         "reportFileName": {
-          "description": "The base filename for the API report files.  It will be combined with \"reportFolder\" or \"reportTempFolder\" to produce a full file path.  It should not contain a file extension, nor a path separator such as \"\\\" or \"/\".  The resulting file with have the extension \"api.md\".  The \"complete\" report variant uses this base filename directly; other variants insert a name such as \"my-report.alpha.api.md\" or \"my-report.beta.api.md\" for alpha and beta variants.",
+          "description": "The base filename for the API report files, to be combined with \"reportFolder\" or \"reportTempFolder\" to produce the full file path.  The \"reportFileName\" should not include any path separators such as \"\\\" or \"/\".  The \"reportFileName\" should not include a file extension, since API Extractor will automatically append an appropriate file extension such as \".api.md\".  If the \"reportVariants\" setting is used, then the file extension includes the variant name, for example \"my-report.public.api.md\" or \"my-report.beta.api.md\".  The \"complete\" variant always uses the simple extension \"my-report.api.md\".\n\nPrevious versions of API Extractor required \"reportFileName\" to include the \".api.md\" extension explicitly; for backwards compatibility, that is still accepted but will be discarded before applying the above rules.",
           "type": ["string"]
@@ -79,3 +91,3 @@ },
         "reportVariants": {
-          "description": "To support different approval requirements for different API levels, multiple variants of the API report can be generated.  The \"reportVariants\" setting specifies a list of variants to be generated.  If omitted, by default only the \"complete\" variant will be generated, which includes all @alpha, @beta, and @public items. Other possible variants are \"alpha\" (@alpha + @beta + @public), \"beta\" (@beta + @public), and \"public\" (@public only). If you are leveraging API-Extractor's trimmed roll-ups feature, these reports will match the contents of each corresponding roll-up.",
+          "description": "To support different approval requirements for different API levels, multiple \"variants\" of the API report can be generated.  The \"reportVariants\" setting specifies a list of variants to be generated.  If omitted, by default only the \"complete\" variant will be generated, which includes all @internal, @alpha, @beta, and @public items.  Other possible variants are \"alpha\" (@alpha + @beta + @public), \"beta\" (@beta + @public), and \"public\" (@public only).",
           "type": "array",
@@ -181,9 +193,2 @@ "items": {
 
-    "newlineKind": {
-      "description": "Specifies what type of newlines API Extractor should use when writing output files.  By default, the output files will be written with Windows-style newlines.  To use POSIX-style newlines, specify \"lf\" instead. To use the OS's default newline kind, specify \"os\".",
-      "type": "string",
-      "enum": ["crlf", "lf", "os"],
-      "default": "crlf"
-    },
-
     "messages": {
@@ -207,7 +212,2 @@ "description": "Configures how API Extractor reports error and warning messages produced during analysis.",
       "additionalProperties": false
-    },
-
-    "testMode": {
-      "description": "Set to true invoking API Extractor's test harness. When \"testMode\" is true, the \"toolVersion\" field in the .api.json file is assigned an empty string to prevent spurious diffs in output files tracked for tests.",
-      "type": "boolean"
     }
@@ -214,0 +214,0 @@ },

package.json

 {
   "name": "@microsoft/api-extractor",
-  "version": "7.47.2",
+  "version": "7.47.3",
   "description": "Analyze the exported API for a TypeScript library and generate reviews, documentation, and .d.ts rollups",
@@ -43,7 +43,7 @@ "keywords": [
     "typescript": "5.4.2",
-    "@microsoft/api-extractor-model": "7.29.3",
     "@rushstack/node-core-library": "5.5.0",
     "@rushstack/rig-package": "0.5.2",
-    "@rushstack/ts-command-line": "4.22.2",
-    "@rushstack/terminal": "0.13.2"
+    "@microsoft/api-extractor-model": "7.29.3",
+    "@rushstack/terminal": "0.13.2",
+    "@rushstack/ts-command-line": "4.22.2"
   },
@@ -50,0 +50,0 @@ "devDependencies": {

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

1660856

increased by0.11%

Lines of code

16470

increased by0.09%

No dependency changes