libchecker/libchecker-rules/libchecker-chart-rules

Chart rule contribution guide

This directory contains the declarative statistics shown on LibChecker's chart page. A rule describes the data that LibChecker should inspect, the condition that produces a match, and the labels and icon shown to the user.

Rules cannot execute scripts or arbitrary code. LibChecker owns all APK, DEX, manifest, and native-file traversal. A rule can only use evidence and operators that the installed app already implements.

Before you start

Answer these questions before writing JSON:

1. What does the chart measure, and why is it useful to LibChecker users?
2. Which installed-app evidence proves a match?
3. Can an app produce one yes/no result, or can it match several capabilities?
4. Is there a primary HTTPS source that explains the technology or capability?
5. Can you test the rule against both matching and non-matching APKs?

Schema v1 supports only the evidence listed in Evidence reference. If your rule needs another source, such as a DEX field, resource-table entry, native symbol, certificate property, or arbitrary file content, propose a generic evidence provider in the LibChecker app first. Do not encode a workaround in the rule.

New rules should normally start with "releaseChannel": "preview-only". Move them to stable only after the preview bundle has been tested with a compatible LibChecker build.

Contribution workflow

1. Fork the repository and create a topic branch.
2. Choose the closest example in rules/:

• `flutter.json` for exact native-library detection.
• `reactivex.json` for exact APK entries with a DEX

fallback.

• `itgsa.json` for facets, recursive conditions, DEX

queries, and manifest receiver actions.

• The predicate example below for a numeric

comparison.

1. Add one UTF-8 JSON file under rules/. Use four-space indentation and name

the file after the final segment of the rule ID.

1. Add the referenced SVG under icons/.
2. Update the tests that enumerate rule IDs, icons, catalog size, and stable

channel contents. Add focused assertions for the new detection data.

1. Run the unit tests and build a preview bundle in a temporary directory.
2. Test the preview rule with known matching and non-matching apps.
3. Regenerate cloud/v1/chart.bundle and cloud/v1/manifest.json with the

bundle version and minimum app version agreed for the target branch.

1. Submit the source rule, icon, tests, generated bundle, and manifest in one

pull request. Include your evidence source and manual test results in the PR description.

Run commands from the repository root:

python3 -m unittest chart.tools.test_build_bundle
python3 chart/tools/build_bundle.py \
  --bundle-version 12 \
  --channel preview \
  --minimum-app-version-code 2731 \
  --output-dir /tmp/libchecker-chart-preview

The numbers above are examples. Read chart/cloud/v1/manifest.json and the target branch before choosing a bundle version or minimum app version.

Repository layout

Minimal rule

This is a complete single-predicate rule:

{
    "id": "official.example-sdk",
    "revision": 1,
    "source": "official",
    "releaseChannel": "preview-only",
    "title": {
        "translations": {
            "en": "Example SDK",
            "zh-Hans": "示例 SDK"
        }
    },
    "details": {
        "description": {
            "translations": {
                "en": "Example SDK provides a documented capability for Android apps.",
                "zh-Hans": "示例 SDK 为 Android 应用提供一项有公开文档的能力。"
            }
        },
        "referenceUrl": "https://example.com/android-sdk"
    },
    "icon": {
        "asset": "icons/example-sdk.svg",
        "renderMode": "monochrome",
        "tintRole": "on_surface"
    },
    "calculation": {
        "kind": "predicate",
        "predicate": {
            "evidence": "native_library",
            "operator": "contains",
            "value": {
                "string": "libexample.so"
            },
            "matchedTitle": {
                "translations": {
                    "en": "Example SDK apps",
                    "zh-Hans": "示例 SDK 应用"
                }
            },
            "unmatchedTitle": {
                "translations": {
                    "en": "Other apps",
                    "zh-Hans": "其他应用"
                }
            }
        }
    },
    "fingerprint": "artifact"
}

Top-level fields

The source schema does not allow unknown fields. The following fields are available to official online rules.

JSON Schema default values document client defaults. The bundle builder does not insert missing optional fields into the generated catalog.

id

The ID must match:

^official\.[a-z0-9]+(?:[.-][a-z0-9]+)*$

Examples:

• Valid: official.flutter, official.android-api-level,

official.vendor.capability.

• Invalid: flutter, official.Flutter, official_target_sdk.

Use a specific, technology-neutral ID. Once a rule has been published, never reuse its ID for a different statistic. The source filename should match the last ID segment, such as official.flutter in flutter.json.

revision

Start a new rule at revision 1. Increase the revision whenever a published rule changes its matching logic, titles, description, icon, calculation type, or other presentation metadata. A change to repository documentation alone does not require a rule revision.

The revision belongs to one rule. It is independent of the generated bundle's bundleVersion.

source

Every rule submitted to this repository must use:

"source": "official"

The builder rejects other values.

Translated text

title, details.description, predicate group titles, and facet titles use the same wrapper. Optional facet short titles use it as well:

{
    "translations": {
        "en": "English text",
        "zh-Hans": "简体中文文本"
    }
}

Translated-text parameters

Rules for translations:

• en and zh-Hans are required. English is the runtime fallback.
• Use zh-Hans for Simplified Chinese. zh and zh-CN are rejected.
• A translated object must contain 2 to 16 locales.
• Locale keys use BCP 47-style tags accepted by the schema, such as en,

zh-Hans, pt-BR, or es-419.

• Each translation must be a non-empty string.
• title, matchedTitle, and unmatchedTitle allow up to 80 characters.
• A facet title and shortTitle allow up to 40 characters.
• details.description allows up to 1,500 characters.
• Keep equivalent meaning across locales. Do not add claims to one language

that are absent from another.

Use short labels for chart and group titles. The matched and unmatched titles name the two result groups, for example Flutter apps and Other apps.

Details and reference URL

details is required:

"details": {
    "description": {
        "translations": {
            "en": "A neutral introduction to the technology.",
            "zh-Hans": "对该技术的中性介绍。"
        }
    },
    "referenceUrl": "https://project.example/documentation"
}

Details parameters

Write a short, neutral description of the technology or capability. Do not say that the currently selected app matches the rule. LibChecker appends the actual analysis result at runtime. Faceted rules also list the matched facet titles.

referenceUrl must:

• use HTTPS;
• contain a valid host;
• contain no username, password, or whitespace;
• be no longer than 512 characters;
• point to a primary project, standards body, vendor, or platform document.

Do not use tracking links, URL shorteners, affiliate links, search results, or an unreviewed third-party summary.

Icons

Every online rule references one repository asset:

"icon": {
    "asset": "icons/example-sdk.svg",
    "renderMode": "monochrome",
    "tintRole": "on_surface"
}

Icon fields

Use original only when the original brand colors carry meaning. LibChecker does not apply tintRole to an original icon. Use monochrome for a shape that should adapt to the active theme.

SVG requirements

An SVG must: