@baybreezy/docd 0.0.1

package/utils/component-api.ts

@@ -0,0 +1,243 @@
+export const DEFAULT_COMPONENT_API_LAYOUT = "table" as const;
+export const DEFAULT_COMPONENT_API_SECTIONS = ["props", "slots", "events", "exposed"] as const;
+export const BUILT_IN_PROSE_COMPONENT_ROOT = "app/components/content/prose/";
+
+export type ProseComponentApiLayout = "field" | "table";
+export type ComponentApiSectionKind = (typeof DEFAULT_COMPONENT_API_SECTIONS)[number];
+
+export interface ComponentApiComponentInput {
+  path?: string;
+  title?: string;
+  layout?: ProseComponentApiLayout;
+  sections?: ComponentApiSectionKind[] | string;
+}
+
+export interface NormalizedComponentApiItem {
+  path: string;
+  title?: string;
+  layout: ProseComponentApiLayout;
+  sections: ComponentApiSectionKind[];
+}
+
+export interface NormalizedComponentApiConfig {
+  heading?: string | false;
+  layout: ProseComponentApiLayout;
+  sections: ComponentApiSectionKind[];
+  components: NormalizedComponentApiItem[];
+  hasExplicitComponents: boolean;
+}
+
+export interface BuiltInComponentApiRegistryItem extends ComponentApiComponentInput {
+  path: string;
+}
+
+export const BUILT_IN_PROSE_COMPONENT_API_REGISTRY: Record<
+  string,
+  false | readonly BuiltInComponentApiRegistryItem[]
+> = {
+  field: [
+    { path: "app/components/content/prose/ProseField.global.vue" },
+    { path: "app/components/content/prose/ProseFieldGroup.global.vue" },
+  ],
+  images: [
+    { path: "app/components/content/prose/ProseImg.global.vue" },
+    { path: "app/components/content/prose/ProseColorModeImage.global.vue" },
+  ],
+  "icon-list": [
+    { path: "app/components/content/prose/ProseIconList.global.vue" },
+    { path: "app/components/content/prose/ProseLi.global.vue" },
+  ],
+  "package-manager": [
+    { path: "app/components/content/prose/ProsePmInstall.global.vue" },
+    { path: "app/components/content/prose/ProsePmRun.global.vue" },
+    { path: "app/components/content/prose/ProsePmX.global.vue" },
+  ],
+  steps: [
+    { path: "app/components/content/prose/ProseSteps.global.vue" },
+    { path: "app/components/content/prose/ProseStep.global.vue" },
+  ],
+  "code-snippet": false,
+  typography: false,
+};
+
+function toPosixPath(value: string) {
+  return value.replace(/\\/g, "/");
+}
+
+export function normalizeComponentApiPath(path: string) {
+  return toPosixPath(path)
+    .trim()
+    .replace(/^([@~])\//, "")
+    .replace(/^\.\//, "")
+    .replace(/^\/(?!\/)/, "");
+}
+
+export function normalizeComponentMetaPath(path: string) {
+  const normalized = normalizeComponentApiPath(path);
+  const proseIndex = normalized.lastIndexOf(BUILT_IN_PROSE_COMPONENT_ROOT);
+
+  if (proseIndex !== -1) {
+    return normalized.slice(proseIndex);
+  }
+
+  return normalized;
+}
+
+export const normalizeProseComponentPath = normalizeComponentMetaPath;
+
+export function isBuiltInProseComponentPath(path: string) {
+  return normalizeComponentMetaPath(path).startsWith(BUILT_IN_PROSE_COMPONENT_ROOT);
+}
+
+export function componentNameFromPath(path: string) {
+  const normalized = normalizeComponentMetaPath(path);
+  const fileName = normalized.split("/").pop() || normalized;
+
+  return fileName.replace(/\.vue$/, "").replace(/\.global$/, "");
+}
+
+export function componentLabelFromName(name: string) {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/_/g, " ")
+    .trim();
+}
+
+export function componentLabelFromPath(path: string) {
+  return componentLabelFromName(componentNameFromPath(path));
+}
+
+export function componentTagFromName(name: string) {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/_/g, "-")
+    .toLowerCase();
+}
+
+export function componentNameFromSlug(slug: string) {
+  const pascalCase = slug
+    .split(/[-_\s]+/g)
+    .filter(Boolean)
+    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+    .join("");
+
+  return `Prose${pascalCase}`;
+}
+
+export function inferredBuiltInProseComponentPathFromSlug(slug: string) {
+  return `${BUILT_IN_PROSE_COMPONENT_ROOT}${componentNameFromSlug(slug)}.global.vue`;
+}
+
+export function normalizeComponentApiLayout(
+  value: unknown,
+  fallback: ProseComponentApiLayout = DEFAULT_COMPONENT_API_LAYOUT
+): ProseComponentApiLayout {
+  return value === "table" || value === "field" ? value : fallback;
+}
+
+export function normalizeComponentApiSections(
+  value: unknown,
+  fallback: readonly ComponentApiSectionKind[] = DEFAULT_COMPONENT_API_SECTIONS
+) {
+  const values = Array.isArray(value)
+    ? value
+    : typeof value === "string"
+      ? value
+          .split(",")
+          .map((section) => section.trim())
+          .filter(Boolean)
+      : [];
+
+  const sections = values.filter((section): section is ComponentApiSectionKind =>
+    (DEFAULT_COMPONENT_API_SECTIONS as readonly string[]).includes(String(section))
+  );
+
+  return (
+    sections.length ? Array.from(new Set(sections)) : [...fallback]
+  ) as ComponentApiSectionKind[];
+}
+
+export function normalizeComponentApiHeading(value: unknown) {
+  if (value === false) {
+    return false;
+  }
+
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const heading = value.trim();
+  return heading || undefined;
+}
+
+function normalizeComponentApiItem(
+  input: unknown,
+  defaults: Pick<NormalizedComponentApiConfig, "layout" | "sections">
+) {
+  if (typeof input === "string") {
+    return {
+      path: normalizeComponentMetaPath(input),
+      layout: defaults.layout,
+      sections: [...defaults.sections],
+    } satisfies NormalizedComponentApiItem;
+  }
+
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    return null;
+  }
+
+  const item = input as Record<string, unknown>;
+
+  if (typeof item.path !== "string" || !item.path.trim()) {
+    return null;
+  }
+
+  return {
+    path: normalizeComponentMetaPath(item.path),
+    title: typeof item.title === "string" ? item.title : undefined,
+    layout: normalizeComponentApiLayout(item.layout, defaults.layout),
+    sections: normalizeComponentApiSections(item.sections, defaults.sections),
+  } satisfies NormalizedComponentApiItem;
+}
+
+export function normalizeComponentApiConfig(
+  input: unknown
+): false | NormalizedComponentApiConfig | null {
+  if (input === false) {
+    return false;
+  }
+
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    return null;
+  }
+
+  const config = input as Record<string, unknown>;
+  const heading = normalizeComponentApiHeading(config.heading);
+  const layout = normalizeComponentApiLayout(config.layout);
+  const sections = normalizeComponentApiSections(config.sections);
+  const defaults = { layout, sections };
+  const components: NormalizedComponentApiItem[] = [];
+
+  const pathItem = normalizeComponentApiItem(config.path, defaults);
+  if (pathItem) {
+    components.push(pathItem);
+  }
+
+  if (Array.isArray(config.components)) {
+    for (const component of config.components) {
+      const normalizedComponent = normalizeComponentApiItem(component, defaults);
+
+      if (normalizedComponent) {
+        components.push(normalizedComponent);
+      }
+    }
+  }
+
+  return {
+    heading,
+    layout,
+    sections,
+    components,
+    hasExplicitComponents: components.length > 0,
+  };
+}

package/utils/generate-prose-component-meta.ts

@@ -0,0 +1,303 @@
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, readdir, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+
+import { getComponentMeta } from "nuxt-component-meta/parser";
+
+import {
+  componentNameFromPath,
+  componentTagFromName,
+  normalizeComponentMetaPath,
+} from "./component-api";
+
+export type { ProseComponentApiLayout } from "./component-api";
+
+export interface ProseComponentMetaTag {
+  name: string;
+  text?: string;
+}
+
+interface BaseProseComponentMetaItem {
+  name: string;
+  description: string;
+  type: string;
+  tags: ProseComponentMetaTag[];
+}
+
+type RawProseComponentSchema = unknown;
+
+interface RawMetaTag {
+  name: string;
+  text?: string;
+}
+
+interface RawPropertyMeta {
+  name: string;
+  description: string;
+  type: string;
+  default?: string;
+  required: boolean;
+  tags: RawMetaTag[];
+  schema?: RawProseComponentSchema;
+}
+
+interface RawSlotMeta {
+  name: string;
+  description: string;
+  type: string;
+  tags: RawMetaTag[];
+  schema?: RawProseComponentSchema;
+}
+
+interface RawEventMeta {
+  name: string;
+  description: string;
+  type: string;
+  signature: string;
+  tags: RawMetaTag[];
+  schema?: RawProseComponentSchema[];
+}
+
+interface RawExposedMeta {
+  name: string;
+  description: string;
+  type: string;
+  tags: RawMetaTag[];
+  schema?: RawProseComponentSchema;
+}
+
+export interface ProseComponentMetaProp extends BaseProseComponentMetaItem {
+  default?: string;
+  required: boolean;
+  schema?: RawProseComponentSchema;
+}
+
+export interface ProseComponentMetaSlot extends BaseProseComponentMetaItem {
+  schema?: RawProseComponentSchema;
+}
+
+export interface ProseComponentMetaEvent extends BaseProseComponentMetaItem {
+  signature: string;
+  schema?: RawProseComponentSchema[];
+}
+
+export interface ProseComponentMetaExposed extends BaseProseComponentMetaItem {
+  schema?: RawProseComponentSchema;
+}
+
+export interface ProseComponentMetaEntry {
+  name: string;
+  tag: string;
+  path: string;
+  props: ProseComponentMetaProp[];
+  slots: ProseComponentMetaSlot[];
+  events: ProseComponentMetaEvent[];
+  exposed: ProseComponentMetaExposed[];
+}
+
+export interface ProseComponentMetaManifest {
+  generatedAt: string;
+  components: Record<string, ProseComponentMetaEntry>;
+  sourceHashes?: Record<string, string>;
+}
+
+export interface ProseComponentMetaSource {
+  absolutePath: string;
+  manifestPath: string;
+}
+
+export interface GenerateProseComponentMetaOptions {
+  rootDir: string;
+  layerRoot: string;
+  componentsDir: string;
+  outputFile: string;
+  cache?: boolean;
+  cacheDir?: string;
+  additionalComponents?: ProseComponentMetaSource[];
+}
+
+export const EMPTY_PROSE_COMPONENT_META_MANIFEST: ProseComponentMetaManifest = {
+  generatedAt: "",
+  components: {},
+};
+
+export const normalizeProseComponentPath = normalizeComponentMetaPath;
+
+function normalizeTags(tags: RawMetaTag[] = []): ProseComponentMetaTag[] {
+  return tags.map((tag) => ({ name: tag.name, text: tag.text }));
+}
+
+function normalizeProp(prop: RawPropertyMeta): ProseComponentMetaProp {
+  return {
+    name: prop.name,
+    description: prop.description || "",
+    type: prop.type || "unknown",
+    default: prop.default,
+    required: prop.required,
+    tags: normalizeTags(prop.tags),
+    schema: prop.schema,
+  };
+}
+
+function normalizeSlot(slot: RawSlotMeta): ProseComponentMetaSlot {
+  return {
+    name: slot.name,
+    description: slot.description || "",
+    type: slot.type || "unknown",
+    tags: normalizeTags(slot.tags),
+    schema: slot.schema,
+  };
+}
+
+function normalizeEvent(event: RawEventMeta): ProseComponentMetaEvent {
+  return {
+    name: event.name,
+    description: event.description || "",
+    type: event.type || "unknown",
+    signature: event.signature || event.type || "unknown",
+    tags: normalizeTags(event.tags),
+    schema: event.schema,
+  };
+}
+
+function normalizeExposed(exposed: RawExposedMeta): ProseComponentMetaExposed {
+  return {
+    name: exposed.name,
+    description: exposed.description || "",
+    type: exposed.type || "unknown",
+    tags: normalizeTags(exposed.tags),
+    schema: exposed.schema,
+  };
+}
+
+async function listVueFiles(dir: string): Promise<string[]> {
+  const files: string[] = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...(await listVueFiles(fullPath)));
+      continue;
+    }
+
+    if (entry.isFile() && fullPath.endsWith(".vue")) {
+      files.push(fullPath);
+    }
+  }
+
+  return files.sort((a, b) => a.localeCompare(b));
+}
+
+function readExistingManifest(outputFile: string): ProseComponentMetaManifest {
+  if (!existsSync(outputFile)) {
+    return EMPTY_PROSE_COMPONENT_META_MANIFEST;
+  }
+
+  try {
+    const contents = readFileSync(outputFile, "utf8");
+    return JSON.parse(contents) as ProseComponentMetaManifest;
+  } catch {
+    return EMPTY_PROSE_COMPONENT_META_MANIFEST;
+  }
+}
+
+export function readGeneratedProseComponentMeta(outputFile: string): ProseComponentMetaManifest {
+  return readExistingManifest(outputFile);
+}
+
+export async function generateProseComponentMeta(
+  options: GenerateProseComponentMetaOptions
+): Promise<ProseComponentMetaManifest> {
+  const previousManifest = readExistingManifest(options.outputFile);
+  const builtInComponentFiles = await listVueFiles(options.componentsDir);
+  const componentSources = new Map<string, ProseComponentMetaSource>();
+  const components: Record<string, ProseComponentMetaEntry> = {};
+  const sourceHashes: Record<string, string> = {};
+
+  for (const componentPath of builtInComponentFiles) {
+    const manifestPath = normalizeComponentMetaPath(relative(options.layerRoot, componentPath));
+    componentSources.set(manifestPath, {
+      absolutePath: componentPath,
+      manifestPath,
+    });
+  }
+
+  for (const component of options.additionalComponents || []) {
+    componentSources.set(component.manifestPath, component);
+  }
+
+  const sources = Array.from(componentSources.values()).sort((a, b) =>
+    a.manifestPath.localeCompare(b.manifestPath)
+  );
+  let hasChanges = sources.length !== Object.keys(previousManifest.components || {}).length;
+
+  for (const component of sources) {
+    const stats = await stat(component.absolutePath);
+    const sourceHash = `${stats.mtimeMs}:${stats.size}`;
+
+    sourceHashes[component.manifestPath] = sourceHash;
+
+    const cachedEntry = previousManifest.components?.[component.manifestPath];
+    const cachedHash = previousManifest.sourceHashes?.[component.manifestPath];
+
+    if (cachedEntry && cachedHash === sourceHash) {
+      components[component.manifestPath] = cachedEntry;
+      continue;
+    }
+
+    hasChanges = true;
+
+    const meta = getComponentMeta(component.absolutePath, {
+      rootDir: options.rootDir,
+      cache: options.cache ?? true,
+      cacheDir: options.cacheDir,
+    });
+
+    const name = componentNameFromPath(component.manifestPath);
+    components[component.manifestPath] = {
+      name,
+      tag: componentTagFromName(name),
+      path: component.manifestPath,
+      props: meta.props.map(normalizeProp),
+      slots: meta.slots.map(normalizeSlot),
+      events: meta.events.map(normalizeEvent),
+      exposed: meta.exposed.map(normalizeExposed),
+    };
+  }
+
+  if (!hasChanges) {
+    return previousManifest;
+  }
+
+  const nextManifest: ProseComponentMetaManifest = {
+    generatedAt: new Date().toISOString(),
+    components,
+    sourceHashes,
+  };
+
+  const nextContents = `${JSON.stringify(nextManifest, null, 2)}\n`;
+  const previousContents = existsSync(options.outputFile)
+    ? readFileSync(options.outputFile, "utf8")
+    : "";
+
+  if (previousContents !== nextContents) {
+    await mkdir(dirname(options.outputFile), { recursive: true });
+    await writeFile(options.outputFile, nextContents, "utf8");
+  }
+
+  return nextManifest;
+}
+
+export function resolveProseComponentPaths(options: { rootDir: string; layerRoot: string }) {
+  const componentsDir = resolve(options.layerRoot, "app/components/content/prose");
+  const outputFile = resolve(options.rootDir, ".data/docd/prose-component-meta.json");
+  const cacheDir = resolve(options.rootDir, ".data/docd/prose-component-meta");
+
+  return {
+    componentsDir,
+    outputFile,
+    cacheDir,
+  };
+}

package/utils/git.ts

@@ -0,0 +1,123 @@
+import { execSync } from "node:child_process";
+
+import gitUrlParse from "git-url-parse";
+import { readGitConfig } from "pkg-types";
+
+export interface GitInfo {
+  // Repository name
+  name: string;
+  // Repository owner/organization
+  owner: string;
+  // Repository URL
+  url: string;
+}
+
+export function getGitBranch() {
+  const envName =
+    process.env.CF_PAGES_BRANCH ||
+    process.env.CI_COMMIT_BRANCH ||
+    process.env.VERCEL_GIT_COMMIT_REF ||
+    process.env.BRANCH ||
+    process.env.GITHUB_REF_NAME;
+
+  if (envName && envName !== "HEAD") {
+    return envName;
+  }
+  try {
+    const branch = execSync("git rev-parse --abbrev-ref HEAD", {
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+      .toString()
+      .trim();
+    if (branch && branch !== "HEAD") {
+      return branch;
+    }
+  } catch {
+    // Ignore error
+  }
+
+  return "main";
+}
+
+/**
+ * Get Git repository information from the local .git config or environment variables.
+ */
+export async function getLocalGitInfo(rootDir: string): Promise<GitInfo | undefined> {
+  const remote = await getLocalGitRemote(rootDir);
+  if (!remote) {
+    return;
+  }
+
+  // https://www.npmjs.com/package/git-url-parse#clipboard-example
+  const { name, owner, source } = gitUrlParse(remote);
+  const url = `https://${source}/${owner}/${name}`;
+
+  return {
+    name,
+    owner,
+    url,
+  };
+}
+
+/**
+ * Read the local .git/config file to get the remote URL of the repository.
+ */
+async function getLocalGitRemote(dir: string): Promise<string | undefined> {
+  try {
+    const parsed = await readGitConfig(dir);
+    if (!parsed) {
+      return;
+    }
+    return parsed.remote?.["origin"]?.url;
+  } catch {
+    // Ignore error
+  }
+}
+
+/**
+ * Get Git repository information from environment variables set by hosting providers (e.g., Vercel, Netlify, GitHub Actions).
+ */
+export function getGitEnv(): GitInfo {
+  const envInfo = {
+    // Provider
+    provider:
+      process.env.VERCEL_GIT_PROVIDER || // vercel
+      (process.env.GITHUB_SERVER_URL ? "github" : undefined) || // github
+      "",
+    // Owner
+    owner:
+      process.env.VERCEL_GIT_REPO_OWNER || // vercel
+      process.env.GITHUB_REPOSITORY_OWNER || // github
+      process.env.CI_PROJECT_PATH?.split("/").shift() || // gitlab
+      "",
+    // Name
+    name:
+      process.env.VERCEL_GIT_REPO_SLUG ||
+      process.env.GITHUB_REPOSITORY?.split("/").pop() || // github
+      process.env.CI_PROJECT_PATH?.split("/").splice(1).join("/") || // gitlab
+      "",
+    // Url
+    url: process.env.REPOSITORY_URL || "", // netlify
+  };
+
+  if (!envInfo.url && envInfo.provider && envInfo.owner && envInfo.name) {
+    envInfo.url = `https://${envInfo.provider}.com/${envInfo.owner}/${envInfo.name}`;
+  }
+
+  // If only url available (ex: Netlify)
+  if (!envInfo.name && !envInfo.owner && envInfo.url) {
+    try {
+      const { name, owner } = gitUrlParse(envInfo.url);
+      envInfo.name = name;
+      envInfo.owner = owner;
+    } catch {
+      // Ignore error
+    }
+  }
+
+  return {
+    name: envInfo.name,
+    owner: envInfo.owner,
+    url: envInfo.url,
+  };
+}

package/utils/meta.ts

@@ -0,0 +1,40 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import { withHttps } from "ufo";
+
+/**
+ * Infers the site URL from various environment variables commonly used in hosting platforms.
+ */
+export function inferSiteURL() {
+  // https://github.com/unjs/std-env/issues/59
+  const url =
+    process.env.NUXT_PUBLIC_SITE_URL || // Nuxt public runtime config
+    process.env.NUXT_SITE_URL || // Nuxt site config
+    process.env.VERCEL_PROJECT_PRODUCTION_URL || // Vercel production URL
+    process.env.VERCEL_BRANCH_URL || // Vercel branch URL
+    process.env.VERCEL_URL || // Vercel deployment URL
+    process.env.URL || // Netlify
+    process.env.CI_PAGES_URL || // Gitlab Pages
+    process.env.CF_PAGES_URL; // Cloudflare Pages
+
+  return url ? withHttps(url) : undefined;
+}
+
+/**
+ * Reads the package.json file from the specified directory and extracts metadata such as `name` and `description`.
+ */
+export async function getPackageJsonMetadata(dir: string) {
+  try {
+    const packageJson = await readFile(resolve(dir, "package.json"), "utf-8");
+    const parsed = JSON.parse(packageJson);
+    return {
+      name: parsed.name,
+      description: parsed.description,
+    };
+  } catch {
+    return {
+      name: "Docd",
+    };
+  }
+}