@volar/language-core 2.4.10 → 2.4.12

package/index.d.ts

@@ -5,5 +5,5 @@ export * from './lib/types';
 export * from './lib/utils';
 import type { Language, LanguagePlugin, MapperFactory, SourceScript, VirtualCode } from './lib/types';
 export declare const defaultMapperFactory: MapperFactory;
-export declare function createLanguage<T>(plugins: LanguagePlugin<T>[], scriptRegistry: Map<T, SourceScript<T>>, sync: (id: T, includeFsFiles: boolean) => void): Language<T>;
+export declare function createLanguage<T>(plugins: LanguagePlugin<T>[], scriptRegistry: Map<T, SourceScript<T>>, sync: (id: T, includeFsFiles: boolean, shouldRegister: boolean) => void, onAssociationDirty?: (targetId: T) => void): Language<T>;
 export declare function forEachEmbeddedCode(virtualCode: VirtualCode): Generator<VirtualCode>;

package/index.js

@@ -27,7 +27,7 @@ const source_map_2 = require("@volar/source-map");
 const linkedCodeMap_1 = require("./lib/linkedCodeMap");
 const defaultMapperFactory = mappings => new source_map_2.SourceMap(mappings);
 exports.defaultMapperFactory = defaultMapperFactory;
-function createLanguage(plugins, scriptRegistry, sync) {
+function createLanguage(plugins, scriptRegistry, sync, onAssociationDirty) {
     const virtualCodeToSourceScriptMap = new WeakMap();
     const virtualCodeToSourceMap = new WeakMap();
     const virtualCodeToLinkedCodeMap = new WeakMap();
@@ -38,8 +38,8 @@ function createLanguage(plugins, scriptRegistry, sync) {
             fromVirtualCode(virtualCode) {
                 return virtualCodeToSourceScriptMap.get(virtualCode);
             },
-            get(id, includeFsFiles = true) {
-                sync(id, includeFsFiles);
+            get(id, includeFsFiles = true, shouldRegister = false) {
+                sync(id, includeFsFiles, shouldRegister);
                 const result = scriptRegistry.get(id);
                 // The sync function provider may not always call the set function due to caching, so it is necessary to explicitly check isAssociationDirty.
                 if (result?.isAssociationDirty) {
@@ -71,14 +71,20 @@ function createLanguage(plugins, scriptRegistry, sync) {
                     const sourceScript = scriptRegistry.get(id);
                     if (sourceScript.languageId !== languageId || sourceScript.associatedOnly !== associatedOnly) {
                         this.delete(id);
+                        triggerTargetsDirty(sourceScript);
                         return this.set(id, snapshot, languageId);
                     }
                     else if (associatedOnly) {
-                        sourceScript.snapshot = snapshot;
+                        if (sourceScript.snapshot !== snapshot) {
+                            sourceScript.snapshot = snapshot;
+                            triggerTargetsDirty(sourceScript);
+                        }
                     }
                     else if (sourceScript.isAssociationDirty || sourceScript.snapshot !== snapshot) {
-                        // snapshot updated
-                        sourceScript.snapshot = snapshot;
+                        if (sourceScript.snapshot !== snapshot) {
+                            sourceScript.snapshot = snapshot;
+                            triggerTargetsDirty(sourceScript);
+                        }
                         const codegenCtx = prepareCreateVirtualCode(sourceScript);
                         if (sourceScript.generated) {
                             const { updateVirtualCode, createVirtualCode } = sourceScript.generated.languagePlugin;
@@ -99,7 +105,6 @@ function createLanguage(plugins, scriptRegistry, sync) {
                                 return;
                             }
                         }
-                        triggerTargetsDirty(sourceScript);
                     }
                     else {
                         // not changed
@@ -200,6 +205,7 @@ function createLanguage(plugins, scriptRegistry, sync) {
             const sourceScript = scriptRegistry.get(id);
             if (sourceScript) {
                 sourceScript.isAssociationDirty = true;
+                onAssociationDirty?.(sourceScript.id);
             }
         });
     }
@@ -211,7 +217,7 @@ function createLanguage(plugins, scriptRegistry, sync) {
         sourceScript.isAssociationDirty = false;
         return {
             getAssociatedScript(id) {
-                sync(id, true);
+                sync(id, true, true);
                 const relatedSourceScript = scriptRegistry.get(id);
                 if (relatedSourceScript) {
                     relatedSourceScript.targetIds.add(sourceScript.id);

package/lib/types.d.ts

@@ -12,7 +12,7 @@ export interface Language<T = unknown> {
     mapperFactory: MapperFactory;
     plugins: LanguagePlugin<T>[];
     scripts: {
-        get(id: T, includeFsFiles?: boolean): SourceScript<T> | undefined;
+        get(id: T, includeFsFiles?: boolean, shouldRegister?: boolean): SourceScript<T> | undefined;
         set(id: T, snapshot: IScriptSnapshot, languageId?: string, plugins?: LanguagePlugin<T>[]): SourceScript<T> | undefined;
         delete(id: T): void;
         fromVirtualCode(virtualCode: VirtualCode): SourceScript<T>;
@@ -49,9 +49,27 @@ export interface VirtualCode {
     embeddedCodes?: VirtualCode[];
     linkedCodeMappings?: Mapping[];
 }
+/**
+ * CodeInformation is a configuration object attached to each CodeMapping (between source code and generated code,
+ * e.g. between the template code in a .vue file and the type-checkable TS code generated from it) that
+ * determines what code/language features are expected to be available for the mapping.
+ *
+ * Due to the dynamic nature of code generation and the fact that, for example, things like Code Actions
+ * and auto-complete shouldn't be triggerable on certain "in-between" regions of generated code, we need
+ * a way to shut off certain features in certain regions, while leaving them enabled in others.
+ */
 export interface CodeInformation {
-    /** virtual code is expected to support verification */
+    /** virtual code is expected to support verification, where verification includes:
+     *
+     * - diagnostics (syntactic, semantic, and others, such as those generated by the TypeScript language service on generated TS code)
+     * - code actions (refactorings, quick fixes,etc.)
+     */
     verification?: boolean | {
+        /**
+         * when present, `shouldReport` callback is invoked to determine whether a diagnostic
+         * raised in the generated code should be propagated back to the original source code.
+         * Note that when this callback is present, diagnostic processing (e.g. typechecking) will
+         * still be performed, but the results will not be reported back to the original source code. */
         shouldReport?(source: string | undefined, code: string | number | undefined): boolean;
     };
     /** virtual code is expected to support assisted completion */
@@ -59,7 +77,16 @@ export interface CodeInformation {
         isAdditional?: boolean;
         onlyImport?: boolean;
     };
-    /** virtual code is expected correctly reflect semantic of the source code */
+    /** virtual code is expected correctly reflect semantic of the source code. Specifically this controls the following langauge features:
+     *
+     * - hover
+     * - inlay hints
+     * - code lens
+     * - semantic tokens
+     * - others
+     *
+     * Note that semantic diagnostics (e.g. TS type-checking) are covered by the `verification` property above.
+     */
     semantic?: boolean | {
         shouldHighlight?(): boolean;
     };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@volar/language-core",
-	"version": "2.4.10",
+	"version": "2.4.12",
 	"license": "MIT",
 	"files": [
 		"**/*.js",
@@ -12,7 +12,7 @@
 		"directory": "packages/language-core"
 	},
 	"dependencies": {
-		"@volar/source-map": "2.4.10"
+		"@volar/source-map": "2.4.12"
 	},
-	"gitHead": "03d1e8b07e1e64921b76b635c7064d7b4fcf63b5"
+	"gitHead": "17b9b8a1f522afd1aad1e598d2fd935680d8a8d7"
 }