@amamo/mdx 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jikkai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# @amamo/mdx
+
+An independent MDX content compiler with a Rust core, official Shiki highlighting, JSON Schema validation, media imports, deterministic manifests, and content-addressed caching. The same compiler state powers the root API, Vite 8, and Next 16.
+
+## Install
+
+```sh
+pnpm add @amamo/mdx
+```
+
+Node.js 20.19 or newer is required. A supported native package is installed through `optionalDependencies`; there is no JavaScript or WASI fallback.
+
+## Configure
+
+Configuration is plain serializable data. Functions and executable plugins are intentionally rejected.
+
+```ts
+// amamo.config.ts
+import { defineConfig } from '@amamo/mdx'
+
+export default defineConfig({
+  root: import.meta.dirname,
+  collections: {
+    posts: {
+      directory: 'content/posts',
+      schema: {
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        type: 'object',
+        properties: {
+          title: { type: 'string' },
+          password: { type: 'string' },
+        },
+        required: ['title'],
+      },
+      sensitive: ['password'],
+    },
+  },
+  highlight: {
+    provider: 'shiki',
+    engine: 'oniguruma',
+    themes: { light: 'vitesse-light', dark: 'vitesse-dark' },
+    unknownLanguage: 'plain',
+  },
+  media: { missing: 'warn' },
+  manifests: {
+    public: {
+      output: '.amamo-mdx/public.json',
+      fields: { key: 'key', title: 'title' },
+    },
+    server: {
+      output: '.amamo-mdx/server.json',
+      key: 'key',
+      fields: {
+        key: 'key',
+        protected: { from: 'password', transform: 'exists' },
+        passwordHash: { from: 'password', transform: 'sha256' },
+      },
+    },
+  },
+})
+```
+
+The default highlighter keeps official Shiki in JavaScript and uses its Oniguruma WASM engine. Set `engine: 'javascript'` when avoiding Oniguruma is more important than grammar compatibility. Relative Markdown media URLs become static imports; authored JSX is left untouched. `unknownLanguage` and `media.missing` accept `error` or their permissive `plain`/`warn` policies.
+
+## Compiler API
+
+```ts
+import { createCompiler } from '@amamo/mdx'
+import config from './amamo.config.js'
+
+const compiler = await createCompiler(config)
+await compiler.build()
+await compiler.transform('content/posts/hello.mdx')
+await compiler.remove('content/posts/deleted.mdx')
+await compiler.dispose()
+```
+
+`build()` produces `.amamo-mdx/collections.mjs`, its declaration file, the private loader index, and configured manifests. Unchanged bytes are not rewritten.
+
+## Vite 8
+
+```ts
+import { defineConfig } from 'vite'
+import { amamoMdx } from '@amamo/mdx/vite'
+import amamo from './amamo.config.js'
+
+export default defineConfig({ plugins: [amamoMdx(amamo)] })
+```
+
+The adapter joins Vite environments onto one startup build and uses Vite's existing watcher for add, change, and delete events.
+
+## Next 16
+
+```js
+// next.config.mjs
+import { withAmamoMdx } from '@amamo/mdx/next'
+import amamo from './amamo.config.js'
+
+export default withAmamoMdx(amamo)({ reactStrictMode: true })
+```
+
+The same private read-only loader is registered for default Turbopack and opt-in Webpack. The config wrapper also accepts and awaits an existing Next config function.
+
+## Security
+
+MDX can contain executable JavaScript. Compile only content from trusted authors. Schema validation is not a sandbox. Fields marked `sensitive` are removed before modules, cache records, and public frontmatter are serialized; manifests may only inspect them with `exists` or hash them with `sha256`.
+
+Relative media imports are confined to the configured root, including symlink resolution. Cache and generated output writes use same-directory temporary files and atomic rename.
+
+## Native targets
+
+- macOS arm64 and x64
+- Linux arm64 and x64, glibc and musl
+- Windows x64 MSVC
+
+Unsupported targets fail during native binding load. No WASI or JavaScript fallback is shipped.
+
+## License
+
+MIT

package/dist/compiler.d.ts

@@ -0,0 +1,28 @@
+import type { IAmamoMdxConfig } from './config.js';
+import type { IDocumentRecord } from './native.js';
+export interface IBuildResult {
+    cached: number;
+    compiled: number;
+    discovered: number;
+    outputsWritten: number;
+}
+export interface ITransformResult {
+    cached: boolean;
+    code: string;
+    map: null;
+    outputsWritten: number;
+    record: IDocumentRecord;
+}
+export interface ICompiler {
+    build(): Promise<IBuildResult>;
+    dispose(): Promise<void>;
+    remove(file: string): Promise<number>;
+    transform(file: string): Promise<ITransformResult>;
+}
+export interface IAdapterCompiler extends ICompiler {
+    readonly generatedCollectionModule: string;
+    isContentFile(file: string): boolean;
+    startWatch(onGeneratedChange?: (paths: string[]) => Promise<void> | void): () => void;
+}
+export declare function createCompiler(config: IAmamoMdxConfig): Promise<ICompiler>;
+export declare function createAdapterCompiler(config: IAmamoMdxConfig): Promise<IAdapterCompiler>;

package/dist/compiler.js

@@ -0,0 +1,446 @@
+import { execFile } from 'node:child_process';
+import { realpathSync, watch } from 'node:fs';
+import { mkdir, open, readFile, readdir, rename, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { normalizeConfig } from './config.js';
+import { configurationFingerprint, prepareNativeBatch, pruneNativeCache, renderNativeManifests, } from './native.js';
+import { createShikiRenderer } from './shiki.js';
+let temporaryFileId = 0;
+const execFileAsync = promisify(execFile);
+class Compiler {
+    config;
+    shiki;
+    generatedCollectionModule;
+    buildInFlight;
+    disposed = false;
+    generatedListener;
+    gitModifiedTimes = new Map();
+    records = new Map();
+    tail = Promise.resolve();
+    watcher;
+    watcherError;
+    constructor(config, shiki) {
+        this.config = config;
+        this.shiki = shiki;
+        this.generatedCollectionModule = path.join(config.generatedDirectory, 'collections.mjs');
+    }
+    build() {
+        if (this.buildInFlight)
+            return this.buildInFlight;
+        const operation = this.enqueue(() => this.buildNow());
+        const tracked = operation.then((result) => {
+            this.buildInFlight = undefined;
+            return result;
+        }, (error) => {
+            this.buildInFlight = undefined;
+            throw error;
+        });
+        this.buildInFlight = tracked;
+        return tracked;
+    }
+    transform(file) {
+        return this.enqueue(() => this.transformNow(cleanFileId(file)));
+    }
+    remove(file) {
+        return this.enqueue(async () => {
+            const absolute = cleanFileId(file);
+            if (!this.records.delete(absolute))
+                return 0;
+            const changed = await this.writeOutputs();
+            if (this.config.cache.enabled) {
+                pruneNativeCache(this.config.cache.directory, [...this.records.values()].map((record) => record.cacheKey));
+            }
+            await this.notifyGeneratedChange(changed);
+            return changed.length;
+        });
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        await this.enqueue(async () => {
+            this.watcher?.close();
+            this.watcher = undefined;
+            this.shiki?.dispose();
+            this.disposed = true;
+        }, false);
+    }
+    isContentFile(file) {
+        return this.metadataForFile(cleanFileId(file)) !== undefined;
+    }
+    startWatch(onGeneratedChange) {
+        if (this.watcher)
+            return () => this.stopWatch();
+        this.generatedListener = onGeneratedChange;
+        this.watcher = watch(this.config.root, { recursive: true }, async (_event, filename) => {
+            if (!filename)
+                return;
+            const file = path.resolve(this.config.root, filename.toString());
+            if (!this.isContentFile(file) && !this.records.has(file))
+                return;
+            try {
+                await stat(file);
+                await this.transform(file);
+            }
+            catch (error) {
+                if (isMissingFile(error)) {
+                    await this.remove(file);
+                }
+                else {
+                    this.watcherError = asError(error);
+                }
+            }
+        });
+        this.watcher.on('error', (error) => {
+            this.watcherError = error;
+        });
+        return () => this.stopWatch();
+    }
+    stopWatch() {
+        this.watcher?.close();
+        this.watcher = undefined;
+        this.generatedListener = undefined;
+    }
+    enqueue(operation, requireOpen = true) {
+        const run = async () => {
+            if (requireOpen)
+                this.assertOpen();
+            return operation();
+        };
+        const result = this.tail.then(run, run);
+        this.tail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    assertOpen() {
+        if (this.disposed)
+            throw new Error('AMAMO_COMPILER_DISPOSED: Compiler is disposed');
+        if (this.watcherError) {
+            const error = this.watcherError;
+            this.watcherError = undefined;
+            throw error;
+        }
+    }
+    async buildNow() {
+        const discovered = await this.discover();
+        const records = await this.compile(discovered.map((document) => document.input));
+        this.records.clear();
+        for (const record of records)
+            this.records.set(path.resolve(record.file), record);
+        const changed = await this.writeOutputs();
+        if (this.config.cache.enabled) {
+            pruneNativeCache(this.config.cache.directory, records.map((record) => record.cacheKey));
+        }
+        await this.notifyGeneratedChange(changed);
+        return {
+            cached: records.filter((record) => record.cached).length,
+            compiled: records.filter((record) => !record.cached).length,
+            discovered: discovered.length,
+            outputsWritten: changed.length,
+        };
+    }
+    async transformNow(file) {
+        const metadata = this.metadataForFile(file);
+        if (!metadata) {
+            throw new Error(`AMAMO_FILE_OUTSIDE_COLLECTION: ${file}`);
+        }
+        for (const record of this.records.values()) {
+            if (record.file !== file &&
+                record.collection === metadata.collection &&
+                record.key === metadata.key) {
+                throw new Error(`AMAMO_DOCUMENT_DUPLICATE_KEY: ${metadata.collection}/${metadata.key}`);
+            }
+        }
+        const document = await this.readDocument(metadata);
+        const records = await this.compile([document.input]);
+        const record = records[0];
+        if (!record)
+            throw new Error(`AMAMO_NATIVE_RESULT_MISSING: ${file}`);
+        this.records.set(file, record);
+        const changed = await this.writeOutputs();
+        if (this.config.cache.enabled) {
+            pruneNativeCache(this.config.cache.directory, [...this.records.values()].map((value) => value.cacheKey));
+        }
+        await this.notifyGeneratedChange(changed);
+        return {
+            cached: record.cached,
+            code: record.module,
+            map: null,
+            outputsWritten: changed.length,
+            record,
+        };
+    }
+    async compile(inputs) {
+        const batch = prepareNativeBatch(this.config, inputs);
+        const highlights = this.shiki ? await this.shiki.highlight(batch.codeBlocks) : [];
+        return batch.finish(highlights);
+    }
+    async discover() {
+        const documentsMetadata = [];
+        const keys = new Map();
+        for (const [collection, config] of Object.entries(this.config.collections).toSorted(([left], [right]) => left.localeCompare(right))) {
+            for (const file of await walkFiles(config.directory)) {
+                const metadata = this.metadataForFile(file, collection);
+                if (!metadata)
+                    continue;
+                const duplicateKey = `${metadata.collection}\0${metadata.key}`;
+                const duplicate = keys.get(duplicateKey);
+                if (duplicate) {
+                    throw new Error(`AMAMO_DOCUMENT_DUPLICATE_KEY: ${metadata.collection}/${metadata.key} is shared by ${duplicate} and ${file}`);
+                }
+                keys.set(duplicateKey, file);
+                documentsMetadata.push(metadata);
+            }
+        }
+        this.gitModifiedTimes.clear();
+        if (this.config.derived.lastModified) {
+            const times = await gitLastModified(this.config.root, documentsMetadata.map(({ file }) => file), Object.values(this.config.collections).map(({ directory }) => directory));
+            for (const [file, modifiedAt] of times)
+                this.gitModifiedTimes.set(file, modifiedAt);
+        }
+        const documents = await Promise.all(documentsMetadata.map((value) => this.readDocument(value)));
+        return documents.toSorted((left, right) => left.input.file.localeCompare(right.input.file));
+    }
+    async readDocument(metadata) {
+        const [source, stats] = await Promise.all([
+            readFile(metadata.file, 'utf8'),
+            stat(metadata.file),
+        ]);
+        return {
+            input: {
+                collection: metadata.collection,
+                file: metadata.file,
+                key: metadata.key,
+                locale: metadata.locale,
+                modifiedAt: this.config.derived.lastModified
+                    ? (this.gitModifiedTimes.get(metadata.file) ?? stats.mtime.toISOString())
+                    : undefined,
+                slug: metadata.slug,
+                source,
+            },
+        };
+    }
+    metadataForFile(file, expectedCollection) {
+        const absolute = path.resolve(file);
+        for (const [collection, config] of Object.entries(this.config.collections)) {
+            if (expectedCollection && collection !== expectedCollection)
+                continue;
+            const relative = path.relative(config.directory, absolute);
+            if (relative.startsWith('..') || path.isAbsolute(relative))
+                continue;
+            const extension = config.extensions.find((value) => relative.endsWith(value));
+            if (!extension)
+                continue;
+            return deriveMetadata(collection, config, absolute, relative.slice(0, -extension.length));
+        }
+        return undefined;
+    }
+    async writeOutputs() {
+        const records = [...this.records.values()].toSorted(compareRecords);
+        const outputs = renderNativeManifests(this.config, records);
+        outputs.push({
+            contents: generateCollectionModule(this.config, records),
+            path: this.generatedCollectionModule,
+        }, {
+            contents: generateCollectionTypes(),
+            path: path.join(this.config.generatedDirectory, 'collections.d.ts'),
+        }, {
+            contents: `${JSON.stringify({
+                cacheDirectory: this.config.cache.directory,
+                configFingerprint: configurationFingerprint(this.config),
+                documents: Object.fromEntries(records.map((record) => [record.file, { cacheKey: record.cacheKey }])),
+                version: 1,
+            }, null, 2)}\n`,
+            path: path.join(this.config.generatedDirectory, 'index.json'),
+        });
+        const changed = [];
+        for (const output of outputs.toSorted((left, right) => left.path.localeCompare(right.path))) {
+            if (await writeIfChanged(output.path, output.contents))
+                changed.push(output.path);
+        }
+        return changed;
+    }
+    async notifyGeneratedChange(paths) {
+        if (paths.length === 0 || !this.generatedListener)
+            return;
+        await this.generatedListener(paths);
+    }
+}
+export async function createCompiler(config) {
+    return createAdapterCompiler(config);
+}
+export async function createAdapterCompiler(config) {
+    const normalized = normalizeConfig(config);
+    const shiki = normalized.highlight.enabled
+        ? await createShikiRenderer(normalized.highlight)
+        : undefined;
+    return new Compiler(normalized, shiki);
+}
+function deriveMetadata(collection, config, file, extensionless) {
+    const segments = extensionless.split(path.sep);
+    let name = segments.pop() ?? '';
+    let locale;
+    if (config.locales) {
+        locale = config.locales.default;
+        for (const candidate of config.locales.names.toSorted((left, right) => right.length - left.length)) {
+            const suffix = `.${candidate}`;
+            if (name.endsWith(suffix)) {
+                name = name.slice(0, -suffix.length);
+                locale = candidate;
+                break;
+            }
+        }
+    }
+    if (!config.slug.indexNames.includes(name))
+        segments.push(name);
+    const slug = segments.filter(Boolean).join('/') || '/';
+    return {
+        collection,
+        file,
+        key: locale ? `${locale}:${slug}` : slug,
+        locale,
+        slug,
+    };
+}
+async function walkFiles(directory) {
+    const files = [];
+    const entries = await readdir(directory, { withFileTypes: true });
+    for (const entry of entries.toSorted((left, right) => left.name.localeCompare(right.name))) {
+        const file = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            files.push(...(await walkFiles(file)));
+        else if (entry.isFile())
+            files.push(file);
+    }
+    return files;
+}
+function generateCollectionModule(config, records) {
+    const collections = Object.keys(config.collections).toSorted();
+    const lines = ['export const collections = {'];
+    for (const collection of collections) {
+        lines.push(`  ${JSON.stringify(collection)}: [`);
+        for (const record of records.filter((value) => value.collection === collection)) {
+            const specifier = importSpecifier(config.generatedDirectory, record.file);
+            const metadata = JSON.stringify({
+                derived: record.derived,
+                frontmatter: record.frontmatter,
+                key: record.key,
+                locale: record.locale,
+                slug: record.slug,
+            });
+            lines.push(`    { ...${metadata}, load: () => import(${JSON.stringify(specifier)}) },`);
+        }
+        lines.push('  ],');
+    }
+    lines.push('};', 'export default collections;', '');
+    return lines.join('\n');
+}
+function generateCollectionTypes() {
+    return `export interface IGeneratedDocument {
+  readonly derived: Readonly<Record<string, unknown>>
+  readonly frontmatter: Readonly<Record<string, unknown>>
+  readonly key: string
+  readonly locale?: string
+  readonly slug?: string
+  readonly load: () => Promise<{ default: unknown }>
+}
+
+export declare const collections: Readonly<Record<string, readonly IGeneratedDocument[]>>
+export default collections
+`;
+}
+function importSpecifier(from, file) {
+    const relative = path.relative(from, file).split(path.sep).join('/');
+    return relative.startsWith('.') ? relative : `./${relative}`;
+}
+async function writeIfChanged(file, contents) {
+    try {
+        if ((await readFile(file, 'utf8')) === contents)
+            return false;
+    }
+    catch (error) {
+        if (!isMissingFile(error))
+            throw error;
+    }
+    await mkdir(path.dirname(file), { recursive: true });
+    const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${temporaryFileId++}.tmp`);
+    let handle;
+    try {
+        handle = await open(temporary, 'wx');
+        await handle.writeFile(contents);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await rename(temporary, file);
+    }
+    catch (error) {
+        await handle?.close();
+        await rm(temporary, { force: true });
+        throw error;
+    }
+    return true;
+}
+function compareRecords(left, right) {
+    return left.collection.localeCompare(right.collection) || left.key.localeCompare(right.key);
+}
+function cleanFileId(file) {
+    const absolute = path.resolve(file.split('?')[0] ?? file);
+    const missing = [];
+    let existing = absolute;
+    while (true) {
+        try {
+            return path.join(realpathSync.native(existing), ...missing);
+        }
+        catch (error) {
+            if (!isMissingFile(error))
+                return absolute;
+            const parent = path.dirname(existing);
+            if (parent === existing)
+                return absolute;
+            missing.unshift(path.basename(existing));
+            existing = parent;
+        }
+    }
+}
+async function gitLastModified(root, files, pathspecs) {
+    const wanted = new Set(files.map(cleanFileId));
+    const relativePathspecs = pathspecs
+        .map((value) => path.relative(root, value))
+        .filter((value) => !value.startsWith('..') && !path.isAbsolute(value));
+    if (wanted.size === 0 || relativePathspecs.length === 0)
+        return new Map();
+    try {
+        const { stdout } = await execFileAsync('git', [
+            '-c',
+            'core.quotepath=false',
+            'log',
+            '--format=AMAMO_COMMIT:%cI',
+            '--name-only',
+            '--relative',
+            '--',
+            ...relativePathspecs,
+        ], { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+        const modified = new Map();
+        let commitTime;
+        for (const rawLine of stdout.split('\n')) {
+            const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine;
+            if (line.startsWith('AMAMO_COMMIT:')) {
+                commitTime = line.slice('AMAMO_COMMIT:'.length);
+            }
+            else if (line && commitTime) {
+                const file = cleanFileId(path.resolve(root, line));
+                if (wanted.has(file) && !modified.has(file))
+                    modified.set(file, commitTime);
+            }
+        }
+        return modified;
+    }
+    catch {
+        return new Map();
+    }
+}
+function isMissingFile(error) {
+    return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}