@taiga-ai/mcp-server 0.25.0-rc.474 → 0.26.0-dev.479

package/src/tools/markdown.test.ts

@@ -1,249 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { fence, nestHeadings, renderDocument } from './markdown.js';
-
-describe('fence', () => {
-  it('is one backtick longer than the longest run inside the body, four at least', () => {
-    expect(fence('markdown', 'plain')).toBe('````markdown\nplain\n````');
-    expect(fence('markdown', 'a ````` five-run inside')).toBe('``````markdown\na ````` five-run inside\n``````');
-    // Two hundred thousand runs would overflow a spread into Math.max.
-    expect(fence('text', '` '.repeat(200_000)).startsWith('````text\n')).toBe(true);
-  });
-});
-
-describe('renderDocument', () => {
-  it('renders a section map as a titled Markdown document with one heading per section', () => {
-    const rendered = renderDocument({
-      name: 'Security Policy',
-      type: 'policy_security',
-      version: 3,
-      data: {
-        sections: {
-          summary: { source: 'template', priority: 'core', content: '  Controls for code.  ' },
-          scope: { title: 'Scope of the policy', content: 'Everything.' },
-          legacy: 'bare text',
-        },
-      },
-    });
-
-    expect(rendered.mimeType).toBe('text/markdown');
-    expect(rendered.text).toBe(
-      [
-        '# Security Policy',
-        '',
-        'type: policy_security | version: 3 | core sections: summary',
-        '',
-        '## summary',
-        '',
-        'Controls for code.',
-        '',
-        '## Scope of the policy',
-        '',
-        'Everything.',
-        '',
-        '## legacy',
-        '',
-        'bare text',
-        '',
-      ].join('\n')
-    );
-  });
-
-  it('tracks fences as CommonMark does: indented, longer closers, info strings, and headings indented up to three spaces', () => {
-    const body = [
-      '````',
-      '```',
-      '# inside a four-tick fence: a three-tick line does not close it',
-      '`````',
-      '## after a five-tick closer',
-      '   ```sh',
-      '# indented opener',
-      '   ```',
-      '  ## indented heading',
-      '    # four spaces is code, not a heading',
-      '```',
-      '```sh',
-      '# an opener-with-info inside an open fence is not its closer',
-      '```',
-      '## out again',
-      '```json``` is not a fence opener',
-      '## still a heading',
-      '~~~',
-      '```',
-      '# backticks inside a tilde fence',
-      '~~~',
-      '## last',
-    ].join('\n');
-
-    expect(nestHeadings(body)).toBe(
-      [
-        '````',
-        '```',
-        '# inside a four-tick fence: a three-tick line does not close it',
-        '`````',
-        '### after a five-tick closer',
-        '   ```sh',
-        '# indented opener',
-        '   ```',
-        '  ### indented heading',
-        '    # four spaces is code, not a heading',
-        '```',
-        '```sh',
-        '# an opener-with-info inside an open fence is not its closer',
-        '```',
-        '### out again',
-        '```json``` is not a fence opener',
-        '### still a heading',
-        '~~~',
-        '```',
-        '# backticks inside a tilde fence',
-        '~~~',
-        '### last',
-      ].join('\n')
-    );
-  });
-
-  it("edits by the parser's offsets: CRLF and lone CR line endings, a tab after a container marker, an empty heading, an HTML block, deep nesting", () => {
-    expect(nestHeadings('```\r\n# in\r\n```\r\n# out')).toBe('```\r\n# in\r\n```\r\n### out');
-    expect(nestHeadings('x\ry\n# h\n## i')).toBe('x\ry\n### h\n### i');
-    expect(nestHeadings('>\t# q\n-\t# x')).toBe('>\t### q\n-\t### x');
-    expect(nestHeadings('#\n##\n# x')).toBe('###\n###\n### x');
-    // A heading-shaped line inside an HTML block is HTML to a CommonMark reader, so it stays.
-    expect(nestHeadings('<details>\n<summary>s</summary>\n## inside\n</details>\n\n## after')).toBe(
-      '<details>\n<summary>s</summary>\n## inside\n</details>\n\n### after'
-    );
-    // Deeper than a recursive walk could take: nested quotes, which the
-    // parser handles in milliseconds (nested list markers it does not).
-    const deep = `${'> '.repeat(20_000)}# deep`;
-    expect(nestHeadings(deep)).toBe(`${'> '.repeat(20_000)}### deep`);
-  });
-
-  it('turns a setext heading into the ATX heading one level down, inside a quote too, and leaves a thematic break alone', () => {
-    expect(nestHeadings('> Quoted\n> ---\ntext\n\n---\n\nAfter\n===')).toBe('> ### Quoted\ntext\n\n---\n\n### After');
-    // Serialized from the parsed content: a quote's prefix on a continuation
-    // line, a hard line break, a leading # that is not an ATX marker, a
-    // trailing # run that would read as a closing sequence, inline markup.
-    expect(nestHeadings('> A\n> B\n> ---')).toBe('> ### A B');
-    expect(nestHeadings('> > A\n> > B\n> > ===')).toBe('> > ### A B');
-    expect(nestHeadings('Title\\\ntwo\n---')).toBe('### Title two');
-    expect(nestHeadings('#1 priority\n===')).toBe('### #1 priority');
-    expect(nestHeadings('Title ##\n---')).toBe('### Title #\\#');
-    expect(nestHeadings('*em* and `code` [l](u)\n===')).toBe('### *em* and `code` [l](u)');
-  });
-
-  it('reads containers as CommonMark does: a fence in a list item, headings in list items and quotes, a setext heading', () => {
-    const body = [
-      '- ```md',
-      '  # literal inside a fence that a list item opened',
-      '  ```',
-      '- ## in a list item',
-      '> ## quoted',
-      '>     # indented code inside a quote',
-      'Setext',
-      '======',
-      'Two line',
-      'setext two',
-      '---',
-      '## atx after',
-    ].join('\n');
-
-    expect(nestHeadings(body)).toBe(
-      [
-        '- ```md',
-        '  # literal inside a fence that a list item opened',
-        '  ```',
-        '- ### in a list item',
-        '> ### quoted',
-        '>     # indented code inside a quote',
-        '### Setext',
-        '### Two line setext two',
-        '### atx after',
-      ].join('\n')
-    );
-  });
-
-  it("nests a section body's own headings under the section heading, leaving fenced code alone", () => {
-    const rendered = renderDocument({
-      name: 'Threat Model',
-      type: 'threat_model',
-      data: {
-        sections: {
-          overview: {
-            content: [
-              '# Overview',
-              'Text.',
-              '## Attack vectors',
-              '##### Deep',
-              '###### Deepest stays',
-              '```md',
-              '# not a heading',
-              '```',
-              '~~~',
-              '## nor this',
-              '~~~',
-              '## After the fences',
-              '#hashtag is not a heading',
-            ].join('\n'),
-          },
-        },
-      },
-    });
-
-    expect(rendered.text).toBe(
-      [
-        '# Threat Model',
-        '',
-        'type: threat_model',
-        '',
-        '## overview',
-        '',
-        '### Overview',
-        'Text.',
-        '### Attack vectors',
-        '###### Deep',
-        '###### Deepest stays',
-        '```md',
-        '# not a heading',
-        '```',
-        '~~~',
-        '## nor this',
-        '~~~',
-        '### After the fences',
-        '#hashtag is not a heading',
-        '',
-      ].join('\n')
-    );
-  });
-
-  it('carries what sits beside the sections as JSON, so nothing is lost', () => {
-    const rendered = renderDocument({
-      name: 'Design Standards',
-      type: 'design_standards',
-      data: { sections: { summary: { content: 'Colors.' } }, tokens: { primary: '#000' } },
-    });
-
-    expect(rendered.text).toContain('## Other data\n\n````json\n{\n  "tokens": {\n    "primary": "#000"\n  }\n}\n````');
-  });
-
-  it('describes large data beside the sections instead of inlining it, and skips empty keys', () => {
-    const rendered = renderDocument({
-      name: 'Design Standards',
-      type: 'design_standards',
-      data: { sections: { summary: { content: 'Colors.' } }, tokens: null, components: { big: 'x'.repeat(25_000) } },
-    });
-
-    expect(rendered.text).toContain('## Other data');
-    expect(rendered.text).toContain(
-      'Beside its sections this document carries components (25010 characters); read them with the get tool as JSON.'
-    );
-    expect(rendered.text).not.toContain('tokens');
-  });
-
-  it('hands over a document that is not a section map as JSON', () => {
-    const doc = { type: 'ui_direction', version: 1, data: { picks: { palette: 'ocean' } } };
-
-    const rendered = renderDocument(doc);
-
-    expect(rendered.mimeType).toBe('application/json');
-    expect(JSON.parse(rendered.text)).toEqual(doc);
-  });
-});

package/src/tools/markdown.ts

@@ -1,151 +0,0 @@
-import { fromMarkdown } from 'mdast-util-from-markdown';
-import { toMarkdown } from 'mdast-util-to-markdown';
-import type { Heading, Node, Parent, PhrasingContent } from 'mdast';
-import { isRecord, isSectionObject, sectionContent, sectionsOf, type StoredDocument } from './sections.js';
-
-/** A document as rendered: its data, and the facts its title and header line name. */
-interface RenderedDocument extends StoredDocument {
-  name?: unknown;
-  type?: unknown;
-}
-
-/**
- * A document as text an IDE can attach: the name as the title, one line of
- * facts, each section as a heading with its text. Policies, instructions and
- * product documents are section maps; what a document carries beside its
- * sections (design tokens, components) follows as JSON or, past a size, is
- * described, and a document that is no section map at all is handed over as
- * JSON.
- */
-export function renderDocument(doc: RenderedDocument): { mimeType: string; text: string } {
-  const data = isRecord(doc.data) ? doc.data : null;
-  const sections = data ? sectionsOf(data) : null;
-  if (!data || !sections) return { mimeType: 'application/json', text: JSON.stringify(doc, null, 2) };
-
-  const title = typeof doc.name === 'string' ? doc.name : String(doc.type ?? 'Document');
-  const lines = [`# ${title}`];
-  const facts = (['type', 'origin', 'version', 'stage', 'derivationOutdated'] as const)
-    .filter((key) => doc[key] !== undefined && doc[key] !== null)
-    .map((key) => `${key}: ${String(doc[key])}`);
-  // Which sections are core is stated here, from metadata, not marked in
-  // the headings: a heading is text a section could forge, this line is not.
-  const core = Object.keys(sections).filter((id) => {
-    const section = sections[id];
-    return isSectionObject(section) && section.priority === 'core';
-  });
-  if (core.length > 0) facts.push(`core sections: ${core.join(', ')}`);
-  if (facts.length > 0) lines.push('', facts.join(' | '));
-  for (const id of Object.keys(sections)) {
-    const content = sectionContent(sections, id);
-    if (content === null) continue;
-    lines.push('', `## ${sectionTitle(sections[id], id)}`, '', nestHeadings(content.trim()));
-  }
-  const { sections: _sections, ...rest } = data;
-  const other = Object.fromEntries(Object.entries(rest).filter(([, value]) => !isEmpty(value)));
-  if (Object.keys(other).length > 0) {
-    const json = JSON.stringify(other, null, 2);
-    lines.push('', '## Other data', '');
-    if (json.length > OTHER_DATA_LIMIT) {
-      // Design tokens and component sources run to hundreds of kilobytes;
-      // an attachment is not the place for them.
-      const keys = Object.entries(other).map(([key, value]) => `${key} (${JSON.stringify(value).length} characters)`);
-      lines.push(`Beside its sections this document carries ${keys.join(', ')}; read them with the get tool as JSON.`);
-    } else {
-      lines.push(fence('json', json));
-    }
-  }
-  return { mimeType: 'text/markdown', text: `${lines.join('\n')}\n` };
-}
-
-/** Past this many characters, data beside the sections is described, not inlined. */
-const OTHER_DATA_LIMIT = 20_000;
-
-const isEmpty = (value: unknown) =>
-  value === null ||
-  value === undefined ||
-  (Array.isArray(value) && value.length === 0) ||
-  (isRecord(value) && Object.keys(value).length === 0);
-
-/**
- * A section body's own headings, one level down, so they sit under the
- * section heading instead of beside it: a derived document writes each
- * section with its own H2. A CommonMark parser says what is a heading, so
- * fenced code, indented code, list items and block quotes are read as a
- * reader's renderer reads them, and a heading-shaped line inside an HTML
- * block is HTML, not a heading, and stays. Every heading lands at least one
- * level under the section's H2, so an H1 and an H2 both become H3 and the
- * rest move one down, H6 at most: an ATX heading (the # kind, an empty one
- * included) takes the marks it needs; a setext heading (underlined)
- * becomes the ATX heading of that depth, serialized from its parsed
- * content (so a quote's prefix, a hard line break or a trailing # run are
- * handled as Markdown, not as text). The edits go by the parser's
- * character offsets, so no line counting of ours can disagree with its own.
- */
-export function nestHeadings(body: string): string {
-  const edits: { start: number; end: number; text: string }[] = [];
-  // An explicit stack, and no spread into push: a body of thousands of
-  // nested quotes, or a list of very many items, must not overflow a walk.
-  const pending: Node[] = [fromMarkdown(body)];
-  while (pending.length > 0) {
-    const node = pending.pop()!;
-    if (
-      node.type === 'heading' &&
-      node.position?.start.offset !== undefined &&
-      node.position.end.offset !== undefined
-    ) {
-      const start = node.position.start.offset;
-      const end = node.position.end.offset;
-      const heading = node as Heading;
-      const target = nestedDepth(heading.depth);
-      const atx = /^#{1,6}(\s|$)/.test(body.slice(start, start + 7));
-      if (atx && target > heading.depth) edits.push({ start, end: start, text: '#'.repeat(target - heading.depth) });
-      else if (!atx) edits.push({ start, end, text: atxOf(target, heading.children) });
-    }
-    if ('children' in node) for (const child of (node as Parent).children) pending.push(child);
-  }
-  let out = body;
-  for (const edit of edits.sort((a, b) => b.start - a.start)) {
-    out = `${out.slice(0, edit.start)}${edit.text}${out.slice(edit.end)}`;
-  }
-  return out;
-}
-
-/** Under the section's H2: at least H3, one level down otherwise, H6 at most. */
-const nestedDepth = (depth: number): Heading['depth'] => Math.min(6, Math.max(3, depth + 1)) as Heading['depth'];
-
-/** An ATX heading of this depth from parsed content, its line breaks turned into spaces: an ATX heading is one line. */
-function atxOf(depth: Heading['depth'], children: PhrasingContent[]): string {
-  const oneLine = (nodes: PhrasingContent[]): PhrasingContent[] =>
-    nodes.map((child) => {
-      if (child.type === 'break') return { type: 'text', value: ' ' };
-      if (child.type === 'text') return { ...child, value: child.value.replace(/\r\n|\r|\n/g, ' ') };
-      return 'children' in child ? { ...child, children: oneLine(child.children as PhrasingContent[]) } : child;
-    });
-  return toMarkdown({ type: 'heading', depth, children: oneLine(children) }).trimEnd();
-}
-
-/** The section's title when it carries one, else its id. */
-function sectionTitle(section: unknown, id: string): string {
-  return isSectionObject(section) && typeof section.title === 'string' && section.title.trim()
-    ? section.title.trim()
-    : id;
-}
-
-/** The mime type a read will answer with, for a list entry that must not disagree with it. */
-export function mimeTypeOf(doc: StoredDocument): string {
-  const data = isRecord(doc.data) ? doc.data : null;
-  return data && sectionsOf(data) ? 'text/markdown' : 'application/json';
-}
-
-/**
- * A fence the body cannot close: one backtick longer than the longest run
- * inside it, four at least.
- */
-export function fence(lang: string, body: string): string {
-  // A loop, not a spread into Math.max: a document with very many backtick
-  // runs would exceed the argument limit and throw.
-  let longest = 0;
-  for (const match of body.matchAll(/`+/g)) longest = Math.max(longest, match[0].length);
-  const marks = '`'.repeat(Math.max(4, longest + 1));
-  return `${marks}${lang}\n${body.trim()}\n${marks}`;
-}