tama violations declare-root

Declares a repository root to the audit when every file it holds is fixed there by somebody else's tooling, and refuses while anything movable is still in it.

#Invocation

tama violations declare-root (--repo <path> | --tree <dir>) [...] [--apply] [--tidy] [--commit] [--push] [--withdraw] [--json]

--repo names one checkout and --tree walks every Git checkout under a directory, so a workshop of two hundred repositories is one command. Without --apply the run is a report. --commit records what it wrote in the repository that received it, --push publishes that commit, and both also finish a declaration an earlier run left uncommitted in a working tree.

#Why a root is different

The five-files-per-folder rule holds wherever a person decides the layout. A repository root is not such a place: npm reads package.json and package-lock.json there, cargo reads Cargo.toml and Cargo.lock there, SwiftPM reads Package.swift there, git reads .gitignore there, GitHub shows README.md and the licence from there, and the release tooling reads .wisent-release.json there. Six such files already exceed the limit and no arrangement of folders can help, so the audit's own answer is the . entry in .tama/violations-ignore. Writing that by hand once per repository is the one-off repair this workshop refuses; this command is its repeatable form.

#What it refuses

A root that still holds a file a person could move into a folder is not declared, and the refusal names those files: they belong in a folder, not in a declaration. A root holding something nothing reads at all — .DS_Store, Thumbs.db, desktop.ini — is refused with a different sentence, because those are deleted rather than moved. Neither refusal writes anything, so the declaration can never launder ordinary clutter into an exemption.

Two Swift shapes are recognised: .swiftlint.yml, .swiftformat and .swift-version are read from the root by the tools that own them, so they are declared; and what a Swift compiler writes beside the code it read — a .swiftmodule with its .swiftdeps, .dia and dependency siblings — is build output that was committed by accident, so --tidy deletes it, drops it from the index and names it in .gitignore. Build output is matched by suffix, not by name: the stem is whatever was being compiled, so a name list would never keep up.

What it cannot read is refused, not guessed: a declaration file that exists and cannot be read (cannot read <path>: <cause>) is never taken for an undeclared root, a git status that fails (git status in <repo> ended with <status>: <stderr>) is never taken for a committed declaration, and inside a Git checkout a failing git ls-files is never taken for a root with nothing ignored. A missing declaration file is an undeclared root, and outside a checkout nothing is ignored.

#What it writes

The entry is appended to .tama/violations-ignore, never replacing what a repository already declares, and it carries a comment naming every root file with the tool that fixes it there. A second run reports the root is already declared and changes nothing.

#Taking it back: --withdraw

A declaration is a claim, and a root that later gains a file somebody could move, or a claim that was wrong, must be audited again. --withdraw removes the paragraph this command wrote and the . entry under it, leaves every other exclusion in the file as it was, and deletes the file when nothing else was in it; --commit and --push carry the withdrawal the same way a declaration is carried. Without --apply it reports would withdraw the root's declaration and changes nothing. A root that is not declared is refused — the root is not declared in <file>; there is nothing to withdraw — so a repeated withdrawal never pretends to take something back twice. The report carries withdrawn, and the text run ends with how many roots were withdrawn.

#Output and state

Text mode prints one line per repository and ends with how many roots were declared, or withdrawn; with a single target it also lists the files and their tools. JSON returns an array of reports with fixed, movable, junk, declared, reason, withdrawn when a withdrawal happened, and the commit revision when one was made. Exit 1 means at least one root was not declared, or under --withdraw not withdrawn; missing paths and unknown arguments print usage and exit 2.

Return to the complete CLI command tree.