@jk2908/mdsrc 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jerome Kenway
+
+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,47 @@
+# @jk2908/mdsrc
+
+A Vite plugin for managing markdown content with type safety.
+
+## Install
+
+```sh
+npm install @jk2908/mdsrc vite
+```
+
+## Usage
+
+```ts
+import plugin from '@jk2908/mdsrc'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+	plugins: [
+		plugin([
+			{
+				dir: 'content',
+				name: 'post',
+				schema: {
+					title: { type: 'string' },
+				},
+			},
+		]),
+	],
+})
+```
+
+The plugin reads markdown content, validates frontmatter against your schema, and generates typed modules during build and watch. Collection config currently uses `name`, `dir`, and `schema`.
+
+If you configure a collection with `name: 'post'`, the generated module exports `allPosts` from the package root.
+
+```ts
+import { allPosts } from '@jk2908/mdsrc'
+
+export const summaries = allPosts.map(post => ({
+	title: post.title,
+	slug: post.__mdsrc.slug,
+}))
+```
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,3 @@
+export declare const NAME = "mdsrc";
+export declare const PKG_NAME = "@jk2908/mdsrc";
+export declare const GENERATED_DIR = ".mdsrc";

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import type { Plugin } from 'vite';
+import type { BuildContext, Collection } from './types.js';
+/**
+ * Read every markdown file in a collection and turn it into the raw entry shape
+ * add mdsrc metadata like slug and filename alongside the trimmed body
+ * return an empty list if the directory read fails
+ */
+export declare function create(dir: string, buildContext: BuildContext): Promise<{
+    __mdsrc: {
+        slug: string;
+        filename: string;
+    };
+    body: string;
+}[]>;
+/**
+ * Build the vite plugin that validates collections and writes the generated modules
+ * keep the runtime data and declaration files in the same pass
+ * resolve package imports from the generated directory
+ */
+export default function plugin(src: Collection[]): Plugin;

package/dist/index.js

@@ -0,0 +1,423 @@
+// src/index.ts
+import { realpathSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+// src/config.ts
+var NAME = "mdsrc";
+var PKG_NAME = `@jk2908/${NAME}`;
+var GENERATED_DIR = `.${NAME}`;
+
+// src/logger.ts
+var LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  fatal: 4
+};
+
+class Logger {
+  static #defaultLevel = "info";
+  #level;
+  constructor(level) {
+    this.#level = level;
+  }
+  static set defaultLevel(level) {
+    Logger.#defaultLevel = level;
+  }
+  static get defaultLevel() {
+    return Logger.#defaultLevel;
+  }
+  static toError(err) {
+    return err instanceof Error ? err : new Error(String(err), { cause: err });
+  }
+  static print(err) {
+    if (err instanceof Error) {
+      return err.message + (err.stack ? `
+${err.stack}` : "");
+    }
+    if (typeof err === "object" && err !== null) {
+      try {
+        return JSON.stringify(err, null, 2);
+      } catch {
+        return String(err);
+      }
+    }
+    return String(err);
+  }
+  set level(level) {
+    this.#level = level;
+  }
+  get level() {
+    return this.#level ?? Logger.#defaultLevel;
+  }
+  log(level, message, error) {
+    if (LEVELS[level] < LEVELS[this.level])
+      return;
+    const entry = {
+      ts: Date.now(),
+      level,
+      message
+    };
+    if (level === "error" || level === "fatal") {
+      entry.error = error ? Logger.toError(error) : new Error(message);
+    }
+    const line = `[${NAME}] [${entry.ts}] [${level.toUpperCase()}] ${message}`;
+    const extra = entry.error ? `
+${Logger.print(entry.error)}` : "";
+    if (level === "warn") {
+      console.warn(line, extra);
+      return;
+    }
+    if (level === "error" || level === "fatal") {
+      console.error(line, extra);
+      return;
+    }
+    console.log(line, extra);
+  }
+  debug(...messages) {
+    this.log("debug", messages.join(" "));
+  }
+  info(...messages) {
+    this.log("info", messages.join(" "));
+  }
+  warn(...messages) {
+    this.log("warn", messages.join(" "));
+  }
+  error(message, error) {
+    this.log("error", message, error === undefined ? undefined : Logger.toError(error));
+  }
+  fatal(message, error) {
+    this.log("fatal", message, error === undefined ? undefined : Logger.toError(error));
+  }
+}
+var logger = new Logger("debug");
+
+// src/utils.ts
+function capitalise(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+function pluralise(str, count) {
+  return count === 1 ? str : str.endsWith("s") ? str : `${str}s`;
+}
+function debounce(fn, wait) {
+  let timeoutId = null;
+  return (...args) => {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+    timeoutId = setTimeout(() => {
+      fn.apply(null, args);
+    }, wait);
+  };
+}
+
+// src/index.ts
+var fileCache = new Map;
+function parse(content) {
+  const regex = /^---\r?\n([\s\S]*?)\r?\n---([\s\S]*)$/;
+  const match = content.match(regex);
+  const metadata = {};
+  if (!match)
+    throw new Error("invalid frontmatter");
+  const [, frontmatter, body] = match;
+  if (frontmatter) {
+    for (const line of frontmatter.split(`
+`)) {
+      const [key, value] = line.split(": ").map((str) => str.trim());
+      metadata[key] = value;
+    }
+  }
+  return { metadata, body };
+}
+async function create(dir, buildContext) {
+  const { logger: logger2 } = buildContext;
+  try {
+    const files = (await fs.readdir(dir)).filter((file) => path.extname(file) === ".md");
+    const filePaths = files.map((file) => path.join(dir, file));
+    if (!files.length) {
+      console.warn(`mdsrc: ${dir} is empty`);
+      return [];
+    }
+    return Promise.all(filePaths.map(async (filePath) => {
+      const file = path.basename(filePath);
+      const { metadata, body } = parse(await fs.readFile(filePath, "utf-8"));
+      return {
+        ...metadata,
+        __mdsrc: {
+          slug: path.basename(file, ".md").toLowerCase().replace(/\s+/g, "-"),
+          filename: file
+        },
+        body: body.trim()
+      };
+    }));
+  } catch (err) {
+    logger2.error("[create]: failed to create entries", err);
+    return [];
+  }
+}
+async function maybeWrite(filePath, content) {
+  const cached = fileCache.get(filePath);
+  if (cached === content) {
+    try {
+      await fs.access(filePath);
+      return false;
+    } catch (err) {
+      if (!(err instanceof Error) || !("code" in err) || err.code !== "ENOENT") {
+        throw err;
+      }
+    }
+  }
+  if (cached === undefined) {
+    try {
+      const current = await fs.readFile(filePath, "utf-8");
+      fileCache.set(filePath, current);
+      if (current === content) {
+        fileCache.set(filePath, content);
+        return false;
+      }
+    } catch (err) {
+      if (!(err instanceof Error) || !("code" in err) || err.code !== "ENOENT") {
+        throw err;
+      }
+    }
+  }
+  await fs.writeFile(filePath, content);
+  fileCache.set(filePath, content);
+  return true;
+}
+function validate(input, schema) {
+  const validated = {};
+  const issues = [];
+  if (typeof input !== "object" || input === null) {
+    issues.push({ message: "Input must be an object" });
+    return { issues };
+  }
+  for (const key in schema) {
+    const entry = schema[key];
+    if (!(key in input)) {
+      if (!entry.optional) {
+        issues.push({ message: `Missing required key: ${key}` });
+      }
+      continue;
+    }
+    const value = input[key];
+    switch (entry.type) {
+      case "string": {
+        if (typeof value !== "string") {
+          issues.push({ message: `Key ${key} must be a string` });
+        } else {
+          if (entry.minLength && value.length < entry.minLength) {
+            issues.push({
+              message: `Key ${key} must be at least ${entry.minLength} characters`
+            });
+          }
+          if (entry.maxLength && value.length > entry.maxLength) {
+            issues.push({
+              message: `Key ${key} must be at most ${entry.maxLength} characters`
+            });
+          }
+          validated[key] = value;
+        }
+        break;
+      }
+      case "number": {
+        let num = value;
+        if (typeof value === "string" && !Number.isNaN(Number(value))) {
+          num = Number(value);
+        }
+        if (typeof num !== "number") {
+          issues.push({ message: `Key ${key} must be a number` });
+        } else {
+          validated[key] = num;
+        }
+        break;
+      }
+      case "boolean": {
+        let bool = value;
+        if (typeof value === "string") {
+          if (value.toLowerCase() === "true") {
+            bool = true;
+          } else if (value.toLowerCase() === "false") {
+            bool = false;
+          }
+        }
+        if (typeof bool !== "boolean") {
+          issues.push({ message: `Key ${key} must be a boolean` });
+        } else {
+          validated[key] = bool;
+        }
+        break;
+      }
+      case "date": {
+        if (typeof value !== "string") {
+          issues.push({ message: `Key ${key} must be a date` });
+        } else {
+          const date = new Date(value);
+          if (Number.isNaN(date.getTime())) {
+            issues.push({ message: `Key ${key} must be a valid date` });
+          } else {
+            validated[key] = date.toISOString();
+          }
+        }
+        break;
+      }
+    }
+  }
+  return issues.length ? { issues } : { value: validated };
+}
+async function build(src, buildContext) {
+  const { logger: logger2, outDir } = buildContext;
+  let names = [];
+  const collections = {};
+  try {
+    if (!outDir)
+      throw new Error("Output directory is not defined");
+    await fs.mkdir(outDir, { recursive: true });
+    for (const collection of src) {
+      const raw = await create(path.join(process.cwd(), collection.dir), buildContext);
+      const validated = await Promise.all(raw.map(async (item) => {
+        try {
+          const { body, __mdsrc, ...metadata } = item;
+          const res = validate(metadata, collection.schema);
+          if (res.issues)
+            throw new Error(JSON.stringify(res.issues, null, 2));
+          return {
+            body,
+            ...res.value,
+            __mdsrc
+          };
+        } catch (err) {
+          logger2.error(`[buildStart]: failed to validate item in ${collection.name}`, err);
+          return null;
+        }
+      }));
+      collections[collection.name] = {
+        items: validated.filter((e) => e !== null),
+        schema: collection.schema
+      };
+    }
+    names = Object.keys(collections);
+    const promises = [];
+    promises.push(maybeWrite(path.join(outDir, "types.ts"), `
+					${names.map((name) => `
+								export type ${capitalise(name)} = {
+									body?: string
+									${Object.entries(collections[name].schema).map(([key, entry]) => `${key}${entry.optional ? "?" : ""}: ${entry.type === "date" ? "string" : entry.type}`).join(`
+  `)}
+									__mdsrc: {
+										slug: string
+										filename: string
+									},
+								}
+							`).join(`
+
+`)}`.trim()));
+    promises.push(maybeWrite(path.join(outDir, "index.d.ts"), `	
+					import type { ${names.map((name) => capitalise(name)).join(", ")} } from './types.js'
+
+					declare module '${PKG_NAME}' {
+						${names.map((name) => `
+									export const all${capitalise(pluralise(name, 2))}: ${capitalise(name)}[]
+								`).join(`
+
+`)}
+					}
+				`.trim()));
+    for (const name of names) {
+      const collection = collections[name]?.items;
+      promises.push(maybeWrite(path.join(outDir, `${name}.js`), `export const all${capitalise(pluralise(name, 2))} = ${collection?.length ? JSON.stringify(collection) : "[]"}`.trim()));
+    }
+    promises.push(maybeWrite(path.join(outDir, "index.js"), names.map((name) => `export * from './${name}.js'`).join(`
+`)));
+    const writes = await Promise.all(promises);
+    buildContext.names = names;
+    return writes.some((changed) => changed);
+  } catch (err) {
+    logger2.error("[build]: failed to generate data", err);
+    throw err;
+  }
+}
+var normaliseWatchPath = (p) => p.replace(/\\/g, "/");
+function plugin(src) {
+  const logger2 = new Logger("debug");
+  const outDir = path.join(process.cwd(), GENERATED_DIR);
+  const watchRoot = normaliseWatchPath(realpathSync.native(process.cwd()));
+  const watchedRoots = src.map((c) => `${normaliseWatchPath(path.join(watchRoot, c.dir))}/`);
+  const resolveWatchFile = (filePath) => {
+    const absolutePath = path.resolve(watchRoot, filePath);
+    const parentPath = path.dirname(absolutePath);
+    try {
+      const resolvedParentPath = normaliseWatchPath(realpathSync.native(parentPath));
+      return normaliseWatchPath(path.join(resolvedParentPath, path.basename(absolutePath)));
+    } catch {
+      return normaliseWatchPath(absolutePath);
+    }
+  };
+  const isWatchedFile = (filePath) => watchedRoots.some((root) => resolveWatchFile(filePath).startsWith(root));
+  const buildContext = {
+    logger: logger2,
+    outDir,
+    names: []
+  };
+  let rebuildRunning = false;
+  let rebuildQueued = false;
+  let rebuildReason = "change";
+  const rebuild = debounce((event, filePath) => {
+    const queue = () => {
+      (async () => {
+        if (rebuildRunning) {
+          rebuildQueued = true;
+          return;
+        }
+        rebuildRunning = true;
+        do {
+          rebuildQueued = false;
+          try {
+            const changed = await build(src, buildContext);
+            if (changed)
+              logger2.info(`[watch]: route graph rebuilt (${rebuildReason})`);
+          } catch (err) {
+            logger2.error("[watch] route rebuild failed", err);
+          }
+        } while (rebuildQueued);
+        rebuildRunning = false;
+      })();
+    };
+    if (!isWatchedFile(filePath))
+      return;
+    const file = resolveWatchFile(filePath);
+    rebuildReason = `${event}: ${path.relative(watchRoot, file)}`;
+    queue();
+  }, 75);
+  return {
+    name: "mdsrc",
+    enforce: "pre",
+    async buildStart() {
+      await build(src, buildContext);
+    },
+    configureServer(server) {
+      logger2.info(`[configureServer]: Watching for changes in ./${src.map((c) => c.dir).join(", ")}...`);
+      server.watcher.on("add", (p) => rebuild("add", p)).on("change", (p) => rebuild("change", p)).on("unlink", (p) => rebuild("unlink", p));
+    },
+    resolveId(id) {
+      if (id === PKG_NAME) {
+        return path.join(outDir, "index.js");
+      }
+      if (id.startsWith(`${PKG_NAME}/`)) {
+        const subpath = id.slice(PKG_NAME.length + 1);
+        if (buildContext.names.some((name) => name === subpath)) {
+          return path.join(outDir, `${subpath}.js`);
+        }
+      }
+      return null;
+    }
+  };
+}
+export {
+  plugin as default,
+  create
+};
+
+//# debugId=07D2E3DD71DADF0964756E2164756E21

package/dist/logger.d.ts

@@ -0,0 +1,53 @@
+declare const LEVELS: {
+    readonly debug: 0;
+    readonly info: 1;
+    readonly warn: 2;
+    readonly error: 3;
+    readonly fatal: 4;
+};
+export type LogLevel = keyof typeof LEVELS;
+/**
+ * Log messages with different severity levels
+ */
+export declare class Logger {
+    #private;
+    constructor(level?: LogLevel);
+    static set defaultLevel(level: LogLevel);
+    static get defaultLevel(): LogLevel;
+    /**
+     * Convert a value to an Error instance
+     */
+    static toError(err: unknown): Error;
+    /**
+     * Stringify the error for logging
+     */
+    static print(err: unknown): string;
+    set level(level: LogLevel);
+    get level(): LogLevel;
+    /**
+     * Log a message with a specific level
+     */
+    log(level: LogLevel, message: string, error?: Error): void;
+    /**
+     * Log a debug message
+     */
+    debug(...messages: string[]): void;
+    /**
+     * Log an info message
+     */
+    info(...messages: string[]): void;
+    /**
+     * Log a warning message
+     */
+    warn(...messages: string[]): void;
+    /**
+     * Log an error message
+     */
+    error(message: string, error?: unknown): void;
+    /**
+     * Log a fatal error message
+     */
+    fatal(message: string, error?: unknown): void;
+}
+export declare const logger: Logger;
+export {};

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+import type { LogLevel, Logger } from './logger.js';
+export type PluginConfig = {
+    logger?: {
+        level?: LogLevel;
+    };
+};
+export type BuildContext = {
+    logger: InstanceType<typeof Logger>;
+    outDir?: string;
+    names?: string[];
+};
+export type SchemaEntry = {
+    type: 'string' | 'number' | 'boolean' | 'date';
+    optional?: boolean;
+    minLength?: number;
+    maxLength?: number;
+};
+export type Schema = Record<string, SchemaEntry>;
+export type Collection = {
+    name: string;
+    dir: string;
+    schema: Schema;
+};
+export type Entries = Record<string, unknown>;
+export type Raw = {
+    __mdsrc: {
+        slug: string;
+        filename: string;
+    };
+    body?: string;
+} & Entries;
+export type Types = Record<string, string>;
+export type Issue = {
+    readonly message: string;
+};
+export type Fail = {
+    readonly issues: Issue[];
+};
+export type Success<Output> = {
+    readonly value: Output;
+    readonly issues?: Issue[];
+    readonly types?: Record<string, string>;
+};
+export type Result<Output> = Success<Output> | Fail;

package/dist/utils.d.ts

@@ -0,0 +1,3 @@
+export declare function capitalise(str: string): string;
+export declare function pluralise(str: string, count: number): string;
+export declare function debounce<T extends unknown[]>(fn: (...args: T) => void, wait: number): (...args: T) => void;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@jk2908/mdsrc",
+  "version": "0.1.0",
+  "type": "module",
+  "author": "Jerome Kenway",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jk2908/mdsrc.git"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "bun run ./build.ts && bun x tsc --project tsconfig.json --emitDeclarationOnly",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.13",
+    "@typescript/native-preview": "^7.0.0-dev.20260421.2",
+    "@types/node": "^24.0.1",
+    "oxfmt": "^0.35.0",
+    "oxlint": "^1.50.0",
+    "vite": "^5.4.2"
+  },
+  "peerDependencies": {
+    "vite": "^4.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bugs": {
+    "url": "https://github.com/jk2908/mdsrc/issues"
+  },
+  "description": "A Vite plugin for managing markdown content with type safety",
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts"
+  ],
+  "homepage": "https://github.com/jk2908/mdsrc#readme",
+  "keywords": [
+    "markdown",
+    "vite-plugin",
+    "typescript",
+    "content-management",
+    "frontmatter"
+  ],
+  "license": "MIT"
+}