fix(migrate): embed DocGen table images, default viewpoint-less views, place anchored paragraphs

[devin-ai-integration]

What and why

Three DocGen fidelity defects, measured by comparing our render of a Cameo project's Detailed Design Document with the Cameo-generated PDF. All three are generic DocGen semantics; none of the fixes is project-specific.

1. An Image of a Cameo table embedded the view, not the table. chain.image planned a Diagram of the view for every collected diagram, so a table diagram (whose view is rendered asElementTable) came out as an Element / Kind / Type / Declared-in listing of every member of the exposed package — 206 of the 343 pages of the sample document. The table definition itself had been lowered correctly to a … Rows query plus a standalone … Document, but the document never referenced it. Now a section that draws a diagram with a written table definition (m.tableOf / view.tables) holds a DocumentQueries::Table over that same query: the query is written once beside the definition's view, and tableFigure shares the body writer with the standalone Document (writeTable → tableDoc/tableFigure), so nothing is lowered twice. The caption is the step's titles when present, else the diagram's name; tables number among the tables, figures among the figures (-doc-number-figures already counted them apart). A definition with no query form is refused where the figure would stand, with the reason, instead of drawn as the listing — a listing of the view's elements is not the table. The step's report row says … is written as a Table over the query '…'.

2. A view conforming to no viewpoint printed only its documentation. planMethod returned when there was no method. MDK's DocumentGenerator.parseView applies a default instead: a view that is itself a diagram shows its own image; any other shows its documentation, then, for each element it exposes, in order, an image of a diagram (a table for a table diagram) and nothing for anything else. defaultView implements exactly that, sharing figure/tableFigure with the Image step and viewDocumentation for the text; the view's report row states that the default applied and what it drew and skipped. Only the absence of a «Conform» triggers it, as in parseView (which reads that relationship alone, not the «View» stereotype's viewpoint tag): the reader now sets DocGenView.ConformMalformed for a «Conform» whose general resolves to nothing, and such a view is refused with that reason rather than given default figures. Views conforming to a viewpoint whose method is malformed keep their refusal; child views that satisfy a viewpoint and expose nothing still print as empty headings.

3. Collaborator paragraphs were appended after the method's content whatever their anchors. sysmlv1.DocGenParagraph now carries Predecessor (the raw siblingId/parentId tag) and Anchor (Kind, Target) parsed from the Containment_<Kind>__<id> form, and migrate places them: a paragraph following nothing opens the section before the generated content, as Cameo prints it; one anchored to a DiagramMainImage follows the figure, table or refusal the section drew for that diagram (sectionPlan.figures marks where each diagram's figure ends, and insert moves the marks along); its followers come after it. When the anchor names no diagram of the model — the ids are Collaborator publish-time ids, which match no xmi:id in the sample project — and the section draws exactly one figure, the paragraph follows that figure and its row says so; when the anchor cannot be placed (another anchor kind, a tag naming nothing, a section drawing several figures with several unresolved anchors) the paragraph follows the content and its row says why. No anchor kind is guessed: only DiagramMainImage is placed, the rest are refused by name.

Intentional golden changes: in documents.golden.sysml the refusal comment of a malformed collaborator paragraph that follows nothing moves before the section's table, since a paragraph following nothing now precedes the generated content; and the Notes view, whose «Conform» names _vp_gone, now carries a refusal comment and its own unmapped report row (the note used to sit on the document's row).

The PDF-toolchain CI job now also runs ./tests/migrate, where the new fixture is rendered as PDF.

Specification basis

MDK DocGen: DocumentGenerator.parseView (Open-MBEE/mdk, src/main/java/org/openmbee/mdk/generator/DocumentGenerator.java) — the no-viewpoint default and the Image step's handling of table diagrams; MDK Collaborator paragraphs' siblingId/parentId anchors. The migration is not a spec-compliance surface; no row in docs/project/spec-compliance.md moves.

How it was verified

• New fixture tests/migrate/testdata/xmi/table_figures.xmi (a document whose view Images a generic table, a refused table, a viewpoint-less view exposing a table diagram, a plain diagram and a block with documentation, and collaborator paragraphs anchored before the content, on a DiagramMainImage, and on a refused figure) with tests/migrate/table_figures_test.go: the embedded Table shares the standalone Document's query, the refusal, the default view's order, the paragraph order, and HTML and PDF renders of the fixture document showing the table's columns and rows and no Element Kind Type Declared in header. internal/translate/xmi/sysmlv1/docgen_test.go covers the raw predecessor chain, the anchor classification and an unsupported anchor kind; internal/translate/migrate/paragraph_placement_internal_test.go covers grouping and the insertion arithmetic of the figure marks.
• go build ./... && go vet ./... && gofmt -l . && go test ./... clean; corpus gates with OPENSYSML_REQUIRE_TRAINING_CORPUS=1 OPENSYSML_REQUIRE_PILOT_CORPORA=1 OPENSYSML_REQUIRE_PSSM_SUITE=1 clean; OPENSYSML_REQUIRE_PDF_TOOLCHAIN=1 go test ./tests/migrate renders the fixture PDF.
• On a Cameo project of 48.7k elements with 103 documents (not in the repository), develop build vs this branch:
  • -validate: no errors on both. -compare-results … -seed 1: the results are identical line for line (the migration-results JSON is byte-identical; the only diagnostic lines that differ are pre-existing "Duplicate of inherited member name" warnings re-listing the sections' diagram N/table N members, 2978 → 2975).
  • -render-documents: 103 documents written on both.
  • The DDD PDF: 343 → 210 pages; pages carrying the Element Kind Type Declared in header 206 → 0. The 9 results/lookup sections print Table 3–Table 12 with the same columns and cell values as their standalone … Document renders (Post-Segment Exchange: 45 rows, tFinal 4962 / 5029 present, table rows byte-identical to the standalone document's). Section 3 prints Table 1. Table of L2 APS Requirements: Key and Table 2. … Driving between its paragraph and 3.1; 3.1/3.2 stay empty headings. 4.3.1.4 reads paragraph → Figure 4 → paragraph.
  • Anchored paragraphs: 75 carry a Containment_DiagramMainImage__<id> anchor whose id names no diagram of the model. 25 (in 24 sections) are placed after their section's only figure; 50 sit in 20 sections drawing 2–5 figures and follow the content, each row naming the anchor and the figure count. Zero paragraphs are placed by an exact diagram id, since the project carries none.
  • Migration report totals: mapped 33080 → 32952, approximated 11378 → 11506, unmapped 4253 → 4255, for 107 rows reworded by these fixes: 81 Image steps whose row now says which query the Table is over (mapped → approximated, since the table's own lowering carries column notes), plus 35 of the 216 rows of the Dump Diagram viewpoint's shared Image step re-verdicted the same way; 2 new rows for the default-view tables of the viewpoint-less section; the collaborator paragraphs' rows now carry their placement notes; 2 tables whose definition has no query form are now refused where the figure would be (mapped → unmapped).
• Out of scope, seen in the ledger: OCL/expression columns (->size(), .oclAsType(...)) and stereotype-tag columns are still omitted from the tables' columns with a note; a 19-column table overflows the landscape page in the PDF backend (the standalone document renders the same), which is a renderer layout matter separate from these fixes.

Before / after (develop build vs this branch)

Section 3 — Key and Driving Requirements (before: paragraph then empty subsections; after: Table 1 / Table 2 between them):

4.3.1.4 Use Case Activity (before: figure → paragraph → paragraph; after: paragraph → figure → paragraph):

4.3.1.5 Time to Execute (before: the element listing; after: Table 3 with the timing analysis rows):

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