tjs-lang 0.7.6 → 0.7.8

package/dist/src/lang/bool-coercion.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Boolean coercion rewriter.
+ *
+ * Fixes the JS footgun `Boolean(new Boolean(false)) === true` (and friends)
+ * by rewriting every truthiness context to call `__tjs.toBool(x)`, which
+ * unwraps boxed primitives before coercing.
+ *
+ * Contexts rewritten:
+ *   if (cond)           → if (__tjs.toBool(cond))
+ *   while (cond)        → while (__tjs.toBool(cond))
+ *   do {} while (cond)  → do {} while (__tjs.toBool(cond))
+ *   for (_; cond; _)    → for (_; __tjs.toBool(cond); _)
+ *   !x                  → !__tjs.toBool(x)
+ *   a && b              → ((__tjs__t)=>__tjs.toBool(__tjs__t)?(b):__tjs__t)(a)
+ *   a || b              → ((__tjs__t)=>__tjs.toBool(__tjs__t)?__tjs__t:(b))(a)
+ *   a ? b : c           → __tjs.toBool(a)?(b):(c)
+ *   Boolean(x)          → __tjs.toBool(x)        (call form, not `new`)
+ *
+ * `??` (nullish coalescing) is intentionally NOT rewritten — its semantics
+ * are about null/undefined specifically, not truthiness, so boxed primitives
+ * behave correctly already.
+ *
+ * `===` / `!==` (identity) are also not touched — that's a separate
+ * footgun handled by the `Is` / `Eq` operators under TjsEquals.
+ *
+ * Always-on under TjsStandard.
+ */
+import type { Program } from 'acorn';
+export interface BoolCoercionPatch {
+    start: number;
+    end: number;
+    newText: string;
+}
+/**
+ * Walk the AST and emit replacement patches for every truthiness context.
+ * Patches are pre-deduped: nested coercions inside an outer patch are
+ * folded into the outer patch's newText, so returned patches don't overlap.
+ */
+export declare function rewriteBoolCoercion(ast: Program, source: string): BoolCoercionPatch[];
+/**
+ * Source-text wrapper: parse, rewrite, re-emit. Used for code that's
+ * extracted before the main parse (test/mock bodies) but still needs the
+ * coercion rewrite to behave consistently with the rest of the module.
+ *
+ * Wraps the body in a function so top-level statements like `expect(...)`
+ * parse as a Program. Returns the original source unchanged if parsing
+ * fails (rather than throwing — a bad test body would already have been
+ * caught by the main parse).
+ */
+export declare function rewriteBoolCoercionInSource(source: string): string;

package/dist/src/lang/docs.d.ts

@@ -4,10 +4,13 @@
  * Dead simple: walk source in order, emit what you find.
  * - Doc blocks render as markdown
  * - Function signatures render as code blocks
+ * - Inline `test 'name' { ... }` blocks render as "Test Cases" section
+ *   with `expect(...).toBe(...)` style assertions translated to comments
  *
  * No magic pairing. No attachment logic. The signature IS the docs.
  * Doc blocks are just editorial commentary when you need it.
  */
+import type { TypeDescriptor } from './types';
 export interface DocResult {
     /** Items in document order */
     items: DocItem[];
@@ -21,6 +24,11 @@ export type DocItem = {
     type: 'function';
     name: string;
     signature: string;
+} | {
+    type: 'class';
+    name: string;
+    extendsName?: string;
+    members: string[];
 };
 /**
  * Generate documentation from TJS source
@@ -33,9 +41,7 @@ export declare function generateDocs(source: string): DocResult;
  * Type metadata for a function parameter
  */
 export interface ParamTypeInfo {
-    type?: {
-        kind: string;
-    };
+    type?: TypeDescriptor;
     required?: boolean;
     example?: any;
 }
@@ -44,9 +50,7 @@ export interface ParamTypeInfo {
  */
 export interface FunctionTypeInfo {
     params?: Record<string, ParamTypeInfo>;
-    returns?: {
-        kind: string;
-    };
+    returns?: TypeDescriptor;
 }
 /**
  * Generate markdown documentation with type metadata
@@ -67,3 +71,24 @@ export interface FunctionTypeInfo {
  * ```
  */
 export declare function generateDocsMarkdown(source: string, types?: Record<string, FunctionTypeInfo>): string;
+/**
+ * Translate `expect(actual).matcher(expected)` calls into inline comments
+ * for documentation rendering. Other lines (setup, console.log, etc.) are
+ * preserved as-is.
+ *
+ *   expect(x).toBe(y)         → x  // → y
+ *   expect(x).toEqual(y)      → x  // ≡ y  (deep equality)
+ *   expect(x).toBeTruthy()    → x  // → truthy
+ *   expect(x).toBeFalsy()     → x  // → falsy
+ *   expect(x).toBeNull()      → x  // → null
+ *   expect(x).toBeUndefined() → x  // → undefined
+ *   expect(x).toContain(y)    → x  // → contains y
+ *   expect(x).toThrow()       → x  // → throws
+ *   expect(x).toBeGreaterThan(n) → x  // → > n
+ *   expect(x).toBeLessThan(n)    → x  // → < n
+ *   expect(x).toBeNaN()       → x  // → NaN
+ *
+ * Uses balanced-paren scanning so nested calls (`expect(f(a, b)).toBe(c)`)
+ * work correctly.
+ */
+export declare function prettifyTestBody(body: string): string;

package/dist/src/lang/linter.d.ts

@@ -29,8 +29,16 @@ export interface LintOptions {
     unreachableCode?: boolean;
     /** Warn about explicit `new` keyword usage (TJS makes classes callable without new) */
     noExplicitNew?: boolean;
+    /**
+     * Check `let` declarations for missing type information and forbid literal
+     * undefined/null assignments to typed lets. If undefined, the parser's
+     * `TjsSafeAssign` mode controls whether the rule runs.
+     */
+    safeAssign?: boolean;
     /** Filename for error messages */
     filename?: string;
+    /** Treat safeAssign violations as errors instead of warnings (TjsStrict semantics) */
+    strict?: boolean;
 }
 /**
  * Lint TJS source code

package/dist/src/lang/parser-transforms.d.ts

@@ -309,3 +309,21 @@ export declare function validateNoEval(source: string): string;
  * Otherwise, performs a bare property access (throws as usual).
  */
 export declare function transformBangAccess(source: string): string;
+/**
+ * Transform `let x: <example>` and `let x: <example> = value` declarations.
+ *
+ * Strips the `: <example>` annotation so Acorn can parse, and records the
+ * variable name + example text so the linter and (later) type inference can
+ * use the annotation. Acorn rejects the colon since it is not valid JS.
+ *
+ *   let x: ''           → let x         (annotation: x → '')
+ *   let x: 0 = 5        → let x = 5     (annotation: x → 0)
+ *   let result: { ok: false } = ...     (annotation: result → { ok: false })
+ *
+ * Only `let` is processed. `const` always has an initializer, so the type
+ * is always inferable. `var` is rejected by TjsNoVar mode.
+ */
+export declare function transformLetTypeAnnotations(source: string): {
+    source: string;
+    annotations: Map<string, string>;
+};

package/dist/src/lang/parser-types.d.ts

@@ -124,6 +124,8 @@ export interface TjsModes {
     tjsSafeEval: boolean;
     /** TjsNoVar: var declarations are syntax errors */
     tjsNoVar: boolean;
+    /** TjsSafeAssign: let declarations need an initializer or `: example` annotation; literal undefined/null/void 0 assigned to typed lets is flagged */
+    tjsSafeAssign: boolean;
 }
 /**
  * Extension info for a single extend block

package/dist/src/lang/parser.d.ts

@@ -8,6 +8,12 @@ import type { Program, FunctionDeclaration } from 'acorn';
 export type { ParseOptions, WasmBlock, TestBlock, PreprocessOptions, TjsModes, } from './parser-types';
 import type { ParseOptions, WasmBlock, TestBlock, PreprocessOptions, TjsModes } from './parser-types';
 export { transformExtensionCalls } from './parser-transforms';
+/**
+ * Strip single-line comments (//) from source.
+ * Replaces comment content with spaces to preserve character offsets.
+ * Skips // inside strings and block comments.
+ */
+export declare function stripLineComments(source: string): string;
 export declare function preprocess(source: string, options?: PreprocessOptions): {
     source: string;
     returnType?: string;
@@ -23,6 +29,7 @@ export declare function preprocess(source: string, options?: PreprocessOptions):
     testErrors: string[];
     polymorphicNames: Set<string>;
     extensions: Map<string, Set<string>>;
+    letAnnotations: Map<string, string>;
 };
 /**
  * Parse source code into an Acorn AST
@@ -39,6 +46,8 @@ export declare function parse(source: string, options?: ParseOptions): {
     wasmBlocks: WasmBlock[];
     tests: TestBlock[];
     testErrors: string[];
+    letAnnotations: Map<string, string>;
+    tjsModes: TjsModes;
 };
 /**
  * Validate that the source contains exactly one function declaration

package/dist/src/lang/runtime.d.ts

@@ -226,6 +226,16 @@ export declare function IsNot(a: unknown, b: unknown): boolean;
  * Usage: `typeof x` with TjsEquals transforms to `TypeOf(x)`
  */
 export declare function TypeOf(value: unknown): string;
+/**
+ * Honest boolean coercion. Like `Boolean(x)` but unwraps boxed primitives
+ * first, fixing the JS footgun `Boolean(new Boolean(false)) === true`.
+ *
+ * Under TjsStandard, the source rewriter wraps every truthiness context
+ * (if/while/for/do-while conditions, `!`, `&&`, `||`, ternary, and
+ * top-level `Boolean(x)` calls) with this function so a boxed `false`
+ * actually behaves as `false`.
+ */
+export declare function toBool(value: unknown): boolean;
 export declare function Eq(a: unknown, b: unknown): boolean;
 /**
  * Honest inequality — what != should have been.
@@ -291,6 +301,26 @@ type TypeSpec = string | {
     check: (v: unknown) => boolean | string;
     description: string;
 };
+/**
+ * Check that a passed-in function's declared shape matches the expected
+ * shape. Returns the function unchanged on a match, or a MonadicError on
+ * mismatch. Untyped functions (no `__tjs` metadata — anonymous arrows
+ * like `x => false`) pass through unchanged on the assumption that the
+ * caller knows what they're doing; they accept any args and return
+ * whatever they return.
+ *
+ * This is a ONE-SHOT check at pass time, NOT a per-call wrapper. The TJS
+ * design call: a wrong-shape callback is ONE error at the boundary, not
+ * N errors when the receiving function invokes the callback N times.
+ *
+ * Compatibility rules (deliberately permissive — strict subtyping is a
+ * separate, larger feature):
+ *   - For each expected param: the actual function may declare fewer
+ *     params (extras simply not used). If both declare a kind, they
+ *     must match exactly. Either side being `any` always matches.
+ *   - For the return type: same exact-match rule when both are known.
+ */
+export declare function checkFnShape(fn: unknown, expectedParamKinds: string[], expectedReturnKind: string, path: string): unknown;
 /** Parameter metadata with optional location */
 interface ParamMeta {
     type: TypeSpec;
@@ -376,6 +406,7 @@ export declare function createRuntime(): {
     checkType: typeof checkType;
     validateArgs: typeof validateArgs;
     wrap: typeof wrap;
+    checkFnShape: typeof checkFnShape;
     wrapClass: typeof wrapClass;
     compareVersions: typeof compareVersions;
     versionsCompatible: typeof versionsCompatible;
@@ -419,6 +450,7 @@ export declare function createRuntime(): {
     Eq: typeof Eq;
     NotEq: typeof NotEq;
     TypeOf: typeof TypeOf;
+    toBool: typeof toBool;
     tjsEquals: symbol;
     registerExtension: (typeName: string, methodName: string, fn: (...args: any[]) => any) => void;
     resolveExtension: (value: unknown, methodName: string) => ((...args: any[]) => any) | undefined;
@@ -444,6 +476,7 @@ export declare const runtime: {
     checkType: typeof checkType;
     validateArgs: typeof validateArgs;
     wrap: typeof wrap;
+    checkFnShape: typeof checkFnShape;
     wrapClass: typeof wrapClass;
     compareVersions: typeof compareVersions;
     versionsCompatible: typeof versionsCompatible;
@@ -489,6 +522,7 @@ export declare const runtime: {
     Eq: typeof Eq;
     NotEq: typeof NotEq;
     TypeOf: typeof TypeOf;
+    toBool: typeof toBool;
 };
 /**
  * Install runtime globally (idempotent, version-checked)

package/dist/src/lang/types.d.ts

@@ -5,7 +5,7 @@ import type { Node } from 'acorn';
 import type { SeqNode } from '../builder';
 /** Represents a type extracted from value patterns */
 export interface TypeDescriptor {
-    kind: 'string' | 'number' | 'integer' | 'non-negative-integer' | 'boolean' | 'null' | 'undefined' | 'array' | 'object' | 'union' | 'any';
+    kind: 'string' | 'number' | 'integer' | 'non-negative-integer' | 'boolean' | 'null' | 'undefined' | 'array' | 'object' | 'union' | 'function' | 'any';
     nullable?: boolean;
     /** For arrays: the element type */
     items?: TypeDescriptor;
@@ -15,6 +15,14 @@ export interface TypeDescriptor {
     members?: TypeDescriptor[];
     /** For destructured parameters: full parameter descriptors */
     destructuredParams?: Record<string, ParameterDescriptor>;
+    /** For functions: declared parameters with names and inferred types */
+    params?: Array<{
+        name: string;
+        type: TypeDescriptor;
+    }>;
+    /** For functions: inferred return type. Concise arrow bodies infer from
+     * the expression; block bodies and complex expressions stay `any`. */
+    returns?: TypeDescriptor;
 }
 /** Describes a function parameter */
 export interface ParameterDescriptor {

package/dist/src/rbac/index.d.ts

@@ -1,5 +1,5 @@
 import type { Store } from '../store/interface';
-export { evaluateAccessShortcut, selectAccessRule, validateSchema, interpretRuleResult, hasRoleLevel, buildRuleContext, } from './rules.js';
+export { evaluateAccessShortcut, selectAccessRule, validateSchema, interpretRuleResult, hasRoleLevel, buildRuleContext, } from './rules.tjs';
 /**
  * Security rule definition
  */

package/dist/src/vm/runtime.d.ts

@@ -149,7 +149,7 @@ export type ExprNode = {
 } | {
     $expr: 'member';
     object: ExprNode;
-    property: string;
+    property: string | ExprNode;
     computed?: boolean;
     optional?: boolean;
 } | {