197 lines
12 KiB
Python
197 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, 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 {})}
|
|
shown = paths | scalars
|
|
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())
|
|
|