@tslite/explain 0.2.0

package/dist/index.cjs

@@ -0,0 +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;

package/dist/index.d.cts

@@ -0,0 +1,40 @@
+import { BaseNode } from '@tslite/core';
+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 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).
+ *  A prosa (`explain`/`suggestion`) é o DEFAULT em inglês (convenção da casa, como as
+ *  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 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). */
+    readonly fix?: {
+        readonly from: string;
+        readonly to: string;
+    };
+    /** Âncora de documentação. */
+    readonly docs?: string;
+}
+/** Um diagnóstico do checker, possivelmente enriquecido com `help` (aditivo). */
+type ExplainedDiagnostic = Diagnostic & {
+    readonly help?: DiagnosticHelp;
+};
+/**
+ * Enriquece os diagnósticos de um `CheckResult` com `help` onde o erro é um JS-ism
+ * reconhecível. `ast` é a MESMA raiz que foi checada (pra achar pais/nós). Os
+ * diagnósticos sem JS-ism reconhecido passam intactos.
+ */
+declare function explain(ast: BaseNode, result: CheckResult): ExplainedDiagnostic[];
+/** 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 };

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import { BaseNode } from '@tslite/core';
+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 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).
+ *  A prosa (`explain`/`suggestion`) é o DEFAULT em inglês (convenção da casa, como as
+ *  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 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). */
+    readonly fix?: {
+        readonly from: string;
+        readonly to: string;
+    };
+    /** Âncora de documentação. */
+    readonly docs?: string;
+}
+/** Um diagnóstico do checker, possivelmente enriquecido com `help` (aditivo). */
+type ExplainedDiagnostic = Diagnostic & {
+    readonly help?: DiagnosticHelp;
+};
+/**
+ * Enriquece os diagnósticos de um `CheckResult` com `help` onde o erro é um JS-ism
+ * reconhecível. `ast` é a MESMA raiz que foi checada (pra achar pais/nós). Os
+ * diagnósticos sem JS-ism reconhecido passam intactos.
+ */
+declare function explain(ast: BaseNode, result: CheckResult): ExplainedDiagnostic[];
+/** 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 };

package/dist/index.js

@@ -0,0 +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};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@tslite/explain",
+  "version": "0.2.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",
+  "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/explain"
+  },
+  "keywords": [
+    "typescript",
+    "diagnostics",
+    "developer-experience",
+    "error-messages",
+    "quickfix",
+    "functional-programming"
+  ],
+  "author": "Anderson D. Rosa <andersondrosa@outlook.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@tslite/core": "0.1.0",
+    "@tslite/type-core": "0.2.0",
+    "@tslite/checker": "0.2.0",
+    "@tslite/operators": "0.2.0",
+    "@tslite/printer": "0.1.0"
+  },
+  "devDependencies": {
+    "@tslite/parser": "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",
+    "lint:fix": "eslint src --fix",
+    "clean": "rm -rf dist",
+    "format": "prettier --write \"{src,tests}/**/*.ts\"",
+    "format:check": "prettier --check \"{src,tests}/**/*.ts\""
+  }
+}