# What is a lens?

**A lens is a YAML file of matching rules that teaches CCE how to read your call sites.**
Same code, same parser, same report format — a different vocabulary. Pass one with
`-mapper-file ./your-lens.yaml` and every scan speaks that vocabulary.

Think of a camera: the built-in mapper is the default factory lens that frames cloud SDK
calls for IAM entitlements. Swapping the lens doesn't change the scene (your code happens
to be what it is) — it changes what CCE *sees* in the scene: which imports matter, what
each method call is called, and what to do about it.

- No Go code, no rebuild: lenses are data. A platform team can maintain one and attach it
  to CI without ever touching the `cce` binary.
- Read-only inventory: a lens finds and classifies call sites; it does not rewrite code.
  Change steps (if you want them) live in OpenRewrite recipes referenced as hints.
- Try one now:

```bash
cce -folder ./my-service -language AUTO -filter all \
    -mapper-file ./my-lens.yaml -format json -output lens-scan.json
```

```yaml
# my-lens.yaml — flag calls to the deprecated `requests` library
definition:
  language:
    python:
      - name: "Legacy requests library"       # human label, shows up in warnings
        prefix: "requests."                   # fast filter: must match the START of the extracted method name
        rule: "requests\\.(?<operation>[a-zA-Z0-9_]+)"   # grok pattern with named captures
        provider: TECH_DEBT                   # the vocabulary bucket this row lands in
        openrewrite_recipe: "org.openrewrite.python.migrate.ReplaceRequestsWithHttpx"
        replacement_fqn: "httpx"
        docs_url: "https://www.python-httpx.org/"
  providers:
    TECH_DEBT:
      servicenameMapping: {}
```

## The pipeline, end to end

```mermaid
flowchart LR
  src["source files<br/>(go / java / py / js)"] --> parser["tree-sitter parser<br/>(unchanged by lenses)"]
  parser --> calls["method-call stream<br/>each call: full package path + symbol"]
  calls --> rules{"match, in order"}
  rules -->|"1. your lens<br/>(-mapper-file)"| rows
  rules -->|"2. built-in mapper<br/>(definition.yaml)"| rows
  rows[/"mapped rows:<br/>provider / resource / operation<br/>+ optional action hints"/] --> report["JSON / SARIF report"]
```

Every lens runs on top of the same two built-ins: the tree-sitter parse and the report
format. Only the *middle* — what a call site means — is yours to define.

## From method name to row

The single most important fact: CCE matches rules against the **extracted method name**,
which is the **full package path + symbol** — *not* the import alias in your source file.

Trace one call. Given:

```python
# app.py
import requests

requests.get("https://example.com/health")
```

| Step | What happens |
|------|--------------|
| 1. Extract | The parser turns the call site into the method name `requests.get` |
| 2. Prefix filter | `prefix: "requests."` matches the start of `requests.get` — this rule is **in play** |
| 3. Rule match | The grok rule matches; the named capture `(?<operation>…)` captures `get` |
| 4. Fill blanks | Nothing captured `resource_group`, so CCE derives `resource` from the prefix (`requests.` → `requests`) |
| 5. Emit | One structured row goes to the report |

The row (same shape as every CCE report):

```json
{
  "provider": "TECH_DEBT",
  "resource": "requests",
  "operation": "get",
  "method": "requests.get",
  "file": "app.py",
  "line": 4
}
```

Because the row is structured, everything downstream is queryable: count `resource` ×
`operation`, diff two scans with `cce diff`, or gate CI on a count. The `openrewrite_*`
fields ride along in JSON as `suggested_action` hints — reminders for the humans, not
executable changes.

## The built-in cloud lens vs your lens

CCE ships one mapping of its own (`pkg/resourcemapper/definition/definition.yaml`) — the
"cloud entitlements" vocabulary: AWS, Azure, GCP, OCI, IBM, Alibaba. You never opt into it;
it is always loaded. Rules to remember:

| Fact | Why it matters |
|------|----------------|
| Your lens is tried **first**; the built-in fills whatever your lens does not match | Lenses *add* vocabulary on top of cloud entitlements — you get both |
| **First match wins** inside a definition | Order rules specific → general; overlapping prefix-less rules warn at load time |
| `prefix` must match the **start** of the extracted method name | The usual full-package-path FQN, e.g. `github.com/aws/aws-sdk-go/service/s3.ListBuckets` — copying the visible import alias is the #1 mistake |
| `%{WORD}` does **not** match `_` or `-` | Use inline regex `(?<name>[a-z0-9_]+)` for underscored identifiers |
| Custom `provider` values (e.g. `PLATFORM`, `TECH_DEBT`) need `-filter all` | `-filter cloud` keeps only the built-in cloud providers |
| `clientFactories` from the lens **merge** with the built-ins | `boto3.client('s3')`-style factory knowledge composes with yours |

## When you reach for a lens

| Situation | Built-in mapper | Lens |
|-----------|-----------------|------|
| "What cloud services does this service touch?" (PoLP) | ✅ | — |
| "Which services call our internal platform SDK instead of going direct?" | ❌ | ✅ `provider: PLATFORM` vs `provider: DIRECT_CLOUD` |
| "Where is deprecated library X still called?" | ❌ | ✅ `provider: TECH_DEBT` + OpenRewrite hint |
| "Does this wrapper client (non-standard method names) resolve?" | ❌ | ✅ grok rule per wrapper shape |

If many teams will run the same lens by id (`cce run -pack`), promote it into a
**catalog recipe** — a small JSON entry pointing at your hosted YAML. That's packaging,
not a new concept: see [Enterprise lenses and catalogs](enterprise-lenses-and-catalogs.md).

## What a lens is **not**

- **Not an IAM policy** — it inventories call sites; it does not verify the caller is
  allowed to make them. See [Entitlements, operations, and IAM](entitlements-operations-and-iam.md).
- **Not a rewriter** — `openrewrite_recipe` is a hint attached to the row, not an action
  CCE performs.
- **Not language-specific magic** — one lens can contain `go`, `java`, `python`,
  `javascript` sections, all applied during the same scan.
- **Not a replacement for the built-in rule base** — a lens *extends* it; unmatched calls
  still fall through to the built-in mapper.

## Glossary

| Term | Plain words |
|------|-------------|
| **Method name** | The extracted call identity: full package path + symbol (`requests.get`) |
| **`prefix`** | Cheap string filter: rule is only tried if this matches the method-name start |
| **`rule`** | Grok pattern with named captures `resource_group` and `operation`; optional — without it, a standard pattern is generated from the prefix |
| **`provider`** | The bucket a row is classified under (cloud vendor, or your org's label) |
| **`resource` / `operation`** | What was called (`s3`) and what was done to it (`ListBuckets`) |
| **Servicename mapping** | Normalizes odd SDK names to standard service names |
| **Action hints** | `openrewrite_recipe` / `replacement_fqn` / `docs_url` — optional suggestions in JSON |
| **Recipe / catalog / pack** | Packaging for lenses: discover by id and run by pack (see enterprise guide) |

## Where to go next

- [Custom lens YAML](../reference/custom-lens-yaml.md) — full syntax: `dataTables`,
  `prefixes_from`, `clientFactories`, `extract_resource_from`, debugging, security limits
- [Enterprise lenses and catalogs](enterprise-lenses-and-catalogs.md) — host lenses for
  CI, register recipes and packs, self-host the catalog
- [Prowler wrapper-client example](https://github.com/appcd-dev/cce/blob/main/docs/example/prowler.yaml) —
  lens for non-standard method names in a real codebase
- [Analysis recipes](../reference/analysis-recipes.md) — the catalog/pack side
