@contractspec/tool.docs-generator 0.0.0-canary-20260128200020

package/README.md

@@ -0,0 +1,95 @@
+# ContractSpec Docs Generator
+
+CLI tool for generating documentation artifacts from ContractSpec specs and DocBlocks.
+
+## Usage
+
+```bash
+bunx contractspec-docs generate
+```
+
+From the monorepo root:
+
+```bash
+bun docs:generate
+```
+
+## Options
+
+- `--source <dir>`: Source directory for generated markdown (default: `generated/docs`).
+- `--out <dir>`: Output directory for generated artifacts (default: `packages/bundles/library/src/components/docs/generated`).
+- `--content-root <dir>`: Root directory for docs content (default: `--source`).
+- `--route-prefix <prefix>`: Route prefix for generated reference pages (default: `/docs/reference`).
+- `--version <version>`: Output version subdirectory (e.g., `v1.0.0`).
+- `--no-docblocks`: Skip DocBlocks from the docs registry.
+
+## Output
+
+The generator writes a typed index manifest plus markdown content.
+
+Note: the `docblocks/` folder under the content root is ignored when scanning
+source markdown to avoid re-indexing DocBlocks on subsequent runs.
+
+Content is stored under `--content-root` (defaults to `--source`). If
+`--version` is provided, both the index and content are nested under that
+version subdirectory.
+
+If `--version` is provided:
+
+```
+<outDir>/<version>/docs-index.generated.ts
+<outDir>/<version>/docs-index.manifest.json
+<outDir>/<version>/docs-index.*.json
+<contentRoot>/<version>/**/*.md
+```
+
+Without `--version`:
+
+```
+<outDir>/docs-index.generated.ts
+<outDir>/docs-index.manifest.json
+<outDir>/docs-index.*.json
+<contentRoot>/**/*.md
+```
+
+The index contains `docsIndex` entries and `docsIndexMeta`:
+
+```ts
+export type DocsIndexEntry = {
+  id: string;
+  title: string;
+  summary?: string;
+  route?: string;
+  source: "generated" | "docblock";
+  contentPath?: string;
+  tags?: string[];
+  kind?: string;
+  visibility?: string;
+  version?: string;
+  owners?: string[];
+};
+
+export type DocsIndexManifest = {
+  generatedAt: string;
+  total: number;
+  version: string | null;
+  contentRoot: string | null;
+  chunks: { key: string; file: string; total: number }[];
+};
+
+export const DOCS_INDEX_MANIFEST = "docs-index.manifest.json";
+```
+
+## Examples
+
+```bash
+bunx contractspec-docs generate \
+  --source generated/docs \
+  --out packages/bundles/library/src/components/docs/generated \
+  --route-prefix /docs/reference \
+  --version v1.0.0
+```
+
+```bash
+bunx contractspec-docs generate --no-docblocks
+```

package/dist/fs.mjs

@@ -0,0 +1,36 @@
+import { dirname, extname, join } from "node:path";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+
+//#region src/fs.ts
+async function ensureDir(path) {
+	await mkdir(path, { recursive: true });
+}
+async function readText(path) {
+	return readFile(path, "utf8");
+}
+async function writeText(path, content) {
+	await ensureDir(dirname(path));
+	await writeFile(path, content, "utf8");
+}
+async function listMarkdownFiles(rootDir, options) {
+	const files = [];
+	const exclude = new Set(options?.excludeDirs ?? []);
+	async function walk(current) {
+		const entries = await readdir(current, { withFileTypes: true });
+		for (const entry of entries) {
+			const fullPath = join(current, entry.name);
+			if (entry.isDirectory()) {
+				if (exclude.has(entry.name)) continue;
+				await walk(fullPath);
+				continue;
+			}
+			if (entry.isFile() && extname(entry.name) === ".md") files.push(fullPath);
+		}
+	}
+	await walk(rootDir);
+	return files;
+}
+
+//#endregion
+export { ensureDir, listMarkdownFiles, readText, writeText };
+//# sourceMappingURL=fs.mjs.map

package/dist/fs.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.mjs","names":[],"sources":["../src/fs.ts"],"sourcesContent":["import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';\nimport { dirname, extname, join } from 'node:path';\n\nexport async function ensureDir(path: string): Promise<void> {\n  await mkdir(path, { recursive: true });\n}\n\nexport async function readText(path: string): Promise<string> {\n  return readFile(path, 'utf8');\n}\n\nexport async function writeText(path: string, content: string): Promise<void> {\n  await ensureDir(dirname(path));\n  await writeFile(path, content, 'utf8');\n}\n\nexport async function copyTextFile(\n  sourcePath: string,\n  destPath: string\n): Promise<void> {\n  const content = await readText(sourcePath);\n  await writeText(destPath, content);\n}\n\nexport async function listMarkdownFiles(\n  rootDir: string,\n  options?: { excludeDirs?: string[] }\n): Promise<string[]> {\n  const files: string[] = [];\n  const exclude = new Set(options?.excludeDirs ?? []);\n\n  async function walk(current: string): Promise<void> {\n    const entries = await readdir(current, { withFileTypes: true });\n\n    for (const entry of entries) {\n      const fullPath = join(current, entry.name);\n      if (entry.isDirectory()) {\n        if (exclude.has(entry.name)) {\n          continue;\n        }\n        await walk(fullPath);\n        continue;\n      }\n      if (entry.isFile() && extname(entry.name) === '.md') {\n        files.push(fullPath);\n      }\n    }\n  }\n\n  await walk(rootDir);\n  return files;\n}\n"],"mappings":";;;;AAGA,eAAsB,UAAU,MAA6B;AAC3D,OAAM,MAAM,MAAM,EAAE,WAAW,MAAM,CAAC;;AAGxC,eAAsB,SAAS,MAA+B;AAC5D,QAAO,SAAS,MAAM,OAAO;;AAG/B,eAAsB,UAAU,MAAc,SAAgC;AAC5E,OAAM,UAAU,QAAQ,KAAK,CAAC;AAC9B,OAAM,UAAU,MAAM,SAAS,OAAO;;AAWxC,eAAsB,kBACpB,SACA,SACmB;CACnB,MAAM,QAAkB,EAAE;CAC1B,MAAM,UAAU,IAAI,IAAI,SAAS,eAAe,EAAE,CAAC;CAEnD,eAAe,KAAK,SAAgC;EAClD,MAAM,UAAU,MAAM,QAAQ,SAAS,EAAE,eAAe,MAAM,CAAC;AAE/D,OAAK,MAAM,SAAS,SAAS;GAC3B,MAAM,WAAW,KAAK,SAAS,MAAM,KAAK;AAC1C,OAAI,MAAM,aAAa,EAAE;AACvB,QAAI,QAAQ,IAAI,MAAM,KAAK,CACzB;AAEF,UAAM,KAAK,SAAS;AACpB;;AAEF,OAAI,MAAM,QAAQ,IAAI,QAAQ,MAAM,KAAK,KAAK,MAC5C,OAAM,KAAK,SAAS;;;AAK1B,OAAM,KAAK,QAAQ;AACnB,QAAO"}

package/dist/generate.mjs

@@ -0,0 +1,163 @@
+import { ensureDir, listMarkdownFiles, readText, writeText } from "./fs.mjs";
+import { extractSummary, extractTitle } from "./markdown.mjs";
+import { defaultDocRegistry } from "@contractspec/lib.contracts/docs";
+import { join, relative, resolve, sep } from "node:path";
+
+//#region src/generate.ts
+function normalizeId(pathValue) {
+	return pathValue.split(sep).join("/").replace(/\.md$/, "");
+}
+function buildGeneratedRoute(routePrefix, id) {
+	return `${routePrefix.endsWith("/") ? routePrefix.slice(0, -1) : routePrefix}/${id}`;
+}
+function buildIndexTypesFile() {
+	return [
+		"export type DocsIndexSource = 'generated' | 'docblock';",
+		"",
+		"export type DocsIndexEntry = {",
+		"  id: string;",
+		"  title: string;",
+		"  summary?: string;",
+		"  route?: string;",
+		"  source: DocsIndexSource;",
+		"  contentPath?: string;",
+		"  tags?: string[];",
+		"  kind?: string;",
+		"  visibility?: string;",
+		"  version?: string;",
+		"  owners?: string[];",
+		"};",
+		"",
+		"export type DocsIndexChunk = {",
+		"  key: string;",
+		"  file: string;",
+		"  total: number;",
+		"};",
+		"",
+		"export type DocsIndexManifest = {",
+		"  generatedAt: string;",
+		"  total: number;",
+		"  version: string | null;",
+		"  contentRoot: string | null;",
+		"  chunks: DocsIndexChunk[];",
+		"};",
+		"",
+		"export const DOCS_INDEX_MANIFEST = \"docs-index.manifest.json\";",
+		""
+	].join("\n");
+}
+function chunkKeyForId(id) {
+	if (!id) return "_common";
+	if (id.includes("/")) {
+		const [prefix] = id.split("/");
+		return prefix || "_common";
+	}
+	return "_common";
+}
+function buildChunkFileName(key, usedNames) {
+	const baseName = `docs-index.${key.replace(/[^a-zA-Z0-9-_]/g, "-") || "common"}.json`;
+	const count = usedNames.get(baseName) ?? 0;
+	const fileName = count === 0 ? baseName : baseName.replace(/\.json$/, `-${count}.json`);
+	usedNames.set(baseName, count + 1);
+	return fileName;
+}
+async function generateDocs(options) {
+	const outputDir = options.version ? join(options.outDir, options.version) : options.outDir;
+	const contentRootBase = options.contentRoot ?? options.sourceDir;
+	const contentRoot = options.version ? join(contentRootBase, options.version) : contentRootBase;
+	const resolvedOutputDir = resolve(outputDir);
+	const resolvedSourceDir = resolve(options.sourceDir);
+	const resolvedContentRoot = resolve(contentRoot);
+	const shouldCopyContent = resolvedContentRoot !== resolvedSourceDir;
+	const contentRootRelative = relative(resolvedOutputDir, resolvedContentRoot) || ".";
+	await ensureDir(outputDir);
+	if (shouldCopyContent) await ensureDir(contentRoot);
+	const markdownFiles = await listMarkdownFiles(options.sourceDir, { excludeDirs: ["docblocks"] });
+	const entries = [];
+	for (const filePath of markdownFiles) {
+		const relativePath = normalizeId(relative(options.sourceDir, filePath));
+		const contentPath = `${relativePath}.md`;
+		const targetPath = join(contentRoot, contentPath);
+		const content = await readText(filePath);
+		const title = extractTitle(content, relativePath);
+		const summary = extractSummary(content);
+		const route = buildGeneratedRoute(options.routePrefix, relativePath);
+		if (shouldCopyContent) await writeText(targetPath, content);
+		entries.push({
+			id: relativePath,
+			title,
+			summary,
+			route,
+			source: "generated",
+			contentPath
+		});
+	}
+	let docblockCount = 0;
+	if (options.includeDocblocks) {
+		const routes = defaultDocRegistry.list();
+		for (const entry of routes) {
+			if (!entry?.block) continue;
+			const { block, route } = entry;
+			if (!block.id) continue;
+			const docPath = `docblocks/${block.id.replace(/\./g, "/")}.md`;
+			await writeText(join(contentRoot, docPath), String(block.body ?? ""));
+			entries.push({
+				id: block.id,
+				title: block.title,
+				summary: block.summary,
+				route,
+				source: "docblock",
+				contentPath: docPath,
+				tags: block.tags,
+				kind: block.kind,
+				visibility: block.visibility,
+				version: block.version,
+				owners: block.owners
+			});
+			docblockCount += 1;
+		}
+	}
+	const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const chunkMap = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		const key = chunkKeyForId(entry.id);
+		const bucket = chunkMap.get(key) ?? [];
+		bucket.push(entry);
+		chunkMap.set(key, bucket);
+	}
+	const usedNames = /* @__PURE__ */ new Map();
+	const chunks = [];
+	for (const [key, chunkEntries] of chunkMap) {
+		chunkEntries.sort((a, b) => a.id.localeCompare(b.id));
+		const file = buildChunkFileName(key, usedNames);
+		await writeText(join(outputDir, file), JSON.stringify(chunkEntries, null, 2));
+		chunks.push({
+			key,
+			file,
+			total: chunkEntries.length
+		});
+	}
+	chunks.sort((a, b) => a.key.localeCompare(b.key));
+	const manifest = {
+		generatedAt,
+		total: entries.length,
+		version: options.version ?? null,
+		contentRoot: contentRootRelative || null,
+		chunks
+	};
+	await writeText(join(outputDir, "docs-index.manifest.json"), JSON.stringify(manifest, null, 2));
+	const indexTypes = buildIndexTypesFile();
+	await writeText(join(outputDir, "docs-index.generated.ts"), indexTypes);
+	return {
+		total: entries.length,
+		generated: markdownFiles.length,
+		docblocks: docblockCount,
+		outputDir,
+		contentRoot,
+		version: options.version
+	};
+}
+
+//#endregion
+export { generateDocs };
+//# sourceMappingURL=generate.mjs.map

package/dist/generate.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.mjs","names":[],"sources":["../src/generate.ts"],"sourcesContent":["import { defaultDocRegistry } from '@contractspec/lib.contracts/docs';\nimport { join, relative, resolve, sep } from 'node:path';\nimport { ensureDir, listMarkdownFiles, readText, writeText } from './fs';\nimport { extractSummary, extractTitle } from './markdown';\nimport type { DocsIndexEntry, GenerateOptions, GenerateResult } from './types';\n\nfunction normalizeId(pathValue: string): string {\n  return pathValue.split(sep).join('/').replace(/\\.md$/, '');\n}\n\nfunction buildGeneratedRoute(routePrefix: string, id: string): string {\n  const cleanPrefix = routePrefix.endsWith('/')\n    ? routePrefix.slice(0, -1)\n    : routePrefix;\n  return `${cleanPrefix}/${id}`;\n}\n\ninterface DocsIndexChunk {\n  key: string;\n  file: string;\n  total: number;\n}\n\ninterface DocsIndexManifest {\n  generatedAt: string;\n  total: number;\n  version: string | null;\n  contentRoot: string | null;\n  chunks: DocsIndexChunk[];\n}\n\nfunction buildIndexTypesFile(): string {\n  return [\n    \"export type DocsIndexSource = 'generated' | 'docblock';\",\n    '',\n    'export type DocsIndexEntry = {',\n    '  id: string;',\n    '  title: string;',\n    '  summary?: string;',\n    '  route?: string;',\n    '  source: DocsIndexSource;',\n    '  contentPath?: string;',\n    '  tags?: string[];',\n    '  kind?: string;',\n    '  visibility?: string;',\n    '  version?: string;',\n    '  owners?: string[];',\n    '};',\n    '',\n    'export type DocsIndexChunk = {',\n    '  key: string;',\n    '  file: string;',\n    '  total: number;',\n    '};',\n    '',\n    'export type DocsIndexManifest = {',\n    '  generatedAt: string;',\n    '  total: number;',\n    '  version: string | null;',\n    '  contentRoot: string | null;',\n    '  chunks: DocsIndexChunk[];',\n    '};',\n    '',\n    'export const DOCS_INDEX_MANIFEST = \"docs-index.manifest.json\";',\n    '',\n  ].join('\\n');\n}\n\nfunction chunkKeyForId(id: string): string {\n  if (!id) return '_common';\n  if (id.includes('/')) {\n    const [prefix] = id.split('/');\n    return prefix || '_common';\n  }\n  return '_common';\n}\n\nfunction buildChunkFileName(\n  key: string,\n  usedNames: Map<string, number>\n): string {\n  const safeKey = key.replace(/[^a-zA-Z0-9-_]/g, '-');\n  const baseName = `docs-index.${safeKey || 'common'}.json`;\n  const count = usedNames.get(baseName) ?? 0;\n  const fileName =\n    count === 0 ? baseName : baseName.replace(/\\.json$/, `-${count}.json`);\n  usedNames.set(baseName, count + 1);\n  return fileName;\n}\n\nexport async function generateDocs(\n  options: GenerateOptions\n): Promise<GenerateResult> {\n  const outputDir = options.version\n    ? join(options.outDir, options.version)\n    : options.outDir;\n  const contentRootBase = options.contentRoot ?? options.sourceDir;\n  const contentRoot = options.version\n    ? join(contentRootBase, options.version)\n    : contentRootBase;\n  const resolvedOutputDir = resolve(outputDir);\n  const resolvedSourceDir = resolve(options.sourceDir);\n  const resolvedContentRoot = resolve(contentRoot);\n  const shouldCopyContent = resolvedContentRoot !== resolvedSourceDir;\n  const contentRootRelative =\n    relative(resolvedOutputDir, resolvedContentRoot) || '.';\n  await ensureDir(outputDir);\n  if (shouldCopyContent) {\n    await ensureDir(contentRoot);\n  }\n\n  const markdownFiles = await listMarkdownFiles(options.sourceDir, {\n    excludeDirs: ['docblocks'],\n  });\n  const entries: DocsIndexEntry[] = [];\n\n  for (const filePath of markdownFiles) {\n    const relativePath = normalizeId(relative(options.sourceDir, filePath));\n    const contentPath = `${relativePath}.md`;\n    const targetPath = join(contentRoot, contentPath);\n\n    const content = await readText(filePath);\n    const title = extractTitle(content, relativePath);\n    const summary = extractSummary(content);\n    const route = buildGeneratedRoute(options.routePrefix, relativePath);\n\n    if (shouldCopyContent) {\n      await writeText(targetPath, content);\n    }\n\n    entries.push({\n      id: relativePath,\n      title,\n      summary,\n      route,\n      source: 'generated',\n      contentPath,\n    });\n  }\n\n  let docblockCount = 0;\n  if (options.includeDocblocks) {\n    const routes = defaultDocRegistry.list();\n\n    for (const entry of routes) {\n      if (!entry?.block) {\n        continue;\n      }\n      const { block, route } = entry;\n      if (!block.id) {\n        continue;\n      }\n\n      const docPath = `docblocks/${block.id.replace(/\\./g, '/')}.md`;\n      const targetPath = join(contentRoot, docPath);\n      await writeText(targetPath, String(block.body ?? ''));\n\n      entries.push({\n        id: block.id,\n        title: block.title,\n        summary: block.summary,\n        route,\n        source: 'docblock',\n        contentPath: docPath,\n        tags: block.tags,\n        kind: block.kind,\n        visibility: block.visibility,\n        version: block.version,\n        owners: block.owners,\n      });\n      docblockCount += 1;\n    }\n  }\n\n  const generatedAt = new Date().toISOString();\n  const chunkMap = new Map<string, DocsIndexEntry[]>();\n  for (const entry of entries) {\n    const key = chunkKeyForId(entry.id);\n    const bucket = chunkMap.get(key) ?? [];\n    bucket.push(entry);\n    chunkMap.set(key, bucket);\n  }\n\n  const usedNames = new Map<string, number>();\n  const chunks: DocsIndexChunk[] = [];\n  for (const [key, chunkEntries] of chunkMap) {\n    chunkEntries.sort((a, b) => a.id.localeCompare(b.id));\n    const file = buildChunkFileName(key, usedNames);\n    await writeText(\n      join(outputDir, file),\n      JSON.stringify(chunkEntries, null, 2)\n    );\n    chunks.push({\n      key,\n      file,\n      total: chunkEntries.length,\n    });\n  }\n\n  chunks.sort((a, b) => a.key.localeCompare(b.key));\n\n  const manifest: DocsIndexManifest = {\n    generatedAt,\n    total: entries.length,\n    version: options.version ?? null,\n    contentRoot: contentRootRelative || null,\n    chunks,\n  };\n\n  await writeText(\n    join(outputDir, 'docs-index.manifest.json'),\n    JSON.stringify(manifest, null, 2)\n  );\n\n  const indexTypes = buildIndexTypesFile();\n  await writeText(join(outputDir, 'docs-index.generated.ts'), indexTypes);\n\n  return {\n    total: entries.length,\n    generated: markdownFiles.length,\n    docblocks: docblockCount,\n    outputDir,\n    contentRoot,\n    version: options.version,\n  };\n}\n"],"mappings":"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"}

package/dist/index.d.mts

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

package/dist/index.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { generateDocs } from "./generate.mjs";
+import { Command } from "commander";
+
+//#region src/index.ts
+const program = new Command();
+program.name("contractspec-docs").description("Generate documentation artifacts from ContractSpec specs").version("1.0.0");
+program.command("generate").description("Generate docs index and content artifacts").option("--source <dir>", "Source directory for generated markdown", "generated/docs").option("--out <dir>", "Output directory for generated artifacts", "packages/bundles/library/src/components/docs/generated").option("--content-root <dir>", "Root directory for docs content (defaults to --source)").option("--route-prefix <prefix>", "Route prefix for generated reference pages", "/docs/reference").option("--version <version>", "Version label for generated docs output").option("--no-docblocks", "Skip DocBlocks registry entries").action(async (options) => {
+	const result = await generateDocs({
+		sourceDir: options.source,
+		outDir: options.out,
+		contentRoot: options.contentRoot ?? options.source,
+		includeDocblocks: Boolean(options.docblocks),
+		routePrefix: options.routePrefix,
+		version: options.version
+	});
+	console.log("✅ Docs generated");
+	console.log(`- Output: ${result.outputDir}`);
+	console.log(`- Content root: ${result.contentRoot}`);
+	console.log(`- Total entries: ${result.total}`);
+	console.log(`- Contract docs: ${result.generated}`);
+	console.log(`- DocBlocks: ${result.docblocks}`);
+	if (result.version) console.log(`- Version: ${result.version}`);
+});
+program.parseAsync();
+
+//#endregion
+export {  };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport { Command } from 'commander';\nimport { generateDocs } from './generate';\n\nconst program = new Command();\n\nprogram\n  .name('contractspec-docs')\n  .description('Generate documentation artifacts from ContractSpec specs')\n  .version('1.0.0');\n\nprogram\n  .command('generate')\n  .description('Generate docs index and content artifacts')\n  .option(\n    '--source <dir>',\n    'Source directory for generated markdown',\n    'generated/docs'\n  )\n  .option(\n    '--out <dir>',\n    'Output directory for generated artifacts',\n    'packages/bundles/library/src/components/docs/generated'\n  )\n  .option(\n    '--content-root <dir>',\n    'Root directory for docs content (defaults to --source)'\n  )\n  .option(\n    '--route-prefix <prefix>',\n    'Route prefix for generated reference pages',\n    '/docs/reference'\n  )\n  .option('--version <version>', 'Version label for generated docs output')\n  .option('--no-docblocks', 'Skip DocBlocks registry entries')\n  .action(async (options) => {\n    const result = await generateDocs({\n      sourceDir: options.source,\n      outDir: options.out,\n      contentRoot: options.contentRoot ?? options.source,\n      includeDocblocks: Boolean(options.docblocks),\n      routePrefix: options.routePrefix,\n      version: options.version,\n    });\n\n    console.log('✅ Docs generated');\n    console.log(`- Output: ${result.outputDir}`);\n    console.log(`- Content root: ${result.contentRoot}`);\n    console.log(`- Total entries: ${result.total}`);\n    console.log(`- Contract docs: ${result.generated}`);\n    console.log(`- DocBlocks: ${result.docblocks}`);\n    if (result.version) {\n      console.log(`- Version: ${result.version}`);\n    }\n  });\n\nprogram.parseAsync();\n"],"mappings":";;;;;AAKA,MAAM,UAAU,IAAI,SAAS;AAE7B,QACG,KAAK,oBAAoB,CACzB,YAAY,2DAA2D,CACvE,QAAQ,QAAQ;AAEnB,QACG,QAAQ,WAAW,CACnB,YAAY,4CAA4C,CACxD,OACC,kBACA,2CACA,iBACD,CACA,OACC,eACA,4CACA,yDACD,CACA,OACC,wBACA,yDACD,CACA,OACC,2BACA,8CACA,kBACD,CACA,OAAO,uBAAuB,0CAA0C,CACxE,OAAO,kBAAkB,kCAAkC,CAC3D,OAAO,OAAO,YAAY;CACzB,MAAM,SAAS,MAAM,aAAa;EAChC,WAAW,QAAQ;EACnB,QAAQ,QAAQ;EAChB,aAAa,QAAQ,eAAe,QAAQ;EAC5C,kBAAkB,QAAQ,QAAQ,UAAU;EAC5C,aAAa,QAAQ;EACrB,SAAS,QAAQ;EAClB,CAAC;AAEF,SAAQ,IAAI,mBAAmB;AAC/B,SAAQ,IAAI,aAAa,OAAO,YAAY;AAC5C,SAAQ,IAAI,mBAAmB,OAAO,cAAc;AACpD,SAAQ,IAAI,oBAAoB,OAAO,QAAQ;AAC/C,SAAQ,IAAI,oBAAoB,OAAO,YAAY;AACnD,SAAQ,IAAI,gBAAgB,OAAO,YAAY;AAC/C,KAAI,OAAO,QACT,SAAQ,IAAI,cAAc,OAAO,UAAU;EAE7C;AAEJ,QAAQ,YAAY"}

package/dist/markdown.mjs

@@ -0,0 +1,21 @@
+//#region src/markdown.ts
+const HEADING_MATCH = /^#\s+(.+)$/m;
+function extractTitle(content, fallback) {
+	return content.match(HEADING_MATCH)?.[1]?.trim() || fallback;
+}
+function extractSummary(content) {
+	const filtered = content.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("#") && !line.startsWith("<!--"));
+	if (!filtered.length) return void 0;
+	const summaryLines = [];
+	for (const line of filtered) {
+		if (summaryLines.length && line.length === 0) break;
+		summaryLines.push(line);
+		if (summaryLines.join(" ").length > 200) break;
+	}
+	const summary = summaryLines.join(" ").trim();
+	return summary.length ? summary : void 0;
+}
+
+//#endregion
+export { extractSummary, extractTitle };
+//# sourceMappingURL=markdown.mjs.map

package/dist/markdown.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.mjs","names":[],"sources":["../src/markdown.ts"],"sourcesContent":["const HEADING_MATCH = /^#\\s+(.+)$/m;\n\nexport function extractTitle(content: string, fallback: string): string {\n  const match = content.match(HEADING_MATCH);\n  return match?.[1]?.trim() || fallback;\n}\n\nexport function extractSummary(content: string): string | undefined {\n  const lines = content.split(/\\r?\\n/).map((line) => line.trim());\n  const filtered = lines.filter(\n    (line) =>\n      line.length > 0 && !line.startsWith('#') && !line.startsWith('<!--')\n  );\n\n  if (!filtered.length) return undefined;\n\n  const summaryLines: string[] = [];\n  for (const line of filtered) {\n    if (summaryLines.length && line.length === 0) break;\n    summaryLines.push(line);\n    if (summaryLines.join(' ').length > 200) break;\n  }\n\n  const summary = summaryLines.join(' ').trim();\n  return summary.length ? summary : undefined;\n}\n"],"mappings":";AAAA,MAAM,gBAAgB;AAEtB,SAAgB,aAAa,SAAiB,UAA0B;AAEtE,QADc,QAAQ,MAAM,cAAc,GAC3B,IAAI,MAAM,IAAI;;AAG/B,SAAgB,eAAe,SAAqC;CAElE,MAAM,WADQ,QAAQ,MAAM,QAAQ,CAAC,KAAK,SAAS,KAAK,MAAM,CAAC,CACxC,QACpB,SACC,KAAK,SAAS,KAAK,CAAC,KAAK,WAAW,IAAI,IAAI,CAAC,KAAK,WAAW,OAAO,CACvE;AAED,KAAI,CAAC,SAAS,OAAQ,QAAO;CAE7B,MAAM,eAAyB,EAAE;AACjC,MAAK,MAAM,QAAQ,UAAU;AAC3B,MAAI,aAAa,UAAU,KAAK,WAAW,EAAG;AAC9C,eAAa,KAAK,KAAK;AACvB,MAAI,aAAa,KAAK,IAAI,CAAC,SAAS,IAAK;;CAG3C,MAAM,UAAU,aAAa,KAAK,IAAI,CAAC,MAAM;AAC7C,QAAO,QAAQ,SAAS,UAAU"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@contractspec/tool.docs-generator",
+  "version": "0.0.0-canary-20260128200020",
+  "type": "module",
+  "description": "CLI tool for generating docs artifacts from ContractSpec specs and DocBlocks",
+  "keywords": [
+    "contractspec",
+    "docs",
+    "generator",
+    "cli",
+    "documentation"
+  ],
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun build:types && bun build:bundle",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "docs:generate": "bun src/index.ts generate --source \"../../../generated/docs\" --out \"../../../packages/bundles/library/src/components/docs/generated\" --content-root \"../../../generated/docs\"",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun test"
+  },
+  "bin": {
+    "contractspec-docs": "./dist/index.js"
+  },
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./*": "./*"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@contractspec/lib.contracts": "0.0.0-canary-20260128200020",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@contractspec/tool.tsdown": "1.52.0",
+    "@contractspec/tool.typescript": "1.52.0",
+    "tsdown": "^0.19.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/tools/docs-generator"
+  },
+  "homepage": "https://contractspec.io"
+}