ConstantValue needs an overhaul

[gafter]

There are numerous inconsistencies and irregularities in ConstantValue. For one, the conversions implemented do not match either language's conversion rules. For example, a value of type byte or ushort is sign-extended rather than padded when converted to int. We should have more extensive documentation and tests, and the implementation should be simplified so as to be more reliable.

See also #18521 and https://github.com/gafter/roslyn/tree/ConstantValue

[gafter]

I used this snippet to produce some tests:

        static void PrintTest(string type, string typeName)
        {
            Console.WriteLine($@"        [Fact]
        public void Test{typeName}Constant()
        {{
            unchecked
            {{
                void Test{typeName}Helper({type} value)
                {{
                    var k1 = ConstantValue.Create(value);
                    Assert.Equal((byte)value, k1.ByteValue);
                    Assert.Equal((sbyte)value, k1.SByteValue);
                    Assert.Equal((short)value, k1.Int16Value);
                    Assert.Equal((ushort)value, k1.UInt16Value);
                    Assert.Equal((int)value, k1.Int32Value);
                    Assert.Equal((uint)value, k1.UInt32Value);
                    Assert.Equal((long)value, k1.Int64Value);
                    Assert.Equal((ulong)value, k1.UInt64Value);
                }}
                Test{typeName}Helper(({type})(-2));
                Test{typeName}Helper(({type})(-1));
                Test{typeName}Helper(({type})(0));
                Test{typeName}Helper(({type})(1));
                Test{typeName}Helper(({type})(2));
                Test{typeName}Helper({type}.MinValue);
                Test{typeName}Helper(({type})({type}.MinValue + 1));
                Test{typeName}Helper(({type})({type}.MinValue + 2));
                Test{typeName}Helper(({type})({type}.MaxValue / 2 - 2));
                Test{typeName}Helper(({type})({type}.MaxValue / 2 - 1));
                Test{typeName}Helper(({type})({type}.MaxValue / 2));
                Test{typeName}Helper(({type})({type}.MaxValue / 2 + 1));
                Test{typeName}Helper(({type})({type}.MaxValue / 2 + 2));
                Test{typeName}Helper(({type})({type}.MaxValue - 2));
                Test{typeName}Helper(({type})({type}.MaxValue - 1));
                Test{typeName}Helper({type}.MaxValue);
            }}
        }}
");
        }
        static void Main(string[] args)
        {
            PrintTest("byte", "Byte");
            PrintTest("sbyte", "SByte");
            PrintTest("char", "Char");
            PrintTest("short", "Int16");
            PrintTest("ushort", "UInt16");
            PrintTest("int", "Int32");
            PrintTest("uint", "UInt32");
            PrintTest("long", "Int64");
            PrintTest("ulong", "UInt64");
        }

[prjm]

Just a question from an outsider: I was just looking around the code related to the ConstantValue class (because I tried to understand how constant propagation / constant value binding is working).
Is there any public documentation available which led to this design? Surely, one can read the code, but it's really a lot of code and it is not so easy to understand the big picture while skipping from one method to another. Otherwise, I'm amazed by the clarity of the code: it is very understandable and identifiers are self-explaining.