@nebutra/next-unicorn-skill 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -5,20 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.0.2] - 2026-02-09
+## [1.0.3] - 2026-02-09
 
 ### Added
 
-- **Ecosystem-level recommendations** — `LibraryRecommendation` now supports `rationale`, `ecosystem` (companion packages with roles), and `stackContext` fields, enabling AI agents to produce unicorn-grade solution stacks instead of single-library suggestions
-- New `EcosystemPackage` type for companion packages (library + version + role)
-- Output schema `RecommendedChange.recommendedLibrary` extended with `rationale`, `ecosystem`, and `stackContext` optional fields
-- SKILL.md Step 3 rewritten to guide AI agents toward ecosystem-level thinking: "not just 'a library that does this', but the specific combination of tools that the best engineering teams ship with"
+- **Gap Analysis** — AI agent can now identify capabilities the project is MISSING entirely, not just hand-rolled code to replace. New `GapRecommendation` type with `domain`, `description`, `recommendedLibrary`, and `priority` (critical/recommended/nice-to-have).
+- New `gaps` option in `AnalyzeOptions` — AI agent provides gap recommendations alongside scanner-based detections.
+- New `gapAnalysis` field in `OutputSchema` — gap recommendations appear in the output alongside `recommendedChanges`.
+- New `GapRecommendationSchema` Zod schema with full validation.
+- SKILL.md Step 2.5: Gap Analysis guidance for AI agents.
+- 3 new gap analysis tests (202 total).
 
 ### Changed
 
-- `LibraryRecommendation` interface extended (backward-compatible — new fields are optional)
-- SKILL.md example now shows full ecosystem recommendation (@lingui/core + @lingui/macro + @lingui/cli + Crowdin TMS)
-- Version bumped to 1.0.2
+- `LibraryRecommendation` enriched with optional `rationale`, `ecosystem`, `antiPatterns`, `alternatives` fields — AI agent can express ecosystem-level solutions (e.g., Lingui + TMS + compile-time extraction).
+- `RecommendedChange.recommendedLibrary` output schema widened to match enriched `LibraryRecommendation`.
+- SKILL.md Step 3 renamed "Recommend Solutions" — guides AI agent to think at ecosystem level.
+- Summary table template updated to render rationale, ecosystem, anti-patterns, and alternatives.
+- README updated with gap analysis, ecosystem recommendations features and API docs.
 
 ## [1.0.1] - 2026-02-09
 

package/README.md

@@ -63,20 +63,14 @@ npm install @nebutra/next-unicorn-skill
 import { analyze, scanCodebase } from '@nebutra/next-unicorn-skill';
 import type { Recommender } from '@nebutra/next-unicorn-skill';
 
-// The recommender function: AI agent decides the full ecosystem for each detection
+// The recommender function: AI agent decides which library fits each detection
 const recommender: Recommender = (detection) => {
   // AI agent uses its knowledge + project context to recommend
   // Return null to skip a detection (false positive, intentional custom code)
   return {
-    library: '@lingui/core',          // primary library
-    version: '^4.0.0',               // verified via Context7
+    library: 'zustand',       // dynamically chosen, not hardcoded
+    version: '^5.0.0',        // verified via Context7
     license: 'MIT',
-    rationale: 'Compile-time extraction with near-zero runtime overhead',
-    ecosystem: [                      // companion packages
-      { library: '@lingui/macro', version: '^4.0.0', role: 'Zero-runtime tagged templates' },
-      { library: '@lingui/cli', version: '^4.0.0', role: 'CI/CD message extraction' },
-    ],
-    stackContext: 'Integrate with Crowdin TMS for professional translation workflows',
   };
 };
 
@@ -118,6 +112,8 @@ Or use as an **MCP SKILL** — provide [`SKILL.md`](./SKILL.md) to your AI agent
 | Feature | Description |
 |---------|-------------|
 | **Pattern-based scanning** | Detects hand-rolled code across 68 Vibe Coding Domains (ISO 25010-aligned) |
+| **Gap analysis** | AI agent identifies missing capabilities — not just hand-rolled code, but things you should have but don't (e.g., no error monitoring, no rate limiting, no event-driven workflows) |
+| **Ecosystem-level recommendations** | Solutions include rationale, companion packages, anti-patterns, and alternatives — not just "use library X" |
 | **Context7 verification** | Every recommendation verified against real, version-correct documentation |
 | **7-dimension impact scoring** | Scalability, performance, security, maintainability, feature richness, UX, UI aesthetics |
 | **Phased migration plans** | Low / medium / high risk phases with adapter strategies |
@@ -245,6 +241,7 @@ const logger = pino({
 | `input` | `InputSchema` | Yes | Project metadata, goals, constraints, focus areas |
 | `context7Client` | `Context7Client` | Yes | Context7 MCP client for doc verification |
 | `recommender` | `Recommender` | Yes | Maps each detection → library recommendation (AI agent provides this) |
+| `gaps` | `GapRecommendation[]` | No | Missing capabilities the project should have (AI agent identifies these) |
 | `vulnClient` | `VulnerabilityClient` | No | OSV client for vulnerability scanning |
 | `registryClient` | `RegistryClient` | No | Package registry client for auto-update |
 | `platformClient` | `PlatformClient` | No | GitHub/GitLab client for PR creation |
@@ -258,7 +255,8 @@ Standalone scanner — returns detections and workspace info without recommendat
 
 ```jsonc
 {
-  "recommendedChanges": [...],     // Recommendations with impact scores
+  "recommendedChanges": [...],     // Replacement recommendations with impact scores
+  "gapAnalysis": [...],            // (optional) Missing capabilities with prioritized recs
   "filesToDelete": [...],          // Files to remove after migration
   "linesSavedEstimate": 1250,      // Total lines saved
   "uxAudit": [...],                // UX completeness (8 categories)

package/SKILL.md

@@ -1,87 +1,78 @@
 ---
 name: analyze-and-recommend-third-party-optimizations
-description: Scans any codebase and identifies where hand-rolled implementations should be replaced by battle-tested third-party libraries, producing structured migration plans with Context7-verified recommendations
-version: 1.0.2
-author: TsekaLuk
-tags:
-  - code-analysis
-  - third-party-libraries
-  - migration-planning
-  - dependency-optimization
-  - context7-verification
-  - ux-audit
-  - impact-scoring
-  - vulnerability-scanning
-  - auto-update
-  - pr-automation
+description: >-
+  Scan a codebase to identify hand-rolled implementations that should be replaced
+  by third-party libraries, and identify missing capabilities the project should
+  have. Produce structured migration plans with Context7-verified recommendations.
+  Use when analyzing technical debt, auditing dependency health, reviewing
+  hand-rolled code, planning library migrations, or assessing capability gaps.
 ---
 
 # Analyze and Recommend Third-Party Optimizations
 
-## Purpose
-
-Scan a codebase to identify hand-rolled implementations that should be replaced by third-party libraries. The scanner detects WHAT is hand-rolled; the AI agent decides WHAT to recommend based on project context, current ecosystem knowledge, and Context7 MCP verification.
-
 ## Architecture
 
 ```
-Scanner (deterministic)     →  AI Agent (generative)        →  Pipeline (deterministic)
-Regex patterns detect          Agent recommends library         Score, plan, audit,
-hand-rolled code               using knowledge + Context7       filter, serialize
+Scanner (deterministic)     →  AI Agent (generative)           →  Pipeline (deterministic)
+Regex patterns detect          1. Recommend replacements           Score, plan, audit,
+hand-rolled code               2. Identify capability gaps         filter, serialize
+                               using knowledge + Context7
 ```
 
-**Key principle**: The pattern catalog contains NO hardcoded library recommendations. Library choices depend on project framework, runtime, existing dependencies, and current ecosystem state — all of which the AI agent evaluates dynamically.
+**Design constraints**:
+- No hardcoded library recommendations — evaluate project context dynamically
+- Two analysis modes: **replacement** (hand-rolled code found) and **gap** (capability missing entirely)
 
 ## Standard Operating Procedure
 
 ### Step 1: Validate Input
 
-Parse and validate `InputSchema` JSON via Zod. Required fields:
-- **Project metadata**: repo path, languages, package managers, current libraries
-- **Optimization goals**: what the project wants to improve
-- **Constraints**: license allowlist, excluded libraries
-- **Priority focus areas**: Vibe Coding Domains to prioritize
+Parse and validate `InputSchema` JSON via Zod. Read `src/schemas/input.schema.ts` for the full schema.
 
 ### Step 2: Scan Codebase
 
-Run `scanCodebase(input)` to walk the file tree and match against regex patterns. The scanner:
+Run `scanCodebase(input)`. The scanner:
+
+1. Detect workspace roots for monorepo support
+2. Match code against 20+ domain patterns (i18n, auth, state-management, etc.)
+3. Record each detection with: file path, line range, pattern category, confidence score, domain
+4. Return `ScanResult` with detections and workspace info
+
+Detections contain no library suggestions — only what was detected and where.
+
+### Step 2.5: Gap Analysis (AI Agent)
+
+Beyond scanner detections, analyze what the project is **missing entirely**. Inspect:
 
-1. Detects workspace roots for monorepo support
-2. Matches code against 20+ domain patterns (i18n, auth, state-management, etc.)
-3. Records each detection with: file path, line range, pattern category, confidence score, domain
-4. Returns `ScanResult` with detections and workspace info
+1. **Installed dependencies** — identify low-level tools that should be upgraded to platform-level solutions
+2. **Monorepo structure** — identify missing architectural layers (e.g., shared token package, shared config preset)
+3. **Cross-cutting concerns** — identify absent capabilities: structured logging, error monitoring, rate limiting, event-driven workflows, transactional email, type-safe API layer
+4. **Architecture patterns** — identify opportunities for multi-package solutions (e.g., design-tokens → tailwind-config → ui three-layer architecture for design systems)
 
-Detections contain **no library suggestions** — only what was detected and where.
+Analyze at three levels of depth:
+- **Single library gap**: missing one tool (e.g., no form validation library)
+- **Ecosystem gap**: missing a coordinated set of tools (e.g., no observability stack)
+- **Architecture gap**: missing an entire structural layer (e.g., no design system, no shared config)
+
+Provide each gap as a `GapRecommendation`. Read `src/index.ts` for the interface. Pass gaps via the `gaps` option in `analyze()`.
+
+**Design system gaps** — Two paths depending on project maturity:
+- **No existing frontend**: Scaffold from reference repos. Read `references/design-system-sources.md` for curated sources and sparse-checkout workflow.
+- **Existing frontend without formal design system**: First extract the spec (audit → tokens → classify → document) via `references/design-system-extraction.md`, then implement the architecture via `references/design-system-sources.md`.
 
 ### Step 3: Recommend Solutions (AI Agent)
 
-For each detection, recommend a **unicorn-grade solution** — not just "a library that does this", but the specific combination of tools that the best engineering teams ship with, configured the way they configure it.
-
-**Recommendation approach:**
-
-1. **Project context** — framework, runtime, existing deps determine the primary library (Next.js App Router → next-intl; Vite SPA → @lingui/core; Edge → jose, not jsonwebtoken)
-2. **Full ecosystem** — include companion packages that complete the solution (e.g., @lingui/macro for zero-runtime tagged templates + @lingui/cli for CI extraction + Crowdin TMS for professional translation workflows)
-3. **Stack integration** — explain how this fits the broader architecture (e.g., "combine react-hook-form + @hookform/resolvers + zod for schema-validated forms that share types with server validation")
-4. **Context7 verification** — call `resolve-library-id` + `query-docs` to confirm the library exists and get latest version/docs
-
-Return a `LibraryRecommendation` per detection:
-```typescript
-{
-  library: '@lingui/core',
-  version: '^4.0.0',
-  license: 'MIT',
-  rationale: 'Compile-time message extraction with near-zero runtime overhead',
-  ecosystem: [
-    { library: '@lingui/macro', version: '^4.0.0', role: 'Zero-runtime tagged template macros' },
-    { library: '@lingui/cli', version: '^4.0.0', role: 'CI/CD message extraction pipeline' },
-  ],
-  stackContext: 'Integrate with Crowdin TMS for professional translation workflows; use @lingui/vite-plugin for Vite or @lingui/swc-plugin for Next.js SWC compiler',
-}
-```
+For each scanner detection, recommend a **solution**. Consider:
 
-Return `null` to skip a detection (intentional custom code, false positive, etc.).
+1. **Ecosystem composition** — recommend companion libraries that work together
+2. **Rationale** — explain WHY this choice fits this project's framework, runtime, and scale
+3. **Anti-patterns** — what NOT to use and why
+4. **Alternatives** — different solutions for different architectural contexts
+5. **Context7 verification** — call `resolve-library-id` + `query-docs` to confirm the library exists and get latest version/docs
 
-**False positive filtering** — skip if:
+Read `src/index.ts` for the `LibraryRecommendation` interface. Return `null` to skip a detection.
+
+**Skip a detection if**:
 - Code has comments explaining why it is custom
 - Detection is in test/mock/fixture files
 - Library is already in project dependencies (suggest version update instead)
@@ -89,15 +80,15 @@ Return `null` to skip a detection (intentional custom code, false positive, etc.
 
 ### Step 4: Score Impact
 
-Compute 7-dimension impact scores (scalability, performance, security, maintainability, feature richness, UX, UI aesthetics) with composite score, migration risk, and estimated effort.
+Call `computeImpactScore()` for each detection. Optionally provide `dimensionHints` and `baseEffortHours` for more accurate scoring. Read `src/scorer/impact-scorer.ts` for the interface.
 
 ### Step 5: Build Migration Plan
 
-Group recommendations into phases by risk (low → medium → high), ordered by domain priority (infrastructure first, presentation last). High-risk items include adapter strategies.
+Call `buildMigrationPlan()` to group recommendations into phases by risk (low, medium, high). High-risk items include adapter strategies.
 
 ### Step 6: Audit UX Completeness
 
-Evaluate frontend codebase across 8 UX categories: accessibility, error/empty/loading states, form validation, performance feel, copy consistency, design system alignment.
+Call `auditUxCompleteness()` to evaluate 8 UX categories. The auditor determines status (present/partial/missing). Fill in `recommendedLibrary` on partial/missing items based on project context.
 
 ### Step 7: Apply Constraints and Serialize
 
@@ -105,64 +96,21 @@ Filter by license allowlist, detect dependency conflicts, serialize to JSON.
 
 ### Optional Steps
 
-- **Step 8**: Vulnerability scanning via OSV database
-- **Step 9**: Auto-update existing dependencies via registry queries
-- **Step 10**: PR auto-creation via GitHub/GitLab API
-
-## Programmatic API
-
-```typescript
-import { analyze, scanCodebase } from './src/index.js';
-import type { Recommender } from './src/index.js';
-
-// Step 1: Scan standalone (for AI agent inspection)
-const scanResult = await scanCodebase(validatedInput);
-
-// Step 2: Full pipeline with ecosystem-level recommender
-const recommender: Recommender = (detection) => ({
-  library: '@lingui/core',
-  version: '^4.0.0',
-  license: 'MIT',
-  rationale: 'Compile-time extraction with near-zero runtime overhead',
-  ecosystem: [
-    { library: '@lingui/macro', version: '^4.0.0', role: 'Zero-runtime tagged templates' },
-    { library: '@lingui/cli', version: '^4.0.0', role: 'CI message extraction' },
-  ],
-  stackContext: 'Integrate with Crowdin TMS; use @lingui/swc-plugin for Next.js',
-});
-
-const result = await analyze({
-  input: inputJson,
-  context7Client: myContext7Client,
-  recommender, // AI agent provides ecosystem-level recommendations
-});
-```
+- **Step 8**: Vulnerability scan via OSV database (`vulnClient`)
+- **Step 9**: Auto-update existing dependencies (`registryClient`)
+- **Step 10**: PR auto-creation via GitHub/GitLab (`platformClient` + `gitOps`)
 
-## Output Artifacts
+## Output
 
 Single `OutputSchema` JSON containing:
-- `recommendedChanges` — recommendations with scores, verification status, adapter strategies
+- `recommendedChanges` — replacement recommendations with scores, verification, adapter strategies
+- `gapAnalysis` (optional) — missing capabilities with prioritized recommendations
 - `filesToDelete` — file paths to remove after migration
 - `linesSavedEstimate` — total lines saved
-- `uxAudit` — UX completeness checklist
+- `uxAudit` — UX completeness checklist (8 categories)
 - `migrationPlan` — phased plan with deletion checklist
 - `vulnerabilityReport` (optional)
 - `updatePlan` (optional)
 - `pullRequests` (optional)
 
-## Vibe Coding Domain Coverage (20+ detection patterns)
-
-| Category | Domains |
-|----------|---------|
-| UX / Design | ux-completeness, a11y-accessibility, forms-ux, state-management |
-| SEO / i18n / Content | seo, i18n, content-marketing |
-| Growth / Data | growth-hacking |
-| App Architecture | agent-architecture, data-fetching-caching, error-handling-resilience |
-| Backend / Platform | database-orm-migrations, auth-security |
-| Observability | observability, logging-tracing-metrics |
-| Testing | testing-strategy |
-| AI Engineering | ai-model-serving |
-| Business | cross-border-ecommerce |
-| File / Media | file-upload-media |
-
-> **Extensibility:** Use `customDomains?: string[]` in input for project-specific domains.
+Read `src/schemas/output.schema.ts` for the full schema.

package/dist/analyzer/pattern-catalog.d.ts

@@ -25,10 +25,13 @@ export interface PatternDefinition {
 }
 /**
  * Returns the full pattern catalog covering Vibe Coding domains.
- * Each covered domain has 2–3 patterns for hand-rolled code detection.
+ *
+ * Domain assignment rules:
+ * - Each pattern goes in its MOST SPECIFIC domain (e.g., A/B test → ab-testing-experimentation, not growth-hacking)
+ * - Parent domains (growth-hacking, observability, ux-completeness) are used only when no specific child domain fits
+ * - Domains with no regex-detectable patterns are left for Gap Analysis (AI Agent)
  *
  * The catalog defines WHAT to detect, not WHAT to recommend.
- * Library recommendations are generated dynamically by the AI agent.
  */
 export declare function getPatternCatalog(): PatternDefinition[];
 /**

package/dist/analyzer/pattern-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pattern-catalog.d.ts","sourceRoot":"","sources":["../../src/analyzer/pattern-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEnE;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,6EAA6E;IAC7E,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,MAAM,EAAE,gBAAgB,CAAC;IACzB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,+CAA+C;IAC/C,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,iBAAiB,EAAE,CAuiBvD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAExE"}
+{"version":3,"file":"pattern-catalog.d.ts","sourceRoot":"","sources":["../../src/analyzer/pattern-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEnE;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,6EAA6E;IAC7E,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,MAAM,EAAE,gBAAgB,CAAC;IACzB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,+CAA+C;IAC/C,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,IAAI,iBAAiB,EAAE,CAkqBvD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAExE"}