@agentskit/doc-bridge 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 1.10.0
+
+### Minor Changes
+
+- 97851d0: Let a repository say which directories are not areas.
+  
+  An area is the unit of architecture between a package and a file, derived as the first directory
+  level under a package's source roots. In a monorepo where every package keeps `tests/` and
+  `fixtures/` beside `src/`, that derives one area per directory — and the doctor's connectivity
+  dimension then asks for a document about a folder of test data. Dogfooding on a 26-package
+  monorepo, 43 of its 81 undocumented areas were `tests/` or `fixtures/`: the metric was mostly
+  measuring directories no documentation should describe.
+  
+  `analysis.areas.exclude` takes glob patterns for directories that hold code without being a unit
+  of architecture. A matching candidate is not derived, and its modules fall to the most specific
+  area that still encloses them — or to none, which is the honest answer for a folder of fixtures.
+  An ownership record naming an excluded path still makes it an area: a person saying a directory is
+  a unit outranks a pattern saying it is not.
+  
+  On that monorepo, excluding `**/tests`, `**/fixtures`, `**/__tests__` and `**/__fixtures__` took
+  areas from 103 to 53 and the documented share from 21% to 34%, before a single document was
+  written.
+
 ## 1.9.0
 
 ### Minor Changes

package/action.yml

@@ -20,7 +20,7 @@ inputs:
   package-version:
     description: Exact @agentskit/doc-bridge npm version (kept in sync with this Action release)
     required: false
-    default: '1.9.0'
+    default: '1.10.0'
 
 runs:
   using: composite

package/dist/cli/program.js

@@ -525,11 +525,20 @@ var AnalysisConfigSchema = z.object({
   /**
    * How code areas are derived — the unit of architecture between a package and a file.
    * `roots` names directories that contain areas rather than being one (`src` holds
-   * `src/query`); `depth` is how many levels below such a root an area sits.
+   * `src/query`); `depth` is how many levels below such a root an area sits; `exclude`
+   * names directories that hold code without being a unit of architecture.
    */
   areas: z.object({
     depth: z.number().int().min(1).max(8).optional(),
-    roots: z.array(z.string().min(1).max(128)).max(32).optional()
+    roots: z.array(z.string().min(1).max(128)).max(32).optional(),
+    /**
+     * Glob patterns for directories that are not areas. A monorepo where every package
+     * keeps `tests/` and `fixtures/` beside `src/` derives one area per directory, and
+     * then connectivity asks for a document about a folder of test data. An ownership
+     * record naming an excluded path still makes it an area: a person saying a directory
+     * is a unit outranks a pattern saying it is not.
+     */
+    exclude: z.array(z.string().min(1).max(256)).max(64).optional()
   }).strict().optional()
 }).strict();
 var WorkflowConfigSchema = z.object({
@@ -2081,6 +2090,9 @@ var areaSuggestionCoverage = (snapshot, options = {}) => {
   }));
 };
 
+// src/discovery/areas.ts
+import { minimatch as minimatch2 } from "minimatch";
+
 // src/discovery/identity.ts
 var MAX_ID_LENGTH = 256;
 var ID_HASH_LENGTH = 32;
@@ -2129,10 +2141,12 @@ var deriveAreas = (options) => {
   const depth = options.depth ?? DEFAULT_AREA_DEPTH;
   const roots = options.roots ?? [...DEFAULT_AREA_ROOTS];
   const ownership = (options.ownership ?? []).map((record) => ({ ...record, path: normalize(record.path) }));
+  const excluded = options.exclude ?? [];
+  const isExcluded2 = (path) => excluded.some((pattern) => minimatch2(path, pattern, { dot: true }));
   const candidates = /* @__PURE__ */ new Map();
   for (const module of options.modules) {
     const path = conventionalAreaPath(module, depth, roots);
-    if (path && !candidates.has(path)) candidates.set(path, module.packageId);
+    if (path && !candidates.has(path) && !isExcluded2(path)) candidates.set(path, module.packageId);
   }
   for (const record of ownership) {
     if (!record.path || candidates.has(record.path)) continue;
@@ -3230,7 +3244,8 @@ var discoverRepository = (opts = {}) => {
     modules: areaModules,
     ownership: Object.entries(opts.config?.routing?.options?.ownership ?? {}).map(([id, record]) => ({ id, path: record.path })),
     ...opts.config?.analysis?.areas?.depth !== void 0 ? { depth: opts.config.analysis.areas.depth } : {},
-    ...opts.config?.analysis?.areas?.roots !== void 0 ? { roots: opts.config.analysis.areas.roots } : {}
+    ...opts.config?.analysis?.areas?.roots !== void 0 ? { roots: opts.config.analysis.areas.roots } : {},
+    ...opts.config?.analysis?.areas?.exclude !== void 0 ? { exclude: opts.config.analysis.areas.exclude } : {}
   });
   const areasById = new Map(areas.map((area) => [area.id, area]));
   const areasByPath = new Map(areas.map((area) => [area.path, area.id]));
@@ -3614,7 +3629,7 @@ var RetrievalIndexV1Schema = z5.object({
 }).strict();
 
 // src/index-builder/scan-corpus.ts
-import { minimatch as minimatch2 } from "minimatch";
+import { minimatch as minimatch3 } from "minimatch";
 
 // src/lib/markdown.ts
 var parseFrontmatter = (markdown) => {
@@ -3765,8 +3780,8 @@ var configuredPathMatches = (relPath, include, exclude) => {
   const normalize3 = (pattern) => toPosix(pattern).replace(/^\.\//, "");
   const included = include?.filter(Boolean).map(normalize3) ?? [];
   const excluded = exclude?.filter(Boolean).map(normalize3) ?? [];
-  if (excluded.some((pattern) => minimatch2(relPath, pattern, { dot: true }))) return false;
-  return included.length === 0 || included.some((pattern) => minimatch2(relPath, pattern, { dot: true }));
+  if (excluded.some((pattern) => minimatch3(relPath, pattern, { dot: true }))) return false;
+  return included.length === 0 || included.some((pattern) => minimatch3(relPath, pattern, { dot: true }));
 };
 var scanAgentCorpus = (root, config) => {
   const agentRoot = containedProjectPath(root, config.corpus.agent.root);
@@ -4040,7 +4055,7 @@ var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}, root
 };
 
 // src/version.ts
-var PACKAGE_VERSION = "1.9.0";
+var PACKAGE_VERSION = "1.10.0";
 
 // src/index-builder/capabilities.ts
 var renderCapabilitiesJson = (config, index, paths) => {
@@ -4945,14 +4960,14 @@ var nextraAdapter = {
 };
 
 // src/index-builder/human-adapters/plain-markdown.ts
-import { minimatch as minimatch3 } from "minimatch";
+import { minimatch as minimatch4 } from "minimatch";
 var stringPatterns = (value) => Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.length > 0) : [];
 var matchesConfiguredPath = (relPath, options) => {
   const normalize3 = (pattern) => pattern.replaceAll("\\", "/").replace(/^\.\//, "");
   const include = stringPatterns(options?.include).map(normalize3);
   const exclude = stringPatterns(options?.exclude).map(normalize3);
-  if (exclude.some((pattern) => minimatch3(relPath, pattern, { dot: true }))) return false;
-  return include.length === 0 || include.some((pattern) => minimatch3(relPath, pattern, { dot: true }));
+  if (exclude.some((pattern) => minimatch4(relPath, pattern, { dot: true }))) return false;
+  return include.length === 0 || include.some((pattern) => minimatch4(relPath, pattern, { dot: true }));
 };
 var plainMarkdownAdapter = {
   plugin: "plain-markdown",
@@ -4990,7 +5005,7 @@ var starlightAdapter = {
 };
 
 // src/index-builder/human-adapters/vitepress.ts
-import { minimatch as minimatch4 } from "minimatch";
+import { minimatch as minimatch5 } from "minimatch";
 var isVitePressPage = (relPath) => !relPath.split("/").some((part) => part === ".vitepress" || part.startsWith("."));
 var srcExcludePatterns = (value) => {
   if (value === void 0) return [];
@@ -5004,7 +5019,7 @@ var srcExcludePatterns = (value) => {
     return pattern;
   });
 };
-var isExcluded = (relPath, patterns) => patterns.some((pattern) => minimatch4(relPath, pattern, { dot: true }));
+var isExcluded = (relPath, patterns) => patterns.some((pattern) => minimatch5(relPath, pattern, { dot: true }));
 var vitepressSlug = (relPath, cleanUrls) => {
   const slug2 = routeSlug(relPath);
   if (cleanUrls || /(?:^|\/)index\.mdx?$/.test(relPath)) return slug2;
@@ -8189,7 +8204,7 @@ var resolveGateIds = (config) => {
 };
 
 // src/rules/engine.ts
-import { minimatch as minimatch5 } from "minimatch";
+import { minimatch as minimatch6 } from "minimatch";
 var diagnosticRules = {
   DOCUMENTATION_QUALITY: "documentation-quality",
   RELATION_UNDOCUMENTED: "graph-undocumented-relation",
@@ -8263,7 +8278,7 @@ var evaluateRules = (report, options = {}) => {
       findings.push(criticalFinding(finding, criticalSeverity, matchingEntity));
     }
     for (const path of resolved.criticalPaths) {
-      if (finding.evidence.some((item) => minimatch5(item.path, path, { dot: true })) && !resolved.ignore.has("critical-path-risk") && criticalSeverity !== "off") {
+      if (finding.evidence.some((item) => minimatch6(item.path, path, { dot: true })) && !resolved.ignore.has("critical-path-risk") && criticalSeverity !== "off") {
         findings.push(criticalFinding(finding, criticalSeverity, path));
       }
     }
@@ -13982,7 +13997,7 @@ var formatBenchmarkText = (result) => [
 // src/audit/documentation.ts
 import { readFileSync as readFileSync28 } from "fs";
 import { resolve as resolve25 } from "path";
-import { minimatch as minimatch6 } from "minimatch";
+import { minimatch as minimatch7 } from "minimatch";
 
 // src/render/data.ts
 var MAX_SYMBOLS2 = 12;
@@ -14313,7 +14328,7 @@ var bodyForDuplicate = (content) => {
   const start = lines[0] === "---" ? lines.findIndex((line, index) => index > 0 && line === "---") + 1 : 0;
   return lines.slice(start).join("\n").replace(/\s+/g, " ").trim().toLocaleLowerCase();
 };
-var matches = (path, patterns) => patterns.some((pattern) => minimatch6(path, pattern, { dot: true }));
+var matches = (path, patterns) => patterns.some((pattern) => minimatch7(path, pattern, { dot: true }));
 var rate2 = (count4, total) => total ? count4 / total : null;
 var metadataPresent = (content, key) => {
   const value = parseFrontmatter(content).data[key];