@groma/scanner-javascript 0.1.1 → 0.2.1

package/README.md

@@ -1,7 +1,7 @@
 # JavaScript scanner
 
-The JavaScript scanner reads tracked and unignored `.js`, `.mjs`, `.cjs` and
-`.jsx` files, covering ECMAScript modules, CommonJS modules and browser scripts.
+The JavaScript scanner reads the `.js`, `.mjs`, `.cjs` and `.jsx` files
+groma.md hands it, covering ECMAScript modules, CommonJS modules and browser scripts.
 It does not require Node.js, installed packages, a bundler, a project build or a
 `tsconfig.json`. Discovery matches JavaScript source directly, even without a
 package manifest.
@@ -17,7 +17,7 @@ groma scanner add /absolute/path/to/groma/plugins/scanners/javascript/dist/packa
 groma scan
 ```
 
-The package bundles the TypeScript 6.0.3 compiler, whose parser reads
+The package bundles the TypeScript 6.0 compiler, whose parser reads
 JavaScript, including JSX in `.js` and `.jsx` files, and includes its license
 notices. Every file is parsed on its own, so no project configuration, module
 resolution or other file changes what a file reports. The compiler's declaration
@@ -31,28 +31,21 @@ TypeScript-style type annotations, as in many Flow-typed files, still parse, and
 octal literals and escapes that only strict mode rejects, such as `0755`, are not
 parse errors.
 
-## Excluded files
+## Included and excluded files
 
-Minified output is not authored source, so it is left out of the scan and the
-source outline:
+The package declares the default
+[include and exclude lists](../index.md#selecting-source-files). It includes
+the four source extensions and the `package.json`, HTML, `project.json` and
+`nx.json` files the entry reader reads. It excludes names that state minified
+output, such as `jquery-ui.min.js`, and `node_modules`, `dist`, `build` and
+`coverage` folders. The scan and the readiness check read only the files the
+lists select.
 
-- a name that states minified output, such as `jquery-ui.min.js`;
-- text whose lines average 500 characters or more, the shape of a bundle a build
-  produced under an ordinary name such as `vendor.js`.
+A bundle under an ordinary name, such as `vendor.js`, is read like any other
+source; a project that keeps it out adds a pattern to `scanners.json`.
 
-The shared Git boundary omits ignored files and dependency or build directories
-such as `node_modules`, `vendor`, `dist` and `build`. Core applies the source
-exclusions configured in `scanners.json`.
-
-Test sources are treated like any other JavaScript source, as in the PHP and
-Swift scanners: a project excludes them explicitly in `scanners.json`. The
-TypeScript scanner instead omits `test` directories and `.test` and `.spec` names
-by default.
-
-Discovery counts any `.js`, `.mjs`, `.cjs` or `.jsx` name, minified files
-included, because it reads file names without opening them. A repository whose
-only JavaScript is minified can therefore be recommended this scanner, and
-readiness then reports that no authored JavaScript source was found.
+Test sources are treated like any other JavaScript source: the defaults name
+none, so a project that keeps them out adds a pattern to `scanners.json`.
 
 TypeScript sources belong to the [TypeScript scanner](../typescript/index.md)
 and single-file components to the [Vue scanner](../vue/index.md). This scanner
@@ -66,6 +59,8 @@ and methods and constructors with a body produce operation evidence with UTF-16
 source offsets.
 Code outside every function is the module's own work, so a browser script's
 top-level calls keep an operation to belong to, without inventing a function.
+Calls inside accessors belong to an anonymous accessor operation; accessors are
+not compared for duplicate logic.
 
 Calls remain unresolved. One parsed file proves no call target: an imported name,
 a `require` result and a method on a value are all decided elsewhere, so core
@@ -77,6 +72,13 @@ JavaScript file belongs to one C4 runtime boundary. Core owns architecture
 identity and curation, and repeated scans preserve one physical owner and the
 authored architecture. JavaScript edits and new files refresh through the shared
 scanner watcher.
+Each literal local `node`, `bun`, `tsx` or `ts-node` command in an unquoted
+`&&`-chained package script can supply an execution entry. Environment
+assignments or `cross-env` may come before the runtime, and runtime options and
+a `run` or `watch` subcommand before the script; the first remaining word must
+name the script, so a preloaded module or `bun build` supplies none. An HTML
+page's script supplies one too, named after the page, or after its folder for
+an `index.html`.
 
 ## Source outline
 
@@ -86,7 +88,8 @@ parses the file alone and lists what it declares at the top level:
 
 - functions, and arrow functions or function expressions assigned directly to a
   `const`, `let` or `var` name;
-- classes, with every method and the constructor as members.
+- classes, including a named class expression assigned to `module.exports`,
+  with every method and the constructor as members.
 
 Fields, accessors, and declarations inside a function, method or block are not
 listed. A declaration is marked as an entry when the component's Code names it,
@@ -96,12 +99,12 @@ Visibility follows how the file publishes a name:
 
 | Value | JavaScript |
 | --- | --- |
-| `public` | An `export`, a name in the file's own `export { name }` list or `export default name`, a name a CommonJS `module.exports` or `exports.name` assignment publishes, and every top-level declaration of a file that states no module boundary, because those names are globals |
+| `public` | An `export`, a name in the file's own `export { name }` list or `export default name`, a name a CommonJS `module.exports` or `exports.name` assignment publishes, including through a chained assignment, and every top-level declaration of a file that states no module boundary, because those names are globals |
 | `private` | Every other top-level declaration, and a `#name` member |
 
 A `.mjs` or `.cjs` file is a module whatever it contains, so its unpublished
 declarations stay private. A `.js` file is a module when it states an `import`,
-an `export` or a CommonJS export; otherwise it is a browser script whose
+an `export`, a CommonJS export or a `require` call; otherwise it is a browser script whose
 declarations any other script on the page may use. Members are `public` unless
 their name is private.
 
@@ -125,8 +128,8 @@ that file states it and a value from another file is one the scanner cannot see.
 
 | Construct | Reported |
 | --- | --- |
-| `fetch(url, init)`, including a `node-fetch` default import | Request; a literal `method` gives the method, no options means `GET`, and options the scanner cannot read, or an input that is not a URL, such as a `Request`, leave it out |
-| `axios.get`, `.post`, `.put`, `.patch`, `.delete`, `.head`, `.options` | Request with that method |
+| `fetch(url, init)`, including a `node-fetch` default import or a named `undici` import | Request; a literal `method` gives the method, no options means `GET`, and options the scanner cannot read, or an input that is neither URL text nor typed as a primitive such as a string, for example a `Request`, leave it out |
+| `axios.get`, `.post`, `.put`, `.patch`, `.delete`, `.head`, `.options`, `.postForm`, `.putForm`, `.patchForm` | Request with that method; form helpers use their matching HTTP method |
 | `axios(config)`, `axios.request(config)` | Request from the config's `url`; its `method`, else the client's, else `GET` |
 | `axios.create(config)` instances | Request whose path follows the config's `baseURL`, and whose method defaults to the config's |
 | `$.get`, `$.post`, `$.getJSON`, `$.getScript` | Request with that helper's method |
@@ -209,21 +212,29 @@ The [producer decisions](../evidence.md#producer-checklist) for this ecosystem:
 7. **Constrained segments.** Route patterns are literal text, `:name`, `:name?`,
    Express 5's trailing optional group `{/:name}`, and a trailing `*`, `*name`,
    `(.*)` or `:name(.*)` catch-all, which needs at least one segment because a
-   request path cannot tell `/files` from `/files/`; Hono's trailing `*` also
-   matches the path without it. A pattern parameter, such as `:id(\d+)`, and
+   request path cannot tell `/files` from `/files/`; Hono's trailing `*` and
+   Express 5's trailing `{/*name}` or `/{*name}` also match the path without it.
+   A pattern parameter, such as `:id(\d+)`, and
    text mixed with a placeholder, such as `talk-:id`, are constrained
    parameters. A pattern that may span segments or that the scanner cannot
    state, such as a regular expression, another optional group or a catch-all
    that is not last, becomes a constrained optional catch-all in place of itself
-   and the rest of the route, so no route is omitted.
+   and the rest of the route, so no route is omitted; the whole segments before
+   it stand.
 8. **Registration order.** Express, Hono and Koa routers take the first
    registered match, so their endpoints carry `order`: the application, named by
    the file that creates it and the variable that holds it, such as
-   `server/app.js#app`, and a position. The routing model has six rules:
+   `server/app.js#app`, and a position. Same-named local applications in one
+   file also carry their declaration position to keep their order separate.
+   The routing model has six rules:
    1. A registrar's entries are its registrations and the references that hand
       it off to other code, such as `registerRoutes(app)`. Serving it with
       `listen`, Node's `createServer(app)` or an imported `serve(app)` registers
-      nothing. The scanner never sees the files that import this one, which run
+      nothing, and neither does a route method called with fewer than two
+      arguments, such as the setting read `app.get('env')`. A `use` that only
+      adds middleware, which takes no place (rule 5), is no entry either, so
+      `if (app.get('env') === 'development') app.use(logger)` leaves the order
+      of the other entries known. The scanner never sees the files that import this one, which run
       after all of it and may add any route, so an export, `export default app`,
       `export const app` or an assignment to `module.exports` or `exports`,
       hands the registrar off at the end of its order; a circular require is the
@@ -244,9 +255,9 @@ The [producer decisions](../evidence.md#producer-checklist) for this ecosystem:
       prefix followed by a constrained optional catch-all, with method `*`
       unless the call states one, named by the registering operation: a route
       with a computed path, a mount under a computed prefix, a path mounted to
-      something other than a recognized router, such as
-      `app.use('/static', express.static('public'))`, a router the scan cannot
-      follow, mounted with or without a path, such as
+      something other than a recognized router or a function the scan sees,
+      such as `app.use('/static', express.static('public'))`, a router the
+      scan cannot follow, mounted with or without a path, such as
       `app.use(require('./routes'))`, a Koa router's `routes()` from another
       file, or a function imported from one, which the scanner cannot see, a
       route builder such as `app.route('/reports')`, Hono's `on`, `mount` and
@@ -255,7 +266,11 @@ The [producer decisions](../evidence.md#producer-checklist) for this ecosystem:
       registrar's root.
    5. Middleware takes no place: a package's handler, such as `express.json()`,
       and any handler before or beside a recognized router in one call, as in
-      `app.use(requireAuth, api)`, which then states no path.
+      `app.use(requireAuth, api)`, which then states no path. Hono's `use`
+      never mounts a router, so it takes no place with or without a path,
+      whatever its handlers. Under a path, an Express or Koa `use` takes none
+      when the scan sees that every handler is a function, as in
+      `app.use('/api', requireAuth)`.
    6. Fastify and Bun.serve prefer the most specific route and carry no order; a
       Fastify plugin, whose routes the scan does not read, blocks its prefix
       without one.
@@ -263,7 +278,7 @@ The [producer decisions](../evidence.md#producer-checklist) for this ecosystem:
 ## Validation
 
 Independent fixtures cover ECMAScript modules, CommonJS, JSX, browser scripts,
-minified files excluded by name and by line length, exact source positions,
+minified names excluded by the default exclusions, exact source positions,
 unresolved calls, the source outline with its visibility rules, one body that
 tokenizes identically in JavaScript and in TypeScript, identical and
 near-duplicate bodies found by `groma lint`, a file that does not parse next to