@mdsrs/fs 0.0.0

package/README.md

@@ -0,0 +1,23 @@
+# @mdsrs/fs
+
+Node filesystem loader for Markdown card collections.
+
+`@mdsrs/fs` turns a human-readable folder of Markdown files into the pure data
+structures exposed by `@mdsrs/core`.
+
+## Example
+
+```ts
+import { loadCollection, resolveContentAssetPath } from '@mdsrs/fs';
+
+const collection = await loadCollection('./cards');
+const assetPath = resolveContentAssetPath('biology/cells.md', './assets/cell.png');
+```
+
+## Folder conventions
+
+- Every `*.md` file is parsed as a deck source.
+- `index.md` contributes cards directly to its folder deck.
+- Other Markdown files become child deck nodes below their folder.
+- Frontmatter can set a human display name with `name = "..."`.
+- Asset paths resolve relative to the Markdown file, while `@/` resolves from the collection root.

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { type Card, type DeckSource, type DeckTreeNode } from '@mdsrs/core';
+export interface LoadCollectionOptions {
+    assetExtensions?: Iterable<string>;
+    includeHidden?: boolean;
+}
+export interface CollectionAsset {
+    path: string;
+    absolutePath: string;
+}
+export interface LoadedCollection {
+    rootPath: string;
+    sources: DeckSource[];
+    cards: Card[];
+    deckTree: DeckTreeNode[];
+    assets: CollectionAsset[];
+}
+export declare const sourceHierarchy: (filePath: string, frontmatterName: string | null) => {
+    folderPath: string;
+    nodePath: string;
+    displayName: string;
+    deckName: string;
+};
+export declare const resolveContentAssetPath: (filePath: string, assetPath: string) => string | null;
+export declare const resolveCollectionAssetPath: (rootPath: string, contentAssetPath: string) => string | null;
+export declare const loadDeckSources: (root: string | URL, options?: LoadCollectionOptions) => Promise<DeckSource[]>;
+export declare const loadAssets: (root: string | URL, options?: LoadCollectionOptions) => Promise<CollectionAsset[]>;
+export declare const loadCollection: (root: string | URL, options?: LoadCollectionOptions) => Promise<LoadedCollection>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAkC,KAAK,IAAI,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAuB5G,MAAM,WAAW,qBAAqB;IACrC,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACnC,aAAa,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,MAAM,EAAE,eAAe,EAAE,CAAC;CAC1B;AA0BD,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,EAAE,iBAAiB,MAAM,GAAG,IAAI;;;;;CAiB/E,CAAC;AAkBF,eAAO,MAAM,uBAAuB,GAAI,UAAU,MAAM,EAAE,WAAW,MAAM,kBAM1E,CAAC;AAEF,eAAO,MAAM,0BAA0B,GAAI,UAAU,MAAM,EAAE,kBAAkB,MAAM,kBAIpF,CAAC;AAEF,eAAO,MAAM,eAAe,GAC3B,MAAM,MAAM,GAAG,GAAG,EAClB,UAAS,qBAA0B,KACjC,OAAO,CAAC,UAAU,EAAE,CAuBtB,CAAC;AAEF,eAAO,MAAM,UAAU,GACtB,MAAM,MAAM,GAAG,GAAG,EAClB,UAAS,qBAA0B,KACjC,OAAO,CAAC,eAAe,EAAE,CAgB3B,CAAC;AAEF,eAAO,MAAM,cAAc,GAC1B,MAAM,MAAM,GAAG,GAAG,EAClB,UAAS,qBAA0B,KACjC,OAAO,CAAC,gBAAgB,CAe1B,CAAC"}

package/dist/index.js

@@ -0,0 +1,152 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildDeckTree, parseCollection } from '@mdsrs/core';
+const frontmatterPattern = /^---\s*\n([\s\S]*?)\n---\s*\n?/;
+const externalUrlPattern = /^(?:[a-z][a-z0-9+.-]*:|#|\/)/i;
+const defaultAssetExtensions = new Set([
+    '.avif',
+    '.gif',
+    '.jpeg',
+    '.jpg',
+    '.m4a',
+    '.m4v',
+    '.mov',
+    '.mp3',
+    '.mp4',
+    '.ogg',
+    '.png',
+    '.svg',
+    '.wav',
+    '.webm',
+    '.webp'
+]);
+const toRootPath = (root) => path.resolve(root instanceof URL ? fileURLToPath(root) : root);
+const toPosixPath = (value) => value.split(path.sep).join('/');
+const parseFrontmatterName = (text) => {
+    const match = text.match(frontmatterPattern);
+    const frontmatter = match?.[1] ?? '';
+    const name = frontmatter.match(/^name\s*=\s*"(.+)"\s*$/m)?.[1];
+    return name ?? null;
+};
+const stripFrontmatter = (text) => text.replace(frontmatterPattern, '');
+const fileStem = (filePath) => filePath.split('/').at(-1)?.replace(/\.md$/, '') ?? 'Untitled';
+const titleize = (value) => value
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => part.slice(0, 1).toUpperCase() + part.slice(1))
+    .join(' ');
+export const sourceHierarchy = (filePath, frontmatterName) => {
+    const pathWithoutExtension = filePath.replace(/\.md$/, '');
+    const parts = pathWithoutExtension.split('/').filter(Boolean);
+    const isIndex = parts.at(-1) === 'index';
+    const nodeParts = isIndex ? parts.slice(0, -1) : parts;
+    const folderParts = isIndex ? nodeParts : nodeParts.slice(0, -1);
+    const nodePath = nodeParts.join('/');
+    const folderPath = folderParts.join('/');
+    const fallbackName = titleize(nodeParts.at(-1) ?? fileStem(filePath));
+    const displayName = frontmatterName ?? fallbackName;
+    return {
+        folderPath,
+        nodePath,
+        displayName,
+        deckName: nodePath || displayName
+    };
+};
+const normalizeContentPath = (contentPath) => {
+    const parts = [];
+    for (const part of contentPath.split('/')) {
+        if (!part || part === '.')
+            continue;
+        if (part === '..') {
+            if (parts.length === 0)
+                return null;
+            parts.pop();
+            continue;
+        }
+        parts.push(part);
+    }
+    return parts.join('/');
+};
+export const resolveContentAssetPath = (filePath, assetPath) => {
+    if (externalUrlPattern.test(assetPath))
+        return assetPath;
+    return assetPath.startsWith('@/')
+        ? normalizeContentPath(assetPath.slice(2))
+        : normalizeContentPath(`${filePath.split('/').slice(0, -1).join('/')}/${assetPath}`);
+};
+export const resolveCollectionAssetPath = (rootPath, contentAssetPath) => {
+    if (externalUrlPattern.test(contentAssetPath))
+        return contentAssetPath;
+    const normalized = normalizeContentPath(contentAssetPath);
+    return normalized ? path.join(rootPath, ...normalized.split('/')) : null;
+};
+export const loadDeckSources = async (root, options = {}) => {
+    const rootPath = toRootPath(root);
+    const files = await walkFiles(rootPath, options);
+    const markdownFiles = files
+        .filter((filePath) => filePath.toLowerCase().endsWith('.md'))
+        .sort((left, right) => left.localeCompare(right));
+    return Promise.all(markdownFiles.map(async (absolutePath) => {
+        const filePath = toPosixPath(path.relative(rootPath, absolutePath));
+        const text = await readFile(absolutePath, 'utf8');
+        const hierarchy = sourceHierarchy(filePath, parseFrontmatterName(text));
+        return {
+            deckName: hierarchy.deckName,
+            filePath,
+            folderPath: hierarchy.folderPath,
+            nodePath: hierarchy.nodePath,
+            displayName: hierarchy.displayName,
+            text: stripFrontmatter(text)
+        };
+    }));
+};
+export const loadAssets = async (root, options = {}) => {
+    const rootPath = toRootPath(root);
+    const assetExtensions = new Set([...(options.assetExtensions ?? defaultAssetExtensions)].map((extension) => extension.startsWith('.') ? extension.toLowerCase() : `.${extension.toLowerCase()}`));
+    const files = await walkFiles(rootPath, options);
+    return files
+        .filter((filePath) => assetExtensions.has(path.extname(filePath).toLowerCase()))
+        .sort((left, right) => left.localeCompare(right))
+        .map((absolutePath) => ({
+        path: toPosixPath(path.relative(rootPath, absolutePath)),
+        absolutePath
+    }));
+};
+export const loadCollection = async (root, options = {}) => {
+    const rootPath = toRootPath(root);
+    const [sources, assets] = await Promise.all([
+        loadDeckSources(rootPath, options),
+        loadAssets(rootPath, options)
+    ]);
+    const cards = parseCollection(sources);
+    return {
+        rootPath,
+        sources,
+        cards,
+        deckTree: buildDeckTree(cards),
+        assets
+    };
+};
+const walkFiles = async (rootPath, options) => {
+    const rootStats = await stat(rootPath);
+    if (!rootStats.isDirectory()) {
+        throw new Error(`Collection root must be a directory: ${rootPath}`);
+    }
+    const files = [];
+    const visit = async (directoryPath) => {
+        const entries = await readdir(directoryPath, { withFileTypes: true });
+        entries.sort((left, right) => left.name.localeCompare(right.name));
+        for (const entry of entries) {
+            if (!options.includeHidden && entry.name.startsWith('.'))
+                continue;
+            const entryPath = path.join(directoryPath, entry.name);
+            if (entry.isDirectory())
+                await visit(entryPath);
+            else if (entry.isFile())
+                files.push(entryPath);
+        }
+    };
+    await visit(rootPath);
+    return files;
+};

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@mdsrs/fs",
+  "version": "0.0.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@mdsrs/core": "0.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}