@groma/scanner-angular 0.1.3 → 0.1.5

package/README.md

@@ -1,9 +1,8 @@
 # Angular scanner
 
-The Angular scanner adds concrete external-template output bindings to the
-TypeScript scanner evidence. Enable it alongside the Java scanner for the
-supported Maven and Angular application. All enabled scanners must complete
-before Groma updates the map.
+The Angular scanner adds explicit component source units and concrete
+external-template output bindings to the TypeScript scanner evidence. Enable it alongside the Java scanner for the
+supported Maven and Angular application. Healthy scanners update the map; failed scanners retain their saved evidence.
 
 ## Build and install
 
@@ -25,10 +24,10 @@ The package contains a bundled ESM entry and TypeScript standard-library
 declarations. Consumers do not run a package build or installation script.
 The prototype package name is not a public publication commitment.
 
-Prepare the application's ordinary dependencies using its package manager.
-The scanner reads each selected project's `tsconfig.json`, its configured source entry points,
-and the Angular resources reachable from that program. It does not install
-dependencies, compile application output, or run application code.
+The scanner reads each selected project's `tsconfig.json`, source entry points
+and external templates. The package supplies the compiler tools; project
+`node_modules`, application compilation and dependency installation are not
+required. Application code is never executed.
 
 ## Compiler tooling
 
@@ -39,14 +38,21 @@ The TypeScript scanner uses its own 7.1 SDK. The package build resolves every
 compiler TypeScript import to the scanner's 5.9.3 installation before bundling,
 so workspace dependency hoisting cannot substitute Groma's compiler.
 
-The adapter uses `NgtscProgram`, its template type checker, and the compiler's
-template and TypeScript symbols. These version-specific compiler APIs are
-pinned with the package. Angular owns template parsing, directive matching,
-output binding, and handler resolution; the adapter does not recreate them.
-See [Angular template type checking](https://angular.dev/tools/cli/template-typecheck).
+Angular's template parser and selector matcher read template syntax. TypeScript
+resolves local class, property and handler identities. The adapter recognizes
+literal `@Component` metadata, direct standalone imports and Angular output
+API imports from source, even when the Angular package is absent.
 
 ## Supported evidence
 
+Literal `templateUrl`, `styleUrl`, and `styleUrls` declarations associate a
+component class with its directly named local template and stylesheet files.
+Core uses that source unit to create one component, or attach new unowned files
+to its existing owner. All member paths appear in Code details. Inline content
+does not create files; ordinary imports, neighboring files, global styles, and
+transitive stylesheet imports do not become companion files. Shared companions
+and conflicting curated ownership follow the core source-unit review rules.
+
 A direct method call in an external template can bind a single resolved
 source output property to a source method with a body. TypeScript locates
 `emit()` calls on that exact property declaration. An emit inside an arrow
@@ -60,14 +66,78 @@ unresolved while Angular establishes the concrete binding.
 
 Angular reports `angular` Code provenance for its source contribution.
 The exact source path keeps one curated owner across both scanners. HTML edits
-participate in the existing watch lifecycle. Repeat scans retain authored
+participate in the existing watch lifecycle, as do CSS, SCSS, Sass, Less, and Stylus
+source edits. Repeat scans retain authored
 architecture, and compiler errors leave the previous complete map in place.
 
 In OKF, the result remains ordinary Code links and readable relationship rows.
-In C4, an Angular component is source evidence, not a new architecture level
-or an automatic architecture component. Core owns relationship interpretation;
+In C4, an Angular declaration supplies source-unit evidence, not a new
+architecture level. Core owns component ownership and relationship interpretation;
 the plugin does not write architecture or introduce metadata.
 
+## Source outline
+
+The scanner outlines the TypeScript files in a component's Code with the
+TypeScript rules of the [source outline contract](../creating-a-plugin.md#source-outline):
+top-level functions and types (classes, interfaces, enums), including namespace
+contents, and each type's constructors and methods. Every declaration has its
+line and visibility, and `entry` marks the names the Code links give. Templates
+and stylesheets have no outline. The package's own TypeScript parses each file
+alone, without `tsconfig.json`, dependencies or compilation.
+
+Core outlines each file once. For a source that the TypeScript scanner also
+owns, the scanner with the lowest id among the file's Code links outlines it,
+here Angular, with the symbols of all those links.
+
+## HTTP endpoints and requests
+
+The scanner reports [HTTP facts](../evidence.md#http-endpoints-and-requests) for
+Angular's `HttpClient`. An Angular application is a client: it serves no endpoint.
+
+| Construct | Reported |
+| --- | --- |
+| `get`, `post`, `put`, `patch`, `delete`, `head`, `options` | Request with that method and the URL the first argument states |
+| `request(method, url)` | Request with that literal method; a computed method leaves the method out |
+
+The receiver must hold the injected client: a constructor parameter property, a
+field, or a local whose declared type is `HttpClient`, or one that
+`inject(HttpClient)` supplies, with `HttpClient` imported from
+`@angular/common/http`. Both names are recognized from source, without the
+Angular packages installed, so a `get` method on any other object is never a
+request. `request(new HttpRequest(...))`, `jsonp`, and a client this scan never
+sees injected report nothing.
+
+The [producer decisions](../evidence.md#producer-checklist) for this
+ecosystem:
+
+1. **Prefixes.** None to add: the scanner reports no endpoint, and a request's
+   path is the URL its own call states, after the base rule below.
+2. **Endpoints.** None. Angular's router routes navigate inside the browser, and
+   interceptors and guards answer no request; reporting either would claim an
+   answer nothing serves and could hide the file that really serves the path.
+3. **Dynamic or unknown.** `` `/talks/${id}` `` fills one whole segment, so it
+   is dynamic. `` `/talks/${id}-latest` ``, a path built from an unresolved
+   value, and a URL the scanner cannot read at the call are unknown. The query
+   and fragment are dropped, computed or not.
+4. **Local helpers.** Not supported: the URL is read at the client call, so a
+   helper that forwards a path parameter reports unknown text, and its callers
+   report nothing. Author those rows.
+5. **Bases.** The [React
+   scanner's](../react/index.md#http-endpoints-and-requests) decision 5 holds
+   unchanged, so an environment object holding `/api` reports `/api/talks`, and
+   a field read through `this` holds its one assignment, so `this.resourceUrl`
+   with `resourceUrl = API_ROOT + '/api/speakers'` reads as that configured base
+   and path, while an injected field is the service's own base setting. A
+   literal environment base is the value in the source file, which an Angular
+   build's `fileReplacements` can swap for another environment, so the reported
+   path is the development one.
+6. **File-location routes.** None: every request names the function that runs
+   the call, and a call outside any function reports nothing.
+7. **Constrained segments.** None: the scanner reports no endpoint, so it reads
+   no route pattern.
+8. **Registration order.** None: without endpoints there is no route order to
+   report.
+
 ## Coverage limits
 
 This revision qualifies the CompanyMergeDialog output-to-parent-handler flow.
@@ -77,16 +147,15 @@ expressions, output mutation, or exhaustive Angular runtime behavior.
 Unresolved or unsupported event bindings produce
 `unsupported-angular-binding` diagnostics rather than relationships.
 DOM events and dependency-library outputs have no supported source output
-provider in this rule. TypeScript semantic errors, including incompatible types,
-fail readiness and scanning alongside syntax and Angular compiler errors.
-Compiler errors fail the scan instead of yielding a
-partial observation. Template strictness follows the project's Angular compiler
-options. Groma enables the template-checker API to resolve output bindings but
-does not enable stricter template checks than the project requests.
+provider in this rule. Missing external types and unsupported bindings remain
+uncertain. Invalid TypeScript or template syntax fails the observation. Source
+scanning does not perform Angular application type checking. Nonliteral
+component metadata, module-based scopes and indirect imports are outside the
+supported binding extraction.
 
 Independent fixture tests load the built package and cover concrete callback
 endpoints, complementary TypeScript evidence, curated ownership, HTML-triggered
-rescan, and failure preservation. See [validation](validation.md) for the
+rescan, failure preservation, the source outline, and the HTTP requests. See [fresh-checkout validation](../fresh-checkout-validation.md) for the
 real-project result and remaining release gates.
 
 ## Nested projects
@@ -97,7 +166,7 @@ dev dependencies, peer dependencies and optional dependencies identify candidate
 A candidate also needs a tracked or unignored `tsconfig.json` and TypeScript 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 installed dependencies;
+framework tooling dependencies are skipped. No matching project produces no evidence. Each compiler uses that project's 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.