@cudoment/cudoc 0.1.0 → 0.3.0

package/README.md

@@ -1,58 +1,31 @@
 # @cudoment/cudoc
 
-Reuse document sections and tables from compiled MDX ASTs. Export a snapshot during compilation, load it on the server, select content by a stable anchor and render it with your site's components.
+Markdown document semantics, compilation, AST queries, cross-document embedding and dataset projection.
 
-```bash
-npm install @cudoment/cudoc
-```
-
-## Embedding
-
-Add the export plugin after the transforms whose results you want to store:
+ESM · Node.js 20+
 
-```js
-import exportAst from "@cudoment/cudoc/embed"
-
-const remarkPlugins = [
-  // Your remark transforms go here.
-  [exportAst, { sourceRoot: "docs", outDir: ".cudoc/ast" }],
-]
+```sh
+npm install @cudoment/cudoc
 ```
 
-Once the source document has compiled, read it in a server component or build script:
-
 ```js
-import { loadAst, sliceSectionByAnchorId } from "@cudoment/cudoc/embed"
-
-const document = loadAst("guide/limits", { outDir: ".cudoc/ast" })
-const section = sliceSectionByAnchorId(document, "rate-limits")
-if (!section) throw new Error("Missing section: rate-limits")
-// Render section.children with your site's components.
+import { compileDocument } from "@cudoment/cudoc/markdown"
+import { renderDocument } from "@cudoment/cudoc/render"
+
+const { tree } = compileDocument(
+  "## Setup (#setup)\n\n> [!NOTE] Requirements\n> Node.js 20+.",
+  { format: "md", syntax: {} },
+)
+const html = renderDocument(tree)
 ```
 
-The snapshot is the host's remark tree at the export plugin. Later host transforms and MDX component execution are outside it. Export and load validate the same AST contract and schema version. Section slices preserve referenced link, image and footnote definitions.
-
-Source compilation must finish before loading an embed. Keep compiler caches and exported ASTs together, and include the JSON files in deployments that read them at runtime. Queries do not execute MDX expressions; rendering and missing-reference policy belong to the consuming site.
-
-## Entry points
-
-| Import                                                                 | Runtime         | Purpose                                                 |
-| ---------------------------------------------------------------------- | --------------- | ------------------------------------------------------- |
-| `@cudoment/cudoc`                                                      | Browser or Node | AST contract, validation, traversal, syntax and queries |
-| `@cudoment/cudoc/query`                                                | Browser or Node | Sections, headings, text and table queries              |
-| `@cudoment/cudoc/ast`, `@cudoment/cudoc/syntax`, `@cudoment/cudoc/mdx` | Browser or Node | Focused common APIs                                     |
-| `@cudoment/cudoc/embed`                                                | Node            | AST export, loading and queries together                |
-| `@cudoment/cudoc/node/load-ast-file`                                   | Node            | Load a known JSON file without build-time path mapping  |
-| `@cudoment/cudoc/node/export-ast`, `@cudoment/cudoc/node/paths`        | Node            | Focused export and path APIs                            |
-
-All entries share one internal core. Internal source paths are not public exports and the core is not a separate npm package. Browser imports never depend on the Node entry points.
-
-For a server bundle that traces files, use `loadAstFile` from `@cudoment/cudoc/node/load-ast-file` with a concrete file path and configure your host's output file tracing.
-
-The optional `cudoc-remark`, `cudoc-docusaurus` and `cudoc-nextra` packages provide syntax transforms and host integration. Their publication is separate from this package.
-
-See the [embedding guide](https://github.com/cudoment/cudoc/blob/main/docs/embedding.md) and [project README](https://github.com/cudoment/cudoc#readme).
+The root and query APIs provide reusable AST operations. Import compilation from `/markdown`, rendering from `/render`, and collection from `/node/library`. Node entry points belong in build/server code. `/embed` handles individual AST snapshots; complete libraries and fenced embeds use the explicit `node/*` APIs. The core has no React runtime dependency.
 
-## License
+Choose `host`, `cudoc` or `both` independently for `headingAnchor`, `badge`, `tableCellList`, `callout` and `link`. The representative callout is `> [!NOTE] Title`. Authors do not register cudoc React components in the recommended setup. Syntax-only rendering needs no stored JSON; cross-document embedding requires document collection.
 
-[MIT](./LICENSE)
+- [Usage guide](https://github.com/cudoment/cudoc/tree/main/README.md#getting-started) · [한국어 가이드](https://github.com/cudoment/cudoc/tree/main/README.ko.md#시작하기)
+- [Markdown syntax](https://github.com/cudoment/cudoc/tree/main/docs/syntax.md)
+- [Embedding](https://github.com/cudoment/cudoc/tree/main/docs/embedding.md)
+- [Standalone HTML alongside a host](https://github.com/cudoment/cudoc/tree/main/docs/html.md#export-alongside-an-existing-site)
+- [API reference](https://github.com/cudoment/cudoc/tree/main/docs/api-reference/README.md)
+- [Runnable examples](https://github.com/cudoment/cudoc/tree/main/examples/README.md)

package/dist/dataset.d.ts

@@ -0,0 +1,10 @@
+import type { Root } from "mdast";
+export type ProjectionOptions = {
+    excludeNodeTypes?: string[];
+    excludeComponents?: string[];
+    stripProperties?: string[];
+};
+export declare const docsDatasetProjection: ProjectionOptions;
+/** Immutable recursive projection of already compiled ASTs, including nested nodes. */
+export declare function projectAst(tree: Root, options?: ProjectionOptions): Root;
+//# sourceMappingURL=dataset.d.ts.map

package/dist/dataset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset.d.ts","sourceRoot":"","sources":["../src/dataset.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAIjC,MAAM,MAAM,iBAAiB,GAAG;IAC9B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC3B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC5B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;CAC3B,CAAA;AACD,eAAO,MAAM,qBAAqB,EAAE,iBAUnC,CAAA;AAED,uFAAuF;AACvF,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,iBAAsB,GAAG,IAAI,CAgC5E"}

package/dist/dataset.js

@@ -0,0 +1,44 @@
+import { validateAstContract } from "./internal/core/ast/validate.js";
+export const docsDatasetProjection = {
+    excludeComponents: [
+        "Table",
+        "TableHeader",
+        "TableBody",
+        "TableRow",
+        "TableHead",
+        "TableCell",
+        "DocDataEmbed",
+    ],
+};
+/** Immutable recursive projection of already compiled ASTs, including nested nodes. */
+export function projectAst(tree, options = {}) {
+    validateAstContract(tree);
+    const strip = new Set(options.stripProperties ?? []);
+    if (["type", "children"].some((key) => strip.has(key)))
+        throw new Error("cudoc: cannot strip structural AST properties");
+    const project = (value) => {
+        if (Array.isArray(value))
+            return value.flatMap((item) => {
+                const result = project(item);
+                return result === undefined ? [] : [result];
+            });
+        if (!value || typeof value !== "object")
+            return value;
+        const node = value;
+        if (options.excludeNodeTypes?.includes(node.type) ||
+            (node.type?.startsWith("mdxJsx") &&
+                node.name &&
+                options.excludeComponents?.includes(node.name)))
+            return undefined;
+        return Object.fromEntries(Object.entries(value)
+            .filter(([key]) => !strip.has(key))
+            .flatMap(([key, item]) => {
+            const result = project(item);
+            return result === undefined ? [] : [[key, result]];
+        }));
+    };
+    const result = project(tree);
+    validateAstContract(result);
+    return result;
+}
+//# sourceMappingURL=dataset.js.map

package/dist/dataset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset.js","sourceRoot":"","sources":["../src/dataset.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAA;AAOrE,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACtD,iBAAiB,EAAE;QACjB,OAAO;QACP,aAAa;QACb,WAAW;QACX,UAAU;QACV,WAAW;QACX,WAAW;QACX,cAAc;KACf;CACF,CAAA;AAED,uFAAuF;AACvF,MAAM,UAAU,UAAU,CAAC,IAAU,EAAE,UAA6B,EAAE;IACpE,mBAAmB,CAAC,IAAI,CAAC,CAAA;IACzB,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,eAAe,IAAI,EAAE,CAAC,CAAA;IACpD,IAAI,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAA;IAClE,MAAM,OAAO,GAAG,CAAC,KAAc,EAAW,EAAE;QAC1C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YACtB,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;gBAC5B,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;gBAC5B,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;YAC7C,CAAC,CAAC,CAAA;QACJ,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAA;QACrD,MAAM,IAAI,GAAG,KAAqB,CAAA;QAClC,IACE,OAAO,CAAC,gBAAgB,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;YAC7C,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,QAAQ,CAAC;gBAC9B,IAAI,CAAC,IAAI;gBACT,OAAO,CAAC,iBAAiB,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAEjD,OAAO,SAAS,CAAA;QAClB,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;aAClB,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;aAClC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE;YACvB,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;YAC5B,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAA;QACpD,CAAC,CAAC,CACL,CAAA;IACH,CAAC,CAAA;IACD,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAS,CAAA;IACpC,mBAAmB,CAAC,MAAM,CAAC,CAAA;IAC3B,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/document.d.ts

@@ -0,0 +1,80 @@
+/** Portable document semantics. Parser and rendering adapters share this model. */
+import type { Root, PhrasingContent } from "mdast";
+import type { Position } from "unist";
+import { type TableColumnLayoutOptions } from "./internal/transforms/table-column-layout/index.js";
+declare module "mdast" {
+    interface RootData {
+        cudocEmbedPrefix?: string;
+        /**
+         * The schema version, under its default field name. A caller may rename the
+         * field through `AstVersionOptions.field`, so reading it back generically
+         * still goes through `resolveAstVersion`.
+         */
+        cudocAstVersion?: number;
+    }
+}
+export type SyntaxMode = "host" | "cudoc" | "both";
+export type SyntaxOptions = Partial<Record<"headingAnchor" | "badge" | "tableCellList" | "callout" | "link", SyntaxMode>>;
+export type Host = "markdown" | "next" | "docusaurus" | "nextra" | "vitepress" | "eleventy" | "html" | "docs";
+export type DocumentDiagnostic = {
+    code: string;
+    message: string;
+    position?: Position;
+};
+export type DocumentOptions = {
+    syntax?: SyntaxOptions;
+    host?: Host;
+    format?: "md" | "mdx";
+    calloutTypes?: string[];
+    components?: Record<string, {
+        kind: "callout" | "link" | "badge";
+        typeAttribute?: string;
+        titleAttribute?: string;
+        urlAttribute?: string;
+    }>;
+    tableColumnLayout?: TableColumnLayoutOptions[];
+    /** Hosts use their native slugger later. Standalone compilers assign IDs here. */
+    headingIds?: "host" | "generate";
+};
+export type DocumentData = {
+    hName?: string;
+    hProperties?: Record<string, unknown>;
+    cudoc?: {
+        kind: string;
+        type?: string;
+        title?: string;
+        badge?: string;
+        explicitId?: boolean;
+    };
+    [key: string]: unknown;
+};
+export type DocumentNode = {
+    type: string;
+    value?: string;
+    name?: string | null;
+    depth?: number;
+    url?: string;
+    identifier?: string;
+    label?: string;
+    attributes?: unknown;
+    children?: DocumentNode[];
+    position?: Position;
+    data?: DocumentData;
+    [key: string]: unknown;
+};
+export declare const DEFAULT_SYNTAX: Required<SyntaxOptions>;
+export declare function resolveSyntax(syntax?: SyntaxOptions): Required<SyntaxOptions>;
+export declare const visibleHeadingText: (node: DocumentNode) => string;
+export declare const nodeText: (node: DocumentNode) => string;
+export declare const isCudoc: (mode: SyntaxMode) => mode is "cudoc" | "both";
+export declare const isHost: (mode: SyntaxMode) => mode is "host" | "both";
+/** Read static JSX/directive attributes without evaluating expressions. */
+export declare function staticAttributes(node: DocumentNode): Record<string, unknown>;
+export declare function hasDynamicAttributes(node: DocumentNode): boolean;
+export declare const canonicalCalloutType: (type: string) => string;
+export declare function makeCallout(type: string, title: DocumentNode[], children: DocumentNode[], position?: Position): DocumentNode;
+/** Convert generated/static native JSX to mdast data understood by mdast-to-hast. */
+export declare function lowerNativeElements(tree: Root): void;
+/** Mutates the compiler's actual tree. It never reparses the source document. */
+export declare function normalizeDocument(tree: Root, source: string, options?: DocumentOptions, inlineParser?: (source: string) => PhrasingContent[]): DocumentDiagnostic[];
+//# sourceMappingURL=document.d.ts.map

package/dist/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"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"}