@bamboocss/node 1.56.7 → 1.57.1

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;
@@ -157,6 +163,8 @@ declare class DiffEngine {
157
163
  * Reload config from disk and refresh the context
158
164
  */
159
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;
160
168
  /** @internal Exact tsconfig files behind the currently attached resolution options. */
161
169
  getResolutionConfigFiles: () => readonly string[];
162
170
  /**
@@ -400,8 +408,13 @@ declare class OutputEngine {
400
408
  * Subdirectories are left alone; they are swept as themselves when their own artifacts
401
409
  * are written.
402
410
  */
403
- prune: (artifacts: Array<Artifact | undefined>) => {
411
+ prune: (artifacts: Array<Artifact | undefined>, {
412
+ dry
413
+ }?: {
414
+ dry?: boolean;
415
+ }) => {
404
416
  removed: number;
417
+ stale: string[];
405
418
  };
406
419
  write: (output: Artifact | undefined) => Promise<PromiseSettledResult<void>[]> | undefined;
407
420
  /**
@@ -429,6 +442,23 @@ declare class OutputEngine {
429
442
  }
430
443
  //#endregion
431
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
+ };
432
462
  declare class BambooContext extends Generator {
433
463
  runtime: Runtime;
434
464
  project: SourceProject;
@@ -490,7 +520,11 @@ declare class BambooContext extends Generator {
490
520
  }) => void;
491
521
  private getExplicitDependencies;
492
522
  initMessage: () => string;
493
- 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[];
494
528
  /**
495
529
  * Fail the build if any file's extraction threw.
496
530
  *
@@ -541,7 +575,7 @@ declare class BambooContext extends Generator {
541
575
  * "do not read it": the token and keyframe scans read whatever `include` covers, and a
542
576
  * project that excludes its `outdir` should not lose them.
543
577
  */
544
- private isGenerated;
578
+ isGenerated: (file: string) => boolean;
545
579
  /**
546
580
  * The text extraction reads for a file: its `parser:before` output, or its bytes when no hook
547
581
  * rewrites it. `undefined` when the file cannot be read at all.
@@ -599,7 +633,6 @@ declare class BambooContext extends Generator {
599
633
  */
600
634
  private hookedAuxiliaryFiles;
601
635
  private hookedAuxiliary;
602
- /** Load the required Rust extractor from the workspace or the published prebuild directory. */
603
636
  private loadNativeExtractor;
604
637
  private prepareNativeSource;
605
638
  /** Prepare a whole extraction pass in one coarse native invocation. */
@@ -629,13 +662,15 @@ declare class BambooContext extends Generator {
629
662
  */
630
663
  private get entrypointSpecifiers();
631
664
  /**
632
- * 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.
633
667
  *
634
- * 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
635
670
  * that wants the whole inventory — the watcher, the token scan — is unaffected: this narrows
636
671
  * what is *parsed*, not what the project holds.
637
672
  */
638
- extractableFiles: (files: readonly string[]) => string[];
673
+ extractableFiles: (files: readonly string[], linked?: readonly string[]) => string[];
639
674
  parseFiles: (styleEncoder?: StyleEncoder) => {
640
675
  filesWithCss: string[];
641
676
  files: string[];
@@ -648,6 +683,13 @@ declare class BambooContext extends Generator {
648
683
  }
649
684
  //#endregion
650
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
+ }
651
693
  /**
652
694
  * `analyze` is one CLI command, but this module is reachable from `@bamboocss/node`'s index,
653
695
  * so a static import made every consumer of that index — the CLI on any command, and the Vite
@@ -662,7 +704,26 @@ declare function analyze(ctx: BambooContext, options?: AnalysisOptions): Promise
662
704
  getTokenReport(format?: ReportFormat): {
663
705
  report: import("@bamboocss/reporter").TokenAnalysisReport;
664
706
  formatted: string;
665
- };
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>;
666
727
  writeReport(filePath: string): Promise<void>;
667
728
  }>;
668
729
  //#endregion
@@ -683,6 +744,11 @@ interface BuilderSetupOptions {
683
744
  configPath?: string;
684
745
  cwd?: string;
685
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;
686
752
  /** Record each atom's first call site during extraction, for `getAtomOrigins`. */
687
753
  atomOrigins?: boolean;
688
754
  /** A watcher-owned change journal. Without one, Builder performs its standalone filesystem scan. */
@@ -700,6 +766,8 @@ declare class Builder {
700
766
  private configDependencies;
701
767
  /** Last complete included inventory, including members which have since been deleted. */
702
768
  private sourceInventory;
769
+ /** Where the glob behind that inventory began, and what it reached through a link. */
770
+ private sourceLinks;
703
771
  /** Existing included owners selected by the last resolution-ledger invalidation pass. */
704
772
  private affectedFiles;
705
773
  /** Dependency-before-importer parse order for the selected owners. */
@@ -747,8 +815,20 @@ declare class Builder {
747
815
  getResolutionReadFiles: () => readonly string[];
748
816
  /** @internal The inventory reconciled by the most recent extraction pass. */
749
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[];
750
829
  /** The compiled `include`/`exclude` matcher of each context, since the compiler asks per module. */
751
830
  private sourceMatchers;
831
+ private sourceMatcherOf;
752
832
  /**
753
833
  * @internal Whether this path is one `include` covers and `exclude` does not.
754
834
  *
@@ -757,8 +837,40 @@ declare class Builder {
757
837
  * compiling it is wasted — and with the TypeScript 7 backend, far from free.
758
838
  */
759
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[];
760
870
  /** @internal Whether creating or deleting this path can change a `dependencies` glob. */
761
871
  isPotentialConfigDependency: (filePath: string) => boolean;
872
+ /** The compiled `dependencies` matcher of each context, since a watcher asks per event. */
873
+ private dependencyMatchers;
762
874
  /** @internal Exact local package/tsconfig files which can change semantic resolution. */
763
875
  getResolutionConfigurationFiles: () => readonly string[];
764
876
  private readResolutionConfiguration;
@@ -766,6 +878,8 @@ declare class Builder {
766
878
  private snapshotResolutionConfigurations;
767
879
  private recordConfigDependencies;
768
880
  setup: (options?: BuilderSetupOptions) => Promise<BambooContext | undefined>;
881
+ /** Whether `dependencies` matches other files now than the context was built with. */
882
+ private dependencyMembersMoved;
769
883
  /** Every file whose content participates in the resolved config, for the dev fast path. */
770
884
  private configGraphFiles;
771
885
  private configGraphUnchanged;
@@ -853,6 +967,11 @@ interface SetupContextOptions {
853
967
  }
854
968
  //#endregion
855
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;
856
975
  declare function codegen(ctx: BambooContext, ids?: ArtifactId[]): Promise<{
857
976
  box: string;
858
977
  msg: string;
@@ -888,11 +1007,98 @@ interface DebugOptions {
888
1007
  outdir: string;
889
1008
  dry: boolean;
890
1009
  onlyConfig?: boolean;
1010
+ /** Write the dump as one `<outdir>.zip`, which a bug report attaches, rather than as files. */
1011
+ zip?: boolean;
891
1012
  }
892
1013
  declare function debug(ctx: BambooContext, options: DebugOptions): Promise<void>;
893
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
894
1064
  //#region src/generate.d.ts
895
- 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);
896
1102
  //#endregion
897
1103
  //#region src/git-ignore.d.ts
898
1104
  declare function setupGitIgnore(ctx: BambooContext): void;
@@ -936,4 +1142,4 @@ declare const hasUncompilableSources: (options: {
936
1142
  include?: readonly string[];
937
1143
  }) => boolean;
938
1144
  //#endregion
939
- 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 };