@tyroneross/navgator 0.2.2 → 0.9.0

package/dist/lessons-store.d.ts

@@ -0,0 +1,93 @@
+/**
+ * NavGator Lessons Store
+ *
+ * Manages per-project and global architectural lessons. Local lessons live at
+ * `<project>/.navgator/lessons/lessons.json`. Promoted lessons are copied (never
+ * moved) into `~/.navgator/lessons/global-lessons.json` and the local copy is
+ * marked with `promoted: true`.
+ *
+ * Zero external deps — uses node fs/path/os only. Writes are atomic (temp+rename).
+ */
+export type Severity = 'critical' | 'important' | 'minor';
+export type LessonCategory = 'api-contract' | 'data-flow' | 'component-communication' | 'llm-architecture' | 'infrastructure' | 'typespec' | 'database-structure';
+export interface LessonContext {
+    first_seen?: string;
+    last_seen?: string;
+    occurrences?: number;
+    files_affected?: string[];
+    resolution?: string;
+}
+export interface LessonExample {
+    bad?: string;
+    good?: string;
+    why?: string;
+}
+export interface Lesson {
+    id: string;
+    category: LessonCategory;
+    pattern: string;
+    signature?: string[];
+    severity: Severity;
+    context?: LessonContext;
+    example?: LessonExample;
+    /** Set to true on the local lesson after a successful promotion. */
+    promoted?: boolean;
+}
+export interface GlobalLesson extends Lesson {
+    source_project: string;
+    applies_to?: string[];
+    promoted_at: string;
+    promoted_from?: string;
+}
+export interface LessonsFile {
+    schema_version: string;
+    project: string;
+    lessons: Lesson[] | GlobalLesson[];
+    /** Preserved on read/write for backward compatibility with repo template file. */
+    _template?: unknown;
+}
+export declare const LESSONS_SCHEMA_VERSION = "1.0.0";
+export declare function globalLessonsPath(): string;
+export declare function localLessonsPath(projectRoot: string): string;
+export declare function readLessons(filePath: string): LessonsFile;
+/**
+ * Atomic write: write to a sibling temp file, then rename into place.
+ * On any failure the caller sees a thrown error and the original is untouched.
+ */
+export declare function writeLessons(filePath: string, data: LessonsFile): void;
+/**
+ * Ensure the global lessons file exists, seeded with an empty template.
+ * Safe to call repeatedly. Never touches `~/.navgator/projects.json`.
+ */
+export declare function ensureGlobalLessonsFile(): string;
+interface ListOpts {
+    scope: 'local' | 'global';
+    projectRoot?: string;
+}
+export declare function listLessons(opts: ListOpts): Lesson[] | GlobalLesson[];
+interface SearchOpts {
+    scope: 'local' | 'global' | 'all';
+    projectRoot?: string;
+    category?: LessonCategory;
+    severity?: Severity;
+    tags?: string[];
+}
+export declare function searchLessons(query: string, opts: SearchOpts): (Lesson | GlobalLesson)[];
+export declare function findLessonById(id: string, opts: ListOpts): Lesson | GlobalLesson | null;
+interface PromoteResult {
+    promoted: boolean;
+    globalLesson: GlobalLesson | null;
+    reason?: 'not-found' | 'already-global' | 'ok';
+}
+interface PromoteOpts {
+    applies_to?: string[];
+    project_name?: string;
+}
+export declare function promoteLesson(id: string, projectRoot: string, opts?: PromoteOpts): PromoteResult;
+interface DemoteResult {
+    demoted: boolean;
+    reason?: 'not-found' | 'ok';
+}
+export declare function demoteLesson(id: string): DemoteResult;
+export {};
+//# sourceMappingURL=lessons-store.d.ts.map

package/dist/lessons-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lessons-store.d.ts","sourceRoot":"","sources":["../src/lessons-store.ts"],"names":[],"mappings":"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"}

package/dist/lessons-store.js

@@ -0,0 +1,265 @@
+/**
+ * NavGator Lessons Store
+ *
+ * Manages per-project and global architectural lessons. Local lessons live at
+ * `<project>/.navgator/lessons/lessons.json`. Promoted lessons are copied (never
+ * moved) into `~/.navgator/lessons/global-lessons.json` and the local copy is
+ * marked with `promoted: true`.
+ *
+ * Zero external deps — uses node fs/path/os only. Writes are atomic (temp+rename).
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+const VALID_CATEGORIES = new Set([
+    'api-contract',
+    'data-flow',
+    'component-communication',
+    'llm-architecture',
+    'infrastructure',
+    'typespec',
+    'database-structure',
+]);
+const VALID_SEVERITIES = new Set([
+    'critical',
+    'important',
+    'minor',
+]);
+const ID_PATTERN = /^lesson-[a-z0-9-]+$/;
+export const LESSONS_SCHEMA_VERSION = '1.0.0';
+// =============================================================================
+// PATHS
+// =============================================================================
+/**
+ * Directory that holds the global lessons file. Honors the
+ * `NAVGATOR_GLOBAL_LESSONS_DIR` env var so tests can redirect to a tmpdir.
+ */
+function globalLessonsDir() {
+    const override = process.env.NAVGATOR_GLOBAL_LESSONS_DIR;
+    if (override && override.trim() !== '')
+        return override;
+    return path.join(os.homedir(), '.navgator', 'lessons');
+}
+export function globalLessonsPath() {
+    return path.join(globalLessonsDir(), 'global-lessons.json');
+}
+export function localLessonsPath(projectRoot) {
+    return path.join(projectRoot, '.navgator', 'lessons', 'lessons.json');
+}
+// =============================================================================
+// READ / WRITE
+// =============================================================================
+function emptyFile(project) {
+    return {
+        schema_version: LESSONS_SCHEMA_VERSION,
+        project,
+        lessons: [],
+    };
+}
+export function readLessons(filePath) {
+    try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return {
+            schema_version: parsed.schema_version || LESSONS_SCHEMA_VERSION,
+            project: parsed.project ?? '',
+            lessons: Array.isArray(parsed.lessons) ? parsed.lessons : [],
+            ...(parsed._template !== undefined ? { _template: parsed._template } : {}),
+        };
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === 'ENOENT') {
+            return emptyFile('');
+        }
+        // Malformed JSON or other read error — return empty so callers can overwrite.
+        if (err instanceof SyntaxError)
+            return emptyFile('');
+        throw err;
+    }
+}
+/**
+ * Atomic write: write to a sibling temp file, then rename into place.
+ * On any failure the caller sees a thrown error and the original is untouched.
+ */
+export function writeLessons(filePath, data) {
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = path.join(dir, `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
+    const payload = JSON.stringify(data, null, 2);
+    try {
+        fs.writeFileSync(tmp, payload, 'utf-8');
+        fs.renameSync(tmp, filePath);
+    }
+    catch (err) {
+        // Best-effort cleanup of the temp file.
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
+}
+/**
+ * Ensure the global lessons file exists, seeded with an empty template.
+ * Safe to call repeatedly. Never touches `~/.navgator/projects.json`.
+ */
+export function ensureGlobalLessonsFile() {
+    const p = globalLessonsPath();
+    if (!fs.existsSync(p)) {
+        writeLessons(p, emptyFile(''));
+    }
+    return p;
+}
+// =============================================================================
+// VALIDATION
+// =============================================================================
+function isValidId(id) {
+    return typeof id === 'string' && ID_PATTERN.test(id);
+}
+function assertValidId(id) {
+    if (!isValidId(id)) {
+        throw new Error(`Invalid lesson id "${id}" — must match ${ID_PATTERN.source}`);
+    }
+}
+function assertValidCategory(c) {
+    if (!VALID_CATEGORIES.has(c)) {
+        throw new Error(`Invalid category "${String(c)}"`);
+    }
+}
+function assertValidSeverity(s) {
+    if (!VALID_SEVERITIES.has(s)) {
+        throw new Error(`Invalid severity "${String(s)}"`);
+    }
+}
+export function listLessons(opts) {
+    if (opts.scope === 'global') {
+        const file = readLessons(globalLessonsPath());
+        return file.lessons || [];
+    }
+    if (!opts.projectRoot) {
+        throw new Error('listLessons: projectRoot required for scope=local');
+    }
+    const file = readLessons(localLessonsPath(opts.projectRoot));
+    return file.lessons || [];
+}
+function lessonMatchesQuery(l, re) {
+    if (!re)
+        return true;
+    if (re.test(l.pattern || ''))
+        return true;
+    if (Array.isArray(l.signature) && l.signature.some((s) => re.test(s)))
+        return true;
+    if (l.example?.bad && re.test(l.example.bad))
+        return true;
+    if (l.example?.good && re.test(l.example.good))
+        return true;
+    if (l.context?.resolution && re.test(l.context.resolution))
+        return true;
+    if (re.test(l.id))
+        return true;
+    return false;
+}
+export function searchLessons(query, opts) {
+    let re = null;
+    if (query && query.trim() !== '') {
+        try {
+            re = new RegExp(query, 'i');
+        }
+        catch {
+            // Fall back to literal substring if regex is invalid.
+            const escaped = query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            re = new RegExp(escaped, 'i');
+        }
+    }
+    const pool = [];
+    if (opts.scope === 'local' || opts.scope === 'all') {
+        if (opts.projectRoot) {
+            const local = readLessons(localLessonsPath(opts.projectRoot));
+            pool.push(...local.lessons);
+        }
+    }
+    if (opts.scope === 'global' || opts.scope === 'all') {
+        const global = readLessons(globalLessonsPath());
+        pool.push(...global.lessons);
+    }
+    return pool.filter((l) => {
+        if (!lessonMatchesQuery(l, re))
+            return false;
+        if (opts.category && l.category !== opts.category)
+            return false;
+        if (opts.severity && l.severity !== opts.severity)
+            return false;
+        if (opts.tags && opts.tags.length > 0) {
+            // Tags only apply to GlobalLesson.applies_to — filter out non-global matches.
+            const applies = l.applies_to;
+            if (!Array.isArray(applies))
+                return false;
+            const hasAll = opts.tags.every((t) => applies.includes(t));
+            if (!hasAll)
+                return false;
+        }
+        return true;
+    });
+}
+export function findLessonById(id, opts) {
+    const list = listLessons(opts);
+    return list.find((l) => l.id === id) || null;
+}
+export function promoteLesson(id, projectRoot, opts = {}) {
+    assertValidId(id);
+    const localPath = localLessonsPath(projectRoot);
+    const localFile = readLessons(localPath);
+    const localLessons = localFile.lessons;
+    const localIdx = localLessons.findIndex((l) => l.id === id);
+    if (localIdx === -1) {
+        return { promoted: false, globalLesson: null, reason: 'not-found' };
+    }
+    const localLesson = localLessons[localIdx];
+    // Re-validate the lesson so we never promote garbage.
+    assertValidCategory(localLesson.category);
+    assertValidSeverity(localLesson.severity);
+    const globalPath = globalLessonsPath();
+    const globalFile = readLessons(globalPath);
+    if (!globalFile.project)
+        globalFile.project = '';
+    const globalLessons = globalFile.lessons;
+    if (globalLessons.some((l) => l.id === id)) {
+        return { promoted: false, globalLesson: null, reason: 'already-global' };
+    }
+    const projectName = opts.project_name ||
+        localFile.project ||
+        path.basename(projectRoot) ||
+        projectRoot;
+    const globalLesson = {
+        ...localLesson,
+        source_project: projectName,
+        applies_to: opts.applies_to && opts.applies_to.length > 0 ? [...opts.applies_to] : undefined,
+        promoted_at: new Date().toISOString(),
+        promoted_from: localPath,
+    };
+    // Don't carry the local-only `promoted` marker into the global record.
+    delete globalLesson.promoted;
+    globalLessons.push(globalLesson);
+    globalFile.lessons = globalLessons;
+    writeLessons(globalPath, globalFile);
+    // Mark the local lesson (copy-then-mark — never move).
+    localLessons[localIdx] = { ...localLesson, promoted: true };
+    localFile.lessons = localLessons;
+    writeLessons(localPath, localFile);
+    return { promoted: true, globalLesson, reason: 'ok' };
+}
+export function demoteLesson(id) {
+    assertValidId(id);
+    const globalPath = globalLessonsPath();
+    const globalFile = readLessons(globalPath);
+    const globalLessons = globalFile.lessons;
+    const next = globalLessons.filter((l) => l.id !== id);
+    if (next.length === globalLessons.length) {
+        return { demoted: false, reason: 'not-found' };
+    }
+    globalFile.lessons = next;
+    writeLessons(globalPath, globalFile);
+    return { demoted: true, reason: 'ok' };
+}
+//# sourceMappingURL=lessons-store.js.map

package/dist/lessons-store.js.map

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

package/dist/llm-dedup.d.ts

@@ -0,0 +1,40 @@
+/**
+ * LLM Use Case Deduplication
+ *
+ * Transforms raw LLM service-call connections (often 100+) into distinct
+ * use cases (typically 5-15) by filtering noise and grouping by purpose.
+ *
+ * 3-layer pipeline:
+ *   Layer 1 — Filter: remove test/dev, import-only, duplicates
+ *   Layer 2 — Group: prompt match → function name → callType+model → file fallback
+ *   Layer 3 — Merge: combine groups connected via import graph
+ */
+import type { ArchitectureComponent, ArchitectureConnection } from './types.js';
+import type { DetectedPrompt } from './scanners/prompts/types.js';
+export interface LLMUseCase {
+    name: string;
+    category?: string;
+    provider: string;
+    model?: string;
+    primaryFile: string;
+    callSites: number;
+    productionCallSites: number;
+    groupedBy: 'prompt' | 'function' | 'calltype' | 'file';
+    /** Feature domain from features.yaml or directory inference */
+    feature?: string;
+    /** Downstream connections — what this LLM call feeds into (for agent classification) */
+    feedsInto?: string[];
+}
+export interface LLMDedupResult {
+    useCases: LLMUseCase[];
+    totalCallSites: number;
+    productionCallSites: number;
+    providers: string[];
+}
+/**
+ * Load feature annotations from .navgator/features.yaml if present.
+ * Returns a map of file glob → feature name.
+ */
+export declare function loadFeatureAnnotations(projectRoot: string): Map<string, string> | null;
+export declare function deduplicateLLMUseCases(components: ArchitectureComponent[], connections: ArchitectureConnection[], prompts?: DetectedPrompt[]): LLMDedupResult;
+//# sourceMappingURL=llm-dedup.d.ts.map

package/dist/llm-dedup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-dedup.d.ts","sourceRoot":"","sources":["../src/llm-dedup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAMlE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;IACvD,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AA+FD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CA0CtF;AAqCD,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,qBAAqB,EAAE,EACnC,WAAW,EAAE,sBAAsB,EAAE,EACrC,OAAO,CAAC,EAAE,cAAc,EAAE,GACzB,cAAc,CA8MhB"}