@valbuild/language-server 0.102.0 → 0.103.0

package/dist/declarations/src/completions.d.ts

@@ -6,26 +6,30 @@ import type { PublicValFiles } from "./publicValFiles.js";
  * Completions for file and image references.
  *
  * Offers the files that actually exist under the project's files directory, and
- * — when the item is accepted — fills in the metadata argument by reading the
+ * — when the item is accepted — fills in the metadata siblings by reading the
  * chosen file. Getting width/height/mimeType right by hand is tedious and a
  * frequent source of the very validation errors this server reports.
  */
 /** Stashed on the item so `resolve` can do the expensive work lazily. */
 export type ValCompletionItemData = {
-    kind: "file-ref";
+    kind: "media-path";
     uri: string;
     /** Val-style ref of the chosen file. */
     ref: string;
     /** Absolute path of the chosen file. */
     filePath: string;
-    subType: "image" | "file";
-    /** Where a metadata argument goes, or what it replaces. */
+    mediaType: "image" | "file";
     /**
-     * Start offset of the reference argument, used to re-find the call at resolve
+     * True when the field is backed by a gallery, in which case the dimensions
+     * and mime type live there and must not be written here too.
+     */
+    gallery: boolean;
+    /**
+     * Start offset of the `path` value, used to re-find its object at resolve
      * time. Offsets captured now cannot be replayed later: see
-     * {@link findFileRefArgument}.
+     * {@link findMediaPathObject}.
      */
-    refArgStart: number;
+    pathValueStart: number;
 };
 export declare function createValCompletions({ document, offset, files, moduleFilePath, snapshot, }: {
     document: TextDocument;
@@ -37,7 +41,7 @@ export declare function createValCompletions({ document, offset, files, moduleFi
     snapshot?: SchemaSourceSnapshot;
 }): CompletionItem[];
 /**
- * Fill in the metadata argument for an accepted file reference.
+ * Fill in the metadata siblings for an accepted media path.
  *
  * Done at resolve time because it reads the file from disk, and an editor
  * requests completions far more often than it accepts one.

package/dist/declarations/src/diagnostics.d.ts

@@ -1,4 +1,4 @@
-import { type ModuleFilePath, type ValidationFix } from "@valbuild/core";
+import { type ModuleFilePath, type SourcePath, type ValidationError, type ValidationFix } from "@valbuild/core";
 import { type SchemaSourceSnapshot } from "@valbuild/shared/internal";
 import { Diagnostic, DiagnosticSeverity } from "vscode-languageserver";
 import type { ValModuleContent } from "./ValProject.js";
@@ -17,7 +17,7 @@ export declare const VAL_DIAGNOSTIC_SOURCE = "val";
  * vocabulary. A diagnostic says what is wrong; a fix says what can be done
  * about it, and travels in {@link ValDiagnosticData.fixes}.
  */
-export declare const VAL_DIAGNOSTIC_CODES: readonly ["val/validation", "val/schema", "val/fatal", "val/file-not-found", "val/missing-module"];
+export declare const VAL_DIAGNOSTIC_CODES: readonly ["val/validation", "val/schema", "val/fatal", "val/file-not-found", "val/missing-module", "val/gallery-membership"];
 export type ValDiagnosticCode = (typeof VAL_DIAGNOSTIC_CODES)[number];
 /**
  * Structured payload attached to every Val diagnostic.
@@ -41,6 +41,20 @@ export type ValDiagnosticData = {
     value?: unknown;
     /** Absolute path of the missing file, for `val/file-not-found`. */
     filePath?: string;
+    /**
+     * Where the gallery is and what the field points at, for `val/gallery-membership`.
+     * Carried here so a code action does not have to re-resolve the schema, and so
+     * a client could show it.
+     */
+    gallery?: GalleryMembership;
+    /**
+     * The path to hand `createFixPatch`, when it differs from
+     * {@link ValDiagnosticData.sourcePath}.
+     *
+     * Only the gallery checks use this: they are reported on the entry that is
+     * wrong but fixed against the record that contains it.
+     */
+    fixSourcePath?: string;
 };
 /**
  * Severity policy, in one place.
@@ -59,7 +73,7 @@ export declare function severityFor({ code, fixes, }: {
     code: ValDiagnosticCode;
     fixes?: ValidationFix[];
 }): DiagnosticSeverity;
-export declare function createValDiagnostics({ moduleFilePath, content, text, valRoot, snapshot, }: {
+export declare function createValDiagnostics({ moduleFilePath, content, text, valRoot, snapshot, galleryChecks, }: {
     moduleFilePath: ModuleFilePath;
     content: ValModuleContent;
     /** Current text of the module, as the editor sees it. */
@@ -80,6 +94,13 @@ export declare function createValDiagnostics({ moduleFilePath, content, text, va
      * unactionable noise on correct code.
      */
     snapshot?: SchemaSourceSnapshot;
+    /**
+     * Verdicts for the gallery placeholders core emits unconditionally, from
+     * {@link resolveGalleryChecks}. Without it the placeholders are dropped: two
+     * permanent warnings on every gallery module is worse than a missed one, and
+     * the caller that can adjudicate them is the one that has a `Service`.
+     */
+    galleryChecks?: ReadonlyMap<string, GalleryCheckVerdict>;
 }): Diagnostic[];
 /**
  * Diagnostic for a project that could not be evaluated at all.
@@ -103,3 +124,86 @@ export declare function createProjectErrorDiagnostic({ moduleFilePath, message,
 export declare function createMissingModuleDiagnostic({ moduleFilePath, }: {
     moduleFilePath: ModuleFilePath;
 }): Diagnostic;
+export declare function isGalleryCheckFix(fix: string): boolean;
+/**
+ * One real problem found behind a gallery placeholder.
+ *
+ * A single placeholder can expand into several of these, each pointing at its
+ * own entry: `handleCheckAllFiles` reporting `shouldApplyPatch` means "no
+ * membership problem, now check the metadata", and `createFixPatch` then returns
+ * one error per entry whose stored metadata disagrees with its file. This is why
+ * the verdict is a list rather than a message, and why each carries its own
+ * source path.
+ */
+export type GalleryCheckFinding = {
+    /** Where to show it: the entry the problem is about. */
+    sourcePath: string;
+    message: string;
+    fixes?: ValidationFix[];
+    /**
+     * Where to *fix* it, when that is not where it is shown.
+     *
+     * The gallery fix is expressed against the record as a whole — it walks every
+     * entry — so `createFixPatch` must be given the record's path and the
+     * placeholder's value, while the diagnostic itself belongs on the offending
+     * entry. Splitting the two is what lets the message be precise without
+     * breaking the fix.
+     */
+    fixSourcePath?: string;
+    /** The placeholder's `value`, which the fix reads. */
+    value?: unknown;
+};
+/**
+ * The verdict on one gallery check. Empty means nothing is wrong and the
+ * placeholder is dropped.
+ */
+export type GalleryCheckVerdict = GalleryCheckFinding[];
+/**
+ * Adjudicate every gallery placeholder in `validation`, by running the same fix
+ * handler `val validate` runs.
+ *
+ * Async and therefore separate from {@link createValDiagnostics}, which stays
+ * synchronous so it can be tested without a project. The caller runs this first
+ * and passes the result in.
+ */
+export declare function resolveGalleryChecks({ validation, runHandler, }: {
+    validation: Record<SourcePath, ValidationError[]>;
+    /**
+     * Runs the fix handler for one error and reports what it found. Injected so
+     * that this module needs no `Service`, and so tests can drive both outcomes.
+     */
+    runHandler: (sourcePath: SourcePath, error: ValidationError) => Promise<GalleryCheckVerdict>;
+}): Promise<Map<string, GalleryCheckVerdict>>;
+/**
+ * Key for one placeholder. A gallery module carries several, all at the same
+ * source path, so the fix names have to be part of the key.
+ */
+export declare function galleryCheckKey(sourcePath: string, error: ValidationError): string;
+/**
+ * A gallery-backed field pointing at something the gallery does not have.
+ *
+ * `ImageSchema.validate` reports this (`packages/core/src/schema/image.ts`:
+ * "The gallery does not have an image at '…'") but attaches no `ValidationFix`,
+ * because the remedy is not a change to this module: either the gallery gains an
+ * entry, or the file moves into the gallery's directory. Both are edits to
+ * somewhere else, which is not what a `ValidationFix` describes.
+ *
+ * So the fix is built in the editor instead, and this is what it needs. Derived
+ * from the **schema**, not from the message: matching on message text would break
+ * the moment the wording changed, silently.
+ */
+export type GalleryMembership = {
+    /** Module path of the gallery this field points at. */
+    referencedModule: string;
+    /** The gallery's directory, when it declares one. */
+    directory?: string;
+    /** The path the field currently holds. */
+    path: string;
+    /** `image` or `file`, for wording and for which metadata to read. */
+    mediaType: "image" | "file";
+};
+export declare function galleryMembershipAt({ sourcePath, content, snapshot, }: {
+    sourcePath: string;
+    content: ValModuleContent;
+    snapshot?: SchemaSourceSnapshot;
+}): GalleryMembership | undefined;

package/dist/declarations/src/galleryFixes.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The two remedies for a gallery-backed field pointing at something its gallery
+ * does not have.
+ *
+ * Core reports the problem (`packages/core/src/schema/image.ts`) and offers no
+ * `ValidationFix`, because neither remedy is a change to the module holding the
+ * field:
+ *
+ *  - **register it** — add an entry to the *gallery* module, keyed by the path,
+ *    carrying the metadata read from the file. An edit to another document.
+ *  - **move the file** — when the file is on disk but outside the gallery's
+ *    directory, move it there and update the path. A file rename plus an edit.
+ *
+ * Both used to be VS Code commands in the extension, driven by diagnostics the
+ * extension computed itself. They are here so that every editor gets them, and
+ * so that a change to how galleries work has one place to be reflected.
+ */
+import ts from "typescript";
+import { CodeAction } from "vscode-languageserver";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+import type { GalleryMembership } from "./diagnostics.js";
+/**
+ * Whether the client will honour a file rename inside a `WorkspaceEdit`.
+ *
+ * A `RenameFile` sent to a client that did not announce `resourceOperations`
+ * is silently dropped, which would leave the path rewritten and the file where it
+ * was — worse than not offering the fix.
+ */
+export declare function canRenameFiles(capabilities: unknown): boolean;
+export declare function createGalleryMembershipActions({ document, gallery, valRoot, read, allowRename, }: {
+    document: TextDocument;
+    gallery: GalleryMembership;
+    valRoot: string;
+    /** The editor's view of a file, falling back to disk. */
+    read: (fsPath: string) => string | undefined;
+    allowRename: boolean;
+}): Promise<CodeAction[]>;
+/**
+ * Where to insert into the record that is a gallery module's content -- the third
+ * argument of its `c.define(...)`.
+ */
+export declare function findRecordInsertion(sourceFile: ts.SourceFile): {
+    insertOffset: number;
+    indentation: string;
+    hasProperties: boolean;
+} | null;

package/dist/declarations/src/index.d.ts

@@ -2,11 +2,15 @@ export { main, createValLanguageServer, type ValSession } from "./server.js";
 export { getLanguageServerVersion } from "./version.js";
 export { createEditorFsHost, mapOpenDocuments, type OpenDocuments, } from "./EditorFsHost.js";
 export { createValProject, defaultCoreResolver, type CoreResolver, type ValProject, type ValProjectInitError, type ValModuleContent, } from "./ValProject.js";
-export { createValDiagnostics, createMissingModuleDiagnostic, createProjectErrorDiagnostic, severityFor, VAL_DIAGNOSTIC_SOURCE, VAL_DIAGNOSTIC_CODES, type ValDiagnosticCode, type ValDiagnosticData, } from "./diagnostics.js";
+export { createValDiagnostics, createMissingModuleDiagnostic, createProjectErrorDiagnostic, severityFor, VAL_DIAGNOSTIC_SOURCE, VAL_DIAGNOSTIC_CODES, type ValDiagnosticCode, type ValDiagnosticData, resolveGalleryChecks, isGalleryCheckFix, galleryCheckKey, type GalleryCheckFinding, type GalleryCheckVerdict, galleryMembershipAt, type GalleryMembership, } from "./diagnostics.js";
 export { findRegisteredModuleSpecifiers, isModuleRegistered, } from "./valModulesRegistry.js";
-export { createValCodeActions, isLocalFix, minimalTextEdit, } from "./codeActions.js";
+export { createValCodeActions, createMissingModuleCodeAction, adjudicateGalleryCheck, isLocalFix, } from "./codeActions.js";
+export { minimalTextEdit } from "./textEdit.js";
+export { createValCommands, isRemoteFix, valCommandNames, readPersonalAccessToken, REMOTE_FIX_COMMANDS, REMOTE_FIX_TITLES, VAL_LOGIN_COMMAND, VAL_UPLOAD_REMOTE_COMMAND, VAL_DOWNLOAD_REMOTE_COMMAND, type RemoteFixCommandArgs, } from "./commands.js";
+export { findValModulesInsertion, valModuleSpecifier, valModulesEntryText, } from "./valModulesRegistry.js";
+export { canRenameFiles, createGalleryMembershipActions, findRecordInsertion, } from "./galleryFixes.js";
 export { createValCompletions, resolveValCompletion, type ValCompletionItemData, } from "./completions.js";
-export { getValCompletionContext, type ValCompletionContext, type ValFileRefContext, type ValStringValueContext, } from "./completionContext.js";
+export { getValCompletionContext, findMediaPathObject, MEDIA_METADATA_KEYS, type MediaMetadataKey, type MediaPathObject, type ValCompletionContext, type ValStringValueContext, } from "./completionContext.js";
 export { createPublicValFiles, DEFAULT_FILES_DIRECTORY, type PublicValFile, type PublicValFiles, } from "./publicValFiles.js";
 export { createModulePathMap, findModulePathAtPosition, getModulePathRange, type ModulePathMap, type ModulePathRange, type ModulePosition, } from "./modulePathMap.js";
 export { isValModuleUri, pathToUri, toModuleFilePath, uriToPath } from "./uri.js";

package/dist/declarations/src/textEdit.d.ts

@@ -0,0 +1,10 @@
+import type { TextEdit } from "vscode-languageserver";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+/**
+ * Narrow an edit down to the region that actually changed.
+ *
+ * A whole-document replacement would work, but it moves the cursor and shows up
+ * as a full-file change in review. Trimming the common prefix and suffix keeps
+ * the edit tight without needing a real diff algorithm.
+ */
+export declare function minimalTextEdit(before: string, after: string, document: TextDocument): TextEdit | undefined;

package/dist/declarations/src/valModulesRegistry.d.ts

@@ -30,3 +30,38 @@ export declare function isModuleRegistered({ sourceFile, valModulesDir, moduleFi
     valModulesDir: string;
     moduleFilePath: ModuleFilePath;
 }): boolean;
+/**
+ * Where to insert a new entry in a `val.modules` file, and how to indent it.
+ *
+ * Only `modules(config, [ … ])` is matched, because that is the shape Val
+ * actually accepts and the shape `examples/next/val.modules.ts` uses. The
+ * over-reporting rule in {@link findRegisteredModuleSpecifiers} is right for
+ * *reading* a file someone else wrote; writing into one has to commit to a
+ * shape, and guessing wrong produces a file that no longer compiles.
+ *
+ * Returns `null` when the array cannot be found — the caller then offers no fix
+ * rather than inserting somewhere arbitrary.
+ */
+export declare function findValModulesInsertion(sourceFile: ts.SourceFile): {
+    insertOffset: number;
+    indentation: string;
+    hasElements: boolean;
+} | null;
+/**
+ * The specifier to write for `moduleFilePath`, relative to the `val.modules`
+ * file that will hold it.
+ *
+ * Both paths are Val-style (root-relative, leading slash). POSIX separators
+ * always: the string ends up in an `import()` in source, where a backslash is an
+ * escape rather than a separator.
+ */
+export declare function valModuleSpecifier({ valModulesFilePath, moduleFilePath, }: {
+    valModulesFilePath: string;
+    moduleFilePath: ModuleFilePath;
+}): string;
+/** The text to insert for one new entry, including its separator. */
+export declare function valModulesEntryText({ specifier, indentation, hasElements, }: {
+    specifier: string;
+    indentation: string;
+    hasElements: boolean;
+}): string;