@aws/nx-plugin 1.0.0-rc.7 → 1.0.0-rc.71

package/src/mcp-server/guide-pipeline.js

@@ -1,115 +1,116 @@
-"use strict";
 /**
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.postProcessGuideWithRemark = exports.parseMdx = void 0;
-const tslib_1 = require("tslib");
-const fs_1 = tslib_1.__importDefault(require("fs"));
-const commands_1 = require("../utils/commands");
-const guide_render_1 = require("./guide-render");
-const mdx_ast_1 = require("./mdx-ast");
-const option_filter_1 = require("./option-filter");
+ */ import fs from "fs";
+import { buildCreateNxWorkspaceCommand, buildInstallCommand, buildNxInitCommand, buildPackageManagerExecCommand, buildPackageManagerShortCommand } from "../utils/commands.js";
+import { buildNxCommand, renderGeneratorCommand, renderSchema } from "./guide-render.js";
+import { hasBareAttr, isJsxElement, readEstreeAttr, readExpressionAttr, readStringAttr } from "./mdx-ast.js";
+import { describePredicate, evaluatePredicate, extractStringArrayExpression, parseWhenExpression } from "./option-filter.js";
 let depsPromise;
-const loadRemarkDeps = () => {
+const loadRemarkDeps = ()=>{
     if (!depsPromise) {
-        depsPromise = (async () => ({
-            unified: (await Promise.resolve().then(() => tslib_1.__importStar(require('unified')))).unified,
-            remarkParse: (await Promise.resolve().then(() => tslib_1.__importStar(require('remark-parse')))).default,
-            remarkMdx: (await Promise.resolve().then(() => tslib_1.__importStar(require('remark-mdx')))).default,
-            remarkStringify: (await Promise.resolve().then(() => tslib_1.__importStar(require('remark-stringify')))).default,
-            remarkFrontmatter: (await Promise.resolve().then(() => tslib_1.__importStar(require('remark-frontmatter')))).default,
-        }))();
+        depsPromise = (async ()=>({
+                unified: (await import("unified")).unified,
+                remarkParse: (await import("remark-parse")).default,
+                remarkMdx: (await import("remark-mdx")).default,
+                remarkStringify: (await import("remark-stringify")).default,
+                remarkFrontmatter: (await import("remark-frontmatter")).default
+            }))();
     }
     return depsPromise;
 };
-const parseMdxWithDeps = (source, deps) => deps
-    .unified()
-    .use(deps.remarkParse)
-    .use(deps.remarkFrontmatter)
-    .use(deps.remarkMdx)
-    .parse(source);
+const parseMdxWithDeps = (source, deps)=>deps.unified().use(deps.remarkParse).use(deps.remarkFrontmatter).use(deps.remarkMdx).parse(source);
 /** Parse MDX (with frontmatter) into mdast. Exposed so callers like
- *  `fetchGuideFrontmatters` don't need to re-load remark themselves. */
-const parseMdx = async (source) => {
+ *  `fetchGuideFrontmatters` don't need to re-load remark themselves. */ export const parseMdx = async (source)=>{
     const deps = await loadRemarkDeps();
     return parseMdxWithDeps(source, deps);
 };
-exports.parseMdx = parseMdx;
-const stringifyMdx = (tree, deps) => String(deps
-    .unified()
-    .use(deps.remarkFrontmatter)
-    .use(deps.remarkMdx)
-    .use(deps.remarkStringify, {
-    bullet: '-',
-    fences: true,
-    listItemIndent: 'one',
-})
-    .stringify(tree));
-const postProcessGuideWithRemark = async (guide, opts) => {
+const stringifyMdx = (tree, deps)=>String(deps.unified().use(deps.remarkFrontmatter).use(deps.remarkMdx).use(deps.remarkStringify, {
+        bullet: '-',
+        fences: true,
+        listItemIndent: 'one'
+    }).stringify(tree));
+/**
+ * Remove nodes that are meaningless once the MDX is rendered to plain markdown
+ * for an agent: the YAML frontmatter block and the `import`/`export` (ESM)
+ * statements at the top of every docs page. They add noise and tokens without
+ * conveying guidance.
+ */ const stripFrontmatterAndEsm = (tree)=>{
+    tree.children = tree.children.filter((node)=>node.type !== 'yaml' && node.type !== 'mdxjsEsm');
+};
+export const postProcessGuideWithRemark = async (guide, opts)=>{
     const deps = await loadRemarkDeps();
     const tree = parseMdxWithDeps(guide, deps);
     await inlineSnippets(tree, opts, deps);
     applyFilterTransforms(tree, opts.options);
     applyComponentTransforms(tree, opts, deps);
+    stripFrontmatterAndEsm(tree);
     return stringifyMdx(tree, deps);
 };
-exports.postProcessGuideWithRemark = postProcessGuideWithRemark;
-const inlineSnippets = async (tree, opts, deps) => {
+const inlineSnippets = async (tree, opts, deps)=>{
     const provider = opts.snippetContentProvider;
-    if (!provider)
-        return;
+    if (!provider) return;
     const pending = [];
-    const walk = (parent) => {
+    const walk = (parent)=>{
         const children = parent.children;
-        for (let i = 0; i < children.length; i++) {
+        for(let i = 0; i < children.length; i++){
             const child = children[i];
-            if (!(0, mdx_ast_1.isJsxElement)(child))
-                continue;
+            if (!isJsxElement(child)) continue;
             if (child.name === 'Snippet') {
-                const name = (0, mdx_ast_1.readStringAttr)(child, 'name');
-                if (name)
-                    pending.push({ parent, index: i, name, node: child });
+                const name = readStringAttr(child, 'name');
+                if (name) pending.push({
+                    parent,
+                    index: i,
+                    name,
+                    node: child
+                });
                 continue;
             }
             walk(child);
         }
     };
     walk(tree);
-    if (pending.length === 0)
-        return;
-    const fetched = await Promise.all(pending.map(async (p) => {
+    if (pending.length === 0) return;
+    const fetched = await Promise.all(pending.map(async (p)=>{
         let raw = '';
         try {
             raw = await provider(p.name);
-        }
-        catch {
+        } catch  {
             raw = '';
         }
-        if (!raw)
-            return { ...p, replacement: undefined };
-        const processed = await (0, exports.postProcessGuideWithRemark)(raw.trim(), opts);
-        return { ...p, replacement: processed };
+        if (!raw) return {
+            ...p,
+            replacement: undefined
+        };
+        const processed = await postProcessGuideWithRemark(raw.trim(), opts);
+        return {
+            ...p,
+            replacement: processed
+        };
     }));
     // Splice in descending index order per parent so earlier indices stay valid.
     const byParent = new Map();
-    for (const f of fetched) {
+    for (const f of fetched){
         const bucket = byParent.get(f.parent) ?? [];
         bucket.push(f);
         byParent.set(f.parent, bucket);
     }
-    for (const [parent, items] of byParent) {
-        items.sort((a, b) => b.index - a.index);
-        for (const { index, name, replacement, node } of items) {
-            if (replacement === undefined)
-                continue;
+    for (const [parent, items] of byParent){
+        items.sort((a, b)=>b.index - a.index);
+        for (const { index, name, replacement, node } of items){
+            if (replacement === undefined) continue;
             const snippetTree = parseMdxWithDeps(replacement, deps);
             const wrapper = {
                 type: 'mdxJsxFlowElement',
                 name: 'Snippet',
-                attributes: [{ type: 'mdxJsxAttribute', name: 'name', value: name }],
-                children: snippetTree.children,
+                attributes: [
+                    {
+                        type: 'mdxJsxAttribute',
+                        name: 'name',
+                        value: name
+                    }
+                ],
+                children: snippetTree.children
             };
             if ('position' in node && node.position) {
                 wrapper.position = node.position;
@@ -118,29 +119,24 @@ const inlineSnippets = async (tree, opts, deps) => {
         }
     }
 };
-const applyFilterTransforms = (tree, options) => {
+const applyFilterTransforms = (tree, options)=>{
     const iac = options?.iac;
-    const transform = (parent) => {
+    const transform = (parent)=>{
         const children = parent.children;
-        for (let i = 0; i < children.length; i++) {
+        for(let i = 0; i < children.length; i++){
             const child = children[i];
-            if (!(0, mdx_ast_1.isJsxElement)(child))
-                continue;
+            if (!isJsxElement(child)) continue;
             if (child.name === 'OptionFilter') {
                 const when = parseWhenAttr(child);
-                if (!when)
-                    continue; // malformed — leave alone
+                if (!when) continue; // malformed — leave alone
                 // Recurse first so nested filters collapse before we replace this wrapper.
                 transform(child);
-                const not = (0, mdx_ast_1.hasBareAttr)(child, 'not');
+                const not = hasBareAttr(child, 'not');
                 if (options) {
-                    const replacement = (0, option_filter_1.evaluatePredicate)(when, not, options)
-                        ? child.children
-                        : [];
+                    const replacement = evaluatePredicate(when, not, options) ? child.children : [];
                     children.splice(i, 1, ...replacement);
                     i += replacement.length - 1;
-                }
-                else {
+                } else {
                     children.splice(i, 1, buildNoteQuote(child, when, not));
                 }
                 continue;
@@ -152,7 +148,7 @@ const applyFilterTransforms = (tree, options) => {
                         type: 'mdxJsxFlowElement',
                         name: 'tmp',
                         attributes: [],
-                        children: body,
+                        children: body
                     };
                     transform(pseudo);
                     children.splice(i, 1, ...pseudo.children);
@@ -172,7 +168,7 @@ const applyFilterTransforms = (tree, options) => {
                     continue;
                 }
                 if (dropped === 'inline') {
-                    const survivor = child.children.find((c) => (0, mdx_ast_1.isJsxElement)(c) && c.name === 'TabItem');
+                    const survivor = child.children.find((c)=>isJsxElement(c) && c.name === 'TabItem');
                     const body = survivor.children;
                     children.splice(i, 1, ...body);
                     i += body.length - 1;
@@ -185,11 +181,9 @@ const applyFilterTransforms = (tree, options) => {
     };
     transform(tree);
 };
-const selectInfrastructureSlot = (node, iac) => {
+const selectInfrastructureSlot = (node, iac)=>{
     const slotName = iac.toLowerCase();
-    const frag = node.children.find((c) => (0, mdx_ast_1.isJsxElement)(c) &&
-        c.name === 'Fragment' &&
-        (0, mdx_ast_1.readStringAttr)(c, 'slot') === slotName);
+    const frag = node.children.find((c)=>isJsxElement(c) && c.name === 'Fragment' && readStringAttr(c, 'slot') === slotName);
     return frag?.children ?? [];
 };
 /**
@@ -198,17 +192,16 @@ const selectInfrastructureSlot = (node, iac) => {
  *   - `'inline'` if exactly one filtered <TabItem> survived — caller
  *     inlines the body so agents see just the picked variant.
  *   - `'keep'` otherwise.
- */
-const applyTabsFilter = (tabs, options) => {
+ */ const applyTabsFilter = (tabs, options)=>{
     const children = tabs.children;
     const surviving = [];
     let anyFiltered = false;
-    for (const child of children) {
-        if (!(0, mdx_ast_1.isJsxElement)(child) || child.name !== 'TabItem') {
+    for (const child of children){
+        if (!isJsxElement(child) || child.name !== 'TabItem') {
             surviving.push(child);
             continue;
         }
-        const filterEstree = (0, mdx_ast_1.readEstreeAttr)(child, '_filter');
+        const filterEstree = readEstreeAttr(child, '_filter');
         if (!filterEstree) {
             surviving.push(child);
             continue;
@@ -216,14 +209,13 @@ const applyTabsFilter = (tabs, options) => {
         anyFiltered = true;
         let predicate;
         try {
-            predicate = (0, option_filter_1.parseWhenExpression)(filterEstree);
-        }
-        catch {
+            predicate = parseWhenExpression(filterEstree);
+        } catch  {
             stripFilterAttr(child);
             surviving.push(child);
             continue;
         }
-        if (!options || (0, option_filter_1.evaluatePredicate)(predicate, false, options)) {
+        if (!options || evaluatePredicate(predicate, false, options)) {
             stripFilterAttr(child);
             surviving.push(child);
         }
@@ -231,52 +223,55 @@ const applyTabsFilter = (tabs, options) => {
     if (anyFiltered) {
         tabs.children = surviving;
     }
-    const tabItems = surviving.filter((c) => (0, mdx_ast_1.isJsxElement)(c) && c.name === 'TabItem');
-    if (tabItems.length === 0 && surviving.length === 0)
-        return 'empty';
-    if (anyFiltered && tabItems.length === 1)
-        return 'inline';
+    const tabItems = surviving.filter((c)=>isJsxElement(c) && c.name === 'TabItem');
+    if (tabItems.length === 0 && surviving.length === 0) return 'empty';
+    if (anyFiltered && tabItems.length === 1) return 'inline';
     return 'keep';
 };
-const stripFilterAttr = (el) => {
-    el.attributes = el.attributes.filter((a) => !(a.type === 'mdxJsxAttribute' && a.name === '_filter'));
+const stripFilterAttr = (el)=>{
+    el.attributes = el.attributes.filter((a)=>!(a.type === 'mdxJsxAttribute' && a.name === '_filter'));
 };
 /**
  * `> [!NOTE] Only when …` blockquote. The alert header goes through as an
  * `html` node so remark-stringify doesn't escape the `[`/`]` brackets —
  * downstream agents match on the literal GitHub alert syntax.
- */
-const buildNoteQuote = (source, predicate, not) => {
-    const marker = (0, option_filter_1.describePredicate)(predicate, not);
-    const description = (0, mdx_ast_1.readStringAttr)(source, 'description');
-    const headerLines = description
-        ? [`[!NOTE] ${marker}`, description]
-        : [`[!NOTE] ${marker}`];
-    const headerNodes = headerLines.map((line) => ({ type: 'html', value: line }));
+ */ const buildNoteQuote = (source, predicate, not)=>{
+    const marker = describePredicate(predicate, not);
+    const description = readStringAttr(source, 'description');
+    const headerLines = description ? [
+        `[!NOTE] ${marker}`,
+        description
+    ] : [
+        `[!NOTE] ${marker}`
+    ];
+    const headerNodes = headerLines.map((line)=>({
+            type: 'html',
+            value: line
+        }));
     return {
         type: 'blockquote',
-        children: [...headerNodes, ...source.children],
+        children: [
+            ...headerNodes,
+            ...source.children
+        ]
     };
 };
-const parseWhenAttr = (node) => {
-    const estree = (0, mdx_ast_1.readEstreeAttr)(node, 'when');
-    if (!estree)
-        return undefined;
+const parseWhenAttr = (node)=>{
+    const estree = readEstreeAttr(node, 'when');
+    if (!estree) return undefined;
     try {
-        return (0, option_filter_1.parseWhenExpression)(estree);
-    }
-    catch {
+        return parseWhenExpression(estree);
+    } catch  {
         return undefined;
     }
 };
-const applyComponentTransforms = (tree, opts, deps) => {
+const applyComponentTransforms = (tree, opts, deps)=>{
     const pm = opts.packageManager ?? 'pnpm';
-    const transform = (parent) => {
+    const transform = (parent)=>{
         const children = parent.children;
-        for (let i = 0; i < children.length; i++) {
+        for(let i = 0; i < children.length; i++){
             const child = children[i];
-            if (!(0, mdx_ast_1.isJsxElement)(child))
-                continue;
+            if (!isJsxElement(child)) continue;
             const replacement = renderComponent(child, opts, pm, deps);
             if (replacement !== undefined) {
                 children.splice(i, 1, ...replacement);
@@ -288,104 +283,102 @@ const applyComponentTransforms = (tree, opts, deps) => {
     };
     transform(tree);
 };
-const renderComponent = (node, opts, pm, deps) => {
-    switch (node.name) {
-        case 'NxCommands': {
-            const commands = readCommandsAttr(node);
-            if (!commands)
-                return undefined;
-            return [
-                codeBlock(commands
-                    .map((c) => (0, guide_render_1.buildNxCommand)(c, opts.packageManager))
-                    .join('\n')),
-            ];
-        }
-        case 'RunGenerator': {
-            const generatorId = (0, mdx_ast_1.readStringAttr)(node, 'generator');
-            if (!generatorId)
-                return undefined;
-            const schema = findSchema(opts.generators, generatorId);
-            if (!schema)
-                return undefined;
-            return parseMarkdownFragment((0, guide_render_1.renderGeneratorCommand)(generatorId, schema, opts.packageManager), deps);
-        }
-        case 'GeneratorParameters': {
-            const generatorId = (0, mdx_ast_1.readStringAttr)(node, 'generator');
-            if (!generatorId)
-                return undefined;
-            const schema = findSchema(opts.generators, generatorId);
-            if (!schema)
-                return undefined;
-            return parseMarkdownFragment((0, guide_render_1.renderSchema)(schema), deps);
-        }
-        case 'CreateNxWorkspaceCommand': {
-            const workspace = (0, mdx_ast_1.readStringAttr)(node, 'workspace');
-            if (!workspace)
-                return undefined;
-            const iac = (0, mdx_ast_1.readStringAttr)(node, 'iac');
-            return [codeBlock((0, commands_1.buildCreateNxWorkspaceCommand)(pm, workspace, iac))];
-        }
-        case 'InstallCommand': {
-            const pkg = (0, mdx_ast_1.readStringAttr)(node, 'pkg') ?? (0, mdx_ast_1.readExpressionAttr)(node, 'pkg');
-            if (!pkg)
-                return undefined;
-            return [
-                codeBlock((0, commands_1.buildInstallCommand)(pm, pkg, (0, mdx_ast_1.hasBareAttr)(node, 'dev'))),
-            ];
-        }
-        case 'PackageManagerShortCommand': {
-            const commands = readCommandsAttr(node);
-            if (!commands)
-                return undefined;
-            return [
-                codeBlock(commands
-                    .map((c) => (0, commands_1.buildPackageManagerShortCommand)(pm, c))
-                    .join('\n')),
-            ];
-        }
-        case 'PackageManagerExecCommand': {
-            const commands = readCommandsAttr(node);
-            if (!commands)
-                return undefined;
-            return [
-                codeBlock(commands.map((c) => (0, commands_1.buildPackageManagerExecCommand)(pm, c)).join('\n')),
-            ];
-        }
+const renderComponent = (node, opts, pm, deps)=>{
+    switch(node.name){
+        case 'NxCommands':
+            {
+                const commands = readCommandsAttr(node);
+                if (!commands) return undefined;
+                return [
+                    codeBlock(commands.map((c)=>buildNxCommand(c, opts.packageManager)).join('\n'))
+                ];
+            }
+        case 'RunGenerator':
+            {
+                const generatorId = readStringAttr(node, 'generator');
+                if (!generatorId) return undefined;
+                const schema = findSchema(opts.generators, generatorId);
+                if (!schema) return undefined;
+                return parseMarkdownFragment(renderGeneratorCommand(generatorId, schema, opts.packageManager), deps);
+            }
+        case 'GeneratorParameters':
+            {
+                const generatorId = readStringAttr(node, 'generator');
+                if (!generatorId) return undefined;
+                const schema = findSchema(opts.generators, generatorId);
+                if (!schema) return undefined;
+                return parseMarkdownFragment(renderSchema(schema), deps);
+            }
+        case 'CreateNxWorkspaceCommand':
+            {
+                const workspace = readStringAttr(node, 'workspace');
+                if (!workspace) return undefined;
+                const iac = readStringAttr(node, 'iac');
+                return [
+                    codeBlock(buildCreateNxWorkspaceCommand(pm, workspace, iac))
+                ];
+            }
+        case 'NxInitCommand':
+            {
+                return [
+                    codeBlock(buildNxInitCommand(pm))
+                ];
+            }
+        case 'InstallCommand':
+            {
+                // Without `pkg`, installs the workspace's existing dependencies
+                const pkg = readStringAttr(node, 'pkg') ?? readExpressionAttr(node, 'pkg');
+                return [
+                    codeBlock(buildInstallCommand(pm, pkg, hasBareAttr(node, 'dev')))
+                ];
+            }
+        case 'PackageManagerShortCommand':
+            {
+                const commands = readCommandsAttr(node);
+                if (!commands) return undefined;
+                return [
+                    codeBlock(commands.map((c)=>buildPackageManagerShortCommand(pm, c)).join('\n'))
+                ];
+            }
+        case 'PackageManagerExecCommand':
+            {
+                const commands = readCommandsAttr(node);
+                if (!commands) return undefined;
+                return [
+                    codeBlock(commands.map((c)=>buildPackageManagerExecCommand(pm, c)).join('\n'))
+                ];
+            }
         default:
             return undefined;
     }
 };
-const codeBlock = (body) => ({
-    type: 'code',
-    lang: 'bash',
-    value: body,
-});
-const parseMarkdownFragment = (markdown, deps) => {
+const codeBlock = (body)=>({
+        type: 'code',
+        lang: 'bash',
+        value: body
+    });
+const parseMarkdownFragment = (markdown, deps)=>{
     const fragTree = deps.unified().use(deps.remarkParse).parse(markdown);
     return fragTree.children;
 };
-const findSchema = (generators, generatorId) => {
-    const info = generators.find((g) => g.id === generatorId);
-    if (!info)
-        return undefined;
+const findSchema = (generators, generatorId)=>{
+    const info = generators.find((g)=>g.id === generatorId);
+    if (!info) return undefined;
     try {
-        return JSON.parse(fs_1.default.readFileSync(info.resolvedSchemaPath, 'utf-8'));
-    }
-    catch {
+        return JSON.parse(fs.readFileSync(info.resolvedSchemaPath, 'utf-8'));
+    } catch  {
         return undefined;
     }
 };
 /** Parse the `commands={[…]}` attribute from the estree that remark-mdx
- *  attaches to the JSX attribute value. */
-const readCommandsAttr = (node) => {
-    const estree = (0, mdx_ast_1.readEstreeAttr)(node, 'commands');
-    if (!estree)
-        return undefined;
+ *  attaches to the JSX attribute value. */ const readCommandsAttr = (node)=>{
+    const estree = readEstreeAttr(node, 'commands');
+    if (!estree) return undefined;
     try {
-        return (0, option_filter_1.extractStringArrayExpression)(estree);
-    }
-    catch {
+        return extractStringArrayExpression(estree);
+    } catch  {
         return undefined;
     }
 };
+
 //# sourceMappingURL=guide-pipeline.js.map