Documentation
¶
Overview ¶
Package layout audits and safely cleans local clone placement under a projects root. Canonical clones live at {root}/{host}/{owner}/{repository}, where {host} is the literal forge hostname. The legacy {owner}/{repository} placement this fleet still uses is read in place and reported as a finding, never silently accepted as a forge.
Index ¶
- func CleanFailed(report CleanReport) bool
- func Failed(report Report) bool
- func OriginAddress(ctx context.Context, path string) (repopath.Address, error)
- func OriginSlug(ctx context.Context, path string) (string, error)
- type CleanAction
- type CleanOptions
- type CleanReport
- type Finding
- type Kind
- type Report
- type Summary
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CleanFailed ¶
func CleanFailed(report CleanReport) bool
CleanFailed reports whether clean had errors or leftover skips that need attention when apply was requested. Dry-run never fails solely for planned removals.
func OriginAddress ¶ added in v0.138.0
OriginAddress returns the canonical clone address the origin remote of the repository at path identifies: the literal forge hostname plus owner/repository. The host is empty for a local-only remote, which names no forge and therefore no first path level.
Types ¶
type CleanAction ¶
type CleanAction struct {
Path string `json:"path" yaml:"path"`
OriginSlug string `json:"origin_slug,omitempty" yaml:"origin_slug,omitempty"`
Status string `json:"status" yaml:"status"` // removed, planned, skipped, error
Reason string `json:"reason" yaml:"reason"`
}
CleanAction is one planned or applied cleanup.
type CleanOptions ¶
CleanOptions controls safe removal of top-level clones.
type CleanReport ¶
type CleanReport struct {
SchemaVersion int `json:"schema_version" yaml:"schema_version"`
ProjectsRoot string `json:"projects_root" yaml:"projects_root"`
DryRun bool `json:"dry_run" yaml:"dry_run"`
Actions []CleanAction `json:"actions" yaml:"actions"`
}
CleanReport summarizes a clean run.
func Clean ¶
func Clean(ctx context.Context, projectsRoot string, options CleanOptions) (CleanReport, error)
Clean removes safe top-level clones. Without Apply it only plans.
func (CleanReport) Markdown ¶
func (report CleanReport) Markdown() string
Markdown renders a clean plan/result.
type Finding ¶
type Finding struct {
Path string `json:"path" yaml:"path"`
Kind Kind `json:"kind" yaml:"kind"`
PathSlug string `json:"path_slug,omitempty" yaml:"path_slug,omitempty"`
OriginSlug string `json:"origin_slug,omitempty" yaml:"origin_slug,omitempty"`
ExpectedPath string `json:"expected_path,omitempty" yaml:"expected_path,omitempty"`
// RemoteURL is the remote URL the clone's canonical path corresponds to. A
// clone that already sits at <root>/{host}/{owner}/{repository} inverts to
// it by pure path arithmetic — no configuration and no repository remote
// is read — and a legacy two-level clone reports the host its origin
// already names, which is the host level it must move under.
RemoteURL string `json:"remote_url,omitempty" yaml:"remote_url,omitempty"`
CanonicalExists bool `json:"canonical_exists,omitempty" yaml:"canonical_exists,omitempty"`
Reason string `json:"reason" yaml:"reason"`
}
Finding is one inspected checkout relative to the projects root.
type Kind ¶
type Kind string
Kind classifies one layout finding.
const ( KindOK Kind = "ok" KindTopLevel Kind = "top_level" KindMisowned Kind = "misowned" KindNoOrigin Kind = "no_origin" KindUnreadable Kind = "unreadable" // KindBadHost reports a first-level entry under the projects root that is // not a literal forge hostname while carrying canonical clones of hosted // repositories. The legacy {owner}/{repository} placement is read in // place — no fleet is ever forced to move to be audited — but it is never // presented as if its owner level were a forge. KindBadHost Kind = "bad_host" )
type Report ¶
type Report struct {
SchemaVersion int `json:"schema_version" yaml:"schema_version"`
ProjectsRoot string `json:"projects_root" yaml:"projects_root"`
ObservedAt time.Time `json:"observed_at" yaml:"observed_at"`
Summary Summary `json:"summary" yaml:"summary"`
Findings []Finding `json:"findings" yaml:"findings"`
}
Report is the deterministic layout audit index.
func Audit ¶
Audit walks projectsRoot for canonical, top-level, and misowned clones.
The first level under the root is the literal forge hostname: canonical clones live at {root}/{host}/{owner}/{repository}. A first-level entry that is not a valid hostname is reported as a layout finding. Its clones are still inspected at the legacy {owner}/{repository} placement, so a fleet that has not moved yet stays fully auditable in place.
type Summary ¶
type Summary struct {
Inspected int `json:"inspected" yaml:"inspected"`
OK int `json:"ok" yaml:"ok"`
TopLevel int `json:"top_level" yaml:"top_level"`
Misowned int `json:"misowned" yaml:"misowned"`
NoOrigin int `json:"no_origin" yaml:"no_origin"`
Unreadable int `json:"unreadable" yaml:"unreadable"`
BadHost int `json:"bad_host" yaml:"bad_host"`
}
Summary counts findings by kind.
Source Files