@openfeapp/web-compat-findings

STATUS: v0 WIP

@openfeapp/web-compat-findings scans built web assets and writes a deterministic compat.findings.json.

This package is the scanner layer. It does not generate compat.lock.json. Lock generation and browser-floor resolution live in @openfeapp/web-compat.

Why this package exists

Bundle compatibility scanning gets brittle when extraction and compatibility policy are mixed together. This package keeps the scanner focused on:

• discovering built JS, CSS, and HTML assets
• extracting generic language signals
• mapping those signals to canonical BCD keys
• emitting deterministic findings with concrete evidence

That keeps the scanner explainable and lets @openfeapp/web-compat own floor derivation.

Install

npm install --save-dev @openfeapp/web-compat-findings

If you also want to derive browser floors, install @openfeapp/web-compat separately and run compat-generate-lock after scanning.

CLI

web-compat-findings --in-dir dist

Supported flags:

• --in-dir
• --ext-js
• --ext-css
• --ext-html
• --spec-js
• --source-type-js module|script|both
• --verbose
• --debug
• --ignore-fuzzy-receiver
• --ignore-fuzzy-css-context
• --ignore-fuzzy-css-value-context
• --ignore-fuzzy-selector-context
• --ignore-fuzzy-html-context
• --ignore-inline-event-handlers
• --ignore-inline-style-attrs
• --ignore-javascript-urls

Default JS syntax intent is ES2022.

No --adapter-*, --registry, --root, --dir, --target, or --floor flags are exposed.

Workflow

1. Discover built assets under --in-dir.
2. Extract generic signals from JS, CSS, and HTML.
3. Map those signals to canonical BCD keys using generated indexes.
4. Normalize and deduplicate findings into a deterministic compat.findings.json.

If you want browser-floor derivation after that, run compat-generate-lock from @openfeapp/web-compat against the emitted findings artifact.

Output artifact

compat.findings.json

This file is deterministic for identical inputs.

Properties of the artifact:

• stable canonical BCD keys
• stable ordering
• deduplicated evidence
• confidence metadata (exact, strong, fuzzy)
• remapped inline HTML evidence back to the original HTML file and source range
• fixed synthetic generated_at timestamp for diff-friendly reproducibility

Example shape:

{
  "format": "compat-findings/v1",
  "generated_at": "1970-01-01T00:00:00.000Z",
  "findings": [
    {
      "kind": "bcd",
      "ref": "bcd:css.selectors.has",
      "key": "css.selectors.has",
      "confidence": "exact",
      "evidence": [
        {
          "path": "index.html",
          "loc": "L1:C10-L1:C18",
          "rule": "css.pseudo-class.exact",
          "confidence": "exact",
          "origin_path": "index.html#inline-style:0.css",
          "origin_kind": "inline-style"
        }
      ]
    }
  ]
}

Architecture

1. CLI layer

bin/web-compat-findings.mjs and src/cli/run-cli.mjs

Responsible for argument parsing, user-facing errors, and progress/debug output.

2. Workflow orchestration

src/workflow/run.mjs

Coordinates discovery, extraction, mapping, normalization, and findings writing.

3. Shared signal IR

Signals are generic facts such as:

• JS global call
• JS member access
• CSS property
• CSS function
• HTML attribute value

Frontends emit signals. They do not emit BCD keys directly.

4. Language frontends

• JS/TS: src/extract/js-extractor.mjs
• CSS: src/extract/css-extractor.mjs
• HTML: src/extract/html-extractor.mjs

5. Generated mapping indexes

generated/bcd-indexes.json is built from upstream data by scripts/build-generated-indexes.mjs.

Inputs:

• @mdn/browser-compat-data
• TypeScript web/runtime typings for extraction-oriented runtime shape discovery

BCD stays the only compatibility authority. Helper metadata is used only to improve extraction and index generation.

Confidence model

• exact: typed or structurally precise match
• strong: reliable lexical/global match with limited ambiguity
• fuzzy: conservative recall-oriented match used when receiver or context is weak

The scanner prefers recall over strict precision. Fuzzy matches can be disabled with the relevant CLI flags.

Maintenance philosophy

The intended maintenance model stays small and boring:

npm update @mdn/browser-compat-data typescript css-tree parse5
npm run build:indexes
npm test

If generated/bcd-indexes.json changes, review the diff and ship it with the dependency refresh.