agents.yaml 0.2.1 → 0.2.2

package/AGENTS.md

@@ -19,3 +19,5 @@ Agents should treat paths listed in `documents` as promoted supplemental guidanc
 The CLI can help discover package and local `AGENTS.md` files, add selected paths to `agents.yaml`, remove paths, initialize the root breadcrumb, and validate that referenced files still exist.
 
 Discovery only considers direct dependencies under a project's `node_modules`; nested dependency `AGENTS.md` files are not automatically activated.
+
+Discovery skips dot-prefixed directories by default. Use `agents discover --include-dot-directories` when hidden project directories should be scanned too.

package/README.md

@@ -17,12 +17,30 @@ pnpm run build
 ```sh
 agents init
 agents discover
+agents discover --include-dot-directories
 agents add ./node_modules/react/AGENTS.md
 agents validate
 ```
 
 Run `agents` with no command for the interactive flow.
 
+Discovery skips dot-prefixed directories by default so local caches and tool
+state do not dominate scan time. Use `--include-dot-directories` when you need
+to search those directories too.
+
+## Benchmark
+
+```sh
+pnpm --filter agents.yaml bench
+```
+
+The benchmark creates a temporary discovery fixture, compares default discovery
+against `--include-dot-directories`, prints median/min/max timings, and removes
+the fixture when it exits. Fixture size can be tuned with
+`AGENTS_BENCH_HIDDEN_DIRS`, `AGENTS_BENCH_FILES_PER_HIDDEN_DIR`,
+`AGENTS_BENCH_VISIBLE_PACKAGES`, `AGENTS_BENCH_ITERATIONS`, and
+`AGENTS_BENCH_WARMUPS`.
+
 ## File Format
 
 ```yaml

package/dist/index.mjs

@@ -15,8 +15,8 @@ function resolveFromRoot(root, input) {
 }
 function formatProjectPath(root, target) {
 	const relative = path.relative(root, target).split(path.sep).join(path.posix.sep);
-	if (relative.startsWith("..")) return target;
-	return relative.startsWith(".") ? relative : `./${relative}`;
+	if (relative === ".." || relative.startsWith("../")) return target;
+	return relative.startsWith("./") ? relative : `./${relative}`;
 }
 //#endregion
 //#region src/agents-file.ts
@@ -174,16 +174,16 @@ const skippedDirectories = new Set([
 	"dist",
 	"build"
 ]);
-async function discoverAgentDocuments(root) {
+async function discoverAgentDocuments(root, options = {}) {
 	const found = [];
-	await walk(root, root, found);
+	await walk(root, root, found, options);
 	return found.filter((document) => document.path !== "./AGENTS.md").sort((left, right) => left.path.localeCompare(right.path));
 }
 async function describeAgentDocument(root, agentsDocumentPath) {
 	const absolutePath = resolveFromRoot(root, agentsDocumentPath);
 	return documentEntry(root, absolutePath, await readPackageDescription(path.dirname(absolutePath)));
 }
-async function walk(root, directory, found) {
+async function walk(root, directory, found, options) {
 	let handle;
 	try {
 		handle = await opendir(directory);
@@ -197,12 +197,16 @@ async function walk(root, directory, found) {
 				await scanDirectNodeModules(root, absolutePath, found);
 				continue;
 			}
-			if (!skippedDirectories.has(entry.name)) await walk(root, absolutePath, found);
+			if (!shouldSkipDirectory(entry.name, options)) await walk(root, absolutePath, found, options);
 			continue;
 		}
 		if (entry.isFile() && entry.name === "AGENTS.md") found.push(await documentEntry(root, absolutePath, await readPackageDescription(path.dirname(absolutePath))));
 	}
 }
+function shouldSkipDirectory(name, options) {
+	if (skippedDirectories.has(name)) return true;
+	return !options.includeDotDirectories && name.startsWith(".");
+}
 async function scanDirectNodeModules(root, nodeModulesPath, found) {
 	let handle;
 	try {
@@ -263,7 +267,7 @@ const helpText = `agents
 Usage:
   agents
   agents init [--force]
-  agents discover [--json]
+  agents discover [--json] [--include-dot-directories]
   agents add <path...>
   agents remove <path...>
   agents validate [--json]
@@ -286,7 +290,10 @@ async function run(argv) {
 			await commandInit(root, parsed.flags.get("force") === true);
 			return;
 		case "discover":
-			await commandDiscover(root, parsed.flags.get("json") === true);
+			await commandDiscover(root, {
+				json: parsed.flags.get("json") === true,
+				includeDotDirectories: parsed.flags.get("include-dot-directories") === true
+			});
 			return;
 		case "add":
 			await commandAdd(root, parsed.values);
@@ -353,9 +360,9 @@ async function commandInit(root, force) {
 	clack.note(result.messages.join("\n"), "Updated");
 	clack.outro("Project breadcrumb is ready.");
 }
-async function commandDiscover(root, json) {
-	const documents = await discoverAgentDocuments(root);
-	if (json) {
+async function commandDiscover(root, options) {
+	const documents = await discoverAgentDocuments(root, { includeDotDirectories: options.includeDotDirectories });
+	if (options.json) {
 		console.log(JSON.stringify(documents, null, 2));
 		return;
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents.yaml",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "A CLI for discovering and curating agent-readable documentation in agents.yaml.",
   "repository": {
     "type": "git",
@@ -31,6 +31,7 @@
     "pnpm": "11.5.2"
   },
   "scripts": {
+    "bench": "node src/discover.bench.ts",
     "build": "vp pack",
     "dev": "src/index.ts",
     "test": "vp test"

package/src/discover.bench.ts

@@ -0,0 +1,219 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import { performance } from "node:perf_hooks"
+import { discoverAgentDocuments, type DiscoverOptions } from "./discover.ts"
+
+type BenchmarkCase = {
+	name: string
+	options?: DiscoverOptions
+}
+
+type BenchmarkResult = {
+	name: string
+	docs: number
+	medianMs: number
+	minMs: number
+	maxMs: number
+}
+
+const hiddenDirectories = readPositiveInteger("AGENTS_BENCH_HIDDEN_DIRS", 250)
+const filesPerHiddenDirectory = readPositiveInteger(
+	"AGENTS_BENCH_FILES_PER_HIDDEN_DIR",
+	8,
+)
+const visiblePackages = readPositiveInteger("AGENTS_BENCH_VISIBLE_PACKAGES", 25)
+const iterations = readPositiveInteger("AGENTS_BENCH_ITERATIONS", 7)
+const warmups = readPositiveInteger("AGENTS_BENCH_WARMUPS", 1)
+
+const cases: BenchmarkCase[] = [
+	{ name: "default" },
+	{
+		name: "include dot directories",
+		options: { includeDotDirectories: true },
+	},
+]
+
+const root = await mkdtemp(path.join(tmpdir(), "agents-yaml-bench-"))
+
+try {
+	await createFixture(root)
+	const results: BenchmarkResult[] = []
+
+	for (const benchmarkCase of cases) {
+		for (let index = 0; index < warmups; index += 1) {
+			await discoverAgentDocuments(root, benchmarkCase.options)
+		}
+
+		results.push(await runCase(root, benchmarkCase))
+	}
+
+	printResults(results)
+} finally {
+	await rm(root, { recursive: true, force: true })
+}
+
+async function createFixture(root: string): Promise<void> {
+	await writeFile(
+		path.join(root, "agents.yaml"),
+		"version: 1\n\ndocuments: []\n",
+		"utf8",
+	)
+	await writeFile(path.join(root, "AGENTS.md"), "# Root guidance\n", "utf8")
+
+	await createDirectDependency(root)
+	await createVisibleProjectDocuments(root)
+	await createHiddenCache(root)
+}
+
+async function createDirectDependency(root: string): Promise<void> {
+	const dependencyPath = path.join(root, "node_modules", "direct-lib")
+	await mkdir(dependencyPath, { recursive: true })
+	await writeFile(
+		path.join(dependencyPath, "AGENTS.md"),
+		"# Direct dependency guidance\n",
+		"utf8",
+	)
+	await writeFile(
+		path.join(dependencyPath, "package.json"),
+		JSON.stringify({
+			name: "direct-lib",
+			description: "Direct fixture dependency.",
+		}),
+		"utf8",
+	)
+}
+
+async function createVisibleProjectDocuments(root: string): Promise<void> {
+	for (let index = 0; index < visiblePackages; index += 1) {
+		const packagePath = path.join(root, "packages", `visible-${index}`)
+		await mkdir(packagePath, { recursive: true })
+		await writeFile(
+			path.join(packagePath, "AGENTS.md"),
+			"# Visible project guidance\n",
+			"utf8",
+		)
+	}
+}
+
+async function createHiddenCache(root: string): Promise<void> {
+	for (let index = 0; index < hiddenDirectories; index += 1) {
+		const cachePath = path.join(root, ".cache", `entry-${index}`, "nested")
+		await mkdir(cachePath, { recursive: true })
+		await writeFile(
+			path.join(cachePath, "AGENTS.md"),
+			"# Hidden cache guidance\n",
+			"utf8",
+		)
+
+		for (
+			let fileIndex = 0;
+			fileIndex < filesPerHiddenDirectory;
+			fileIndex += 1
+		) {
+			await writeFile(
+				path.join(cachePath, `file-${fileIndex}.txt`),
+				"x".repeat(100),
+				"utf8",
+			)
+		}
+	}
+}
+
+async function runCase(
+	root: string,
+	benchmarkCase: BenchmarkCase,
+): Promise<BenchmarkResult> {
+	const durations: number[] = []
+	let docs = 0
+
+	for (let index = 0; index < iterations; index += 1) {
+		const start = performance.now()
+		const discovered = await discoverAgentDocuments(root, benchmarkCase.options)
+		const duration = performance.now() - start
+
+		docs = discovered.length
+		durations.push(duration)
+	}
+
+	const sorted = [...durations].sort((left, right) => left - right)
+	const medianMs = sorted[Math.floor(sorted.length / 2)]
+	const minMs = sorted[0]
+	const maxMs = sorted[sorted.length - 1]
+
+	if (medianMs === undefined || minMs === undefined || maxMs === undefined) {
+		throw new Error("Benchmark did not record any durations")
+	}
+
+	return {
+		name: benchmarkCase.name,
+		docs,
+		medianMs,
+		minMs,
+		maxMs,
+	}
+}
+
+function printResults(results: BenchmarkResult[]): void {
+	console.log("agents discover benchmark")
+	console.log(
+		[
+			`fixture: hiddenDirectories=${hiddenDirectories}`,
+			`filesPerHiddenDirectory=${filesPerHiddenDirectory}`,
+			`visiblePackages=${visiblePackages}`,
+			`iterations=${iterations}`,
+			`warmups=${warmups}`,
+		].join(", "),
+	)
+	console.log("")
+	console.log(
+		[
+			pad("case", 24),
+			pad("docs", 8),
+			pad("median", 10),
+			pad("min", 10),
+			pad("max", 10),
+		].join(""),
+	)
+	console.log("-".repeat(62))
+
+	for (const result of results) {
+		console.log(
+			[
+				pad(result.name, 24),
+				pad(String(result.docs), 8),
+				pad(formatMs(result.medianMs), 10),
+				pad(formatMs(result.minMs), 10),
+				pad(formatMs(result.maxMs), 10),
+			].join(""),
+		)
+	}
+
+	const defaultResult = results.find((result) => result.name === "default")
+	const includeDotResult = results.find(
+		(result) => result.name === "include dot directories",
+	)
+	if (defaultResult && includeDotResult && defaultResult.medianMs > 0) {
+		const ratio = includeDotResult.medianMs / defaultResult.medianMs
+		console.log("")
+		console.log(`include dot directories median: ${ratio.toFixed(1)}x default`)
+	}
+}
+
+function readPositiveInteger(name: string, fallback: number): number {
+	const raw = process.env[name]
+	if (!raw) return fallback
+
+	const value = Number.parseInt(raw, 10)
+	if (Number.isInteger(value) && value > 0) return value
+
+	throw new Error(`${name} must be a positive integer`)
+}
+
+function formatMs(value: number): string {
+	return `${value.toFixed(1)}ms`
+}
+
+function pad(value: string, width: number): string {
+	return value.padEnd(width, " ")
+}

package/src/discover.test.ts

@@ -132,6 +132,26 @@ describe("agents.yaml dependency discovery", () => {
 			},
 		])
 	})
+
+	it("skips dot-prefixed directories by default", async () => {
+		const root = await createTempProject()
+		const hiddenAgentsPath = path.join(root, ".cache", "AGENTS.md")
+		await mkdir(path.dirname(hiddenAgentsPath), { recursive: true })
+		await writeFile(hiddenAgentsPath, "# Hidden cache guidance\n", "utf8")
+
+		await expect(discoverAgentDocuments(root)).resolves.toEqual([])
+	})
+
+	it("can include dot-prefixed directories when requested", async () => {
+		const root = await createTempProject()
+		const hiddenAgentsPath = path.join(root, ".cache", "AGENTS.md")
+		await mkdir(path.dirname(hiddenAgentsPath), { recursive: true })
+		await writeFile(hiddenAgentsPath, "# Hidden cache guidance\n", "utf8")
+
+		await expect(
+			discoverAgentDocuments(root, { includeDotDirectories: true }),
+		).resolves.toEqual([{ path: "./.cache/AGENTS.md" }])
+	})
 })
 
 async function createTempProject(): Promise<string> {

package/src/discover.ts

@@ -7,6 +7,10 @@ export type DiscoveredDocument = {
 	description?: string
 }
 
+export type DiscoverOptions = {
+	includeDotDirectories?: boolean
+}
+
 const skippedDirectories = new Set([
 	".git",
 	".hg",
@@ -20,9 +24,10 @@ const skippedDirectories = new Set([
 
 export async function discoverAgentDocuments(
 	root: string,
+	options: DiscoverOptions = {},
 ): Promise<DiscoveredDocument[]> {
 	const found: DiscoveredDocument[] = []
-	await walk(root, root, found)
+	await walk(root, root, found, options)
 	return found
 		.filter((document) => document.path !== "./AGENTS.md")
 		.sort((left, right) => left.path.localeCompare(right.path))
@@ -44,6 +49,7 @@ async function walk(
 	root: string,
 	directory: string,
 	found: DiscoveredDocument[],
+	options: DiscoverOptions,
 ): Promise<void> {
 	let handle
 	try {
@@ -61,8 +67,8 @@ async function walk(
 				continue
 			}
 
-			if (!skippedDirectories.has(entry.name)) {
-				await walk(root, absolutePath, found)
+			if (!shouldSkipDirectory(entry.name, options)) {
+				await walk(root, absolutePath, found, options)
 			}
 			continue
 		}
@@ -79,6 +85,11 @@ async function walk(
 	}
 }
 
+function shouldSkipDirectory(name: string, options: DiscoverOptions): boolean {
+	if (skippedDirectories.has(name)) return true
+	return !options.includeDotDirectories && name.startsWith(".")
+}
+
 async function scanDirectNodeModules(
 	root: string,
 	nodeModulesPath: string,

package/src/paths.ts

@@ -15,9 +15,9 @@ export function formatProjectPath(root: string, target: string): string {
 		.relative(root, target)
 		.split(path.sep)
 		.join(path.posix.sep)
-	if (relative.startsWith("..")) {
+	if (relative === ".." || relative.startsWith("../")) {
 		return target
 	}
 
-	return relative.startsWith(".") ? relative : `./${relative}`
+	return relative.startsWith("./") ? relative : `./${relative}`
 }

package/src/run.ts

@@ -37,7 +37,7 @@ const helpText = `agents
 Usage:
   agents
   agents init [--force]
-  agents discover [--json]
+  agents discover [--json] [--include-dot-directories]
   agents add <path...>
   agents remove <path...>
   agents validate [--json]
@@ -62,7 +62,11 @@ export async function run(argv: string[]): Promise<void> {
 			await commandInit(root, parsed.flags.get("force") === true)
 			return
 		case "discover":
-			await commandDiscover(root, parsed.flags.get("json") === true)
+			await commandDiscover(root, {
+				json: parsed.flags.get("json") === true,
+				includeDotDirectories:
+					parsed.flags.get("include-dot-directories") === true,
+			})
 			return
 		case "add":
 			await commandAdd(root, parsed.values)
@@ -137,9 +141,14 @@ async function commandInit(root: string, force: boolean): Promise<void> {
 	clack.outro("Project breadcrumb is ready.")
 }
 
-async function commandDiscover(root: string, json: boolean): Promise<void> {
-	const documents = await discoverAgentDocuments(root)
-	if (json) {
+async function commandDiscover(
+	root: string,
+	options: { json: boolean; includeDotDirectories: boolean },
+): Promise<void> {
+	const documents = await discoverAgentDocuments(root, {
+		includeDotDirectories: options.includeDotDirectories,
+	})
+	if (options.json) {
 		console.log(JSON.stringify(documents, null, 2))
 		return
 	}