feat(authoring): versioned manifest with pages, geometry, and stable flow identity - #83
Merged
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
feat(authoring): versioned manifest with pages, geometry, and stable flow identity
What changed
tmforge applywas not idempotent. Applying one manifest twice produced models thattmforge diffreported as 4 added / 4 removed flows, with 0 of 18 finding ids matching.Element ids were already derived from aliases; page and connector ids were minted fresh
with
Guid.NewGuid().Four slices, all on the manifest path:
flows[].alias; alias-less objects fall back to a structural key. Aliases and structuralkeys use separate GUID namespaces (
tmforge-alias:/tmforge-structural:) so theycannot collide, plus a post-build count guard.
schema/versionon the manifest, validated againstthe raw JSON before deserializing. Optional
x/y/width/heighton boundaries andelements, emitted by
export --geometry(opt-in).pages: [{alias, name}]pluspageon boundaries and elements.A flow may not cross pages; an unknown page reference is refused, not defaulted.
set --idandremove --idresolve a flow by its alias.Why
The finding id is
{ruleId}:{diagram}:{target}:{occurrence}, so an unstable page GUID movedevery finding, not just flow-targeted ones. That defeated ANA-001's stable identity, made
tmforge analysis diffreport 18 resolved + 18 introduced for a no-op re-apply, and orphanedthreat-register triage. Manifests are the reviewable authoring surface, so this is the path
where identity has to hold.
Behaviour changes reviewers should see
applynow rejects a document whoseschemais nottmforge-manifest. Anythingfeeding it other JSON will fail loudly instead of silently coercing.
AuthoringSupport.RekeyComponent/RekeyConnectornow throw when the id is absent(was a silent no-op, which hid a real multi-page bug). All call sites verified.
model; that is pre-existing and only measured here, and
--geometryis the way out.Recorded in
docs/cli-reference.mdand in theExtractoverload's<remarks>.