@outfitter/docs-core 0.1.0

package/README.md

@@ -0,0 +1,47 @@
+# @outfitter/docs-core
+
+Core docs assembly and freshness-check primitives for Outfitter-based projects.
+
+## Scope
+
+- Discover publishable workspace packages
+- Assemble package docs into a centralized output tree
+- Rewrite relative links so relocated docs remain valid
+- Check generated docs for drift (missing, changed, unexpected files)
+- Render `llms.txt` and `llms-full.txt` from the same docs graph
+- Process MDX inputs with `strict` or `lossy` downleveling modes
+
+## API
+
+```ts
+import {
+  checkLlmsDocs,
+  checkPackageDocs,
+  syncLlmsDocs,
+  syncPackageDocs,
+} from "@outfitter/docs-core";
+
+const syncResult = await syncPackageDocs({
+  workspaceRoot: process.cwd(),
+  mdxMode: "strict",
+});
+
+const checkResult = await checkPackageDocs({
+  workspaceRoot: process.cwd(),
+});
+
+const llmsSyncResult = await syncLlmsDocs({
+  workspaceRoot: process.cwd(),
+  mdxMode: "lossy",
+  targets: ["llms", "llms-full"],
+});
+
+const llmsCheckResult = await checkLlmsDocs({
+  workspaceRoot: process.cwd(),
+  targets: ["llms", "llms-full"],
+});
+```
+
+## License
+
+MIT

package/dist/cli-sync.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env bun
+// @bun
+import {
+  syncLlmsDocs,
+  syncPackageDocs
+} from "./shared/@outfitter/docs-core-d4ex21rp.js";
+
+// packages/docs-core/src/cli-sync.ts
+function parseArgs(argv) {
+  const options = {};
+  for (let i = 0;i < argv.length; i += 1) {
+    const arg = argv[i];
+    const nextValue = argv[i + 1];
+    if (arg === "--cwd") {
+      if (typeof nextValue === "string") {
+        options.cwd = nextValue;
+        i += 1;
+      }
+      continue;
+    }
+    if (arg === "--packages-dir") {
+      if (typeof nextValue === "string") {
+        options.packagesDir = nextValue;
+        i += 1;
+      }
+      continue;
+    }
+    if (arg === "--mdx-mode") {
+      if (nextValue === "strict" || nextValue === "lossy") {
+        options.mdxMode = nextValue;
+        i += 1;
+      }
+      continue;
+    }
+    if (arg === "--output-dir" && typeof nextValue === "string") {
+      options.outputDir = nextValue;
+      i += 1;
+    }
+  }
+  return options;
+}
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const result = await syncPackageDocs({
+    ...options.cwd ? { workspaceRoot: options.cwd } : {},
+    ...options.mdxMode ? { mdxMode: options.mdxMode } : {},
+    ...options.packagesDir ? { packagesDir: options.packagesDir } : {},
+    ...options.outputDir ? { outputDir: options.outputDir } : {}
+  });
+  if (result.isErr()) {
+    process.stderr.write(`docs sync failed: ${result.error.message}
+`);
+    process.exit(1);
+  }
+  process.stdout.write(`docs sync complete: ${result.value.packageNames.length} package(s), ` + `${result.value.writtenFiles.length} file(s) written, ` + `${result.value.removedFiles.length} stale file(s) removed
+`);
+  for (const warning of result.value.warnings) {
+    process.stderr.write(`docs warning: ${warning.path}: ${warning.message}
+`);
+  }
+  const llmsResult = await syncLlmsDocs({
+    ...options.cwd ? { workspaceRoot: options.cwd } : {},
+    ...options.mdxMode ? { mdxMode: options.mdxMode } : {},
+    ...options.packagesDir ? { packagesDir: options.packagesDir } : {},
+    ...options.outputDir ? { outputDir: options.outputDir } : {}
+  });
+  if (llmsResult.isErr()) {
+    process.stderr.write(`docs sync failed: ${llmsResult.error.message}
+`);
+    process.exit(1);
+  }
+  process.stdout.write(`llms sync complete: ${llmsResult.value.packageNames.length} package(s), ` + `${llmsResult.value.writtenFiles.length} file(s) written
+`);
+  for (const warning of llmsResult.value.warnings) {
+    process.stderr.write(`docs warning: ${warning.path}: ${warning.message}
+`);
+  }
+}
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`docs sync failed: ${message}
+`);
+  process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+import { Result } from "better-result";
+type MdxMode = "strict" | "lossy";
+interface PackageDocsOptions {
+	readonly workspaceRoot?: string;
+	readonly packagesDir?: string;
+	readonly outputDir?: string;
+	readonly excludedFilenames?: readonly string[];
+	readonly mdxMode?: MdxMode;
+}
+type LlmsTarget = "llms" | "llms-full";
+interface LlmsDocsOptions extends PackageDocsOptions {
+	readonly llmsFile?: string;
+	readonly llmsFullFile?: string;
+	readonly targets?: readonly LlmsTarget[];
+}
+interface SyncPackageDocsResult {
+	readonly packageNames: readonly string[];
+	readonly writtenFiles: readonly string[];
+	readonly removedFiles: readonly string[];
+	readonly warnings: readonly DocsWarning[];
+}
+type DriftKind = "missing" | "changed" | "unexpected";
+interface DocsDrift {
+	readonly path: string;
+	readonly kind: DriftKind;
+}
+interface DocsWarning {
+	readonly path: string;
+	readonly message: string;
+}
+interface CheckPackageDocsResult {
+	readonly packageNames: readonly string[];
+	readonly expectedFiles: readonly string[];
+	readonly drift: readonly DocsDrift[];
+	readonly isUpToDate: boolean;
+	readonly warnings: readonly DocsWarning[];
+}
+interface SyncLlmsDocsResult {
+	readonly packageNames: readonly string[];
+	readonly writtenFiles: readonly string[];
+	readonly warnings: readonly DocsWarning[];
+}
+interface CheckLlmsDocsResult {
+	readonly packageNames: readonly string[];
+	readonly expectedFiles: readonly string[];
+	readonly drift: readonly DocsDrift[];
+	readonly isUpToDate: boolean;
+	readonly warnings: readonly DocsWarning[];
+}
+declare class DocsCoreError extends Error {
+	readonly _tag: "DocsCoreError";
+	readonly category: "validation" | "internal";
+	readonly context: Record<string, unknown> | undefined;
+	constructor(input: {
+		message: string;
+		category: "validation" | "internal";
+		context?: Record<string, unknown>;
+	});
+	static validation(message: string, context?: Record<string, unknown>): DocsCoreError;
+	static internal(message: string, context?: Record<string, unknown>): DocsCoreError;
+}
+type PackageDocsError = DocsCoreError;
+declare function syncPackageDocs(options?: PackageDocsOptions): Promise<Result<SyncPackageDocsResult, PackageDocsError>>;
+declare function checkPackageDocs(options?: PackageDocsOptions): Promise<Result<CheckPackageDocsResult, PackageDocsError>>;
+declare function syncLlmsDocs(options?: LlmsDocsOptions): Promise<Result<SyncLlmsDocsResult, PackageDocsError>>;
+declare function checkLlmsDocs(options?: LlmsDocsOptions): Promise<Result<CheckLlmsDocsResult, PackageDocsError>>;
+export { syncPackageDocs, syncLlmsDocs, checkPackageDocs, checkLlmsDocs, SyncPackageDocsResult, SyncLlmsDocsResult, PackageDocsOptions, PackageDocsError, MdxMode, LlmsTarget, LlmsDocsOptions, DriftKind, DocsWarning, DocsDrift, DocsCoreError, CheckPackageDocsResult, CheckLlmsDocsResult };