[ixuz]

What and why

Replacing the Solid client libraries used to mean touching most of packages/solid and its tests at once. The libraries were imported in more than 40 files, internals were read in several places, and tests mocked the libraries directly. This pull request moves every use of them behind modules of the app's own. A later switch is then new code behind fixed interfaces, with no changes in the callers. Nothing changes for users, and nothing changes in what the app writes to a pod.

• One folder for the libraries. Only packages/solid/src/client/ imports them: rdf.ts (the data model), resources.ts (reading and writing pods, with an own HttpError), session.ts (the sign-in client), access.ts (the public-read grant) and linearDataset.ts. packages/shacl/src/turtleDocument.ts is shacl's only importer. The types get the app's own names (Dataset, Subject, NamedSubject, SubjectBuilder). The functions keep the names the code already called, so callers changed their imports and type names only.
• No library internals outside client/. The change log, the resource info the ETag map is keyed by, a subject's predicates and a dataset's graphs are reached through functions rdf.ts exports (changesOf, sourceOf, propertiesOf, datasetFromQuads, withQuads, isEmptyDataset, parseQuads).
• The implicit behavior is written down. client/rdf.ts documents it and client/rdf.test.ts pins it against the current library:
  • listing subjects skips blank nodes;
  • local names resolve against the source URL;
  • the date-reading rule (GHSA-7p4m);
  • language tags are lowercased;
  • decimals, as read and as written.
• Errors. HttpError keeps the library's statusCode, response.status and message, which retryable.ts and typeIndex.ts rely on, and carries the library's error as cause. Its name is HttpError, so the crash screen's copyable details now start with HttpError: instead of Error:.
• Sign-in in two parts. solidSessionGateway.ts keeps the logic that depends on no library: the login hash, issuer discovery, and 401 as expiry. It takes the client from client/session.ts, which provides restore, login, logout, and a fetch and a WebID that are always the current session's. composition gets one factory, createSolidSession, that returns { sessionGateway, fetch, webId }. The own-pod release reads from fix(composition): read a release outside the user's own pod as no one #325 ask that same client who is logged in.
• Grant and profiles injected. createSolidReleasePublisher takes grantPublicRead, and the storage gateway takes its profile lookup (getProfileStorages). The publisher's fence and its server workarounds stay around the grant. The publisher's tests also run the real grant through the fence, for WAC and ACP.
• Tests go through the app's seams. Fixtures are built in src/testing/, and tests mock the app's modules, not the libraries'.
• The boundary rule. npm run check:boundaries lets only client/ and shacl's module import an @inrupt/ package outside tests. Only client/access.ts may import the access-control functions.
• Docs. vendor-code.md now states what a swap really costs. A replacement provides the client/ modules with the current library's type shapes, because callers read subject.url and use the builder chain, and it matches the behavior their tests pin. boundaries.md, architecture.md, testing.md, authentication.md, the package's README and a few links follow.

Out of scope, as the issue says: a second implementation, a build-time switch and choosing a replacement library.

Closes: #323

Checklist

• One issue. This pull request addresses one issue, linked above.
• One step. This pull request does not finish its issue, so it says Refs:, not Closes:. Leave this unchecked otherwise.
• Done, as AGENTS.md defines it: npm run check passes (lint, Markdown and spelling included), npm run lint:reuse too if a file was added, and npm run crosscheck too if ns/ or decks/ changed. (crosscheck n/a: ns/ and decks/ are unchanged)
• Tests. New and changed code has its tests, and every package stays at 100% coverage (docs/testing.md).
• Docs. The docs say what changed, and a new page in docs/ is listed in docs/docs.ttl. (no new page)
• Languages. A new or changed message is in every locale: en, sv, ko, de, es and fr (packages/ui/src/i18n/). (n/a: no message changed)
• Vocabulary and shapes. Any change to ns/ was agreed in an issue first; no published ns/shapes/*/vN.ttl or decks/*/vN.ttl was edited; generated files were regenerated, not edited. (n/a: ns/ and decks/ are unchanged)
• Breaking? Nothing in the public API breaks, or a commit says so (! and a BREAKING CHANGE: footer). npm run check:breaking sees a line of api/ that goes, but not a feature removed, nor a reader that reads less than before.
• Pod data. Any change to what the app writes to a pod comes with its migration (docs/migrations.md). (n/a: the app writes the same data and requests)
• Policy. Any change to an external rule the code follows (SM-2, the plural rules, a specification) is cited. (n/a: no external rule changed)
• Licenses. New content is MIT, or a deck states its own license; a new file has its SPDX header (npm run lint:reuse), or a new deck its line in REUSE.toml; third-party content is credited.
• Architecture. Imports follow docs/boundaries.md and the layers of docs/architecture.md.
• Run. I ran the app (npm run dev) and tried the change, and considered the user journeys.
• Authorship. I read and understand every line of this pull request, and answer for it, whatever tools helped write it (CONTRIBUTING.md).
• Commits. Each commit is one logical change, in Conventional Commits form (type(scope): subject, ! and a BREAKING CHANGE: footer if it breaks something), with an imperative subject and a body that explains why (CONTRIBUTING.md).