@art-md/constructs 0.0.1 → 0.0.3

package/src/parser/fields/stripStrong.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it, vi } from 'vitest';
+
+// eslint-disable-next-line import/order
+import { rawSliceMock } from '../../test/helpers';
+// eslint-disable-next-line import/order
+import { rawSlice } from '../mdast';
+
+import { stripStrong } from './stripStrong';
+
+vi.mock('../mdast', () => {
+	return rawSliceMock();
+});
+
+describe('stripStrong', () => {
+	it('WHEN stripping ** wrappers', () => {
+		vi.mocked(rawSlice).mockReturnValue('**hello**');
+
+		const result = stripStrong({ type: 'strong', children: [] }, { markdown: '' } as never);
+
+		expect(result).toBe('hello');
+	});
+
+	it('WHEN stripping __ wrappers', () => {
+		vi.mocked(rawSlice).mockReturnValue('__hello__');
+
+		const result = stripStrong({ type: 'strong', children: [] }, { markdown: '' } as never);
+
+		expect(result).toBe('hello');
+	});
+
+	it('WHEN not wrapped returns raw', () => {
+		vi.mocked(rawSlice).mockReturnValue('hello');
+
+		const result = stripStrong({ type: 'strong', children: [] }, { markdown: '' } as never);
+
+		expect(result).toBe('hello');
+	});
+});

package/src/parser/fields/stripStrong.ts

@@ -0,0 +1,12 @@
+import type { ParserVisitContext } from '@art-md/primitives';
+import type { Strong } from 'mdast';
+
+import { rawSlice } from '../mdast';
+
+export function stripStrong(node: Strong, context: ParserVisitContext): string {
+	const raw = rawSlice(node, context);
+	return raw.length >= 4 &&
+		((raw.startsWith('**') && raw.endsWith('**')) || (raw.startsWith('__') && raw.endsWith('__')))
+		? raw.slice(2, -2)
+		: raw;
+}

package/src/parser/index.ts

@@ -0,0 +1,8 @@
+export { createArtDocumentFromNode } from './document';
+
+export * from './constructs/FieldBlock';
+export * from './constructs/FieldInline';
+export * from './constructs/NaturalBlock';
+export * from './constructs/SectionBlock';
+
+export type * from './types';

package/src/parser/mdast/index.ts

@@ -0,0 +1 @@
+export { rawSlice } from './rawSlice';

package/src/parser/mdast/rawSlice.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+
+import { rawSlice } from './rawSlice';
+
+describe('rawSlice', () => {
+	it('FOR a node with position returns the raw slice', () => {
+		const node = {
+			type: 'text',
+			position: {
+				start: { line: 1, column: 1, offset: 0 },
+				end: { line: 1, column: 6, offset: 5 },
+			},
+		};
+		const context = { source: { markdown: 'Hello world' } } as never;
+
+		const result = rawSlice(node, context);
+
+		expect(result).toBe('Hello');
+	});
+
+	it('WHEN node lacks position returns empty string', () => {
+		const node = { type: 'text' };
+		const context = { source: { markdown: 'Hello world' } } as never;
+
+		const result = rawSlice(node, context);
+
+		expect(result).toBe('');
+	});
+
+	it('WHEN node lacks position end returns empty string', () => {
+		const node = {
+			type: 'text',
+			position: {
+				start: { line: 1, column: 1, offset: 0 },
+			},
+		} as never;
+		const context = { source: { markdown: 'Hello world' } } as never;
+
+		const result = rawSlice(node, context);
+
+		expect(result).toBe('');
+	});
+});

package/src/parser/mdast/rawSlice.ts

@@ -0,0 +1,8 @@
+import type { MdastNode, ParserVisitContext } from '@art-md/primitives';
+
+export function rawSlice(node: MdastNode, context: ParserVisitContext): string {
+	if (!node.position?.start || !node.position?.end) {
+		return '';
+	}
+	return context.source.markdown.slice(node.position.start.offset, node.position.end.offset);
+}

package/src/parser/naturalExpression/createNaturalExpressionFromNode.test.ts

@@ -0,0 +1,40 @@
+import type { MdastNode } from '@art-md/primitives';
+import { nodePositionMock } from '@art-md/primitives/src/test/helpers';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createNaturalExpressionFromNode } from './createNaturalExpressionFromNode';
+
+vi.mock('@art-md/primitives/src/parser/helpers', () => {
+	return nodePositionMock();
+});
+
+describe('createNaturalExpressionFronNode', () => {
+	it('WHEN creating a NaturalExpression from a node', async () => {
+		const node = {
+			type: 'text',
+			value: 'hello',
+			position: { start: { offset: 0 }, end: { offset: 5 } },
+		};
+
+		const result = createNaturalExpressionFromNode(node as MdastNode);
+
+		expect(result.construct).toBe('NaturalExpression');
+		expect(result.type).toBe('text');
+		expect(result.value).toBe('hello');
+	});
+
+	it('WHEN recursively creating children from node children', async () => {
+		const node = {
+			type: 'paragraph',
+			position: { start: { offset: 0 }, end: { offset: 5 } },
+			children: [
+				{ type: 'text', value: 'hello', position: { start: { offset: 0 }, end: { offset: 5 } } },
+			],
+		};
+
+		const result = createNaturalExpressionFromNode(node as MdastNode);
+
+		expect(result.children).toHaveLength(1);
+		expect(result.children[0]?.type).toBe('text');
+	});
+});

package/src/parser/naturalExpression/createNaturalExpressionFromNode.ts

@@ -0,0 +1,25 @@
+import { type MdastNode } from '@art-md/primitives';
+import { nodePosition } from '@art-md/primitives/src/parser/helpers';
+
+import type { NaturalExpression } from '../../factories';
+
+export function createNaturalExpressionFromNode(node: MdastNode): NaturalExpression {
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars
+	const { position: _, children: mdastChildren, type, value, ...attributes } = node;
+
+	let children: NaturalExpression[] = [];
+	if (Array.isArray(mdastChildren)) {
+		children = mdastChildren.map((child: MdastNode) => createNaturalExpressionFromNode(child));
+	}
+
+	const expression: NaturalExpression = {
+		construct: 'NaturalExpression',
+		type,
+		attributes,
+		value,
+		position: nodePosition(node),
+		children,
+	};
+
+	return expression;
+}

package/src/parser/naturalExpression/index.ts

@@ -0,0 +1 @@
+export { createNaturalExpressionFromNode } from './createNaturalExpressionFromNode';

package/src/parser/public.ts

@@ -0,0 +1,16 @@
+import { createFieldBlockParser } from './constructs/FieldBlock';
+import { createFieldInlineParser } from './constructs/FieldInline';
+import { createNaturalBlockParser } from './constructs/NaturalBlock';
+import { createSectionBlockParser } from './constructs/SectionBlock';
+import type { ConstructParserFactory } from './types';
+
+export { createArtDocumentFromNode } from './document/createArtDocumentFromNode';
+
+export const CONSTRUCT_PARSERS: ConstructParserFactory[] = [
+	createFieldBlockParser,
+	createFieldInlineParser,
+	createSectionBlockParser,
+];
+export const DEFAULT_CONSTRUCT_PARSER = createNaturalBlockParser;
+
+export type * from './types';

package/src/parser/tags/extractTags.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest';
+
+import { extractTags } from './extractTags';
+
+describe('extractTags', () => {
+	it('WHEN there are no tags returns empty tags and unmodified text', () => {
+		const result = extractTags('Hello there');
+		expect(result).toEqual({ tags: [], stripped: 'Hello there' });
+	});
+
+	it('WHEN extracting a single trailing tag', () => {
+		const result = extractTags('Hello there (#friend)');
+
+		expect(result).toEqual({
+			tags: [{ construct: 'Tag', name: 'friend' }],
+			stripped: 'Hello there',
+		});
+	});
+
+	it('WHEN extracting multiple trailing tags', () => {
+		const result = extractTags('Hello there (#friend) (#family)');
+
+		expect(result).toEqual({
+			tags: [
+				{ construct: 'Tag', name: 'friend' },
+				{ construct: 'Tag', name: 'family' },
+			],
+			stripped: 'Hello there',
+		});
+	});
+
+	it('WHEN the only tag is in the middle returns empty tags and unmodified text', () => {
+		const result = extractTags('Hello (#friend) there');
+
+		expect(result).toEqual({
+			tags: [],
+			stripped: 'Hello (#friend) there',
+		});
+	});
+
+	it('WHEN extracting only the trailing valid tag, keeping the middle tag in the text', () => {
+		const result = extractTags('Hello (#bad) there (#good)');
+
+		expect(result).toEqual({
+			tags: [{ construct: 'Tag', name: 'good' }],
+			stripped: 'Hello (#bad) there',
+		});
+	});
+
+	it('WHEN whitespace after the last tag and still extracts it ignores', () => {
+		const result = extractTags('Hello there (#friend)   ');
+
+		expect(result).toEqual({
+			tags: [{ construct: 'Tag', name: 'friend' }],
+			stripped: 'Hello there',
+		});
+	});
+
+	it('WHEN there are no tags but trailing whitespace returns empty tags and unmodified text', () => {
+		const result = extractTags('Hello there   ');
+
+		expect(result).toEqual({
+			tags: [],
+			stripped: 'Hello there   ',
+		});
+	});
+
+	it('WHEN text is only a tag with no preceding text returns empty tags', () => {
+		const result = extractTags('(#tag)');
+
+		expect(result).toEqual({
+			tags: [],
+			stripped: '(#tag)',
+		});
+	});
+
+	it('FOR empty string returns empty tags', () => {
+		const result = extractTags('');
+
+		expect(result).toEqual({
+			tags: [],
+			stripped: '',
+		});
+	});
+});

package/src/parser/tags/extractTags.ts

@@ -0,0 +1,23 @@
+import { type Tag, createTag } from '../../factories';
+
+const TRAILING_TAGS = /^(.*?)((?:\(#[\w-]+\)\s*)+)$/;
+const TAG = /\(#([\w-]+)\)/g;
+
+export function extractTags(text: string): { tags: Tag[]; stripped: string } {
+	const trimmed = text.trimEnd();
+	const match = trimmed.match(TRAILING_TAGS);
+	if (!match || !match[1] || !match[2]) {
+		return {
+			tags: [],
+			stripped: text,
+		};
+	}
+
+	const tags = [...match[2].matchAll(TAG)].map(matchResult =>
+		createTag({ name: matchResult[1] ?? '' }),
+	);
+	return {
+		tags,
+		stripped: match[1].trimEnd(),
+	};
+}

package/src/parser/tags/index.ts

@@ -0,0 +1 @@
+export { extractTags } from './extractTags';

package/src/parser/types.ts

@@ -0,0 +1,21 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import type { MdastNode, ParserVisitContext } from '@art-md/primitives';
+
+import type { Construct } from '../factories';
+
+export type ConstructProcessor = {
+	captureNode(context: ParserVisitContext, node: MdastNode): Construct | null;
+};
+
+export type ConstructIntegrator = {
+	integrate(context: ParserVisitContext, node: MdastNode, construct: Construct): ParserVisitContext;
+};
+
+export type ConstructParser = {
+	readonly name: string;
+	processor?: ConstructProcessor;
+	integrator?: ConstructIntegrator;
+};
+
+export type ConstructParserFactory = () => ConstructParser;

package/src/serializer/constructs/Document/createDocumentToMdast.test.ts

@@ -0,0 +1,22 @@
+import type { Heading, Text } from 'mdast';
+import { describe, expect, it } from 'vitest';
+
+import { createDocumentToMdast } from './createDocumentToMdast';
+
+describe('createDocumentToMdast', () => {
+	it('WHEN wrapping children in a root node', () => {
+		const toMdast = createDocumentToMdast();
+		const heading: Heading = {
+			type: 'heading',
+			depth: 1,
+			children: [{ type: 'text', value: 'Hello' } as Text],
+		};
+
+		const result = toMdast.toMdast({ construct: 'Document' } as never, [heading]);
+
+		expect(result).toEqual({
+			type: 'root',
+			children: [heading],
+		});
+	});
+});

package/src/serializer/constructs/Document/createDocumentToMdast.ts

@@ -0,0 +1,15 @@
+import type { Node } from 'mdast';
+
+import type { ConstructSerializer } from '../../types';
+
+export function createDocumentToMdast(): ConstructSerializer {
+	return {
+		name: 'Document',
+		toMdast(_node, children) {
+			return {
+				type: 'root',
+				children,
+			} as Node;
+		},
+	};
+}

package/src/serializer/constructs/Document/index.ts

@@ -0,0 +1 @@
+export { createDocumentToMdast } from './createDocumentToMdast';

package/src/serializer/constructs/FieldBlock/createFieldBlockToMdast.test.ts

@@ -0,0 +1,36 @@
+import type { Text } from 'mdast';
+import { describe, expect, it } from 'vitest';
+
+import { makeFieldBlockFixture, makeTagFixture } from '../../../test/helpers';
+
+import { createFieldBlockToMdast } from './createFieldBlockToMdast';
+
+describe('createFieldBlockToMdast', () => {
+	it('WHEN converting a FieldBlock to a label paragraph', () => {
+		const toMdast = createFieldBlockToMdast();
+		const value: Text = { type: 'text', value: ' Generate and manage agent instructions.' };
+
+		const result = toMdast.toMdast(makeFieldBlockFixture({ name: 'Purpose' }) as never, [value]);
+
+		expect(result).toEqual({
+			type: 'paragraph',
+			children: [{ type: 'strong', children: [{ type: 'text', value: 'Purpose:' }] }],
+		});
+	});
+
+	it('WHEN present includes tags', () => {
+		const toMdast = createFieldBlockToMdast();
+
+		const result = toMdast.toMdast(
+			makeFieldBlockFixture({ name: 'Purpose', tags: [makeTagFixture()] }) as never,
+			[],
+		);
+		expect(result).toEqual({
+			type: 'paragraph',
+			children: [
+				{ type: 'strong', children: [{ type: 'text', value: 'Purpose:' }] },
+				{ type: 'text', value: ' (#test)' },
+			],
+		});
+	});
+});

package/src/serializer/constructs/FieldBlock/createFieldBlockToMdast.ts

@@ -0,0 +1,26 @@
+import type { Node } from 'mdast';
+
+import type { FieldBlock } from '../../../factories';
+import { tagsToMdast } from '../../tags';
+import type { ConstructSerializer } from '../../types';
+
+export function createFieldBlockToMdast(): ConstructSerializer {
+	return {
+		name: 'FieldBlock',
+		// eslint-disable-next-line @typescript-eslint/no-unused-vars
+		toMdast(node, _children) {
+			const field = node as unknown as FieldBlock;
+			const tagNode = field.tags?.length ? tagsToMdast(field.tags) : null;
+			return {
+				type: 'paragraph',
+				children: [
+					{
+						type: 'strong',
+						children: [{ type: 'text', value: `${field.name}:` }],
+					},
+					...(tagNode ? [tagNode] : []),
+				],
+			} as Node;
+		},
+	};
+}

package/src/serializer/constructs/FieldBlock/index.ts

@@ -0,0 +1 @@
+export { createFieldBlockToMdast } from './createFieldBlockToMdast';

package/src/serializer/constructs/FieldInline/createFieldInlineToMdast.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+
+import { makeFieldInlineFixture, makeTagFixture } from '../../../test/helpers';
+
+import { createFieldInlineToMdast } from './createFieldInlineToMdast';
+
+describe('createFieldInlineToMdast', () => {
+	it('WHEN converting a FieldInline to a paragraph with strong label', () => {
+		const toMdast = createFieldInlineToMdast();
+
+		const result = toMdast.toMdast(makeFieldInlineFixture({ name: 'Purpose' }) as never, []);
+
+		expect(result).toEqual({
+			type: 'paragraph',
+			children: [
+				{ type: 'strong', children: [{ type: 'text', value: 'Purpose:' }] },
+				{ type: 'text', value: ' ' },
+			],
+		});
+	});
+
+	it('WHEN present appends tags', () => {
+		const toMdast = createFieldInlineToMdast();
+
+		const result = toMdast.toMdast(
+			makeFieldInlineFixture({ name: 'Purpose', tags: [makeTagFixture()] }) as never,
+			[],
+		);
+		expect(result).toEqual({
+			type: 'paragraph',
+			children: [
+				{ type: 'strong', children: [{ type: 'text', value: 'Purpose:' }] },
+				{ type: 'text', value: ' ' },
+				{ type: 'text', value: ' (#test)' },
+			],
+		});
+	});
+});

package/src/serializer/constructs/FieldInline/createFieldInlineToMdast.ts

@@ -0,0 +1,27 @@
+import type { Node } from 'mdast';
+
+import type { FieldInline } from '../../../factories';
+import { tagsToMdast } from '../../tags';
+import type { ConstructSerializer } from '../../types';
+
+export function createFieldInlineToMdast(): ConstructSerializer {
+	return {
+		name: 'FieldInline',
+		toMdast(node, children) {
+			const field = node as unknown as FieldInline;
+			const tagNode = field.tags?.length ? tagsToMdast(field.tags) : null;
+			return {
+				type: 'paragraph',
+				children: [
+					{
+						type: 'strong',
+						children: [{ type: 'text', value: `${field.name}:` }],
+					},
+					{ type: 'text', value: ' ' },
+					...children,
+					...(tagNode ? [tagNode] : []),
+				],
+			} as Node;
+		},
+	};
+}

package/src/serializer/constructs/FieldInline/index.ts

@@ -0,0 +1 @@
+export { createFieldInlineToMdast } from './createFieldInlineToMdast';

package/src/serializer/constructs/NaturalBlock/createNaturalBlockToMdast.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'vitest';
+
+import { makeNaturalBlockFixture, makeTagFixture } from '../../../test/helpers';
+
+import { createNaturalBlockToMdast } from './createNaturalBlockToMdast';
+
+describe('createNaturalBlockToMdast', () => {
+	it('WHEN parsing a text value into a root with paragraph', () => {
+		const toMdast = createNaturalBlockToMdast();
+
+		const result = toMdast.toMdast(
+			makeNaturalBlockFixture({ type: 'text', value: ' Hello world' }) as never,
+			[],
+		);
+		expect(result).toMatchObject({
+			type: 'root',
+			children: expect.arrayContaining([expect.objectContaining({ type: 'paragraph' })]),
+		});
+	});
+
+	it('WHEN parsing a code block value', () => {
+		const toMdast = createNaturalBlockToMdast();
+
+		const result = toMdast.toMdast(
+			makeNaturalBlockFixture({
+				type: 'code',
+				lang: null,
+				meta: null,
+				value: '```\nconst x = 1;\n```',
+			}) as never,
+			[],
+		);
+		expect(result).toMatchObject({
+			type: 'root',
+			children: expect.arrayContaining([expect.objectContaining({ type: 'code' })]),
+		});
+	});
+
+	it('WHEN children in a paragraph includes', () => {
+		const toMdast = createNaturalBlockToMdast();
+
+		const result = toMdast.toMdast(
+			makeNaturalBlockFixture({ type: 'paragraph', value: 'Hello' }) as never,
+			[{ type: 'text', value: 'child' } as never],
+		);
+		expect(result).toMatchObject({
+			type: 'root',
+			children: expect.arrayContaining([
+				expect.objectContaining({
+					type: 'paragraph',
+					children: expect.arrayContaining([expect.objectContaining({ value: 'child' })]),
+				}),
+			]),
+		});
+	});
+
+	it('WHEN present includes tags in a paragraph', () => {
+		const toMdast = createNaturalBlockToMdast();
+
+		const result = toMdast.toMdast(
+			makeNaturalBlockFixture({
+				type: 'paragraph',
+				value: 'Hello',
+				tags: [makeTagFixture()],
+			}) as never,
+			[{ type: 'text', value: 'child' } as never],
+		);
+		expect(result).toMatchObject({
+			type: 'root',
+			children: expect.arrayContaining([
+				expect.objectContaining({
+					type: 'paragraph',
+					children: expect.arrayContaining([expect.objectContaining({ value: ' (#test)' })]),
+				}),
+			]),
+		});
+	});
+
+	it('WHEN paragraph has no children does not include tags', () => {
+		const toMdast = createNaturalBlockToMdast();
+
+		const result = toMdast.toMdast(
+			makeNaturalBlockFixture({
+				type: 'paragraph',
+				value: 'Hello',
+				tags: [makeTagFixture()],
+			}) as never,
+			[],
+		);
+		expect(result).toMatchObject({
+			type: 'root',
+			children: expect.arrayContaining([
+				expect.objectContaining({
+					type: 'paragraph',
+					children: expect.not.arrayContaining([expect.objectContaining({ value: ' (#test)' })]),
+				}),
+			]),
+		});
+	});
+
+	it('WHEN paragraph tags are empty does not include tags', () => {
+		const toMdast = createNaturalBlockToMdast();
+
+		const result = toMdast.toMdast(
+			makeNaturalBlockFixture({
+				type: 'paragraph',
+				value: 'Hello',
+				tags: [],
+			}) as never,
+			[{ type: 'text', value: 'child' } as never],
+		);
+		expect(result).toMatchObject({
+			type: 'root',
+			children: expect.arrayContaining([
+				expect.objectContaining({
+					type: 'paragraph',
+					children: expect.arrayContaining([expect.objectContaining({ value: 'child' })]),
+				}),
+			]),
+		});
+	});
+});

package/src/serializer/constructs/NaturalBlock/createNaturalBlockToMdast.ts

@@ -0,0 +1,30 @@
+import type { Node } from 'mdast';
+import { fromMarkdown } from 'mdast-util-from-markdown';
+
+import type { NaturalBlock } from '../../../factories';
+import { tagsToMdast } from '../../tags';
+import type { ConstructSerializer } from '../../types';
+
+export function createNaturalBlockToMdast(): ConstructSerializer {
+	return {
+		name: 'NaturalBlock',
+		toMdast(node, children) {
+			const block = node as unknown as NaturalBlock;
+			const parsed = fromMarkdown(block.value);
+			if (block.type === 'paragraph' && children.length > 0) {
+				const paragraph = parsed.children.find(child => child.type === 'paragraph');
+				if (paragraph && 'children' in paragraph) {
+					const tagNode = block.tags?.length ? tagsToMdast(block.tags) : null;
+					paragraph.children = [
+						...children,
+						...(tagNode ? [tagNode] : []),
+					] as typeof paragraph.children;
+				}
+			}
+			return {
+				type: 'root',
+				children: parsed.children,
+			} as Node;
+		},
+	};
+}

package/src/serializer/constructs/NaturalBlock/index.ts

@@ -0,0 +1 @@
+export { createNaturalBlockToMdast } from './createNaturalBlockToMdast';