@fougere/core 0.6.0-alpha.0 → 0.8.0-alpha.0

package/src/scan/handler-parser.ts

@@ -1,9 +1,4 @@
-/**
- * Handler signature parser — extracts method signatures from handler source files.
- *
- * The AST says what the author declared; TypeScript's checker says what those types mean.
- * TypeScript is lazy-loaded to avoid bundling the compiler in production builds.
- */
+/** Handler signature parser — extracts method signatures from handler source files. */
 import type { TypeRef, Param, Signature } from '../wire/signature.js';
 import type ts from '@typescript/typescript6';
 import { readFileSync, existsSync, statSync } from 'node:fs';
@@ -26,26 +21,11 @@ interface TypeProject {
   program: ts.Program;
 }
 
-/**
- * One checked program per project/configuration during a scan.
- *
- * A checker is a project reader, not a file parser: creating one per handler would reopen
- * the standard library and every imported declaration for each method. `scanProject`
- * resets this map at the start of a run, so an edited source can never meet a program from
- * the previous run.
- */
+/** One checked program per project/configuration during a scan. */
 const typeProjects = new Map<string, TypeProject>();
 const compilerProjects = new Map<string, { key: string; roots: string[]; options: ts.CompilerOptions }>();
 
-/**
- * What survives a run: the parsed declarations, and the program built over them.
- *
- * Rebuilding a program re-reads `lib.d.ts` and every imported `.d.ts`, and that is FIXED
- * work — measured, a second scan in one process cost the same at 16 frond files as at 406.
- * The mtime is the guard, so a run still cannot see a stale type: a file that moved is
- * re-read and TypeScript invalidates it and everything depending on it, which is a
- * narrower rule than discarding the program and not a weaker one.
- */
+/** What survives a run. */
 const sourceFiles = new Map<string, { mtime: number; file: ts.SourceFile }>();
 const retained = new Map<string, { host: ts.CompilerHost; program: ts.Program }>();
 
@@ -61,8 +41,8 @@ export function forgetParsedSources(): void {
 }
 
 function keptHost(key: string, options: ts.CompilerOptions): ts.CompilerHost {
-  const held = retained.get(key);
-  if (held) return held.host;
+  const cached = retained.get(key);
+  if (cached) return cached.host;
   const typescript = getTS();
   const base = typescript.createCompilerHost(options);
   const host: ts.CompilerHost = {
@@ -138,13 +118,7 @@ function compilerProjectOf(filePath: string, projectRoot?: string): { key: strin
   return configured;
 }
 
-/**
- * Declare every file a run will read, so one program covers it.
- *
- * `checkedSourceOf` rebuilds whenever it meets a root it has not seen, and a frond lives
- * outside its project's tsconfig `include`, so every declaration was a new root: 44 files
- * cost 7.3 s that way against 0.34 s for one program.
- */
+/** Declare every file a run will read, so one program covers it. */
 export async function seedTypeProgram(filePaths: readonly string[], projectRoot?: string): Promise<void> {
   const typescript = await loadTS();
   const grouped = new Map<string, { options: ts.CompilerOptions; paths: string[] }>();
@@ -152,9 +126,9 @@ export async function seedTypeProgram(filePaths: readonly string[], projectRoot?
   for (const filePath of filePaths) {
     const absolute = resolvePath(filePath);
     const configured = compilerProjectOf(absolute, projectRoot);
-    const held = grouped.get(configured.key) ?? { options: configured.options, paths: [] };
-    held.paths.push(absolute);
-    grouped.set(configured.key, held);
+    const group = grouped.get(configured.key) ?? { options: configured.options, paths: [] };
+    group.paths.push(absolute);
+    grouped.set(configured.key, group);
   }
 
   for (const [key, { options, paths }] of grouped) {
@@ -168,25 +142,25 @@ function checkedSourceOf(filePath: string, projectRoot?: string): { source: ts.S
   const typescript = getTS();
   const absolute = resolvePath(filePath);
   const configured = compilerProjectOf(absolute, projectRoot);
-  let held = typeProjects.get(configured.key);
+  let project = typeProjects.get(configured.key);
 
-  if (!held) {
+  if (!project) {
     // `path.resolve` is variadic, so handing it directly to `map` also passed the
     // index and the whole roots array as path segments. A fixture without a warm scan
     // cache exposed that first-run-only failure.
     const roots = new Set(configured.roots.map((root) => resolvePath(root)));
     roots.add(absolute);
     const program = builtProgram(configured.key, [...roots], configured.options);
-    held = { roots, options: configured.options, program };
-    typeProjects.set(configured.key, held);
-  } else if (!held.roots.has(absolute)) {
-    held.roots.add(absolute);
-    held.program = builtProgram(configured.key, [...held.roots], held.options);
+    project = { roots, options: configured.options, program };
+    typeProjects.set(configured.key, project);
+  } else if (!project.roots.has(absolute)) {
+    project.roots.add(absolute);
+    project.program = builtProgram(configured.key, [...project.roots], project.options);
   }
 
-  const source = held.program.getSourceFile(absolute);
+  const source = project.program.getSourceFile(absolute);
   if (!source) throw new Error(`TypeScript did not include '${absolute}' in its program.`);
-  return { source, checker: held.program.getTypeChecker() };
+  return { source, checker: project.program.getTypeChecker() };
 }
 
 /** A file, opened. Five places read and parsed one, each spelling the same two calls. */
@@ -428,20 +402,7 @@ function resolveSpecifier(specifier: string, fromFile: string, projectRoot: stri
 
 // ── Mixin / heritage parsing ─────────────────
 
-/**
- * The class a returned expression carries, however it is wrapped.
- *
- * A mixin does not always hand its class back bare. `Crud` returns
- * `asCrudConstructor(class CrudHandler { … })` — one assertion helper standing between
- * `return` and the class — and a parser accepting only a bare `return class` found
- * nothing there, silently: the five inherited CRUD ops stopped being derived, and a warm
- * scan cache kept answering the old parse for weeks (`scan-cache.ts` keys on source, not
- * on parser version).
- *
- * So unwrap rather than match one shape: descend through call arguments, `as` and
- * `satisfies` assertions, and parentheses. What is looked for is a class; where the
- * author put it is their business.
- */
+/** The class a returned expression carries, however it is wrapped. */
 function classInExpression(expr: ts.Node, depth = 0): ts.ClassExpression | undefined {
   const ts = getTS();
   if (depth > 8) return undefined;
@@ -502,7 +463,7 @@ function extractClassMethods(
     // `private`/`protected` is a statement about the surface, and the AST carries it —
     // it was read past. Every helper a handler names by intent (`mustOwn`, `readMany`,
     // `refuse`) became a callable op: measured on the bench, `list.readMany` executed
-    // and `list.mayPublish` judged its argument. A door is what the author declares
+    // and `list.mayPublish` validated its argument. A door is what the author declares
     // public, and TypeScript already has the word for it. `#name` is private too, but
     // it is not an identifier, so it never reached here in the first place.
     if (member.modifiers?.some((m) => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword)) continue;
@@ -521,14 +482,7 @@ function extractClassMethods(
   return results;
 }
 
-/**
- * The first sentence of a member's doc comment, or nothing.
- *
- * One sentence on purpose: what a caller needs to choose an operation is a claim,
- * not an essay, and the rest of the comment addresses whoever edits the method.
- * Reads the leading trivia rather than `ts.getJSDocTags` — the comment is what the
- * author wrote, tags are a schema they never agreed to.
- */
+/** The first sentence of a member's doc comment, or nothing. */
 function docSentenceOf(member: ts.Node, source: ts.SourceFile): string | undefined {
   const ts = getTS();
   const ranges = ts.getLeadingCommentRanges(source.text, member.pos) ?? [];
@@ -551,11 +505,7 @@ function docSentenceOf(member: ts.Node, source: ts.SourceFile): string | undefin
  * Parse inherited methods from a class's heritage clause.
  * Handles both `extends Crud(Entity)` (mixin) and `extends BaseClass` patterns.
  */
-/**
- * Where a name used here is declared. The checker follows the import, the re-export chain
- * and an installed package's types — the three cases three hand-rolled functions treated
- * separately.
- */
+/** Where a name used here is declared. */
 function declarationFileOf(node: ts.Node, checker: ts.TypeChecker): string | undefined {
   const typescript = getTS();
   let symbol = checker.getSymbolAtLocation(node);
@@ -564,13 +514,7 @@ function declarationFileOf(node: ts.Node, checker: ts.TypeChecker): string | und
   return symbol.declarations?.[0]?.getSourceFile().fileName;
 }
 
-/**
- * The methods a base class contributes, read from the INSTANTIATED type.
- *
- * `extends Crud(Post)` gives `create(input: Partial<Post>)` directly: the checker has
- * already substituted the mixin's type parameter. The three functions this replaces
- * detected the generic names and mapped them to the mixin's arguments by position.
- */
+/** The methods a base class contributes, read from the INSTANTIATED type. */
 function inheritedFromBase(
   base: ts.ExpressionWithTypeArguments,
   checker: ts.TypeChecker,
@@ -617,10 +561,8 @@ function parseInheritedMethods(
   checker: ts.TypeChecker,
   skip: Set<string>,
   /**
-   * Base classes this pass could not open — an INSTALLED one, typically, whose
-   * source is not in the workspace. Reported rather than treated as "no inherited
-   * method": the two used to be the same answer, so an op inherited from a
-   * published base class was absent from the façade without a word.
+   * Base classes this pass could not open — an INSTALLED one, typically, whose source is not in
+   * the workspace.
    */
   unresolved: string[],
 ): Signature[] {
@@ -685,14 +627,7 @@ function findDefaultClass(source: ts.SourceFile): ts.ClassDeclaration | undefine
   return undefined;
 }
 
-/**
- * What a handler file yielded — its methods, AND what the pass could not open.
- *
- * The second half is why this is a pair rather than an array: an unresolvable base
- * class used to give the same answer as a base class with no method, so an op
- * inherited from an installed package was missing from the façade in silence. The
- * pair travels through the scan cache, which is why {@link PARSER_VERSION} moved.
- */
+/** What a handler file yielded — its methods, AND what the pass could not open. */
 export interface HandlerParse {
   methods: Signature[];
   /** Base classes whose source this pass could not open. Empty is a claim. */
@@ -708,11 +643,7 @@ export async function parseAllHandlerMethods(filePath: string, projectRoot?: str
   return parseClassMethods(filePath, CONSTRUCTOR_ONLY, projectRoot);
 }
 
-/**
- * Parse a presenter source file and extract all method signatures.
- *
- * Returns all methods (no CRUD filtering) — each method is a computed field.
- */
+/** Parse a presenter source file and extract all method signatures. */
 export async function parsePresenterMethods(filePath: string, projectRoot?: string): Promise<Signature[]> {
   await loadTS();
   // No `projectRoot`, so no heritage pass and nothing to report: a presenter's

package/src/scan/result.ts

@@ -1,24 +1,11 @@
 import type { Fronds } from '../descriptor/Fronds.js';
 
 /** Result of scanning a project directory. */
-/**
- * Something the scan could NOT do — recorded instead of swallowed.
- *
- * The scan answers with what it found. Until now it answered the same way whether
- * a directory held nothing or could not be read, and whether a handler declared no
- * operation or failed to parse: `catch → empty`. So every downstream reader — the
- * façade, the identity card, anything asking "what does this app serve?" — could
- * not tell **"there is nothing"** from **"I could not look"**.
- *
- * That distinction is what makes a rule about an ABSENCE sound. Without it, a check
- * derived from the scan reports "nothing wrong" precisely when it read nothing.
- */
+/** Something the scan could NOT do — recorded instead of swallowed. */
 export interface ScanDiagnostic {
   /**
-   * `blocking` — the app now serves less than its source declares, and no caller
-   * can know it: a handler that failed to parse contributes zero operations.
-   * `warning` — something may be missing and the scan cannot decide, e.g. a base
-   * class it is not allowed to resolve. Statable in `frond.config.ts`.
+   * `blocking` — the app now serves less than its source declares, and no caller can know it: a
+   * handler that failed to parse contributes zero operations.
    */
   severity: 'blocking' | 'warning';
   /** Stable rule name — `handler-parse-failed`, `directory-unreadable`. */

package/src/scan/scanner.ts

@@ -31,13 +31,7 @@ import {
 
 // FS
 
-/**
- * What this scan run could not do. Reset by {@link scanProject}, which owns a run.
- *
- * Module-scoped like the loader and the cache root above: the scanner already has a
- * notion of "the current run". Three sites record — measured — so a per-run object
- * would carry twenty methods to spare one line of reset.
- */
+/** What this scan run could not do. */
 let diagnostics: ScanDiagnostic[] = [];
 
 function record(d: ScanDiagnostic): void {
@@ -45,10 +39,8 @@ function record(d: ScanDiagnostic): void {
 }
 
 /**
- * An absent convention directory is the ordinary case — a frond without
- * `presenters/` is not a defect. Anything else (permissions, an I/O error, a path
- * that is not a directory) means the scan did not look, and answering `[]` says
- * it did. One `catch` used to conflate the two.
+ * An absent convention directory is the ordinary case — a frond without `presenters/` is not a
+ * defect.
  */
 async function readEntries(path: string): Promise<Dirent[]> {
   try {
@@ -94,8 +86,18 @@ async function loadDefault(filePath: string): Promise<unknown> {
 
 async function loadClass(filePath: string): Promise<ProviderEntry['ctor']> {
   const ctor = await loadDefault(filePath);
-  if (typeof ctor !== 'function' || !ctor.prototype)
-    throw new Error(`${filePath}: default export is not a class`);
+  // A convention directory holds classes, because a provider is registered under one and
+  // asked for by its type. What is NOT a class — a shared contract, a pure function, a
+  // table of constants — belongs beside them rather than among them, and saying where
+  // costs one line: measured twice on a real project, both times a file that had to move.
+  if (typeof ctor !== 'function' || !ctor.prototype) {
+    throw new Error(
+      `${filePath}: default export is not a class. This directory is scanned for providers, `
+      + 'which are registered under a class name — a contract or a pure function has no key '
+      + `to answer under. Move it beside the directory, at the frond's root, where the scan `
+      + 'reads nothing and an import still reaches it.',
+    );
+  }
   return ctor as ProviderEntry['ctor'];
 }
 
@@ -115,13 +117,7 @@ function findWorkspaceRoot(from: string): string {
   return resolvePath(from); // fallback: use project root itself
 }
 
-/**
- * Strip the 'Handler' suffix → the name the handler answers to. 'PostHandler' → 'post'.
- *
- * Nothing here checks that an entity carries the result, and nothing should: a handler
- * about no stored row is ordinary. The old name of this function — `toEntityName` — is
- * what let "one façade per entity" be repeated until it read as a rule.
- */
+/** Strip the 'Handler' suffix → the name the handler answers to. */
 function toAddress(className: string): string {
   const base = className.endsWith('Handler') ? className.slice(0, -7) : className;
   return lowerFirst(base);
@@ -130,18 +126,8 @@ function toAddress(className: string): string {
 // Scan
 
 /**
- * The container key a constructor parameter asks for — derived from its TYPE, not from
- * how the type was spelled.
- *
- * `deps` used to be `p.type.name`, so the key WAS the alias's name: `type ListStorage =
- * Storage<List>` resolved only because someone had spelled it exactly like the
- * registration key (`ListStorage`), while `type ListRepo = Storage<List>` — the same type —
- * typechecked and died at boot on `'ListRepo' is not registered`. And `Storage<List>`
- * written out in full asked for `'Storage'`, which nothing registers.
- *
- * `Storage<X>` names X's storage, so that is the key. The generic argument was already
- * parsed (`TypeRef.generics`) and thrown away. Anything else keeps its own name: a
- * plain service IS designated by its class name.
+ * The container key a constructor parameter asks for — derived from its TYPE, not from how the
+ * type was spelled.
  */
 function depKeyOf(type: TypeRef): string {
   // `Facade<PostHandler>` — the second port, read exactly like the first. The type names
@@ -166,32 +152,25 @@ function depKeyOf(type: TypeRef): string {
   // `RepositoryOf<Post>` — what an author writes when no repository file exists. The dual
   // of the line below: one names the port, the other the holder, and both resolve to a key
   // rather than to a class the author would have to invent.
-  const held = type.name === 'RepositoryOf' ? type.generics?.[0]?.name : undefined;
-  if (held) return repositoryKeyOf(held);
+  const subject = type.name === 'RepositoryOf' ? type.generics?.[0]?.name : undefined;
+  if (subject) return repositoryKeyOf(subject);
 
-  const target = type.name === 'Storage' ? type.generics?.[0]?.name : undefined;
+  // The GENERIC names the subject, so a prefix does not change the key — `MeiliStorage<Card>`
+  // is `Card`'s storage. A class named `FileStorage` is untouched: it carries no generic.
+  const target = type.name.endsWith('Storage') && type.generics?.length === 1
+    ? type.generics[0]?.name
+    : undefined;
   if (!target) return type.name;
 
   return storageKeyOf(target);
 }
 
-/**
- * `'[Account, Ledger]'` → `['Account', 'Ledger']`.
- *
- * The tuple was chosen over the variadic form the parser reads more cleanly, because the
- * variadic one costs arities-with-defaults and a `never` filter on the TypeScript side
- * while the tuple maps to `[Storage<Account>, Storage<Ledger>]` in one line. The
- * parser does not get to decide alone; this split is what that choice costs.
- */
+/** `'[Account, Ledger]'` → `['Account', 'Ledger']`. */
 function tupleMembers(raw: string): string[] {
   return raw.replace(/^\[|\]$/g, '').split(',').map((member) => member.trim()).filter(Boolean);
 }
 
-/**
- * These readings are semantic: an unchanged file can mean something different after an
- * imported alias changes. The parser's TypeScript Program is the cache for one scan; a
- * cache keyed only by this file's bytes would be unsound.
- */
+/** These readings are semantic. */
 const ctorParamsOf = (filePath: string) =>
   parseConstructorParams(filePath);
 
@@ -203,6 +182,9 @@ const handlerMethodsOf = (filePath: string, projectRoot?: string) =>
 
 async function toProvider(filePath: string): Promise<ProviderEntry> {
   const ctor = await loadClass(filePath);
+  // Read here, while the class is the one the source declared. What a bundler does to
+  // that name later is why it is carried rather than asked for again.
+  const name = ctor.name;
   const params = await ctorParamsOf(filePath);
   const deps = params.map((p) => depKeyOf(p.type));
 
@@ -222,10 +204,10 @@ async function toProvider(filePath: string): Promise<ProviderEntry> {
     deps.push(storageKeyOf(lowerFirst((target as { name: string }).name)));
   }
 
-  // No `name` beside `ctor`: a provider registers under `ctor.name`, which is what
-  // `depKeyOf` returns since it reads the type as written. The camelCase field that
-  // used to sit here called itself the registration key and was one nowhere.
-  return { ctor, deps, filePath };
+  // `name` beside `ctor`, and it IS the registration key — what `depKeyOf` returns, since
+  // it reads the type as written. It used to be asked of `ctor.name` at boot, which held
+  // until a bundler lowered a static field and renamed the declaration doing it.
+  return { name, ctor, deps, filePath };
 }
 
 async function toEntityEntry(filePath: string): Promise<EntityEntry | null> {
@@ -272,12 +254,7 @@ function resolveSchema(type: TypeRef, moduleExports: Record<string, unknown>): S
   return undefined;
 }
 
-/**
- * Parse ALL method signatures for unified binding.
- *
- * Resolves schemas for all params (not just the first) and stores
- * full signatures for the binding algorithm.
- */
+/** Parse ALL method signatures for unified binding. */
 async function inferOperations(
   filePath: string,
   handlerName: string,
@@ -308,15 +285,8 @@ async function inferOperations(
   }
 
   /**
-   * A base class the parse could not open — an installed package, typically, whose
-   * source is not in the workspace. Its operations are missing from this façade, and
-   * the scan cannot tell whether there were any.
-   *
-   * A warning, not a refusal: an installed base class with no operation is perfectly
-   * ordinary, and the boot has no way to decide between the two. So it names the
-   * clause and stops there. Stating the contract in `frond.config.ts` is the answer
-   * — the third producer, which creates an op neither other producer found — and it
-   * silences this by making the op exist.
+   * A base class the parse could not open — an installed package, typically, whose source is not
+   * in the workspace.
    */
   for (const base of parsed.unresolvedHeritage) {
     record({
@@ -342,10 +312,10 @@ async function inferOperations(
     // caller supplies through the body are candidates: a schema-typed collector, fact or
     // context parameter is not input merely because it names an entity. The old loop
     // ignored provenance and assigned the first schema it met, so swapping two parameters
-    // silently changed the contract the façade used to judge the request body.
+    // silently changed the contract the façade used to validate the request body.
     const binding = computeBindingPlan(method.params, collectorTypeNames);
     const candidates = method.params.flatMap((param, index) => {
-      if (binding[index]?.source.kind !== 'body') return [];
+      if (binding[index]?.source.kind !== 'input') return [];
       const schema = resolveSchema(param.type, moduleExports);
       return schema ? [{ param, schema }] : [];
     });
@@ -522,13 +492,7 @@ async function scanFrond(frondPath: string, name: string, source: FrondDescripto
     entities: entitiesDir, handlers: handlersDir,
     presenters: presentersDir, collectors: collectorsDir, seeds: seedsDir,
   } = conventions.dirs;
-  /**
-   * A convention directory, read by whoever knows the shape it holds.
-   *
-   * The same three lines were written six times — list, read in parallel, drop what the
-   * reader refused — which is what made `handlers/` quietly special: it grew a second
-   * pass for its surfaces and nothing else could.
-   */
+  /** A convention directory, read by whoever knows the shape it holds. */
   const collect = async <T extends object>(
     dir: string,
     read: (filePath: string) => Promise<T | null>,
@@ -615,15 +579,7 @@ async function scanFrond(frondPath: string, name: string, source: FrondDescripto
   };
 }
 
-/**
- * The frond's name — the directory, unless its `package.json` renames it. One rule for a
- * frond under `fronds/` and for the root frond alike, so the root needs no second spelling.
- *
- * Carrying the convention is what makes a frond; the key never marked anything and
- * nothing read it. It earns its keep as the one thing the directory cannot say: that
- * `fronds/blog-v2/` serves the frond still called `blog` — so a rename on disk does not
- * rename the entity keys, the `@fronds/*` import or a `remotes:` entry.
- */
+/** The frond's name — the directory, unless its `package.json` renames it. */
 async function frondNameOf(frondPath: string, dirName: string): Promise<string> {
   try {
     const pkg = JSON.parse(await readFile(join(frondPath, 'package.json'), 'utf8')) as {
@@ -637,15 +593,8 @@ async function frondNameOf(frondPath: string, dirName: string): Promise<string>
 }
 
 /**
- * A frond is a directory carrying the convention, and the project root is one such
- * directory — so a single-domain app writes `entities/` next to `app/` and never names
- * anything. `fronds/` is not the definition, it is where the OTHERS live: the root frond
- * stays put when a second domain appears, which is what makes flattening free instead of
- * a deferred move.
- *
- * `entities/` is the test, not "any convention directory". `services/` and `repositories/`
- * are ordinary top-level names in projects that never heard of Fougere, and a domain
- * without a single entity is not a domain.
+ * A frond is a directory carrying the convention, and the project root is one such directory — so
+ * a single-domain app writes `entities/` next to `app/` and never names anything.
  */
 async function rootFrondOf(root: string, workspaceRoot: string, conventions: Conventions): Promise<FrondDescriptor | null> {
   if ((await files(join(root, conventions.dirs.entities))).length === 0) return null;
@@ -653,21 +602,7 @@ async function rootFrondOf(root: string, workspaceRoot: string, conventions: Con
   return scanFrond(root, name, { path: root, package: frondPackage(name, conventions) }, conventions, workspaceRoot);
 }
 
-/**
- * `@fronds/<name>` → the directory it names, for every frond of a project.
- *
- * The framework states this convention — `FrondSource.package` has always spelled it, and
- * `fougere sync` writes it into a consumer's tsconfig — and until now its own reader could
- * not resolve it. The Nuxt module registered a Vite alias, so a `.vue` page could import
- * `@fronds/blog/entities/Post`, while the SCAN loaded sources through a bare jiti: a frond
- * naming its neighbour got `Cannot find module '@fronds/user/entities/User.js'`. So the one
- * form that survives a split was the one form that did not run.
- *
- * Hand it to the module loader — `createJiti(url, { alias: await frondAliases(root) })` —
- * and the named form resolves everywhere the framework reads. A directory listing and a
- * `package.json` read, no parsing: it is deliberately callable BEFORE the loader exists,
- * which is what makes the chicken-and-egg go away.
- */
+/** `@fronds/<name>` → the directory it names, for every frond of a project. */
 export async function frondAliases(root: string, conventions: Conventions = DEFAULT_CONVENTIONS): Promise<Record<string, string>> {
   const frondsDir = join(root, conventions.fronds);
   const aliases: Record<string, string> = {};
@@ -681,17 +616,7 @@ export async function frondAliases(root: string, conventions: Conventions = DEFA
     aliases[frondPackage(await frondNameOf(path, dir), conventions)] = resolvePath(path);
   }
 
-  /**
-   * A SYNCED frond answers to the same name.
-   *
-   * `fougere sync` writes `.fougere/remotes/<name>/` and registers it in `remotes.json`,
-   * which the Nuxt module already reads to alias `@fronds/<name>`. Doing it here too is
-   * what makes the convention mean ONE thing: a consumer writes `@fronds/blog/entities/Post`
-   * and never learns whether that frond is on this disk or was fetched from a card.
-   *
-   * A local frond wins a name collision — its source is the truth, a synced copy is a
-   * mirror of somebody else's.
-   */
+  /** A SYNCED frond answers to the same name. */
   try {
     const registry = JSON.parse(
       await readFile(join(root, '.fougere', 'remotes.json'), 'utf8'),
@@ -757,18 +682,7 @@ export async function scanProject(
   return { fronds, diagnostics };
 }
 
-/**
- * What changes when a frond's domain changes — the paths a dev loop watches.
- *
- * It lives beside the scan rather than beside the conventions it reads, because it turns
- * names into DISK paths: `join` is `node:path`, and `conventions.ts` is reached from
- * `index` through `frond()`, which an edge bundle imports. Measured — esbuild refused the
- * Worker with `Could not resolve "node:path"`.
- *
- * The root frond IS the scan root, so watching its path would match every write in the
- * project: `.nuxt/`, `node_modules/`, the build output. Its convention directories are
- * the frond, and they are what a scan re-reads.
- */
+/** What changes when a frond's domain changes — the paths a dev loop watches. */
 export function watchPathsOf(
   frond: { source: { path: string } },
   scanRoot: string,