@tslite/explain 0.2.1 → 0.3.0

package/dist/index.cjs

@@ -1 +1 @@
-'use strict';var core=require('@tslite/core'),printer=require('@tslite/printer'),operators=require('@tslite/operators');var i="checker D9 / docs/SCOPE-BOUNDARY.md";function h(e,t){let n=T(e);return t.diagnostics.map(s=>{let o=u(s,n);return o?{...s,help:o}:s})}function u(e,t){let n=e.node;switch(n.type){case "NewExpression":return B(n);case "ClassDeclaration":case "ClassExpression":return k();case "FunctionDeclaration":case "FunctionExpression":return O();case "ThisExpression":return E();case "MemberExpression":return e.code==="forbidden-member"?D(n):x(e,n,t)}}function x(e,t,n){if(e.code!=="no-such-member"&&e.code!=="not-object")return;let s=l(t);if(!s)return;let o=operators.jsMethodReplacements[s];if(o)return w(t,s,o,n);if(operators.knownProtoMembersWithoutOperator.has(s))return N(s)}function w(e,t,n,s){let o=printer.print(e.object),a=s.get(e),c=a?.type==="CallExpression"&&a.callee===e,d=c?a.arguments.map(m=>printer.print(m)):[],p=n.call(o,d),g=printer.print(c?a:e);return {reason:"proto-member",category:"portability",explain:`${n.on==="array"?"Arrays":n.on==="string"?"Strings":"Values"} in TSL have no \`.${t}\` method (prototype member). TSL is FP-first and PORTABLE: \`.${t}\` does not translate cleanly to the target (in Python, for instance, it is a function). This is not a language bug \u2014 it is the model.`,suggestion:`Use the \`${n.operator}\` operator (@tslite/operators): \`${p}\`.`,fix:{from:g,to:p},docs:i}}function N(e){return {reason:"proto-member",category:"portability",explain:`\`.${e}\` is a JS prototype method/property \u2014 TSL is FP-first and immutable, so array/string/object methods are not vocabulary. This is not a language bug \u2014 it is the model.`,suggestion:"Rewrite it functionally with @tslite/operators (map/filter/reduce/\u2026), or use the imperative capability if you truly need to mutate.",docs:i}}function D(e){return {reason:"forbidden-substrate",category:"js-ism",explain:`\`.${l(e)??"constructor/prototype/__proto__"}\` is JS runtime substrate (inheritance/prototype) \u2014 it does not exist in TSL, which is FP-first and portable. Forbidden by identity + portability (and it closes the sandbox escape). This is not a language bug \u2014 it is the model.`,docs:i}}function B(e){let t=e.callee,n=t?.type==="Identifier"?t.name:"X";return {reason:"no-new",category:"js-ism",explain:"TSL has no `new` and no classes \u2014 it is FP-first (no OO). `new` was removed on purpose: native capabilities come in as FACTORY functions via DI. Not a language bug.",suggestion:`Inject a factory and call \`${n.charAt(0).toLowerCase()+n.slice(1)}(\u2026)\` instead of \`new ${n}(\u2026)\`.`,docs:i}}function k(){return {reason:"no-class",category:"js-ism",explain:"`class` does not exist in TSL \u2014 it is FP-first, no OO. An instance is just an object with props; behavior comes from functions. This is not a language bug \u2014 it is the model.",suggestion:'Model with objects + functions (a factory function via DI for "methods").',docs:i}}function E(){return {reason:"no-this",category:"js-ism",explain:"`this` does not exist in TSL \u2014 no OO, no implicit receiver. This is not a language bug \u2014 it is the model.",suggestion:"Pass the data as an explicit ARGUMENT instead of `this`.",docs:i}}function O(){return {reason:"no-function-expr",category:"js-ism",explain:"Only ARROW functions are functions in TSL (`(x) => \u2026`). `function(){}` is out (it brings `this`/`arguments`/construction \u2014 OO substrate). This is not a language bug \u2014 it is the model.",suggestion:"Use an arrow: `const f = (x) => \u2026`.",docs:i}}function l(e){if(!e.computed)return e.property.name;let t=e.property;return t.type==="Literal"&&typeof t.value=="string"?t.value:void 0}function T(e){let t=new WeakMap;return core.walk(e,{"*":(n,s)=>{s&&t.set(n,s);}}),t}exports.explain=h;exports.helpFor=u;
+'use strict';var core=require('@tslite/core'),printer=require('@tslite/printer'),operators=require('@tslite/operators');var a="checker D9 / docs/SCOPE-BOUNDARY.md";function w(e,n){let t=M(e);return n.diagnostics.map(o=>{let s=m(o,t);return s?{...o,help:s}:o})}function m(e,n){let t=e.node;switch(t.type){case "NewExpression":return E(t);case "ClassDeclaration":case "ClassExpression":return O();case "FunctionDeclaration":case "FunctionExpression":return T();case "ThisExpression":return H();case "MemberExpression":return e.code==="forbidden-member"?k(t):N(e,t,n)}}function N(e,n,t){if(e.code!=="no-such-member"&&e.code!=="not-object")return;let o=g(n);if(!o)return;let s=operators.jsMethodReplacements[o];if(s)return D(n,o,s,t);if(operators.knownProtoMembersWithoutOperator.has(o))return B(o)}function D(e,n,t,o){let s=printer.print(e.object),i=o.get(e),l=i?.type==="CallExpression"&&i.callee===e,y=l?i.arguments.map(f=>printer.print(f)):[],r=l?i:e,c=t.call(s,y),u=printer.print(r),d=r.loc?{start:r.loc.start,end:r.loc.end}:void 0;return {reason:"proto-member",category:"portability",explain:`${t.on==="array"?"Arrays":t.on==="string"?"Strings":"Values"} in TSL have no \`.${n}\` method (prototype member). TSL is FP-first and PORTABLE: \`.${n}\` does not translate cleanly to the target (in Python, for instance, it is a function). This is not a language bug \u2014 it is the model.`,suggestion:`Use the \`${t.operator}\` operator (@tslite/operators): \`${c}\`.`,fix:d?{from:u,to:c,range:d}:{from:u,to:c},docs:a}}function B(e){return {reason:"proto-member",category:"portability",explain:`\`.${e}\` is a JS prototype method/property \u2014 TSL is FP-first and immutable, so array/string/object methods are not vocabulary. This is not a language bug \u2014 it is the model.`,suggestion:"Rewrite it functionally with @tslite/operators (map/filter/reduce/\u2026), or use the imperative capability if you truly need to mutate.",docs:a}}function k(e){return {reason:"forbidden-substrate",category:"js-ism",explain:`\`.${g(e)??"constructor/prototype/__proto__"}\` is JS runtime substrate (inheritance/prototype) \u2014 it does not exist in TSL, which is FP-first and portable. Forbidden by identity + portability (and it closes the sandbox escape). This is not a language bug \u2014 it is the model.`,docs:a}}function E(e){let n=e.callee,t=n?.type==="Identifier"?n.name:"X";return {reason:"no-new",category:"js-ism",explain:"TSL has no `new` and no classes \u2014 it is FP-first (no OO). `new` was removed on purpose: native capabilities come in as FACTORY functions via DI. Not a language bug.",suggestion:`Inject a factory and call \`${t.charAt(0).toLowerCase()+t.slice(1)}(\u2026)\` instead of \`new ${t}(\u2026)\`.`,docs:a}}function O(){return {reason:"no-class",category:"js-ism",explain:"`class` does not exist in TSL \u2014 it is FP-first, no OO. An instance is just an object with props; behavior comes from functions. This is not a language bug \u2014 it is the model.",suggestion:'Model with objects + functions (a factory function via DI for "methods").',docs:a}}function H(){return {reason:"no-this",category:"js-ism",explain:"`this` does not exist in TSL \u2014 no OO, no implicit receiver. This is not a language bug \u2014 it is the model.",suggestion:"Pass the data as an explicit ARGUMENT instead of `this`.",docs:a}}function T(){return {reason:"no-function-expr",category:"js-ism",explain:"Only ARROW functions are functions in TSL (`(x) => \u2026`). `function(){}` is out (it brings `this`/`arguments`/construction \u2014 OO substrate). This is not a language bug \u2014 it is the model.",suggestion:"Use an arrow: `const f = (x) => \u2026`.",docs:a}}function g(e){if(!e.computed)return e.property.name;let n=e.property;return n.type==="Literal"&&typeof n.value=="string"?n.value:void 0}function M(e){let n=new WeakMap;return core.walk(e,{"*":(t,o)=>{o&&n.set(t,o);}}),n}exports.explain=w;exports.helpFor=m;

package/dist/index.d.cts

@@ -3,6 +3,15 @@ import { Diagnostic, CheckResult } from '@tslite/checker';
 
 /** Por que o erro aconteceu — a "raiz JS-ism" que o help explica. */
 type JsIsmReason = "proto-member" | "no-new" | "no-class" | "no-this" | "no-function-expr" | "forbidden-substrate";
+/**
+ * A chave estável de i18n (ver E2).
+ *
+ * Houve aqui um `SyntaxGapReason` (`type-args-not-supported`), mitigação para
+ * `f<T>(x)` não existir na gramática. **Saiu porque a lacuna foi fechada** — hoje
+ * o parser lê argumento de tipo de verdade (parser TODO / checker TC27). A
+ * categoria volta quando houver um buraco de gramática real para descrever.
+ */
+type HelpReason = JsIsmReason;
 /** A CLASSE do porquê — deixa uma UI didática renderizar diferente de erro de tipo. */
 type HelpCategory = "js-ism" | "portability" | "capability-off";
 /** O help auxiliar: prosa explicativa + sugestão + auto-fix aplicável (por IA/editor).
@@ -10,16 +19,31 @@ type HelpCategory = "js-ism" | "portability" | "capability-off";
  *  mensagens do checker). `reason` é a CHAVE estável de tradução: um add-on de i18n no
  *  frontend mapeia `reason` (+ os campos estruturados) → idioma, sem tocar isto. */
 interface DiagnosticHelp {
-    readonly reason: JsIsmReason;
+    readonly reason: HelpReason;
     readonly category: HelpCategory;
     /** "Why this is NOT a language bug" — default prose (English). */
     readonly explain: string;
     /** The correct idiom (e.g. "Use the `length(xs)` operator"). */
     readonly suggestion?: string;
-    /** Reescrita mecânica: `from` → `to` (aplicável por code-action ou por uma IA). */
+    /**
+     * Reescrita mecânica: `from` → `to` (aplicável por code-action ou por uma IA).
+     * `range` é o trecho EXATO a substituir (convenção TSLite: linha 1-based, coluna
+     * 0-based, fim exclusivo) — presente só quando o nó tem `loc`, isto é, quando o
+     * AST veio de autoria TEXTUAL. Em AST de builders (nocode) não há posição.
+     */
     readonly fix?: {
         readonly from: string;
         readonly to: string;
+        readonly range?: {
+            readonly start: {
+                readonly line: number;
+                readonly column: number;
+            };
+            readonly end: {
+                readonly line: number;
+                readonly column: number;
+            };
+        };
     };
     /** Âncora de documentação. */
     readonly docs?: string;
@@ -37,4 +61,4 @@ declare function explain(ast: BaseNode, result: CheckResult): ExplainedDiagnosti
 /** O `help` de um diagnóstico isolado, dado o mapa de pais (ou `undefined`). */
 declare function helpFor(d: Diagnostic, parents: WeakMap<BaseNode, BaseNode>): DiagnosticHelp | undefined;
 
-export { type DiagnosticHelp, type ExplainedDiagnostic, type HelpCategory, type JsIsmReason, explain, helpFor };
+export { type DiagnosticHelp, type ExplainedDiagnostic, type HelpCategory, type HelpReason, type JsIsmReason, explain, helpFor };

package/dist/index.d.ts

@@ -3,6 +3,15 @@ import { Diagnostic, CheckResult } from '@tslite/checker';
 
 /** Por que o erro aconteceu — a "raiz JS-ism" que o help explica. */
 type JsIsmReason = "proto-member" | "no-new" | "no-class" | "no-this" | "no-function-expr" | "forbidden-substrate";
+/**
+ * A chave estável de i18n (ver E2).
+ *
+ * Houve aqui um `SyntaxGapReason` (`type-args-not-supported`), mitigação para
+ * `f<T>(x)` não existir na gramática. **Saiu porque a lacuna foi fechada** — hoje
+ * o parser lê argumento de tipo de verdade (parser TODO / checker TC27). A
+ * categoria volta quando houver um buraco de gramática real para descrever.
+ */
+type HelpReason = JsIsmReason;
 /** A CLASSE do porquê — deixa uma UI didática renderizar diferente de erro de tipo. */
 type HelpCategory = "js-ism" | "portability" | "capability-off";
 /** O help auxiliar: prosa explicativa + sugestão + auto-fix aplicável (por IA/editor).
@@ -10,16 +19,31 @@ type HelpCategory = "js-ism" | "portability" | "capability-off";
  *  mensagens do checker). `reason` é a CHAVE estável de tradução: um add-on de i18n no
  *  frontend mapeia `reason` (+ os campos estruturados) → idioma, sem tocar isto. */
 interface DiagnosticHelp {
-    readonly reason: JsIsmReason;
+    readonly reason: HelpReason;
     readonly category: HelpCategory;
     /** "Why this is NOT a language bug" — default prose (English). */
     readonly explain: string;
     /** The correct idiom (e.g. "Use the `length(xs)` operator"). */
     readonly suggestion?: string;
-    /** Reescrita mecânica: `from` → `to` (aplicável por code-action ou por uma IA). */
+    /**
+     * Reescrita mecânica: `from` → `to` (aplicável por code-action ou por uma IA).
+     * `range` é o trecho EXATO a substituir (convenção TSLite: linha 1-based, coluna
+     * 0-based, fim exclusivo) — presente só quando o nó tem `loc`, isto é, quando o
+     * AST veio de autoria TEXTUAL. Em AST de builders (nocode) não há posição.
+     */
     readonly fix?: {
         readonly from: string;
         readonly to: string;
+        readonly range?: {
+            readonly start: {
+                readonly line: number;
+                readonly column: number;
+            };
+            readonly end: {
+                readonly line: number;
+                readonly column: number;
+            };
+        };
     };
     /** Âncora de documentação. */
     readonly docs?: string;
@@ -37,4 +61,4 @@ declare function explain(ast: BaseNode, result: CheckResult): ExplainedDiagnosti
 /** O `help` de um diagnóstico isolado, dado o mapa de pais (ou `undefined`). */
 declare function helpFor(d: Diagnostic, parents: WeakMap<BaseNode, BaseNode>): DiagnosticHelp | undefined;
 
-export { type DiagnosticHelp, type ExplainedDiagnostic, type HelpCategory, type JsIsmReason, explain, helpFor };
+export { type DiagnosticHelp, type ExplainedDiagnostic, type HelpCategory, type HelpReason, type JsIsmReason, explain, helpFor };

package/dist/index.js

@@ -1 +1 @@
-import {walk}from'@tslite/core';import {print}from'@tslite/printer';import {jsMethodReplacements,knownProtoMembersWithoutOperator}from'@tslite/operators';var i="checker D9 / docs/SCOPE-BOUNDARY.md";function h(e,t){let n=T(e);return t.diagnostics.map(s=>{let o=u(s,n);return o?{...s,help:o}:s})}function u(e,t){let n=e.node;switch(n.type){case "NewExpression":return B(n);case "ClassDeclaration":case "ClassExpression":return k();case "FunctionDeclaration":case "FunctionExpression":return O();case "ThisExpression":return E();case "MemberExpression":return e.code==="forbidden-member"?D(n):x(e,n,t)}}function x(e,t,n){if(e.code!=="no-such-member"&&e.code!=="not-object")return;let s=l(t);if(!s)return;let o=jsMethodReplacements[s];if(o)return w(t,s,o,n);if(knownProtoMembersWithoutOperator.has(s))return N(s)}function w(e,t,n,s){let o=print(e.object),a=s.get(e),c=a?.type==="CallExpression"&&a.callee===e,d=c?a.arguments.map(m=>print(m)):[],p=n.call(o,d),g=print(c?a:e);return {reason:"proto-member",category:"portability",explain:`${n.on==="array"?"Arrays":n.on==="string"?"Strings":"Values"} in TSL have no \`.${t}\` method (prototype member). TSL is FP-first and PORTABLE: \`.${t}\` does not translate cleanly to the target (in Python, for instance, it is a function). This is not a language bug \u2014 it is the model.`,suggestion:`Use the \`${n.operator}\` operator (@tslite/operators): \`${p}\`.`,fix:{from:g,to:p},docs:i}}function N(e){return {reason:"proto-member",category:"portability",explain:`\`.${e}\` is a JS prototype method/property \u2014 TSL is FP-first and immutable, so array/string/object methods are not vocabulary. This is not a language bug \u2014 it is the model.`,suggestion:"Rewrite it functionally with @tslite/operators (map/filter/reduce/\u2026), or use the imperative capability if you truly need to mutate.",docs:i}}function D(e){return {reason:"forbidden-substrate",category:"js-ism",explain:`\`.${l(e)??"constructor/prototype/__proto__"}\` is JS runtime substrate (inheritance/prototype) \u2014 it does not exist in TSL, which is FP-first and portable. Forbidden by identity + portability (and it closes the sandbox escape). This is not a language bug \u2014 it is the model.`,docs:i}}function B(e){let t=e.callee,n=t?.type==="Identifier"?t.name:"X";return {reason:"no-new",category:"js-ism",explain:"TSL has no `new` and no classes \u2014 it is FP-first (no OO). `new` was removed on purpose: native capabilities come in as FACTORY functions via DI. Not a language bug.",suggestion:`Inject a factory and call \`${n.charAt(0).toLowerCase()+n.slice(1)}(\u2026)\` instead of \`new ${n}(\u2026)\`.`,docs:i}}function k(){return {reason:"no-class",category:"js-ism",explain:"`class` does not exist in TSL \u2014 it is FP-first, no OO. An instance is just an object with props; behavior comes from functions. This is not a language bug \u2014 it is the model.",suggestion:'Model with objects + functions (a factory function via DI for "methods").',docs:i}}function E(){return {reason:"no-this",category:"js-ism",explain:"`this` does not exist in TSL \u2014 no OO, no implicit receiver. This is not a language bug \u2014 it is the model.",suggestion:"Pass the data as an explicit ARGUMENT instead of `this`.",docs:i}}function O(){return {reason:"no-function-expr",category:"js-ism",explain:"Only ARROW functions are functions in TSL (`(x) => \u2026`). `function(){}` is out (it brings `this`/`arguments`/construction \u2014 OO substrate). This is not a language bug \u2014 it is the model.",suggestion:"Use an arrow: `const f = (x) => \u2026`.",docs:i}}function l(e){if(!e.computed)return e.property.name;let t=e.property;return t.type==="Literal"&&typeof t.value=="string"?t.value:void 0}function T(e){let t=new WeakMap;return walk(e,{"*":(n,s)=>{s&&t.set(n,s);}}),t}export{h as explain,u as helpFor};
+import {walk}from'@tslite/core';import {print}from'@tslite/printer';import {jsMethodReplacements,knownProtoMembersWithoutOperator}from'@tslite/operators';var a="checker D9 / docs/SCOPE-BOUNDARY.md";function w(e,n){let t=M(e);return n.diagnostics.map(o=>{let s=m(o,t);return s?{...o,help:s}:o})}function m(e,n){let t=e.node;switch(t.type){case "NewExpression":return E(t);case "ClassDeclaration":case "ClassExpression":return O();case "FunctionDeclaration":case "FunctionExpression":return T();case "ThisExpression":return H();case "MemberExpression":return e.code==="forbidden-member"?k(t):N(e,t,n)}}function N(e,n,t){if(e.code!=="no-such-member"&&e.code!=="not-object")return;let o=g(n);if(!o)return;let s=jsMethodReplacements[o];if(s)return D(n,o,s,t);if(knownProtoMembersWithoutOperator.has(o))return B(o)}function D(e,n,t,o){let s=print(e.object),i=o.get(e),l=i?.type==="CallExpression"&&i.callee===e,y=l?i.arguments.map(f=>print(f)):[],r=l?i:e,c=t.call(s,y),u=print(r),d=r.loc?{start:r.loc.start,end:r.loc.end}:void 0;return {reason:"proto-member",category:"portability",explain:`${t.on==="array"?"Arrays":t.on==="string"?"Strings":"Values"} in TSL have no \`.${n}\` method (prototype member). TSL is FP-first and PORTABLE: \`.${n}\` does not translate cleanly to the target (in Python, for instance, it is a function). This is not a language bug \u2014 it is the model.`,suggestion:`Use the \`${t.operator}\` operator (@tslite/operators): \`${c}\`.`,fix:d?{from:u,to:c,range:d}:{from:u,to:c},docs:a}}function B(e){return {reason:"proto-member",category:"portability",explain:`\`.${e}\` is a JS prototype method/property \u2014 TSL is FP-first and immutable, so array/string/object methods are not vocabulary. This is not a language bug \u2014 it is the model.`,suggestion:"Rewrite it functionally with @tslite/operators (map/filter/reduce/\u2026), or use the imperative capability if you truly need to mutate.",docs:a}}function k(e){return {reason:"forbidden-substrate",category:"js-ism",explain:`\`.${g(e)??"constructor/prototype/__proto__"}\` is JS runtime substrate (inheritance/prototype) \u2014 it does not exist in TSL, which is FP-first and portable. Forbidden by identity + portability (and it closes the sandbox escape). This is not a language bug \u2014 it is the model.`,docs:a}}function E(e){let n=e.callee,t=n?.type==="Identifier"?n.name:"X";return {reason:"no-new",category:"js-ism",explain:"TSL has no `new` and no classes \u2014 it is FP-first (no OO). `new` was removed on purpose: native capabilities come in as FACTORY functions via DI. Not a language bug.",suggestion:`Inject a factory and call \`${t.charAt(0).toLowerCase()+t.slice(1)}(\u2026)\` instead of \`new ${t}(\u2026)\`.`,docs:a}}function O(){return {reason:"no-class",category:"js-ism",explain:"`class` does not exist in TSL \u2014 it is FP-first, no OO. An instance is just an object with props; behavior comes from functions. This is not a language bug \u2014 it is the model.",suggestion:'Model with objects + functions (a factory function via DI for "methods").',docs:a}}function H(){return {reason:"no-this",category:"js-ism",explain:"`this` does not exist in TSL \u2014 no OO, no implicit receiver. This is not a language bug \u2014 it is the model.",suggestion:"Pass the data as an explicit ARGUMENT instead of `this`.",docs:a}}function T(){return {reason:"no-function-expr",category:"js-ism",explain:"Only ARROW functions are functions in TSL (`(x) => \u2026`). `function(){}` is out (it brings `this`/`arguments`/construction \u2014 OO substrate). This is not a language bug \u2014 it is the model.",suggestion:"Use an arrow: `const f = (x) => \u2026`.",docs:a}}function g(e){if(!e.computed)return e.property.name;let n=e.property;return n.type==="Literal"&&typeof n.value=="string"?n.value:void 0}function M(e){let n=new WeakMap;return walk(e,{"*":(t,o)=>{o&&n.set(t,o);}}),n}export{w as explain,m as helpFor};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tslite/explain",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "TSLite explain — enriches type-check diagnostics with 'why it is NOT a language bug' help for JS/OO habits (proto members, new, class), with operator suggestions and auto-fixes",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -40,13 +40,13 @@
   },
   "dependencies": {
     "@tslite/core": "0.2.0",
-    "@tslite/checker": "0.2.1",
     "@tslite/printer": "0.2.0",
-    "@tslite/operators": "0.2.1",
-    "@tslite/type-core": "0.2.0"
+    "@tslite/checker": "0.3.0",
+    "@tslite/type-core": "0.3.0",
+    "@tslite/operators": "0.3.0"
   },
   "devDependencies": {
-    "@tslite/parser": "0.2.0"
+    "@tslite/parser": "0.3.0"
   },
   "scripts": {
     "build": "tsup",