@tslite/analysis 0.1.0

package/dist/index.cjs

@@ -0,0 +1 @@
+'use strict';var core=require('@tslite/core');var I=new Set,T=(...e)=>new Set(e),m={atoms:new Set,vars:new Set},M=(...e)=>({atoms:new Set(e),vars:new Set}),C=e=>({atoms:new Set,vars:new Set([e])}),R=e=>{let t=new Set,o=new Set;for(let n of e){for(let r of n.atoms)t.add(r);for(let r of n.vars)o.add(r);}return {atoms:t,vars:o}},Y=(e,t)=>{let o=new Set(e.atoms),n=new Set;for(let r of e.vars){let i=t.get(r);if(i){for(let s of i.atoms)o.add(s);for(let s of i.vars)n.add(s);}else n.add(r);}return {atoms:o,vars:n}},U={params:[],latent:m},V=(e,t)=>{let o=new Map;return e.params.forEach((n,r)=>{let i=t[r];n&&i&&o.set(n,i);}),Y(e.latent,o)},O=e=>new Set(e.atoms),ae=e=>{let t=new Set;for(let o of e)for(let n of o)t.add(n);return t},fe=(e,t)=>{for(let o of e)if(!t.has(o))return  false;return  true},j=(e,t)=>[...e].filter(o=>!t.has(o));var de=e=>{let t={};for(let[o,n]of Object.entries(e))t[o]=new Set(n);return t},pe=(e,t,o=[])=>{let n=new Array(t).fill(null),r="\u03B5";return n[e]=r,{params:n,latent:{atoms:new Set(o),vars:new Set([r])}}},L={nodeEffects:{ForStatement:"loops",ForInStatement:"loops",ForOfStatement:"loops",WhileStatement:"loops",DoWhileStatement:"loops",AssignmentExpression:"mutates",UpdateExpression:"mutates"}},ye=new Set(["ArrowFunctionExpression","FunctionExpression","FunctionDeclaration"]),h=e=>ye.has(e.type),p=e=>e,ue=e=>p(e).body,me=e=>p(e).params??[],S=e=>e&&e.type==="Identifier"?p(e).name:void 0,Ee=e=>{let t=p(e).object,o=p(e).property,n=S(t);if(!n)return null;let r=p(e).computed?void 0:S(o);return {path:r?`${n}.${r}`:n,root:n}},ge=e=>typeof e=="object"&&e!==null&&"latent"in e,$=(e,t)=>ge(e)?V(e,t):{atoms:new Set(e),vars:new Set},J=(e,t)=>{let o=0;return {rules:e,env:t,schemeOf:new Map,active:new Set,fresh:()=>`\u03B5${o++}`}},Q=e=>{let t={};for(let[o,n]of Object.entries(e))t[o]={kind:"capability",decl:n};return core.rootScope(t)};function x(e,t,o){let n=o.schemeOf.get(e);if(n)return n;if(o.active.has(e))return U;o.active.add(e);let r=me(e),i=r.map(v=>v.type==="Identifier"?o.fresh():null),s={};r.forEach((v,D)=>{let K=S(v);K&&i[D]&&(s[K]={kind:"param",var:i[D]});});let a=core.childScope(t,s),f=ue(e),u=f?E(f,a,o):m,d={params:i,latent:u};return o.active.delete(e),o.schemeOf.set(e,d),d}function _(e,t,o){x(e,t,o);}function E(e,t,o){let n=o.rules.nodeEffects[e.type],r=n?M(n):m;if(h(e))return _(e,t,o),r;if(e.type==="CallExpression"||e.type==="NewExpression")return R([r,we(e,t,o)]);if(e.type==="BlockStatement"||e.type==="Program"){let s=p(e).body??[];return R([r,ve(s,t,o)])}let i=[r];return core.forEachChild(e,s=>i.push(E(s,t,o))),R(i)}function ve(e,t,o){let n=t,r={};for(let s of e)if(s.type==="FunctionDeclaration"){let a=S(p(s).id);a&&(r[a]={kind:"fn",node:s,scope:n});}Object.keys(r).length&&(n=core.childScope(n,r));for(let s in r)r[s].kind==="fn"&&(r[s].scope=n);for(let s in r){let a=r[s];a.kind==="fn"&&_(a.node,n,o);}let i=[];for(let s of e)if(s.type!=="FunctionDeclaration"){if(s.type==="VariableDeclaration"){let a=p(s).declarations??[];for(let f of a){let u=p(f).id,d=p(f).init,v=S(u);if(v&&d&&h(d)){let D=core.childScope(n,{[v]:{kind:"fn",node:d,scope:n}});_(d,D,o),n=D;}else d&&i.push(E(d,n,o)),v&&(n=core.childScope(n,{[v]:{kind:"value"}}));}continue}i.push(E(s,n,o));}return R(i)}function we(e,t,o){let n=p(e).callee,r=p(e).arguments??[],i=r.map(f=>h(f)?m:E(f,t,o)),s=r.map(f=>Re(f,t,o)),a=Se(n,s,t,o);return R([a,...i])}function Re(e,t,o){if(h(e))return x(e,t,o).latent;if(e.type==="Identifier"){let n=core.lookup(t,S(e));if(!n)return null;if(n.kind==="fn")return x(n.node,n.scope,o).latent;if(n.kind==="param")return C(n.var);if(n.kind==="capability")return $(n.decl,[])}return null}function Se(e,t,o,n){if(!e)return m;if(e.type==="Identifier"){let r=core.lookup(o,S(e));if(!r)return m;switch(r.kind){case "capability":return $(r.decl,t);case "fn":return V(x(r.node,r.scope,n),t);case "param":return C(r.var);case "value":return m}}if(h(e))return V(x(e,o,n),t);if(e.type==="MemberExpression"){let r=Ee(e),i=r&&(n.env[r.path]??n.env[r.root]);if(i)return $(i,t)}return E(e,o,n)}function W(e,t={}){let o=t.env??{},n=J(t.rules??L,o),r=Q(o);if(t.root&&t.root!==e){E(t.root,r,n);let i=n.schemeOf.get(e);if(i)return O(i.latent)}return h(e)?O(x(e,r,n).latent):O(E(e,r,n))}function z(e,t={}){let o=t.env??{},n=J(t.rules??L,o);E(e,Q(o),n);let r=new Map;for(let[i,s]of n.schemeOf)r.set(i,O(s.latent));return r}var X=e=>e.size?`{ ${[...e].sort().join(", ")} }`:"pure";function G(e,t,o){let n=W(e,o),r=j(n,t);return r.length===0?[]:[{node:e,declared:t,inferred:n,excess:r,message:`Effect contract violated: declared ${X(t)} but infers ${X(n)} \u2014 not allowed: ${r.join(", ")}.`}]}function Z(e){switch(e){case "pure":return I;case "io":return T("io");case "any":return null}}function Be(e,t,o){let n=Z(t);return n===null?[]:G(e,n,o)}var b=e=>e,B=e=>e&&e.type==="Identifier"?b(e).name:void 0,N=(e,t)=>b(e)[t],Ne=new Set(["ArrowFunctionExpression","FunctionExpression","FunctionDeclaration"]),F=e=>Ne.has(e.type);function Oe(e){if(!e)return null;if(e.type==="Identifier"){let t=B(e);return {path:t,root:t}}if(e.type==="MemberExpression"){let t=b(e).object,o=b(e).property,n=b(e).computed,r=B(t);if(!r)return null;let i=n?void 0:B(o);return {path:i?`${r}.${i}`:r,root:r}}return null}function te(e){let{categories:t,matrix:o}=e,n=o.defaultPolicy??"allow",r=s=>t[s.path]??t[s.root],i=(s,a)=>o.rules[s]?.[a]??n;return (s,a)=>{if(!a)return null;let f=t[a];if(f===void 0)return null;let u=Oe(N(s,"callee"));if(!u)return null;let d=r(u);return d===void 0||i(f,d)!=="deny"?null:{call:s,from:a,to:u.path,fromCategory:f,toCategory:d,message:`Policy violated: ${f} '${a}' must not call ${d} '${u.path}' (${f} \u2192 ${d} is deny).`}}}var oe=e=>e.type==="CallExpression"||e.type==="NewExpression";function xe(e,t){let o=te(t),n=[],r=(i,s)=>{if(oe(i)){let a=o(i,s);a&&n.push(a);}if(i.type==="VariableDeclaration"){for(let a of b(i).declarations??[]){let f=N(a,"init");if(!f)continue;let u=F(f)?B(N(a,"id"))??s:s;r(f,u);}return}if(i.type==="FunctionDeclaration"){let a=B(N(i,"id"))??s;core.forEachChild(i,f=>r(f,a));return}core.forEachChild(i,a=>r(a,s));};return r(e,null),n}function ne(e){let t=te(e),o=new Map,n=[],r=()=>n.length?n[n.length-1]:null,i=null;return {enter(s){if(s.type==="VariableDeclarator"){let a=N(s,"init"),f=B(N(s,"id"));a&&F(a)&&f&&(i={name:f,fn:a});}if(F(s)){let a=i&&i.fn===s?i.name:s.type==="FunctionDeclaration"?B(N(s,"id"))??r():r();n.push(a),i=null;}if(oe(s)){let a=t(s,r());a&&o.set(s,a);}},exit(s){F(s)&&n.pop();},result:()=>o}}var w=e=>e,be=e=>e&&e.type==="Identifier"?w(e).name:void 0,c=(e,t)=>w(e)[t],g=(e,t)=>w(e)[t]??[];function y(e,t){if(e)switch(e.type){case "Identifier":t.add(w(e).name);return;case "AssignmentPattern":y(c(e,"left"),t);return;case "RestElement":y(c(e,"argument"),t);return;case "ArrayPattern":for(let o of g(e,"elements"))y(o,t);return;case "ObjectPattern":for(let o of g(e,"properties"))o.type==="RestElement"?y(c(o,"argument"),t):y(c(o,"value"),t);return}}function ke(e){let t=new Set;for(let o of e)if(o.type==="VariableDeclaration")for(let n of g(o,"declarations"))y(c(n,"id"),t);else if(o.type==="FunctionDeclaration"){let n=be(c(o,"id"));n&&t.add(n);}return t}var l=(e,t)=>{for(let o of t)e.add(o);},k=(e,t)=>{for(let o of t)e.delete(o);},De=new Set,re=e=>new Set(e);function H(e,t){let o=new Set;switch(e.type){case "Identifier":o.add(w(e).name);break;case "MemberExpression":{l(o,t(c(e,"object"))),w(e).computed&&l(o,t(c(e,"property")));break}case "Property":{w(e).computed&&l(o,t(c(e,"key"))),l(o,t(c(e,"value")));break}case "ArrowFunctionExpression":case "FunctionExpression":case "FunctionDeclaration":{let n=g(e,"params"),r=new Set;for(let i of n)y(i,r),i.type==="AssignmentPattern"&&l(o,t(c(i,"right")));l(o,t(c(e,"body"))),k(o,r);break}case "BlockStatement":case "Program":{let n=g(e,"body");for(let r of n)l(o,t(r));k(o,ke(n));break}case "VariableDeclarator":{l(o,t(c(e,"init")));let n=c(e,"id");n&&n.type!=="Identifier"&&A(n,o,t);break}case "CatchClause":{let n=new Set;y(c(e,"param"),n),l(o,t(c(e,"body"))),k(o,n);break}case "LabeledStatement":l(o,t(c(e,"body")));break;case "BreakStatement":case "ContinueStatement":break;case "ForInStatement":case "ForOfStatement":{let n=c(e,"left");l(o,t(c(e,"right")));let r=new Set;if(n.type==="VariableDeclaration")for(let s of g(n,"declarations"))y(c(s,"id"),r);else y(n,r);let i=re(t(c(e,"body")));k(i,r),l(o,i);break}case "ForStatement":{let n=c(e,"init"),r=new Set;if(n){if(n.type==="VariableDeclaration")for(let i of g(n,"declarations"))y(c(i,"id"),r);l(o,t(n));}for(let i of ["test","update","body"]){let s=re(t(c(e,i)));k(s,r),l(o,s);}break}default:core.forEachChild(e,n=>l(o,t(n)));break}return o}function se(e,t={}){let o=new Map,n=new Set(t.globals??[]),r=i=>{if(!i)return De;let s=H(i,r);return k(s,n),o.set(i,s),s};return r(e),o}function A(e,t,o){if(e.type==="AssignmentPattern")l(t,o(c(e,"right"))),A(c(e,"left"),t,o);else if(e.type==="ArrayPattern")for(let n of g(e,"elements"))n&&A(n,t,o);else if(e.type==="ObjectPattern")for(let n of g(e,"properties")){w(n).computed&&l(t,o(c(n,"key")));let r=c(n,"value")??c(n,"argument");r&&A(r,t,o);}}function Ve(e,t){return se(e,t).get(e)??new Set}function Pe(e,t){return {root:e,diagnostics:t.diagnostics,typeOf:o=>t.overlay.get(o)?.type,scopeOf:o=>t.overlay.get(o)?.scope}}function Fe(e,t){let o=new Map,n={tree:e,read:s=>o.get(s.name)},r=t.filter(s=>!!s.visitor),i=t.filter(s=>!s.visitor&&s.run);if(r.length){let s=a=>{for(let f of r)f.visitor.enter?.(a,n);core.forEachChild(a,s);for(let f=r.length-1;f>=0;f--)r[f].visitor.exit?.(a,n);};s(e.root);for(let a of r)o.set(a.name,a.visitor.result());}for(let s of i)o.set(s.name,s.run(n));return o}var ie=new Set,Ae=(e,t)=>({name:"effects",run:o=>z(o.tree.root,{env:e,rules:t})}),Ie=e=>({name:"deps",visitor:(()=>{let t=new Set(e?.globals??[]),o=new Map;return {exit(n){let r=H(n,i=>i?o.get(i)??ie:ie);for(let i of t)r.delete(i);o.set(n,r);},result:()=>o}})()}),Te=e=>({name:"policies",visitor:ne(e)});exports.DEFAULT_RULES=L;exports.PURE=I;exports.PURE_ROW=m;exports.PURE_SCHEME=U;exports.analyze=Fe;exports.checkEffectPolicy=Be;exports.checkEffects=G;exports.checkPolicies=xe;exports.deps=se;exports.depsOverlay=Ie;exports.effect=T;exports.effectCeiling=Z;exports.effectEnv=de;exports.effectsOverlay=Ae;exports.effectsOverlayOf=z;exports.excess=j;exports.forwardEffect=pe;exports.freeVars=Ve;exports.groundRow=O;exports.inferEffects=W;exports.instantiateScheme=V;exports.join=ae;exports.joinRows=R;exports.policiesOverlay=Te;exports.rowOf=M;exports.rowOfVar=C;exports.substituteRow=Y;exports.typedTreeOf=Pe;exports.within=fe;

package/dist/index.d.cts

@@ -0,0 +1,265 @@
+import { BaseNode } from '@tslite/core';
+import { Effects } from '@tslite/capability';
+import { Diagnostic, Schema, Scope, CheckResult } from '@tslite/checker';
+
+/** Um átomo de efeito (vocabulário da app): `io`, `loops`, `time`, … */
+type EffectAtom = string;
+/** Uma variável de efeito (`ε`) — o "genérico" do eixo de efeitos. */
+type EffectVar = string;
+/** O efeito concreto de algo: o conjunto de átomos. `∅` = `pure`. */
+type Effect = ReadonlySet<EffectAtom>;
+/** O efeito vazio (bottom do lattice) — puro. */
+declare const PURE: Effect;
+/** Constrói um efeito concreto a partir de átomos. */
+declare const effect: (...atoms: EffectAtom[]) => Effect;
+/**
+ * Uma **linha de efeito**: átomos concretos `⊔` variáveis de efeito ainda não
+ * resolvidas. `pure` é `{ atoms: ∅, vars: ∅ }`.
+ */
+interface EffectRow {
+    readonly atoms: ReadonlySet<EffectAtom>;
+    readonly vars: ReadonlySet<EffectVar>;
+}
+/** A linha pura (bottom). */
+declare const PURE_ROW: EffectRow;
+/** Uma linha só de átomos concretos. */
+declare const rowOf: (...atoms: EffectAtom[]) => EffectRow;
+/** Uma linha que é só uma variável de efeito (`ε`). */
+declare const rowOfVar: (v: EffectVar) => EffectRow;
+/** Junção (`⊔`) de linhas — união de átomos e de variáveis. */
+declare const joinRows: (rows: Iterable<EffectRow>) => EffectRow;
+/**
+ * Substitui as variáveis de `row` pelas linhas ligadas em `bindings` (unindo
+ * seus átomos/vars); variáveis sem ligação permanecem livres. É o `substitute`
+ * do eixo de efeitos.
+ */
+declare const substituteRow: (row: EffectRow, bindings: ReadonlyMap<EffectVar, EffectRow>) => EffectRow;
+/**
+ * O contrato de efeito de uma função: para cada parâmetro, a `ε` que ele
+ * introduz se for chamado dentro do corpo (`null` caso contrário), e a linha
+ * **latente** — o que o corpo faz quando a função é chamada (podendo mencionar
+ * essas `ε`). É o análogo de uma assinatura genérica `map<T,U,ε>`.
+ */
+interface EffectScheme {
+    readonly params: readonly (EffectVar | null)[];
+    readonly latent: EffectRow;
+}
+/** Um scheme puro sem parâmetros-efeito. */
+declare const PURE_SCHEME: EffectScheme;
+/**
+ * Instancia um scheme no call site: liga cada `ε` de parâmetro à linha de efeito
+ * do argumento correspondente (quando o argumento é "chamável") e devolve a
+ * linha latente já substituída. É o `instantiate` do eixo de efeitos — o mesmo
+ * padrão do checker, sobre linhas em vez de tipos.
+ */
+declare const instantiateScheme: (scheme: EffectScheme, argRows: readonly (EffectRow | null)[]) => EffectRow;
+/**
+ * "Aterra" uma linha no seu efeito **concreto**: descarta as variáveis livres
+ * (um higher-order não-instanciado é puro *em si*). É a ponte da linha para o
+ * `Effect` que os contratos comparam.
+ */
+declare const groundRow: (row: EffectRow) => Effect;
+/** Junção (`⊔`) de efeitos concretos — a união. */
+declare const join: (effects: Iterable<Effect>) => Effect;
+/** `inferido ⊆ declarado`? (o inferido cabe no contrato). */
+declare const within: (inferred: Effect, declared: Effect) => boolean;
+/** Os átomos de `inferred` que `declared` **não** permite. */
+declare const excess: (inferred: Effect, declared: Effect) => EffectAtom[];
+
+/** A declaração de efeito de uma capability da DI: concreta ou higher-order. */
+type EffectDecl = Effect | EffectScheme;
+/** Efeitos declarados por nome — a borda DI (capabilities/funções externas). */
+type EffectEnv = Readonly<Record<string, EffectDecl>>;
+/** Açúcar: monta um `EffectEnv` concreto a partir de listas de átomos. */
+declare const effectEnv: (decls: Readonly<Record<string, readonly string[]>>) => EffectEnv;
+/**
+ * Açúcar para uma capability **higher-order** cujo efeito é o do seu parâmetro
+ * de índice `paramIndex` (ex.: `map`/`filter`/`forEach` herdam o efeito do
+ * callback). `extra` são átomos que a própria capability sempre faz.
+ */
+declare const forwardEffect: (paramIndex: number, arity: number, extra?: readonly string[]) => EffectScheme;
+/** Quais nós produzem qual efeito **direto** (extensível pela app). */
+interface EffectRules {
+    readonly nodeEffects: Readonly<Record<string, string>>;
+}
+/** Regras padrão (capability imperativa, D30): loops → `loops`; mutação → `mutates`. */
+declare const DEFAULT_RULES: EffectRules;
+interface InferOptions {
+    /** Efeitos declarados das capabilities/funções chamadas (DI). */
+    readonly env?: EffectEnv;
+    /** Regras de efeito direto por tipo de nó. */
+    readonly rules?: EffectRules;
+    /**
+     * A raiz, para resolver chamadas a **funções irmãs/externas** ao `node`
+     * (`const g = …; const f = () => g()`). Sem ela, só nested + params + DI.
+     */
+    readonly root?: BaseNode;
+}
+/**
+ * Infere o efeito **concreto** de executar `node` (variáveis de efeito livres,
+ * de higher-order não instanciado, são aterradas — um `map` *em si* é puro).
+ */
+declare function inferEffects(node: BaseNode, opts?: InferOptions): Effect;
+/**
+ * O **overlay** de efeitos: o efeito concreto de **cada função** sob `root`, numa
+ * travessia (schemes memoizados). É o que a camada de overlays (`effectsOverlay`)
+ * consome para devolver um `Map<nó-de-função, Effect>`.
+ */
+declare function effectsOverlayOf(root: BaseNode, opts?: {
+    readonly env?: EffectEnv;
+    readonly rules?: EffectRules;
+}): Map<BaseNode, Effect>;
+
+/** Uma violação de contrato de efeito (erro como dado). */
+interface EffectViolation {
+    readonly node: BaseNode;
+    readonly declared: Effect;
+    readonly inferred: Effect;
+    readonly excess: readonly string[];
+    readonly message: string;
+}
+/**
+ * Checa uma função contra o efeito que ela **promete**. Se o inferido exceder o
+ * declarado, devolve a violação (com os átomos culpados). Lista vazia = ok.
+ * Sobre-declarar é seguro (`{} ⊆ { io }`); o erro é fazer **mais** do que prometeu.
+ */
+declare function checkEffects(node: BaseNode, declared: Effect, opts?: InferOptions): EffectViolation[];
+
+/**
+ * Traduz o nível `host.effects` num **teto** de efeito permitido. `null` = `"any"`
+ * (escape-hatch, sem restrição). `"io"` libera o átomo de side-effect padrão `io`;
+ * para um lattice de átomos mais fino (`net`/`fs`/`rand`…), use `checkEffects`
+ * direto com o conjunto declarado — `host.effects` é a régua grossa (3 níveis).
+ */
+declare function effectCeiling(level: Effects): Effect | null;
+/**
+ * Enforça o eixo `host.effects` de um `CapabilityProfile`: infere o efeito de `node`
+ * (sob o `env` de efeitos da DI — `effectEnv({ save: ["io"] })`) e devolve as
+ * violações que **excedem** o teto. Lista vazia = ok; `"any"` nunca viola.
+ *
+ * É a "ligação" do analysis no capability (A1): o consumidor roda
+ * `check(ast, env, { profile })` (gating sintático, soft) e, em paralelo,
+ * `checkEffectPolicy(ast, profile.host.effects, { env: effectEnv(...) })`.
+ */
+declare function checkEffectPolicy(node: BaseNode, level: Effects, opts?: InferOptions): EffectViolation[];
+
+/** A árvore JÁ TIPADA — a saída do kernel que todo overlay consome (read-only). */
+interface TypedTree {
+    readonly root: BaseNode;
+    readonly diagnostics: readonly Diagnostic[];
+    /** O tipo de um nó (do `TypeOverlay` do checker). */
+    typeOf(node: BaseNode): Schema | undefined;
+    /** O escopo léxico em um nó (do `TypeOverlay` do checker). */
+    scopeOf(node: BaseNode): Scope | undefined;
+}
+/** Embrulha o `CheckResult` do kernel numa fachada read-only para os overlays. */
+declare function typedTreeOf(root: BaseNode, result: CheckResult): TypedTree;
+/** O que um overlay produz: um mapa por nó. */
+type OverlayResult<T> = ReadonlyMap<BaseNode, T>;
+/** Contexto entregue a um overlay: a árvore tipada + leitura cruzada de outros. */
+interface OverlayCtx {
+    readonly tree: TypedTree;
+    /** O resultado de um overlay já calculado nesta rodada (ver `dependsOn`). */
+    read<U>(overlay: Overlay<U>): OverlayResult<U> | undefined;
+}
+/** Hooks de um overlay-visitor — o runner os dirige num walk compartilhado. */
+interface OverlayVisitor<T> {
+    enter?(node: BaseNode, ctx: OverlayCtx): void;
+    exit?(node: BaseNode, ctx: OverlayCtx): void;
+    result(): OverlayResult<T>;
+}
+/** O contrato de um overlay plugin. Forneça `run` OU `visitor`. */
+interface Overlay<T> {
+    readonly name: string;
+    /** Overlays cujos resultados este lê via `ctx.read` (ordena o runner). */
+    readonly dependsOn?: readonly Overlay<unknown>[];
+    /** Forma A — controle total: o overlay faz a própria travessia. */
+    run?(ctx: OverlayCtx): OverlayResult<T>;
+    /** Forma B — passe compartilhado: hooks fundidos num walk único. */
+    readonly visitor?: OverlayVisitor<T>;
+}
+/** O resultado de uma rodada de overlays: o mapa de cada um, por nome. */
+type Analysis = ReadonlyMap<string, OverlayResult<unknown>>;
+/**
+ * Roda a camada de overlays sobre a árvore tipada. Os overlays-`visitor` são
+ * **fundidos num único DFS** (enter na descida, exit na subida); os
+ * overlays-`run` rodam depois (podendo `read` os resultados dos visitors). O
+ * kernel já rodou fora — aqui não se tipa nada de novo.
+ */
+declare function analyze(tree: TypedTree, overlays: readonly Overlay<unknown>[]): Analysis;
+
+/** Uma categoria arquitetural (tag): `controller`, `service`, `repo`, … */
+type Category = string;
+/** A decisão de uma aresta entre categorias. */
+type Decision = "allow" | "deny";
+/** A matriz de permissão: `from → to → decisão`. */
+interface PolicyMatrix {
+    /** Regras explícitas. Ausência cai no `defaultPolicy`. */
+    readonly rules: Readonly<Record<Category, Readonly<Record<Category, Decision>>>>;
+    /** Decisão para pares sem regra. Default: `allow` (estilo deny-list). */
+    readonly defaultPolicy?: Decision;
+}
+interface PolicyOptions {
+    /**
+     * A categoria de cada nome — capabilities da DI (`repo`, `repo.save`) ou
+     * funções locais (`handle`). Para um callee `obj.m`, tenta `obj.m` e cai em
+     * `obj`. Nomes sem categoria não participam de nenhuma regra.
+     */
+    readonly categories: Readonly<Record<string, Category>>;
+    /** A matriz de permissão entre categorias. */
+    readonly matrix: PolicyMatrix;
+}
+/** Uma violação de política (erro como dado). */
+interface PolicyViolation {
+    readonly call: BaseNode;
+    /** Nome da função chamadora (`null` = chamada de topo, fora de função). */
+    readonly from: string | null;
+    /** Nome/caminho do callee (`repo.save`, `svc`). */
+    readonly to: string;
+    readonly fromCategory: Category;
+    readonly toCategory: Category;
+    readonly message: string;
+}
+/**
+ * Verifica as **políticas de arquitetura** sobre o call graph de `root`. Para
+ * cada chamada `A → B` cujas duas pontas têm categoria, consulta a matriz; o que
+ * for `deny` vira uma violação. Por aresta direta — sem propagação.
+ */
+declare function checkPolicies(root: BaseNode, opts: PolicyOptions): PolicyViolation[];
+
+/** Uma entrada da qual algo depende (uma variável livre). */
+type Dep = string;
+/** O overlay: para cada nó, o conjunto de entradas das quais ele depende. */
+type DepsOverlay = Map<BaseNode, ReadonlySet<Dep>>;
+interface DepsOptions {
+    /**
+     * Nomes sempre ligados (globals/DI/capabilities): nunca contam como entrada.
+     * Útil para focar deps em params/estado e ignorar a borda estável.
+     */
+    readonly globals?: Iterable<string>;
+}
+/**
+ * Computa o overlay de deps de `node`: para cada subárvore, suas variáveis
+ * livres. Travessia recursiva (bottom-up) que preenche o `Map`.
+ */
+declare function deps(node: BaseNode, opts?: DepsOptions): DepsOverlay;
+/** Conveniência: as variáveis livres (deps) da raiz `node`. */
+declare function freeVars(node: BaseNode, opts?: DepsOptions): ReadonlySet<Dep>;
+
+/**
+ * `effects` como overlay: o efeito concreto de **cada função** (`Map<fn, Effect>`).
+ * Faz a própria travessia (grafo lazy de schemes) — forma `run`.
+ */
+declare const effectsOverlay: (env: EffectEnv, rules?: EffectRules) => Overlay<Effect>;
+/**
+ * `deps` como overlay-**visitor**: as variáveis livres de cada subárvore. Em
+ * pós-ordem (`exit`), combina os filhos (já no map) — partilha o walk do runner.
+ */
+declare const depsOverlay: (opts?: DepsOptions) => Overlay<ReadonlySet<Dep>>;
+/**
+ * `policies` como overlay-**visitor**: a violação em cada chamada proibida
+ * (`Map<callNode, PolicyViolation>`). Por aresta direta, sem propagação.
+ */
+declare const policiesOverlay: (opts: PolicyOptions) => Overlay<PolicyViolation>;
+
+export { type Analysis, type Category, DEFAULT_RULES, type Decision, type Dep, type DepsOptions, type DepsOverlay, type Effect, type EffectAtom, type EffectDecl, type EffectEnv, type EffectRow, type EffectRules, type EffectScheme, type EffectVar, type EffectViolation, type InferOptions, type Overlay, type OverlayCtx, type OverlayResult, type OverlayVisitor, PURE, PURE_ROW, PURE_SCHEME, type PolicyMatrix, type PolicyOptions, type PolicyViolation, type TypedTree, analyze, checkEffectPolicy, checkEffects, checkPolicies, deps, depsOverlay, effect, effectCeiling, effectEnv, effectsOverlay, effectsOverlayOf, excess, forwardEffect, freeVars, groundRow, inferEffects, instantiateScheme, join, joinRows, policiesOverlay, rowOf, rowOfVar, substituteRow, typedTreeOf, within };

package/dist/index.d.ts

@@ -0,0 +1,265 @@
+import { BaseNode } from '@tslite/core';
+import { Effects } from '@tslite/capability';
+import { Diagnostic, Schema, Scope, CheckResult } from '@tslite/checker';
+
+/** Um átomo de efeito (vocabulário da app): `io`, `loops`, `time`, … */
+type EffectAtom = string;
+/** Uma variável de efeito (`ε`) — o "genérico" do eixo de efeitos. */
+type EffectVar = string;
+/** O efeito concreto de algo: o conjunto de átomos. `∅` = `pure`. */
+type Effect = ReadonlySet<EffectAtom>;
+/** O efeito vazio (bottom do lattice) — puro. */
+declare const PURE: Effect;
+/** Constrói um efeito concreto a partir de átomos. */
+declare const effect: (...atoms: EffectAtom[]) => Effect;
+/**
+ * Uma **linha de efeito**: átomos concretos `⊔` variáveis de efeito ainda não
+ * resolvidas. `pure` é `{ atoms: ∅, vars: ∅ }`.
+ */
+interface EffectRow {
+    readonly atoms: ReadonlySet<EffectAtom>;
+    readonly vars: ReadonlySet<EffectVar>;
+}
+/** A linha pura (bottom). */
+declare const PURE_ROW: EffectRow;
+/** Uma linha só de átomos concretos. */
+declare const rowOf: (...atoms: EffectAtom[]) => EffectRow;
+/** Uma linha que é só uma variável de efeito (`ε`). */
+declare const rowOfVar: (v: EffectVar) => EffectRow;
+/** Junção (`⊔`) de linhas — união de átomos e de variáveis. */
+declare const joinRows: (rows: Iterable<EffectRow>) => EffectRow;
+/**
+ * Substitui as variáveis de `row` pelas linhas ligadas em `bindings` (unindo
+ * seus átomos/vars); variáveis sem ligação permanecem livres. É o `substitute`
+ * do eixo de efeitos.
+ */
+declare const substituteRow: (row: EffectRow, bindings: ReadonlyMap<EffectVar, EffectRow>) => EffectRow;
+/**
+ * O contrato de efeito de uma função: para cada parâmetro, a `ε` que ele
+ * introduz se for chamado dentro do corpo (`null` caso contrário), e a linha
+ * **latente** — o que o corpo faz quando a função é chamada (podendo mencionar
+ * essas `ε`). É o análogo de uma assinatura genérica `map<T,U,ε>`.
+ */
+interface EffectScheme {
+    readonly params: readonly (EffectVar | null)[];
+    readonly latent: EffectRow;
+}
+/** Um scheme puro sem parâmetros-efeito. */
+declare const PURE_SCHEME: EffectScheme;
+/**
+ * Instancia um scheme no call site: liga cada `ε` de parâmetro à linha de efeito
+ * do argumento correspondente (quando o argumento é "chamável") e devolve a
+ * linha latente já substituída. É o `instantiate` do eixo de efeitos — o mesmo
+ * padrão do checker, sobre linhas em vez de tipos.
+ */
+declare const instantiateScheme: (scheme: EffectScheme, argRows: readonly (EffectRow | null)[]) => EffectRow;
+/**
+ * "Aterra" uma linha no seu efeito **concreto**: descarta as variáveis livres
+ * (um higher-order não-instanciado é puro *em si*). É a ponte da linha para o
+ * `Effect` que os contratos comparam.
+ */
+declare const groundRow: (row: EffectRow) => Effect;
+/** Junção (`⊔`) de efeitos concretos — a união. */
+declare const join: (effects: Iterable<Effect>) => Effect;
+/** `inferido ⊆ declarado`? (o inferido cabe no contrato). */
+declare const within: (inferred: Effect, declared: Effect) => boolean;
+/** Os átomos de `inferred` que `declared` **não** permite. */
+declare const excess: (inferred: Effect, declared: Effect) => EffectAtom[];
+
+/** A declaração de efeito de uma capability da DI: concreta ou higher-order. */
+type EffectDecl = Effect | EffectScheme;
+/** Efeitos declarados por nome — a borda DI (capabilities/funções externas). */
+type EffectEnv = Readonly<Record<string, EffectDecl>>;
+/** Açúcar: monta um `EffectEnv` concreto a partir de listas de átomos. */
+declare const effectEnv: (decls: Readonly<Record<string, readonly string[]>>) => EffectEnv;
+/**
+ * Açúcar para uma capability **higher-order** cujo efeito é o do seu parâmetro
+ * de índice `paramIndex` (ex.: `map`/`filter`/`forEach` herdam o efeito do
+ * callback). `extra` são átomos que a própria capability sempre faz.
+ */
+declare const forwardEffect: (paramIndex: number, arity: number, extra?: readonly string[]) => EffectScheme;
+/** Quais nós produzem qual efeito **direto** (extensível pela app). */
+interface EffectRules {
+    readonly nodeEffects: Readonly<Record<string, string>>;
+}
+/** Regras padrão (capability imperativa, D30): loops → `loops`; mutação → `mutates`. */
+declare const DEFAULT_RULES: EffectRules;
+interface InferOptions {
+    /** Efeitos declarados das capabilities/funções chamadas (DI). */
+    readonly env?: EffectEnv;
+    /** Regras de efeito direto por tipo de nó. */
+    readonly rules?: EffectRules;
+    /**
+     * A raiz, para resolver chamadas a **funções irmãs/externas** ao `node`
+     * (`const g = …; const f = () => g()`). Sem ela, só nested + params + DI.
+     */
+    readonly root?: BaseNode;
+}
+/**
+ * Infere o efeito **concreto** de executar `node` (variáveis de efeito livres,
+ * de higher-order não instanciado, são aterradas — um `map` *em si* é puro).
+ */
+declare function inferEffects(node: BaseNode, opts?: InferOptions): Effect;
+/**
+ * O **overlay** de efeitos: o efeito concreto de **cada função** sob `root`, numa
+ * travessia (schemes memoizados). É o que a camada de overlays (`effectsOverlay`)
+ * consome para devolver um `Map<nó-de-função, Effect>`.
+ */
+declare function effectsOverlayOf(root: BaseNode, opts?: {
+    readonly env?: EffectEnv;
+    readonly rules?: EffectRules;
+}): Map<BaseNode, Effect>;
+
+/** Uma violação de contrato de efeito (erro como dado). */
+interface EffectViolation {
+    readonly node: BaseNode;
+    readonly declared: Effect;
+    readonly inferred: Effect;
+    readonly excess: readonly string[];
+    readonly message: string;
+}
+/**
+ * Checa uma função contra o efeito que ela **promete**. Se o inferido exceder o
+ * declarado, devolve a violação (com os átomos culpados). Lista vazia = ok.
+ * Sobre-declarar é seguro (`{} ⊆ { io }`); o erro é fazer **mais** do que prometeu.
+ */
+declare function checkEffects(node: BaseNode, declared: Effect, opts?: InferOptions): EffectViolation[];
+
+/**
+ * Traduz o nível `host.effects` num **teto** de efeito permitido. `null` = `"any"`
+ * (escape-hatch, sem restrição). `"io"` libera o átomo de side-effect padrão `io`;
+ * para um lattice de átomos mais fino (`net`/`fs`/`rand`…), use `checkEffects`
+ * direto com o conjunto declarado — `host.effects` é a régua grossa (3 níveis).
+ */
+declare function effectCeiling(level: Effects): Effect | null;
+/**
+ * Enforça o eixo `host.effects` de um `CapabilityProfile`: infere o efeito de `node`
+ * (sob o `env` de efeitos da DI — `effectEnv({ save: ["io"] })`) e devolve as
+ * violações que **excedem** o teto. Lista vazia = ok; `"any"` nunca viola.
+ *
+ * É a "ligação" do analysis no capability (A1): o consumidor roda
+ * `check(ast, env, { profile })` (gating sintático, soft) e, em paralelo,
+ * `checkEffectPolicy(ast, profile.host.effects, { env: effectEnv(...) })`.
+ */
+declare function checkEffectPolicy(node: BaseNode, level: Effects, opts?: InferOptions): EffectViolation[];
+
+/** A árvore JÁ TIPADA — a saída do kernel que todo overlay consome (read-only). */
+interface TypedTree {
+    readonly root: BaseNode;
+    readonly diagnostics: readonly Diagnostic[];
+    /** O tipo de um nó (do `TypeOverlay` do checker). */
+    typeOf(node: BaseNode): Schema | undefined;
+    /** O escopo léxico em um nó (do `TypeOverlay` do checker). */
+    scopeOf(node: BaseNode): Scope | undefined;
+}
+/** Embrulha o `CheckResult` do kernel numa fachada read-only para os overlays. */
+declare function typedTreeOf(root: BaseNode, result: CheckResult): TypedTree;
+/** O que um overlay produz: um mapa por nó. */
+type OverlayResult<T> = ReadonlyMap<BaseNode, T>;
+/** Contexto entregue a um overlay: a árvore tipada + leitura cruzada de outros. */
+interface OverlayCtx {
+    readonly tree: TypedTree;
+    /** O resultado de um overlay já calculado nesta rodada (ver `dependsOn`). */
+    read<U>(overlay: Overlay<U>): OverlayResult<U> | undefined;
+}
+/** Hooks de um overlay-visitor — o runner os dirige num walk compartilhado. */
+interface OverlayVisitor<T> {
+    enter?(node: BaseNode, ctx: OverlayCtx): void;
+    exit?(node: BaseNode, ctx: OverlayCtx): void;
+    result(): OverlayResult<T>;
+}
+/** O contrato de um overlay plugin. Forneça `run` OU `visitor`. */
+interface Overlay<T> {
+    readonly name: string;
+    /** Overlays cujos resultados este lê via `ctx.read` (ordena o runner). */
+    readonly dependsOn?: readonly Overlay<unknown>[];
+    /** Forma A — controle total: o overlay faz a própria travessia. */
+    run?(ctx: OverlayCtx): OverlayResult<T>;
+    /** Forma B — passe compartilhado: hooks fundidos num walk único. */
+    readonly visitor?: OverlayVisitor<T>;
+}
+/** O resultado de uma rodada de overlays: o mapa de cada um, por nome. */
+type Analysis = ReadonlyMap<string, OverlayResult<unknown>>;
+/**
+ * Roda a camada de overlays sobre a árvore tipada. Os overlays-`visitor` são
+ * **fundidos num único DFS** (enter na descida, exit na subida); os
+ * overlays-`run` rodam depois (podendo `read` os resultados dos visitors). O
+ * kernel já rodou fora — aqui não se tipa nada de novo.
+ */
+declare function analyze(tree: TypedTree, overlays: readonly Overlay<unknown>[]): Analysis;
+
+/** Uma categoria arquitetural (tag): `controller`, `service`, `repo`, … */
+type Category = string;
+/** A decisão de uma aresta entre categorias. */
+type Decision = "allow" | "deny";
+/** A matriz de permissão: `from → to → decisão`. */
+interface PolicyMatrix {
+    /** Regras explícitas. Ausência cai no `defaultPolicy`. */
+    readonly rules: Readonly<Record<Category, Readonly<Record<Category, Decision>>>>;
+    /** Decisão para pares sem regra. Default: `allow` (estilo deny-list). */
+    readonly defaultPolicy?: Decision;
+}
+interface PolicyOptions {
+    /**
+     * A categoria de cada nome — capabilities da DI (`repo`, `repo.save`) ou
+     * funções locais (`handle`). Para um callee `obj.m`, tenta `obj.m` e cai em
+     * `obj`. Nomes sem categoria não participam de nenhuma regra.
+     */
+    readonly categories: Readonly<Record<string, Category>>;
+    /** A matriz de permissão entre categorias. */
+    readonly matrix: PolicyMatrix;
+}
+/** Uma violação de política (erro como dado). */
+interface PolicyViolation {
+    readonly call: BaseNode;
+    /** Nome da função chamadora (`null` = chamada de topo, fora de função). */
+    readonly from: string | null;
+    /** Nome/caminho do callee (`repo.save`, `svc`). */
+    readonly to: string;
+    readonly fromCategory: Category;
+    readonly toCategory: Category;
+    readonly message: string;
+}
+/**
+ * Verifica as **políticas de arquitetura** sobre o call graph de `root`. Para
+ * cada chamada `A → B` cujas duas pontas têm categoria, consulta a matriz; o que
+ * for `deny` vira uma violação. Por aresta direta — sem propagação.
+ */
+declare function checkPolicies(root: BaseNode, opts: PolicyOptions): PolicyViolation[];
+
+/** Uma entrada da qual algo depende (uma variável livre). */
+type Dep = string;
+/** O overlay: para cada nó, o conjunto de entradas das quais ele depende. */
+type DepsOverlay = Map<BaseNode, ReadonlySet<Dep>>;
+interface DepsOptions {
+    /**
+     * Nomes sempre ligados (globals/DI/capabilities): nunca contam como entrada.
+     * Útil para focar deps em params/estado e ignorar a borda estável.
+     */
+    readonly globals?: Iterable<string>;
+}
+/**
+ * Computa o overlay de deps de `node`: para cada subárvore, suas variáveis
+ * livres. Travessia recursiva (bottom-up) que preenche o `Map`.
+ */
+declare function deps(node: BaseNode, opts?: DepsOptions): DepsOverlay;
+/** Conveniência: as variáveis livres (deps) da raiz `node`. */
+declare function freeVars(node: BaseNode, opts?: DepsOptions): ReadonlySet<Dep>;
+
+/**
+ * `effects` como overlay: o efeito concreto de **cada função** (`Map<fn, Effect>`).
+ * Faz a própria travessia (grafo lazy de schemes) — forma `run`.
+ */
+declare const effectsOverlay: (env: EffectEnv, rules?: EffectRules) => Overlay<Effect>;
+/**
+ * `deps` como overlay-**visitor**: as variáveis livres de cada subárvore. Em
+ * pós-ordem (`exit`), combina os filhos (já no map) — partilha o walk do runner.
+ */
+declare const depsOverlay: (opts?: DepsOptions) => Overlay<ReadonlySet<Dep>>;
+/**
+ * `policies` como overlay-**visitor**: a violação em cada chamada proibida
+ * (`Map<callNode, PolicyViolation>`). Por aresta direta, sem propagação.
+ */
+declare const policiesOverlay: (opts: PolicyOptions) => Overlay<PolicyViolation>;
+
+export { type Analysis, type Category, DEFAULT_RULES, type Decision, type Dep, type DepsOptions, type DepsOverlay, type Effect, type EffectAtom, type EffectDecl, type EffectEnv, type EffectRow, type EffectRules, type EffectScheme, type EffectVar, type EffectViolation, type InferOptions, type Overlay, type OverlayCtx, type OverlayResult, type OverlayVisitor, PURE, PURE_ROW, PURE_SCHEME, type PolicyMatrix, type PolicyOptions, type PolicyViolation, type TypedTree, analyze, checkEffectPolicy, checkEffects, checkPolicies, deps, depsOverlay, effect, effectCeiling, effectEnv, effectsOverlay, effectsOverlayOf, excess, forwardEffect, freeVars, groundRow, inferEffects, instantiateScheme, join, joinRows, policiesOverlay, rowOf, rowOfVar, substituteRow, typedTreeOf, within };

package/dist/index.js

@@ -0,0 +1 @@
+import {forEachChild,rootScope,childScope,lookup}from'@tslite/core';var I=new Set,T=(...e)=>new Set(e),m={atoms:new Set,vars:new Set},M=(...e)=>({atoms:new Set(e),vars:new Set}),C=e=>({atoms:new Set,vars:new Set([e])}),R=e=>{let t=new Set,o=new Set;for(let n of e){for(let r of n.atoms)t.add(r);for(let r of n.vars)o.add(r);}return {atoms:t,vars:o}},Y=(e,t)=>{let o=new Set(e.atoms),n=new Set;for(let r of e.vars){let i=t.get(r);if(i){for(let s of i.atoms)o.add(s);for(let s of i.vars)n.add(s);}else n.add(r);}return {atoms:o,vars:n}},U={params:[],latent:m},V=(e,t)=>{let o=new Map;return e.params.forEach((n,r)=>{let i=t[r];n&&i&&o.set(n,i);}),Y(e.latent,o)},O=e=>new Set(e.atoms),ae=e=>{let t=new Set;for(let o of e)for(let n of o)t.add(n);return t},fe=(e,t)=>{for(let o of e)if(!t.has(o))return  false;return  true},j=(e,t)=>[...e].filter(o=>!t.has(o));var de=e=>{let t={};for(let[o,n]of Object.entries(e))t[o]=new Set(n);return t},pe=(e,t,o=[])=>{let n=new Array(t).fill(null),r="\u03B5";return n[e]=r,{params:n,latent:{atoms:new Set(o),vars:new Set([r])}}},L={nodeEffects:{ForStatement:"loops",ForInStatement:"loops",ForOfStatement:"loops",WhileStatement:"loops",DoWhileStatement:"loops",AssignmentExpression:"mutates",UpdateExpression:"mutates"}},ye=new Set(["ArrowFunctionExpression","FunctionExpression","FunctionDeclaration"]),h=e=>ye.has(e.type),p=e=>e,ue=e=>p(e).body,me=e=>p(e).params??[],S=e=>e&&e.type==="Identifier"?p(e).name:void 0,Ee=e=>{let t=p(e).object,o=p(e).property,n=S(t);if(!n)return null;let r=p(e).computed?void 0:S(o);return {path:r?`${n}.${r}`:n,root:n}},ge=e=>typeof e=="object"&&e!==null&&"latent"in e,$=(e,t)=>ge(e)?V(e,t):{atoms:new Set(e),vars:new Set},J=(e,t)=>{let o=0;return {rules:e,env:t,schemeOf:new Map,active:new Set,fresh:()=>`\u03B5${o++}`}},Q=e=>{let t={};for(let[o,n]of Object.entries(e))t[o]={kind:"capability",decl:n};return rootScope(t)};function x(e,t,o){let n=o.schemeOf.get(e);if(n)return n;if(o.active.has(e))return U;o.active.add(e);let r=me(e),i=r.map(v=>v.type==="Identifier"?o.fresh():null),s={};r.forEach((v,D)=>{let K=S(v);K&&i[D]&&(s[K]={kind:"param",var:i[D]});});let a=childScope(t,s),f=ue(e),u=f?E(f,a,o):m,d={params:i,latent:u};return o.active.delete(e),o.schemeOf.set(e,d),d}function _(e,t,o){x(e,t,o);}function E(e,t,o){let n=o.rules.nodeEffects[e.type],r=n?M(n):m;if(h(e))return _(e,t,o),r;if(e.type==="CallExpression"||e.type==="NewExpression")return R([r,we(e,t,o)]);if(e.type==="BlockStatement"||e.type==="Program"){let s=p(e).body??[];return R([r,ve(s,t,o)])}let i=[r];return forEachChild(e,s=>i.push(E(s,t,o))),R(i)}function ve(e,t,o){let n=t,r={};for(let s of e)if(s.type==="FunctionDeclaration"){let a=S(p(s).id);a&&(r[a]={kind:"fn",node:s,scope:n});}Object.keys(r).length&&(n=childScope(n,r));for(let s in r)r[s].kind==="fn"&&(r[s].scope=n);for(let s in r){let a=r[s];a.kind==="fn"&&_(a.node,n,o);}let i=[];for(let s of e)if(s.type!=="FunctionDeclaration"){if(s.type==="VariableDeclaration"){let a=p(s).declarations??[];for(let f of a){let u=p(f).id,d=p(f).init,v=S(u);if(v&&d&&h(d)){let D=childScope(n,{[v]:{kind:"fn",node:d,scope:n}});_(d,D,o),n=D;}else d&&i.push(E(d,n,o)),v&&(n=childScope(n,{[v]:{kind:"value"}}));}continue}i.push(E(s,n,o));}return R(i)}function we(e,t,o){let n=p(e).callee,r=p(e).arguments??[],i=r.map(f=>h(f)?m:E(f,t,o)),s=r.map(f=>Re(f,t,o)),a=Se(n,s,t,o);return R([a,...i])}function Re(e,t,o){if(h(e))return x(e,t,o).latent;if(e.type==="Identifier"){let n=lookup(t,S(e));if(!n)return null;if(n.kind==="fn")return x(n.node,n.scope,o).latent;if(n.kind==="param")return C(n.var);if(n.kind==="capability")return $(n.decl,[])}return null}function Se(e,t,o,n){if(!e)return m;if(e.type==="Identifier"){let r=lookup(o,S(e));if(!r)return m;switch(r.kind){case "capability":return $(r.decl,t);case "fn":return V(x(r.node,r.scope,n),t);case "param":return C(r.var);case "value":return m}}if(h(e))return V(x(e,o,n),t);if(e.type==="MemberExpression"){let r=Ee(e),i=r&&(n.env[r.path]??n.env[r.root]);if(i)return $(i,t)}return E(e,o,n)}function W(e,t={}){let o=t.env??{},n=J(t.rules??L,o),r=Q(o);if(t.root&&t.root!==e){E(t.root,r,n);let i=n.schemeOf.get(e);if(i)return O(i.latent)}return h(e)?O(x(e,r,n).latent):O(E(e,r,n))}function z(e,t={}){let o=t.env??{},n=J(t.rules??L,o);E(e,Q(o),n);let r=new Map;for(let[i,s]of n.schemeOf)r.set(i,O(s.latent));return r}var X=e=>e.size?`{ ${[...e].sort().join(", ")} }`:"pure";function G(e,t,o){let n=W(e,o),r=j(n,t);return r.length===0?[]:[{node:e,declared:t,inferred:n,excess:r,message:`Effect contract violated: declared ${X(t)} but infers ${X(n)} \u2014 not allowed: ${r.join(", ")}.`}]}function Z(e){switch(e){case "pure":return I;case "io":return T("io");case "any":return null}}function Be(e,t,o){let n=Z(t);return n===null?[]:G(e,n,o)}var b=e=>e,B=e=>e&&e.type==="Identifier"?b(e).name:void 0,N=(e,t)=>b(e)[t],Ne=new Set(["ArrowFunctionExpression","FunctionExpression","FunctionDeclaration"]),F=e=>Ne.has(e.type);function Oe(e){if(!e)return null;if(e.type==="Identifier"){let t=B(e);return {path:t,root:t}}if(e.type==="MemberExpression"){let t=b(e).object,o=b(e).property,n=b(e).computed,r=B(t);if(!r)return null;let i=n?void 0:B(o);return {path:i?`${r}.${i}`:r,root:r}}return null}function te(e){let{categories:t,matrix:o}=e,n=o.defaultPolicy??"allow",r=s=>t[s.path]??t[s.root],i=(s,a)=>o.rules[s]?.[a]??n;return (s,a)=>{if(!a)return null;let f=t[a];if(f===void 0)return null;let u=Oe(N(s,"callee"));if(!u)return null;let d=r(u);return d===void 0||i(f,d)!=="deny"?null:{call:s,from:a,to:u.path,fromCategory:f,toCategory:d,message:`Policy violated: ${f} '${a}' must not call ${d} '${u.path}' (${f} \u2192 ${d} is deny).`}}}var oe=e=>e.type==="CallExpression"||e.type==="NewExpression";function xe(e,t){let o=te(t),n=[],r=(i,s)=>{if(oe(i)){let a=o(i,s);a&&n.push(a);}if(i.type==="VariableDeclaration"){for(let a of b(i).declarations??[]){let f=N(a,"init");if(!f)continue;let u=F(f)?B(N(a,"id"))??s:s;r(f,u);}return}if(i.type==="FunctionDeclaration"){let a=B(N(i,"id"))??s;forEachChild(i,f=>r(f,a));return}forEachChild(i,a=>r(a,s));};return r(e,null),n}function ne(e){let t=te(e),o=new Map,n=[],r=()=>n.length?n[n.length-1]:null,i=null;return {enter(s){if(s.type==="VariableDeclarator"){let a=N(s,"init"),f=B(N(s,"id"));a&&F(a)&&f&&(i={name:f,fn:a});}if(F(s)){let a=i&&i.fn===s?i.name:s.type==="FunctionDeclaration"?B(N(s,"id"))??r():r();n.push(a),i=null;}if(oe(s)){let a=t(s,r());a&&o.set(s,a);}},exit(s){F(s)&&n.pop();},result:()=>o}}var w=e=>e,be=e=>e&&e.type==="Identifier"?w(e).name:void 0,c=(e,t)=>w(e)[t],g=(e,t)=>w(e)[t]??[];function y(e,t){if(e)switch(e.type){case "Identifier":t.add(w(e).name);return;case "AssignmentPattern":y(c(e,"left"),t);return;case "RestElement":y(c(e,"argument"),t);return;case "ArrayPattern":for(let o of g(e,"elements"))y(o,t);return;case "ObjectPattern":for(let o of g(e,"properties"))o.type==="RestElement"?y(c(o,"argument"),t):y(c(o,"value"),t);return}}function ke(e){let t=new Set;for(let o of e)if(o.type==="VariableDeclaration")for(let n of g(o,"declarations"))y(c(n,"id"),t);else if(o.type==="FunctionDeclaration"){let n=be(c(o,"id"));n&&t.add(n);}return t}var l=(e,t)=>{for(let o of t)e.add(o);},k=(e,t)=>{for(let o of t)e.delete(o);},De=new Set,re=e=>new Set(e);function H(e,t){let o=new Set;switch(e.type){case "Identifier":o.add(w(e).name);break;case "MemberExpression":{l(o,t(c(e,"object"))),w(e).computed&&l(o,t(c(e,"property")));break}case "Property":{w(e).computed&&l(o,t(c(e,"key"))),l(o,t(c(e,"value")));break}case "ArrowFunctionExpression":case "FunctionExpression":case "FunctionDeclaration":{let n=g(e,"params"),r=new Set;for(let i of n)y(i,r),i.type==="AssignmentPattern"&&l(o,t(c(i,"right")));l(o,t(c(e,"body"))),k(o,r);break}case "BlockStatement":case "Program":{let n=g(e,"body");for(let r of n)l(o,t(r));k(o,ke(n));break}case "VariableDeclarator":{l(o,t(c(e,"init")));let n=c(e,"id");n&&n.type!=="Identifier"&&A(n,o,t);break}case "CatchClause":{let n=new Set;y(c(e,"param"),n),l(o,t(c(e,"body"))),k(o,n);break}case "LabeledStatement":l(o,t(c(e,"body")));break;case "BreakStatement":case "ContinueStatement":break;case "ForInStatement":case "ForOfStatement":{let n=c(e,"left");l(o,t(c(e,"right")));let r=new Set;if(n.type==="VariableDeclaration")for(let s of g(n,"declarations"))y(c(s,"id"),r);else y(n,r);let i=re(t(c(e,"body")));k(i,r),l(o,i);break}case "ForStatement":{let n=c(e,"init"),r=new Set;if(n){if(n.type==="VariableDeclaration")for(let i of g(n,"declarations"))y(c(i,"id"),r);l(o,t(n));}for(let i of ["test","update","body"]){let s=re(t(c(e,i)));k(s,r),l(o,s);}break}default:forEachChild(e,n=>l(o,t(n)));break}return o}function se(e,t={}){let o=new Map,n=new Set(t.globals??[]),r=i=>{if(!i)return De;let s=H(i,r);return k(s,n),o.set(i,s),s};return r(e),o}function A(e,t,o){if(e.type==="AssignmentPattern")l(t,o(c(e,"right"))),A(c(e,"left"),t,o);else if(e.type==="ArrayPattern")for(let n of g(e,"elements"))n&&A(n,t,o);else if(e.type==="ObjectPattern")for(let n of g(e,"properties")){w(n).computed&&l(t,o(c(n,"key")));let r=c(n,"value")??c(n,"argument");r&&A(r,t,o);}}function Ve(e,t){return se(e,t).get(e)??new Set}function Pe(e,t){return {root:e,diagnostics:t.diagnostics,typeOf:o=>t.overlay.get(o)?.type,scopeOf:o=>t.overlay.get(o)?.scope}}function Fe(e,t){let o=new Map,n={tree:e,read:s=>o.get(s.name)},r=t.filter(s=>!!s.visitor),i=t.filter(s=>!s.visitor&&s.run);if(r.length){let s=a=>{for(let f of r)f.visitor.enter?.(a,n);forEachChild(a,s);for(let f=r.length-1;f>=0;f--)r[f].visitor.exit?.(a,n);};s(e.root);for(let a of r)o.set(a.name,a.visitor.result());}for(let s of i)o.set(s.name,s.run(n));return o}var ie=new Set,Ae=(e,t)=>({name:"effects",run:o=>z(o.tree.root,{env:e,rules:t})}),Ie=e=>({name:"deps",visitor:(()=>{let t=new Set(e?.globals??[]),o=new Map;return {exit(n){let r=H(n,i=>i?o.get(i)??ie:ie);for(let i of t)r.delete(i);o.set(n,r);},result:()=>o}})()}),Te=e=>({name:"policies",visitor:ne(e)});export{L as DEFAULT_RULES,I as PURE,m as PURE_ROW,U as PURE_SCHEME,Fe as analyze,Be as checkEffectPolicy,G as checkEffects,xe as checkPolicies,se as deps,Ie as depsOverlay,T as effect,Z as effectCeiling,de as effectEnv,Ae as effectsOverlay,z as effectsOverlayOf,j as excess,pe as forwardEffect,Ve as freeVars,O as groundRow,W as inferEffects,V as instantiateScheme,ae as join,R as joinRows,Te as policiesOverlay,M as rowOf,C as rowOfVar,Y as substituteRow,Pe as typedTreeOf,fe as within};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@tslite/analysis",
+  "version": "0.1.0",
+  "description": "TSLite analysis — behavior/effect overlays over the AST (effect inference + propagation + contracts)",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/andersondrosa/tslite.git",
+    "directory": "packages/analysis"
+  },
+  "keywords": [
+    "ast",
+    "effects",
+    "effect-system",
+    "analysis",
+    "purity",
+    "typescript"
+  ],
+  "author": "Anderson D. Rosa <andersondrosa@outlook.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@tslite/core": "0.1.0",
+    "@tslite/checker": "0.1.0",
+    "@tslite/capability": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests",
+    "lint:fix": "eslint src tests --fix",
+    "clean": "rm -rf dist",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\""
+  }
+}