Merge remote-tracking branch 'origin/main' into 2026-08-16-issue-78

`main` gave `buildFileForContract` the caller's licence and copyright and
renamed the identifier rule, neither of which a textual merge reaches:
the tagged overload delegates to a signature that no longer exists. It
carries both through to the delegate, and the paragraph restating the
single unlink is replaced by what the loop main landed actually does.

The two sides each added a symlink test to `LibFsIsPresentTest`; both
stay, one for the tagged path and one for a live link.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: thedavidmeister

foundry.toml

@@ -1,6 +1,6 @@
 [package]
 name = "rain-sol-codegen"
-version = "0.1.30"
+version = "0.1.32"
 
 [profile.default]
 src = 'src'

src/lib/LibCodeGen.sol

@@ -17,15 +17,27 @@ uint256 constant MAX_LINE_LENGTH = 120;
 /// needs to match what formatters expect.
 string constant NEWLINE_DUE_TO_MAX_LENGTH = "\n    ";
 
-/// Thrown when a contract name is not a Solidity identifier. Such a name cannot
-/// be interpolated into a file path or a constant declaration.
+/// Thrown when a name is not a Solidity identifier. Such a name cannot be
+/// interpolated into a file path or a constant declaration.
 /// @param name The rejected name.
-error InvalidContractName(string name);
+error InvalidIdentifier(string name);
 
 /// Thrown when a bytecode hash is asked for at an address that holds no code.
 /// @param instance The address that holds no code.
 error CodelessInstance(address instance);
 
+/// Thrown when an SPDX licence identifier is not a non-empty single line. An
+/// empty identifier names no licence on a tag that a presence check accepts, and
+/// solc refuses the file it heads with "Invalid SPDX license identifier". A line
+/// break ends the tag's line so that everything after it lands as source.
+/// @param spdxLicenseIdentifier The rejected identifier.
+error InvalidSpdxLicenseIdentifier(string spdxLicenseIdentifier);
+
+/// Thrown when a copyright text is not a non-empty single line, for the same
+/// reasons the licence identifier has to be one.
+/// @param copyrightText The rejected text.
+error InvalidCopyrightText(string copyrightText);
+
 /// @title LibCodeGen
 /// @notice Library for generating Solidity code snippets for contract function
 /// pointers, code hashes, associated comments, etc. All snippets are returned
@@ -34,22 +46,27 @@ error CodelessInstance(address instance);
 library LibCodeGen {
     /// Reverts unless `name` is a Solidity identifier: at least one character,
     /// drawn from ASCII letters, digits, `_` and `$`, and not starting with a
-    /// digit. A contract name is such an identifier, and restricting it to one
-    /// is also what makes it safe to interpolate into a path: no identifier
-    /// contains a path separator, and none of them is `.` or `..`.
+    /// digit. Every name this library interpolates verbatim into generated
+    /// source or into a path is one, and being an identifier is what makes that
+    /// interpolation safe. A declaration named by an identifier is the
+    /// declaration the caller asked for and no other, because no identifier
+    /// carries a space, a `;` or any other character that ends a declaration or
+    /// starts another. A path built from an identifier stays a direct child of
+    /// the directory it is joined to, because no identifier contains a path
+    /// separator and none of them is `.` or `..`.
     /// @param name The name to check.
-    function requireContractName(string memory name) internal pure {
+    function requireIdentifier(string memory name) internal pure {
         bytes memory nameBytes = bytes(name);
         if (nameBytes.length == 0) {
-            revert InvalidContractName(name);
+            revert InvalidIdentifier(name);
         }
         for (uint256 i = 0; i < nameBytes.length; i++) {
             bytes1 char = nameBytes[i];
             bool isLetter = (char >= 0x41 && char <= 0x5A) || (char >= 0x61 && char <= 0x7A);
             bool isDigit = char >= 0x30 && char <= 0x39;
             bool isUnderscoreOrDollar = char == 0x5F || char == 0x24;
             if (!(isLetter || isUnderscoreOrDollar || (isDigit && i > 0))) {
-                revert InvalidContractName(name);
+                revert InvalidIdentifier(name);
             }
         }
     }
@@ -66,16 +83,58 @@ library LibCodeGen {
         return bytes(comment).length == 0 ? "\n" : string.concat("\n", comment, "\n");
     }
 
+    /// True when `text` can be interpolated into a header line as itself: at
+    /// least one byte, and no byte that ends a line. Solidity ends a `//`
+    /// comment at either a line feed or a carriage return, so a value carrying
+    /// one would close the tag's line and continue as source.
+    /// @param text The text to check.
+    /// @return Whether the text is a non-empty single line.
+    function isSingleLine(string memory text) internal pure returns (bool) {
+        bytes memory textBytes = bytes(text);
+        if (textBytes.length == 0) {
+            return false;
+        }
+        for (uint256 i = 0; i < textBytes.length; i++) {
+            if (textBytes[i] == 0x0A || textBytes[i] == 0x0D) {
+                return false;
+            }
+        }
+        return true;
+    }
+
     /// The file prefix for autogenerated files outlines the license, pragma,
     /// and a note about the file being autogenerated. The pragma is ^ as the
     /// generated code is expected to be imported into some concrete contract
     /// with pragma = version.
-    function filePrefix() internal pure returns (string memory) {
+    ///
+    /// The generated file lands in the calling project's repo, so the licence it
+    /// is under and the copyright holder it names are the calling project's to
+    /// state and are taken from the caller. Both are interpolated verbatim into
+    /// their tags, and both have to be a non-empty single line for the tag they
+    /// land on to say what it appears to.
+    /// @param spdxLicenseIdentifier The SPDX licence identifier for the
+    /// generated file, interpolated verbatim.
+    /// @param copyrightText The copyright text for the generated file,
+    /// interpolated verbatim.
+    /// @return The text that heads the generated file.
+    function filePrefix(string memory spdxLicenseIdentifier, string memory copyrightText)
+        internal
+        pure
+        returns (string memory)
+    {
+        if (!isSingleLine(spdxLicenseIdentifier)) {
+            revert InvalidSpdxLicenseIdentifier(spdxLicenseIdentifier);
+        }
+        if (!isSingleLine(copyrightText)) {
+            revert InvalidCopyrightText(copyrightText);
+        }
         //REUSE-IgnoreStart
         return string.concat(
-            "// SPDX-License-Identifier: LicenseRef-DCL-1.0\n"
-            "// SPDX-FileCopyrightText: Copyright (c) 2020 Rain Open Source Software Ltd\n"
-            "pragma solidity ^0.8.25;\n\n",
+            "// SPDX-License-Identifier: ",
+            spdxLicenseIdentifier,
+            "\n" "// SPDX-FileCopyrightText: ",
+            copyrightText,
+            "\n" "pragma solidity ^0.8.25;\n\n",
             "// THIS FILE IS AUTOGENERATED BY THE BUILD SCRIPT. DO NOT EDIT BY HAND.\n"
         );
         //REUSE-IgnoreEnd
@@ -253,7 +312,7 @@ library LibCodeGen {
     /// @return A string containing the Solidity code for the described by meta
     /// hash constant.
     function describedByMetaHashConstantString(Vm vm, string memory name) internal view returns (string memory) {
-        requireContractName(name);
+        requireIdentifier(name);
         bytes memory describedByMeta = vm.readFileBinary(string.concat("meta/", name, ".rain.meta"));
         return bytes32ConstantString(
             vm,
@@ -269,14 +328,16 @@ library LibCodeGen {
     /// @param vm The Vm instance used to format values as strings.
     /// @param comment The comment to include above the constant declaration.
     /// An empty comment emits no comment line.
-    /// @param name The name of the constant.
+    /// @param name The name of the constant, interpolated verbatim. Has to be a
+    /// Solidity identifier.
     /// @param data The bytes data for the constant.
     /// @return A string containing the Solidity code for the bytes constant.
     function bytesConstantString(Vm vm, string memory comment, string memory name, bytes memory data)
         internal
         pure
         returns (string memory)
     {
+        requireIdentifier(name);
         string memory hexData = LibHexString.bytesToHex(vm, data);
         return string.concat(
             commentPrefix(comment),
@@ -297,14 +358,16 @@ library LibCodeGen {
     /// @param vm The Vm instance used to format values as strings.
     /// @param comment The comment to include above the constant declaration.
     /// An empty comment emits no comment line.
-    /// @param name The name of the constant.
+    /// @param name The name of the constant, interpolated verbatim. Has to be a
+    /// Solidity identifier.
     /// @param data The uint8 data for the constant.
     /// @return A string containing the Solidity code for the uint8 constant.
     function uint8ConstantString(Vm vm, string memory comment, string memory name, uint8 data)
         internal
         pure
         returns (string memory)
     {
+        requireIdentifier(name);
         string memory intString = vm.toString(data);
         return string.concat(
             commentPrefix(comment),
@@ -325,14 +388,16 @@ library LibCodeGen {
     /// @param vm The Vm instance used to format values as strings.
     /// @param comment The comment to include above the constant declaration.
     /// An empty comment emits no comment line.
-    /// @param name The name of the constant.
+    /// @param name The name of the constant, interpolated verbatim. Has to be a
+    /// Solidity identifier.
     /// @param data The bytes32 value for the constant.
     /// @return A string containing the Solidity code for the bytes32 constant.
     function bytes32ConstantString(Vm vm, string memory comment, string memory name, bytes32 data)
         internal
         pure
         returns (string memory)
     {
+        requireIdentifier(name);
         string memory hexString = vm.toString(data);
         return string.concat(
             commentPrefix(comment),
@@ -354,14 +419,16 @@ library LibCodeGen {
     /// @param vm The Vm instance used to format values as strings.
     /// @param comment The comment to include above the constant declaration.
     /// An empty comment emits no comment line.
-    /// @param name The name of the constant.
+    /// @param name The name of the constant, interpolated verbatim. Has to be a
+    /// Solidity identifier.
     /// @param data The address for the constant.
     /// @return A string containing the Solidity code for the address constant.
     function addressConstantString(Vm vm, string memory comment, string memory name, address data)
         internal
         pure
         returns (string memory)
     {
+        requireIdentifier(name);
         string memory addressString = vm.toString(data);
         return string.concat(
             commentPrefix(comment),

src/lib/LibFs.sol

@@ -102,7 +102,7 @@ library LibFs {
     /// @param contractName The name of the contract, interpolated verbatim.
     /// @return The file path as a string.
     function pathForContractIn(string memory dir, string memory contractName) private pure returns (string memory) {
-        LibCodeGen.requireContractName(contractName);
+        LibCodeGen.requireIdentifier(contractName);
         return string.concat(dir, "/", contractName, ".sol");
     }
 
@@ -171,30 +171,51 @@ library LibFs {
     /// committed already.
     ///
     /// The whole file content is built before anything on disk is touched, and
-    /// building it reverts for an `instance` that holds no code. A revert does
-    /// not roll back cheatcode filesystem effects, so ordering the build first
-    /// is what keeps a failed generation from leaving the directory worse than
-    /// it found it: nothing is created, unlinked or written unless there is
-    /// content to write.
+    /// building it reverts for an `instance` that holds no code and for a
+    /// licence or copyright `filePrefix` refuses. A revert does not roll back
+    /// cheatcode filesystem effects, so ordering the build first is what keeps
+    /// a failed generation from leaving the directory worse than it found it:
+    /// nothing is created, unlinked or written unless there is content to
+    /// write.
     ///
-    /// Anything already at the path is unlinked before the write, so a symlink
+    /// The path is unlinked until it holds nothing, then written, so a symlink
     /// there is replaced by a regular file rather than written through to its
-    /// target, including a symlink whose target does not exist, and the path
-    /// does not exist between the unlink and the write.
-    /// Any manual changes to the generated file, or any other existing file at
-    /// that path, are lost.
+    /// target, whether or not that target exists, and the path does not exist
+    /// between the last unlink and the write. Taking a live symlink off the
+    /// path takes what it resolves to with it, because that is what the unlink
+    /// acts on first.
+    /// Any manual changes to the generated file, any other existing file at
+    /// that path, and whatever a symlink at that path resolves to, are lost.
+    ///
+    /// A directory at the path, and a symlink at the path that resolves to a
+    /// directory, are the cases this cannot unlink, and both revert rather than
+    /// being written into or through.
     ///
     /// The whole file is written on every call, so the same arguments always
     /// produce the same bytes. The prefix and bytecode hash constant are always
     /// included, further content is provided in the body parameter, which is
     /// expected to be generated by `LibCodeGen` by the caller.
+    ///
+    /// The file lands in the calling project's repo, so the licence it is under
+    /// and the copyright holder it names come from the caller and are subject to
+    /// `LibCodeGen.filePrefix`'s rule for them.
     /// @param vm The Vm instance for file operations.
     /// @param instance The contract instance whose bytecode hash is to be
     /// included.
     /// @param contractName The name of the contract.
+    /// @param spdxLicenseIdentifier The SPDX licence identifier the written file
+    /// declares.
+    /// @param copyrightText The copyright text the written file declares.
     /// @param body The body of the contract file to be written.
-    function buildFileForContract(Vm vm, address instance, string memory contractName, string memory body) internal {
-        buildFileForContract(vm, instance, GENERATED_DIR, contractName, body);
+    function buildFileForContract(
+        Vm vm,
+        address instance,
+        string memory contractName,
+        string memory spdxLicenseIdentifier,
+        string memory copyrightText,
+        string memory body
+    ) internal {
+        buildFileForContract(vm, instance, GENERATED_DIR, contractName, spdxLicenseIdentifier, copyrightText, body);
     }
 
     /// @notice Builds a file for a generated contract inside `dir` rather than
@@ -217,20 +238,32 @@ library LibFs {
     /// @param dir The directory to put the file in, without a trailing
     /// separator, interpolated verbatim.
     /// @param contractName The name of the contract.
+    /// @param spdxLicenseIdentifier The SPDX licence identifier the written file
+    /// declares.
+    /// @param copyrightText The copyright text the written file declares.
     /// @param body The body of the contract file to be written.
     function buildFileForContract(
         Vm vm,
         address instance,
         string memory dir,
         string memory contractName,
+        string memory spdxLicenseIdentifier,
+        string memory copyrightText,
         string memory body
     ) internal {
         string memory path = pathForContractIn(dir, contractName);
-        string memory content =
-            string.concat(LibCodeGen.filePrefix(), LibCodeGen.bytecodeHashConstantString(vm, instance), body);
+        string memory content = string.concat(
+            LibCodeGen.filePrefix(spdxLicenseIdentifier, copyrightText),
+            LibCodeGen.bytecodeHashConstantString(vm, instance),
+            body
+        );
         //forge-lint: disable-next-line(unsafe-cheatcode)
         vm.createDir(dir, true);
-        if (isPresent(vm, path)) {
+        // `vm.removeFile` resolves the path before it acts, so on a live symlink
+        // it takes what the link points at and leaves the link, now dangling.
+        // Every pass removes something the next one no longer finds, so this
+        // ends with the path holding nothing.
+        while (isPresent(vm, path)) {
             //forge-lint: disable-next-line(unsafe-cheatcode)
             vm.removeFile(path);
         }
@@ -251,17 +284,21 @@ library LibFs {
     /// `GENERATED_DIR` itself, so the first generation for a tag does not need
     /// it committed already.
     ///
-    /// Anything already at the path is unlinked before the write, so a symlink
+    /// The path is unlinked until it holds nothing, then written, so a symlink
     /// there is replaced by a regular file rather than written through to its
-    /// target, including a symlink whose target does not exist, and the path
-    /// does not exist between the unlink and the write.
-    /// Any manual changes to the generated file, or any other existing file at
-    /// that path, are lost.
+    /// target, whether or not that target exists, and the path does not exist
+    /// between the last unlink and the write.
+    /// Any manual changes to the generated file, any other existing file at
+    /// that path, and whatever a symlink at that path resolves to, are lost.
     ///
     /// The whole file is written on every call, so the same arguments always
     /// produce the same bytes. The prefix and bytecode hash constant are always
     /// included, further content is provided in the body parameter, which is
     /// expected to be generated by `LibCodeGen` by the caller.
+    ///
+    /// The file lands in the calling project's repo, so the licence it is under
+    /// and the copyright holder it names come from the caller and are subject to
+    /// `LibCodeGen.filePrefix`'s rule for them.
     /// @dev This is the `dir` overload of `buildFileForContract` applied to
     /// `dirForTag(tag)`, so everything that overload states holds here, and the
     /// only thing this function adds is that the directory is not the caller's
@@ -272,14 +309,19 @@ library LibFs {
     /// included.
     /// @param tag The tag whose directory the file lives in.
     /// @param contractName The name of the contract.
+    /// @param spdxLicenseIdentifier The SPDX licence identifier the written file
+    /// declares.
+    /// @param copyrightText The copyright text the written file declares.
     /// @param body The body of the contract file to be written.
     function buildFileForTaggedContract(
         Vm vm,
         address instance,
         string memory tag,
         string memory contractName,
+        string memory spdxLicenseIdentifier,
+        string memory copyrightText,
         string memory body
     ) internal {
-        buildFileForContract(vm, instance, dirForTag(tag), contractName, body);
+        buildFileForContract(vm, instance, dirForTag(tag), contractName, spdxLicenseIdentifier, copyrightText, body);
     }
 }

test/concrete/CodeGennable.sol

@@ -7,7 +7,7 @@ pragma solidity =0.8.25;
 /// code. It carries no behaviour of its own: what the tests want from it is a
 /// stable, non-zero `codehash` to feed to `bytecodeHashConstantString` and
 /// `buildFileForContract`. The name is asserted on in
-/// `LibCodeGen.requireContractName.t.sol` and used as a contract name in
+/// `LibCodeGen.requireIdentifier.t.sol` and used as a contract name in
 /// `LibCodeGen.describedByMetaHashConstantString.t.sol`, so it is not free to
 /// change.
 contract CodeGennable {}