@art-md/constructs 0.0.1 → 0.0.3

package/src/serializer/constructs/NaturalExpression/createNaturalExpressionToMdast.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+
+import { makeNaturalExpressionFixture } from '../../../test/helpers';
+
+import { createNaturalExpressionToMdast } from './createNaturalExpressionToMdast';
+
+describe('createNaturalExpressionToMdast', () => {
+	it('WHEN converting a NaturalExpression to an mdast node', () => {
+		const toMdast = createNaturalExpressionToMdast();
+
+		const result = toMdast.toMdast(makeNaturalExpressionFixture() as never, []);
+
+		expect(result).toEqual({ type: 'text', value: 'hello', children: [] });
+	});
+
+	it('WHEN converting preserves attributes in the mdast node', () => {
+		const toMdast = createNaturalExpressionToMdast();
+
+		const result = toMdast.toMdast(
+			makeNaturalExpressionFixture({
+				type: 'inlineCode',
+				value: 'code',
+				attributes: { lang: 'ts' },
+			}) as never,
+			[],
+		);
+		expect(result).toEqual({ type: 'inlineCode', value: 'code', lang: 'ts', children: [] });
+	});
+});

package/src/serializer/constructs/NaturalExpression/createNaturalExpressionToMdast.ts

@@ -0,0 +1,15 @@
+import type { Node } from 'mdast';
+
+import type { NaturalExpression } from '../../../factories';
+import type { ConstructSerializer } from '../../types';
+
+export function createNaturalExpressionToMdast(): ConstructSerializer {
+	return {
+		name: 'NaturalExpression',
+		toMdast(node, children) {
+			const expression = node as unknown as NaturalExpression;
+			const attributes = { ...expression.attributes };
+			return { type: expression.type, value: expression.value, children, ...attributes } as Node;
+		},
+	};
+}

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

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

package/src/serializer/constructs/SectionBlock/createSectionBlockToMdast.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest';
+
+import { makeSectionBlockFixture, makeTagFixture } from '../../../test/helpers';
+
+import { createSectionBlockToMdast } from './createSectionBlockToMdast';
+
+function stripPositions(node: unknown): unknown {
+	if (node === null || typeof node !== 'object') return node;
+	if (Array.isArray(node)) return node.map(stripPositions);
+	const obj = node as Record<string, unknown>;
+	const rest: Record<string, unknown> = {};
+	for (const key of Object.keys(obj)) {
+		if (key === 'position') continue;
+		rest[key] = stripPositions(obj[key]);
+	}
+	return rest;
+}
+
+describe('createSectionBlockToMdast', () => {
+	it('WHEN converting a SectionBlock to an mdast heading', () => {
+		const toMdast = createSectionBlockToMdast();
+
+		const result = toMdast.toMdast(
+			makeSectionBlockFixture({ name: 'Module', depth: 1 }) as never,
+			[],
+		);
+
+		expect(stripPositions(result)).toEqual({
+			type: 'heading',
+			depth: 1,
+			children: [{ type: 'text', value: 'Module' }],
+		});
+	});
+
+	it('WHEN not provided defaults depth to 1', () => {
+		const toMdast = createSectionBlockToMdast();
+
+		const result = toMdast.toMdast(makeSectionBlockFixture({ name: 'Section' }) as never, []);
+
+		expect(stripPositions(result)).toEqual({
+			type: 'heading',
+			depth: 1,
+			children: [{ type: 'text', value: 'Section' }],
+		});
+	});
+
+	it('WHEN converting preserves inline formatting in heading names', () => {
+		const toMdast = createSectionBlockToMdast();
+
+		const result = toMdast.toMdast(
+			makeSectionBlockFixture({ name: 'Hello _World_! How are **you**?', depth: 1 }) as never,
+			[],
+		);
+		expect(stripPositions(result)).toEqual({
+			type: 'heading',
+			depth: 1,
+			children: [
+				{ type: 'text', value: 'Hello ' },
+				{ type: 'emphasis', children: [{ type: 'text', value: 'World' }] },
+				{ type: 'text', value: '! How are ' },
+				{ type: 'strong', children: [{ type: 'text', value: 'you' }] },
+				{ type: 'text', value: '?' },
+			],
+		});
+	});
+
+	it('WHEN present includes tags in the heading text', () => {
+		const toMdast = createSectionBlockToMdast();
+
+		const result = toMdast.toMdast(
+			makeSectionBlockFixture({ name: 'Hello', depth: 1, tags: [makeTagFixture()] }) as never,
+			[],
+		);
+		expect(stripPositions(result)).toEqual({
+			type: 'heading',
+			depth: 1,
+			children: [
+				{ type: 'text', value: 'Hello' },
+				{ type: 'text', value: ' (#test)' },
+			],
+		});
+	});
+});

package/src/serializer/constructs/SectionBlock/createSectionBlockToMdast.ts

@@ -0,0 +1,29 @@
+import type { Node, RootContent } from 'mdast';
+import { fromMarkdown } from 'mdast-util-from-markdown';
+
+import type { SectionBlock } from '../../../factories';
+import { tagsToMdast } from '../../tags';
+import type { ConstructSerializer } from '../../types';
+
+export function createSectionBlockToMdast(): ConstructSerializer {
+	return {
+		name: 'SectionBlock',
+		// eslint-disable-next-line @typescript-eslint/no-unused-vars
+		toMdast(node, _children) {
+			const section = node as unknown as SectionBlock;
+			const depth = section.depth ?? 1;
+			const parsed = fromMarkdown(`# ${section.name}`);
+			const heading = parsed.children.find(child => child.type === 'heading');
+			const tagNode = section.tags?.length ? tagsToMdast(section.tags) : null;
+			const children: RootContent[] =
+				heading && 'children' in heading
+					? [...heading.children, ...(tagNode ? [tagNode] : [])]
+					: [{ type: 'text' as const, value: section.name }, ...(tagNode ? [tagNode] : [])];
+			return {
+				type: 'heading',
+				depth: depth as 1 | 2 | 3 | 4 | 5 | 6,
+				children,
+			} as Node;
+		},
+	};
+}

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

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

package/src/serializer/index.ts

@@ -0,0 +1,8 @@
+export * from './constructs/Document';
+export * from './constructs/FieldBlock';
+export * from './constructs/FieldInline';
+export * from './constructs/NaturalBlock';
+export * from './constructs/NaturalExpression';
+export * from './constructs/SectionBlock';
+
+export type * from './types';

package/src/serializer/public.ts

@@ -0,0 +1,18 @@
+import { createDocumentToMdast } from './constructs/Document';
+import { createFieldBlockToMdast } from './constructs/FieldBlock';
+import { createFieldInlineToMdast } from './constructs/FieldInline';
+import { createNaturalBlockToMdast } from './constructs/NaturalBlock';
+import { createNaturalExpressionToMdast } from './constructs/NaturalExpression';
+import { createSectionBlockToMdast } from './constructs/SectionBlock';
+import type { ConstructSerializerFactory } from './types';
+
+export const CONSTRUCT_SERIALIZERS: ConstructSerializerFactory[] = [
+	createDocumentToMdast,
+	createFieldBlockToMdast,
+	createFieldInlineToMdast,
+	createNaturalBlockToMdast,
+	createNaturalExpressionToMdast,
+	createSectionBlockToMdast,
+];
+
+export type * from './types';

package/src/serializer/tags/index.ts

@@ -0,0 +1,2 @@
+export { tagToMdast } from './tagToMdast';
+export { tagsToMdast } from './tagsToMdast';

package/src/serializer/tags/tagToMdast.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from 'vitest';
+
+import { tagToMdast } from './tagToMdast';
+
+describe('tagToMdast', () => {
+	it('WHEN called returns a text node with the tag name', () => {
+		const result = tagToMdast({ construct: 'Tag', name: 'friend' });
+		expect(result).toEqual({ type: 'text', value: '(#friend)' });
+	});
+});

package/src/serializer/tags/tagToMdast.ts

@@ -0,0 +1,7 @@
+import type { Text } from 'mdast';
+
+import type { Tag } from '../../factories';
+
+export function tagToMdast(tag: Tag): Text {
+	return { type: 'text', value: `(#${tag.name})` };
+}

package/src/serializer/tags/tagsToMdast.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { tagToMdastMock } from '../../test/helpers';
+
+import { tagsToMdast } from './tagsToMdast';
+
+vi.mock('./tagToMdast', () => {
+	return tagToMdastMock();
+});
+
+describe('tagsToMdast', () => {
+	it('WHEN joining tag values into a text node', async () => {
+		const result = tagsToMdast([
+			{ construct: 'Tag', name: 'a' },
+			{ construct: 'Tag', name: 'b' },
+		]);
+		expect(result).toEqual({ type: 'text', value: ' (#a) (#b)' });
+	});
+});

package/src/serializer/tags/tagsToMdast.ts

@@ -0,0 +1,10 @@
+import type { Text } from 'mdast';
+
+import type { Tag } from '../../factories';
+
+import { tagToMdast } from './tagToMdast';
+
+export function tagsToMdast(tags: Tag[]): Text {
+	const value = tags.map(tag => tagToMdast(tag).value).join(' ');
+	return { type: 'text', value: ` ${value}` };
+}

package/src/serializer/types.ts

@@ -0,0 +1,10 @@
+import type { Node } from 'mdast';
+
+import type { Construct } from '../factories';
+
+export type ConstructSerializer = {
+	readonly name: string;
+	toMdast(node: Construct, children: Node[]): Node;
+};
+
+export type ConstructSerializerFactory = () => ConstructSerializer;

package/src/test/helpers/constructs/FieldBlock/createFieldBlockFromNodeMock.ts

@@ -0,0 +1,17 @@
+/**
+ * @mocks createFieldBlockFromNode() from `src/constructs/FieldBlock/private/helpers`
+ */
+
+import { vi } from 'vitest';
+
+export const createFieldBlockFromNodeMock = (
+	name: string = 'Test',
+): {
+	createFieldBlockFromNode: ReturnType<typeof vi.fn>;
+} => ({
+	createFieldBlockFromNode: vi.fn(() => ({
+		construct: 'FieldBlock',
+		name,
+		children: [],
+	})),
+});

package/src/test/helpers/constructs/FieldBlock/createFieldBlockMock.ts

@@ -0,0 +1,17 @@
+/**
+ * @mocks createFieldBlock() from `src/constructs/FieldBlock/private/factory`
+ */
+
+import { vi } from 'vitest';
+
+export const createFieldBlockMock = (
+	name: string = 'Test',
+): {
+	createFieldBlock: ReturnType<typeof vi.fn>;
+} => ({
+	createFieldBlock: vi.fn(() => ({
+		construct: 'FieldBlock',
+		name,
+		children: [],
+	})),
+});

package/src/test/helpers/constructs/FieldBlock/makeFieldBlockFixture.ts

@@ -0,0 +1,16 @@
+/**
+ * @fixture FieldBlock of factory`libs/constructs/src/constructs/FieldBlock/factory/createFieldBlock.ts`
+ */
+
+import type { FieldBlock, Tag } from '../../../../factories';
+
+export const makeFieldBlockFixture = (options?: {
+	name?: string;
+	children?: FieldBlock['children'];
+	tags?: Tag[];
+}): FieldBlock => ({
+	construct: 'FieldBlock',
+	name: options?.name ?? 'Test',
+	children: options?.children ?? [],
+	...(options?.tags !== undefined ? { tags: options.tags } : {}),
+});

package/src/test/helpers/constructs/FieldBlock/makeFieldBlockMock.ts

@@ -0,0 +1,16 @@
+/**
+ * @fixture FieldBlock of factory`libs/constructs/src/constructs/FieldBlock/private/factory/createFieldBlock.ts`
+ */
+
+import type { FieldBlock, Tag } from '../../../../factories';
+
+export const makeFieldBlockMock = (options?: {
+	name?: string;
+	children?: FieldBlock['children'];
+	tags?: Tag[];
+}): FieldBlock => ({
+	construct: 'FieldBlock',
+	name: options?.name ?? 'Test',
+	children: options?.children ?? [],
+	...(options?.tags !== undefined ? { tags: options.tags } : {}),
+});

package/src/test/helpers/constructs/FieldInline/createFieldInlineFromNodeMock.ts

@@ -0,0 +1,17 @@
+/**
+ * @mocks createFieldInlineFromNode() from `src/constructs/FieldInline/private/helpers`
+ */
+
+import { vi } from 'vitest';
+
+export const createFieldInlineFromNodeMock = (
+	name: string = 'Test',
+): {
+	createFieldInlineFromNode: ReturnType<typeof vi.fn>;
+} => ({
+	createFieldInlineFromNode: vi.fn(() => ({
+		construct: 'FieldInline',
+		name,
+		children: [],
+	})),
+});

package/src/test/helpers/constructs/FieldInline/createFieldInlineMock.ts

@@ -0,0 +1,17 @@
+/**
+ * @mocks createFieldInline() from `src/constructs/FieldInline/private/factory`
+ */
+
+import { vi } from 'vitest';
+
+export const createFieldInlineMock = (
+	name: string = 'Test',
+): {
+	createFieldInline: ReturnType<typeof vi.fn>;
+} => ({
+	createFieldInline: vi.fn(() => ({
+		construct: 'FieldInline',
+		name,
+		children: [],
+	})),
+});

package/src/test/helpers/constructs/FieldInline/makeFieldInlineFixture.ts

@@ -0,0 +1,16 @@
+/**
+ * @fixture FieldInline of factory`libs/constructs/src/constructs/FieldInline/factory/createFieldInline.ts`
+ */
+
+import type { FieldInline, Tag } from '../../../../factories';
+
+export const makeFieldInlineFixture = (options?: {
+	name?: string;
+	children?: FieldInline['children'];
+	tags?: Tag[];
+}): FieldInline => ({
+	construct: 'FieldInline',
+	name: options?.name ?? 'Test',
+	children: options?.children ?? [],
+	...(options?.tags !== undefined ? { tags: options.tags } : {}),
+});

package/src/test/helpers/constructs/FieldInline/makeFieldInlineMock.ts

@@ -0,0 +1,16 @@
+/**
+ * @fixture FieldInline of factory`libs/constructs/src/constructs/FieldInline/private/factory/createFieldInline.ts`
+ */
+
+import type { FieldInline, Tag } from '../../../../factories';
+
+export const makeFieldInlineMock = (options?: {
+	name?: string;
+	children?: FieldInline['children'];
+	tags?: Tag[];
+}): FieldInline => ({
+	construct: 'FieldInline',
+	name: options?.name ?? 'Test',
+	children: options?.children ?? [],
+	...(options?.tags !== undefined ? { tags: options.tags } : {}),
+});

package/src/test/helpers/constructs/NaturalBlock/createNaturalBlockFromNodeMock.ts

@@ -0,0 +1,17 @@
+/**
+ * @mocks createNaturalBlockFromNode() from `src/constructs/NaturalBlock/private/helpers`
+ */
+
+import { vi } from 'vitest';
+
+export const createNaturalBlockFromNodeMock = (
+	value: string = 'hello',
+): {
+	createNaturalBlockFromNode: ReturnType<typeof vi.fn>;
+} => ({
+	createNaturalBlockFromNode: vi.fn(() => ({
+		construct: 'NaturalBlock',
+		value,
+		children: [],
+	})),
+});

package/src/test/helpers/constructs/NaturalBlock/createNaturalBlockMock.ts

@@ -0,0 +1,17 @@
+/**
+ * @mocks createNaturalBlock() from `src/constructs/NaturalBlock/private/factory`
+ */
+
+import { vi } from 'vitest';
+
+export const createNaturalBlockMock = (
+	value: string = 'hello',
+): {
+	createNaturalBlock: ReturnType<typeof vi.fn>;
+} => ({
+	createNaturalBlock: vi.fn(() => ({
+		construct: 'NaturalBlock',
+		value,
+		children: [],
+	})),
+});

package/src/test/helpers/constructs/NaturalBlock/makeNaturalBlockFixture.ts

@@ -0,0 +1,22 @@
+/**
+ * @fixture NaturalBlock of factory`libs/constructs/src/constructs/NaturalBlock/factory/createNaturalBlock.ts`
+ */
+
+import type { NaturalBlock, Tag } from '../../../../factories';
+
+export const makeNaturalBlockFixture = (options?: {
+	value?: string;
+	type?: string;
+	lang?: string | null;
+	meta?: string | null;
+	children?: NaturalBlock['children'];
+	tags?: Tag[];
+}): NaturalBlock => ({
+	construct: 'NaturalBlock',
+	value: options?.value ?? 'hello',
+	children: options?.children ?? [],
+	...(options?.type !== undefined ? { type: options.type } : {}),
+	...(options?.lang !== undefined ? { lang: options.lang } : {}),
+	...(options?.meta !== undefined ? { meta: options.meta } : {}),
+	...(options?.tags !== undefined ? { tags: options.tags } : {}),
+});

package/src/test/helpers/constructs/NaturalBlock/makeNaturalBlockMock.ts

@@ -0,0 +1,22 @@
+/**
+ * @fixture NaturalBlock of factory`libs/constructs/src/constructs/NaturalBlock/private/factory/createNaturalBlock.ts`
+ */
+
+import type { NaturalBlock, Tag } from '../../../../factories';
+
+export const makeNaturalBlockMock = (options?: {
+	value?: string;
+	type?: string;
+	lang?: string | null;
+	meta?: string | null;
+	children?: NaturalBlock['children'];
+	tags?: Tag[];
+}): NaturalBlock => ({
+	construct: 'NaturalBlock',
+	value: options?.value ?? 'hello',
+	children: options?.children ?? [],
+	...(options?.type !== undefined ? { type: options.type } : {}),
+	...(options?.lang !== undefined ? { lang: options.lang } : {}),
+	...(options?.meta !== undefined ? { meta: options.meta } : {}),
+	...(options?.tags !== undefined ? { tags: options.tags } : {}),
+});

package/src/test/helpers/constructs/NaturalExpression/makeNaturalExpressionFixture.ts

@@ -0,0 +1,18 @@
+/**
+ * @fixture NaturalExpression of factory`libs/constructs/src/constructs/NaturalExpression/factory/createNaturalExpression.ts`
+ */
+
+import type { NaturalExpression } from '../../../../factories';
+
+export const makeNaturalExpressionFixture = (options?: {
+	type?: string;
+	value?: string;
+	attributes?: Record<string, unknown>;
+	children?: NaturalExpression['children'];
+}): NaturalExpression => ({
+	construct: 'NaturalExpression',
+	type: options?.type ?? 'text',
+	value: options?.value ?? 'hello',
+	children: options?.children ?? [],
+	...(options?.attributes !== undefined ? { attributes: options.attributes } : {}),
+});

package/src/test/helpers/constructs/NaturalExpression/makeNaturalExpressionMock.ts

@@ -0,0 +1,18 @@
+/**
+ * @fixture NaturalExpression of factory`libs/constructs/src/constructs/NaturalExpression/private/factory/createNaturalExpression.ts`
+ */
+
+import type { NaturalExpression } from '../../../../factories';
+
+export const makeNaturalExpressionMock = (options?: {
+	type?: string;
+	value?: string;
+	attributes?: Record<string, unknown>;
+	children?: NaturalExpression['children'];
+}): NaturalExpression => ({
+	construct: 'NaturalExpression',
+	type: options?.type ?? 'text',
+	value: options?.value ?? 'hello',
+	children: options?.children ?? [],
+	...(options?.attributes !== undefined ? { attributes: options.attributes } : {}),
+});

package/src/test/helpers/constructs/SectionBlock/createSectionBlockFromNodeMock.ts

@@ -0,0 +1,17 @@
+/**
+ * @mocks createSectionBlockFromNode() from `src/constructs/SectionBlock/private/helpers`
+ */
+
+import { vi } from 'vitest';
+
+export const createSectionBlockFromNodeMock = (
+	name: string = 'Test',
+): {
+	createSectionBlockFromNode: ReturnType<typeof vi.fn>;
+} => ({
+	createSectionBlockFromNode: vi.fn(() => ({
+		construct: 'SectionBlock',
+		name,
+		children: [],
+	})),
+});

package/src/test/helpers/constructs/SectionBlock/createSectionBlockMock.ts

@@ -0,0 +1,17 @@
+/**
+ * @mocks createSectionBlock() from `src/constructs/SectionBlock/private/factory`
+ */
+
+import { vi } from 'vitest';
+
+export const createSectionBlockMock = (
+	name: string = 'Test',
+): {
+	createSectionBlock: ReturnType<typeof vi.fn>;
+} => ({
+	createSectionBlock: vi.fn(() => ({
+		construct: 'SectionBlock',
+		name,
+		children: [],
+	})),
+});

package/src/test/helpers/constructs/SectionBlock/makeSectionBlockFixture.ts

@@ -0,0 +1,20 @@
+/**
+ * @fixture SectionBlock of factory`libs/constructs/src/constructs/SectionBlock/factory/createSectionBlock.ts`
+ */
+
+import type { SectionBlock, Tag } from '../../../../factories';
+
+export const makeSectionBlockFixture = (options?: {
+	name?: string;
+	depth?: number;
+	kind?: string;
+	children?: SectionBlock['children'];
+	tags?: Tag[];
+}): SectionBlock => ({
+	construct: 'SectionBlock',
+	name: options?.name ?? 'Test',
+	children: options?.children ?? [],
+	...(options?.depth !== undefined ? { depth: options.depth } : {}),
+	...(options?.kind !== undefined ? { kind: options.kind } : {}),
+	...(options?.tags !== undefined ? { tags: options.tags } : {}),
+});

package/src/test/helpers/constructs/Tag/makeTagFixture.ts

@@ -0,0 +1,10 @@
+/**
+ * @fixture Tag of factory`libs/constructs/src/constructs/Tag/factory/createTag.ts`
+ */
+
+import type { Tag } from '../../../../factories';
+
+export const makeTagFixture = (options?: { name?: string }): Tag => ({
+	construct: 'Tag',
+	name: options?.name ?? 'test',
+});

package/src/test/helpers/constructs/index.ts

@@ -0,0 +1,14 @@
+export * from './FieldBlock/createFieldBlockFromNodeMock';
+export * from './FieldBlock/createFieldBlockMock';
+export * from './FieldBlock/makeFieldBlockFixture';
+export * from './FieldInline/createFieldInlineFromNodeMock';
+export * from './FieldInline/createFieldInlineMock';
+export * from './FieldInline/makeFieldInlineFixture';
+export * from './NaturalBlock/createNaturalBlockFromNodeMock';
+export * from './NaturalBlock/createNaturalBlockMock';
+export * from './NaturalBlock/makeNaturalBlockFixture';
+export * from './NaturalExpression/makeNaturalExpressionFixture';
+export * from './SectionBlock/createSectionBlockFromNodeMock';
+export * from './SectionBlock/createSectionBlockMock';
+export * from './SectionBlock/makeSectionBlockFixture';
+export * from './Tag/makeTagFixture';

package/src/test/helpers/index.ts

@@ -0,0 +1,2 @@
+export * from './constructs';
+export * from './parsers';

package/src/test/helpers/parsers/fields/stripStrongMock.ts

@@ -0,0 +1,11 @@
+/**
+ * @mocks stripStrong()  from `src/parsers/fields`
+ */
+
+import { vi } from 'vitest';
+
+export const stripStrongMock = (
+	returnValue: string = '',
+): { stripStrong: ReturnType<typeof vi.fn> } => ({
+	stripStrong: vi.fn(() => returnValue),
+});

package/src/test/helpers/parsers/index.ts

@@ -0,0 +1,5 @@
+export * from './fields/stripStrongMock';
+export * from './mdast/rawSliceMock';
+export * from './natural-expression/createNaturalExpressionFromNodeMock';
+export * from './tags/extractTagsMock';
+export * from './tags/tagToMdastMock';

package/src/test/helpers/parsers/mdast/rawSliceMock.ts

@@ -0,0 +1,9 @@
+/**
+ * @mocks rawSlice() from `src/parsers/mdast`
+ */
+
+import { vi } from 'vitest';
+
+export const rawSliceMock = (returnValue: string = ''): { rawSlice: ReturnType<typeof vi.fn> } => ({
+	rawSlice: vi.fn(() => returnValue),
+});