@memoarchitect/tools 0.13.0 → 0.15.0

package/packages/tools/lib/authoring/outline-source.d.ts

@@ -0,0 +1,57 @@
+import type { MEMOConfig } from '../model/config.js';
+import type { IrIdentityIndex } from '../model/ir-identity.js';
+import type { ApiModel } from '../stage2/api-model.js';
+import { type ProjectModel } from '../toolchain/project-model.js';
+import { type SourceOutline } from './source-outline.js';
+/** The outline of one project file, given its current text. */
+export interface OutlineSource {
+    /**
+     * The outline of a file as it is on disk. `file` is project-relative.
+     * Rejects with a message when the text is not one the selected compiler
+     * accepts: there is no outline to edit then.
+     */
+    outline(file: string, text: string): Promise<SourceOutline>;
+    /**
+     * Compile the project with `text` in place of the file, before it reaches
+     * disk. Rejects with the compiler's diagnostics when it does not accept
+     * the result: an edit that would make the project invalid SysML is not
+     * written. `also` is every other file the same edit changes, project-relative,
+     * since an edit that spans files is valid only as a whole: one file alone can
+     * leave a reference to what another file's edit removed. Gives the outline of
+     * the text when the compile states one;
+     * OpenSysML's verdict on a content document does not, since stating it
+     * would cost a conversion of the whole model.
+     */
+    verify(file: string, text: string, also?: ReadonlyMap<string, string>): Promise<SourceOutline | undefined>;
+}
+/**
+ * Outlines from a handoff, recompiling when a file changed since it was
+ * compiled. `texts` are the files' contents as that compile read them.
+ */
+export declare function handoffOutlineSource(options: {
+    projectRoot: string;
+    config: MEMOConfig;
+    api: ApiModel;
+    texts: ReadonlyMap<string, string>;
+}): OutlineSource;
+/**
+ * The outline source of the selected compiler, for a caller holding no loaded
+ * project: the project loads on first use, reusing `.memo/stage1/` when
+ * nothing changed.
+ */
+export declare function selectedOutlineSource(projectRoot: string, config: MEMOConfig): OutlineSource;
+/** The outline source for a loaded project: its compiler's. */
+export declare function outlineSourceFor(projectRoot: string, config: MEMOConfig, project: ProjectModel): OutlineSource;
+/** The outlines of every project file of a loaded project. */
+export declare function projectOutlines(projectRoot: string, project: ProjectModel): SourceOutline[];
+/** The outlines of a handoff's project files, read against the files on disk. */
+export declare function outlinesFromHandoff(projectRoot: string, api: ApiModel): SourceOutline[];
+/**
+ * The identity index a write resolves against: every declaration with an
+ * identity, and each element's.
+ */
+export declare function outlineIdentityIndex(outlines: readonly SourceOutline[], elements: Iterable<{
+    id: string;
+    file?: string;
+}>, projectRoot: string): IrIdentityIndex;
+//# sourceMappingURL=outline-source.d.ts.map

package/packages/tools/lib/authoring/outline-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outline-source.d.ts","sourceRoot":"","sources":["../../src/authoring/outline-source.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAyC,KAAK,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAMzG,OAAO,EAAoC,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE3F,+DAA+D;AAC/D,MAAM,WAAW,aAAa;IAC1B;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5D;;;;;;;;;;OAUG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;CAC9G;AAID;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,UAAU,CAAC;IACnB,GAAG,EAAE,QAAQ,CAAC;IACd,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC,GAAG,aAAa,CAoBhB;AA0ED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,aAAa,CAY5F;AAED,+DAA+D;AAC/D,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,GAAG,aAAa,CAE9G;AAiCD,8DAA8D;AAC9D,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,aAAa,EAAE,CAE3F;AASD,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,GAAG,aAAa,EAAE,CAWvF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAChC,QAAQ,EAAE,SAAS,aAAa,EAAE,EAClC,QAAQ,EAAE,QAAQ,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EACjD,WAAW,EAAE,MAAM,GACpB,eAAe,CAQjB"}

package/packages/tools/lib/authoring/outline-source.js

@@ -0,0 +1,203 @@
+// ─── Outlines of a project, from whichever compiler is selected ─────────────
+//
+// A write resolves its identity against the outline of the file as it is on
+// disk now (plans/memo-write-back-from-handoff.md). That is the last handoff,
+// when the file is unchanged since that compile, and otherwise a fresh compile:
+// an outline read from a handoff of other bytes would put every range in the
+// wrong place.
+// ─────────────────────────────────────────────────────────────────────────────
+import { createHash } from 'node:crypto';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { loadProjectModel, Stage1RejectedError } from '../toolchain/project-model.js';
+import { resolveToolchain } from '../toolchain/effective.js';
+import { defaultRegistry } from '../toolchain/default-registry.js';
+import { OPENSYSML_PROVIDER_ID } from '../toolchain/providers/opensysml.js';
+import { checkWithOpenSysML } from '../toolchain/providers/opensysml-check.js';
+import { outlineIdentities, outlineIdentityTable } from './outline-identity.js';
+import { emptyOutline, outlineFromHandoff } from './source-outline.js';
+const sha = (text) => createHash('sha256').update(text).digest('hex');
+/**
+ * Outlines from a handoff, recompiling when a file changed since it was
+ * compiled. `texts` are the files' contents as that compile read them.
+ */
+export function handoffOutlineSource(options) {
+    let { api } = options;
+    let hashes = new Map([...options.texts].map(([file, text]) => [file, sha(text)]));
+    return {
+        async outline(file, text) {
+            // An empty file declares nothing, whether or not it was compiled.
+            if (!text.trim())
+                return emptyOutline(file, text);
+            if (hashes.get(file) !== sha(text)) {
+                const project = await loadProjectModel({ projectRoot: options.projectRoot, config: options.config });
+                if (!project.api)
+                    throw new Error(`${project.compiler} built no handoff to outline ${file} from`);
+                api = project.api;
+                hashes = new Map([...projectTexts(options.projectRoot, project)].map(([f, t]) => [f, sha(t)]));
+                if (hashes.get(file) !== sha(text)) {
+                    throw new Error(`${file} changed while it was being compiled; repeat the edit`);
+                }
+            }
+            return outlineFromHandoff(api, resolve(options.projectRoot, file), file, text);
+        },
+        verify: (file, text, also) => verifyWithSelected(options.projectRoot, options.config, file, text, also),
+    };
+}
+/**
+ * Verify an edit with the selected compiler: OpenSysML compiles the edited
+ * text as a content document, any other compiler a scratch copy of the
+ * project.
+ */
+function verifyWithSelected(projectRoot, config, file, text, also) {
+    return resolveToolchain(config, defaultRegistry).lowering === OPENSYSML_PROVIDER_ID
+        ? verifyAsContent(projectRoot, config, file, text, also)
+        : verifyInScratchCopy(projectRoot, config, file, text, also);
+}
+/** OpenSysML's verdict on the project with the file's text replaced, read without writing it. */
+async function verifyAsContent(projectRoot, config, file, text, also) {
+    const absolute = resolve(projectRoot, file);
+    const replaced = new Map([...(also ?? [])].map(([path, content]) => [resolve(projectRoot, path), content]));
+    replaced.set(absolute, text);
+    const errors = await checkWithOpenSysML(config, projectRoot, replaced);
+    if (errors.length > 0) {
+        const where = (d) => `${d.file ? relativeTo(projectRoot, resolve(projectRoot, d.file)) : file}:${d.range?.start.line ?? '?'}`;
+        throw new Error(`opensysml rejects the updated ${file}: ${errors.slice(0, 3).map(d => `${where(d)} ${d.message}`).join('; ')}`);
+    }
+    return undefined;
+}
+/** What a scratch copy of a project leaves out: tool state and dependencies, which are linked. */
+const NOT_COPIED = new Set(['.memo', '.git', 'node_modules']);
+/**
+ * Compile the project with one file's text replaced, in a scratch copy of the
+ * project: every stage 1 compiler reads its documents from disk, and the
+ * project's own file must not change until the edit is known to be valid.
+ * The libraries are not copied; the copy resolves them as the project does.
+ */
+async function verifyInScratchCopy(projectRoot, config, file, text, also) {
+    const scratch = realpathSync(mkdtempSync(join(tmpdir(), 'memo-verify-')));
+    try {
+        cpSync(projectRoot, scratch, {
+            recursive: true,
+            filter: source => !NOT_COPIED.has(basename(source)) || source === projectRoot,
+        });
+        const modules = join(projectRoot, 'node_modules');
+        if (existsSync(modules))
+            symlinkSync(modules, join(scratch, 'node_modules'), 'dir');
+        for (const [path, content] of [...(also ?? []), [file, text]]) {
+            const target = join(scratch, path);
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, content, 'utf8');
+        }
+        const target = join(scratch, file);
+        let project;
+        try {
+            project = await loadProjectModel({ projectRoot: scratch, config, cache: false });
+        }
+        catch (e) {
+            if (e instanceof Stage1RejectedError) {
+                const errors = e.diagnostics.filter(d => d.severity === 'error')
+                    .map(d => `${d.file ? relative(scratch, resolve(scratch, d.file)) : file}:${d.range?.start.line ?? '?'} ${d.message}`);
+                throw new Error(`${e.compiler} rejects the updated ${file}: ${errors.slice(0, 3).join('; ')}`);
+            }
+            throw e;
+        }
+        if (!project.api)
+            throw new Error(`${project.compiler} built no handoff to verify ${file} with`);
+        return outlineFromHandoff(project.api, target, file, text);
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}
+/**
+ * The outline source of the selected compiler, for a caller holding no loaded
+ * project: the project loads on first use, reusing `.memo/stage1/` when
+ * nothing changed.
+ */
+export function selectedOutlineSource(projectRoot, config) {
+    let loaded;
+    const source = () => (loaded ??= loadProjectModel({ projectRoot, config })
+        .then(project => outlineSourceFor(projectRoot, config, project)));
+    return {
+        async outline(file, text) {
+            return (await source()).outline(file, text);
+        },
+        async verify(file, text) {
+            return verifyWithSelected(projectRoot, config, file, text);
+        },
+    };
+}
+/** The outline source for a loaded project: its compiler's. */
+export function outlineSourceFor(projectRoot, config, project) {
+    return handoffOutlineSource({ projectRoot, config, api: project.api, texts: projectTexts(projectRoot, project) });
+}
+/** The project's own files and their text, by project-relative path. */
+function projectTexts(projectRoot, project) {
+    const texts = new Map();
+    for (const file of projectFilesOf(project.api, projectRoot)) {
+        if (existsSync(file))
+            texts.set(relative(projectRoot, file), readFileSync(file, 'utf8'));
+    }
+    return texts;
+}
+/**
+ * The absolute files of the project's own documents: the handoff's project
+ * documents, and those of a library root inside the project directory (a
+ * project's `methodology/`), which the handoff marks as library documents but
+ * which are the project's files to edit. A library outside it is not.
+ */
+function projectFilesOf(api, projectRoot) {
+    const root = resolve(projectRoot);
+    const inProject = (file) => !relative(root, file).startsWith('..') && !isAbsolute(relative(root, file));
+    const files = new Set();
+    for (const [file, namespaces] of api.rootNamespacesByFile()) {
+        for (const namespace of namespaces) {
+            const role = api.source(namespace['@id'])?.role;
+            if (role === 'project' || (role === 'library' && inProject(resolve(file))))
+                files.add(file);
+        }
+    }
+    return [...files];
+}
+const relativeTo = (projectRoot, file) => (isAbsolute(file) ? relative(projectRoot, file) : file).replaceAll('\\', '/');
+/** The outlines of every project file of a loaded project. */
+export function projectOutlines(projectRoot, project) {
+    return outlinesFromHandoff(projectRoot, project.api);
+}
+/**
+ * An outline kept with the document it was read from: a document the last
+ * compile did not convert keeps its element objects, so the same root
+ * namespace and the same text give the same outline.
+ */
+const keptOutlines = new WeakMap();
+/** The outlines of a handoff's project files, read against the files on disk. */
+export function outlinesFromHandoff(projectRoot, api) {
+    return projectFilesOf(api, projectRoot).filter(file => existsSync(file)).map(file => {
+        const name = relativeTo(projectRoot, file);
+        const text = readFileSync(file, 'utf8');
+        const roots = api.rootNamespacesIn(file);
+        const kept = roots.length > 0 ? keptOutlines.get(roots[0]) : undefined;
+        if (kept && kept.name === name && kept.text === text && kept.roots === roots.length)
+            return kept.outline;
+        const outline = outlineFromHandoff(api, file, name, text);
+        if (roots.length > 0)
+            keptOutlines.set(roots[0], { name, text, roots: roots.length, outline });
+        return outline;
+    });
+}
+/**
+ * The identity index a write resolves against: every declaration with an
+ * identity, and each element's.
+ */
+export function outlineIdentityIndex(outlines, elements, projectRoot) {
+    const byMemoElement = outlineIdentityTable(outlines, elements, projectRoot);
+    const elementOf = new Map(Object.entries(byMemoElement).map(([element, identity]) => [identity, element]));
+    const byIdentity = new Map();
+    for (const [identity, { node }] of outlineIdentities(outlines)) {
+        byIdentity.set(identity, { identity: { id: identity, metaclass: node.metaclass }, memoElementId: elementOf.get(identity) });
+    }
+    return { byMemoElement, byIdentity };
+}
+//# sourceMappingURL=outline-source.js.map

package/packages/tools/lib/authoring/outline-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outline-source.js","sourceRoot":"","sources":["../../src/authoring/outline-source.ts"],"names":[],"mappings":"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"}

package/packages/tools/lib/authoring/source-outline.d.ts

@@ -0,0 +1,82 @@
+import type { ApiModel } from '../stage2/api-model.js';
+/** What a writer does with a member: regenerate it, carry it, or address it. */
+export type OutlineRole = 'package' | 'attribute' | 'doc' | 'metadata' | 'expose' | 'import' | 'connection' | 'declaration';
+export interface OutlineNode {
+    /** The SysML metaclass, as the API names it: `PartUsage`, `AttributeUsage`, `Package`. */
+    metaclass: string;
+    role: OutlineRole;
+    /** The name the declaration declares, when it declares one. */
+    name?: string;
+    /**
+     * What addresses the declaration within its file: its owner's key and its
+     * name — its qualified name, for a declaration in named owners — or, when
+     * it declares no name, its place among the anonymous declarations of its
+     * metaclass there (`P::@ConnectionUsage[1]`). A redefinition
+     * (`attribute :>> x`) is named by the feature it redefines.
+     */
+    key: string;
+    /** Offset of the declaration's first character. */
+    start: number;
+    /** Offset just past its last character. */
+    end: number;
+    /** Offset just past the body's `{`, and the offset of its `}`. */
+    body?: {
+        open: number;
+        close: number;
+    };
+    members: OutlineNode[];
+    /** The features a metadata annotation sets (`providedId`, `label`). */
+    fields: string[];
+}
+export interface SourceOutline {
+    /** The file, as the caller named it. */
+    file: string;
+    text: string;
+    roots: OutlineNode[];
+}
+/** Every node of an outline, depth first in source order. */
+export declare function outlineNodes(outline: SourceOutline | readonly OutlineNode[]): Generator<OutlineNode>;
+/**
+ * The members written inside a declaration's body. A compiler also places
+ * features it reads from the declaration's head under it — the ends of
+ * `connect a to b`, a flow's payload — and a writer must never move those.
+ */
+export declare function bodyMembers(node: OutlineNode): OutlineNode[];
+/**
+ * The braces of a declaration's body: the first `{` at the top level of its
+ * text and the `}` that closes it, skipping strings and comments. Undefined for
+ * a declaration that ends in `;`.
+ */
+export declare function findBody(text: string, start: number, end: number): {
+    open: number;
+    close: number;
+} | undefined;
+/**
+ * The outline of one file from a handoff that compiled it.
+ *
+ * `absoluteFile` names the file as the handoff's index resolves it; `text` is
+ * the file's bytes at the time of that compile, which the caller checks.
+ * Elements the handoff gives no range — the ones a compiler implies rather than
+ * reads — are not declarations; their ranged members are kept under the
+ * nearest ranged owner.
+ */
+export declare function outlineFromHandoff(api: ApiModel, absoluteFile: string, file: string, text: string): SourceOutline;
+/**
+ * The outline of one file from MEMO's parse of it: the same facts, read from
+ * the syntax tree, so the writers work alike under MEMO's compiler. `root` is
+ * the parsed document's model.
+ */
+export declare function outlineFromParse(root: {
+    members?: unknown[];
+}, file: string, text: string): SourceOutline;
+/**
+ * The outline of the text after replacing `[from, to)` with `inserted`, without
+ * compiling it: a declaration inside the replaced range is gone, one after it
+ * moves by the length difference, and one around it grows or shrinks. A writer
+ * that removes a declaration and then inserts elsewhere in the same text needs
+ * the outline of a text no compiler has seen.
+ */
+export declare function spliceOutline(outline: SourceOutline, from: number, to: number, inserted: string): SourceOutline;
+/** An outline with nothing in it: the outline of an empty or new file. */
+export declare function emptyOutline(file: string, text?: string): SourceOutline;
+//# sourceMappingURL=source-outline.d.ts.map

package/packages/tools/lib/authoring/source-outline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-outline.d.ts","sourceRoot":"","sources":["../../src/authoring/source-outline.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAc,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEnE,gFAAgF;AAChF,MAAM,MAAM,WAAW,GACjB,SAAS,GAAG,WAAW,GAAG,KAAK,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,GAAG,aAAa,CAAC;AAExG,MAAM,WAAW,WAAW;IACxB,0FAA0F;IAC1F,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,WAAW,CAAC;IAClB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,kEAAkE;IAClE,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,uEAAuE;IACvE,MAAM,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC1B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,WAAW,EAAE,CAAC;CACxB;AAED,6DAA6D;AAC7D,wBAAiB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,WAAW,EAAE,GAAG,SAAS,CAAC,WAAW,CAAC,CAOrG;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,EAAE,CAI5D;AAqBD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CA6B9G;AAgDD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAgCjH;AAmCD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,EAAE,CAAA;CAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAuBzG;AAID;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,CAiB/G;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAK,GAAG,aAAa,CAEnE"}

package/packages/tools/lib/authoring/source-outline.js

@@ -0,0 +1,267 @@
+// ─── Source outline ──────────────────────────────────────────────────────────
+//
+// What a write-back needs to know about a file, and no more: where each
+// declaration is, what it is called, where its body opens and closes, and its
+// members (plans/memo-write-back-from-handoff.md). The writers used to read
+// these from MEMO's syntax tree, which tied them to MEMO's grammar. An outline
+// is built from a stage 1 handoff — every element states its byte range and
+// qualified name — or, while MEMO's compiler exists, from MEMO's parse; the
+// writers read the outline either way.
+//
+// Offsets are JavaScript string offsets into the file's text, the unit a splice
+// is made in. A handoff states byte offsets; they are converted here.
+// ─────────────────────────────────────────────────────────────────────────────
+/** Every node of an outline, depth first in source order. */
+export function* outlineNodes(outline) {
+    const stack = [...('roots' in outline ? outline.roots : outline)].reverse();
+    while (stack.length > 0) {
+        const node = stack.pop();
+        yield node;
+        stack.push(...[...node.members].reverse());
+    }
+}
+/**
+ * The members written inside a declaration's body. A compiler also places
+ * features it reads from the declaration's head under it — the ends of
+ * `connect a to b`, a flow's payload — and a writer must never move those.
+ */
+export function bodyMembers(node) {
+    const body = node.body;
+    if (!body)
+        return [];
+    return node.members.filter(member => member.start >= body.open && member.end <= body.close);
+}
+// ─── Roles ───────────────────────────────────────────────────────────────────
+const CONNECTIONS = new Set([
+    'ConnectionUsage', 'InterfaceUsage', 'AllocationUsage', 'FlowUsage', 'SuccessionFlowUsage',
+]);
+function roleOf(metaclass) {
+    if (metaclass === 'Package' || metaclass === 'LibraryPackage')
+        return 'package';
+    if (metaclass === 'AttributeUsage')
+        return 'attribute';
+    if (metaclass === 'Documentation')
+        return 'doc';
+    if (metaclass === 'MetadataUsage')
+        return 'metadata';
+    if (metaclass.endsWith('Expose'))
+        return 'expose';
+    if (metaclass.endsWith('Import'))
+        return 'import';
+    if (CONNECTIONS.has(metaclass))
+        return 'connection';
+    return 'declaration';
+}
+// ─── Bodies ──────────────────────────────────────────────────────────────────
+/**
+ * The braces of a declaration's body: the first `{` at the top level of its
+ * text and the `}` that closes it, skipping strings and comments. Undefined for
+ * a declaration that ends in `;`.
+ */
+export function findBody(text, start, end) {
+    let depth = 0;
+    let open = -1;
+    for (let i = start; i < end; i++) {
+        const c = text[i];
+        if (c === '"' || c === "'") {
+            for (i++; i < end && text[i] !== c; i++)
+                if (text[i] === '\\')
+                    i++;
+            continue;
+        }
+        if (c === '/' && text[i + 1] === '/') {
+            while (i < end && text[i] !== '\n')
+                i++;
+            continue;
+        }
+        if (c === '/' && text[i + 1] === '*') {
+            const close = text.indexOf('*/', i + 2);
+            i = close < 0 ? end : close + 1;
+            continue;
+        }
+        if (c === '{') {
+            if (depth === 0 && open < 0)
+                open = i;
+            depth++;
+        }
+        else if (c === '}') {
+            depth--;
+            if (depth === 0 && open >= 0)
+                return { open: open + 1, close: i };
+        }
+        else if (c === ';' && depth === 0 && open < 0) {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/** Turn raw nodes into outline nodes, keying each under its owner. */
+function finish(text, raws, ownerKey) {
+    const anonymous = new Map();
+    return raws.map(raw => {
+        let key;
+        if (raw.name)
+            key = ownerKey ? `${ownerKey}::${raw.name}` : raw.name;
+        else {
+            const n = anonymous.get(raw.metaclass) ?? 0;
+            anonymous.set(raw.metaclass, n + 1);
+            key = `${ownerKey ? `${ownerKey}::` : ''}@${raw.metaclass}[${n}]`;
+        }
+        return {
+            metaclass: raw.metaclass,
+            role: roleOf(raw.metaclass),
+            ...(raw.name ? { name: raw.name } : {}),
+            key,
+            start: raw.start,
+            end: raw.end,
+            ...(() => { const body = findBody(text, raw.start, raw.end); return body ? { body } : {}; })(),
+            members: finish(text, raw.members, key),
+            fields: raw.fields,
+        };
+    });
+}
+// ─── From a stage 1 handoff ──────────────────────────────────────────────────
+/** Byte offset → string offset, for one file's text. */
+function byteToChar(text) {
+    // eslint-disable-next-line no-control-regex
+    if (!/[^\u0000-\u007f]/.test(text))
+        return byte => byte;
+    const bytes = Buffer.from(text, 'utf8');
+    return byte => bytes.subarray(0, byte).toString('utf8').length;
+}
+/**
+ * The outline of one file from a handoff that compiled it.
+ *
+ * `absoluteFile` names the file as the handoff's index resolves it; `text` is
+ * the file's bytes at the time of that compile, which the caller checks.
+ * Elements the handoff gives no range — the ones a compiler implies rather than
+ * reads — are not declarations; their ranged members are kept under the
+ * nearest ranged owner.
+ */
+export function outlineFromHandoff(api, absoluteFile, file, text) {
+    const toChar = byteToChar(text);
+    const ranged = (element) => {
+        const entry = api.source(element['@id']);
+        return entry?.startByte !== undefined && entry.endByte !== undefined ? entry : undefined;
+    };
+    const visit = (element) => {
+        const entry = ranged(element);
+        const metaclass = String(element['@type']);
+        // A metadata annotation's fields are `fields`, not declarations.
+        const children = metaclass === 'MetadataUsage' ? [] : api.ownedMembers(element['@id']).flatMap(visit);
+        if (!entry)
+            return children;
+        return [{
+                metaclass,
+                // `attribute :>> x = …` declares no name; the name it is written
+                // with is the feature it redefines. `variant x;` is written with
+                // the name of the feature it references.
+                name: api.name(element['@id']) ?? variantName(api, element),
+                start: toChar(entry.startByte),
+                end: toChar(entry.endByte),
+                members: children,
+                fields: metaclass === 'MetadataUsage'
+                    ? api.ownedMembers(element['@id']).map(m => api.name(m['@id'])).filter((n) => Boolean(n))
+                    : [],
+            }];
+    };
+    const roots = [];
+    for (const namespace of api.rootNamespacesIn(absoluteFile)) {
+        for (const member of api.ownedMembers(namespace['@id']))
+            roots.push(...visit(member));
+    }
+    roots.sort((a, b) => a.start - b.start);
+    return { file, text, roots: finish(text, roots, '') };
+}
+/** The name of the feature `variant x;` references: a variant member declares none. */
+function variantName(api, element) {
+    const owning = api.element(String(element.owningRelationship?.['@id'] ?? ''));
+    if (owning?.['@type'] !== 'VariantMembership')
+        return undefined;
+    const referenced = api.related(element['@id'], ['ReferenceSubsetting'], 'referencedFeature')[0];
+    return referenced ? api.name(referenced['@id']) : undefined;
+}
+// ─── From MEMO's parse ───────────────────────────────────────────────────────
+/** MEMO's syntax-tree node types that do not carry the metaclass's own name. */
+const PARSE_METACLASS = {
+    PackageDeclaration: 'Package',
+    PartMember: 'PartUsage',
+    AttributeMember: 'AttributeUsage',
+    RefMember: 'ReferenceUsage',
+    DocComment: 'Documentation',
+    MetadataApplication: 'MetadataUsage',
+    PrefixMetadataAnnotation: 'MetadataUsage',
+    ExposeMember: 'NamespaceExpose',
+    ImportDeclaration: 'NamespaceImport',
+    EnumDefinition: 'EnumerationDefinition',
+    EnumLiteral: 'EnumerationUsage',
+    FlowConnectionUsage: 'FlowUsage',
+    AllocateUsage: 'AllocationUsage',
+    MessageUsage: 'FlowUsage',
+    BindingUsage: 'BindingConnectorAsUsage',
+    SuccessionUsage: 'SuccessionAsUsage',
+    ActorMember: 'PartUsage',
+    StakeholderMember: 'PartUsage',
+    SubjectMember: 'ReferenceUsage',
+};
+/**
+ * The outline of one file from MEMO's parse of it: the same facts, read from
+ * the syntax tree, so the writers work alike under MEMO's compiler. `root` is
+ * the parsed document's model.
+ */
+export function outlineFromParse(root, file, text) {
+    // A key is the owner's key and the declared name, as `finish` makes it.
+    const visit = (node) => {
+        const cst = node?.$cstNode;
+        if (!node || typeof node !== 'object' || !node.$type || !cst)
+            return [];
+        const metaclass = PARSE_METACLASS[node.$type] ?? node.$type;
+        const name = typeof node.name === 'string' ? node.name : undefined;
+        // A metadata annotation's fields are `fields`, not declarations.
+        const children = metaclass === 'MetadataUsage' ? []
+            : [...(node.members ?? []), ...(node.body ?? []), ...(node.usageBody ?? [])].flatMap(visit);
+        return [{
+                metaclass,
+                name,
+                start: cst.offset,
+                end: cst.offset + cst.length,
+                members: children,
+                fields: metaclass === 'MetadataUsage'
+                    ? (node.body ?? []).map((field) => field.name).filter(Boolean)
+                    : [],
+            }];
+    };
+    const roots = (root.members ?? []).flatMap(visit);
+    return { file, text, roots: finish(text, roots, '') };
+}
+// ─── Editing an outline with its text ────────────────────────────────────────
+/**
+ * The outline of the text after replacing `[from, to)` with `inserted`, without
+ * compiling it: a declaration inside the replaced range is gone, one after it
+ * moves by the length difference, and one around it grows or shrinks. A writer
+ * that removes a declaration and then inserts elsewhere in the same text needs
+ * the outline of a text no compiler has seen.
+ */
+export function spliceOutline(outline, from, to, inserted) {
+    const delta = inserted.length - (to - from);
+    const moved = (offset) => (offset >= to ? offset + delta : offset);
+    const map = (nodes) => nodes
+        .filter(node => !(to > from && node.start >= from && node.end <= to))
+        .map(node => ({
+        ...node,
+        start: moved(node.start),
+        end: moved(node.end),
+        ...(node.body ? { body: { open: moved(node.body.open), close: moved(node.body.close) } } : {}),
+        members: map(node.members),
+    }));
+    return {
+        ...outline,
+        text: outline.text.slice(0, from) + inserted + outline.text.slice(to),
+        roots: map(outline.roots),
+    };
+}
+/** An outline with nothing in it: the outline of an empty or new file. */
+export function emptyOutline(file, text = '') {
+    return { file, text, roots: [] };
+}
+//# sourceMappingURL=source-outline.js.map