|
| 1 | +--- |
| 2 | +title: codeanalyzer-iac |
| 3 | +description: "The infrastructure-as-code backend. It turns Helm charts into the canonical schema v2 IaC model, as analysis.json or a Neo4j property graph." |
| 4 | +--- |
| 5 | + |
| 6 | +import { Tabs, TabItem, Aside, Badge, LinkCard, CardGrid, Steps } from "@astrojs/starlight/components"; |
| 7 | + |
| 8 | +<p><Badge text="Beta" variant="caution" /></p> |
| 9 | + |
| 10 | +The **codeanalyzer-iac** backend analyzes infrastructure-as-code. Its command is **`caniac`**. It reads a repository, or a Neo4j graph that already holds one, and publishes one typed model of the infrastructure sources. |
| 11 | + |
| 12 | +`caniac` is built on the [Helm](https://helm.sh/) SDK, pinned to version 4.2.4. It never calls the `helm` CLI. Helm is the first dialect. Every other file stays an ordinary `Artifact`, and the analyzer never drops it. |
| 13 | + |
| 14 | +<Aside type="caution" title="There is no CLDK.iac(...) factory yet"> |
| 15 | +The other backends have a matching SDK facade. This one does not. Use `caniac` as a command, or read the graph that it writes. Java, Python, and TypeScript analyses are unaffected. |
| 16 | +</Aside> |
| 17 | + |
| 18 | +## Install |
| 19 | + |
| 20 | +<Tabs> |
| 21 | + <TabItem label="Shell"> |
| 22 | + Prebuilt binary for macOS and Linux: |
| 23 | + |
| 24 | + ```bash |
| 25 | + curl --proto '=https' --tlsv1.2 -LsSf https://github.com/codellm-devkit/codeanalyzer-iac/releases/latest/download/caniac-installer.sh | sh |
| 26 | + ``` |
| 27 | + </TabItem> |
| 28 | + <TabItem label="Homebrew"> |
| 29 | + ```bash |
| 30 | + brew install codellm-devkit/tap/codeanalyzer-iac |
| 31 | + ``` |
| 32 | + </TabItem> |
| 33 | + <TabItem label="pip"> |
| 34 | + ```bash |
| 35 | + pip install codeanalyzer-iac |
| 36 | + ``` |
| 37 | + </TabItem> |
| 38 | +</Tabs> |
| 39 | + |
| 40 | +## Analyze a repository |
| 41 | + |
| 42 | +```bash |
| 43 | +caniac --app-name payments . |
| 44 | +caniac --app-name payments charts/ deploy/values-prod.yaml |
| 45 | +caniac --app-name payments --workspace-root . charts/api |
| 46 | +``` |
| 47 | + |
| 48 | +Paths can be files or directories, and they can overlap. They are selection filters, not identity roots. Identity comes from `--workspace-root`, which defaults to the current directory. `charts/api/values.yaml` is therefore the same artifact whether you selected the repository, `charts/`, or that one file. |
| 49 | + |
| 50 | +Every input file and every `--config` file must resolve below the workspace root. The analyzer does not follow symlinks out of it, and the walker skips `.git`. |
| 51 | + |
| 52 | +With no path, the input is `.`. With no `--app-name`, the application takes the base name of the workspace root. In graph mode a name is mandatory. |
| 53 | + |
| 54 | +## Analysis levels |
| 55 | + |
| 56 | +<Aside type="caution" title="This scale is not the SDK scale"> |
| 57 | +`caniac` takes `-a 1|2|3`. The language backends take `-a 1..4`. The numbers do not line up, and level 4 here is rejected rather than accepted. Read this table, not the [dataflow levels](/guides/dataflow/#the-four-analysis-levels). |
| 58 | +</Aside> |
| 59 | + |
| 60 | +| Level | Adds | Never does | |
| 61 | +| --- | --- | --- | |
| 62 | +| L1 | Artifact classification, Helm facets, chart metadata, values keys, template definitions, template calls, value references, resource templates, source diagnostics | Resolution or rendering | |
| 63 | +| L2 | Chart membership, dependency resolution, named-template targets, value-reference targets, unresolved records | Rendering or any I/O | |
| 64 | +| L3 | Render profiles, value layers, renders, rendered Kubernetes resources and addresses | Cluster access, install, upgrade, dependency fetching | |
| 65 | + |
| 66 | +`-a/--analysis-level` takes 1, 2, or 3, and defaults to 1. The levels are additive. Every fact that a lower level published is present, unchanged, at every higher level. |
| 67 | + |
| 68 | +The graph always receives the deepest implemented level, which is L3 today. `--emit cypher` and `--emit neo4j` therefore raise the level to 3 unless you passed `--analysis-level` yourself. An explicit level below 3 with those targets is rejected rather than raised without a word. |
| 69 | + |
| 70 | +```bash |
| 71 | +caniac testdata/helm/l1-v2 --app-name payments --analysis-level 1 > analysis.json |
| 72 | + |
| 73 | +caniac --workspace-root testdata/helm/profiles --app-name payments \ |
| 74 | + --config .codeanalyzer-iac.yaml --analysis-level 3 > analysis.json |
| 75 | +``` |
| 76 | + |
| 77 | +## Output modes |
| 78 | + |
| 79 | +| `--emit` | Writes | To stdout | To `-o DIR` | |
| 80 | +| --- | --- | --- | --- | |
| 81 | +| `json` (filesystem default) | The analysis document | Compact JSON, one trailing newline | `analysis.json` | |
| 82 | +| `cypher` | The replayable projection script | The script | `graph.cypher` | |
| 83 | +| `neo4j` (graph-mode default) | A reconciled generation over Bolt | Nothing | Nothing | |
| 84 | +| `schema` | The embedded graph catalog | `schema.neo4j.json` | `schema.neo4j.json` | |
| 85 | + |
| 86 | +In filesystem mode, `--emit cypher` never consults the target graph. The script is projected from the analysis alone, so it has no hash-conflict guard against facts that are already in the graph. `--emit neo4j` does have that guard. |
| 87 | + |
| 88 | +`--emit schema` takes no input path. `-f/--format` accepts only `json`. `msgpack` is named so that the analyzer can reject it with a clear message instead of a bad parse. `-j/--jobs` bounds parallel parsing and rendering, and it defaults to the CPU count. The output is byte-identical whatever you set it to. |
| 89 | + |
| 90 | +Stdout carries analysis data and nothing else. Errors go to stderr, one line each. A successful run leaves stderr empty. The analyzer discards the value-coalescing warnings that Helm itself emits, rather than letting them onto either stream. |
| 91 | + |
| 92 | +## Graph mode |
| 93 | + |
| 94 | +A single positional Neo4j or Bolt URI switches the analyzer into graph mode. |
| 95 | + |
| 96 | +```bash |
| 97 | +caniac neo4j://localhost:7687 --app-name payments |
| 98 | +``` |
| 99 | + |
| 100 | +In graph mode the analyzer reads the complete `Artifact.source` for every `can://artifact/<app-name>/...` node, makes sure that each one matches the stored `sha256`, and writes its enrichment back onto those same nodes. |
| 101 | + |
| 102 | +`--app-name` is required here. The URI names a database, not an application, and the analyzer will not pick one for you. You cannot mix a URI and filesystem paths in one invocation. In graph mode `--emit` defaults to `neo4j`, so the command above reads and writes the same database over one connection. |
| 103 | + |
| 104 | +If a source does not match its recorded hash, that becomes a diagnostic on the artifact and the analyzer skips its semantic model. The recorded spans address the old text, so a changed source makes every one of them wrong. Other artifacts are analyzed normally. There is no flag to accept a mismatch. |
| 105 | + |
| 106 | +## Exit status |
| 107 | + |
| 108 | +| Exit | Meaning | |
| 109 | +| --- | --- | |
| 110 | +| 0 | The analysis completed | |
| 111 | +| 1 | An analyzer-wide failure, or `--strict` with at least one error-severity diagnostic | |
| 112 | + |
| 113 | +Isolated failures are diagnostics inside the model, not process failures. An unparsable file, or a chart that the analyzer cannot render, still exits 0. A file that the analyzer cannot read as text stays a raw inventory entry, with a digest and no source, and reports `IAC_SOURCE_NOT_TEXT` at `warning` severity. A repository with binaries in it therefore still passes `--strict`. |
| 114 | + |
| 115 | +Whether a document is published on exit 1 depends on how far the run got: |
| 116 | + |
| 117 | +- An invalid configuration and a `--strict` failure are both decided after the analysis is written, so those runs still leave a document to read. |
| 118 | +- An unreadable input root, an unreachable graph, and a failed graph commit all end the run before that write, so they publish nothing. |
| 119 | + |
| 120 | +`--strict` changes only the exit status. It never changes the document. |
| 121 | + |
| 122 | +`--eager` reconciles away the stale facts that this analyzer owns for the selected application: `codeanalyzer-iac` nodes and aliases, `iac_*` properties, facet labels, and `IAC_*` relationships. It never removes an `Artifact`. |
| 123 | + |
| 124 | +## Schema |
| 125 | + |
| 126 | +The repository pins the accepted `codeanalyzer-schema` contract at commit [`b84428f`](https://github.com/codellm-devkit/codeanalyzer-schema/commit/b84428f1accebe2b259d32c15387f04a00167f2c). `make schema-check` and the pin-parity test keep every copy of that commit in step. |
| 127 | + |
| 128 | +## See also |
| 129 | + |
| 130 | +<CardGrid> |
| 131 | + <LinkCard title="Backends overview" href="/backends/" description="All CLDK analysis backends and their maturity tiers." /> |
| 132 | + <LinkCard title="Analysis at scale" href="/at-scale/" description="The emit and poll split that this backend writes into." /> |
| 133 | + <LinkCard title="Deploy on Kubernetes" href="/at-scale/kubernetes/" description="Scheduled emit jobs against a shared Neo4j." /> |
| 134 | + <LinkCard title="Source repository" href="https://github.com/codellm-devkit/codeanalyzer-iac" description="codellm-devkit/codeanalyzer-iac on GitHub." /> |
| 135 | +</CardGrid> |
0 commit comments