226 lines
8.7 KiB
Python
Executable File
226 lines
8.7 KiB
Python
Executable File
#!/usr/bin/env python3
|
|
# SPDX-FileCopyrightText: 2026 Coffey Labs LLC
|
|
# SPDX-License-Identifier: Apache-2.0
|
|
"""The chart's values reference, charts/inbuxa/VALUES.md, from values.yaml
|
|
(each value's comment and default) and values.schema.json (its type and
|
|
limits). CI checks the committed copy is current:
|
|
|
|
tools/values-reference.py writes it
|
|
tools/values-reference.py --check fails when it's out of date
|
|
|
|
Standard library only: values.yaml is read line by line, which is how its
|
|
comments are kept, and the chart's values.yaml keeps to the plain block
|
|
style this reads (one key per line; lists and maps inline, or as a block
|
|
under their key).
|
|
"""
|
|
import json, re, sys
|
|
from pathlib import Path
|
|
|
|
ROOT = Path(__file__).resolve().parent.parent
|
|
CHART = ROOT / "charts" / "inbuxa"
|
|
OUT = CHART / "VALUES.md"
|
|
KEY = re.compile(r"^(?P<indent> *)(?P<key>[A-Za-z0-9_.\"-]+):(?: (?P<value>.*))?$")
|
|
|
|
|
|
def read_values(text):
|
|
"""[(path, comment lines, default or None for a section, block lines)]"""
|
|
entries, stack, comment, current = [], [], [], None
|
|
for raw in text.splitlines():
|
|
line = raw.rstrip()
|
|
stripped = line.strip()
|
|
if stripped.startswith("#"):
|
|
comment.append(re.sub(r"^# ?", "", stripped))
|
|
continue
|
|
if not stripped:
|
|
# A blank line ends a comment that belongs to nothing below it
|
|
comment = [] if comment and not entries else comment
|
|
continue
|
|
m = KEY.match(line)
|
|
if m and not stripped.startswith("- "):
|
|
indent = len(m["indent"])
|
|
while stack and stack[-1][0] >= indent:
|
|
stack.pop()
|
|
key = m["key"].strip('"')
|
|
stack.append((indent, key))
|
|
path = ".".join(k for _, k in stack)
|
|
value = m["value"]
|
|
if value is not None and " #" in value:
|
|
value = value.split(" #", 1)[0].rstrip()
|
|
current = [path, comment, value, []]
|
|
entries.append(current)
|
|
comment = []
|
|
elif current is not None:
|
|
# A list item or a nested line under the last key
|
|
current[3].append(raw)
|
|
comment = []
|
|
return entries
|
|
|
|
|
|
def resolve(schema, root):
|
|
while isinstance(schema, dict):
|
|
if "$ref" in schema:
|
|
schema = dict(walk_ref(root, schema["$ref"]), **{k: v for k, v in schema.items() if k != "$ref"})
|
|
continue
|
|
if "allOf" in schema:
|
|
merged = {k: v for k, v in schema.items() if k != "allOf"}
|
|
for part in schema["allOf"]:
|
|
part = resolve(part, root)
|
|
for k, v in part.items():
|
|
if k == "properties":
|
|
merged.setdefault("properties", {})
|
|
for name, sub in v.items():
|
|
merged["properties"][name] = (
|
|
{"allOf": [merged["properties"][name], sub]}
|
|
if name in merged["properties"] else sub
|
|
)
|
|
else:
|
|
merged.setdefault(k, v)
|
|
schema = merged
|
|
continue
|
|
return schema
|
|
return schema or {}
|
|
|
|
|
|
def walk_ref(root, ref):
|
|
node = root
|
|
for part in ref.lstrip("#/").split("/"):
|
|
node = node[part]
|
|
return node
|
|
|
|
|
|
def schema_at(root, path):
|
|
node = resolve(root, root)
|
|
for key in path.split("."):
|
|
props = node.get("properties", {})
|
|
if key in props:
|
|
node = resolve(props[key], root)
|
|
elif isinstance(node.get("additionalProperties"), dict):
|
|
node = resolve(node["additionalProperties"], root)
|
|
else:
|
|
return {}
|
|
return node
|
|
|
|
|
|
def describe_type(s):
|
|
if "anyOf" in s or "oneOf" in s:
|
|
kinds = []
|
|
for alt in s.get("anyOf", s.get("oneOf")):
|
|
kinds.append(alt.get("type", "object"))
|
|
kind = " or ".join(dict.fromkeys(str(k) for k in kinds))
|
|
else:
|
|
kind = s.get("type", "")
|
|
if not kind and s.get("enum"):
|
|
# An enum alone: the type its values have
|
|
names = {bool: "boolean", int: "integer", float: "number", str: "string"}
|
|
kind = " or ".join(dict.fromkeys(names.get(type(v), "value") for v in s["enum"]))
|
|
if isinstance(kind, list):
|
|
kind = " or ".join(kind)
|
|
if kind == "array" and isinstance(s.get("items"), dict) and s["items"].get("type"):
|
|
kind = f"list of {s['items']['type']}"
|
|
if kind == "object" and isinstance(s.get("additionalProperties"), dict) and not s.get("properties"):
|
|
kind = f"map of {s['additionalProperties'].get('type', 'object')}"
|
|
limits = []
|
|
if "enum" in s:
|
|
limits.append("one of " + ", ".join(f"`{json.dumps(v)}`" for v in s["enum"]))
|
|
for word, key in (("at least", "minimum"), ("more than", "exclusiveMinimum"),
|
|
("at most", "maximum")):
|
|
if key in s:
|
|
limits.append(f"{word} {s[key]}")
|
|
for word, key in (("at least", "minLength"), ("at most", "maxLength")):
|
|
if key in s:
|
|
limits.append(f"{word} {s[key]} character" + ("" if s[key] == 1 else "s"))
|
|
if "pattern" in s:
|
|
limits.append(f"matching `{s['pattern']}`")
|
|
return kind, limits
|
|
|
|
|
|
def prose(comment):
|
|
"""The comment's prose, and its indented lines (examples) as a block"""
|
|
text, example = [], []
|
|
for line in comment:
|
|
if line.startswith(" ") or (example and line.startswith("-")):
|
|
example.append(line[2:] if line.startswith(" ") else line)
|
|
else:
|
|
text.append(line)
|
|
paragraph = " ".join(t for t in text if t).strip()
|
|
return paragraph, example
|
|
|
|
|
|
def render(entries, root):
|
|
return "\n".join(HEADER + body(entries, root)).rstrip() + "\n"
|
|
|
|
|
|
HEADER = [
|
|
"<!-- Generated by tools/values-reference.py from values.yaml and",
|
|
" values.schema.json. Don't edit it by hand: change those, then run",
|
|
" the tool. CI fails when this is out of date. -->",
|
|
"",
|
|
"# inbuxa chart values",
|
|
"",
|
|
"Every value the chart takes, with its default and what the values",
|
|
"schema allows. A value the schema doesn't name is refused, as is one",
|
|
"outside these limits, before anything is applied.",
|
|
"",
|
|
]
|
|
|
|
|
|
def body(entries, root):
|
|
"""Every value's entry, as Markdown lines (the docs pages use these too)"""
|
|
out = []
|
|
for path, comment, value, block in entries:
|
|
depth = path.count(".")
|
|
s = schema_at(root, path)
|
|
kind, limits = describe_type(s)
|
|
paragraph, example = prose(comment)
|
|
if not paragraph and s.get("description"):
|
|
paragraph = s["description"]
|
|
is_section = (value is None or value == "") and not block and s.get("properties")
|
|
if is_section or (value is None and not block and kind == "object" and s.get("properties")):
|
|
out.append(f"{'#' * min(depth + 2, 4)} `{path}`")
|
|
out.append("")
|
|
if paragraph:
|
|
out += [paragraph, ""]
|
|
if example:
|
|
out += ["```yaml", *example, "```", ""]
|
|
continue
|
|
default = value if value not in (None, "") else None
|
|
# One line each for the name, the default, the limits and the
|
|
# comment: a backslash ends a line without starting a paragraph
|
|
head = f"- **`{path}`**" + (f" ({kind})" if kind else "")
|
|
rest = []
|
|
if limits:
|
|
rest.append("Allowed: " + "; ".join(limits) + ".")
|
|
if paragraph:
|
|
rest.append(paragraph)
|
|
if default is not None or not block:
|
|
lines = [head] + ([f"Default: `{default}`."] if default is not None else []) + rest
|
|
out += [" " * (i > 0) + t + ("\\" if i < len(lines) - 1 else "") for i, t in enumerate(lines)]
|
|
else:
|
|
out += [head + "\\", " Default:", "", " ```yaml"]
|
|
indent = min(len(b) - len(b.lstrip()) for b in block if b.strip())
|
|
out += [" " + b[indent:] for b in block if b.strip()]
|
|
out.append(" ```")
|
|
if rest:
|
|
out += [""] + [" " + t + ("\\" if i < len(rest) - 1 else "") for i, t in enumerate(rest)]
|
|
if example:
|
|
out += ["", " ```yaml", *[" " + e for e in example], " ```"]
|
|
out.append("")
|
|
return out
|
|
|
|
|
|
def main():
|
|
values = (CHART / "values.yaml").read_text()
|
|
schema = json.loads((CHART / "values.schema.json").read_text())
|
|
text = render(read_values(values), schema)
|
|
if "--check" in sys.argv[1:]:
|
|
if not OUT.exists() or OUT.read_text() != text:
|
|
sys.exit(f"{OUT.relative_to(ROOT)} is out of date: run tools/values-reference.py")
|
|
print(f"{OUT.relative_to(ROOT)} is current")
|
|
return
|
|
OUT.write_text(text)
|
|
print(f"wrote {OUT.relative_to(ROOT)}")
|
|
|
|
|
|
if __name__ == "__main__":
|
|
main()
|