@mark1russell7/api-report 0.5.2 → 0.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -132,7 +132,7 @@ A library with many exports can keep each name on a page that the report makes.
132
132
 
133
133
  - The command `update` writes the file. Do not edit it.
134
134
  - The command `check` fails when the file differs from the text that the report gives.
135
- - The file has a section for each entry, with an import of its names and their declarations. It has no comments, because the report has none.
135
+ - The file has a section for each entry, with an import of its names and their declarations. It has no comments, because the report has none. The field `docs` adds the doc comments.
136
136
  - The hand-written pages explain the main calls. The first rule above does not apply to them, because the file shows each export. The rules for imports and declarations still apply. The list `pages` can be empty.
137
137
 
138
138
  A site can need more fields in the front matter of the page, for example an `order` for its menu. The field `frontmatter` gives them. A field `title` or `description` replaces the default text.
@@ -154,6 +154,36 @@ A site can need more fields in the front matter of the page, for example an `ord
154
154
 
155
155
  Each value is a text, a number or a boolean. The field `frontmatter` needs the field `reference`.
156
156
 
157
+ The field `docs` puts the doc comment of each declaration above the declaration. The doc comments come from the built `.d.ts` files.
158
+
159
+ ```json
160
+ {
161
+ "apiReport": {
162
+ "pages": [
163
+ {
164
+ "package": "packages/lib",
165
+ "pages": [],
166
+ "reference": "packages/site/content/docs/each-export.md",
167
+ "docs": true
168
+ }
169
+ ]
170
+ }
171
+ }
172
+ ```
173
+
174
+ - The report does not change. A change of a doc comment changes only the page.
175
+ - The field `docs` needs the field `reference`. Without the field, the page has no doc comments.
176
+
177
+ ## The model of the API
178
+
179
+ The function `packageModel(folder)` gives the public API of a package as data. A site can render it in its own shell.
180
+
181
+ - `entries` has each entry point, with its subpath and its names.
182
+ - Each name has its exported name, its kind, a type-only flag and the key of its declaration.
183
+ - `declarations` has the text of each declaration by key, and the text of its doc comment.
184
+
185
+ The model has the same entries, names and declarations as the report. `apiModel(report, packageName, docs)` gives the model of the text of a report. The text of a report has no doc comments, so the argument `docs` gives them.
186
+
157
187
  ## Library
158
188
 
159
189
  The package also exports the functions of the tool:
@@ -165,4 +195,5 @@ The package also exports the functions of the tool:
165
195
  - `packageFolders(root, globs)`, `globFolders(root, glob)`, `globToRegExp(glob)` and `workspaceGlobs(root)` find the packages. They come from `@mark1russell7/conventions/workspace`.
166
196
  - `diffLines(before, after)` and `unifiedDiff(before, after)` give a line diff.
167
197
  - `pageFaults(report, packageName, pages, except, complete)` and `reportEntries(report)` hold a hand-written page against a report.
168
- - `referencePage(report, packageName, frontmatter)` gives the Markdown of the page of each export. The argument `frontmatter` is optional.
198
+ - `referencePage(model, frontmatter)` and `referencePage(report, packageName, frontmatter)` give the Markdown of the page of each export. The argument `frontmatter` is optional.
199
+ - `packageModel(folder)` and `apiModel(report, packageName, docs)` give the model of the API.
package/build/cli.js CHANGED
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- import { a as runCli } from "./run-Bw-iqwFC.js";
2
+ import { a as runCli } from "./run-DohS8GVx.js";
3
3
  // src/cli.ts
4
4
  try {
5
5
  process.exitCode = runCli(process.argv.slice(2), {
package/build/index.d.ts CHANGED
@@ -50,6 +50,8 @@ interface DeclarationInfo {
50
50
  readonly ambient: Map<string, string[]>;
51
51
  /** Each module specifier that the file names: the files that it reaches. */
52
52
  readonly references: Set<string>;
53
+ /** The text of the doc comment of each declaration of `locals`, by name. A declaration without a doc comment has no item. */
54
+ readonly docs: Map<string, string>;
53
55
  }
54
56
  /**
55
57
  * This function splits the text of a declaration file into its top-level statements. It removes the
@@ -150,6 +152,75 @@ export declare function targetOf(value: unknown): string | null | undefined;
150
152
  export declare function entriesOf(manifest: Manifest, root: string): Entry[];
151
153
  /** This function gives the commands of the `bin` field, in name order. A string `bin` has the name of the package without its scope. */
152
154
  export declare function binsOf(manifest: Manifest): Bin[];
155
+ /** The command that the header of a report names, when the options give no other command. */
156
+ export declare const DEFAULT_TOOL = "api-report";
157
+ /** The options of a report. */
158
+ interface ReportOptions {
159
+ /** The manifest of the package: the report reads its `imports` and `bin` fields. */
160
+ readonly manifest?: Manifest;
161
+ /** The command that the header names, for example `api-report` or `node scripts/api-report.mjs`. */
162
+ readonly tool?: string;
163
+ }
164
+ /** The number of lines of the header of a report. */
165
+ export declare const HEADER_LINES = 5;
166
+ /**
167
+ * This function gives the report of the public API of a package. `entries` gives the subpath and
168
+ * the declaration file of each entry, relative to `root`. The report has the exported names of each
169
+ * entry, the bins of the manifest, and then the declaration of each name.
170
+ */
171
+ export declare function apiReport(packageName: string, root: string, entries: readonly Entry[], options?: ReportOptions): string;
172
+ /** The options of the report of a package folder. */
173
+ interface PackageReportOptions {
174
+ /** The command that the header names. */
175
+ readonly tool?: string;
176
+ /** When true (the default), the fields of `publishConfig` replace the fields of the source, as pnpm publishes them. */
177
+ readonly publishConfig?: boolean;
178
+ }
179
+ /** This function gives the report of the package in the folder `dir`. */
180
+ export declare function packageReport(dir: string, options?: PackageReportOptions): string;
181
+ /** The kind of a name of an entry: a declaration, a namespace, a name of a different package or an ambient declaration. */
182
+ type ApiNameKind = "declaration" | "namespace" | "external" | "ambient";
183
+ /** One name of an entry of the model. */
184
+ interface ApiName {
185
+ /** The exported name. A member of a namespace has the name of the namespace first: `ns.name`. An ambient declaration has the name `ambient`. */
186
+ readonly name: string;
187
+ /** The key of the declaration of the name in `declarations`. For an external name, the key is the package and the name: `pkg#name`. */
188
+ readonly key: string;
189
+ /** True when the entry exports the name as a type only. */
190
+ readonly isType: boolean;
191
+ /** The kind of the name. */
192
+ readonly kind: ApiNameKind;
193
+ }
194
+ /** One entry point of the package: its subpath and its names. */
195
+ interface ApiEntry {
196
+ /** The subpath of the entry in the field `exports`: `.` or `./svg`. */
197
+ readonly subpath: string;
198
+ /** The names of the entry, in the order of the report. An entry without a declaration file has no names. */
199
+ readonly names: readonly ApiName[];
200
+ }
201
+ /** The declaration of one key, and the text of its doc comment. */
202
+ interface ApiDeclaration {
203
+ /** The text of the declaration, as the report gives it: without comments and private members. */
204
+ readonly text: string;
205
+ /** The text of the doc comment of the declaration, without the comment marks. A declaration without a doc comment has no doc. */
206
+ readonly doc?: string;
207
+ }
208
+ /** The model of the public API of one package. */
209
+ interface ApiModel {
210
+ /** The name of the package. */
211
+ readonly packageName: string;
212
+ /** The entry points of the package, in the order of the report. */
213
+ readonly entries: readonly ApiEntry[];
214
+ /** The declaration of each key of the names. Each key has the form `file#name`. */
215
+ readonly declarations: Readonly<Record<string, ApiDeclaration>>;
216
+ }
217
+ /**
218
+ * This function gives the model of a report. `docs` gives the text of the doc comment of each key. The
219
+ * report has no doc comments, so without `docs` the model has no doc comments.
220
+ */
221
+ export declare function apiModel(report: string, packageName: string, docs?: ReadonlyMap<string, string>): ApiModel;
222
+ /** This function gives the model of the package in the folder `dir`, with the doc comments of its built `.d.ts` files. */
223
+ export declare function packageModel(dir: string, options?: PackageReportOptions): ApiModel;
153
224
  /** The value of one field of the front matter of the page of each export. */
154
225
  type FrontmatterValue = string | number | boolean;
155
226
  /** One package and the pages that tell its API: an item of the field `pages` of `apiReport`. */
@@ -162,6 +233,8 @@ interface ApiPage {
162
233
  readonly reference?: string;
163
234
  /** The fields that the page of each export adds to its front matter, for example the `order` of a site. A field `title` or `description` replaces the default. */
164
235
  readonly frontmatter?: Readonly<Record<string, FrontmatterValue>>;
236
+ /** When true, the page of each export puts the doc comment of each declaration above it. The field needs `reference`. */
237
+ readonly docs?: boolean;
165
238
  /** The names that the check does not examine, each with its reason. */
166
239
  readonly except?: Readonly<Record<string, string>>;
167
240
  }
@@ -182,36 +255,15 @@ export declare function pageFaults(report: string, packageName: string, pages: r
182
255
  * export when the source gave the declaration a different name. A name from a bundler does not show. A
183
256
  * comment also tells the package of an external name.
184
257
  *
258
+ * The first argument is a model, or the text of a report with the name of its package. A model with doc
259
+ * comments puts the doc comment of each declaration above the declaration. The text of a report has no doc
260
+ * comments.
261
+ *
185
262
  * The fields of `frontmatter` go into the front matter, after the title and the description. A field `title` or
186
263
  * `description` replaces the default.
187
264
  */
265
+ export declare function referencePage(model: ApiModel, frontmatter?: Readonly<Record<string, FrontmatterValue>>): string;
188
266
  export declare function referencePage(report: string, packageName: string, frontmatter?: Readonly<Record<string, FrontmatterValue>>): string;
189
- /** The command that the header of a report names, when the options give no other command. */
190
- export declare const DEFAULT_TOOL = "api-report";
191
- /** The options of a report. */
192
- interface ReportOptions {
193
- /** The manifest of the package: the report reads its `imports` and `bin` fields. */
194
- readonly manifest?: Manifest;
195
- /** The command that the header names, for example `api-report` or `node scripts/api-report.mjs`. */
196
- readonly tool?: string;
197
- }
198
- /** The number of lines of the header of a report. */
199
- export declare const HEADER_LINES = 5;
200
- /**
201
- * This function gives the report of the public API of a package. `entries` gives the subpath and
202
- * the declaration file of each entry, relative to `root`. The report has the exported names of each
203
- * entry, the bins of the manifest, and then the declaration of each name.
204
- */
205
- export declare function apiReport(packageName: string, root: string, entries: readonly Entry[], options?: ReportOptions): string;
206
- /** The options of the report of a package folder. */
207
- interface PackageReportOptions {
208
- /** The command that the header names. */
209
- readonly tool?: string;
210
- /** When true (the default), the fields of `publishConfig` replace the fields of the source, as pnpm publishes them. */
211
- readonly publishConfig?: boolean;
212
- }
213
- /** This function gives the report of the package in the folder `dir`. */
214
- export declare function packageReport(dir: string, options?: PackageReportOptions): string;
215
267
  /** The path of the report in a package folder, when the configuration gives no other path. */
216
268
  export declare const REPORT_FILE = "test/api/public-api.txt";
217
269
  /** The configuration of the reports: the field `apiReport` of the root `package.json`, or the options of the CLI. */
@@ -296,5 +348,5 @@ interface CliIo {
296
348
  export declare const USAGE: string;
297
349
  /** This function starts the bin with the arguments `args`, and gives its exit code. */
298
350
  export declare function runCli(args: readonly string[], io: CliIo): number;
299
- export { type ApiPage, type ApiReportConfig, type Bin, type CliIo, type DeclarationInfo, type DiffLine, type Entry, type EntryFile, type FrontmatterValue, type ImportBinding, type LocalExport, type Manifest, type Mode, type PackageReportOptions, type PackageResult, type Reexport, type ReportOptions, type RunOptions, type RunResult, type UnifiedDiffOptions, globFolders, globToRegExp, packageFolders, reportFolders, workspaceGlobs };
351
+ export { type ApiDeclaration, type ApiEntry, type ApiModel, type ApiName, type ApiNameKind, type ApiPage, type ApiReportConfig, type Bin, type CliIo, type DeclarationInfo, type DiffLine, type Entry, type EntryFile, type FrontmatterValue, type ImportBinding, type LocalExport, type Manifest, type Mode, type PackageReportOptions, type PackageResult, type Reexport, type ReportOptions, type RunOptions, type RunResult, type UnifiedDiffOptions, globFolders, globToRegExp, packageFolders, reportFolders, workspaceGlobs };
300
352
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","names":[],"sources":["../src/declarations.ts","../src/diff.ts","../src/entries.ts","../src/page.ts","../src/reference.ts","../src/report.ts","../src/run.ts"],"mappings":";;;;;;;UAOiB;;WAEN;;WAEA;WACA;;;UAIM;;WAEN;WACA;;;UAIM;WACN;WACA;WACA;WACA;;;UAIM;;WAEN,QAAQ;;WAER,UAAU,YAAY;;WAEtB,WAAW;;WAEX;aAAkB;aAAuB;;;WAEzC;aAAuB;aAAuB;aAAuB;;;WAErE,SAAS,YAAY;;WAErB,SAAS;;WAET,YAAY;;;;;;wBAqCP,aAAa;;;;;wBAiJb,kBAAkB,gBAAgB,gBAAkB;;;UClOnD;WACN;WACA;;;wBAOK,UAAU,2BAA2B,2BAA2B;;UAoE/D;;WAEN;;WAEA;;WAEA;;;;;;wBAOK,YAAY,gBAAgB,eAAe,UAAS;;UCrFnD;WACN;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA,gBAAgB,SAAS;;;;UAKnB;;WAEN;;WAEA;;;UAIM;;WAEN;;WAEA;;WAEA;;WAEA,iBAAiB;;;UAIX;WACN;WACA;;;;;;qBAUE;;qBAGA,SAAU,WAAW;;wBAMlB,kBAAkB,UAAU,WAAW;;;;;wBAYvC,kBAAkB;;wBAQlB,aAAa,iBAAiB;;;;;;wBAc9B,SAAS;;;;;;;wBA0ET,UAAU,UAAU,UAAU,eAAe;;wBAkD7C,OAAO,UAAU,WAAW;;KCrNhC;;UAGK;;WAEN;;WAEA;;WAEA;;WAEA,cAAc,SAAS,eAAe;;WAEtC,SAAS,SAAS;;;wBAIb,cAAc,iBAAiB,oBAAoB;;;;;;;;;wBA0DnD,WAAW,gBAAgB,qBAAqB,0BAA0B,SAAQ,SAAS,yBAA8B;;;;;;;;;;wBCyCzH,cAAc,gBAAgB,qBAAqB,cAAa,SAAS,eAAe;;qBClG3F;;UAGI;;WAEN,WAAW;;WAEX;;;qBAsME;;;;;;wBAOG,UAAU,qBAAqB,cAAc,kBAAkB,SAAS,UAAS;;UAyEhF;;WAEN;;WAEA;;;wBAIK,cAAc,aAAa,UAAS;;qBCjTvC;;UAGI;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA,iBAAiB;;;KAIhB;;UAGK,mBAAmB;WACzB,MAAM;;WAEN;;WAEA;;;UAIM;;WAEN;;WAEA;;;;;;;WAOA;;WAEA;WACA;;WAEA;;WAEA;;;UAIM;WACN,MAAM;WACN,mBAAmB;;WAEnB;;;;;;;;wBASK,WAAW,eAAe;;;;;;;wBAkI1B,WAAW,SAAS,aAAa;;wBAiGjC,aAAa,QAAQ,WAAW;;wBA6BhC,gBAAgB,QAAQ;;UAavB;WACN;WACA,KAAK,SAAS;WACd,SAAS;WACT,SAAS;;;qBAIP;;wBAqBG,OAAO,yBAAyB,IAAI"}
1
+ {"version":3,"file":"index.d.ts","names":[],"sources":["../src/declarations.ts","../src/diff.ts","../src/entries.ts","../src/report.ts","../src/model.ts","../src/page.ts","../src/reference.ts","../src/run.ts"],"mappings":";;;;;;;UAOiB;;WAEN;;WAEA;WACA;;;UAIM;;WAEN;WACA;;;UAIM;WACN;WACA;WACA;WACA;;;UAIM;;WAEN,QAAQ;;WAER,UAAU,YAAY;;WAEtB,WAAW;;WAEX;aAAkB;aAAuB;;;WAEzC;aAAuB;aAAuB;aAAuB;;;WAErE,SAAS,YAAY;;WAErB,SAAS;;WAET,YAAY;;WAEZ,MAAM;;;;;;wBA+DD,aAAa;;;;;wBAkKb,kBAAkB,gBAAgB,gBAAkB;;;UC/QnD;WACN;WACA;;;wBAOK,UAAU,2BAA2B,2BAA2B;;UAoE/D;;WAEN;;WAEA;;WAEA;;;;;;wBAOK,YAAY,gBAAgB,eAAe,UAAS;;UCrFnD;WACN;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA,gBAAgB,SAAS;;;;UAKnB;;WAEN;;WAEA;;;UAIM;;WAEN;;WAEA;;WAEA;;WAEA,iBAAiB;;;UAIX;WACN;WACA;;;;;;qBAUE;;qBAGA,SAAU,WAAW;;wBAMlB,kBAAkB,UAAU,WAAW;;;;;wBAYvC,kBAAkB;;wBAQlB,aAAa,iBAAiB;;;;;;wBAc9B,SAAS;;;;;;;wBA0ET,UAAU,UAAU,UAAU,eAAe;;wBAkD7C,OAAO,UAAU,WAAW;;qBCnM/B;;UAGI;;WAEN,WAAW;;WAEX;;;qBAsME;;;;;;wBAOG,UAAU,qBAAqB,cAAc,kBAAkB,SAAS,UAAS;;UA4FhF;;WAEN;;WAEA;;;wBAIK,cAAc,aAAa,UAAS;;KC1UxC;;UAGK;;WAEN;;WAEA;;WAEA;;WAEA,MAAM;;;UAIA;;WAEN;;WAEA,gBAAgB;;;UAIV;;WAEN;;WAEA;;;UAIM;;WAEN;;WAEA,kBAAkB;;WAElB,cAAc,SAAS,eAAe;;;;;;wBAOjC,SAAS,gBAAgB,qBAAqB,OAAM,8BAA0C;;wBA8C9F,aAAa,aAAa,UAAS,uBAA4B;;KCzFnE;;UAGK;;WAEN;;WAEA;;WAEA;;WAEA,cAAc,SAAS,eAAe;;WAEtC;;WAEA,SAAS,SAAS;;;wBAIb,cAAc,iBAAiB,oBAAoB;;;;;;;;;wBAgDnD,WAAW,gBAAgB,qBAAqB,0BAA0B,SAAQ,SAAS,yBAA8B;;;;;;;;;;;;;;wBCGzH,cAAc,OAAO,UAAU,cAAc,SAAS,eAAe;wBACrE,cAAc,gBAAgB,qBAAqB,cAAc,SAAS,eAAe;;qBCjE5F;;UAGI;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA,iBAAiB;;;KAIhB;;UAGK,mBAAmB;WACzB,MAAM;;WAEN;;WAEA;;;UAIM;;WAEN;;WAEA;;;;;;;WAOA;;WAEA;WACA;;WAEA;;WAEA;;;UAIM;WACN,MAAM;WACN,mBAAmB;;WAEnB;;;;;;;;wBASK,WAAW,eAAe;;;;;;;wBA0I1B,WAAW,SAAS,aAAa;;wBAkGjC,aAAa,QAAQ,WAAW;;wBA6BhC,gBAAgB,QAAQ;;UAavB;WACN;WACA,KAAK,SAAS;WACd,SAAS;WACT,SAAS;;;qBAIP;;wBAqBG,OAAO,yBAAyB,IAAI"}
package/build/index.js CHANGED
@@ -1,3 +1,3 @@
1
- import { C as diffLines, E as statementsOf, S as targetOf, T as parseDeclarations, _ as byCode, a as runCli, b as patternMatch, c as DEFAULT_TOOL, d as packageReport, f as referencePage, g as binsOf, h as PUBLISH_CONFIG_FIELDS, i as readConfig, l as HEADER_LINES, m as reportEntries, n as USAGE, o as runReports, p as pageFaults, r as formatResult, s as summaryMarkdown, t as REPORT_FILE, u as apiReport, v as declarationPathOf, w as unifiedDiff, x as publishedManifest, y as entriesOf } from "./run-Bw-iqwFC.js";
1
+ import { C as publishedManifest, D as parseDeclarations, E as unifiedDiff, O as statementsOf, S as patternMatch, T as diffLines, _ as PUBLISH_CONFIG_FIELDS, a as runCli, b as declarationPathOf, c as referencePage, d as apiModel, f as packageModel, g as packageReport, h as apiReport, i as readConfig, l as pageFaults, m as HEADER_LINES, n as USAGE, o as runReports, p as DEFAULT_TOOL, r as formatResult, s as summaryMarkdown, t as REPORT_FILE, u as reportEntries, v as binsOf, w as targetOf, x as entriesOf, y as byCode } from "./run-DohS8GVx.js";
2
2
  import { globFolders, globToRegExp, packageFolders, reportFolders, workspaceGlobs } from "@mark1russell7/conventions/workspace";
3
- export { DEFAULT_TOOL, HEADER_LINES, PUBLISH_CONFIG_FIELDS, REPORT_FILE, USAGE, apiReport, binsOf, byCode, declarationPathOf, diffLines, entriesOf, formatResult, globFolders, globToRegExp, packageFolders, packageReport, pageFaults, parseDeclarations, patternMatch, publishedManifest, readConfig, referencePage, reportEntries, reportFolders, runCli, runReports, statementsOf, summaryMarkdown, targetOf, unifiedDiff, workspaceGlobs };
3
+ export { DEFAULT_TOOL, HEADER_LINES, PUBLISH_CONFIG_FIELDS, REPORT_FILE, USAGE, apiModel, apiReport, binsOf, byCode, declarationPathOf, diffLines, entriesOf, formatResult, globFolders, globToRegExp, packageFolders, packageModel, packageReport, pageFaults, parseDeclarations, patternMatch, publishedManifest, readConfig, referencePage, reportEntries, reportFolders, runCli, runReports, statementsOf, summaryMarkdown, targetOf, unifiedDiff, workspaceGlobs };