Skip to content

Export the FunctionElement catalog-rename carry, so a host that renames in the catalog itself can carry a function rename - #119

Merged
ww-mw merged 2 commits into
mainfrom
export-function-rename-catalog-carry
Oct 16, 2026
Merged

ww-mw merged 2 commits into
mainfrom
export-function-rename-catalog-carry

Conversation

@ww-mw

@ww-mw ww-mw commented Oct 16, 2026 •

Copy link
Copy Markdown
Member

A5 (C-052 sub-point): a FunctionElement rename also renames the System Composer interface dictionary's copy (p_Name / p_FunctionPrototype), through the existing catalog-rename code, in both formats.

Why vscode needs this

#109 implements A5 inside core. The session records each function rename beside the catalog, and both save writers (scJsonTextWithRenames, scXmlWithRenames) turn that record into edits. The VS Code extension never saves through the session:

  • Its text editor splices the open document.
  • Its binary editor zips the members itself.

Both editors carry a catalog rename into the document when the edit is made, using the barrel's scanScJsonText / scanScXml + scRenameEdits. Those know entry names only, and the gate in front of them (catalogRenameOf) passes only a rename of a top-level entry. So in vscode a FunctionElement rename updates the data part and leaves the catalog's p_Name f / y = f(u,v) as they were read. When the file is reopened, MATLAB's interface dictionary disagrees with the data part.

#109's body left this for a vscode follow-up because it needs a wider barrel. This PR widens it. The vscode half adds one gate and one branch per editor that call these exports.

What is exported

No new logic. These are the functions #109 built, made public:

Name What it is
scFunctionRenameEdits(text, fns, renames): ScTextEdit[] #109's private functionRenameEdits, renamed to the barrel's sc* spelling (beside scRenameEdits). Both save writers call it under the new name.
scanScJsonFunctions(text): ScFunction[] The functions of each service interface in a textual dictionary's whole JSON text.
scanScXmlFunctions(xml): ScFunction[] The same, in a binary dictionary's interfaceDictionary.xml member.
type ScFunction { interfaceName; name; nameSite: ScNameSite; prototypeSite: ScNameSite | null }
type CatalogFunctionRenames ReadonlyMap<string, ReadonlyMap<string, string>>. It was already exported from ScCatalog.ts, and is now on the barrel too.

ScNameSite and ScTextEdit, which these signatures reference, were already on the barrel.

The private // comments become doc comments. Two deviations from a word-for-word promotion, both because a hover shows each doc on its own:

  • The doc on scanScJsonFunctions spells out its opening "The same, ...".
  • ScFunction's fields get one-line docs.

The barrel's System Composer block gets one sentence, naming these as the way a host carries a function rename.

Not exported:

  • renameFunctionInCatalog / catalogFunctionRenames. They record renames since the read, keyed by the names in the file. vscode rewrites its document at every edit, so that record goes stale.
  • scXmlWithRenames / scJsonTextWithRenames. They return a whole text, and the text editor needs ranges for one WorkspaceEdit.

src/datamodel/parser/ScCatalog.ts and src/index.ts change, and dist/ is regenerated. Exactly 8 dist files change: ScCatalog and index, .js / .d.ts and their maps. A rebuild of unmodified main reproduced dist/ byte for byte, so these 8 files come from this change alone.

Tests

test/scCatalog.test.ts, a new describe('a host carries a function rename with the barrel') that imports through ../src/index.js, as the file's other tests do (6 tests):

  • Text (arch.sldd): the scan lists ServiceInterface's f and f1, and not f2, which was added without System Composer. Renaming f to compute gives exactly two edits, at the catalog's "p_Name" and "p_FunctionPrototype". The data part is left to the host's own splice. The result is byte-equal to scJsonTextWithRenames for the same rename.
  • Binary: the same, on functionElementRename.test.ts's catalog member (the example/dd1.sldd shape), copied rather than moved so that no existing test changes. The data interface named f and g's argument g stay as read. The result is byte-equal to scXmlWithRenames.
  • A catalog Prototype that cannot follow, in both formats: one that names another function, one with trailing text, and an empty one. p_Name still moves, and the Prototype keeps its text, as the save writes it.
  • Guards: no edits for an interface or a function the catalog does not list, a rename to the same name, a data interface spelled like the function, or a function argument. No functions are found in a catalog with no service interface, or in a dictionary with no catalog.
  • A carry made one rename at a time equals the save's one pass. This covers a chain, a rename back, a swap through a temporary name, and an interface already renamed in the text (keyed by its new name). The vscode half relies on this equivalence.

test/publicTypeSurface.test.ts gets 1 compiled consumer that names ScFunction, CatalogFunctionRenames, ScNameSite and ScTextEdit. vitest erases type-only imports, so only this test can catch a missing type export.

Fail-before: I ran the new tests against main's source. All 7 fail, and the 42 existing tests in those two files pass:

  • The 6 runtime tests fail with TypeError: scanScJsonFunctions is not a function (or scanScXmlFunctions).
  • The type-surface test fails with "has no exported member" for all 5 names.

A mutant that writes the Prototype even when it cannot follow fails exactly the "cannot follow" test.

No behaviour change: no existing test is modified. The test diffs add lines only, and publicTypeSurface does not enumerate exported names. #109's tests in functionElementRename.test.ts pass unchanged, which covers the renamed call sites.

Gate

npm run verify is green: typecheck, build, smoke, test, check:pack, check:leak and check:browser.

  • Tests: 238 files passed, 1 skipped; 7,929 tests passed, 26 skipped.
  • On main (b8c3f2b): 238 files passed, 1 skipped; 7,922 tests passed, 26 skipped. That is +7, the new tests.

Part of the maintainer's A5 ruling; the vscode half follows once this is tagged.

After review. 55b65f8 corrects two doc comments the API reviewer flagged as non-blocking: CatalogFunctionRenames now says how a host keys it (by the names its open text spells), not only how the session's record does; and scFunctionRenameEdits says its edits come in scan order, which applyScEdits sorts. Comments only; verify 7929 passed / 26 skipped; dist rebuilt.

ww-mw added 2 commits October 16, 2026 11:41
…name into the catalog

Maintainer ruling A5: a FunctionElement rename also renames the System
Composer interface dictionary's copy (p_Name / p_FunctionPrototype),
through the existing catalog-rename code, in both formats. #109 does
this in the session's save. vscode never saves through the session. Its
two editors carry a catalog rename into the open document when the edit
is made, using the barrel's scanScJsonText / scanScXml and scRenameEdits,
and the barrel had nothing for a function.

So the barrel now exports what #109 built, with no new logic:
- scFunctionRenameEdits(text, fns, renames): ScTextEdit[]. This is #109's
  private functionRenameEdits, renamed to the barrel's sc* spelling. Both
  save writers call it under the new name.
- scanScJsonFunctions(text) and scanScXmlFunctions(xml): ScFunction[].
- The types ScFunction and CatalogFunctionRenames. ScNameSite and
  ScTextEdit, which these signatures reference, were already exported.

The private // comments become doc comments. ScFunction's fields get
docs, and the JSON scanner's "The same, ..." is spelled out, because a
hover shows each doc on its own.

Tests: scCatalog.test.ts gets 6 barrel tests, covering both formats, a
catalog Prototype that cannot follow, the guards, and a carry made one
rename at a time that equals the save's one pass. publicTypeSurface.test.ts
gets 1 compiled consumer of the types. No existing test changes. dist/ is
regenerated.
…der the edits come in

CatalogFunctionRenames described only the session's own record, keyed by the names in the file
as read; a host that carries a rename into its open text keys by the names that text spells now,
and the doc now says both. scFunctionRenameEdits returns its edits in scan order rather than
ascending position, unlike scRenameEdits; applyScEdits sorts them, and the doc now says so.
Comments only: the emitted JavaScript differs in comments alone.
@ww-mw
ww-mw merged commit 56818c2 into main Oct 16, 2026
4 checks passed
@ww-mw
ww-mw deleted the export-function-rename-catalog-carry branch October 16, 2026 16:04
@ww-mw ww-mw mentioned this pull request Oct 16, 2026
ww-mw added a commit to mathworks/data-explorer-vscode that referenced this pull request Oct 16, 2026
data-explorer-core v1.39.0 (mathworks/data-explorer-core#119, released
in #120 there) exports scFunctionRenameEdits, scanScJsonFunctions,
scanScXmlFunctions and the ScFunction and CatalogFunctionRenames types
from its barrel, which the previous commit calls to carry a
FunctionElement rename into the System Composer catalog. The lockfile
changes only core's entries: the root dependency spec and
node_modules/data-explorer-core, now 1.39.0 resolved at
8e334082682eae7901cc07016f4fb90b3cdc7c73.
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