docs: rewrite how-resolver-works.md to STE rules

[elharo]

Along with the usual style improvements:

• Much more precise and careful definitions of terms. The previous definition of artifact was simply wrong.

[elharo]

CI seems borked:

[13](https://github.com/apache/maven-resolver/actions/runs/31255258160/job/93097599126?pr=2046#step:12:914)
Error: [ERROR] /Users/runner/work/maven-resolver/maven-resolver/maven-resolver-impl/src/test/java/org/eclipse/aether/internal/impl/DefaultRepositorySystemReentrancyTest.java:[361,17] incompatible types: no instance(s) of type variable(s) T exist so that java.util.List<T> conforms to java.util.Map<java.lang.String,org.eclipse.aether.spi.validator.ValidatorFactory>
Error: [ERROR] /Users/runner/work/maven-resolver/maven-resolver/maven-resolver-impl/src/test/java/org/eclipse/aether/internal/impl/DefaultRepositorySystemReentrancyTest.java:[398,17] incompatible types: no instance(s) of type variable(s) T exist so that java.util.List<T> conforms to java.util.Map<java.lang.String,org.eclipse.aether.spi.validator.ValidatorFactory>
Error: [ERROR] /Users/runner/work/maven-resolver/maven-resolver/maven-resolver-impl/src/test/java/org/eclipse/aether/internal/impl/DefaultRepositorySystemReentrancyTest.java:[457,17] incompatible types: no instance(s) of type variable(s) T exist so that java.util.List<T> conforms to java.util.Map<java.lang.String,org.eclipse.aether.spi.validator.ValidatorFactory>
[INFO] 3 errors

[gnodet]

The prose improvements are welcome, but there are several factual accuracy issues that need fixing before this can be merged:

1. resolveArtifacts description is wrong — it does not build a flattened list; flattening is done by doFlattenDependencyNodes inside resolveDependencies
2. TODO left in published docs — "TODO: do they give the same result?" on line 119
3. Grammar error — "also be resolved" missing "can" on line 68
4. "binary resource" is inaccurate — POMs are text/XML; the Artifact Javadoc says "identifying coordinates and optionally a file"
5. Dirty graph omits cycles — CollectResult explicitly tracks List<DependencyCycle>
6. <aside> HTML tag — not used anywhere else in site markdown, rendering risk with Doxia

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

Claude Code on behalf of gnodet

[gnodet]

This description is factually incorrect. resolveArtifacts takes a pre-supplied Collection<? extends ArtifactRequest> and resolves their paths — it does not build a flattened list. DefaultRepositorySystem.resolveArtifacts (lines 308-334) delegates directly to artifactResolver.resolveArtifacts(session, requests). Flattening is done only inside resolveDependencies via doFlattenDependencyNodes (line 421-422).

Suggested:

Suggested change

	* `List<ArtifactResult> resolveArtifacts(RepositorySystemSession session, Collection<? extends ArtifactRequest> requests)` performs the artifact resolution step. It builds a flattened list and downloads artifacts before returning.
	* `List<ArtifactResult> resolveArtifacts(RepositorySystemSession session, Collection<? extends ArtifactRequest> requests)` performs only the artifact resolution step. It resolves the paths for a collection of artifacts, downloading them from remote repositories if necessary.

[gnodet]

This TODO should not appear in published documentation. Either answer the question and replace with a factual statement, or remove it.

[gnodet]

Thanks for fixing the grammar error and adding cycles to the dirty graph description. Four issues from the previous review remain:

1. TODO in published docs (line 119) — still present
2. resolveArtifacts description (line 148) — still says "builds a flattened list"; it takes a pre-supplied Collection and resolves paths, no flattening
3. "binary resource" (line 34) — POMs are text/XML, not binary
4. <aside> tag (line 67) — not used elsewhere in site markdown

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

Claude Code on behalf of gnodet