@art-md/constructs 0.0.4 → 0.0.6

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# CHANGELOG
+
+## 0.0.6
+
+### Changed
+
+- **Update dependencies** - `mdast-util-from-markdown@2.1.0`
+
+## 0.0.5
+
+### Fixed
+
+- **Package exports** — now target the dist build rather than the TypeScript source.
+
+## 0.0.4
+
+### Removed
+
+- **`kind` from `SectionBlock` (breaking):** the `kind?` member is gone from the type, the factory data, and `createSectionBlock`. A heading's text is never split: `SectionBlock.name` is the whole heading text. Consumers that interpret headings as `Kind: Name` parse the text themselves.
+
+### Docs
+
+- **Round-trip fidelity:** full-text names serialise verbatim — a heading such as `## Module: Greeting` no longer degrades to `## Greeting` on write. Claim restated as structural fidelity, not byte-identity: extraneous whitespace, CRLF, and heading indentation are normalised per CommonMark; exactly one final newline.
+
+## 0.0.3
+
+### Fixed
+
+- **Package entry point:** `main` declares `./src/index.ts`, but `files` published only `dist/`, publish `src/` instead.
+
+## 0.0.2
+
+### Documented
+
+- Architecture knowledge and README updated.
+
+## 0.0.1
+
+### Added
+
+- **Construct registry:** open block and inline construct maps with extension via declaration merging, and the `Construct` union with `BlockContent`/`InlineContent` subsets.
+- **Construct factories:** factory functions building each construct record from plain factory-data.
+- **Construct Parser contract:** `ConstructProcessor`, `ConstructIntegrator`, `ConstructParser`, and `ConstructParserFactory` hooks that drive construct-agnostic detection.
+- **Construct Parser registry:** ordered `CONSTRUCT_PARSERS` factory list, `DEFAULT_CONSTRUCT_PARSER` fallback, and document root creation.
+- **Construct Serializer contract:** `ConstructSerializer` and `ConstructSerializerFactory`, registering adapters by construct name.
+- **Construct Serializer registry:** `CONSTRUCT_SERIALIZERS` factory list for markdown restoration.
+- **Document:** document root construct produced from the mdast tree.
+- **Construct: Tag:** trailing `(#tag)` metadata construct shared across tag-supporting constructs.
+- **Construct: NaturalExpression:** pass-through expression retaining mdast type, attributes, value, and recursive children.
+- **Construct: NaturalBlock:** fallback construct capturing unclaimed block content as natural markdown.
+- **Construct: FieldInline:** inline field with a `**Name:**` label, phrasing children converted to expressions, and trailing `(#tag)` tags.
+- **Construct: FieldBlock:** block field with a `**Name:**` label that captures following blocks as children until a boundary construct arrives.
+- **Construct: SectionBlock:** heading-based nesting construct with depth hierarchy, kind detection, and `(#tag)` tags.
+- **Shared parsing helpers:** field-label detection, raw source slicing, trailing `(#tag)` extraction, and natural expression conversion.
+- **Shared serialization helpers:** `(#tag)` restoration in the correct position.
+
+### Tested
+
+- Exhaustive unit coverage for all construct factories, parser hooks, serializers, and shared helpers.
+
+### Documented
+
+- Architecture references for the API, factories, parsers, and serializers.

package/README.md

@@ -12,7 +12,7 @@ Make sure you read the [Art MD README](../../README.md) first.
 
 ### Build Targets
 
-This library is packaged for use in bundlers such as Vite and Astro. The main entry point is the TypeScript source code.
+This package is meant for use in Node.js environments. The entry point is built using `esbuild` pre-configured by [Workspace Tooling](https://github.com/noodlestan/workspace-tooling).
 
 ### Scripts
 

package/dist/factories/constructs/Document/factory/createDocument.d.ts

@@ -0,0 +1,3 @@
+import { type ArtDocument } from '@art-md/primitives';
+import type { DocumentFactoryData } from './types.js';
+export declare function createDocument(data: DocumentFactoryData): ArtDocument;

package/dist/factories/constructs/Document/factory/types.d.ts

@@ -0,0 +1,4 @@
+import type { BlockContent } from '../../../types.js';
+export type DocumentFactoryData = {
+    children?: BlockContent[];
+};

package/dist/factories/constructs/Document/index.d.ts

@@ -0,0 +1,2 @@
+export { createDocument } from './factory/createDocument.js';
+export type { DocumentFactoryData } from './factory/types.js';

package/dist/factories/constructs/FieldBlock/factory/createFieldBlock.d.ts

@@ -0,0 +1,3 @@
+import type { FieldBlock } from '../types.js';
+import type { FieldBlockFactoryData } from './types.js';
+export declare function createFieldBlock(data: FieldBlockFactoryData): FieldBlock;

package/dist/factories/constructs/FieldBlock/factory/types.d.ts

@@ -0,0 +1,7 @@
+import type { BlockContent } from '../../../types.js';
+import type { Tag } from '../../Tag/index.js';
+export type FieldBlockFactoryData = {
+    name: string;
+    children?: BlockContent[];
+    tags?: Tag[];
+};

package/dist/factories/constructs/FieldBlock/index.d.ts

@@ -0,0 +1,3 @@
+export { createFieldBlock } from './factory/createFieldBlock.js';
+export type { FieldBlock } from './types.js';
+export type { FieldBlockFactoryData } from './factory/types.js';

package/dist/factories/constructs/FieldBlock/types.d.ts

@@ -0,0 +1,9 @@
+import type { ContainerConstructBase } from '@art-md/primitives';
+import type { BlockContent } from '../../types.js';
+import type { Tag } from '../Tag/index.js';
+export type FieldBlock = ContainerConstructBase & {
+    construct: 'FieldBlock';
+    name: string;
+    children: BlockContent[];
+    tags?: Tag[];
+};

package/dist/factories/constructs/FieldInline/factory/createFieldInline.d.ts

@@ -0,0 +1,3 @@
+import type { FieldInline } from '../types.js';
+import type { FieldInlineFactoryData } from './types.js';
+export declare function createFieldInline(data: FieldInlineFactoryData): FieldInline;

package/dist/factories/constructs/FieldInline/factory/types.d.ts

@@ -0,0 +1,7 @@
+import type { NaturalExpression } from '../../NaturalExpression/index.js';
+import type { Tag } from '../../Tag/index.js';
+export type FieldInlineFactoryData = {
+    name: string;
+    children?: NaturalExpression[];
+    tags?: Tag[];
+};

package/dist/factories/constructs/FieldInline/index.d.ts

@@ -0,0 +1,3 @@
+export { createFieldInline } from './factory/createFieldInline.js';
+export type { FieldInline } from './types.js';
+export type { FieldInlineFactoryData } from './factory/types.js';

package/dist/factories/constructs/FieldInline/types.d.ts

@@ -0,0 +1,9 @@
+import type { ContainerConstructBase } from '@art-md/primitives';
+import type { NaturalExpression } from '../NaturalExpression/index.js';
+import type { Tag } from '../Tag/index.js';
+export type FieldInline = ContainerConstructBase & {
+    construct: 'FieldInline';
+    name: string;
+    children: NaturalExpression[];
+    tags?: Tag[];
+};

package/dist/factories/constructs/NaturalBlock/factory/createNaturalBlock.d.ts

@@ -0,0 +1,3 @@
+import type { NaturalBlock } from '../types.js';
+import type { NaturalBlockFactoryData } from './types.js';
+export declare function createNaturalBlock(data: NaturalBlockFactoryData): NaturalBlock;

package/dist/factories/constructs/NaturalBlock/factory/types.d.ts

@@ -0,0 +1,11 @@
+import type { ContainerConstructBase } from '@art-md/primitives';
+import type { Tag } from '../../Tag/index.js';
+export type NaturalBlockFactoryData = {
+    value: string;
+    children: ContainerConstructBase[];
+    type?: string;
+    lang?: string | null;
+    meta?: string | null;
+    tags?: Tag[];
+    attributes?: Record<string, unknown>;
+};

package/dist/factories/constructs/NaturalBlock/index.d.ts

@@ -0,0 +1,3 @@
+export { createNaturalBlock } from './factory/createNaturalBlock.js';
+export type { NaturalBlock } from './types.js';
+export type { NaturalBlockFactoryData } from './factory/types.js';

package/dist/factories/constructs/NaturalBlock/types.d.ts

@@ -0,0 +1,12 @@
+import type { ContainerConstructBase } from '@art-md/primitives';
+import type { Tag } from '../Tag/index.js';
+export type NaturalBlock = ContainerConstructBase & {
+    construct: 'NaturalBlock';
+    value: string;
+    children: ContainerConstructBase[];
+    type?: string;
+    lang?: string | null;
+    meta?: string | null;
+    tags?: Tag[];
+    [key: string]: unknown;
+};

package/dist/factories/constructs/NaturalExpression/factory/createNaturalExpression.d.ts

@@ -0,0 +1,3 @@
+import type { NaturalExpression } from '../types.js';
+import type { NaturalExpressionFactoryData } from './types.js';
+export declare function createNaturalExpression(data: NaturalExpressionFactoryData): NaturalExpression;

package/dist/factories/constructs/NaturalExpression/factory/types.d.ts

@@ -0,0 +1,7 @@
+import type { NaturalExpression } from '../types.js';
+export type NaturalExpressionFactoryData = {
+    type: string;
+    value?: string;
+    attributes?: Record<string, unknown>;
+    children?: NaturalExpression[];
+};

package/dist/factories/constructs/NaturalExpression/index.d.ts

@@ -0,0 +1,3 @@
+export { createNaturalExpression } from './factory/createNaturalExpression.js';
+export type { NaturalExpression } from './types.js';
+export type { NaturalExpressionFactoryData } from './factory/types.js';

package/dist/factories/constructs/NaturalExpression/types.d.ts

@@ -0,0 +1,8 @@
+import type { ContainerConstructBase } from '@art-md/primitives';
+export type NaturalExpression = ContainerConstructBase & {
+    construct: 'NaturalExpression';
+    type: string;
+    attributes?: Record<string, unknown>;
+    value?: string;
+    children: NaturalExpression[];
+};

package/dist/factories/constructs/SectionBlock/factory/createSectionBlock.d.ts

@@ -0,0 +1,3 @@
+import type { SectionBlock } from '../types.js';
+import type { SectionBlockFactoryData } from './types.js';
+export declare function createSectionBlock(data: SectionBlockFactoryData): SectionBlock;

package/dist/factories/constructs/SectionBlock/factory/types.d.ts

@@ -0,0 +1,8 @@
+import type { ConstructBase } from '@art-md/primitives';
+import type { Tag } from '../../Tag/index.js';
+export type SectionBlockFactoryData = {
+    name: string;
+    depth?: number;
+    children?: ConstructBase[];
+    tags?: Tag[];
+};

package/dist/factories/constructs/SectionBlock/index.d.ts

@@ -0,0 +1,3 @@
+export { createSectionBlock } from './factory/createSectionBlock.js';
+export type { SectionBlock } from './types.js';
+export type { SectionBlockFactoryData } from './factory/types.js';

package/dist/factories/constructs/SectionBlock/types.d.ts

@@ -0,0 +1,9 @@
+import type { ConstructBase, ContainerConstructBase } from '@art-md/primitives';
+import type { Tag } from '../Tag/index.js';
+export type SectionBlock = ContainerConstructBase & {
+    construct: 'SectionBlock';
+    name: string;
+    tags?: Tag[];
+    children: ConstructBase[];
+    depth?: number;
+};

package/dist/factories/constructs/Tag/factory/createTag.d.ts

@@ -0,0 +1,3 @@
+import type { Tag } from '../types.js';
+import type { TagFactoryData } from './types.js';
+export declare function createTag(tagData: TagFactoryData): Tag;

package/dist/factories/constructs/Tag/factory/types.d.ts

@@ -0,0 +1,3 @@
+export type TagFactoryData = {
+    name: string;
+};

package/dist/factories/constructs/Tag/index.d.ts

@@ -0,0 +1,3 @@
+export { createTag } from './factory/createTag.js';
+export type { Tag } from './types.js';
+export type { TagFactoryData } from './factory/types.js';

package/dist/factories/constructs/Tag/types.d.ts

@@ -0,0 +1,5 @@
+import type { ConstructBase } from '@art-md/primitives';
+export type Tag = ConstructBase & {
+    construct: 'Tag';
+    name: string;
+};

package/dist/factories/index.d.ts

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

package/dist/factories/public.d.ts

@@ -0,0 +1,36 @@
+import { createDocument } from './constructs/Document/index.js';
+import { createFieldBlock } from './constructs/FieldBlock/index.js';
+import { createFieldInline } from './constructs/FieldInline/index.js';
+import { createNaturalBlock } from './constructs/NaturalBlock/index.js';
+import { createNaturalExpression } from './constructs/NaturalExpression/index.js';
+import { createSectionBlock } from './constructs/SectionBlock/index.js';
+import { createTag } from './constructs/Tag/index.js';
+export type { FieldBlock } from './constructs/FieldBlock/index.js';
+export type { FieldInline } from './constructs/FieldInline/index.js';
+export type { NaturalBlock } from './constructs/NaturalBlock/index.js';
+export type { NaturalExpression } from './constructs/NaturalExpression/index.js';
+export type { SectionBlock } from './constructs/SectionBlock/index.js';
+export type { Tag } from './constructs/Tag/index.js';
+export type * from './types.js';
+export declare const FACTORIES: ({
+    name: string;
+    factory: typeof createDocument;
+} | {
+    name: string;
+    factory: typeof createFieldBlock;
+} | {
+    name: string;
+    factory: typeof createFieldInline;
+} | {
+    name: string;
+    factory: typeof createNaturalBlock;
+} | {
+    name: string;
+    factory: typeof createNaturalExpression;
+} | {
+    name: string;
+    factory: typeof createSectionBlock;
+} | {
+    name: string;
+    factory: typeof createTag;
+})[];

package/dist/factories/types.d.ts

@@ -0,0 +1,31 @@
+import type { FieldBlock } from './constructs/FieldBlock/index.js';
+import type { FieldInline } from './constructs/FieldInline/index.js';
+import type { NaturalBlock } from './constructs/NaturalBlock/index.js';
+import type { NaturalExpression } from './constructs/NaturalExpression/index.js';
+import type { SectionBlock } from './constructs/SectionBlock/index.js';
+import type { Tag } from './constructs/Tag/index.js';
+/**
+ * Open registry of block-level constructs. Augment via declaration merging when new constructs land.
+ *
+ * @conventions-ignore Conventions: Typescript / Types / No Interface
+ */
+export interface BlockConstructMap {
+    SectionBlock: SectionBlock;
+    FieldBlock: FieldBlock;
+    FieldInline: FieldInline;
+    NaturalBlock: NaturalBlock;
+}
+/**
+ * Open registry of inline/expression-level constructs. Augment via declaration merging when new constructs land.
+ *
+ * @conventions-ignore Conventions: Typescript / Types / No Interface
+ */
+export interface InlineConstructMap {
+    NaturalExpression: NaturalExpression;
+    Tag: Tag;
+}
+/** Open registry of all constructs. */
+export type ConstructMap = BlockConstructMap & InlineConstructMap;
+export type BlockContent = BlockConstructMap[keyof BlockConstructMap];
+export type InlineContent = InlineConstructMap[keyof InlineConstructMap];
+export type Construct = ConstructMap[keyof ConstructMap];

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './factories/public.js';
+export * from './parser/public.js';
+export * from './serializer/public.js';