@skillsmith/core 0.5.3 → 0.5.4

package/dist/src/analysis/tree-sitter/pythonIncremental.test.js

@@ -0,0 +1,142 @@
+/**
+ * SMI-4293: PythonIncrementalParser unit tests.
+ *
+ * Covers the six cases called out in the plan:
+ *   1. First parse caches the tree.
+ *   2. Unchanged content re-parse hits the cache (no re-parse).
+ *   3. Incremental edits re-use the previous tree via tree.edit().
+ *   4. LRU eviction at the configured max.
+ *   5. Corrupted cached tree falls back gracefully (returns null, adapter
+ *      then falls back to regex).
+ *   6. Unsupported / unavailable grammar surfaces `isReady === false` and
+ *      `parseSync` returns null.
+ *
+ * @see docs/internal/implementation/github-wave-5c-tree-sitter-incremental.md
+ */
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
+// Silence warn output from the SMI-4316 hardening paths; behavioural
+// assertions live in pythonIncremental.hardening.test.ts.
+vi.mock('../../utils/logger.js', () => ({
+    createLogger: () => ({
+        warn: vi.fn(),
+        error: vi.fn(),
+        info: vi.fn(),
+        debug: vi.fn(),
+        auditLog: vi.fn(),
+        securityLog: vi.fn(),
+    }),
+}));
+import { PythonIncrementalParser } from './pythonIncremental.js';
+describe('PythonIncrementalParser', () => {
+    const parsers = [];
+    beforeAll(() => {
+        // No-op — each test creates its own parser so disposal is explicit.
+    });
+    function trackedParser(options = {}, loader) {
+        const p = loader
+            ? new PythonIncrementalParser(options, loader)
+            : new PythonIncrementalParser(options);
+        parsers.push(p);
+        return p;
+    }
+    afterAll(() => {
+        for (const p of parsers)
+            p.dispose();
+    });
+    // ------------------------------------------------------------------
+    // 1. First parse caches the tree
+    // ------------------------------------------------------------------
+    it('caches a tree after the first parse', async () => {
+        const parser = trackedParser();
+        const result = await parser.parse('def foo():\n    pass\n', 'first.py');
+        expect(result).not.toBeNull();
+        expect(parser.cacheSize).toBe(1);
+        expect(result?.functions.map((f) => f.name)).toContain('foo');
+    });
+    // ------------------------------------------------------------------
+    // 2. Unchanged content hits the cache and still returns results
+    // ------------------------------------------------------------------
+    it('reuses the cached tree when content is unchanged', async () => {
+        const parser = trackedParser();
+        const src = 'def foo():\n    return 42\n';
+        const r1 = await parser.parse(src, 'unchanged.py');
+        const r2 = await parser.parse(src, 'unchanged.py');
+        expect(r1).toEqual(r2);
+        // Still only one entry; parse didn't create a duplicate.
+        expect(parser.cacheSize).toBe(1);
+    });
+    // ------------------------------------------------------------------
+    // 3. Incremental edit re-parses using the previous tree
+    // ------------------------------------------------------------------
+    it('applies incremental edits and observes the change', async () => {
+        const parser = trackedParser();
+        const filePath = 'edit.py';
+        const v1 = 'def foo():\n    return 1\n';
+        const v2 = 'def foo():\n    return 2\n';
+        await parser.parse(v1, filePath);
+        const r2 = await parser.parse(v2, filePath);
+        expect(r2).not.toBeNull();
+        expect(r2?.functions).toHaveLength(1);
+        expect(r2?.functions[0].name).toBe('foo');
+    });
+    it('detects newly added functions across an edit', async () => {
+        const parser = trackedParser();
+        const filePath = 'add.py';
+        await parser.parse('def a():\n    pass\n', filePath);
+        const r = await parser.parse('def a():\n    pass\n\ndef b():\n    pass\n', filePath);
+        expect(r).not.toBeNull();
+        const names = r?.functions.map((f) => f.name).sort();
+        expect(names).toEqual(['a', 'b']);
+    });
+    // ------------------------------------------------------------------
+    // 4. LRU eviction at max
+    // ------------------------------------------------------------------
+    it('evicts the least-recently-used tree when the cache is full', async () => {
+        const parser = trackedParser({ maxTrees: 3 });
+        await parser.parse('def a(): pass\n', 'a.py');
+        await parser.parse('def b(): pass\n', 'b.py');
+        await parser.parse('def c(): pass\n', 'c.py');
+        expect(parser.cacheSize).toBe(3);
+        // Touch a.py and b.py so c.py becomes LRU.
+        await parser.parse('def a(): pass\n', 'a.py');
+        await parser.parse('def b(): pass\n', 'b.py');
+        // Adding a new file should evict c.py.
+        await parser.parse('def d(): pass\n', 'd.py');
+        expect(parser.cacheSize).toBe(3);
+    });
+    // ------------------------------------------------------------------
+    // 5. Corrupted cached tree falls back gracefully
+    //    (simulated by forcing the cached tree's .edit to throw)
+    // ------------------------------------------------------------------
+    it('invalidates and returns null when the cached tree is corrupted', async () => {
+        const parser = trackedParser();
+        const filePath = 'corrupt.py';
+        await parser.parse('def ok(): pass\n', filePath);
+        // Reach into the private cache to sabotage the tree.
+        const cache = parser
+            .cache;
+        const entry = cache.get(filePath);
+        if (!entry)
+            throw new Error('expected cache entry');
+        entry.tree.edit = () => {
+            throw new Error('simulated corruption');
+        };
+        const r = await parser.parse('def ok(): return 1\n', filePath);
+        expect(r).toBeNull();
+        expect(parser.cacheSize).toBe(0);
+    });
+    // ------------------------------------------------------------------
+    // 6. Grammar unavailable (loader rejects) → isReady stays false
+    // ------------------------------------------------------------------
+    it('flags init failure when the WASM loader rejects', async () => {
+        const failingLoader = async () => {
+            throw new Error('module not found');
+        };
+        const parser = trackedParser({}, failingLoader);
+        const result = await parser.parse('def x(): pass\n', 'fail.py');
+        expect(result).toBeNull();
+        expect(parser.isReady).toBe(false);
+        expect(parser.hasFailedInit).toBe(true);
+    });
+});
+//# sourceMappingURL=pythonIncremental.test.js.map

package/dist/src/analysis/tree-sitter/pythonIncremental.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pythonIncremental.test.js","sourceRoot":"","sources":["../../../../src/analysis/tree-sitter/pythonIncremental.test.ts"],"names":[],"mappings":"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"}

package/dist/src/analysis/tree-sitter/queries/python.d.ts

@@ -0,0 +1,43 @@
+/**
+ * SMI-4293: Python Tree-Sitter Query Strings
+ *
+ * TypeScript-consumable tree-sitter queries used by the PythonAdapter
+ * when the WASM parser is available. Paired with python.scm for reference
+ * but this module is what runtime code imports (loadable without fs reads).
+ *
+ * These queries drive the query-based extraction path that replaces the
+ * regex fallback. The extraction must match-or-exceed the regex baseline;
+ * see queryExtractionMatchesOrExceedsRegex.test.ts (finding H3).
+ *
+ * @see docs/internal/implementation/github-wave-5c-tree-sitter-incremental.md
+ * @module analysis/tree-sitter/queries/python
+ */
+/**
+ * Query capturing `import x`, `import x as y`, `import x.y.z`.
+ */
+export declare const PYTHON_IMPORT_QUERY = "\n(import_statement\n  name: (dotted_name) @import.module)\n\n(import_statement\n  name: (aliased_import\n    name: (dotted_name) @import.module\n    alias: (identifier) @import.alias))\n";
+/**
+ * Query capturing `from module import name`, aliased imports, and wildcard.
+ * Relative imports (`from .x import y`) capture the dotted_name portion as
+ * the module name; the leading dots are preserved via relative_import wrapping.
+ */
+export declare const PYTHON_FROM_IMPORT_QUERY = "\n(import_from_statement\n  module_name: (dotted_name) @from.module\n  name: (dotted_name) @from.name)\n\n(import_from_statement\n  module_name: (dotted_name) @from.module\n  name: (aliased_import\n    name: (dotted_name) @from.name\n    alias: (identifier) @from.alias))\n\n(import_from_statement\n  module_name: (dotted_name) @from.module\n  (wildcard_import) @from.wildcard)\n\n(import_from_statement\n  module_name: (relative_import) @from.module\n  name: (_) @from.name)\n";
+/**
+ * Query capturing top-level and nested function definitions.
+ * `async` is a child marker when present; we detect it via node type.
+ */
+export declare const PYTHON_FUNCTION_QUERY = "\n(function_definition\n  name: (identifier) @function.name\n  parameters: (parameters) @function.params) @function.def\n";
+/**
+ * Query capturing class definitions.
+ */
+export declare const PYTHON_CLASS_QUERY = "\n(class_definition\n  name: (identifier) @class.name) @class.def\n";
+/**
+ * Query capturing `__all__ = [...]` export declarations.
+ */
+export declare const PYTHON_ALL_EXPORT_QUERY = "\n(assignment\n  left: (identifier) @all.var\n  right: (list\n    (string) @all.name)\n  (#eq? @all.var \"__all__\"))\n";
+/**
+ * Combined query used for a single pass over the tree.
+ * Keeps capture names namespaced so extraction can partition results.
+ */
+export declare const PYTHON_COMBINED_QUERY: string;
+//# sourceMappingURL=python.d.ts.map

package/dist/src/analysis/tree-sitter/queries/python.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python.d.ts","sourceRoot":"","sources":["../../../../../src/analysis/tree-sitter/queries/python.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;GAEG;AACH,eAAO,MAAM,mBAAmB,gMAQ/B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,keAkBpC,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,8HAIjC,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,wEAG9B,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,uBAAuB,4HAMnC,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAMtB,CAAA"}

package/dist/src/analysis/tree-sitter/queries/python.js

@@ -0,0 +1,88 @@
+/**
+ * SMI-4293: Python Tree-Sitter Query Strings
+ *
+ * TypeScript-consumable tree-sitter queries used by the PythonAdapter
+ * when the WASM parser is available. Paired with python.scm for reference
+ * but this module is what runtime code imports (loadable without fs reads).
+ *
+ * These queries drive the query-based extraction path that replaces the
+ * regex fallback. The extraction must match-or-exceed the regex baseline;
+ * see queryExtractionMatchesOrExceedsRegex.test.ts (finding H3).
+ *
+ * @see docs/internal/implementation/github-wave-5c-tree-sitter-incremental.md
+ * @module analysis/tree-sitter/queries/python
+ */
+/**
+ * Query capturing `import x`, `import x as y`, `import x.y.z`.
+ */
+export const PYTHON_IMPORT_QUERY = `
+(import_statement
+  name: (dotted_name) @import.module)
+
+(import_statement
+  name: (aliased_import
+    name: (dotted_name) @import.module
+    alias: (identifier) @import.alias))
+`;
+/**
+ * Query capturing `from module import name`, aliased imports, and wildcard.
+ * Relative imports (`from .x import y`) capture the dotted_name portion as
+ * the module name; the leading dots are preserved via relative_import wrapping.
+ */
+export const PYTHON_FROM_IMPORT_QUERY = `
+(import_from_statement
+  module_name: (dotted_name) @from.module
+  name: (dotted_name) @from.name)
+
+(import_from_statement
+  module_name: (dotted_name) @from.module
+  name: (aliased_import
+    name: (dotted_name) @from.name
+    alias: (identifier) @from.alias))
+
+(import_from_statement
+  module_name: (dotted_name) @from.module
+  (wildcard_import) @from.wildcard)
+
+(import_from_statement
+  module_name: (relative_import) @from.module
+  name: (_) @from.name)
+`;
+/**
+ * Query capturing top-level and nested function definitions.
+ * `async` is a child marker when present; we detect it via node type.
+ */
+export const PYTHON_FUNCTION_QUERY = `
+(function_definition
+  name: (identifier) @function.name
+  parameters: (parameters) @function.params) @function.def
+`;
+/**
+ * Query capturing class definitions.
+ */
+export const PYTHON_CLASS_QUERY = `
+(class_definition
+  name: (identifier) @class.name) @class.def
+`;
+/**
+ * Query capturing `__all__ = [...]` export declarations.
+ */
+export const PYTHON_ALL_EXPORT_QUERY = `
+(assignment
+  left: (identifier) @all.var
+  right: (list
+    (string) @all.name)
+  (#eq? @all.var "__all__"))
+`;
+/**
+ * Combined query used for a single pass over the tree.
+ * Keeps capture names namespaced so extraction can partition results.
+ */
+export const PYTHON_COMBINED_QUERY = [
+    PYTHON_IMPORT_QUERY,
+    PYTHON_FROM_IMPORT_QUERY,
+    PYTHON_FUNCTION_QUERY,
+    PYTHON_CLASS_QUERY,
+    PYTHON_ALL_EXPORT_QUERY,
+].join('\n');
+//# sourceMappingURL=python.js.map

package/dist/src/analysis/tree-sitter/queries/python.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"python.js","sourceRoot":"","sources":["../../../../../src/analysis/tree-sitter/queries/python.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;CAQlC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;;;;;;;;;;;;;;;;;;CAkBvC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;CAIpC,CAAA;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;CAGjC,CAAA;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;;;;;;CAMtC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,mBAAmB;IACnB,wBAAwB;IACxB,qBAAqB;IACrB,kBAAkB;IAClB,uBAAuB;CACxB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA"}

package/dist/src/analysis/tree-sitter/queryExtractionMatchesOrExceedsRegex.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * SMI-4293 / finding H3: Regression guard for query-based extraction.
+ *
+ * Before the WASM query path replaces the regex path, this test asserts
+ * that for every Python fixture, the query-based extraction produces a
+ * SUPERSET OR EQUAL SET of constructs relative to the regex baseline.
+ * A missing construct in the query path blocks the PR — queries must be
+ * extended until parity is reached.
+ *
+ * @see docs/internal/implementation/github-wave-5c-tree-sitter-incremental.md
+ */
+export {};
+//# sourceMappingURL=queryExtractionMatchesOrExceedsRegex.test.d.ts.map

package/dist/src/analysis/tree-sitter/queryExtractionMatchesOrExceedsRegex.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryExtractionMatchesOrExceedsRegex.test.d.ts","sourceRoot":"","sources":["../../../../src/analysis/tree-sitter/queryExtractionMatchesOrExceedsRegex.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/src/analysis/tree-sitter/queryExtractionMatchesOrExceedsRegex.test.js

@@ -0,0 +1,174 @@
+/**
+ * SMI-4293 / finding H3: Regression guard for query-based extraction.
+ *
+ * Before the WASM query path replaces the regex path, this test asserts
+ * that for every Python fixture, the query-based extraction produces a
+ * SUPERSET OR EQUAL SET of constructs relative to the regex baseline.
+ * A missing construct in the query path blocks the PR — queries must be
+ * extended until parity is reached.
+ *
+ * @see docs/internal/implementation/github-wave-5c-tree-sitter-incremental.md
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { PythonAdapter } from '../adapters/python.js';
+import { PythonIncrementalParser } from './pythonIncremental.js';
+// Fixtures span every construct the regex extractor recognises, plus a
+// handful of edge cases the original Python test suite exercises.
+const FIXTURES = [
+    {
+        name: 'simple-imports',
+        source: `
+import os
+import sys
+import json
+    `,
+    },
+    {
+        name: 'aliased-imports',
+        source: `
+import numpy as np
+import pandas as pd
+    `,
+    },
+    {
+        name: 'from-imports',
+        source: `
+from os import path, getcwd
+from typing import Optional, List
+    `,
+    },
+    {
+        name: 'from-aliased-and-wildcard',
+        source: `
+from django.http import HttpResponse as Resp
+from utils import *
+    `,
+    },
+    {
+        name: 'top-level-functions-classes',
+        source: `
+def top_fn():
+    pass
+
+async def async_fn(a, b):
+    return a + b
+
+class PublicClass:
+    def method(self):
+        pass
+
+class _Private:
+    pass
+
+def _hidden():
+    pass
+    `,
+    },
+    {
+        name: 'all-export-list',
+        source: `
+__all__ = ["ExportedFn", "ExportedCls"]
+
+def ExportedFn():
+    pass
+
+class ExportedCls:
+    pass
+
+def not_exported_but_public():
+    pass
+    `,
+    },
+    {
+        name: 'nested-functions',
+        source: `
+def outer():
+    def middle():
+        def inner():
+            pass
+        return inner
+    return middle
+    `,
+    },
+    {
+        name: 'decorators',
+        source: `
+@decorator
+def decorated():
+    pass
+
+@decorator1
+@decorator2
+def multi_decorated():
+    pass
+
+@module.attr_decorator
+def attr_decorated():
+    pass
+    `,
+    },
+    {
+        name: 'type-hinted-function',
+        source: `
+def typed(a: int, b: str, c: Optional[List[int]]) -> Dict[str, Any]:
+    pass
+    `,
+    },
+    {
+        name: 'empty-module',
+        source: '',
+    },
+    {
+        name: 'comments-only',
+        source: `
+# just a comment
+# nothing else
+    `,
+    },
+];
+function normalize(result) {
+    return {
+        imports: new Set(result.imports.map((i) => `${i.module}::${[...i.namedImports].sort().join(',')}`)),
+        exports: new Set(result.exports.map((e) => `${e.name}::${e.kind}`)),
+        functions: new Set(result.functions.map((f) => `${f.name}::${f.isAsync}`)),
+    };
+}
+function isSuperset(candidate, baseline) {
+    const missing = [];
+    for (const item of baseline)
+        if (!candidate.has(item))
+            missing.push(item);
+    return missing.length === 0 ? { ok: true } : { ok: false, missing };
+}
+describe('Python query extraction vs regex baseline (finding H3)', () => {
+    const regexAdapter = new PythonAdapter();
+    const queryParser = new PythonIncrementalParser();
+    beforeAll(async () => {
+        await queryParser.ensureReady();
+    });
+    afterAll(() => {
+        regexAdapter.dispose();
+        queryParser.dispose();
+    });
+    it('boots the WASM parser for the regression guard', () => {
+        expect(queryParser.isReady).toBe(true);
+    });
+    for (const fixture of FIXTURES) {
+        it(`query extraction ⊇ regex baseline for fixture "${fixture.name}"`, () => {
+            const regexResult = regexAdapter.parseFile(fixture.source, `${fixture.name}.py`);
+            const queryResult = queryParser.parseSync(fixture.source, `${fixture.name}.py`);
+            expect(queryResult).not.toBeNull();
+            if (!queryResult)
+                return; // keep type narrowing happy
+            const regex = normalize(regexResult);
+            const query = normalize(queryResult);
+            const importCheck = isSuperset(query.imports, regex.imports);
+            const exportCheck = isSuperset(query.exports, regex.exports);
+            const functionCheck = isSuperset(query.functions, regex.functions);
+            expect(importCheck, `imports missing vs regex baseline: ${'missing' in importCheck ? JSON.stringify(importCheck.missing) : '[]'}`).toMatchObject({ ok: true });
+            expect(exportCheck, `exports missing vs regex baseline: ${'missing' in exportCheck ? JSON.stringify(exportCheck.missing) : '[]'}`).toMatchObject({ ok: true });
+            expect(functionCheck, `functions missing vs regex baseline: ${'missing' in functionCheck ? JSON.stringify(functionCheck.missing) : '[]'}`).toMatchObject({ ok: true });
+        });
+    }
+});
+//# sourceMappingURL=queryExtractionMatchesOrExceedsRegex.test.js.map

package/dist/src/analysis/tree-sitter/queryExtractionMatchesOrExceedsRegex.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryExtractionMatchesOrExceedsRegex.test.js","sourceRoot":"","sources":["../../../../src/analysis/tree-sitter/queryExtractionMatchesOrExceedsRegex.test.ts"],"names":[],"mappings":"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"}

package/dist/src/analytics/ROIDashboardService.csv.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ROI dashboard CSV export helpers — extracted from ROIDashboardService to keep
+ * the main service file under the 500-line governance limit.
+ */
+import type { ROIDashboard } from './types.js';
+/**
+ * Render a partial ROI dashboard as CSV.
+ * Handles user-only, stakeholder-only, or combined payloads.
+ */
+export declare function convertROIToCSV(data: Partial<ROIDashboard>): string;
+//# sourceMappingURL=ROIDashboardService.csv.d.ts.map

package/dist/src/analytics/ROIDashboardService.csv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ROIDashboardService.csv.d.ts","sourceRoot":"","sources":["../../../src/analytics/ROIDashboardService.csv.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,MAAM,CAsCnE"}

package/dist/src/analytics/ROIDashboardService.csv.js

@@ -0,0 +1,43 @@
+/**
+ * ROI dashboard CSV export helpers — extracted from ROIDashboardService to keep
+ * the main service file under the 500-line governance limit.
+ */
+/**
+ * Render a partial ROI dashboard as CSV.
+ * Handles user-only, stakeholder-only, or combined payloads.
+ */
+export function convertROIToCSV(data) {
+    const lines = [];
+    if (data.user) {
+        lines.push('User ROI Dashboard');
+        lines.push('');
+        lines.push('Metric,Value');
+        lines.push(`User ID,${data.user.userId}`);
+        lines.push(`Total Time Saved (min),${data.user.totalTimeSaved.toFixed(1)}`);
+        lines.push(`Estimated Value (USD),${data.user.estimatedValueUsd.toFixed(2)}`);
+        lines.push('');
+        lines.push('Top Skills');
+        lines.push('Skill ID,Skill Name,Time Saved (min)');
+        for (const skill of data.user.topSkills) {
+            lines.push(`${skill.skillId},${skill.skillName},${skill.timeSaved.toFixed(1)}`);
+        }
+    }
+    if (data.stakeholder) {
+        lines.push('Stakeholder ROI Dashboard');
+        lines.push('');
+        lines.push('Metric,Value');
+        lines.push(`Total Users,${data.stakeholder.totalUsers}`);
+        lines.push(`Total Activations,${data.stakeholder.totalActivations}`);
+        lines.push(`Avg Time Saved Per User (min),${data.stakeholder.avgTimeSavedPerUser.toFixed(1)}`);
+        lines.push(`Total Estimated Value (USD),${data.stakeholder.totalEstimatedValue.toFixed(2)}`);
+        lines.push(`Adoption Rate (%),${(data.stakeholder.adoptionRate * 100).toFixed(1)}`);
+        lines.push('');
+        lines.push('Skill Leaderboard');
+        lines.push('Skill ID,Skill Name,User Count,Total Value (USD)');
+        for (const skill of data.stakeholder.skillLeaderboard) {
+            lines.push(`${skill.skillId},${skill.skillName},${skill.userCount},${skill.totalValue.toFixed(2)}`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=ROIDashboardService.csv.js.map

package/dist/src/analytics/ROIDashboardService.csv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ROIDashboardService.csv.js","sourceRoot":"","sources":["../../../src/analytics/ROIDashboardService.csv.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAA2B;IACzD,MAAM,KAAK,GAAa,EAAE,CAAA;IAE1B,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAA;QAChC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QACd,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;QAC1B,KAAK,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAA;QACzC,KAAK,CAAC,IAAI,CAAC,0BAA0B,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;QAC3E,KAAK,CAAC,IAAI,CAAC,yBAAyB,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;QAC7E,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QACd,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAA;QACxB,KAAK,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAA;QAClD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACxC,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;QACjF,CAAC;IACH,CAAC;IAED,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACrB,KAAK,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAA;QACvC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QACd,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;QAC1B,KAAK,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC,CAAA;QACxD,KAAK,CAAC,IAAI,CAAC,qBAAqB,IAAI,CAAC,WAAW,CAAC,gBAAgB,EAAE,CAAC,CAAA;QACpE,KAAK,CAAC,IAAI,CAAC,iCAAiC,IAAI,CAAC,WAAW,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;QAC9F,KAAK,CAAC,IAAI,CAAC,+BAA+B,IAAI,CAAC,WAAW,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;QAC5F,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,WAAW,CAAC,YAAY,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;QACnF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QACd,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAA;QAC/B,KAAK,CAAC,IAAI,CAAC,kDAAkD,CAAC,CAAA;QAC9D,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,WAAW,CAAC,gBAAgB,EAAE,CAAC;YACtD,KAAK,CAAC,IAAI,CACR,GAAG,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CACxF,CAAA;QACH,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC"}

package/dist/src/analytics/ROIDashboardService.d.ts

@@ -15,19 +15,63 @@ export interface ROIComputeOptions {
     startDate?: string;
     endDate?: string;
 }
+/**
+ * Options for the public {@link ROIDashboardService.getDashboard} entrypoint.
+ * Both dates must be provided together (or neither, which defaults to the last 30 days).
+ */
+export interface GetDashboardOptions {
+    userId?: string;
+    startDate?: string;
+    endDate?: string;
+}
+/**
+ * Strict ISO-8601 / RFC-3339 profile matcher (SMI-4317). Accepts `YYYY-MM-DD`
+ * and `YYYY-MM-DDTHH:MM:SS(.sss)?(Z|[+-]HH:MM)`; rejects RFC-2822, slash
+ * separators, space-as-T, bare date-time without offset, and any trailing
+ * content. Syntactic guard only — calendar validity (e.g., `2026-13-01`) is
+ * caught by the paired `Date.parse` check. Exported for tests/reuse.
+ */
+export declare const ISO_8601_STRICT: RegExp;
 export declare class ROIDashboardService {
     private repo;
     private readonly TIME_SAVED_PER_SUCCESS;
     private readonly VALUE_PER_MINUTE;
     constructor(db: DatabaseType);
     /**
-     * Get user ROI dashboard data
+     * Get user ROI dashboard data for a rolling window (last `days` days).
+     * For an explicit ISO-8601 range, use {@link getDashboard}.
      */
     getUserROI(userId: string, days?: number): ROIDashboard['user'];
     /**
-     * Get stakeholder aggregate ROI dashboard
+     * Core per-user ROI computation over an explicit ISO-8601 range.
+     * Shared between {@link getUserROI} (days-based) and {@link getDashboard}.
+     */
+    private buildUserROI;
+    /**
+     * Get stakeholder aggregate ROI dashboard for a rolling window (last `days` days).
+     * For an explicit ISO-8601 range, use {@link getDashboard}.
      */
     getStakeholderROI(days?: number): ROIDashboard['stakeholder'];
+    /**
+     * Core stakeholder ROI computation over an explicit ISO-8601 range.
+     * Shared between {@link getStakeholderROI} (days-based) and {@link getDashboard}.
+     */
+    private buildStakeholderROI;
+    /**
+     * Public date-range-aware dashboard entrypoint (SMI-1683 / GitHub #603).
+     *
+     * Behavior:
+     * - Both dates omitted: defaults to the last 30 days ending now.
+     * - Exactly one date provided: throws {@link ValidationError} (the range is ambiguous).
+     * - `startDate >= endDate`: throws {@link ValidationError}.
+     * - `userId` provided: returns `{ user }` with date-filtered per-user metrics.
+     * - `userId` omitted: returns `{ stakeholder }` aggregated over the range.
+     *
+     * @param options.userId    Optional — when supplied, returns the per-user dashboard.
+     * @param options.startDate Optional ISO-8601 timestamp; must be paired with `endDate`.
+     * @param options.endDate   Optional ISO-8601 timestamp; must be paired with `startDate`.
+     */
+    getDashboard(options?: GetDashboardOptions): ROIDashboard;
     /**
      * Compute and store ROI metrics for a period
      * This should be run periodically (e.g., daily) to maintain the dashboard
@@ -42,6 +86,24 @@ export declare class ROIDashboardService {
      */
     refreshMetrics(): void;
     private getDateRange;
+    /**
+     * Resolve the range for {@link getDashboard}: default to last 30 days when both
+     * dates are omitted, validate that exactly-one-date was not supplied, and enforce
+     * `startDate < endDate`.
+     */
+    private resolveDashboardRange;
+    /**
+     * Throw a typed {@link ValidationError} when the supplied range is malformed.
+     *
+     * Validation layers (SMI-4317):
+     * 1. Strict ISO-8601 / RFC-3339 regex — rejects shapes like `2026/01/01`,
+     *    `2026-01-01 00:00:00` (space), `Jan 1 2026`, or RFC-2822 that
+     *    `Date.parse` would otherwise accept.
+     * 2. `Date.parse` NaN check — catches syntactically valid but semantically
+     *    invalid dates (e.g., `2026-13-01`) that the regex cannot detect.
+     * 3. Ordering — rejects when `startDate >= endDate`.
+     */
+    private assertValidRange;
     private calculateTimeSaved;
     private groupBySkill;
     private calculateWeeklyTrend;
@@ -50,6 +112,5 @@ export declare class ROIDashboardService {
     private computeUserMetrics;
     private computeSkillMetrics;
     private computeDailyMetrics;
-    private convertROIToCSV;
 }
 //# sourceMappingURL=ROIDashboardService.d.ts.map