Skip to content

Fix children count mismatch and enhance query entry labeling#50

Merged
Malcolmnixon merged 1 commit into
mainfrom
fix/describe-children-count-and-entry-labels
Jul 21, 2026
Merged

Fix children count mismatch and enhance query entry labeling#50
Malcolmnixon merged 1 commit into
mainfrom
fix/describe-children-count-and-entry-labels

Conversation

@Malcolmnixon

Copy link
Copy Markdown
Member

This pull request introduces significant improvements to the clarity and usability of Markdown output generated by the SysML2Tools Query subsystem. The most important changes ensure that the describe verb and other query verbs now provide a more accurate and user-friendly summary and entries section: the child count in summaries always matches the number of visible, named children, and each entries table (or its absence) is clearly labeled with a verb-specific bold-text label. This makes reports easier to read and interpret, especially when there are zero results. Several new tests and documentation updates accompany these changes to guarantee correctness and document the new behavior.

Markdown Output Improvements:

  • The entries table in Markdown output is now always preceded by a verb-specific bold-text label (e.g., **Children** for describe, **Uses** for uses), and when there are no entries, a verb-specific fallback message is shown (e.g., _No children._). This label is always plain bold text, never a Markdown heading, so the report remains in a single section. The dependencies verb remains an exception, using prose bullets without a label. [1] [2] [3] [4]

  • For verbs without a specific label mapping, a generic **Entries** label and _No entries._ fallback are used, ensuring future verbs render sensibly. [1] [2]

Summary and Child Count Accuracy:

  • The describe verb summary now reports a Children: N line where N is the count of visible, named children actually included in the entries table—never the raw count of AST child nodes. This prevents confusion when non-element children or hidden stdlib children are present but not listed. [1] [2] [3] [4]

Documentation and Requirements Updates:

  • Documentation and requirements files (.md, .yaml) have been updated to describe the new Markdown output format, child count semantics, and rationale for these changes. This includes new or revised requirement sections and scenario/test documentation. [1] [2] [3] [4] [5]

Test Coverage:

  • New and updated tests verify that the entries label and fallback messaging behave as expected for all verbs, that the label is always bold text (never a heading), and that the Children count matches the actual number of listed children. [1] [2] [3]

These changes collectively improve the clarity, correctness, and maintainability of query results, making them more intuitive for users and easier to embed in other documentation.

- QueryEngine.Describe now derives its 'Children: N' summary count from the
  same filtered entries list used to build the Entries table, so the count
  can never diverge from the number of rows actually shown (previously it
  counted every raw AST child node, including non-element comments/metadata
  annotations/imports that have no QualifiedName and are excluded from
  Entries).
- QueryResultRenderer.RenderMarkdown now precedes each verb's entries table
  (or its 'no entries' fallback) with a verb-specific bold-text label (e.g.
  **Children** for describe, **Uses** for uses), so an empty result reads as
  an unremarkable, expected outcome for that verb instead of an ambiguous,
  possibly-broken one. The label is always plain bold text, never an ATX
  heading, so the report stays within a single Markdown section regardless
  of the caller's requested heading depth.
- Added/updated unit and integration tests, design docs, reqstream
  requirements, and verification test-scenario write-ups.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@Malcolmnixon Malcolmnixon added the bug Something isn't working label Jul 21, 2026
@Malcolmnixon
Malcolmnixon merged commit 314e465 into main Jul 21, 2026
9 checks passed
@Malcolmnixon
Malcolmnixon deleted the fix/describe-children-count-and-entry-labels branch July 21, 2026 14:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant