Files
2026-11-20 20:15:33 +01:00

236 lines
16 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.
`~/.claude-projects/do-epic/` holds do-epic's machine-wide settings, not a project's. It needs no `checkout`,
and project-config doesn't read anything from it, so no project may use `do-epic` as its key.
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.
`jira-finding-type` is an optional setting, allowed only beside such a plan: the Jira issue type
`todo-item add` files an item as, such as "Feature", for a Jira project that has no Task type.
Task where left out. `todo-item add` fails, naming the types the project has, where it has none of that name.
`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
written by `project-record save`, except a change to ## Goals or ## Audience, which is refused:
edit those two in Jira. A save rewrites the whole description from markdown, which keeps no
mention, macro or block id that markdown can't hold.
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.
`coding-conventions` is an optional setting, a list of paths spelt as the others are: the files in
which the project's team wrote its own coding conventions, such as
`coding-conventions = ["checkout:CONVENTIONS.md"]`. Each reviewer agent larv-review launches reads
them beside the principles and the standards, and the team's rule wins where they conflict. `project-config coding-conventions`
prints one path a line. Left out, the reviewers read no such file. 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.
`merge` is an optional setting, "chunk" or "human": who merges a chunk's pull request. Left out, it is
"chunk": `chunk-pr merge` merges it. Under "human", for a team whose rules keep the merge with a person,
`chunk-pr merge` leaves the pull request ready and says it awaits a person's merge. `project-config merge`
prints chunk or human; the full listing shows the setting only where it is human.
`epic-branch` is an optional setting: a template that names an epic's working branch, with {epic} for the
epic's key, such as `epic-branch = "{epic}"` or "epic/{epic}". The epic is the Jira epic `plan` names, or
under do-epic the epic it drives. Each chunk then
branches off that branch, and `chunk-pr` opens its pull request into it and merges it there without a
person, whatever `merge` and `wait-for-approval` say: those guard the default branch. `chunk-preflight`
makes the branch on origin off the default branch, or merges the default branch into it, and stops where
that merge conflicts, which a person resolves. `chunk-pr open-epic` opens the pull request from the branch
into the default branch, which a person merges. Left out, each chunk merges into the default branch.
`review-request-comment` is an optional setting, one line of text that doesn't start with `-`: the
comment that asks the project's auto-reviewer for a review, such as "@reviewbot review", for a reviewer
that on its own reviews only pull requests into the default branch. `chunk-pr ready` and `chunk-pr push` post it on a pull request
into the epic's working branch. It requires `epic-branch`. Left out, no comment is posted.
Each of the two is printed with the others only where it is set.
`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 `coding-conventions` to anything but a list of paths, sets `wait-for-approval` or
`tooling-on-host` to anything but true or false, sets `merge` to anything but chunk or human, sets `epic-branch` to anything but a branch name with one {epic}, sets `review-request-comment` to anything but one line of text or without `epic-branch`, 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, sets `parallel-chunks` to anything but a whole number of 1 or more, or sets `jira-finding-type` to anything but a name or without a `plan` in Jira, and where `coding-conventions`, `env-file`, `epic-branch`, `jira-finish-transition`, `jira-finish-status`, `notifier`, `review-request-comment` or `touch-predictions` is asked for and not set. No path setting has a default.
"""
import pathlib
import sys
from project_config.settings import CODING_CONVENTIONS, CONFIG, ENV_FILE, JIRA_FINISH_STATUS, JIRA_FINISH_TRANSITION, JIRA_SCORE_BAR, JIRA_SCORE_FORMULA, load, OPTIONAL, ProjectConfig, SCALARS, SETTINGS, Unnamed
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
# A one-value setting prints its value, its default where the config leaves it out; one without a default, as `notifier`, prints only where set.
scalars = {scalar.name: scalar.shown(value) for scalar in SCALARS if (value := getattr(config, scalar.field)) is not None}
paths = {**config.places, **({ENV_FILE: str(config.env_file)} if config.env_file 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 {})}
# The listing names the conventions on one line; asked for alone, they print one path a line, for a script to read.
conventions = [str(path) for path in config.coding_conventions]
paths |= {CODING_CONVENTIONS: ", ".join(conventions)} if conventions else {}
shown = paths | scalars | ({CODING_CONVENTIONS: "\n".join(conventions)} if conventions else {})
if argv and argv[0] not in shown:
print(f"{config.folder / CONFIG} sets no `{argv[0]}`", file=sys.stderr)
return 1
# The listing leaves out each one-value setting at its default.
defaults = ProjectConfig(config.key, config.folder, config.top, {})
listed = [*(f"{name}: {path}" for name, path in paths.items()), *(f"{scalar.name}: {scalars[scalar.name]}" for scalar in SCALARS if getattr(config, scalar.field) != getattr(defaults, scalar.field))]
print(shown[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())