doc-repo 0.1.0-alpha.0

package/dist/core/site/buildSiteBundle.js

@@ -0,0 +1,79 @@
+import fs from "fs-extra";
+import { convertMarkdown } from "../parser/convertMarkdown.js";
+import { AppError } from "../../shared/errors.js";
+const createDir = (name) => ({
+    type: "dir",
+    name,
+    dirs: new Map(),
+    files: [],
+});
+const finalize = (node) => {
+    const childDirs = [...node.dirs.values()]
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((dir) => ({
+        type: "dir",
+        name: dir.name,
+        children: finalize(dir),
+    }));
+    const childFiles = node.files.sort((a, b) => a.name.localeCompare(b.name));
+    return [...childDirs, ...childFiles];
+};
+const addFileToTree = (root, relativePath, id) => {
+    const segments = relativePath.split("/");
+    const fileName = segments.pop() ?? relativePath;
+    let cursor = root;
+    for (const segment of segments) {
+        if (!cursor.dirs.has(segment)) {
+            cursor.dirs.set(segment, createDir(segment));
+        }
+        cursor = cursor.dirs.get(segment);
+    }
+    cursor.files.push({
+        type: "file",
+        name: fileName,
+        id,
+    });
+};
+export const buildSiteBundle = async (files) => {
+    const pages = [];
+    const root = createDir("root");
+    // 実在する全ページのID集合を先に構築し、リンク解決の唯一の正とする。
+    const knownIds = new Set(files.map((file) => file.relativePath.replace(/\.md$/i, "")));
+    // ベース名 → ID。同名が複数ある場合は曖昧なので除外し、一意なものだけ救済対象にする。
+    const basenameCounts = new Map();
+    const basenameToId = new Map();
+    for (const id of knownIds) {
+        const basename = id.split("/").pop() ?? id;
+        basenameCounts.set(basename, (basenameCounts.get(basename) ?? 0) + 1);
+        basenameToId.set(basename, id);
+    }
+    const uniqueBasenames = new Map();
+    for (const [basename, count] of basenameCounts) {
+        if (count === 1) {
+            uniqueBasenames.set(basename, basenameToId.get(basename));
+        }
+    }
+    for (const file of files) {
+        const id = file.relativePath.replace(/\.md$/i, "");
+        let converted;
+        try {
+            const source = await fs.readFile(file.absolutePath, "utf8");
+            converted = convertMarkdown(source, file.relativePath, knownIds, uniqueBasenames);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new AppError(`Markdown の読み取りまたは変換に失敗しました: ${file.relativePath} (${detail})`, "MARKDOWN_READ_OR_CONVERT_FAILED", `対象ファイルを確認してください: ${file.relativePath}`);
+        }
+        pages.push({
+            id,
+            title: converted.title,
+            relativePath: file.relativePath,
+            html: converted.html,
+        });
+        addFileToTree(root, file.relativePath, id);
+    }
+    return {
+        pages,
+        tree: finalize(root),
+    };
+};

package/dist/core/site/copyAssets.d.ts

@@ -0,0 +1 @@
+export declare const copyAssets: (templatesDir: string, stagingDir: string) => Promise<void>;

package/dist/core/site/copyAssets.js

@@ -0,0 +1,8 @@
+import path from "node:path";
+import fs from "fs-extra";
+const ASSET_FILES = ["styles.css"];
+export const copyAssets = async (templatesDir, stagingDir) => {
+    for (const file of ASSET_FILES) {
+        await fs.copyFile(path.join(templatesDir, file), path.join(stagingDir, file));
+    }
+};

package/dist/core/site/generateSite.d.ts

@@ -0,0 +1,2 @@
+import type { GenerationContext, GenerationResult } from "../../shared/types.js";
+export declare const generateSite: (context: GenerationContext) => Promise<GenerationResult>;

package/dist/core/site/generateSite.js

@@ -0,0 +1,101 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import fs from "fs-extra";
+import { detectRoot } from "../scanner/detectRoot.js";
+import { scanMarkdown } from "../scanner/scanMarkdown.js";
+import { buildSiteBundle } from "./buildSiteBundle.js";
+import { renderPages } from "./renderPages.js";
+import { copyAssets } from "./copyAssets.js";
+import { atomicPublish } from "./atomicPublish.js";
+import { AppError, toUserGuidance } from "../../shared/errors.js";
+import { createLogger } from "../../shared/logger.js";
+const resolveTargetDir = async (rootDir, scopePath) => {
+    if (!scopePath) {
+        return rootDir;
+    }
+    const targetDir = path.resolve(rootDir, scopePath);
+    const relativeToRoot = path.relative(rootDir, targetDir);
+    if (relativeToRoot.startsWith("..") || path.isAbsolute(relativeToRoot)) {
+        throw new AppError("指定した生成範囲がリポジトリルート配下ではありません。", "SCOPE_OUTSIDE_ROOT", "リポジトリルートからの相対パスで、配下のフォルダを指定してください。");
+    }
+    if (!(await fs.pathExists(targetDir))) {
+        throw new AppError(`指定した生成範囲が見つかりません: ${scopePath}`, "SCOPE_NOT_FOUND", "存在するフォルダを、リポジトリルートからの相対パスで指定してください。");
+    }
+    const stat = await fs.stat(targetDir);
+    if (!stat.isDirectory()) {
+        throw new AppError(`指定した生成範囲はフォルダではありません: ${scopePath}`, "SCOPE_NOT_DIRECTORY", "生成範囲にはフォルダを指定してください。");
+    }
+    return targetDir;
+};
+const resolveRequestedTargetPath = (rootDir, scopePath) => {
+    if (!scopePath) {
+        return rootDir;
+    }
+    return path.resolve(rootDir, scopePath);
+};
+const resolveTemplatesDir = async (cwd) => {
+    const cwdTemplatesDir = path.resolve(cwd, "templates");
+    if (await fs.pathExists(cwdTemplatesDir)) {
+        return cwdTemplatesDir;
+    }
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    const bundledTemplatesDir = path.resolve(moduleDir, "../../../templates");
+    if (await fs.pathExists(bundledTemplatesDir)) {
+        return bundledTemplatesDir;
+    }
+    throw new AppError("テンプレートディレクトリが見つかりません。", "TEMPLATE_MISSING", "プロジェクトルートに templates/ が存在するか、パッケージに templates/ が同梱されていることを確認してください。");
+};
+export const generateSite = async (context) => {
+    const logger = createLogger();
+    const warnings = [];
+    let outputDir = path.join(path.resolve(context.cwd), ".doc-repo");
+    let targetPath = path.resolve(context.cwd);
+    try {
+        const detected = await detectRoot(context.cwd);
+        const rootDir = detected.detectedRoot;
+        outputDir = path.join(rootDir, ".doc-repo");
+        const stagingDir = path.join(rootDir, `.doc-repo.__staging__.${Date.now()}`);
+        targetPath = resolveRequestedTargetPath(rootDir, context.scopePath);
+        const targetDir = await resolveTargetDir(rootDir, context.scopePath);
+        const templatesDir = await resolveTemplatesDir(context.cwd);
+        if (detected.usedFallback) {
+            warnings.push("Git ルートが見つからなかったため、カレントディレクトリを対象に処理しました。");
+        }
+        const markdownFiles = await scanMarkdown(rootDir, targetDir);
+        if (markdownFiles.length === 0) {
+            warnings.push("Markdown ファイルが 0 件でした。空サイトを生成しました。");
+        }
+        logger.info(`対象ルート: ${rootDir}`);
+        logger.info(`生成対象: ${targetDir}`);
+        logger.info(`検出Markdown数: ${markdownFiles.length}`);
+        await fs.ensureDir(stagingDir);
+        const bundle = await buildSiteBundle(markdownFiles);
+        await renderPages(templatesDir, stagingDir, bundle);
+        await copyAssets(templatesDir, stagingDir);
+        await atomicPublish(stagingDir, outputDir);
+        return {
+            status: "success",
+            exitCode: 0,
+            outputDir,
+            targetPath,
+            markdownFileCount: markdownFiles.length,
+            message: "ドキュメントサイトの生成に成功しました。",
+            warnings,
+        };
+    }
+    catch (error) {
+        const guidance = toUserGuidance(error);
+        logger.error(guidance.reason);
+        return {
+            status: "failure",
+            exitCode: 1,
+            outputDir,
+            targetPath,
+            markdownFileCount: 0,
+            message: "ドキュメントサイトの生成に失敗しました。",
+            warnings,
+            errorReason: guidance.reason,
+            hint: guidance.hint,
+        };
+    }
+};

package/dist/core/site/renderPages.d.ts

@@ -0,0 +1,2 @@
+import type { SiteBundle } from "../../shared/types.js";
+export declare const renderPages: (templatesDir: string, stagingDir: string, bundle: SiteBundle) => Promise<void>;

package/dist/core/site/renderPages.js

@@ -0,0 +1,82 @@
+import path from "node:path";
+import fs from "fs-extra";
+import { docHref, siteRootPrefix } from "../../shared/sitePaths.js";
+const TEMPLATE_FILE = "page.html";
+const escapeHtml = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+// テンプレートのプレースホルダ置換。$ 連鎖を解釈させないため split/join を使う。
+const fill = (template, key, value) => template.split(key).join(value);
+// サイドバーのツリーを、現在ページからの相対 .html リンクとして静的 HTML にレンダリングする。
+// フォルダは <details>/<summary> でネイティブに開閉でき、JS は不要。
+const renderTree = (nodes, currentRelativePath, currentId) => {
+    const renderNodes = (items) => {
+        const lis = items
+            .map((item) => {
+            if (item.type === "dir") {
+                return `<li><details open><summary>${escapeHtml(item.name)}</summary>${renderNodes(item.children)}</details></li>`;
+            }
+            const href = docHref(currentRelativePath, item.id);
+            const selected = item.id === currentId ? ' class="selected" aria-current="page"' : "";
+            return `<li><a href="${href}"${selected}>${escapeHtml(item.name)}</a></li>`;
+        })
+            .join("");
+        return `<ul>${lis}</ul>`;
+    };
+    return renderNodes(nodes);
+};
+const renderPageHtml = (template, page, tree) => {
+    const stylesHref = `${siteRootPrefix(page.relativePath)}styles.css`;
+    const homeHref = `${siteRootPrefix(page.relativePath)}index.html`;
+    const sidebar = renderTree(tree, page.relativePath, page.id);
+    let html = fill(template, "__TITLE__", escapeHtml(page.title));
+    html = fill(html, "__STYLES_HREF__", stylesHref);
+    html = fill(html, "__HOME_HREF__", homeHref);
+    html = fill(html, "__SIDEBAR__", sidebar);
+    html = fill(html, "__ARTICLE__", page.html);
+    return html;
+};
+// ルート index.html: ホームページ（README 優先、なければ先頭ページ）へリダイレクトする静的 HTML。
+const pickHomePage = (pages) => pages.find((page) => page.id === "README" || page.id === "readme") ?? pages[0];
+const renderIndexHtml = (bundle) => {
+    const home = pickHomePage(bundle.pages);
+    if (!home) {
+        return [
+            "<!doctype html>",
+            '<html lang="ja">',
+            "<head>",
+            '<meta charset="utf-8" />',
+            "<title>doc-repo</title>",
+            '<link rel="stylesheet" href="./styles.css" />',
+            "</head>",
+            "<body>",
+            '<main class="content"><article><p class="muted">No Markdown files found.</p></article></main>',
+            "</body>",
+            "</html>",
+            "",
+        ].join("\n");
+    }
+    const homeHref = `./${docHref("index.md", home.id)}`;
+    return [
+        "<!doctype html>",
+        '<html lang="ja">',
+        "<head>",
+        '<meta charset="utf-8" />',
+        `<meta http-equiv="refresh" content="0; url=${homeHref}" />`,
+        `<link rel="canonical" href="${homeHref}" />`,
+        "<title>doc-repo</title>",
+        "</head>",
+        "<body>",
+        `<p>移動中です… <a href="${homeHref}">${escapeHtml(home.title)}</a></p>`,
+        "</body>",
+        "</html>",
+        "",
+    ].join("\n");
+};
+// 各 Markdown を 1 対 1 で実 HTML に出力し、ルート index.html も生成する。
+export const renderPages = async (templatesDir, stagingDir, bundle) => {
+    const template = await fs.readFile(path.join(templatesDir, TEMPLATE_FILE), "utf8");
+    for (const page of bundle.pages) {
+        const outputPath = path.join(stagingDir, ...page.id.split("/")) + ".html";
+        await fs.outputFile(outputPath, renderPageHtml(template, page, bundle.tree), "utf8");
+    }
+    await fs.outputFile(path.join(stagingDir, "index.html"), renderIndexHtml(bundle), "utf8");
+};

package/dist/shared/errors.d.ts

@@ -0,0 +1,9 @@
+export declare class AppError extends Error {
+    readonly code: string;
+    readonly hint: string;
+    constructor(message: string, code: string, hint: string);
+}
+export declare const toUserGuidance: (error: unknown) => {
+    reason: string;
+    hint: string;
+};

package/dist/shared/errors.js

@@ -0,0 +1,28 @@
+export class AppError extends Error {
+    code;
+    hint;
+    constructor(message, code, hint) {
+        super(message);
+        this.name = "AppError";
+        this.code = code;
+        this.hint = hint;
+    }
+}
+export const toUserGuidance = (error) => {
+    if (error instanceof AppError) {
+        return {
+            reason: `${error.code}: ${error.message}`,
+            hint: error.hint,
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            reason: error.message,
+            hint: "実行ディレクトリの権限と入力ファイルを確認して再実行してください。",
+        };
+    }
+    return {
+        reason: "Unknown error",
+        hint: "詳細ログを確認し、問題が解消しない場合は再実行してください。",
+    };
+};

package/dist/shared/logger.d.ts

@@ -0,0 +1,7 @@
+export type LogLevel = "info" | "error";
+export interface Logger {
+    log: (level: LogLevel, message: string) => void;
+    info: (message: string) => void;
+    error: (message: string) => void;
+}
+export declare const createLogger: () => Logger;

package/dist/shared/logger.js

@@ -0,0 +1,16 @@
+export const createLogger = () => {
+    const log = (level, message) => {
+        const prefix = `[doc-repo:${level}]`;
+        const line = `${prefix} ${message}`;
+        if (level === "error") {
+            console.error(line);
+            return;
+        }
+        console.log(line);
+    };
+    return {
+        log,
+        info: (message) => log("info", message),
+        error: (message) => log("error", message),
+    };
+};

package/dist/shared/sitePaths.d.ts

@@ -0,0 +1,5 @@
+export declare const pageDirDepth: (relativePath: string) => number;
+export declare const siteRootPrefix: (relativePath: string) => string;
+export declare const repoRootPrefix: (relativePath: string) => string;
+export declare const docHref: (currentRelativePath: string, targetId: string) => string;
+export declare const assetHref: (currentRelativePath: string, pathFromRoot: string, suffix: string) => string;

package/dist/shared/sitePaths.js

@@ -0,0 +1,28 @@
+import path from "node:path";
+// マルチページ静的サイトのリンク計算ヘルパー。
+// 出力は `.doc-repo/<id>.html` のミラー構造になり、ページ間リンクはブラウザネイティブの相対パスで解決する。
+const toPosix = (value) => value.split(path.sep).join(path.posix.sep);
+// 各セグメントを URL エンコードしつつ、`/`・`.`・`..` は保つ。
+// 日本語やスペースを含む ID/パスでも file:// で確実に解決できるようにする。
+const encodePath = (value) => value
+    .split("/")
+    .map((segment) => (segment === "" || segment === "." || segment === ".." ? segment : encodeURIComponent(segment)))
+    .join("/");
+// ページの出力ディレクトリの深さ（セグメント数）。ルート直下のページは 0。
+export const pageDirDepth = (relativePath) => {
+    const dir = path.posix.dirname(toPosix(relativePath));
+    return dir === "." || dir === "" ? 0 : dir.split("/").length;
+};
+// ページ出力ディレクトリから `.doc-repo` ルートへ戻る相対プレフィックス（styles.css 等のサイト内資産向け）。
+export const siteRootPrefix = (relativePath) => "../".repeat(pageDirDepth(relativePath));
+// ページ出力ディレクトリからリポジトリルートへ戻る相対プレフィックス（`.doc-repo` を抜ける画像・添付向け）。
+export const repoRootPrefix = (relativePath) => "../".repeat(pageDirDepth(relativePath) + 1);
+// 現在ページから対象ページ ID（拡張子なし）への相対 `.html` リンク。
+export const docHref = (currentRelativePath, targetId) => {
+    const currentDir = path.posix.dirname(toPosix(currentRelativePath));
+    const baseDir = currentDir === "." ? "" : currentDir;
+    const relative = path.posix.relative(baseDir, toPosix(targetId));
+    return `${encodePath(relative)}.html`;
+};
+// リポジトリ相対の資産パス（画像・添付など）を、現在ページからの相対パスへ変換する。
+export const assetHref = (currentRelativePath, pathFromRoot, suffix) => `${repoRootPrefix(currentRelativePath)}${encodePath(pathFromRoot)}${suffix}`;

package/dist/shared/types.d.ts

@@ -0,0 +1,45 @@
+export type ExecutionStatus = "success" | "failure";
+export interface MarkdownFile {
+    absolutePath: string;
+    relativePath: string;
+}
+export interface SitePage {
+    id: string;
+    title: string;
+    relativePath: string;
+    html: string;
+}
+export interface TreeDirNode {
+    type: "dir";
+    name: string;
+    children: TreeNode[];
+}
+export interface TreeFileNode {
+    type: "file";
+    name: string;
+    id: string;
+}
+export type TreeNode = TreeDirNode | TreeFileNode;
+export interface SiteBundle {
+    pages: SitePage[];
+    tree: TreeNode[];
+}
+export interface RootDetectionResult {
+    detectedRoot: string;
+    usedFallback: boolean;
+}
+export interface GenerationContext {
+    cwd: string;
+    scopePath?: string;
+}
+export interface GenerationResult {
+    status: ExecutionStatus;
+    exitCode: number;
+    outputDir: string;
+    targetPath: string;
+    markdownFileCount: number;
+    message: string;
+    warnings: string[];
+    errorReason?: string;
+    hint?: string;
+}

package/dist/shared/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "doc-repo",
+  "version": "0.1.0-alpha.0",
+  "description": "Generate a static documentation site from repository Markdown files.",
+  "keywords": [
+    "markdown",
+    "documentation",
+    "static-site",
+    "cli",
+    "repository",
+    "docs"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Ryuta Otsuka",
+    "url": "https://github.com/Ryuta1005"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ryuta1005/doc-repo.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Ryuta1005/doc-repo/issues"
+  },
+  "homepage": "https://github.com/Ryuta1005/doc-repo#readme",
+  "type": "module",
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "bin": {
+    "doc-repo": "dist/cli/index.js"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "prebuild": "npm run clean",
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsx src/cli/index.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc -p tsconfig.tests.json",
+    "test": "vitest run --coverage",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "fast-glob": "^3.3.3",
+    "fs-extra": "^11.3.5",
+    "markdown-it": "^14.2.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/jsdom": "^28.0.3",
+    "@types/markdown-it": "^14.1.2",
+    "@types/node": "^25.9.2",
+    "@vitest/coverage-v8": "^4.1.8",
+    "jsdom": "^29.1.1",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  }
+}