rbtr-lang-javascript 2026.9.0.dev0__py3-none-any.whl

rbtr_lang_javascript/tests/cases_docstrings.py

@@ -0,0 +1,225 @@
+"""JavaScript / TypeScript docstring-extraction test cases.
+
+Each `@case` returns `(lang, source, symbol_name, snippet)` consumed by
+`test_docstrings.py`; tags drive the documented/undocumented assertion.
+"""
+
+from __future__ import annotations
+
+from pytest_cases import case
+
+type DocstringCase = tuple[str, str, str, str]
+
+
+@case(tags=["documented", "canonical", "exterior_doc"])
+def case_js_jsdoc_on_function() -> DocstringCase:
+    """Canonical JSDoc above a function declaration."""
+    src = """\
+/** Return a friendly greeting. */
+function greet() {}
+"""
+    return "javascript", src, "greet", "Return a friendly greeting"
+
+
+@case(tags=["documented", "canonical", "exterior_doc"])
+def case_js_jsdoc_on_class() -> DocstringCase:
+    """Canonical JSDoc above a class declaration."""
+    src = """\
+/** A widget. */
+class Widget {}
+"""
+    return "javascript", src, "Widget", "A widget"
+
+
+@case(tags=["documented", "canonical", "exterior_doc"])
+def case_js_jsdoc_on_arrow_function() -> DocstringCase:
+    """Arrow-function assignment — the `@function` capture
+    lands on the `lexical_declaration`, so JSDoc attaches via
+    the walk on that node's prev_named_sibling.
+    """
+    src = """\
+/** Increment. */
+const inc = (x) => x + 1;
+"""
+    return "javascript", src, "inc", "Increment"
+
+
+@case(tags=["documented", "edge_case", "exterior_doc"])
+def case_js_multiline_jsdoc() -> DocstringCase:
+    """Multi-line JSDoc with leading `*` gutter."""
+    src = """\
+/**
+ * Compute a checksum over *data*.
+ *
+ * The algorithm is CRC32 — explained below.
+ */
+function checksum(data) { return 0; }
+"""
+    return "javascript", src, "checksum", "The algorithm is CRC32"
+
+
+@case(tags=["documented", "edge_case", "exterior_doc"])
+def case_js_banner_comment() -> DocstringCase:
+    """`/*! ... */` banner comments are common in bundled UMD
+    libs; the grammar lands them as `comment` nodes and we
+    attach them — the benchmark will say whether that hurts.
+    """
+    src = """\
+/*! (c) 2024 Acme. */
+function publicApi() {}
+"""
+    return "javascript", src, "publicApi", "(c) 2024 Acme"
+
+
+@case(tags=["documented", "unconventional", "exterior_doc"])
+def case_js_line_comment_run() -> DocstringCase:
+    """`//` comment runs used as docs — common in TS-first
+    code where JSDoc is syntactically less convenient.
+    """
+    src = """\
+// First description line.
+// Second description line.
+function documented() {}
+"""
+    return "javascript", src, "documented", "First description line"
+
+
+@case(tags=["undocumented", "no_docs"])
+def case_js_function_without_doc() -> DocstringCase:
+    """Plain function, no comments."""
+    src = """\
+function bare() {}
+"""
+    return "javascript", src, "bare", "PHANTOM_DOC_TEXT_SHOULD_NEVER_APPEAR"
+
+
+@case(tags=["undocumented", "boundary_not_attached"])
+def case_js_jsdoc_detached_by_blank_line() -> DocstringCase:
+    """A blank line between the JSDoc block and the function
+    breaks attachment.
+    """
+    src = """\
+/** Stale JSDoc — not attached. */
+
+function stale() {}
+"""
+    return "javascript", src, "stale", "Stale JSDoc"
+
+
+@case(tags=["undocumented", "invalid"])
+def case_js_jsdoc_above_import_does_not_attach_to_class() -> DocstringCase:
+    """JSDoc above an `import` stays on the import line.  A
+    class several statements later must *not* inherit it.
+    Imports are excluded from attachment by design (see
+    `treesitter.extract_symbols`).
+    """
+    src = """\
+/** Nonsense JSDoc above import. */
+import { x } from './x';
+
+class Real {}
+"""
+    return "javascript", src, "Real", "Nonsense JSDoc"
+
+
+@case(tags=["documented", "canonical", "exterior_doc"])
+def case_ts_jsdoc_on_function() -> DocstringCase:
+    """Canonical JSDoc above a typed function declaration."""
+    src = """\
+/** Return the length of *s*. */
+function len(s: string): number { return s.length; }
+"""
+    return "typescript", src, "len", "Return the length"
+
+
+@case(tags=["documented", "canonical", "exterior_doc"])
+def case_ts_jsdoc_on_class() -> DocstringCase:
+    """JSDoc above a TypeScript class — grammar uses
+    `type_identifier` for the class name.
+    """
+    src = """\
+/** A widget. */
+class Widget {}
+"""
+    return "typescript", src, "Widget", "A widget"
+
+
+@case(tags=["documented", "canonical", "exterior_doc"])
+def case_ts_jsdoc_on_arrow_function() -> DocstringCase:
+    """Arrow-function assignment with a type annotation."""
+    src = """\
+/** Increment. */
+const inc: (x: number) => number = (x) => x + 1;
+"""
+    return "typescript", src, "inc", "Increment"
+
+
+@case(tags=["documented", "edge_case", "exterior_doc"])
+def case_ts_jsdoc_on_generic_function() -> DocstringCase:
+    """Generic type parameters between name and arguments."""
+    src = """\
+/** Identity. */
+function identity<T>(x: T): T { return x; }
+"""
+    return "typescript", src, "identity", "Identity"
+
+
+@case(tags=["documented", "edge_case", "exterior_doc"])
+def case_ts_multiline_jsdoc_with_tags() -> DocstringCase:
+    """Multi-line JSDoc with `@param` / `@returns` tags."""
+    src = """\
+/**
+ * Compute a hash.
+ *
+ * @param data bytes to hash
+ * @returns hex digest
+ */
+function hash(data: Uint8Array): string { return ''; }
+"""
+    return "typescript", src, "hash", "@returns hex digest"
+
+
+@case(tags=["documented", "unconventional", "exterior_doc"])
+def case_ts_line_comment_run() -> DocstringCase:
+    """`//` comment runs used as docs, common in TS-heavy
+    codebases that avoid JSDoc because types are already in
+    the signature.
+    """
+    src = """\
+// Describe the value.
+// Useful in calling code.
+function describe(x: number): string { return String(x); }
+"""
+    return "typescript", src, "describe", "Describe the value"
+
+
+@case(tags=["undocumented", "no_docs"])
+def case_ts_function_without_doc() -> DocstringCase:
+    """Plain TS function."""
+    src = """\
+function bare(x: number): number { return x; }
+"""
+    return "typescript", src, "bare", "PHANTOM_DOC_TEXT_SHOULD_NEVER_APPEAR"
+
+
+@case(tags=["undocumented", "boundary_not_attached"])
+def case_ts_jsdoc_detached_by_blank_line() -> DocstringCase:
+    """Blank line breaks attachment for TS too."""
+    src = """\
+/** Stale JSDoc. */
+
+function stale(): void {}
+"""
+    return "typescript", src, "stale", "Stale JSDoc"
+
+
+@case(tags=["undocumented", "invalid"])
+def case_ts_jsdoc_above_import() -> DocstringCase:
+    """JSDoc above `import` does not attach to a later class."""
+    src = """\
+/** Nonsense JSDoc. */
+import { x } from './x';
+
+class Real {}
+"""
+    return "typescript", src, "Real", "Nonsense JSDoc"

rbtr_lang_javascript/tests/cases_extraction.py

@@ -0,0 +1,429 @@
+"""JavaScript / TypeScript / TSX extraction test cases.
+
+Each `@case` returns test data consumed by `test_extraction.py` via
+`pytest-cases`. See the plugin docstring for the source→chunk mapping.
+"""
+
+from __future__ import annotations
+
+import pytest
+from pytest_cases import case
+
+type SymbolCase = tuple[str, str, list[tuple[str, str, str]]]
+type ImportCase = tuple[str, str, dict[str, str]]
+type MultiImportCase = tuple[str, str, int, list[dict[str, str]]]
+type MixedCase = tuple[str, str, set[str], list[tuple[str, str]]]
+
+_xfail_nested = pytest.mark.xfail(
+    reason="nested/chained destructuring unsupported — no query-only recursion",
+    strict=True,
+)
+
+
+@case(tags=["symbol"])
+def case_js_function_declaration() -> SymbolCase:
+    """function greet() {}."""
+    return "javascript", "function greet() {}\n", [("function", "greet", "")]
+
+
+@case(tags=["symbol"])
+def case_js_arrow_function() -> SymbolCase:
+    """const add = (a, b) => a + b."""
+    return "javascript", "const add = (a, b) => a + b;\n", [("function", "add", "")]
+
+
+@case(tags=["symbol"])
+def case_js_arrow_function_block() -> SymbolCase:
+    """Arrow function with block body."""
+    src = """\
+const fetch = () => {
+  return data;
+};
+"""
+    return "javascript", src, [("function", "fetch", "")]
+
+
+@case(tags=["symbol"])
+def case_js_multiple_functions() -> SymbolCase:
+    """Multiple function forms."""
+    src = """\
+function a() {}
+function b() {}
+const c = () => {};
+"""
+    return (
+        "javascript",
+        src,
+        [
+            ("function", "a", ""),
+            ("function", "b", ""),
+            ("function", "c", ""),
+        ],
+    )
+
+
+@case(tags=["symbol"])
+def case_js_class() -> SymbolCase:
+    """class User {}."""
+    return "javascript", "class User {}\n", [("class", "User", "")]
+
+
+@case(tags=["symbol"])
+def case_js_class_extends() -> SymbolCase:
+    """class Admin extends User {}."""
+    return "javascript", "class Admin extends User {}\n", [("class", "Admin", "")]
+
+
+@case(tags=["symbol"])
+def case_js_nested_function() -> SymbolCase:
+    """A function nested in a function is addressed by the outer function."""
+    src = """\
+function outer() {
+  function inner() {
+    return 1;
+  }
+  return inner;
+}
+"""
+    return "javascript", src, [("function", "inner", "outer")]
+
+
+@case(tags=["import"])
+def case_js_import_named_single() -> ImportCase:
+    """import { foo } from './models'."""
+    return (
+        "javascript",
+        "import { foo } from './models';\n",
+        {"module": "models", "names": "foo", "dots": "1"},
+    )
+
+
+@case(tags=["import"])
+def case_js_import_named_multiple() -> ImportCase:
+    """import { foo, bar } from './models'."""
+    return (
+        "javascript",
+        "import { foo, bar } from './models';\n",
+        {"module": "models", "names": "foo,bar", "dots": "1"},
+    )
+
+
+@case(tags=["import"])
+def case_js_import_named_parent() -> ImportCase:
+    """import from parent directory."""
+    return (
+        "javascript",
+        "import { Config } from '../config';\n",
+        {"module": "config", "names": "Config", "dots": "2"},
+    )
+
+
+@case(tags=["import"])
+def case_js_import_named_grandparent() -> ImportCase:
+    """import from grandparent directory."""
+    return (
+        "javascript",
+        "import { util } from '../../shared/util';\n",
+        {"module": "shared/util", "names": "util", "dots": "3"},
+    )
+
+
+@case(tags=["import"])
+def case_js_import_default() -> ImportCase:
+    """import React from 'react'."""
+    return "javascript", "import React from 'react';\n", {"module": "react", "names": "React"}
+
+
+@case(tags=["import"])
+def case_js_import_default_relative() -> ImportCase:
+    """import App from './App'."""
+    return (
+        "javascript",
+        "import App from './App';\n",
+        {"module": "App", "names": "App", "dots": "1"},
+    )
+
+
+@case(tags=["import"])
+def case_js_import_namespace() -> ImportCase:
+    """import * as utils from '../utils'."""
+    return (
+        "javascript",
+        "import * as utils from '../utils';\n",
+        {"module": "utils", "names": "utils", "dots": "2"},
+    )
+
+
+@case(tags=["import"])
+def case_js_import_side_effect() -> ImportCase:
+    """import './styles.css' — side-effect only."""
+    return "javascript", "import './styles.css';\n", {"module": "styles", "dots": "1"}
+
+
+@case(tags=["import"])
+def case_js_import_side_effect_no_ext() -> ImportCase:
+    """import './polyfills' — no extension."""
+    return "javascript", "import './polyfills';\n", {"module": "polyfills", "dots": "1"}
+
+
+@case(tags=["import"])
+def case_js_import_package() -> ImportCase:
+    """import express from 'express' — absolute."""
+    return (
+        "javascript",
+        "import express from 'express';\n",
+        {"module": "express", "names": "express"},
+    )
+
+
+@case(tags=["import"])
+def case_js_import_scoped_package() -> ImportCase:
+    """import from scoped npm package."""
+    return (
+        "javascript",
+        "import { render } from '@testing-library/react';\n",
+        {"module": "@testing-library/react", "names": "render"},
+    )
+
+
+@case(tags=["multi_import"])
+def case_js_multiple_imports() -> MultiImportCase:
+    """Two import statements."""
+    src = """\
+import React from 'react';
+import { useState } from 'react';
+"""
+    return (
+        "javascript",
+        src,
+        2,
+        [
+            {"module": "react", "names": "React"},
+            {"module": "react", "names": "useState"},
+        ],
+    )
+
+
+@case(tags=["mixed"])
+def case_js_full_module() -> MixedCase:
+    """Realistic JS module with JSDoc on every symbol.
+
+    Adding JSDoc here exercises the production-plugin default
+    (leading-comment attachment on) against the conventional
+    JS documentation style.  The expected-kinds tuple is
+    unchanged — this confirms documentation does not disturb
+    symbol extraction.  Content assertions for docstring
+    presence are covered by `test_docstrings.py`.
+    """
+    src = """\
+import { Model } from './model';
+
+/** Service facade over `Model`. */
+class Service {
+}
+
+/** Create a new service instance. */
+function create() {
+}
+
+/** Tear it down. */
+const destroy = () => {};
+"""
+    return "javascript", src, {"import", "class", "function"}, []
+
+
+@case(tags=["symbol"])
+def case_ts_function() -> SymbolCase:
+    """function greet(): void {}."""
+    return "typescript", "function greet(): void {}\n", [("function", "greet", "")]
+
+
+@case(tags=["symbol"])
+def case_ts_arrow_function() -> SymbolCase:
+    """Arrow function with type annotations."""
+    return (
+        "typescript",
+        "const add = (a: number, b: number): number => a + b;\n",
+        [("function", "add", "")],
+    )
+
+
+@case(tags=["symbol"])
+def case_ts_class() -> SymbolCase:
+    """class Service {}."""
+    return "typescript", "class Service {}\n", [("class", "Service", "")]
+
+
+@case(tags=["symbol"])
+def case_ts_class_generics() -> SymbolCase:
+    """class Container<T> {}."""
+    return "typescript", "class Container<T> {}\n", [("class", "Container", "")]
+
+
+@case(tags=["symbol"])
+def case_ts_namespace_function() -> SymbolCase:
+    """A function in a TS namespace is addressed by the namespace.
+
+    TS `namespace` is not tracked today (`f` → ""); target "N".
+    """
+    src = """\
+namespace N {
+  export function f(): void {}
+}
+"""
+    return "typescript", src, [("function", "f", "N")]
+
+
+@case(tags=["symbol"])
+def case_ts_nested_namespace() -> SymbolCase:
+    """Nested TS namespaces compose."""
+    src = """\
+namespace A {
+  export namespace B {
+    export function f(): void {}
+  }
+}
+"""
+    return "typescript", src, [("function", "f", "A::B")]
+
+
+@case(tags=["import"])
+def case_ts_import_named() -> ImportCase:
+    """import { User } from './types'."""
+    return (
+        "typescript",
+        "import { User } from './types';\n",
+        {"module": "types", "names": "User", "dots": "1"},
+    )
+
+
+@case(tags=["import"])
+def case_ts_import_type() -> ImportCase:
+    """import type { Config } from './config'."""
+    return (
+        "typescript",
+        "import type { Config } from './config';\n",
+        {"module": "config", "names": "Config", "dots": "1"},
+    )
+
+
+@case(tags=["import"])
+def case_ts_import_default() -> ImportCase:
+    """import Express from 'express'."""
+    return (
+        "typescript",
+        "import Express from 'express';\n",
+        {"module": "express", "names": "Express"},
+    )
+
+
+@case(tags=["import"])
+def case_ts_import_namespace() -> ImportCase:
+    """import * as path from 'path'."""
+    return "typescript", "import * as path from 'path';\n", {"module": "path", "names": "path"}
+
+
+@case(tags=["import"])
+def case_ts_import_side_effect() -> ImportCase:
+    """import './setup'."""
+    return "typescript", "import './setup';\n", {"module": "setup", "dots": "1"}
+
+
+@case(tags=["mixed"])
+def case_ts_full_module() -> MixedCase:
+    """Realistic TS module with JSDoc on every symbol.
+
+    Mirrors the JS variant; expected-kinds tuple unchanged.
+    Content assertions for docstring presence are in
+    `test_docstrings.py`.
+    """
+    src = """\
+import { Model } from './model';
+
+/** Repository over `Model` records. */
+class Repository {
+}
+
+/** Run a query and return the first row. */
+function query(): void {
+}
+"""
+    return "typescript", src, {"import", "class", "function"}, []
+
+
+@case(tags=["symbol"])
+def case_js_module_const() -> SymbolCase:
+    """Top-level const."""
+    return "javascript", "const MAX = 100;\n", [("variable", "MAX", "")]
+
+
+@case(tags=["symbol"])
+def case_js_exported_const() -> SymbolCase:
+    """Exported top-level const."""
+    return "javascript", "export const TIMEOUT = 30;\n", [("variable", "TIMEOUT", "")]
+
+
+@case(tags=["symbol"])
+def case_ts_module_const() -> SymbolCase:
+    """Top-level annotated const."""
+    return "typescript", "const MAX: number = 100;\n", [("variable", "MAX", "")]
+
+
+@case(tags=["symbol"])
+def case_js_object_destructure() -> SymbolCase:
+    """Object destructuring (shorthand)."""
+    return "javascript", "const {a, b} = o;\n", [("variable", "a", ""), ("variable", "b", "")]
+
+
+@case(tags=["symbol"])
+def case_js_object_renamed() -> SymbolCase:
+    """Object destructuring with rename binds the renamed target."""
+    return "javascript", "const {a: ra} = o;\n", [("variable", "ra", "")]
+
+
+@case(tags=["symbol"])
+def case_js_array_destructure() -> SymbolCase:
+    """Array destructuring."""
+    return "javascript", "const [x, y] = arr;\n", [("variable", "x", ""), ("variable", "y", "")]
+
+
+@case(tags=["symbol"])
+def case_js_object_rest() -> SymbolCase:
+    """Object rest element."""
+    return (
+        "javascript",
+        "const {a, ...rest} = o;\n",
+        [("variable", "a", ""), ("variable", "rest", "")],
+    )
+
+
+@case(tags=["symbol"])
+def case_js_exported_destructure() -> SymbolCase:
+    """Exported destructuring."""
+    return (
+        "javascript",
+        "export const {a, b} = o;\n",
+        [("variable", "a", ""), ("variable", "b", "")],
+    )
+
+
+@case(tags=["symbol"])
+def case_ts_object_destructure() -> SymbolCase:
+    """TS object destructuring."""
+    return "typescript", "const {a, b} = o;\n", [("variable", "a", ""), ("variable", "b", "")]
+
+
+@case(tags=["symbol"], marks=_xfail_nested)
+def case_js_nested_array_xfail() -> SymbolCase:
+    """Nested array destructuring — only the outer level captured today."""
+    return (
+        "javascript",
+        "const [a, [b, c]] = x;\n",
+        [("variable", "a", ""), ("variable", "b", ""), ("variable", "c", "")],
+    )
+
+
+@case(tags=["symbol"], marks=_xfail_nested)
+def case_js_nested_object_xfail() -> SymbolCase:
+    """Nested object destructuring — nothing captured today."""
+    return "javascript", "const {a: {b}} = x;\n", [("variable", "b", "")]

rbtr_lang_javascript/tests/samples/javascript/config.js

@@ -0,0 +1,2 @@
+// Locale configuration for the greeter.
+export const LOCALE = "en";

rbtr_lang_javascript/tests/samples/javascript/javascript.js

@@ -0,0 +1,46 @@
+// Greeter — format greetings for named recipients.
+//
+// The JavaScript plugin extracts function declarations, generator
+// functions, arrow functions bound to consts, classes, module-level
+// const/let variables (including destructuring), imports, and methods
+// (class members, including get/set accessors; object-literal methods are
+// captured without a scope).
+
+import { LOCALE } from "./config.js";
+import format from "formatter";
+import "./styles.css";
+
+export const DEFAULT_GREETING = "Hello";
+const { locale, fallback } = LOCALE;
+
+/** Format a greeting for a name. */
+export function formatGreeting(name) {
+  return `${DEFAULT_GREETING}, ${name} (${locale ?? fallback})`;
+}
+
+const cachedDefault = () => DEFAULT_GREETING;
+
+/** Stateful greeter holding a prefix. */
+export class Greeter {
+  constructor(prefix = DEFAULT_GREETING) {
+    this.prefix = prefix;
+  }
+
+  greet(name) {
+    return format(`${this.prefix}, ${name}`);
+  }
+}
+
+/** Yield each recipient name in turn. */
+export function* recipients(names) {
+  for (const name of names) {
+    yield name;
+  }
+}
+
+/** Greeting helpers grouped as an object literal. */
+export const helpers = {
+  shout(name) {
+    return `${name.toUpperCase()}!`;
+  },
+};