Skip to content

Read a project store whole, and project it into a main page - #48

Merged
ww-mw merged 2 commits into
mainfrom
project-page-model
Sep 30, 2026
Merged

ww-mw merged 2 commits into
mainfrom
project-page-model

Conversation

@ww-mw

@ww-mw ww-mw commented Sep 30, 2026

Copy link
Copy Markdown
Member

A .prj is a marker file; everything about the project lives in the sibling resources/project/ store, read entirely by convention. This fixes five things that store says which were being read wrongly or not at all, adds the parts of a project that were never modelled, and projects all of it into the view model behind a project main page (rather than a table).

The five defects

Each made the viewer state something false about a real project.

What was wrong
Nested member paths A File entity's location is relative to its parent entity, not to the project root. Read verbatim, every file inside a folder reported a bare basename — utils/helper.m and a root-level helper.m produced the same row. 357 of monophonic_syntethizer's 372 members are nested.
Invented references A path folder, a working folder and a project→project reference are all spelled type="Reference"; only the collection they sit in separates them. A scan across every collection therefore invented references: monophonic_syntethizer has none and was reported as referencing three.
The project root on the path The root is on the MATLAB path, recorded as Ref="", and is normally the first folder MATLAB adds. Testing the Ref for truthiness dropped it from almost every project.
Two collections of one type A real project carries both location="Root" type="Files" (its members) and location="ALM" type="Files" (artifact tracking). Matching on type alone assigned the member list twice and let store order pick the winner — and the ALM collection holds no member files at all, only a DIR_SIGNIFIER, so losing that race meant zero members.
The distributed layout Not read at all. It carries no pointer documents: an entity's location and type are its filename.

On the reference fix, the collections whose meaning we model are skipped by name, rather than allow-listing the ones that hold references: that collection's spelling varies by release, and a missed spelling would silently drop real references, which is worse than the bug being fixed.

On distributed, both layouts now normalize to one Entity shape so every collection reader is layout-blind. A layout we cannot walk is reported through the warnings channel rather than guessed at — the readers would otherwise return a project that looks complete and is empty, the one outcome a user cannot tell apart from a fact about their project.

What was never modelled

Most of what a project actually is: entry points (shortcuts and the startup/shutdown files, including the run order the store encodes as a *Prev linked list and nothing else recovers), shortcut groups, the designated cache/codegen/startup locations, whether a label is MATLAB's or the project's own, and the declared metadata format.

The page

buildProjectPage projects all of it into a view model. A project is not a table: MATLAB opens no document tab for one, and the file tree a table would show is already in VS Code's Explorer. What is nowhere else is everything around the file list, so that is what a page shows. The grouping, the run-order split, the label usage counts and the coverage figure are facts about the store rather than presentation, so they are derived once here and are testable without a webview.

It lives beside the parser rather than in datamodel/display/ because moduleBoundaries.test.ts pins that folder to zero outbound edges, and a projection of ParsedProject needs its types.

Verification

Against two real stores, both now reading with no warnings:

monophonic_syntethizer soc_swhw
layout fixedPathV2, 1166 metadata docs distributed, 29 docs
members / labelled 372 / 197 7 / 5
path folders 88 (incl. the root) 3 (incl. the root)
hooks 1 startup, 2 shutdown in run order 1 shutdown
shortcuts 11, in 2 named groups 5, two of which target folders
references 0 (was 3, fabricated) 0

Those figures match the reviewed page mockup exactly. 4981 tests pass; npm run verify is clean.

A `.prj` is a marker file; everything about the project lives in the sibling
`resources/project/` store, read entirely by convention. Five things that store
says were being read wrongly or not at all, each of which made the viewer state
something false about a real project:

- A File entity's `location` is relative to its PARENT entity, not to the project
  root. Read verbatim, every file inside a folder reported a bare basename, so
  `utils/helper.m` and a root-level `helper.m` produced the same row. 357 of
  monophonic_syntethizer's 372 members are nested.
- A path folder, a working folder and a project->project reference are all spelled
  `type="Reference"`; only the collection they sit in separates them. A scan across
  every collection therefore INVENTED references — that project has none and was
  reported as referencing three. The collections whose meaning we model are now
  skipped by name, rather than allow-listing the ones that hold references, because
  that collection's spelling varies by release and a missed spelling would drop
  real references.
- The project root is on the MATLAB path, recorded as `Ref=""`, and is normally the
  first folder MATLAB adds. Testing the Ref for truthiness dropped it from almost
  every project.
- Two collections of one type can coexist: a real project carries both
  `location="Root" type="Files"` (its members) and `location="ALM" type="Files"`
  (artifact tracking). Matching on type alone assigned the member list twice and
  let store order pick the winner — and the ALM collection holds no member files at
  all, only a DIR_SIGNIFIER, so losing that race meant zero members.
- The `distributed` layout was not read at all. It carries no pointer documents:
  an entity's location and type are its filename. Both layouts now normalize to one
  entity shape, so every collection reader is layout-blind. A layout we cannot walk
  is reported instead of guessed at, since the readers would otherwise return a
  project that looks complete and empty.

Then the parts of a project that were never modelled, which are most of what a
project IS: entry points (shortcuts and the startup/shutdown files, including the
run order the store encodes as a `*Prev` linked list and nothing else recovers),
shortcut groups, the designated cache/codegen/startup locations, whether a label is
MATLAB's or the project's own, and the declared metadata format.

`buildProjectPage` projects all of it into the view model behind a project's main
page. A project is not a table: MATLAB opens no document tab for one, and the file
tree a table would show is already in the Explorer. What is nowhere else is
everything around the file list, so that is what a page shows. The grouping, the
run-order split, the label usage counts and the coverage figure are facts about the
store rather than presentation, so they are derived once here and testable without
a webview.

Verified against two real stores: monophonic_syntethizer (fixedPathV2, 1166
metadata documents) and soc_swhw (distributed), both now reading with no warnings.
A reference resolved to { id, name } — a UUID and a basename — which is
enough to label a row and not enough to open anything. The store's own
`Ref` is a path relative to this project's root (`../Lib/Lib.prj`), and
it was read, used to derive the basename, and then dropped.

That left the page's References section with nowhere to point: its
`path` field held the UUID, so a host offering a link would have offered
to open a path that cannot exist. Reference is now { id, name, path },
and a reference the store gave no path for reports '' so the page can
tell that it has nothing to link.
@ww-mw
ww-mw merged commit 32cc2cb into main Sep 30, 2026
1 check passed
@ww-mw
ww-mw deleted the project-page-model branch September 30, 2026 20:22
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