@glossic/core 0.1.0

package/dist/index.js

@@ -0,0 +1,1136 @@
+import fs2 from 'fs/promises';
+import path3 from 'path';
+import { z } from 'zod';
+import { sortBy, ManifestSchema, MANIFEST_VERSION, toPosix, GlossicConfigSchema, compareStrings, isRetryableProviderError, ProviderError } from '@glossic/schema';
+export { compareStrings, joinPosix, relativePosix, sortBy, toPosix } from '@glossic/schema';
+import { glob } from 'tinyglobby';
+import { parse } from 'yaml';
+import { createJiti } from 'jiti';
+import picomatch from 'picomatch';
+
+// package.json
+var package_default = {
+  version: "0.1.0"};
+var pathExists = async (target) => {
+  try {
+    await fs2.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+};
+var readText = async (target) => {
+  try {
+    return await fs2.readFile(target, "utf8");
+  } catch {
+    return void 0;
+  }
+};
+var readJson = async (target) => {
+  const raw = await readText(target);
+  if (raw === void 0) {
+    return void 0;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+};
+
+// src/cache.ts
+var DEFAULT_CACHE_PATH = ".glossic/cache.json";
+var CACHE_VERSION = "1";
+var CacheEntrySchema = z.object({
+  unitId: z.string().min(1),
+  unitHash: z.string().min(1),
+  promptVersion: z.string().min(1),
+  model: z.string().min(1),
+  lang: z.string().min(1),
+  outputPath: z.string().min(1),
+  generatedAt: z.string().min(1)
+});
+var CacheFileSchema = z.object({
+  version: z.string().min(1),
+  entries: z.array(CacheEntrySchema)
+});
+var emptyCache = () => ({ version: CACHE_VERSION, entries: [] });
+var readCache = async (target) => {
+  try {
+    const raw = await fs2.readFile(path3.resolve(target), "utf8");
+    const parsed = CacheFileSchema.parse(JSON.parse(raw));
+    return parsed.version === CACHE_VERSION ? parsed : emptyCache();
+  } catch {
+    return emptyCache();
+  }
+};
+var serializeCache = (cache) => {
+  return `${JSON.stringify({ ...cache, entries: sortBy(cache.entries, (entry) => entry.unitId) }, null, 2)}
+`;
+};
+var writeCache = async (cache, target) => {
+  const absolute = path3.resolve(target);
+  await fs2.mkdir(path3.dirname(absolute), { recursive: true });
+  await fs2.writeFile(absolute, serializeCache(cache), "utf8");
+  return absolute;
+};
+var indexCache = (cache) => {
+  return new Map(cache.entries.map((entry) => [entry.unitId, entry]));
+};
+var DEFAULT_MANIFEST_PATH = ".glossic/manifest.json";
+var sortUnit = (unit) => ({
+  ...unit,
+  facts: {
+    ...unit.facts,
+    base: {
+      ...unit.facts.base,
+      files: sortBy(unit.facts.base.files, (file) => file.path),
+      languages: [...unit.facts.base.languages].sort(
+        (a, b) => b.count - a.count || compareStrings(a.language, b.language)
+      )
+    },
+    producedBy: [...unit.facts.producedBy].sort(compareStrings)
+  }
+});
+var compareRelations = (a, b) => {
+  return compareStrings(a.from, b.from) || compareStrings(a.to, b.to) || compareStrings(a.kind, b.kind);
+};
+var buildManifest = (workspace, results, options = {}) => {
+  const units = results.flatMap((result) => result.units).map(sortUnit);
+  const relations = results.flatMap((result) => result.relations);
+  return ManifestSchema.parse({
+    version: MANIFEST_VERSION,
+    generatedAt: options.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    workspace: {
+      ...workspace,
+      projects: sortBy(workspace.projects, (project) => project.id)
+    },
+    units: sortBy(units, (unit) => unit.id),
+    relations: [...relations].sort(compareRelations)
+  });
+};
+var serializeManifest = (manifest) => {
+  return `${JSON.stringify(manifest, null, 2)}
+`;
+};
+var writeManifest = async (manifest, target) => {
+  const absolute = path3.resolve(target);
+  await fs2.mkdir(path3.dirname(absolute), { recursive: true });
+  await fs2.writeFile(absolute, serializeManifest(manifest), "utf8");
+  return absolute;
+};
+var readManifest = async (target) => {
+  try {
+    const raw = await fs2.readFile(path3.resolve(target), "utf8");
+    return ManifestSchema.parse(JSON.parse(raw));
+  } catch {
+    return void 0;
+  }
+};
+var GLOB_IGNORES = ["**/node_modules/**", "**/dist/**", "**/build/**", "**/.git/**"];
+var LOCKFILE_PACKAGE_MANAGERS = [
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["package-lock.json", "npm"],
+  ["bun.lock", "bun"],
+  ["bun.lockb", "bun"],
+  ["composer.lock", "composer"],
+  ["composer.json", "composer"]
+];
+var asStringArray = (value) => Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+var detectPackageManager = async (dir, pkg) => {
+  const declared = pkg?.packageManager;
+  if (typeof declared === "string" && declared.length > 0) {
+    const [name] = declared.split("@");
+    if (name !== void 0 && name.length > 0) {
+      return name;
+    }
+  }
+  for (const [lockfile, manager] of LOCKFILE_PACKAGE_MANAGERS) {
+    if (await pathExists(path3.join(dir, lockfile))) {
+      return manager;
+    }
+  }
+  return void 0;
+};
+var detectMonorepo = async (root, pkg) => {
+  const pnpmWorkspace = await readText(path3.join(root, "pnpm-workspace.yaml"));
+  if (pnpmWorkspace !== void 0) {
+    const parsed = parse(pnpmWorkspace);
+    const globs = asStringArray(parsed?.packages);
+    if (globs.length > 0) {
+      return { tool: "pnpm", globs };
+    }
+  }
+  const workspaces = Array.isArray(pkg?.workspaces) ? pkg.workspaces : asStringArray(pkg?.workspaces?.packages);
+  if (workspaces.length > 0) {
+    return { tool: "npm-workspaces", globs: workspaces };
+  }
+  if (await pathExists(path3.join(root, "turbo.json"))) {
+    return { tool: "turbo", globs: ["apps/*", "packages/*"] };
+  }
+  if (await pathExists(path3.join(root, "nx.json"))) {
+    return { tool: "nx", globs: ["apps/*", "libs/*", "packages/*"] };
+  }
+  const lerna = await readJson(path3.join(root, "lerna.json"));
+  if (lerna !== void 0) {
+    const globs = asStringArray(lerna.packages);
+    return { tool: "lerna", globs: globs.length > 0 ? globs : ["packages/*"] };
+  }
+  return void 0;
+};
+var expandProjectDirs = async (root, globs) => {
+  const patterns = [];
+  const ignore = [...GLOB_IGNORES];
+  for (const entry of globs) {
+    if (entry.startsWith("!")) {
+      ignore.push(`${entry.slice(1)}/**`);
+      continue;
+    }
+    patterns.push(`${entry}/package.json`);
+  }
+  if (patterns.length === 0) return [];
+  const manifests = await glob({
+    patterns,
+    cwd: root,
+    ignore,
+    onlyFiles: true,
+    followSymbolicLinks: false,
+    dot: false
+  });
+  const dirs = manifests.map((manifest) => toPosix(path3.posix.dirname(toPosix(manifest))));
+  return [...new Set(dirs)].sort();
+};
+var buildProject = async (root, rootDir, fallbackManager) => {
+  const dir = path3.resolve(root, rootDir);
+  const pkg = await readJson(path3.join(dir, "package.json"));
+  const packageManager = await detectPackageManager(dir, pkg) ?? fallbackManager;
+  const name = pkg?.name ?? path3.basename(dir);
+  const project = {
+    id: rootDir === "." ? "root" : rootDir,
+    name,
+    rootDir
+  };
+  return packageManager === void 0 ? project : { ...project, packageManager };
+};
+var resolveWorkspace = async (root) => {
+  const absoluteRoot = path3.resolve(root);
+  const pkg = await readJson(path3.join(absoluteRoot, "package.json"));
+  const packageManager = await detectPackageManager(absoluteRoot, pkg);
+  const name = pkg?.name ?? path3.basename(absoluteRoot);
+  const marker = await detectMonorepo(absoluteRoot, pkg);
+  const projectDirs = marker === void 0 ? [] : await expandProjectDirs(absoluteRoot, marker.globs);
+  const isMonorepo = projectDirs.length > 0;
+  const rootDirs = isMonorepo ? projectDirs : ["."];
+  const projects = await Promise.all(
+    rootDirs.map((rootDir) => buildProject(absoluteRoot, rootDir, packageManager))
+  );
+  const workspace = {
+    name,
+    root: toPosix(absoluteRoot),
+    isMonorepo,
+    tool: isMonorepo && marker !== void 0 ? marker.tool : "none",
+    projects: sortBy(projects, (project) => project.id)
+  };
+  return packageManager === void 0 ? workspace : { ...workspace, packageManager };
+};
+
+// src/scan.ts
+var orderAdapters = (adapters, wanted) => {
+  const byName = new Map(adapters.map((adapter) => [adapter.name, adapter]));
+  return wanted.map((name) => byName.get(name)).filter((adapter) => adapter !== void 0);
+};
+var selectAdapter = async (adapters, ctx) => {
+  for (const adapter of adapters) {
+    if (await adapter.detect(ctx)) {
+      return adapter;
+    }
+  }
+  return void 0;
+};
+var scan = async (ctx) => {
+  const config = ctx.config ?? GlossicConfigSchema.parse({});
+  const workspace = await resolveWorkspace(path3.resolve(ctx.root));
+  const adapters = orderAdapters(ctx.adapters, config.adapters);
+  const adapterContext = { root: workspace.root, workspace, config };
+  const results = [];
+  const adapterByProject = {};
+  for (const project of workspace.projects) {
+    const discoverContext = { ...adapterContext, project };
+    const adapter = await selectAdapter(adapters, discoverContext);
+    if (adapter === void 0) continue;
+    adapterByProject[project.id] = adapter.name;
+    const units = await adapter.discover(discoverContext);
+    results.push(await adapter.extract({ ...discoverContext, units }));
+  }
+  const manifest = buildManifest(
+    workspace,
+    results,
+    ctx.generatedAt === void 0 ? {} : { generatedAt: ctx.generatedAt }
+  );
+  return { manifest, workspace, adapterByProject };
+};
+
+// src/markdown.ts
+var unitDocPath = (unit) => {
+  return unit.path === "." ? "root.md" : `${unit.path}.md`;
+};
+var INDEX_DOC_PATH = "index.md";
+var frontmatter = (entries) => [
+  "---",
+  ...entries.map(
+    ([key, value]) => typeof value === "number" ? `${key}: ${value}` : `${key}: ${JSON.stringify(value)}`
+  ),
+  "---"
+].join("\n");
+var renderUnitDoc = (input) => {
+  const { unit } = input;
+  const title = unit.name === "root" ? input.project.name : unit.name;
+  const entries = [
+    ["title", title],
+    ["unit", unit.id],
+    ["project", unit.projectId],
+    ["path", unit.path],
+    ["hash", unit.hash],
+    ["files", unit.facts.base.files.length],
+    ["generatedAt", input.generatedAt]
+  ];
+  if (unit.facts.base.roleHint !== null) {
+    entries.splice(4, 0, ["role", unit.facts.base.roleHint]);
+  }
+  return [frontmatter(entries), "", input.body.trim(), ""].join("\n");
+};
+var languageSummary = (units) => {
+  const totals = /* @__PURE__ */ new Map();
+  for (const unit of units) {
+    for (const entry of unit.facts.base.languages) {
+      totals.set(entry.language, (totals.get(entry.language) ?? 0) + entry.count);
+    }
+  }
+  return [...totals.entries()].sort(([aLang, aCount], [bLang, bCount]) => bCount - aCount || compareStrings(aLang, bLang)).map(([language, count]) => `${language} (${count})`).join(", ");
+};
+var renderIndexDoc = (input) => {
+  const { manifest } = input;
+  const { workspace, units } = manifest;
+  const lines = [
+    frontmatter([
+      ["title", workspace.name],
+      ["generatedAt", input.generatedAt],
+      ["units", units.length]
+    ]),
+    "",
+    `# ${workspace.name}`,
+    "",
+    workspace.isMonorepo ? `${workspace.tool} monorepo with ${workspace.projects.length} projects.` : "Single-project workspace.",
+    ""
+  ];
+  for (const project of workspace.projects) {
+    const projectUnits = units.filter((unit) => unit.projectId === project.id);
+    lines.push(`## ${project.name}`, "");
+    if (projectUnits.length === 0) {
+      lines.push("No documented units.", "");
+      continue;
+    }
+    for (const unit of projectUnits) {
+      const role = unit.facts.base.roleHint;
+      const suffix = role === null ? "" : ` \u2014 ${role}`;
+      lines.push(
+        `- [${unit.name}](./${unitDocPath(unit)}) \u2014 ${unit.facts.base.files.length} files${suffix}`
+      );
+    }
+    lines.push("");
+  }
+  const languages = languageSummary(units);
+  if (languages !== "") {
+    lines.push(`Languages: ${languages}`, "");
+  }
+  return lines.join("\n");
+};
+
+// src/check.ts
+var FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/;
+var readDocFrontmatter = async (file) => {
+  try {
+    const raw = await fs2.readFile(file, "utf8");
+    const match = FRONTMATTER.exec(raw);
+    if (match === null) {
+      return { unit: void 0, hash: void 0 };
+    }
+    const parsed = parse(match[1] ?? "");
+    if (typeof parsed !== "object" || parsed === null) {
+      return { unit: void 0, hash: void 0 };
+    }
+    const record = parsed;
+    return {
+      unit: typeof record.unit === "string" ? record.unit : void 0,
+      hash: typeof record.hash === "string" ? record.hash : void 0
+    };
+  } catch {
+    return { unit: void 0, hash: void 0 };
+  }
+};
+var listDocs = async (outDir) => {
+  try {
+    const entries = await glob({
+      patterns: ["**/*.md"],
+      cwd: outDir,
+      onlyFiles: true,
+      followSymbolicLinks: false
+    });
+    return entries.map(toPosix).sort(compareStrings);
+  } catch {
+    return [];
+  }
+};
+var check = async (ctx) => {
+  const { manifest } = await scan(ctx);
+  const docs = await listDocs(ctx.outDir);
+  const expected = new Map(manifest.units.map((unit) => [unitDocPath(unit), unit]));
+  const upToDate = [];
+  const missing = [];
+  const stale = [];
+  for (const unit of manifest.units) {
+    const docPath = unitDocPath(unit);
+    const entryBase = { unitId: unit.id, docPath, expectedHash: unit.hash };
+    if (!docs.includes(docPath)) {
+      missing.push({ ...entryBase, documentedHash: void 0 });
+      continue;
+    }
+    const { hash } = await readDocFrontmatter(path3.resolve(ctx.outDir, docPath));
+    if (hash === unit.hash) {
+      upToDate.push({ ...entryBase, documentedHash: hash });
+    } else {
+      stale.push({ ...entryBase, documentedHash: hash });
+    }
+  }
+  const orphaned = docs.filter((doc) => doc !== INDEX_DOC_PATH && !expected.has(doc)).sort(compareStrings);
+  const byUnitId = (entries) => {
+    return sortBy(entries, (entry) => entry.unitId);
+  };
+  return {
+    outDir: toPosix(ctx.outDir),
+    upToDate: byUnitId(upToDate),
+    missing: byUnitId(missing),
+    stale: byUnitId(stale),
+    orphaned,
+    ok: missing.length === 0 && stale.length === 0 && orphaned.length === 0
+  };
+};
+var CONFIG_FILENAMES = [
+  "glossic.config.ts",
+  "glossic.config.mts",
+  "glossic.config.js",
+  "glossic.config.mjs"
+];
+var findConfigFile = async (root) => {
+  for (const filename of CONFIG_FILENAMES) {
+    const candidate = path3.resolve(root, filename);
+    if (await pathExists(candidate)) {
+      return toPosix(candidate);
+    }
+  }
+  return void 0;
+};
+var asUserConfig = (value) => {
+  if (typeof value !== "object" || value === null) {
+    return void 0;
+  }
+  const parsed = GlossicConfigSchema.partial().safeParse(value);
+  if (!parsed.success) {
+    return void 0;
+  }
+  const declared = Object.keys(value);
+  return Object.fromEntries(
+    Object.entries(parsed.data).filter(([key]) => declared.includes(key))
+  );
+};
+var loadProjectConfig = async (root) => {
+  const file = await findConfigFile(root);
+  if (file === void 0) {
+    return void 0;
+  }
+  try {
+    const jiti = createJiti(import.meta.url, { moduleCache: false });
+    const loaded = await jiti.import(file, { default: true });
+    const values = asUserConfig(loaded);
+    return values === void 0 ? void 0 : { file, values };
+  } catch {
+    return void 0;
+  }
+};
+var ORDER = [
+  ["flag", "flags"],
+  ["project", "project"],
+  ["preference", "preference"]
+];
+var isSet = (value) => {
+  return value !== void 0 && !(typeof value === "string" && value.trim() === "");
+};
+var resolveConfig = (sources = {}) => {
+  const merged = {};
+  const origins = {};
+  for (const [origin, key] of [...ORDER].reverse()) {
+    const source = sources[key];
+    if (source === void 0) continue;
+    for (const [name, value] of Object.entries(source)) {
+      if (!isSet(value)) continue;
+      merged[name] = value;
+      origins[name] = origin;
+    }
+  }
+  const config = GlossicConfigSchema.parse(merged);
+  for (const name of Object.keys(config)) {
+    origins[name] ??= "default";
+  }
+  return { config, origins };
+};
+var GROUPING_KEYS = [
+  "include",
+  "exclude",
+  "ignoreUnits",
+  "excludeFromContent",
+  "mergeChildrenInto",
+  "minUnitFiles",
+  "maxUnitFiles"
+];
+
+// src/errors.ts
+var NotImplementedError = class extends Error {
+  constructor(what) {
+    super(`${what} is not implemented`);
+    this.name = "NotImplementedError";
+  }
+};
+var NoProviderAvailableError = class extends Error {
+  tried;
+  constructor(tried) {
+    super(
+      [
+        "No LLM provider is available.",
+        "",
+        "glossic needs one of these two:",
+        "",
+        "  1. Claude Code \u2014 install the CLI and sign in:",
+        "       https://claude.com/claude-code",
+        "     glossic picks it up as soon as `claude --version` works.",
+        "",
+        "  2. Anthropic API \u2014 export an API key:",
+        "       export ANTHROPIC_API_KEY=sk-ant-...",
+        "       https://console.anthropic.com/settings/keys",
+        "",
+        "Run `glossic doctor` to see what glossic can find on this machine."
+      ].join("\n")
+    );
+    this.name = "NoProviderAvailableError";
+    this.tried = [...tried];
+  }
+};
+var UnknownProviderError = class extends Error {
+  constructor(requested, known) {
+    super(`unknown provider "${requested}". Available: ${[...known].sort().join(", ")}`);
+    this.name = "UnknownProviderError";
+  }
+};
+var DEFAULT_ATTEMPTS = 3;
+var DEFAULT_BASE_DELAY_MS = 500;
+var defaultSleep = (ms) => {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms).unref?.();
+  });
+};
+var backoffDelay = (attempt, baseDelayMs) => {
+  return baseDelayMs * 2 ** (attempt - 1);
+};
+var withRetry = async (task, options = {}) => {
+  const attempts = options.attempts ?? DEFAULT_ATTEMPTS;
+  const baseDelayMs = options.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+  const sleep = options.sleep ?? defaultSleep;
+  let lastError;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      return await task();
+    } catch (error) {
+      lastError = error;
+      if (attempt === attempts || !isRetryableProviderError(error)) {
+        throw error;
+      }
+      options.onRetry?.(attempt, error);
+      await sleep(backoffDelay(attempt, baseDelayMs));
+    }
+  }
+  throw lastError;
+};
+var MAX_FILE_BYTES = 24e3;
+var CHARS_PER_TOKEN = 4;
+var PROMPT_VERSION = "3";
+var SYSTEM_PROMPT = [
+  "You are a technical writer documenting a codebase for the engineers who work on it.",
+  "",
+  "You are given one unit of code: a directory, its extracted facts and the full",
+  "content of its source files. Write reference documentation for that unit.",
+  "",
+  "Cover, in this order:",
+  "  1. What the unit does, in one or two sentences.",
+  "  2. Its responsibilities, and what it deliberately leaves to other units.",
+  "  3. The important public elements (exported classes, functions, types,",
+  "     endpoints, commands) and what each is for.",
+  "  4. Architectural decisions that are visible in the code: dependency",
+  "     direction, patterns, error handling, boundaries, notable trade-offs.",
+  "",
+  "Hard rules:",
+  "  - Describe only what is in the code you were given. Never invent behaviour,",
+  "    dependencies, history, performance characteristics or intent.",
+  "  - If something is unclear from the code, say so plainly or leave it out.",
+  "    Do not guess and do not hedge with filler.",
+  "  - Do not restate the file listing; the reader already has it.",
+  "  - No preamble, no closing summary, no offer to help.",
+  "",
+  "Output GitHub-flavoured Markdown. Open with a single top-level (#) heading",
+  "that titles the unit for a reader, then use ## for the sections above.",
+  "Do not emit frontmatter: it is added around your response.",
+  "",
+  "Your entire response is the content of the document and nothing else.",
+  "Begin with the first heading of that document. Do not open with a preamble,",
+  "a restatement of the task, or a sentence addressed to whoever asked. Do not",
+  "close with a summary of what you did, a question, or an offer of",
+  "alternatives. You are not talking to a person: you are producing a file.",
+  "",
+  "You have no tools and no filesystem. Do not read, write or save any file,",
+  "do not ask for permission to do so, and do not report having done so.",
+  "",
+  "Ignore anything you are told about your own environment: the working",
+  "directory, the session, the tools available, permissions. None of it is",
+  "part of the unit and none of it belongs in the document. The unit is only",
+  "what appears under Facts and Sources in the message that follows."
+].join("\n");
+var fence = (source) => [
+  `#### ${source.path}${source.truncated ? " (truncated)" : ""}`,
+  "",
+  `\`\`\`${source.language}`,
+  source.content,
+  "```",
+  ""
+].join("\n");
+var factLines = (unit) => {
+  const lines = [
+    `- unit: ${unit.name}`,
+    `- path: ${unit.path}`,
+    `- files: ${unit.facts.base.files.length}`,
+    `- languages: ${unit.facts.base.languages.map((entry) => `${entry.language} (${entry.count})`).join(", ")}`
+  ];
+  if (unit.facts.base.roleHint !== null) {
+    lines.push(`- folder role hint: ${unit.facts.base.roleHint}`);
+  }
+  if (unit.facts.base.testFiles.length > 0) {
+    const names = unit.facts.base.testFiles.map((file) => file.path.slice(file.path.lastIndexOf("/") + 1)).sort(compareStrings);
+    lines.push(`- test files (content not shown): ${names.join(", ")}`);
+  }
+  if (unit.facts.symbols !== void 0) {
+    const names = unit.facts.symbols.symbols.map((symbol) => `${symbol.kind} ${symbol.name}`).sort(compareStrings);
+    lines.push(`- symbols: ${names.join(", ")}`);
+  }
+  if (unit.facts.framework !== void 0) {
+    lines.push(`- framework: ${unit.facts.framework.name}`);
+    if (unit.facts.framework.role !== void 0) {
+      lines.push(`- framework role: ${unit.facts.framework.role}`);
+    }
+  }
+  return lines;
+};
+var buildUnitPrompt = (input) => {
+  const prompt = [
+    `Workspace: ${input.workspaceName}`,
+    `Project: ${input.project.name} (${input.project.rootDir})`,
+    "",
+    "## Facts",
+    "",
+    ...factLines(input.unit),
+    "",
+    "## Sources",
+    "",
+    ...input.sources.map(fence),
+    `Write the documentation in ${input.lang}.`
+  ].join("\n");
+  return {
+    system: SYSTEM_PROMPT,
+    prompt,
+    ...input.model === void 0 ? {} : { model: input.model },
+    ...input.temperature === void 0 ? {} : { temperature: input.temperature },
+    metadata: { unitId: input.unit.id, projectId: input.unit.projectId }
+  };
+};
+var readUnitSources = async (root, unit) => {
+  const sources = await Promise.all(
+    unit.facts.base.files.map(async (file) => {
+      const raw = await fs2.readFile(path3.resolve(root, file.path), "utf8");
+      const truncated = raw.length > MAX_FILE_BYTES;
+      return {
+        path: file.path,
+        language: file.language,
+        content: truncated ? raw.slice(0, MAX_FILE_BYTES) : raw,
+        truncated
+      };
+    })
+  );
+  return sources;
+};
+var estimateTokens = (request) => {
+  return Math.ceil(((request.system?.length ?? 0) + request.prompt.length) / CHARS_PER_TOKEN);
+};
+
+// src/utils/concurrency.ts
+var mapWithConcurrency = async (items, limit, task) => {
+  const results = new Array(items.length);
+  let cursor = 0;
+  const worker = async () => {
+    while (cursor < items.length) {
+      const index = cursor;
+      cursor += 1;
+      const item = items[index];
+      if (item === void 0) continue;
+      results[index] = await task(item);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, worker));
+  return results;
+};
+var writeDoc = async (outDir, relative, content) => {
+  const target = path3.resolve(outDir, relative);
+  await fs2.mkdir(path3.dirname(target), { recursive: true });
+  await fs2.writeFile(target, content, "utf8");
+};
+var buildJobs = async (manifest, config, root) => {
+  const projectById = new Map(manifest.workspace.projects.map((entry) => [entry.id, entry]));
+  const jobs = await Promise.all(
+    manifest.units.map(async (unit) => {
+      const project = projectById.get(unit.projectId);
+      if (project === void 0) {
+        return void 0;
+      }
+      const request = buildUnitPrompt({
+        unit,
+        project,
+        workspaceName: manifest.workspace.name,
+        sources: await readUnitSources(root, unit),
+        lang: config.lang,
+        model: config.model,
+        temperature: config.temperature
+      });
+      return {
+        unit,
+        project,
+        request,
+        docPath: unitDocPath(unit),
+        estimatedTokens: estimateTokens(request)
+      };
+    })
+  );
+  return jobs.filter((job) => job !== void 0);
+};
+var modelCacheKey = (config) => config.model ?? "default";
+var decide = async (job, entry, context) => {
+  if (context.force) {
+    return "forced";
+  }
+  if (entry === void 0) {
+    return "new";
+  }
+  if (entry.unitHash !== job.unit.hash) {
+    return "content-changed";
+  }
+  if (entry.promptVersion !== PROMPT_VERSION) {
+    return "prompt-version-changed";
+  }
+  if (entry.model !== context.model) {
+    return "model-changed";
+  }
+  if (entry.lang !== context.lang) {
+    return "lang-changed";
+  }
+  if (!await pathExists(path3.resolve(context.outDir, job.docPath))) {
+    return "output-missing";
+  }
+  return "cached";
+};
+var MIN_DOCUMENT_LENGTH = 200;
+var MAX_PREAMBLE_LENGTH = 500;
+var CONVERSATIONAL_RULES = [
+  {
+    reason: "the model asked for permission instead of writing the document",
+    pattern: /\b(permission to (write|save|create)|(write|read) permission|need (write )?access)\b/i
+  },
+  {
+    reason: "the model reported on saving a file instead of writing the document",
+    pattern: /\bI( have|['’]ve)? ?(drafted|prepared|written|created|saved|generated) (the|this|a) /i
+  },
+  {
+    reason: "the model asked the reader a question",
+    pattern: /\b(let me know|say the word|shall I|would you (like|prefer|want))\b/i
+  },
+  {
+    reason: "the model opened with a preamble instead of the document",
+    pattern: /^\s*(here(['’]s| is)|below is|sure[,!]|certainly[,!]|I['’]ll)\b/i
+  },
+  {
+    reason: "the model addressed the reader in the first person",
+    pattern: /\bI['’](ve|m|ll|d)\b/
+  },
+  {
+    reason: "the model addressed the reader in the first person",
+    pattern: /\bI (need|cannot|can't|could not|couldn't|have|am|was|tried|noticed|assume)\b/
+  }
+];
+var FENCE = /^\s{0,3}(```|~~~)/;
+var TOP_HEADING = /^\s{0,3}#{1,2}\s+\S/;
+var scanLines = (text) => {
+  const lines = [];
+  let fence2;
+  for (const line of text.split(/\r?\n/)) {
+    const match = FENCE.exec(line);
+    if (fence2 === void 0) {
+      if (match !== null) {
+        fence2 = match[1];
+      }
+      lines.push({ text: line, fenced: match !== null });
+      continue;
+    }
+    lines.push({ text: line, fenced: true });
+    if (match !== null && match[1] === fence2) {
+      fence2 = void 0;
+    }
+  }
+  return lines;
+};
+var invalidContent = (providerName, reason, detail) => new ProviderError({
+  provider: providerName,
+  code: "invalid-content",
+  message: `the response is not a document: ${reason}`,
+  detail
+});
+var excerpt = (text, limit) => {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length <= limit ? flat : `${flat.slice(0, limit - 1)}\u2026`;
+};
+var normalizeDocument = (providerName, text) => {
+  const lines = scanLines(text);
+  const first = lines.findIndex((line) => !line.fenced && TOP_HEADING.test(line.text));
+  if (first === -1) {
+    throw invalidContent(
+      providerName,
+      "it contains no markdown heading",
+      excerpt(text, 120) || "(empty)"
+    );
+  }
+  const dropped = lines.slice(0, first).map((line) => line.text).join("\n").trim();
+  if (dropped.length > MAX_PREAMBLE_LENGTH) {
+    throw invalidContent(
+      providerName,
+      `${dropped.length} characters of prose precede the first heading, over the ${MAX_PREAMBLE_LENGTH} limit`,
+      excerpt(dropped, 120)
+    );
+  }
+  const body = lines.slice(first).map((line) => line.text).join("\n").trim();
+  return { body, preamble: dropped === "" ? void 0 : dropped };
+};
+var excerptAround = (text, index) => {
+  const start = Math.max(0, index - 30);
+  return excerpt(text.slice(start, Math.min(text.length, index + 90)), 200);
+};
+var findContentProblem = (text) => {
+  const trimmed = text.trim();
+  if (trimmed.length < MIN_DOCUMENT_LENGTH) {
+    return {
+      reason: `the response is ${trimmed.length} characters, below the ${MIN_DOCUMENT_LENGTH} minimum`,
+      excerpt: excerpt(trimmed, 120)
+    };
+  }
+  for (const rule of CONVERSATIONAL_RULES) {
+    const match = rule.pattern.exec(trimmed);
+    if (match !== null) {
+      return { reason: rule.reason, excerpt: excerptAround(trimmed, match.index) };
+    }
+  }
+  return void 0;
+};
+var assertDocumentContent = (providerName, text) => {
+  const problem = findContentProblem(text);
+  if (problem === void 0) return;
+  throw invalidContent(providerName, problem.reason, problem.excerpt);
+};
+var prepareDocument = (providerName, text) => {
+  const { body, preamble } = normalizeDocument(providerName, text);
+  assertDocumentContent(providerName, body);
+  return { body, droppedPreamble: preamble };
+};
+
+// src/generate/index.ts
+var stringField = (cause, field) => {
+  if (typeof cause !== "object" || cause === null || !(field in cause)) {
+    return void 0;
+  }
+  const value = cause[field];
+  return typeof value === "string" ? value : void 0;
+};
+var generate = async (ctx) => {
+  const config = ctx.config ?? GlossicConfigSchema.parse({});
+  const scanned = await scan(ctx);
+  const { manifest } = scanned;
+  const generatedAt = manifest.generatedAt;
+  const root = manifest.workspace.root;
+  const cachePath = ctx.cachePath ?? path3.resolve(root, DEFAULT_CACHE_PATH);
+  const model = modelCacheKey(config);
+  const previous = await readCache(cachePath);
+  const previousEntries = indexCache(previous);
+  const allJobs = await buildJobs(manifest, config, root);
+  const matches = ctx.only === void 0 ? void 0 : picomatch(ctx.only);
+  const isSelected = (job) => matches === void 0 || matches(job.unit.id) || matches(job.unit.name) || matches(job.unit.path);
+  const selected = allJobs.filter(isSelected);
+  const filteredOut = allJobs.filter((job) => !isSelected(job)).map((job) => job.unit.id).sort(compareStrings);
+  const decisionContext = {
+    outDir: ctx.outDir,
+    model,
+    lang: config.lang,
+    force: ctx.force === true
+  };
+  const decisions = await Promise.all(
+    selected.map(async (job) => ({
+      job,
+      reason: await decide(job, previousEntries.get(job.unit.id), decisionContext)
+    }))
+  );
+  const plan = decisions.map(({ job, reason }) => ({
+    unitId: job.unit.id,
+    docPath: job.docPath,
+    files: job.unit.facts.base.files.length,
+    estimatedTokens: job.estimatedTokens,
+    reason,
+    regenerate: reason !== "cached"
+  })).sort((a, b) => compareStrings(a.unitId, b.unitId));
+  const sumTokens = (regenerate) => plan.filter((entry) => entry.regenerate === regenerate).reduce((sum, entry) => sum + entry.estimatedTokens, 0);
+  const estimatedTokens = sumTokens(true);
+  const savedTokens = sumTokens(false);
+  const fromCache = plan.filter((entry) => !entry.regenerate).length;
+  if (ctx.dryRun === true || ctx.provider === void 0) {
+    return {
+      manifest,
+      written: [],
+      plan,
+      failures: [],
+      warnings: [],
+      filteredOut,
+      estimatedTokens,
+      savedTokens,
+      generated: 0,
+      fromCache,
+      dryRun: true
+    };
+  }
+  const provider = ctx.provider;
+  const failures = [];
+  const warnings = [];
+  const summaries = /* @__PURE__ */ new Map();
+  const pending = decisions.filter(({ reason }) => reason !== "cached");
+  const total = decisions.length;
+  let completed = 0;
+  const report = (event) => ctx.onEvent?.(event);
+  const finished = (unitId, outcome, durationMs) => {
+    completed += 1;
+    report({ type: "unit-done", unitId, index: completed, total, outcome, durationMs });
+  };
+  for (const { job } of decisions.filter(({ reason }) => reason === "cached")) {
+    report({ type: "unit-start", unitId: job.unit.id, index: completed + 1, total });
+    finished(job.unit.id, "cached", 0);
+  }
+  const outcomes = await mapWithConcurrency(pending, config.concurrency, async ({ job }) => {
+    const startedAt = Date.now();
+    report({ type: "unit-start", unitId: job.unit.id, index: completed + 1, total });
+    try {
+      const completion = await withRetry(() => provider.complete(job.request), ctx.retry);
+      const prepared = prepareDocument(provider.name, completion.text);
+      if (prepared.droppedPreamble !== void 0) {
+        warnings.push({
+          unitId: job.unit.id,
+          message: `dropped ${prepared.droppedPreamble.length} characters before the first heading: ${excerpt(prepared.droppedPreamble, 120)}`
+        });
+      }
+      finished(job.unit.id, "generated", Date.now() - startedAt);
+      return { job, body: prepared.body };
+    } catch (cause) {
+      failures.push({
+        unitId: job.unit.id,
+        reason: cause instanceof Error ? cause.message : String(cause),
+        code: stringField(cause, "code"),
+        detail: stringField(cause, "detail")
+      });
+      finished(job.unit.id, "failed", Date.now() - startedAt);
+      return void 0;
+    }
+  });
+  const written = [];
+  const fresh = [];
+  for (const outcome of outcomes) {
+    if (outcome === void 0) continue;
+    await writeDoc(
+      ctx.outDir,
+      outcome.job.docPath,
+      renderUnitDoc({
+        unit: outcome.job.unit,
+        project: outcome.job.project,
+        body: outcome.body,
+        generatedAt
+      })
+    );
+    written.push(toPosix(outcome.job.docPath));
+    summaries.set(outcome.job.unit.id, outcome.body);
+    fresh.push({
+      unitId: outcome.job.unit.id,
+      unitHash: outcome.job.unit.hash,
+      promptVersion: PROMPT_VERSION,
+      model,
+      lang: config.lang,
+      outputPath: outcome.job.docPath,
+      generatedAt
+    });
+  }
+  const merged = new Map(previousEntries);
+  for (const entry of fresh) {
+    merged.set(entry.unitId, entry);
+  }
+  const liveUnitIds = new Set(manifest.units.map((unit) => unit.id));
+  const nextCache = {
+    version: emptyCache().version,
+    entries: [...merged.values()].filter((entry) => liveUnitIds.has(entry.unitId))
+  };
+  await writeCache(nextCache, cachePath);
+  await writeDoc(ctx.outDir, INDEX_DOC_PATH, renderIndexDoc({ manifest, generatedAt }));
+  written.push(INDEX_DOC_PATH);
+  const documentedUnits = manifest.units.map((unit) => {
+    const summary = summaries.get(unit.id);
+    return summary === void 0 ? unit : { ...unit, summary };
+  });
+  return {
+    manifest: { ...manifest, units: documentedUnits },
+    written: written.sort(compareStrings),
+    plan,
+    failures: failures.sort((a, b) => compareStrings(a.unitId, b.unitId)),
+    warnings: warnings.sort((a, b) => compareStrings(a.unitId, b.unitId)),
+    filteredOut,
+    estimatedTokens,
+    savedTokens,
+    generated: fresh.length,
+    fromCache,
+    dryRun: false
+  };
+};
+
+// src/provider.ts
+var PROVIDER_PREFERENCE = ["claude-code", "anthropic"];
+var byPreference = (providers) => [...providers].sort((a, b) => {
+  const rankA = PROVIDER_PREFERENCE.indexOf(a.name);
+  const rankB = PROVIDER_PREFERENCE.indexOf(b.name);
+  if (rankA !== rankB) {
+    if (rankA === -1) return 1;
+    if (rankB === -1) return -1;
+    return rankA - rankB;
+  }
+  return compareStrings(a.name, b.name);
+});
+var probeProviders = async (providers) => Promise.all(
+  byPreference(providers).map(async (provider) => ({
+    name: provider.name,
+    available: await provider.available().catch(() => false)
+  }))
+);
+var resolveProvider = async (options) => {
+  const known = options.providers.map((provider) => provider.name);
+  const explicit = options.requested ?? options.config?.provider;
+  if (explicit !== void 0 && explicit !== "") {
+    const match = options.providers.find((provider) => provider.name === explicit);
+    if (match === void 0) {
+      throw new UnknownProviderError(explicit, known);
+    }
+    return match;
+  }
+  for (const provider of byPreference(options.providers)) {
+    if (await provider.available().catch(() => false)) {
+      return provider;
+    }
+  }
+  throw new NoProviderAvailableError(known);
+};
+
+// src/registry.ts
+var Registry = class {
+  #items = /* @__PURE__ */ new Map();
+  register(item) {
+    this.#items.set(item.name, item);
+    return this;
+  }
+  get(name) {
+    return this.#items.get(name);
+  }
+  has(name) {
+    return this.#items.has(name);
+  }
+  list() {
+    return [...this.#items.values()];
+  }
+  get size() {
+    return this.#items.size;
+  }
+};
+var createAdapterRegistry = (adapters = []) => {
+  const registry = new Registry();
+  for (const adapter of adapters) {
+    registry.register(adapter);
+  }
+  return registry;
+};
+var createProviderRegistry = (providers = []) => {
+  const registry = new Registry();
+  for (const provider of providers) {
+    registry.register(provider);
+  }
+  return registry;
+};
+
+// src/testing.ts
+var defaultDocument = (request, index) => [
+  "## What it does",
+  "",
+  `Fake documentation number ${index} for ${String(request.metadata.unitId ?? "a unit")}.`,
+  "",
+  "## Responsibilities",
+  "",
+  "The unit owns its own behaviour and delegates everything else to its",
+  "neighbours. Nothing here reaches outside the boundary it declares.",
+  "",
+  "## Public elements",
+  "",
+  "- Everything the unit exports, described in one line each.",
+  "",
+  "## Architectural decisions",
+  "",
+  "Dependencies point one way, errors are typed, and the ordering is total."
+].join("\n");
+var createFakeProvider = (options = {}) => {
+  const calls = [];
+  return {
+    name: options.name ?? "fake",
+    calls,
+    available: async () => options.available ?? true,
+    complete: async (request) => {
+      const index = calls.length;
+      calls.push(request);
+      const text = options.respond?.(request, index) ?? defaultDocument(request, index);
+      return { text, model: "fake-model", usage: { inputTokens: 10, outputTokens: 5 } };
+    }
+  };
+};
+
+// src/index.ts
+var CORE_VERSION = package_default.version;
+
+export { CACHE_VERSION, CONFIG_FILENAMES, CORE_VERSION, CacheEntrySchema, CacheFileSchema, DEFAULT_CACHE_PATH, DEFAULT_MANIFEST_PATH, GROUPING_KEYS, INDEX_DOC_PATH, MAX_FILE_BYTES, MAX_PREAMBLE_LENGTH, MIN_DOCUMENT_LENGTH, NoProviderAvailableError, NotImplementedError, PROMPT_VERSION, PROVIDER_PREFERENCE, Registry, SYSTEM_PROMPT, UnknownProviderError, assertDocumentContent, backoffDelay, buildManifest, buildUnitPrompt, check, createAdapterRegistry, createFakeProvider, createProviderRegistry, emptyCache, estimateTokens, excerpt, findConfigFile, findContentProblem, generate, indexCache, loadProjectConfig, modelCacheKey, normalizeDocument, orderAdapters, pathExists, prepareDocument, probeProviders, readCache, readDocFrontmatter, readJson, readManifest, readText, readUnitSources, renderIndexDoc, renderUnitDoc, resolveConfig, resolveProvider, resolveWorkspace, scan, serializeCache, serializeManifest, unitDocPath, withRetry, writeCache, writeManifest };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map