@memoarchitect/tools 0.11.2 → 0.12.0

package/packages/tools/lib/server/dev-server.js

@@ -20,6 +20,7 @@ import { assertSingleDomainMutation, MixedMutationDomainError } from './mutation
 import { classifyConflict } from './conflict-policy.js';
 import { checkRulePolicy, insertRulePolicy, renderRulePolicy } from './rule-policy-writer.js';
 import { loadViewLayouts, saveViewLayout } from './view-layout-store.js';
+import { updateViewExpose, writeViewDeclaration } from './view-writer.js';
 import { usageKeyword } from '../model/semantic.js';
 import { loadDhfDocs, saveDhfDoc, deleteDhfDoc, loadDhfSettings, saveDhfSettings, listRepoTemplates, readRepoTemplate, saveRepoTemplate, } from './dhf-doc-store.js';
 const MODEL_MUTATION_MESSAGES = new Set([
@@ -92,7 +93,30 @@ function streamFile(res, fullPath, status = 200) {
     res.writeHead(status, { 'Content-Type': mime, 'Content-Length': size });
     createReadStream(fullPath).pipe(res);
 }
-/** Resolve only project-owned screen captures under model/assets. */
+/**
+ * The subtrees a project's screen captures may be served from.
+ *
+ * `model/assets` is where MEMO put them back when the whole model lived under
+ * `model/`. A project laid out with its source in `src/` has no `model/`
+ * directory at all and keeps its captures in `assets/` beside it — and those
+ * were unreachable, so its UI Screens workspace drew every region over a
+ * blank backdrop with no error to explain it. The request simply fell through
+ * to the SPA and the `<img>` got an HTML document back.
+ *
+ * Naming roots at all is the allow-list, and that part is not negotiable:
+ * this server hands project files to a browser, so it serves these two
+ * subtrees and nothing else — not `.env`, not `.git/`, not the source.
+ */
+const CAPTURE_ROOTS = ['model/assets', 'assets'];
+/** True when `candidate` is a real descendant of `root` — the traversal guard. */
+function isWithinRoot(root, candidate) {
+    const fromRoot = relative(root, candidate);
+    return Boolean(fromRoot)
+        && fromRoot !== '..'
+        && !fromRoot.startsWith('../')
+        && !fromRoot.startsWith('..\\');
+}
+/** Resolve only project-owned screen captures, under either capture root. */
 export function resolveProjectAssetRequest(projectRoot, requestUrl) {
     let pathname;
     try {
@@ -101,15 +125,45 @@ export function resolveProjectAssetRequest(projectRoot, requestUrl) {
     catch {
         return undefined;
     }
-    if (!pathname.startsWith('/model/'))
+    if (!pathname.startsWith('/model/') && !pathname.startsWith('/assets/'))
         return undefined;
-    const assetRoot = resolve(projectRoot, 'model', 'assets');
     const requested = resolve(projectRoot, pathname.replace(/^\//, ''));
-    const fromAssetRoot = relative(assetRoot, requested);
-    if (!fromAssetRoot || fromAssetRoot === '..' || fromAssetRoot.startsWith('../') || fromAssetRoot.startsWith('..\\')) {
-        return undefined;
+    const within = CAPTURE_ROOTS.some(root => isWithinRoot(resolve(projectRoot, root), requested));
+    return within ? requested : undefined;
+}
+/**
+ * Report views that share an id.
+ *
+ * Kind collisions are already recorded this way (`KindNameCollision`) for the
+ * same reason: a `Map` keyed by a name silently keeps one writer, and which one
+ * survives then depends on file iteration order. A view is looked up by id from
+ * the URL, from the explorer and from every permalink, so a collision does not
+ * make views ambiguous — it makes the shadowed ones unreachable.
+ */
+function reportDuplicateViewIds(diagrams) {
+    const byId = new Map();
+    for (const diagram of diagrams) {
+        const list = byId.get(diagram.id);
+        if (list)
+            list.push(diagram);
+        else
+            byId.set(diagram.id, [diagram]);
+    }
+    const collisions = [...byId.values()].filter(group => group.length > 1);
+    if (collisions.length === 0)
+        return;
+    const shadowed = collisions.reduce((sum, group) => sum + group.length - 1, 0);
+    console.error(`[Views] ${shadowed} view(s) are UNREACHABLE: ${collisions.length} id(s) are `
+        + 'declared by more than one view, and a view is addressed by its id. '
+        + 'Give each view its own `providedId`:');
+    for (const group of collisions) {
+        const reachable = group[0].shortId ?? group[0].name ?? group[0].id;
+        console.error(`  - ${group[0].id} is claimed by ${group.length} views; only ${reachable} can be opened`);
+        for (const shadow of group.slice(1)) {
+            console.error(`      shadowed: ${shadow.shortId ?? shadow.name ?? shadow.id}`
+                + `${shadow.sourceFile ? `  (${shadow.sourceFile})` : ''}`);
+        }
     }
-    return requested;
 }
 export async function createDevServer(options) {
     const { port, webPackagePath, initialMessages, transformClientHtml } = options;
@@ -219,10 +273,19 @@ export async function createDevServer(options) {
     /** Serve captures referenced by project-relative ScreenCapture.imageUri. */
     function serveProjectAsset(req, res) {
         const requestUrl = req.url ?? '/';
-        if (!requestUrl.split('?')[0].startsWith('/model/'))
+        const pathname = requestUrl.split('?')[0];
+        if (!pathname.startsWith('/model/') && !pathname.startsWith('/assets/'))
             return false;
         const requested = resolveProjectAssetRequest(options.projectRoot, requestUrl);
-        if (!requested || !existsSync(requested) || !statSync(requested).isFile()) {
+        const owned = Boolean(requested) && existsSync(requested) && statSync(requested).isFile();
+        if (!owned) {
+            // `/assets/` is ALSO where the client's own hashed bundles live,
+            // and this handler runs before the web dist. Claiming every
+            // `/assets/` request would 404 the application's own JavaScript,
+            // so an unclaimed one falls through; `/model/` is unambiguous and
+            // still reports a missing capture as a missing capture.
+            if (pathname.startsWith('/assets/'))
+                return false;
             res.writeHead(404);
             res.end('Capture not found');
             return true;
@@ -321,20 +384,39 @@ export async function createDevServer(options) {
     const { WebSocketServer } = await import('ws');
     const wss = new WebSocketServer({ server });
     const clients = new Set();
-    // User-created views are project state, not session state. Merge them into
-    // the initial model payload so a UI screen created from the workbench is
-    // still present after the dev server restarts.
-    const initialModelIndex = initialMessages.findIndex(message => message.type === 'model:update');
-    if (initialModelIndex >= 0) {
-        const initialModel = initialMessages[initialModelIndex];
-        const authored = initialModel.payload.diagrams ?? [];
-        const authoredIds = new Set(authored.map(diagram => diagram.id));
-        const userDiagrams = loadUserDiagrams(options.projectRoot).filter(diagram => !authoredIds.has(diagram.id));
-        initialMessages[initialModelIndex] = {
-            type: 'model:update',
-            payload: { ...initialModel.payload, diagrams: [...authored, ...userDiagrams] },
-        };
+    // Every view is DECLARED in SysML — see `view-writer.ts`. The sidecar at
+    // .memo/user-diagrams.json used to be merged in here as a second class of
+    // view, which is how a view could exist for Architect and for nothing else:
+    // no source file, so invisible to `memo validate`, to `syside check`, to
+    // review, and — wherever `.memo/` is ignored — to git.
+    //
+    // Rows left in that file are therefore not views but UNDECLARED views: an
+    // error to be fixed by declaring them, not a state to render. They are
+    // reported by id and not merged. The file is never rewritten or deleted
+    // here — those rows are the only record of what still needs declaring.
+    const undeclared = loadUserDiagrams(options.projectRoot);
+    if (undeclared.length > 0) {
+        const initialModel = initialMessages.find(m => m.type === 'model:update');
+        const declaredIds = new Set((initialModel?.payload.diagrams ?? []).map(diagram => diagram.id));
+        const orphans = undeclared.filter(diagram => !declaredIds.has(diagram.id));
+        if (orphans.length > 0) {
+            console.error(`[Views] ${orphans.length} view(s) in .memo/user-diagrams.json have no SysML declaration `
+                + 'and were NOT loaded. Declare each as a `view … { }` in source, then delete its row:');
+            for (const orphan of orphans) {
+                console.error(`  - ${orphan.id}  ${orphan.name ?? ''} (${orphan.viewKind ?? 'unknown kind'})`);
+            }
+        }
     }
+    // A view is addressed by its id, so two views sharing one is not a
+    // duplicate label — it is one view the product can never open. Every lookup
+    // returns whichever loaded first and the rest are shadowed silently, with
+    // no error anywhere, which is the worst way for a model to be wrong.
+    //
+    // Found in affera as 11 of 95 views unreachable: ten clinical-step views
+    // all declaring VIEW-AFR-OP-SOS-004, and a CIU interconnect view claiming
+    // the id of the CIU decomposition view, so opening it showed the other.
+    reportDuplicateViewIds(initialMessages.find(m => m.type === 'model:update')
+        ?.payload.diagrams ?? []);
     const currentDiagrams = () => {
         const model = initialMessages.find(m => m.type === 'model:update');
         return model?.payload.diagrams ?? [];
@@ -918,8 +1000,10 @@ export async function createDevServer(options) {
                 if (existsSync(path))
                     recordWriteTransaction(sourceFile, readFileSync(path, 'utf8'));
             }
-            // User-authored diagrams are sidecars rather than semantic
-            // relationships, but they must not retain a stale element ID.
+            // The only rows left in the sidecar are UNDECLARED views awaiting
+            // migration; none is loaded as a view. They are still kept accurate,
+            // because they are the record of what needs declaring and a dangling
+            // element ID would carry straight into the declaration.
             const diagrams = loadUserDiagrams(options.projectRoot);
             let changed = false;
             const cleaned = diagrams.map(diagram => {
@@ -1254,10 +1338,17 @@ export async function createDevServer(options) {
                         const safeStem = rawStem
                             .normalize('NFKD').replace(/[^a-zA-Z0-9_-]+/g, '-').replace(/^-+|-+$/g, '')
                             || 'capture';
-                        const assetDir = resolve(options.projectRoot, 'model', 'assets', safeView);
+                        // Write into the layout the project actually uses. Creating
+                        // `model/` under a project whose source lives in `src/`
+                        // resurrects a directory that layout deliberately does not
+                        // have, and the capture would then sit outside the tree the
+                        // rest of the model is kept in.
+                        const captureRoot = existsSync(resolve(options.projectRoot, 'model'))
+                            ? resolve(options.projectRoot, 'model', 'assets')
+                            : resolve(options.projectRoot, 'assets');
+                        const assetDir = resolve(captureRoot, safeView);
                         const assetPath = resolve(assetDir, `${safeStem}${extension}`);
-                        const modelRoot = resolve(options.projectRoot, 'model');
-                        if (relative(modelRoot, assetPath).startsWith('..'))
+                        if (!isWithinRoot(captureRoot, assetPath))
                             throw new Error('Invalid capture path.');
                         mkdirSync(assetDir, { recursive: true });
                         writeFileSync(assetPath, bytes);
@@ -1276,29 +1367,60 @@ export async function createDevServer(options) {
                 else if (msg.type === 'diagram:create') {
                     const { projectRoot } = options;
                     const diagram = { ...msg.payload, auto: false };
-                    const userDiagrams = loadUserDiagrams(projectRoot);
-                    userDiagrams.push(diagram);
-                    saveUserDiagrams(projectRoot, userDiagrams);
-                    broadcastDiagramChange(diagram, 'create');
-                    console.log(`[Diagram] Created: ${diagram.name} (${diagram.id})`);
+                    // A view is model content, so it is DECLARED, not recorded in
+                    // a sidecar. Writing the SysML puts it where `memo validate`,
+                    // `syside check`, review and git can all see it, and — the
+                    // derived diagram then carrying a `sourceFile` — takes its
+                    // `.viewlayout` companion out of the hidden store too.
+                    const declared = await writeViewDeclaration(projectRoot, currentModel() ?? { elements: {}, diagrams: [] }, diagram);
+                    if (!declared.success) {
+                        // No fallback. A view that cannot be declared is not one
+                        // this project can hold, and recording it in a sidecar
+                        // would only hide that until something downstream needed
+                        // the declaration.
+                        const error = `The view "${diagram.name}" was not created: ${declared.reason}. `
+                            + 'Every view must be declared in SysML.';
+                        console.error(`[Diagram] REFUSED: ${error}`);
+                        ws.send(JSON.stringify({ type: 'app:error', payload: { requestId: msg.payload?.requestId, error } }));
+                        return;
+                    }
+                    console.log(`[Diagram] Declared: ${diagram.name} (${diagram.id}) as ${declared.identifier} in ${declared.filePath}`);
+                    // The file watcher recompiles and `view-deriver` emits the
+                    // diagram; no broadcast here, or clients would briefly hold
+                    // a second, sidecar-shaped copy of it.
+                    await recompileAfterWrite();
                 }
                 else if (msg.type === 'diagram:update') {
+                    // What a view shows lives in its `expose` members, not in a
+                    // list of ids in a sidecar, so the update is applied to the
+                    // declaration. This used to edit the sidecar, which meant
+                    // that for a DECLARED view it silently did nothing at all.
                     const { projectRoot } = options;
-                    const userDiagrams = loadUserDiagrams(projectRoot);
-                    const idx = userDiagrams.findIndex(d => d.id === msg.payload.id);
-                    if (idx >= 0) {
-                        userDiagrams[idx] = { ...userDiagrams[idx], ...msg.payload };
-                        saveUserDiagrams(projectRoot, userDiagrams);
-                        broadcastDiagramChange(userDiagrams[idx], 'update');
+                    const declared = currentDiagrams().find(d => d.id === msg.payload?.id);
+                    const result = declared
+                        ? await updateViewExpose(projectRoot, currentModel() ?? { elements: {} }, declared, msg.payload?.elementIds)
+                        : { success: false, reason: `no view "${msg.payload?.id}" is declared` };
+                    if (result.success) {
+                        console.log(`[Diagram] Exposed ${result.exposed.join(', ')} on ${declared.name} (${result.filePath})`);
+                        await recompileAfterWrite();
+                    }
+                    else {
+                        const error = `The view "${declared?.name ?? msg.payload?.id}" was not changed: ${result.reason}.`;
+                        console.error(`[Diagram] REFUSED: ${error}`);
+                        ws.send(JSON.stringify({ type: 'app:error', payload: { requestId: msg.payload?.requestId, error } }));
                     }
                 }
                 else if (msg.type === 'diagram:delete') {
-                    const { projectRoot } = options;
-                    const userDiagrams = loadUserDiagrams(projectRoot);
-                    const filtered = userDiagrams.filter(d => d.id !== msg.payload.id);
-                    saveUserDiagrams(projectRoot, filtered);
-                    broadcastDiagramChange({ id: msg.payload.id }, 'delete');
-                    console.log(`[Diagram] Deleted: ${msg.payload.id}`);
+                    // Deleting a view means deleting its declaration, which is
+                    // `element:delete` on the view element — not a sidecar edit.
+                    const declared = currentDiagrams().find(d => d.id === msg.payload?.id);
+                    const where = declared?.sourceFile
+                        ? `Remove its \`view\` declaration from ${declared.sourceFile}.`
+                        : 'It is not declared in SysML.';
+                    const error = `The view "${declared?.name ?? msg.payload?.id}" cannot be deleted from here — `
+                        + `a view exists because it is declared. ${where}`;
+                    console.error(`[Diagram] REFUSED: ${error}`);
+                    ws.send(JSON.stringify({ type: 'app:error', payload: { requestId: msg.payload?.requestId, error } }));
                 }
                 else if (msg.type === 'diagram:layout:update') {
                     const { diagramId, layout } = msg.payload;