Revision control
++ // Copyright (C) 2024 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
++ // Qt-Security score:significant reason:default
++
++ #include "qqmllshelputils_p.h"
++
++ #include <QtQmlLS/private/qqmllsutils_p.h>
++ #include <QtCore/private/qfactoryloader_p.h>
++ #include <QtCore/qlibraryinfo.h>
++ #include <QtCore/qdiriterator.h>
++ #include <QtCore/qdir.h>
++ #include <QtQmlCompiler/private/qqmljstyperesolver_p.h>
++
++ #include <QtCore/qtyperevision.h>
++
++ #include <optional>
++
++ QT_BEGIN_NAMESPACE
++
++ Q_STATIC_LOGGING_CATEGORY(QQmlLSHelpUtilsLog, "qt.languageserver.helpUtils")
++
++ using namespace QQmlJS::Dom;
++
++ static QStringList documentationFiles(const QString &qtInstallationPath)
++ {
++ QStringList result;
++ QDirIterator dirIterator(qtInstallationPath, QStringList{ "*.qch"_L1 }, QDir::Files);
++ while (dirIterator.hasNext()) {
++ const auto fileInfo = dirIterator.nextFileInfo();
++ result << fileInfo.absoluteFilePath();
++ }
++ return result;
++ }
++
++ HelpManager::HelpManager()
++ {
++ const QFactoryLoader pluginLoader(QQmlLSHelpPluginInterface_iid, u"/help"_s);
++ const auto keys = pluginLoader.metaDataKeys();
++ for (qsizetype i = 0; i < keys.size(); ++i) {
++ auto instance = qobject_cast<QQmlLSHelpPluginInterface *>(pluginLoader.instance(i));
++ if (instance) {
++ m_helpPlugin =
++ instance->initialize(QDir::tempPath() + "/collectionFile.qhc"_L1, nullptr);
++ break;
++ }
++ }
++ }
++
++ void HelpManager::setDocumentationRootPath(const QString &path)
++ {
++ QMutexLocker guard(&m_mutex);
++ if (m_docRootPath == path)
++ return;
++ m_docRootPath = path;
++
++ const auto foundQchFiles = documentationFiles(path);
++ if (foundQchFiles.isEmpty()) {
++ qCWarning(QQmlLSHelpUtilsLog)
++ << "No documentation files found in the Qt doc installation path: " << path;
++ return;
++ }
++
++ return registerDocumentations(foundQchFiles);
++ }
++
++ QString HelpManager::documentationRootPath() const
++ {
++ QMutexLocker guard(&m_mutex);
++ return m_docRootPath;
++ }
++
++ void HelpManager::registerDocumentations(const QStringList &docs) const
++ {
++ if (!m_helpPlugin)
++ return;
++ std::for_each(docs.cbegin(), docs.cend(),
++ [this](const auto &file) { m_helpPlugin->registerDocumentation(file); });
++ }
++
++ static QByteArray documentationForImports(const DomItem &item)
++ {
++ DomItem domImport;
++ item.filterUp(
++ [&domImport](DomType type, const DomItem &item) {
++ if (type != DomType::Import)
++ return true;
++ domImport = item;
++ return false;
++ },
++ FilterUpOptions::ReturnOuter);
++ if (!domImport)
++ return {};
++
++ const Import *import = domImport.as<Import>();
++ if (!import)
++ return {};
++ auto domEnvironment = item.environment().ownerAs<DomEnvironment>();
++ if (!domEnvironment)
++ return {};
++ const auto &importer = domEnvironment->semanticAnalysis().m_importer;
++ if (!importer)
++ return {};
++
++ const QString qmldirLocation = importer->pathOfModule(
++ import->uri.toString(),
++ import->version.isLatest() ? QTypeRevision()
++ : QTypeRevision::fromVersion(import->version.majorVersion,
++ import->version.minorVersion));
++
++ return "Library at path %1\n\nImport paths:\n\n * %2"_L1
++ .arg(qmldirLocation, domEnvironment->loadPaths().join("\n * "_L1))
++ .toUtf8();
++ }
++
++
++ std::optional<QByteArray> HelpManager::extractDocumentation(const DomItem &item) const
++ {
++ if (const QByteArray documentation = documentationForImports(item); !documentation.isEmpty())
++ return documentation;
++
++ if (!m_helpPlugin || m_helpPlugin->registeredNamespaces().empty())
++ return std::nullopt;
++
++ if (item.internalKind() == DomType::ScriptIdentifierExpression) {
++ const auto resolvedType =
++ QQmlLSUtils::resolveExpressionType(item, QQmlLSUtils::ResolveOwnerType);
++ if (!resolvedType)
++ return std::nullopt;
++ return extractDocumentationForIdentifiers(item, resolvedType.value());
++ } else {
++ return extractDocumentationForDomElements(item);
++ }
++
++ Q_UNREACHABLE_RETURN(std::nullopt);
++ }
++
++ std::optional<QByteArray>
++ HelpManager::extractDocumentationForIdentifiers(const DomItem &item,
++ QQmlLSUtils::ExpressionType expr) const
++ {
++ const auto links = collectDocumentationLinks(item, expr.semanticScope, expr.name.value_or(item.name()));
++ if (links.empty())
++ return std::nullopt;
++ switch (expr.type) {
++ case QQmlLSUtils::QmlObjectIdIdentifier:
++ case QQmlLSUtils::JavaScriptIdentifier:
++ case QQmlLSUtils::GroupedPropertyIdentifier:
++ case QQmlLSUtils::PropertyIdentifier: {
++ ExtractDocumentation extractor(DomType::PropertyDefinition);
++ return tryExtract(extractor, links, expr.name.value());
++ }
++ case QQmlLSUtils::PropertyChangedSignalIdentifier:
++ case QQmlLSUtils::PropertyChangedHandlerIdentifier:
++ case QQmlLSUtils::SignalIdentifier:
++ case QQmlLSUtils::SignalHandlerIdentifier:
++ case QQmlLSUtils::MethodIdentifier: {
++ ExtractDocumentation extractor(DomType::MethodInfo);
++ return tryExtract(extractor, links, expr.name.value());
++ }
++ case QQmlLSUtils::SingletonIdentifier:
++ case QQmlLSUtils::AttachedTypeIdentifier:
++ case QQmlLSUtils::AttachedTypeIdentifierInBindingTarget:
++ case QQmlLSUtils::QmlComponentIdentifier: {
++ const auto &keyword = item.field(Fields::identifier).value().toString();
++ // The keyword is a qmlobject. Keyword search should be sufficient.
++ // TODO: Still there can be multiple qmlobject documentation, with
++ // different Qt versions. We should pick the best one.
++ ExtractDocumentation extractor(DomType::QmlObject);
++ return tryExtract(extractor, m_helpPlugin->documentsForKeyword(keyword), keyword);
++ }
++
++ // Not implemented yet
++ case QQmlLSUtils::EnumeratorIdentifier:
++ case QQmlLSUtils::EnumeratorValueIdentifier:
++ default:
++ qCDebug(QQmlLSHelpUtilsLog)
++ << "Documentation extraction for" << expr.name.value() << "was not implemented";
++ return std::nullopt;
++ }
++ Q_UNREACHABLE_RETURN(std::nullopt);
++ }
++
++ std::optional<QByteArray> HelpManager::extractDocumentationForDomElements(const DomItem &item) const
++ {
++ const auto qmlFile = item.containingFile().as<QmlFile>();
++ if (!qmlFile)
++ return std::nullopt;
++
++ const auto name = item.field(Fields::name).value().toString();
++ std::vector<QQmlLSHelpProviderBase::DocumentLink> links;
++ switch (item.internalKind()) {
++ case DomType::QmlObject: {
++ links = collectDocumentationLinks(item, item.nearestSemanticScope(), name);
++ break;
++ }
++ case DomType::PropertyDefinition: {
++ links = collectDocumentationLinks(
++ item, QQmlLSUtils::findDefiningScopeForProperty(item.nearestSemanticScope(), name),
++ name);
++ break;
++ }
++ case DomType::Binding: {
++ links = collectDocumentationLinks(
++ item, QQmlLSUtils::findDefiningScopeForBinding(item.nearestSemanticScope(), name),
++ name);
++ break;
++ }
++ case DomType::MethodInfo: {
++ links = collectDocumentationLinks(
++ item, QQmlLSUtils::findDefiningScopeForMethod(item.nearestSemanticScope(), name),
++ name);
++ break;
++ }
++ default:
++ qCDebug(QQmlLSHelpUtilsLog)
++ << item.internalKindStr() << "was not implemented for documentation extraction";
++ return std::nullopt;
++ }
++
++ ExtractDocumentation extractor(item.internalKind());
++ return tryExtract(extractor, links, name);
++ }
++
++ std::optional<QByteArray>
++ HelpManager::tryExtract(ExtractDocumentation &extractor,
++ const std::vector<QQmlLSHelpProviderBase::DocumentLink> &links,
++ const QString &name) const
++ {
++ if (!m_helpPlugin)
++ return std::nullopt;
++
++ for (auto &&link : links) {
++ const auto fileData = m_helpPlugin->fileData(link.url);
++ if (fileData.isEmpty()) {
++ qCDebug(QQmlLSHelpUtilsLog) << "No documentation found for" << link.url;
++ continue;
++ }
++ const auto &documentation = extractor.execute(QString::fromUtf8(fileData), name,
++ HtmlExtractor::ExtractionMode::Simplified);
++ if (documentation.isEmpty())
++ continue;
++ return documentation.toUtf8();
++ }
++
++ return std::nullopt;
++ }
++
++ std::optional<QByteArray>
++ HelpManager::documentationForItem(const DomItem &file, QLspSpecification::Position position)
++ {
++ QMutexLocker guard(&m_mutex);
++
++ // Prepare Cpp types to Qml types mapping.
++ const auto fileItem = file.containingFile().as<QmlFile>();
++ if (!fileItem)
++ return std::nullopt;
++ const auto typeResolver = fileItem->typeResolver();
++ if (typeResolver) {
++ const auto &names = typeResolver->importedNames();
++ for (auto &&[scope, qmlName] : names.asKeyValueRange()) {
++ auto sc = scope;
++ // in some situations, scope->internalName() could be the same
++ // as qmlName. In those cases, the key we are looking for is the
++ // first scope which is non-composite type.
++ // This is mostly the case for templated controls.
++ // Popup <-> Popup
++ // T.Popup <-> Popup
++ // QQuickPopup <-> Popup
++ if (sc && sc->internalName() == qmlName) {
++ while (sc && sc->isComposite())
++ sc = sc->baseType();
++ }
++ if (sc && !m_cppTypesToQmlTypes.contains(sc->internalName()))
++ m_cppTypesToQmlTypes.insert(sc->internalName(), qmlName);
++ }
++ }
++
++ std::optional<QByteArray> result;
++ const auto [line, character] = position;
++ const auto itemLocations = QQmlLSUtils::itemsFromTextLocation(file, line, character);
++ // Process found item's internalKind and fetch its documentation.
++ for (const auto &entry : itemLocations) {
++ result = extractDocumentation(entry.domItem);
++ if (result.has_value())
++ break;
++ }
++
++ return result;
++ }
++
++ /*
++ * Returns the list of potential documentation links for the given item.
++ * A keyword is not necessarily a unique name, so we need to find the scope where
++ * the keyword is defined. If the item is a property, method or binding, it will
++ * search for the defining scope and return the documentation links by looking at
++ * the imported names. If the item is a QmlObject, it will return the documentation
++ * links for qmlobject name.
++ */
++ std::vector<QQmlLSHelpProviderBase::DocumentLink>
++ HelpManager::collectDocumentationLinks(const DomItem &item, const QQmlJSScope::ConstPtr &definingScope,
++ const QString &name) const
++ {
++ if (!(m_helpPlugin && definingScope))
++ return {};
++ const auto &qmlFile = item.containingFile().as<QmlFile>();
++ if (!qmlFile)
++ return {};
++ const auto typeResolver = qmlFile->typeResolver();
++ if (!typeResolver)
++ return {};
++
++ std::vector<QQmlLSHelpProviderBase::DocumentLink> links;
++ const auto &foundScopeName = definingScope->internalName();
++ if (m_cppTypesToQmlTypes.contains(foundScopeName)) {
++ const QString id = m_cppTypesToQmlTypes.value(foundScopeName) + u"::"_s + name;
++ links = m_helpPlugin->documentsForIdentifier(id);
++ if (!links.empty())
++ return links;
++ }
++
++ const auto &containingObjectName = item.qmlObject().name();
++ auto scope = item.nearestSemanticScope();
++ while (scope && scope->isComposite()) {
++ const QString id = containingObjectName + u"::"_s + name;
++ links = m_helpPlugin->documentsForIdentifier(id);
++ if (!links.empty())
++ return links;
++ scope = scope->baseType();
++ }
++
++ while (scope && !m_cppTypesToQmlTypes.contains(scope->internalName())) {
++ const QString id = m_cppTypesToQmlTypes.value(scope->internalName()) + u"::"_s + name;
++ links = m_helpPlugin->documentsForIdentifier(id);
++ if (!links.empty())
++ return links;
++ scope = scope->baseType();
++ }
++
++ return m_helpPlugin->documentsForKeyword(name);
++ }
++
++ QT_END_NAMESPACE