Merge pull request #35808 from storybookjs/valentin/angular-docgen-harness-acm

Harness: Gate the Angular component meta analyzer against Compodoc

Author: valentinpalkovic

code/lib/cli-storybook/src/sandbox-templates.ts

@@ -1261,45 +1261,35 @@ export const daily: TemplateKey[] = [
 
 export const templatesByCadence = { normal, merged, daily };
 
-/**
- * Features a sandbox must enable for the docgen service to write the per-component static snapshots
- * that the recorded docgen baselines are read from. Both are required: without
- * `componentsManifest`, `experimentalDocgenServer` writes nothing to disk.
- */
+// Both are required: without `componentsManifest`, `experimentalDocgenServer` writes nothing to disk
+// for the recorded baselines to read.
 const DOCGEN_SERVER_FEATURES = ['experimentalDocgenServer', 'componentsManifest'] as const;
 
-const mainConfigFeatures = (template: Template): Record<string, unknown> | undefined => {
+// Templates whose `mainConfig` is a function of the generated `ConfigFile`, so its features cannot be
+// read without running the sandbox generator. Listed by name so a new function-form template throws
+// below instead of silently dropping out of docgen baseline coverage.
+const UNREADABLE_MAIN_CONFIG_TEMPLATES = new Set<string>(['cra/default-js']);
+
+const enablesDocgenServer = (key: string, template: Template): boolean => {
   const { mainConfig } = template.modifications ?? {};
-  if (!mainConfig) {
-    return undefined;
-  }
-  if (typeof mainConfig !== 'function') {
-    return mainConfig.features;
-  }
-  // Templates that rewrite the generated config read from the `ConfigFile` they are handed; the
-  // ones that only declare features ignore it. Reading features out of the latter is worth a stub;
-  // the former are expected to throw here and simply do not declare these flags.
-  try {
-    return mainConfig({ getFieldValue: () => undefined } as never)?.features;
-  } catch {
-    return undefined;
+  if (typeof mainConfig === 'function') {
+    if (!UNREADABLE_MAIN_CONFIG_TEMPLATES.has(key)) {
+      // eslint-disable-next-line local-rules/no-uncategorized-errors
+      throw new Error(
+        `Template "${key}" declares mainConfig as a function, whose features cannot be read here. ` +
+          `Move ${DOCGEN_SERVER_FEATURES.join(' and ')} into the object form to opt into docgen ` +
+          `baseline coverage, or add the key to UNREADABLE_MAIN_CONFIG_TEMPLATES to stay out of it.`
+      );
+    }
+    return false;
   }
-};
-
-/** Whether a template's sandbox runs with server-side docgen, and so carries docgen baselines. */
-const enablesDocgenServer = (template: Template): boolean => {
-  const features = mainConfigFeatures(template);
+  const features = mainConfig?.features;
   return DOCGEN_SERVER_FEATURES.every((feature) => features?.[feature] === true);
 };
 
-/**
- * Templates whose sandbox runs with server-side docgen enabled.
- *
- * Derived from the flags rather than kept as a second list, so turning them on for a template is all
- * it takes to bring it into docgen baseline coverage — both the recorder and the CI step that
- * verifies it read this.
- */
+// Derived from the flags rather than kept as a second list, so turning them on for a template is all
+// it takes to bring it into docgen baseline coverage.
 export const docgenServerTemplates = (): TemplateKey[] =>
   (Object.entries(allTemplates) as [TemplateKey, Template][])
-    .filter(([, template]) => enablesDocgenServer(template))
+    .filter(([key, template]) => enablesDocgenServer(key, template))
     .map(([key]) => key);

code/lib/docgen-harness/README.md

@@ -67,20 +67,31 @@ src/
 - argTypes: every baseline key, description, default value, and type must survive.
   A type may only change by normalized deep equality or a clear improvement - a catch-all becoming structured, a literal union gaining members.
   About half the corpus records `other`, where the legacy engine parked free text it could not resolve (`TreeNode`, `Array([object Object])`, `{ theme: string; dense: boolean }`).
-  Such a stub accepts a candidate that adds structure or resolves it to the scalar it already named; an unrelated scalar is a lateral change and fails.
+  Such a stub accepts a candidate that adds populated structure (an empty enum/union/object is not an improvement) or resolves it to the scalar or single literal it already named; an unrelated scalar or literal is a lateral change and fails.
   Only the three markers that record nothing at all accept any candidate: `empty-enum`, `undefined`, and the empty string - today's Angular and Vue spellings, so adding a framework means revisiting that list.
   A resolution the rule cannot recognize (legacy `TSFunctionType` becoming a `function` sbType, say) fails rather than guessing; re-record and review the diff.
-  `required`, `table.category`, `jsDocTags`, `control`/`action`, and description/default contents are deliberately not compared; each would lock in a recorded lie (#28706) or engine-specific vocabulary.
+  A recorded `table.type.summary` must survive (dropping it is a violation), but its text may change freely outside `strictTable`.
+  `required`, `table.category`, `jsDocTags`, `control`/`action`, and description/default contents are deliberately not compared (except `required` under `strictTable`); each would lock in a recorded lie (#28706) or engine-specific vocabulary.
 - Snippets: represented binding names are compared as sets, so formatting can never fail, but a lost binding does.
   Directive spelling is normalized, so `:x`/`v-bind:x`, `@x`/`v-on:x`, `#x`/`v-slot:x`, and any `.modifier` all read as the same name.
+  The Angular comparison additionally gates root-element identity: the tag name must match and bare (valueless) attributes - the mangled attribute-selector markers - must survive.
 - Acceptance: there is no allowlist file.
   The committed baseline is the allowlist - accept an intentional change by re-recording with `-u` and reviewing the diff.
-- The recorders read each committed file before its snapshot call, so a `-u` re-record still compares the fresh output against the last committed text.
+- The recorders read each committed file and run every gate BEFORE the snapshot call, so a `-u` run refuses to queue a regressed recording and stays red until the code is fixed.
   Regressions fail with named violations; improvements pass.
 - The committed `argtypes*.snapshot` files are pretty-format text, not JSON.
-  `parseArgTypesSnapshot` reads them back and verifies itself by re-serializing every parse byte-for-byte; anything outside that grammar throws.
+  `parseArgTypesSnapshot` reads them back, verifies itself by re-serializing every parse byte-for-byte, and rejects any parsed string carrying the writer-ambiguous entry-boundary shape.
+  A string whose unescaped write is byte-identical to real entry boundaries cannot be detected at parse time; the recorders' parsed-vs-live proofs guard that case on normal and CI runs, and on `-u` runs against the exact bytes queued for writing.
 - Adding a framework: extend the `Framework` union and compilation fails at the switch in `snippets.ts` until the new matcher exists.
 
+### Trust model
+
+The comparator machine-checks a deliberate subset: baseline arg names, description presence, default presence, `table.type.summary` presence, and type fidelity for argTypes; represented binding names, root-element identity, and bare-attribute survival for Angular snippets.
+Everything else - description/default/summary text, `table.category`, `control`/`action`, per-arg `jsDocTags`, added args - is caught only by the byte-exact snapshot diffs reviewed at `-u` time, or by the sandbox gate's `change` findings.
+Two flags scope trust to where the baseline earns it: `legacyBaseline` (only on legs whose baseline is a legacy compodoc recording) waives the raw `false`/`NaN`/`null` defaults that pipeline invents, and `strictTable` (only on the ACM self-ratchet, whose baseline the same engine recorded) additionally gates `table.type.summary` text changes and `table.type.required` true->false flips.
+The sandbox baseline gate runs in the daily CI tier, so a whole-project regression can merge green and surface up to a day later, detached from the offending PR.
+Known-accepted blind spots: enum members whose quoted and bare spellings collide normalize to the same member (`'"small"'` reads as `small`), and `\r`/`\r\n` in extracted strings are LF-normalized by vitest at write time, so a CR-bearing extraction can never record green (perma-loud, never silent).
+
 ## The vue-component-meta recorder (vue3)
 
 `vue3-component-meta-baselines.test.ts` replicates the vue3-vite vite plugin's meta processing exactly - checker options, empty-meta skip, nested-schema pruning, exposed de-duplication, and the vue-docgen-api event-description backfill - so the `cm-` snapshots show what a `vue-component-meta` user actually gets today.

code/lib/docgen-harness/package.json

@@ -38,6 +38,7 @@
     "@angular/platform-browser": "^21.2.14",
     "@angular/platform-browser-dynamic": "^21.2.14",
     "@compodoc/compodoc": "2.0.0",
+    "@storybook/angular-cm": "workspace:*",
     "@storybook/angular-compodoc": "workspace:*",
     "@storybook/angular-vite": "workspace:*",
     "@storybook/react": "workspace:*",

code/lib/docgen-harness/src/angular/__testfixtures__/complex-selector/acm-argtypes-filtered.snapshot

@@ -0,0 +1,19 @@
+{
+  "emphasis": {
+    "description": undefined,
+    "name": "emphasis",
+    "table": {
+      "category": "inputs",
+      "defaultValue": {
+        "summary": false,
+      },
+      "type": {
+        "required": true,
+        "summary": "boolean",
+      },
+    },
+    "type": {
+      "name": "boolean",
+    },
+  },
+}

code/lib/docgen-harness/src/angular/__testfixtures__/complex-selector/acm-argtypes.snapshot

@@ -0,0 +1,19 @@
+{
+  "emphasis": {
+    "description": undefined,
+    "name": "emphasis",
+    "table": {
+      "category": "inputs",
+      "defaultValue": {
+        "summary": false,
+      },
+      "type": {
+        "required": true,
+        "summary": "boolean",
+      },
+    },
+    "type": {
+      "name": "boolean",
+    },
+  },
+}

code/lib/docgen-harness/src/angular/__testfixtures__/complex-selector/acm-snippet-PropsAsWritten.snapshot

@@ -0,0 +1 @@
+<button sb-harness-action [emphasis]="true"></button>

code/lib/docgen-harness/src/angular/__testfixtures__/cross-file-inheritance/acm-argtypes-filtered.snapshot

@@ -0,0 +1,36 @@
+{
+  "dismissible": {
+    "description": "Whether the alert shows a close button.",
+    "name": "dismissible",
+    "table": {
+      "category": "inputs",
+      "defaultValue": {
+        "summary": false,
+      },
+      "type": {
+        "required": true,
+        "summary": "boolean",
+      },
+    },
+    "type": {
+      "name": "boolean",
+    },
+  },
+  "heading": {
+    "description": undefined,
+    "name": "heading",
+    "table": {
+      "category": "inputs",
+      "defaultValue": {
+        "summary": "",
+      },
+      "type": {
+        "required": true,
+        "summary": "string",
+      },
+    },
+    "type": {
+      "name": "string",
+    },
+  },
+}

code/lib/docgen-harness/src/angular/__testfixtures__/cross-file-inheritance/acm-argtypes.snapshot

@@ -0,0 +1,55 @@
+{
+  "dismissed": {
+    "action": "dismissed",
+    "description": undefined,
+    "name": "dismissed",
+    "table": {
+      "category": "outputs",
+      "defaultValue": {
+        "summary": undefined,
+      },
+      "type": {
+        "required": true,
+        "summary": "EventEmitter",
+      },
+    },
+    "type": {
+      "name": "other",
+      "value": "void",
+    },
+  },
+  "dismissible": {
+    "description": "Whether the alert shows a close button.",
+    "name": "dismissible",
+    "table": {
+      "category": "inputs",
+      "defaultValue": {
+        "summary": false,
+      },
+      "type": {
+        "required": true,
+        "summary": "boolean",
+      },
+    },
+    "type": {
+      "name": "boolean",
+    },
+  },
+  "heading": {
+    "description": undefined,
+    "name": "heading",
+    "table": {
+      "category": "inputs",
+      "defaultValue": {
+        "summary": "",
+      },
+      "type": {
+        "required": true,
+        "summary": "string",
+      },
+    },
+    "type": {
+      "name": "string",
+    },
+  },
+}

code/lib/docgen-harness/src/angular/__testfixtures__/cross-file-inheritance/acm-snippet-PropsAsWritten.snapshot

@@ -0,0 +1 @@
+<sb-cross-file-inheritance [dismissible]="true" [heading]="'Storage almost full'" (dismissed)="dismissed($event)"></sb-cross-file-inheritance>

code/lib/docgen-harness/src/angular/__testfixtures__/decorator-generic/acm-argtypes-filtered.snapshot

@@ -0,0 +1,38 @@
+{
+  "items": {
+    "description": undefined,
+    "name": "items",
+    "table": {
+      "category": "inputs",
+      "defaultValue": {
+        "summary": "[]",
+      },
+      "type": {
+        "required": true,
+        "summary": "T[]",
+      },
+    },
+    "type": {
+      "name": "other",
+      "value": "empty-enum",
+    },
+  },
+  "selected": {
+    "description": undefined,
+    "name": "selected",
+    "table": {
+      "category": "inputs",
+      "defaultValue": {
+        "summary": undefined,
+      },
+      "type": {
+        "required": false,
+        "summary": "T",
+      },
+    },
+    "type": {
+      "name": "other",
+      "value": "empty-enum",
+    },
+  },
+}