Navegador

docs: add IaC language support to ingestion, enrichment, and installation guides

lmata 2026-03-30 02:48 trunk

Commit dcf17e99c17a680f200d9571521055b1c3e0171dd013fbda121458a8c9d98dee

Parent 66c638480837fc1…

3 files changed +12 -2 +3 -1 +37 -1

~ docs/getting-started/installation.md ~ docs/guide/framework-enrichment.md ~ docs/guide/ingestion.md

M docs/getting-started/installation.md

+12 -2

		--- docs/getting-started/installation.md
		+++ docs/getting-started/installation.md
		@@ -51,10 +51,20 @@
51	51	pip install "navegador[languages]"
52	52	```
53	53
54	54	After installing, all 13 languages are parsed automatically by `navegador ingest`. No additional configuration is required.
55	55
	56	+=== "[iac]"
	57	+
	58	+ Infrastructure-as-Code parsers for HCL/Terraform, Puppet, Bash/Shell, Ansible, and Chef.
	59	+
	60	+ ```bash
	61	+ pip install "navegador[iac]"
	62	+ ```
	63	+
	64	+ After installing, `.tf`, `.hcl`, `.pp`, `.sh`, `.bash`, and `.zsh` files are parsed automatically. Ansible YAML files are detected heuristically by directory structure. Chef cookbooks are enriched via the Chef enricher on top of the Ruby parser.
	65	+
56	66	=== "[llm]"
57	67
58	68	LLM provider integrations for Anthropic, OpenAI, and Ollama. Required for `navegador ask`, `navegador docs`, and `navegador semantic-search`.
59	69
60	70	```bash
		@@ -66,11 +76,11 @@
66	76	=== "all extras"
67	77
68	78	Install everything at once:
69	79
70	80	```bash
71		- pip install "navegador[sqlite,redis,languages,llm]"
	81	+ pip install "navegador[sqlite,redis,languages,iac,llm]"
72	82	```
73	83
74	84	## Verify
75	85
76	86	```bash
		@@ -78,11 +88,11 @@
78	88	```
79	89
80	90	Expected output:
81	91
82	92	```
83		-navegador, version 0.7.0
	93	+navegador, version 0.8.0
84	94	```
85	95
86	96	## Shell completions
87	97
88	98	Install shell completions for tab-completion of commands and flags:
89	99

	--- docs/getting-started/installation.md
	+++ docs/getting-started/installation.md
	@@ -51,10 +51,20 @@
51	pip install "navegador[languages]"
52	```
53
54	After installing, all 13 languages are parsed automatically by `navegador ingest`. No additional configuration is required.
55










56	=== "[llm]"
57
58	LLM provider integrations for Anthropic, OpenAI, and Ollama. Required for `navegador ask`, `navegador docs`, and `navegador semantic-search`.
59
60	```bash
	@@ -66,11 +76,11 @@
66	=== "all extras"
67
68	Install everything at once:
69
70	```bash
71	pip install "navegador[sqlite,redis,languages,llm]"
72	```
73
74	## Verify
75
76	```bash
	@@ -78,11 +88,11 @@
78	```
79
80	Expected output:
81
82	```
83	navegador, version 0.7.0
84	```
85
86	## Shell completions
87
88	Install shell completions for tab-completion of commands and flags:
89

	--- docs/getting-started/installation.md
	+++ docs/getting-started/installation.md
	@@ -51,10 +51,20 @@
51	pip install "navegador[languages]"
52	```
53
54	After installing, all 13 languages are parsed automatically by `navegador ingest`. No additional configuration is required.
55
56	=== "[iac]"
57
58	Infrastructure-as-Code parsers for HCL/Terraform, Puppet, Bash/Shell, Ansible, and Chef.
59
60	```bash
61	pip install "navegador[iac]"
62	```
63
64	After installing, `.tf`, `.hcl`, `.pp`, `.sh`, `.bash`, and `.zsh` files are parsed automatically. Ansible YAML files are detected heuristically by directory structure. Chef cookbooks are enriched via the Chef enricher on top of the Ruby parser.
65
66	=== "[llm]"
67
68	LLM provider integrations for Anthropic, OpenAI, and Ollama. Required for `navegador ask`, `navegador docs`, and `navegador semantic-search`.
69
70	```bash
	@@ -66,11 +76,11 @@
76	=== "all extras"
77
78	Install everything at once:
79
80	```bash
81	pip install "navegador[sqlite,redis,languages,iac,llm]"
82	```
83
84	## Verify
85
86	```bash
	@@ -78,11 +88,11 @@
88	```
89
90	Expected output:
91
92	```
93	navegador, version 0.8.0
94	```
95
96	## Shell completions
97
98	Install shell completions for tab-completion of commands and flags:
99

M docs/guide/framework-enrichment.md

+3 -1

		--- docs/guide/framework-enrichment.md
		+++ docs/guide/framework-enrichment.md
		@@ -41,10 +41,12 @@
41	41	\| pytest \| Python \| `def test_`, `@pytest.mark.`, `conftest.py` \| `Test`, `Fixture`, `TestSuite` \|
42	42	\| SQLAlchemy \| Python \| `Base` subclasses, `Column`, `relationship()` \| `Model`, `Column`, `Relation` \|
43	43	\| Next.js \| TypeScript \| `pages/`, `app/`, `getServerSideProps` \| `Page`, `Route`, `ServerComponent` \|
44	44	\| Express \| JavaScript \| `app.get/post/put/delete`, `Router` \| `Route`, `Middleware` \|
45	45	\| NestJS \| TypeScript \| `@Controller`, `@Injectable`, `@Module` \| `Controller`, `Service`, `Module` \|
	46	+\| Terraform \| HCL \| `main.tf`, `variables.tf`, `outputs.tf` \| Cross-file module resolution, provider grouping \|
	47	+\| Chef \| Ruby \| `metadata.rb`, `Berksfile` \| `chef_recipe`, `chef_resource`, `chef_cookbook`, `chef_include` \|
46	48
47	49	!!! note
48	50	Framework detection is automatic when `--framework auto` is used (the default). Navegador inspects imports and decorator patterns to identify which frameworks are present.
49	51
50	52	---
		@@ -77,11 +79,11 @@
77	79	navegador enrich ./src --framework django
78	80	navegador enrich ./src --framework fastapi
79	81	navegador enrich ./src --framework pytest
80	82	```
81	83
82		-Valid values: `django`, `flask`, `fastapi`, `pytest`, `sqlalchemy`, `nextjs`, `express`, `nestjs`, `auto` (default).
	84	+Valid values: `django`, `flask`, `fastapi`, `pytest`, `sqlalchemy`, `nextjs`, `express`, `nestjs`, `terraform`, `chef`, `auto` (default).
83	85
84	86	### JSON output
85	87
86	88	```bash
87	89	navegador enrich ./src --json
88	90

	--- docs/guide/framework-enrichment.md
	+++ docs/guide/framework-enrichment.md
	@@ -41,10 +41,12 @@
41	\| pytest \| Python \| `def test_`, `@pytest.mark.`, `conftest.py` \| `Test`, `Fixture`, `TestSuite` \|
42	\| SQLAlchemy \| Python \| `Base` subclasses, `Column`, `relationship()` \| `Model`, `Column`, `Relation` \|
43	\| Next.js \| TypeScript \| `pages/`, `app/`, `getServerSideProps` \| `Page`, `Route`, `ServerComponent` \|
44	\| Express \| JavaScript \| `app.get/post/put/delete`, `Router` \| `Route`, `Middleware` \|
45	\| NestJS \| TypeScript \| `@Controller`, `@Injectable`, `@Module` \| `Controller`, `Service`, `Module` \|


46
47	!!! note
48	Framework detection is automatic when `--framework auto` is used (the default). Navegador inspects imports and decorator patterns to identify which frameworks are present.
49
50	---
	@@ -77,11 +79,11 @@
77	navegador enrich ./src --framework django
78	navegador enrich ./src --framework fastapi
79	navegador enrich ./src --framework pytest
80	```
81
82	Valid values: `django`, `flask`, `fastapi`, `pytest`, `sqlalchemy`, `nextjs`, `express`, `nestjs`, `auto` (default).
83
84	### JSON output
85
86	```bash
87	navegador enrich ./src --json
88

	--- docs/guide/framework-enrichment.md
	+++ docs/guide/framework-enrichment.md
	@@ -41,10 +41,12 @@
41	\| pytest \| Python \| `def test_`, `@pytest.mark.`, `conftest.py` \| `Test`, `Fixture`, `TestSuite` \|
42	\| SQLAlchemy \| Python \| `Base` subclasses, `Column`, `relationship()` \| `Model`, `Column`, `Relation` \|
43	\| Next.js \| TypeScript \| `pages/`, `app/`, `getServerSideProps` \| `Page`, `Route`, `ServerComponent` \|
44	\| Express \| JavaScript \| `app.get/post/put/delete`, `Router` \| `Route`, `Middleware` \|
45	\| NestJS \| TypeScript \| `@Controller`, `@Injectable`, `@Module` \| `Controller`, `Service`, `Module` \|
46	\| Terraform \| HCL \| `main.tf`, `variables.tf`, `outputs.tf` \| Cross-file module resolution, provider grouping \|
47	\| Chef \| Ruby \| `metadata.rb`, `Berksfile` \| `chef_recipe`, `chef_resource`, `chef_cookbook`, `chef_include` \|
48
49	!!! note
50	Framework detection is automatic when `--framework auto` is used (the default). Navegador inspects imports and decorator patterns to identify which frameworks are present.
51
52	---
	@@ -77,11 +79,11 @@
79	navegador enrich ./src --framework django
80	navegador enrich ./src --framework fastapi
81	navegador enrich ./src --framework pytest
82	```
83
84	Valid values: `django`, `flask`, `fastapi`, `pytest`, `sqlalchemy`, `nextjs`, `express`, `nestjs`, `terraform`, `chef`, `auto` (default).
85
86	### JSON output
87
88	```bash
89	navegador enrich ./src --json
90

M docs/guide/ingestion.md

+37 -1

		--- docs/guide/ingestion.md
		+++ docs/guide/ingestion.md
		@@ -28,14 +28,27 @@
28	28	\| `.rb` \| Ruby \| `[languages]` \|
29	29	\| `.swift` \| Swift \| `[languages]` \|
30	30	\| `.c`, `.h` \| C \| `[languages]` \|
31	31	\| `.cpp`, `.cc`, `.cxx`, `.hpp` \| C++ \| `[languages]` \|
32	32
33		-Install extended language support:
	33	+Infrastructure-as-Code:
	34	+
	35	+\| Extension(s) \| Language \| Extra \|
	36	+\|---\|---\|---\|
	37	+\| `.tf`, `.hcl` \| HCL / Terraform \| `[iac]` \|
	38	+\| `.pp` \| Puppet \| `[iac]` \|
	39	+\| `.sh`, `.bash`, `.zsh` \| Bash / Shell \| `[iac]` \|
	40	+\| `.yml`, `.yaml` \| Ansible \| `[iac]` (heuristic detection) \|
	41	+\| `.rb` (in Chef cookbooks) \| Chef \| `[iac]` (enricher on Ruby parser) \|
	42	+
	43	+Ansible files are not matched by extension — navegador detects them by directory structure (`roles/`, `playbooks/`, `group_vars/`, `host_vars/`) or content (`hosts:` + `tasks:` keys). Chef uses the existing Ruby parser; the Chef enricher promotes nodes with Chef-specific semantic types.
	44	+
	45	+Install language and IaC support:
34	46
35	47	```bash
36	48	pip install "navegador[languages]"
	49	+pip install "navegador[iac]"
37	50	```
38	51
39	52	The following directories are always skipped: `.git`, `.venv`, `venv`, `node_modules`, `__pycache__`, `dist`, `build`, `.next`, `target` (Rust/Java builds), `vendor` (Go modules), `.gradle`.
40	53
41	54	### What gets extracted
		@@ -49,10 +62,33 @@
49	62	\| Call relationships \| `CALLS` edges between functions based on static call analysis \|
50	63	\| Inheritance \| `INHERITS` edges from subclass to parent \|
51	64
52	65	Doc comment formats supported per language: Python docstrings, JSDoc (`/** */`), Rust `///`, Java Javadoc.
53	66
	67	+### IaC extraction
	68	+
	69	+IaC parsers map infrastructure constructs to the standard node labels with a `semantic_type` property for specificity:
	70	+
	71	+\| Language \| Construct \| Node label \| `semantic_type` \|
	72	+\|---\|---\|---\|---\|
	73	+\| Terraform \| `resource` \| `Class` \| `terraform_resource` \|
	74	+\| Terraform \| `variable` / `output` / `locals` \| `Variable` \| `terraform_variable` / `terraform_output` / `terraform_local` \|
	75	+\| Terraform \| `module` \| `Module` \| `terraform_module` \|
	76	+\| Terraform \| `data` / `provider` \| `Class` \| `terraform_data` / `terraform_provider` \|
	77	+\| Puppet \| `class` / `define` / `node` \| `Class` \| `puppet_class` / `puppet_defined_type` / `puppet_node` \|
	78	+\| Puppet \| resource declaration \| `Function` \| `puppet_resource` \|
	79	+\| Puppet \| `include` \| `Import` \| `puppet_include` \|
	80	+\| Ansible \| playbook file \| `Module` \| `ansible_playbook` \|
	81	+\| Ansible \| play \| `Class` \| `ansible_play` \|
	82	+\| Ansible \| task / handler \| `Function` \| `ansible_task` / `ansible_handler` \|
	83	+\| Ansible \| role \| `Import` \| `ansible_role` \|
	84	+\| Bash \| function \| `Function` \| `shell_function` \|
	85	+\| Bash \| variable \| `Variable` \| `shell_variable` \|
	86	+\| Bash \| `source` / `.` \| `Import` \| `shell_source` \|
	87	+
	88	+Cross-references are extracted where possible: Terraform `var.x`, `module.x`, and resource-to-resource dependencies become `REFERENCES` / `DEPENDS_ON` edges. Ansible `notify:` keys create `CALLS` edges to handlers. Puppet `include` creates `IMPORTS` edges.
	89	+
54	90	### Options
55	91
56	92	\| Flag \| Effect \|
57	93	\|---\|---\|
58	94	\| `--clear` \| Wipe the graph before ingesting (full rebuild) \|
59	95

	--- docs/guide/ingestion.md
	+++ docs/guide/ingestion.md
	@@ -28,14 +28,27 @@
28	\| `.rb` \| Ruby \| `[languages]` \|
29	\| `.swift` \| Swift \| `[languages]` \|
30	\| `.c`, `.h` \| C \| `[languages]` \|
31	\| `.cpp`, `.cc`, `.cxx`, `.hpp` \| C++ \| `[languages]` \|
32
33	Install extended language support:












34
35	```bash
36	pip install "navegador[languages]"

37	```
38
39	The following directories are always skipped: `.git`, `.venv`, `venv`, `node_modules`, `__pycache__`, `dist`, `build`, `.next`, `target` (Rust/Java builds), `vendor` (Go modules), `.gradle`.
40
41	### What gets extracted
	@@ -49,10 +62,33 @@
49	\| Call relationships \| `CALLS` edges between functions based on static call analysis \|
50	\| Inheritance \| `INHERITS` edges from subclass to parent \|
51
52	Doc comment formats supported per language: Python docstrings, JSDoc (`/** */`), Rust `///`, Java Javadoc.
53























54	### Options
55
56	\| Flag \| Effect \|
57	\|---\|---\|
58	\| `--clear` \| Wipe the graph before ingesting (full rebuild) \|
59

	--- docs/guide/ingestion.md
	+++ docs/guide/ingestion.md
	@@ -28,14 +28,27 @@
28	\| `.rb` \| Ruby \| `[languages]` \|
29	\| `.swift` \| Swift \| `[languages]` \|
30	\| `.c`, `.h` \| C \| `[languages]` \|
31	\| `.cpp`, `.cc`, `.cxx`, `.hpp` \| C++ \| `[languages]` \|
32
33	Infrastructure-as-Code:
34
35	\| Extension(s) \| Language \| Extra \|
36	\|---\|---\|---\|
37	\| `.tf`, `.hcl` \| HCL / Terraform \| `[iac]` \|
38	\| `.pp` \| Puppet \| `[iac]` \|
39	\| `.sh`, `.bash`, `.zsh` \| Bash / Shell \| `[iac]` \|
40	\| `.yml`, `.yaml` \| Ansible \| `[iac]` (heuristic detection) \|
41	\| `.rb` (in Chef cookbooks) \| Chef \| `[iac]` (enricher on Ruby parser) \|
42
43	Ansible files are not matched by extension — navegador detects them by directory structure (`roles/`, `playbooks/`, `group_vars/`, `host_vars/`) or content (`hosts:` + `tasks:` keys). Chef uses the existing Ruby parser; the Chef enricher promotes nodes with Chef-specific semantic types.
44
45	Install language and IaC support:
46
47	```bash
48	pip install "navegador[languages]"
49	pip install "navegador[iac]"
50	```
51
52	The following directories are always skipped: `.git`, `.venv`, `venv`, `node_modules`, `__pycache__`, `dist`, `build`, `.next`, `target` (Rust/Java builds), `vendor` (Go modules), `.gradle`.
53
54	### What gets extracted
	@@ -49,10 +62,33 @@
62	\| Call relationships \| `CALLS` edges between functions based on static call analysis \|
63	\| Inheritance \| `INHERITS` edges from subclass to parent \|
64
65	Doc comment formats supported per language: Python docstrings, JSDoc (`/** */`), Rust `///`, Java Javadoc.
66
67	### IaC extraction
68
69	IaC parsers map infrastructure constructs to the standard node labels with a `semantic_type` property for specificity:
70
71	\| Language \| Construct \| Node label \| `semantic_type` \|
72	\|---\|---\|---\|---\|
73	\| Terraform \| `resource` \| `Class` \| `terraform_resource` \|
74	\| Terraform \| `variable` / `output` / `locals` \| `Variable` \| `terraform_variable` / `terraform_output` / `terraform_local` \|
75	\| Terraform \| `module` \| `Module` \| `terraform_module` \|
76	\| Terraform \| `data` / `provider` \| `Class` \| `terraform_data` / `terraform_provider` \|
77	\| Puppet \| `class` / `define` / `node` \| `Class` \| `puppet_class` / `puppet_defined_type` / `puppet_node` \|
78	\| Puppet \| resource declaration \| `Function` \| `puppet_resource` \|
79	\| Puppet \| `include` \| `Import` \| `puppet_include` \|
80	\| Ansible \| playbook file \| `Module` \| `ansible_playbook` \|
81	\| Ansible \| play \| `Class` \| `ansible_play` \|
82	\| Ansible \| task / handler \| `Function` \| `ansible_task` / `ansible_handler` \|
83	\| Ansible \| role \| `Import` \| `ansible_role` \|
84	\| Bash \| function \| `Function` \| `shell_function` \|
85	\| Bash \| variable \| `Variable` \| `shell_variable` \|
86	\| Bash \| `source` / `.` \| `Import` \| `shell_source` \|
87
88	Cross-references are extracted where possible: Terraform `var.x`, `module.x`, and resource-to-resource dependencies become `REFERENCES` / `DEPENDS_ON` edges. Ansible `notify:` keys create `CALLS` edges to handlers. Puppet `include` creates `IMPORTS` edges.
89
90	### Options
91
92	\| Flag \| Effect \|
93	\|---\|---\|
94	\| `--clear` \| Wipe the graph before ingesting (full rebuild) \|
95

Navegador

Keyboard Shortcuts