@lensmcp/cluster 1.23.13 → 1.24.0

package/perf/perf-rules-analysis.d.ts

@@ -0,0 +1,28 @@
+import { type BarrelMeasurement, type HeavyBarrelThresholds, type ProjectCompilation, type SourceReader } from './heavy-barrel-import';
+export interface BarrelAnalysisJob {
+    workspaceRoot: string;
+    /** The tsconfig whose library aliases are read. */
+    tsConfig: string;
+    projects: ProjectCompilation[];
+    thresholds: HeavyBarrelThresholds;
+    budgetMs: number;
+}
+export interface BarrelAnalysisOutcome {
+    complete: boolean;
+    measurements: BarrelMeasurement[];
+    elapsedMs: number;
+    /** Set when the analysis threw — nothing is concluded. */
+    error?: string;
+    /** Where it ran. */
+    thread: 'worker' | 'main';
+}
+/** A source reader over the real files: each read once, size-capped. */
+export declare function fileReader(): SourceReader;
+/** Library discovery + the analysis, within the budget. Never throws. */
+export declare function runBarrelAnalysis(job: BarrelAnalysisJob, thread?: BarrelAnalysisOutcome['thread']): BarrelAnalysisOutcome;
+/**
+ * {@link runBarrelAnalysis} on a worker thread: the caller's event loop stays free while it runs. The worker never
+ * keeps the process alive. When no worker can be started, the analysis runs here, as it did before — the outcome
+ * says which.
+ */
+export declare function runBarrelAnalysisOffThread(job: BarrelAnalysisJob): Promise<BarrelAnalysisOutcome>;

package/perf/perf-rules-analysis.js

@@ -0,0 +1 @@
+"use strict";var u=Object.defineProperty;var l=(e,t)=>u(e,"name",{value:t,configurable:!0});var c=Object.defineProperty,i=l((e,t)=>c(e,"name",{value:t,configurable:!0}),"i");Object.defineProperty(exports,"__esModule",{value:!0}),exports.fileReader=fileReader,exports.runBarrelAnalysis=runBarrelAnalysis,exports.runBarrelAnalysisOffThread=runBarrelAnalysisOffThread;const tslib_1=require("tslib"),fs=tslib_1.__importStar(require("node:fs")),path=tslib_1.__importStar(require("node:path")),node_worker_threads_1=require("node:worker_threads"),heavy_barrel_import_1=require("./heavy-barrel-import"),workspace_libraries_1=require("./workspace-libraries"),MAX_SOURCE_BYTES=1024*1024;function fileReader(){const e=new Map,t=new Map;return{read(r){if(e.has(r))return e.get(r);let s;try{fs.statSync(r).size<=MAX_SOURCE_BYTES&&(s=fs.readFileSync(r,"utf8"))}catch{s=void 0}return e.set(r,s),s},exists(r){let s=t.get(r);if(s===void 0){try{s=fs.statSync(r).isFile()}catch{s=!1}t.set(r,s)}return s}}}l(fileReader,"fileReader"),i(fileReader,"fileReader");function runBarrelAnalysis(e,t="main"){const r=Date.now(),s=r+e.budgetMs;try{const a=(0,workspace_libraries_1.discoverWorkspaceLibraries)(e.workspaceRoot,{tsConfig:e.tsConfig}),n=(0,heavy_barrel_import_1.analyzeBarrelImports)({workspaceRoot:e.workspaceRoot,libraries:a,projects:e.projects,thresholds:e.thresholds,source:fileReader(),expired:i(()=>Date.now()>s,"expired")});return{complete:n.complete,measurements:n.measurements,elapsedMs:Date.now()-r,thread:t}}catch(a){return{complete:!1,measurements:[],elapsedMs:Date.now()-r,error:a?.message??String(a),thread:t}}}l(runBarrelAnalysis,"runBarrelAnalysis"),i(runBarrelAnalysis,"runBarrelAnalysis");function workerScript(){const e=path.join(__dirname,"perf-rules-worker.js");if(fs.existsSync(e))return{file:e,eval:!1};const t=path.join(__dirname,"perf-rules-worker.ts");if(fs.existsSync(t))try{const r=require.resolve("@swc-node/register");return{file:`require(${JSON.stringify(r)}); require(${JSON.stringify(t)});`,eval:!0}}catch{return}}l(workerScript,"workerScript"),i(workerScript,"workerScript");function runBarrelAnalysisOffThread(e){const t=workerScript();return t?new Promise(r=>{let s=!1;const a=i(o=>{s||(s=!0,r(o))},"settle");let n;try{n=new node_worker_threads_1.Worker(t.file,{eval:t.eval,workerData:e})}catch{a(runBarrelAnalysis(e,"main"));return}n.unref(),n.once("message",o=>a(o)),n.once("error",o=>a({complete:!1,measurements:[],elapsedMs:0,error:o.message,thread:"worker"})),n.once("exit",o=>a({complete:!1,measurements:[],elapsedMs:0,error:`the analysis worker exited (${o}) without an answer`,thread:"worker"}))}):Promise.resolve(runBarrelAnalysis(e,"main"))}l(runBarrelAnalysisOffThread,"runBarrelAnalysisOffThread"),i(runBarrelAnalysisOffThread,"runBarrelAnalysisOffThread");

package/perf/perf-rules-plugin.d.ts

@@ -0,0 +1,71 @@
+import { type BarrelMeasurement } from './heavy-barrel-import';
+import { type PerfRulePublisher } from './perf-rule-events';
+import { type BarrelAnalysisOutcome } from './perf-rules-analysis';
+export interface PerfRulesPluginOptions {
+    /** The Nx project this compiler builds. */
+    project: string;
+    workspaceRoot: string;
+    /** The project's tsconfig — the library aliases are read from what it sees. */
+    tsConfig: string;
+    /** The bus file. Default `LENSMCP_EVENT_FILE`, else `<workspace>/.lensmcp/events.jsonl`. */
+    eventFile?: string;
+    /** A multi-entry compilation: entry name → project — or a function, read per compilation, when the entries change.
+     *  Absent: every module is `project`'s. */
+    entries?: Record<string, string> | (() => Record<string, string>);
+    env?: NodeJS.ProcessEnv;
+    /** How long after a compilation the analysis runs. */
+    delayMs?: number;
+    publisher?: PerfRulePublisher;
+    now?: () => number;
+    /** After each analysis — for the spec and for anyone who wants the measurements. */
+    onAnalysis?: (run: PerfRulesRun) => void;
+    log?: (line: string) => void;
+}
+/** One analysis, as `onAnalysis` sees it. */
+export interface PerfRulesRun {
+    complete: boolean;
+    elapsedMs: number;
+    /** Where the analysis ran: a worker thread, or this one (the spec's `analyze()`, or no worker could start). */
+    thread: BarrelAnalysisOutcome['thread'];
+    measurements: BarrelMeasurement[];
+    /** Per project: the subjects open after this run. */
+    open: Record<string, string[]>;
+    published: number;
+}
+export declare class PerfRulesPlugin {
+    private readonly options;
+    private readonly settings;
+    private readonly publisher;
+    private readonly now;
+    private readonly log;
+    /** Per project: the module-set fingerprint last analysed (or pending). */
+    private readonly signatures;
+    /** Per project: the subjects this process has published as open. */
+    private readonly open;
+    /** Per project: the title last logged per subject — a finding is logged when it opens or changes, not per run. */
+    private readonly logged;
+    private readonly pending;
+    private timer;
+    /** The analysis on its worker thread, while it runs — the next one waits for it. */
+    private running;
+    private closed;
+    /** The most recent compilation that built enough modules to estimate per-module compile time from. */
+    private estimateBasis;
+    constructor(options: PerfRulesPluginOptions);
+    apply(compiler: any): void;
+    /** Each project's modules in this compilation — by entry when `entries` says, else all of them. */
+    private projectModules;
+    private collect;
+    private schedule;
+    /** Take every pending project's modules: the job one analysis runs. */
+    private takeJob;
+    /** Run the rules over every pending project on THIS thread, publish what changed. Exposed for the spec. */
+    analyze(): PerfRulesRun | undefined;
+    /**
+     * Run the rules over every pending project on a worker thread, publish what changed — what the timer runs. One
+     * at a time: projects that changed meanwhile wait for this one, then go in the next.
+     */
+    analyzeOffThread(): Promise<PerfRulesRun | undefined>;
+    private conclude;
+    private publishProject;
+}

package/perf/perf-rules-plugin.js

@@ -0,0 +1 @@
+"use strict";var E=Object.defineProperty;var g=(l,e)=>E(l,"name",{value:e,configurable:!0});var _=Object.defineProperty,p=g((l,e)=>_(l,"name",{value:e,configurable:!0}),"p");Object.defineProperty(exports,"__esModule",{value:!0}),exports.PerfRulesPlugin=void 0;const tslib_1=require("tslib"),path=tslib_1.__importStar(require("node:path")),heavy_barrel_import_1=require("./heavy-barrel-import"),perf_config_1=require("./perf-config"),perf_rule_events_1=require("./perf-rule-events"),perf_rules_analysis_1=require("./perf-rules-analysis"),NAME="LensmcpPerfRulesPlugin",DEFAULT_DELAY_MS=1e3;function fnv(l){let e=2166136261;for(let t=0;t<l.length;t++)e^=l.charCodeAt(t),e=Math.imul(e,16777619);return e>>>0}g(fnv,"fnv"),p(fnv,"fnv");const resourceOf=p(l=>{if(typeof l.resource!="string"||!l.resource)return;const e=l.resource.search(/[?#]/);return e===-1?l.resource:l.resource.slice(0,e)},"resourceOf");class PerfRulesPlugin{static{g(this,"PerfRulesPlugin")}static{p(this,"PerfRulesPlugin")}constructor(e){this.options=e,this.signatures=new Map,this.open=new Map,this.logged=new Map,this.pending=new Map,this.closed=!1;const t=e.env??process.env;this.settings=(0,perf_config_1.resolveBundleRuleSettings)(e.workspaceRoot,t),this.publisher=e.publisher??(0,perf_rule_events_1.createPerfRulePublisher)(e.eventFile??(t.LENSMCP_EVENT_FILE||path.join(e.workspaceRoot,".lensmcp","events.jsonl"))),this.now=e.now??Date.now,this.log=e.log??(s=>console.log(s))}apply(e){if(!this.settings.enabled)return;const t=new WeakMap;e.hooks.thisCompilation.tap(NAME,s=>{t.set(s,0),s.hooks.buildModule.tap(NAME,()=>t.set(s,(t.get(s)??0)+1))}),e.hooks.done.tap(NAME,s=>{try{if(s.hasErrors())return;const i=s.compilation,o={durationMs:Math.max(0,(s.endTime??0)-(s.startTime??0)),builtModules:t.get(i)??0};this.collect(i,o)}catch{}}),e.hooks.watchClose?.tap(NAME,()=>{this.closed=!0,this.timer&&clearTimeout(this.timer),this.timer=void 0,this.pending.clear()})}projectModules(e){const t=new Map,s=typeof this.options.entries=="function"?this.options.entries():this.options.entries;if(!s)return t.set(this.options.project,e.modules),t;const i=new Map;for(const[o,r]of Object.entries(s)){const c=e.entrypoints?.get(o);if(!c)continue;const h=i.get(r)??new Set;for(const u of c.chunks??[])for(const n of e.chunkGraph.getChunkModulesIterable(u))h.add(n);i.set(r,h)}for(const[o,r]of i)t.set(o,r);return t}collect(e,t){t.builtModules>=50&&(this.estimateBasis=t);let s=!1;for(const[i,o]of this.projectModules(e)){let r=0,c=0,h=0;const u=[];for(const a of o){const f=resourceOf(a);if(!f)continue;const d=fnv(f);r=r+d>>>0,c=(c^Math.imul(d,2654435761))>>>0,h++,u.push(a)}const n=`${h}:${r.toString(36)}:${c.toString(36)}`;if(this.signatures.get(i)===n)continue;this.signatures.set(i,n);const j=e.moduleGraph,M=u.map(a=>{const f=new Set;for(const m of j.getOutgoingConnections(a)){const b=m.module?resourceOf(m.module):void 0;b&&f.add(b)}let d;try{d=typeof a.size=="function"?a.size():0}catch{d=0}return{resource:resourceOf(a),size:d,dependencies:[...f]}});this.pending.set(i,{modules:M,compile:t}),s=!0}s&&this.schedule()}schedule(){this.timer&&clearTimeout(this.timer),this.timer=setTimeout(()=>{this.timer=void 0,this.analyzeOffThread()},this.options.delayMs??DEFAULT_DELAY_MS),this.timer.unref?.()}takeJob(){if(this.pending.size===0)return;const e=[...this.pending].map(([t,s])=>({project:t,modules:s.modules,compile:s.compile}));return this.pending.clear(),{workspaceRoot:this.options.workspaceRoot,tsConfig:this.options.tsConfig,projects:e,thresholds:this.settings.thresholds,budgetMs:this.settings.budgetMs}}analyze(){const e=this.takeJob();return e?this.conclude(e,(0,perf_rules_analysis_1.runBarrelAnalysis)(e,"main")):void 0}analyzeOffThread(){if(this.running)return this.running.then(()=>this.analyzeOffThread());const e=this.takeJob();if(!e)return Promise.resolve(void 0);const t=(0,perf_rules_analysis_1.runBarrelAnalysisOffThread)(e).then(s=>this.closed?void 0:this.conclude(e,s)).finally(()=>{this.running=void 0,this.pending.size>0&&!this.closed&&!this.timer&&this.schedule()});return this.running=t,t}conclude(e,t){const{projects:s}=e;if(t.error){this.log(`[perf-rules] analysis failed: ${t.error}`);for(const o of s)this.signatures.delete(o.project);return}const i={complete:t.complete,elapsedMs:t.elapsedMs,thread:t.thread,measurements:t.measurements,open:{},published:0};if(!t.complete){this.log(`[perf-rules] ${s.map(o=>o.project).join(", ")}: the analysis ran past its ${this.settings.budgetMs} ms budget \u2014 nothing concluded (LENSMCP_PERF_RULES_BUDGET_MS)`);for(const o of s)this.signatures.delete(o.project);return this.options.onAnalysis?.(i),i}try{for(const o of s)i.published+=this.publishProject(o,t.measurements.filter(r=>r.project===o.project&&r.fires),i)}catch(o){this.log(`[perf-rules] publishing failed: ${o?.message??String(o)}`);for(const r of s)this.signatures.delete(r.project);return}return this.options.onAnalysis?.(i),i}publishProject(e,t,s){const i=this.now(),o=this.open.get(e.project)??new Set,r=new Set,c=this.logged.get(e.project)??new Map;let h=0;for(const u of t){const n=(0,heavy_barrel_import_1.describeHeavyBarrel)(u,e.compile.builtModules>=50?e.compile:this.estimateBasis);r.add(n.subject),this.publisher.publish((0,perf_rule_events_1.buildPerfFindingEvent)(e.project,{...n,rule:heavy_barrel_import_1.HEAVY_BARREL_RULE,docs:`${perf_rule_events_1.PERF_RULES_DOC}#bundleheavy-barrel-import`},i))&&h++,c.get(n.subject)!==n.title&&(c.set(n.subject,n.title),this.log(`[perf-rules] ${heavy_barrel_import_1.HEAVY_BARREL_RULE}: ${n.title} \u2014 ${n.cost.modules} modules (${(n.cost.bytes/(1024*1024)).toFixed(1)} MB) compiled for nothing; import ${n.subject} by subpath (the files and lines: perf://rules)`))}for(const u of o)r.has(u)||(this.publisher.publish((0,perf_rule_events_1.buildPerfRetractedEvent)(heavy_barrel_import_1.HEAVY_BARREL_RULE,e.project,u,"cleared",i))&&h++,c.delete(u),this.log(`[perf-rules] ${heavy_barrel_import_1.HEAVY_BARREL_RULE}: cleared for ${e.project} \u2014 it no longer compiles ${u} through its root barrel`));return(!this.open.has(e.project)||o.size>0||r.size>0)&&this.publisher.publish((0,perf_rule_events_1.buildPerfScanEvent)(heavy_barrel_import_1.HEAVY_BARREL_RULE,e.project,[...r].sort(),i,void 0,s.elapsedMs))&&h++,this.open.set(e.project,r),this.logged.set(e.project,c),s.open[e.project]=[...r].sort(),h}}exports.PerfRulesPlugin=PerfRulesPlugin;

package/perf/perf-rules-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/perf/perf-rules-worker.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});const node_worker_threads_1=require("node:worker_threads"),perf_rules_analysis_1=require("./perf-rules-analysis");node_worker_threads_1.parentPort?.postMessage((0,perf_rules_analysis_1.runBarrelAnalysis)(node_worker_threads_1.workerData,"worker"));

package/perf/source-scan.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A static scan of TypeScript/JavaScript source for what `bundle/heavy-barrel-import` needs to know: which names a
+ * file imports from a specifier, and which names a library file exports (declared, re-exported, or `export *`-ed).
+ *
+ * Deliberately not a parser: the rule runs inside the dev webpack process after a compilation, over hundreds of
+ * files, and must stay cheap and dependency-free. It reads import/export STATEMENTS — which sit at a file's top
+ * level in practice — after blanking comments, so a commented-out import never counts. What it cannot read (a
+ * dynamic `import()`/`require()` of the specifier, a namespace object passed around whole) is reported as
+ * `wholeModule`, and the rule treats that importer as needing everything: an unreadable usage never produces a
+ * finding, it only prevents one.
+ */
+/** One name a file imports. */
+export interface ImportedName {
+    /** The exported name (`default` for a default import). */
+    imported: string;
+    /** `import type`, or `{ type X }`: erased by the compiler, costs nothing at runtime. */
+    typeOnly: boolean;
+}
+/** Everything one file takes from one specifier. */
+export interface SpecifierUsage {
+    specifier: string;
+    names: ImportedName[];
+    /** The whole module object escapes (`import *` used other than as `ns.name`, `require()`, `import()`). */
+    wholeModule: boolean;
+    /** `import 'x'` / `export * from 'x'` — loaded for its effects or forwarded whole. */
+    sideEffect: boolean;
+}
+/** What a library file exports, and from where. */
+export interface ExportIndex {
+    /** Names declared here as values (functions, classes, consts, enums). */
+    values: Set<string>;
+    /** Names declared here as types only (interfaces, type aliases) — no runtime module behind them. */
+    types: Set<string>;
+    /** `export { a as b } from './x'` — exported name → [specifier, name there]. */
+    reexports: Map<string, {
+        specifier: string;
+        name: string;
+        typeOnly: boolean;
+    }>;
+    /** `export * from './x'` — searched, in order, for any name not found above. */
+    stars: string[];
+    /** `export * as ns from './x'` — the name stands for that whole module. */
+    namespaces: Map<string, string>;
+    /** Specifiers this file's OWN code loads (value and side-effect imports — not re-exports, not type-only). */
+    valueImports: string[];
+}
+/**
+ * The source with every comment replaced by spaces (newlines kept), strings, template literals and regex literals
+ * left intact — so offsets and line numbers still match the file, and a `//` inside a string is not a comment.
+ * Jumps from one quote or slash to the next: the text between them is copied as it is.
+ */
+export declare function blankComments(src: string): string;
+/**
+ * What `source` imports from each specifier `wanted` accepts — named imports, default, namespaces (with the
+ * `ns.name` accesses that follow), `import x = require()`, re-exports, side-effect and dynamic loads.
+ */
+export declare function scanImports(source: string, wanted: (specifier: string) => boolean): SpecifierUsage[];
+/** What a library file exports, read from its source. */
+export declare function scanExports(source: string): ExportIndex;

package/perf/source-scan.js

@@ -0,0 +1,5 @@
+"use strict";var y=Object.defineProperty;var d=(o,r)=>y(o,"name",{value:r,configurable:!0});var u=Object.defineProperty,m=d((o,r)=>u(o,"name",{value:r,configurable:!0}),"m");Object.defineProperty(exports,"__esModule",{value:!0}),exports.blankComments=blankComments,exports.scanImports=scanImports,exports.scanExports=scanExports;const KEYWORDS_BEFORE_REGEX=new Set(["return","typeof","case","do","else","in","of","void","delete","throw","new","yield","await","instanceof"]),PUNCT_BEFORE_REGEX=new Set(["(",",","=",":","[","!","&","|","?","{","}",";","+","-","*","%","<",">","~","^"]);function regexAllowedAt(o,r){let s=r-1;for(;s>=0&&(o[s]===" "||o[s]==="	"||o[s]===`
+`||o[s]==="\r");)s--;if(s<0)return!0;const a=o[s];if(PUNCT_BEFORE_REGEX.has(a))return!0;if(!/[\w$]/.test(a))return!1;let l=s;for(;l>0&&/[\w$]/.test(o[l-1]);)l--;return KEYWORDS_BEFORE_REGEX.has(o.slice(l,s+1))}d(regexAllowedAt,"regexAllowedAt"),m(regexAllowedAt,"regexAllowedAt");function stringEnd(o,r){const s=o[r];let a=r+1;for(;a<o.length&&o[a]!==s;){if(o[a]==="\\")a++;else if(s!=="`"&&o[a]===`
+`)return a;a++}return Math.min(a+1,o.length)}d(stringEnd,"stringEnd"),m(stringEnd,"stringEnd");function regexEnd(o,r){let s=r+1,a=!1;for(;s<o.length&&o[s]!==`
+`;){const l=o[s];if(l==="\\")s++;else if(l==="[")a=!0;else if(l==="]")a=!1;else if(l==="/"&&!a)return s+1;s++}return s}d(regexEnd,"regexEnd"),m(regexEnd,"regexEnd");function blankComments(o){const r=[],s=/[/"'`]/g;let a=0,l=0;for(;;){s.lastIndex=l;const t=s.exec(o);if(!t)break;const c=t.index;if(o[c]!=="/"){l=stringEnd(o,c);continue}const e=o[c+1];if(e==="/"||e==="*"){const n=e==="/"?o.indexOf(`
+`,c):o.indexOf("*/",c+2),i=n===-1?o.length:e==="/"?n:n+2;r.push(o.slice(a,c),o.slice(c,i).replace(/[^\n]/g," ")),a=l=i;continue}l=regexAllowedAt(o,c)?regexEnd(o,c):c+1}return r.push(o.slice(a)),r.join("")}d(blankComments,"blankComments"),m(blankComments,"blankComments");const SPEC=String.raw`['"]([^'"\n]+)['"]`,IMPORT_NAMED=new RegExp(String.raw`\bimport\s+(type\s+)?(?:([\w$]+)\s*,\s*)?\{([^}]*)\}\s*from\s*${SPEC}`,"g"),IMPORT_NAMESPACE=new RegExp(String.raw`\bimport\s+(type\s+)?(?:([\w$]+)\s*,\s*)?\*\s*as\s+([\w$]+)\s+from\s*${SPEC}`,"g"),IMPORT_DEFAULT=new RegExp(String.raw`\bimport\s+(type\s+)?([\w$]+)\s+from\s*${SPEC}`,"g"),IMPORT_EQUALS=new RegExp(String.raw`\bimport\s+(type\s+)?([\w$]+)\s*=\s*require\s*\(\s*${SPEC}\s*\)`,"g"),IMPORT_BARE=new RegExp(String.raw`\bimport\s*${SPEC}`,"g"),EXPORT_FROM=new RegExp(String.raw`\bexport\s+(type\s+)?\{([^}]*)\}\s*from\s*${SPEC}`,"g"),EXPORT_STAR=new RegExp(String.raw`\bexport\s+(type\s+)?\*\s*(?:as\s+([\w$]+)\s+)?from\s*${SPEC}`,"g"),DYNAMIC=new RegExp(String.raw`\b(?:require|import)\s*\(\s*${SPEC}\s*\)`,"g"),EXPORT_LOCAL=/\bexport\s+(type\s+)?\{([^}]*)\}(?!\s*from)/g,EXPORT_VALUE_DECL=/\bexport\s+(?:declare\s+)?(?:default\s+)?(?:async\s+)?(?:function\s*\*?\s*|(?:abstract\s+class|class|const\s+enum|enum|const|let|var)\s+)([\w$]+)/g,EXPORT_DESTRUCTURED=/\bexport\s+(?:declare\s+)?(?:const|let|var)\s+[{[]([^}\]]*)[}\]]/g,EXPORT_TYPE_DECL=/\bexport\s+(?:declare\s+)?(?:interface|type)\s+([\w$]+)/g,EXPORT_DEFAULT=/\bexport\s+default\b/,EXPORT_NAMESPACE_DECL=/\bexport\s+(?:declare\s+)?namespace\s+([\w$]+)/g;function parseSpecifiers(o,r){const s=[];for(const a of o.split(",")){const l=a.trim();if(!l)continue;const t=/^(type\s+)?([\w$]+)(?:\s+as\s+([\w$]+))?$/.exec(l);t&&s.push({imported:t[2],local:t[3]??t[2],typeOnly:r||!!t[1]})}return s}d(parseSpecifiers,"parseSpecifiers"),m(parseSpecifiers,"parseSpecifiers");function reEscape(o){return o.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}d(reEscape,"reEscape"),m(reEscape,"reEscape");function scanImports(o,r){const s=blankComments(o),a=new Map,l=m(e=>{let n=a.get(e);return n||(n={specifier:e,names:[],wholeModule:!1,sideEffect:!1},a.set(e,n)),n},"of"),t=new Set,c=[];for(const e of s.matchAll(IMPORT_NAMED)){const n=e[4];if(t.add(e.index),!r(n))continue;const i=l(n),p=!!e[1];e[2]&&i.names.push({imported:"default",typeOnly:p});for(const f of parseSpecifiers(e[3],p))i.names.push({imported:f.imported,typeOnly:f.typeOnly})}for(const e of s.matchAll(IMPORT_NAMESPACE)){const n=e[4];if(t.add(e.index),!r(n))continue;const i=l(n);e[2]&&i.names.push({imported:"default",typeOnly:!!e[1]}),c.push({local:e[3],specifier:n,typeOnly:!!e[1]})}for(const e of s.matchAll(IMPORT_EQUALS)){const n=e[3];t.add(e.index),r(n)&&(l(n),c.push({local:e[2],specifier:n,typeOnly:!!e[1]}))}for(const e of s.matchAll(IMPORT_DEFAULT)){const n=e[3];t.add(e.index),r(n)&&l(n).names.push({imported:"default",typeOnly:!!e[1]})}for(const e of s.matchAll(EXPORT_FROM)){const n=e[3];if(!r(n))continue;const i=l(n);for(const p of parseSpecifiers(e[2],!!e[1]))i.names.push({imported:p.imported,typeOnly:p.typeOnly})}for(const e of s.matchAll(EXPORT_STAR)){const n=e[3];if(!r(n)||e[1])continue;const i=l(n);i.wholeModule=!0,i.sideEffect=!0}for(const e of s.matchAll(IMPORT_BARE)){if(t.has(e.index))continue;const n=e[1];r(n)&&(l(n).sideEffect=!0)}for(const e of s.matchAll(DYNAMIC)){const n=e[1];if(!r(n))continue;const i=s.slice(Math.max(0,e.index-64),e.index);/\bimport\s+(?:type\s+)?[\w$]+\s*=\s*$/.test(i)||(l(n).wholeModule=!0)}for(const e of c){const n=l(e.specifier),i=new RegExp(String.raw`(?<![\w$.])${reEscape(e.local)}\s*(\.|\?\.|\[)?\s*([\w$]+)?`,"g");let p=0;for(const f of s.matchAll(i)){if(f[1]==="."||f[1]==="?."){f[2]&&n.names.push({imported:f[2],typeOnly:e.typeOnly});continue}p++,p>1&&(n.wholeModule=!0)}}for(const e of a.values()){const n=new Set;e.names=e.names.filter(p=>{const f=`${p.imported}:${p.typeOnly}`;return n.has(f)?!1:(n.add(f),!0)});const i=new Set(e.names.filter(p=>!p.typeOnly).map(p=>p.imported));e.names=e.names.filter(p=>!p.typeOnly||!i.has(p.imported))}return[...a.values()]}d(scanImports,"scanImports"),m(scanImports,"scanImports");function scanExports(o){const r=blankComments(o),s={values:new Set,types:new Set,reexports:new Map,stars:[],namespaces:new Map,valueImports:[]},a=new Map,l=new Set;for(const t of r.matchAll(IMPORT_NAMED)){const c=!!t[1];t[2]&&a.set(t[2],{specifier:t[4],name:"default",typeOnly:c});const e=parseSpecifiers(t[3],c);for(const n of e)a.set(n.local,{specifier:t[4],name:n.imported,typeOnly:n.typeOnly});!c&&(t[2]||e.some(n=>!n.typeOnly))&&l.add(t[4])}for(const t of r.matchAll(IMPORT_NAMESPACE))a.set(t[3],{specifier:t[4],name:"*",typeOnly:!!t[1]}),t[1]||l.add(t[4]);for(const t of r.matchAll(IMPORT_EQUALS))a.set(t[2],{specifier:t[3],name:"*",typeOnly:!!t[1]}),t[1]||l.add(t[3]);for(const t of r.matchAll(IMPORT_DEFAULT))a.set(t[2],{specifier:t[3],name:"default",typeOnly:!!t[1]}),t[1]||l.add(t[3]);for(const t of r.matchAll(IMPORT_BARE))l.add(t[1]);for(const t of r.matchAll(DYNAMIC))l.add(t[1]);s.valueImports=[...l];for(const t of r.matchAll(EXPORT_VALUE_DECL))s.values.add(t[1]);for(const t of r.matchAll(EXPORT_DESTRUCTURED))for(const c of t[1].split(",")){const e=/([\w$]+)\s*(?:=.*)?$/.exec(c.split(":").pop().trim())?.[1];e&&s.values.add(e)}for(const t of r.matchAll(EXPORT_NAMESPACE_DECL))s.values.add(t[1]);for(const t of r.matchAll(EXPORT_TYPE_DECL))s.types.add(t[1]);EXPORT_DEFAULT.test(r)&&s.values.add("default");for(const t of r.matchAll(EXPORT_FROM))for(const c of parseSpecifiers(t[2],!!t[1]))s.reexports.set(c.local,{specifier:t[3],name:c.imported,typeOnly:c.typeOnly});for(const t of r.matchAll(EXPORT_STAR))t[1]||(t[2]?s.namespaces.set(t[2],t[3]):s.stars.push(t[3]));for(const t of r.matchAll(EXPORT_LOCAL))for(const c of parseSpecifiers(t[2],!!t[1])){const e=a.get(c.imported);e&&e.name==="*"?s.namespaces.set(c.local,e.specifier):e?s.reexports.set(c.local,{specifier:e.specifier,name:e.name,typeOnly:c.typeOnly||e.typeOnly}):c.typeOnly?s.types.add(c.local):s.values.add(c.local)}return s}d(scanExports,"scanExports"),m(scanExports,"scanExports");

package/perf/workspace-libraries.d.ts

@@ -0,0 +1,52 @@
+/** An exact entry: `@org/contracts/audit` → `<abs>/shared/contracts/src/audit/index.ts`. */
+export interface LibraryEntry {
+    specifier: string;
+    entry: string;
+}
+/** A wildcard entry: `@org/platform/*` → `<abs>/shared/platform/src/` + `*`. */
+export interface LibraryWildcard {
+    /** The specifier before the `*` (`@org/platform/`). */
+    prefix: string;
+    /** The directory the `*` is resolved in, ending in a separator. */
+    dir: string;
+}
+export interface WorkspaceLibrary {
+    /** The root specifier — the barrel's import path. */
+    name: string;
+    /** Other specifiers that resolve to the same barrel (`@a/config` and `@b/config` → one file). */
+    aliases: string[];
+    /** The library's directory (where its `project.json` / `package.json` is); its modules are under it. */
+    root: string;
+    /** The barrel: the file the root specifier resolves to. */
+    rootEntry: string;
+    subpaths: LibraryEntry[];
+    wildcards: LibraryWildcard[];
+    /** Source files in the library (tests, stories and declarations excluded), capped at the walk's bound. */
+    files: number;
+}
+export interface DiscoverOptions {
+    /** The project's tsconfig (absolute). Default `<workspace>/tsconfig.base.json`. */
+    tsConfig?: string;
+    /** The most files counted per library. */
+    maxFilesPerLibrary?: number;
+}
+/**
+ * JSON with comments and trailing commas (tsconfig's dialect) → a value. Strings are kept verbatim, so a
+ * `"https://…"` is not taken for a comment. `undefined` when it does not parse.
+ */
+export declare function parseJsonc(text: string): unknown;
+/** The `paths` the project's tsconfig sees, absolute: the first config along the `extends` chain that defines them. */
+export declare function readTsconfigPaths(tsConfig: string): Map<string, string[]> | undefined;
+/** A target path as the compiler would resolve it to a file: itself, with an extension, or its index. */
+export declare function resolveSourceFile(target: string, exists?: (file: string) => boolean): string | undefined;
+/** Source files under `dir`, capped at `max` (a capped count is still "at least"). */
+export declare function countSourceFiles(dir: string, max: number): number;
+/**
+ * The libraries a project can import by alias. A library is an exact alias that is not itself a subpath of a
+ * shorter alias; its subpaths are the aliases (and package exports) under it.
+ */
+export declare function discoverWorkspaceLibraries(workspaceRoot: string, options?: DiscoverOptions): WorkspaceLibrary[];
+/** The library `file` belongs to — the one with the deepest root. */
+export declare function libraryOf(libraries: WorkspaceLibrary[], file: string): WorkspaceLibrary | undefined;
+/** Is `file` one of `lib`'s modules? */
+export declare function belongsTo(lib: WorkspaceLibrary, file: string): boolean;

package/perf/workspace-libraries.js

@@ -0,0 +1,2 @@
+"use strict";var g=Object.defineProperty;var l=(t,e)=>g(t,"name",{value:e,configurable:!0});var y=Object.defineProperty,u=l((t,e)=>y(t,"name",{value:e,configurable:!0}),"u");Object.defineProperty(exports,"__esModule",{value:!0}),exports.parseJsonc=parseJsonc,exports.readTsconfigPaths=readTsconfigPaths,exports.resolveSourceFile=resolveSourceFile,exports.countSourceFiles=countSourceFiles,exports.discoverWorkspaceLibraries=discoverWorkspaceLibraries,exports.libraryOf=libraryOf,exports.belongsTo=belongsTo;const tslib_1=require("tslib"),fs=tslib_1.__importStar(require("node:fs")),path=tslib_1.__importStar(require("node:path")),SOURCE_FILE=/\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs)$/,NOT_SOURCE=/(?:\.d\.[cm]?ts|\.(?:spec|test|stories|e2e-spec)\.[cm]?[jt]sx?)$/,SKIP_DIRS=new Set(["node_modules","dist","build","coverage",".git","__tests__","__mocks__","__fixtures__",".nx"]),RESOLVE_EXTENSIONS=["",".ts",".tsx",".mts",".cts",".js",".jsx",".mjs",".cjs"],INDEX_FILES=["index.ts","index.tsx","index.mts","index.js","index.mjs","index.cjs"];function parseJsonc(t){let e="",s=0;const o=t.length;for(;s<o;){const n=t[s];if(n==='"'){let r=s+1;for(;r<o&&t[r]!=='"';)t[r]==="\\"&&r++,r++;e+=t.slice(s,r+1),s=r+1;continue}if(n==="/"&&t[s+1]==="/"){const r=t.indexOf(`
+`,s);s=r===-1?o:r;continue}if(n==="/"&&t[s+1]==="*"){const r=t.indexOf("*/",s+2);s=r===-1?o:r+2;continue}e+=n,s++}try{return JSON.parse(e.replace(/,(\s*[}\]])/g,"$1"))}catch{return}}l(parseJsonc,"parseJsonc"),u(parseJsonc,"parseJsonc");function readJson(t){try{return parseJsonc(fs.readFileSync(t,"utf8"))}catch{return}}l(readJson,"readJson"),u(readJson,"readJson");function readTsconfigPaths(t){let e=t;const s=new Set;for(;e&&!s.has(e)&&s.size<8;){s.add(e);const o=readJson(e);if(!o)return;const n=o.compilerOptions?.paths;if(n&&typeof n=="object"){const f=path.resolve(path.dirname(e),o.compilerOptions?.baseUrl??"."),d=new Map;for(const[m,b]of Object.entries(n))Array.isArray(b)&&d.set(m,b.filter(i=>typeof i=="string").map(i=>path.resolve(f,i)));return d}const r=Array.isArray(o.extends)?o.extends[o.extends.length-1]:o.extends;e=r&&(r.startsWith(".")||path.isAbsolute(r))?path.resolve(path.dirname(e),r.endsWith(".json")?r:`${r}.json`):void 0}}l(readTsconfigPaths,"readTsconfigPaths"),u(readTsconfigPaths,"readTsconfigPaths");function resolveSourceFile(t,e=isFile){for(const o of RESOLVE_EXTENSIONS)if(o&&e(t+o))return t+o;if(e(t))return t;for(const o of INDEX_FILES){const n=path.join(t,o);if(e(n))return n}const s=/\.(c|m)?js$/.exec(t);if(s){const o=t.slice(0,-s[0].length);for(const n of[".ts",".tsx",".mts",".cts"])if(e(o+n))return o+n}}l(resolveSourceFile,"resolveSourceFile"),u(resolveSourceFile,"resolveSourceFile");function asDir(t){return t.endsWith(path.sep)?t:t+path.sep}l(asDir,"asDir"),u(asDir,"asDir");function isFile(t){try{return fs.statSync(t).isFile()}catch{return!1}}l(isFile,"isFile"),u(isFile,"isFile");function libraryRootOf(t,e){let s=path.dirname(t);for(;s.startsWith(e)&&s!==e;){if(isFile(path.join(s,"project.json"))||isFile(path.join(s,"package.json")))return s;const o=path.dirname(s);if(o===s)break;s=o}return path.dirname(t)}l(libraryRootOf,"libraryRootOf"),u(libraryRootOf,"libraryRootOf");function countSourceFiles(t,e){let s=0;const o=[t];for(;o.length&&s<e;){const n=o.pop();let r;try{r=fs.readdirSync(n,{withFileTypes:!0})}catch{continue}for(const f of r)if(f.isDirectory())!SKIP_DIRS.has(f.name)&&!f.name.startsWith(".")&&o.push(path.join(n,f.name));else if(f.isFile()&&SOURCE_FILE.test(f.name)&&!NOT_SOURCE.test(f.name)&&(s++,s>=e))break}return s}l(countSourceFiles,"countSourceFiles"),u(countSourceFiles,"countSourceFiles");function exportTarget(t,e){if(typeof t=="string")return resolveSourceFile(path.resolve(e,t));if(!t||typeof t!="object"||Array.isArray(t))return;const s=t,o=["source","development","require","import","node","default",...Object.keys(s)];for(const n of o){if(n==="types")continue;const r=exportTarget(s[n],e);if(r&&SOURCE_FILE.test(r)&&!/\.d\.[cm]?ts$/.test(r))return r}}l(exportTarget,"exportTarget"),u(exportTarget,"exportTarget");function packageEntries(t){const e=readJson(path.join(t.root,"package.json"))?.exports;if(!(!e||typeof e!="object"||Array.isArray(e)))for(const[s,o]of Object.entries(e)){if(!s.startsWith("./")||s==="./package.json")continue;const n=s.slice(2);if(n.includes("*")){const d=typeof o=="string"?o:void 0;d&&d.includes("*")&&n.endsWith("*")&&t.wildcards.push({prefix:`${t.name}/${n.slice(0,-1)}`,dir:asDir(path.resolve(t.root,d.slice(0,d.indexOf("*"))))});continue}const r=`${t.name}/${n}`;if(t.subpaths.some(d=>d.specifier===r))continue;const f=exportTarget(o,t.root);f&&t.subpaths.push({specifier:r,entry:f})}}l(packageEntries,"packageEntries"),u(packageEntries,"packageEntries");function discoverWorkspaceLibraries(t,e={}){const s=e.tsConfig??path.join(t,"tsconfig.base.json"),o=readTsconfigPaths(s)??(s.endsWith("tsconfig.base.json")?void 0:readTsconfigPaths(path.join(t,"tsconfig.base.json")));if(!o)return[];const n=new Map,r=[];for(const[i,p]of o){if(i.endsWith("/*")){const h=p.find(a=>a.endsWith("*"));h&&r.push({key:i.slice(0,-1),dir:asDir(h.slice(0,-1))});continue}if(!i.includes("*"))for(const h of p){const a=resolveSourceFile(h);if(a){n.set(i,a);break}}}const f=[...n.keys()],d=[];for(const[i,p]of n){if(p.includes(`${path.sep}node_modules${path.sep}`)||f.some(c=>c!==i&&i.startsWith(`${c}/`)))continue;const h=libraryRootOf(p,t),a={name:i,aliases:[],root:h,rootEntry:p,subpaths:f.filter(c=>c.startsWith(`${i}/`)).map(c=>({specifier:c,entry:n.get(c)})),wildcards:r.filter(c=>c.key.startsWith(`${i}/`)).map(c=>({prefix:c.key,dir:c.dir})),files:0};packageEntries(a),d.push(a)}const m=new Map;for(const i of d)m.set(i.rootEntry,[...m.get(i.rootEntry)??[],i]);const b=[];for(const i of m.values()){i.sort((a,c)=>c.subpaths.length+c.wildcards.length-(a.subpaths.length+a.wildcards.length)||a.name.length-c.name.length||a.name.localeCompare(c.name));const[p,...h]=i;for(const a of h)p.aliases.push(a.name),p.subpaths.push(...a.subpaths),p.wildcards.push(...a.wildcards);p.files=countSourceFiles(p.root,e.maxFilesPerLibrary??2e4),b.push(p)}return b}l(discoverWorkspaceLibraries,"discoverWorkspaceLibraries"),u(discoverWorkspaceLibraries,"discoverWorkspaceLibraries");function libraryOf(t,e){let s;for(const o of t)belongsTo(o,e)&&(!s||o.root.length>s.root.length)&&(s=o);return s}l(libraryOf,"libraryOf"),u(libraryOf,"libraryOf");function belongsTo(t,e){return e.startsWith(t.root+path.sep)&&!e.includes(`${path.sep}node_modules${path.sep}`)}l(belongsTo,"belongsTo"),u(belongsTo,"belongsTo");

package/pod-memory-events.d.ts

@@ -0,0 +1,71 @@
+import { type PodMemoryReport, type ReleasedGenerationReport, type RetainedGenerationReport } from './pod-memory';
+/** Who a pod is — stamped into every event's `raw`. */
+export interface PodIdentity {
+    /** The Nx project (`LENSMCP_PROJECT`) — what the lens attributes to. */
+    project: string;
+    /** The cluster service name (`SERVICE_NAME`) — what `lensmcp mem <svc>` takes. */
+    service: string;
+    /** The devserver's pod id (`Child#<pod>`). */
+    pod: number;
+    pid: number;
+    /** The pod-tree generation (`LENSMCP_POD_GENERATION`, a rolling recycle's). */
+    podGeneration: number;
+}
+/** Loose BaseEvent shape — cluster does not depend on `@lensmcp/protocol-types`. */
+export interface PodMemoryBusEvent {
+    id: string;
+    sessionId: string;
+    timestamp: number;
+    source: 'memory';
+    category: 'memory';
+    severity: 'info' | 'warning';
+    context: {
+        sessionId: string;
+        projectName: string;
+    };
+    fingerprint: string;
+    title: string;
+    message?: string;
+    raw: Record<string, unknown>;
+}
+/** One post-GC reading. */
+export declare function buildPodMemoryEvent(who: PodIdentity, r: PodMemoryReport, id?: () => string): PodMemoryBusEvent;
+/** A closed generation proven still in memory. */
+export declare function buildPodRetainedEvent(who: PodIdentity, r: RetainedGenerationReport, at: number, id?: () => string): PodMemoryBusEvent;
+/** The retraction: a generation reported retained is gone. Same bucket as the verdict it retracts. */
+export declare function buildPodReleasedEvent(who: PodIdentity, r: ReleasedGenerationReport, at: number, id?: () => string): PodMemoryBusEvent;
+/** How a pod process ended, for `pod-memory-exited`. */
+export interface PodExit {
+    code: number | null;
+    signal: string | null;
+}
+/**
+ * The pod process is gone: whatever the lens shows for it should go too. Readings only arrive on swaps and after
+ * bursts, so without this a recycled or crashed pod would sit in `memory://pods` beside its successor. The
+ * readings' bucket — it is one event per pod lifetime.
+ */
+export declare function buildPodExitedEvent(who: PodIdentity, exit: PodExit, at: number, id?: () => string): PodMemoryBusEvent;
+/** The flood guard and rotation every bus writer shares — node-instrumentation's, loaded lazily. */
+interface BusHygiene {
+    maybeRotateEventFile(file: string, addedBytes: number): void;
+    createEventFloodGuard(opts?: {
+        burst?: number;
+        perSec?: number;
+    }): {
+        admit(fp: string): {
+            ok: boolean;
+            suppressed: number;
+        };
+    };
+}
+/** Appends pod-memory events to the bus. */
+export interface PodMemoryPublisher {
+    /** `false` when the flood guard dropped it, or there is no bus to write to. */
+    publish(event: PodMemoryBusEvent): boolean;
+}
+/**
+ * A publisher for `eventFile` (the devserver's `LENSMCP_EVENT_FILE`, which the serve executor always sets).
+ * Without one there is no bus to write to — a devserver run by hand still logs its lines.
+ */
+export declare function createPodMemoryPublisher(eventFile: string | undefined, hygiene?: BusHygiene): PodMemoryPublisher;
+export {};

package/pod-memory-events.js

@@ -0,0 +1,2 @@
+"use strict";var u=Object.defineProperty;var i=(e,r)=>u(e,"name",{value:r,configurable:!0});var p=Object.defineProperty,n=i((e,r)=>p(e,"name",{value:r,configurable:!0}),"n");Object.defineProperty(exports,"__esModule",{value:!0}),exports.buildPodMemoryEvent=buildPodMemoryEvent,exports.buildPodRetainedEvent=buildPodRetainedEvent,exports.buildPodReleasedEvent=buildPodReleasedEvent,exports.buildPodExitedEvent=buildPodExitedEvent,exports.createPodMemoryPublisher=createPodMemoryPublisher;const tslib_1=require("tslib"),fs=tslib_1.__importStar(require("node:fs")),path=tslib_1.__importStar(require("node:path")),pod_memory_1=require("./pod-memory"),MB=1024*1024,mb=n(e=>Math.round(e/MB),"mb");let idCounter=0;function makeId(){return idCounter=(idCounter+1)%65535,`${Date.now().toString(36)}${idCounter.toString(36)}${Math.random().toString(36).slice(2,8)}`}i(makeId,"makeId"),n(makeId,"makeId");function envelope(e,r,o,t,d,s,a){const l="pending";return{id:a(),sessionId:l,timestamp:r,source:"memory",category:"memory",severity:o,context:{sessionId:l,projectName:e.project},fingerprint:t,title:d,raw:{...s,project:e.project,service:e.service,pod:e.pod,pid:e.pid,podGeneration:e.podGeneration}}}i(envelope,"envelope"),n(envelope,"envelope");function buildPodMemoryEvent(e,r,o=makeId){return envelope(e,r.at,"info",`pod-memory:${e.project}`,`${e.service} pod #${e.pod}: ${mb(r.live)} MB live after GC (${r.trigger}, generation ${r.gen})`,{kind:"pod-memory",...r},o)}i(buildPodMemoryEvent,"buildPodMemoryEvent"),n(buildPodMemoryEvent,"buildPodMemoryEvent");function buildPodRetainedEvent(e,r,o,t=makeId){const d=envelope(e,o,"warning",`pod-memory-retained:${e.project}`,`${e.service} pod #${e.pod}: generation ${r.gen} still in memory ${(0,pod_memory_1.ageLabel)(r.ageMs)} after close`,{kind:"pod-memory-retained",...r},t);return d.message=`Its app was closed ${(0,pod_memory_1.ageLabel)(r.ageMs)} ago, ${r.swapsSinceClose} swap(s) and ${r.gcs} full GC(s) since, and ${r.alive.join(", ")} ${r.alive.length===1?"is":"are"} still alive: something still points into it.`,d}i(buildPodRetainedEvent,"buildPodRetainedEvent"),n(buildPodRetainedEvent,"buildPodRetainedEvent");function buildPodReleasedEvent(e,r,o,t=makeId){return envelope(e,o,"info",`pod-memory-retained:${e.project}`,r.reason==="pod-exited"?`${e.service} pod #${e.pod}: generation ${r.gen} went with its pod`:`${e.service} pod #${e.pod}: generation ${r.gen} was collected after all`,{kind:"pod-memory-released",...r},t)}i(buildPodReleasedEvent,"buildPodReleasedEvent"),n(buildPodReleasedEvent,"buildPodReleasedEvent");function buildPodExitedEvent(e,r,o,t=makeId){return envelope(e,o,"info",`pod-memory:${e.project}`,`${e.service} pod #${e.pod} exited`,{kind:"pod-memory-exited",code:r.code,signal:r.signal},t)}i(buildPodExitedEvent,"buildPodExitedEvent"),n(buildPodExitedEvent,"buildPodExitedEvent");function createPodMemoryPublisher(e,r){if(!e)return{publish:n(()=>!1,"publish")};const o=r??(()=>{try{return require("@lensmcp/node-instrumentation")}catch{return}})(),t=o?.createEventFloodGuard({burst:30,perSec:5});let d=!1;return{publish(s){const a=t?.admit(s.fingerprint)??{ok:!0,suppressed:0};if(!a.ok)return!1;const l=JSON.stringify(a.suppressed>0?{...s,raw:{...s.raw,floodSuppressed:a.suppressed}}:s)+`
+`;try{return d||(fs.mkdirSync(path.dirname(e),{recursive:!0}),d=!0),o?.maybeRotateEventFile(e,l.length),fs.appendFileSync(e,l),!0}catch{return d=!1,!1}}}}i(createPodMemoryPublisher,"createPodMemoryPublisher"),n(createPodMemoryPublisher,"createPodMemoryPublisher");

package/pod-memory.d.ts

@@ -0,0 +1,258 @@
+export interface PodMemoryPolicy {
+    /** `LENSMCP_POD_GC=0` turns off the scheduled collections, the idle one and the reports they make. */
+    enabled: boolean;
+    /** When to collect after a swap, from the swap — in addition to the collection once it has settled. */
+    scheduleMs: number[];
+    /** Collect once the pod has been quiet this long after traffic or a swap. `0` = off. */
+    idleMs: number;
+    /** …at most once per this long. */
+    idleEveryMs: number;
+    /** How long a closed generation may stay in memory before it is called retained. */
+    retainedAfterMs: number;
+    /** How quiet the pod must be before a swap counts as settled. */
+    settleMs: number;
+}
+/** Full GCs a closed generation must survive before it is called retained: one could have raced its last timer. */
+export declare const RETAINED_MIN_GCS = 2;
+/**
+ * - `LENSMCP_POD_GC` — `0`/`false`/`off`/`no` disables the scheduled and idle collections (and their reports).
+ * - `LENSMCP_POD_GC_SCHEDULE_MS` — default `30000,120000,300000`: the collections after a swap, by delay from it.
+ * - `LENSMCP_POD_GC_IDLE_MS` — default `60000`. `0` disables the idle collection.
+ * - `LENSMCP_POD_GC_IDLE_EVERY_MS` — default `300000`.
+ * - `LENSMCP_POD_RETAINED_AFTER_MS` — default `300000` (5 min).
+ * - `LENSMCP_POD_GC_SETTLE_MS` — default `2000`.
+ */
+export declare function podMemoryPolicy(env?: NodeJS.ProcessEnv): PodMemoryPolicy;
+/** What made the pod collect. `swap+<delay>` names a scheduled run by its delay from the swap. */
+export type PodMemoryTrigger = 'boot' | 'swap-settled' | `swap+${string}` | 'idle' | 'retention-check';
+/** One post-GC reading. MIRROR of `PodMemoryReportRaw` in `@lensmcp/protocol-types` (cluster does not depend on it). */
+export interface PodMemoryReport {
+    trigger: PodMemoryTrigger;
+    at: number;
+    /** The app generation serving now (1 = the one the pod booted with). */
+    gen: number;
+    /** Hot swaps since boot. */
+    swaps: number;
+    /** Heap in use after a full GC. */
+    live: number;
+    /** Heap in use just before it — garbage included. */
+    used: number;
+    /** Heap V8 has reserved after the GC (`heapTotal`). */
+    reserved: number;
+    rss: number;
+    external: number;
+    /** The young generation's reserved size. */
+    youngGen: number;
+    /** V8's heap limit. */
+    limit: number;
+    /** Live heap right after the first app was built — what one generation of this service weighs. */
+    baseline?: number;
+    /** How long the collection paused the pod. */
+    gcMs: number;
+    /** The generation this pod's latest swap replaced. */
+    previousGen?: number;
+    /** Is it still in memory? `null` when there is none (no swap yet). */
+    previousAlive: boolean | null;
+    /** Closed generations still in memory, whatever their age. */
+    closedAlive: number;
+    /** …of them, the ones past the retained bound. */
+    retained: number;
+    /** Live `NestContainer` instances, when they can be counted. */
+    containers?: number;
+    /** Whether this process maps stack traces through source maps (`--enable-source-maps`) — what it costs. */
+    sourceMaps: boolean;
+}
+/** A closed generation proven still in memory. MIRROR of `PodMemoryRetainedRaw`. */
+export interface RetainedGenerationReport {
+    gen: number;
+    closedAt: number;
+    ageMs: number;
+    /** Swaps since this generation's app was closed. */
+    swapsSinceClose: number;
+    /** Full GCs it survived. */
+    gcs: number;
+    /** Which of its registered objects are still alive: `module`, `app`, `nestApp`, `container`, `rootModule`. */
+    alive: string[];
+    /** Live instances of the classes a swapped app leaks through, where they could be counted. */
+    counts?: Record<string, number>;
+    /** Heap in use after the GC that proved it. */
+    live: number;
+}
+/** A retained generation collected after all, or gone with its pod. MIRROR of `PodMemoryReleasedRaw`. */
+export interface ReleasedGenerationReport {
+    gen: number;
+    closedAt: number;
+    ageMs: number;
+    reason: 'collected' | 'pod-exited';
+}
+/** Report message: one post-GC reading. */
+export interface PodMemoryReportMessage {
+    type: 'pod-memory';
+    report: PodMemoryReport;
+}
+/** Report message: a closed generation is proven retained. */
+export interface PodMemoryRetainedMessage {
+    type: 'pod-memory-retained';
+    retained: RetainedGenerationReport;
+}
+/** Report message: a generation that was reported retained is gone. */
+export interface PodMemoryReleasedMessage {
+    type: 'pod-memory-released';
+    released: ReleasedGenerationReport;
+}
+export type PodMemoryMessage = PodMemoryReportMessage | PodMemoryRetainedMessage | PodMemoryReleasedMessage;
+/**
+ * A full, synchronous GC. V8 only hands out `gc` to a context created after the flag is set, hence the fresh
+ * context. `false` where it will not (the reading is then simply uncollected).
+ */
+export declare function fullGc(): boolean;
+/**
+ * Live instances of `ctor` — a full GC and a walk of the heap — or `undefined` where Node cannot count.
+ *
+ * `v8.queryObjects` is experimental and says so with a process warning the first time; a pod's output is the
+ * developer's console, and that line would be noise the lens put there. The warning is dropped for this call
+ * only (Node emits it once per process, so later calls have nothing to drop).
+ */
+export declare function countLiveInstances(ctor: unknown): number | undefined;
+/** Counts instances of the shared classes a bundle loaded, by name. */
+export interface LiveObjectCounter {
+    /** Live `NestContainer` instances, or `undefined` when the bundle has no Nest or Node cannot count. */
+    containers(): number | undefined;
+    /** Every class it can count — one full GC each, so only when something is being reported. */
+    all(): Record<string, number> | undefined;
+}
+/**
+ * Resolve each class from the BUNDLE's directory and take it out of the module cache — never `require` it:
+ * a pod that does not use TypeORM must not load TypeORM to find out. Externals are shared by every generation
+ * (webpack-node-externals), so one class counts the instances every generation made.
+ */
+export declare function createLiveObjectCounter(bundlePath: string, cache?: Record<string, {
+    exports?: unknown;
+} | undefined>): LiveObjectCounter;
+/** What a generation is made of, as far as this process can see. Every one is held WEAKLY once registered. */
+export interface GenerationTargets {
+    /** The bundle's CJS Module — every closure the bundle made reaches it through `require`'s scope. */
+    module?: object;
+    /** What `createChildApp()` returned. */
+    app?: object;
+    /** The Nest application, when the app exposes it. */
+    nestApp?: object;
+    /** Its DI container. */
+    container?: object;
+    /** Its root module class. */
+    rootModule?: object;
+}
+/**
+ * The marker a heap snapshot finds a closed generation by: its class name, its `label` string, and a WeakRef
+ * per target. Weak on purpose — the marker must never be the reason a generation is alive — and named so the
+ * snapshot analyser (`lensmcp mem <svc> --snapshot --analyze`) can find it and walk the shortest path from the
+ * GC roots to whatever is still alive.
+ */
+export declare class LensmcpClosedGeneration {
+    readonly gen: number;
+    readonly label: string;
+    readonly refs: Record<string, WeakRef<object>>;
+    constructor(gen: number, targets: GenerationTargets);
+}
+/** One closed generation, as the tracker sees it. */
+export interface ClosedGenerationView {
+    gen: number;
+    closedAt: number;
+    swapsAtClose: number;
+    /** Full GCs since its close. */
+    gcs: number;
+    /** Names of the targets not yet collected. */
+    alive: string[];
+    /** When it was reported retained, if it was. */
+    reportedAt?: number;
+}
+/** Callbacks the tracker reports through. */
+export interface GenerationTrackerOptions {
+    /** A closed generation's last registered target was collected. `reported` = it had been called retained. */
+    onFreed?: (view: ClosedGenerationView, reported: boolean) => void;
+    now?: () => number;
+}
+/**
+ * Which closed generations are still in memory, by FinalizationRegistry — never by holding them.
+ */
+export declare class GenerationTracker {
+    private readonly opts;
+    private readonly closed;
+    /** Generations proven gone, most recent last (bounded) — so "is the previous one gone?" has an answer. */
+    private readonly freed;
+    private readonly registry;
+    private readonly now;
+    constructor(opts?: GenerationTrackerOptions);
+    /** A generation's app has been closed: from here on, everything it was made of should go. */
+    close(gen: number, swapsAtClose: number, targets: GenerationTargets): void;
+    /** A full GC ran: every closed generation still here survived one more. */
+    noteGc(): void;
+    /** `true` still in memory, `false` proven gone, `undefined` never closed here. */
+    isAlive(gen: number): boolean | undefined;
+    views(): ClosedGenerationView[];
+    /** Closed generations past the bound and through enough GCs, not yet reported. */
+    dueForReport(retainedAfterMs: number, at?: number): ClosedGenerationView[];
+    /** How many closed generations are past the bound (reported or about to be). */
+    retainedCount(retainedAfterMs: number, at?: number): number;
+    markReported(gen: number, at?: number): void;
+    /** The oldest generation proven retained — what the recycle rule weighs. */
+    oldestRetained(retainedAfterMs: number, at?: number): ClosedGenerationView | undefined;
+    /** The markers, for a heap snapshot to find (it reads them; nothing here does). */
+    markers(): LensmcpClosedGeneration[];
+    /** The pod is going away: whatever was reported retained goes with it. */
+    forgetAll(): ClosedGenerationView[];
+    private collected;
+    private drop;
+    private markFreed;
+    private view;
+}
+/** What the monitor needs to know about the pod it runs in. */
+export interface PodMemoryHostState {
+    /** The generation serving now. */
+    gen: number;
+    swaps: number;
+    baseline?: number;
+    /** A swap is running or queued, or a previous app is still closing. */
+    busy: boolean;
+    /** The last moment a swap started or ended, or a previous app finished closing. */
+    lastBusyAt: number;
+}
+/** The pod the monitor runs in. */
+export interface PodMemoryHost {
+    policy: PodMemoryPolicy;
+    state(): PodMemoryHostState;
+    send(message: PodMemoryMessage): void;
+    counter?: LiveObjectCounter;
+    /** A generation was just reported retained — the recycle rule's cue. */
+    onRetained?(oldest: ClosedGenerationView): void;
+    now?: () => number;
+}
+/** Drives the collections and the reports. One per pod. */
+export interface PodMemoryMonitor {
+    readonly tracker: GenerationTracker;
+    /** The pod has built its first app. Measures and returns the boot baseline. */
+    booted(): Promise<PodMemoryReport>;
+    /** A swap replaced generation `previousGen`: run the post-swap schedule (a newer swap restarts it). */
+    swapped(previousGen: number | undefined, previousClosed: () => boolean): void;
+    /** A generation's app was closed. */
+    closed(gen: number, swaps: number, targets: GenerationTargets): void;
+    /** Request traffic, for the idle collection. */
+    activity(): void;
+    /** Collect and report now. Serialised: concurrent callers share one queue. */
+    measure(trigger: PodMemoryTrigger): Promise<PodMemoryReport>;
+    /** For the recycle rule. */
+    oldestRetained(): ClosedGenerationView | undefined;
+    /** The pod is exiting. */
+    stop(): void;
+}
+/** `30000` → `30s`, `120000` → `2m`. */
+export declare function delayLabel(ms: number): string;
+export declare function createPodMemoryMonitor(host: PodMemoryHost): PodMemoryMonitor;
+/** `45000` → `45s`, `660000` → `11 min`. */
+export declare function ageLabel(ms: number): string;
+/** The one log line the parent prints per report. */
+export declare function describePodMemory(who: string, r: PodMemoryReport): string;
+/** The parent's line for a generation proven retained. */
+export declare function describeRetained(who: string, service: string, r: RetainedGenerationReport): string;
+/** The parent's line for a retained generation that went. */
+export declare function describeReleased(who: string, service: string, r: ReleasedGenerationReport): string;