@valbuild/language-server 0.135.0 → 0.136.1

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @valbuild/language-server
 
+## 0.136.1
+
+### Patch Changes
+
+- Updated dependencies [[`e673b43`](https://github.com/valbuild/val/commit/e673b43feaf48b7f30881d6786c858a0cb6a44a2), [`5c82928`](https://github.com/valbuild/val/commit/5c82928992d29f133f81cf0704a273c0449b18f1), [`4450be5`](https://github.com/valbuild/val/commit/4450be570ec3a66d7d98ba273c333ca2d2f163d9), [`d2f385a`](https://github.com/valbuild/val/commit/d2f385a04978992a5036379235e447ba7775faef)]:
+  - @valbuild/shared@0.136.1
+  - @valbuild/server@0.136.1
+  - @valbuild/core@0.136.1
+
+## 0.136.0
+
+### Patch Changes
+
+- [#699](https://github.com/valbuild/val/pull/699) [`1d72d00`](https://github.com/valbuild/val/commit/1d72d00a1b036959ae0f1540121701cbb2694dcb) Thanks [@freekh](https://github.com/freekh)! - A `*.val.ts` with no default export is no longer reported as a missing module
+
+  `*.val.ts` is a naming convention, not a promise: plenty of files under it hold
+  only the schemas and helpers the modules beside them import. Every one of those
+  was getting two errors in the editor — `Module '…' was not found in
+val.modules` and `… is not registered in val.modules, so Val will not serve it`
+  — both on line 1, telling their author to register a file that has nothing to
+  register. `val validate` has never reported them; only the editor did.
+
+  The default export is what makes a `*.val.ts` a module, so that is what the
+  diagnostic now asks about:
+
+  - **No default export → nothing is reported.** The file is not a module, so it
+    is not a module Val is failing to serve.
+  - **A default export → one diagnostic, on the `export default` itself** rather
+    than on line 1, so it is next to the thing that has to change, and the
+    duplicate fatal beside it is gone. The message now gives both remedies: add
+    the file to `val.modules`, or export what it holds by name instead. The "Val:
+    register … in val.modules" quick fix is offered there.
+
+  The rule is `findDefaultExport` in `@valbuild/server`, which `val validate`
+  already used to decide the same question — so the editor and the CLI now agree
+  about which files are modules, including the cases that are easy to get wrong
+  (`export * from …` carries no default; `export type { T as default }` and
+  `export default interface T {}` are both gone after transpilation).
+
+  Because the diagnostic now replaces a module's own findings rather than adding
+  to them, the editor also stops guessing about registration it cannot read: a
+  `val.modules` that registers modules through a tsconfig path alias
+  (`import("_/content/page.val")`), or that builds its list in another file, is no
+  longer taken to register nothing.
+
+- Updated dependencies [[`f3a4bb7`](https://github.com/valbuild/val/commit/f3a4bb7aea604943b92545c122243798c759715c), [`1d72d00`](https://github.com/valbuild/val/commit/1d72d00a1b036959ae0f1540121701cbb2694dcb)]:
+  - @valbuild/core@0.136.0
+  - @valbuild/server@0.136.0
+  - @valbuild/shared@0.136.0
+
 ## 0.135.0
 
 ### Patch Changes

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

@@ -1,6 +1,6 @@
 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 { Diagnostic, DiagnosticSeverity, type Range } from "vscode-languageserver";
 import { type MediaCheckVerdict } from "./mediaChecks.js";
 import type { ValModuleContent } from "./ValProject.js";
 /** Marks diagnostics as ours, so a client can filter on it. */
@@ -130,9 +130,23 @@ export declare function createProjectErrorDiagnostic({ moduleFilePath, message,
  *
  * Val only serves modules listed there, so an unregistered module silently does
  * nothing — worth surfacing even though it is not a validation error.
+ *
+ * Reported on the `export default`, which is also why a file that has none gets
+ * no diagnostic at all (see `findValModuleDefinition`): the default export is
+ * the thing that makes a `*.val.ts` a module, so it is the thing being asked
+ * about, and pointing at line 1 of a file full of shared schemas asked its
+ * author to register something that does not exist.
+ *
+ * The message carries both remedies for the same reason. Only one of them is
+ * "add it to val.modules"; the other is to stop default-exporting, which is how
+ * a helper that landed in the module slot is fixed. Never "wrap it in
+ * `c.define`" — that turns it into an unregistered module, i.e. straight back
+ * to here.
  */
-export declare function createMissingModuleDiagnostic({ moduleFilePath, }: {
+export declare function createMissingModuleDiagnostic({ moduleFilePath, range, }: {
     moduleFilePath: ModuleFilePath;
+    /** The module's `export default`, from `findValModuleDefinition`. */
+    range: Range;
 }): Diagnostic;
 export declare function isGalleryCheckFix(fix: string): boolean;
 /**

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

@@ -20,6 +20,18 @@ export declare function findRegisteredModuleSpecifiers(sourceFile: ts.SourceFile
 /**
  * Whether `moduleFilePath` is registered by the given `val.modules` file.
  *
+ * Answers `true` whenever it cannot tell, which is the same safe direction
+ * {@link findRegisteredModuleSpecifiers} takes and matters more here than it
+ * looks: the caller publishes the missing-module diagnostic *instead of* the
+ * module's own diagnostics, so a false "unregistered" does not just add noise,
+ * it hides every real finding in the file. Two things it cannot tell:
+ *
+ *  - a `val.modules` with no dynamic imports at all, which is what a registry
+ *    that builds its list somewhere else looks like from here;
+ *  - a non-relative specifier naming a `.val` module (`_/content/page.val`),
+ *    which is a tsconfig path alias — a shape `loadValModules` resolves and
+ *    this file, having no compiler options, cannot.
+ *
  * @param valModulesDir directory containing the val.modules file, relative to
  *   the Val root (`""` when it sits at the root).
  * @param moduleFilePath the module's path, Val-style: root-relative, leading

package/dist/valbuild-language-server.cjs.dev.js

@@ -183,7 +183,7 @@ var packageJson = {
 		"lsp",
 		"language-server"
 	],
-	version: "0.135.0",
+	version: "0.136.1",
 	bin: {
 		"val-language-server": "./bin.js"
 	},
@@ -1627,11 +1627,24 @@ function createProjectErrorDiagnostic({
  *
  * Val only serves modules listed there, so an unregistered module silently does
  * nothing — worth surfacing even though it is not a validation error.
+ *
+ * Reported on the `export default`, which is also why a file that has none gets
+ * no diagnostic at all (see `findValModuleDefinition`): the default export is
+ * the thing that makes a `*.val.ts` a module, so it is the thing being asked
+ * about, and pointing at line 1 of a file full of shared schemas asked its
+ * author to register something that does not exist.
+ *
+ * The message carries both remedies for the same reason. Only one of them is
+ * "add it to val.modules"; the other is to stop default-exporting, which is how
+ * a helper that landed in the module slot is fixed. Never "wrap it in
+ * `c.define`" — that turns it into an unregistered module, i.e. straight back
+ * to here.
  */
 function createMissingModuleDiagnostic({
-  moduleFilePath
+  moduleFilePath,
+  range
 }) {
-  return build(FALLBACK_RANGE, `${moduleFilePath} is not registered in val.modules, so Val will not serve it.`, {
+  return build(range, `${moduleFilePath} is not registered in val.modules, so Val will not serve it. Add it there — or, if this file is not meant to be a Val module, export what it holds by name instead: a default export is what makes a *.val.ts a module.`, {
     code: "val/missing-module",
     sourcePath: moduleFilePath
   });
@@ -2243,6 +2256,18 @@ function findRegisteredModuleSpecifiers(sourceFile) {
 /**
  * Whether `moduleFilePath` is registered by the given `val.modules` file.
  *
+ * Answers `true` whenever it cannot tell, which is the same safe direction
+ * {@link findRegisteredModuleSpecifiers} takes and matters more here than it
+ * looks: the caller publishes the missing-module diagnostic *instead of* the
+ * module's own diagnostics, so a false "unregistered" does not just add noise,
+ * it hides every real finding in the file. Two things it cannot tell:
+ *
+ *  - a `val.modules` with no dynamic imports at all, which is what a registry
+ *    that builds its list somewhere else looks like from here;
+ *  - a non-relative specifier naming a `.val` module (`_/content/page.val`),
+ *    which is a tsconfig path alias — a shape `loadValModules` resolves and
+ *    this file, having no compiler options, cannot.
+ *
  * @param valModulesDir directory containing the val.modules file, relative to
  *   the Val root (`""` when it sits at the root).
  * @param moduleFilePath the module's path, Val-style: root-relative, leading
@@ -2254,11 +2279,23 @@ function isModuleRegistered({
   moduleFilePath
 }) {
   const target = stripValModuleExtension(moduleFilePath);
-  return findRegisteredModuleSpecifiers(sourceFile).some(specifier => {
+  const specifiers = findRegisteredModuleSpecifiers(sourceFile);
+  if (specifiers.length === 0) {
+    return true;
+  }
+  return specifiers.some(specifier => {
+    const stripped = stripValModuleExtension(specifier);
     // Specifiers are written relative to the val.modules file and normally omit
     // the extension ("./content/page.val").
-    const resolved = specifier.startsWith(".") ? path__default["default"].posix.normalize(path__default["default"].posix.join("/", valModulesDir, stripValModuleExtension(specifier))) : stripValModuleExtension(specifier);
-    return resolved === target;
+    if (specifier.startsWith(".")) {
+      return path__default["default"].posix.normalize(path__default["default"].posix.join("/", valModulesDir, stripped)) === target;
+    }
+    if (specifier.startsWith("/")) {
+      return stripped === target;
+    }
+    // A path alias, which needs the project's tsconfig to resolve. A bare
+    // package import is not one of these, so it stays a plain non-match.
+    return stripped.endsWith(".val");
   });
 }
 
@@ -3668,6 +3705,60 @@ function keysOfKeyOf(schema, snapshot) {
   }
 }
 
+/**
+ * Where a file declares its Val module, or `undefined` when it declares none.
+ *
+ * `*.val.ts` is a naming convention, not a guarantee: a file under it may hold
+ * nothing but the schemas and helpers the modules beside it import. The default
+ * export is what separates the two, and `findDefaultExport` in
+ * `@valbuild/server` is the one implementation of that rule — the same one
+ * `val validate` uses to decide whether an unregistered file is worth reporting
+ * at all. It is imported rather than reimplemented because the subtleties are
+ * not obvious (a star re-export carries no default, a type-only export is gone
+ * after transpilation), and two copies would answer differently the first time
+ * one of them was fixed.
+ *
+ * Only the `export default` keywords are returned, never the whole definition:
+ * a module's source is most of its file, and a diagnostic spanning that paints
+ * the file red.
+ */
+function findValModuleDefinition(sourceFile) {
+  const statement = server.findDefaultExport(sourceFile);
+  if (!statement) {
+    return undefined;
+  }
+  const start = statement.getStart(sourceFile);
+  return {
+    start: sourceFile.getLineAndCharacterOfPosition(start),
+    end: sourceFile.getLineAndCharacterOfPosition(keywordsEnd(sourceFile, statement, start))
+  };
+}
+
+/**
+ * The end of the `export default` a statement opens with.
+ *
+ * Three shapes reach this, and only the first two can be narrowed: `export
+ * default <expr>`, where everything before the expression is the keywords;
+ * `export default function f() {}` and `export default class C {}`, where they
+ * are modifiers; and `export { x as default }`, which has no `default` keyword
+ * to stop at and is short enough to underline whole.
+ */
+function keywordsEnd(sourceFile, statement, start) {
+  if (ts__default["default"].isExportAssignment(statement)) {
+    // Up to the exported expression is `export default` plus whitespace (and,
+    // rarely, a comment); trimming the tail keeps the underline on the keywords.
+    return start + sourceFile.text.slice(start, statement.expression.getStart(sourceFile)).trimEnd().length;
+  }
+  const defaultModifier = ts__default["default"].canHaveModifiers(statement) ? (ts__default["default"].getModifiers(statement) ?? []).find(modifier => modifier.kind === ts__default["default"].SyntaxKind.DefaultKeyword) : undefined;
+  return defaultModifier?.end ?? statement.end;
+}
+
+/** Parse a Val module's text the way {@link findValModuleDefinition} needs it. */
+function parseValModule(moduleFilePath, text) {
+  // Parent pointers: `getStart` walks them to skip leading trivia.
+  return ts__default["default"].createSourceFile(moduleFilePath, text, ts__default["default"].ScriptTarget.ES2020, true);
+}
+
 /**
  * The two remedies for a gallery-backed field pointing at something its gallery
  * does not have.
@@ -4127,15 +4218,14 @@ function applyEnvOverrides(options) {
 const PROJECT_WIDE_FILE_RE = /[/\\]val\.(modules|config)\.(ts|js)$/;
 
 /**
- * Report a Val module that `val.modules` does not register.
+ * Whether `val.modules` leaves this module out.
  *
  * Reads `val.modules.{ts,js}` on demand, through the editor's buffer when it is
  * open: adding a module to the registry must clear the diagnostic straight away,
- * not only once the user saves. Returns `undefined` when no such file exists —
- * that is a project-level problem, not something to blame on an individual
- * module.
+ * not only once the user saves. Answers `false` when no such file exists — that
+ * is a project-level problem, not something to blame on an individual module.
  */
-function findMissingModuleDiagnostic(valRoot, moduleFilePath, read) {
+function isModuleUnregistered(valRoot, moduleFilePath, read) {
   for (const candidate of ["val.modules.ts", "val.modules.js"]) {
     const file = path__default["default"].join(valRoot, candidate);
     let text = read(file);
@@ -4146,16 +4236,13 @@ function findMissingModuleDiagnostic(valRoot, moduleFilePath, read) {
         continue;
       }
     }
-    const registered = isModuleRegistered({
+    return !isModuleRegistered({
       sourceFile: ts__default["default"].createSourceFile(file, text, ts__default["default"].ScriptTarget.ES2020),
       valModulesDir: "",
       moduleFilePath
     });
-    return registered ? undefined : createMissingModuleDiagnostic({
-      moduleFilePath
-    });
   }
-  return undefined;
+  return false;
 }
 
 /**
@@ -4220,6 +4307,27 @@ function createValLanguageServer(connection) {
       return;
     }
     try {
+      // An unregistered file is answered from its own text alone, before the
+      // project is consulted at all. Val cannot have evaluated it -- it is not
+      // in the graph `val.modules` describes -- so everything downstream has
+      // only the one thing to say about it, and said it twice: `Service.get`
+      // reports `Module '...' was not found in val.modules` as a fatal on line
+      // 1, beside this diagnostic saying the same. And when the file has no
+      // `export default` neither of them is a finding at all: it is a
+      // `*.val.ts` holding the schemas the modules beside it import, which Val
+      // never serves and there is nothing to register.
+      const unregistered = isModuleUnregistered(project.valRoot, moduleFilePath, readOpenDocument);
+      if (unregistered) {
+        const definition = findValModuleDefinition(parseValModule(moduleFilePath, document.getText()));
+        connection.sendDiagnostics({
+          uri,
+          diagnostics: definition ? [createMissingModuleDiagnostic({
+            moduleFilePath,
+            range: definition
+          })] : []
+        });
+        return;
+      }
       // The module's own content changed, so any cached result is stale.
       project.invalidate(moduleFilePath);
       const result = await project.getModule(moduleFilePath);
@@ -4283,10 +4391,6 @@ function createValLanguageServer(connection) {
           mediaChecks
         } : {})
       });
-      const unregistered = findMissingModuleDiagnostic(project.valRoot, moduleFilePath, readOpenDocument);
-      if (unregistered) {
-        diagnostics.push(unregistered);
-      }
       connection.sendDiagnostics({
         uri,
         diagnostics

package/dist/valbuild-language-server.cjs.prod.js

@@ -183,7 +183,7 @@ var packageJson = {
 		"lsp",
 		"language-server"
 	],
-	version: "0.135.0",
+	version: "0.136.1",
 	bin: {
 		"val-language-server": "./bin.js"
 	},
@@ -1627,11 +1627,24 @@ function createProjectErrorDiagnostic({
  *
  * Val only serves modules listed there, so an unregistered module silently does
  * nothing — worth surfacing even though it is not a validation error.
+ *
+ * Reported on the `export default`, which is also why a file that has none gets
+ * no diagnostic at all (see `findValModuleDefinition`): the default export is
+ * the thing that makes a `*.val.ts` a module, so it is the thing being asked
+ * about, and pointing at line 1 of a file full of shared schemas asked its
+ * author to register something that does not exist.
+ *
+ * The message carries both remedies for the same reason. Only one of them is
+ * "add it to val.modules"; the other is to stop default-exporting, which is how
+ * a helper that landed in the module slot is fixed. Never "wrap it in
+ * `c.define`" — that turns it into an unregistered module, i.e. straight back
+ * to here.
  */
 function createMissingModuleDiagnostic({
-  moduleFilePath
+  moduleFilePath,
+  range
 }) {
-  return build(FALLBACK_RANGE, `${moduleFilePath} is not registered in val.modules, so Val will not serve it.`, {
+  return build(range, `${moduleFilePath} is not registered in val.modules, so Val will not serve it. Add it there — or, if this file is not meant to be a Val module, export what it holds by name instead: a default export is what makes a *.val.ts a module.`, {
     code: "val/missing-module",
     sourcePath: moduleFilePath
   });
@@ -2243,6 +2256,18 @@ function findRegisteredModuleSpecifiers(sourceFile) {
 /**
  * Whether `moduleFilePath` is registered by the given `val.modules` file.
  *
+ * Answers `true` whenever it cannot tell, which is the same safe direction
+ * {@link findRegisteredModuleSpecifiers} takes and matters more here than it
+ * looks: the caller publishes the missing-module diagnostic *instead of* the
+ * module's own diagnostics, so a false "unregistered" does not just add noise,
+ * it hides every real finding in the file. Two things it cannot tell:
+ *
+ *  - a `val.modules` with no dynamic imports at all, which is what a registry
+ *    that builds its list somewhere else looks like from here;
+ *  - a non-relative specifier naming a `.val` module (`_/content/page.val`),
+ *    which is a tsconfig path alias — a shape `loadValModules` resolves and
+ *    this file, having no compiler options, cannot.
+ *
  * @param valModulesDir directory containing the val.modules file, relative to
  *   the Val root (`""` when it sits at the root).
  * @param moduleFilePath the module's path, Val-style: root-relative, leading
@@ -2254,11 +2279,23 @@ function isModuleRegistered({
   moduleFilePath
 }) {
   const target = stripValModuleExtension(moduleFilePath);
-  return findRegisteredModuleSpecifiers(sourceFile).some(specifier => {
+  const specifiers = findRegisteredModuleSpecifiers(sourceFile);
+  if (specifiers.length === 0) {
+    return true;
+  }
+  return specifiers.some(specifier => {
+    const stripped = stripValModuleExtension(specifier);
     // Specifiers are written relative to the val.modules file and normally omit
     // the extension ("./content/page.val").
-    const resolved = specifier.startsWith(".") ? path__default["default"].posix.normalize(path__default["default"].posix.join("/", valModulesDir, stripValModuleExtension(specifier))) : stripValModuleExtension(specifier);
-    return resolved === target;
+    if (specifier.startsWith(".")) {
+      return path__default["default"].posix.normalize(path__default["default"].posix.join("/", valModulesDir, stripped)) === target;
+    }
+    if (specifier.startsWith("/")) {
+      return stripped === target;
+    }
+    // A path alias, which needs the project's tsconfig to resolve. A bare
+    // package import is not one of these, so it stays a plain non-match.
+    return stripped.endsWith(".val");
   });
 }
 
@@ -3668,6 +3705,60 @@ function keysOfKeyOf(schema, snapshot) {
   }
 }
 
+/**
+ * Where a file declares its Val module, or `undefined` when it declares none.
+ *
+ * `*.val.ts` is a naming convention, not a guarantee: a file under it may hold
+ * nothing but the schemas and helpers the modules beside it import. The default
+ * export is what separates the two, and `findDefaultExport` in
+ * `@valbuild/server` is the one implementation of that rule — the same one
+ * `val validate` uses to decide whether an unregistered file is worth reporting
+ * at all. It is imported rather than reimplemented because the subtleties are
+ * not obvious (a star re-export carries no default, a type-only export is gone
+ * after transpilation), and two copies would answer differently the first time
+ * one of them was fixed.
+ *
+ * Only the `export default` keywords are returned, never the whole definition:
+ * a module's source is most of its file, and a diagnostic spanning that paints
+ * the file red.
+ */
+function findValModuleDefinition(sourceFile) {
+  const statement = server.findDefaultExport(sourceFile);
+  if (!statement) {
+    return undefined;
+  }
+  const start = statement.getStart(sourceFile);
+  return {
+    start: sourceFile.getLineAndCharacterOfPosition(start),
+    end: sourceFile.getLineAndCharacterOfPosition(keywordsEnd(sourceFile, statement, start))
+  };
+}
+
+/**
+ * The end of the `export default` a statement opens with.
+ *
+ * Three shapes reach this, and only the first two can be narrowed: `export
+ * default <expr>`, where everything before the expression is the keywords;
+ * `export default function f() {}` and `export default class C {}`, where they
+ * are modifiers; and `export { x as default }`, which has no `default` keyword
+ * to stop at and is short enough to underline whole.
+ */
+function keywordsEnd(sourceFile, statement, start) {
+  if (ts__default["default"].isExportAssignment(statement)) {
+    // Up to the exported expression is `export default` plus whitespace (and,
+    // rarely, a comment); trimming the tail keeps the underline on the keywords.
+    return start + sourceFile.text.slice(start, statement.expression.getStart(sourceFile)).trimEnd().length;
+  }
+  const defaultModifier = ts__default["default"].canHaveModifiers(statement) ? (ts__default["default"].getModifiers(statement) ?? []).find(modifier => modifier.kind === ts__default["default"].SyntaxKind.DefaultKeyword) : undefined;
+  return defaultModifier?.end ?? statement.end;
+}
+
+/** Parse a Val module's text the way {@link findValModuleDefinition} needs it. */
+function parseValModule(moduleFilePath, text) {
+  // Parent pointers: `getStart` walks them to skip leading trivia.
+  return ts__default["default"].createSourceFile(moduleFilePath, text, ts__default["default"].ScriptTarget.ES2020, true);
+}
+
 /**
  * The two remedies for a gallery-backed field pointing at something its gallery
  * does not have.
@@ -4127,15 +4218,14 @@ function applyEnvOverrides(options) {
 const PROJECT_WIDE_FILE_RE = /[/\\]val\.(modules|config)\.(ts|js)$/;
 
 /**
- * Report a Val module that `val.modules` does not register.
+ * Whether `val.modules` leaves this module out.
  *
  * Reads `val.modules.{ts,js}` on demand, through the editor's buffer when it is
  * open: adding a module to the registry must clear the diagnostic straight away,
- * not only once the user saves. Returns `undefined` when no such file exists —
- * that is a project-level problem, not something to blame on an individual
- * module.
+ * not only once the user saves. Answers `false` when no such file exists — that
+ * is a project-level problem, not something to blame on an individual module.
  */
-function findMissingModuleDiagnostic(valRoot, moduleFilePath, read) {
+function isModuleUnregistered(valRoot, moduleFilePath, read) {
   for (const candidate of ["val.modules.ts", "val.modules.js"]) {
     const file = path__default["default"].join(valRoot, candidate);
     let text = read(file);
@@ -4146,16 +4236,13 @@ function findMissingModuleDiagnostic(valRoot, moduleFilePath, read) {
         continue;
       }
     }
-    const registered = isModuleRegistered({
+    return !isModuleRegistered({
       sourceFile: ts__default["default"].createSourceFile(file, text, ts__default["default"].ScriptTarget.ES2020),
       valModulesDir: "",
       moduleFilePath
     });
-    return registered ? undefined : createMissingModuleDiagnostic({
-      moduleFilePath
-    });
   }
-  return undefined;
+  return false;
 }
 
 /**
@@ -4220,6 +4307,27 @@ function createValLanguageServer(connection) {
       return;
     }
     try {
+      // An unregistered file is answered from its own text alone, before the
+      // project is consulted at all. Val cannot have evaluated it -- it is not
+      // in the graph `val.modules` describes -- so everything downstream has
+      // only the one thing to say about it, and said it twice: `Service.get`
+      // reports `Module '...' was not found in val.modules` as a fatal on line
+      // 1, beside this diagnostic saying the same. And when the file has no
+      // `export default` neither of them is a finding at all: it is a
+      // `*.val.ts` holding the schemas the modules beside it import, which Val
+      // never serves and there is nothing to register.
+      const unregistered = isModuleUnregistered(project.valRoot, moduleFilePath, readOpenDocument);
+      if (unregistered) {
+        const definition = findValModuleDefinition(parseValModule(moduleFilePath, document.getText()));
+        connection.sendDiagnostics({
+          uri,
+          diagnostics: definition ? [createMissingModuleDiagnostic({
+            moduleFilePath,
+            range: definition
+          })] : []
+        });
+        return;
+      }
       // The module's own content changed, so any cached result is stale.
       project.invalidate(moduleFilePath);
       const result = await project.getModule(moduleFilePath);
@@ -4283,10 +4391,6 @@ function createValLanguageServer(connection) {
           mediaChecks
         } : {})
       });
-      const unregistered = findMissingModuleDiagnostic(project.valRoot, moduleFilePath, readOpenDocument);
-      if (unregistered) {
-        diagnostics.push(unregistered);
-      }
       connection.sendDiagnostics({
         uri,
         diagnostics

package/dist/valbuild-language-server.esm.js

@@ -2,7 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import ts from 'typescript';
 import { Internal, DEFAULT_VAL_REMOTE_HOST, DEFAULT_CONTENT_HOST } from '@valbuild/core';
-import { fixHandlers, createService, analyzeValModule, createFixPatch, parsePersonalAccessTokenFile, getPersonalAccessTokenPath, startValLogin, awaitValLoginConfirmation, persistPersonalAccessToken, ValLoginError, findAndEvalValConfigFile, patchSourceFile, getSettings, uploadRemoteFile, findJsonEntryFilePath, rebaseContentOp, classifyJsonValuesOp, planJsonValuesEntryExtraction, extractImageMetadata, extractFileMetadata } from '@valbuild/server';
+import { fixHandlers, createService, analyzeValModule, createFixPatch, parsePersonalAccessTokenFile, getPersonalAccessTokenPath, startValLogin, awaitValLoginConfirmation, persistPersonalAccessToken, ValLoginError, findAndEvalValConfigFile, patchSourceFile, getSettings, uploadRemoteFile, findJsonEntryFilePath, rebaseContentOp, classifyJsonValuesOp, planJsonValuesEntryExtraction, extractImageMetadata, extractFileMetadata, findDefaultExport } from '@valbuild/server';
 import { DiagnosticSeverity, ShowDocumentRequest, ApplyWorkspaceEditRequest, CodeActionKind, CodeAction, MarkupContent, CompletionItemKind, DidChangeWatchedFilesNotification } from 'vscode-languageserver';
 import { TextDocuments, TextDocumentSyncKind, createConnection, ProposedFeatures } from 'vscode-languageserver/node';
 import { TextDocument } from 'vscode-languageserver-textdocument';
@@ -172,7 +172,7 @@ var packageJson = {
 		"lsp",
 		"language-server"
 	],
-	version: "0.135.0",
+	version: "0.136.1",
 	bin: {
 		"val-language-server": "./bin.js"
 	},
@@ -1616,11 +1616,24 @@ function createProjectErrorDiagnostic({
  *
  * Val only serves modules listed there, so an unregistered module silently does
  * nothing — worth surfacing even though it is not a validation error.
+ *
+ * Reported on the `export default`, which is also why a file that has none gets
+ * no diagnostic at all (see `findValModuleDefinition`): the default export is
+ * the thing that makes a `*.val.ts` a module, so it is the thing being asked
+ * about, and pointing at line 1 of a file full of shared schemas asked its
+ * author to register something that does not exist.
+ *
+ * The message carries both remedies for the same reason. Only one of them is
+ * "add it to val.modules"; the other is to stop default-exporting, which is how
+ * a helper that landed in the module slot is fixed. Never "wrap it in
+ * `c.define`" — that turns it into an unregistered module, i.e. straight back
+ * to here.
  */
 function createMissingModuleDiagnostic({
-  moduleFilePath
+  moduleFilePath,
+  range
 }) {
-  return build(FALLBACK_RANGE, `${moduleFilePath} is not registered in val.modules, so Val will not serve it.`, {
+  return build(range, `${moduleFilePath} is not registered in val.modules, so Val will not serve it. Add it there — or, if this file is not meant to be a Val module, export what it holds by name instead: a default export is what makes a *.val.ts a module.`, {
     code: "val/missing-module",
     sourcePath: moduleFilePath
   });
@@ -2232,6 +2245,18 @@ function findRegisteredModuleSpecifiers(sourceFile) {
 /**
  * Whether `moduleFilePath` is registered by the given `val.modules` file.
  *
+ * Answers `true` whenever it cannot tell, which is the same safe direction
+ * {@link findRegisteredModuleSpecifiers} takes and matters more here than it
+ * looks: the caller publishes the missing-module diagnostic *instead of* the
+ * module's own diagnostics, so a false "unregistered" does not just add noise,
+ * it hides every real finding in the file. Two things it cannot tell:
+ *
+ *  - a `val.modules` with no dynamic imports at all, which is what a registry
+ *    that builds its list somewhere else looks like from here;
+ *  - a non-relative specifier naming a `.val` module (`_/content/page.val`),
+ *    which is a tsconfig path alias — a shape `loadValModules` resolves and
+ *    this file, having no compiler options, cannot.
+ *
  * @param valModulesDir directory containing the val.modules file, relative to
  *   the Val root (`""` when it sits at the root).
  * @param moduleFilePath the module's path, Val-style: root-relative, leading
@@ -2243,11 +2268,23 @@ function isModuleRegistered({
   moduleFilePath
 }) {
   const target = stripValModuleExtension(moduleFilePath);
-  return findRegisteredModuleSpecifiers(sourceFile).some(specifier => {
+  const specifiers = findRegisteredModuleSpecifiers(sourceFile);
+  if (specifiers.length === 0) {
+    return true;
+  }
+  return specifiers.some(specifier => {
+    const stripped = stripValModuleExtension(specifier);
     // Specifiers are written relative to the val.modules file and normally omit
     // the extension ("./content/page.val").
-    const resolved = specifier.startsWith(".") ? path.posix.normalize(path.posix.join("/", valModulesDir, stripValModuleExtension(specifier))) : stripValModuleExtension(specifier);
-    return resolved === target;
+    if (specifier.startsWith(".")) {
+      return path.posix.normalize(path.posix.join("/", valModulesDir, stripped)) === target;
+    }
+    if (specifier.startsWith("/")) {
+      return stripped === target;
+    }
+    // A path alias, which needs the project's tsconfig to resolve. A bare
+    // package import is not one of these, so it stays a plain non-match.
+    return stripped.endsWith(".val");
   });
 }
 
@@ -3657,6 +3694,60 @@ function keysOfKeyOf(schema, snapshot) {
   }
 }
 
+/**
+ * Where a file declares its Val module, or `undefined` when it declares none.
+ *
+ * `*.val.ts` is a naming convention, not a guarantee: a file under it may hold
+ * nothing but the schemas and helpers the modules beside it import. The default
+ * export is what separates the two, and `findDefaultExport` in
+ * `@valbuild/server` is the one implementation of that rule — the same one
+ * `val validate` uses to decide whether an unregistered file is worth reporting
+ * at all. It is imported rather than reimplemented because the subtleties are
+ * not obvious (a star re-export carries no default, a type-only export is gone
+ * after transpilation), and two copies would answer differently the first time
+ * one of them was fixed.
+ *
+ * Only the `export default` keywords are returned, never the whole definition:
+ * a module's source is most of its file, and a diagnostic spanning that paints
+ * the file red.
+ */
+function findValModuleDefinition(sourceFile) {
+  const statement = findDefaultExport(sourceFile);
+  if (!statement) {
+    return undefined;
+  }
+  const start = statement.getStart(sourceFile);
+  return {
+    start: sourceFile.getLineAndCharacterOfPosition(start),
+    end: sourceFile.getLineAndCharacterOfPosition(keywordsEnd(sourceFile, statement, start))
+  };
+}
+
+/**
+ * The end of the `export default` a statement opens with.
+ *
+ * Three shapes reach this, and only the first two can be narrowed: `export
+ * default <expr>`, where everything before the expression is the keywords;
+ * `export default function f() {}` and `export default class C {}`, where they
+ * are modifiers; and `export { x as default }`, which has no `default` keyword
+ * to stop at and is short enough to underline whole.
+ */
+function keywordsEnd(sourceFile, statement, start) {
+  if (ts.isExportAssignment(statement)) {
+    // Up to the exported expression is `export default` plus whitespace (and,
+    // rarely, a comment); trimming the tail keeps the underline on the keywords.
+    return start + sourceFile.text.slice(start, statement.expression.getStart(sourceFile)).trimEnd().length;
+  }
+  const defaultModifier = ts.canHaveModifiers(statement) ? (ts.getModifiers(statement) ?? []).find(modifier => modifier.kind === ts.SyntaxKind.DefaultKeyword) : undefined;
+  return defaultModifier?.end ?? statement.end;
+}
+
+/** Parse a Val module's text the way {@link findValModuleDefinition} needs it. */
+function parseValModule(moduleFilePath, text) {
+  // Parent pointers: `getStart` walks them to skip leading trivia.
+  return ts.createSourceFile(moduleFilePath, text, ts.ScriptTarget.ES2020, true);
+}
+
 /**
  * The two remedies for a gallery-backed field pointing at something its gallery
  * does not have.
@@ -4116,15 +4207,14 @@ function applyEnvOverrides(options) {
 const PROJECT_WIDE_FILE_RE = /[/\\]val\.(modules|config)\.(ts|js)$/;
 
 /**
- * Report a Val module that `val.modules` does not register.
+ * Whether `val.modules` leaves this module out.
  *
  * Reads `val.modules.{ts,js}` on demand, through the editor's buffer when it is
  * open: adding a module to the registry must clear the diagnostic straight away,
- * not only once the user saves. Returns `undefined` when no such file exists —
- * that is a project-level problem, not something to blame on an individual
- * module.
+ * not only once the user saves. Answers `false` when no such file exists — that
+ * is a project-level problem, not something to blame on an individual module.
  */
-function findMissingModuleDiagnostic(valRoot, moduleFilePath, read) {
+function isModuleUnregistered(valRoot, moduleFilePath, read) {
   for (const candidate of ["val.modules.ts", "val.modules.js"]) {
     const file = path.join(valRoot, candidate);
     let text = read(file);
@@ -4135,16 +4225,13 @@ function findMissingModuleDiagnostic(valRoot, moduleFilePath, read) {
         continue;
       }
     }
-    const registered = isModuleRegistered({
+    return !isModuleRegistered({
       sourceFile: ts.createSourceFile(file, text, ts.ScriptTarget.ES2020),
       valModulesDir: "",
       moduleFilePath
     });
-    return registered ? undefined : createMissingModuleDiagnostic({
-      moduleFilePath
-    });
   }
-  return undefined;
+  return false;
 }
 
 /**
@@ -4209,6 +4296,27 @@ function createValLanguageServer(connection) {
       return;
     }
     try {
+      // An unregistered file is answered from its own text alone, before the
+      // project is consulted at all. Val cannot have evaluated it -- it is not
+      // in the graph `val.modules` describes -- so everything downstream has
+      // only the one thing to say about it, and said it twice: `Service.get`
+      // reports `Module '...' was not found in val.modules` as a fatal on line
+      // 1, beside this diagnostic saying the same. And when the file has no
+      // `export default` neither of them is a finding at all: it is a
+      // `*.val.ts` holding the schemas the modules beside it import, which Val
+      // never serves and there is nothing to register.
+      const unregistered = isModuleUnregistered(project.valRoot, moduleFilePath, readOpenDocument);
+      if (unregistered) {
+        const definition = findValModuleDefinition(parseValModule(moduleFilePath, document.getText()));
+        connection.sendDiagnostics({
+          uri,
+          diagnostics: definition ? [createMissingModuleDiagnostic({
+            moduleFilePath,
+            range: definition
+          })] : []
+        });
+        return;
+      }
       // The module's own content changed, so any cached result is stale.
       project.invalidate(moduleFilePath);
       const result = await project.getModule(moduleFilePath);
@@ -4272,10 +4380,6 @@ function createValLanguageServer(connection) {
           mediaChecks
         } : {})
       });
-      const unregistered = findMissingModuleDiagnostic(project.valRoot, moduleFilePath, readOpenDocument);
-      if (unregistered) {
-        diagnostics.push(unregistered);
-      }
       connection.sendDiagnostics({
         uri,
         diagnostics

package/package.json

@@ -11,7 +11,7 @@
     "lsp",
     "language-server"
   ],
-  "version": "0.135.0",
+  "version": "0.136.1",
   "bin": {
     "val-language-server": "./bin.js"
   },
@@ -29,9 +29,9 @@
     "typescript": "^6.0.3",
     "vscode-languageserver": "^10.1.0",
     "vscode-languageserver-textdocument": "^1.0.14",
-    "@valbuild/server": "0.135.0",
-    "@valbuild/shared": "0.134.1",
-    "@valbuild/core": "0.134.0"
+    "@valbuild/core": "0.136.1",
+    "@valbuild/server": "0.136.1",
+    "@valbuild/shared": "0.136.1"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",