@tyroneross/navgator 0.2.2 → 0.9.0

package/dist/enrich/fetchers.js

@@ -0,0 +1,89 @@
+/**
+ * Vendored, dependency-free upstream version fetchers for NavGator.
+ *
+ * Self-contained: uses the global `fetch` (Node ≥18) — no axios, no api-registry
+ * import. These are the ONLY network calls in the enrichment fold, and they run
+ * exclusively on the freshness path (refreshExternal / the external-resolver
+ * agent), never inside scan(). The engine stays offline and deterministic.
+ *
+ * Equivalent to api-registry/src/http.ts's fetchers, re-implemented here so
+ * NavGator carries no cross-plugin dependency.
+ */
+const UA = { 'User-Agent': 'navgator-external-resolver' };
+const TIMEOUT_MS = 8000;
+async function getJson(url, headers = {}) {
+    try {
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+        const res = await fetch(url, { headers: { ...UA, ...headers }, signal: ctrl.signal });
+        clearTimeout(t);
+        if (!res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch {
+        return null; // network failure → caller marks node unresolved
+    }
+}
+/** npm: latest dist-tag + publish time. */
+export async function fetchNpmLatest(pkg) {
+    const data = (await getJson(`https://registry.npmjs.org/${encodeURIComponent(pkg)}`));
+    if (!data?.['dist-tags']?.latest)
+        return null;
+    const version = data['dist-tags'].latest;
+    return {
+        version,
+        released_at: data.time?.[version],
+        docs_url: data.homepage,
+        repo_url: data.repository?.url?.replace(/^git\+/, '').replace(/\.git$/, ''),
+    };
+}
+/** PyPI: latest version + release date. */
+export async function fetchPypiLatest(pkg) {
+    const data = (await getJson(`https://pypi.org/pypi/${encodeURIComponent(pkg)}/json`));
+    const version = data?.info?.version;
+    if (!version)
+        return null;
+    const files = data?.releases?.[version];
+    return {
+        version,
+        released_at: files?.[0]?.upload_time_iso_8601,
+        docs_url: data?.info?.project_urls?.['Documentation'] ??
+            data?.info?.project_urls?.['Homepage'] ??
+            data?.info?.home_page,
+        repo_url: data?.info?.project_urls?.['Source'] ?? data?.info?.project_urls?.['Repository'],
+    };
+}
+/**
+ * GitHub Releases: latest tag + publish date for `owner/repo`.
+ * Used for spm/cargo/go nodes that expose versions via tags, not a registry.
+ * Honors GITHUB_TOKEN when present to avoid the 60/hr unauthenticated limit.
+ */
+export async function fetchGitHubLatest(ownerRepo) {
+    const headers = process.env['GITHUB_TOKEN']
+        ? { Authorization: `Bearer ${process.env['GITHUB_TOKEN']}` }
+        : {};
+    const data = (await getJson(`https://api.github.com/repos/${ownerRepo}/releases/latest`, headers));
+    if (!data?.tag_name)
+        return null;
+    return {
+        version: data.tag_name.replace(/^v/, ''),
+        released_at: data.published_at,
+        docs_url: data.html_url,
+        repo_url: `https://github.com/${ownerRepo}`,
+    };
+}
+/** Dispatch by ecosystem. `ref` is a package name, or owner/repo for github. */
+export async function fetchLatest(registry, ref) {
+    switch (registry) {
+        case 'npm':
+            return fetchNpmLatest(ref);
+        case 'pypi':
+            return fetchPypiLatest(ref);
+        case 'github':
+            return fetchGitHubLatest(ref);
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=fetchers.js.map

package/dist/enrich/fetchers.js.map

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

package/dist/file-resolve.d.ts

@@ -0,0 +1,35 @@
+/**
+ * NavGator File-Level Resolution
+ * Resolves file paths to import connections when no component exists.
+ * Enables `navgator impact src/foo.ts` and `navgator connections src/foo.ts`.
+ */
+import type { ArchitectureConnection } from './types.js';
+export interface FileConnections {
+    filePath: string;
+    fileId: string;
+    /** Files that import this file */
+    importedBy: ArchitectureConnection[];
+    /** Files this file imports */
+    imports: ArchitectureConnection[];
+    /** Non-import connections (service calls, etc.) where this file appears */
+    otherFrom: ArchitectureConnection[];
+    otherTo: ArchitectureConnection[];
+}
+/**
+ * Check if a query looks like a file path.
+ */
+export declare function looksLikeFilePath(query: string): boolean;
+/**
+ * Resolve a file path to its import connections.
+ * Returns null if no connections found for this file.
+ */
+export declare function resolveFileConnections(query: string, allConnections: ArchitectureConnection[]): FileConnections | null;
+/**
+ * Format file-level impact analysis for CLI output.
+ */
+export declare function formatFileImpact(fc: FileConnections): string;
+/**
+ * Format file-level connections for CLI output.
+ */
+export declare function formatFileConnections(fc: FileConnections): string;
+//# sourceMappingURL=file-resolve.d.ts.map

package/dist/file-resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-resolve.d.ts","sourceRoot":"","sources":["../src/file-resolve.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,UAAU,EAAE,sBAAsB,EAAE,CAAC;IACrC,8BAA8B;IAC9B,OAAO,EAAE,sBAAsB,EAAE,CAAC;IAClC,2EAA2E;IAC3E,SAAS,EAAE,sBAAsB,EAAE,CAAC;IACpC,OAAO,EAAE,sBAAsB,EAAE,CAAC;CACnC;AAWD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAUxD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,sBAAsB,EAAE,GACvC,eAAe,GAAG,IAAI,CA8BxB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,eAAe,GAAG,MAAM,CAyD5D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,eAAe,GAAG,MAAM,CA+CjE"}

package/dist/file-resolve.js

@@ -0,0 +1,159 @@
+/**
+ * NavGator File-Level Resolution
+ * Resolves file paths to import connections when no component exists.
+ * Enables `navgator impact src/foo.ts` and `navgator connections src/foo.ts`.
+ */
+/**
+ * Normalize a query to match FILE: connection IDs.
+ * Strips leading ./ and normalizes separators.
+ */
+function normalizeToFileId(query) {
+    const normalized = query.replace(/\\/g, '/').replace(/^\.\//, '');
+    return `FILE:${normalized}`;
+}
+/**
+ * Check if a query looks like a file path.
+ */
+export function looksLikeFilePath(query) {
+    return (query.includes('/') ||
+        query.includes('.ts') ||
+        query.includes('.js') ||
+        query.includes('.tsx') ||
+        query.includes('.jsx') ||
+        query.includes('.py') ||
+        query.includes('.swift'));
+}
+/**
+ * Resolve a file path to its import connections.
+ * Returns null if no connections found for this file.
+ */
+export function resolveFileConnections(query, allConnections) {
+    const fileId = normalizeToFileId(query);
+    const normalized = query.replace(/\\/g, '/').replace(/^\.\//, '');
+    // Find connections where this file is the source or target
+    const importedBy = [];
+    const imports = [];
+    const otherFrom = [];
+    const otherTo = [];
+    for (const conn of allConnections) {
+        const fromMatch = conn.from.component_id === fileId ||
+            conn.from.component_id === `FILE:${normalized}` ||
+            conn.code_reference?.file === normalized;
+        const toMatch = conn.to.component_id === fileId ||
+            conn.to.component_id === `FILE:${normalized}`;
+        if (conn.connection_type === 'imports') {
+            if (fromMatch)
+                imports.push(conn);
+            if (toMatch)
+                importedBy.push(conn);
+        }
+        else {
+            if (fromMatch)
+                otherFrom.push(conn);
+            if (toMatch)
+                otherTo.push(conn);
+        }
+    }
+    const total = importedBy.length + imports.length + otherFrom.length + otherTo.length;
+    if (total === 0)
+        return null;
+    return { filePath: normalized, fileId, importedBy, imports, otherFrom, otherTo };
+}
+/**
+ * Format file-level impact analysis for CLI output.
+ */
+export function formatFileImpact(fc) {
+    const lines = [];
+    lines.push(`NavGator - File Impact: ${fc.filePath}\n`);
+    lines.push('========================================');
+    lines.push(`File: ${fc.filePath}`);
+    const directCount = fc.importedBy.length;
+    const severity = directCount > 5 ? 'CRITICAL' : directCount >= 3 ? 'HIGH' : directCount >= 1 ? 'MEDIUM' : 'LOW';
+    lines.push(`Impact: ${severity} (${directCount} file${directCount !== 1 ? 's' : ''} import this)`);
+    if (fc.importedBy.length > 0) {
+        lines.push(`\nIMPORTED BY (${fc.importedBy.length}):`);
+        lines.push('These files import this file:\n');
+        for (const conn of fc.importedBy) {
+            const fromFile = conn.from.component_id.replace('FILE:', '');
+            const lineInfo = conn.code_reference?.line_start ? `:${conn.code_reference.line_start}` : '';
+            lines.push(`  ${fromFile}${lineInfo}`);
+            if (conn.code_reference?.symbol) {
+                lines.push(`    import: ${conn.code_reference.symbol}`);
+            }
+        }
+    }
+    if (fc.imports.length > 0) {
+        lines.push(`\nIMPORTS (${fc.imports.length}):`);
+        lines.push('This file imports:\n');
+        for (const conn of fc.imports) {
+            const toFile = conn.to.component_id.replace('FILE:', '');
+            lines.push(`  ${toFile}`);
+        }
+    }
+    if (fc.otherFrom.length > 0) {
+        lines.push(`\nOUTGOING SERVICE CALLS (${fc.otherFrom.length}):`);
+        for (const conn of fc.otherFrom) {
+            const target = conn.to.component_id;
+            lines.push(`  → ${target} (${conn.connection_type})`);
+        }
+    }
+    if (fc.otherTo.length > 0) {
+        lines.push(`\nINCOMING REFERENCES (${fc.otherTo.length}):`);
+        for (const conn of fc.otherTo) {
+            const source = conn.from.component_id;
+            lines.push(`  ← ${source} (${conn.connection_type})`);
+        }
+    }
+    lines.push('\n========================================');
+    lines.push('Files that may need changes:');
+    for (const conn of fc.importedBy) {
+        const fromFile = conn.from.component_id.replace('FILE:', '');
+        lines.push(`  - ${fromFile}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Format file-level connections for CLI output.
+ */
+export function formatFileConnections(fc) {
+    const lines = [];
+    lines.push(`NavGator - File Connections: ${fc.filePath}\n`);
+    lines.push('========================================');
+    lines.push(`File: ${fc.filePath}`);
+    if (fc.importedBy.length > 0) {
+        lines.push(`\nIMPORTED BY (${fc.importedBy.length}):`);
+        for (const conn of fc.importedBy) {
+            const fromFile = conn.from.component_id.replace('FILE:', '');
+            const lineInfo = conn.code_reference?.line_start ? `:${conn.code_reference.line_start}` : '';
+            lines.push(`├── ${fromFile}${lineInfo}`);
+            if (conn.code_reference?.symbol) {
+                lines.push(`│   └── import: ${conn.code_reference.symbol}`);
+            }
+        }
+    }
+    if (fc.imports.length > 0) {
+        lines.push(`\nIMPORTS (${fc.imports.length}):`);
+        for (const conn of fc.imports) {
+            const toFile = conn.to.component_id.replace('FILE:', '');
+            lines.push(`├── ${toFile}`);
+        }
+    }
+    if (fc.otherFrom.length > 0) {
+        lines.push(`\nOUTGOING (${fc.otherFrom.length}):`);
+        for (const conn of fc.otherFrom) {
+            lines.push(`├── ${conn.connection_type} → ${conn.to.component_id}`);
+        }
+    }
+    if (fc.otherTo.length > 0) {
+        lines.push(`\nINCOMING (${fc.otherTo.length}):`);
+        for (const conn of fc.otherTo) {
+            lines.push(`├── ${conn.connection_type} ← ${conn.from.component_id}`);
+        }
+    }
+    const total = fc.importedBy.length + fc.imports.length + fc.otherFrom.length + fc.otherTo.length;
+    if (total === 0) {
+        lines.push('\nNo connections found for this file.');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=file-resolve.js.map

package/dist/file-resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-resolve.js","sourceRoot":"","sources":["../src/file-resolve.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAgBH;;;GAGG;AACH,SAAS,iBAAiB,CAAC,KAAa;IACtC,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAClE,OAAO,QAAQ,UAAU,EAAE,CAAC;AAC9B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,OAAO,CACL,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;QACnB,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC;QACrB,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC;QACrB,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC;QACtB,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC;QACtB,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC;QACrB,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CACzB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAAa,EACb,cAAwC;IAExC,MAAM,MAAM,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;IACxC,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAElE,2DAA2D;IAC3D,MAAM,UAAU,GAA6B,EAAE,CAAC;IAChD,MAAM,OAAO,GAA6B,EAAE,CAAC;IAC7C,MAAM,SAAS,GAA6B,EAAE,CAAC;IAC/C,MAAM,OAAO,GAA6B,EAAE,CAAC;IAE7C,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;QAClC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,KAAK,MAAM;YACjD,IAAI,CAAC,IAAI,CAAC,YAAY,KAAK,QAAQ,UAAU,EAAE;YAC/C,IAAI,CAAC,cAAc,EAAE,IAAI,KAAK,UAAU,CAAC;QAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,YAAY,KAAK,MAAM;YAC7C,IAAI,CAAC,EAAE,CAAC,YAAY,KAAK,QAAQ,UAAU,EAAE,CAAC;QAEhD,IAAI,IAAI,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;YACvC,IAAI,SAAS;gBAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClC,IAAI,OAAO;gBAAE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrC,CAAC;aAAM,CAAC;YACN,IAAI,SAAS;gBAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACpC,IAAI,OAAO;gBAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IACrF,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE7B,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;AACnF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAAmB;IAClD,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,CAAC,IAAI,CAAC,2BAA2B,EAAE,CAAC,QAAQ,IAAI,CAAC,CAAC;IACvD,KAAK,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAC;IACvD,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC;IAEnC,MAAM,WAAW,GAAG,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC;IACzC,MAAM,QAAQ,GAAG,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC;IAChH,KAAK,CAAC,IAAI,CAAC,WAAW,QAAQ,KAAK,WAAW,QAAQ,WAAW,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;IAEnG,IAAI,EAAE,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC,UAAU,CAAC,MAAM,IAAI,CAAC,CAAC;QACvD,KAAK,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC;QAC9C,KAAK,MAAM,IAAI,IAAI,EAAE,CAAC,UAAU,EAAE,CAAC;YACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YAC7D,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,cAAc,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7F,KAAK,CAAC,IAAI,CAAC,KAAK,QAAQ,GAAG,QAAQ,EAAE,CAAC,CAAC;YACvC,IAAI,IAAI,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC;gBAChC,KAAK,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC;YAC1D,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;QAChD,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;QACnC,KAAK,MAAM,IAAI,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC;YAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YACzD,KAAK,CAAC,IAAI,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,IAAI,EAAE,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,6BAA6B,EAAE,CAAC,SAAS,CAAC,MAAM,IAAI,CAAC,CAAC;QACjE,KAAK,MAAM,IAAI,IAAI,EAAE,CAAC,SAAS,EAAE,CAAC;YAChC,MAAM,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC;YACpC,KAAK,CAAC,IAAI,CAAC,OAAO,MAAM,KAAK,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAED,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,0BAA0B,EAAE,CAAC,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;QAC5D,KAAK,MAAM,IAAI,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC;YAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC;YACtC,KAAK,CAAC,IAAI,CAAC,OAAO,MAAM,KAAK,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,4CAA4C,CAAC,CAAC;IACzD,KAAK,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;IAC3C,KAAK,MAAM,IAAI,IAAI,EAAE,CAAC,UAAU,EAAE,CAAC;QACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAC7D,KAAK,CAAC,IAAI,CAAC,OAAO,QAAQ,EAAE,CAAC,CAAC;IAChC,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,EAAmB;IACvD,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,CAAC,IAAI,CAAC,gCAAgC,EAAE,CAAC,QAAQ,IAAI,CAAC,CAAC;IAC5D,KAAK,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAC;IACvD,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC;IAEnC,IAAI,EAAE,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC,UAAU,CAAC,MAAM,IAAI,CAAC,CAAC;QACvD,KAAK,MAAM,IAAI,IAAI,EAAE,CAAC,UAAU,EAAE,CAAC;YACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YAC7D,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,cAAc,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7F,KAAK,CAAC,IAAI,CAAC,OAAO,QAAQ,GAAG,QAAQ,EAAE,CAAC,CAAC;YACzC,IAAI,IAAI,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC;gBAChC,KAAK,CAAC,IAAI,CAAC,mBAAmB,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC;YAC9D,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;QAChD,KAAK,MAAM,IAAI,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC;YAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YACzD,KAAK,CAAC,IAAI,CAAC,OAAO,MAAM,EAAE,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,IAAI,EAAE,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC,SAAS,CAAC,MAAM,IAAI,CAAC,CAAC;QACnD,KAAK,MAAM,IAAI,IAAI,EAAE,CAAC,SAAS,EAAE,CAAC;YAChC,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,eAAe,MAAM,IAAI,CAAC,EAAE,CAAC,YAAY,EAAE,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;IAED,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;QACjD,KAAK,MAAM,IAAI,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC;YAC9B,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,eAAe,MAAM,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,EAAE,CAAC,UAAU,CAAC,MAAM,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC;IACjG,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;QAChB,KAAK,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC;IACtD,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/freshness/dirty-ledger.d.ts

@@ -0,0 +1,7 @@
+/** Append paths to the dirty set (deduped, sorted). Safe to call concurrently-ish. */
+export declare function markDirty(paths: string[], root: string): void;
+/** Read the current dirty set (sorted). */
+export declare function readDirty(root: string): string[];
+/** Remove the given drained paths, leaving anything that arrived later. */
+export declare function clearDirty(drained: string[], root: string): void;
+//# sourceMappingURL=dirty-ledger.d.ts.map

package/dist/freshness/dirty-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dirty-ledger.d.ts","sourceRoot":"","sources":["../../src/freshness/dirty-ledger.ts"],"names":[],"mappings":"AAoCA,sFAAsF;AACtF,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAQ7D;AAED,2CAA2C;AAC3C,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAEhD;AAED,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAQhE"}

package/dist/freshness/dirty-ledger.js

@@ -0,0 +1,56 @@
+/**
+ * The dirty-set ledger: an append-only set of changed paths since the last clean
+ * drain. The PostToolUse hook appends here (fast, non-blocking); the drainer
+ * reads it, scans, and clears the drained subset. Late arrivals (marked while a
+ * scan is in flight) survive a partial clear and are picked up next drain.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { dirtyLedgerPath } from './paths.js';
+function load(root) {
+    const p = dirtyLedgerPath(root);
+    if (!fs.existsSync(p))
+        return { version: 1, paths: [], updated_at: 0 };
+    try {
+        const parsed = JSON.parse(fs.readFileSync(p, 'utf8'));
+        if (parsed?.version === 1 && Array.isArray(parsed.paths))
+            return parsed;
+    }
+    catch {
+        /* corrupt -> reset; never block the hook or drainer */
+    }
+    return { version: 1, paths: [], updated_at: 0 };
+}
+function save(root, data) {
+    const p = dirtyLedgerPath(root);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const tmp = `${p}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf8');
+    fs.renameSync(tmp, p); // atomic on same filesystem
+}
+/** Append paths to the dirty set (deduped, sorted). Safe to call concurrently-ish. */
+export function markDirty(paths, root) {
+    const data = load(root);
+    const set = new Set(data.paths);
+    for (const raw of paths) {
+        const v = raw.trim();
+        if (v)
+            set.add(v);
+    }
+    save(root, { version: 1, paths: [...set].sort(), updated_at: Date.now() });
+}
+/** Read the current dirty set (sorted). */
+export function readDirty(root) {
+    return load(root).paths;
+}
+/** Remove the given drained paths, leaving anything that arrived later. */
+export function clearDirty(drained, root) {
+    const data = load(root);
+    const drop = new Set(drained);
+    save(root, {
+        version: 1,
+        paths: data.paths.filter((p) => !drop.has(p)),
+        updated_at: Date.now(),
+    });
+}
+//# sourceMappingURL=dirty-ledger.js.map

package/dist/freshness/dirty-ledger.js.map

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

package/dist/freshness/drainer.d.ts

@@ -0,0 +1,38 @@
+export type DrainStatus = 'busy' | 'debounced' | 'clean' | 'drained' | 'error';
+export interface DrainResult {
+    status: DrainStatus;
+    scanned: number;
+    error?: string;
+}
+export interface DrainOptions {
+    /** Injected scanner. Production passes a wrapper over NavGator `scan()`. */
+    scanFn: (root: string, changed: string[]) => Promise<void>;
+    /** Skip if the last stamp was generated within this window (default 3000ms). */
+    minIntervalMs?: number;
+}
+export declare function drain(root: string, opts: DrainOptions): Promise<DrainResult>;
+export interface DrainUntilCleanOptions extends DrainOptions {
+    /** Max drain attempts before giving up (default 12). Bounds worst-case time. */
+    maxAttempts?: number;
+    /** Override the post-attempt wait; defaults to minIntervalMs (busy waits less). */
+    waitMs?: number;
+}
+/**
+ * Trailing-edge guarantee. A single `drain()` can leave the *final* edits of a
+ * burst undrained (debounced) or skipped (busy). This loops past those states —
+ * sleeping out the debounce window between tries — until the ledger is actually
+ * empty, so the view self-heals within ~minIntervalMs of edits stopping instead
+ * of waiting for the 5-minute autoRefresh backstop. The hook spawns this
+ * detached, so the sleeps never block an edit. Returns every attempt's result.
+ */
+export declare function drainUntilClean(root: string, opts: DrainUntilCleanOptions): Promise<DrainResult[]>;
+/**
+ * Stamp coherence for out-of-band scans. NavGator's existing `autoRefreshIfStale`
+ * backstop runs an incremental scan WITHOUT going through the drainer, which
+ * would leave the dirty ledger and stamp stale — making the stamp lie (report
+ * dirty when the graph is actually current). Call this after any such scan to
+ * reconcile: the incremental scan already covered every changed file via hashes,
+ * so the whole ledger is safely cleared and a clean stamp written. Best-effort.
+ */
+export declare function reconcileClean(root: string): Promise<void>;
+//# sourceMappingURL=drainer.d.ts.map

package/dist/freshness/drainer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drainer.d.ts","sourceRoot":"","sources":["../../src/freshness/drainer.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,WAAW,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;AAE/E,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAuClF;AAID,MAAM,WAAW,sBAAuB,SAAQ,YAAY;IAC1D,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,WAAW,EAAE,CAAC,CAaxB;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhE"}

package/dist/freshness/drainer.js

@@ -0,0 +1,88 @@
+/**
+ * The background drainer. Coalesces the dirty set and runs one incremental scan
+ * under the single-writer lock, then writes an honest stamp. Designed to be
+ * invoked repeatedly and cheaply (by the hook, the orchestrator, or a timer):
+ *  - busy      -> another drainer holds the lock; caller should not wait.
+ *  - debounced -> a drain ran within minIntervalMs; skipped (dirty set kept).
+ *  - clean     -> nothing dirty; stamp refreshed only.
+ *  - drained   -> scanned, cleared the drained subset, stamp updated.
+ *  - error     -> scan threw; dirty set left intact for a retry.
+ */
+import { readDirty, clearDirty } from './dirty-ledger.js';
+import { acquireLock, releaseLock } from './scan-lock.js';
+import { computeStamp, writeStamp, readStamp } from './stamp.js';
+export async function drain(root, opts) {
+    const minInterval = opts.minIntervalMs ?? 3000;
+    // Debounce off the last stamp's generated_at (only when there IS prior state).
+    const prior = readStamp(root);
+    if (prior && Date.now() - prior.generated_at < minInterval) {
+        return { status: 'debounced', scanned: 0 };
+    }
+    if (!acquireLock(root)) {
+        return { status: 'busy', scanned: 0 };
+    }
+    try {
+        const dirty = readDirty(root);
+        if (dirty.length === 0) {
+            writeStamp(root, await computeStamp(root, { inFlight: false }));
+            return { status: 'clean', scanned: 0 };
+        }
+        // Mark in-flight so concurrent readers see the truth during the scan.
+        writeStamp(root, await computeStamp(root, { inFlight: true }));
+        try {
+            await opts.scanFn(root, dirty);
+        }
+        catch (e) {
+            // Leave the dirty set intact; clear the in-flight flag honestly.
+            writeStamp(root, await computeStamp(root, { inFlight: false }));
+            return { status: 'error', scanned: 0, error: e instanceof Error ? e.message : String(e) };
+        }
+        const completedAt = Date.now();
+        clearDirty(dirty, root); // clears only what we drained; late arrivals remain
+        writeStamp(root, await computeStamp(root, { inFlight: false, generatedAt: completedAt }));
+        return { status: 'drained', scanned: dirty.length };
+    }
+    finally {
+        releaseLock(root);
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Trailing-edge guarantee. A single `drain()` can leave the *final* edits of a
+ * burst undrained (debounced) or skipped (busy). This loops past those states —
+ * sleeping out the debounce window between tries — until the ledger is actually
+ * empty, so the view self-heals within ~minIntervalMs of edits stopping instead
+ * of waiting for the 5-minute autoRefresh backstop. The hook spawns this
+ * detached, so the sleeps never block an edit. Returns every attempt's result.
+ */
+export async function drainUntilClean(root, opts) {
+    const maxAttempts = opts.maxAttempts ?? 12;
+    const baseWait = opts.waitMs ?? opts.minIntervalMs ?? 3000;
+    const results = [];
+    for (let i = 0; i < maxAttempts; i++) {
+        const res = await drain(root, { scanFn: opts.scanFn, minIntervalMs: opts.minIntervalMs });
+        results.push(res);
+        const settled = res.status === 'drained' || res.status === 'clean';
+        if (settled && readDirty(root).length === 0)
+            break; // ledger truly empty → done
+        if (res.status === 'error')
+            break; // a scan that throws won't fix itself by retrying
+        await sleep(res.status === 'busy' ? Math.min(1000, baseWait) : baseWait);
+    }
+    return results;
+}
+/**
+ * Stamp coherence for out-of-band scans. NavGator's existing `autoRefreshIfStale`
+ * backstop runs an incremental scan WITHOUT going through the drainer, which
+ * would leave the dirty ledger and stamp stale — making the stamp lie (report
+ * dirty when the graph is actually current). Call this after any such scan to
+ * reconcile: the incremental scan already covered every changed file via hashes,
+ * so the whole ledger is safely cleared and a clean stamp written. Best-effort.
+ */
+export async function reconcileClean(root) {
+    const all = readDirty(root);
+    if (all.length > 0)
+        clearDirty(all, root);
+    writeStamp(root, await computeStamp(root, { inFlight: false }));
+}
+//# sourceMappingURL=drainer.js.map

package/dist/freshness/drainer.js.map

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

package/dist/freshness/paths.d.ts

@@ -0,0 +1,9 @@
+/** The `.navgator` base dir for a project root (sibling of `architecture/`). */
+export declare function navgatorBase(root: string): string;
+/** Dirty-set ledger: append-only set of changed paths since the last clean drain. */
+export declare function dirtyLedgerPath(root: string): string;
+/** Single-writer scan lock. */
+export declare function scanLockPath(root: string): string;
+/** Freshness stamp, stored next to the graph it describes. */
+export declare function stampPath(root: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/freshness/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/freshness/paths.ts"],"names":[],"mappings":"AAQA,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,+BAA+B;AAC/B,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,8DAA8D;AAC9D,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C"}

package/dist/freshness/paths.js

@@ -0,0 +1,24 @@
+/**
+ * Single source of truth for freshness-subsystem file locations.
+ * Derived from NavGator config so local vs shared storage mode is honored:
+ * getStoragePath() returns <base>/architecture, so its dirname is the base.
+ */
+import * as path from 'path';
+import { getConfig, getStoragePath } from '../config.js';
+/** The `.navgator` base dir for a project root (sibling of `architecture/`). */
+export function navgatorBase(root) {
+    return path.dirname(getStoragePath(getConfig(), root));
+}
+/** Dirty-set ledger: append-only set of changed paths since the last clean drain. */
+export function dirtyLedgerPath(root) {
+    return path.join(navgatorBase(root), 'dirty.json');
+}
+/** Single-writer scan lock. */
+export function scanLockPath(root) {
+    return path.join(navgatorBase(root), 'scan.lock');
+}
+/** Freshness stamp, stored next to the graph it describes. */
+export function stampPath(root) {
+    return path.join(navgatorBase(root), 'architecture', 'freshness.json');
+}
+//# sourceMappingURL=paths.js.map

package/dist/freshness/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/freshness/paths.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEzD,gFAAgF;AAChF,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,SAAS,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC,CAAC;AACrD,CAAC;AAED,+BAA+B;AAC/B,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,CAAC;AACpD,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,cAAc,EAAE,gBAAgB,CAAC,CAAC;AACzE,CAAC"}

package/dist/freshness/scan-lock.d.ts

@@ -0,0 +1,8 @@
+export declare const LOCK_TTL_MS = 60000;
+/** Try to take the lock. Returns true on success, false if a live lock exists. */
+export declare function acquireLock(root: string): boolean;
+/** Refresh the heartbeat mid-scan (call periodically for long scans). */
+export declare function touchLock(root: string): void;
+/** Release the lock if we own it. */
+export declare function releaseLock(root: string): void;
+//# sourceMappingURL=scan-lock.d.ts.map

package/dist/freshness/scan-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-lock.d.ts","sourceRoot":"","sources":["../../src/freshness/scan-lock.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,WAAW,QAAS,CAAC;AA0BlC,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAWjD;AAED,yEAAyE;AACzE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAS5C;AAED,qCAAqC;AACrC,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAU9C"}