refactor(ivy): Update @publicApi to @codeGenApi on ivy instructions (#29820)

- Removes `@publicApi` annotation from ivy instructions
- Adds new `@codeGenApi` annotation to ivy instructions
- Updates ts_api_guardian to support the new annotation properly

PR Close #29820

tools/ts-api-guardian/lib/cli.ts

@@ -30,18 +30,18 @@ export function startCli() {
   // Angular project tag rules unless specified explicitly through a given option.
   if (argv['useAngularTagRules']) {
     options.exportTags = {
-      required: ['publicApi'],
+      requireAtLeastOne: ['publicApi', 'codeGenApi'],
       banned: ['experimental'],
       toCopy: ['deprecated']
     };
     options.memberTags = {
-      required: [],
-      banned: ['experimental', 'publicApi'],
+      requireAtLeastOne: [],
+      banned: ['experimental', 'publicApi', 'codeGenApi'],
       toCopy: ['deprecated']
     };
     options.paramTags = {
-      required: [],
-      banned: ['experimental', 'publicApi'],
+      requireAtLeastOne: [],
+      banned: ['experimental', 'publicApi', 'codeGenApi'],
       toCopy: ['deprecated']
     };
   }

tools/ts-api-guardian/lib/serializer.ts

@@ -17,9 +17,10 @@ const baseTsOptions: ts.CompilerOptions = {
 
 export interface JsDocTagOptions {
   /**
-   * An array of names of jsdoc tags that must exist.
+   * An array of names of jsdoc tags, one of which must exist. If no tags are provided, there are no
+   * required tags.
    */
-  required?: string[];
+  requireAtLeastOne?: string[];
 
   /**
    * An array of names of jsdoc tags that must not exist.
@@ -316,15 +317,16 @@ class ResolvedDeclarationEmitter {
 
   private processJsDocTags(node: ts.Node, tagOptions: JsDocTagOptions) {
     const jsDocTags = getJsDocTags(node);
-    const missingRequiredTags =
-        tagOptions.required.filter(requiredTag => jsDocTags.every(tag => tag !== requiredTag));
-    if (missingRequiredTags.length) {
+    const requireAtLeastOne = tagOptions.requireAtLeastOne;
+    const isMissingAnyRequiredTag = requireAtLeastOne != null && requireAtLeastOne.length > 0 &&
+        jsDocTags.every(tag => requireAtLeastOne.indexOf(tag) === -1);
+    if (isMissingAnyRequiredTag) {
       this.diagnostics.push({
         type: 'error',
         message: createErrorMessage(
-            node, 'Required jsdoc tags - ' +
-                missingRequiredTags.map(tag => `"@${tag}"`).join(', ') +
-                ` - are missing on ${getName(node)}.`)
+            node, 'Required jsdoc tags - One of the tags: ' +
+                requireAtLeastOne.map(tag => `"@${tag}"`).join(', ') +
+                ` - must exist on ${getName(node)}.`)
       });
     }
     const bannedTagsFound =
@@ -436,7 +438,7 @@ function hasModifier(node: ts.Node, modifierKind: ts.SyntaxKind): boolean {
 }
 
 function applyDefaultTagOptions(tagOptions: JsDocTagOptions | undefined): JsDocTagOptions {
-  return {required: [], banned: [], toCopy: [], ...tagOptions};
+  return {requireAtLeastOne: [], banned: [], toCopy: [], ...tagOptions};
 }
 
 function getName(node: any) {

tools/ts-api-guardian/test/unit_test.ts

@@ -531,8 +531,8 @@ describe('unit test', () => {
     `;
     checkThrows(
         {'file.d.ts': input},
-        'file.d.ts(2,1): error: Required jsdoc tags - "@stable" - are missing on `A`.',
-        {exportTags: {required: ['stable']}});
+        'file.d.ts(2,1): error: Required jsdoc tags - One of the tags: "@stable" - must exist on `A`.',
+        {exportTags: {requireAtLeastOne: ['stable']}});
   });
 
   it('should throw on missing required jsdoc tags on fields', () => {
@@ -544,8 +544,8 @@ describe('unit test', () => {
     `;
     checkThrows(
         {'file.d.ts': input},
-        'file.d.ts(3,3): error: Required jsdoc tags - "@stable" - are missing on `value`.',
-        {memberTags: {required: ['stable']}});
+        'file.d.ts(3,3): error: Required jsdoc tags - One of the tags: "@stable" - must exist on `value`.',
+        {memberTags: {requireAtLeastOne: ['stable']}});
   });
 
   it('should throw on missing required jsdoc tags on parameters', () => {
@@ -557,8 +557,21 @@ describe('unit test', () => {
     `;
     checkThrows(
         {'file.d.ts': input},
-        'file.d.ts(3,7): error: Required jsdoc tags - "@stable" - are missing on `param`.',
-        {paramTags: {required: ['stable']}});
+        'file.d.ts(3,7): error: Required jsdoc tags - One of the tags: "@stable" - must exist on `param`.',
+        {paramTags: {requireAtLeastOne: ['stable']}});
+  });
+
+  it('should require at least one of the requireOnOf tags', () => {
+    const input = `
+      /** @experimental */
+      export declare class A {
+        foo(param: number): void;
+      }
+    `;
+    checkThrows(
+        {'file.d.ts': input},
+        'file.d.ts(3,7): error: Required jsdoc tags - One of the tags: "@stable", "@foo", "@bar" - must exist on `param`.',
+        {paramTags: {requireAtLeastOne: ['stable', 'foo', 'bar']}});
   });
 });