@clarify-labs/cli 0.11.3 → 0.11.5

package/output/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_engine = require("./engine-6WmOk7xk.cjs");
+const require_engine = require("./engine-VgAP_Ms6.cjs");
 exports.ClarifyEngine = require_engine.ClarifyEngine;
 exports.createClarifyEngine = require_engine.createClarifyEngine;
 exports.createViteAdapter = require_engine.createViteAdapter;

package/output/index.js

@@ -1,2 +1,2 @@
-import { l as createViteAdapter, n as createClarifyEngine, t as ClarifyEngine, u as defineConfig } from "./engine-CrYRJRZT.js";
+import { d as defineConfig, n as createClarifyEngine, t as ClarifyEngine, u as createViteAdapter } from "./engine-DuiJVdO8.js";
 export { ClarifyEngine, createClarifyEngine, createViteAdapter, defineConfig };

package/output/parsers/content/content.d.ts

@@ -6,7 +6,7 @@ export type ProcessedMdxContent = {
 export type ContentTransform = (input: ClarifyContentTransformInput) => Promise<ClarifyContentTransformInput> | ClarifyContentTransformInput;
 export type ContentProcessor = {
     processMdx(source: string, filePath?: string): Promise<ProcessedMdxContent>;
-    processText(source: string, kind: Exclude<ClarifyContentKind, 'mdx'>, filePath?: string): Promise<string>;
+    processText(source: string, kind: Exclude<ClarifyContentKind, 'markdown+jsx'>, filePath?: string): Promise<string>;
 };
 export declare function createContentProcessor(transform?: ContentTransform): ContentProcessor;
 /**

package/output/parsers/markdown/markdown.d.ts

@@ -0,0 +1,34 @@
+import { ContentDiagnostic } from '../../types.js';
+type CompileMarkdownContentOptions = {
+    filePath?: string;
+    projectRoot?: string;
+};
+/**
+ * Validate Markdown content for diagnostics WITHOUT running the build-time
+ * rehype pipeline (Shiki highlighting, slug injection, code-block parsing).
+ *
+ * `rehypePlugins` includes `rehypeShiki`, which loads grammar/WASM assets and
+ * is expensive. The real highlighting happens at Vite build time via the
+ * `@mdx-js/rollup` plugin (see `createContentCompilerPlugin` in
+ * `core/adapters.ts`), which runs the full remark + rehype pipeline.
+ * Re-running it here, during route discovery (Phase 3), would compile every
+ * `.md` file twice and invoke Shiki once per file per `engine.refresh()` -
+ * see ARCHITECTURE.md §2.2 which states "不应在 core 中执行代码高亮".
+ *
+ * `format: 'md'` mirrors the adapter's markdown compiler semantics (no JSX,
+ * raw HTML allowed via `remarkRehypeOptions`), so the same class of syntax
+ * errors that would break the Vite build is surfaced as a diagnostic here
+ * instead of leaking out as an opaque
+ * `Failed to fetch dynamically imported module` at runtime.
+ *
+ * MDX files are handled by `compileMdxContent` in `mdx.ts`. Keep the two
+ * compilers separate so each format can evolve its own diagnostic rules
+ * without contaminating the other.
+ */
+export declare function compileMarkdownContent(content: string, options?: CompileMarkdownContentOptions): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    diagnostic: ContentDiagnostic;
+}>;
+export {};

package/output/parsers/markdown/mdx.d.ts

@@ -11,32 +11,40 @@ export declare function rehypeParseCodeBlocks(): (tree: HastNode) => void;
 export declare const remarkPlugins: unknown[];
 export declare const rehypePlugins: NonNullable<CompileOptions['rehypePlugins']>;
 type ContentCompileDiagnosticOptions = {
-    format: 'markdown' | 'mdx';
+    format: 'markdown' | 'markdown+jsx';
     phase: 'syntax' | 'compilation';
     error: unknown;
     filePath?: string;
     projectRoot?: string;
 };
 export declare function createContentCompileDiagnostic(options: ContentCompileDiagnosticOptions): ContentDiagnostic;
+type CompileContentOptions = {
+    filePath?: string;
+    projectRoot?: string;
+};
 /**
  * Validate MDX content for diagnostics WITHOUT running the build-time rehype
  * pipeline (Shiki highlighting, slug injection, code-block parsing).
  *
  * `rehypePlugins` includes `rehypeShiki`, which loads grammar/WASM assets and
  * is expensive. The real highlighting happens at Vite build time via the
- * `@mdx-js/rollup` plugins (see `createMarkdownPlugin` and `createMdxPlugin`
- * in `core/adapters.ts`), which
- * runs the full remark + rehype pipeline. Re-running it here, during route
- * discovery (Phase 3), would compile every `.mdx` file twice and invoke Shiki
- * once per file per `engine.refresh()` — see ARCHITECTURE.md §2.2 which states
- * "不应在 core 中执行代码高亮".
+ * `@mdx-js/rollup` plugin (see `createContentCompilerPlugin` in
+ * `core/adapters.ts`), which runs the full remark + rehype pipeline.
+ * Re-running it here, during route discovery (Phase 3), would compile every
+ * `.mdx` file twice and invoke Shiki once per file per `engine.refresh()` -
+ * see ARCHITECTURE.md §2.2 which states "不应在 core 中执行代码高亮".
  *
  * The remark pipeline still runs (shared with the Vite plugin via
- * `remarkPlugins`), so MDX/JSX syntax errors — the only class of error this
- * diagnostic is meant to surface ahead of the Vite build — are caught. The
+ * `remarkPlugins`), so MDX/JSX syntax errors - the only class of error this
+ * diagnostic is meant to surface ahead of the Vite build - are caught. The
  * output is discarded; only the thrown error is used.
+ *
+ * `.md` files are handled by `compileMarkdownContent` in `markdown.ts`, which
+ * mirrors the adapter's markdown compiler semantics (`format: 'md'`, raw HTML
+ * allowed). Keep the two compilers separate so each format can evolve its own
+ * diagnostic rules without contaminating the other.
  */
-export declare function compileMdxContent(content: string, filePath?: string, projectRoot?: string): Promise<{
+export declare function compileMdxContent(content: string, options?: CompileContentOptions): Promise<{
     ok: true;
 } | {
     ok: false;

package/output/parsers/routes/routes.d.ts

@@ -1,4 +1,4 @@
-import { ContentRoute, ClarifyNavigationNode, ClarifyPagesConfig, ClarifyPagesGroup, ClarifyPagesItem, ClarifyRouteIntent, ClarifyTabsConfig, LocalizedNavigation, LocalizedTabbedNavigation, ResolvedClarifyLocalesConfig, TabbedNavigation } from '../../types.js';
+import { ContentRoute, ClarifyNavigationNode, ClarifyPagesConfig, ClarifyPagesGroup, ClarifyPagesItem, ClarifyRouteIntent, ClarifyTabsConfig, LocalizedNavigation, LocalizedTabbedNavigation, MarkdownContentRoute, ResolvedClarifyLocalesConfig, TabbedNavigation } from '../../types.js';
 import { ContentProcessor } from '../content/content.js';
 export type FindContentRoutesOptions = {
     contentProcessor?: ContentProcessor;
@@ -8,11 +8,10 @@ export declare function normalizePath(path: string): string;
 export declare function basePathFromRef(ref: string): string;
 export declare function openAPIPagePathFromRef(ref: string, tagFilter?: string[], explicitPath?: string): string;
 export declare function routePathFromRef(ref: string, explicitPath?: string): string;
-export declare function virtualModuleIdFromRef(ref: string): string;
 export declare function localizedRoutePath(basePath: string, locale: string, _i18n: ResolvedClarifyLocalesConfig): string;
-export declare function findContentRoutes(dir: string, base?: string, options?: FindContentRoutesOptions): Promise<ContentRoute[]>;
-export declare function withAlternates(route: ContentRoute, routes: ContentRoute[], locales: ResolvedClarifyLocalesConfig): ContentRoute;
-export declare function findLocalizedContentRoutes(contentRoot: string, locales?: ResolvedClarifyLocalesConfig, options?: FindContentRoutesOptions): Promise<ContentRoute[]>;
+export declare function findContentRoutes(dir: string, base?: string, options?: FindContentRoutesOptions): Promise<MarkdownContentRoute[]>;
+export declare function withAlternates<T extends ContentRoute>(route: T, routes: ContentRoute[], locales: ResolvedClarifyLocalesConfig): T;
+export declare function findLocalizedContentRoutes(contentRoot: string, locales?: ResolvedClarifyLocalesConfig, options?: FindContentRoutesOptions): Promise<MarkdownContentRoute[]>;
 export declare function buildNavigation(routes: ContentRoute[]): ClarifyNavigationNode[];
 export declare function routeIntentFromPagesItem(item: ClarifyPagesItem): ClarifyRouteIntent;
 export declare function applyConfiguredPageRoutePaths(routes: ContentRoute[], tabs?: ClarifyTabsConfig, locales?: ResolvedClarifyLocalesConfig): ContentRoute[];

package/output/parsers/routes/routes.test-utils.d.ts

@@ -1,5 +1,5 @@
-import { ContentRoute, ResolvedClarifyLocalesConfig } from '../../types.js';
-type ContentRouteFixture = Partial<Omit<ContentRoute, 'kind' | 'meta' | 'module' | 'source'>> & {
+import { ContentRoute, OpenAPIContentRoute, ResolvedClarifyLocalesConfig } from '../../types.js';
+type ContentRouteFixture = Partial<Omit<ContentRoute, 'kind' | 'meta' | 'module' | 'source' | 'openapi'>> & {
     kind?: ContentRoute['kind'];
     title?: string;
     description?: string;
@@ -9,7 +9,9 @@ type ContentRouteFixture = Partial<Omit<ContentRoute, 'kind' | 'meta' | 'module'
     frontmatter?: ContentRoute['source']['frontmatter'];
     content?: string;
     sourceEditUrl?: string;
-    virtualModuleId?: string;
+    pageVirtualModuleId?: string;
+    contentVirtualModuleId?: string;
+    openapi?: OpenAPIContentRoute['openapi'];
     meta?: Partial<ContentRoute['meta']>;
     module?: Partial<ContentRoute['module']>;
     source?: Partial<ContentRoute['source']>;

package/output/plugins/openapi/parser.d.ts

@@ -1,5 +1,5 @@
 import { ContentProcessor } from '../../parsers/content/content.js';
-import { ContentDiagnostic, ContentRoute, ContentSection, OpenAPISpec } from '../../types.js';
+import { ContentDiagnostic, ContentSection, OpenAPIContentRoute, OpenAPISpec } from '../../types.js';
 export type OpenAPIParseResult = {
     ok: true;
     spec: OpenAPISpec;
@@ -7,7 +7,7 @@ export type OpenAPIParseResult = {
     ok: false;
     diagnostic: ContentDiagnostic;
 };
-export declare function findOpenAPIRoutes(dir: string, base?: string): ContentRoute[];
+export declare function findOpenAPIRoutes(dir: string, base?: string): OpenAPIContentRoute[];
 export declare function normalizeOpenAPISpecSectionIds(spec: OpenAPISpec): OpenAPISpec;
 /** Filter an OpenAPI spec to only include paths that have at least one operation matching the given tags. */
 export declare function filterSpecByTags(spec: OpenAPISpec, tags: string[]): OpenAPISpec;

package/output/plugins/openapi/routes.d.ts

@@ -0,0 +1,3 @@
+import { ContentRoute, OpenAPIContentRoute, ResolvedClarifyLocalesConfig, ResolvedProjectConfig } from '../../types.js';
+export declare function discoverOpenAPIRoutes(contentRoot: string, locales?: ResolvedClarifyLocalesConfig): OpenAPIContentRoute[];
+export declare function expandConfiguredOpenAPIRoutes(routes: ContentRoute[], config: ResolvedProjectConfig): ContentRoute[];

package/output/plugins/openapi/state.d.ts

@@ -0,0 +1,7 @@
+import { VirtualModules } from '../../core/runtime/virtual-modules.js';
+import { ClarifyHookContext, ContentRoute } from '../../types.js';
+export declare class OpenAPIPluginState {
+    private readonly specModules;
+    enrichRoutes(routes: ContentRoute[], ctx: ClarifyHookContext): Promise<ContentRoute[]>;
+    contributeModules(modules: VirtualModules, routes: ContentRoute[]): VirtualModules;
+}

package/output/types.d.ts

@@ -275,9 +275,16 @@ export type ContentRouteMeta = {
     keywords?: string[];
     sections?: ContentSection[];
 };
-export type ContentRouteModule = {
-    virtualModuleId: string;
+export type PageRouteModule = {
+    pageVirtualModuleId: string;
 };
+export type MarkdownRouteModule = PageRouteModule & {
+    contentVirtualModuleId: string;
+};
+export type OpenAPIRouteModule = PageRouteModule & {
+    contentVirtualModuleId?: never;
+};
+export type ContentRouteModule = MarkdownRouteModule | OpenAPIRouteModule;
 export type OpenAPIContentRouteState = {
     /** Operation tag filter applied to this route. Undefined means all operations. */
     tagFilter?: string[];
@@ -298,7 +305,7 @@ export type ContentRouteSource = {
     /** Public edit URL for this route's source file. */
     sourceEditUrl?: string;
 };
-export type ContentRoute = {
+type ContentRouteBase = {
     path: string;
     basePath?: string;
     locale?: string;
@@ -306,15 +313,22 @@ export type ContentRoute = {
     /** Indicates this route is a bare alias for the default locale (e.g., /path instead of /locale/path). Should not be indexed. */
     isBareAlias?: boolean;
     alternates?: Record<string, string>;
-    kind: string;
     meta: ContentRouteMeta;
-    module: ContentRouteModule;
     source: ContentRouteSource;
-    /** OpenAPI-specific route state. Present only for OpenAPI routes. */
-    openapi?: OpenAPIContentRouteState;
     diagnostic?: ContentDiagnostic;
     artifacts?: ContentRouteArtifacts;
 };
+export type MarkdownContentRoute = ContentRouteBase & {
+    kind: 'markdown' | 'markdown+jsx';
+    module: MarkdownRouteModule;
+    openapi?: never;
+};
+export type OpenAPIContentRoute = ContentRouteBase & {
+    kind: 'openapi';
+    module: OpenAPIRouteModule;
+    openapi?: OpenAPIContentRouteState;
+};
+export type ContentRoute = MarkdownContentRoute | OpenAPIContentRoute;
 export type ClarifyNavigationTab = {
     type: 'tab';
     path: string;
@@ -385,7 +399,7 @@ export type ClarifyRouteDiscoveryInput = {
     locale?: string;
     routes: ContentRoute[];
 };
-export type ClarifyContentKind = 'mdx' | 'openapi';
+export type ClarifyContentKind = 'markdown' | 'markdown+jsx' | 'openapi';
 export type ClarifyContentTransformInput = {
     kind: ClarifyContentKind;
     source: string;
@@ -449,8 +463,9 @@ export type ClarifyBuildHooks = {
     'build:shouldRun'?: ClarifyInterceptHook;
     'ssg:shouldRun'?: ClarifyInterceptHook;
 };
+export type ClarifyDevServerPostHook = () => void;
 export type ClarifyDevHooks = {
-    'dev:configureServer'?: (server: ViteDevServer, ctx: ClarifyHookContext) => MaybePromise<void>;
+    'dev:configureServer'?: (server: ViteDevServer, ctx: ClarifyHookContext) => MaybePromise<void | ClarifyDevServerPostHook>;
 };
 export type ClarifyHooks = ClarifyLifecycleHooks & ClarifyPipelineHooks & ClarifyBuildHooks & ClarifyDevHooks;
 export type ClarifyPlugin = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clarify-labs/cli",
-  "version": "0.11.3",
+  "version": "0.11.5",
   "license": "AGPL-3.0-only",
   "type": "module",
   "repository": {
@@ -39,8 +39,8 @@
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^12.1.0",
-    "@clarify-labs/renderer": "0.11.3",
-    "@clarify-labs/templates": "0.11.3",
+    "@clarify-labs/renderer": "0.11.5",
+    "@clarify-labs/templates": "0.11.5",
     "@mdx-js/mdx": "^3.1.1",
     "@mdx-js/rollup": "^3.1.1",
     "@modelcontextprotocol/sdk": "^1.29.0",