@heroiclands/content-language-server 0.1.1 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # HeroicLands content language server
 
-`@heroiclands/content-language-server` provides definition, reference, and workspace search for Markdown notes in HeroicLands content projects. It reads authored notes and project configuration through one exact `@heroiclands/package-build` dependency.
+`@heroiclands/content-language-server` provides definition, reference, completion, diagnostics, and workspace search for Markdown notes in HeroicLands content projects. It reads authored notes and project configuration through one exact `@heroiclands/package-build` dependency.
 
 Start its `heroiclands-content-language-server` executable from the content project root. The server builds a private index when it starts and after saves. The index lives in the platform cache outside the project's `build/` directory, so a clean or package build does not replace editor navigation data.
 
@@ -10,4 +10,10 @@ See the [language server guide](docs/content-language-server.md) for LSP request
 
 Editors can pass explicit foreign content roots in LSP initialization options. A normal workspace-symbol query stays in the current project; an `all:` query searches the configured roots as well. The server returns standard LSP symbols and locations, so the editor controls how results are presented.
 
+Workspace-symbol queries accept `name:`, `shortcode:`, `type:`, `tag:`, and `package:` filters. For example, `all:type:lore` searches every configured project, while `package:thalorna name:camel` searches names in one configured package.
+
+Completion searches anywhere in indexed names, aliases, and Addresses. It inserts the shortest Address that identifies the selected target in the current note, including its system or package when needed. Ordinary `[[...]]` links default to readable `note` content; `![[...]]` embeds default to systemless `none` assets. Clients receive standard LSP completion items with exact text edits.
+
+Open notes receive diagnostics for complete links, embeds, and declared Address fields. The server reads live text for ranges and checks targets against saved indexes and declared content dependencies. It waits briefly after typing before publishing findings.
+
 Maintainers use the [publishing guide](docs/publishing.md) for the first npm release and trusted publisher configuration.

package/docs/content-language-server.md

@@ -1,6 +1,6 @@
 # Content language server
 
-`heroiclands-content-language-server` provides editor navigation for Markdown notes in a HeroicLands content project. It is a stdio Language Server Protocol process. Start it from the project root so it can read `package-build.config.yaml` and the saved content tree.
+`heroiclands-content-language-server` provides editor navigation and reference diagnostics for Markdown notes in a HeroicLands content project. It is a stdio Language Server Protocol process. Start it from the project root so it can read `package-build.config.yaml` and the saved content tree.
 
 The server builds a private JSONL index during initialization, before answering navigation requests. It rebuilds after nearby save notifications settle. Unsaved buffer text identifies an Address under the cursor, but workspace search uses saved metadata. A new, renamed, or deleted note enters the index when the editor sends a save or file-operation notification. A successful rebuild replaces the complete snapshot; a failed rebuild reports an editor message and keeps the last complete snapshot available with a stale-results warning.
 
@@ -17,14 +17,34 @@ heroiclands-content-language-server --rebuild-index
 
 The first prints the private JSONL path. The second is manual recovery when a file operation did not trigger a rebuild; it prints the path on success and exits nonzero on failure. Restarting the server also rebuilds from saved source. A failed rebuild leaves the complete prior snapshot in place. If there is no valid prior snapshot, navigation reports that no index is available.
 
-| LSP request               | Behavior                                                                                                                     |
-| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `textDocument/definition` | Follows an Address or wikilink to the indexed note. An anchor lands on its indexed line.                                     |
-| `workspace/symbol`        | Finds notes by name, alias, ASCII name, shortcode, or Address. `tag:myth` searches tags. One result appears per source note. |
-| `textDocument/references` | Finds authored wikilinks, embeds, and declared frontmatter Address values or keys. Ordinary prose is excluded.               |
+| LSP request                       | Behavior                                                                                                                                              |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `textDocument/definition`         | Follows an Address or wikilink to the indexed note. An anchor lands on its indexed line.                                                              |
+| `textDocument/completion`         | Completes unfinished wikilinks, anchors, and declared frontmatter Address values or keys.                                                             |
+| `workspace/symbol`                | Finds notes by name, alias, ASCII name, shortcode, or Address. Field and project prefixes narrow the saved index. One result appears per source note. |
+| `textDocument/references`         | Finds authored wikilinks, embeds, and declared frontmatter Address values or keys. Ordinary prose is excluded.                                        |
+| `textDocument/publishDiagnostics` | Reports invalid complete links, embeds, anchors, and declared frontmatter Address targets in open notes.                                              |
 
 Reference search uses indexed frontmatter to select candidates and reads saved Markdown source for exact ranges and body links. Unsaved edits identify the target under the cursor but do not enter workspace search. The server writes only LSP messages to stdout and uses UTF-16 positions.
 
+### Reference diagnostics
+
+The server checks a complete `[[Address|Text]]` link, `![[Address|Text]]` embed, or declared frontmatter Address against the saved private index. It checks section anchors against indexed headings and accepts only icon, image, or audio assets in embeds. A missing label, unresolved target, wrong target type, or missing anchor produces a finding at the written Address. Fenced code and unfinished links produce no reference finding. Ordinary prose and frontmatter fields that are not declared as Addresses are outside this check.
+
+Open buffer text supplies the exact source positions, including UTF-16 offsets for non-ASCII text. The index supplies target metadata; unsaved edits in another note do not change resolution. The server waits 300 milliseconds after the latest edit before publishing diagnostics, then checks again after a save or index rebuild. Closing a document clears its findings.
+
+An explicitly configured foreign project can be searched even when it is not a declared build dependency. A reference to that project's content is diagnosed until the citing package declares the dependency in `package-build.config.yaml`. When a declared foreign package's index is unavailable, the diagnostic says the index is unavailable; it does not claim the target is missing. A dependency with `contentIndex: false` cannot provide content targets.
+
+### Address completion
+
+Completion inside a `[[...` link searches the selected projects' saved indexes, including when an editor inserts the closing `]]` after the cursor. The query matches anywhere in a note's full name, aliases, shortcode, short Address, or canonical Address. The existing `nameAscii` and `aliasesAscii` fields supply typeable forms of names with non-ASCII characters. The server builds lowercase search keys in memory when it loads an index and transliterates the query with the same rule. The JSONL format carries no separate search field.
+
+Each result identifies its owning package and canonical Address. Readable `note` content, systemless `none` targets, and game system documents stay selectable even when they share a Markdown file. An ordinary `[[link|text]]` defaults to `note`, while an embedded `![[link|text]]` defaults to `none` and uses `image` as the type of a bare shortcode. Stating a system selects that exact target: `[[macro-autoattack|Text]]` reaches the readable note, and `[[none-macro-autoattack|Text]]` reaches the Macro. An embed offers asset targets and can reach an icon with `![[icon-anvil|Anvil]]`.
+
+The text edit inserts the shortest Address that parses to the selected target at the cursor. A local game system document can require `sohl-being-bctrncml`, while a target in another package requires a fully qualified Address. A `[[...#` query completes anchors from the selected note. Completion in a declared frontmatter Address field uses that field's type and system defaults: image, icon, and folder fields use `none`; other fields use their game system block or `note` outside one. Explicit system segments keep their stated meaning. Input `doc<type>` aliases select readable note records; generated records and completion candidates use the authored type.
+
+The server reads open buffer text to locate the cursor and replacement range. Candidate metadata comes from the saved JSONL index; unsaved frontmatter changes do not add candidates. Completion preserves closing brackets immediately after the cursor and ignores positions within existing display text. A missing foreign index is reported through the usual LSP status message while other indexed projects remain available.
+
 ## Foreign content projects
 
 An LSP client selects foreign project roots through `initialize`:
@@ -39,8 +59,21 @@ An LSP client selects foreign project roots through `initialize`:
 
 The paths name repositories containing their own `package-build.config.yaml`, `.yml`, or `.mjs`. They are editor search configuration, independent of a package's build dependencies. The server validates each foreign project's private index when first used and rebuilds it from saved source if missing or incompatible. A valid complete cache is reusable. An unconfigured cache never adds a project to search. A failed foreign root produces an LSP status message while available projects remain searchable. Save and file-operation notifications refresh the affected project. Clients can update the root list with `workspace/didChangeConfiguration` using `settings.heroiclands.foreignRoots`.
 
-Plain `workspace/symbol` queries search the current project. Prefix the query with `all:` to include configured foreign projects; `all:tag:myth` searches tags in that scope. Results name the owning package and open its source note. Package-qualified definitions open a note or asset from its owning root. A bare Address with matches in multiple configured projects returns all destinations for the client to present. `textDocument/references` searches the current and configured foreign projects and reports exact saved source ranges.
+Plain `workspace/symbol` queries search names, aliases, shortcodes, and Addresses in the current project. The query prefixes below narrow matches using saved JSONL records. Searches do not read unsaved frontmatter or scan Markdown files.
+
+| Query                         | Matches                                                         |
+| ----------------------------- | --------------------------------------------------------------- |
+| `name:alyra`                  | Full names and aliases, including their ASCII forms             |
+| `shortcode:alpha`             | Shortcodes                                                      |
+| `type:lore`                   | Note types                                                      |
+| `tag:myth`                    | Tags                                                            |
+| `all:camel`                   | Ordinary matches in the current and configured foreign projects |
+| `all:type:lore`               | A field filter across those projects                            |
+| `package:thalorna`            | All indexed notes in that configured package                    |
+| `package:thalorna name:camel` | A field filter within that package                              |
+
+`package:` selects the current project or an explicitly configured foreign project by its exact package name. It does not discover other caches or add a build dependency. A missing package or an unknown prefix returns no results. An empty unqualified query lists the current project's notes; an incomplete `name:`, `shortcode:`, `type:`, or `package:` query returns no results. Results name the owning package and open its source note. Package-qualified definitions open a note or asset from its owning root. A bare Address uses the citing project's package default. `textDocument/references` searches the current and configured foreign projects and reports exact saved source ranges.
 
 ## Editor integration
 
-An LSP client starts the executable with the content project as its working directory and associates it with Markdown notes under the configured content directory. The process handles `initialize`, `shutdown`, `exit`, full and incremental document synchronization, save and file-operation notifications, configuration changes, definition, references, and workspace symbols. It does not advertise completion, diagnostics, rename, or document symbols. An editor integration supplies its own installation, project discovery, and UI commands.
+An LSP client starts the executable with the content project as its working directory and associates it with Markdown notes under the configured content directory. The process handles `initialize`, `shutdown`, `exit`, full and incremental document synchronization, save and file-operation notifications, configuration changes, definition, completion, references, diagnostics, and workspace symbols. It does not advertise rename or document symbols. An editor integration supplies its own installation, project discovery, and UI commands.

package/engine/content-language-server.mjs

@@ -9,21 +9,27 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import YAML from "yaml";
 import { parseAddress, renderAddress } from "@heroiclands/package-build/engine/address";
 import { addressPositions } from "@heroiclands/package-build/engine/note-addresses";
-import { parseWikilink, WIKILINK } from "@heroiclands/package-build/engine/wikilink-syntax";
+import {
+    linkFindingMessage,
+    parseWikilink,
+    WIKILINK,
+} from "@heroiclands/package-build/engine/wikilink-syntax";
 import {
     CONFIG_FILENAMES,
     configFromData,
     loadPackConfig,
 } from "@heroiclands/package-build/engine/pack-config";
 import { noteFile } from "@heroiclands/package-build/engine/index-records";
+import { asciiName } from "@heroiclands/package-build/engine/content-index";
 import { NOTE_VOCABULARY } from "@heroiclands/package-build/engine/note-vocabulary";
 import {
     languageIndexDirectory,
     readLanguageIndex,
     rebuildLanguageIndex,
 } from "./content-language-index.mjs";
-import { matchAllOutsideCode } from "@heroiclands/package-build/engine/code-fences";
+import { codeRegions, matchAllOutsideCode } from "@heroiclands/package-build/engine/code-fences";
 import { embedsIn, EMBED_DEFAULT_TYPE } from "@heroiclands/package-build/engine/content-embeds";
+import { ASSET_TYPE_NAMES } from "@heroiclands/package-build/engine/asset-types";
 
 const EMPTY_RANGE = { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } };
 const require = createRequire(import.meta.url);
@@ -71,11 +77,78 @@ function noteName(record) {
     return typeof record.name === "string" ? record.name : (record.name?.full ?? record.shortcode);
 }
 
+/** Use the index generator's transliteration for both saved fields and typed queries. */
+function searchKey(value) {
+    return typeof value === "string" ? (asciiName(value) ?? "").toLowerCase() : "";
+}
+
+/** Parse editor symbol filters without looking outside configured projects. */
+function symbolQuery(query) {
+    let text = String(query ?? "").trim();
+    let includeForeign = false;
+    if (/^all:/i.test(text)) {
+        includeForeign = true;
+        text = text.slice(4).trim();
+    }
+    let selectedPackage = null;
+    if (/^package:/i.test(text)) {
+        const selected = /^package:([^\s]+)(?:\s+(.*))?$/i.exec(text);
+        if (!selected) return null;
+        selectedPackage = selected[1].toLowerCase();
+        text = (selected[2] ?? "").trim();
+        includeForeign = true;
+    }
+    const prefix = /^([a-z]+):(.*)$/is.exec(text);
+    if (prefix && !["name", "shortcode", "type", "tag"].includes(prefix[1].toLowerCase()))
+        return null;
+    const field = prefix?.[1].toLowerCase() ?? "all";
+    const needle = (prefix ? prefix[2] : text).trim();
+    if (field !== "all" && field !== "tag" && !needle) return null;
+    return { includeForeign, selectedPackage, field, needle };
+}
+
+/** A completion item changes the Address text while its label remains readable. */
+function completionItem(label, detail, inserted, text, from, to, filterText) {
+    return {
+        label,
+        kind: 18,
+        detail,
+        filterText,
+        textEdit: {
+            range: { start: positionAt(text, from), end: positionAt(text, to) },
+            newText: inserted,
+        },
+    };
+}
+
+/** Ignore ordinary prose completion before loading any foreign project. */
+function mayCompleteAddress(text, offset) {
+    if (text == null || offset < 0) return false;
+    const bodyStart = text.match(/^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/)?.[0].length ?? 0;
+    if (offset < bodyStart) return true;
+    const lineStart = text.lastIndexOf("\n", offset - 1) + 1;
+    const lineEnd = text.indexOf("\n", offset);
+    const before = text.slice(lineStart, offset);
+    const open = before.lastIndexOf("[[");
+    const after = text.slice(offset, lineEnd < 0 ? text.length : lineEnd);
+    return (
+        open >= 0 &&
+        !before.slice(open + 2).includes("]]") &&
+        (!after.includes("]]") || after.startsWith("]]"))
+    );
+}
+
 /** An index read from the package's configured content tree. */
 export class ContentWorkspace {
     constructor(
         config = loadPackConfig(),
-        { cacheBase, onStatus = () => {}, loadProjectConfig = loadForeignConfig } = {},
+        {
+            cacheBase,
+            onStatus = () => {},
+            onDiagnostics = () => {},
+            onIndexChanged,
+            loadProjectConfig = loadForeignConfig,
+        } = {},
     ) {
         this.config = config;
         this.cacheBase = cacheBase;
@@ -87,9 +160,13 @@ export class ContentWorkspace {
         this.started = false;
         this.rebuildTimer = null;
         this.onStatus = onStatus;
+        this.onDiagnostics = onDiagnostics;
+        this.onIndexChanged = onIndexChanged ?? (() => this.publishOpenDiagnostics());
+        this.diagnosticTimers = new Map();
         this.records = [];
         this.byAddress = new Map();
         this.byFile = new Map();
+        this.searchKeys = new Map();
         this.types = new Set(Object.keys(NOTE_VOCABULARY));
         this.documents = new Map();
         this.foreignRoots = [];
@@ -125,6 +202,7 @@ export class ContentWorkspace {
                 if (message) this.onStatus(config.contentPackage + ": " + message);
             },
             loadProjectConfig: this.loadProjectConfig,
+            onIndexChanged: () => this.publishOpenDiagnostics(),
         });
         project.documents = this.documents;
         this.foreign.set(root, project);
@@ -132,13 +210,21 @@ export class ContentWorkspace {
     }
 
     /** Return usable indexes, reporting one failed root without hiding the others. */
-    indexedWorkspaces(includeForeign = false) {
+    indexedWorkspaces(includeForeign = false, selectedPackage = null) {
         this.requireIndex();
-        const projects = [this];
+        const projects =
+            selectedPackage && this.config.contentPackage.toLowerCase() !== selectedPackage ?
+                []
+            :   [this];
         if (includeForeign)
             for (const root of this.foreignRoots) {
                 try {
                     const project = this.foreignWorkspace(root);
+                    if (
+                        selectedPackage &&
+                        project.config.contentPackage.toLowerCase() !== selectedPackage
+                    )
+                        continue;
                     project.start(true);
                     project.requireIndex();
                     projects.push(project);
@@ -152,16 +238,17 @@ export class ContentWorkspace {
     /** Find every indexed owner of a written Address for navigation. */
     resolveCandidates(value, defaults = {}, projects = [this]) {
         const packages = new Set(projects.map((project) => project.config.contentPackage));
+        const tuple = parseAddress(value, {
+            package: this.config.contentPackage,
+            system: "note",
+            types: new Set(projects.flatMap((project) => [...project.types])),
+            packages,
+            ...defaults,
+        });
+        if (tuple.reason) return [];
         const found = [];
         for (const project of projects) {
-            const tuple = parseAddress(value, {
-                package: project.config.contentPackage,
-                system: "none",
-                types: project.types,
-                packages,
-                ...defaults,
-            });
-            if (tuple.reason) continue;
+            if (project.config.contentPackage !== tuple.package) continue;
             const record = project.byAddress.get(renderAddress(tuple));
             if (record) found.push({ record, project });
         }
@@ -223,12 +310,14 @@ export class ContentWorkspace {
         const records = readLanguageIndex(this.cacheDirectory, this.config.contentPackage);
         this.loadRecords(records);
         this.indexState = state;
+        this.onIndexChanged();
         return true;
     }
 
     loadRecords(records) {
         const byAddress = new Map();
         const byFile = new Map();
+        const searchKeys = new Map();
         const types = new Set(Object.keys(NOTE_VOCABULARY));
         for (const record of records) {
             if (record.type) types.add(record.type);
@@ -238,10 +327,26 @@ export class ContentWorkspace {
                 const file = noteFile(this.contentRoot, record);
                 if (!byFile.has(file)) byFile.set(file, record);
             }
+            searchKeys.set(record, [
+                ...new Set(
+                    [
+                        noteName(record),
+                        record.nameAscii,
+                        ...(record.name?.aliases ?? []),
+                        ...(record.aliasesAscii ?? []),
+                        record.shortcode,
+                        record.address?.slug,
+                        record.address?.canonical,
+                    ]
+                        .map(searchKey)
+                        .filter(Boolean),
+                ),
+            ]);
         }
         this.records = records;
         this.byAddress = byAddress;
         this.byFile = byFile;
+        this.searchKeys = searchKeys;
         this.types = types;
     }
 
@@ -252,6 +357,7 @@ export class ContentWorkspace {
             const stat = fs.statSync(path.join(this.cacheDirectory, "metadata.json"));
             this.indexState = `${stat.mtimeMs}:${stat.size}`;
             this.onStatus(null);
+            this.onIndexChanged();
             return true;
         } catch (error) {
             let stale = this.records.length > 0;
@@ -292,6 +398,8 @@ export class ContentWorkspace {
     close() {
         if (this.rebuildTimer) clearTimeout(this.rebuildTimer);
         this.rebuildTimer = null;
+        for (const timer of this.diagnosticTimers.values()) clearTimeout(timer);
+        this.diagnosticTimers.clear();
         for (const project of this.foreign.values()) project.close();
     }
 
@@ -328,7 +436,7 @@ export class ContentWorkspace {
     resolve(value, defaults = {}, projects = [this]) {
         const tuple = parseAddress(value, {
             package: this.config.contentPackage,
-            system: "none",
+            system: "note",
             types: new Set(projects.flatMap((project) => [...project.types])),
             packages: new Set(projects.map((project) => project.config.contentPackage)),
             ...defaults,
@@ -342,22 +450,233 @@ export class ContentWorkspace {
         return null;
     }
 
+    /** Spell TARGET with the shortest suffix that resolves to that exact indexed owner. */
+    shortestAddress(target, owner, defaults, projects) {
+        const canonical = target.address?.canonical?.toLowerCase();
+        if (!canonical) return null;
+        const parts = canonical.split("-");
+        if (parts.length !== 4) return null;
+        const suffixes = [
+            ...(defaults.type ? [parts[3]] : []),
+            parts.slice(2).join("-"),
+            parts.slice(1).join("-"),
+            canonical,
+        ];
+        const vocabulary = {
+            package: this.config.contentPackage,
+            system: defaults.system ?? "note",
+            type: defaults.type,
+            types: new Set(projects.flatMap((project) => [...project.types])),
+            packages: new Set(projects.map((project) => project.config.contentPackage)),
+        };
+        for (const written of suffixes) {
+            const tuple = parseAddress(written, vocabulary);
+            if (tuple.reason || renderAddress(tuple) !== canonical) continue;
+            const owners = projects.filter((project) => project.byAddress.has(canonical));
+            if (owners.length === 1 && owners[0] === owner) return written;
+        }
+        return null;
+    }
+
+    /** Complete an unfinished wikilink using saved metadata and open-buffer context. */
+    linkCompletion(text, offset, projects) {
+        const bodyStart = text.match(/^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/)?.[0].length ?? 0;
+        if (offset < bodyStart) return null;
+        const body = text.slice(bodyStart);
+        const bodyOffset = offset - bodyStart;
+        if (
+            codeRegions(body).some(
+                (region) => region.start <= bodyOffset && bodyOffset <= region.end,
+            )
+        )
+            return null;
+        const lineStart = text.lastIndexOf("\n", offset - 1) + 1;
+        const lineEnd = text.indexOf("\n", offset);
+        const before = text.slice(lineStart, offset);
+        const open = before.lastIndexOf("[[");
+        if (open < 0 || before.slice(open + 2).includes("]]")) return null;
+        const embed = open > 0 && before[open - 1] === "!";
+        const after = text.slice(offset, lineEnd < 0 ? text.length : lineEnd);
+        if (after.includes("]]") && !after.startsWith("]]")) return null;
+        const from = lineStart + open + 2;
+        const written = text.slice(from, offset);
+        if (written.includes("|") || written.includes("[") || written.includes("]")) return null;
+        const hash = written.indexOf("#");
+        const defaults = embed ? { system: "none", type: EMBED_DEFAULT_TYPE } : {};
+        if (hash < 0)
+            return {
+                kind: "address",
+                from,
+                to: offset,
+                query: written,
+                defaults,
+                accepts: embed ? [...ASSET_TYPE_NAMES] : null,
+            };
+        if (embed) return null;
+        const target = this.resolve(written.slice(0, hash), {}, projects);
+        if (!target) return null;
+        return {
+            kind: "anchor",
+            target,
+            from: from + hash + 1,
+            to: offset,
+            query: written.slice(hash + 1),
+        };
+    }
+
+    /** Find the declared Address scalar or key containing the cursor. */
+    frontmatterCompletion(text, offset) {
+        const header = /^---\r?\n/.exec(text)?.[0];
+        if (!header) return null;
+        const closing = /\r?\n---(?:\r?\n|$)/g;
+        closing.lastIndex = header.length;
+        const end = closing.exec(text)?.index;
+        if (end == null || offset < header.length || offset > end) return null;
+        const yamlText = text.slice(header.length, end);
+        let document;
+        let frontmatter;
+        try {
+            document = YAML.parseDocument(yamlText);
+            frontmatter = document.toJS();
+        } catch {
+            return null;
+        }
+        if (!frontmatter || typeof frontmatter !== "object") return null;
+        const cursor = offset - header.length;
+        let found = null;
+        const scalar = (node, position) => {
+            if (!YAML.isScalar(node) || !node.range || found) return;
+            let [start, finish] = node.range;
+            const raw = yamlText.slice(start, finish);
+            if (
+                (raw.startsWith('"') && raw.endsWith('"')) ||
+                (raw.startsWith("'") && raw.endsWith("'"))
+            ) {
+                start += 1;
+                finish -= 1;
+            }
+            if (cursor < start || cursor > finish) return;
+            found = {
+                kind: "address",
+                from: header.length + start,
+                to: header.length + finish,
+                query: yamlText.slice(start, cursor),
+                defaults: { system: position.system ?? "note", type: position.type },
+                accepts: position.accepts ?? (position.type ? [position.type] : null),
+            };
+        };
+        const visit = (node, segments, position) => {
+            if (!node || found) return;
+            if (segments.length) {
+                const [head, ...tail] = segments;
+                if (YAML.isMap(node))
+                    for (const pair of node.items)
+                        if (head === "*" || String(pair.key?.value) === String(head))
+                            visit(pair.value, tail, position);
+                if (YAML.isSeq(node))
+                    node.items.forEach((child, index) => {
+                        if (head === "*" || String(index) === String(head))
+                            visit(child, tail, position);
+                    });
+                return;
+            }
+            if (position.shape === "keys" && YAML.isMap(node))
+                for (const pair of node.items) scalar(pair.key, position);
+            else if (position.shape === "list" && YAML.isSeq(node))
+                for (const child of node.items) scalar(child, position);
+            else if (position.shape === "scalar-or-map" && YAML.isMap(node))
+                for (const pair of node.items) scalar(pair.value, position);
+            else scalar(node, position);
+        };
+        for (const position of addressPositions(frontmatter, this.config)) {
+            visit(document.contents, position.path, position);
+            if (found) break;
+        }
+        return found;
+    }
+
+    completion(uri, position, projects = [this]) {
+        const text = this.text(uri);
+        if (text == null) return [];
+        const offset = offsetAt(text, position);
+        if (offset < 0) return [];
+        const context =
+            this.linkCompletion(text, offset, projects) ?? this.frontmatterCompletion(text, offset);
+        if (!context) return [];
+        const needle = searchKey(context.query);
+        if (context.kind === "anchor")
+            return (context.target.anchors ?? [])
+                .filter((anchor) => searchKey(`${anchor.slug} ${anchor.name}`).includes(needle))
+                .map((anchor) =>
+                    completionItem(
+                        anchor.slug,
+                        anchor.name,
+                        anchor.slug,
+                        text,
+                        context.from,
+                        context.to,
+                        context.query,
+                    ),
+                );
+        const items = [];
+        const seen = new Set();
+        for (const project of projects)
+            for (const record of project.records) {
+                const canonical = record.address?.canonical?.toLowerCase();
+                if (!canonical || project.byAddress.get(canonical) !== record) continue;
+                if (seen.has(canonical)) continue;
+                if (
+                    context.accepts &&
+                    !context.accepts.some(
+                        (accepted) => record.type === accepted || record.type === `doc${accepted}`,
+                    )
+                )
+                    continue;
+                if (!(project.searchKeys.get(record) ?? []).some((key) => key.includes(needle)))
+                    continue;
+                const inserted = this.shortestAddress(record, project, context.defaults, projects);
+                if (!inserted) continue;
+                seen.add(canonical);
+                items.push(
+                    completionItem(
+                        `${noteName(record)} — ${canonical}`,
+                        `${record.package} · ${canonical}`,
+                        inserted,
+                        text,
+                        context.from,
+                        context.to,
+                        context.query,
+                    ),
+                );
+            }
+        return items.sort((a, b) => a.label.localeCompare(b.label));
+    }
+
     /** Link and declared frontmatter targets, with exact source ranges. */
-    referencesInText(text, file, projects = [this], includeFrontmatter = true) {
+    referencesInText(
+        text,
+        file,
+        projects = [this],
+        includeFrontmatter = true,
+        includeUnresolved = false,
+    ) {
         const found = [];
         const bodyStart = text.match(/^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/)?.[0].length ?? 0;
         const linkText = text.slice(bodyStart);
         for (const match of matchAllOutsideCode(linkText, new RegExp(WIKILINK.source, "g"))) {
+            if (match.index > 0 && linkText[match.index - 1] === "!") continue;
             const parsed = parseWikilink(match[1]);
             const record =
                 parsed.target ? this.resolve(parsed.target, {}, projects) : this.byFile.get(file);
-            if (!record) continue;
+            if (!record && !includeUnresolved) continue;
             const start = bodyStart + match.index + (parsed.target ? 2 : 3);
             found.push({
                 record,
                 anchor: parsed.anchor,
                 written: parsed.target,
                 defaults: {},
+                kind: "link",
+                labelled: parsed.labelled,
                 location: location(
                     file,
                     text,
@@ -367,15 +686,17 @@ export class ContentWorkspace {
             });
         }
         for (const embed of embedsIn(linkText)) {
-            const defaults = { type: EMBED_DEFAULT_TYPE };
+            const defaults = { system: "none", type: EMBED_DEFAULT_TYPE };
             const record = this.resolve(embed.written, defaults, projects);
-            if (!record) continue;
+            if (!record && !includeUnresolved) continue;
             const start = bodyStart + embed.index + 3;
             found.push({
                 record,
                 anchor: "",
                 written: embed.written,
                 defaults,
+                kind: "embed",
+                labelled: embed.labelled,
                 location: location(file, text, start, start + embed.written.length),
             });
         }
@@ -411,17 +732,19 @@ export class ContentWorkspace {
             const scalar = (part, value) => {
                 if (!YAML.isScalar(part) || typeof value !== "string" || !part.range) return;
                 const defaults = {
-                    system: position.system ?? "none",
+                    system: position.system ?? "note",
                     type: position.type,
                 };
                 const record = this.resolve(value, defaults, projects);
-                if (!record) return;
+                if (!record && !includeUnresolved) return;
                 const start = yamlStart + part.range[0];
                 found.push({
                     record,
                     anchor: "",
                     written: value,
                     defaults,
+                    kind: "frontmatter",
+                    accepts: position.accepts,
                     location: location(file, text, start, yamlStart + part.range[1]),
                 });
             };
@@ -435,11 +758,133 @@ export class ContentWorkspace {
                 scalar(node, node.value);
             }
         };
-        for (const position of addressPositions(frontmatter))
+        for (const position of addressPositions(frontmatter, this.config))
             visit(document.contents, position.path, position);
         return found;
     }
 
+    /** Validate complete references using live ranges and saved target metadata. */
+    diagnostics(uri) {
+        const text = this.text(uri);
+        if (text == null) return [];
+        let projects;
+        let localIndexAvailable = true;
+        try {
+            projects = this.indexedWorkspaces(true);
+        } catch {
+            projects = [this];
+            localIndexAvailable = false;
+        }
+        const source = this.sourceWorkspace(uri, projects);
+        const declarations = ["systems", "requires", "recommends"]
+            .flatMap((key) => source.config.relationships?.[key] ?? [])
+            .map((entry) => [entry.contentPackage ?? entry.id, entry]);
+        const dependencies = new Map(declarations);
+        const available = new Set(projects.map((project) => project.config.contentPackage));
+        if (!localIndexAvailable) available.delete(this.config.contentPackage);
+        const types = new Set(projects.flatMap((project) => [...project.types]));
+        const candidates = source.referencesInText(text, fileURLToPath(uri), projects, true, true);
+        const diagnostics = [];
+        for (const candidate of candidates) {
+            const { written, defaults, record, anchor, kind, accepts, labelled } = candidate;
+            const target = written || `#${anchor}`;
+            let reason = null;
+            let message = null;
+            let severity = 1;
+            if (kind !== "frontmatter" && !labelled) reason = "unlabelled";
+            else {
+                const tuple =
+                    written ?
+                        parseAddress(
+                            written,
+                            {
+                                package: source.config.contentPackage,
+                                system: defaults.system ?? "note",
+                                type: defaults.type,
+                                types,
+                            },
+                            { declared: true },
+                        )
+                    :   null;
+                const targetPackage = tuple?.package ?? source.config.contentPackage;
+                const dependency = dependencies.get(targetPackage);
+                if (tuple?.reason)
+                    reason =
+                        ["unknown-type", "not-lowercase"].includes(tuple.reason) ?
+                            tuple.reason
+                        :   "not-an-address";
+                else if (targetPackage !== source.config.contentPackage && !dependency)
+                    message = `Address ${target} names ${targetPackage}, which is not a declared content dependency`;
+                else if (dependency?.contentIndex === false) reason = "no-content-index";
+                else if (!available.has(targetPackage)) {
+                    severity = 2;
+                    message = `Content index for ${targetPackage} is unavailable; ${target} cannot be checked`;
+                } else if (!record) reason = "unresolved";
+                else if (kind === "embed" && !ASSET_TYPE_NAMES.has(record.type))
+                    reason = "not-an-asset";
+                else if (
+                    accepts?.length &&
+                    !accepts.some((type) => record.type === type || record.type === `doc${type}`)
+                )
+                    message = `Address ${target} targets ${record.type}, but this field accepts ${accepts.join(", ")}`;
+                else if (
+                    kind === "frontmatter" &&
+                    !accepts?.length &&
+                    defaults.type &&
+                    record.type !== defaults.type
+                )
+                    message = `Address ${target} targets ${record.type}, but this field accepts ${defaults.type}`;
+                else if (
+                    anchor &&
+                    !record.anchors?.some(
+                        (entry) => entry.slug.toLowerCase() === anchor.toLowerCase(),
+                    )
+                )
+                    reason = "unknown-anchor";
+            }
+            if (reason)
+                message = linkFindingMessage({
+                    reason,
+                    target,
+                    anchor,
+                    type: record?.type,
+                });
+            if (message)
+                diagnostics.push({
+                    range: candidate.location.range,
+                    severity,
+                    source: "heroiclands",
+                    message,
+                });
+        }
+        return diagnostics.sort(
+            (a, b) =>
+                a.range.start.line - b.range.start.line ||
+                a.range.start.character - b.range.start.character,
+        );
+    }
+
+    scheduleDiagnostics(uri) {
+        if (this.diagnosticTimers.has(uri)) clearTimeout(this.diagnosticTimers.get(uri));
+        this.diagnosticTimers.set(
+            uri,
+            setTimeout(() => {
+                this.diagnosticTimers.delete(uri);
+                if (this.documents.has(uri)) this.onDiagnostics(uri, this.diagnostics(uri));
+            }, 300),
+        );
+    }
+
+    publishOpenDiagnostics() {
+        for (const uri of this.documents.keys()) this.scheduleDiagnostics(uri);
+    }
+
+    clearDiagnostics(uri) {
+        if (this.diagnosticTimers.has(uri)) clearTimeout(this.diagnosticTimers.get(uri));
+        this.diagnosticTimers.delete(uri);
+        this.onDiagnostics(uri, []);
+    }
+
     targetAt(uri, position, projects = [this]) {
         const text = this.text(uri);
         if (text == null) return null;
@@ -501,33 +946,36 @@ export class ContentWorkspace {
     }
 
     symbols(query) {
-        const includeForeign = /^all:/i.test(query);
-        const search = includeForeign ? query.slice(4) : query;
-        return this.indexedWorkspaces(includeForeign).flatMap((project) =>
-            project.symbolMatches(search),
+        const filter = symbolQuery(query);
+        if (!filter) return [];
+        return this.indexedWorkspaces(filter.includeForeign, filter.selectedPackage).flatMap(
+            (project) => project.symbolMatches(filter),
         );
     }
 
-    symbolMatches(query) {
-        const tag = /^tag:(.*)$/i.exec(query);
-        const needle = (tag ? tag[1] : query).trim().toLowerCase();
+    symbolMatches({ field, needle }) {
+        const normalized = field === "name" ? searchKey(needle) : needle.toLowerCase();
         const found = new Map();
         for (const record of this.records) {
             if (!record.file?.path) continue;
+            const names = [
+                record.name?.full,
+                record.nameAscii,
+                ...(record.name?.aliases ?? []),
+                ...(record.aliasesAscii ?? []),
+            ];
             const values =
-                tag ?
-                    (record.tags ?? [])
-                :   [
-                        record.name?.full,
-                        record.nameAscii,
-                        ...(record.name?.aliases ?? []),
-                        ...(record.aliasesAscii ?? []),
-                        record.shortcode,
-                        record.address?.slug,
-                        record.address?.canonical,
-                    ];
+                field === "tag" ? (record.tags ?? [])
+                : field === "name" ? names
+                : field === "shortcode" ? [record.shortcode]
+                : field === "type" ? [record.type]
+                : [...names, record.shortcode, record.address?.slug, record.address?.canonical];
             const match = values.find(
-                (value) => typeof value === "string" && value.toLowerCase().includes(needle),
+                (value) =>
+                    typeof value === "string" &&
+                    (field === "name" ? searchKey(value) : value.toLowerCase()).includes(
+                        normalized,
+                    ),
             );
             if (!match) continue;
             const file = noteFile(this.contentRoot, record);
@@ -535,7 +983,7 @@ export class ContentWorkspace {
             found.set(file, {
                 name: String(noteName(record)),
                 kind: 1,
-                containerName: `${record.package} · ${record.address?.slug ?? [record.type, record.shortcode].filter(Boolean).join(" ")} · ${tag ? `tag: ${match}` : match}`,
+                containerName: `${record.package} · ${record.address?.slug ?? [record.type, record.shortcode].filter(Boolean).join(" ")} · ${field === "tag" ? `tag: ${match}` : match}`,
                 location: { uri: pathToFileURL(file).href, range: EMPTY_RANGE },
             });
         }
@@ -610,6 +1058,7 @@ export function respond(workspace, message) {
                     positionEncoding: "utf-16",
                     textDocumentSync: { openClose: true, change: 2, save: true },
                     definitionProvider: true,
+                    completionProvider: { triggerCharacters: ["[", "#", "-"] },
                     referencesProvider: true,
                     workspaceSymbolProvider: true,
                     workspace: {
@@ -627,9 +1076,11 @@ export function respond(workspace, message) {
         case "workspace/didChangeConfiguration":
             if (params.settings?.heroiclands?.foreignRoots)
                 workspace.configureForeignRoots(params.settings.heroiclands.foreignRoots);
+            workspace.publishOpenDiagnostics();
             return undefined;
         case "textDocument/didOpen":
             workspace.documents.set(params.textDocument.uri, params.textDocument.text);
+            workspace.scheduleDiagnostics(params.textDocument.uri);
             return undefined;
         case "textDocument/didChange": {
             const uri = params.textDocument.uri;
@@ -643,13 +1094,16 @@ export function respond(workspace, message) {
                 }
             }
             workspace.documents.set(uri, text);
+            workspace.scheduleDiagnostics(uri);
             return undefined;
         }
         case "textDocument/didClose":
             workspace.documents.delete(params.textDocument.uri);
+            workspace.clearDiagnostics(params.textDocument.uri);
             return undefined;
         case "textDocument/didSave":
             workspace.scheduleRebuildForUri(params.textDocument.uri);
+            workspace.scheduleDiagnostics(params.textDocument.uri);
             return undefined;
         case "workspace/didChangeWatchedFiles":
         case "workspace/didCreateFiles":
@@ -664,6 +1118,13 @@ export function respond(workspace, message) {
         }
         case "textDocument/definition":
             return workspace.definition(params.textDocument.uri, params.position);
+        case "textDocument/completion": {
+            const text = workspace.text(params.textDocument.uri);
+            if (!mayCompleteAddress(text, offsetAt(text ?? "", params.position))) return [];
+            const projects = workspace.indexedWorkspaces(true);
+            const source = workspace.sourceWorkspace(params.textDocument.uri, projects);
+            return source.completion(params.textDocument.uri, params.position, projects);
+        }
         case "textDocument/references":
             return workspace.references(params.textDocument.uri, params.position);
         case "workspace/symbol":
@@ -693,6 +1154,12 @@ export function runLanguageServer(
                 params: { type: 1, message: status },
             });
     };
+    workspace.onDiagnostics = (uri, diagnostics) =>
+        send({
+            jsonrpc: "2.0",
+            method: "textDocument/publishDiagnostics",
+            params: { uri, diagnostics },
+        });
     input.on("data", (chunk) => {
         pending = Buffer.concat([pending, chunk]);
         while (true) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/content-language-server",
-    "version": "0.1.1",
+    "version": "0.2.1",
     "description": "Language server for HeroicLands content projects",
     "license": "GPL-3.0-or-later",
     "type": "module",
@@ -21,7 +21,7 @@
         "changeset:version": "changeset version && npm install --package-lock-only"
     },
     "dependencies": {
-        "@heroiclands/package-build": "22.12.3",
+        "@heroiclands/package-build": "22.14.4",
         "yaml": "^2.8.1"
     },
     "devDependencies": {