@wgtechlabs/mdd-engine 0.1.0-dev.8a1ef77 → 0.1.0-pr.b4e4512

package/README.md

@@ -12,6 +12,7 @@ Built with TypeScript and Bun. Runs on Node.js 22, 24, and 26 without Bun. The d
 my-project/
   mdd/
     config.json           # optional
+    footer.md             # optional shared social links
     contents/
       index.md            # required homepage
       get-started/
@@ -69,9 +70,39 @@ The result includes:
 - `navigation`: sorted folder/page tree, with optional landing URLs.
 - `assets`: referenced content files with checkout-relative sources, documentation-root-relative destinations, and public URLs.
 - `theme`: the built-in default or selected theme file locations.
+- `footer`: optional shared footer source and validated social-link data.
 
 Paths in the model use forward slashes. Resolve sources against the same `projectDir` used to compile. Asset destinations are filesystem paths, while asset URLs and page routes are URL-encoded. Decode page-route segments when deriving output directories. Prefix asset destinations with the documentation output directory when exporting; do not prefix them with a GitHub repository name a second time. The engine emits no files and starts no server.
 
+## Headless search
+
+Build a serializable index from a successful compilation:
+
+```js
+import { createSearchIndex } from '@wgtechlabs/mdd-engine';
+import { search } from '@wgtechlabs/mdd-engine/search';
+
+const index = createSearchIndex(result.site);
+const restored = JSON.parse(JSON.stringify(index));
+console.log(search(restored, 'installation', { limit: 10 }));
+// [{ title, url, section?, excerpt, score }]
+```
+
+The dependency-free `/search` entry point works in browsers and Node. Results reuse compiled page URLs and heading anchors, respect the public base path, and contain plain text for the consuming interface to display safely. MDD owns exporting/loading the index and presenting search controls. See [search matching, limits, and validation](docs/SEARCH.md).
+
+## Shared social footer
+
+Write social links once in `mdd/footer.md`:
+
+```markdown
+:::socials
+- [GitHub](https://github.com/wgtechlabs)
+- [Community](https://example.org/community)
+:::
+```
+
+The engine returns these as `site.footer.socials`, with plain labels and validated absolute HTTPS URLs. It does not render a footer or select icons. MDD composes the main footer and its theme styles it. This file is excluded from pages, navigation, and search; `socials` is not an article component. See the [footer format and boundaries](docs/FOOTER.md).
+
 ## Markdown and components
 
 Supported Markdown includes headings, lists, code fences, links, images, GFM tables, task lists, and strikethrough. Optional YAML frontmatter supports `title`, `description`, `navTitle`, and finite numeric `order`:
@@ -121,7 +152,7 @@ bun run coverage
 bun audit
 ```
 
-`bun run build` emits Node ESM and TypeScript declarations to `dist/`. `bun run smoke` creates a package archive, installs it into an isolated consumer, and runs it with the current Node binary. It checks that Bun is unavailable inside the consumer and that all three base-path fixtures compile. On POSIX systems, `MDD_TEST_NODE_BINARIES` can contain colon-separated Node binary paths to exercise the same archive across versions.
+`bun run build` emits Node ESM and TypeScript declarations to `dist/`. `bun run smoke` creates a package archive, installs it into an isolated consumer, and runs it with the current Node binary. It checks compilation, footer data, and serialized search at all three base paths without Bun in the runtime, and bundles the isolated search entry for browsers. On POSIX systems, `MDD_TEST_NODE_BINARIES` can contain colon-separated Node binary paths to exercise the same archive across versions.
 
 Follow [Clean Workflow](AGENTS.md), [contributing](CONTRIBUTING.md), and the [engine contract](docs/SPEC.md). See [verification](docs/VERIFICATION.md) for the checks performed during bootstrap.
 

package/dist/footer.d.ts

@@ -0,0 +1,3 @@
+import type { Diagnostic, Footer } from "./types.js";
+/** The shared footer is data, never an article or executable author markup. */
+export declare function parseFooter(source: string, file: string, diagnostics: Diagnostic[]): Footer | undefined;

package/dist/footer.js

@@ -0,0 +1,82 @@
+import { parseMarkdown } from "./markdown.js";
+function socialUrl(value) {
+    // Reject URL normalization that could hide a scheme, credentials, or controls.
+    if (!/^https:\/\/[^/?#]/i.test(value) || /[\s\\\p{Cc}\p{Cf}]/u.test(value))
+        return undefined;
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "https:" ||
+            !url.hostname ||
+            url.username ||
+            url.password)
+            return undefined;
+        return url.href;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The shared footer is data, never an article or executable author markup. */
+export function parseFooter(source, file, diagnostics) {
+    if (!source.trim())
+        return undefined;
+    const tree = parseMarkdown(source);
+    const report = (code, message, node) => {
+        diagnostics.push({
+            severity: "error",
+            code,
+            message,
+            file,
+            line: node.position?.start.line,
+            column: node.position?.start.column,
+        });
+    };
+    const component = tree.children[0];
+    if (tree.children.length !== 1 ||
+        component?.type !== "containerDirective" ||
+        component.name !== "socials" ||
+        Object.keys(component.attributes ?? {}).length) {
+        report("INVALID_FOOTER", "Use a single :::socials block without attributes in footer.md.", component ?? tree);
+        return undefined;
+    }
+    const list = component.children[0];
+    if (component.children.length !== 1 ||
+        list?.type !== "list" ||
+        list.ordered ||
+        !list.children.length) {
+        report("INVALID_FOOTER", "The socials block must contain an unordered list of labeled Markdown links.", list ?? component);
+        return undefined;
+    }
+    const socials = [];
+    for (const item of list.children) {
+        const paragraph = item.children[0];
+        const link = paragraph?.type === "paragraph" ? paragraph.children[0] : undefined;
+        if (item.children.length !== 1 ||
+            item.checked != null ||
+            paragraph?.type !== "paragraph" ||
+            paragraph.children.length !== 1 ||
+            link?.type !== "link" ||
+            !link.children.length ||
+            link.children.some((child) => child.type !== "text")) {
+            report("INVALID_SOCIAL_LINK", "Each item must be one Markdown link with a plain text label, without tasks or nested content.", item);
+            continue;
+        }
+        const label = link.children
+            .map((child) => (child.type === "text" ? child.value : ""))
+            .join("")
+            .trim();
+        if (!label) {
+            report("INVALID_SOCIAL_LINK", "Social links need a nonempty label.", link);
+            continue;
+        }
+        const url = socialUrl(link.url);
+        if (!url) {
+            report("UNSAFE_SOCIAL_URL", "Social links must use absolute HTTPS URLs without credentials, whitespace, controls, or backslashes.", link);
+            continue;
+        }
+        socials.push({ label, url });
+    }
+    return socials.length === list.children.length
+        ? { source: file, socials }
+        : undefined;
+}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import type { CompileOptions, CompileResult } from "./types.js";
-export type { Asset, CompileOptions, CompileResult, Diagnostic, Heading, Metadata, NavigationItem, Page, Site, Theme, } from "./types.js";
+export { type SearchIndex, type SearchOptions, type SearchPage, type SearchResult, type SearchSection, search, validateSearchIndex, } from "./search.js";
+export { createSearchIndex } from "./search-index.js";
+export type { Asset, CompileOptions, CompileResult, Diagnostic, Footer, Heading, Metadata, NavigationItem, Page, Site, SocialLink, Theme, } from "./types.js";
 /** Compile a local checkout; never fetch repositories, execute author code, or emit files. */
 export declare function compileProject(options: CompileOptions): Promise<CompileResult>;

package/dist/index.js

@@ -1,8 +1,11 @@
 import { readFile } from "node:fs/promises";
+import { parseFooter } from "./footer.js";
 import { resolveLinks } from "./links.js";
 import { parseDocument, renderDocument, } from "./markdown.js";
 import { loadProject, relativeSource } from "./project.js";
 import { navigationFor, normalizeBasePath, publicUrl, routeFor, } from "./routes.js";
+export { search, validateSearchIndex, } from "./search.js";
+export { createSearchIndex } from "./search-index.js";
 const reserved = new Set([
     "_assets",
     "_mdd",
@@ -46,6 +49,18 @@ export async function compileProject(options) {
     const project = await loadProject(options, diagnostics);
     if (!project)
         return { diagnostics };
+    let footer;
+    if (project.footer) {
+        const source = relativeSource(project.root, project.footer);
+        const text = await readFile(project.footer, "utf8");
+        try {
+            footer = parseFooter(text, source, diagnostics);
+        }
+        catch (error) {
+            diagnostics.push(nestingDiagnostic(error, source));
+            return { diagnostics };
+        }
+    }
     const sources = [];
     const routes = new Map();
     for (const file of project.files) {
@@ -123,6 +138,7 @@ export async function compileProject(options) {
             navigation: navigationFor(pages, sources.map((source) => source.relative)),
             assets,
             theme: project.theme,
+            ...(footer ? { footer } : {}),
         },
         diagnostics,
     };

package/dist/markdown.d.ts

@@ -6,6 +6,8 @@ export interface ParsedDocument {
     title: string;
     headings: Heading[];
 }
+/** Shared syntax parser; callers validate the allowed document context. */
+export declare function parseMarkdown(source: string): Root;
 export declare function parseDocument(source: string, file: string, diagnostics: Diagnostic[]): ParsedDocument;
 export declare function renderDocument(document: ParsedDocument): Promise<{
     html: string;

package/dist/markdown.js

@@ -46,6 +46,10 @@ const htmlRenderer = unified()
     .use(rehypeStringify);
 const markdownRenderer = unified().use(remarkGfm).use(remarkStringify);
 const componentNames = new Set(["note", "tip", "warning", "details"]);
+/** Shared syntax parser; callers validate the allowed document context. */
+export function parseMarkdown(source) {
+    return parser.parse(source);
+}
 /** Keep the same first-wins, reachable definitions that the HTML renderer uses. */
 function retainReferencedDefinitions(tree) {
     const definitions = new Map();
@@ -99,7 +103,7 @@ function unsafeUrl(url, image) {
         !(image ? ["http", "https"] : ["http", "https", "mailto", "tel"]).includes(scheme));
 }
 export function parseDocument(source, file, diagnostics) {
-    const tree = parser.parse(source);
+    const tree = parseMarkdown(source);
     retainReferencedDefinitions(tree);
     const metadata = {};
     const headings = [];

package/dist/project.d.ts

@@ -5,6 +5,7 @@ export interface Project {
     title?: string;
     theme: Theme;
     files: string[];
+    footer?: string;
 }
 export declare class AuthoringError extends Error {
     readonly code: string;

package/dist/project.js

@@ -139,7 +139,7 @@ async function optionalFile(root, file) {
     }
     return safeFile(root, file);
 }
-async function scan(root) {
+async function scan(root, excludedFile) {
     const files = [];
     async function walk(directory) {
         const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
@@ -156,6 +156,8 @@ async function scan(root) {
             if (entry.isSymbolicLink()) {
                 throw new AuthoringError("CONTENT_SYMLINK", `Content discovery does not follow symlinks: ${file}`);
             }
+            if (file === excludedFile)
+                continue;
             if (entry.isDirectory())
                 await walk(file);
             else if (path.extname(entry.name).toLowerCase() === ".md")
@@ -174,6 +176,12 @@ export async function loadProject(options, diagnostics) {
             throw new Error(`Cannot resolve project directory ${options.projectDir}`, { cause: error });
         });
         const mddRoot = await directory(root, relativePath(options.mddDir ?? "mdd", "mddDir"));
+        const footerPath = path.join(mddRoot, "footer.md");
+        source = relativeSource(root, footerPath);
+        const footer = await optionalFile(root, footerPath);
+        if (footer && (await lstat(footerPath)).isSymbolicLink()) {
+            throw new AuthoringError("FOOTER_SYMLINK", "The shared footer must be a regular file, not a symlink.");
+        }
         const configPath = path.join(mddRoot, "config.json");
         source = relativeSource(root, configPath);
         const configFile = await optionalFile(root, configPath);
@@ -229,14 +237,21 @@ export async function loadProject(options, diagnostics) {
             };
         }
         source = relativeSource(root, contentsRoot);
-        const files = await scan(contentsRoot);
+        const files = await scan(contentsRoot, footer ?? footerPath);
         if (!files.includes(path.join(contentsRoot, "index.md"))) {
             source = relativeSource(root, path.join(contentsRoot, "index.md"));
             throw new AuthoringError("MISSING_HOME", "The content root must contain an index.md homepage.");
         }
         if (diagnostics.some((diagnostic) => diagnostic.severity === "error"))
             return undefined;
-        return { root, contentsRoot, title, theme, files };
+        return {
+            root,
+            contentsRoot,
+            title,
+            theme,
+            files,
+            ...(footer ? { footer } : {}),
+        };
     }
     catch (error) {
         if (!(error instanceof AuthoringError))

package/dist/search-index.d.ts

@@ -0,0 +1,4 @@
+import { type SearchIndex } from "./search.js";
+import type { Site } from "./types.js";
+/** Build only from successfully compiled pages; no source paths or HTML are indexed. */
+export declare function createSearchIndex(site: Site): SearchIndex;

package/dist/search-index.js

@@ -0,0 +1,62 @@
+import { toString as nodeText } from "mdast-util-to-string";
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import { unified } from "unified";
+import { SKIP, visit } from "unist-util-visit";
+import { validateSearchIndex, } from "./search.js";
+const parser = unified().use(remarkParse).use(remarkGfm);
+const blockTypes = new Set(["paragraph", "code", "tableCell", "listItem"]);
+function indexPage(page) {
+    const sections = [{ title: "", url: page.url, text: "" }];
+    let headingIndex = 0;
+    const chunks = [[]];
+    visit(parser.parse(page.markdown), (node) => {
+        if (node.type === "definition" || node.type === "html")
+            return SKIP;
+        if (node.type === "heading") {
+            const heading = page.headings[headingIndex++];
+            if (!heading ||
+                heading.text !== nodeText(node) ||
+                heading.depth !== node.depth) {
+                throw new TypeError("Search indexing requires matching compiled Markdown and headings.");
+            }
+            sections.push({
+                title: heading.text,
+                url: `${page.url}#${encodeURIComponent(heading.id)}`,
+                text: "",
+            });
+            chunks.push([]);
+            return SKIP;
+        }
+        const text = chunks[chunks.length - 1];
+        if (!text)
+            return;
+        if (blockTypes.has(node.type) || node.type === "break")
+            text.push(" ");
+        if (node.type === "text" ||
+            node.type === "code" ||
+            node.type === "inlineCode")
+            text.push(node.value);
+        if ((node.type === "image" || node.type === "imageReference") && node.alt)
+            text.push(node.alt);
+    });
+    if (headingIndex !== page.headings.length) {
+        throw new TypeError("Search indexing requires matching compiled Markdown and headings.");
+    }
+    sections.forEach((entry, index) => {
+        entry.text = (chunks[index] ?? []).join("").replace(/\s+/gu, " ").trim();
+    });
+    return {
+        url: page.url,
+        title: page.title,
+        description: page.description ?? "",
+        sections,
+    };
+}
+/** Build only from successfully compiled pages; no source paths or HTML are indexed. */
+export function createSearchIndex(site) {
+    const index = { version: 1, pages: site.pages.map(indexPage) };
+    index.pages.sort((a, b) => (a.url < b.url ? -1 : a.url > b.url ? 1 : 0));
+    validateSearchIndex(index);
+    return index;
+}

package/dist/search.d.ts

@@ -0,0 +1,33 @@
+/** Versioned, JSON-serializable input for the browser-safe search API. */
+export interface SearchIndex {
+    version: 1;
+    pages: SearchPage[];
+}
+export interface SearchPage {
+    url: string;
+    title: string;
+    description: string;
+    sections: SearchSection[];
+}
+export interface SearchSection {
+    /** Empty for content before the first heading. */
+    title: string;
+    url: string;
+    text: string;
+}
+export interface SearchOptions {
+    /** Maximum results, from 0 to 100. Defaults to 10. */
+    limit?: number;
+}
+export interface SearchResult {
+    title: string;
+    url: string;
+    /** Present when the destination is a compiled heading. */
+    section?: string;
+    excerpt: string;
+    score: number;
+}
+/** Validate deserialized data before any result can become a link. */
+export declare function validateSearchIndex(value: unknown): asserts value is SearchIndex;
+/** Return at most one hit per page, without filesystem, network, or DOM access. */
+export declare function search(index: SearchIndex, query: string, options?: SearchOptions): SearchResult[];

package/dist/search.js

@@ -0,0 +1,153 @@
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function pageUrl(value) {
+    if (typeof value !== "string" ||
+        !value.startsWith("/") ||
+        value.startsWith("//") ||
+        !value.endsWith("/") ||
+        /[?#\\\s\p{Cc}]/u.test(value))
+        return false;
+    try {
+        const parsed = new URL(value, "https://mdd.invalid");
+        return (parsed.pathname === value &&
+            value.split("/").every((part) => {
+                const decoded = decodeURIComponent(part);
+                return (decoded !== "." && decoded !== ".." && !/[/\\\p{Cc}]/u.test(decoded));
+            }));
+    }
+    catch {
+        return false;
+    }
+}
+function sectionUrl(value, page) {
+    if (value === page)
+        return true;
+    if (typeof value !== "string" || !value.startsWith(`${page}#`))
+        return false;
+    try {
+        const fragment = value.slice(page.length + 1);
+        const id = decodeURIComponent(fragment);
+        return (id.startsWith("mdd-") &&
+            !/\p{Cc}/u.test(id) &&
+            fragment === encodeURIComponent(id));
+    }
+    catch {
+        return false;
+    }
+}
+/** Validate deserialized data before any result can become a link. */
+export function validateSearchIndex(value) {
+    if (!record(value) || value.version !== 1 || !Array.isArray(value.pages)) {
+        throw new TypeError("Invalid search index: expected version 1 and pages.");
+    }
+    const urls = new Set();
+    for (const page of value.pages) {
+        if (!record(page) ||
+            !pageUrl(page.url) ||
+            urls.has(page.url) ||
+            typeof page.title !== "string" ||
+            typeof page.description !== "string" ||
+            !Array.isArray(page.sections))
+            throw new TypeError("Invalid search index page.");
+        urls.add(page.url);
+        const sections = new Set();
+        for (const section of page.sections) {
+            if (!record(section) ||
+                !sectionUrl(section.url, page.url) ||
+                sections.has(section.url) ||
+                typeof section.title !== "string" ||
+                typeof section.text !== "string")
+                throw new TypeError("Invalid search index section.");
+            sections.add(section.url);
+        }
+    }
+}
+function normalize(value) {
+    return value
+        .normalize("NFKC")
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\p{M}_]+/gu, " ")
+        .trim();
+}
+function excerpt(value) {
+    const characters = Array.from(value.replace(/\s+/gu, " ").trim());
+    return characters.length > 160
+        ? `${characters.slice(0, 159).join("")}…`
+        : characters.join("");
+}
+/** Return at most one hit per page, without filesystem, network, or DOM access. */
+export function search(index, query, options = {}) {
+    validateSearchIndex(index);
+    const limit = options.limit ?? 10;
+    if (!Number.isInteger(limit) || limit < 0 || limit > 100) {
+        throw new RangeError("Search limit must be an integer from 0 to 100.");
+    }
+    if (typeof query !== "string")
+        throw new TypeError("Search query must be a string.");
+    if (query.length > 512)
+        throw new RangeError("Search query must not exceed 512 characters.");
+    const terms = [...new Set(normalize(query).split(" ").filter(Boolean))];
+    const phrase = terms.join(" ");
+    if (terms.length > 32)
+        throw new RangeError("Search query must not exceed 32 unique terms.");
+    if (!terms.length || !limit)
+        return [];
+    const results = [];
+    for (const page of index.pages) {
+        const title = normalize(page.title);
+        const description = normalize(page.description);
+        const sections = page.sections.map((section) => ({
+            section,
+            title: normalize(section.title),
+            text: normalize(section.text),
+        }));
+        const weights = terms.map((term) => {
+            if (title.includes(term))
+                return 8;
+            if (sections.some((section) => section.title.includes(term)))
+                return 4;
+            if (description.includes(term))
+                return 2;
+            return sections.some((section) => section.text.includes(term)) ? 1 : 0;
+        });
+        if (weights.some((weight) => weight === 0))
+            continue;
+        const metadataMatch = terms.every((term) => title.includes(term) || description.includes(term));
+        const matches = sections
+            .map((entry) => ({
+            ...entry,
+            score: terms.reduce((score, term) => score +
+                (entry.title.includes(term)
+                    ? 4
+                    : entry.text.includes(term)
+                        ? 1
+                        : 0), 0),
+        }))
+            .filter((entry) => terms.every((term) => title.includes(term) ||
+            description.includes(term) ||
+            entry.title.includes(term) ||
+            entry.text.includes(term)));
+        // A stable sort preserves document order when multiple sections tie.
+        matches.sort((a, b) => b.score - a.score);
+        const best = matches[0]?.section;
+        const destination = metadataMatch ? undefined : best;
+        results.push({
+            title: page.title,
+            url: destination?.url ?? page.url,
+            ...(destination?.title ? { section: destination.title } : {}),
+            excerpt: excerpt(best?.text ||
+                page.description ||
+                page.sections.find((section) => section.text)?.text ||
+                page.title),
+            score: weights.reduce((sum, weight) => sum + weight, 0) +
+                (title === phrase
+                    ? 24
+                    : sections.some((section) => section.title === phrase)
+                        ? 12
+                        : 0),
+        });
+    }
+    results.sort((a, b) => b.score - a.score || (a.url < b.url ? -1 : a.url > b.url ? 1 : 0));
+    return results.slice(0, limit);
+}

package/dist/types.d.ts

@@ -54,6 +54,15 @@ export type Theme = {
     css: string;
     js?: string;
 };
+export interface SocialLink {
+    label: string;
+    url: string;
+}
+export interface Footer {
+    /** POSIX path relative to projectDir; not a documentation page. */
+    source: string;
+    socials: SocialLink[];
+}
 export interface Site {
     title: string;
     basePath: string;
@@ -61,6 +70,7 @@ export interface Site {
     navigation: NavigationItem[];
     assets: Asset[];
     theme: Theme;
+    footer?: Footer;
 }
 export interface CompileOptions {
     projectDir: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wgtechlabs/mdd-engine",
-  "version": "0.1.0-dev.8a1ef77",
+  "version": "0.1.0-pr.b4e4512",
   "description": "Headless Markdown documentation compiler for mdd",
   "type": "module",
   "license": "MIT",
@@ -18,6 +18,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./search": {
+      "types": "./dist/search.d.ts",
+      "import": "./dist/search.js"
     }
   },
   "types": "./dist/index.d.ts",