docs: spec audit — add github README, update fileutil/constants/timeutil/tty specs#38848
Conversation
…til/tty - Create pkg/github/README.md (ObjectiveMapping spec) - Add EnsureParentDir to pkg/fileutil/README.md functions table - Add ## Dependencies section to pkg/constants/README.md - Add ## Dependencies section to pkg/timeutil/README.md - Add ## Dependencies section to pkg/tty/README.md Closes #38847 Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
|
🧪 Test Quality Sentinel completed test quality analysis. No test files were added or modified in this PR. The PR only adds/modifies README.md documentation files (pkg/constants/README.md, pkg/fileutil/README.md, pkg/github/README.md, pkg/timeutil/README.md, pkg/tty/README.md). Test Quality Sentinel skipped. |
|
✅ Design Decision Gate 🏗️ completed the design decision gate check. No ADR enforcement needed. The default-volume gate triggered (145 additions > 100 threshold) only because the naive directory-prefix counter classifies pkg/**/README.md files as business logic. In reality all 5 changed files in PR #38848 are pure documentation: pkg/github/README.md (new spec, 120 lines), and Dependencies/API-table additions to pkg/constants, pkg/fileutil, pkg/timeutil, and pkg/tty README.md spec files. No source code changed and no architectural decision is being made — this is a spec-librarian documentation audit. Per the Design Decision Gate criteria, documentation updates do not warrant an ADR, so no draft ADR was generated and no blocking comment was posted. |
There was a problem hiding this comment.
Pull request overview
This PR updates package-level specifications to satisfy the spec-librarian audit by adding one missing package spec (pkg/github) and filling in missing sections/entries across several existing package specs.
Changes:
- Added a new
pkg/github/README.mdspec documentingObjectiveMapping, its methods/functions, constants, configuration precedence, and dependencies. - Updated
pkg/fileutil/README.mdto include the missingEnsureParentDirpublic API entry. - Added
## Dependenciessections topkg/constants,pkg/timeutil, andpkg/ttypackage specs.
Show a summary per file
| File | Description |
|---|---|
| pkg/github/README.md | New spec for ObjectiveMapping API, constants, precedence, examples, and deps |
| pkg/fileutil/README.md | Adds missing EnsureParentDir entry to the public API table |
| pkg/constants/README.md | Documents package dependencies (stdlib-only) |
| pkg/timeutil/README.md | Documents package dependencies (stdlib-only) |
| pkg/tty/README.md | Documents package dependencies, including golang.org/x/term |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 5/5 changed files
- Comments generated: 6
| |-------|------|-------------| | ||
| | `LabelToValue` | `map[string]int` | Maps label names (case-insensitive) to numeric values | | ||
| | `MultiLabelLogic` | `string` | How multiple matching labels are combined: `"max"` (default), `"sum"`, or `"first"` | | ||
| | `PriorityLabels` | `[]string` | Evaluation order when `MultiLabelLogic` is `"first"` | |
| | `ValidateLabelExists` | `func(label string) bool` | Reports whether a given label has a defined objective value | | ||
| | `GetAllLabels` | `func() []string` | Returns all labels defined in the mapping, sorted alphabetically | | ||
| | `MarshalJSON` | `func() ([]byte, error)` | Implements `json.Marshaler`; produces indented JSON output | | ||
| | `String` | `func() string` | Returns a human-readable summary: `ObjectiveMapping{labels: N, logic: X, priorities: M}` | |
|
|
||
| ### Constants | ||
|
|
||
| The package exports named constants for every label and its default value, grouped by priority tier: |
| |----------|-------|-------------| | ||
| | `MultiLabelLogicMax` | `"max"` | Use the highest matching label value (default) | | ||
| | `MultiLabelLogicSum` | `"sum"` | Sum all matching label values | | ||
| | `MultiLabelLogicFirst` | `"first"` | Use the first match in priority order | |
| score := om.ComputeObjectiveValue([]string{"bug", "high-priority"}) | ||
| // score == 60 (max of bug=60, high-priority=35) | ||
|
|
||
| // Check which labels contributed | ||
| objectiveLabels := om.GetObjectiveLabels([]string{"bug", "good first issue"}) | ||
| // objectiveLabels == ["bug"] |
|
|
||
| - All label comparisons are case-insensitive: labels are normalised with `strings.ToLower(strings.TrimSpace(...))` before lookup. | ||
| - The default `MultiLabelLogic` is `"max"`. Callers that do not set this field get max-value semantics automatically. | ||
| - `PriorityLabels` is only consulted when `MultiLabelLogic` is `"first"`; it establishes evaluation precedence among matching labels. |
pelikhan
deleted the
copilot/fix-9919-1036865607-3874a1f2-4cff-4998-ae64-d13398527155
branch
Addresses the 2026-06-12 spec-librarian audit: one missing spec and four incomplete specs across the package tree.
Changes
pkg/github/README.md(new) — Full spec forObjectiveMapping: type fields, all methods (ComputeObjectiveValue,GetObjectiveLabels,ValidateLabelExists,GetAllLabels,MarshalJSON,String), standalone functions (DefaultObjectiveMapping,LoadObjectiveMappingFromConfig), all exported constants grouped by priority tier,OBJECTIVE_MAPPING_JSON→ config file → defaults precedence chain, and dependencies.pkg/fileutil/README.md— Added missingEnsureParentDir(path string, perm os.FileMode) errorrow to the Public API functions table.pkg/constants/README.md— Added## Dependenciessection (stdlib only; no internal deps).pkg/timeutil/README.md— Added## Dependenciessection (stdlib only; no internal deps).pkg/tty/README.md— Added## Dependenciessection documenting thegolang.org/x/termexternal dependency.