feat: add template class support to Concerto Reflection

Implement template class reflection with:
- Template class declaration and specialization parsing via ClangParser
- TemplateClass runtime representation with specialization lookup
- Code generation for template classes and their specializations
- Header generation for template class declarations
- Documentation and test coverage

Author: ArthurVasseur

.gitignore

@@ -1,5 +1,7 @@
 .vscode
 .xmake
+.cache
 dist-newstyle
 vsxmake2022
+compile_commands.json
 build

README.md

@@ -202,6 +202,111 @@ Concerto Reflection exposes a rich runtime API.  Here are some of the key capab
 * All reflection entities (packages, classes, enums, methods, members) can carry key–value attributes.  Use `HasAttribute` and `GetAttribute` to inspect them.
 * Built‑in types such as `Int32` are also registered with the reflection system, allowing you to treat fundamental types like any other class.
 
+
+### Template class support
+
+Concerto Reflection supports C++ template classes with full reflection metadata for each specialization.
+
+#### Annotating template classes
+
+Mark template classes with the standard reflection macros:
+
+```cpp
+template<typename T>
+class CCT_CLASS() Container : public cct::refl::Object
+{
+public:
+    Container() : m_value() {}
+
+    CCT_MEMBER()
+    T m_value;
+
+    CCT_METHOD()
+    void SetValue(T val) { m_value = val; }
+
+    CCT_METHOD()
+    T GetValue() const { return m_value; }
+
+    CCT_OBJECT(Container);
+};
+
+// Explicitly instantiate the specializations you want to reflect
+template class Container<int>;
+template class Container<double>;
+```
+
+#### Accessing template specializations at runtime
+
+Once loaded, you can retrieve specializations in two ways:
+
+**Method 1: Using the TemplateClass API**
+
+```cpp
+const auto* containerClass = cct::refl::GetClassByName("cct::sample::Container");
+if (containerClass && containerClass->IsTemplateClass())
+{
+    auto* templateClass = dynamic_cast<cct::refl::TemplateClass*>(
+        const_cast<cct::refl::Class*>(containerClass));
+
+    // Get a specific specialization by type string
+    auto* intSpec = templateClass->GetSpecialization("int"sv);
+    if (intSpec)
+    {
+        auto obj = intSpec->CreateDefaultObject();
+        // Use the specialized instance...
+    }
+}
+```
+
+**Method 2: Direct retrieval by full name**
+
+```cpp
+const auto* intSpec = cct::refl::GetClassByName("cct::sample::Container<int>");
+if (intSpec)
+{
+    auto obj = intSpec->CreateDefaultObject();
+    // Use the specialized instance...
+}
+```
+
+#### Multi-parameter templates
+
+Templates with multiple parameters are fully supported:
+
+```cpp
+template<typename K, typename V>
+class CCT_CLASS() Pair : public cct::refl::Object
+{
+public:
+    CCT_MEMBER()
+    K m_key;
+
+    CCT_MEMBER()
+    V m_value;
+
+    CCT_OBJECT(Pair);
+};
+
+// Explicitly instantiate specializations
+template class Pair<int, double>;
+template class Pair<std::string, int>;
+```
+
+Then retrieve them:
+
+```cpp
+const auto* pairSpec = cct::refl::GetClassByName("cct::sample::Pair<int,double>");
+```
+
+#### How it works
+
+The package generator:
+1. Detects template class declarations and their explicit instantiations
+2. Generates a base `TemplateClass` that describes the template parameters
+3. For each explicit instantiation, generates a specialization class with the concrete type information
+4. Registers all specializations in the reflection namespace for runtime discovery
+
+---
 ---
 
 ## 📚 Examples & Documentation

Src/Concerto/PackageGenerator/ClangParser/ClangParser.cpp

@@ -21,6 +21,7 @@
 #include <clang/Tooling/CompilationDatabase.h>
 #include <clang/Tooling/Tooling.h>
 #include <llvm/ADT/SmallString.h>
+#include <clang/AST/PrettyPrinter.h>
 
 using namespace clang;
 using namespace clang::tooling;
@@ -218,6 +219,8 @@ namespace cct
 		for (const auto* D : TU->decls())
 			ProcessDeclaration(D);
 
+		RemoveEmptyNamespaces(m_package.namepsaces);
+
 		return &m_package;
 	}
 
@@ -393,7 +396,15 @@ namespace cct
 
 	void ClangParser::ProcessDeclaration(const Decl* declaration)
 	{
-		if (const auto* RD = llvm::dyn_cast<CXXRecordDecl>(declaration))
+		if (const auto* CTD = llvm::dyn_cast<ClassTemplateDecl>(declaration))
+		{
+			ProcessTemplateRecord(CTD);
+		}
+		else if (const auto* CTSD = llvm::dyn_cast<ClassTemplateSpecializationDecl>(declaration))
+		{
+			ProcessTemplateSpecialization(CTSD);
+		}
+		else if (const auto* RD = llvm::dyn_cast<CXXRecordDecl>(declaration))
 		{
 			ProcessRecord(RD);
 		}
@@ -407,7 +418,11 @@ namespace cct
 			// Visit nested declarations inside namespaces
 			for (const auto* SD : ND->decls())
 			{
-				if (const auto* RD2 = llvm::dyn_cast<CXXRecordDecl>(SD))
+				if (const auto* CTD2 = llvm::dyn_cast<ClassTemplateDecl>(SD))
+					ProcessTemplateRecord(CTD2);
+				else if (const auto* CTSD2 = llvm::dyn_cast<ClassTemplateSpecializationDecl>(SD))
+					ProcessTemplateSpecialization(CTSD2);
+				else if (const auto* RD2 = llvm::dyn_cast<CXXRecordDecl>(SD))
 					ProcessRecord(RD2);
 				else if (const auto* ED2 = llvm::dyn_cast<EnumDecl>(SD))
 					ProcessEnum(ED2);
@@ -416,4 +431,205 @@ namespace cct
 			}
 		}
 	}
+
+	void ClangParser::ProcessTemplateRecord(const ClassTemplateDecl* templateDeclaration)
+	{
+		if (!templateDeclaration)
+			return;
+
+		const auto* recordDecl = templateDeclaration->getTemplatedDecl();
+		if (!recordDecl || !recordDecl->isThisDeclarationADefinition())
+			return;
+
+		std::optional<std::pair<std::string, TomlAttributes>> classAttr;
+		for (const auto* A : recordDecl->attrs())
+		{
+			std::string scope; TomlAttributes attrs;
+			if (!ExtractCctAttribute(A, *m_astContext, *m_sourceManager, *m_langOptions, scope, attrs))
+				continue;
+			if (scope == "cct::Class")
+			{
+				classAttr = std::make_pair(scope, attrs);
+				break;
+			}
+		}
+
+		if (!classAttr)
+			return;
+
+		Class cls;
+		cls.name = recordDecl->getNameAsString();
+		cls.scope = "cct::Class";
+		cls.tomlAttributes = GetAttributesOr(classAttr->second, {});
+		cls.isTemplateClass = true;
+
+		const auto* paramList = templateDeclaration->getTemplateParameters();
+		if (paramList)
+		{
+			for (unsigned i = 0; i < paramList->size(); ++i)
+			{
+				const auto* templateParam = paramList->getParam(i);
+				::TemplateParameter tparam;
+				if (const auto* typeParam = llvm::dyn_cast<TemplateTypeParmDecl>(templateParam))
+				{
+					tparam.name = typeParam->getNameAsString();
+					if (typeParam->hasDefaultArgument())
+					{
+						// TODO: Extract default argument
+					}
+				}
+				else if (const auto* nonTypeParam = llvm::dyn_cast<NonTypeTemplateParmDecl>(templateParam))
+				{
+					tparam.name = nonTypeParam->getNameAsString();
+				}
+
+				if (!tparam.name.empty())
+					cls.templateParameters.push_back(std::move(tparam));
+			}
+		}
+
+		if (recordDecl->getNumBases() > 0)
+		{
+			const auto& base = *recordDecl->bases_begin();
+			cls.base = QualTypeToString(base.getType(), *m_astContext);
+		}
+
+		for (const auto* F : recordDecl->fields())
+		{
+			bool hasAttr = false;
+			TomlAttributes memberAttrs;
+			std::string scope;
+			for (const auto* A : F->attrs())
+			{
+				TomlAttributes attrs;
+				if (!ExtractCctAttribute(A, *m_astContext, *m_sourceManager, *m_langOptions, scope, attrs))
+					continue;
+				if (scope == "cct::Member" || scope == "cct::NativeMember")
+				{
+					hasAttr = true;
+					memberAttrs = GetAttributesOr(attrs, {});
+					break;
+				}
+			}
+			if (!hasAttr) continue;
+
+			Class::Member m;
+			m.name = F->getNameAsString();
+			m.type = QualTypeToString(F->getType(), *m_astContext);
+			m.isNative = scope == "cct::NativeMember";
+			m.tomlAttributes = memberAttrs;
+			cls.members.push_back(std::move(m));
+		}
+
+		for (const auto* M : recordDecl->methods())
+		{
+			bool hasAttr = false;
+			TomlAttributes methodAttrs;
+			for (const auto* A : M->attrs())
+			{
+				std::string scope; TomlAttributes attrs;
+				if (!ExtractCctAttribute(A, *m_astContext, *m_sourceManager, *m_langOptions, scope, attrs))
+					continue;
+				if (scope == "cct::Method")
+				{
+					hasAttr = true;
+					methodAttrs = GetAttributesOr(attrs, {});
+					break;
+				}
+			}
+			if (!hasAttr) continue;
+
+			Class::Method mm;
+			mm.name = M->getNameAsString();
+			mm.returnValue = QualTypeToString(M->getReturnType(), *m_astContext);
+			mm.tomlAttributes = methodAttrs;
+
+			unsigned pi = 0;
+			for (const auto* P : M->parameters())
+			{
+				Class::Method::Params param;
+				param.type = QualTypeToString(P->getType(), *m_astContext);
+				if (P->getIdentifier()) param.name = P->getNameAsString();
+				else { param.name = std::string("arg") + std::to_string(pi); }
+				mm.params.push_back(std::move(param));
+				++pi;
+			}
+			cls.methods.push_back(std::move(mm));
+		}
+
+		std::vector<std::string> nsChain = GetNamespaceChain(recordDecl->getDeclContext());
+		InsertClassIntoPackage(m_package, nsChain, cls);
+	}
+
+	void ClangParser::ProcessTemplateSpecialization(const ClassTemplateSpecializationDecl* specializationDeclaration)
+	{
+		if (!specializationDeclaration || !specializationDeclaration->isThisDeclarationADefinition())
+			return;
+
+		const auto& templateArgs = specializationDeclaration->getTemplateArgs();
+		std::vector<std::string> typeArgs;
+
+		for (unsigned i = 0; i < templateArgs.size(); ++i)
+		{
+			const auto& arg = templateArgs[i];
+			if (arg.getKind() == TemplateArgument::Type)
+			{
+				typeArgs.push_back(QualTypeToString(arg.getAsType(), *m_astContext));
+			}
+			else if (arg.getKind() == TemplateArgument::Integral)
+			{
+				llvm::SmallString<32> s;
+				arg.getAsIntegral().toString(s, /*Radix=*/10);
+				typeArgs.emplace_back(s.begin(), s.end());
+			}
+		}
+
+		const auto* templateDecl = specializationDeclaration->getSpecializedTemplate();
+		if (!templateDecl)
+			return;
+
+		const auto templateClassName = templateDecl->getNameAsString();
+
+		std::vector<std::string> nsChain = GetNamespaceChain(specializationDeclaration->getDeclContext());
+		Namespace* leaf = nsChain.empty() ? nullptr : EnsureNamespace(m_package, nsChain);
+		auto& classList = nsChain.empty() ? m_package.classes : leaf->classes;
+
+		auto it = std::ranges::find_if(classList, [&](const Class& c)
+		{
+			return c.name == templateClassName && c.isTemplateClass;
+		});
+
+		if (it == classList.end())
+			return;
+
+		it->templateSpecializations.push_back(typeArgs.empty() ? "" :
+			[&typeArgs]()
+			{
+				std::string result;
+				for (std::size_t i = 0; i < typeArgs.size(); ++i)
+				{
+					result += typeArgs[i];
+					if (i < typeArgs.size() - 1)
+						result += ",";
+				}
+				return result;
+			}()
+		);
+	}
+
+	void ClangParser::RemoveEmptyNamespaces(std::vector<Namespace>& namespaces)
+	{
+		auto it = namespaces.begin();
+		while (it != namespaces.end())
+		{
+			RemoveEmptyNamespaces(it->namespaces);
+
+			bool isEmpty = it->classes.empty() && it->enums.empty() && it->namespaces.empty();
+
+			if (isEmpty)
+				it = namespaces.erase(it);
+			else
+				++it;
+		}
+	}
 }