Manifests: Add a warning field to story entries

[valentinpalkovic]

What I did

A generated story snippet can be valid but incomplete. Server-side snippet generation reads the story file rather than running it, so an arg merged in through a spread, or a template held in a variable, simply cannot be resolved. The snippet that comes out is still useful, it is just missing something.

There was nowhere to say that. The only option was to write it into the snippet itself:

<!-- unresolved: ...sharedArgs -->
<sb-button [label]="'meta'" [count]="1"></sb-button>

Which pushes the problem onto every consumer. The docs Source block renders it as a stray comment, an agent reading components.json has to know to parse it back out, and a non-HTML renderer has no comment syntax to hide it in.

This adds a warning to each story entry, so the caveat travels as data next to the snippet:

 {
   "id": "button--primary",
   "name": "Primary",
-  "snippet": "<!-- unresolved: ...sharedArgs -->\n<sb-button [label]=\"'meta'\" [count]=\"1\"></sb-button>"
+  "snippet": "<sb-button [label]=\"'meta'\" [count]=\"1\"></sb-button>",
+  "warning": "Incomplete snippet: `...sharedArgs` could not be resolved statically."
 }

The whole change is the field on StoryDoc and the matching entry in the valibot schema:

export interface StoryDoc {
  id: string;
  name: string;
  snippet?: string;
  description?: string;
  summary?: string;
  /**
   * Why the snippet is an incomplete example: what a static pass could not resolve, in the source
   * text it was written as. A story that carries this still carries a `snippet`; an `error` means
   * there is no snippet at all.
   */
  warning?: string;
  error?: StoryDocsError;
}

The distinction from error is the part worth agreeing on: a story with a warning still has a snippet, a story with an error does not. One says "here is an example, mind the gap", the other says "there is no example".

Nothing populates it yet. The Angular server-side snippet generator is the first producer and is stacked on top of this. Reviewing the format on its own seemed better than reviewing it buried in a framework PR.

No change is needed for it to reach manifests/components.json, because the manifest passes the stories map straight through. There is a test for exactly that, so a future refactor of the merge cannot silently drop the field:

expect(mergeManifestPayloads(docgen, storyDocs).stories['button--primary']).toEqual({
  id: 'button--primary',
  name: 'Primary',
  snippet: '<Button />',
  warning: 'Incomplete snippet: `...sharedArgs` could not be resolved statically.',
});

Command	What it does	Run from
yarn vitest run code/core/src/core-server/utils/manifests	Checks the field survives into the merged manifest	repo root

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

• stories
• unit tests
• integration tests
• end-to-end tests

Manual testing

No user-visible behaviour changes on its own: the field is additive and optional, and nothing writes it yet. The first producer is the stacked Angular PR, where it is reachable from the Docs Source block and from components.json.

Documentation

• Add or update documentation reflecting your changes
• If you are deprecating/removing a feature, make sure to update MIGRATION.MD

The docgen server RFC documents the payload shapes while they are experimental; this field should land there once a producer ships.

Checklist for Maintainers

• When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli-storybook/src/sandbox-templates.ts

• Declare whether manual QA will be needed for this PR during the next release, through qa:needed or qa:skip

• Make sure this PR contains one of the labels below:

  Available labels

  • bug: Internal changes that fixes incorrect behavior.
  • maintenance: User-facing maintenance tasks.
  • dependencies: Upgrading (sometimes downgrading) dependencies.
  • build: Internal-facing build tooling & test updates. Will not show up in release changelog.
  • cleanup: Minor cleanup style change. Will not show up in release changelog.
  • documentation: Documentation only changes. Will not show up in release changelog.
  • feature request: Introducing a new feature.
  • BREAKING CHANGE: Changes that break compatibility in some way with current major version.
  • other: Changes that don't fit in the above categories.

[github-actions]

	Fails
🚫	PR is not labeled with one of: ["qa:needed","qa:skip","qa:success"]

Generated by 🚫 dangerJS against ce31afc

[coderabbitai]

Walkthrough

The StoryDoc contract now supports optional warnings for incomplete snippets. Manifest merge coverage verifies that warnings remain with story metadata.

Changes

Story warning metadata

Layer / File(s)	Summary
StoryDoc warning contract code/core/src/shared/open-service/services/story-docs/definition.ts, code/core/src/shared/open-service/services/story-docs/types.ts	The schema and StoryDoc type now accept an optional warning string. The type documentation distinguishes warnings from errors.
Manifest warning preservation code/core/src/core-server/utils/manifests/components-ref-manifest.test.ts	The merge test verifies that a story warning remains alongside the snippet and other story metadata.

Possibly related PRs

• storybookjs/storybook#35726: Related story-doc and toolset refactoring consumes and preserves story metadata.
• storybookjs/storybook#35733: Related story-doc extraction handling uses warning and error payloads.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@code/core/src/shared/open-service/services/story-docs/definition.ts`:
- Line 21: Update the StoryDoc Valibot schema in definition.ts and the StoryDoc
type in types.ts to represent mutually exclusive valid states: a warning is
allowed only when snippet is present, and warning must not coexist with error.
Preserve the existing valid states and enforce these constraints consistently at
both validation and type levels.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: be45e492-7dc6-4243-b3f0-2ebf3b04f2f0

📥 Commits

Reviewing files that changed from the base of the PR and between b3263a1 and ce31afc.

📒 Files selected for processing (3)

• code/core/src/core-server/utils/manifests/components-ref-manifest.test.ts
• code/core/src/shared/open-service/services/story-docs/definition.ts
• code/core/src/shared/open-service/services/story-docs/types.ts