docspack 0.2.0 → 0.3.0

package/dist/verify.js

@@ -4,7 +4,7 @@ import { readBuildConfig } from "./config.js";
 import { discoverPackages, resolvePackageDir } from "./discovery.js";
 import { DocspackError } from "./errors.js";
 import { readExportSurface } from "./exports.js";
-import { chunkId, LLMS_DIR, MANIFEST_FILE, parseManifest } from "./spec.js";
+import { chunkId, formatDocumentedLibrary, LLMS_DIR, MANIFEST_FILE, parseDocumentedLibrary, parseManifest, } from "./spec.js";
 /** Below this length a name is too generic to reason about. */
 const MIN_SYMBOL = 4;
 /**
@@ -125,28 +125,39 @@ async function verifyOne(cwd, packageDir) {
 }
 async function verifyPackage(cwd, id, packageDir, manifest) {
     const empty = { id, checked: 0, matched: 0, unrecognised: 0, findings: [] };
-    const { documents } = await readBuildConfig(packageDir);
-    if (documents === undefined) {
+    const declaredLibraries = await documentedLibraries(packageDir, manifest);
+    if (declaredLibraries.length === 0) {
         return {
             ...empty,
             status: "skipped",
-            reason: `declares no "docspack.documents", so there is nothing to check against`,
+            reason: `declares no "documents", so there is nothing to check against`,
         };
     }
-    const libraryDir = (await resolvePackageDir(documents, packageDir)) ?? (await resolvePackageDir(documents, cwd));
-    if (libraryDir === undefined) {
-        return { ...empty, status: "skipped", documents, reason: `${documents} is not installed` };
+    const documents = declaredLibraries.map(formatDocumentedLibrary);
+    // An entity is fine if any documented library declares it: a monorepo documents eighteen
+    // packages from one surface, and a name belongs to whichever of them exports it.
+    const names = new Set();
+    const missing = [];
+    for (const library of declaredLibraries) {
+        const libraryDir = (await resolvePackageDir(library.name, packageDir)) ??
+            (await resolvePackageDir(library.name, cwd));
+        const surface = libraryDir === undefined ? undefined : await readExportSurface(libraryDir);
+        if (surface === undefined || surface.names.size === 0) {
+            missing.push(library.name);
+            continue;
+        }
+        for (const name of surface.names)
+            names.add(name);
     }
-    const surface = await readExportSurface(libraryDir);
-    if (surface === undefined || surface.names.size === 0) {
+    if (names.size === 0) {
         return {
             ...empty,
             status: "skipped",
             documents,
-            reason: `${documents} ships no type declarations to check against`,
+            reason: `${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} not installed, or ship no type declarations`,
         };
     }
-    const declared = new Set([...surface.names].map(normalize));
+    const declared = new Set([...names].map(normalize));
     const findings = [];
     let checked = 0;
     let matched = 0;
@@ -163,7 +174,7 @@ async function verifyPackage(cwd, id, packageDir, manifest) {
                 matched += 1;
                 continue;
             }
-            const suggestion = nearestName(symbol, surface);
+            const suggestion = nearestName(symbol, names);
             if (suggestion === undefined) {
                 unrecognised += 1;
                 continue;
@@ -177,7 +188,29 @@ async function verifyPackage(cwd, id, packageDir, manifest) {
             });
         }
     }
-    return { id, status: "verified", documents, checked, matched, unrecognised, findings };
+    return {
+        id,
+        status: "verified",
+        documents,
+        ...(missing.length === 0 ? {} : { unchecked: missing }),
+        checked,
+        matched,
+        unrecognised,
+        findings,
+    };
+}
+/**
+ * What a package says it documents.
+ *
+ * The manifest is the answer when it carries one, because that is the only copy a consumer of an
+ * installed package can see. The `docspack` key is read as a fallback: it is build configuration
+ * rather than payload, and a package built before `documents` reached the manifest has only that.
+ */
+async function documentedLibraries(packageDir, manifest) {
+    if (manifest.documents !== undefined && manifest.documents.length > 0)
+        return manifest.documents;
+    const { documents } = await readBuildConfig(packageDir);
+    return (documents ?? []).map(parseDocumentedLibrary);
 }
 /**
  * The name worth checking in an entity like `client.setKey()`, or nothing when the entity is
@@ -211,12 +244,12 @@ function normalize(name) {
  * is left alone. In particular a differing first word is never a match: `includeLanguages` and
  * `excludeLanguages` are two edits apart and mean opposite things.
  */
-function nearestName(symbol, surface) {
+function nearestName(symbol, names) {
     const lower = normalize(symbol);
     const words = camelWords(symbol);
     let best;
     let bestDistance = Number.POSITIVE_INFINITY;
-    for (const candidate of surface.names) {
+    for (const candidate of names) {
         if (candidate.length < MIN_SYMBOL)
             continue;
         const candidateWords = camelWords(candidate);

package/dist/verify.js.map

@@ -1 +1 @@
-{"version":3,"file":"verify.js","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EACL,OAAO,EAEP,uBAAuB,EACvB,QAAQ,EACR,aAAa,EAEb,sBAAsB,EACtB,aAAa,GACd,MAAM,WAAW,CAAC;AA+CnB,+DAA+D;AAC/D,MAAM,UAAU,GAAG,CAAC,CAAC;AAErB;;;GAGG;AACH,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC;IACxB,SAAS;IACT,KAAK;IACL,OAAO;IACP,MAAM;IACN,MAAM;IACN,OAAO;IACP,SAAS;IACT,OAAO;IACP,OAAO;IACP,MAAM;IACN,WAAW;IACX,OAAO;IACP,QAAQ;IACR,SAAS;IACT,KAAK;IACL,QAAQ;IACR,SAAS;IACT,SAAS;IACT,QAAQ;IACR,SAAS;IACT,QAAQ;IACR,UAAU;IACV,OAAO;IACP,UAAU;IACV,SAAS;CACV,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC;IACvB,OAAO;IACP,QAAQ;IACR,SAAS;IACT,QAAQ;IACR,UAAU;IACV,IAAI;IACJ,QAAQ;IACR,YAAY;IACZ,MAAM;IACN,MAAM;IACN,MAAM;IACN,WAAW;IACX,QAAQ;IACR,QAAQ;IACR,IAAI;IACJ,MAAM;IACN,SAAS;IACT,SAAS;IACT,SAAS;IACT,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,KAAK;IACL,QAAQ;CACT,CAAC,CAAC;AAEH,0FAA0F;AAC1F,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC;IACzB,KAAK;IACL,KAAK;IACL,MAAM;IACN,IAAI;IACJ,MAAM;IACN,OAAO;IACP,MAAM;IACN,IAAI;IACJ,KAAK;IACL,KAAK;IACL,MAAM;IACN,IAAI;IACJ,KAAK;IACL,KAAK;IACL,MAAM;IACN,KAAK;CACN,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAsB;IACxD,MAAM,QAAQ,GACZ,OAAO,CAAC,UAAU,KAAK,SAAS;QAC9B,CAAC,CAAC,MAAM,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC;QACpC,CAAC,CAAC,CAAC,MAAM,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;IAEzD,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;AAC9E,CAAC;AAED,KAAK,UAAU,eAAe,CAAC,GAAW;IACxC,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACjD,MAAM,OAAO,GAAsB,EAAE,CAAC;IAEtC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,OAAO,CAAC,IAAI,CAAC,MAAM,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC;IACxE,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,KAAK,UAAU,SAAS,CAAC,GAAW,EAAE,UAAkB;IACtD,IAAI,QAAyB,CAAC;IAC9B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,EAAE,aAAa,CAAC,EAAE,MAAM,CAAC,CAAC;QAC9E,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,GAAG,QAAQ,IAAI,aAAa,EAAE,CAAC,CAAC;IAC5E,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,aAAa,CAAC,MAAM,QAAQ,IAAI,aAAa,OAAO,UAAU,EAAE,EAAE;YAC1E,IAAI,EAAE,6BAA6B;SACpC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,aAAa,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,IAAI,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;AAC1F,CAAC;AAED,KAAK,UAAU,aAAa,CAC1B,GAAW,EACX,EAAU,EACV,UAAkB,EAClB,QAAyB;IAEzB,MAAM,KAAK,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAE5E,MAAM,iBAAiB,GAAG,MAAM,mBAAmB,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IAC1E,IAAI,iBAAiB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnC,OAAO;YACL,GAAG,KAAK;YACR,MAAM,EAAE,SAAS;YACjB,MAAM,EAAE,+DAA+D;SACxE,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,iBAAiB,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;IACjE,yFAAyF;IACzF,iFAAiF;IACjF,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,OAAO,IAAI,iBAAiB,EAAE,CAAC;QACxC,MAAM,UAAU,GACd,CAAC,MAAM,iBAAiB,CAAC,OAAO,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;YACnD,CAAC,MAAM,iBAAiB,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;QAC/C,MAAM,OAAO,GAAG,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,iBAAiB,CAAC,UAAU,CAAC,CAAC;QAC3F,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACtD,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC3B,SAAS;QACX,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK;YAAE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpD,CAAC;IAED,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO;YACL,GAAG,KAAK;YACR,MAAM,EAAE,SAAS;YACjB,SAAS;YACT,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,8CAA8C;SACnH,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;IACpD,MAAM,QAAQ,GAAmB,EAAE,CAAC;IACpC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,YAAY,GAAG,CAAC,CAAC;IAErB,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;QACpC,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YACpC,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;YACvC,IAAI,MAAM,KAAK,SAAS;gBAAE,SAAS;YAEnC,OAAO,IAAI,CAAC,CAAC;YACb,mFAAmF;YACnF,+CAA+C;YAC/C,IAAI,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;gBACpC,OAAO,IAAI,CAAC,CAAC;gBACb,SAAS;YACX,CAAC;YAED,MAAM,UAAU,GAAG,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YAC9C,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;gBAC7B,YAAY,IAAI,CAAC,CAAC;gBAClB,SAAS;YACX,CAAC;YAED,QAAQ,CAAC,IAAI,CAAC;gBACZ,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,CAAC;gBAC9B,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,MAAM;gBACN,MAAM;gBACN,UAAU;aACX,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO;QACL,EAAE;QACF,MAAM,EAAE,UAAU;QAClB,SAAS;QACT,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;QACvD,OAAO;QACP,OAAO;QACP,YAAY;QACZ,QAAQ;KACT,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,mBAAmB,CAChC,UAAkB,EAClB,QAAyB;IAEzB,IAAI,QAAQ,CAAC,SAAS,KAAK,SAAS,IAAI,QAAQ,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAC,SAAS,CAAC;IACjG,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,eAAe,CAAC,UAAU,CAAC,CAAC;IACxD,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;AACvD,CAAC;AAED;;;GAGG;AACH,SAAS,eAAe,CAAC,MAAc;IACrC,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,MAAM,CAAC;IACjD,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAEzE,IAAI,MAAM,CAAC,MAAM,GAAG,UAAU;QAAE,OAAO,SAAS,CAAC;IACjD,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3D,IAAI,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1D,IAAI,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3D,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,wFAAwF;AACxF,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;AAC/C,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,WAAW,CAAC,MAAc,EAAE,KAA0B;IAC7D,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IACjC,IAAI,IAAwB,CAAC;IAC7B,IAAI,YAAY,GAAG,MAAM,CAAC,iBAAiB,CAAC;IAE5C,KAAK,MAAM,SAAS,IAAI,KAAK,EAAE,CAAC;QAC9B,IAAI,SAAS,CAAC,MAAM,GAAG,UAAU;YAAE,SAAS;QAC5C,MAAM,cAAc,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;QAC7C,IAAI,aAAa,CAAC,KAAK,EAAE,cAAc,CAAC;YAAE,OAAO,SAAS,CAAC;QAE3D,IAAI,cAAc,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC;YAAE,SAAS;QAC7C,MAAM,KAAK,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;QACnC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC;YAAE,SAAS;QAExD,MAAM,QAAQ,GAAG,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QAC/C,IAAI,QAAQ,GAAG,YAAY,EAAE,CAAC;YAC5B,YAAY,GAAG,QAAQ,CAAC;YACxB,IAAI,GAAG,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED,IAAI,IAAI,KAAK,SAAS,IAAI,YAAY,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC7D,8FAA8F;IAC9F,IAAI,YAAY,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,mDAAmD;AACnD,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,IAAI;SACR,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;SACtC,KAAK,CAAC,UAAU,CAAC;SACjB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;SACjC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;AACvC,CAAC;AAED;;;;GAIG;AACH,SAAS,aAAa,CAAC,CAAoB,EAAE,CAAoB;IAC/D,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACjE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxE,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3C,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAE5E,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;QAC1B,IAAI,IAAI,KAAK,OAAO,CAAC,KAAK,CAAC;YAAE,KAAK,IAAI,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,KAAK,KAAK,OAAO,CAAC,MAAM,CAAC;AAClC,CAAC;AAED,8DAA8D;AAC9D,SAAS,YAAY,CAAC,CAAS,EAAE,CAAS,EAAE,KAAa;IACvD,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,GAAG,KAAK;QAAE,OAAO,KAAK,GAAG,CAAC,CAAC;IAE5D,IAAI,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;IACzE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACtC,MAAM,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CACpB,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,EACzB,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,EACtB,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAC9B,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACpB,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACrC,CAAC;QACD,IAAI,OAAO,GAAG,KAAK;YAAE,OAAO,KAAK,GAAG,CAAC,CAAC;QACtC,QAAQ,GAAG,OAAO,CAAC;IACrB,CAAC;IACD,OAAO,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC;AACzC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docspack",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Local, version-locked documentation packages for AI agents, indexed in SQLite and served over MCP.",
   "keywords": [
     "ai",

package/src/build.ts

@@ -11,11 +11,14 @@ import { fetchableLinks, parseLlmsTxt } from "./llms-txt.js";
 import {
   CHUNKS_DIR,
   type ChunkSpec,
+  type DocumentedLibrary,
   estimateTokens,
   LLMS_DIR,
   MANIFEST_FILE,
+  parseDocumentedLibrary,
   serializeManifest,
 } from "./spec.js";
+import { STOPWORDS } from "./stopwords.js";
 
 export interface BuildOptions {
   /** Directory the docs package is written to. */
@@ -30,6 +33,14 @@ export interface BuildOptions {
   readonly source?: string;
   readonly pages?: number;
   readonly maxChunkTokens?: number;
+  /**
+   * Merge adjacent sections until a chunk reaches this size, never crossing `maxChunkTokens`.
+   * Off unless set: splitting at every heading is right for prose, and wrong only for generated
+   * reference, where a heading is a field name.
+   */
+  readonly minChunkTokens?: number;
+  /** Libraries this package documents, each `name` or `name@version`. Recorded in the manifest. */
+  readonly documents?: readonly string[];
   readonly http?: HttpClient;
   readonly onProgress?: (message: string) => void;
 }
@@ -76,7 +87,14 @@ export async function buildPackage(input: BuildOptions): Promise<BuildResult> {
   }
 
   const maxTokens = options.maxChunkTokens ?? DEFAULT_MAX_CHUNK_TOKENS;
-  const { chunks, files } = chunkDocuments(documents, maxTokens);
+  const minTokens = options.minChunkTokens;
+  if (minTokens !== undefined && minTokens > maxTokens) {
+    throw new DocspackError(
+      `minChunkTokens (${minTokens}) is larger than maxChunkTokens (${maxTokens})`,
+      { hint: "A chunk cannot be required to be bigger than it is allowed to be." },
+    );
+  }
+  const { chunks, files } = chunkDocuments(documents, maxTokens, minTokens);
 
   const llmsDir = join(options.out, LLMS_DIR);
   await rm(llmsDir, { recursive: true, force: true });
@@ -85,9 +103,15 @@ export async function buildPackage(input: BuildOptions): Promise<BuildResult> {
   for (const file of files) {
     await writeFile(join(llmsDir, file.path), file.contents, "utf8");
   }
+  const libraries: DocumentedLibrary[] = (options.documents ?? []).map(parseDocumentedLibrary);
   await writeFile(
     join(llmsDir, MANIFEST_FILE),
-    serializeManifest({ name: identity.name, version: identity.version, chunks }),
+    serializeManifest({
+      name: identity.name,
+      version: identity.version,
+      ...(libraries.length === 0 ? {} : { documents: libraries }),
+      chunks,
+    }),
     "utf8",
   );
   await writeFile(join(options.out, "llms.txt"), renderLlmsTxt(identity.name, chunks), "utf8");
@@ -114,7 +138,7 @@ export async function buildPackage(input: BuildOptions): Promise<BuildResult> {
     version: identity.version,
     dir: options.out,
     chunks: chunks.length,
-    tokens: chunks.reduce((total, chunk) => total + chunk.tokens, 0),
+    tokens: chunks.reduce((total, chunk) => total + (chunk.tokens ?? 0), 0),
     warnings,
   };
 }
@@ -142,6 +166,12 @@ async function withConfig(options: BuildOptions): Promise<BuildOptions> {
     ...(options.maxChunkTokens === undefined && config.maxChunkTokens !== undefined
       ? { maxChunkTokens: config.maxChunkTokens }
       : {}),
+    ...(options.minChunkTokens === undefined && config.minChunkTokens !== undefined
+      ? { minChunkTokens: config.minChunkTokens }
+      : {}),
+    ...(options.documents === undefined && config.documents !== undefined
+      ? { documents: config.documents }
+      : {}),
     ...(options.pages === undefined && config.pages !== undefined ? { pages: config.pages } : {}),
   };
 }
@@ -396,16 +426,18 @@ function renderOperation(
 function chunkDocuments(
   documents: readonly SourceDocument[],
   maxTokens: number,
+  minTokens: number | undefined,
 ): { chunks: ChunkSpec[]; files: { path: string; contents: string }[] } {
   const chunks: ChunkSpec[] = [];
   const files: { path: string; contents: string }[] = [];
   const taken = new Set<string>();
 
   for (const document of documents) {
+    const text = collapseTablePadding(document.text);
     const sections =
       document.atomic === true
-        ? [{ heading: document.title, body: document.text }]
-        : splitMarkdown(document.text, document.title, maxTokens);
+        ? [{ heading: document.title, body: text, level: 0 }]
+        : splitMarkdown(text, document.title, maxTokens, minTokens);
 
     for (const section of sections) {
       const directives = readDirectives(section.body);
@@ -419,11 +451,9 @@ function chunkDocuments(
         id,
         file,
         tokens: estimateTokens(contents),
-        // Directive tags first: they are the author aiming one chunk, and `uniqueWords` caps.
-        tags: uniqueWords([
-          ...directives.tags,
+        tags: chunkTags(directives.tags, [
           document.title,
-          section.heading,
+          ...(section.headings ?? [section.heading]),
           ...(document.tags ?? []),
         ]),
         entities: [
@@ -440,17 +470,35 @@ function chunkDocuments(
   return { chunks, files };
 }
 
+/** One piece of a document, before it becomes a chunk. */
+interface Section {
+  readonly heading: string;
+  readonly body: string;
+  /** Depth of the heading in the source, or 0 when it was inherited rather than written. */
+  readonly level: number;
+  /**
+   * Headings to index as tags, when they are not just `heading`. A packed chunk answers for every
+   * section in it, so all of their headings are search terms for it.
+   */
+  readonly headings?: readonly string[];
+}
+
 /**
  * Splits Markdown at `##` headings, then `###`, then paragraphs, until every piece fits the token
  * budget. Retrieval works best when a chunk answers one question.
+ *
+ * With `minTokens` set, adjacent pieces are then packed back together up to the budget. Every
+ * API generator emits pages whose headings are field names — `Category` is one line, `Sizes` is
+ * three — and one chunk per heading there is hundreds of chunks too small to answer anything.
  */
 function splitMarkdown(
   text: string,
   title: string,
   maxTokens: number,
-): { heading: string; body: string }[] {
-  const sections = splitAtLevel(text, 2, title);
-  const result: { heading: string; body: string }[] = [];
+  minTokens: number | undefined,
+): Section[] {
+  const sections = splitAtLevel(text, 2, title, 0);
+  const result: Section[] = [];
 
   for (const section of sections) {
     if (estimateTokens(section.body) <= maxTokens) {
@@ -458,7 +506,7 @@ function splitMarkdown(
       continue;
     }
 
-    const deeper = splitAtLevel(section.body, 3, section.heading);
+    const deeper = splitAtLevel(section.body, 3, section.heading, section.level);
     for (const part of deeper) {
       if (estimateTokens(part.body) <= maxTokens) {
         if (part.body.trim().length > 0) result.push(part);
@@ -468,22 +516,26 @@ function splitMarkdown(
         ...splitParagraphs(part.body, maxTokens).map((body, index) => ({
           heading: index === 0 ? part.heading : `${part.heading} (${index + 1})`,
           body,
+          // A continuation carries no heading of its own, so packing must not re-emit one.
+          level: index === 0 ? part.level : 0,
         })),
       );
     }
   }
 
-  return result.length > 0 ? result : [{ heading: title, body: text }];
+  const pieces = result.length > 0 ? result : [{ heading: title, body: text, level: 0 }];
+  return minTokens === undefined ? pieces : packSections(pieces, title, minTokens, maxTokens);
 }
 
 function splitAtLevel(
   text: string,
   level: number,
   fallbackHeading: string,
-): { heading: string; body: string }[] {
+  fallbackLevel: number,
+): Section[] {
   const marker = new RegExp(`^#{${level}}\\s+(.+?)\\s*$`);
-  const sections: { heading: string; body: string[] }[] = [];
-  let current = { heading: fallbackHeading, body: [] as string[] };
+  const sections: { heading: string; body: string[]; level: number }[] = [];
+  let current = { heading: fallbackHeading, body: [] as string[], level: fallbackLevel };
   let inFence = false;
 
   for (const line of text.split("\n")) {
@@ -492,7 +544,7 @@ function splitAtLevel(
     const match = inFence ? null : marker.exec(line);
     if (match?.[1] !== undefined) {
       if (current.body.join("\n").trim().length > 0) sections.push(current);
-      current = { heading: match[1], body: [] };
+      current = { heading: match[1], body: [], level };
       continue;
     }
     current.body.push(line);
@@ -501,10 +553,57 @@ function splitAtLevel(
 
   return sections.map((section) => ({
     heading: section.heading,
+    level: section.level,
     body: section.body.join("\n").trim(),
   }));
 }
 
+/**
+ * Merges adjacent sections until a group reaches `minTokens`, never crossing `maxTokens`. A
+ * merged group is headed by the document title and keeps each section's own heading inside it,
+ * so a whole component lands in one chunk without losing the structure a reader needs.
+ */
+function packSections(
+  sections: readonly Section[],
+  title: string,
+  minTokens: number,
+  maxTokens: number,
+): Section[] {
+  const packed: Section[] = [];
+  let group: Section[] = [];
+  let tokens = 0;
+
+  const flush = (): void => {
+    if (group.length === 1 && group[0] !== undefined) packed.push(group[0]);
+    else if (group.length > 1) {
+      packed.push({
+        heading: title,
+        level: 0,
+        body: group.map(withHeading).join("\n\n"),
+        headings: group.map((section) => section.heading),
+      });
+    }
+    group = [];
+    tokens = 0;
+  };
+
+  for (const section of sections) {
+    const size = estimateTokens(withHeading(section));
+    if (group.length > 0 && (tokens >= minTokens || tokens + size > maxTokens)) flush();
+    group.push(section);
+    tokens += size;
+  }
+  flush();
+
+  return packed;
+}
+
+/** A section as it appeared in the source, heading included when it had one. */
+function withHeading(section: Section): string {
+  if (section.level === 0) return section.body;
+  return `${"#".repeat(section.level)} ${section.heading}\n\n${section.body}`;
+}
+
 function splitParagraphs(text: string, maxTokens: number): string[] {
   const parts: string[] = [];
   let buffer: string[] = [];
@@ -620,14 +719,69 @@ function slugify(input: string, fallback: string): string {
   return slug.length > 0 ? slug : fallback;
 }
 
-function uniqueWords(inputs: readonly string[]): string[] {
-  const words = new Set<string>();
+const MAX_TAGS = 24;
+
+/**
+ * The words indexed alongside a chunk.
+ *
+ * Directive tags are taken as the author wrote them — those are deliberate, and one of them
+ * being a function word is the author's decision. Words lifted out of a title or a heading are
+ * filtered: nobody chose them as search terms, and the tag field is weighted 3× in the ranking,
+ * which is what made "How to use it" the answer to every question beginning "how do I".
+ */
+function chunkTags(authored: readonly string[], derived: readonly string[]): string[] {
+  const tags = new Set(words(authored));
+  for (const word of words(derived)) {
+    if (!STOPWORDS.has(word)) tags.add(word);
+  }
+  return [...tags].slice(0, MAX_TAGS);
+}
+
+function words(inputs: readonly string[]): string[] {
+  const found: string[] = [];
   for (const input of inputs) {
-    for (const word of input.toLowerCase().match(/[\p{L}\p{N}]{2,}/gu) ?? []) {
-      words.add(word);
-    }
+    found.push(...(input.toLowerCase().match(/[\p{L}\p{N}]{2,}/gu) ?? []));
   }
-  return [...words].slice(0, 24);
+  return found;
+}
+
+/** A row of a Markdown table: `| Name | Type |`, and the `|---|---:|` rule under it. */
+const TABLE_ROW = /^\|.*\|/;
+const TABLE_RULE = /^[|\-: \t]+$/;
+
+/**
+ * Collapses the alignment padding out of Markdown tables.
+ *
+ * Every API generator pads table cells into columns. That padding is whitespace to a reader and
+ * to a renderer, but tokens are estimated from characters, so a generated props table is
+ * measured at several times its real weight — which spends the response budget, trips
+ * `chunk-too-large`, and forces splits that leave fragments competing for the same query. One
+ * chart's props table measured 4,094 tokens padded and 1,245 collapsed.
+ *
+ * Runs inside a code fence are left alone; a fenced table is example text, and its alignment is
+ * the thing being shown.
+ */
+export function collapseTablePadding(text: string): string {
+  let inFence = false;
+
+  return text
+    .split("\n")
+    .map((line) => {
+      if (/^\s*(?:```|~~~)/.test(line)) {
+        inFence = !inFence;
+        return line;
+      }
+      if (inFence) return line;
+
+      const indent = /^[ \t]*/.exec(line)?.[0] ?? "";
+      const rest = line.slice(indent.length);
+      // Four spaces or more is an indented code block, whatever the line looks like.
+      if (indent.length >= 4 || !TABLE_ROW.test(rest)) return line;
+
+      const collapsed = rest.replace(/[ \t]{2,}/g, " ");
+      return indent + (TABLE_RULE.test(rest) ? collapsed.replace(/-{4,}/g, "---") : collapsed);
+    })
+    .join("\n");
 }
 
 function uniqueId(base: string, taken: Set<string>): string {