Skip to content

Read a project saved as a single XML file - #57

Merged
ww-mw merged 1 commit into
mainfrom
read-single-file-project
Oct 2, 2026
Merged

ww-mw merged 1 commit into
mainfrom
read-single-file-project

Conversation

@ww-mw

@ww-mw ww-mw commented Oct 2, 2026

Copy link
Copy Markdown
Member

matlab.project.convertDefinitionFiles(root, "SingleFile") collapses a project's whole content store into one resources/project/Project.xml whose root element is <project MetadataType="monolithic">. The reader indexed only documents rooted at <Info>, so that one document was dropped, the index came out empty, and a converted project reported "No readable project entries were found under resources/project/" and showed as empty — before any layout detection ran, so not even the "cannot read this format yet" message a user could act on.

It is a third layout, and it fits the two already here: the entity tree IS the element tree, where a tag is the entity's type, the Location attribute is its location, and the <Info> child is its def. So monolithicLayout joins fixedPathV2Layout and distributedLayout behind the same Layout seam, and all seven collection readers are unchanged.

Two things in it are not obvious:

  • <Info> means two things in this layout — every entity's def, AND the type of the entity holding the project's name — separated only by whether it carries a Location. Taking the first <Info> child blindly makes the name entity the def of <project> itself and loses the name.
  • An element with neither attributes nor children parses as the empty STRING rather than an object, which matters because a bare <DIR_SIGNIFIER/> is of that shape and DIR_SIGNIFIER is the only thing marking a member as a folder.

Which KIND of store it is is settled structurally, by the root element, before MetadataType is consulted at all: a monolithic store's manifest is the store, so there is no separate document to ask. A store declaring a layout we cannot walk is still reported rather than guessed at — which now includes one that declares monolithic and holds no such document.

Verification

Checked against MATLAB R2027a, which converts a project between these formats in place. The same 372-member project (89 folders, 197 labelled files, 88 path folders, 7 labels, 14 entry points, 2 groups, 3 working folders) written as SingleFile, FixedPathMultiFile and MultiFile parses to byte-identical results, format aside, with zero warnings and identical startup/shutdown run order.

That is the invariant the new parity test pins — three encodings of one project cannot disagree about what the project is — since the per-layout tests can all pass while the walkers disagree.

npm run verify: 5148 tests pass.

Note on the fourth format: DefinitionFiles.Toml removes resources/ and the .prj marker, leaving a root matlab.toml. There is no .prj for the extension to open, so it is out of scope here rather than fixed.

`matlab.project.convertDefinitionFiles(root, "SingleFile")` collapses a
project's whole content store into one `resources/project/Project.xml`
whose root element is `<project MetadataType="monolithic">`. The reader
indexed only documents rooted at `<Info>`, so that one document was
dropped, the index came out empty, and a converted project reported "No
readable project entries were found under resources/project/" and showed
as empty — before any layout detection ran, so not even the "cannot read
this format yet" message a user could act on.

It is a third layout, and it fits the two that were already here: the
entity tree IS the element tree, where a tag is the entity's type, the
`Location` attribute is its location, and the `<Info>` child is its def.
So `monolithicLayout` joins `fixedPathV2Layout` and `distributedLayout`
behind the same `Layout` seam and all seven collection readers are
unchanged.

Two things in it are not obvious. `<Info>` means two things in this
layout — every entity's def, AND the type of the entity holding the
project's name — separated only by whether it carries a `Location`, so
taking the first `<Info>` child blindly makes the name entity the def of
`<project>` itself and loses the name. And an element with neither
attributes nor children parses as the empty STRING rather than an object,
which matters because a bare `<DIR_SIGNIFIER/>` is of that shape and
`DIR_SIGNIFIER` is the only thing marking a member as a folder.

Which KIND of store it is is settled structurally, by the root element,
before `MetadataType` is consulted at all: a monolithic store's manifest
is the store, so there is no separate document to ask. A store declaring
a layout we cannot walk is still reported rather than guessed at, which
now includes one that declares `monolithic` and holds no such document.

Checked against MATLAB R2027a, which converts a project between these
formats in place: the same 372-member project written as SingleFile,
FixedPathMultiFile and MultiFile parses to byte-identical results,
`format` aside. That is the invariant the new parity test pins — three
encodings of one project cannot disagree about what the project is —
since the per-layout tests can all pass while the walkers disagree.
@ww-mw
ww-mw merged commit 8fcfd0d into main Oct 2, 2026
4 checks passed
@ww-mw
ww-mw deleted the read-single-file-project branch October 2, 2026 15:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant