diffwiki-core 0.12.0 → 0.13.0

package/dist/index.js

@@ -47,7 +47,7 @@ import {
   upsertPlugin,
   writePluginRegistry,
   writeRegistry
-} from "./chunk-MLUJY3HI.js";
+} from "./chunk-7V2DIQNL.js";
 
 // src/config.ts
 import fs from "fs/promises";
@@ -91,12 +91,20 @@ 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/slugify.ts
 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
 import matter from "gray-matter";
@@ -110,10 +118,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/;
@@ -158,8 +166,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 matter.stringify(article.body, front, MATTER_OPTS);
 }
 
@@ -168,7 +176,7 @@ import fs2 from "fs/promises";
 import path from "path";
 async function fireHook(event, collection, relPath) {
   try {
-    const { emitPluginEvent: emitPluginEvent2 } = await import("./events-UCJWB4WP.js");
+    const { emitPluginEvent: emitPluginEvent2 } = await import("./events-AVD3G5AX.js");
     await emitPluginEvent2(event, collection, relPath);
   } catch {
   }
@@ -205,18 +213,15 @@ async function resolveCollectionDir(name) {
 }
 function ensureMdPath(file) {
   if (/\.mdx?$/.test(file)) return file;
-  const dir = path.dirname(file);
-  const base = slugify(path.basename(file));
-  const rel = dir === "." ? `${base}.md` : path.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 = path.join(dir, `${slugify(title)}.md`);
+  const filePath = path.join(dir, `${slugifyPath(title)}.md`);
   const body = opts.body ?? `# ${title}
 `;
-  await fs2.mkdir(dir, { recursive: true });
+  await fs2.mkdir(path.dirname(filePath), { recursive: true });
   await fs2.writeFile(
     filePath,
     serializeArticle({ title, tags: opts.tags, body, audience: opts.audience, status: opts.status }),
@@ -562,6 +567,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 {
@@ -590,7 +602,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);
@@ -1080,8 +1096,12 @@ function localGraph(graph, focusId, include, siblingCap = 12) {
 
 // src/site.ts
 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,
@@ -1089,7 +1109,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,
@@ -1107,44 +1127,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) {
@@ -1267,12 +1293,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) {
@@ -1283,6 +1317,7 @@ async function nativeSearch(term, collections, collection) {
       let body = "";
       try {
         const parsed = parseArticle(await fs7.readFile(full, "utf8"));
+        if (hideSystem && parsed.audience === "system") continue;
         if (parsed.title) title = parsed.title;
         tags = parsed.tags;
         body = parsed.body;
@@ -1335,28 +1370,49 @@ async function resolveDefaultSearchMode() {
   }
   return { engine, type: searchTypes[0] };
 }
+async function dropSystemHits(hits) {
+  const kept = [];
+  for (const hit of hits) {
+    try {
+      if (parseArticle(await fs7.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 };
   }
 }
@@ -1380,6 +1436,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;
@@ -1407,6 +1464,7 @@ async function buildSearchIndex(collection) {
     try {
       const collEntry = await findCollection(e.name);
       const collDir = path8.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;
@@ -1739,6 +1797,151 @@ async function appendPluginDiagnostics(out, config) {
   }
 }
 
+// src/lint.ts
+import fs11 from "fs/promises";
+import path10 from "path";
+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 fs11.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const e of entries) {
+    const full = path10.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 = path10.relative(coll.path, full);
+      const label = `${coll.name}/${rel}`;
+      let findings = [];
+      try {
+        const parsed = parseArticle(await fs11.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/edit.ts
 async function resolveEditTarget(target, cwd) {
   if (target && target.trim()) {
@@ -1829,6 +2032,8 @@ export {
   installPlugin,
   invalidateLinkGraph,
   isLinkedWorktree,
+  lintArticle,
+  lintCollections,
   listArticleTree,
   listAvailablePlugins,
   listCollections,
@@ -1847,6 +2052,7 @@ export {
   rankDocs,
   readArticle,
   readConfig,
+  readContextCollections,
   readPluginRegistry,
   readProjectConfig,
   readRegistry,
@@ -1877,7 +2083,9 @@ export {
   setArticleMeta,
   setConfigValue,
   setTags,
+  showSystemEnabled,
   slugify,
+  slugifyPath,
   toTreeNodes,
   tokenize,
   unregisterCollection,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffwiki-core",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Core configuration, registry, and article management for diffwiki",
   "license": "MIT",
   "type": "module",