@bamboocss/node 1.56.6 → 1.57.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.
package/dist/index.d.cts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { n as markStaticCompilerActive, t as isStaticCompilerActive } from "./static-compiler-C1QNL5nu.cjs";
2
2
  import { ReportFormat } from "@bamboocss/reporter";
3
- import { AnalysisOptions, Artifact, ArtifactId, BambooHooks, Config, CssArtifactType, LoadConfigResult, ParserResultInterface, ResultItem, Runtime, SpecFile, WatchOptions, WatcherEventType } from "@bamboocss/types";
3
+ import { AnalysisOptions, Artifact, ArtifactId, BambooHooks, Config, CssArtifactType, DiffConfigResult, LoadConfigResult, ParserResultInterface, ResultItem, Runtime, SpecFile, WatchOptions, WatcherEventType } from "@bamboocss/types";
4
4
  import { DeadImport, ParserOptions, StyleEncoder, Stylesheet } from "@bamboocss/core";
5
5
  import { Generator, generatePackageExports } from "@bamboocss/generator";
6
6
 
@@ -74,10 +74,16 @@ interface FoldCall {
74
74
  /**
75
75
  * Code the evaluator does not run. `statement`: a helper's body uses one — `subject` is its
76
76
  * keyword, or `expression` for a statement run for its effect. `write`: the binding `subject` is
77
- * reassigned or written into after its declaration. `line` is 1-based; `column` too, in UTF-16.
77
+ * reassigned or written into after its declaration. `recursion`: a helper call the evaluator does not
78
+ * follow — `subject` is `loop` when the helper is already running with arguments it cannot tell
79
+ * apart, `depth` when calls nest deeper than it follows, `calls` when one call makes more of them
80
+ * than it follows, `module` when the helper is called again through another module while it runs;
81
+ * `helper` and the location are the recursive helper: for `loop` the first to run of those its
82
+ * cycle goes through, for `calls` the same of the cycle the innermost recurring call closes, for
83
+ * `depth` the one most of the calls running are of. `line` is 1-based; `column` too, in UTF-16.
78
84
  */
79
85
  interface FoldRefusal {
80
- kind: 'statement' | 'write';
86
+ kind: 'statement' | 'write' | 'recursion';
81
87
  subject: string;
82
88
  helper?: string;
83
89
  excerpt: string;
@@ -134,6 +140,17 @@ interface FoldAnalysis {
134
140
  dependencies: string[];
135
141
  }>;
136
142
  dependencies: string[];
143
+ /**
144
+ * Bamboo bindings a `<script setup>` compiled for a separate render function exposes to its
145
+ * template, as `__returned__` getters: where the getter reads the binding, what that becomes
146
+ * once nothing reads it, and every `$setup.<name>` the module reads.
147
+ */
148
+ vueExposures: Array<{
149
+ name: string;
150
+ span: FoldSpan;
151
+ replacement: string;
152
+ reads: FoldSpan[];
153
+ }>;
137
154
  errors: string[];
138
155
  }
139
156
  //#endregion
@@ -146,6 +163,8 @@ declare class DiffEngine {
146
163
  * Reload config from disk and refresh the context
147
164
  */
148
165
  reloadConfigAndRefreshContext(fn?: (conf: LoadConfigResult) => void): Promise<import("@bamboocss/types").DiffConfigResult>;
166
+ /** The file read again, and its tsconfig, for a context no integration prepared. */
167
+ private readAgain;
149
168
  /** @internal Exact tsconfig files behind the currently attached resolution options. */
150
169
  getResolutionConfigFiles: () => readonly string[];
151
170
  /**
@@ -389,8 +408,13 @@ declare class OutputEngine {
389
408
  * Subdirectories are left alone; they are swept as themselves when their own artifacts
390
409
  * are written.
391
410
  */
392
- prune: (artifacts: Array<Artifact | undefined>) => {
411
+ prune: (artifacts: Array<Artifact | undefined>, {
412
+ dry
413
+ }?: {
414
+ dry?: boolean;
415
+ }) => {
393
416
  removed: number;
417
+ stale: string[];
394
418
  };
395
419
  write: (output: Artifact | undefined) => Promise<PromiseSettledResult<void>[]> | undefined;
396
420
  /**
@@ -418,6 +442,23 @@ declare class OutputEngine {
418
442
  }
419
443
  //#endregion
420
444
  //#region src/create-context.d.ts
445
+ /**
446
+ * What the build warns about a style it could not read, in parts: what is lost, why, what to do
447
+ * about it, and where to read more. The build's warning is all four; the editor's diagnostic —
448
+ * `@bamboocss/eslint-plugin`'s `no-unresolved-styles` — the first and the third, the same words.
449
+ *
450
+ * A recipe does not degrade the way a `css()` call does, so it does not get the same explanation.
451
+ * Its classes are named from a hash of its config: a declaration the build cannot see changes that
452
+ * hash, the browser asks for a name no rule was emitted under, and *every* style is lost rather
453
+ * than the unresolved one. A `css()` call's loss is partial — what the build saw still applies — so
454
+ * its wording says which half is missing rather than implying the element is unstyled.
455
+ */
456
+ declare function explainUnresolvedStyle(entry: Pick<UnresolvedStyle, 'kind' | 'prop' | 'reason'>): {
457
+ what: string;
458
+ why: string;
459
+ fix: string;
460
+ see: string;
461
+ };
421
462
  declare class BambooContext extends Generator {
422
463
  runtime: Runtime;
423
464
  project: SourceProject;
@@ -479,7 +520,11 @@ declare class BambooContext extends Generator {
479
520
  }) => void;
480
521
  private getExplicitDependencies;
481
522
  initMessage: () => string;
482
- getFiles: () => string[];
523
+ /**
524
+ * The sources `include` names. `linked`, where given, is filled with where the glob began and
525
+ * the folders and files it reached through a link: where a source may really be somewhere else.
526
+ */
527
+ getFiles: (linked?: string[]) => string[];
483
528
  /**
484
529
  * Fail the build if any file's extraction threw.
485
530
  *
@@ -530,7 +575,7 @@ declare class BambooContext extends Generator {
530
575
  * "do not read it": the token and keyframe scans read whatever `include` covers, and a
531
576
  * project that excludes its `outdir` should not lose them.
532
577
  */
533
- private isGenerated;
578
+ isGenerated: (file: string) => boolean;
534
579
  /**
535
580
  * The text extraction reads for a file: its `parser:before` output, or its bytes when no hook
536
581
  * rewrites it. `undefined` when the file cannot be read at all.
@@ -588,7 +633,6 @@ declare class BambooContext extends Generator {
588
633
  */
589
634
  private hookedAuxiliaryFiles;
590
635
  private hookedAuxiliary;
591
- /** Load the required Rust extractor from the workspace or the published prebuild directory. */
592
636
  private loadNativeExtractor;
593
637
  private prepareNativeSource;
594
638
  /** Prepare a whole extraction pass in one coarse native invocation. */
@@ -618,13 +662,15 @@ declare class BambooContext extends Generator {
618
662
  */
619
663
  private get entrypointSpecifiers();
620
664
  /**
621
- * The files this pass has to read, out of everything `include` matched.
665
+ * The files this pass has to read, out of everything `include` matched: each real file once, and
666
+ * of those the ones that can reach an entrypoint.
622
667
  *
623
- * See `selectExtractable`. Kept behind a method so the reasons live in one place and a caller
668
+ * See `firstSpellingOfEachFile`, given `linked` — what the glob reported reaching through a link —
669
+ * and `selectExtractable`. Kept behind a method so the reasons live in one place and a caller
624
670
  * that wants the whole inventory — the watcher, the token scan — is unaffected: this narrows
625
671
  * what is *parsed*, not what the project holds.
626
672
  */
627
- extractableFiles: (files: readonly string[]) => string[];
673
+ extractableFiles: (files: readonly string[], linked?: readonly string[]) => string[];
628
674
  parseFiles: (styleEncoder?: StyleEncoder) => {
629
675
  filesWithCss: string[];
630
676
  files: string[];
@@ -637,6 +683,13 @@ declare class BambooContext extends Generator {
637
683
  }
638
684
  //#endregion
639
685
  //#region src/analyze.d.ts
686
+ /** The configured names no source uses, by what they are. */
687
+ interface UnusedNames {
688
+ tokens: string[];
689
+ recipes: string[];
690
+ patterns: string[];
691
+ keyframes: string[];
692
+ }
640
693
  /**
641
694
  * `analyze` is one CLI command, but this module is reachable from `@bamboocss/node`'s index,
642
695
  * so a static import made every consumer of that index — the CLI on any command, and the Vite
@@ -651,7 +704,26 @@ declare function analyze(ctx: BambooContext, options?: AnalysisOptions): Promise
651
704
  getTokenReport(format?: ReportFormat): {
652
705
  report: import("@bamboocss/reporter").TokenAnalysisReport;
653
706
  formatted: string;
654
- };
707
+ }; /** Every pattern the config defines, and how often each is called. */
708
+ getPatternReport: () => import("@bamboocss/reporter").PatternReportEntry[]; /** Every style property written, and how often. */
709
+ getUtilityReport: () => import("@bamboocss/reporter").UtilityReportEntry[]; /** Every keyframe the theme defines, and how often an animation names it. */
710
+ getKeyframeReport: () => import("@bamboocss/reporter").KeyframeReportEntry[];
711
+ /**
712
+ * The configured names no source uses, of the kinds asked for.
713
+ *
714
+ * Tokens and keyframes are what the build's own prune removes, run with every prune on
715
+ * whatever the config says, so a name here is one the stylesheet already ships without.
716
+ * Anything the prune keeps for a reader it cannot follow — a `token()` path built at runtime,
717
+ * a theme, a `keepTokens` pattern — is kept here too, and not listed: being told a token is
718
+ * unused when something still asks for it is worse than not being told at all. A recipe or a
719
+ * pattern is one no source calls and `staticCss` does not emit regardless.
720
+ *
721
+ * Read off a sheet of its own. The prune's settings are laid over the context's while it is
722
+ * built, and `unresolvedPath` is off for it: that one only decides how loudly the prune says
723
+ * what it could not read, and a project that does not prune tokens never hears it.
724
+ */
725
+ getUnused(kinds?: ReadonlyArray<keyof UnusedNames>): UnusedNames; /** The names as JSON, of the kinds `getUnused` was asked for. */
726
+ writeUnused(filePath: string, unused: Partial<UnusedNames>): Promise<void>;
655
727
  writeReport(filePath: string): Promise<void>;
656
728
  }>;
657
729
  //#endregion
@@ -672,6 +744,11 @@ interface BuilderSetupOptions {
672
744
  configPath?: string;
673
745
  cwd?: string;
674
746
  dev?: boolean;
747
+ /**
748
+ * A build that rebuilds on change — `vite build --watch` — and so takes the config fast path a
749
+ * dev server takes. Unlike `dev`, it leaves the context as a build's.
750
+ */
751
+ watch?: boolean;
675
752
  /** Record each atom's first call site during extraction, for `getAtomOrigins`. */
676
753
  atomOrigins?: boolean;
677
754
  /** A watcher-owned change journal. Without one, Builder performs its standalone filesystem scan. */
@@ -689,6 +766,8 @@ declare class Builder {
689
766
  private configDependencies;
690
767
  /** Last complete included inventory, including members which have since been deleted. */
691
768
  private sourceInventory;
769
+ /** Where the glob behind that inventory began, and what it reached through a link. */
770
+ private sourceLinks;
692
771
  /** Existing included owners selected by the last resolution-ledger invalidation pass. */
693
772
  private affectedFiles;
694
773
  /** Dependency-before-importer parse order for the selected owners. */
@@ -736,8 +815,20 @@ declare class Builder {
736
815
  getResolutionReadFiles: () => readonly string[];
737
816
  /** @internal The inventory reconciled by the most recent extraction pass. */
738
817
  getSourceFiles: () => readonly string[];
818
+ /** The folders each context's patterns are globbed from. @see getWatchDirectories */
819
+ private patternDirectories;
820
+ /** Those, and the folders the glob reached through a link, for one context and glob. @see getWatchDirectories */
821
+ private watchDirectories;
822
+ /**
823
+ * @internal The folders `include` and `dependencies` are globbed from, absolute — and each folder
824
+ * the last glob reached through a link — where a file appearing can change the stylesheet, and so
825
+ * what a watcher has to watch for it to be seen. A link a pattern's wildcard reaches,
826
+ * `node_modules/@acme/*` to a workspace package, leads somewhere no pattern names.
827
+ */
828
+ getWatchDirectories: () => readonly string[];
739
829
  /** The compiled `include`/`exclude` matcher of each context, since the compiler asks per module. */
740
830
  private sourceMatchers;
831
+ private sourceMatcherOf;
741
832
  /**
742
833
  * @internal Whether this path is one `include` covers and `exclude` does not.
743
834
  *
@@ -746,8 +837,40 @@ declare class Builder {
746
837
  * compiling it is wasted — and with the TypeScript 7 backend, far from free.
747
838
  */
748
839
  isPotentialSourceFile: (filePath: string) => boolean;
840
+ /** The folders each context's `include` is globbed from. @see isPotentialSourceFile */
841
+ private includeBaseCache;
842
+ private includeBases;
843
+ /** The linked paths of each glob, resolved once each. @see linkedPaths */
844
+ private linkedPathCache;
845
+ /**
846
+ * Where each folder and file the glob behind the inventory reached through a link — or the folder
847
+ * it began at, spelled through a link above it — really is, which is what a bundler resolving a
848
+ * module there names it by. Resolved once per glob, and only when asked, so a build that never
849
+ * asks pays nothing. Any difference in spelling counts, case too: a bundler names a module as the
850
+ * system does, and a path the inventory spells otherwise is no member of it.
851
+ */
852
+ private linkedPaths;
853
+ /**
854
+ * An absolute, `/`-spelled path as the inventory spells it — each way, where two links reach one
855
+ * folder and the inventory holds the files under both. None, where no link is in the way.
856
+ */
857
+ private sourcePathsOf;
858
+ /**
859
+ * @internal `filePath` as the source inventory spells it, where a bundler names it by where it
860
+ * really is: through each folder or file a link was read at. None, where no link is in the way.
861
+ */
862
+ toSourcePaths: (filePath: string) => readonly string[];
863
+ /** The inventory's sources by where each really is, for one inventory and glob. @see getRealSourceFiles */
864
+ private realSourceFiles;
865
+ /**
866
+ * @internal The sources the inventory reached through a link, by where each really is: the names
867
+ * a bundler gives them, and so what it reports compiling and editing.
868
+ */
869
+ getRealSourceFiles: () => readonly string[];
749
870
  /** @internal Whether creating or deleting this path can change a `dependencies` glob. */
750
871
  isPotentialConfigDependency: (filePath: string) => boolean;
872
+ /** The compiled `dependencies` matcher of each context, since a watcher asks per event. */
873
+ private dependencyMatchers;
751
874
  /** @internal Exact local package/tsconfig files which can change semantic resolution. */
752
875
  getResolutionConfigurationFiles: () => readonly string[];
753
876
  private readResolutionConfiguration;
@@ -755,6 +878,8 @@ declare class Builder {
755
878
  private snapshotResolutionConfigurations;
756
879
  private recordConfigDependencies;
757
880
  setup: (options?: BuilderSetupOptions) => Promise<BambooContext | undefined>;
881
+ /** Whether `dependencies` matches other files now than the context was built with. */
882
+ private dependencyMembersMoved;
758
883
  /** Every file whose content participates in the resolved config, for the dev fast path. */
759
884
  private configGraphFiles;
760
885
  private configGraphUnchanged;
@@ -842,6 +967,11 @@ interface SetupContextOptions {
842
967
  }
843
968
  //#endregion
844
969
  //#region src/codegen.d.ts
970
+ /**
971
+ * What a rebuild after a config edit writes: the artifacts the edit changed, or every artifact,
972
+ * as a run from cold would, when the edit changed what all of them are written from.
973
+ */
974
+ declare const artifactsToRebuild: (affected: DiffConfigResult) => ArtifactId[] | undefined;
845
975
  declare function codegen(ctx: BambooContext, ids?: ArtifactId[]): Promise<{
846
976
  box: string;
847
977
  msg: string;
@@ -877,11 +1007,98 @@ interface DebugOptions {
877
1007
  outdir: string;
878
1008
  dry: boolean;
879
1009
  onlyConfig?: boolean;
1010
+ /** Write the dump as one `<outdir>.zip`, which a bug report attaches, rather than as files. */
1011
+ zip?: boolean;
880
1012
  }
881
1013
  declare function debug(ctx: BambooContext, options: DebugOptions): Promise<void>;
882
1014
  //#endregion
1015
+ //#region src/doctor.d.ts
1016
+ /** What `bamboo doctor` found: the project as the build reads it, and what stops the build. */
1017
+ interface DoctorReport {
1018
+ cwd: string;
1019
+ /** The config file the project was loaded from. */
1020
+ config: string;
1021
+ /** The files `include` and `exclude` select. */
1022
+ sources: number;
1023
+ /** The generated `styled-system`, against what `bamboo codegen` would write now. */
1024
+ artifacts: {
1025
+ outdir: string;
1026
+ files: number; /** Absent, relative to `outdir`. */
1027
+ missing: string[]; /** Present and other than codegen would write them, relative to `outdir`. */
1028
+ stale: string[];
1029
+ /**
1030
+ * Generated once and no longer, which `bamboo codegen` removes, relative to `outdir`: a module
1031
+ * for a pattern or recipe the config dropped resolves, and answers with class names for rules
1032
+ * that are gone.
1033
+ */
1034
+ leftover: string[];
1035
+ };
1036
+ /** Files the build could not extract, relative to `cwd`, with why. */
1037
+ unextracted: Array<{
1038
+ file: string;
1039
+ message: string;
1040
+ }>;
1041
+ /** Calls to a pattern or recipe the entrypoint does not export, as `file: name`. */
1042
+ deadCalls: string[];
1043
+ conditions: number;
1044
+ /** Token count by category. */
1045
+ tokens: Record<string, number>;
1046
+ utilities: number;
1047
+ recipes: number;
1048
+ patterns: number;
1049
+ /** One line for each thing to fix; the command fails when there is any. */
1050
+ problems: string[];
1051
+ }
1052
+ /**
1053
+ * Check a project the way the build reads it, without writing anything.
1054
+ *
1055
+ * What it reports are the causes of a build that does not do what it is asked, in the order a
1056
+ * reader would look: a generated `styled-system` out of step with the config — the types and the
1057
+ * runtime say one thing and the stylesheet another — a source the extractor cannot read, whose
1058
+ * every style is absent, and a call naming a pattern or recipe that does not exist.
1059
+ */
1060
+ declare function doctor(ctx: BambooContext): Promise<DoctorReport>;
1061
+ /** The report as a reader takes it in: the project first, then what to fix. */
1062
+ declare function formatDoctorReport(report: DoctorReport): string;
1063
+ //#endregion
883
1064
  //#region src/generate.d.ts
884
- declare function generate(config: Config, configPath?: string): Promise<void>;
1065
+ interface GenerateOptions {
1066
+ /**
1067
+ * Refuse to build when `include` matches no files, instead of writing an empty stylesheet over
1068
+ * the one already there.
1069
+ *
1070
+ * For globs a person just typed, where matching nothing is a mistake — `bamboo ./codgen`,
1071
+ * `bamboo 'src/*.tsxx'` — and not a config's own, which a new project has nothing under yet.
1072
+ * Watching, where the files may be about to appear, only a directory is refused: a glob matches
1073
+ * files, so nothing appearing under it ever matches it.
1074
+ */
1075
+ requireFiles?: boolean;
1076
+ }
1077
+ declare function generate(config: Config, configPath?: string, options?: GenerateOptions): Promise<void>;
1078
+ //#endregion
1079
+ //#region src/node-runtime.d.ts
1080
+ /**
1081
+ * Whether a `cwd`-relative, `/`-spelled path is one the source glob returns for `include` and
1082
+ * `exclude`, told without walking: what decides a file's membership when it appears, and whether
1083
+ * the compiler reads a module.
1084
+ *
1085
+ * As the glob reads the two, which a matcher handed the same lists does not:
1086
+ *
1087
+ * - A negated `include` pattern — `!src/legacy/**` — is one more thing to pass over, where such a
1088
+ * matcher matches every path it does not name: `README.md`, and each module in `node_modules`,
1089
+ * was a source. So is a negated `exclude` pattern, which the glob reads without its `!`.
1090
+ * - A file passed over is matched with hidden paths in reach, so `**\/*.d.ts` drops one under
1091
+ * `.storybook` that `include` names, though a wildcard of `include`'s own does not enter it.
1092
+ * - A folder the walk meets below where it began, with a name an ignore matches outright —
1093
+ * `src/legacy`, `**\/legacy`, not `src/legacy/*` — is not read: nothing in it is a source. The
1094
+ * folder a walk begins at is never tested, so `src/legacy/**` beside `exclude: ['src/legacy']`
1095
+ * reads it, and a pattern without a glob — looked up in its own folder — is one wherever it is.
1096
+ * - A pattern is matched as its own walk spells what it meets: one written as an absolute path
1097
+ * against where a file is from the root, and every other against where it is from `cwd` — so
1098
+ * `**\/*.tsx` reaches nothing above `cwd`, and an absolute `exclude` beside a relative `include`
1099
+ * passes over nothing, as the glob passes over nothing for it.
1100
+ */
1101
+ declare const sourceMatcher: (include?: readonly string[], exclude?: string[], cwd?: string) => ((path: string) => boolean);
885
1102
  //#endregion
886
1103
  //#region src/git-ignore.d.ts
887
1104
  declare function setupGitIgnore(ctx: BambooContext): void;
@@ -925,4 +1142,4 @@ declare const hasUncompilableSources: (options: {
925
1142
  include?: readonly string[];
926
1143
  }) => boolean;
927
1144
  //#endregion
928
- export { BambooContext, Builder, type BuilderSetupOptions, type BuilderSourceChanges, type CssGenOptions, ParserResult, SourceProject, type UnresolvedStyle, analyze, buildInfo, codegen, cssgen, debug, findViteConfig, generate, generatePackageExports, hasUncompilableSources, isStaticCompilerActive, loadConfigAndCreateContext, markStaticCompilerActive, setLogStream, setupConfig, setupGitIgnore, spec, startProfiling };
1145
+ export { BambooContext, Builder, type BuilderSetupOptions, type BuilderSourceChanges, type CssGenOptions, type DoctorReport, type GenerateOptions, ParserResult, SourceProject, type UnresolvedStyle, analyze, artifactsToRebuild, buildInfo, codegen, cssgen, debug, doctor, explainUnresolvedStyle, findViteConfig, formatDoctorReport, generate, generatePackageExports, hasUncompilableSources, isStaticCompilerActive, loadConfigAndCreateContext, markStaticCompilerActive, setLogStream, setupConfig, setupGitIgnore, sourceMatcher, spec, startProfiling };