@skillit/core 1.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Pradeep Mouli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# @skillit/core
+
+Shared types, renderers, and utilities for the [skillit](https://github.com/pradeepmouli/skillit) plugin ecosystem.
+
+## Usage
+
+This package is used by source adapters (like `@skillit/typedoc`) to render extracted API info into SKILL.md and llms.txt files. You typically don't install this directly — it's a dependency of the plugins.
+
+```ts
+import {
+  renderSkills,
+  renderSkill,
+  writeSkills,
+  renderLlmsTxt,
+  estimateTokens
+} from '@skillit/core';
+
+// Render extracted skills into SKILL.md files
+const rendered = renderSkills(extractedSkills, {
+  outDir: 'skills',
+  maxTokens: 4000,
+  license: 'MIT'
+});
+
+// Write to disk
+writeSkills(rendered, { outDir: 'skills' });
+
+// Optionally render llms.txt
+const llms = renderLlmsTxt(extractedSkills, {
+  projectName: 'my-lib',
+  projectDescription: 'A great library'
+});
+```
+
+## API
+
+### `renderSkills(skills, options?)` / `renderSkill(skill, options?)`
+
+Renders extracted API data into SKILL.md content with agentskills.io-compliant frontmatter.
+
+### `renderLlmsTxt(skills, options)`
+
+Renders llms.txt (summary index) and llms-full.txt (complete API) following the llmstxt.org spec.
+
+### `writeSkills(rendered, options)`
+
+Writes rendered skill files to disk.
+
+### `estimateTokens(text)` / `truncateToTokenBudget(text, maxTokens)`
+
+Token budgeting utilities (~4 chars/token estimation).
+
+## License
+
+MIT

package/dist/audit-formatter.d.ts

@@ -0,0 +1,36 @@
+import type { AuditResult } from './audit-types.js';
+import type { SkillJudgeEstimate } from './audit-score.js';
+/**
+ * Format an {@link AuditResult} as human-readable text suitable for TypeDoc logs.
+ *
+ * Output groups issues by severity (fatal → error → warning → alert),
+ * then lists passing checks at the end. Empty severity groups are omitted.
+ *
+ * @category Audit
+ */
+export declare function formatAuditText(result: AuditResult): string;
+/**
+ * Format an {@link AuditResult} as pretty-printed JSON for machine consumption.
+ *
+ * Returns the full result object serialized with 2-space indentation so it
+ * can be parsed by downstream tooling without any further transformation.
+ *
+ * @category Audit
+ */
+export declare function formatAuditJson(result: AuditResult): string;
+/**
+ * Format a {@link SkillJudgeEstimate} as human-readable text.
+ *
+ * Shows total score, grade, per-dimension breakdown with inline suggestions
+ * for dimensions below 80% of their max, and a numbered improvement list.
+ *
+ * @example
+ * ```typescript
+ * const estimate = estimateSkillJudgeScore(auditResult);
+ * console.log(formatScoreEstimate(estimate));
+ * ```
+ *
+ * @category Audit
+ */
+export declare function formatScoreEstimate(estimate: SkillJudgeEstimate): string;
+//# sourceMappingURL=audit-formatter.d.ts.map

package/dist/audit-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-formatter.d.ts","sourceRoot":"","sources":["../src/audit-formatter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,WAAW,EAAiB,MAAM,kBAAkB,CAAC;AAC/E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAuD3D;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAwC3D;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAE3D;AAmCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,CAyCxE"}

package/dist/audit-formatter.js

@@ -0,0 +1,173 @@
+// ---------------------------------------------------------------------------
+// Severity display configuration
+// ---------------------------------------------------------------------------
+const SEVERITY_ORDER = ['fatal', 'error', 'warning', 'alert'];
+const SEVERITY_EMOJI = {
+    fatal: '🔴',
+    error: '🔴',
+    warning: '🟡',
+    alert: '🔵'
+};
+const SEVERITY_LABEL = {
+    fatal: 'FATAL',
+    error: 'ERROR',
+    warning: 'WARNING',
+    alert: 'ALERT'
+};
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function fileRef(issue) {
+    return issue.line !== null ? `${issue.file}:${issue.line}` : issue.file;
+}
+function groupBySeverity(issues) {
+    const map = new Map();
+    for (const sev of SEVERITY_ORDER) {
+        map.set(sev, []);
+    }
+    for (const issue of issues) {
+        map.get(issue.severity).push(issue);
+    }
+    return map;
+}
+function groupByFile(issues) {
+    const map = new Map();
+    for (const issue of issues) {
+        const ref = fileRef(issue);
+        if (!map.has(ref))
+            map.set(ref, []);
+        map.get(ref).push(issue);
+    }
+    return map;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Format an {@link AuditResult} as human-readable text suitable for TypeDoc logs.
+ *
+ * Output groups issues by severity (fatal → error → warning → alert),
+ * then lists passing checks at the end. Empty severity groups are omitted.
+ *
+ * @category Audit
+ */
+export function formatAuditText(result) {
+    const lines = [];
+    // Header
+    lines.push(`📊 Skill Documentation Audit: ${result.package}`);
+    const { fatal, error, warning, alert } = result.summary;
+    lines.push(`   ${fatal} fatal · ${error} error · ${warning} warning · ${alert} alert`);
+    // Issue groups
+    const bySeverity = groupBySeverity(result.issues);
+    for (const sev of SEVERITY_ORDER) {
+        const sevIssues = bySeverity.get(sev);
+        if (sevIssues.length === 0)
+            continue;
+        lines.push('');
+        lines.push(`${SEVERITY_EMOJI[sev]} ${SEVERITY_LABEL[sev]} (${sevIssues.length})`);
+        lines.push('');
+        const byFile = groupByFile(sevIssues);
+        for (const [ref, fileIssues] of byFile) {
+            lines.push(`  ${ref}`);
+            for (const issue of fileIssues) {
+                lines.push(`    ⚠ ${issue.message}`);
+                lines.push(`      Suggestion: ${issue.suggestion}`);
+            }
+        }
+    }
+    // Passing checks
+    if (result.passing.length > 0) {
+        lines.push('');
+        lines.push(`✅ PASSING (${result.passing.length} checks)`);
+        for (const pass of result.passing) {
+            const detail = pass.detail ? ` — ${pass.detail}` : '';
+            lines.push(`  ✓ ${pass.message}${detail}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Format an {@link AuditResult} as pretty-printed JSON for machine consumption.
+ *
+ * Returns the full result object serialized with 2-space indentation so it
+ * can be parsed by downstream tooling without any further transformation.
+ *
+ * @category Audit
+ */
+export function formatAuditJson(result) {
+    return JSON.stringify(result, null, 2);
+}
+// ---------------------------------------------------------------------------
+// Dimension metadata for formatting
+// ---------------------------------------------------------------------------
+const DIMENSION_LABELS = [
+    {
+        key: 'd1_knowledgeDelta',
+        label: 'D1 Knowledge Delta',
+        max: 20,
+        hint: 'add @remarks to complex functions'
+    },
+    { key: 'd2_procedures', label: 'D2 Procedures', max: 15, hint: 'add @useWhen' },
+    { key: 'd3_antiPatterns', label: 'D3 Anti-Patterns', max: 15, hint: 'add @never' },
+    { key: 'd4_description', label: 'D4 Description', max: 15, hint: 'add package.json description' },
+    {
+        key: 'd5_progressiveDisclosure',
+        label: 'D5 Progressive Disclosure',
+        max: 15,
+        hint: 'add @category'
+    },
+    { key: 'd6_freedom', label: 'D6 Freedom', max: 15, hint: 'add @avoidWhen' },
+    { key: 'd7_pattern', label: 'D7 Pattern', max: 10, hint: 'add @category' },
+    { key: 'd8_usability', label: 'D8 Usability', max: 15, hint: 'add @param/@returns' }
+];
+// Width of the longest label (for alignment)
+const LABEL_WIDTH = Math.max(...DIMENSION_LABELS.map((d) => d.label.length));
+/**
+ * Format a {@link SkillJudgeEstimate} as human-readable text.
+ *
+ * Shows total score, grade, per-dimension breakdown with inline suggestions
+ * for dimensions below 80% of their max, and a numbered improvement list.
+ *
+ * @example
+ * ```typescript
+ * const estimate = estimateSkillJudgeScore(auditResult);
+ * console.log(formatScoreEstimate(estimate));
+ * ```
+ *
+ * @category Audit
+ */
+export function formatScoreEstimate(estimate) {
+    const lines = [];
+    // Header
+    lines.push(`📊 Skill-Judge Estimate: ${estimate.total}/${120} (${estimate.percentage}%) — Grade ${estimate.grade}`);
+    lines.push('');
+    // Per-dimension rows
+    for (const dim of DIMENSION_LABELS) {
+        const score = estimate.dimensions[dim.key];
+        const pctOfMax = score / dim.max;
+        const needsHint = pctOfMax < 0.8;
+        const labelPadded = dim.label.padEnd(LABEL_WIDTH);
+        const scoreStr = `${score}/${dim.max}`;
+        // Right-align score within a 5-char field
+        const scoreField = scoreStr.padStart(5);
+        const hintStr = needsHint ? `  ← ${dim.hint}` : '';
+        lines.push(`  ${labelPadded}: ${scoreField}${hintStr}`);
+    }
+    // Top improvements
+    if (estimate.improvements.length > 0) {
+        lines.push('');
+        lines.push('  Top improvements:');
+        estimate.improvements.forEach((imp, i) => {
+            const hasTargets = imp.targets && imp.targets.length > 0;
+            const suffix = hasTargets ? ' — missing on:' : '';
+            lines.push(`  ${i + 1}. ${imp.suggestion}${suffix}`);
+            if (hasTargets && imp.targets) {
+                for (const t of imp.targets) {
+                    lines.push(`     ${t.file} → ${t.name} (${t.kind})`);
+                }
+            }
+        });
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=audit-formatter.js.map

package/dist/audit-formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-formatter.js","sourceRoot":"","sources":["../src/audit-formatter.ts"],"names":[],"mappings":"AAGA,8EAA8E;AAC9E,iCAAiC;AACjC,8EAA8E;AAE9E,MAAM,cAAc,GAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AAE/E,MAAM,cAAc,GAAkC;IACpD,KAAK,EAAE,IAAI;IACX,KAAK,EAAE,IAAI;IACX,OAAO,EAAE,IAAI;IACb,KAAK,EAAE,IAAI;CACZ,CAAC;AAEF,MAAM,cAAc,GAAkC;IACpD,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;CACf,CAAC;AAEF,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,SAAS,OAAO,CAAC,KAAiB;IAChC,OAAO,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;AAC1E,CAAC;AAED,SAAS,eAAe,CAAC,MAAoB;IAC3C,MAAM,GAAG,GAAG,IAAI,GAAG,EAA+B,CAAC;IACnD,KAAK,MAAM,GAAG,IAAI,cAAc,EAAE,CAAC;QACjC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACnB,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,WAAW,CAAC,MAAoB;IACvC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC5C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;QAC3B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACpC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,MAAmB;IACjD,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,SAAS;IACT,KAAK,CAAC,IAAI,CAAC,iCAAiC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9D,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC;IACxD,KAAK,CAAC,IAAI,CAAC,MAAM,KAAK,YAAY,KAAK,YAAY,OAAO,cAAc,KAAK,QAAQ,CAAC,CAAC;IAEvF,eAAe;IACf,MAAM,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAElD,KAAK,MAAM,GAAG,IAAI,cAAc,EAAE,CAAC;QACjC,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC;QACvC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAErC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,GAAG,cAAc,CAAC,GAAG,CAAC,IAAI,cAAc,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;QAClF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAEf,MAAM,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;QACtC,KAAK,MAAM,CAAC,GAAG,EAAE,UAAU,CAAC,IAAI,MAAM,EAAE,CAAC;YACvC,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC;YACvB,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE,CAAC;gBAC/B,KAAK,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;gBACrC,KAAK,CAAC,IAAI,CAAC,qBAAqB,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC;YACtD,CAAC;QACH,CAAC;IACH,CAAC;IAED,iBAAiB;IACjB,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,cAAc,MAAM,CAAC,OAAO,CAAC,MAAM,UAAU,CAAC,CAAC;QAC1D,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YAClC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACtD,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,GAAG,MAAM,EAAE,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,MAAmB;IACjD,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AACzC,CAAC;AAED,8EAA8E;AAC9E,oCAAoC;AACpC,8EAA8E;AAE9E,MAAM,gBAAgB,GAKjB;IACH;QACE,GAAG,EAAE,mBAAmB;QACxB,KAAK,EAAE,oBAAoB;QAC3B,GAAG,EAAE,EAAE;QACP,IAAI,EAAE,mCAAmC;KAC1C;IACD,EAAE,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,eAAe,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE;IAC/E,EAAE,GAAG,EAAE,iBAAiB,EAAE,KAAK,EAAE,kBAAkB,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE;IAClF,EAAE,GAAG,EAAE,gBAAgB,EAAE,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,8BAA8B,EAAE;IACjG;QACE,GAAG,EAAE,0BAA0B;QAC/B,KAAK,EAAE,2BAA2B;QAClC,GAAG,EAAE,EAAE;QACP,IAAI,EAAE,eAAe;KACtB;IACD,EAAE,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE;IAC3E,EAAE,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE;IAC1E,EAAE,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,qBAAqB,EAAE;CACrF,CAAC;AAEF,6CAA6C;AAC7C,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;AAE7E;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAA4B;IAC9D,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,SAAS;IACT,KAAK,CAAC,IAAI,CACR,4BAA4B,QAAQ,CAAC,KAAK,IAAI,GAAG,KAAK,QAAQ,CAAC,UAAU,cAAc,QAAQ,CAAC,KAAK,EAAE,CACxG,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,qBAAqB;IACrB,KAAK,MAAM,GAAG,IAAI,gBAAgB,EAAE,CAAC;QACnC,MAAM,KAAK,GAAG,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC3C,MAAM,QAAQ,GAAG,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC;QACjC,MAAM,SAAS,GAAG,QAAQ,GAAG,GAAG,CAAC;QAEjC,MAAM,WAAW,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAClD,MAAM,QAAQ,GAAG,GAAG,KAAK,IAAI,GAAG,CAAC,GAAG,EAAE,CAAC;QACvC,0CAA0C;QAC1C,MAAM,UAAU,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QACxC,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAEnD,KAAK,CAAC,IAAI,CAAC,KAAK,WAAW,KAAK,UAAU,GAAG,OAAO,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,mBAAmB;IACnB,IAAI,QAAQ,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;QAClC,QAAQ,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;YACvC,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;YACzD,MAAM,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;YAClD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,UAAU,GAAG,MAAM,EAAE,CAAC,CAAC;YACrD,IAAI,UAAU,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;gBAC9B,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;oBAC5B,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;gBACvD,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/audit-score.d.ts

@@ -0,0 +1,76 @@
+import type { AuditResult } from './audit-types.js';
+import type { ExtractedSkill } from './types.js';
+/**
+ * An agent-actionable improvement suggestion with specific file/export targets.
+ *
+ * @category Audit
+ */
+export interface ActionableImprovement {
+    /** Human-readable suggestion */
+    suggestion: string;
+    /** Points gained if fixed */
+    points: number;
+    /** Dimension affected (e.g. "D3") */
+    dimension: string;
+    /** Specific exports to annotate (file path → export name + kind) */
+    targets?: Array<{
+        file: string;
+        name: string;
+        kind: string;
+    }>;
+}
+/**
+ * A skill-judge score estimate derived from audit check results.
+ *
+ * Maps the 20+ audit checks to the 8 skill-judge dimensions and produces
+ * a total score, percentage, letter grade, and top improvement suggestions.
+ *
+ * @category Audit
+ */
+export interface SkillJudgeEstimate {
+    dimensions: {
+        /** /20 — How much new knowledge the skill imparts */
+        d1_knowledgeDelta: number;
+        /** /15 — Quality of usage procedures and conditions */
+        d2_procedures: number;
+        /** /15 — Coverage of known pitfalls and anti-patterns */
+        d3_antiPatterns: number;
+        /** /15 — Clarity and completeness of descriptions */
+        d4_description: number;
+        /** /15 — Progressive disclosure: discovery vs. depth */
+        d5_progressiveDisclosure: number;
+        /** /15 — Freedom from prescriptive over-constraints */
+        d6_freedom: number;
+        /** /10 — Pattern consistency and grouping */
+        d7_pattern: number;
+        /** /15 — Developer usability: params, returns, examples */
+        d8_usability: number;
+    };
+    /** Sum of all dimensions (max 120) */
+    total: number;
+    /** total / 120 * 100, rounded to one decimal */
+    percentage: number;
+    /** Letter grade based on percentage */
+    grade: 'A' | 'B' | 'C' | 'D' | 'F';
+    /** Top 3 actionable improvement suggestions (may be fewer if all dimensions pass 80%) */
+    improvements: ActionableImprovement[];
+}
+/**
+ * Estimate the 8-dimension skill-judge score from an {@link AuditResult}.
+ *
+ * Each dimension starts at a baseline and adds/deducts based on which audit
+ * checks pass or fail. Dimensions are capped at their respective maxima.
+ *
+ * @param audit - The completed audit result to score
+ * @param skill - Optional extracted skill; when provided, improvements include specific file/export targets
+ * @returns A {@link SkillJudgeEstimate} with dimension breakdown, total, grade, and improvements
+ *
+ * @category Audit
+ * @useWhen
+ * - You want a quick human-readable quality rating after running an audit
+ * - Building dashboards that track skill quality over time
+ * @avoidWhen
+ * - Using as a hard CI gate — prefer explicit audit codes (F1, E4, etc.) for gating
+ */
+export declare function estimateSkillJudgeScore(audit: AuditResult, skill?: ExtractedSkill): SkillJudgeEstimate;
+//# sourceMappingURL=audit-score.d.ts.map

package/dist/audit-score.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-score.d.ts","sourceRoot":"","sources":["../src/audit-score.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAMjD;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/D;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE;QACV,qDAAqD;QACrD,iBAAiB,EAAE,MAAM,CAAC;QAC1B,uDAAuD;QACvD,aAAa,EAAE,MAAM,CAAC;QACtB,yDAAyD;QACzD,eAAe,EAAE,MAAM,CAAC;QACxB,qDAAqD;QACrD,cAAc,EAAE,MAAM,CAAC;QACvB,wDAAwD;QACxD,wBAAwB,EAAE,MAAM,CAAC;QACjC,uDAAuD;QACvD,UAAU,EAAE,MAAM,CAAC;QACnB,6CAA6C;QAC7C,UAAU,EAAE,MAAM,CAAC;QACnB,2DAA2D;QAC3D,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,KAAK,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IACnC,yFAAyF;IACzF,YAAY,EAAE,qBAAqB,EAAE,CAAC;CACvC;AAoCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,WAAW,EAClB,KAAK,CAAC,EAAE,cAAc,GACrB,kBAAkB,CA2FpB"}