list_components suggests refdes prefixes that it then returns no components for

[vzegnameta]

Summary

When list_components is called with a refdes prefix that matches nothing, the error message helpfully lists the prefixes the design does contain. That list is built from every component in the design, including DNS (Do Not Stuff) parts. The query itself, however, excludes DNS parts unless include_dns=true is passed.

As a result, the error message can recommend a prefix that returns nothing when you actually query it.

Reproduction

Take a design (Cadence .DSN in my case) with these two properties:

• every component under some prefix — call it AA — is marked DNS
• no component at all uses some other prefix — call it BB

Step 1 — query the prefix that genuinely does not exist:

list_components(design=<design>, type="BB")

→ {"error": "No components with prefix 'BB' found in design '<design>'.
             Available prefixes: [..., AA, ...]"}

AA is presented as an available prefix.

Step 2 — query AA, exactly as the tool just suggested:

list_components(design=<design>, type="AA")

→ {"components": []}

Empty. No error, no notes.

Step 3 — query AA again with DNS included:

list_components(design=<design>, type="AA", include_dns=true)

→ 7 components, each carrying "dns": true

The prefix does exist in the design. The tool knew that when it built the suggestion list in step 1. The default query path in step 2 filters those parts out.

Why this is a problem

There are two distinct defects here.

1. The suggestion is not actionable.

The reason to list available prefixes in an error is to tell the caller what to try next. A prefix that is DNS-only is guaranteed to come back empty at default settings, so the tool is pointing the caller at a dead end. Nothing in the error text distinguishes prefixes that will return components from prefixes that will not, so the caller cannot tell which of the offered suggestions are usable.

The inconsistency is entirely internal to the tool: one call says the prefix is present, the next call says it is absent, and both are the same tool reading the same design with the same default arguments.

2. "Nothing found" has two different response shapes, and the more misleading one is silent.

• Prefix absent from the design entirely → an error field, plus the prefix list.
• Prefix present but every part under it is DNS → a bare {"components": []} with no error and no notes.

A caller receiving the second shape has no way to distinguish "this design contains no components under this prefix" from "this design contains components under this prefix, but they are all DNS." The empty array reads as a definitive negative.

Those two conditions have opposite engineering meanings. A board with no test points at all and a board whose test points are all depopulated are very different boards, and this response cannot tell them apart.

The documented behavior for the tool states that if no components match, the error lists every prefix the design does have. That describes the first shape only. The second shape does not follow it, and it is the shape you hit whenever a prefix is DNS-only.

For contrast, search_components_by_refdes returns a notes field when its pattern matches nothing, so a caller at least receives an explicit statement that the search came back empty. list_components returns no such signal on the DNS-filtered path.

Impact

The failure is silent and directional: it produces a confident-looking negative rather than an error. An automated caller enumerating a design by walking the advertised prefix list will conclude that entire classes of parts are absent when they are in fact present but depopulated. Because no error is raised and no note is attached, there is nothing to detect downstream — the only way to catch it is manual reconciliation against the schematic or BOM.

This is most likely to bite on part classes that are commonly fitted as DNS/DNI by convention, which are exactly the classes an automated design review would want to reason about explicitly.