Files
claude-config/bin/project_config/main.py
T

206 lines
12 KiB
Python

"""Print the paths a project's config sets.
usage: project-config [<setting>]
Run inside a checkout, or a worktree of one. It finds the config that names the checkout,
~/.claude-projects/<key>/config.toml, and prints each setting and its absolute path, as in
`plan: /home/me/code/acme/todo.md`. Given a setting, it prints only that setting's path.
The config is TOML. `checkout` names the project's main checkout, and every setting in the example below is a path:
"checkout:<path>" inside the checkout, "folder:<path>" inside the config's own folder, or one that
starts with / or ~/. In a worktree, a "checkout:" path is the worktree's own file.
checkout = "~/code/acme-billing"
plan = "folder:todo.md"
working-rules = "folder:AGENTS.md"
decisions = "folder:docs/decisions.md"
score-anchors = "folder:docs/score-anchors.md"
comprehension-history = "folder:docs/comprehension-history.md"
reading-cost = "folder:docs/reading-cost.md"
changelog = "checkout:CHANGELOG.md"
goals-and-audience = "folder:goals.md"
principles = "folder:principles"
standards = "~/.claude/skills/larv-review/standards"
`principles` and `standards` name the folders the reviewers hold the project to: the technical
principles and the review standards. A standards folder must hold quality.md, prose.md, comments.md
and readme.md, since the reviewers and the rules name those files.
`plan` may name a Jira Cloud epic in place of a path, as "jira:" and the epic's address:
"jira:https://acme.atlassian.net/browse/ABC-12". The plan is then the epic's open child issues, in
Jira's backlog order, and `project-config plan` prints the setting as the config spells it. Such a
config must set `env-file`, and that file must hold ATLASSIAN_EMAIL and ATLASSIAN_API_TOKEN.
Such a config must also set two settings. `jira-score-formula` is the formula that scores an item.
`jira-score-bar` is the lowest score at which `todo-item add` files an item that isn't exempt, as a
bare number. They hold what a todo.md states as `Score` and `Bar`, which `rank_todo.py --help` describes:
jira-score-formula = "100 * V / (2**S + 8)"
jira-score-bar = 1
`jira-finish-transition` and `jira-finish-status` are optional settings, set together and only
beside such a plan, since each Jira workflow differs. `todo-item finish` moves an item's issue by
the workflow transition the first names. That transition must lead to the status the second names,
which must be one Jira counts as done. Write both names as Jira shows them:
jira-finish-transition = "Mark as done"
jira-finish-status = "Done"
Where the config leaves them out, `todo-item finish` fails in a Jira plan. Each is printed with the others only where it is set.
`goals-and-audience` may name a Jira Cloud epic the same way, where `plan` names one too. The
epic's description is then the goals file, with ## Goals and ## Audience as headings, and
`project-config goals-and-audience` prints the setting as the config spells it. The description is
only read: edit it in Jira.
Each record, `decisions`, `score-anchors`, `comprehension-history`, `reading-cost` and `changelog`,
may name a Confluence Cloud page in place of a path, as "confluence:" and the page's address, with or
without the title at its end: "confluence:https://acme.atlassian.net/wiki/spaces/ENG/pages/2293761".
The record is then that page's text, which `project-record` reads and writes as markdown, and
`project-config <record>` prints the setting as the config spells it. A mention or a macro on the
page reads as plain text, and a save writes that text in its place. Such a config must set
`env-file`, holding ATLASSIAN_EMAIL and ATLASSIAN_API_TOKEN, as for a Jira epic.
`decisions` and `comprehension-history` may name a page only where `plan` names a Jira epic, since
rule-hook ranks a plan kept as a file before tool calls, and a read from Confluence mustn't hold it up.
`env-file` is an optional setting: the file of KEY=value credentials the project's tools read,
a path that starts with / or ~/ and lies outside the checkout and the config's folder, such as
"~/.claude-projects/acme-billing.env". Where it is left out, the project has no credentials file, and
a tool that needs one fails naming the setting. It is printed with the others only where it is set.
`touch-predictions` is an optional setting, a path spelt as the others are, never a page: the record
where `touch-predictions record` appends what each chunk was predicted to touch beside what it touched.
Left out, the project keeps no such record. It is printed with the others only where it is set.
`notifier` is an optional setting, "mattermost" or "slack": the service that sends loop-claude's DMs and
`notify`'s messages to the human. Setting it requires `env-file`, which holds that service's keys;
`notify --help` names them. Left out, the project gets no DMs. It is printed with the others only where it
is set.
`wait-for-approval` is an optional setting, true or false: whether `chunk-pr merge` waits for a human's
approval of the pull request, as its branch protection requires on GitHub, before it merges. Left out, it is
false. `project-config wait-for-approval` prints true or false; the full listing shows the setting only where
it is true.
`tooling-on-host` is an optional setting, true or false: whether the loop may run the project's language
runtime, package manager, tests and task runner directly on the host, for a project with no container
setup. Left out, it is false, and they run through the project's container setup.
`readability-floor` is an optional setting, a number from 1 to 10: the comprehension score a project
aims for. While the panel's overall score is under it, code health weighs 4 times as much in the plan's
ranking, and a scoring run with a mean under it asks for a floor item. A legacy project, whose code
scores low, may lower it. Left out, it is 7.0.
`parallel-chunks` is an optional setting, a whole number of 1 or more: the most chunks of the project
loop-claude runs at once, each in its own tmux window. Left out, it is 1.
`project-config tooling-on-host`, `project-config readability-floor` and `project-config parallel-chunks`
print their values; the full listing shows each only where the config changes it from what it is when
left out.
Four optional settings say how the project writes, for a project whose owners don't write as
~/.claude/CLAUDE.md does:
language = "Swedish"
commit-title = "[{id}] {summary}"
pull-request-title = "[{id}] {summary}"
branch = "feature/{id}"
`language` names the language of the project's prose by its English name; left out, it is English.
The others are templates. {summary} is the one line that says what a commit or pull request does,
and {id} is the ID of the chunk's first plan item. A title template holds {summary} once and {id}
at most once, never directly beside {summary}, with no space at its start or end and no control
character; left out, it is "{summary}". `branch` holds {id} once, among letters, digits and
. _ / -; left out, it is "item-{id}". A template has no way to write a literal { or }.
A title must fit its template only on a branch that fits `branch`. On any other branch, as for a
chunk with no plan item, such as a release review, it may be the bare summary. A tool that reads
a title for its summary tries `commit-title`, then `pull-request-title`, then takes the title whole.
`project-config <setting>` prints each one's value, and the full listing shows it only where the
config changes it from what it is when left out.
In a Jira plan an item's ID is its issue's number. To name a chunk by its issue key, write the
Jira project's key before {id}, as here for the key ABC:
branch = "ABC-{id}"
commit-title = "ABC-{id} - {summary}"
pull-request-title = "ABC-{id} - {summary}"
The chunk for the issue ABC-123 is then on the branch ABC-123, in the worktree <checkout>-ABC-123,
and its commits and pull request are titled "ABC-123 - …".
Exit 1, naming each fault on stderr, where no config names the checkout, or its config leaves out a
setting, names an unknown one, misspells a path, a language or a template, sets `wait-for-approval` or
`tooling-on-host` to anything but true or false, sets `notifier` to anything but mattermost or slack or
without `env-file`, sets `jira-finish-transition` or `jira-finish-status` to anything but a name, without the other or
without a `plan` in Jira, names a Jira `plan` and leaves out `jira-score-formula` or `jira-score-bar`, sets
one of those two without a `plan` in Jira, sets the formula to one that doesn't parse or the bar to anything
but a number, sets `readability-floor` to anything but a number
from 1 to 10, or sets `parallel-chunks` to anything but a whole number of 1 or more, and where `env-file`, `jira-finish-transition`, `jira-finish-status`, `notifier` or `touch-predictions` is asked for and not set. No path setting has a default.
"""
import pathlib
import sys
from project_config.settings import CONFIG, DEFAULT_FLOOR, ENV_FILE, JIRA_FINISH_STATUS, JIRA_FINISH_TRANSITION, JIRA_SCORE_BAR, JIRA_SCORE_FORMULA, load, NOTIFIER, OPTIONAL, PARALLEL_CHUNKS, ProjectConfig, READABILITY_FLOOR, SETTINGS, TOOLING_ON_HOST, Unnamed, WAIT_FOR_APPROVAL
from failure import Failure
from git_cli.git_repo import git, Git
from project_config import templates
def main(argv: list[str]) -> int:
if argv[:1] in (["-h"], ["--help"]):
print(__doc__.strip())
return 0
if len(argv) > 1 or (argv and argv[0] not in (*SETTINGS, *OPTIONAL)):
print(f"usage: project-config [<setting>], where <setting> is one of {', '.join((*SETTINGS, *OPTIONAL))}", file=sys.stderr)
return 1
config = located(None, pathlib.Path.home())
if isinstance(config, Failure):
print(config.reason, file=sys.stderr)
return 1
switches = {WAIT_FOR_APPROVAL: config.wait_for_approval, TOOLING_ON_HOST: config.tooling_on_host}
if argv and argv[0] in switches:
print("true" if switches[argv[0]] else "false")
return 0
if argv == [READABILITY_FLOOR]:
print(config.readability_floor)
return 0
if argv == [PARALLEL_CHUNKS]:
print(config.parallel_chunks)
return 0
if argv and argv[0] in config.texts:
print(config.texts[argv[0]])
return 0
paths = {**config.places, **({ENV_FILE: str(config.env_file)} if config.env_file else {}), **({NOTIFIER: config.notifier} if config.notifier else {}), **({JIRA_SCORE_FORMULA: config.jira_scoring.formula, JIRA_SCORE_BAR: f"{config.jira_scoring.bar:g}"} if config.jira_scoring else {}), **({JIRA_FINISH_TRANSITION: config.jira_finish.transition, JIRA_FINISH_STATUS: config.jira_finish.status} if config.jira_finish else {})}
if argv and argv[0] not in paths:
print(f"{config.folder / CONFIG} sets no `{argv[0]}`", file=sys.stderr)
return 1
defaults = ProjectConfig(config.key, config.folder, config.top, {}).texts
listed = [f"{name}: {path}" for name, path in paths.items()] + [f"{name}: true" for name, on in switches.items() if on] + ([f"{READABILITY_FLOOR}: {config.readability_floor}"] if config.readability_floor != DEFAULT_FLOOR else []) + ([f"{PARALLEL_CHUNKS}: {config.parallel_chunks}"] if config.parallel_chunks != 1 else []) + [f"{name}: {text}" for name, text in config.texts.items() if text != defaults[name]]
print(paths[argv[0]] if argv else "\n".join(listed))
return 0
def located(directory: str | None, home: pathlib.Path, run: Git = git) -> ProjectConfig | Failure:
"""The config under home of the checkout that holds directory, else the current directory."""
found = run("rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir", cwd=directory)
if isinstance(found, Failure):
return Unnamed(found.reason)
if len(lines := found.splitlines()) != 2:
return Failure(f"git rev-parse printed {found!r}, not a checkout's top folder and git directory on two lines")
# The common dir is the main checkout's .git, whichever worktree runs this.
return load(pathlib.Path(lines[0]), pathlib.Path(lines[1]).parent, home)
def title_templates(directory: str | None, home: pathlib.Path, run: Git = git) -> templates.Titles | Failure:
"""The title templates of the project whose checkout holds directory, else the current directory. Bare summaries where no config names a checkout there, as in a third party's clone, so every title is read as it stands. A Failure where a config is faulty or cannot be read: read bare, a templated project's round titles would count for nothing."""
config = located(directory, home, run)
if isinstance(config, Unnamed):
return templates.BARE
return config if isinstance(config, Failure) else config.titles
def project() -> ProjectConfig | Failure:
"""The config of the project whose checkout holds the current directory, under the user's home."""
return located(None, pathlib.Path.home())