agentsmap 0.1.0 → 0.1.1

package/README.md

@@ -30,6 +30,12 @@ Interactive by default — prompts you for each file's purpose. Use `--non-inter
 agentsmap init --non-interactive
 ```
 
+Include `AGENTS.md` files from installed dependencies:
+
+```bash
+agentsmap init --deps
+```
+
 ### `agentsmap validate`
 
 Check that your `AGENTS.map.md` is valid: all listed paths exist, required fields are present, no duplicates, no path traversal.
@@ -49,29 +55,17 @@ Exits with code 1 on errors. Warnings (like unlisted `AGENTS.md` files) don't fa
 
 ### `agentsmap resolve <path>`
 
-Show which `AGENTS.md` files apply to a given path, ranked by specificity.
+Show which `AGENTS.md` files apply to a given path, ranked by priority then specificity.
 
 ```bash
 agentsmap resolve src/services/payments/checkout.ts
 ```
 
-Output:
+Use `--tag` to find entries by domain instead of path:
 
-```
-2 AGENTS.md file(s) apply to src/services/payments/checkout.ts:
-
-(most specific)
-  services/payments/AGENTS.md
-    Purpose: PCI rules, Stripe integration patterns.
-    Matched pattern: services/payments/**
-    Specificity: 6
-    Owners: @payments-team
-
-(#2)
-  AGENTS.md
-    Purpose: Global repo conventions.
-    Matched pattern: **
-    Specificity: 0
+```bash
+agentsmap resolve --tag frontend
+agentsmap resolve --tag backend,compliance
 ```
 
 Use `--json` for machine-readable output:
@@ -88,6 +82,12 @@ Find all `AGENTS.md` files in your repo and show whether they're listed in the m
 agentsmap discover
 ```
 
+Include dependencies:
+
+```bash
+agentsmap discover --deps
+```
+
 Output shows listed files with `+` and unlisted with `?`, along with suggested purposes.
 
 ## Programmatic API
@@ -120,7 +120,18 @@ const result = validate(map, "/path/to/repo");
 - Path: /services/payments/AGENTS.md
   - Purpose: PCI rules, Stripe patterns.
   - Applies to: /services/payments/**
+  - Priority: critical
   - Owners: @payments-team
+  - Tags: backend, compliance
+```
+
+Entries can also reference dependencies:
+
+```markdown
+- Path: /node_modules/@acme/ui/AGENTS.md
+  - Purpose: Acme UI component conventions, theming, a11y.
+  - Applies to: /src/components/**
+  - Tags: frontend
 ```
 
 When an agent enters your repo, it reads this file, matches entries by glob pattern, and loads the most specific instructions. If the map is missing or stale, agents fall back to scanning — nothing breaks.

package/dist/discoverer.d.ts

@@ -6,6 +6,11 @@
  * Returns POSIX-style relative paths from rootDir.
  */
 export declare function discoverAgentFiles(rootDir: string): string[];
+/**
+ * Scan node_modules for AGENTS.md files shipped by dependencies.
+ * Only checks the root of each package (not recursive).
+ */
+export declare function discoverDependencyAgentFiles(rootDir: string): string[];
 /**
  * Read the first meaningful line from an AGENTS.md file to infer a purpose.
  * Skips blank lines and heading markers.

package/dist/discoverer.js

@@ -59,6 +59,53 @@ function scanDir(currentDir, rootDir, results) {
         }
     }
 }
+/**
+ * Scan node_modules for AGENTS.md files shipped by dependencies.
+ * Only checks the root of each package (not recursive).
+ */
+export function discoverDependencyAgentFiles(rootDir) {
+    const results = [];
+    const nmDir = path.join(rootDir, "node_modules");
+    if (!fs.existsSync(nmDir))
+        return results;
+    let entries;
+    try {
+        entries = fs.readdirSync(nmDir, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (entry.name.startsWith("@")) {
+            // Scoped packages: @scope/package
+            const scopeDir = path.join(nmDir, entry.name);
+            let scopedEntries;
+            try {
+                scopedEntries = fs.readdirSync(scopeDir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const pkg of scopedEntries) {
+                if (!pkg.isDirectory())
+                    continue;
+                checkPackageForAgentsMd(path.join(scopeDir, pkg.name), `node_modules/${entry.name}/${pkg.name}`, results);
+            }
+        }
+        else if (!entry.name.startsWith(".")) {
+            checkPackageForAgentsMd(path.join(nmDir, entry.name), `node_modules/${entry.name}`, results);
+        }
+    }
+    return results.sort();
+}
+function checkPackageForAgentsMd(pkgDir, relativePkgPath, results) {
+    const agentsPath = path.join(pkgDir, "AGENTS.md");
+    if (fs.existsSync(agentsPath)) {
+        results.push(`${relativePkgPath}/AGENTS.md`);
+    }
+}
 /**
  * Read the first meaningful line from an AGENTS.md file to infer a purpose.
  * Skips blank lines and heading markers.

package/dist/generator.d.ts

@@ -8,6 +8,8 @@ export declare function defaultScope(agentsPath: string): string[];
 export declare function createMap(entries: Array<{
     path: string;
     purpose: string;
+    priority?: "critical" | "high" | "normal" | "low";
+    last_modified?: string;
     owners?: string[];
     tags?: string[];
 }>): AgentsMap;

package/dist/generator.js

@@ -21,6 +21,10 @@ export function createMap(entries) {
                 scope: defaultScope(e.path),
                 purpose: e.purpose,
             };
+            if (e.priority && e.priority !== "normal")
+                entry.priority = e.priority;
+            if (e.last_modified)
+                entry.last_modified = e.last_modified;
             if (e.owners && e.owners.length > 0)
                 entry.owners = e.owners;
             if (e.tags && e.tags.length > 0)
@@ -43,6 +47,12 @@ export function toMarkdown(map) {
         lines.push(`- Path: /${entry.path}`);
         lines.push(`  - Purpose: ${entry.purpose}`);
         lines.push(`  - Applies to: ${entry.scope.map((s) => `/${s}`).join(", ")}`);
+        if (entry.priority && entry.priority !== "normal") {
+            lines.push(`  - Priority: ${entry.priority}`);
+        }
+        if (entry.last_modified) {
+            lines.push(`  - Last modified: ${entry.last_modified}`);
+        }
         if (entry.owners && entry.owners.length > 0) {
             lines.push(`  - Owners: ${entry.owners.join(", ")}`);
         }

package/dist/index.js

@@ -11,14 +11,14 @@ import * as path from "node:path";
 import * as readline from "node:readline";
 import { parseMap, findMap } from "./parser.js";
 import { validate } from "./validator.js";
-import { resolveEntries, formatMatch } from "./resolver.js";
-import { discoverAgentFiles, inferPurpose } from "./discoverer.js";
+import { resolveEntries, resolveByTag, formatMatch } from "./resolver.js";
+import { discoverAgentFiles, discoverDependencyAgentFiles, inferPurpose } from "./discoverer.js";
 import { createMap, toMarkdown } from "./generator.js";
 const program = new Command();
 program
     .name("agentsmap")
     .description("CLI tool for the AGENTS.map specification — discover, validate, and resolve AGENTS.md files.")
-    .version("0.1.0");
+    .version("0.1.1");
 // ──────────────────────────────────────────────────────────────────────────────
 // init
 // ──────────────────────────────────────────────────────────────────────────────
@@ -26,10 +26,18 @@ program
     .command("init")
     .description("Scan for AGENTS.md files and generate an AGENTS.map.md file.")
     .option("--non-interactive", "Skip interactive prompts; use inferred or placeholder purposes.")
+    .option("--deps", "Include AGENTS.md files from installed dependencies (node_modules).")
     .action(async (opts) => {
     const cwd = process.cwd();
     console.log(chalk.blue("Scanning for AGENTS.md files..."));
     const files = discoverAgentFiles(cwd);
+    if (opts.deps) {
+        const depFiles = discoverDependencyAgentFiles(cwd);
+        if (depFiles.length > 0) {
+            console.log(chalk.blue(`Found ${depFiles.length} dependency AGENTS.md file(s).`));
+            files.push(...depFiles);
+        }
+    }
     if (files.length === 0) {
         console.log(chalk.yellow("No AGENTS.md files found in this directory tree."));
         console.log(chalk.dim("Create an AGENTS.md file and run this command again."));
@@ -137,9 +145,10 @@ program
 // resolve
 // ──────────────────────────────────────────────────────────────────────────────
 program
-    .command("resolve <target-path>")
-    .description("Show which AGENTS.md files apply to a given path.")
+    .command("resolve [target-path]")
+    .description("Show which AGENTS.md files apply to a given path or tag.")
     .option("--json", "Output in JSON format.")
+    .option("--tag <tags>", "Find entries by tag (comma-separated) instead of path.")
     .action((targetPath, opts) => {
     const cwd = process.cwd();
     let map;
@@ -151,6 +160,38 @@ program
         console.log(chalk.red(err.message));
         process.exit(1);
     }
+    // Tag-based resolution
+    if (opts.tag) {
+        const tags = opts.tag.split(",").map((t) => t.trim());
+        const matches = resolveByTag(map, tags);
+        if (opts.json) {
+            const output = matches.map((m) => ({
+                path: m.entry.path,
+                purpose: m.entry.purpose,
+                matchedPattern: m.matchedPattern,
+                priority: m.entry.priority ?? "normal",
+                owners: m.entry.owners,
+                tags: m.entry.tags,
+            }));
+            console.log(JSON.stringify(output, null, 2));
+            return;
+        }
+        if (matches.length === 0) {
+            console.log(chalk.yellow(`No entries tagged "${opts.tag}".`));
+            return;
+        }
+        console.log(chalk.blue(`${matches.length} entry(s) tagged ${chalk.bold(opts.tag)}:\n`));
+        for (const match of matches) {
+            console.log(formatMatch(match));
+            console.log();
+        }
+        return;
+    }
+    // Path-based resolution
+    if (!targetPath) {
+        console.log(chalk.red("Provide a target path or use --tag."));
+        process.exit(1);
+    }
     const matches = resolveEntries(map, targetPath);
     if (opts.json) {
         const output = matches.map((m) => ({
@@ -158,6 +199,7 @@ program
             purpose: m.entry.purpose,
             matchedPattern: m.matchedPattern,
             specificity: m.specificity,
+            priority: m.entry.priority ?? "normal",
             owners: m.entry.owners,
             tags: m.entry.tags,
         }));
@@ -184,10 +226,24 @@ program
 program
     .command("discover")
     .description("Scan for all AGENTS.md files and show their listing status.")
-    .action(() => {
+    .option("--deps", "Include AGENTS.md files from installed dependencies (node_modules).")
+    .action((opts) => {
     const cwd = process.cwd();
     console.log(chalk.blue("Scanning for AGENTS.md files...\n"));
     const files = discoverAgentFiles(cwd);
+    if (opts.deps) {
+        const depFiles = discoverDependencyAgentFiles(cwd);
+        if (depFiles.length > 0) {
+            console.log(chalk.blue(`Dependencies with AGENTS.md (${depFiles.length}):\n`));
+            for (const f of depFiles) {
+                const purpose = inferPurpose(path.join(cwd, f));
+                console.log(`  ${chalk.magenta("⬡")} ${f}`);
+                console.log(`    ${chalk.dim(purpose)}`);
+            }
+            console.log();
+            files.push(...depFiles);
+        }
+    }
     if (files.length === 0) {
         console.log(chalk.yellow("No AGENTS.md files found."));
         return;

package/dist/parser.js

@@ -3,6 +3,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import * as posixPath from "node:path/posix";
 const MAP_FILENAME = "AGENTS.map.md";
 /** Find the AGENTS.map.md file in the given directory. */
 export function findMap(dir) {
@@ -72,6 +73,18 @@ export function parseMarkdown(content) {
                 .map((t) => t.trim());
             continue;
         }
+        // Match "- Priority: ..."
+        const priorityMatch = trimmed.match(/^-\s+Priority:\s+(.+)$/i);
+        if (priorityMatch) {
+            currentEntry.priority = priorityMatch[1].trim().toLowerCase();
+            continue;
+        }
+        // Match "- Last modified: ..."
+        const lastModifiedMatch = trimmed.match(/^-\s+Last\s+modified:\s+(.+)$/i);
+        if (lastModifiedMatch) {
+            currentEntry.last_modified = lastModifiedMatch[1].trim();
+            continue;
+        }
         // Match "- Last reviewed: ..."
         const reviewedMatch = trimmed.match(/^-\s+Last\s+reviewed:\s+(.+)$/i);
         if (reviewedMatch) {
@@ -88,13 +101,24 @@ export function parseMarkdown(content) {
         entries,
     };
 }
+/** Derive a default scope from an entry path. */
+function defaultScopeFromPath(entryPath) {
+    const dir = posixPath.dirname(entryPath);
+    if (dir === ".")
+        return ["**"];
+    return [`${dir}/**`];
+}
 /** Finalize a partially-parsed entry with defaults for missing fields. */
 function finalizeEntry(partial) {
     const entry = {
         path: partial.path,
-        scope: partial.scope ?? ["**"],
+        scope: partial.scope ?? defaultScopeFromPath(partial.path),
         purpose: partial.purpose ?? "",
     };
+    if (partial.priority)
+        entry.priority = partial.priority;
+    if (partial.last_modified)
+        entry.last_modified = partial.last_modified;
     if (partial.owners)
         entry.owners = partial.owners;
     if (partial.tags)

package/dist/resolver.d.ts

@@ -17,6 +17,11 @@ export declare function calculateSpecificity(pattern: string): number;
  * Returns matches sorted by specificity (most specific first).
  */
 export declare function resolveEntries(map: AgentsMap, targetPath: string): ResolveMatch[];
+/**
+ * Resolve entries by tag, regardless of scope.
+ * Returns entries that have at least one of the given tags.
+ */
+export declare function resolveByTag(map: AgentsMap, tags: string[]): ResolveMatch[];
 /**
  * Format a resolved match for human-readable display.
  */

package/dist/resolver.js

@@ -2,6 +2,13 @@
  * Path resolution and scope matching for AGENTS.map entries.
  */
 import picomatch from "picomatch";
+/** Map priority to a numeric rank (higher = more important). */
+const PRIORITY_RANK = {
+    critical: 4,
+    high: 3,
+    normal: 2,
+    low: 1,
+};
 /**
  * Calculate the specificity of a glob pattern.
  * More specific patterns have higher scores.
@@ -65,8 +72,42 @@ export function resolveEntries(map, targetPath) {
             }
         }
     }
-    // Sort by specificity (most specific first)
-    matches.sort((a, b) => b.specificity - a.specificity);
+    // Sort by priority (critical first), then specificity (most specific first)
+    matches.sort((a, b) => {
+        const aPriority = PRIORITY_RANK[a.entry.priority ?? "normal"];
+        const bPriority = PRIORITY_RANK[b.entry.priority ?? "normal"];
+        if (bPriority !== aPriority)
+            return bPriority - aPriority;
+        return b.specificity - a.specificity;
+    });
+    return matches;
+}
+/**
+ * Resolve entries by tag, regardless of scope.
+ * Returns entries that have at least one of the given tags.
+ */
+export function resolveByTag(map, tags) {
+    const normalizedTags = tags.map((t) => t.toLowerCase());
+    const matches = [];
+    for (const entry of map.entries) {
+        if (!entry.tags || entry.tags.length === 0)
+            continue;
+        const entryTags = entry.tags.map((t) => t.toLowerCase());
+        const matched = normalizedTags.find((t) => entryTags.includes(t));
+        if (matched) {
+            matches.push({
+                entry,
+                matchedPattern: `tag:${matched}`,
+                specificity: 0,
+            });
+        }
+    }
+    // Sort by priority
+    matches.sort((a, b) => {
+        const aPriority = PRIORITY_RANK[a.entry.priority ?? "normal"];
+        const bPriority = PRIORITY_RANK[b.entry.priority ?? "normal"];
+        return bPriority - aPriority;
+    });
     return matches;
 }
 /**
@@ -78,6 +119,12 @@ export function formatMatch(match) {
     lines.push(`    Purpose: ${match.entry.purpose}`);
     lines.push(`    Matched pattern: ${match.matchedPattern}`);
     lines.push(`    Specificity: ${match.specificity}`);
+    if (match.entry.priority && match.entry.priority !== "normal") {
+        lines.push(`    Priority: ${match.entry.priority}`);
+    }
+    if (match.entry.last_modified) {
+        lines.push(`    Last modified: ${match.entry.last_modified}`);
+    }
     if (match.entry.owners && match.entry.owners.length > 0) {
         lines.push(`    Owners: ${match.entry.owners.join(", ")}`);
     }

package/dist/types.d.ts

@@ -1,6 +1,8 @@
 /**
  * AGENTS.map type definitions (v1 spec).
  */
+/** Priority levels for entries, inspired by sitemap priority. */
+export type Priority = "critical" | "high" | "normal" | "low";
 /** A single entry in the AGENTS.map.md file. */
 export interface AgentsMapEntry {
     /** POSIX path relative to repo root. Must not contain ".." or start with "/". */
@@ -9,11 +11,15 @@ export interface AgentsMapEntry {
     scope: string[];
     /** 1-3 sentences explaining why/when to use this file. */
     purpose: string;
+    /** How important this file is for agents. Default: "normal". */
+    priority?: Priority;
+    /** Date the AGENTS.md content was last meaningfully changed (YYYY-MM-DD). */
+    last_modified?: string;
     /** Optional team handles, CODEOWNERS aliases, etc. */
     owners?: string[];
     /** Optional categorical labels. */
     tags?: string[];
-    /** Optional date in YYYY-MM-DD format. */
+    /** Date a human last verified the instructions are still correct (YYYY-MM-DD). */
     last_reviewed?: string;
 }
 /** The parsed AGENTS.map structure. */

package/dist/validator.js

@@ -67,14 +67,39 @@ export function validate(map, rootDir) {
         }
         seenPaths.add(normalizedPath);
         // Check that the file actually exists
+        // Dependency paths (node_modules/) are ephemeral — warn instead of error
         const fullPath = path.join(rootDir, entry.path);
+        const isDep = entry.path.startsWith("node_modules/");
         if (!fs.existsSync(fullPath)) {
             diagnostics.push({
-                severity: "error",
-                message: `Entry "${entry.path}": file does not exist at ${fullPath}.`,
+                severity: isDep ? "warning" : "error",
+                message: isDep
+                    ? `Entry "${entry.path}": dependency file not found. Run npm install to resolve.`
+                    : `Entry "${entry.path}": file does not exist at ${fullPath}.`,
                 entryPath: entry.path,
             });
         }
+        // Validate priority if present
+        if (entry.priority) {
+            const validPriorities = ["critical", "high", "normal", "low"];
+            if (!validPriorities.includes(entry.priority)) {
+                diagnostics.push({
+                    severity: "warning",
+                    message: `Entry "${entry.path}": priority "${entry.priority}" is not a valid value. Expected: critical, high, normal, or low.`,
+                    entryPath: entry.path,
+                });
+            }
+        }
+        // Validate last_modified format if present
+        if (entry.last_modified) {
+            if (!/^\d{4}-\d{2}-\d{2}$/.test(entry.last_modified)) {
+                diagnostics.push({
+                    severity: "warning",
+                    message: `Entry "${entry.path}": last_modified "${entry.last_modified}" is not in YYYY-MM-DD format.`,
+                    entryPath: entry.path,
+                });
+            }
+        }
         // Validate last_reviewed format if present
         if (entry.last_reviewed) {
             if (!/^\d{4}-\d{2}-\d{2}$/.test(entry.last_reviewed)) {

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "agentsmap",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "CLI tool for the AGENTS.map specification — discover, validate, and resolve AGENTS.md instruction files.",
   "type": "module",
   "bin": {
-    "agentsmap": "./dist/index.js"
+    "agentsmap": "dist/index.js"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",