Remember what a document declares, per file

CLAUDE.md

@@ -103,7 +103,9 @@ While a document is open the server must not read it from disk ([LSP] `textDocum
 
 A service may hold an index it derives from its whole source and rebuilds on invalidation.
 A service never remembers the answer to a query.
-Answers are remembered by one PSR-16 decorator per backend, applied in wiring, never around open documents.
+What a document declares is remembered by one PSR-16 decorator on `DeclarationSourceInterface`, applied in wiring.
+Its key is the document's path and text together, so an entry describes one state of one file and is never invalidated.
+The cache's size limit evicts.
 
 #### Invalidation
 

phpstan.neon

@@ -346,7 +346,6 @@ parameters:
                 - src/Resolution/ExpressionResolver.php # resolveConstFetch: the candidate-loop caller
                 - src/Resolution/TypeSource/NativeTypeSource.php # identity-keyed type authority (issue #519)
                 - src/Knowledge/CompositeSymbolSource.php # composite delegates to backends
-                - src/Knowledge/CachingSymbolSource.php # decorator delegates to the wrapped source
                 - tests/*
         -
             method: 'Firehed\PhpLsp\Domain\ResolvedSymbolInterface::format()'

src/Cache/CacheFactory.php

@@ -19,11 +19,20 @@
  */
 final class CacheFactory
 {
-    public static function inMemory(): CacheInterface
+    /**
+     * @param int $maxItems The least recently used entry is dropped past this
+     *                      count; zero is unbounded
+     */
+    public static function inMemory(int $maxItems = 0): CacheInterface
     {
         // ArrayAdapter's second argument disables its copy-on-read (named
         // `storeSerialized` in symfony/cache 7, `deepClone` in 8), so a hit
         // returns the cached instance rather than a clone.
-        return new Psr16Cache(new ArrayAdapter(0, false));
+        return new Psr16Cache(new ArrayAdapter(
+            defaultLifetime: 0,
+            deepClone: false,
+            maxLifetime: 0,
+            maxItems: $maxItems,
+        ));
     }
 }

src/Document/DocumentManager.php

@@ -36,11 +36,6 @@ public function get(string $uri): ?TextDocument
         return $this->documents[FileUri::toPath($uri)] ?? null;
     }
 
-    public function isOpen(string $uri): bool
-    {
-        return $this->get($uri) !== null;
-    }
-
     public function read(string $uri): ?TextDocument
     {
         return $this->get($uri);

src/Document/DocumentManagerInterface.php

@@ -18,6 +18,4 @@ public function update(string $uri, string $content, int $version): void;
     public function close(string $uri): void;
 
     public function get(string $uri): ?TextDocument;
-
-    public function isOpen(string $uri): bool;
 }

src/Document/TextDocument.php

@@ -8,8 +8,8 @@
 
 final class TextDocument
 {
-    /** @var list<int> Byte offsets of line starts */
-    private array $lineOffsets;
+    /** @var list<int>|null */
+    private ?array $offsets = null;
 
     public function __construct(
         public readonly string $uri,
@@ -18,7 +18,6 @@ public function __construct(
         private readonly string $content,
         private readonly PositionEncoding $encoding = PositionEncoding::Utf16,
     ) {
-        $this->lineOffsets = $this->computeLineOffsets();
     }
 
     public function getContent(): string
@@ -33,13 +32,13 @@ public function withContent(string $content, int $version): self
 
     public function getLine(int $line): string
     {
-        if ($line < 0 || $line >= count($this->lineOffsets)) {
+        if ($line < 0 || $line >= count($this->lineOffsets())) {
             return '';
         }
 
-        $start = $this->lineOffsets[$line];
-        $end = $line + 1 < count($this->lineOffsets)
-            ? $this->lineOffsets[$line + 1] - 1 // -1 to exclude newline
+        $start = $this->lineOffsets()[$line];
+        $end = $line + 1 < count($this->lineOffsets())
+            ? $this->lineOffsets()[$line + 1] - 1 // -1 to exclude newline
             : strlen($this->content);
 
         return substr($this->content, $start, $end - $start);
@@ -61,14 +60,14 @@ public function textBeforeCursor(int $line, int $character): string
 
     public function offsetAt(int $line, int $character): int
     {
-        if ($line < 0 || $line >= count($this->lineOffsets)) {
+        if ($line < 0 || $line >= count($this->lineOffsets())) {
             return 0;
         }
 
         // The negotiated encoding measures `character`; the interior is bytes.
         // Converting against the line content also clamps an over-long column
         // to the line's byte length, so no separate line-end clamp is needed.
-        return $this->lineOffsets[$line]
+        return $this->lineOffsets()[$line]
             + $this->encoding->characterToByteOffset($this->getLine($line), $character);
     }
 
@@ -80,7 +79,7 @@ public function positionAt(int $offset): array
         $offset = max(0, min($offset, strlen($this->content)));
 
         $line = 0;
-        foreach ($this->lineOffsets as $i => $lineOffset) {
+        foreach ($this->lineOffsets() as $i => $lineOffset) {
             if ($lineOffset > $offset) {
                 break;
             }
@@ -91,11 +90,22 @@ public function positionAt(int $offset): array
             'line' => $line,
             'character' => $this->encoding->byteToCharacterOffset(
                 $this->getLine($line),
-                $offset - $this->lineOffsets[$line],
+                $offset - $this->lineOffsets()[$line],
             ),
         ];
     }
 
+    /**
+     * Byte offsets of line starts. Derived on first use: a document read only
+     * for what it declares is never asked for a position.
+     *
+     * @return list<int>
+     */
+    private function lineOffsets(): array
+    {
+        return $this->offsets ??= $this->computeLineOffsets();
+    }
+
     /**
      * @return list<int>
      */

src/Domain/DeclaredSymbol.php

@@ -17,4 +17,9 @@ public function __construct(
         public SymbolInfoInterface $info,
     ) {
     }
+
+    public function declares(QualifiedName $name, NameKind $kind): bool
+    {
+        return $this->kind->keyFor($this->name) === $kind->keyFor($name);
+    }
 }

src/Knowledge/AutoloadFilesBackend.php

@@ -8,7 +8,6 @@
 use Firehed\PhpLsp\Document\DocumentSourceInterface;
 use Firehed\PhpLsp\Domain\ComposerAutoloadMap;
 use Firehed\PhpLsp\Domain\FileUri;
-use Firehed\PhpLsp\Parser\SyntaxSource\SyntaxSourceInterface;
 
 /**
  * The {@see SymbolSourceInterface} over Composer's `autoload.files` set — the one
@@ -41,10 +40,8 @@ final class AutoloadFilesBackend implements SymbolSourceInterface, Invalidatable
 
     public function __construct(
         private readonly ComposerAutoloadMapReader $mapReader,
-        private readonly DeclarationSymbolInfoFactory $infoFactory,
-        private readonly DeclarationScanner $scanner,
-        private readonly DocumentSourceInterface $reader,
-        private readonly SyntaxSourceInterface $parser,
+        private readonly DocumentSourceInterface $documents,
+        private readonly DeclarationSourceInterface $declarations,
     ) {
         $this->buildIndex($this->mapReader->current());
     }
@@ -69,8 +66,9 @@ private function buildIndex(ComposerAutoloadMap $map): void
     {
         $this->clearAllSymbols();
         foreach ($map->autoloadFiles() as $path) {
-            $declarations = $this->scanner->scanFile($path, $this->reader, $this->parser);
-            $this->setSymbolsFor(FileUri::fromPath($path), ...$this->infoFactory->allIn($declarations, $path));
+            $document = $this->documents->read($path);
+            $declared = $document === null ? [] : $this->declarations->declarationsIn($document);
+            $this->setSymbolsFor(FileUri::fromPath($path), ...$declared);
         }
         $this->mapAtBuild = $map;
     }

src/Knowledge/BuiltinBackend.php

@@ -47,8 +47,7 @@
  * open-document and disk backends, so a name either of them can resolve never
  * reaches reflection (RFC 1 §5.3).
  *
- * Built-ins are fixed for a given target environment, so a {@see CachingSymbolSource}
- * in front of this backend remembers them (RFC 1 §5.3). This backend is reflection-backed and therefore describes the
+ * This backend is reflection-backed and therefore describes the
  * *server's* runtime, not the project's target — a known §4.7 gap deferred to Step 5
  * (Plan 0002 §5); the interim treats every reflected built-in as available.
  *

src/Knowledge/CachingDeclarationSource.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Firehed\PhpLsp\Knowledge;
+
+use Firehed\PhpLsp\Cache\CacheKey;
+use Firehed\PhpLsp\Document\TextDocument;
+use Firehed\PhpLsp\Domain\DeclaredSymbol;
+use Firehed\PhpLsp\Domain\FileUri;
+use Psr\SimpleCache\CacheInterface;
+
+/**
+ * Keyed by the file and its text together, so an entry describes exactly one
+ * state of one file and never goes stale: changed text is a different key.
+ */
+final readonly class CachingDeclarationSource implements DeclarationSourceInterface
+{
+    public function __construct(
+        private DeclarationSourceInterface $inner,
+        private CacheInterface $cache,
+    ) {
+    }
+
+    public function declarationsIn(TextDocument $document): array
+    {
+        $key = CacheKey::from(FileUri::toPath($document->uri) . "\0" . $document->getContent());
+
+        /** @var list<DeclaredSymbol>|null $declared */
+        $declared = $this->cache->get($key);
+        if ($declared === null) {
+            $declared = $this->inner->declarationsIn($document);
+            $this->cache->set($key, $declared);
+        }
+
+        return $declared;
+    }
+}