fabrique 2.0.22 → 2.0.23

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/CONTRIBUTING.md CHANGED
@@ -75,6 +75,9 @@ yarn install
75
75
 
76
76
  > Use the `dev` versions only if required.
77
77
 
78
+ > NOTE: the PR is published only if it carries the `dev` label: add it to the PR to get a `dev` release, otherwise the release is skipped.
79
+ > Pull requests coming from forks always run in dry-run mode: nothing is published.
80
+
78
81
  ### 2. Push to `develop`
79
82
 
80
83
  - Impacted packages are published as: `x.y.z-rc.<timestamp>`
@@ -116,6 +119,7 @@ flowchart LR
116
119
 
117
120
  ## Important Rules
118
121
 
119
- - if an equivalent **stable** version already exists on npm: the release is skipped
122
+ - if an equivalent **stable** version already exists on npm: the release fails — bump the `package.json#version` before releasing (this also blocks `dev` / `rc` releases of a stable version that was already published)
120
123
  - the `package.json` file in the repo must keep stable versions (`x.y.z`)
121
124
  - `-dev` / `-rc` suffixes are generated in CI
125
+ - the npm publish authenticates with [GitHub Actions OIDC](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-oidc): no `NPM_TOKEN` secret is required (the `release.yml` workflow requests the `id-token: write` permission)
package/README.md CHANGED
@@ -101,6 +101,11 @@ It tries to be non-destructive.
101
101
 
102
102
  > INFO: run the command **inside** the `fabrique` project.
103
103
 
104
+ > WARNING: the files belonging to the `fabrique` template are **overwritten** on each upgrade.
105
+ > Only `src/**/*`, `README.md`, `LICENSE`, `package.json`, `yarn.lock` and `.github/auto_assign.yml` are preserved: every other file present in the template (ex: `.github/workflows/*`, `tsconfig.json`, `vitest.config.ts`, `.yarnrc.yml`, `.prettierrc`, `.nvmrc`, and the `fabrique/` directory) is replaced by the template's version.
106
+ > Do not hand-edit these files: your changes would be silently lost on the next upgrade. Instead, put your custom configuration in separate files (ex: an additional workflow file, or a dedicated tsconfig extending the generated one).
107
+ > The `package.json` scripts are merged: your scripts are kept as long as they are not prefixed with `fb:` (they are moved under the `=== FB: CUSTOM SCRIPTS ===` section), while `fb:`-prefixed scripts are considered fabrique-owned and replaced by the template's versions.
108
+
104
109
  ##### options
105
110
 
106
111
  - `--force`: forces an upgrade even if the lib is not a `fabrique` project or if the version is identical. _Use with caution._
@@ -123,7 +128,12 @@ This command builds an existing `fabrique` project.
123
128
  Summary:
124
129
 
125
130
  - TypeScript files are transpiled into JavaScript files.
131
+ - The public API of your library is defined by a generated barrel file: at build time, a temporary `src/index.ts` re-exporting all non-private, non-test source files is generated, transpiled, then **removed**.
132
+ Never commit it, and don't import it from your sources: import your modules directly instead.
133
+ Only the files transitively imported from this barrel (or from `src/index.protected.ts`) are transpiled and published.
126
134
  - You can exclude some files or directories by adding the suffix `.private` to the file or directory name (ex: `src/**/*.private/**/.ts`, `src/**/*.private.ts`).
135
+ Private files are excluded from the barrel and are not published, unless they are imported by an exported file.
136
+ - Files suffixed with `.test.ts`, `.spec.ts` or `.bench.ts` are excluded from the barrel and are never published (tests run from the sources with `fb:test`).
127
137
  - You can exclude `protected` files or directories by adding the suffix `.protected` to the file or directory name.
128
138
  These files are exported into a separate `src/index.protected.ts` file, that can be imported by `import * from '@my-organization/my-library/protected'`.
129
139
  - A ready to publish package is generated in the `dist` folder.
@@ -132,11 +142,12 @@ Summary:
132
142
 
133
143
  <summary>Details</summary>
134
144
 
135
- 1. All `src/**/*.ts` files are transpiled into `dist/src/**/*.js`, `dist/src/**/*.js.map`, and `dist/src/**/*.d.ts` files.
136
- 1. All `src/**/*.ts` files except `src/**/*.{test,spec,bench,protected,private}.ts` and `src/**/*.{test,spec,bench,protected,private}/**/*.ts`
137
- are exported into a temporatry `src/index.ts` file (and transpiled into `dist/src/index.js`).
138
- 1. All `src/**/*.protected.ts` files except `src/**/*.{test,spec,bench,private}.ts` and `src/**/*.{test,spec,bench,private}/**/*.ts`
139
- are exported into a temporatry `src/index.protected.ts` file (and transpiled into `dist/src/index.protected.js`).
145
+ 1. A temporary `src/index.ts` re-exporting all `src/**/*.ts` files except `src/**/*.{test,spec,bench,protected,private}.ts` and `src/**/*.{test,spec,bench,protected,private}/**/*.ts`
146
+ is generated (and transpiled into `dist/src/index.js`). This file is removed once the build completes: never commit it.
147
+ 1. A temporary `src/index.protected.ts` re-exporting all `src/**/*.protected.ts` files except `src/**/*.{test,spec,bench,private}.ts` and `src/**/*.{test,spec,bench,private}/**/*.ts`
148
+ is generated (and transpiled into `dist/src/index.protected.js`).
149
+ 1. TypeScript is compiled with the barrel files as the only entry points: a file is transpiled into `dist/src/**/*.js` (with its `.js.map` and `.d.ts` files) only if it is transitively imported from `src/index.ts` (or `src/index.protected.ts`).
150
+ All other files (ex: all `*.test.ts` files, or `*.private.ts` files not imported by an exported file) are not transpiled at all.
140
151
 
141
152
  - NOTE: if no `protected` files are found, the `index.protected.ts` file is not generated
142
153
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fabrique",
3
- "version": "2.0.22",
3
+ "version": "2.0.23",
4
4
  "type": "module",
5
5
  "description": "CLI to build a library",
6
6
  "keywords": [],
@@ -81,6 +81,9 @@ yarn install
81
81
 
82
82
  > Use the `dev` versions only if required.
83
83
 
84
+ > NOTE: the PR is published only if it carries the `dev` label: add it to the PR to get a `dev` release, otherwise the release is skipped.
85
+ > Pull requests coming from forks always run in dry-run mode: nothing is published.
86
+
84
87
  ### 2. Push to `develop`
85
88
 
86
89
  - Impacted packages are published as: `x.y.z-rc.<timestamp>`
@@ -122,6 +125,7 @@ flowchart LR
122
125
 
123
126
  ## Important Rules
124
127
 
125
- - if an equivalent **stable** version already exists on npm: the release is skipped
128
+ - if an equivalent **stable** version already exists on npm: the release fails — bump the `package.json#version` before releasing (this also blocks `dev` / `rc` releases of a stable version that was already published)
126
129
  - the `package.json` file in the repo must keep stable versions (`x.y.z`)
127
130
  - `-dev` / `-rc` suffixes are generated in CI
131
+ - the npm publish authenticates with [GitHub Actions OIDC](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-oidc): no `NPM_TOKEN` secret is required (the `release.yml` workflow requests the `id-token: write` permission)