[FEATURE] Add opt-in documentation lint (PoC for #1157)

Adds a proof-of-concept documentation linter that hooks into the compiler
pipeline as a node transformer. As a first rule it warns when a section
heading contains a discouraged phrase (e.g. "Non-Composer mode").

The linter is opt-in (the `lint` theme setting, default off) and emits
warnings only, so it never breaks or rejects third-party extension
documentation unless a caller explicitly enables it and opts into
--fail-on-log. This is deliberate: there is no reliable back-channel to
third-party extension authors to tell them their docs started failing a
newly added rule.

Matching is case-insensitive and word-bounded so a short phrase does not
match inside a larger word. The configurable phrase list is trimmed and
de-duplicated.

Tests:
- Unit tests for the opt-in toggle, phrase parsing (trim/empty/dedup),
  case-insensitivity and word-boundary matching (no false positives).
- Integration tests for the enabled (warning emitted) and disabled
  (no warning, opt-in respected) cases.

Refs #1157

Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>

Author: CybotTM

packages/typo3-docs-theme/resources/config/typo3-docs-theme.php

@@ -22,6 +22,7 @@
 use T3Docs\Typo3DocsTheme\Compiler\NodeTransformers\CollectFileObjectsTransformer;
 use T3Docs\Typo3DocsTheme\Compiler\NodeTransformers\CollectPrefixLinkTargetsTransformer;
 use T3Docs\Typo3DocsTheme\Compiler\NodeTransformers\ConfvalMenuNodeTransformer;
+use T3Docs\Typo3DocsTheme\Compiler\NodeTransformers\LintDiscouragedPhrasesTransformer;
 use T3Docs\Typo3DocsTheme\Compiler\NodeTransformers\RedirectsNodeTransformer;
 use T3Docs\Typo3DocsTheme\Compiler\NodeTransformers\RemoveInterlinkSelfReferencesFromCrossReferenceNodeTransformer;
 use T3Docs\Typo3DocsTheme\Compiler\NodeTransformers\ReplacePermalinksNodeTransformer;
@@ -116,6 +117,8 @@
         ->tag('phpdoc.guides.compiler.nodeTransformers')
         ->set(Typo3TalkNodeTransformer::class)
         ->tag('phpdoc.guides.compiler.nodeTransformers')
+        ->set(LintDiscouragedPhrasesTransformer::class)
+        ->tag('phpdoc.guides.compiler.nodeTransformers')
         ->set(TwigExtension::class)
         ->tag('twig.extension')
         ->autowire()

packages/typo3-docs-theme/src/Compiler/NodeTransformers/LintDiscouragedPhrasesTransformer.php

@@ -0,0 +1,127 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link https://phpdoc.org
+ */
+
+namespace T3Docs\Typo3DocsTheme\Compiler\NodeTransformers;
+
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
+use phpDocumentor\Guides\Compiler\NodeTransformer;
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\Nodes\SectionNode;
+use Psr\Log\LoggerInterface;
+use T3Docs\Typo3DocsTheme\Settings\Typo3DocsThemeSettings;
+
+use function array_filter;
+use function array_map;
+use function array_unique;
+use function array_values;
+use function explode;
+use function in_array;
+use function preg_match;
+use function preg_quote;
+use function sprintf;
+use function strtolower;
+use function trim;
+
+/**
+ * Proof-of-concept documentation linter for issue #1157.
+ *
+ * This transformer demonstrates how a documentation-content lint rule can be
+ * hooked into the render pipeline: it traverses section headings and emits a
+ * warning when a heading contains a discouraged phrase (e.g. "Non-Composer
+ * mode").
+ *
+ * Two deliberate design choices, both driven by the fact that render-guides
+ * renders *third-party* extension documentation whose authors we have no
+ * reliable back-channel to:
+ *
+ *  1. Opt-in: the rule does nothing unless the `lint` theme setting is truthy.
+ *     A failing lint must never silently break or reject an extension's docs
+ *     just because the rule set changed.
+ *  2. Warning severity: findings are logged as warnings, so they only abort a
+ *     render when the caller explicitly passes `--fail-on-log`. By default they
+ *     are advisory.
+ *
+ * Matching is case-insensitive and bound to whole words, so a short phrase does
+ * not match inside a larger word (e.g. "id" does not flag "Identifier").
+ *
+ * @implements NodeTransformer<SectionNode>
+ */
+final class LintDiscouragedPhrasesTransformer implements NodeTransformer
+{
+    /** @var list<string> */
+    private const DEFAULT_DISCOURAGED_PHRASES = ['Non-Composer mode'];
+
+    public function __construct(
+        private readonly Typo3DocsThemeSettings $themeSettings,
+        private readonly LoggerInterface $logger,
+    ) {}
+
+    public function enterNode(Node $node, CompilerContextInterface $compilerContext): Node
+    {
+        if (!$node instanceof SectionNode || !$this->isLintEnabled()) {
+            return $node;
+        }
+
+        $heading = $node->getTitle()->toString();
+
+        foreach ($this->getDiscouragedPhrases() as $phrase) {
+            if (preg_match('/\b' . preg_quote($phrase, '/') . '\b/iu', $heading) !== 1) {
+                continue;
+            }
+            $this->logger->warning(
+                sprintf('Heading "%s" contains the discouraged phrase "%s".', $heading, $phrase),
+                $compilerContext->getLoggerInformation(),
+            );
+        }
+
+        return $node;
+    }
+
+    public function leaveNode(Node $node, CompilerContextInterface $compilerContext): Node
+    {
+        return $node;
+    }
+
+    public function supports(Node $node): bool
+    {
+        return $node instanceof SectionNode;
+    }
+
+    public function getPriority(): int
+    {
+        // Read-only pass; ordering relative to other transformers is irrelevant.
+        return 1000;
+    }
+
+    private function isLintEnabled(): bool
+    {
+        return in_array(
+            strtolower($this->themeSettings->getSettings('lint', 'false')),
+            ['1', 'true', 'yes', 'on'],
+            true,
+        );
+    }
+
+    /** @return list<string> */
+    private function getDiscouragedPhrases(): array
+    {
+        $configured = trim($this->themeSettings->getSettings('lint_discouraged_phrases', ''));
+        if ($configured === '') {
+            return self::DEFAULT_DISCOURAGED_PHRASES;
+        }
+
+        $phrases = array_filter(array_map(trim(...), explode(',', $configured)), static fn(string $phrase): bool => $phrase !== '');
+
+        return array_values(array_unique($phrases));
+    }
+}

packages/typo3-docs-theme/src/DependencyInjection/Typo3DocsThemeExtension.php

@@ -71,6 +71,8 @@ public function load(array $configs, ContainerBuilder $container): void
                         'typo3_core_preferred' => $this->getConfigValue($configs, 'typo3_core_preferred', ''),
                         'confval_default' => $this->getConfigValue($configs, 'confval_default', 'Option'),
                         'disable_version_switch' => $this->getConfigValue($configs, 'disable_version_switch', ''),
+                        'lint' => $this->getConfigValue($configs, 'lint', 'false'),
+                        'lint_discouraged_phrases' => $this->getConfigValue($configs, 'lint_discouraged_phrases', ''),
                     ],
                 ],
             );

packages/typo3-docs-theme/tests/unit/Compiler/NodeTransformers/LintDiscouragedPhrasesTransformerTest.php

@@ -0,0 +1,87 @@
+<?php
+
+declare(strict_types=1);
+
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
+use phpDocumentor\Guides\Nodes\InlineCompoundNode;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
+use phpDocumentor\Guides\Nodes\SectionNode;
+use phpDocumentor\Guides\Nodes\TitleNode;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use Psr\Log\AbstractLogger;
+use Stringable;
+use T3Docs\Typo3DocsTheme\Compiler\NodeTransformers\LintDiscouragedPhrasesTransformer;
+use T3Docs\Typo3DocsTheme\Settings\Typo3DocsThemeSettings;
+
+final class LintDiscouragedPhrasesTransformerTest extends TestCase
+{
+    /**
+     * @param array<string, string> $settings
+     * @param list<string>          $expectedPhrases the discouraged phrases expected to be reported for $heading
+     */
+    #[Test]
+    #[DataProvider('lintProvider')]
+    public function reportsDiscouragedPhrasesInHeadings(array $settings, string $heading, array $expectedPhrases): void
+    {
+        $logger = new class () extends AbstractLogger {
+            /** @var list<string> */
+            public array $warnings = [];
+
+            /** @param mixed[] $context */
+            public function log($level, string|Stringable $message, array $context = []): void
+            {
+                if ($level === 'warning') {
+                    $this->warnings[] = (string) $message;
+                }
+            }
+        };
+
+        $transformer = new LintDiscouragedPhrasesTransformer(new Typo3DocsThemeSettings($settings), $logger);
+
+        $section = new SectionNode(new TitleNode(new InlineCompoundNode([new PlainTextInlineNode($heading)]), 1, 'heading-id'));
+        $transformer->enterNode($section, self::createMock(CompilerContextInterface::class));
+
+        self::assertCount(count($expectedPhrases), $logger->warnings);
+        foreach ($expectedPhrases as $phrase) {
+            self::assertNotEmpty(
+                array_filter($logger->warnings, static fn(string $w): bool => str_contains($w, '"' . $phrase . '"')),
+                sprintf('Expected a warning for phrase "%s", got: %s', $phrase, implode(' | ', $logger->warnings)),
+            );
+        }
+    }
+
+    /**
+     * @return iterable<string, array{array<string, string>, string, list<string>}>
+     */
+    public static function lintProvider(): iterable
+    {
+        // Opt-in: nothing happens unless `lint` is truthy.
+        yield 'disabled by default' => [[], 'Installing in Non-Composer mode', []];
+        yield 'disabled explicitly' => [['lint' => 'false'], 'Installing in Non-Composer mode', []];
+        yield 'disabled on garbage token' => [['lint' => 'enabled'], 'Installing in Non-Composer mode', []];
+        yield 'enabled via true' => [['lint' => 'true'], 'Installing in Non-Composer mode', ['Non-Composer mode']];
+        yield 'enabled via 1' => [['lint' => '1'], 'Installing in Non-Composer mode', ['Non-Composer mode']];
+        yield 'enabled via yes' => [['lint' => 'yes'], 'Installing in Non-Composer mode', ['Non-Composer mode']];
+        yield 'enabled case-insensitive token' => [['lint' => 'TRUE'], 'Installing in Non-Composer mode', ['Non-Composer mode']];
+
+        // Default phrase only triggers when present.
+        yield 'no discouraged phrase' => [['lint' => 'true'], 'Installing with Composer', []];
+
+        // Case-insensitive phrase matching.
+        yield 'case-insensitive heading' => [['lint' => 'true'], 'The NON-COMPOSER MODE chapter', ['Non-Composer mode']];
+
+        // Word-boundary matching: no false positive inside a larger word.
+        yield 'word boundary no false positive' => [['lint' => 'true', 'lint_discouraged_phrases' => 'id'], 'The Identifier field', []];
+        yield 'word boundary real match' => [['lint' => 'true', 'lint_discouraged_phrases' => 'id'], 'The id field', ['id']];
+
+        // Custom phrase list replaces the default.
+        yield 'custom list replaces default' => [['lint' => 'true', 'lint_discouraged_phrases' => 'foo, bar'], 'Non-Composer mode is fine here', []];
+        yield 'custom list matches' => [['lint' => 'true', 'lint_discouraged_phrases' => 'foo, bar'], 'foo and bar', ['foo', 'bar']];
+
+        // Whitespace and empty fragments are ignored; duplicates are de-duplicated (one warning, not two).
+        yield 'whitespace and empty fragments' => [['lint' => 'true', 'lint_discouraged_phrases' => ' foo , , bar '], 'foo bar', ['foo', 'bar']];
+        yield 'duplicate phrase warns once' => [['lint' => 'true', 'lint_discouraged_phrases' => 'foo, foo'], 'foo here', ['foo']];
+    }
+}

tests/Integration/tests/lint/lint-discouraged-phrases-disabled/expected/index.html

@@ -0,0 +1,8 @@
+        <!-- content start -->
+                <section class="section" id="installing-in-non-composer-mode">
+            <h1>Installing in Non-Composer mode<a class="headerlink" href="#installing-in-non-composer-mode" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h1>
+            
+    <p>Body text.</p>
+
+    </section>
+        <!-- content end -->

tests/Integration/tests/lint/lint-discouraged-phrases-disabled/input/index.rst

@@ -0,0 +1,5 @@
+===============================
+Installing in Non-Composer mode
+===============================
+
+Body text.

tests/Integration/tests/lint/lint-discouraged-phrases-enabled/expected/index.html

@@ -0,0 +1,8 @@
+        <!-- content start -->
+                <section class="section" id="installing-in-non-composer-mode">
+            <h1>Installing in Non-Composer mode<a class="headerlink" href="#installing-in-non-composer-mode" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h1>
+            
+    <p>Body text.</p>
+
+    </section>
+        <!-- content end -->

tests/Integration/tests/lint/lint-discouraged-phrases-enabled/expected/logs/warning.log

@@ -0,0 +1 @@
+app.WARNING: Heading "Installing in Non-Composer mode" contains the discouraged phrase "Non-Composer mode". {"rst-file":"index.rst"} []

tests/Integration/tests/lint/lint-discouraged-phrases-enabled/input/guides.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<guides xmlns="https://www.phpdoc.org/guides"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="https://www.phpdoc.org/guides vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
+    links-are-relative="true"
+>
+    <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
+               lint="true"
+    />
+</guides>

tests/Integration/tests/lint/lint-discouraged-phrases-enabled/input/index.rst

@@ -0,0 +1,5 @@
+===============================
+Installing in Non-Composer mode
+===============================
+
+Body text.