fix(ui): cap the suggestion list, because a real environment offers 94

Running it against `C:\Python314` — 352 packages, the scale fixture — the default
threshold of 5 qualifies **94 packages**. The ranking is right (setuptools at 150
dependents, then zope at 93, zope-interface at 86; it is a Plone environment and
those really are its workhorses) but a "Worth pinning" section with 94 rows is not a
suggestion, it is a second package list.

No unit test could have said this. The fixtures have six packages because that is
what proves the threshold logic; the usability of the result at scale is a property
of real dependency graphs.

**Raising the default would have been the wrong fix.** A deep tree is exactly where
a bulk update is most dangerous, so it is exactly where the feature has to work. The
screen shows the top 8 and says how many more qualify — `RUFF_ROWS_SHOWN`'s pattern,
including its rule that the count comes from the **full** list so a capped view never
misreports a total. `pins::suggest` is unchanged and still returns everything at or
above the threshold, which is what keeps it composable.

Measured in --release while there: probe **605 ms**, graph build plus the entire
suggest pass **1 ms**. The plan's worry about `dependent_count` being O(n·m) over 350
packages was unfounded — the subprocess dominates completely, and there is no case
for a batched counts method.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-08-14 20:19:28 +07:00
1 parent fc897ef569
commit 929cff898a
6 files changed
+69 -1

No files matched your search

+19
View File
@@ -781,6 +781,25 @@ called.**
| **UI** | The suggestion section on Pins, above the list; `useEnvStore.suggestions` keyed on its own `suggestionsFor`; the app's first `type="number"` in Settings. |
| **Docs** | UI-SPEC §4 (the section, and the Settings threshold), PRD P1-2 marked shipped. |
**The one thing only a real environment could say: 94 suggestions.**
Against `C:\Python314` — 352 packages, the scale fixture — the default threshold of 5 qualifies
**94 packages**, a quarter of the environment. The top of the list is right (`setuptools` at 150
dependents, then `zope` at 93, `zope-interface` at 86) but a "Worth pinning" section with 94 rows
is not a suggestion, it is a second package list.
Raising the default was the wrong fix: a deep dependency tree is exactly where a bulk update is
most dangerous, so it is exactly where the feature has to work. The screen shows the top
`SUGGESTIONS_SHOWN = 8` and says how many more qualify — the `RUFF_ROWS_SHOWN` pattern, and for
the same reason: the count comes from the **full** list, so a capped view never misreports a total.
`pins::suggest` still returns everything at or above the threshold, which is what makes it
composable.
Measured while there, in `--release`: the probe is **605 ms** and the graph build plus the whole
suggest pass is **1 ms**. The plan's worry that `dependent_count` looping over 350 packages would
be O(n·m) enough to matter was unfounded — the subprocess dominates completely, and there is no
case for a batched counts method.
**Three things the plan had wrong, all found by doing it.**
1. **A six-place checklist, not five.** `crates/pipdock-cli/tests/golden.rs` keeps its *own* copy of
+6
View File
@@ -103,6 +103,12 @@ having acted, and it is absent entirely when there is nothing to suggest. Accept
ordinary `Exclude` pin with the count as its reason (PRD P1-2's "suggest pin with reason"), which
the reason field below can then replace.
**It shows the top 8 and says how many more qualify.** Measured against the 352-package fixture,
the default threshold of 5 qualifies 94 — a quarter of the environment. Raising the default would
be the wrong fix, because a deep dependency tree is exactly where a bulk update is most dangerous;
the count in the "N more" line comes from the full list, so a capped view never misreports a total.
Same rule as `RUFF_ROWS_SHOWN` in the Health report.
It costs one `probe.py` run, and that is why it is here rather than on a sidebar badge: only
someone who opened this tab pays for it. It is also **silent on failure** — this screen's job is
listing pins and it does that either way, so an error row about an advisory would be the loudest
+2
View File
@@ -174,6 +174,8 @@
"suggestIntro": "These are depended on by a lot of what you have installed, so a bulk update is more likely to disturb something. Pinning keeps them out of Select all — you can still update them one at a time.",
"suggest_one": "{{pkg}} — {{count}} package depends on it.",
"suggest_other": "{{pkg}} — {{count}} packages depend on it.",
"suggestMore_one": "{{count}} more package would qualify. Pin some of these, or raise the count in Settings.",
"suggestMore_other": "{{count}} more packages would qualify. Pin some of these, or raise the count in Settings.",
"suggestAccept": "Pin",
"suggestAcceptFor": "Pin {{pkg}}",
"suggestReason_one": "{{count}} package depended on it",
+1
View File
@@ -166,6 +166,7 @@
"suggestTitle": "Nên cân nhắc ghim",
"suggestIntro": "Rất nhiều gói bạn đang cài phụ thuộc vào những gói này, nên một lần cập nhật hàng loạt dễ làm xáo trộn thứ gì đó. Ghim sẽ giữ chúng ngoài Chọn tất cả — bạn vẫn có thể cập nhật từng gói một.",
"suggest_other": "{{pkg}} — {{count}} gói phụ thuộc vào nó.",
"suggestMore_other": "Còn {{count}} gói nữa cũng đủ điều kiện. Hãy ghim bớt, hoặc nâng ngưỡng trong Cài đặt.",
"suggestAccept": "Ghim",
"suggestAcceptFor": "Ghim {{pkg}}",
"suggestReason_other": "{{count}} gói đã phụ thuộc vào nó"
+18
View File
@@ -186,6 +186,24 @@ describe('PdPins', () => {
expect(ipc.pinSuggestions).toHaveBeenCalledTimes(1)
})
it('caps the list and says how many it did not show', async () => {
// Found by running against the 352-package fixture: the default threshold of 5 qualifies 94
// packages there. A quarter of the environment is not a suggestion, it is a second package
// list — and the deep trees where that happens are exactly where the feature matters, so
// the answer is a bounded view, not a higher default.
withEnv()
vi.mocked(ipc.pinSuggestions).mockResolvedValue(
Array.from({ length: 94 }, (_, i) => ({ pkg: `pkg${i}`, dependents: 100 - i })),
)
render(<PdPins />)
await vi.waitFor(() => {
expect(screen.getByText(/86 more packages would qualify/)).toBeInTheDocument()
})
// The count is from the *full* list, so a capped view never misreports the total.
expect(screen.getAllByRole('button', { name: /^Pin pkg/ })).toHaveLength(8)
})
it('renders nothing at all when there is nothing to suggest', () => {
// An empty "Worth pinning" heading is a question nobody asked.
withEnv()
+23 -1
View File
@@ -30,6 +30,21 @@ import { PdPinChip } from '@/components/PdPinChip'
import { useEnvPackages } from '@/screens/useEnvPackages'
import { useEnvStore } from '@/stores'
/**
* How many suggestions to offer at once.
*
* **Measured, not guessed.** Against the 352-package scale fixture the default threshold of 5
* qualifies **94** packages — a quarter of the environment, which is not a suggestion but a second
* package list. Deep dependency trees are exactly where a bulk update is most dangerous and
* therefore exactly where this feature matters, so the answer cannot be "raise the default until
* the list is short".
*
* Bounded here rather than in `pins::suggest`, which correctly returns everything at or above the
* threshold: the count below is *from the full list*, so a capped view never misreports the total.
* The same rule `PdHealthReport`'s `RUFF_ROWS_SHOWN` follows, for the same reason.
*/
export const SUGGESTIONS_SHOWN = 8
export function PdPins() {
const { t } = useTranslation()
const selected = useEnvStore((s) => s.selected)
@@ -72,7 +87,7 @@ export function PdPins() {
</h2>
<p className="mt-1 max-w-2xl text-data text-text-dim">{t('pins.suggestIntro')}</p>
<ul className="mt-2 space-y-1">
{suggestions.map((s) => (
{suggestions.slice(0, SUGGESTIONS_SHOWN).map((s) => (
<li
key={s.pkg}
data-suggestion={s.pkg}
@@ -103,6 +118,13 @@ export function PdPins() {
</li>
))}
</ul>
{/* Never a silent cap. The number comes from the full list, so it is the honest total
rather than the length of what is rendered. */}
{suggestions.length > SUGGESTIONS_SHOWN ? (
<p className="mt-2 text-data text-text-dim">
{t('pins.suggestMore', { count: suggestions.length - SUGGESTIONS_SHOWN })}
</p>
) : null}
</section>
) : null}