@art-md/constructs 0.0.1 → 0.0.3

package/src/parser/constructs/FieldBlock/private/helpers/createFieldBlockFromNode.test.ts

@@ -0,0 +1,63 @@
+import { makeParserVisitContextMock } from '@art-md/primitives/src/test/helpers';
+import type { Paragraph } from 'mdast';
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createFieldBlock } from '../../../../../factories';
+
+import { createFieldBlockFromNode } from './createFieldBlockFromNode';
+
+vi.mock('../../../../../factories/constructs/FieldBlock/factory/createFieldBlock', async () => {
+	const { createFieldBlockMock } = await import('../../../../../test/helpers');
+	return createFieldBlockMock();
+});
+
+describe('createFieldBlockFromNode', () => {
+	it('WHEN text does not start with strong returns null', () => {
+		const markdown = 'Foo **Purpose:**';
+		const tree = fromMarkdown(markdown);
+		const paragraph = tree.children[0] as Paragraph;
+		const context = makeParserVisitContextMock({ markdown });
+
+		const result = createFieldBlockFromNode(paragraph, context);
+
+		expect(result).toBeNull();
+	});
+
+	it('WHEN text after the strong is not empty returns null', () => {
+		const markdown = '**Purpose:** leftover';
+		const tree = fromMarkdown(markdown);
+		const paragraph = tree.children[0] as Paragraph;
+		const context = makeParserVisitContextMock({ markdown });
+
+		const result = createFieldBlockFromNode(paragraph, context);
+
+		expect(result).toBeNull();
+	});
+
+	it('WHEN creating a FieldBlock from a paragraph', () => {
+		const markdown = '**Purpose:**';
+		const tree = fromMarkdown(markdown);
+		const paragraph = tree.children[0] as Paragraph;
+		const context = makeParserVisitContextMock({ markdown });
+
+		const result = createFieldBlockFromNode(paragraph, context);
+
+		expect(createFieldBlock).toHaveBeenCalledWith({ name: 'Purpose', tags: [] });
+		expect(result).toBe(vi.mocked(createFieldBlock).mock.results[0]?.value);
+	});
+
+	it('WHEN trailing tags follow the strong passes them to createFieldBlock', () => {
+		const markdown = '**Purpose:** (#purpose)';
+		const tree = fromMarkdown(markdown);
+		const paragraph = tree.children[0] as Paragraph;
+		const context = makeParserVisitContextMock({ markdown });
+
+		createFieldBlockFromNode(paragraph, context);
+
+		expect(createFieldBlock).toHaveBeenCalledWith({
+			name: 'Purpose',
+			tags: [{ construct: 'Tag', name: 'purpose' }],
+		});
+	});
+});

package/src/parser/constructs/FieldBlock/private/helpers/createFieldBlockFromNode.ts

@@ -0,0 +1,33 @@
+import type { ParserVisitContext } from '@art-md/primitives';
+import { nodePosition } from '@art-md/primitives';
+import type { Paragraph, Strong } from 'mdast';
+
+import { type FieldBlock, createFieldBlock } from '../../../../../factories';
+import { stripStrong } from '../../../../fields';
+import { rawSlice } from '../../../../mdast';
+import { extractTags } from '../../../../tags';
+
+export function createFieldBlockFromNode(
+	paragraph: Paragraph,
+	context: ParserVisitContext,
+): FieldBlock | null {
+	const strong = paragraph.children[0] as Strong;
+	const paragraphRaw = rawSlice(paragraph, context);
+	const strongRaw = rawSlice(strong, context);
+
+	const afterStrong = paragraphRaw.slice(strongRaw.length);
+	const { tags, stripped } = extractTags(afterStrong);
+	if (stripped.trim().length > 0) {
+		return null;
+	}
+	const inner = stripStrong(strong, context);
+	const colonIndex = inner.indexOf(':');
+
+	const field = createFieldBlock({
+		name: inner.slice(0, colonIndex).trim(),
+		tags,
+	});
+	field.position = nodePosition(paragraph);
+
+	return field;
+}

package/src/parser/constructs/FieldBlock/private/helpers/onBeforeConstruct.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { onBeforeConstruct } from './onBeforeConstruct';
+
+describe('onBeforeConstruct', () => {
+	it('FOR a non-boundary construct returns the same context', () => {
+		const context = { parent: vi.fn() } as never;
+
+		const result = onBeforeConstruct({ construct: 'NaturalBlock' } as never, context);
+
+		expect(result).toBe(context);
+	});
+
+	it('FOR a boundary construct without a parent returns the same context', () => {
+		const context = { parent: vi.fn(() => undefined) } as never;
+
+		const result = onBeforeConstruct({ construct: 'FieldBlock' } as never, context);
+
+		expect(result).toBe(context);
+	});
+
+	it('FOR a boundary construct with a parent returns the parent context', () => {
+		const parent = { construct: 'Document' } as never;
+		const context = { parent: vi.fn(() => parent) } as never;
+
+		const result = onBeforeConstruct({ construct: 'SectionBlock' } as never, context);
+
+		expect(result).toBe(parent);
+	});
+});

package/src/parser/constructs/FieldBlock/private/helpers/onBeforeConstruct.ts

@@ -0,0 +1,19 @@
+import type { ConstructBase, ParserVisitContext } from '@art-md/primitives';
+
+const FIELD_BLOCK_BOUNDARIES = new Set(['FieldBlock', 'FieldInline', 'SectionBlock']);
+
+export function onBeforeConstruct(
+	construct: ConstructBase,
+	context: ParserVisitContext,
+): ParserVisitContext {
+	if (!FIELD_BLOCK_BOUNDARIES.has(construct.construct)) {
+		return context;
+	}
+
+	const parent = context.parent();
+	if (!parent) {
+		return context;
+	}
+
+	return parent;
+}

package/src/parser/constructs/FieldBlock/private/index.ts

@@ -0,0 +1,2 @@
+export * from './integrator/createFieldBlockIntegrator';
+export * from './processor/createFieldBlockProcessor';

package/src/parser/constructs/FieldBlock/private/integrator/createFieldBlockIntegrator.test.ts

@@ -0,0 +1,23 @@
+import { makeParserVisitContextMock } from '@art-md/primitives/src/test/helpers';
+import { describe, expect, it, vi } from 'vitest';
+
+import { makeFieldBlockFixture } from '../../../../../test/helpers';
+import { onBeforeConstruct } from '../helpers/onBeforeConstruct';
+
+import { createFieldBlockIntegrator } from './createFieldBlockIntegrator';
+
+describe('createFieldBlockIntegrator', () => {
+	it('WHEN integrating captures the construct and returns a child context', () => {
+		const integrator = createFieldBlockIntegrator();
+		const context = makeParserVisitContextMock();
+		const nextContext = makeParserVisitContextMock();
+		vi.mocked(context.childContext).mockReturnValue(nextContext);
+		const field = makeFieldBlockFixture();
+
+		const result = integrator.integrate(context, {} as never, field as never);
+
+		expect(context.captureChildConstruct).toHaveBeenCalledWith(field);
+		expect(context.childContext).toHaveBeenCalledWith(field, onBeforeConstruct);
+		expect(result).toBe(nextContext);
+	});
+});

package/src/parser/constructs/FieldBlock/private/integrator/createFieldBlockIntegrator.ts

@@ -0,0 +1,13 @@
+import type { FieldBlock } from '../../../../../factories';
+import type { ConstructIntegrator } from '../../../../types';
+import { onBeforeConstruct } from '../helpers/onBeforeConstruct';
+
+export function createFieldBlockIntegrator(): ConstructIntegrator {
+	return {
+		integrate(context, _node, construct) {
+			const field = construct as FieldBlock;
+			context.captureChildConstruct(field);
+			return context.childContext(field, onBeforeConstruct);
+		},
+	};
+}

package/src/parser/constructs/FieldBlock/private/processor/createFieldBlockProcessor.test.ts

@@ -0,0 +1,63 @@
+import { makeParserVisitContextMock } from '@art-md/primitives/src/test/helpers';
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createFieldBlockFromNodeMock } from '../../../../../test/helpers';
+import { createFieldBlockFromNode } from '../helpers/createFieldBlockFromNode';
+
+import { createFieldBlockProcessor } from './createFieldBlockProcessor';
+
+vi.mock('../helpers/createFieldBlockFromNode', async () => {
+	return createFieldBlockFromNodeMock();
+});
+
+describe('createFieldBlockProcessor', () => {
+	it('WHEN called returns a processor function', () => {
+		const processor = createFieldBlockProcessor();
+
+		expect(processor.captureNode).toBeInstanceOf(Function);
+	});
+
+	it('FOR non-paragraph nodes returns null', () => {
+		const processor = createFieldBlockProcessor();
+		const context = makeParserVisitContextMock({ markdown: 'Hello' });
+
+		const result = processor.captureNode(context, { type: 'heading', children: [] } as never);
+
+		expect(result).toBeNull();
+	});
+
+	it('FOR paragraph with no children returns null', () => {
+		const processor = createFieldBlockProcessor();
+		const context = makeParserVisitContextMock({ markdown: 'Hello' });
+
+		const result = processor.captureNode(context, { type: 'paragraph', children: [] } as never);
+
+		expect(result).toBeNull();
+	});
+
+	it('WHEN first child is not a field strong returns null', () => {
+		const processor = createFieldBlockProcessor();
+		const markdown = 'Hello world';
+		const tree = fromMarkdown(markdown);
+		const context = makeParserVisitContextMock({ markdown });
+		const paragraph = tree.children[0] as never;
+
+		const result = processor.captureNode(context, paragraph);
+
+		expect(result).toBeNull();
+	});
+
+	it('WHEN first child is a field strong returns the createFieldBlockFromNode result', () => {
+		const processor = createFieldBlockProcessor();
+		const markdown = '**Name:** value';
+		const tree = fromMarkdown(markdown);
+		const context = makeParserVisitContextMock({ markdown });
+		const paragraph = tree.children[0] as never;
+
+		const result = processor.captureNode(context, paragraph);
+
+		expect(createFieldBlockFromNode).toHaveBeenCalledWith(paragraph, context);
+		expect(result).toMatchObject({ construct: 'FieldBlock', name: 'Test' });
+	});
+});

package/src/parser/constructs/FieldBlock/private/processor/createFieldBlockProcessor.ts

@@ -0,0 +1,21 @@
+import type { Paragraph } from 'mdast';
+
+import { isFieldStrong } from '../../../../fields';
+import type { ConstructProcessor } from '../../../../types';
+import { createFieldBlockFromNode } from '../helpers/createFieldBlockFromNode';
+
+export function createFieldBlockProcessor(): ConstructProcessor {
+	return {
+		captureNode(context, node) {
+			if (node.type !== 'paragraph') {
+				return null;
+			}
+			const paragraph = node as Paragraph;
+			const first = paragraph.children[0];
+			if (first === undefined || !isFieldStrong(first, context)) {
+				return null;
+			}
+			return createFieldBlockFromNode(paragraph, context);
+		},
+	};
+}

package/src/parser/constructs/FieldInline/createFieldInlineParser.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest';
+
+import { createFieldInlineParser } from './createFieldInlineParser';
+
+describe('createFieldInlineParser', () => {
+	it('WHEN called returns a parser with FieldInline name, processor and factory', () => {
+		const parser = createFieldInlineParser();
+
+		expect(parser.name).toBe('FieldInline');
+		expect(parser.processor).toBeDefined();
+	});
+});

package/src/parser/constructs/FieldInline/createFieldInlineParser.ts

@@ -0,0 +1,8 @@
+import type { ConstructParserFactory } from '../../types';
+
+import { createFieldInlineProcessor } from './private';
+
+export const createFieldInlineParser: ConstructParserFactory = () => ({
+	name: 'FieldInline',
+	processor: createFieldInlineProcessor(),
+});

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

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

package/src/parser/constructs/FieldInline/private/helpers/createFieldInlineFromNode.test.ts

@@ -0,0 +1,100 @@
+import { makeParserVisitContextMock } from '@art-md/primitives/src/test/helpers';
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createFieldInline } from '../../../../../factories';
+
+import { createFieldInlineFromNode } from './createFieldInlineFromNode';
+
+vi.mock('../../../../../factories/constructs/FieldInline/factory/createFieldInline', async () => {
+	const { createFieldInlineMock } = await import('../../../../../test/helpers');
+	return createFieldInlineMock();
+});
+
+describe('createFieldInlineFromNode', () => {
+	it('WHEN nothing but whitespace follows the strong returns null', () => {
+		const markdown = '**Name:**   ';
+		const tree = fromMarkdown(markdown);
+		const paragraph = tree.children[0] as never;
+		const context = makeParserVisitContextMock({ markdown });
+
+		const result = createFieldInlineFromNode(paragraph, context);
+
+		expect(result).toBeNull();
+	});
+
+	it('WHEN only tags follow the strong returns null', () => {
+		const markdown = '**Name:** (#tag)';
+		const tree = fromMarkdown(markdown);
+		const paragraph = tree.children[0] as never;
+		const context = makeParserVisitContextMock({ markdown });
+
+		const result = createFieldInlineFromNode(paragraph, context);
+
+		expect(result).toBeNull();
+	});
+
+	it('WHEN capturing inline field values from paragraph siblings after the label', () => {
+		const markdown = '**Greeting:** Hello world.';
+		const tree = fromMarkdown(markdown);
+		const paragraph = tree.children[0] as never;
+		const context = makeParserVisitContextMock({ markdown });
+
+		const result = createFieldInlineFromNode(paragraph, context);
+
+		expect(createFieldInline).toHaveBeenCalledWith({
+			name: 'Greeting',
+			children: [
+				expect.objectContaining({
+					construct: 'NaturalExpression',
+					type: 'text',
+					value: 'Hello world.',
+				}),
+			],
+			tags: [],
+		});
+		expect(result).toBe(vi.mocked(createFieldInline).mock.results[0]?.value);
+	});
+
+	it('WHEN converting preserves inline child types in the field children', () => {
+		const markdown = '**Remote:** `git@example.com`';
+		const tree = fromMarkdown(markdown);
+		const paragraph = tree.children[0] as never;
+		const context = makeParserVisitContextMock({ markdown });
+
+		createFieldInlineFromNode(paragraph, context);
+
+		expect(createFieldInline).toHaveBeenCalledWith({
+			name: 'Remote',
+			children: [
+				expect.objectContaining({
+					construct: 'NaturalExpression',
+					type: 'inlineCode',
+					value: 'git@example.com',
+				}),
+			],
+			tags: [],
+		});
+	});
+
+	it('WHEN extracting tags and strips it from the last text child', () => {
+		const markdown = '**Greeting:** Hello there (#friend)';
+		const tree = fromMarkdown(markdown);
+		const paragraph = tree.children[0] as never;
+		const context = makeParserVisitContextMock({ markdown });
+
+		createFieldInlineFromNode(paragraph, context);
+
+		expect(createFieldInline).toHaveBeenCalledWith({
+			name: 'Greeting',
+			children: [
+				expect.objectContaining({
+					construct: 'NaturalExpression',
+					type: 'text',
+					value: 'Hello there',
+				}),
+			],
+			tags: [{ construct: 'Tag', name: 'friend' }],
+		});
+	});
+});

package/src/parser/constructs/FieldInline/private/helpers/createFieldInlineFromNode.ts

@@ -0,0 +1,51 @@
+import type { ParserVisitContext } from '@art-md/primitives';
+import { nodePosition } from '@art-md/primitives';
+import type { Paragraph, Strong } from 'mdast';
+
+import { type FieldInline, type Tag, createFieldInline } from '../../../../../factories';
+import { stripStrong } from '../../../../fields';
+import { rawSlice } from '../../../../mdast';
+import { createNaturalExpressionFromNode } from '../../../../naturalExpression';
+import { extractTags } from '../../../../tags';
+
+import { trimFieldEdges } from './trimFieldEdges';
+
+export function createFieldInlineFromNode(
+	paragraph: Paragraph,
+	context: ParserVisitContext,
+): FieldInline | null {
+	const strong = paragraph.children[0] as Strong;
+	const paragraphRaw = rawSlice(paragraph, context);
+	const strongRaw = rawSlice(strong, context);
+
+	const afterStrong = paragraphRaw.slice(strongRaw.length);
+	const { stripped } = extractTags(afterStrong);
+	if (stripped.trim().length === 0) {
+		return null;
+	}
+	const inner = stripStrong(strong, context);
+	const colonIndex = inner.indexOf(':');
+
+	const expressions = paragraph.children
+		.slice(1)
+		.map(child => createNaturalExpressionFromNode(child));
+	const children = trimFieldEdges(expressions);
+	const last = children[children.length - 1];
+	let tags: Tag[] = [];
+	if (last?.type === 'text' && typeof last.value === 'string') {
+		const extracted = extractTags(last.value);
+		if (extracted.tags.length) {
+			tags = extracted.tags;
+			last.value = extracted.stripped;
+		}
+	}
+
+	const field = createFieldInline({
+		name: inner.slice(0, colonIndex).trim(),
+		children,
+		tags,
+	});
+	field.position = nodePosition(paragraph);
+
+	return field;
+}

package/src/parser/constructs/FieldInline/private/helpers/trimFieldEdges.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+
+import { makeNaturalExpressionFixture } from '../../../../../test/helpers';
+
+import { trimFieldEdges } from './trimFieldEdges';
+
+describe('trimFieldEdges', () => {
+	it('WHEN the edge texts have surrounding whitespace trims them', () => {
+		const expressions = [makeNaturalExpressionFixture({ value: '  hello  ' })];
+
+		const result = trimFieldEdges(expressions);
+
+		expect(result).toEqual([makeNaturalExpressionFixture({ value: 'hello' })]);
+	});
+
+	it('WHEN there are no text nodes leaves them untouched', () => {
+		const expressions = [
+			makeNaturalExpressionFixture({ type: 'inlineCode', value: 'a' }),
+			makeNaturalExpressionFixture({ type: 'inlineCode', value: 'b' }),
+		];
+
+		const result = trimFieldEdges(expressions);
+
+		expect(result).toEqual(expressions);
+	});
+
+	it('WHEN the first text is only whitespace removes it', () => {
+		const expressions = [
+			makeNaturalExpressionFixture({ value: '  ' }),
+			makeNaturalExpressionFixture({ type: 'inlineCode', value: 'a' }),
+		];
+
+		const result = trimFieldEdges(expressions);
+
+		expect(result).toEqual([makeNaturalExpressionFixture({ type: 'inlineCode', value: 'a' })]);
+	});
+
+	it('WHEN the last text is only whitespace removes it', () => {
+		const expressions = [
+			makeNaturalExpressionFixture({ type: 'inlineCode', value: 'a' }),
+			makeNaturalExpressionFixture({ value: '  ' }),
+		];
+
+		const result = trimFieldEdges(expressions);
+
+		expect(result).toEqual([makeNaturalExpressionFixture({ type: 'inlineCode', value: 'a' })]);
+	});
+});

package/src/parser/constructs/FieldInline/private/helpers/trimFieldEdges.ts

@@ -0,0 +1,18 @@
+import type { NaturalExpression } from '../../../../../factories';
+
+export function trimFieldEdges(value: NaturalExpression[]): typeof value {
+	const trimmed = [...value];
+	const first = trimmed[0];
+	const last = trimmed[trimmed.length - 1];
+
+	if (first?.type === 'text' && typeof first?.value === 'string')
+		first.value = first.value.replace(/^\s+/, '');
+	if (last?.type === 'text' && typeof last?.value === 'string')
+		last.value = last.value.replace(/\s+$/, '');
+
+	return trimmed.filter(
+		expression =>
+			expression.type !== 'text' ||
+			(typeof expression.value === 'string' && expression.value.length > 0),
+	);
+}

package/src/parser/constructs/FieldInline/private/index.ts

@@ -0,0 +1 @@
+export * from './processor/createFieldInlineProcessor';

package/src/parser/constructs/FieldInline/private/processor/createFieldInlineProcessor.test.ts

@@ -0,0 +1,57 @@
+import { makeParserVisitContextMock } from '@art-md/primitives/src/test/helpers';
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createFieldInlineFromNodeMock } from '../../../../../test/helpers';
+import { createFieldInlineFromNode } from '../helpers/createFieldInlineFromNode';
+
+import { createFieldInlineProcessor } from './createFieldInlineProcessor';
+
+vi.mock('../helpers/createFieldInlineFromNode', async () => {
+	return createFieldInlineFromNodeMock();
+});
+
+describe('createFieldInlineProcessor', () => {
+	it('FOR non-paragraph nodes returns null', () => {
+		const processor = createFieldInlineProcessor();
+		const context = makeParserVisitContextMock({ markdown: 'Hello world' });
+
+		const result = processor.captureNode(context, { type: 'heading', children: [] } as never);
+
+		expect(result).toBeNull();
+	});
+
+	it('FOR paragraphs with no children returns null', () => {
+		const processor = createFieldInlineProcessor();
+		const context = makeParserVisitContextMock({ markdown: 'Hello world' });
+
+		const result = processor.captureNode(context, { type: 'paragraph', children: [] } as never);
+
+		expect(result).toBeNull();
+	});
+
+	it('WHEN the first child is not a field strong returns null', () => {
+		const processor = createFieldInlineProcessor();
+		const markdown = 'Hello world';
+		const tree = fromMarkdown(markdown);
+		const paragraph = tree.children[0] as never;
+		const context = makeParserVisitContextMock({ markdown });
+
+		const result = processor.captureNode(context, paragraph);
+
+		expect(result).toBeNull();
+	});
+
+	it('WHEN the first child is a field strong returns the createFieldInlineFromNode result', () => {
+		const processor = createFieldInlineProcessor();
+		const markdown = '**Name:** value';
+		const tree = fromMarkdown(markdown);
+		const paragraph = tree.children[0] as never;
+		const context = makeParserVisitContextMock({ markdown });
+
+		const result = processor.captureNode(context, paragraph);
+
+		expect(createFieldInlineFromNode).toHaveBeenCalledWith(paragraph, context);
+		expect(result).toMatchObject({ construct: 'FieldInline', name: 'Test' });
+	});
+});

package/src/parser/constructs/FieldInline/private/processor/createFieldInlineProcessor.ts

@@ -0,0 +1,21 @@
+import type { Paragraph } from 'mdast';
+
+import { isFieldStrong } from '../../../../fields';
+import type { ConstructProcessor } from '../../../../types';
+import { createFieldInlineFromNode } from '../helpers/createFieldInlineFromNode';
+
+export function createFieldInlineProcessor(): ConstructProcessor {
+	return {
+		captureNode(context, node) {
+			if (node.type !== 'paragraph') {
+				return null;
+			}
+			const paragraph = node as Paragraph;
+			const first = paragraph.children[0];
+			if (first === undefined || !isFieldStrong(first, context)) {
+				return null;
+			}
+			return createFieldInlineFromNode(paragraph, context);
+		},
+	};
+}

package/src/parser/constructs/NaturalBlock/createNaturalBlockParser.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest';
+
+import { createNaturalBlockParser } from './createNaturalBlockParser';
+
+describe('createNaturalBlockParser', () => {
+	it('WHEN called returns a parser with NaturalBlock name, processor and factory', () => {
+		const parser = createNaturalBlockParser();
+
+		expect(parser.name).toBe('NaturalBlock');
+		expect(parser.processor).toBeDefined();
+	});
+});

package/src/parser/constructs/NaturalBlock/createNaturalBlockParser.ts

@@ -0,0 +1,8 @@
+import type { ConstructParserFactory } from '../../types';
+
+import { createNaturalBlockProcessor } from './private';
+
+export const createNaturalBlockParser: ConstructParserFactory = () => ({
+	name: 'NaturalBlock',
+	processor: createNaturalBlockProcessor(),
+});

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

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