support ---@meta [name]

once declared `name`, user can only require this file by declared name

meta file can not be required with name `_`

Author: sumneko

changelog.md

@@ -9,6 +9,7 @@
 * `CHG` definition: supports finding definitions for `@class` and `@alias`, since they may be defined multi times
 * `CHG` rename: supports `@field`
 * `CHG` improve patch for `.luarc.json`
+* `CHG` `---@meta [name]`: once declared `name`, user can only require this file by declared name. meta file can not be required with name `_`
 * `CHG` remove telemetry
 * `FIX` [#831]
 * `FIX` [#1729]

meta/template/basic.lua

@@ -1,4 +1,4 @@
----@meta
+---@meta _
 
 ---#DES 'arg'
 ---@type string[]

meta/template/bit.lua

@@ -1,5 +1,5 @@
 ---#if not JIT then DISABLE() end
----@meta
+---@meta bit
 
 ---@version JIT
 ---@class bitlib

meta/template/bit32.lua

@@ -1,5 +1,5 @@
 ---#if VERSION ~= 5.2 then DISABLE() end
----@meta
+---@meta bit32
 
 ---@version 5.2
 ---#DES 'bit32'

meta/template/builtin.lua

@@ -1,4 +1,4 @@
----@meta
+---@meta _
 
 ---@class unknown
 ---@class any

meta/template/coroutine.lua

@@ -1,4 +1,4 @@
----@meta
+---@meta coroutine
 
 ---#DES 'coroutine'
 ---@class coroutinelib

meta/template/debug.lua

@@ -1,4 +1,4 @@
----@meta
+---@meta debug
 
 ---#DES 'debug'
 ---@class debuglib

meta/template/ffi.lua

@@ -1,5 +1,5 @@
 ---#if not JIT then DISABLE() end
----@meta
+---@meta ffi
 
 ---@class ffi.namespace*: table
 ---@field [string] function

meta/template/io.lua

@@ -1,4 +1,4 @@
----@meta
+---@meta io
 
 ---#DES 'io'
 ---@class iolib

meta/template/jit.lua

@@ -1,5 +1,5 @@
 ---#if not JIT then DISABLE() end
----@meta
+---@meta jit
 
 ---@version JIT
 ---@class jitlib

meta/template/math.lua

@@ -1,4 +1,4 @@
----@meta
+---@meta math
 
 ---#DES 'math'
 ---@class mathlib

meta/template/os.lua

@@ -1,4 +1,4 @@
----@meta
+---@meta os
 
 ---#DES 'os'
 ---@class oslib

meta/template/package.lua

@@ -1,4 +1,4 @@
----@meta
+---@meta package
 
 ---#if VERSION >=5.4 then
 ---#DES 'require>5.4'

meta/template/string.buffer.lua

@@ -1,5 +1,5 @@
 ---#if not JIT then DISABLE() end
----@meta
+---@meta string.buffer
 
 ---@version JIT
 --- The string buffer library allows high-performance manipulation of string-like data.

meta/template/string.lua

@@ -1,4 +1,4 @@
----@meta
+---@meta string
 
 ---#DES 'string'
 ---@class stringlib

meta/template/table.clear.lua

@@ -1,9 +1,9 @@
 ---#if not JIT then DISABLE() end
----@meta
+---@meta table.clear
 
 ---@version JIT
 ---#DES 'table.clear'
 ---@param tab table
 local function clear(tab) end
 
-return clear
+return clear

meta/template/table.lua

@@ -1,4 +1,4 @@
----@meta
+---@meta table
 
 ---#DES 'table'
 ---@class tablelib

meta/template/table.new.lua

@@ -1,5 +1,5 @@
 ---#if not JIT then DISABLE() end
----@meta
+---@meta table.new
 
 ---@version JIT
 ---#DES 'table.new'
@@ -8,4 +8,4 @@
 ---@return table
 local function new(narray, nhash) end
 
-return new
+return new

meta/template/utf8.lua

@@ -1,5 +1,5 @@
 ---#if VERSION <= 5.2 then DISABLE() end
----@meta
+---@meta utf8
 
 ---@version >5.3
 ---#DES 'utf8'

script/core/semantic-tokens.lua

@@ -694,6 +694,14 @@ local Care = util.switch()
             type       = define.TokenTypes.operator,
         }
     end)
+    : case 'doc.meta.name'
+    : call(function (source, options, results)
+        results[#results+1] = {
+            start      = source.start,
+            finish     = source.finish,
+            type       = define.TokenTypes.namespace,
+        }
+    end)
 
 ---@param state table
 ---@param results table

script/parser/guide.lua

@@ -178,6 +178,7 @@ local childMap = {
     ['doc.cast']           = {'name', '#casts'},
     ['doc.cast.block']     = {'extends'},
     ['doc.operator']       = {'op', 'exp', 'extends'},
+    ['doc.meta']           = {'name'},
 }
 
 ---@type table<string, fun(obj: parser.object, list: parser.object[])>

script/parser/luadoc.lua

@@ -1116,8 +1116,10 @@ local docSwitch = util.switch()
     end)
     : case 'meta'
     : call(function ()
+        local requireName = parseName('doc.meta.name')
         return {
             type   = 'doc.meta',
+            name   = requireName,
             start  = getFinish(),
             finish = getFinish(),
         }

script/vm/doc.lua

@@ -44,12 +44,38 @@ function vm.isMetaFile(uri)
     for _, doc in ipairs(status.ast.docs) do
         if doc.type == 'doc.meta' then
             cache.isMeta = true
+            cache.metaName = doc.name
             return true
         end
     end
     return false
 end
 
+---@param uri uri
+---@return string?
+function vm.getMetaName(uri)
+    if not vm.isMetaFile(uri) then
+        return nil
+    end
+    local cache = files.getCache(uri)
+    if not cache then
+        return nil
+    end
+    if not cache.metaName then
+        return nil
+    end
+    return cache.metaName[1]
+end
+
+---@param uri uri
+---@return boolean
+function vm.isMetaFileRequireable(uri)
+    if not vm.isMetaFile(uri) then
+        return false
+    end
+    return vm.getMetaName(uri) ~= '_'
+end
+
 ---@param doc parser.object
 ---@return table<string, boolean>?
 function vm.getValidVersions(doc)

script/workspace/require-path.lua

@@ -59,12 +59,24 @@ end
 ---@param path string
 ---@return require-manager.visibleResult[]
 function mt:getRequireResultByPath(path)
+    local vm  = require 'vm'
     local uri = furi.encode(path)
+    local result = {}
+    if vm.isMetaFile(uri) then
+        local metaName = vm.getMetaName(uri)
+        if metaName then
+            if vm.isMetaFileRequireable(uri) then
+                result[#result+1] = {
+                    name = metaName,
+                }
+            end
+            return result
+        end
+    end
     local searchers   = config.get(self.scp.uri, 'Lua.runtime.path')
     local strict      = config.get(self.scp.uri, 'Lua.runtime.pathStrict')
     local libUri      = files.getLibraryUri(self.scp.uri, uri)
     local libraryPath = libUri and furi.decode(libUri)
-    local result = {}
     for _, searcher in ipairs(searchers) do
         local isAbsolute = searcher:match '^[/\\]'
                         or searcher:match '^%a+%:'
@@ -157,22 +169,39 @@ end
 --- 查找符合指定require name的所有uri
 ---@param name string
 ---@return uri[]
----@return table<uri, string>
+---@return table<uri, string>?
 function mt:searchUrisByRequireName(name)
+    local vm          = require 'vm'
     local searchers   = config.get(self.scp.uri, 'Lua.runtime.path')
     local strict      = config.get(self.scp.uri, 'Lua.runtime.pathStrict')
     local separator   = config.get(self.scp.uri, 'Lua.completion.requireSeparator')
     local path        = name:gsub('%' .. separator, '/')
     local results     = {}
     local searcherMap = {}
+    local excludes    = {}
+
+    for uri in files.eachFile(self.scp.uri) do
+        if vm.isMetaFileRequireable(uri) then
+            local metaName = vm.getMetaName(uri)
+            if metaName == name then
+                results[#results+1] = uri
+                return results
+            end
+            if metaName then
+                excludes[uri] = true
+            end
+        end
+    end
 
     for _, searcher in ipairs(searchers) do
         local fspath = searcher:gsub('%?', (path:gsub('%%', '%%%%')))
         fspath = workspace.normalize(fspath)
         local tail = '/' .. furi.encode(fspath):gsub('^file:[/]*', '')
         for uri in files.eachFile(self.scp.uri) do
             if  not searcherMap[uri]
-            and util.stringEndWith(uri, tail) then
+            and not excludes[uri]
+            and util.stringEndWith(uri, tail)
+            and (not vm.isMetaFile(uri) or vm.isMetaFileRequireable(uri)) then
                 local parentUri = files.getLibraryUri(self.scp.uri, uri) or self.scp.uri
                 if parentUri == nil or parentUri == '' then
                     parentUri = furi.encode '/'
@@ -223,7 +252,7 @@ function mt:findUrisByRequireName(suri, name)
     for _, uri in ipairs(cache.results) do
         if uri ~= suri then
             results[#results+1] = uri
-            searcherMap[uri] = cache.searcherMap[uri]
+            searcherMap[uri] = cache.searcherMap and cache.searcherMap[uri]
         end
     end
     return results, searcherMap
@@ -242,6 +271,8 @@ end
 
 ---@param uri uri
 ---@param name string
+---@return uri[]
+---@return table<uri, string>?
 function m.findUrisByRequireName(uri, name)
     local scp = scope.getScope(uri)
     ---@type require-manager

test/completion/common.lua

@@ -3538,7 +3538,7 @@ TEST [[
 require '<??>'
 ]]
 (function (results)
-    assert(#results == 11, require 'utility'.dump(results))
+    assert(#results == 9, require 'utility'.dump(results))
 end)
 
 TEST [[

test/crossfile/completion.lua

@@ -10,6 +10,7 @@ local define   = require 'proto.define'
 rawset(_G, 'TEST', true)
 
 local CompletionItemKind = define.CompletionItemKind
+local NeedRemoveMeta = false
 
 local EXISTS = {}
 
@@ -87,7 +88,9 @@ function TEST(data)
     assert(result ~= nil)
     result.complete = nil
     result.enableCommon = nil
-    removeMetas(result)
+    if NeedRemoveMeta then
+        removeMetas(result)
+    end
     for _, item in ipairs(result) do
         if item.id then
             local r = core.resolve(item.id)
@@ -439,6 +442,51 @@ TEST {
 
 config.set(nil, 'Lua.runtime.path', originRuntimePath)
 
+TEST {
+    {
+        path = 'abc.lua',
+        content = '---@meta _',
+    },
+    {
+        path = 'test.lua',
+        content = 'require "a<??>"',
+        main = true,
+    },
+    completion = nil
+}
+
+TEST {
+    {
+        path = 'abc.lua',
+        content = '---@meta xxxxx',
+    },
+    {
+        path = 'test.lua',
+        content = 'require "a<??>"',
+        main = true,
+    },
+    completion = nil
+}
+
+TEST {
+    {
+        path = 'abc.lua',
+        content = '---@meta xxxxx',
+    },
+    {
+        path = 'test.lua',
+        content = 'require "xx<??>"',
+        main = true,
+    },
+    completion = {
+        {
+            label = 'xxxxx',
+            kind = CompletionItemKind.File,
+            textEdit = EXISTS,
+        }
+    }
+}
+
 TEST {
     {
         path = 'a.lua',
@@ -561,6 +609,8 @@ TEST {
     completion = nil,
 }
 
+NeedRemoveMeta = true
+
 TEST {
     { path = 'f/a.lua' },
     { path = 'f/b.lua' },