@rse/ase 0.9.35 → 0.9.36

package/dst/ase-skills.js

@@ -37,17 +37,19 @@ export class Skills {
             const time = pkg.time ?? {};
             const verEntry = version !== "" ? pkg.versions?.[version] : undefined;
             let repository = "";
+            let deps = "N.A.";
             if (verEntry !== undefined) {
                 const r = verEntry.repository;
                 if (typeof r === "string")
                     repository = r;
                 else if (r !== undefined && typeof r.url === "string")
                     repository = r.url;
+                deps = Object.keys(verEntry.dependencies ?? {}).length;
             }
-            return { version, time, repository };
+            return { version, time, repository, deps };
         }
         catch {
-            return { version: "", time: {}, repository: "" };
+            return { version: "", time: {}, repository: "", deps: "N.A." };
         }
     }
     /*  fetch GitHub stars given a repository URL (or empty string)  */
@@ -83,7 +85,7 @@ export class Skills {
     static async fetchMavenInfo(coord) {
         const [groupId, artifactId] = coord.split(":", 2);
         if (groupId === undefined || artifactId === undefined || groupId === "" || artifactId === "")
-            return { version: "", created: "", updated: "", repository: "" };
+            return { version: "", created: "", updated: "", repository: "", deps: "N.A." };
         try {
             const latest = await Skills.httpLimit(() => ofetch("https://search.maven.org/solrsearch/select" +
                 `?q=g:%22${encodeURIComponent(groupId)}%22+AND+a:%22${encodeURIComponent(artifactId)}%22` +
@@ -113,6 +115,7 @@ export class Skills {
             }
             const created = typeof firstTs === "number" ? new Date(firstTs).toISOString() : updated;
             let repository = "";
+            let deps = "N.A.";
             if (version !== "") {
                 try {
                     const pom = await Skills.httpLimit(() => ofetch(`https://repo1.maven.org/maven2/${groupId.replace(/\./g, "/")}` +
@@ -126,16 +129,31 @@ export class Skills {
                             if (url !== null)
                                 repository = url[1];
                         }
+                        /*  count the `<dependency>` entries of the direct
+                            `<dependencies>` block, skipping `test`/`provided`
+                            scopes; a `<dependencyManagement>` block is ignored
+                            as it only declares versions, not real dependencies  */
+                        const managed = /<dependencyManagement>[\s\S]*?<\/dependencyManagement>/gi;
+                        const stripped = pom.replace(managed, "");
+                        const depRe = /<dependency>([\s\S]*?)<\/dependency>/gi;
+                        let count = 0;
+                        let dep;
+                        while ((dep = depRe.exec(stripped)) !== null) {
+                            const scope = /<scope>\s*([^<\s]+)\s*<\/scope>/i.exec(dep[1]);
+                            if (scope === null || (scope[1] !== "test" && scope[1] !== "provided"))
+                                count++;
+                        }
+                        deps = count;
                     }
                 }
                 catch {
                     repository = "";
                 }
             }
-            return { version, created, updated, repository };
+            return { version, created, updated, repository, deps };
         }
         catch {
-            return { version: "", created: "", updated: "", repository: "" };
+            return { version: "", created: "", updated: "", repository: "", deps: "N.A." };
         }
     }
     /*  fetch the "Used By" count from `mvnrepository.com` as a downloads proxy
@@ -180,7 +198,7 @@ export class Skills {
         -   "JavaScript"/"TypeScript": NPM registry (pacote) + GitHub stars + npm-downloads
         -   "Java"/"Kotlin":           Maven Central + GitHub stars + mvnrepository.com "Used By"
         -   "Unknown":                 not supported -- return empty result  */
-    static async info(stack, components) {
+    static async info(stack, components, staleMonths = 18, smallScope = false) {
         if (stack === "JavaScript" || stack === "TypeScript") {
             /*  per package: kick off packument and downloads in parallel,
                 then stars as soon as the packument resolves; across packages
@@ -194,7 +212,7 @@ export class Skills {
                 ]);
                 const created = p.time.created ?? "";
                 const updated = p.version !== "" ? (p.time[p.version] ?? "") : "";
-                const rank = Skills.computeRank(downloads, stars, created, updated);
+                const rank = Skills.computeRank(downloads, stars, created, updated, p.deps, staleMonths, smallScope);
                 return {
                     name,
                     version: p.version,
@@ -203,6 +221,7 @@ export class Skills {
                     repository: p.repository,
                     stars,
                     downloads,
+                    deps: p.deps,
                     rank
                 };
             }));
@@ -222,7 +241,7 @@ export class Skills {
                 const [i, downloads, stars] = await Promise.all([
                     infoPromise, downloadsPromise, starsPromise
                 ]);
-                const rank = Skills.computeRank(downloads, stars, i.created, i.updated);
+                const rank = Skills.computeRank(downloads, stars, i.created, i.updated, i.deps, staleMonths, smallScope);
                 return {
                     name,
                     version: i.version,
@@ -231,6 +250,7 @@ export class Skills {
                     repository: i.repository,
                     stars,
                     downloads,
+                    deps: i.deps,
                     rank
                 };
             }));
@@ -253,7 +273,7 @@ export class Skills {
         is structurally unavailable, e.g. Maven Central exposes no
         per-artifact download counts) is likewise treated as neutral `1`, so
         such stacks can still be ranked by the remaining metrics.  */
-    static computeRank(downloads, stars, created, updated) {
+    static computeRank(downloads, stars, created, updated, deps, staleMonths, smallScope) {
         const d = typeof downloads === "number" ? downloads + 1 : 1;
         const s = typeof stars === "number" ? stars + 1 : 1;
         const cMs = created !== "" ? Date.parse(created) : NaN;
@@ -277,7 +297,31 @@ export class Skills {
             entry rankable without rewarding the missing date.  */
         const lifespan = (!Number.isNaN(cMs) && !Number.isNaN(uMs)) ? Math.max(0, uMs - cMs) : 1;
         const recentness = !Number.isNaN(uMs) ? Math.exp(-Math.max(0, (now - uMs) / msPerDay) / halfLife) : 0.5;
-        return d * s * lifespan * recentness;
+        let rank = d * s * lifespan * recentness;
+        /*  hard, caller-tunable staleness penalty on top of the soft
+            `recentness` decay: unlike the smooth exp-decay above, this is a
+            two-tier *cliff* keyed off the `staleMonths` threshold. Past the
+            first tier (`staleMonths`) the rank is cut to `0.3x`, past the
+            second tier (`2 x staleMonths`, i.e. long abandoned) to `0.1x`.
+            A component below the first tier -- or one whose `updated` date
+            is unknown -- is left unpenalized.  */
+        if (!Number.isNaN(uMs)) {
+            const ageMonths = (now - uMs) / msPerDay / 30;
+            if (ageMonths > 2 * staleMonths)
+                rank *= 0.1;
+            else if (ageMonths > staleMonths)
+                rank *= 0.3;
+        }
+        /*  small-scope dependency-weight penalty: for a narrow, self-
+            contained need, dragging in a heavy dependency tree is usually
+            the wrong call, so each real component is demoted in proportion
+            to its own number of *direct* dependencies (`1 / (1 + deps)`).
+            A zero-dep component is left unpenalized; an unknown `deps` count
+            (`"N.A."`) is treated neutrally. This only applies when the
+            caller flags the need as small-scope.  */
+        if (smallScope && typeof deps === "number")
+            rank *= 1 / (1 + deps);
+        return rank;
     }
     /*  compute the per-alternative product-sum (rating) row from a
         weighted decision matrix. Each input row has the shape
@@ -318,20 +362,28 @@ export class SkillsMCP {
                 "version + earliest/latest release timestamps from the Maven Central Solr " +
                 "search endpoint, the SCM/project URL from the latest POM at `repo1.maven.org`, " +
                 "GitHub stars (if applicable), and the \"Used By\" count from `mvnrepository.com` " +
-                "as the `downloads` proxy. Returns a JSON `text` array of " +
-                "`{ name, version, created, updated, repository, stars, downloads, rank }` " +
-                "objects, sorted in descending order by `rank`. Failures of individual side " +
-                "calls are isolated and reported as `\"N.A.\"` or empty string so every entry " +
-                "has the full shape.",
+                "as the `downloads` proxy. The number of *direct* dependencies is read as `deps` " +
+                "(from the packument version entry for NPM, or the latest POM's `<dependencies>` " +
+                "block for Maven). Returns a JSON `text` array of " +
+                "`{ name, version, created, updated, repository, stars, downloads, deps, rank }` " +
+                "objects, sorted in descending order by `rank`. The `rank` applies a two-tier hard " +
+                "staleness penalty keyed off `staleMonths` (0.3x past the threshold, 0.1x past twice " +
+                "it) and, when `smallScope` is set, a dependency-weight penalty of `1/(1+deps)` so " +
+                "dependency-heavy components sink. Failures of individual side calls are isolated " +
+                "and reported as `\"N.A.\"` or empty string so every entry has the full shape.",
             inputSchema: {
                 stack: z.string()
                     .describe("Technology stack: \"JavaScript\", \"TypeScript\", \"Java\", \"Kotlin\", or \"Unknown\""),
                 components: z.array(z.string())
-                    .describe("List of package names (NPM) or Maven coordinates `groupId:artifactId` (Java/Kotlin)")
+                    .describe("List of package names (NPM) or Maven coordinates `groupId:artifactId` (Java/Kotlin)"),
+                staleMonths: z.number().optional()
+                    .describe("Staleness threshold in months (default 18); a release older than this is rank-penalized"),
+                smallScope: z.boolean().optional()
+                    .describe("If true, penalize each component by its direct-dependency count (small-scope need)")
             }
         }, async (args) => {
             try {
-                const result = await Skills.info(args.stack, args.components);
+                const result = await Skills.info(args.stack, args.components, args.staleMonths, args.smallScope);
                 return {
                     content: [{ type: "text", text: JSON.stringify(result) }]
                 };

package/package.json

@@ -6,7 +6,7 @@
     "homepage":                             "http://github.com/rse/ase",
     "repository":                           { "url": "git+https://github.com/rse/ase.git", "type": "git" },
     "bugs":                                 { "url": "http://github.com/rse/ase/issues" },
-    "version":                              "0.9.35",
+    "version":                              "0.9.36",
     "license":                              "Apache-2.0",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name":        "ase",
-    "version":     "0.9.35",
+    "version":     "0.9.36",
     "description": "Agentic Software Engineering (ASE)",
     "keywords":    [ "agentic", "software", "engineering" ],
     "homepage":    "https://ase.tools",

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name":        "ase",
-    "version":     "0.9.35",
+    "version":     "0.9.36",
     "description": "Agentic Software Engineering (ASE)",
     "keywords":    [ "agentic", "software", "engineering" ],
     "homepage":    "https://ase.tools",

package/plugin/.github/plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name":        "ase",
-    "version":     "0.9.35",
+    "version":     "0.9.36",
     "description": "Agentic Software Engineering (ASE)",
     "keywords":    [ "agentic", "software", "engineering" ],
     "homepage":    "https://ase.tools",

package/plugin/package.json

@@ -6,7 +6,7 @@
     "homepage":                             "http://github.com/rse/ase",
     "repository":                           { "url": "git+https://github.com/rse/ase.git", "type": "git" },
     "bugs":                                 { "url": "http://github.com/rse/ase/issues" },
-    "version":                              "0.9.35",
+    "version":                              "0.9.36",
     "license":                              "Apache-2.0",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",

package/plugin/skills/ase-arch-discover/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ase-arch-discover
-argument-hint: "[--help|-h] [--limit|-l=12] <functionality>"
+argument-hint: "[--help|-h] [--limit|-l=12] [--staleness|-s=18] [--small-scope|-S] <functionality>"
 description: >
     Discover additional, third-party components (libraries/frameworks) for
     the technology stack to provide needed functionality.
@@ -25,7 +25,7 @@ Discover Components
 
 <expand name="getopt"
     arg1="ase-arch-discover"
-    arg2="--limit|-l=12">
+    arg2="--limit|-l=12 --staleness|-s=18 --small-scope|-S">
     $ARGUMENTS
 </expand>
 
@@ -166,18 +166,25 @@ for the technology stack to *provide* the *needed functionality*
             entries by Maven coordinate.
 
     6.  Call the `ase_component_info(stack: "<stack/>", components:
-        [ "<package-1/>", ..., "<package-C/>" ])` tool of the `ase` MCP
-        server *once* for the entire candidate set of discovered packages.
-        The tool dispatches internally on <stack/> and fetches all
-        metadata in maximum parallel and returns an array of objects `{
-        name, version, created, updated, repository, stars, downloads,
-        rank }`. For each
-        component <component-K/> (K=1-C) read from its corresponding
-        entry: <version-K/> from `version`, <updated-K/> from `updated`,
-        <created-K/> from `created`, <repository-K/> from `repository`,
-        <stars-K/> from `stars` (numeric or `N.A.`), <downloads-K/>
-        from `downloads` (numeric or `N.A.`) and <rank-K/> from `rank`
-        (numeric).
+        [ "<package-1/>", ..., "<package-C/>" ], staleMonths:
+        <getopt-option-staleness/>, smallScope: <getopt-option-small-scope/>)`
+        tool of the `ase` MCP server *once* for the entire candidate set of
+        discovered packages. When the <getopt-option-small-scope/> option is
+        enabled, the ranking treats the <functionality/> as *small-scope*,
+        i.e. narrow, self-contained, and low-effort enough that a
+        *dependency-free/hand-rolled* implementation is a realistic
+        alternative to pulling in a third-party component. The tool
+        dispatches internally on <stack/>
+        and fetches all metadata in maximum parallel and returns an array
+        of objects `{ name, version, created, updated, repository, stars,
+        downloads, deps, rank }`. For each component <component-K/>
+        (K=1-C) read from its corresponding entry: <version-K/> from
+        `version`, <updated-K/> from `updated`, <created-K/> from
+        `created`, <repository-K/> from `repository`, <stars-K/> from
+        `stars` (numeric or `N.A.`), <downloads-K/> from `downloads`
+        (numeric or `N.A.`), <deps-K/> from `deps` (numeric or `N.A.`)
+        and <rank-K/> from `rank` (numeric). The returned `rank` already
+        reflects the staleness and small-scope dependency penalties.
 
     7.  Sort, in descending order, the discovered candidate components
         <component-K/> (K=1-C) by their `rank` field and trim the result
@@ -192,7 +199,15 @@ for the technology stack to *provide* the *needed functionality*
         you should not stumble over) is its single most distinguishing
         perspective, and remember this as an <info-K/> (K=1-N) formatted
         like `<type/>: <hint/>` where <type/> is one of `USP`, `Crux`,
-        or `Gotcha` and <hint/> is a 1-6 word hint. Do not output
+        or `Gotcha` and <hint/> is a 1-6 word hint.
+
+        *Staleness override*: determine the coarse age <age-K/> (like
+        `2y`) of the last release from <updated-K/>. If <updated-K/> is
+        known and its age exceeds *twice* <getopt-option-staleness/>
+        months, *append* to <info-K/> the hint `Gotcha: stale/abandoned
+        -- last release <age-K/> ago`; else if its age exceeds
+        <getopt-option-staleness/> months, *append* to <info-K/> the
+        hint `Gotcha: aging -- last release <age-K/> ago`. Do not output
         anything.
     </step>
 
@@ -217,11 +232,11 @@ for the technology stack to *provide* the *needed functionality*
         <template>
         <ase-tpl-bullet-normal/> **COMPONENT RANKING**:
 
-        | ⚑ *Component* | ▣ *Package*    | ❖ *Version*  | ↓ *Downloads*      | ⎈ *Stars*      | ⏲ *Updated*      | ☆ *Created*  |
-        | :------------ | :------------- | -----------: | -----------------: | -------------: | :--------------- | :----------- |
-        | **<name-1/>** | `<package-1/>` | <version-1/> | **<downloads-1/>** | **<stars-1/>** | **<updated-1/>** | <created-1/> |
+        | ⚑ *Component* | ▣ *Package*    | ❖ *Version*  | ↓ *Downloads*      | ⎈ *Stars*      | ⏲ *Updated*      | ☆ *Created*  | ⚭ *Dep.*   |
+        | :------------ | :------------- | -----------: | -----------------: | -------------: | :--------------- | :----------- | ---------: |
+        | **<name-1/>** | `<package-1/>` | <version-1/> | **<downloads-1/>** | **<stars-1/>** | **<updated-1/>** | <created-1/> | <deps-1/>  |
         [...]
-        | **<name-N/>** | `<package-N/>` | <version-N/> | **<downloads-N/>** | **<stars-N/>** | **<updated-N/>** | <created-N/> |
+        | **<name-N/>** | `<package-N/>` | <version-N/> | **<downloads-N/>** | **<stars-N/>** | **<updated-N/>** | <created-N/> | <deps-N/>  |
         </template>
     </step>
 </flow>

package/plugin/skills/ase-arch-discover/help.md

@@ -8,6 +8,8 @@
 `ase-arch-discover`
     [`--help`|`-h`]
     [`--limit`|`-l=12`]
+    [`--staleness`|`-s=18`]
+    [`--small-scope`|`-S`]
     *functionality*
 
 ##  DESCRIPTION
@@ -20,9 +22,13 @@ The skill determines the project's technology stack (TypeScript,
 JavaScript, Kotlin, or Java), derives essential keywords from the
 requested functionality, queries the corresponding package registry
 (NPM or Maven Central), retrieves metadata (version, downloads,
-stars, dates) via the `ase_component_info` MCP tool, and reports
-the top-ranked components as a Markdown table together with a single
-distinguishing hint (USP, Crux, or Gotcha) per component.
+stars, dates, dependency count) via the `ase_component_info` MCP tool,
+and reports the top-ranked components as a Markdown table together with
+a single distinguishing hint (USP, Crux, or Gotcha) per component.
+
+The ranking penalizes *stale* components (last release older than the
+`--staleness` threshold) and, when the `--small-scope` option is given,
+demotes dependency-heavy components.
 
 ##  OPTIONS
 
@@ -31,6 +37,19 @@ distinguishing hint (USP, Crux, or Gotcha) per component.
     in the final ranking (default: 12). Raise it for a broader, more
     exhaustive survey, lower it for a quicker, narrower lookup.
 
+`--staleness`|`-s=18`:
+    The *staleness threshold* in months (default: 18). A component whose
+    last release is older than this is rank-penalized and flagged with an
+    `aging` gotcha; older than *twice* the threshold, it is penalized
+    harder and flagged as `stale/abandoned`.
+
+`--small-scope`|`-S`:
+    Treat the requested *functionality* as *small-scope* (default: off).
+    When enabled, the ranking demotes dependency-heavy components by a
+    dependency-weight penalty, since a dependency-free/hand-rolled
+    implementation is a realistic alternative for narrow, self-contained
+    functionality.
+
 ##  ARGUMENTS
 
 *functionality*:
@@ -57,6 +76,12 @@ Discover a broader set of up to 20 HTTP client components:
 ❯ /ase-arch-discover --limit 20 HTTP client with retries
 ```
 
+Discover HTTP clients, flagging any without a release in the last 12 months:
+
+```text
+❯ /ase-arch-discover --staleness 12 HTTP client with retries
+```
+
 ##  SEE ALSO
 
 [`ase-arch-analyze`](../ase-arch-analyze/help.md), [`ase-meta-search`](../ase-meta-search/help.md), [`ase-meta-evaluate`](../ase-meta-evaluate/help.md).