@groma/scanner-vue 0.1.4 → 0.2.0

package/README.md

@@ -1,9 +1,10 @@
 # Vue scanner
 
-The Vue scanner adds single-file component (SFC) event bindings to Groma's
+The Vue scanner adds single-file component (SFC) event bindings to groma.md's
 TypeScript scanner evidence. Its bundled compiler tools read local source
-without project dependencies. The scanner reads each selected project's
-`tsconfig.json`; it does not execute application code.
+without project dependencies. The scanner uses each selected project's
+`tsconfig.json`, or the nearest one above that package; it does not execute
+application code.
 
 ```sh
 bun install --frozen-lockfile --ignore-scripts
@@ -17,10 +18,11 @@ groma scanner add /absolute/path/to/groma/plugins/scanners/vue/dist/package
 groma scan
 ```
 
-The package bundles Vue language-core 3.3.11, Volar TypeScript 2.4.28,
-Vue compiler-dom 3.5.42 and its own TypeScript 5.9.3. Compiler-sfc 3.5.42
+The package bundles Vue language-core, Volar TypeScript, Vue compiler-dom and
+its own TypeScript 6.0, the last release with the classic compiler API these
+tools use; the package manifest pins the exact versions. Compiler-sfc
 provides build-time declarations only. The build
-pins compiler imports to that TypeScript installation. The separate TypeScript scanner uses its own 7.1 SDK. Compiler libraries and Vue helper declarations
+pins compiler imports to that TypeScript installation. The separate TypeScript scanner uses the native TypeScript 7 SDK. Compiler libraries and Vue helper declarations
 ship in the package; no consumer build or installation script is required.
 
 [Vue language tools](https://github.com/vuejs/language-tools) supply project
@@ -30,6 +32,16 @@ code with the TypeScript checker, which resolves component imports and handler
 function identities. The scanner translates these facts into the existing
 supplied-callback evidence contract; it has no separate name or type resolver.
 
+The package declares the default
+[include and exclude lists](../index.md#selecting-source-files). It includes
+`.vue` components, their JavaScript and TypeScript sources and stylesheets,
+HTML pages, `tsconfig*.json` configs, and the `package.json`, `project.json` and
+`nx.json` files the entry reader reads. It excludes `node_modules`, `dist`,
+`build` and `coverage` folders. The scan and the readiness check read only the
+files groma.md hands them, even when the project's `tsconfig.json` includes
+more; a source they read can still import another file as compiler context, and
+an external `src` block outside the files is left out of its component.
+
 ## Supported interaction
 
 ### External source blocks
@@ -53,35 +65,38 @@ trigger the existing shared scanner refresh.
 ### Inline event bindings
 
 The qualified example is Vue REPL's CodeMirror `change` event bound to the
-parent's `onChange` function. A static imported SFC must use a typed
-`defineEmits` declaration assigned to a constant. A call to that same symbol
-must supply a declared literal event name inside a source function. The parent
-template must bind the event directly to one source function declaration or
-constant function expression. Imported TypeScript functions use the same rule.
+parent's `onChange` function. A static imported SFC must assign `defineEmits`
+to a constant and declare the event in a type literal, function type, or
+literal runtime array. A call to that same symbol must supply a declared
+literal event name inside a source function or directly in an inline template
+event expression. The parent template must bind the event directly to one
+source function declaration or constant function expression. Imported
+TypeScript functions use the same rule.
 See [Vue component events](https://vuejs.org/guide/components/events).
 
-The observation records the emitting function, literal emit call, concrete
-template attribute and supplied handler. All positions refer to the original
-physical source, as zero-based UTF-16 offsets; lines are one-based. The nearest
+The observation records the emitting function or child template, literal emit
+call, concrete parent template attribute and supplied handler. All positions
+refer to the original physical source, as zero-based UTF-16 offsets; lines are one-based. The nearest
 function owns a nested emit call. Repeated scans are deterministic.
 
 Unresolved, dynamic or unsupported bindings produce `unsupported-vue-binding`
 diagnostics and no certain relationship. This revision does not support
-Options API events, runtime `defineEmits` arrays, dynamic components, dynamic
-event names, handler expressions or modifiers, state stores, routing, server
-frameworks or arbitrary event mutation. Compiler syntax/template errors fail
-the scan and preserve the previous complete map. Readiness errors explain
-invalid configuration or source syntax. Typed event names are read from the
-local `defineEmits` type literal; missing Vue types do not erase that evidence.
-
-Vue contributes `vue` Code provenance for configured source files. Shared core
+Options API events, dynamic components, dynamic event names, handler
+expressions or modifiers, state stores, or arbitrary event mutation. Nuxt
+server routes and shared HTTP client calls are observed separately. Compiler
+syntax/template errors fail the scan and preserve the previous complete map.
+Missing generated TypeScript config bases and missing declared source roots
+produce warnings while available source is scanned. Other invalid configuration
+fails readiness. Missing Vue types do not erase local `defineEmits` evidence.
+
+Vue contributes `vue` Code provenance for selected source files. Shared core
 keeps one physical-file owner, interprets complementary and conflicting
-observations, and writes readable relationship rows. `.vue` and TypeScript
-edits participate in the existing scan watcher.
+observations, and writes readable relationship rows. A change to a file the
+include list names triggers a rescan.
 
 In OKF, the result is ordinary source links and relationship Markdown. An SFC
 is source evidence; it does not automatically define a C4 responsibility or
-add a containment level. Groma's existing ownership and relationship model
+add a containment level. groma.md's existing ownership and relationship model
 owns that interpretation. No new architecture metadata is added.
 
 See [fresh-checkout validation](../fresh-checkout-validation.md) for the pinned project and executed release
@@ -121,13 +136,14 @@ there.
 | --- | --- |
 | `fetch(url, options)`, `$fetch(url, options)`, `useFetch(url, options)` | Request; a literal `method` gives the method, no options means `GET`, and options the scanner cannot read leave it out |
 | `$fetch` and `useFetch` with a `baseURL` option | Request whose path follows that base |
-| `axios.get`, `.post`, `.put`, `.patch`, `.delete`, `.head`, `.options` | Request with that method |
+| `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 |
 | `server/api/**` | Endpoint at `/api/...`, with the method its file name states |
 | `server/routes/**` | Endpoint at the path after `server/routes`, with the method its file name states |
 
-`fetch` counts when it is the runtime's or the default export of `node-fetch`,
+`fetch` counts when it is the runtime's, the default export of `node-fetch`, or
+a named `undici` import,
 as on the React page. `$fetch` and `useFetch` must resolve to a declaration
 outside the project source, such as an installed package's types, so a project's
 own `useFetch` composable, whose body decides the URL, is never read as Nuxt's;
@@ -205,20 +221,22 @@ In a component, the source range is in the `.vue` file's own lines. The
 functions a `<script setup>` block exposes to its template are compared.
 `setup()` on the argument of `defineComponent({ ... })` is an anonymous callback,
 while the methods under its `methods` property are compared. Top-level statements
-of a block are initializer code, and template expressions are not operations.
+of a block are initializer code, and template expressions are not compared
+operations. A direct template emit has a source operation named `(template)`
+only for the event relationship.
 Scripts the component keeps in a separate file are TypeScript modules, which the
 TypeScript scanner compares.
 
 ## Nested projects
 
-Run Groma from the repository root. The scanner finds package declarations in
-tracked and unignored files, including nested apps and libraries. Dependencies,
-dev dependencies, peer dependencies and optional dependencies identify candidates.
-A candidate also needs a tracked or unignored `tsconfig.json` and Vue source
-files belonging to that package, outside nested packages. Declaration files and
-inactive fixtures with a `.fixture` suffix do not qualify. Packages with only
-framework tooling dependencies are skipped. No matching project produces no evidence. Each compiler uses that project's configuration and local source;
+Run groma.md from the repository root. The scanner finds package declarations
+among its files, including nested apps and libraries. Dependencies, dev
+dependencies, peer dependencies and optional dependencies identify candidates.
+A candidate also needs a `tsconfig.json` among its files in the package or an
+ancestor, and Vue source files belonging to that package, outside nested
+Vue projects. Declaration files and inactive fixtures with a `.fixture` suffix
+do not qualify. Packages with only framework tooling dependencies are skipped.
+No matching project produces no evidence. Each compiler uses the nearest configuration and local source;
 imported source in sibling repository libraries keeps its original source path.
 Readiness checks all selected projects. An invalid selected project fails this scanner's observation; other scanners
 can still update the architecture.
-Source and nested package/configuration changes use the shared scanner watch flow.