diffwiki-core 0.12.0 → 0.14.0-rc.202608012047.5d78e11

package/dist/{chunk-MLUJY3HI.js → chunk-B67AZFRA.js}

@@ -116,7 +116,7 @@ ${problems.map((p) => `  - ${p}`).join("\n")}`);
 // src/collections.ts
 async function fireHook(event, collection) {
   try {
-    const { emitPluginEvent: emitPluginEvent2 } = await import("./events-UCJWB4WP.js");
+    const { emitPluginEvent: emitPluginEvent2 } = await import("./events-QZYAWK7I.js");
     await emitPluginEvent2(event, collection);
   } catch {
   }
@@ -130,7 +130,7 @@ async function findCollection(name) {
 async function findCollectionById(id) {
   return (await readRegistry()).collections.find((c) => c.id === id);
 }
-async function createCollection(name) {
+async function createCollection(name, opts) {
   if (await findCollection(name)) throw new CollectionExistsError(name);
   const dir = collectionDir(name);
   await fs2.mkdir(dir, { recursive: true });
@@ -138,7 +138,8 @@ async function createCollection(name) {
     name,
     type: "global",
     path: dir,
-    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    ...opts?.audience ? { audience: opts.audience } : {}
   };
   await registerCollection(entry);
   void fireHook("collection-added", name);
@@ -350,7 +351,11 @@ function mapHits(result, collections) {
       tags: Array.isArray(h.tags) ? h.tags.filter((t) => typeof t === "string") : [],
       snippet: typeof h.snippet === "string" ? h.snippet : void 0,
       score: typeof h.score === "number" ? h.score : void 0,
-      docid: typeof h.docid === "string" ? h.docid : void 0
+      docid: typeof h.docid === "string" ? h.docid : void 0,
+      rawChunk: typeof h.rawChunk === "string" ? h.rawChunk : void 0,
+      cleanedChunk: typeof h.cleanedChunk === "string" ? h.cleanedChunk : void 0,
+      line: typeof h.line === "number" ? h.line : void 0,
+      snippetFromBody: h.snippetFromBody === true ? true : void 0
     });
   }
   return out;

package/dist/{events-UCJWB4WP.js → events-QZYAWK7I.js}

@@ -1,6 +1,6 @@
 import {
   emitPluginEvent
-} from "./chunk-MLUJY3HI.js";
+} from "./chunk-B67AZFRA.js";
 export {
   emitPluginEvent
 };

package/dist/index.cjs

@@ -359,7 +359,11 @@ function mapHits(result, collections) {
       tags: Array.isArray(h.tags) ? h.tags.filter((t) => typeof t === "string") : [],
       snippet: typeof h.snippet === "string" ? h.snippet : void 0,
       score: typeof h.score === "number" ? h.score : void 0,
-      docid: typeof h.docid === "string" ? h.docid : void 0
+      docid: typeof h.docid === "string" ? h.docid : void 0,
+      rawChunk: typeof h.rawChunk === "string" ? h.rawChunk : void 0,
+      cleanedChunk: typeof h.cleanedChunk === "string" ? h.cleanedChunk : void 0,
+      line: typeof h.line === "number" ? h.line : void 0,
+      snippetFromBody: h.snippetFromBody === true ? true : void 0
     });
   }
   return out;
@@ -523,7 +527,7 @@ async function findCollection(name) {
 async function findCollectionById(id) {
   return (await readRegistry()).collections.find((c) => c.id === id);
 }
-async function createCollection(name) {
+async function createCollection(name, opts) {
   if (await findCollection(name)) throw new CollectionExistsError(name);
   const dir = collectionDir(name);
   await import_promises3.default.mkdir(dir, { recursive: true });
@@ -531,7 +535,8 @@ async function createCollection(name) {
     name,
     type: "global",
     path: dir,
-    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    ...opts?.audience ? { audience: opts.audience } : {}
   };
   await registerCollection(entry);
   void fireHook("collection-added", name);
@@ -607,6 +612,8 @@ __export(index_exports, {
   installPlugin: () => installPlugin,
   invalidateLinkGraph: () => invalidateLinkGraph,
   isLinkedWorktree: () => isLinkedWorktree,
+  lintArticle: () => lintArticle,
+  lintCollections: () => lintCollections,
   listArticleTree: () => listArticleTree,
   listAvailablePlugins: () => listAvailablePlugins,
   listCollections: () => listCollections,
@@ -625,6 +632,7 @@ __export(index_exports, {
   rankDocs: () => rankDocs,
   readArticle: () => readArticle,
   readConfig: () => readConfig,
+  readContextCollections: () => readContextCollections,
   readPluginRegistry: () => readPluginRegistry,
   readProjectConfig: () => readProjectConfig,
   readRegistry: () => readRegistry,
@@ -655,7 +663,9 @@ __export(index_exports, {
   setArticleMeta: () => setArticleMeta,
   setConfigValue: () => setConfigValue,
   setTags: () => setTags,
+  showSystemEnabled: () => showSystemEnabled,
   slugify: () => slugify,
+  slugifyPath: () => slugifyPath,
   toTreeNodes: () => toTreeNodes,
   tokenize: () => tokenize,
   unregisterCollection: () => unregisterCollection,
@@ -718,6 +728,10 @@ async function getConfigValue(key) {
   const value = config[key];
   return typeof value === "string" ? value : void 0;
 }
+async function showSystemEnabled() {
+  const config = await readConfig();
+  return config.showSystem === true || config.showSystem === "true";
+}
 
 // src/index.ts
 init_registry();
@@ -727,6 +741,10 @@ function slugify(input) {
   const slug = input.toLowerCase().replace(/^#+\s*/, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80).replace(/-+$/g, "");
   return slug.length > 0 ? slug : "untitled";
 }
+function slugifyPath(input) {
+  const segs = input.split("/").map((s) => s.trim()).filter((s) => s.length > 0).map((s) => slugify(s));
+  return segs.length > 0 ? segs.join("/") : "untitled";
+}
 
 // src/frontmatter.ts
 var import_gray_matter = __toESM(require("gray-matter"), 1);
@@ -740,10 +758,10 @@ var YAML_ENGINE = {
 };
 var MATTER_OPTS = { engines: { yaml: YAML_ENGINE } };
 function coerceAudience(value) {
-  return value === "private" ? "private" : "public";
+  return value === "private" || value === "system" ? value : "public";
 }
 function coerceStatus(value) {
-  return value === "draft" ? "draft" : "published";
+  return value === "draft" || value === "deprecated" ? value : "published";
 }
 function parseFallback(raw) {
   const fenceRe = /^---[ \t]*\n([\s\S]*?)\n---[ \t]*\n/;
@@ -788,8 +806,8 @@ function parseArticle(raw) {
 }
 function serializeArticle(article) {
   const front = { title: article.title, tags: article.tags };
-  if (article.audience === "private") front.audience = "private";
-  if (article.status === "draft") front.status = "draft";
+  if (article.audience === "private" || article.audience === "system") front.audience = article.audience;
+  if (article.status === "draft" || article.status === "deprecated") front.status = article.status;
   return import_gray_matter.default.stringify(article.body, front, MATTER_OPTS);
 }
 
@@ -840,18 +858,15 @@ async function resolveCollectionDir(name) {
 }
 function ensureMdPath(file) {
   if (/\.mdx?$/.test(file)) return file;
-  const dir = import_node_path3.default.dirname(file);
-  const base = slugify(import_node_path3.default.basename(file));
-  const rel = dir === "." ? `${base}.md` : import_node_path3.default.join(dir, `${base}.md`);
-  return rel;
+  return `${slugifyPath(file)}.md`;
 }
 async function createArticle(opts) {
   const { collection, title } = parseAddTarget(opts.target);
   const { name, dir } = await resolveCollectionDir(collection);
-  const filePath = import_node_path3.default.join(dir, `${slugify(title)}.md`);
+  const filePath = import_node_path3.default.join(dir, `${slugifyPath(title)}.md`);
   const body = opts.body ?? `# ${title}
 `;
-  await import_promises5.default.mkdir(dir, { recursive: true });
+  await import_promises5.default.mkdir(import_node_path3.default.dirname(filePath), { recursive: true });
   await import_promises5.default.writeFile(
     filePath,
     serializeArticle({ title, tags: opts.tags, body, audience: opts.audience, status: opts.status }),
@@ -1201,6 +1216,13 @@ function normaliseSite(raw) {
     ...home !== void 0 ? { home } : {}
   };
 }
+function normaliseContext(raw) {
+  if (!raw || typeof raw !== "object") return void 0;
+  const r = raw;
+  if (!Array.isArray(r.collections)) return void 0;
+  const collections = r.collections.filter((c) => typeof c === "string");
+  return collections.length > 0 ? { collections } : void 0;
+}
 async function readProjectConfig(dir) {
   let raw;
   try {
@@ -1229,7 +1251,11 @@ async function readProjectConfig(dir) {
     collections.push({ name, path: parsed.path });
   }
   const site = normaliseSite(parsed.site);
-  return { ...site ? { site } : {}, collections };
+  const context = normaliseContext(parsed.context);
+  return { ...site ? { site } : {}, ...context ? { context } : {}, collections };
+}
+async function readContextCollections(dir) {
+  return (await readProjectConfig(dir))?.context?.collections ?? [];
 }
 async function resolveProjectCollections(dir) {
   const config = await readProjectConfig(dir);
@@ -1727,8 +1753,12 @@ function localGraph(graph, focusId, include, siblingCap = 12) {
 // src/site.ts
 init_errors();
 var isStatic = () => process.env.DIFFWIKI_STATIC === "1";
-function toTreeNodes(coll, nodes) {
-  const visible = isStatic() ? nodes.filter((n) => n.audience !== "private" && n.status !== "draft") : nodes;
+function toTreeNodes(coll, nodes, showSystem = false) {
+  const visible = nodes.filter((n) => {
+    if (!showSystem && n.audience === "system") return false;
+    if (isStatic() && (n.audience === "private" || n.status === "draft")) return false;
+    return true;
+  });
   return visible.map(
     (n) => n.children ? {
       name: n.name,
@@ -1736,7 +1766,7 @@ function toTreeNodes(coll, nodes) {
       path: n.slug ? `/${coll}/${n.slug}` : void 0,
       ...n.audience ? { audience: n.audience } : {},
       ...n.status ? { status: n.status } : {},
-      children: toTreeNodes(coll, n.children)
+      children: toTreeNodes(coll, n.children, showSystem)
     } : {
       name: n.name,
       title: n.title ?? n.name,
@@ -1754,44 +1784,50 @@ async function gitInfo(e) {
   const s = await collectionGitStatus(e);
   return s ? { branch: s.branch, behind: s.hasUpstream ? s.behind : void 0 } : {};
 }
-async function buildCollections() {
+async function buildCollections(opts) {
+  const showSystem = opts?.showSystem ?? false;
   const entries = await listCollections();
   const infos = await Promise.all(
     entries.map(async (e) => {
-      const { title, audience, status } = await collectionMeta(e.path);
+      const meta = await collectionMeta(e.path);
+      const audience = meta.audience ?? e.audience;
       return {
         name: e.name,
         type: e.type,
         path: e.path,
-        ...title ? { title } : {},
+        ...meta.title ? { title: meta.title } : {},
         ...await gitInfo(e),
         ...audience ? { audience } : {},
-        ...status ? { status } : {}
+        ...meta.status ? { status: meta.status } : {}
       };
     })
   );
-  return isStatic() ? infos.filter((c) => c.audience !== "private" && c.status !== "draft") : infos;
+  const visible = showSystem ? infos : infos.filter((c) => c.audience !== "system");
+  return isStatic() ? visible.filter((c) => c.audience !== "private" && c.status !== "draft") : visible;
 }
-async function buildNavTree() {
+async function buildNavTree(opts) {
+  const showSystem = opts?.showSystem ?? false;
   const entries = await listCollections();
   const trees = await Promise.all(
     entries.map(async (e) => {
-      const { title, audience, status } = await collectionMeta(e.path);
+      const meta = await collectionMeta(e.path);
+      const audience = meta.audience ?? e.audience;
       return {
         collection: {
           name: e.name,
           type: e.type,
           path: e.path,
-          ...title ? { title } : {},
+          ...meta.title ? { title: meta.title } : {},
           ...await gitInfo(e),
           ...audience ? { audience } : {},
-          ...status ? { status } : {}
+          ...meta.status ? { status: meta.status } : {}
         },
-        nodes: toTreeNodes(e.name, await listArticleTree(e.name))
+        nodes: toTreeNodes(e.name, await listArticleTree(e.name), showSystem)
       };
     })
   );
-  return isStatic() ? trees.filter((t) => t.collection.audience !== "private" && t.collection.status !== "draft") : trees;
+  const visible = showSystem ? trees : trees.filter((t) => t.collection.audience !== "system");
+  return isStatic() ? visible.filter((t) => t.collection.audience !== "private" && t.collection.status !== "draft") : visible;
 }
 function findNode(nodes, slug) {
   for (const n of nodes) {
@@ -1978,12 +2014,20 @@ async function collectMarkdownFiles(dir) {
   }
   return files;
 }
-async function nativeSearch(term, collections, collection) {
+function normalizeCollections(collection) {
+  if (collection === void 0) return [];
+  const names = Array.isArray(collection) ? collection : [collection];
+  return names.map((n) => n.trim()).filter(Boolean);
+}
+async function nativeSearch(term, collections, collection, hideSystem = false) {
   let targets = collections;
-  if (collection) {
-    const one = collections.find((c) => c.name === collection);
-    if (!one) throw new CollectionNotFoundError(collection);
-    targets = [one];
+  const names = normalizeCollections(collection);
+  if (names.length > 0) {
+    for (const n of names) {
+      if (!collections.some((c) => c.name === n)) throw new CollectionNotFoundError(n);
+    }
+    const wanted = new Set(names);
+    targets = collections.filter((c) => wanted.has(c.name));
   }
   const docs = [];
   for (const entry of targets) {
@@ -1994,6 +2038,7 @@ async function nativeSearch(term, collections, collection) {
       let body = "";
       try {
         const parsed = parseArticle(await import_promises10.default.readFile(full, "utf8"));
+        if (hideSystem && parsed.audience === "system") continue;
         if (parsed.title) title = parsed.title;
         tags = parsed.tags;
         body = parsed.body;
@@ -2046,28 +2091,49 @@ async function resolveDefaultSearchMode() {
   }
   return { engine, type: searchTypes[0] };
 }
+async function dropSystemHits(hits) {
+  const kept = [];
+  for (const hit of hits) {
+    try {
+      if (parseArticle(await import_promises10.default.readFile(hit.path, "utf8")).audience === "system") continue;
+    } catch {
+    }
+    kept.push(hit);
+  }
+  return kept;
+}
 async function search(term, opts) {
   const collections = await listCollections();
+  const wanted = normalizeCollections(opts?.collection);
+  for (const n of wanted) {
+    if (!collections.some((c) => c.name === n)) throw new CollectionNotFoundError(n);
+  }
+  const showSystem = opts?.showSystem ?? await showSystemEnabled();
+  const hideSystem = !showSystem && wanted.length === 0;
+  const searchable = hideSystem ? collections.filter((c) => c.audience !== "system") : collections;
+  const filterHits = (hits) => wanted.length > 0 ? hits.filter((h) => wanted.includes(h.collection)) : hits;
   const engine = opts?.engine ?? await resolveDefaultEngine();
   log2.debug(`resolved search engine "${engine}"`);
   if (engine === NATIVE_ENGINE) {
-    const hits = await nativeSearch(term, collections, opts?.collection);
+    const hits = await nativeSearch(term, searchable, opts?.collection, hideSystem);
     return { hits, engine, fellBackToNative: false };
   }
   const provider = await loadSearchProvider(engine);
   if (!provider) {
     const error = `no provider found for engine "${engine}"`;
     log2.warn(`engine "${engine}" unavailable, falling back to native: ${error}`);
-    const hits = await nativeSearch(term, collections, opts?.collection);
+    const hits = await nativeSearch(term, searchable, opts?.collection, hideSystem);
     return { hits, engine, fellBackToNative: true, error };
   }
   try {
-    const hits = await provider.handleSearch(term, collections, opts);
+    const providerOpts = { ...opts, collection: wanted.length === 1 ? wanted[0] : void 0 };
+    const raw = filterHits(await provider.handleSearch(term, searchable, providerOpts));
+    const hits = hideSystem ? await dropSystemHits(raw) : raw;
     return { hits, engine, fellBackToNative: false };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     log2.warn(`engine "${engine}" failed, falling back to native: ${message}`);
-    const hits = await nativeSearch(term, collections, opts?.collection);
+    const hits = await nativeSearch(term, searchable, opts?.collection, hideSystem);
     return { hits, engine, fellBackToNative: true, error: message };
   }
 }
@@ -2092,6 +2158,7 @@ async function readArticleParts(collDir, slug) {
 }
 async function flatten(coll, collDir, nodes, out) {
   for (const n of nodes) {
+    if (n.audience === "system") continue;
     if (isStatic2() && (n.audience === "private" || n.status === "draft")) continue;
     if (n.slug && !n.children) {
       const title = n.title ?? n.name;
@@ -2119,6 +2186,7 @@ async function buildSearchIndex(collection) {
     try {
       const collEntry = await findCollection(e.name);
       const collDir = import_node_path10.default.resolve(collEntry?.path ?? e.path);
+      if (collEntry?.audience === "system") continue;
       if (isStatic2()) {
         const cm = await collectionMeta(collDir);
         if (cm.audience === "private" || cm.status === "draft") continue;
@@ -2480,6 +2548,153 @@ async function appendPluginDiagnostics(out, config) {
   }
 }
 
+// src/lint.ts
+var import_promises14 = __toESM(require("fs/promises"), 1);
+var import_node_path13 = __toESM(require("path"), 1);
+init_collections();
+init_errors();
+var BUDGETS = {
+  recipe: { min: 300, max: 1e3 },
+  "recipe-steps": { min: 500, max: 1500 },
+  guide: { min: 1500, max: 5e3 },
+  "system-design": { min: 2e3, max: 6e3 },
+  "component-design": { min: 1e3, max: 3e3 },
+  // Fallback for a bare `architecture` tag when system vs component isn't declared.
+  architecture: { min: 1e3, max: 6e3 }
+};
+function estimateTokens(body) {
+  return Math.ceil(body.trim().length / 4);
+}
+function inferShape(tags, body) {
+  const t = new Set(tags.map((x) => x.toLowerCase()));
+  if (t.has("guide")) return "guide";
+  if (t.has("component-design") || t.has("component")) return "component-design";
+  if (t.has("system-design") || t.has("system")) return "system-design";
+  if (t.has("architecture")) return "architecture";
+  if (/^###\s+Step\b/im.test(body)) return "recipe-steps";
+  return "recipe";
+}
+function lintArticle(article) {
+  const findings = [];
+  const { title, tags, status, body } = article;
+  const shape = inferShape(tags, body);
+  const tokens = estimateTokens(body);
+  const budget = BUDGETS[shape];
+  if (!title || !title.trim()) {
+    findings.push({ level: "error", rule: "frontmatter-title", message: "missing frontmatter title" });
+  }
+  if (tags.map((x) => x.toLowerCase()).includes("diffwiki-template")) {
+    findings.push({
+      level: "error",
+      rule: "template-tag-leak",
+      message: "instance still tagged diffwiki-template"
+    });
+  }
+  if (tags.length === 0) {
+    findings.push({ level: "warn", rule: "no-tags", message: "no tags -- add topic tags for recall" });
+  }
+  const hasRefsSection = /^##\s+References\b/im.test(body);
+  const hasInlineLink = /\]\([^)]+\)/.test(body);
+  if (!hasRefsSection && !hasInlineLink) {
+    findings.push({
+      level: "error",
+      rule: "no-references",
+      message: "has no ## References section and no inline links"
+    });
+  }
+  if ((shape === "guide" || shape === "architecture") && !hasRefsSection) {
+    findings.push({
+      level: "warn",
+      rule: "missing-references-section",
+      message: `${shape} should end with a ## References section`
+    });
+  }
+  if (tokens > budget.max) {
+    findings.push({
+      level: "error",
+      rule: "token-budget",
+      message: `body ~${tokens} tokens exceeds ${shape} budget (${budget.max})`
+    });
+  } else if (tokens < budget.min) {
+    findings.push({
+      level: "warn",
+      rule: "token-thin",
+      message: `body ~${tokens} tokens is thin for ${shape} (min ${budget.min})`
+    });
+  }
+  if (status === "draft") {
+    findings.push({ level: "warn", rule: "status-draft", message: "status is still draft" });
+  }
+  if (/\*\*Load when:\*\*/i.test(body)) {
+    findings.push({
+      level: "warn",
+      rule: "load-when-prefix",
+      message: "remove the **Load when:** prefix (implicit trigger)"
+    });
+  }
+  if (/^[A-Za-z0-9][\w .+-]*:\s/.test(title)) {
+    findings.push({ level: "warn", rule: "title-prefix", message: `title "${title}" repeats a path-like prefix` });
+  }
+  return findings;
+}
+async function walkMarkdown(dir) {
+  let entries;
+  try {
+    entries = await import_promises14.default.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const e of entries) {
+    const full = import_node_path13.default.join(dir, e.name);
+    if (e.isDirectory()) out.push(...await walkMarkdown(full));
+    else if (e.isFile() && /\.mdx?$/.test(e.name) && !/-template\.mdx?$/.test(e.name)) out.push(full);
+  }
+  return out;
+}
+async function resolveScope(scope) {
+  const all = await listCollections();
+  if (scope === "all") return all.filter((c) => c.audience !== "system");
+  if (scope === "current") {
+    const cur = await resolveCwdCollection(process.cwd());
+    if (!cur) throw new Error("No collection for the current directory -- pass -c <name> or -c all.");
+    return [cur];
+  }
+  const names = scope.split(",").map((s) => s.trim()).filter(Boolean);
+  const chosen = [];
+  for (const n of names) {
+    const hit = all.find((c) => c.name === n);
+    if (!hit) throw new CollectionNotFoundError(n);
+    chosen.push(hit);
+  }
+  return chosen;
+}
+async function lintCollections(scope) {
+  const collections = await resolveScope(scope);
+  const files = [];
+  let errorCount = 0;
+  let warnCount = 0;
+  for (const coll of collections) {
+    for (const full of await walkMarkdown(coll.path)) {
+      const rel = import_node_path13.default.relative(coll.path, full);
+      const label = `${coll.name}/${rel}`;
+      let findings = [];
+      try {
+        const parsed = parseArticle(await import_promises14.default.readFile(full, "utf8"));
+        findings = lintArticle(parsed);
+      } catch (err) {
+        findings = [{ level: "error", rule: "parse", message: `could not parse: ${err.message}` }];
+      }
+      for (const f of findings) {
+        if (f.level === "error") errorCount++;
+        else warnCount++;
+      }
+      files.push({ path: label, findings });
+    }
+  }
+  return { files, fileCount: files.length, errorCount, warnCount };
+}
+
 // src/index.ts
 init_logger();
 
@@ -2584,6 +2799,8 @@ init_registry2();
   installPlugin,
   invalidateLinkGraph,
   isLinkedWorktree,
+  lintArticle,
+  lintCollections,
   listArticleTree,
   listAvailablePlugins,
   listCollections,
@@ -2602,6 +2819,7 @@ init_registry2();
   rankDocs,
   readArticle,
   readConfig,
+  readContextCollections,
   readPluginRegistry,
   readProjectConfig,
   readRegistry,
@@ -2632,7 +2850,9 @@ init_registry2();
   setArticleMeta,
   setConfigValue,
   setTags,
+  showSystemEnabled,
   slugify,
+  slugifyPath,
   toTreeNodes,
   tokenize,
   unregisterCollection,