marksites 0.1.0

package/dist/conversion/directory.js

@@ -0,0 +1,208 @@
+import { mkdir, readFile, rename, rm, stat } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, posix, relative, resolve, sep, } from "node:path";
+import { countActiveAnnotations } from "../annotations/model.js";
+import { readAnnotations, serializeAnnotations, } from "../annotations/storage.js";
+import { renderMarkdown } from "../markdown-to-html.js";
+import { atomicWriteFile } from "../utils/files.js";
+import { BUILD_MANIFEST, assertNoOutputCollisions, loadManifest, writeManifest, } from "./manifest.js";
+import { buildBreadcrumbs, buildFileTree } from "./navigation.js";
+import { DEFAULT_OUTPUT_DIRECTORY, findMarkdownFiles, firstExistingPath, pathExists, toLegacyMetadataPaths, } from "./paths.js";
+import { OUTPUT_COMPATIBILITY_VERSION, contentHash, renderFingerprint, rewriteMarkdownLinks, } from "./rendering.js";
+async function migrateLegacyMetadata(files, output) {
+    let moved = 0;
+    for (const file of files) {
+        const metadata = join(output, ...file.metadataPath.split("/"));
+        if (await pathExists(metadata))
+            continue;
+        const legacy = await firstExistingPath(toLegacyMetadataPaths(file.relativePath).map((path) => join(output, ...path.split("/"))));
+        if (!legacy)
+            continue;
+        await mkdir(dirname(metadata), { recursive: true });
+        await rename(legacy, metadata);
+        moved++;
+    }
+    return moved;
+}
+async function loadSources(files) {
+    for (const file of files) {
+        const [source, sourceStat] = await Promise.all([
+            readFile(file.sourcePath, "utf8"),
+            stat(file.sourcePath),
+        ]);
+        file.source = source;
+        file.sourceHash = contentHash(file.source);
+        file.modifiedAt = sourceStat.mtime.toISOString();
+    }
+}
+async function moveRenamedDocuments(files, previous, output, removed) {
+    let deleted = 0;
+    let metadataMoved = 0;
+    const added = files.filter((file) => !previous?.files[file.relativePath]);
+    for (const file of added) {
+        const matches = removed.filter((old) => previous?.files[old]?.sourceHash === file.sourceHash &&
+            added.filter((candidate) => candidate.sourceHash === file.sourceHash)
+                .length === 1);
+        if (matches.length !== 1)
+            continue;
+        const old = matches[0];
+        const oldData = previous.files[old];
+        const oldMetadata = join(output, ...oldData.annotations.split("/"));
+        const nextMetadata = join(output, ...file.metadataPath.split("/"));
+        if ((await pathExists(oldMetadata)) && oldMetadata !== nextMetadata) {
+            await mkdir(dirname(nextMetadata), { recursive: true });
+            const value = await readAnnotations(oldMetadata);
+            value.document = file.relativePath;
+            await atomicWriteFile(nextMetadata, serializeAnnotations(value));
+            await rm(oldMetadata);
+            metadataMoved++;
+        }
+        const oldHtml = join(output, ...oldData.output.split("/"));
+        if (await pathExists(oldHtml)) {
+            await rm(oldHtml);
+            deleted++;
+        }
+        warnAboutStaleLinks(files, old);
+        removed.splice(removed.indexOf(old), 1);
+    }
+    return { deleted, metadataMoved };
+}
+function warnAboutStaleLinks(files, oldPath) {
+    for (const file of files) {
+        const formerHref = posix.relative(posix.dirname(file.relativePath), oldPath);
+        if (file.source?.includes(formerHref)) {
+            console.warn(`Possible stale Markdown link in ${file.relativePath}: ${formerHref}`);
+        }
+    }
+}
+async function loadMetadata(files, output) {
+    let created = 0;
+    for (const file of files) {
+        const metadata = join(output, ...file.metadataPath.split("/"));
+        const existed = await pathExists(metadata);
+        file.annotations = await readAnnotations(metadata, file.relativePath);
+        if (!existed)
+            created++;
+        file.annotationHash = contentHash(serializeAnnotations(file.annotations));
+    }
+    return created;
+}
+async function removeDeletedHtml(removed, previous, output) {
+    let deleted = 0;
+    const orphaned = [];
+    for (const old of removed) {
+        const info = previous?.files[old];
+        if (!info)
+            continue;
+        const oldHtml = join(output, ...info.output.split("/"));
+        if (await pathExists(oldHtml)) {
+            await rm(oldHtml);
+            deleted++;
+        }
+        if (await pathExists(join(output, ...info.annotations.split("/")))) {
+            orphaned.push(info.annotations);
+        }
+    }
+    return { deleted, orphaned };
+}
+async function renderChangedFiles(files, input, output, previous, full) {
+    let converted = 0;
+    let skipped = 0;
+    const manifestFiles = {};
+    for (const file of files) {
+        const old = previous?.files[file.relativePath];
+        const destination = join(output, ...file.outputPath.split("/"));
+        const changed = full ||
+            !old ||
+            old.sourceHash !== file.sourceHash ||
+            old.modifiedAt !== file.modifiedAt ||
+            old.annotationHash !== file.annotationHash ||
+            !(await pathExists(destination));
+        if (changed) {
+            await atomicWriteFile(destination, renderMarkdown(file.source, {
+                title: basename(file.relativePath, extname(file.relativePath)),
+                modifiedAt: file.modifiedAt,
+                fileTree: {
+                    title: "ファイル",
+                    items: buildFileTree(files, file.outputPath),
+                    breadcrumbs: buildBreadcrumbs(files, file),
+                },
+                markedOptions: { walkTokens: rewriteMarkdownLinks },
+            }, file.annotations));
+            converted++;
+        }
+        else {
+            skipped++;
+        }
+        manifestFiles[file.relativePath] = {
+            sourceHash: file.sourceHash,
+            modifiedAt: file.modifiedAt,
+            annotationHash: file.annotationHash,
+            output: file.outputPath,
+            annotations: file.metadataPath,
+        };
+    }
+    return { converted, skipped, files: manifestFiles };
+}
+export async function convertDirectoryDetailed(input, outputArgument) {
+    const output = outputArgument
+        ? resolve(outputArgument)
+        : resolve(DEFAULT_OUTPUT_DIRECTORY);
+    const outputRelative = relative(input, output);
+    const outputInsideInput = outputRelative !== "" &&
+        !outputRelative.startsWith(`..${sep}`) &&
+        outputRelative !== ".." &&
+        !isAbsolute(outputRelative);
+    const files = await findMarkdownFiles(input, outputInsideInput ? output : undefined);
+    if (files.length === 0)
+        throw new Error(`No Markdown files found in: ${input}`);
+    assertNoOutputCollisions(files);
+    await mkdir(output, { recursive: true });
+    const manifestPath = join(output, BUILD_MANIFEST);
+    const loaded = await loadManifest(manifestPath);
+    if (loaded.warning)
+        console.warn(loaded.warning);
+    const previous = loaded.manifest;
+    await loadSources(files);
+    let annotationsMoved = await migrateLegacyMetadata(files, output);
+    const currentPaths = new Set(files.map((file) => file.relativePath));
+    const removed = Object.keys(previous?.files ?? {}).filter((path) => !currentPaths.has(path));
+    const renamed = await moveRenamedDocuments(files, previous, output, removed);
+    annotationsMoved += renamed.metadataMoved;
+    const annotationsCreated = await loadMetadata(files, output);
+    const treeHash = contentHash(files
+        .map((file) => `${file.relativePath}\0${file.annotations ? countActiveAnnotations(file.annotations) : 0}`)
+        .sort()
+        .join("\n"));
+    const fingerprint = renderFingerprint();
+    const full = !previous ||
+        loaded.warning !== undefined ||
+        previous.generator.outputCompatibilityVersion !==
+            OUTPUT_COMPATIBILITY_VERSION ||
+        previous.generator.renderFingerprint !== fingerprint ||
+        previous.treeHash !== treeHash;
+    const removedResult = await removeDeletedHtml(removed, previous, output);
+    const rendered = await renderChangedFiles(files, input, output, previous, full);
+    await writeManifest(manifestPath, {
+        schemaVersion: 1,
+        generator: {
+            name: "marksites",
+            version: "0.1.0",
+            outputCompatibilityVersion: OUTPUT_COMPATIBILITY_VERSION,
+            renderFingerprint: fingerprint,
+        },
+        treeHash,
+        files: rendered.files,
+    });
+    return {
+        converted: rendered.converted,
+        skipped: rendered.skipped,
+        deleted: renamed.deleted + removedResult.deleted,
+        annotationsCreated,
+        annotationsMoved,
+        orphanedAnnotations: removedResult.orphaned,
+        outputRoot: output,
+    };
+}
+export async function convertDirectory(input, outputArgument) {
+    return (await convertDirectoryDetailed(input, outputArgument)).converted;
+}

package/dist/conversion/gitignore.d.ts

@@ -0,0 +1,8 @@
+import createIgnore from "ignore";
+interface GitignoreRules {
+    basePath: string;
+    matcher: ReturnType<typeof createIgnore>;
+}
+export declare function loadGitignoreRules(root: string, directory: string, inherited: GitignoreRules[]): Promise<GitignoreRules[]>;
+export declare function isGitignored(relativePath: string, directory: boolean, rules: GitignoreRules[]): boolean;
+export {};

package/dist/conversion/gitignore.js

@@ -0,0 +1,43 @@
+import { readFile } from "node:fs/promises";
+import { join, posix, relative } from "node:path";
+import createIgnore from "ignore";
+export async function loadGitignoreRules(root, directory, inherited) {
+    let source;
+    try {
+        source = await readFile(join(directory, ".gitignore"), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return inherited;
+        throw error;
+    }
+    const basePath = relative(root, directory).split("\\").join(posix.sep);
+    return [
+        ...inherited,
+        {
+            basePath: basePath || ".",
+            matcher: createIgnore().add(source),
+        },
+    ];
+}
+export function isGitignored(relativePath, directory, rules) {
+    let ignored = false;
+    for (const ruleSet of rules) {
+        const scoped = scopePath(relativePath, ruleSet.basePath);
+        if (!scoped)
+            continue;
+        const result = ruleSet.matcher.test(directory ? `${scoped}/` : scoped);
+        if (result.ignored)
+            ignored = true;
+        if (result.unignored)
+            ignored = false;
+    }
+    return ignored;
+}
+function scopePath(relativePath, basePath) {
+    if (basePath === ".")
+        return relativePath;
+    if (!relativePath.startsWith(`${basePath}/`))
+        return undefined;
+    return relativePath.slice(basePath.length + 1);
+}

package/dist/conversion/manifest.d.ts

@@ -0,0 +1,8 @@
+import type { BuildManifest, MarkdownFile } from "./types.js";
+export declare const BUILD_MANIFEST = ".marksites-build.json";
+export declare function assertNoOutputCollisions(files: MarkdownFile[]): void;
+export declare function loadManifest(path: string): Promise<{
+    manifest?: BuildManifest;
+    warning?: string;
+}>;
+export declare function writeManifest(path: string, manifest: BuildManifest): Promise<void>;

package/dist/conversion/manifest.js

@@ -0,0 +1,40 @@
+import { readFile } from "node:fs/promises";
+import { atomicWriteFile } from "../utils/files.js";
+export const BUILD_MANIFEST = ".marksites-build.json";
+export function assertNoOutputCollisions(files) {
+    const paths = new Map();
+    for (const file of files) {
+        for (const output of [file.outputPath, file.metadataPath]) {
+            const key = output.toLowerCase();
+            if (paths.has(key))
+                throw new Error(`Multiple Markdown files map to: ${output}`);
+            paths.set(key, file.relativePath);
+        }
+        if (file.outputPath === BUILD_MANIFEST ||
+            file.metadataPath === BUILD_MANIFEST) {
+            throw new Error(`Output path is reserved: ${BUILD_MANIFEST}`);
+        }
+    }
+}
+export async function loadManifest(path) {
+    try {
+        const value = JSON.parse(await readFile(path, "utf8"));
+        if (value.schemaVersion !== 1 ||
+            !value.generator ||
+            typeof value.treeHash !== "string" ||
+            typeof value.files !== "object") {
+            throw new Error("unsupported schema");
+        }
+        return { manifest: value };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return {};
+        return {
+            warning: `Ignoring invalid build manifest ${path}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+export async function writeManifest(path, manifest) {
+    await atomicWriteFile(path, `${JSON.stringify(manifest, null, 2)}\n`);
+}

package/dist/conversion/navigation.d.ts

@@ -0,0 +1,4 @@
+import type { FileBreadcrumb, FileTreeNode } from "../types.js";
+import type { MarkdownFile } from "./types.js";
+export declare function buildFileTree(files: MarkdownFile[], currentOutputPath: string): FileTreeNode[];
+export declare function buildBreadcrumbs(files: MarkdownFile[], current: MarkdownFile): FileBreadcrumb[];

package/dist/conversion/navigation.js

@@ -0,0 +1,70 @@
+import { basename, posix } from "node:path";
+import { countActiveAnnotations } from "../annotations/model.js";
+function encodeRelativeHref(path) {
+    return path.split(posix.sep).map(encodeURIComponent).join("/");
+}
+export function buildFileTree(files, currentOutputPath) {
+    const root = { directories: new Map(), files: [] };
+    for (const file of files) {
+        const parts = file.relativePath.split("/");
+        parts.pop();
+        let directory = root;
+        for (const part of parts) {
+            let child = directory.directories.get(part);
+            if (!child) {
+                child = { directories: new Map(), files: [] };
+                directory.directories.set(part, child);
+            }
+            directory = child;
+        }
+        directory.files.push(file);
+    }
+    function render(directory) {
+        return [
+            ...[...directory.directories]
+                .sort(([left], [right]) => left.localeCompare(right, "en"))
+                .map(([name, child]) => ({
+                type: "directory",
+                name,
+                children: render(child),
+            })),
+            ...[...directory.files]
+                .sort((left, right) => basename(left.relativePath).localeCompare(basename(right.relativePath), "en"))
+                .map((file) => ({
+                type: "file",
+                name: basename(file.relativePath),
+                href: encodeRelativeHref(posix.relative(posix.dirname(currentOutputPath), file.outputPath) ||
+                    posix.basename(file.outputPath)),
+                current: file.outputPath === currentOutputPath,
+                commentCount: file.annotations
+                    ? countActiveAnnotations(file.annotations)
+                    : 0,
+            })),
+        ];
+    }
+    return render(root);
+}
+function hrefBetween(current, target) {
+    return encodeRelativeHref(posix.relative(posix.dirname(current), target) || posix.basename(target));
+}
+export function buildBreadcrumbs(files, current) {
+    const findIndex = (directory) => files.find((file) => posix.dirname(file.relativePath) === directory &&
+        ["index.md", "index.markdown"].includes(posix.basename(file.relativePath).toLowerCase()));
+    const result = [];
+    const parts = current.relativePath.split("/");
+    const fileName = parts.pop();
+    let directory = "";
+    for (const part of parts) {
+        directory = directory ? `${directory}/${part}` : part;
+        const index = findIndex(directory);
+        result.push({
+            name: part,
+            href: index
+                ? hrefBetween(current.outputPath, index.outputPath)
+                : undefined,
+        });
+    }
+    if (fileName)
+        result.push({ name: fileName, current: true });
+    return result;
+}

package/dist/conversion/paths.d.ts

@@ -0,0 +1,10 @@
+import type { MarkdownFile } from "./types.js";
+export declare const DEFAULT_OUTPUT_DIRECTORY = "marksites";
+export declare function isMarkdown(path: string): boolean;
+export declare function toHtmlPath(path: string): string;
+export declare function toMetadataPath(path: string): string;
+export declare function toLegacyMetadataPaths(path: string): string[];
+export declare function toPosix(path: string): string;
+export declare function pathExists(path: string): Promise<boolean>;
+export declare function firstExistingPath(paths: string[]): Promise<string | undefined>;
+export declare function findMarkdownFiles(root: string, excludedDirectory?: string): Promise<MarkdownFile[]>;

package/dist/conversion/paths.js

@@ -0,0 +1,86 @@
+import { access, readdir } from "node:fs/promises";
+import { join, posix, relative, resolve, sep } from "node:path";
+import { isGitignored, loadGitignoreRules } from "./gitignore.js";
+import { BUILD_MANIFEST } from "./manifest.js";
+const EXCLUDED_DIRECTORY_NAMES = new Set([
+    ".git",
+    "coverage",
+    "dist",
+    "node_modules",
+]);
+export const DEFAULT_OUTPUT_DIRECTORY = "marksites";
+export function isMarkdown(path) {
+    return /\.(md|markdown)$/i.test(path);
+}
+export function toHtmlPath(path) {
+    return path.replace(/\.(md|markdown)$/i, ".html");
+}
+export function toMetadataPath(path) {
+    const htmlPath = toHtmlPath(path);
+    return posix.join(posix.dirname(htmlPath), `.${posix.basename(htmlPath, posix.extname(htmlPath))}.json`);
+}
+export function toLegacyMetadataPaths(path) {
+    const htmlPath = toHtmlPath(path);
+    const directory = posix.dirname(htmlPath);
+    const name = posix.basename(htmlPath, posix.extname(htmlPath));
+    return [
+        posix.join(directory, `.${name}.marksites.json`),
+        posix.join(directory, `${name}.annotations.json`),
+    ];
+}
+export function toPosix(path) {
+    return path.split(sep).join(posix.sep);
+}
+export async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function firstExistingPath(paths) {
+    for (const path of paths)
+        if (await pathExists(path))
+            return path;
+    return undefined;
+}
+export async function findMarkdownFiles(root, excludedDirectory) {
+    const files = [];
+    async function visit(directory, inheritedRules) {
+        if (directory !== root &&
+            (await pathExists(join(directory, BUILD_MANIFEST)))) {
+            return;
+        }
+        const rules = await loadGitignoreRules(root, directory, inheritedRules);
+        const entries = await readdir(directory, { withFileTypes: true });
+        entries.sort((left, right) => left.isDirectory() !== right.isDirectory()
+            ? left.isDirectory()
+                ? -1
+                : 1
+            : left.name.localeCompare(right.name, "en"));
+        for (const entry of entries) {
+            const absolute = join(directory, entry.name);
+            const relativePath = toPosix(relative(root, absolute));
+            if (isGitignored(relativePath, entry.isDirectory(), rules))
+                continue;
+            if (entry.isDirectory()) {
+                if (resolve(absolute) !== excludedDirectory &&
+                    !EXCLUDED_DIRECTORY_NAMES.has(entry.name)) {
+                    await visit(absolute, rules);
+                }
+            }
+            else if (entry.isFile() && isMarkdown(entry.name)) {
+                files.push({
+                    sourcePath: absolute,
+                    relativePath,
+                    outputPath: toHtmlPath(relativePath),
+                    metadataPath: toMetadataPath(relativePath),
+                });
+            }
+        }
+    }
+    await visit(root, []);
+    return files;
+}

package/dist/conversion/rendering.d.ts

@@ -0,0 +1,5 @@
+import type { Token } from "marked";
+export declare const OUTPUT_COMPATIBILITY_VERSION = 5;
+export declare function contentHash(value: string | Buffer): string;
+export declare function rewriteMarkdownLinks(token: Token): void;
+export declare function renderFingerprint(): string;

package/dist/conversion/rendering.js

@@ -0,0 +1,39 @@
+import { createHash } from "node:crypto";
+import { emptyAnnotationDocument } from "../annotations/model.js";
+import { renderMarkdown } from "../markdown-to-html.js";
+export const OUTPUT_COMPATIBILITY_VERSION = 5;
+export function contentHash(value) {
+    return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+function rewriteMarkdownHref(href) {
+    if (/^[a-z][a-z\d+.-]*:/i.test(href) ||
+        href.startsWith("//") ||
+        href.startsWith("/")) {
+        return href;
+    }
+    return href.replace(/\.(md|markdown)(?=([?#]|$))/i, ".html");
+}
+export function rewriteMarkdownLinks(token) {
+    if (token.type === "link")
+        token.href = rewriteMarkdownHref(token.href);
+}
+export function renderFingerprint() {
+    const representativeHtml = renderMarkdown("## Heading\n\n[Document](guide.md)\n\n```js\nconst value = 1;\n```\n", {
+        title: "marksites-render-fingerprint",
+        modifiedAt: "2026-01-01T00:00:00.000Z",
+        fileTree: {
+            title: "ファイル",
+            items: [
+                {
+                    type: "file",
+                    name: "index.md",
+                    href: "index.html",
+                    current: true,
+                },
+            ],
+            breadcrumbs: [{ name: "docs" }, { name: "index.md", current: true }],
+        },
+        markedOptions: { walkTokens: rewriteMarkdownLinks },
+    }, emptyAnnotationDocument("index.md"));
+    return contentHash(`${OUTPUT_COMPATIBILITY_VERSION}\n${representativeHtml}`);
+}

package/dist/conversion/single-file.d.ts

@@ -0,0 +1 @@
+export declare function convertFile(input: string, outputArgument?: string): Promise<string>;

package/dist/conversion/single-file.js

@@ -0,0 +1,35 @@
+import { mkdir, readFile, rename, stat } from "node:fs/promises";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { readAnnotations } from "../annotations/storage.js";
+import { renderMarkdown } from "../markdown-to-html.js";
+import { atomicWriteFile } from "../utils/files.js";
+import { DEFAULT_OUTPUT_DIRECTORY, firstExistingPath, isMarkdown, pathExists, } from "./paths.js";
+export async function convertFile(input, outputArgument) {
+    if (!isMarkdown(input))
+        throw new Error(`Input file must use .md or .markdown: ${input}`);
+    const output = outputArgument
+        ? resolve(outputArgument)
+        : resolve(DEFAULT_OUTPUT_DIRECTORY, `${basename(input, extname(input))}.html`);
+    const outputName = basename(output, extname(output));
+    const metadataPath = join(dirname(output), `.${outputName}.json`);
+    const legacyPaths = [
+        join(dirname(output), `.${outputName}.marksites.json`),
+        join(dirname(output), `${outputName}.annotations.json`),
+    ];
+    if (!(await pathExists(metadataPath))) {
+        const legacy = await firstExistingPath(legacyPaths);
+        if (legacy)
+            await rename(legacy, metadataPath);
+    }
+    const annotations = await readAnnotations(metadataPath, basename(input));
+    const [markdown, sourceStat] = await Promise.all([
+        readFile(input, "utf8"),
+        stat(input),
+    ]);
+    await mkdir(dirname(output), { recursive: true });
+    await atomicWriteFile(output, renderMarkdown(markdown, {
+        title: basename(input, extname(input)),
+        modifiedAt: sourceStat.mtime.toISOString(),
+    }, annotations));
+    return output;
+}

package/dist/conversion/types.d.ts

@@ -0,0 +1,39 @@
+import type { AnnotationDocument } from "../annotations/model.js";
+export interface MarkdownFile {
+    sourcePath: string;
+    relativePath: string;
+    outputPath: string;
+    metadataPath: string;
+    source?: string;
+    sourceHash?: string;
+    modifiedAt?: string;
+    annotations?: AnnotationDocument;
+    annotationHash?: string;
+}
+export interface ManifestFile {
+    sourceHash: string;
+    modifiedAt: string;
+    annotationHash: string;
+    output: string;
+    annotations: string;
+}
+export interface BuildManifest {
+    schemaVersion: 1;
+    generator: {
+        name: "marksites";
+        version: string;
+        outputCompatibilityVersion: number;
+        renderFingerprint: string;
+    };
+    treeHash: string;
+    files: Record<string, ManifestFile>;
+}
+export interface ConversionResult {
+    converted: number;
+    skipped: number;
+    deleted: number;
+    annotationsCreated: number;
+    annotationsMoved: number;
+    orphanedAnnotations: string[];
+    outputRoot: string;
+}

package/dist/conversion/types.js

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

package/dist/features/annotations/index.d.ts

@@ -0,0 +1,7 @@
+import { type AnnotationDocument } from "../../annotations/model.js";
+import type { DocumentFeature } from "../types.js";
+export interface AnnotationsFeature extends DocumentFeature {
+    panel: string;
+    count: number;
+}
+export declare function createAnnotationsFeature(data?: AnnotationDocument): AnnotationsFeature;