@wonsukchoi/crondex 0.5.0 → 0.7.0

package/README.md

@@ -27,8 +27,16 @@ npx @wonsukchoi/crondex list                          # browse everything
 npx @wonsukchoi/crondex list --category devops        # filter by category or --tag
 npx @wonsukchoi/crondex show backup-reminder          # print one job's YAML
 npx @wonsukchoi/crondex add backup-reminder --dest ./cron/backup-reminder.yaml
+npx @wonsukchoi/crondex recommend "warn me before my SSL cert expires"
 ```
 
+`recommend` takes a free-text description of what you want and ranks the
+catalog against it (weighted keyword match over tags/name/id/category/
+description, zero tokens, no network call) — handy for an agent that just
+got asked "can you set up something for X" and needs to check whether a
+ready-made job already covers it before writing one from scratch. Add
+`--limit <n>` to control how many results come back (default 5).
+
 Or install once and drop the scope prefix on every call:
 
 ```bash
@@ -52,7 +60,7 @@ node bin/crondex.js list
 
 ```
 crondex/
-├── bin/crondex.js         CLI: list / show / add
+├── bin/crondex.js         CLI: list / show / add / recommend
 ├── catalog.json           generated index of every job — read this first
 ├── schema/job.schema.json spec every job file follows
 ├── jobs/

package/bin/crondex.js

@@ -30,14 +30,92 @@ Usage:
   crondex list [--category <name>] [--tag <name>]
   crondex show <id>
   crondex add <id> [--dest <path>]
+  crondex recommend "<what you want done>" [--limit <n>]
 
 Examples:
   crondex list --category devops
   crondex show dependency-audit
   crondex add backup-reminder --dest ./cron/backup-reminder.yaml
+  crondex recommend "warn me before my SSL cert expires"
 `);
 }
 
+const STOPWORDS = new Set([
+  "a", "an", "the", "to", "for", "of", "in", "on", "at", "by", "and", "or", "my", "me", "i",
+  "can", "you", "do", "does", "this", "that", "these", "those", "please", "want", "wants",
+  "wanted", "need", "needs", "help", "with", "is", "are", "be", "it", "so", "when", "should",
+  "could", "would", "how", "what", "which", "up", "down", "get", "make", "set", "just", "really",
+  "some", "something", "any", "want", "us", "our", "your", "yours", "if", "then", "than",
+]);
+
+function stem(word) {
+  if (word.length > 4 && word.endsWith("ies")) return word.slice(0, -3) + "y";
+  if (word.length > 4 && word.endsWith("es") && !word.endsWith("ses")) return word.slice(0, -2);
+  if (word.length > 3 && word.endsWith("s") && !word.endsWith("ss")) return word.slice(0, -1);
+  return word;
+}
+
+function tokenize(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, " ")
+    .split(/[\s-]+/)
+    .filter((w) => w.length > 1 && !STOPWORDS.has(w))
+    .map(stem);
+}
+
+// id and name are near-duplicates of each other (id is just the slugified
+// name), so they're merged into one "title" field — otherwise a match on a
+// shared word like "water" gets weighted 3+3 instead of 3, which can outrank
+// a more specific job that only matches once via tags.
+const RECOMMEND_WEIGHTS = { tags: 4, title: 3, category: 2, description: 1 };
+
+function scoreJob(queryTokens, job) {
+  const fields = {
+    tags: job.tags.map((t) => stem(t.toLowerCase())),
+    title: [...new Set([...tokenize(job.name), ...tokenize(job.id.replace(/-/g, " "))])],
+    category: tokenize(job.category ?? ""),
+    description: tokenize(job.description ?? ""),
+  };
+  let score = 0;
+  const matched = new Set();
+  for (const qt of queryTokens) {
+    for (const [field, weight] of Object.entries(RECOMMEND_WEIGHTS)) {
+      if (fields[field].includes(qt)) {
+        score += weight;
+        matched.add(qt);
+      }
+    }
+  }
+  return { score, matchedTerms: [...matched] };
+}
+
+function recommend(queryText) {
+  const limit = Number(flag("limit")) || 5;
+  const queryTokens = tokenize(queryText);
+  if (!queryTokens.length) {
+    console.log("query too vague to match on — describe what you want the job to check or remind you about.");
+    return;
+  }
+  const ranked = CATALOG.jobs
+    .map((job) => ({ job, ...scoreJob(queryTokens, job) }))
+    .filter((r) => r.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit);
+  if (!ranked.length) {
+    console.log(`no confident match for "${queryText}". Run "crondex list" to browse everything.`);
+    return;
+  }
+  console.log(`top match${ranked.length > 1 ? "es" : ""} for "${queryText}":`);
+  console.log();
+  for (const r of ranked) {
+    console.log(`${r.job.id}  [${r.job.category}]  score ${r.score}  (${r.job.modes.join(", ")})`);
+    console.log(`  ${r.job.description}`);
+    console.log(`  matched: ${r.matchedTerms.join(", ")}`);
+    console.log();
+  }
+}
+
 function catalogInfoLine() {
   const viaNpx = process.env.npm_command === "exec";
   const freshness = viaNpx
@@ -98,6 +176,13 @@ switch (cmd) {
     }
     add(args[0]);
     break;
+  case "recommend":
+    if (!args[0]) {
+      console.error('usage: crondex recommend "<what you want done>" [--limit <n>]');
+      process.exit(1);
+    }
+    recommend(args[0]);
+    break;
   default:
     printHelp();
 }