236 lines
16 KiB
Python
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())
|
|
|