Read-only/Write-only extern properties, Read-only vector properties (luau-lang#2071)

Implements the `read` and `write` property attributes for external type
definitions, which the embedded `vector` type now makes use of:

**Before:**
```luau
declare extern type vector with
    x: number
    y: number
    z: number
end
```

**After:**
```luau
declare extern type vector with
    read x: number
    read y: number
    read z: number
end
```

The following code now creates type-errors in the expected places:

```luau
--!strict
local function increment(v: vector)
    v.x += 1        -- TE
    v.x -= 1        -- TE
    v.y *= 1        -- TE
    v.z /= 1        -- TE
    print(v.x)      -- No TE
    print(v.x > 5)  -- No TE
    v.x = 15        -- TE
end

increment(vector.create(1, 2, 3))
```

This PR also supports different read/write types:

```luau
-- Definition
declare extern type Foo with
    read Bar: number
    write Bar: string
end

-- Script
local f: Foo
local b: number = f.Bar
f.Bar = "Hello, World!"
```

Additionally,
* Adds two new tests for the implemented syntax
* Adds the `LuauLValueCompoundAssignmentVisitLhs`,
`LuauExternReadWriteAttributes` and `LuauTypeCheckerVectorReadOnly`
flags

Closes luau-lang#2062

Author: PhoenixWhitefire

Analysis/src/ConstraintGenerator.cpp

@@ -46,6 +46,7 @@ LUAU_FASTFLAG(LuauCaptureRecursiveCallsForTablesAndGlobals2)
 LUAU_FASTFLAGVARIABLE(LuauForwardPolarityForFunctionTypes)
 LUAU_FASTFLAGVARIABLE(LuauKeepExplicitMapForGlobalTypes)
 LUAU_FASTFLAGVARIABLE(LuauRefinementTypeVector)
+LUAU_FASTFLAG(LuauExternReadWriteAttributes)
 
 namespace Luau
 {
@@ -2061,16 +2062,16 @@ ControlFlow ConstraintGenerator::visit(const ScopePtr& scope, AstStatDeclareExte
         }
     }
 
-    for (const AstDeclaredExternTypeProperty& prop : declaredExternType->props)
+    for (const AstDeclaredExternTypeProperty& externProp : declaredExternType->props)
     {
-        Name propName(prop.name.value);
-        TypeId propTy = resolveType(scope, prop.ty, /* inTypeArguments */ false, /* replaceErrorWithFresh */ false, /* initialPolarity */ Polarity::Mixed);
+        Name propName(externProp.name.value);
+        TypeId propTy = resolveType(scope, externProp.ty, /* inTypeArguments */ false, /* replaceErrorWithFresh */ false, /* initialPolarity */ Polarity::Mixed);
 
         bool assignToMetatable = isMetamethod(propName);
 
         // Function typeArguments always take 'self', but this isn't reflected in the
         // parsed annotation. Add it here.
-        if (prop.isMethod)
+        if (externProp.isMethod)
         {
             if (FunctionType* ftv = getMutable<FunctionType>(propTy))
             {
@@ -2082,9 +2083,9 @@ ControlFlow ConstraintGenerator::visit(const ScopePtr& scope, AstStatDeclareExte
                 FunctionDefinition defn;
 
                 defn.definitionModuleName = module->name;
-                defn.definitionLocation = prop.location;
+                defn.definitionLocation = externProp.location;
                 // No data is preserved for varargLocation
-                defn.originalNameLocation = prop.nameLocation;
+                defn.originalNameLocation = externProp.nameLocation;
 
                 ftv->definition = defn;
             }
@@ -2094,11 +2095,30 @@ ControlFlow ConstraintGenerator::visit(const ScopePtr& scope, AstStatDeclareExte
 
         if (props.count(propName) == 0)
         {
-            props[propName] = {propTy, /*deprecated*/ false, /*deprecatedSuggestion*/ "", prop.location};
+            Property tableProp;
+
+            if (FFlag::LuauExternReadWriteAttributes)
+            {
+                if (externProp.access == AstTableAccess::Read)
+                    tableProp = Property::readonly(propTy);
+                else if (externProp.access == AstTableAccess::Write)
+                    tableProp = Property::writeonly(propTy);
+                else
+                    tableProp = Property::rw(propTy);
+
+                tableProp.location = externProp.location;
+            }
+            else
+            {
+                tableProp = {propTy, /*deprecated*/ false, /*deprecatedSuggestion*/ "", externProp.location};
+            }
+
+            props[propName] = tableProp;
         }
         else
         {
             Luau::Property& prop = props[propName];
+            bool addedWriteTypeByOverload = false;
 
             if (auto readTy = prop.readTy)
             {
@@ -2120,14 +2140,30 @@ ControlFlow ConstraintGenerator::visit(const ScopePtr& scope, AstStatDeclareExte
                 }
                 else
                 {
-                    reportError(
-                        declaredExternType->location,
-                        GenericError{format("Cannot overload read type of non-function class member '%s'", propName.c_str())}
-                    );
+                    if (FFlag::LuauExternReadWriteAttributes)
+                    {
+                        if (externProp.access == AstTableAccess::Write && !prop.writeTy.has_value())
+                        {
+                            prop.writeTy = propTy;
+                            addedWriteTypeByOverload = true;
+                        }
+                        else
+                            reportError(
+                                declaredExternType->location,
+                                GenericError{format("Cannot overload read type of non-function extern type member '%s'", propName.c_str())}
+                            );
+                    }
+                    else
+                    {
+                        reportError(
+                            declaredExternType->location,
+                            GenericError{format("Cannot overload read type of non-function extern type member '%s'", propName.c_str())}
+                        );
+                    }
                 }
             }
 
-            if (auto writeTy = prop.writeTy)
+            if (auto writeTy = prop.writeTy; writeTy && !addedWriteTypeByOverload)
             {
                 // We special-case this logic to keep the intersection flat; otherwise we
                 // would create a ton of nested intersection typeArguments.
@@ -2147,10 +2183,23 @@ ControlFlow ConstraintGenerator::visit(const ScopePtr& scope, AstStatDeclareExte
                 }
                 else
                 {
-                    reportError(
-                        declaredExternType->location,
-                        GenericError{format("Cannot overload write type of non-function class member '%s'", propName.c_str())}
-                    );
+                    if (FFlag::LuauExternReadWriteAttributes)
+                    {
+                        if (externProp.access == AstTableAccess::Read && !prop.readTy.has_value())
+                            prop.readTy = propTy;
+                        else
+                            reportError(
+                                declaredExternType->location,
+                                GenericError{format("Cannot overload write type of non-function extern type member '%s'", propName.c_str())}
+                            );
+                    }
+                    else
+                    {
+                        reportError(
+                            declaredExternType->location,
+                            GenericError{format("Cannot overload write type of non-function extern type member '%s'", propName.c_str())}
+                        );
+                    }
                 }
             }
         }

Analysis/src/EmbeddedBuiltinDefinitions.cpp

@@ -3,6 +3,7 @@
 
 LUAU_FASTFLAGVARIABLE(LuauTypeCheckerUdtfRenameClassToExtern)
 LUAU_FASTFLAGVARIABLE(LuauNewMathConstantsAnalysis)
+LUAU_FASTFLAGVARIABLE(LuauTypeCheckerVectorReadOnly)
 
 namespace Luau
 {
@@ -329,6 +330,37 @@ declare buffer: {
 
 static const char* const kBuiltinDefinitionVectorSrc = R"BUILTIN_SRC(
 
+-- While vector would have been better represented as a built-in primitive type, type solver extern type handling covers most of the properties
+declare extern type vector with
+    read x: number
+    read y: number
+    read z: number
+end
+
+declare vector: {
+    create: @checked (x: number, y: number, z: number?) -> vector,
+    magnitude: @checked (vec: vector) -> number,
+    normalize: @checked (vec: vector) -> vector,
+    cross: @checked (vec1: vector, vec2: vector) -> vector,
+    dot: @checked (vec1: vector, vec2: vector) -> number,
+    angle: @checked (vec1: vector, vec2: vector, axis: vector?) -> number,
+    floor: @checked (vec: vector) -> vector,
+    ceil: @checked (vec: vector) -> vector,
+    abs: @checked (vec: vector) -> vector,
+    sign: @checked (vec: vector) -> vector,
+    clamp: @checked (vec: vector, min: vector, max: vector) -> vector,
+    max: @checked (vector, ...vector) -> vector,
+    min: @checked (vector, ...vector) -> vector,
+    lerp: @checked (vec1: vector, vec2: vector, t: number) -> vector,
+
+    zero: vector,
+    one: vector,
+}
+
+)BUILTIN_SRC";
+
+static const char* const kBuiltinDefinitionVectorSrc_DEPRECATED = R"BUILTIN_SRC(
+
 -- While vector would have been better represented as a built-in primitive type, type solver extern type handling covers most of the properties
 declare extern type vector with
     x: number
@@ -373,7 +405,14 @@ std::string getBuiltinDefinitionSource()
     result += kBuiltinDefinitionDebugSrc;
     result += kBuiltinDefinitionUtf8Src;
     result += kBuiltinDefinitionBufferSrc;
-    result += kBuiltinDefinitionVectorSrc;
+    if (FFlag::LuauTypeCheckerVectorReadOnly)
+    {
+        result += kBuiltinDefinitionVectorSrc;
+    }
+    else
+    {
+        result += kBuiltinDefinitionVectorSrc_DEPRECATED;
+    }
 
     return result;
 }

Analysis/src/TypeChecker2.cpp

@@ -42,6 +42,7 @@ LUAU_FASTFLAG(LuauExternTypesNormalizeWithShapes)
 LUAU_FASTFLAGVARIABLE(LuauCheckFunctionStatementTypes)
 LUAU_FASTFLAGVARIABLE(LuauComparisonToNilsIsAlwaysOk2)
 LUAU_FASTFLAGVARIABLE(LuauLValueCompoundAssignmentVisitLhs)
+LUAU_FASTFLAG(LuauExternReadWriteAttributes)
 
 namespace Luau
 {
@@ -3661,17 +3662,22 @@ void TypeChecker2::checkIndexTypeFromType(
         // because extern typeArguments come into being with full knowledge of their
         // shape. We instead want to report the unknown property error of
         // the `else` branch.
-        else if (context == ValueContext::LValue && !get<ExternType>(tableTy))
+        else if (context == ValueContext::LValue && (FFlag::LuauExternReadWriteAttributes || !get<ExternType>(tableTy)))
         {
             const auto lvPropTypes = lookupProp(norm.get(), prop, ValueContext::RValue, location, astIndexExprType, dummy);
             if (lvPropTypes.foundOneProp() && lvPropTypes.noneMissingProp())
                 reportError(PropertyAccessViolation{tableTy, prop, PropertyAccessViolation::CannotWrite}, location);
             else if (get<PrimitiveType>(tableTy) || get<FunctionType>(tableTy))
                 reportError(NotATable{tableTy}, location);
             else
-                reportError(CannotExtendTable{tableTy, CannotExtendTable::Property, prop}, location);
+            {
+                if (FFlag::LuauExternReadWriteAttributes && get<ExternType>(tableTy))
+                    reportError(UnknownProperty{tableTy, prop}, location);
+                else
+                    reportError(CannotExtendTable{tableTy, CannotExtendTable::Property, prop}, location);
+            }
         }
-        else if (context == ValueContext::RValue && !get<ExternType>(tableTy))
+        else if (context == ValueContext::RValue && (FFlag::LuauExternReadWriteAttributes || !get<ExternType>(tableTy)))
         {
             const auto rvPropTypes = lookupProp(norm.get(), prop, ValueContext::LValue, location, astIndexExprType, dummy);
             if (rvPropTypes.foundOneProp() && rvPropTypes.noneMissingProp())
@@ -3733,7 +3739,14 @@ PropertyType TypeChecker2::hasIndexTypeFromType(
         // is compatible with the indexer's indexType
         // Construct the intersection and test inhabitedness!
         if (auto property = lookupExternTypeProp(cls, prop))
-            return {NormalizationResult::True, context == ValueContext::LValue ? property->writeTy : property->readTy};
+        {
+            if (FFlag::LuauExternReadWriteAttributes
+                && ((context == ValueContext::LValue && !property->writeTy) || (context == ValueContext::RValue && !property->readTy))
+            )
+                return {NormalizationResult::False, {}};
+            else
+                return {NormalizationResult::True, context == ValueContext::LValue ? property->writeTy : property->readTy};
+        }
         if (cls->indexer)
         {
             TypeId inhabitedTestType = module->internalTypes.addType(IntersectionType{{cls->indexer->indexType, astIndexExprType}});

Ast/include/Luau/Ast.h

@@ -1052,20 +1052,21 @@ class AstStatDeclareFunction : public AstStat
     AstTypePack* retTypes;
 };
 
+enum class AstTableAccess
+{
+    Read = 0b01,
+    Write = 0b10,
+    ReadWrite = 0b11,
+};
+
 struct AstDeclaredExternTypeProperty
 {
     AstName name;
     Location nameLocation;
     AstType* ty = nullptr;
     bool isMethod = false;
     Location location;
-};
-
-enum class AstTableAccess
-{
-    Read = 0b01,
-    Write = 0b10,
-    ReadWrite = 0b11,
+    AstTableAccess access = AstTableAccess::ReadWrite;
 };
 
 struct AstTableIndexer

Ast/src/Parser.cpp

@@ -22,6 +22,7 @@ LUAU_DYNAMIC_FASTFLAGVARIABLE(DebugLuauReportReturnTypeVariadicWithTypeSuffix, f
 LUAU_FASTFLAGVARIABLE(DesugaredArrayTypeReferenceIsEmpty)
 LUAU_FASTFLAGVARIABLE(LuauConst2)
 LUAU_FASTFLAGVARIABLE(DebugLuauNoInline)
+LUAU_FASTFLAGVARIABLE(LuauExternReadWriteAttributes)
 
 // Clip with DebugLuauReportReturnTypeVariadicWithTypeSuffix
 bool luau_telemetry_parsed_return_type_variadic_with_type_suffix = false;
@@ -1632,6 +1633,30 @@ AstStat* Parser::parseDeclaration(const Location& start, const AstArray<AstAttr*
             }
             else
             {
+                AstTableAccess access = AstTableAccess::ReadWrite;
+
+                if (FFlag::LuauExternReadWriteAttributes)
+                {
+                    if (lexer.current().type == Lexeme::Name && lexer.lookahead().type != ':')
+                    {
+                        if (AstName(lexer.current().name) == "read")
+                        {
+                            access = AstTableAccess::Read;
+                            lexer.next();
+                        }
+                        else if (AstName(lexer.current().name) == "write")
+                        {
+                            access = AstTableAccess::Write;
+                            lexer.next();
+                        }
+                        else
+                        {
+                            report(lexer.current().location, "Expected blank or 'read' or 'write' attribute, got '%s'", lexer.current().name);
+                            lexer.next();
+                        }
+                    }
+                }
+
                 Location propStart = lexer.current().location;
                 std::optional<Name> propName = parseNameOpt("property name");
 
@@ -1641,7 +1666,7 @@ AstStat* Parser::parseDeclaration(const Location& start, const AstArray<AstAttr*
                 expectAndConsume(':', "property type annotation");
                 AstType* propType = parseType();
                 props.push_back(
-                    AstDeclaredExternTypeProperty{propName->name, propName->location, propType, false, Location(propStart, lexer.previousLocation())}
+                    AstDeclaredExternTypeProperty{propName->name, propName->location, propType, false, Location(propStart, lexer.previousLocation()), access}
                 );
             }
         }

tests/Parser.test.cpp

@@ -19,6 +19,7 @@ LUAU_FASTINT(LuauParseErrorLimit)
 LUAU_DYNAMIC_FASTFLAG(DebugLuauReportReturnTypeVariadicWithTypeSuffix)
 LUAU_FASTFLAG(LuauConst2)
 LUAU_FASTFLAG(DebugLuauNoInline)
+LUAU_FASTFLAG(LuauExternReadWriteAttributes)
 
 // Clip with DebugLuauReportReturnTypeVariadicWithTypeSuffix
 extern bool luau_telemetry_parsed_return_type_variadic_with_type_suffix;
@@ -4780,4 +4781,37 @@ TEST_CASE_FIXTURE(Fixture, "explicit_type_instantiation_errors")
     matchParseError("local a = x:a<<T>>", "Expected '(', '{' or <string> when parsing function call, got <eof>");
 }
 
+TEST_CASE_FIXTURE(Fixture, "extern_read_write_attributes")
+{
+    ScopedFastFlag _[] = {
+        {FFlag::DebugLuauForceOldSolver, false},
+        {FFlag::LuauExternReadWriteAttributes, true}
+    };
+
+    ParseResult result = tryParse(R"(
+        declare extern type Foo with
+            read ReadOnlyMember: string
+            write WriteOnlyMember: number
+            ReadWriteMember: vector
+            wRITE BadAttributeMember: buffer
+        end
+    )");
+
+    REQUIRE_EQ(result.errors.size(), 1);
+    CHECK_EQ(result.errors[0].getLocation().begin.line, 5);
+    CHECK_EQ(result.errors[0].getMessage(), "Expected blank or 'read' or 'write' attribute, got 'wRITE'");
+
+    AstStatBlock* stat = result.root;
+
+    REQUIRE_EQ(stat->body.size, 1);
+
+    AstStatDeclareExternType* declaredExternType = stat->body.data[0]->as<AstStatDeclareExternType>();
+    CHECK_EQ(declaredExternType->props.size, 4);
+
+    CHECK_EQ(declaredExternType->props.data[0].access, AstTableAccess::Read);
+    CHECK_EQ(declaredExternType->props.data[1].access, AstTableAccess::Write);
+    CHECK_EQ(declaredExternType->props.data[2].access, AstTableAccess::ReadWrite);
+    CHECK_EQ(declaredExternType->props.data[3].access, AstTableAccess::ReadWrite);
+}
+
 TEST_SUITE_END();