Issue #3586359: Polish developer APIs and internal documentation

Kristen Polrequested to merge
issue/ai_context-3586359:3586359-beta4-polish into 1.0.x

Description

Polishes developer APIs, internal API documentation, configuration dependencies, and several small code-quality issues before 1.0.0-rc1.

Developer API documentation

  • Adds ai_context.api.php with documented stubs and examples for:
    • hook_ai_context_scope_info_alter()
    • hook_ai_context_scope_values_alter()
  • Removes the misplaced example hook definitions from ai_context.module.
  • Adds missing entity-lifecycle hook documentation.
  • Documents ai_context.scheduler_defaults and links function-call plugin documentation.
  • Adds @internal to classes and services already identified as internal by the API stability policy.
  • AiContextSelectorInterface is now explicitly marked @internal, aligning its source documentation with the existing API stability policy.

Configuration consistency

  • Adds the missing content_moderation dependency to the default AI Context Item view display because it renders the moderation control.

Global scope descriptions

Separates the two contexts in which the Global scope description appears:

  • Scope overview and settings pages now display only: “Always include this context for every agent.”
  • The context-item form retains the warning that enabling Global context clears other scope settings.
  • The descriptions remain separate, complete translatable strings.

Automated coverage verifies both descriptions.

Subcontext configuration lookup

  • Updates AiContextSubcontextToggleTrait to use the consuming service's injected ConfigFactoryInterface.
  • Keeps an explicit config lookup on the content entity, which cannot use service-oriented dependency injection.
  • Throws a clear logic exception if a service uses the trait without exposing an injected config factory.

Additional cleanup

  • Adds declare(strict_types=1); to DynamicEntityReferenceFieldBuilder.
  • Updates spelling configuration for API terminology.
  • Normalizes all unit-test classes to use both @group annotations and #[Group] attributes, preserving group filtering with PHPUnit 9 on Drupal 10 and PHPUnit 10+ on Drupal 11.

This MR does not intentionally change selection, storage, matching, access, or public API behavior. The only user-facing copy change removes context-item save guidance from scope overview and settings pages where no context item is being saved.

No post-merge configuration import, database update, or other manual deployment step is required.

Testing instructions

Automated testing

From web/modules/contrib/ai_context, run:

./lint.sh

From the Drupal project root, run:

ddev phpunit web/modules/contrib/ai_context/tests/src/Unit/AiContextScopeGlobalTest.php
ddev phpunit web/modules/contrib/ai_context/tests/src/Functional/AiContextScopeSettingsTest.php

Manual testing

  1. Visit /admin/config/ai/context/settings/scope.
  2. Confirm the Global scope description says: Always include this context for every agent.
  3. Confirm the page does not mention clearing previous scope settings.
  4. Open the Global scope settings page.
  5. Confirm it uses the same general description and does not show the context-item save warning.
  6. Visit /admin/config/ai/context/items/add.
  7. Locate the Global context checkbox.
  8. Confirm its description contains:
    • Always include this context for every agent.
    • A line break.
    • Saving the form with this enabled will clear previous scope settings.

Checklist

  • I have updated the MR title to use format: Issue #1234: My issue title.
  • I have updated the MR description to include: Closes #1234
  • I have performed a self-review of my own code
  • I have added or updated tests, or explained in the description why this change is not covered by tests
  • I have updated documentation for any new or changed functionality
  • I have written testing instructions and verified them locally
  • I have noted any required post-merge steps (config imports, cache rebuilds, manual changes)
  • This MR contains no breaking API or hook changes, or they are explicitly documented in the description

AI Compliance

Note

Check the one that best describes your usage, or leave all unchecked if AI was not significantly used.

  • AI Assisted Code
    Mainly written by a human; AI used for autocomplete or partial generation under full human supervision.

  • AI Generated Code
    Mainly generated by AI, reviewed and approved by a human before this MR was created.

  • Vibe Coded
    Generated by AI and only functionally reviewed before this MR was created.

Closes #3586359

Edited by Kristen Pol

Merge request reports