feat(migrate): lower Cameo tables, matrices, relation maps and DocGen documents to DocumentQueries

[devin-ai-integration]

What and why

Cameo tables, matrices and relation maps are uml:Diagrams, so the migrator turned each into a view exposing whatever happened to be displayed and kept the table's definition — scope, row types, columns, sort, dependency criteria — only as a tool-profile comment. MDK DocGen documents (Document_Profile and Document_View_Collaborator_Profile applications) became comments plus stub action defs, so the documents were inert. Those definitions are semantic and have an exact target in this project's DocumentQueries vocabulary; this PR reads them in the XMI layer and lowers them to executable queries and renderable documents, so a migrated model answers -run-query and renders through -render-document.

Tables, matrices, relation maps (recognised only by the exact profile URIs MagicDrawProfile, Dependency_Matrix_Profile.xmi, and by the MagicDraw module snapshots bundled in the archive; a user stereotype merely named InstanceTable or TableStructure elsewhere stays ordinary metadata). Each definition on a diagram is written beside the diagram's view, in the diagram's owning namespace:

calc def 'Pump Table Rows' :> DocumentQueries::Query {
    DocumentQueries::Project(
        source = DocumentQueries::OrderBy(
            source = DocumentQueries::WhereFeature(
                source = DocumentQueries::WhereType(
                    source = DocumentQueries::Union(
                        source = DocumentQueries::Descendants(
                            source = DocumentQueries::Named(qualifiedName = ("Plant::Inventory"))),
                        other = DocumentQueries::Named(qualifiedName = ("Plant::Spares::s1", "Plant::Spares::s2"))),
                    type = ("Plant::Structure::Pump")),
                'feature' = "isIndividual", operator = "=", value = "true"),
            property = "mass", direction = "descending", missing = "last", multiple = "first"),
        properties = ("name"),
        columns = (DocumentQueries::Column(name = "mass", expression = Plant::Structure::Pump::mass ?? "")))
}
part def 'Pump Table Document' :> DocumentQueries::Document {
    attribute redefines title = "Pump Table";
    part rows : DocumentQueries::Table {
        attribute redefines caption = "Pump Table";
        calc rows : 'Pump Table Rows';
    }
}

• «InstanceTable» / «DiagramTable»: scope → Descendants(Named(roots)) (a whole-model scope lists the migrated top-level roots); explicit rows → one Union(source = …, other = Named(qualifiedName = (row1, row2, …))); row type → WhereType (+ WhereFeature(isIndividual) for instance tables) or WhereMetadata for a user stereotype the migrator writes as a metadata def; columns → Project(properties) and Column(expression = T::p ?? ""); sort → OrderBy(missing = "last", multiple = "first").
• «DependencyMatrix» + «MatrixFilter»: rows as above, one RelatedColumn(relationshipKind, direction, maxDepth = 1, aggregate = "list", targets = <column query>) per criterion; "With relations" → WhereRelated; Both → two related columns, approximated and reported; same-named criteria are made unique (Trace, Trace 2).
• «RelationMap»: RelatedElements(source = Named(context), relationshipKind, direction, maxDepth = depth) per criterion, unioned and type-filtered.
• Properties a generated Column reads are kept reachable (not written private), the same way a view's exposed features are.
• Presentation-only attributes are dropped silently. A criterion no relationship kind spells, a column on a derived or tool property, QPROPs beyond name/documentation/qualifiedName/owner/id, sort by tool id, malformed dependencyCriteria XML, a non-integer depth, an unparsable sort, a dangling scope, and a table naming no row type are refused with an Unmapped report row quoting the construct and every fault; the view is still written.

DocGen documents (exact URIs Document_Profile.xmi, Document_View_Collaborator_Profile.xmi). A «Document» class becomes part def '<Name> Document' :> DocumentQueries::Document; its view tree becomes nested Sections in declaration order; each view's «Conform»ed method activity is walked from its initial node along control flow, with the «Expose» suppliers as the root:

• CollectOwnedElements → Descendants, CollectOwners → Ancestors, CollectByDirectedRelationshipStereotypes → RelatedElements, FilterByMetaclasses → WhereType, FilterByStereotypes → WhereType/WhereMetadata, FilterByNames → WhereName(matches), include = false → Except, SortByName/SortByAttribute → OrderBy, Union/Intersection/XOR forks, CollectionAndFilterGroup and StructuredQuery inlined; depth = 0 → unbounded.
• TableStructure → Table, BulletedList → List, Paragraph/collaborator paragraphs → Paragraph (literal text, or calc values : <query> when the paragraph reads its targets' documentation), Image → view-backed Diagram, Dynamic View → nested Section. A table's or image's caption attribute is its DocGen title (titles between titlePrefix/titleSuffix, the diagram's name by default); its captions text follows as a Paragraph only while showCaptions holds.
• A Diagram block's source must be an accessible feature: a view held by a definition is reached through a ref <anchor> : <Def>; the Document declares, and a view nested under another view through the usage chain from its package (ref redefines source = truck.'Truck Internals';).
• Generated member names never collide with the members inherited from DocumentQueries (title, rows, items, values, source, …), and references written inside a generated block are qualified past any synthesized member that would shadow them.
• Refused with the construct quoted, the surrounding sections still written: CollectTypes, CollectByAssociation, OCL/expression steps beyond a bare feature read, user scripts, Parallel joined by anything but a set operation, a recursive dynamic view, a viewpoint naming no method, a collaborator paragraph naming no view, an Image of a diagram rendered as textual notation, a view under a namespace no feature chain reaches.

Library extensions to DocumentQueries (spelling gaps only): maxDepth on Descendants/Ancestors/RelatedElements/WhereRelated/RelatedColumn may be omitted or null for no bound (before, maxDepth <= 0 silently returned nothing); RelatedColumn.targets : Element[0..*] ordered keeps only related elements a second query lists (a matrix cell); the built-in query property isIndividual; and Named(qualifiedName : String[1..*]) resolving elements by qualified name so a package or definition can be a query root (packages and definitions are not valid feature values). In the executor, a declared satisfy/verify assertion typed by a requirement definition now relates its subject to that definition as well as to the anonymous assertion usage — otherwise every migrated matrix over requirement definitions (satisfy requirement : R; is how a v1 «Satisfy» migrates) had empty cells.

«typeModifier»: [] on a property or parameter with no collection multiplicity → [0..*] ordered nonunique, [n] → [n] ordered nonunique, */& on a part or item property → ref; two-dimensional shapes, [] on an existing collection and */& on an attribute or parameter stay comments with the reason reported.

Existing diagram behaviour is unchanged: the view with its expose set, render, and the MTIP DiagramLayout::Canvas/Layout/Route annotations are written as before; the Table Document is a sibling.

Specification basis

Non-normative: the target vocabulary is this project's DocumentQueries library (docs/manual/query-cookbook.md); the source semantics are Cameo's MagicDraw and Dependency Matrix profiles and the Open-MBEE MDK DocGen profile (CollectFilterParser, Utils in the public mdk repository: depth = 0 is unbounded, CollectOwnedElements excludes the source, FilterByNames is a full-match regex, every step deduplicates). No row of docs/project/spec-compliance.md moves.

How it was verified

• gofmt -l . empty; go build ./...; go vet ./...; staticcheck clean; go test -count=1 ./... green with OPENSYSML_REQUIRE_PILOT_CORPORA, OPENSYSML_REQUIRE_TRAINING_CORPUS, OPENSYSML_REQUIRE_PILOT_LIBRARY_XMI and OPENSYSML_REQUIRE_PSSM_SUITE set (training corpus assertion, pilot corpora, PSSM migration and RDF round-trip ratchets unmoved). python3 scripts/changelog.py check and scripts/check-doc-ids.py pass.
• New fixtures under tests/migrate/testdata/xmi/ with validated goldens (notation + report): tables (instance table with explicit rows and sorts, generic table, whole-model scope, metadata-filtered rows, dependency matrix with duplicate criteria and Both, relation map), documents (DocGen sections, literal and query-backed paragraphs, lists, tables, image diagrams including a view held by a part definition and a view nested in a view, hidden captions (showCaptions="false"), refusals, malformed collaborator, recursive dynamic view), table_homonyms (user InstanceTable/TableStructure stereotypes on non-profile URIs stay metadata; malformed table serialization refused with the exact faults), type_modifiers, and a table diagram with a HUDS layout record pinning Canvas/Layout and the Table Document on one view. TestMigratedNotationAnalysesClean validates every golden with no errors.
• Executable and renderable: TestMigratedTablesExecute, TestMigratedTablesRender, TestMigratedDocumentsRender and TestTableHomonymsAndMalformedTables (tests/migrate/documents_test.go) run every generated Rows query through the real executor with row assertions, and render the migrated Documents through the real Markdown and HTML backends (headings, captions, cells, list items, five Mermaid diagrams in order, hidden captions absent). Unit tests for Named, nullable maxDepth, RelatedColumn.targets, isIndividual, the requirement-definition edge, the DocGen planner (cycles, refusals, image paragraphs) and the XMI readers.
• Leakage audit: rg over internal/, docs/, changes/ for tool-internal identifiers, profile ids and work-item labels in reader-facing text — none.
• Docs: docs/reference/sysml-v1-migration.md (tables, matrices, relation maps, DocGen, typeModifier, the refused list) and docs/manual/query-cookbook.md (Named, unbounded maxDepth, RelatedColumn.targets, isIndividual, with a checked cookbook example).

Real-model before/after (TMT-2024x.mdzip with -layout TMT_mtip.xml, this branch vs. develop at its merge base):

	develop	this branch
elements migrated	48,296 (32,360 mapped, 11,350 approximated, 4,586 unmapped)	49,060 (32,857 mapped, 11,458 approximated, 4,745 unmapped)
DocumentQueries::Query definitions / Document definitions	0 / 0	99 / 103 (98 Table, 101 Diagram, 769 Section blocks)
max generated query call depth (histogram)	—	7 ({2: 2, 3: 7, 4: 19, 5: 48, 6: 20, 7: 3})
layout join	721 records, 721 joined, 0 unmatched; 4,196 of 10,374 placements written (6,020 not exposed, 158 resolving to no element); 9 of 4,792 routes (4,783 not exposed, 0 dangling); 0 malformed; 481 Canvas annotations	identical
results sidecar (-migration-results)	62 run configurations measured, 41 of them requested/behaviour-bearing (behavior = run), 30 with 82 stored snapshots standing for 4,158 runs	byte-identical (cmp)
migration wall / RSS	14.9 s / 673 MB	15.6 s / 626 MB
-validate on the full output	0 errors, 3,550 warnings, 10.2 s	0 errors, 3,851 warnings, 10.5 s

The 301 additional warnings are all Duplicate of inherited member name for the generated Documents' title/rows/caption/section members, the same warning class develop already reports 2,658 times for the model's own view hierarchy. The new unmapped rows are the refused table criteria and DocGen steps listed above, each with its construct quoted. Explicit table rows are written as one list-valued Union, keeping call depth at 7 across every generated query; validation of nested calc invocations in the checker is unchanged by this PR.

Checklist

• make test and make lint pass locally
• Tests added or updated for the change
• Documentation extended where it already covers the surface (see CONTRIBUTING.md)
• Changelog entry added as changes/unreleased/<slug>.<section>.md, not as an edit to CHANGELOG.md
• baselines regenerated and make docs-counts run if a gate count moved (compliance rows need nothing: the census is counted at docs build)
• No internal work-item labels (waves, slices, F4, K5) in the body, docs, or changelog

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[devin-ai-integration]

Devin Review found 2 new potential issues.

6 flags not posted on this PR by your GitHub settings — view them in Devin Review. (Configure)