diff --git a/README.md b/README.md index 37b9ef3..fdc2878 100644 --- a/README.md +++ b/README.md @@ -122,7 +122,7 @@ Dervish discovers these conventions automatically from existing examples. The do | Domain | What gets extracted | Example extracted symbols | What Dervish discovers | Why it helps an LLM | |--------|-------------------|--------------------------|----------------------|---------------------| | Ansible roles | Module names from `tasks/main.yml` in order | `fail`, `include_vars`, `set_fact`, `package`, `file`, `template`, `service`, `npm`, `pip`, `lineinfile` | `fail?.(include_vars+set_fact+package+file+template+service+...)+.include+?.(npm+pip)+?.lineinfile?` | "Validate preconditions first, then set vars, install packages, configure with templates, start services. Include sub-roles last." | -| Helm charts | K8s resource kinds from `helm template` output in rendered order | `ServiceAccount`, `ClusterRole`, `ClusterRoleBinding`, `Service`, `Deployment`, `ConfigMap`, `Alertmanager` | `ServiceAccount.ClusterRole.ClusterRoleBinding.Service.Deployment` (iDRegEx minimal core) | "Every Prometheus stack needs this bootstrap pipeline. Everything else is optional." | +| Helm charts (cross-project, 15 charts) | K8s resource kinds from `helm template` output in rendered order | `NetworkPolicy`, `PodDisruptionBudget`, `ServiceAccount`, `Secret`, `ConfigMap`, `Service`, `Deployment`, `StatefulSet`, `ClusterRole`, `ClusterRoleBinding` | `NetworkPolicy?.PodDisruptionBudget?.ServiceAccount?.Secret?.ConfigMap?.PersistentVolumeClaim?.ClusterRole?.ClusterRoleBinding?.Service.Deployment?.StatefulSet?.(IngressClass+MutatingWebhookConfiguration)?.ValidatingWebhookConfiguration?.Job?` | "Writing a Helm chart? Start with resilience (PDB, NetworkPolicy), then identity (ServiceAccount, Secrets), then the Service, then your workload. Only cluster-wide tools need RBAC." | | GitHub Actions (Go lint) | Step `uses:` or `run:` values from workflow YAML in job order | `actions/checkout`, `actions/setup-go`, `golangci/golangci-lint-action`, `megalinter/megalinter` | `actions/checkout.(actions/setup-go+run:echo+run:sudo)+.golangci/golangci-lint-action?.megalinter?` | "Starting a new Go project on GitHub Actions? Four independent projects converged on: checkout → setup Go → (optional golangci-lint) → (optional megalinter)." | @@ -133,7 +133,7 @@ Dervish has been tested against public datasets from Ansible Galaxy, Helm, and G | Dataset | Best grammar | Compression | |---------|-------------|-------------| | Ansible Galaxy (15 roles) | `fail?.(include_vars+set_fact+package+file+template+service+...)+.include+?.(npm+pip)+?.lineinfile?` | 5,000 tokens → 60 tokens (83×) | -| Helm (6 configs) | `ServiceAccount.ClusterRole.ClusterRoleBinding.Service.Deployment` | ~3,000 tokens → 40 tokens (75×) | +| Helm cross-project (15 charts) | `NetworkPolicy?.PodDisruptionBudget?.ServiceAccount?.Secret?.ConfigMap?...Service.Deployment?.StatefulSet?...` | 121 tokens → 35 tokens (3.5×) | | Go lint (6 jobs) | `actions/checkout.(actions/setup-go+run:echo+run:sudo)+.golangci/golangci-lint-action?.megalinter?` | ~900 tokens → 30 tokens (30×) | The sweet spot: **multiple implementations of the same abstract task** with a shared but undocumented pattern. Not everything works — Dockerfiles, pre-commit configs, and schema-enforced formats are too rigid or too diverse to yield a convention. diff --git a/SHOWCASE.md b/SHOWCASE.md index 8a7c246..abf84b1 100644 --- a/SHOWCASE.md +++ b/SHOWCASE.md @@ -14,7 +14,7 @@ r+ → one or more (iteration) r+? → zero or more ``` -## 1. Ansible Galaxy roles (15 geerlingguy roles) — flagship +## 1. Ansible Galaxy roles (15 geerlingguy roles) 15 popular Ansible roles by Jeff Geerling. There is NO written convention for the module ordering in `tasks/main.yml`. Our grammar is its first @@ -53,19 +53,35 @@ phpmyadmin uses raw `lineinfile` instead of templates; composer needs a `stat` check + `uri` download; pip is purely `pip` — all three deviate from the mainstream install → configure → enable pattern. -## 2. Helm chart (kube-prometheus-stack, 6 configs) +## 2. Helm charts — cross-project convention (15 charts, 6 publishers) -6 different `values.yaml` files rendered through the same chart: +15 popular Helm charts from **Bitnami** (10), **Grafana**, **Jetstack** (cert-manager), +**Argo**, **Ingress-Nginx**, and **Elastic**. Different publishers, different +purposes (databases, web servers, infrastructure tools) — but they converged +on a common resource ordering: ```text -Best: iDRegEx | MDL 1433 -Grammar: ServiceAccount.ClusterRole.ClusterRoleBinding.Service.Deployment +Best: CRX | MDL 230 +Grammar: NetworkPolicy?.PodDisruptionBudget?.ServiceAccount?.Secret? + .ConfigMap?.PersistentVolumeClaim?.ClusterRole?.ClusterRoleBinding? + .Role?.RoleBinding?.Service.Deployment?.StatefulSet?. + (IngressClass+MutatingWebhookConfiguration)?.ValidatingWebhookConfiguration?.Job? + +Match rates: CRX=15/15 ``` -The **minimal core** every config must deploy. CRX captures the full -vocabulary (19 kinds). Which one an agent uses depends on the task: -- Bootstrapping a new cluster: iDRegEx — what you can't skip -- Writing a complete chart: CRX — everything you might need +Every chart follows: **resilience → identity → data → service → workload → extensions**. + +`Service` is the **only resource type that appears in all 15 charts**. +Bitnami charts (10/15) consistently start with `NetworkPolicy + PodDisruptionBudget` +before identity and service. Infrastructure tools (cert-manager, grafana, +argo-cd, ingress-nginx) add RBAC and admission webhooks for cluster-wide access. + +**Why it helps an LLM:** Generating a Helm chart template? You know the +structure: start with availability guarantees (PDB, NetworkPolicy), then +identity (ServiceAccount, Secrets), then the Service endpoint, then your +workload type. Only cluster-wide tools need RBAC and webhooks — skip them +for simple application charts. ## 3. GitHub Actions (cross-project Go lint, 6 jobs) diff --git a/chart_token_savings.png b/chart_token_savings.png index ec7b081..ee78970 100644 Binary files a/chart_token_savings.png and b/chart_token_savings.png differ