# Fully Qualified Names

> A name cannot be dissected any further by
means of a definition: it is a primitive sign
-- Ludwig Wittgenstein

Powered by [`tree-sitter`](https://github.com/tree-sitter/tree-sitter), `fully-qualified-names` lets you extract simple and fully qualified names from code written in JavaScript, TypeScript, Python or Java. Those names are further split into declarations and usages which provides a convenient simplification of more complex ASTs for static analysis.

## How to use

The package offers a Rust and a JS API, the latter based on WASM. To get names from a Python code snippet in Rust you would use something like the following.

``` rust
use fully-qualified-names::Python;

let code = r#"class Person:
  def __init__(self, name):
    self.name = name

  def hello(self):
    return f"Hello, {self.name}"
"#;

let names = Python::find_names(code).unwrap();
println!("{names:?}");
```

The same in JS would look as follows.

``` javascript
import { Python } from '@aws/fully-qualified-names';

const code = `class Person:
  def __init__(self, name):
    self.name = name

  def hello(self):
    return f"Hello, {self.name}"
`;

const names = await Python.findNames(code);
console.log(JSON.stringify(names));
```

## Background

In programming, identifers are used to refer to values, types and code passages.

### Names

Those all have simple names which are context-specific, and fully qualified names
(subsequently abbreviated as FQNs),
which are unambiguous and unique across projects.

Take e.g. the following Rust code snippet.

``` rust
let list = std::vec::Vec::new();
```

Here we have several simple names (`list`, `std`, `vec`, `Vec`, `new`),
which include variable (`list`), module (`std`, `vec`), type (`Vec`) and method (`new`) names.

All of those have FQNs as well, the `new` method's FQN is explicitly stated as `std::vec::Vec::new`,
the `list` variable's FQN can only be determined with knowledge of the surrounding package
and module structure.

### Declaration -- Usage

The names introduced above can be furthermore be separated into declarations (`list`) and usages (`std::vec::Vec::new`)

**Declaration**: A declaration is a statement which _introduces_ a name into a scope.

**Value Usage**: A symbol name is used in an expression which requires _evaluating_ (i.e. looking up) the symbol’s definition.

**Type Usage**: A type name is _used_ by the compiler in a left-hand-side context to
* ensure a value in a right-right-hand side context has the required type
* avoid type propagation/inference across scopes

## Security

See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.

## License

This project is licensed under the Apache-2.0 License.