MapComplete/scripts/generateTaginfoProjectFiles.ts

import { AllKnownLayouts } from "../src/Customizations/AllKnownLayouts"
import Locale from "../src/UI/i18n/Locale"
import { Translation } from "../src/UI/i18n/Translation"
import { readFileSync, writeFileSync } from "fs"
import ThemeConfig from "../src/Models/ThemeConfig/ThemeConfig"
import LayerConfig from "../src/Models/ThemeConfig/LayerConfig"
import { Utils } from "../src/Utils"
import { Lists } from "../src/Utils/Lists"
import { Strings } from "../src/Utils/Strings"

/**
 * Generates all the files in "Docs/TagInfo". These are picked up by the taginfo project, showing a link to the mapcomplete theme if the key is used
 */
interface TagInfoEntry {
    key: string
    description: string
    value?: string
    icon_url?: string
    doc_url?: string
}

interface TagInfoProjectFile {
    // data format version, currently always 1, will get updated if there are incompatible changes to the format (required)
    data_format: 1
    // timestamp when project file was updated is not given as it pollutes the github history
    project: {
        name: string // name of the project (required)
        description: string // short description of the project (required)
        project_url: string // home page of the project with general information (required)
        doc_url: string // documentation of the project and especially the tags used (optional)
        icon_url: string // project logo, should work in 16x16 pixels on white and light gray backgrounds (optional)
        contact_name: string // contact name, needed for taginfo maintainer (required)
        contact_email: string // contact email, needed for taginfo maintainer (required)
    }
    tags: TagInfoEntry[]
}

interface TagInfoPrototype {
    key: string
    value?: string
    shownText: string
    layerName: string
    layer: LayerConfig
    icon?: string
    emoji?: string
    trid?: string
}

const outputDirectory = "Docs/TagInfo"

function generateLayerUsage(layer: LayerConfig): TagInfoPrototype[] {
    if (layer.name === undefined) {
        return [] // Probably a duplicate or irrelevant layer
    }

    const usedTags = layer.source.osmTags.asChange({})
    const result: TagInfoPrototype[] = []
    const layerName = layer.name.txt
    for (const kv of usedTags) {
        result.push({
            key: kv.k,
            value: kv.v,
            layerName,
            shownText: "Features with this tag are displayed",
            layer,
        })
    }

    for (const tr of layer.tagRenderings) {
        let condition = tr.condition?.asHumanString(false, false, {}) ?? ""

        if (condition !== "") {
            condition = ` (This is only shown if ${condition})`
        }

        {
            const usesImageCarousel = (tr.render?.txt?.indexOf("image_carousel") ?? -2) > 0
            const usesImageUpload = (tr.render?.txt?.indexOf("image_upload") ?? -2) > 0

            if (usesImageCarousel || usesImageUpload) {
                const descrNoUpload = `Images are displayed based on the keys image, image:0, image:1,..., panoramax, panoramax:0, panoramx:1, ... ,  wikidata, wikipedia, wikimedia_commons and mapillary`
                const descrUpload = `${descrNoUpload} Furthermore, this layer shows images based on the keys panoramax, image, wikidata, wikipedia, wikimedia_commons and mapillary`

                const shownText = (usesImageUpload ? descrUpload : descrNoUpload) + condition
                const keys = ["image", "panoramax", "mapillary", "wikidata", "wikipedia"]
                for (const key of keys) {
                    result.push({
                        key,
                        shownText,
                        layerName,
                        layer,
                        emoji: "📷",
                        trid: "images",
                    })
                }
            }
        }

        const q = tr.question?.txt
        const key = tr.freeform?.key
        if (key != undefined) {
            let descr = "Values of `" + key + '` are shown with "' + tr.render.txt + '"'
            if (q != undefined) {
                descr += ' and can be updated. The question is "' + q + '"'
            }
            result.push({
                key,
                layerName,
                shownText: descr,
                layer,
                icon: !Strings.isEmoji(tr.renderIcon) ? tr.renderIcon : undefined,
                emoji: Strings.isEmoji(tr.renderIcon) ? tr.renderIcon : undefined,
                trid: tr.id,
            })
        }

        for (const mapping of tr.mappings ?? []) {
            for (const kv of mapping.if.asChange({})) {
                result.push({
                    key: kv.k,
                    value: kv.v,
                    layerName,
                    layer,
                    shownText: `${mapping.if.asHumanString()} is displayed as "${
                        mapping.then.txt
                    }"`,
                    icon: !Strings.isEmoji(mapping.icon) ? mapping.icon : undefined,
                    emoji: Strings.isEmoji(mapping.icon) ? mapping.icon : undefined,
                    trid: tr.id,
                })
            }
        }
    }

    return result.filter((result) => !result.key.startsWith("_"))
}

/**
 * Generates the JSON-object representing the theme for inclusion on taginfo
 * @param layout
 */
function generateTagInfoEntry(layout: ThemeConfig): string {
    const usedTags: TagInfoPrototype[] = []
    for (const layer of layout.layers) {
        if (layer.source === null) {
            continue
        }
        if (layer.source.geojsonSource !== undefined && layer.source.isOsmCacheLayer !== true) {
            continue
        }
        usedTags.push(...generateLayerUsage(layer))
    }

    if (usedTags.length == 0) {
        return undefined
    }

    let icon = layout.icon
    if (icon.startsWith("./")) {
        icon = icon.substring(2)
    }

    const merged: Map<string, TagInfoPrototype[]> = new Map<string, TagInfoPrototype[]>()
    for (const entry of usedTags) {
        const key = entry.key + ";" + (entry.value ?? "") + ";" + entry.shownText
        let entries = merged.get(key)
        if (!entries) {
            entries = []
            merged.set(key, entries)
        }
        entries.push(entry)
    }

    const entries: TagInfoEntry[] = []

    const repo = "https://source.mapcomplete.org/MapComplete/MapComplete/"
    const branchBase = repo + "src/branch/develop/"
    Array.from(merged.values()).forEach((prototypes: TagInfoPrototype[]) => {
        // We use a prototype without condition, as this has a higher chance of being the "root"-layer
        const p = prototypes[0]
        const layers = prototypes.map((p) => p.layerName)

        let layerDescr = `layers ${layers.join(", ")}`
        if (layers.length === 1) {
            layerDescr = `layer ${layers[0]}`
        }
        let doc_url = branchBase + "Docs/Layers/" + p.layer.id + ".md"
        if (p.trid) {
            doc_url += "#" + p.trid.replace(/[^a-zA-Z0-9]/g, "_")
        }
        let defaultIcon = undefined
        if (p.layer.hasDefaultIcon()) {
            defaultIcon = p.layer.mapRendering
                .map((pr) => pr.marker?.at(-1)?.icon?.render?.txt)
                .find((x) => x !== undefined)
        }
        let value = p.value
        if (value === "") {
            value = undefined
        }
        entries.push({
            key: p.key,
            value,
            description: p.shownText + " by " + layerDescr,
            doc_url,
            icon_url: p.icon ?? defaultIcon,
        })
    })

    const themeInfo: TagInfoProjectFile = {
        // data format version, currently always 1, will get updated if there are incompatible changes to the format (required)
        data_format: 1,
        // timestamp when project file was updated is not given as it pollutes the github history
        project: {
            name: "MapComplete " + layout.title.txt, // name of the project (required)
            description: layout.shortDescription.txt, // short description of the project (required)
            project_url: "https://mapcomplete.org/" + layout.id, // home page of the project with general information (required)
            doc_url: repo + "src/branch/develop/Docs/Themes", // documentation of the project and especially the tags used (optional)
            icon_url: "https://mapcomplete.org/" + icon, // project logo, should work in 16x16 pixels on white and light gray backgrounds (optional)
            contact_name: "Pieter Vander Vennet", // contact name, needed for taginfo maintainer (required)
            contact_email: "info@mapcomplete.org", // contact email, needed for taginfo maintainer (required)
        },
        tags: entries,
    }

    const filename = "mapcomplete_" + layout.id
    console.log("Writing info about " + layout.id)
    writeFileSync(`${outputDirectory}/${filename}.json`, JSON.stringify(themeInfo, null, 2))
    return filename
}

// Write the URLS to the taginfo repository. Might fail if the repository is not checked ou
function generateProjectsOverview(files: string[]) {
    try {
        const tagInfoList = "../../git/taginfo-projects/project_list.txt"
        const projectList = readFileSync(tagInfoList, { encoding: "utf8" })
            .split("\n")
            .filter((entry) => entry.indexOf("mapcomplete_") < 0)
            .concat(
                files.map(
                    (f) =>
                        `${f} https://source.mapcomplete.org/MapComplete/MapComplete/raw/branch/develop/Docs/TagInfo/${f}.json`
                )
            )
            .sort()
            .filter((entry) => entry != "")

        console.log("Writing taginfo project filelist")
        writeFileSync(tagInfoList, projectList.join("\n") + "\n")
    } catch (e) {
        console.warn(
            "Could not write the taginfo-projects list - the repository is probably not checked out. Are you creating a fork? Ignore this message then."
        )
    }
}

function main() {
    console.log("Creating taginfo project files")

    Locale.language.setData("en")
    Translation.forcedLanguage = "en"

    const files = []

    for (const layout of AllKnownLayouts.allKnownLayouts.values()) {
        if (layout.hideFromOverview) {
            continue
        }
        if (layout.id === "personal") {
            continue
        }
        files.push(generateTagInfoEntry(layout))
    }
    generateProjectsOverview(Lists.noNull(files))
}

main()