Check alt text of the assets media fields name - #2549

Closes #2548

Built on media in change sets (#2546) and the check engine on change sets, both merged.

What

This is the next F-MED (#2427) slice. The built-in altText check (#2535) now also checks media fields, so S2's image without alt text fails the check with a finding that names the field (CHK-01, MED-02).

• AltTextCheckType: when the subject has a content type, each media field, and each item of a list of media, is checked against the version of its image that readers will see:

  • when the subject's change set holds the image, the live version once that set publishes what it proposes;
  • otherwise, the live version now.

  An image with no live version, one that only a change set proposes, fails with its own finding outside that set. Whatever version another set publishes later, nothing checks this content against it.

  An image whose version has no alt text is a finding. The finding points at the field (/hero, /gallery/1, or /photo/value on an entity), names the file, and says to set alt text with update_media. The asset's id is the excerpt. Media that is not an image, such as a PDF, needs no alt text.

• IMediaLibrary.LiveVersionAsync(id, publishing): the version readers see. That is the newest version a person wrote in the library after the published one, since library writes take effect at once; otherwise it is the published version. publishing names a version a set will publish, to ask what readers see once it has. A version that any change set has proposed counts only once its set publishes it.

• ProposedMediaVersions (new table, with migrations for SQLite and PostgreSQL): every media version a change set proposes, kept when the set later moves on to a newer version. This is how the library tells a person's write from a set's. The version rows cannot record it themselves, since a trigger keeps them unchanged. The change set directory adds a row whenever it records a media operation or extends one. The migration fills the table from the operations stored today, and its Down drops the table.

• CheckSubject.SetOperations (optional): the operations of the set the content goes live with, so a check can see what that set proposes. ChangeSetChecks passes the set's operations when it runs its checks, so the set is read once per run, not once per item.

• check_draft takes an optional change_set_id. An agent can then check a draft against the media versions its set proposes, such as alt text it just added with update_media. It refuses a set the agent may not read and one that is published, rejected or reverted.

• ChangeSet: a newer version of an asset the set already proposes moves its operation on, as for entries. So update_media after upload_media in one set, which is S2, extends the upload instead of being refused as a duplicate. A media duplicate now says which version to update from, as an entry's does.

• MediaFields.Holds decides what counts as a media field. MediaTools and the check share it.

Why

The check already covered images in text, and the comment in it left assets of the library to F-MED. What goes live is what counts:

• A published image without alt text fails even while a newer version with alt text waits in another set, or in a rejected one. That holds even when the set has moved on to a later version since. It passes once the page goes live in the set that adds the alt text.
• A person who uploads or describes an image in the admin library changes it at once, without a change set. So their alt text counts on every page right away, including pages in a set that holds the image, and a later version a set proposes does not hide it.

An asset the library does not hold is no finding. Entry writes already refuse such references, and check examples name made-up ids.

Choices worth a look:

• The check needs ProposedMediaVersions to read the version that goes live. A person's library write is live at once, while a set's version is live only when the set publishes it. The operation rows keep only the last version a set proposes. Without the table, a version the set moved past would pass for a library write, as the fourth review showed. Nothing else reads the table.
• A table of proposed versions, not a column on the version rows. Versions are immutable by trigger, and when the library writes a version it does not yet know whether a set will propose it. The set directory does know, at the moment it records the operation.
• The migration's backfill knows only the versions sets propose now. A version a set moved past before this migration is unknown, so it reads as a library write. v2 has no release yet, so this affects development data only.

Tests

Integration tests, each on SQLite and PostgreSQL:

• A page whose hero and second gallery item name an image without alt text fails with findings at /hero and /gallery/1, naming the file. The gallery item with alt text passes.
• A published image without alt text fails on an entity at /photo/value. Once a version with alt text is published, the page and the entity pass. An unknown asset passes.
• Version 1 of an image is published without alt text, and version 2 with alt text waits in a set. A page fails with no set and with another set, and passes with the set that holds version 2.
• An image that only change sets propose, whose latest version has alt text, fails with no set and with another set. It passes with the set that holds it, and fails again once that set is rejected.
• A person's library writes count at once. An upload without alt text fails with the alt-text finding. Once the person describes it in the library, the page passes with no set and with another set. A later version without alt text that a set proposes fails only with that set. Content outside the set still passes while the set is pending, and after it is rejected.
• A library write older than the published version no longer counts.
• A PDF in a media field passes.
• Over MCP, versions a set moved past:
  • An agent describes a published image without alt text and then captions it in the same set. It also uploads a new image with alt text and captions it there.
  • Outside the set, the published image still fails with the alt-text finding, and the new one fails as not published. Both hold while the set is pending and after it is rejected.
  • Inside the set, the published image passes.
• Over MCP, a person describes in the library an image that an agent's set uploaded and attached. check_draft with the set turns from fail to pass. The set's own checks pass when it is submitted and published. Outside the set afterwards, the page passes on the person's version, while the published version stays 1.
• Over MCP, S2 in one set: an agent uploads an image without alt text and attaches it in one session. check_draft fails at /hero. update_media adds alt text in the same session and extends the upload to version 2. check_draft then passes, and so does the set's own alt-text check when it is submitted.
• Over MCP, an entity: a product's media fact fails at /photo/value and passes once update_media describes the photo in the same set.
• Over MCP, check_draft refuses an unknown change set and a rejected one.
• Over MCP, with a published image:
  1. A published image is attached to a page in the agent's set.
  2. check_draft with that change_set_id fails at /hero.
  3. update_media adds alt text in the same set.
  4. check_draft now passes.
  5. Submitting the set runs its checks, and alt-text passes there too.

Unit tests:

• A media operation, like an entry's, moves on to a newer version from the same base. A stale media operation is a duplicate that names the version to update from.
• The check never throws, whatever a media field holds (null, numbers, non-ids, objects, mixed lists, on pages and entity facts), and whatever the set names: no set, an upload, or a delete followed by a create of the same asset.

The existing unit tests of the check, conformance included, pass unchanged, and so do the check_draft tests. The migration tests apply and revert the new migration on both providers. The full suite ran locally against a postgres:17 container as well as SQLite. There is no new package or project reference.

Review

The media stack review found a High problem: the check read the asset's latest version rather than the one that goes live. That is fixed above. Its Low findings are fixed too: only images need alt text, and the acceptance is tested through update_media.

A second review blocked again, for two reasons:

• High: S2 could not finish in one set, because update_media after upload_media was refused as a duplicate.
• Medium: an image never published and outside the set was still read at its latest version.

Both are fixed above, together with its Low findings: check_draft validates change_set_id, the entity half is tested through update_media, and a stale comment is gone.

A third review blocked on a High problem: an image a person uploads or describes in the admin library never goes through a change set. So it was never published, and content using it could never pass. The check now reads the live version, as described above. Its Low findings are fixed too:

• the media duplicate message;
• the set is read once per run;
• a stale test comment is gone;
• there is a never-throws test for media values;
• the scope text of Check alt text of media fields #2548 is updated.

A fourth review blocked on two problems in that fix:

• High: a version a set had moved past within the same set was taken for a library write. Its alt text then counted outside the set, while pending and after rejection. ProposedMediaVersions now keeps those versions.
• Medium: inside its own set, the check ignored a person's later alt text in the library. The check now asks for the live version once the set publishes.

A fifth review gave MERGE, with three Low findings:

• a reverted upload stays live through a later library write: A reverted media upload stays live through a later library write #2663;
• a library save can carry a rejected set's metadata live, which is existing behaviour of the library view: A library save carries a rejected set's media metadata live #2664;
• undoing and redoing the migration forgets the versions sets had moved past. That is the backfill limit described above, and v2 has no release yet.

Checklist

• Linked to an issue a maintainer has confirmed
• Targets v2
• Tests or docs updated where behaviour changed
• No tool-generated co-author trailers or footers