Skip to content

Commit e835518

Browse files
JosmithrJosmithr
authored
build: Update API-Extractor report configurations to include @legacy and @system in API reports (#24439)
Both `@legacy` and `@system` have breaking change implications, so including them in our API reports will offer useful context in code reviews.
1 parent 7c01374 commit e835518

File tree

60 files changed

+1264
-1235
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

60 files changed

+1264
-1235
lines changed

‎azure/packages/azure-service-utils/api-report/azure-service-utils.legacy.alpha.api.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
55
```ts
66

7-
// @alpha
7+
// @alpha @legacy
88
export function generateToken(tenantId: string, key: string, scopes: ScopeType[], documentId?: string, user?: IUser, lifetime?: number, ver?: string): string;
99

1010
export { IUser }

‎common/build/build-common/api-extractor-base.json

+8-1
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,14 @@
2121
"reportFileName": "<unscopedPackageName>",
2222
"reportFolder": "<projectFolder>/api-report/",
2323
"reportTempFolder": "<projectFolder>/_api-extractor-temp/",
24-
"reportVariants": ["public", "beta", "alpha"] // TODO: add "complete"?
24+
"reportVariants": ["public", "beta", "alpha"], // TODO: add "complete"?
25+
26+
// Add `@legacy` and `@system` to the list of tags included in API reports.
27+
// These tags have breaking change implications, so they provide useful context during code reviews.
28+
"tagsToReport": {
29+
"@legacy": true,
30+
"@system": true
31+
}
2532
},
2633

2734
/**

‎experimental/dds/tree/api-report/experimental-tree.alpha.api.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -689,7 +689,7 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
689689
// @alpha
690690
export type SharedTreeArgs<WF extends WriteFormat = WriteFormat> = [writeFormat: WF, options?: SharedTreeOptions<WF>];
691691

692-
// @alpha
692+
// @alpha @legacy
693693
export const SharedTreeAttributes: IChannelAttributes;
694694

695695
// @alpha
@@ -715,7 +715,7 @@ export class SharedTreeFactory implements IChannelFactory {
715715
get type(): string;
716716
}
717717

718-
// @alpha
718+
// @alpha @legacy
719719
export const SharedTreeFactoryType = "SharedTree";
720720

721721
// @alpha

‎packages/common/client-utils/api-report/client-utils.legacy.alpha.api.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,10 @@
66

77
export { EventEmitter }
88

9-
// @alpha
9+
// @alpha @legacy
1010
export type EventEmitterEventType = string;
1111

12-
// @alpha
12+
// @alpha @legacy
1313
export class TypedEventEmitter<TEvent> extends EventEmitter implements IEventProvider<TEvent & IEvent> {
1414
constructor();
1515
// (undocumented)
@@ -28,7 +28,7 @@ export class TypedEventEmitter<TEvent> extends EventEmitter implements IEventPro
2828
readonly removeListener: TypedEventTransform<this, TEvent>;
2929
}
3030

31-
// @alpha (undocumented)
31+
// @alpha @legacy (undocumented)
3232
export type TypedEventTransform<TThis, TEvent> = TransformedEvent<TThis, "newListener" | "removeListener", Parameters<(event: string, listener: (...args: any[]) => void) => void>> & IEventTransformer<TThis, TEvent & IEvent> & TransformedEvent<TThis, EventEmitterEventType, any[]>;
3333

3434
// (No @packageDocumentation comment for this package)

‎packages/common/container-definitions/api-report/container-definitions.legacy.alpha.api.md

+42-42
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ export namespace ConnectionState {
2222
// @public
2323
export type ConnectionState = ConnectionState.Disconnected | ConnectionState.EstablishingConnection | ConnectionState.CatchingUp | ConnectionState.Connected;
2424

25-
// @alpha
25+
// @alpha @legacy
2626
export const ContainerErrorTypes: {
2727
readonly clientSessionExpiredError: "clientSessionExpiredError";
2828
readonly genericError: "genericError";
@@ -32,10 +32,10 @@ export const ContainerErrorTypes: {
3232
readonly usageError: "usageError";
3333
};
3434

35-
// @alpha
35+
// @alpha @legacy
3636
export type ContainerErrorTypes = (typeof ContainerErrorTypes)[keyof typeof ContainerErrorTypes];
3737

38-
// @alpha
38+
// @alpha @legacy
3939
export interface ContainerWarning extends IErrorBase_2 {
4040
logged?: boolean;
4141
}
@@ -56,14 +56,14 @@ export interface IAudienceEvents extends IEvent {
5656
(event: "selfChanged", listener: (oldValue: ISelf | undefined, newValue: ISelf) => void): void;
5757
}
5858

59-
// @alpha
59+
// @alpha @legacy
6060
export interface IAudienceOwner extends IAudience {
6161
addMember(clientId: string, details: IClient): void;
6262
removeMember(clientId: string): boolean;
6363
setCurrentClientId(clientId: string): void;
6464
}
6565

66-
// @alpha
66+
// @alpha @legacy
6767
export interface IBatchMessage {
6868
// (undocumented)
6969
compression?: string;
@@ -75,12 +75,12 @@ export interface IBatchMessage {
7575
referenceSequenceNumber?: number;
7676
}
7777

78-
// @alpha
78+
// @alpha @legacy
7979
export interface ICodeDetailsLoader extends Partial<IProvideFluidCodeDetailsComparer> {
8080
load(source: IFluidCodeDetails): Promise<IFluidModuleWithDetails>;
8181
}
8282

83-
// @alpha
83+
// @alpha @legacy
8484
export interface IConnectionDetails {
8585
checkpointSequenceNumber: number | undefined;
8686
// (undocumented)
@@ -90,7 +90,7 @@ export interface IConnectionDetails {
9090
serviceConfiguration: IClientConfiguration;
9191
}
9292

93-
// @alpha
93+
// @alpha @legacy
9494
export interface IContainer extends IEventProvider<IContainerEvents> {
9595
attach(request: IRequest, attachProps?: {
9696
deltaConnection?: "none" | "delayed";
@@ -122,7 +122,7 @@ export interface IContainer extends IEventProvider<IContainerEvents> {
122122
serialize(): string;
123123
}
124124

125-
// @alpha
125+
// @alpha @legacy
126126
export interface IContainerContext {
127127
readonly attachState: AttachState;
128128
// (undocumented)
@@ -173,7 +173,7 @@ export interface IContainerContext {
173173
updateDirtyContainerState(dirty: boolean): void;
174174
}
175175

176-
// @alpha
176+
// @alpha @legacy
177177
export interface IContainerEvents extends IEvent {
178178
(event: "readonly", listener: (readonly: boolean) => void): void;
179179
(event: "connected", listener: (clientId: string) => void): any;
@@ -190,23 +190,23 @@ export interface IContainerEvents extends IEvent {
190190
(event: "metadataUpdate", listener: (metadata: Record<string, string>) => void): any;
191191
}
192192

193-
// @alpha (undocumented)
193+
// @alpha @legacy (undocumented)
194194
export interface IContainerLoadMode {
195195
// (undocumented)
196196
deltaConnection?: "none" | "delayed" | undefined;
197197
// (undocumented)
198198
opsBeforeReturn?: undefined | "cached" | "all";
199199
}
200200

201-
// @alpha
201+
// @alpha @legacy
202202
export type IContainerPolicies = {
203203
maxClientLeaveWaitTime?: number;
204204
};
205205

206206
// @public
207207
export type ICriticalContainerError = IErrorBase_2;
208208

209-
// @alpha @sealed
209+
// @alpha @sealed @legacy
210210
export interface IDeltaManager<T, U> extends IEventProvider<IDeltaManagerEvents>, IDeltaSender {
211211
readonly active: boolean;
212212
readonly clientDetails: IClientDetails;
@@ -225,7 +225,7 @@ export interface IDeltaManager<T, U> extends IEventProvider<IDeltaManagerEvents>
225225
readonly version: string;
226226
}
227227

228-
// @alpha @sealed
228+
// @alpha @sealed @legacy
229229
export interface IDeltaManagerEvents extends IEvent {
230230
// @deprecated (undocumented)
231231
(event: "prepareSend", listener: (messageBuffer: any[]) => void): any;
@@ -241,7 +241,7 @@ export interface IDeltaManagerEvents extends IEvent {
241241
}) => void): any;
242242
}
243243

244-
// @alpha @sealed
244+
// @alpha @sealed @legacy
245245
export interface IDeltaQueue<T> extends IEventProvider<IDeltaQueueEvents<T>>, IDisposable {
246246
idle: boolean;
247247
length: number;
@@ -256,70 +256,70 @@ export interface IDeltaQueue<T> extends IEventProvider<IDeltaQueueEvents<T>>, ID
256256
}>;
257257
}
258258

259-
// @alpha @sealed
259+
// @alpha @sealed @legacy
260260
export interface IDeltaQueueEvents<T> extends IErrorEvent {
261261
(event: "push", listener: (task: T) => void): any;
262262
(event: "op", listener: (task: T) => void): any;
263263
(event: "idle", listener: (count: number, duration: number) => void): any;
264264
}
265265

266-
// @alpha @sealed
266+
// @alpha @sealed @legacy
267267
export interface IDeltaSender {
268268
flush(): void;
269269
}
270270

271271
export { IErrorBase }
272272

273-
// @alpha
273+
// @alpha @legacy
274274
export interface IFluidBrowserPackage extends IFluidPackage {
275275
fluid: {
276276
browser: IFluidBrowserPackageEnvironment;
277277
[environment: string]: IFluidPackageEnvironment;
278278
};
279279
}
280280

281-
// @alpha
281+
// @alpha @legacy
282282
export interface IFluidBrowserPackageEnvironment extends IFluidPackageEnvironment {
283283
umd: {
284284
files: string[];
285285
library: string;
286286
};
287287
}
288288

289-
// @alpha
289+
// @alpha @legacy
290290
export interface IFluidCodeDetails {
291291
readonly config?: IFluidCodeDetailsConfig;
292292
readonly package: string | Readonly<IFluidPackage>;
293293
}
294294

295-
// @alpha (undocumented)
295+
// @alpha @legacy (undocumented)
296296
export const IFluidCodeDetailsComparer: keyof IProvideFluidCodeDetailsComparer;
297297

298-
// @alpha
298+
// @alpha @legacy
299299
export interface IFluidCodeDetailsComparer extends IProvideFluidCodeDetailsComparer {
300300
compare(a: IFluidCodeDetails, b: IFluidCodeDetails): Promise<number | undefined>;
301301
satisfies(candidate: IFluidCodeDetails, constraint: IFluidCodeDetails): Promise<boolean>;
302302
}
303303

304-
// @alpha
304+
// @alpha @legacy
305305
export interface IFluidCodeDetailsConfig {
306306
// (undocumented)
307307
readonly [key: string]: string;
308308
}
309309

310-
// @alpha (undocumented)
310+
// @alpha @legacy (undocumented)
311311
export interface IFluidModule {
312312
// (undocumented)
313313
fluidExport: FluidObject<IRuntimeFactory & IProvideFluidCodeDetailsComparer>;
314314
}
315315

316-
// @alpha
316+
// @alpha @legacy
317317
export interface IFluidModuleWithDetails {
318318
details: IFluidCodeDetails;
319319
module: IFluidModule;
320320
}
321321

322-
// @alpha
322+
// @alpha @legacy
323323
export interface IFluidPackage {
324324
[key: string]: unknown;
325325
fluid: {
@@ -328,23 +328,23 @@ export interface IFluidPackage {
328328
name: string;
329329
}
330330

331-
// @alpha
331+
// @alpha @legacy
332332
export interface IFluidPackageEnvironment {
333333
[target: string]: undefined | {
334334
files: string[];
335335
[key: string]: unknown;
336336
};
337337
}
338338

339-
// @alpha
339+
// @alpha @legacy
340340
export interface IGetPendingLocalStateProps {
341341
readonly notifyImminentClosure: boolean;
342342
readonly sessionExpiryTimerStarted?: number;
343343
readonly snapshotSequenceNumber?: number;
344344
readonly stopBlobAttachingSignal?: AbortSignal;
345345
}
346346

347-
// @alpha
347+
// @alpha @legacy
348348
export interface IHostLoader extends ILoader {
349349
createDetachedContainer(codeDetails: IFluidCodeDetails, createDetachedProps?: {
350350
canReconnect?: boolean;
@@ -356,12 +356,12 @@ export interface IHostLoader extends ILoader {
356356
}): Promise<IContainer>;
357357
}
358358

359-
// @alpha
359+
// @alpha @legacy
360360
export interface ILoader extends Partial<IProvideLoader> {
361361
resolve(request: IRequest, pendingLocalState?: string): Promise<IContainer>;
362362
}
363363

364-
// @alpha
364+
// @alpha @legacy
365365
export type ILoaderOptions = {
366366
cache?: boolean;
367367
client?: IClient;
@@ -370,25 +370,25 @@ export type ILoaderOptions = {
370370
maxClientLeaveWaitTime?: number;
371371
};
372372

373-
// @alpha (undocumented)
373+
// @alpha @legacy (undocumented)
374374
export interface IProvideFluidCodeDetailsComparer {
375375
// (undocumented)
376376
readonly IFluidCodeDetailsComparer: IFluidCodeDetailsComparer;
377377
}
378378

379-
// @alpha (undocumented)
379+
// @alpha @legacy (undocumented)
380380
export interface IProvideLoader {
381381
// (undocumented)
382382
readonly ILoader: ILoader;
383383
}
384384

385-
// @alpha (undocumented)
385+
// @alpha @legacy (undocumented)
386386
export interface IProvideRuntimeFactory {
387387
// (undocumented)
388388
readonly IRuntimeFactory: IRuntimeFactory;
389389
}
390390

391-
// @alpha
391+
// @alpha @legacy
392392
export interface IRuntime extends IDisposable {
393393
createSummary(blobRedirectTable?: Map<string, string>): ISummaryTree;
394394
getEntryPoint(): Promise<FluidObject>;
@@ -400,10 +400,10 @@ export interface IRuntime extends IDisposable {
400400
setConnectionState(connected: boolean, clientId?: string): any;
401401
}
402402

403-
// @alpha (undocumented)
403+
// @alpha @legacy (undocumented)
404404
export const IRuntimeFactory: keyof IProvideRuntimeFactory;
405405

406-
// @alpha
406+
// @alpha @legacy
407407
export interface IRuntimeFactory extends IProvideRuntimeFactory {
408408
instantiateRuntime(context: IContainerContext, existing: boolean): Promise<IRuntime>;
409409
}
@@ -414,13 +414,13 @@ export interface ISelf {
414414
readonly clientId: string;
415415
}
416416

417-
// @alpha
417+
// @alpha @legacy
418418
export const isFluidBrowserPackage: (maybePkg: unknown) => maybePkg is Readonly<IFluidBrowserPackage>;
419419

420-
// @alpha
420+
// @alpha @legacy
421421
export const isFluidPackage: (pkg: unknown) => pkg is Readonly<IFluidPackage>;
422422

423-
// @alpha
423+
// @alpha @legacy
424424
export interface ISnapshotTreeWithBlobContents extends ISnapshotTree {
425425
// (undocumented)
426426
blobsContents?: {
@@ -434,7 +434,7 @@ export interface ISnapshotTreeWithBlobContents extends ISnapshotTree {
434434

435435
export { IThrottlingWarning }
436436

437-
// @alpha
437+
// @alpha @legacy
438438
export enum LoaderHeader {
439439
// @deprecated (undocumented)
440440
cache = "fluid-cache",
@@ -447,7 +447,7 @@ export enum LoaderHeader {
447447
version = "version"
448448
}
449449

450-
// @alpha (undocumented)
450+
// @alpha @legacy (undocumented)
451451
export type ReadOnlyInfo = {
452452
readonly readonly: false | undefined;
453453
} | {

0 commit comments

Comments
 (0)