@vegamo/loom 0.1.1

package/dist/shared/entity-utils.js

@@ -0,0 +1,207 @@
+/**
+ * 实体文件与实体引用工具
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+export const ENTITY_DIRNAME = 'entities';
+export const ENTITY_FILENAME_SUFFIX = '.entity.schema.json';
+function toKebabCase(value) {
+    return value
+        .trim()
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/[^a-zA-Z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .toLowerCase();
+}
+function normalizeToken(value) {
+    return value.replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
+}
+export function getEntitiesDir(outDir) {
+    return path.join(outDir, ENTITY_DIRNAME);
+}
+export function toEntityFilename(entityName) {
+    const base = toKebabCase(entityName);
+    if (!base) {
+        throw new Error('Entity name is empty.');
+    }
+    return `${base}${ENTITY_FILENAME_SUFFIX}`;
+}
+function readEntityByPath(filepath) {
+    const raw = fs.readFileSync(filepath, 'utf-8');
+    return JSON.parse(raw);
+}
+export function isValidEntityDocument(obj) {
+    if (typeof obj !== 'object' || obj === null) {
+        return false;
+    }
+    const entity = obj;
+    return (typeof entity.title === 'string' &&
+        entity.type === 'object' &&
+        typeof entity.properties === 'object' &&
+        entity.properties !== null &&
+        !Array.isArray(entity.properties));
+}
+export function listEntityFiles(outDir) {
+    const entitiesDir = getEntitiesDir(outDir);
+    if (!fs.existsSync(entitiesDir)) {
+        return [];
+    }
+    const files = fs
+        .readdirSync(entitiesDir)
+        .filter((f) => f.endsWith(ENTITY_FILENAME_SUFFIX))
+        .sort();
+    return files.map((filename) => {
+        const filepath = path.join(entitiesDir, filename);
+        const stat = fs.statSync(filepath);
+        const doc = readEntityByPath(filepath);
+        const properties = typeof doc.properties === 'object' && doc.properties && !Array.isArray(doc.properties)
+            ? doc.properties
+            : {};
+        return {
+            filename,
+            filepath,
+            title: typeof doc.title === 'string' ? doc.title : filename,
+            description: typeof doc.description === 'string' ? doc.description : '',
+            fieldCount: Object.keys(properties).length,
+            updatedAt: stat.mtime,
+        };
+    });
+}
+export function readEntityFile(outDir, filename) {
+    const filepath = path.join(getEntitiesDir(outDir), filename);
+    return readEntityByPath(filepath);
+}
+export function writeEntityFile(outDir, filename, doc) {
+    const entitiesDir = getEntitiesDir(outDir);
+    if (!fs.existsSync(entitiesDir)) {
+        fs.mkdirSync(entitiesDir, { recursive: true });
+    }
+    const filepath = path.join(entitiesDir, filename);
+    fs.writeFileSync(filepath, `${JSON.stringify(doc, null, 2)}\n`, 'utf-8');
+}
+/**
+ * 根据实体名或文件名解析到真实文件名
+ */
+export function resolveEntityFilename(outDir, nameOrFilename) {
+    const entities = listEntityFiles(outDir);
+    if (entities.length === 0) {
+        return null;
+    }
+    const isFilenameInput = nameOrFilename.endsWith(ENTITY_FILENAME_SUFFIX);
+    if (isFilenameInput) {
+        const found = entities.find((e) => e.filename === nameOrFilename);
+        return found ? found.filename : null;
+    }
+    const normalizedInput = normalizeToken(nameOrFilename);
+    const byFileBase = entities.find((e) => normalizeToken(e.filename.replace(ENTITY_FILENAME_SUFFIX, '')) === normalizedInput);
+    if (byFileBase) {
+        return byFileBase.filename;
+    }
+    const byTitle = entities.find((e) => normalizeToken(e.title) === normalizedInput);
+    return byTitle ? byTitle.filename : null;
+}
+function parseStringArray(raw) {
+    if (!Array.isArray(raw)) {
+        return null;
+    }
+    if (!raw.every((item) => typeof item === 'string' && item.trim().length > 0)) {
+        return null;
+    }
+    return raw.map((item) => item.trim());
+}
+/**
+ * 解析 x-entity-ref:
+ * - "User"
+ * - { "entity": "User", "pick": ["id", "name"] }
+ */
+export function parseEntityRefConfig(raw) {
+    if (typeof raw === 'string' && raw.trim()) {
+        return { entity: raw.trim() };
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return null;
+    }
+    const obj = raw;
+    if (typeof obj.entity !== 'string' || !obj.entity.trim()) {
+        return null;
+    }
+    const parsed = { entity: obj.entity.trim() };
+    const pick = parseStringArray(obj.pick);
+    const omit = parseStringArray(obj.omit);
+    const required = parseStringArray(obj.required);
+    if (obj.pick !== undefined && pick === null) {
+        return null;
+    }
+    if (obj.omit !== undefined && omit === null) {
+        return null;
+    }
+    if (obj.required !== undefined && required === null) {
+        return null;
+    }
+    if (pick && pick.length > 0) {
+        parsed.pick = pick;
+    }
+    if (omit && omit.length > 0) {
+        parsed.omit = omit;
+    }
+    if (required && required.length > 0) {
+        parsed.required = required;
+    }
+    return parsed;
+}
+function deepClone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function ensureObjectProperties(entitySchema) {
+    const properties = entitySchema.properties;
+    if (typeof properties !== 'object' || properties === null || Array.isArray(properties)) {
+        throw new Error('Entity schema must contain an object "properties" field.');
+    }
+    return properties;
+}
+/**
+ * 根据实体和 ref 配置，生成引用后的 schema 片段
+ */
+export function resolveEntitySchemaByRef(entity, ref) {
+    const base = deepClone(entity);
+    const properties = ensureObjectProperties(base);
+    const allFields = Object.keys(properties);
+    let selected = [...allFields];
+    if (ref.pick && ref.pick.length > 0) {
+        const missing = ref.pick.filter((field) => !allFields.includes(field));
+        if (missing.length > 0) {
+            throw new Error(`Fields not found in entity "${ref.entity}": ${missing.join(', ')}`);
+        }
+        selected = [...ref.pick];
+    }
+    if (ref.omit && ref.omit.length > 0) {
+        const missing = ref.omit.filter((field) => !allFields.includes(field));
+        if (missing.length > 0) {
+            throw new Error(`Fields not found in entity "${ref.entity}": ${missing.join(', ')}`);
+        }
+        selected = selected.filter((field) => !ref.omit?.includes(field));
+    }
+    const selectedProperties = {};
+    for (const key of selected) {
+        selectedProperties[key] = deepClone(properties[key]);
+    }
+    base.properties = selectedProperties;
+    const baseRequiredRaw = Array.isArray(base.required) ? base.required : [];
+    const baseRequired = baseRequiredRaw.filter((item) => typeof item === 'string');
+    let required = baseRequired.filter((field) => selected.includes(field));
+    if (ref.required && ref.required.length > 0) {
+        const missing = ref.required.filter((field) => !selected.includes(field));
+        if (missing.length > 0) {
+            throw new Error(`Required fields are not selected in entity "${ref.entity}": ${missing.join(', ')}`);
+        }
+        required = [...ref.required];
+    }
+    if (required.length > 0) {
+        base.required = required;
+    }
+    else {
+        delete base.required;
+    }
+    return { schema: base, fields: selected };
+}
+//# sourceMappingURL=entity-utils.js.map

package/dist/shared/entity-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-utils.js","sourceRoot":"","sources":["../../src/shared/entity-utils.ts"],"names":[],"mappings":"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"}

package/dist/shared/logger.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 日志工具
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export declare function setLogLevel(level: LogLevel): void;
+export declare const logger: {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    success(message: string, ...args: unknown[]): void;
+};
+//# sourceMappingURL=logger.d.ts.map

package/dist/shared/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/shared/logger.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAW3D,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAEjD;AAMD,eAAO,MAAM,MAAM;mBACF,MAAM,WAAW,OAAO,EAAE,GAAG,IAAI;kBAMlC,MAAM,WAAW,OAAO,EAAE,GAAG,IAAI;kBAMjC,MAAM,WAAW,OAAO,EAAE,GAAG,IAAI;mBAMhC,MAAM,WAAW,OAAO,EAAE,GAAG,IAAI;qBAM/B,MAAM,WAAW,OAAO,EAAE,GAAG,IAAI;CAKnD,CAAC"}

package/dist/shared/logger.js

@@ -0,0 +1,45 @@
+/**
+ * 日志工具
+ */
+import chalk from 'chalk';
+let currentLevel = 'info';
+const LEVEL_PRIORITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+export function setLogLevel(level) {
+    currentLevel = level;
+}
+function shouldLog(level) {
+    return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[currentLevel];
+}
+export const logger = {
+    debug(message, ...args) {
+        if (shouldLog('debug')) {
+            console.debug(chalk.gray(`[debug] ${message}`), ...args);
+        }
+    },
+    info(message, ...args) {
+        if (shouldLog('info')) {
+            console.log(chalk.blue(`[info] ${message}`), ...args);
+        }
+    },
+    warn(message, ...args) {
+        if (shouldLog('warn')) {
+            console.warn(chalk.yellow(`[warn] ${message}`), ...args);
+        }
+    },
+    error(message, ...args) {
+        if (shouldLog('error')) {
+            console.error(chalk.red(`[error] ${message}`), ...args);
+        }
+    },
+    success(message, ...args) {
+        if (shouldLog('info')) {
+            console.log(chalk.green(`[ok] ${message}`), ...args);
+        }
+    },
+};
+//# sourceMappingURL=logger.js.map

package/dist/shared/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/shared/logger.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B,IAAI,YAAY,GAAa,MAAM,CAAC;AAEpC,MAAM,cAAc,GAA6B;IAC/C,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;CACT,CAAC;AAEF,MAAM,UAAU,WAAW,CAAC,KAAe;IACzC,YAAY,GAAG,KAAK,CAAC;AACvB,CAAC;AAED,SAAS,SAAS,CAAC,KAAe;IAChC,OAAO,cAAc,CAAC,KAAK,CAAC,IAAI,cAAc,CAAC,YAAY,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,KAAK,CAAC,OAAe,EAAE,GAAG,IAAe;QACvC,IAAI,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,OAAO,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,GAAG,IAAe;QACtC,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YACtB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,OAAO,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,GAAG,IAAe;QACtC,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YACtB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,OAAO,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,GAAG,IAAe;QACvC,IAAI,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,WAAW,OAAO,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IAED,OAAO,CAAC,OAAe,EAAE,GAAG,IAAe;QACzC,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YACtB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,OAAO,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;CACF,CAAC"}

package/dist/shared/manifest-utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * docs 索引 (manifest) 工具
+ */
+import type { LoomManifest } from './types.js';
+export declare function getManifestPath(outDir: string): string;
+export declare function buildManifest(outDir: string): LoomManifest;
+export declare function writeManifest(outDir: string, manifest: LoomManifest): void;
+export declare function rebuildManifest(outDir: string): LoomManifest;
+//# sourceMappingURL=manifest-utils.d.ts.map

package/dist/shared/manifest-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-utils.d.ts","sourceRoot":"","sources":["../../src/shared/manifest-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EACV,YAAY,EAIb,MAAM,YAAY,CAAC;AA0FpB,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CA8B1D;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAG1E;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAI5D"}

package/dist/shared/manifest-utils.js

@@ -0,0 +1,110 @@
+/**
+ * docs 索引 (manifest) 工具
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { listSchemaFiles, readSchemaFile } from './schema-utils.js';
+import { listEntityFiles, parseEntityRefConfig } from './entity-utils.js';
+const MANIFEST_FILENAME = '.loom-manifest.json';
+const ENTITY_REF_KEY = 'x-entity-ref';
+function collectEntityRefs(schema, pointer = '') {
+    if (typeof schema !== 'object' || schema === null || Array.isArray(schema)) {
+        return [];
+    }
+    const node = schema;
+    const refs = [];
+    const parsed = parseEntityRefConfig(node[ENTITY_REF_KEY]);
+    if (parsed) {
+        refs.push({
+            entity: parsed.entity,
+            fields: parsed.pick,
+            jsonPointer: pointer || '/',
+        });
+    }
+    for (const [key, value] of Object.entries(node)) {
+        if (key === ENTITY_REF_KEY) {
+            continue;
+        }
+        const childPointer = `${pointer}/${escapeJsonPointer(key)}`;
+        refs.push(...collectEntityRefs(value, childPointer));
+    }
+    return refs;
+}
+function escapeJsonPointer(segment) {
+    return segment.replace(/~/g, '~0').replace(/\//g, '~1');
+}
+function buildEndpointRefs(doc, filename, endpoint) {
+    const refs = [];
+    const addScopeRefs = (scope, schema) => {
+        const found = collectEntityRefs(schema);
+        for (const ref of found) {
+            refs.push({
+                entity: ref.entity,
+                fields: ref.fields,
+                filename,
+                method: endpoint.method,
+                path: endpoint.path,
+                scope,
+                jsonPointer: ref.jsonPointer,
+            });
+        }
+    };
+    if (endpoint.request?.body) {
+        addScopeRefs('request.body', endpoint.request.body);
+    }
+    if (endpoint.request?.query) {
+        addScopeRefs('request.query', endpoint.request.query);
+    }
+    if (endpoint.request?.params) {
+        addScopeRefs('request.params', endpoint.request.params);
+    }
+    if (endpoint.request?.headers) {
+        addScopeRefs('request.headers', endpoint.request.headers);
+    }
+    for (const [statusCode, schema] of Object.entries(endpoint.response)) {
+        addScopeRefs(`response.${statusCode}`, schema);
+    }
+    return refs;
+}
+export function getManifestPath(outDir) {
+    return path.join(outDir, MANIFEST_FILENAME);
+}
+export function buildManifest(outDir) {
+    const files = listSchemaFiles(outDir);
+    const entities = listEntityFiles(outDir);
+    const endpointIndex = [];
+    const references = [];
+    for (const file of files) {
+        const doc = readSchemaFile(file.filepath);
+        for (const endpoint of doc.endpoints) {
+            endpointIndex.push({
+                filename: file.filename,
+                method: endpoint.method,
+                path: endpoint.path,
+                summary: endpoint.summary,
+            });
+            references.push(...buildEndpointRefs(doc, file.filename, endpoint));
+        }
+    }
+    return {
+        version: 1,
+        generatedAt: new Date().toISOString(),
+        endpointIndex,
+        entities: entities.map((entity) => ({
+            name: entity.title,
+            filename: entity.filename,
+            fieldCount: entity.fieldCount,
+        })),
+        references,
+    };
+}
+export function writeManifest(outDir, manifest) {
+    const filepath = getManifestPath(outDir);
+    fs.writeFileSync(filepath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf-8');
+}
+export function rebuildManifest(outDir) {
+    const manifest = buildManifest(outDir);
+    writeManifest(outDir, manifest);
+    return manifest;
+}
+//# sourceMappingURL=manifest-utils.js.map

package/dist/shared/manifest-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-utils.js","sourceRoot":"","sources":["../../src/shared/manifest-utils.ts"],"names":[],"mappings":"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"}

package/dist/shared/schema-entity-resolver.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 在文档展示阶段解析 x-entity-ref，返回可直接渲染的 schema 结构
+ */
+import type { EndpointDefinition, EntityDocument, SchemaDocument } from './types.js';
+export interface EntityResolveIssue {
+    scope: string;
+    jsonPointer: string;
+    message: string;
+}
+export declare function resolveEndpointEntityRefs(endpoint: EndpointDefinition, docsDir: string, issues: EntityResolveIssue[], entityCache: Map<string, EntityDocument>): EndpointDefinition;
+export declare function resolveDocumentEntityRefs(doc: SchemaDocument, docsDir: string): {
+    doc: SchemaDocument;
+    issues: EntityResolveIssue[];
+};
+//# sourceMappingURL=schema-entity-resolver.d.ts.map

package/dist/shared/schema-entity-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-entity-resolver.d.ts","sourceRoot":"","sources":["../../src/shared/schema-entity-resolver.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAgBrF,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAyHD,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,kBAAkB,EAAE,EAC5B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,GACvC,kBAAkB,CA6BpB;AAED,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE,MAAM,GACd;IAAE,GAAG,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,kBAAkB,EAAE,CAAA;CAAE,CAYvD"}

package/dist/shared/schema-entity-resolver.js

@@ -0,0 +1,134 @@
+/**
+ * 在文档展示阶段解析 x-entity-ref，返回可直接渲染的 schema 结构
+ */
+import { parseEntityRefConfig, readEntityFile, resolveEntityFilename, resolveEntitySchemaByRef, } from './entity-utils.js';
+const ENTITY_REF_KEY = 'x-entity-ref';
+const ENTITY_REF_ERROR_KEY = 'x-entity-ref-error';
+const OVERRIDE_KEYS = new Set([
+    'title',
+    'description',
+    'nullable',
+    'deprecated',
+    'readOnly',
+    'writeOnly',
+    'default',
+    'example',
+    'examples',
+]);
+function deepClone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function buildResolvedNode(sourceNode, resolvedSchema) {
+    const next = deepClone(resolvedSchema);
+    next[ENTITY_REF_KEY] = sourceNode[ENTITY_REF_KEY];
+    for (const [key, value] of Object.entries(sourceNode)) {
+        if (key === ENTITY_REF_KEY)
+            continue;
+        if (key.startsWith('x-') || OVERRIDE_KEYS.has(key)) {
+            next[key] = deepClone(value);
+        }
+    }
+    return next;
+}
+function createFallbackRefNode(node, message) {
+    const fallback = {
+        type: 'object',
+        description: `[Entity ref error] ${message}`,
+        [ENTITY_REF_KEY]: deepClone(node[ENTITY_REF_KEY]),
+        [ENTITY_REF_ERROR_KEY]: message,
+    };
+    return fallback;
+}
+function resolveObjectEntries(node, jsonPointer, context, skipEntityRefKey) {
+    const next = {};
+    for (const [key, child] of Object.entries(node)) {
+        if (skipEntityRefKey && key === ENTITY_REF_KEY) {
+            next[key] = deepClone(child);
+            continue;
+        }
+        const childPointer = `${jsonPointer}/${key.replace(/~/g, '~0').replace(/\//g, '~1')}`;
+        next[key] = resolveNode(child, childPointer, context);
+    }
+    return next;
+}
+function resolveNode(value, jsonPointer, context) {
+    if (Array.isArray(value)) {
+        return value.map((item, index) => resolveNode(item, `${jsonPointer}/${index}`, context));
+    }
+    if (typeof value !== 'object' || value === null) {
+        return value;
+    }
+    const node = value;
+    const parsedRef = parseEntityRefConfig(node[ENTITY_REF_KEY]);
+    if (node[ENTITY_REF_KEY] !== undefined) {
+        if (!parsedRef) {
+            const message = 'Invalid x-entity-ref format';
+            context.issues.push({ scope: context.scope, jsonPointer, message });
+            return createFallbackRefNode(node, message);
+        }
+        const filename = resolveEntityFilename(context.docsDir, parsedRef.entity);
+        if (!filename) {
+            const message = `Entity "${parsedRef.entity}" not found`;
+            context.issues.push({ scope: context.scope, jsonPointer, message });
+            return createFallbackRefNode(node, message);
+        }
+        let entity = context.entityCache.get(filename);
+        if (!entity) {
+            try {
+                entity = readEntityFile(context.docsDir, filename);
+            }
+            catch (err) {
+                const message = `Failed to read entity "${filename}": ${err instanceof Error ? err.message : String(err)}`;
+                context.issues.push({ scope: context.scope, jsonPointer, message });
+                return createFallbackRefNode(node, message);
+            }
+            context.entityCache.set(filename, entity);
+        }
+        try {
+            const resolved = resolveEntitySchemaByRef(entity, parsedRef);
+            const mergedNode = buildResolvedNode(node, resolved.schema);
+            // 只保留 ref 元数据，继续解析其子节点，避免在当前节点上重复展开自身 ref。
+            return resolveObjectEntries(mergedNode, jsonPointer, context, true);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            context.issues.push({ scope: context.scope, jsonPointer, message });
+            return createFallbackRefNode(node, message);
+        }
+    }
+    return resolveObjectEntries(node, jsonPointer, context, false);
+}
+function resolveScopeSchema(schema, scope, docsDir, issues, entityCache) {
+    return resolveNode(schema, '', { scope, docsDir, issues, entityCache });
+}
+export function resolveEndpointEntityRefs(endpoint, docsDir, issues, entityCache) {
+    const next = deepClone(endpoint);
+    if (next.request?.body) {
+        next.request.body = resolveScopeSchema(next.request.body, 'request.body', docsDir, issues, entityCache);
+    }
+    if (next.request?.query) {
+        next.request.query = resolveScopeSchema(next.request.query, 'request.query', docsDir, issues, entityCache);
+    }
+    if (next.request?.params) {
+        next.request.params = resolveScopeSchema(next.request.params, 'request.params', docsDir, issues, entityCache);
+    }
+    if (next.request?.headers) {
+        next.request.headers = resolveScopeSchema(next.request.headers, 'request.headers', docsDir, issues, entityCache);
+    }
+    const resolvedResponse = {};
+    for (const [statusCode, schema] of Object.entries(next.response)) {
+        resolvedResponse[statusCode] = resolveScopeSchema(schema, `response.${statusCode}`, docsDir, issues, entityCache);
+    }
+    next.response = resolvedResponse;
+    return next;
+}
+export function resolveDocumentEntityRefs(doc, docsDir) {
+    const issues = [];
+    const entityCache = new Map();
+    const resolvedDoc = {
+        ...doc,
+        endpoints: doc.endpoints.map((endpoint) => resolveEndpointEntityRefs(endpoint, docsDir, issues, entityCache)),
+    };
+    return { doc: resolvedDoc, issues };
+}
+//# sourceMappingURL=schema-entity-resolver.js.map

package/dist/shared/schema-entity-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-entity-resolver.js","sourceRoot":"","sources":["../../src/shared/schema-entity-resolver.ts"],"names":[],"mappings":"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"}

package/dist/shared/schema-utils.d.ts

@@ -0,0 +1,21 @@
+/**
+ * JSON Schema 解析/操作工具函数
+ */
+import type { SchemaDocument, SchemaFileMeta } from './types.js';
+/**
+ * 读取并解析一个 schema 文件
+ */
+export declare function readSchemaFile(filepath: string): SchemaDocument;
+/**
+ * 扫描目录下所有 .schema.json 文件，返回元信息列表
+ */
+export declare function listSchemaFiles(docsDir: string): SchemaFileMeta[];
+/**
+ * 将 SchemaDocument 写入文件
+ */
+export declare function writeSchemaFile(filepath: string, doc: SchemaDocument): void;
+/**
+ * 校验一个对象是否符合 SchemaDocument 的基本结构
+ */
+export declare function isValidSchemaDocument(obj: unknown): obj is SchemaDocument;
+//# sourceMappingURL=schema-utils.d.ts.map

package/dist/shared/schema-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-utils.d.ts","sourceRoot":"","sources":["../../src/shared/schema-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjE;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAG/D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAqBjE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI,CAM3E;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,cAAc,CAQzE"}