@typestyles/build-runner 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/LICENSE +204 -0
  2. package/README.md +199 -0
  3. package/dist/index.cjs +521 -8
  4. package/dist/index.d.cts +179 -1
  5. package/dist/index.d.ts +179 -1
  6. package/dist/index.js +498 -7
  7. package/package.json +5 -3
package/dist/index.d.cts CHANGED
@@ -1,3 +1,181 @@
1
+ /**
2
+ * Relative `.ts` paths documented for convention entries (first extension per base).
3
+ * Shared by bundler integrations and `@typestyles/next/build`.
4
+ */
5
+ declare const DEFAULT_EXTRACT_MODULE_CANDIDATES: readonly string[];
6
+ /**
7
+ * Resolve the default extraction module when the user did not pass explicit `modules`.
8
+ * Returns at most one path using `/` separators, relative to `root`.
9
+ */
10
+ declare function discoverDefaultExtractModules(root: string): string[];
11
+
12
+ declare const TYPESTYLES_IMPORT_RE: RegExp;
13
+ /**
14
+ * Extract namespace information from source code for invalidation and duplicate checks.
15
+ */
16
+ declare function extractNamespaces(code: string): {
17
+ keys: string[];
18
+ prefixes: string[];
19
+ };
20
+ interface DuplicateNamespaceReporter {
21
+ error(message: string): void;
22
+ }
23
+ /**
24
+ * Fail the build when the same style namespace appears in more than one module.
25
+ */
26
+ declare function reportDuplicateNamespaces(moduleNamespaces: Map<string, {
27
+ keys: string[];
28
+ prefixes: string[];
29
+ }>, id: string, prefixes: string[], reporter: DuplicateNamespaceReporter): void;
30
+
31
+ type TypestylesIntegrationMode = 'runtime' | 'build' | 'hybrid';
32
+ interface TypestylesExtractOptions {
33
+ /**
34
+ * Modules that register typestyles styles, relative to the project root.
35
+ * When omitted, uses {@link discoverDefaultExtractModules}.
36
+ */
37
+ modules?: string[];
38
+ /**
39
+ * Output CSS filename. Defaults to `typestyles.css`.
40
+ */
41
+ fileName?: string;
42
+ }
43
+ /**
44
+ * Resolve extraction modules from explicit config or convention entry discovery.
45
+ */
46
+ declare function resolveExtractModules(root: string, extract: TypestylesExtractOptions | undefined): string[];
47
+ /**
48
+ * Default to `build` when at least one extraction module resolves; otherwise `runtime`.
49
+ */
50
+ declare function resolveExtractMode(explicitMode: TypestylesIntegrationMode | undefined, resolvedModules: string[]): TypestylesIntegrationMode;
51
+
52
+ interface TypestylesExtractManifestV1 {
53
+ version: 1;
54
+ css: string;
55
+ }
56
+ interface TypestylesRouteCssEntry {
57
+ css: string;
58
+ }
59
+ interface TypestylesExtractManifestV2 {
60
+ version: 2;
61
+ /** Full-app CSS (union of all registered styles). */
62
+ css: string;
63
+ /** Per-route critical CSS paths relative to project root. */
64
+ routes: Record<string, TypestylesRouteCssEntry>;
65
+ }
66
+ type TypestylesExtractManifest = TypestylesExtractManifestV1 | TypestylesExtractManifestV2;
67
+ declare function isManifestV2(manifest: TypestylesExtractManifest): manifest is TypestylesExtractManifestV2;
68
+ /** Normalize App Router paths for manifest lookup (`/about`, no trailing slash). */
69
+ declare function normalizeRoutePath(routePath: string): string;
70
+
71
+ interface VerifyTypestylesBuildOptions {
72
+ /** Project root used to resolve `cssFile` and `manifestFile`. */
73
+ root: string;
74
+ /** Extracted CSS path relative to `root`. */
75
+ cssFile: string;
76
+ /**
77
+ * Manifest path relative to `root`. When omitted, manifest checks are skipped.
78
+ * Pass `false` explicitly to skip (same as omitting).
79
+ */
80
+ manifestFile?: string | false;
81
+ /** Expected manifest `css` field. Defaults to `cssFile`. */
82
+ manifestCssPath?: string;
83
+ /** Expected manifest version. Defaults to `1`. */
84
+ manifestVersion?: number;
85
+ /** Minimum CSS byte length. When omitted, only checks that the file is non-empty. */
86
+ minBytes?: number;
87
+ /** Substrings that must appear in the emitted CSS (app-specific sanity checks). */
88
+ requiredCssSubstrings?: readonly string[];
89
+ /**
90
+ * When the manifest is v2, require at least this many route entries.
91
+ * Ignored for v1 manifests.
92
+ */
93
+ minRouteEntries?: number;
94
+ }
95
+ interface VerifyTypestylesBuildResult {
96
+ cssPath: string;
97
+ cssBytes: number;
98
+ manifestPath?: string;
99
+ manifestVersion?: number;
100
+ }
101
+ declare class VerifyTypestylesBuildError extends Error {
102
+ readonly code: string;
103
+ constructor(message: string, code: string);
104
+ }
105
+ /**
106
+ * Verify that a zero-runtime TypeStyles build produced expected CSS (and optional manifest).
107
+ *
108
+ * Use after `runTypestylesBuild`, `buildTypestylesForNext`, or a bundler plugin build step in CI
109
+ * to catch silent extraction gaps — styles unreachable from the convention entry are dropped
110
+ * without a compile error.
111
+ */
112
+ declare function verifyTypestylesBuild(options: VerifyTypestylesBuildOptions): VerifyTypestylesBuildResult;
113
+
114
+ interface NextAppRoute {
115
+ /** App Router path, e.g. `/`, `/about`, `/blog/[slug]`. */
116
+ routePath: string;
117
+ /** Page file relative to project root with `/` separators. */
118
+ pageFile: string;
119
+ /** Layout files from root to route segment, relative to project root. */
120
+ layoutFiles: string[];
121
+ }
122
+ /**
123
+ * Convert `app/about/page.tsx` (relative to `appDir`) to `/about`.
124
+ * Route groups `(marketing)` are omitted from the URL.
125
+ */
126
+ declare function pageRelPathToRoutePath(pageRelPath: string): string;
127
+ /**
128
+ * Discover App Router pages under `appDir` (default `app`).
129
+ */
130
+ declare function discoverNextAppRoutes(root: string, appDir?: string): NextAppRoute[];
131
+
132
+ /**
133
+ * Trace local modules reachable from entry files and return those that import `typestyles`.
134
+ * Paths are relative to `root` with `/` separators.
135
+ */
136
+ declare function traceTypestylesModules(root: string, entryFiles: string[]): Promise<string[]>;
137
+ /** Load a traced module for style extraction. */
138
+ declare function createModuleLoader(root: string, modulePath: string): () => Promise<unknown>;
139
+
140
+ interface CollectRouteCssOptions {
141
+ root: string;
142
+ /** Convention entry modules (relative to root) included in every route bundle. */
143
+ sharedModules: string[];
144
+ /** App Router directory relative to root. Default `app`. */
145
+ appDir?: string;
146
+ /** Output directory for per-route CSS relative to root. */
147
+ routeCssOutDir?: string;
148
+ /**
149
+ * Collect CSS from traced modules.
150
+ * Injected by `@typestyles/next/build` so this package stays bundler-agnostic.
151
+ */
152
+ collectCss: (loaders: Array<() => unknown | Promise<unknown>>) => Promise<string>;
153
+ }
154
+ interface CollectRouteCssResult {
155
+ routes: Record<string, TypestylesRouteCssEntry>;
156
+ }
157
+ /**
158
+ * Emit per-route CSS files and return manifest route entries.
159
+ */
160
+ declare function collectAndWriteRouteCss(options: CollectRouteCssOptions): Promise<CollectRouteCssResult>;
161
+ declare function buildManifestV2(cssOutFile: string, routeEntries: Record<string, TypestylesRouteCssEntry>): TypestylesExtractManifestV2;
162
+
163
+ declare function readTypestylesManifest(root: string, manifestFile?: string): TypestylesExtractManifest;
164
+ declare function readCssFile(root: string, cssRelPath: string): string;
165
+ interface GetRouteCssOptions {
166
+ /** Project root used to resolve manifest and CSS paths. */
167
+ root: string;
168
+ /** Manifest path relative to `root`. Defaults to `app/typestyles.manifest.json`. */
169
+ manifestFile?: string;
170
+ }
171
+ /**
172
+ * Read pre-extracted CSS for an App Router route from the build manifest.
173
+ *
174
+ * When the manifest is v2 and includes a route entry, returns that route's CSS.
175
+ * Otherwise falls back to the full-app stylesheet path in the manifest.
176
+ */
177
+ declare function getRouteCss(routePath: string, options: GetRouteCssOptions): string;
178
+
1
179
  interface RunTypestylesBuildOptions {
2
180
  /**
3
181
  * Project root used to resolve extraction entry modules.
@@ -16,4 +194,4 @@ interface RunTypestylesBuildOptions {
16
194
  */
17
195
  declare function runTypestylesBuild({ root, modules, }: RunTypestylesBuildOptions): Promise<string>;
18
196
 
19
- export { type RunTypestylesBuildOptions, runTypestylesBuild };
197
+ export { type CollectRouteCssOptions, type CollectRouteCssResult, DEFAULT_EXTRACT_MODULE_CANDIDATES, type DuplicateNamespaceReporter, type GetRouteCssOptions, type NextAppRoute, type RunTypestylesBuildOptions, TYPESTYLES_IMPORT_RE, type TypestylesExtractManifest, type TypestylesExtractManifestV1, type TypestylesExtractManifestV2, type TypestylesExtractOptions, type TypestylesIntegrationMode, type TypestylesRouteCssEntry, VerifyTypestylesBuildError, type VerifyTypestylesBuildOptions, type VerifyTypestylesBuildResult, buildManifestV2, collectAndWriteRouteCss, createModuleLoader, discoverDefaultExtractModules, discoverNextAppRoutes, extractNamespaces, getRouteCss, isManifestV2, normalizeRoutePath, pageRelPathToRoutePath, readCssFile, readTypestylesManifest, reportDuplicateNamespaces, resolveExtractMode, resolveExtractModules, runTypestylesBuild, traceTypestylesModules, verifyTypestylesBuild };
package/dist/index.d.ts CHANGED
@@ -1,3 +1,181 @@
1
+ /**
2
+ * Relative `.ts` paths documented for convention entries (first extension per base).
3
+ * Shared by bundler integrations and `@typestyles/next/build`.
4
+ */
5
+ declare const DEFAULT_EXTRACT_MODULE_CANDIDATES: readonly string[];
6
+ /**
7
+ * Resolve the default extraction module when the user did not pass explicit `modules`.
8
+ * Returns at most one path using `/` separators, relative to `root`.
9
+ */
10
+ declare function discoverDefaultExtractModules(root: string): string[];
11
+
12
+ declare const TYPESTYLES_IMPORT_RE: RegExp;
13
+ /**
14
+ * Extract namespace information from source code for invalidation and duplicate checks.
15
+ */
16
+ declare function extractNamespaces(code: string): {
17
+ keys: string[];
18
+ prefixes: string[];
19
+ };
20
+ interface DuplicateNamespaceReporter {
21
+ error(message: string): void;
22
+ }
23
+ /**
24
+ * Fail the build when the same style namespace appears in more than one module.
25
+ */
26
+ declare function reportDuplicateNamespaces(moduleNamespaces: Map<string, {
27
+ keys: string[];
28
+ prefixes: string[];
29
+ }>, id: string, prefixes: string[], reporter: DuplicateNamespaceReporter): void;
30
+
31
+ type TypestylesIntegrationMode = 'runtime' | 'build' | 'hybrid';
32
+ interface TypestylesExtractOptions {
33
+ /**
34
+ * Modules that register typestyles styles, relative to the project root.
35
+ * When omitted, uses {@link discoverDefaultExtractModules}.
36
+ */
37
+ modules?: string[];
38
+ /**
39
+ * Output CSS filename. Defaults to `typestyles.css`.
40
+ */
41
+ fileName?: string;
42
+ }
43
+ /**
44
+ * Resolve extraction modules from explicit config or convention entry discovery.
45
+ */
46
+ declare function resolveExtractModules(root: string, extract: TypestylesExtractOptions | undefined): string[];
47
+ /**
48
+ * Default to `build` when at least one extraction module resolves; otherwise `runtime`.
49
+ */
50
+ declare function resolveExtractMode(explicitMode: TypestylesIntegrationMode | undefined, resolvedModules: string[]): TypestylesIntegrationMode;
51
+
52
+ interface TypestylesExtractManifestV1 {
53
+ version: 1;
54
+ css: string;
55
+ }
56
+ interface TypestylesRouteCssEntry {
57
+ css: string;
58
+ }
59
+ interface TypestylesExtractManifestV2 {
60
+ version: 2;
61
+ /** Full-app CSS (union of all registered styles). */
62
+ css: string;
63
+ /** Per-route critical CSS paths relative to project root. */
64
+ routes: Record<string, TypestylesRouteCssEntry>;
65
+ }
66
+ type TypestylesExtractManifest = TypestylesExtractManifestV1 | TypestylesExtractManifestV2;
67
+ declare function isManifestV2(manifest: TypestylesExtractManifest): manifest is TypestylesExtractManifestV2;
68
+ /** Normalize App Router paths for manifest lookup (`/about`, no trailing slash). */
69
+ declare function normalizeRoutePath(routePath: string): string;
70
+
71
+ interface VerifyTypestylesBuildOptions {
72
+ /** Project root used to resolve `cssFile` and `manifestFile`. */
73
+ root: string;
74
+ /** Extracted CSS path relative to `root`. */
75
+ cssFile: string;
76
+ /**
77
+ * Manifest path relative to `root`. When omitted, manifest checks are skipped.
78
+ * Pass `false` explicitly to skip (same as omitting).
79
+ */
80
+ manifestFile?: string | false;
81
+ /** Expected manifest `css` field. Defaults to `cssFile`. */
82
+ manifestCssPath?: string;
83
+ /** Expected manifest version. Defaults to `1`. */
84
+ manifestVersion?: number;
85
+ /** Minimum CSS byte length. When omitted, only checks that the file is non-empty. */
86
+ minBytes?: number;
87
+ /** Substrings that must appear in the emitted CSS (app-specific sanity checks). */
88
+ requiredCssSubstrings?: readonly string[];
89
+ /**
90
+ * When the manifest is v2, require at least this many route entries.
91
+ * Ignored for v1 manifests.
92
+ */
93
+ minRouteEntries?: number;
94
+ }
95
+ interface VerifyTypestylesBuildResult {
96
+ cssPath: string;
97
+ cssBytes: number;
98
+ manifestPath?: string;
99
+ manifestVersion?: number;
100
+ }
101
+ declare class VerifyTypestylesBuildError extends Error {
102
+ readonly code: string;
103
+ constructor(message: string, code: string);
104
+ }
105
+ /**
106
+ * Verify that a zero-runtime TypeStyles build produced expected CSS (and optional manifest).
107
+ *
108
+ * Use after `runTypestylesBuild`, `buildTypestylesForNext`, or a bundler plugin build step in CI
109
+ * to catch silent extraction gaps — styles unreachable from the convention entry are dropped
110
+ * without a compile error.
111
+ */
112
+ declare function verifyTypestylesBuild(options: VerifyTypestylesBuildOptions): VerifyTypestylesBuildResult;
113
+
114
+ interface NextAppRoute {
115
+ /** App Router path, e.g. `/`, `/about`, `/blog/[slug]`. */
116
+ routePath: string;
117
+ /** Page file relative to project root with `/` separators. */
118
+ pageFile: string;
119
+ /** Layout files from root to route segment, relative to project root. */
120
+ layoutFiles: string[];
121
+ }
122
+ /**
123
+ * Convert `app/about/page.tsx` (relative to `appDir`) to `/about`.
124
+ * Route groups `(marketing)` are omitted from the URL.
125
+ */
126
+ declare function pageRelPathToRoutePath(pageRelPath: string): string;
127
+ /**
128
+ * Discover App Router pages under `appDir` (default `app`).
129
+ */
130
+ declare function discoverNextAppRoutes(root: string, appDir?: string): NextAppRoute[];
131
+
132
+ /**
133
+ * Trace local modules reachable from entry files and return those that import `typestyles`.
134
+ * Paths are relative to `root` with `/` separators.
135
+ */
136
+ declare function traceTypestylesModules(root: string, entryFiles: string[]): Promise<string[]>;
137
+ /** Load a traced module for style extraction. */
138
+ declare function createModuleLoader(root: string, modulePath: string): () => Promise<unknown>;
139
+
140
+ interface CollectRouteCssOptions {
141
+ root: string;
142
+ /** Convention entry modules (relative to root) included in every route bundle. */
143
+ sharedModules: string[];
144
+ /** App Router directory relative to root. Default `app`. */
145
+ appDir?: string;
146
+ /** Output directory for per-route CSS relative to root. */
147
+ routeCssOutDir?: string;
148
+ /**
149
+ * Collect CSS from traced modules.
150
+ * Injected by `@typestyles/next/build` so this package stays bundler-agnostic.
151
+ */
152
+ collectCss: (loaders: Array<() => unknown | Promise<unknown>>) => Promise<string>;
153
+ }
154
+ interface CollectRouteCssResult {
155
+ routes: Record<string, TypestylesRouteCssEntry>;
156
+ }
157
+ /**
158
+ * Emit per-route CSS files and return manifest route entries.
159
+ */
160
+ declare function collectAndWriteRouteCss(options: CollectRouteCssOptions): Promise<CollectRouteCssResult>;
161
+ declare function buildManifestV2(cssOutFile: string, routeEntries: Record<string, TypestylesRouteCssEntry>): TypestylesExtractManifestV2;
162
+
163
+ declare function readTypestylesManifest(root: string, manifestFile?: string): TypestylesExtractManifest;
164
+ declare function readCssFile(root: string, cssRelPath: string): string;
165
+ interface GetRouteCssOptions {
166
+ /** Project root used to resolve manifest and CSS paths. */
167
+ root: string;
168
+ /** Manifest path relative to `root`. Defaults to `app/typestyles.manifest.json`. */
169
+ manifestFile?: string;
170
+ }
171
+ /**
172
+ * Read pre-extracted CSS for an App Router route from the build manifest.
173
+ *
174
+ * When the manifest is v2 and includes a route entry, returns that route's CSS.
175
+ * Otherwise falls back to the full-app stylesheet path in the manifest.
176
+ */
177
+ declare function getRouteCss(routePath: string, options: GetRouteCssOptions): string;
178
+
1
179
  interface RunTypestylesBuildOptions {
2
180
  /**
3
181
  * Project root used to resolve extraction entry modules.
@@ -16,4 +194,4 @@ interface RunTypestylesBuildOptions {
16
194
  */
17
195
  declare function runTypestylesBuild({ root, modules, }: RunTypestylesBuildOptions): Promise<string>;
18
196
 
19
- export { type RunTypestylesBuildOptions, runTypestylesBuild };
197
+ export { type CollectRouteCssOptions, type CollectRouteCssResult, DEFAULT_EXTRACT_MODULE_CANDIDATES, type DuplicateNamespaceReporter, type GetRouteCssOptions, type NextAppRoute, type RunTypestylesBuildOptions, TYPESTYLES_IMPORT_RE, type TypestylesExtractManifest, type TypestylesExtractManifestV1, type TypestylesExtractManifestV2, type TypestylesExtractOptions, type TypestylesIntegrationMode, type TypestylesRouteCssEntry, VerifyTypestylesBuildError, type VerifyTypestylesBuildOptions, type VerifyTypestylesBuildResult, buildManifestV2, collectAndWriteRouteCss, createModuleLoader, discoverDefaultExtractModules, discoverNextAppRoutes, extractNamespaces, getRouteCss, isManifestV2, normalizeRoutePath, pageRelPathToRoutePath, readCssFile, readTypestylesManifest, reportDuplicateNamespaces, resolveExtractMode, resolveExtractModules, runTypestylesBuild, traceTypestylesModules, verifyTypestylesBuild };