doc-repo 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryuta Otsuka
+
+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.ja.md

@@ -0,0 +1,162 @@
+# doc-repo
+
+リポジトリ内の Markdown を、フォルダツリーでたどれる静的ドキュメントサイトに変換する CLI です。
+
+> [!WARNING]
+> `doc-repo` は現時点で alpha 想定です。CLI の引数仕様や生成ファイル構成は将来変更される可能性があります。
+
+![doc-repo screenshot placeholder](./docs/assets/screenshot-sample.png)
+
+## なぜ使うのか
+
+リポジトリ内に仕様書・設計メモ・運用ドキュメントが増えると、次の課題が起きやすくなります。
+
+- Markdown ファイルが複数階層に散らばり、全体を追いづらい
+- エディタを開かないと文書の中身を横断閲覧しにくい
+- 非開発者へ「まずどのファイルを見ればよいか」を共有しづらい
+
+`doc-repo` は、これらを「左ツリー / 右本文」の 2 ペイン閲覧にまとめることで、閲覧導線をシンプルにします。
+
+## 主な特徴
+
+- リポジトリ内の `.md` を再帰的に自動収集
+- ディレクトリ構造を保ったツリーナビゲーション
+- ローカルサーバー不要（`index.html` を直接開ける）
+- 対象ディレクトリ指定（`scopePath`）に対応
+- `--open` で生成後にブラウザを自動起動
+
+## クイックスタート
+
+前提:
+
+- Node.js 20 以上
+
+リポジトリ内で実行:
+
+```bash
+npx doc-repo
+```
+
+alpha タグで配布している期間は、次を利用してください。
+
+```bash
+npx doc-repo@alpha
+```
+
+生成後にブラウザで開く:
+
+```bash
+open .doc-repo/index.html
+```
+
+特定ディレクトリのみ生成する場合:
+
+```bash
+npx doc-repo specs
+npx doc-repo docs/project
+```
+
+## CLI
+
+```bash
+doc-repo [scopePath] [--open]
+```
+
+| 引数 / オプション | 説明                                                 | デフォルト     |
+| ----------------- | ---------------------------------------------------- | -------------- |
+| `scopePath`       | 生成対象ディレクトリ（Git ルート基準の相対パス）     | Git ルート全体 |
+| `--open`          | 生成後に `.doc-repo/index.html` を既定ブラウザで開く | `false`        |
+
+### 対象ルートと収集対象の違い
+
+- 対象ルート: Git ルート（見つからない場合はカレント）
+- 収集対象: 対象ルート内で `scopePath` が指すディレクトリ配下
+
+## 生成結果
+
+`.doc-repo` 配下に、Markdown のツリーをミラーしたマルチページ静的サイトを生成します。
+
+```text
+.doc-repo/
+├── index.html        # ホーム（README があれば README）へリダイレクト
+├── styles.css
+├── README.html
+└── docs/
+    └── guide/
+        └── page.html
+```
+
+各 Markdown は単独の `.html` として出力され、文書間リンクは素の相対リンクになります。
+そのため `file://` で直接開いても遷移できます。
+
+信頼性に関する挙動:
+
+- 生成成功時のみ `.doc-repo` を置換（再実行で最新化）
+- 一時ディレクトリで生成してから切り替え
+- 失敗時は既存 `.doc-repo` を保持
+- Markdown 0 件時は空サイトを生成し、警告付き成功（exit code 0）
+
+### 終了コード
+
+| コード | 意味                       |
+| ------ | -------------------------- |
+| `0`    | 成功（警告付き成功を含む） |
+| `1`    | 失敗                       |
+
+## 現在の制限事項
+
+- ローカルサーバー起動（`serve`）は未対応
+- ファイル監視（`watch`）は未対応
+- ブラウザ上での Markdown 編集は未対応
+- include/exclude の詳細設定は未対応
+
+## Markdown 対応方針（現状）
+
+- 変換ライブラリ: `markdown-it`
+- `html: false`（Markdown 内の生 HTML は無効）
+- `linkify: true`, `typographer: true`
+- GFM の一部拡張（例: task list、Mermaid、コードハイライト）は未対応
+- 相対画像・相対リンクは現状「入力ファイル配置を維持した再配置」をしていないため、構成によっては期待通りに表示されない場合あり
+
+## セキュリティ注意
+
+- 生 HTML は無効化していますが、生成対象は基本的に信頼できるリポジトリを想定してください
+- 未知のリポジトリに対して実行する場合は、生成結果を確認してから共有してください
+
+## `.doc-repo` の Git 管理方針
+
+用途に応じて選択してください。
+
+- 一時生成物として扱う場合: `.gitignore` に `.doc-repo/` を追加
+- 成果物配布・公開に使う場合: 生成物コミット運用も可（毎回再生成で置換される前提）
+
+## 開発者向け
+
+開発者向け手順:
+
+```bash
+npm install
+npm run dev
+npm run dev -- specs
+```
+
+ビルド:
+
+```bash
+npm run build
+```
+
+ビルド済み CLI 実行:
+
+```bash
+node dist/cli/index.js
+node dist/cli/index.js specs
+```
+
+## Issues / Feedback
+
+不具合報告や要望は GitHub Issues を利用してください。
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,162 @@
+# doc-repo
+
+doc-repo is a CLI that converts Markdown files in your repository into a browsable static documentation site with a directory tree.
+
+> [!WARNING]
+> `doc-repo` is currently in alpha. CLI arguments and generated file structure may change in future releases.
+
+![doc-repo screenshot placeholder](./docs/assets/screenshot-sample.png)
+
+## Why doc-repo?
+
+As repositories grow, Markdown documents (specs, design notes, operational docs) tend to become harder to navigate.
+
+- Markdown files are scattered across multiple directories.
+- It is hard to browse content across files without opening an editor.
+- It is difficult to share a clear reading path with non-developers.
+
+doc-repo addresses this by generating a two-pane viewer (left tree / right content) that makes repository documents easier to explore.
+
+## Features
+
+- Recursively discovers `.md` files in your repository
+- Preserves directory structure in tree navigation
+- Works without a local server (`index.html` can be opened directly)
+- Supports directory-scoped generation (`scopePath`)
+- Supports `--open` to launch the generated page automatically
+
+## Quick Start
+
+Prerequisite:
+
+- Node.js 20+
+
+Run inside a repository:
+
+```bash
+npx doc-repo
+```
+
+If the package is published under an alpha tag, use:
+
+```bash
+npx doc-repo@alpha
+```
+
+Open the generated site:
+
+```bash
+open .doc-repo/index.html
+```
+
+Generate only a specific directory:
+
+```bash
+npx doc-repo specs
+npx doc-repo docs/project
+```
+
+## CLI
+
+```bash
+doc-repo [scopePath] [--open]
+```
+
+| Argument / Option | Description                                                            | Default        |
+| ----------------- | ---------------------------------------------------------------------- | -------------- |
+| `scopePath`       | Directory to generate from (path relative to Git root)                 | Whole Git root |
+| `--open`          | Open `.doc-repo/index.html` with your default browser after generation | `false`        |
+
+### Target Root vs Collection Scope
+
+- Target root: Git root (or current directory when Git root is not found)
+- Collection scope: Directory under target root resolved from `scopePath`
+
+## Output
+
+doc-repo generates a multi-page static site under `.doc-repo`, mirroring your Markdown tree:
+
+```text
+.doc-repo/
+├── index.html        # redirects to the home page (README if present)
+├── styles.css
+├── README.html
+└── docs/
+    └── guide/
+        └── page.html
+```
+
+Each Markdown file becomes a standalone `.html`, and links between documents are
+plain relative links, so it works even when opened directly via `file://`.
+
+Reliability behavior:
+
+- Replaces `.doc-repo` only after a successful generation
+- Generates in a staging directory before publishing
+- Keeps existing `.doc-repo` when generation fails
+- Generates an empty site and exits successfully with warning when no Markdown files are found
+
+### Exit Codes
+
+| Code | Meaning                                   |
+| ---- | ----------------------------------------- |
+| `0`  | Success (including success with warnings) |
+| `1`  | Failure                                   |
+
+## Current Limitations
+
+- Local server mode (`serve`) is not supported yet
+- File watching (`watch`) is not supported yet
+- Browser-based Markdown editing is not supported yet
+- Detailed include/exclude rules are not supported yet
+
+## Markdown Support (Current)
+
+- Converter: `markdown-it`
+- `html: false` (raw HTML in Markdown is disabled)
+- `linkify: true`, `typographer: true`
+- Some GFM extensions (task lists, Mermaid, code highlighting) are not yet supported
+- Relative images/links may not render as expected in some repository layouts because assets are not currently rewritten/rebased
+
+## Security Notes
+
+- Raw HTML is disabled, but generation is still intended for trusted repositories
+- If you run doc-repo on unknown repositories, review output before sharing
+
+## Git Policy for `.doc-repo`
+
+Choose a policy based on your use case:
+
+- Treat as temporary artifact: add `.doc-repo/` to `.gitignore`
+- Treat as distributable artifact: committing generated files is also possible (output is replaced on each successful run)
+
+## Development
+
+For contributors:
+
+```bash
+npm install
+npm run dev
+npm run dev -- specs
+```
+
+Build:
+
+```bash
+npm run build
+```
+
+Run compiled CLI:
+
+```bash
+node dist/cli/index.js
+node dist/cli/index.js specs
+```
+
+## Issues / Feedback
+
+Please use GitHub Issues for bug reports and feature requests.
+
+## License
+
+MIT

package/dist/cli/exitCode.d.ts

@@ -0,0 +1,2 @@
+import type { GenerationResult } from "../shared/types.js";
+export declare const resolveExitCode: (result: GenerationResult) => number;

package/dist/cli/exitCode.js

@@ -0,0 +1,3 @@
+export const resolveExitCode = (result) => {
+    return result.exitCode;
+};

package/dist/cli/formatResultMessage.d.ts

@@ -0,0 +1,2 @@
+import type { GenerationResult } from "../shared/types.js";
+export declare const formatResultMessage: (result: GenerationResult) => string;

package/dist/cli/formatResultMessage.js

@@ -0,0 +1,18 @@
+export const formatResultMessage = (result) => {
+    const lines = [result.message, `生成対象: ${result.targetPath}`, `出力先: ${result.outputDir}`];
+    if (result.warnings.length > 0) {
+        lines.push("警告:");
+        for (const warning of result.warnings) {
+            lines.push(`- ${warning}`);
+        }
+    }
+    if (result.status === "failure") {
+        if (result.errorReason) {
+            lines.push(`理由: ${result.errorReason}`);
+        }
+        if (result.hint) {
+            lines.push(`対処: ${result.hint}`);
+        }
+    }
+    return lines.join("\n");
+};

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare const run: (argv?: string[], cwd?: string) => Promise<void>;

package/dist/cli/index.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { Command } from "commander";
+import { generateSite } from "../core/site/generateSite.js";
+import { formatResultMessage } from "./formatResultMessage.js";
+import { resolveExitCode } from "./exitCode.js";
+const openFile = (filePath) => {
+    if (process.platform === "win32") {
+        const child = spawn("cmd", ["/c", "start", "", filePath], { detached: true, stdio: "ignore" });
+        child.unref();
+        return;
+    }
+    const cmd = process.platform === "darwin" ? "open" : "xdg-open";
+    const child = spawn(cmd, [filePath], { detached: true, stdio: "ignore" });
+    child.unref();
+};
+export const run = async (argv = process.argv, cwd = process.cwd()) => {
+    const program = new Command();
+    program
+        .name("doc-repo")
+        .description("Generate a static documentation site from Markdown files.")
+        .argument("[scopePath]", "Repository-relative directory to generate")
+        .option("--open", "生成後にブラウザで index.html を開く")
+        .action(async (scopePath, options) => {
+        const result = await generateSite({ cwd, scopePath });
+        const message = formatResultMessage(result);
+        if (result.status === "failure") {
+            console.error(message);
+        }
+        else {
+            console.log(message);
+            if (options?.open) {
+                openFile(path.join(result.outputDir, "index.html"));
+            }
+        }
+        process.exitCode = resolveExitCode(result);
+    });
+    await program.parseAsync(argv);
+};
+if (process.env.VITEST !== "true") {
+    void run();
+}

package/dist/core/parser/convertMarkdown.d.ts

@@ -0,0 +1,4 @@
+export declare const convertMarkdown: (source: string, relativePath: string, knownIds?: Set<string>, uniqueBasenames?: Map<string, string>) => {
+    title: string;
+    html: string;
+};

package/dist/core/parser/convertMarkdown.js

@@ -0,0 +1,127 @@
+import path from "node:path";
+import MarkdownIt from "markdown-it";
+import { assetHref, docHref } from "../../shared/sitePaths.js";
+const md = new MarkdownIt({
+    html: false,
+    linkify: true,
+    typographer: true,
+});
+const EXTERNAL_OR_HASH = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i;
+// markdown-it は href を内部でパーセントエンコードするため、解決前に生パスへ戻す。
+// 不正なエスケープはデコードせず元の値を返す（安全側）。
+const decodePathSafe = (value) => {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+};
+const splitUrlAndSuffix = (url) => {
+    const hashIndex = url.indexOf("#");
+    const queryIndex = url.indexOf("?");
+    const firstSuffixIndex = hashIndex === -1 ? queryIndex : queryIndex === -1 ? hashIndex : Math.min(hashIndex, queryIndex);
+    if (firstSuffixIndex === -1) {
+        return { rawPath: decodePathSafe(url), suffix: "" };
+    }
+    return {
+        rawPath: decodePathSafe(url.slice(0, firstSuffixIndex)),
+        suffix: url.slice(firstSuffixIndex),
+    };
+};
+const rebaseRepoRelativeUrl = (url, relativePath) => {
+    if (!url || EXTERNAL_OR_HASH.test(url)) {
+        return url;
+    }
+    const { rawPath, suffix } = splitUrlAndSuffix(url);
+    const pathFromRoot = resolvePathFromRoot(rawPath, relativePath);
+    if (!pathFromRoot) {
+        return url;
+    }
+    return assetHref(relativePath, pathFromRoot, suffix);
+};
+// リポジトリルートからの正規化パスを求める。ルート外（../ で抜ける）や空は null。
+const resolvePathFromRoot = (rawPath, relativePath) => {
+    if (!rawPath) {
+        return null;
+    }
+    const normalizedRelativePath = relativePath.split(path.sep).join(path.posix.sep);
+    const pathFromRoot = rawPath.startsWith("/")
+        ? rawPath.slice(1)
+        : path.posix.normalize(path.posix.join(path.posix.dirname(normalizedRelativePath), rawPath));
+    if (!pathFromRoot || pathFromRoot.startsWith("../")) {
+        return null;
+    }
+    return pathFromRoot;
+};
+// 既知のページID集合に対してリンク先を解決し、一致したIDだけを返す。
+// 推測ではなく実在ページとの突き合わせで判定するため、遷移可否が安定する。
+// 厳密解決に失敗した .md リンクは、同名ページが一意な場合のみベース名で救済する。
+const resolveDocId = (href, relativePath, knownIds, uniqueBasenames) => {
+    if (!href || EXTERNAL_OR_HASH.test(href)) {
+        return null;
+    }
+    const { rawPath } = splitUrlAndSuffix(href);
+    const pathFromRoot = resolvePathFromRoot(rawPath, relativePath);
+    if (/\.md$/i.test(rawPath)) {
+        if (pathFromRoot) {
+            const id = pathFromRoot.replace(/\.md$/i, "");
+            if (knownIds.has(id)) {
+                return id;
+            }
+        }
+        // フォールバック: 相対パスがズレていても、同名ページが 1 件だけなら救済する。
+        const basename = path.posix.basename(rawPath).replace(/\.md$/i, "");
+        return uniqueBasenames.get(basename) ?? null;
+    }
+    if (!pathFromRoot) {
+        return null;
+    }
+    const basename = path.posix.basename(rawPath);
+    const isDirectoryLike = rawPath.endsWith("/") || !basename.includes(".");
+    if (isDirectoryLike) {
+        const indexId = path.posix.join(pathFromRoot, "index");
+        if (knownIds.has(indexId)) {
+            return indexId;
+        }
+    }
+    return knownIds.has(pathFromRoot) ? pathFromRoot : null;
+};
+const imageRule = md.renderer.rules.image;
+md.renderer.rules.image = (tokens, idx, options, env, self) => {
+    const src = tokens[idx]?.attrGet("src");
+    const { relativePath } = (env ?? {});
+    if (src && relativePath) {
+        tokens[idx]?.attrSet("src", rebaseRepoRelativeUrl(src, relativePath));
+    }
+    return imageRule ? imageRule(tokens, idx, options, env, self) : self.renderToken(tokens, idx, options);
+};
+const linkOpenRule = md.renderer.rules.link_open;
+md.renderer.rules.link_open = (tokens, idx, options, env, self) => {
+    const href = tokens[idx]?.attrGet("href");
+    const { relativePath, knownIds, uniqueBasenames } = (env ?? {});
+    if (href && relativePath) {
+        const docId = knownIds ? resolveDocId(href, relativePath, knownIds, uniqueBasenames ?? new Map()) : null;
+        if (docId) {
+            // 実在ページに一致したリンクは、現在ページからの相対 .html リンクへ。
+            tokens[idx]?.attrSet("href", docHref(relativePath, docId));
+        }
+        else {
+            // それ以外（画像/添付/外部/未解決）は資産として相対パスへリベースする。
+            tokens[idx]?.attrSet("href", rebaseRepoRelativeUrl(href, relativePath));
+        }
+    }
+    return linkOpenRule ? linkOpenRule(tokens, idx, options, env, self) : self.renderToken(tokens, idx, options);
+};
+const findTitle = (source, relativePath) => {
+    const heading = source.match(/^#\s+(.+)$/m);
+    if (heading?.[1]) {
+        return heading[1].trim();
+    }
+    return path.basename(relativePath, ".md");
+};
+export const convertMarkdown = (source, relativePath, knownIds = new Set(), uniqueBasenames = new Map()) => {
+    const title = findTitle(source, relativePath);
+    const html = md.render(source, { relativePath, knownIds, uniqueBasenames });
+    return { title, html };
+};

package/dist/core/scanner/detectRoot.d.ts

@@ -0,0 +1,2 @@
+import type { RootDetectionResult } from "../../shared/types.js";
+export declare const detectRoot: (cwd: string) => Promise<RootDetectionResult>;

package/dist/core/scanner/detectRoot.js

@@ -0,0 +1,22 @@
+import path from "node:path";
+import fs from "fs-extra";
+export const detectRoot = async (cwd) => {
+    let current = path.resolve(cwd);
+    while (true) {
+        const gitPath = path.join(current, ".git");
+        if (await fs.pathExists(gitPath)) {
+            return {
+                detectedRoot: current,
+                usedFallback: false,
+            };
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return {
+                detectedRoot: path.resolve(cwd),
+                usedFallback: true,
+            };
+        }
+        current = parent;
+    }
+};

package/dist/core/scanner/scanMarkdown.d.ts

@@ -0,0 +1,2 @@
+import type { MarkdownFile } from "../../shared/types.js";
+export declare const scanMarkdown: (rootDir: string, scanDir?: string) => Promise<MarkdownFile[]>;

package/dist/core/scanner/scanMarkdown.js

@@ -0,0 +1,22 @@
+import path from "node:path";
+import fg from "fast-glob";
+export const scanMarkdown = async (rootDir, scanDir = rootDir) => {
+    const relativePrefix = path.relative(rootDir, scanDir);
+    const matches = await fg("**/*.md", {
+        cwd: scanDir,
+        onlyFiles: true,
+        dot: false,
+        ignore: ["node_modules/**", ".git/**", ".doc-repo/**", "dist/**"],
+    });
+    return matches
+        .sort((a, b) => a.localeCompare(b))
+        .map((matchedPath) => {
+        const relativePath = relativePrefix
+            ? path.posix.join(relativePrefix.split(path.sep).join(path.posix.sep), matchedPath)
+            : matchedPath;
+        return {
+            relativePath,
+            absolutePath: path.join(rootDir, relativePath),
+        };
+    });
+};

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

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

package/dist/core/site/atomicPublish.js

@@ -0,0 +1,21 @@
+import fs from "fs-extra";
+export const atomicPublish = async (stagingDir, outputDir) => {
+    const backupDir = `${outputDir}.__backup__`;
+    await fs.remove(backupDir);
+    try {
+        if (await fs.pathExists(outputDir)) {
+            await fs.move(outputDir, backupDir, { overwrite: true });
+        }
+        await fs.move(stagingDir, outputDir, { overwrite: true });
+        await fs.remove(backupDir);
+    }
+    catch (error) {
+        if (!(await fs.pathExists(outputDir)) && (await fs.pathExists(backupDir))) {
+            await fs.move(backupDir, outputDir, { overwrite: true });
+        }
+        if (await fs.pathExists(stagingDir)) {
+            await fs.remove(stagingDir);
+        }
+        throw error;
+    }
+};

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

@@ -0,0 +1,2 @@
+import type { MarkdownFile, SiteBundle } from "../../shared/types.js";
+export declare const buildSiteBundle: (files: MarkdownFile[]) => Promise<SiteBundle>;