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

.github/workflows/pr.yml

@@ -739,7 +739,7 @@ jobs:
           OPENSYSML_KATEX: ${{ github.workspace }}/build/doc-pdf/katex/node_modules/.bin/katex
           OPENSYSML_DOT: ${{ github.workspace }}/build/doc-pdf/graphviz/bin/dot
           OPENSYSML_PLANTUML_JAR: ${{ github.workspace }}/build/doc-pdf/plantuml/plantuml-1.2026.8.jar
-        run: go test -count=1 -v -run Installed ./internal/doc/docpdf
+        run: go test -count=1 -v -run Installed ./internal/doc/docpdf ./tests/migrate
 
   vscode-extension:
     name: VS Code extension

changes/unreleased/docgen-table-figures-and-paragraph-order.fixed.md

@@ -0,0 +1,23 @@
+- **A migrated DocGen `Image` of a Cameo table embeds the table, not a listing of its view.** An
+  `Image` step (or a viewpoint-less view) drawing an instance table, generic table, matrix or
+  relation map diagram wrote a `Diagram` of the view rendered `asElementTable`, which a document
+  drew as an Element / Kind / Type / Declared-in dump of the view's members. The section now
+  holds a `Table` over the same `… Rows` query the table's standalone document uses — written
+  once, beside the view — captioned by the step's title, numbered among the tables, and the
+  report row says which query it is over. A table whose definition has no query form is refused
+  where the figure would be, with the reason, instead of drawn as the listing.
+- **A DocGen view conforming to no viewpoint shows what MDK's default behavior shows.** Such a
+  view wrote its documentation alone. It now follows `DocumentGenerator.parseView`: a view that
+  is itself a diagram shows its own figure; any other shows, after its documentation, each
+  diagram it exposes in order — a plain diagram as a figure, a table diagram as its table —
+  and nothing for an exposed element that is not a diagram, the report row naming what it drew
+  and what it left out. As in MDK, only a missing «Conform» means that: a view whose «Conform»
+  names no element is refused with the reason, and the «View» stereotype's `viewpoint` tag
+  chooses no method.
+- **Collaborator paragraphs stand where their anchors put them.** Every collaborator paragraph
+  followed the section's generated content. A paragraph with no `siblingId`/`parentId` now
+  precedes it, as Cameo prints it; one anchored to a generated figure
+  (`Containment_DiagramMainImage__<id>`) follows the figure, table or refusal the section drew
+  for that diagram, with its followers after it — after the section's only figure when the anchor
+  names no diagram of the model — and one whose anchor cannot be placed (another anchor kind, a
+  tag naming nothing, an ambiguous section) follows the content with the reason in its row.

docs/reference/sysml-v1-migration.md

@@ -560,7 +560,10 @@ whole number, an instance table naming no classifier, a matrix with no filter, a
 whose XML does not parse — with every fault stated at once. A refused table is an `unmapped`
 report row and a `not migrated` comment beside its view, which is still written; the rest of the
 model is unaffected. Presentation settings (`displayMode`, `showScopeAsRoot`, colors, widths,
-legend, `rowsOrder`…) draw the table and are dropped without a report row.
+legend, `rowsOrder`…) draw the table and are dropped without a report row. A [DocGen
+document](#docgen-documents) whose step draws the table's diagram embeds the same `Table` over
+the same `… Rows` query — the query is written once, beside the view — so the section and the
+standalone document render the same columns and cells.
 
 ### DocGen documents
 
@@ -575,8 +578,18 @@ DocGen prints it, with the view's own documentation as a `Paragraph` — the sam
 `view` carries as `doc`, tool HTML reduced to text — before its method's content, unless that
 comment is shown by one of the view's collaborator paragraphs, in which case it is written once, in
 that paragraph's place; a collaborator paragraph that cannot be shown (a malformed application) is
-refused as usual and does not hide the documentation. The tree is the one
-DocGen walks: every property of a view typed by a view is a section, and a view is entered
+refused as usual and does not hide the documentation. A view with no «Conform» gets
+DocGen's default behavior, that of MDK's
+[`DocumentGenerator.parseView`](https://github.com/Open-MBEE/mdk/blob/develop/src/main/java/org/openmbee/mdk/generator/DocumentGenerator.java)
+when the view has no viewpoint or method: a view that is itself a diagram shows its own figure, and any other shows,
+after its documentation, each diagram it exposes or imports in that order — an `Image` of a
+plain diagram, the `Table` of a table diagram — and nothing for an exposed element that is not
+a diagram; the view's report row says the default applied and what it showed. Only the
+«Conform» generalization decides, as it does in `parseView`: the «View» stereotype's `viewpoint`
+tag, which the «View» row above writes as a `satisfy`, names no method for the section. A view whose «Conform» names no element of the export is refused with that reason rather
+than given the default, and a view whose «Conform» names a viewpoint keeps its method's refusal
+when that method is malformed. The tree
+is the one DocGen walks: every property of a view typed by a view is a section, and a view is entered
 for its own sections only through a composite or shared property — a plain reference places
 the view as a section without its children, and the «Expose» dependencies of a property feed
 its view only when the property is composite.
@@ -630,10 +643,10 @@ section, in the activity's order:
 | `CollectionAndFilterGroup`, `StructuredQuery` | the group's chain, inlined |
 | `TableStructure` with `TableAttributeColumn` (`Name`, `Documentation`), `TablePropertyColumn` (a value property of the rows' definition, or a requirement's `Id`/`Text`), `TableExpressionColumn` naming a bare query property | `part table : Table { attribute redefines caption = …; calc rows : …; }` over `Project(properties, columns = (Column(…)))`, the built-in properties first (a built-in column behind a value property is moved ahead of it with the note) and a value property captioned like a built-in property as `<caption> 2`; a requirement's `Id` is its `shortName` and its `Text` its `documentation`, where the migration writes them; `includeDoc` adds `documentation`; a `MonteCarloAnalysis` statistic column (`N`, `Mean`, `Deviation`, `OutOfSpec`) reads the statistic the row's nested analysis records, as `Column(name = "N", expression = 'Monte Carlo'.runs)` and a sort on it as `OrderBy(property = "'Monte Carlo'.runs")`, when an instance the table lists records it — otherwise the column is omitted with the note saying so; a column beyond these — a property of a used project — is omitted with the note saying which, and a table with no writable column is refused. The caption is the table's title (`titles`, between `titlePrefix` and `titleSuffix`), and its `captions` text follows the table as a `Paragraph` unless `showCaptions` is false |
 | `BulletedList(orderedList, includeDoc)` | `part list : List { attribute redefines style = "number" / "bullet"; calc items : …; }`; `includeDoc` follows each item's name with its documentation |
-| `Paragraph(body)`; a «CollaboratorParagraph» reading the comment body | `part paragraph : Paragraph { attribute redefines text = "…"; }`, tool HTML reduced to text; a paragraph over the targets' documentation is `calc values : …` over `Project(properties = ("documentation"))` |
+| `Paragraph(body)`; a «CollaboratorParagraph» reading the comment body | `part paragraph : Paragraph { attribute redefines text = "…"; }`, tool HTML reduced to text; a paragraph over the targets' documentation is `calc values : …` over `Project(properties = ("documentation"))`. A collaborator paragraph stands where its `siblingId` (else `parentId`) tag puts it: one naming another paragraph of the view follows that paragraph; one with no tag comes, as Cameo prints it, before the content the method generates; one naming the generated figure of a diagram, `Containment_DiagramMainImage__<id>`, follows the figure or table the section drew for that diagram, or the refusal standing where it would have been. An anchor of that form naming no diagram of the model (Collaborator writes publish-time ids) is placed after the section's only figure when it draws exactly one and no other anchor is as unresolved, the row saying so; otherwise, and for an anchor of another kind (`Containment_<Kind>__…`) or a tag naming nothing, the paragraph follows the generated content and its row names the anchor and why |
 | a «CollaboratorImageParagraph» — a comment stereotyped MagicDraw «AttachedFile», or one carrying an `<img>` | `part 'image N' : Image { attribute redefines location = "images/<file>"; attribute redefines caption = "<comment text>"; attribute redefines alt = "<file>"; }`, and the attached bytes are written beside the notation under `images/`, as the base of the file name with the suffix the bytes' content type calls for — `figure.txt` holding PNG bytes is `images/figure.png` (an `http(s)` source names the URL instead and writes no file; the comment body is the caption and an empty one is allowed). The attachment is found in the archive by the `ATTACHED_FILE` extension's stream id, then the `file` tag name or an entry with that base name; an image no archive entry holds keeps its caption as a paragraph, noted, and a captionless one is **unmapped** — the note names the file. A server-relative `src` (a path the View Editor serves) resolves against `-image-base-url`; without it the paragraph keeps its text with the same note saying so. Writing the files requires `-o`; `images/` beside the model is the migration's, so a re-run replaces the files it wrote before as it replaces the model, and a file of another name there is left alone — a run never writes over the model it is writing, the input, or its `-migration-report`/`-migration-results` files |
 | an `Image` step over a diagram that draws nothing, whose note (the diagram's own comment) holds an `<img>` | `part image : Image { attribute redefines location = <resolved src>; attribute redefines caption = <the figure's title>; attribute redefines alt = <img alt>; }` instead of leaving the figure out — approximated, since layout and free symbols drop; a note that says more than the title follows as the caption paragraph; the note's image not in the archive and not resolved against `-image-base-url` leaves the figure out with the same hint |
-| `Image` | one `part diagram : Diagram { attribute redefines caption = "<title>"; ref redefines source = <its view>; }` per diagram the chain collected (see below), captioned by its `titles` entry (else the diagram's name) between `titlePrefix` and `titleSuffix`, its `captions` entry following as a `Paragraph` unless `showCaptions` is false. A diagram written as a graph view — an activity diagram as an `ActionFlowView`, a state machine diagram as a `StateTransitionView` — is drawn like any other; one whose view renders as textual notation (a sequence diagram, whose Interaction is written as a scenario and not as the occurrence parts a `SequenceView` draws; an activity or state machine diagram whose behavior is not written as a definition) is refused with the reason, since a document draws no text view. A diagram that shows nothing — its tool lists no element and its stream draws nothing, or free symbols only (a diagram of pasted pictures draws them, so its figure is written) — would be an empty figure, so no `Diagram` is written for it: the step is reported mapped (approximated when the archive cannot tell what it shows) with the reason, and its caption stays as a paragraph, as DocGen shows it. An `Image` whose chain holds no diagram is mapped as drawing nothing, the note saying what the chain held instead |
+| `Image` | one `part diagram : Diagram { attribute redefines caption = "<title>"; ref redefines source = <its view>; }` per diagram the chain collected (see below), captioned by its `titles` entry (else the diagram's name) between `titlePrefix` and `titleSuffix`, its `captions` entry following as a `Paragraph` unless `showCaptions` is false. A diagram that is a Cameo [table, matrix or relation map](#tables-matrices-and-relation-maps) is shown as DocGen shows it, as the table: `part table : Table { attribute redefines caption = "<title>"; calc rows : <its '… Rows' query>; }` over the query its definition already lowered, written once beside the view, never as a `Diagram` of the view rendered `asElementTable` (which a document would draw as a listing of the view's members); the step's row says the diagram is written as a Table over that query, and `-doc-number-figures` counts it among the tables. A table whose definition is refused (no query form) is refused in its place, the reason given, rather than drawn as that listing. A diagram written as a graph view — an activity diagram as an `ActionFlowView`, a state machine diagram as a `StateTransitionView` — is drawn like any other; one whose view renders as textual notation (a sequence diagram, whose Interaction is written as a scenario and not as the occurrence parts a `SequenceView` draws; an activity or state machine diagram whose behavior is not written as a definition) is refused with the reason, since a document draws no text view. A diagram that shows nothing — its tool lists no element and its stream draws nothing, or free symbols only (a diagram of pasted pictures draws them, so its figure is written) — would be an empty figure, so no `Diagram` is written for it: the step is reported mapped (approximated when the archive cannot tell what it shows) with the reason, and its caption stays as a paragraph, as DocGen shows it. An `Image` whose chain holds no diagram is mapped as drawing nothing, the note saying what the chain held instead |
 | `Dynamic View` | a nested `Section` with the called activity's title, lowered the same way; an activity that calls itself is refused, since a recursive section has no static spelling |
 
 The diagrams among the collected elements are no query's rows — a migrated diagram is a view —