@@ -14,7 +14,7 @@ import { agentIdentityComponents } from "@executablemd/core";
1414import type { PermissionMode } from "@executablemd/core" ;
1515import type { GeneratedSelection } from "@executablemd/core/api" ;
1616import type { ExecutionInstallation } from "@executablemd/core/host" ;
17- import { useScope } from "effection" ;
17+ import { scoped , useScope } from "effection" ;
1818import { cwd } from "@executablemd/runtime" ;
1919import { resolve , join } from "node:path" ;
2020import type { Operation } from "effection" ;
@@ -33,7 +33,10 @@ import { runReplProgram } from "./repl/program.ts";
3333import type { ReplInputPass } from "./repl/program.ts" ;
3434import { ReplEntryHost } from "./repl-entry-installation.ts" ;
3535import type { ReplEntryInstallation } from "./repl-entry-installation.ts" ;
36- import { renderSyntaxDocumentation , renderSyntaxMarkdown , syntaxSymbols } from "./syntax.ts" ;
36+ import { inspectSyntax , renderSyntaxMarkdown } from "@executablemd/core" ;
37+ import { Component , Syntax } from "@executablemd/core/api" ;
38+ import { useSyntax } from "@executablemd/core/host" ;
39+ import { useTestingComponents } from "@executablemd/testing" ;
3740
3841const REPL_INCLUDES : readonly string [ ] = Object . freeze ( [ "components" , "." ] ) ;
3942
@@ -288,25 +291,26 @@ export function* assembleReplProfile(
288291 installElicitation : noElicitationOfItsOwn ,
289292 } ) ;
290293
294+ const entryInstallations = Object . freeze ( [
295+ ...installations ,
296+ children . installation ,
297+ Object . freeze ( {
298+ components : agentIdentityComponents ( ) ,
299+ declarations : Object . freeze ( [ plan ] ) ,
300+ } ) ,
301+ ] ) ;
291302 const profile = Object . freeze ( {
292303 children,
293304 mounts,
294305 includes,
295306 projectCwd,
296- vocabulary : entryVocabulary ( includes , plugins , children . installation . components ) ,
307+ vocabulary : entryVocabulary ( includes , entryInstallations ) ,
297308 // Read off the admitted assembly here, once, while it is in hand. Copied
298309 // rather than referenced so nothing downstream can reach a Plugin value
299310 // through the profile, and frozen because a profile is read and never
300311 // changed.
301312 plugins : names ,
302- installations : Object . freeze ( [
303- ...installations ,
304- children . installation ,
305- Object . freeze ( {
306- components : agentIdentityComponents ( ) ,
307- declarations : Object . freeze ( [ plan ] ) ,
308- } ) ,
309- ] ) ,
313+ installations : entryInstallations ,
310314 generated : ordinaryGeneratedSelection ( ) ,
311315 permissionMode,
312316 ...( entryInstallation === undefined ? { } : { entryInstallation } ) ,
@@ -329,33 +333,108 @@ export function* assembleReplProfile(
329333 } ) ;
330334}
331335
332- /**
333- * Describe one profile's entry vocabulary, through the machinery `xmd syntax` uses.
334- *
335- * One construction for both questions, and the same one the command line
336- * answers from: an operator printing the vocabulary and a reply asking about it
337- * are asking about one language, and two renderings that agreed only by hand
338- * would be one release away from disagreeing.
339- *
340- * Exported because a profile assembled for a proof describes the same vocabulary
341- * as a profile assembled for a command — the includes and the Plugins differ,
342- * and nothing else does.
343- */
336+ /** Describe the finalized entry installations without acquiring their resources. */
344337export function entryVocabulary (
345338 includes : readonly string [ ] ,
346- plugins : CommandPlugins ,
347- components : import ( "@executablemd/core/host" ) . ExecutionInstallation [ "components" ] = [ ] ,
339+ installations : readonly ExecutionInstallation [ ] = [ ] ,
348340) : EntryVocabulary {
341+ function * ordinary ( ) {
342+ return {
343+ includes : [ ...includes ] ,
344+ registry : new Map ( yield * Component . operations . registry ) ,
345+ components : installations . flatMap ( ( one ) =>
346+ ( one . components ?? [ ] ) . map ( ( item ) => ( { ...item } ) ) ,
347+ ) ,
348+ declarations : installations . flatMap ( ( one ) =>
349+ ( one . declarations ?? [ ] ) . map ( ( item ) => ( { ...item } ) ) ,
350+ ) ,
351+ } ;
352+ }
349353 return Object . freeze ( {
350- * symbols ( ) : Operation < string > {
351- return renderSyntaxMarkdown ( yield * syntaxSymbols ( includes , plugins , components ) ) ;
354+ symbols ( ) : Operation < string > {
355+ return scoped ( function * ( ) {
356+ const inputs = yield * ordinary ( ) ;
357+ yield * useSyntax ( ( ) => inspectSyntax ( inputs ) ) ;
358+ return (
359+ renderSyntaxMarkdown ( yield * Syntax . operations . symbols ) +
360+ "\nMarkdown test components are documented by name with REPL.Syntax and run through REPL.Test.\n" +
361+ ENTRY_AVAILABILITY
362+ ) ;
363+ } ) ;
352364 } ,
353365 documentation ( names : readonly string [ ] ) : Operation < string > {
354- return renderSyntaxDocumentation ( includes , names , plugins , components ) ;
366+ return scoped ( function * ( ) {
367+ const inputs = yield * ordinary ( ) ;
368+ const runnable = yield * inspectSyntax ( inputs ) ;
369+ const ordinaryNames = new Set (
370+ runnable . categories . flatMap ( ( category ) => category . entries . map ( ( entry ) => entry . name ) ) ,
371+ ) ;
372+ // Inspect testing separately so reference registrations cannot replace
373+ // an ordinary selection or read its moving session files a second time.
374+ yield * useTestingComponents ( ) ;
375+ const testing = yield * inspectSyntax ( { includes : [ ] } ) ;
376+ const readable = {
377+ ...runnable ,
378+ categories : [
379+ runnable . categories [ 0 ] ,
380+ {
381+ ...runnable . categories [ 1 ] ,
382+ entries : [
383+ ...runnable . categories [ 1 ] . entries ,
384+ ...testing . categories [ 1 ] . entries . filter ( ( entry ) => ! ordinaryNames . has ( entry . name ) ) ,
385+ ] . sort ( ( left , right ) => {
386+ if ( left . name < right . name ) {
387+ return - 1 ;
388+ }
389+ return left . name > right . name ? 1 : 0 ;
390+ } ) ,
391+ } ,
392+ runnable . categories [ 2 ] ,
393+ ] ,
394+ } satisfies import ( "@executablemd/core" ) . SyntaxSymbols ;
395+ yield * useSyntax ( function * ( ) {
396+ return readable ;
397+ } ) ;
398+ yield * Syntax . around ( {
399+ symbols : function * ( ) {
400+ return runnable ;
401+ } ,
402+ } ) ;
403+ const documentation = yield * Syntax . operations . documentation ( names ) ;
404+ return (
405+ documentation +
406+ ENTRY_AVAILABILITY +
407+ ( names . some ( ( name ) => ! ordinaryNames . has ( name ) ) ? TEST_CONTEXT : "" )
408+ ) ;
409+ } ) ;
355410 } ,
356411 } ) ;
357412}
358413
414+ const ENTRY_AVAILABILITY =
415+ "\nAvailability describes resolution in an ordinary entry, not permission to perform every effect or a guarantee of success.\n" ;
416+
417+ const TEST_CONTEXT = `
418+ Components marked unavailable cannot run in an ordinary entry. Use them in a Markdown test
419+ requested through REPL.Test. Save this complete test as the session-relative
420+ \`components/assertions.test.md\`:
421+
422+ \`\`\`xmd
423+ <Test name="assertions">
424+ <Assert expr={true} />
425+ <AssertEquals actual="yes" expected="yes" />
426+ </Test>
427+ \`\`\`
428+
429+ Then write this in a Sidekick response:
430+
431+ \`\`\`xmd
432+ <REPL.Test path="components/assertions.test.md" />
433+ \`\`\`
434+
435+ The file runs as a test document; do not submit it as an ordinary entry.
436+ ` ;
437+
359438/**
360439 * The Plan Component's elicitation installer, which installs nothing.
361440 *
0 commit comments