LibreChat/config/circular-deps.mjs
Marco Beretta c00c776e0e
📦 feat: Scaffold the @librechat/chat Package (#16964)
* feat: Scaffold the @librechat/chat package

Adds packages/chat with core, react and components entries, a tsdown build,
a node-environment jest config, turbo and root build wiring, import boundary
rules, design-lint scope, and core types for the chat transport, stream,
host and status. No code moves yet.

* test: Cover the @librechat/chat boundaries as scenarios

* fix: Run the chat suite in test:turbo and build it for the mock lane

test:turbo now selects @librechat/chat, the mock e2e job builds the package the
chat-package scenarios load, and the synthetic repository in the suppression
scenarios carries the packages/chat/src root lint:design:record names.

* chore: Build the chat package in frontend:ci too

* chore: Run the chat suite in test:all

* fix: Hold core TSX to the chat boundary and scan the package for cycles

* fix: Apply the chat import boundary to JavaScript sources

* fix: Keep nested core files off the components entry

* fix: Close the remaining chat package gates and fence aborts by generation

Blocks imports through the @librechat/frontend workspace name, adds the chat
sources to the i18n scan, the CSS color gate and the client Tailwind content,
and lets ChatAbortRequest carry the generation it means to stop.

* fix: Keep JSX out of the chat core and carry abort and reconnect outcomes

Rejects JSX under the core, copies the chat manifest before the Docker
install, keys the client app build caches on the chat sources, fences
reconnects by generation, and types the abort result the transport returns.

* test: Give the CSS gate's scratch tree the chat root it now scans

* fix: Close the remaining @librechat/chat gates and wiring

Rejects import() and require() across the package boundaries, holds chat
components to the literal-copy rule, compiles TSX in the package's jest
transform, builds the package in Frontend Unit Tests, requires its test job for
main promotion, adds it to the unused-dependency scan, and lists it wherever a
sibling workspace is listed: Dockerfile.multi, the docker smoke paths, the
remaining node_modules caches, the reinstall helper, the bun build chain and
AGENTS.md.

* fix: Tighten the chat boundaries and carry steering and Assistants aborts

Template-literal import() and require() and self-imports through the package
name are rejected, user-facing JSX attributes need localized text, the cycle
scan resolves self-imports, Dockerfile.multi builds the package for the client
stage, and the transport carries steer, cancelSteer, armSteer and the
Assistants abort key.

* feat: Match the chat transport and host contracts to the client's

The transport now reports settled and replaced starts, the stream's protocol
version and resumed flag, reconnect replay, generation status, paused-run
resume with approvals or answers, abort and steer protocol versions, and the
request error shape. The host config and auth carry what the client's
ChatSettings now supplies: rename-while-running, model specs, retention mode
and the user.

* fix: Keep lazy React-entry loads out of the core and type the Assistants stop

Relative import() and require() of the /react entry from core are rejected,
and an abortKey stop resolves to the terminal conversation and run messages the
Assistants route returns.

* fix: Fence start controls by protocol and close extension-bearing entry loads

Settled and replaced start results carry the protocol version, core loads of
the /react or /components entry with a file extension are rejected, and
test:packages:chat builds data-provider first.
2026-10-10 21:00:10 +02:00

233 lines
8 KiB
JavaScript

import path from 'node:path';
import { createRequire } from 'node:module';
import { fileURLToPath, pathToFileURL } from 'node:url';
const root = path.resolve(fileURLToPath(import.meta.url), '../..');
/**
* Module graphs checked for cycles. `alias` mirrors each target's tsconfig
* paths (or module-alias for the legacy server); `internal` lists the aliased
* specifier prefixes that are first-party alongside relative/absolute imports.
* `minModules` is a resolution-rot guard: if a graph shrinks below it, the
* scan is no longer seeing the real codebase and must fail rather than
* silently pass.
*/
const targets = [
{
name: '@librechat/api',
dir: 'packages/api',
entries: ['src/index.ts', 'src/telemetry.ts'],
alias: { '~': 'src' },
internal: ['~'],
minModules: 200,
},
{
name: 'librechat-data-provider',
dir: 'packages/data-provider',
entries: ['src/index.ts', 'src/react-query/index.ts'],
alias: { 'librechat-data-provider/react-query': 'src/react-query/index.ts', src: 'src' },
internal: ['src/', 'librechat-data-provider/react-query'],
minModules: 20,
/**
* Grandfathered: the core type modules (schemas, config, api-endpoints,
* types/{assistants,agents,runs,web}) hold six pre-existing type-only
* knots that need their own untangling PR. Runtime edges are still
* enforced; the exclusion is logged on every run so it cannot read as
* full coverage.
*/
typeEdges: false,
},
{
name: '@librechat/data-schemas',
dir: 'packages/data-schemas',
entries: ['src/index.ts', 'src/admin/capabilities.ts'],
alias: { '~': 'src' },
internal: ['~'],
minModules: 75,
},
{
name: '@librechat/client',
dir: 'packages/client',
entries: ['src/index.ts'],
alias: { '~': 'src' },
internal: ['~'],
minModules: 100,
},
{
name: '@librechat/chat',
dir: 'packages/chat',
entries: ['src/index.ts', 'src/react.ts', 'src/components.ts'],
/** A self-import through the package name crosses an entry; resolve it so the scan sees it. */
alias: {
'@librechat/chat/components': 'src/components.ts',
'@librechat/chat/react': 'src/react.ts',
'@librechat/chat': 'src/index.ts',
},
internal: ['@librechat/chat'],
minModules: 3,
},
{
name: 'api server',
dir: 'api',
entries: ['server/index.js'],
alias: { '~': '.' },
internal: ['~'],
minModules: 150,
},
];
/**
* Recursively collects every type-only dependency specifier: `import type` /
* `export type ... from` declarations, inline type specifiers (`import { type
* Foo } from` — kind lives on the child specifier, source on the parent), and
* `import('...')` type expressions (TSImportType), which nest arbitrarily deep
* inside other declarations. All forms carry the specifier as `source.value`.
*/
const collectTypeSpecifiers = (node, specifiers) => {
if (node === null || typeof node !== 'object') {
return;
}
if (Array.isArray(node)) {
for (const item of node) {
collectTypeSpecifiers(item, specifiers);
}
return;
}
const typeOnly =
node.type === 'TSImportType' ||
(node.importKind ?? node.exportKind) === 'type' ||
(Array.isArray(node.specifiers) &&
node.specifiers.some((s) => (s.importKind ?? s.exportKind) === 'type'));
if (typeOnly && typeof node.source?.value === 'string') {
specifiers.add(node.source.value);
}
for (const value of Object.values(node)) {
if (value !== null && typeof value === 'object') {
collectTypeSpecifiers(value, specifiers);
}
}
};
/**
* Bundlers erase type-only edges before building the module graph, so purely
* type-level cycles (the declaration-graph kind) would never be reported.
* Re-materialize each type-only specifier as a bare side-effect import so the
* scanned graph carries type edges too. Uses the real parser (not a regex) so
* imports inside string templates never count.
*/
const typeEdgesPlugin = (parseAst) => ({
name: 'type-edges',
transform(code, id) {
const extension = /\.([mc]?tsx?)(?:$|\?)/.exec(id)?.[1];
if (!extension) {
return null;
}
const { body } = parseAst(code, { lang: extension.endsWith('x') ? 'tsx' : 'ts' });
const specifiers = new Set();
collectTypeSpecifiers(body, specifiers);
if (specifiers.size === 0) {
return null;
}
const edges = [...specifiers].map((s) => `\nimport ${JSON.stringify(s)};`).join('');
return { code: code + edges, map: null };
},
});
/** Stub style/asset imports: rolldown no longer bundles CSS, and assets carry no module edges. */
const assetsPlugin = {
name: 'assets-as-empty',
load(id) {
if (/\.(css|scss|sass|less|svg|png|jpe?g|gif|webp)(?:$|\?)/.test(id)) {
return { code: 'export {};', moduleType: 'js' };
}
return null;
},
};
/** Loads the rolldown instance the tsdown builds run on, keeping resolution semantics identical. */
async function loadRolldown() {
const apiRequire = createRequire(path.join(root, 'packages/api/package.json'));
const tsdownRequire = createRequire(apiRequire.resolve('tsdown'));
const { rolldown } = await import(pathToFileURL(tsdownRequire.resolve('rolldown')).href);
const { parseAst } = await import(pathToFileURL(tsdownRequire.resolve('rolldown/parseAst')).href);
return { rolldown, parseAst };
}
// eslint-disable-next-line no-control-regex
const stripAnsi = (message) => message.replace(/\u001B\[[0-9;]*m/g, '');
const relativize = (message) => stripAnsi(message).replaceAll(root + path.sep, '');
async function scan({ rolldown, parseAst }, target) {
const cycles = [];
const unresolved = [];
const isInternal = (id) =>
id.startsWith('.') || path.isAbsolute(id) || target.internal.some((p) => id.startsWith(p));
const alias = Object.fromEntries(
Object.entries(target.alias).map(([key, dir]) => [key, path.join(root, target.dir, dir)]),
);
try {
const build = await rolldown({
input: target.entries.map((entry) => path.join(root, target.dir, entry)),
platform: 'node',
resolve: { alias },
external: (id) => !isInternal(id),
plugins: [...(target.typeEdges === false ? [] : [typeEdgesPlugin(parseAst)]), assetsPlugin],
checks: { circularDependency: true },
onLog(_level, log) {
if (log.code === 'CIRCULAR_DEPENDENCY') {
cycles.push(relativize(log.message));
} else if (log.code === 'UNRESOLVED_IMPORT') {
unresolved.push(relativize(log.message));
}
},
});
const { output } = await build.generate({ format: 'cjs' });
const modules = output.reduce((sum, chunk) => sum + (chunk.moduleIds?.length ?? 0), 0);
await build.close();
return { target, cycles, unresolved, modules, error: null };
} catch (error) {
return { target, cycles, unresolved, modules: 0, error };
}
}
function report({ target, cycles, unresolved, modules, error }) {
const problems = [];
if (error) {
problems.push(`build failed: ${relativize(error.message)}`);
}
if (cycles.length > 0) {
problems.push(...cycles);
}
if (unresolved.length > 0) {
problems.push(...unresolved.map((message) => `unresolved first-party import: ${message}`));
}
if (!error && modules < target.minModules) {
problems.push(
`graph has ${modules} modules, below the ${target.minModules} floor; the scan is no longer resolving the real codebase`,
);
}
if (problems.length === 0) {
const scope =
target.typeEdges === false
? 'runtime edges only, type edges grandfathered'
: 'runtime + type edges';
console.log(`✓ ${target.name}: no circular dependencies (${modules} modules, ${scope})`);
return true;
}
console.error(`✗ ${target.name}:`);
for (const problem of problems) {
console.error(` ${problem}`);
}
return false;
}
const engine = await loadRolldown();
const results = await Promise.all(targets.map((target) => scan(engine, target)));
const passed = results.map(report).every(Boolean);
if (!passed) {
console.error('\nCircular dependency check failed.');
process.exit(1);
}