@apollion-dsi/scripts 0.7.7 → 0.8.1

package/src/command/build.ts

@@ -95,6 +95,20 @@ function build(config: Configuration, previousFileSizes: unknown) {
   });
 }
 
+/**
+ * Run a one-shot webpack production build for the consumer app at `paths`.
+ *
+ * Side effects:
+ * - Sets `process.env.BABEL_ENV` / `NODE_ENV` to `'production'`.
+ * - Empties `paths.appBuild` and copies `paths.appPublic` into it.
+ * - On failure: prints the formatted error and exits with code 1
+ *   (or merely warns when `TSC_COMPILE_ON_ERROR=true`).
+ * - On `process.env.CI`-truthy runs, treats any webpack warning as a hard error.
+ *
+ * @param paths       Resolved app paths — typically `createAppPaths()`.
+ * @param userConfig  Optional override. Merged on top of {@link defaultDevConfig}.
+ *                    Pass `configureWebpack` here to mutate the final webpack config.
+ */
 export async function createProductionBuild(
   paths: AppPaths,
   userConfig: CustomConfigType = defaultDevConfig,

package/src/command/create/helper.ts

@@ -18,7 +18,6 @@ export const templateDependencies = [
   '@types/react-dom',
   '@types/react-router-dom',
   'styled-components',
-  '@types/styled-components',
   '@apollion-dsi/core',
   '@apollion-dsi/scripts',
   '@apollion-dsi/eslint-config',

package/src/command/dev.ts

@@ -22,6 +22,18 @@ import createDevServerConfig from '../config/webpackDevServer.config';
 import checkRequiredFiles from '../utils/checkRequiredFiles';
 import { choosePort, createCompiler, prepareProxy, prepareUrls } from '../utils/WebpackDevServerUtils';
 
+/**
+ * Boot a webpack-dev-server for the consumer app described by `paths`.
+ *
+ * Side effects:
+ * - Sets `process.env.BABEL_ENV` / `NODE_ENV` to `'development'`.
+ * - Picks an available port starting at `userConfig.port ?? 3000`.
+ * - Registers `SIGINT`/`SIGTERM` handlers that stop the server and exit.
+ *
+ * @param paths       Resolved app paths — typically `createAppPaths()`.
+ * @param userConfig  Optional override. Merged on top of {@link defaultDevConfig}.
+ *                    Pass `configureWebpack` here to mutate the final webpack config.
+ */
 export async function createDevServer(paths: AppPaths, userConfig: CustomConfigType = defaultDevConfig) {
   const useCustomConfig = fs.existsSync(paths.appCustomConfig);
 

package/src/command/test.ts

@@ -10,7 +10,7 @@ require('../config/env');
 
 import { execSync } from 'child_process';
 
-import jestRunner from 'jest-cli';
+import { run as jestRun } from 'jest-cli';
 
 const argv = process.argv.slice(2);
 
@@ -30,4 +30,4 @@ if (!process.env.CI && argv.indexOf('--watchAll') === -1 && argv.indexOf('--watc
   argv.push(hasSourceControl ? '--watch' : '--watchAll');
 }
 
-jestRunner.run(argv);
+jestRun(argv);

package/src/config/env.ts

@@ -3,6 +3,16 @@ import path from 'path';
 
 import { CustomConfigType } from './shared';
 
+/**
+ * Load environment variables from `.env*` files in cascading order
+ * (`.env.<NODE_ENV>.local`, `.env.local`, `.env.<NODE_ENV>`, `.env`)
+ * and prepend the consumer's `NODE_PATH` entries with absolute paths.
+ *
+ * **Throws** when `process.env.NODE_ENV` is unset — required so the
+ * cascade can pick the right file. Skips `.env.local` for `NODE_ENV=test`.
+ *
+ * @param paths  `AppPaths` (only `paths.dotenv` is read).
+ */
 export function getEnviroment(paths) {
   const { NODE_ENV, ENV } = process.env;
 
@@ -43,6 +53,19 @@ export function getEnviroment(paths) {
     .join(path.delimiter);
 }
 
+/**
+ * Pick the `REACT_APP_*` subset of `process.env`, augment it with the
+ * fixed `NODE_ENV`/`PUBLIC_URL`/`WDS_SOCKET_*`/`FAST_REFRESH` keys, and
+ * return both the raw object (for runtime consumers) and a stringified
+ * form ready for webpack's `DefinePlugin`.
+ *
+ * **Security:** vars NOT prefixed with `REACT_APP_` (e.g. `SECRET_KEY`)
+ * are excluded — this is the boundary that prevents server-only secrets
+ * from leaking into the client bundle.
+ *
+ * @param publicUrl  `paths.publicUrlOrPath` — exposed as `PUBLIC_URL`.
+ * @param config     Resolved `CustomConfigType` (only `useFastRefresh` is read).
+ */
 export default function getClientEnvironment(publicUrl: string, config: CustomConfigType) {
   // Grab NODE_ENV and REACT_APP_* environment variables and prepare them to be
   // injected into the application via DefinePlugin in webpack configuration.

package/src/config/paths.ts

@@ -3,22 +3,42 @@ import path from 'path';
 
 import getPublicUrlOrPath from '../utils/getPublicUrlOrPath';
 
+/**
+ * Resolved filesystem locations the build/dev/test commands operate on.
+ * Every entry is an absolute path computed from the consumer app root.
+ */
 export type AppPaths = {
+  /** `.env` file the consumer app reads from. Suffixed variants (`.env.local`, `.env.<NODE_ENV>`) are derived from this. */
   dotenv: string;
+  /** Consumer app root (= the directory containing `package.json`). */
   appPath: string;
+  /** Output directory for production bundles. Honors `scriptsrc.js#output`, defaults to `build/`. */
   appBuild: string;
+  /** Directory copied verbatim into `appBuild` during production builds. */
   appPublic: string;
+  /** Entry HTML used as the webpack `HtmlWebpackPlugin` template. */
   appHtml: string;
+  /** Resolved JS/TS entry under `src/` (extension picked by `moduleFileExtensions`). */
   appIndexJs: string;
+  /** Consumer app `src/` root. */
   appSrc: string;
+  /** Optional consumer-provided override file (`scriptsrc.js`). */
   appCustomConfig: string;
+  /** Consumer app `tsconfig.json`. */
   appTsConfig: string;
+  /** Consumer `yarn.lock` — drives "use yarn?" detection. */
   yarnLockFile: string;
+  /** Optional `src/setupTests.{ts,tsx,js}` resolved with the same extension precedence. */
   testsSetup: string;
+  /** Optional `src/setupProxy.js`. */
   proxySetup: string;
+  /** Consumer `node_modules/`. */
   appNodeModules: string;
+  /** Consumer `package.json`. */
   appPackageJson: string;
+  /** Public URL (or absolute pathname in dev) derived from env + homepage — see {@link getPublicUrlOrPath}. */
   publicUrlOrPath: string;
+  /** Source extensions tried (in order) when resolving JS/TS entries. */
   moduleFileExtensions: string[];
 };
 
@@ -36,6 +56,17 @@ export const moduleFileExtensions = [
   'jsx',
 ];
 
+/**
+ * Build the {@link AppPaths} object for the consumer app rooted at `basePath`.
+ *
+ * Reads (synchronously, at call time):
+ * - `<basePath>/package.json` — for `homepage`.
+ * - `<basePath>/scriptsrc.js` — if present, for `output` override.
+ * - `process.env.NODE_ENV`, `process.env.PUBLIC_URL` — drive public-url resolution.
+ *
+ * @param basePath  Defaults to `process.cwd()`. Pass an explicit path in tests
+ *                  to point at a fixture without changing the working dir.
+ */
 export function createAppPaths(basePath: string = process.cwd()): AppPaths {
   const appDirectory = fs.realpathSync(basePath);
   const resolveApp = (relativePath) => path.resolve(appDirectory, relativePath);

package/src/config/shared.ts

@@ -1,20 +1,35 @@
 import { Configuration } from 'webpack';
 
+/**
+ * Shape of the optional `scriptsrc.js` consumer apps drop next to their
+ * `package.json` to override CLI defaults. Every field is optional —
+ * unset keys fall back to {@link defaultDevConfig}.
+ */
 export type CustomConfigType = {
+  /** Dev server port. Default `3000`. `choosePort` will increment if busy. */
   port?: number;
+  /** Dev server host. Default `'0.0.0.0'` (listens on all interfaces). */
   host?: string;
+  /** HTML `<title>` injected via `HtmlWebpackPlugin`. */
   head?: HeadConfigType;
+  /** Constants exposed to the bundle via `DefinePlugin`. Stringified for you. */
   constants?: Record<string, string>;
+  /** Arbitrary i18n config object — opaque to the CLI, forwarded to consumer code. */
   i18nConfig?: Record<string, any>;
+  /** Enable React Refresh in dev. Default `true`. */
   useFastRefresh?: boolean;
+  /** Relay compiler artifact dir (used by `babel-plugin-relay`). */
   relayArtifactDirectory?: string;
+  /** Last-mile escape hatch: receives the resolved webpack config and must return one. */
   configureWebpack?: (config: Configuration, env: 'development' | 'production' | 'test') => Configuration;
 };
 
+/** `<head>` overrides — only `title` is consumed today. */
 export type HeadConfigType = {
   title: string;
 };
 
+/** Defaults merged into every `CustomConfigType` consumer override. */
 export const defaultDevConfig = {
   port: 3000,
   host: '0.0.0.0',

package/src/config/webpack.config.js

@@ -7,7 +7,7 @@ import ModuleNotFoundPlugin from '../utils/ModuleNotFoundPlugin';
 import ModuleScopePlugin from '../utils/ModuleScopePlugin';
 import ReactRefreshWebpackPlugin from '@pmmmwh/react-refresh-webpack-plugin';
 import CaseSensitivePathsPlugin from 'case-sensitive-paths-webpack-plugin';
-import GitRevision from 'git-revision-webpack-plugin';
+import { GitRevisionPlugin as GitRevisionPluginCtor } from 'git-revision-webpack-plugin';
 import HtmlWebpackPlugin from 'html-webpack-plugin';
 import resolve from 'resolve';
 import TerserPlugin from 'terser-webpack-plugin';
@@ -21,7 +21,7 @@ import modules from './modules';
 export default (webpackEnv, paths, options = {}) => {
   const appPackageJson = require(paths.appPackageJson);
 
-  const GitRevisionPlugin = new GitRevision({ branch: true });
+  const GitRevisionPlugin = new GitRevisionPluginCtor({ branch: true });
 
   const shouldInlineRuntimeChunk = process.env.INLINE_RUNTIME_CHUNK !== 'false';
 
@@ -64,7 +64,9 @@ export default (webpackEnv, paths, options = {}) => {
     output: {
       path: isEnvProduction ? paths.appBuild : undefined,
       pathinfo: isEnvDevelopment,
-      filename: isEnvProduction ? 'static/js/[name].[contenthash:8].js' : isEnvDevelopment && 'static/js/bundle.js',
+      filename: isEnvProduction
+        ? 'static/js/[name].[contenthash:8].js'
+        : isEnvDevelopment && 'static/js/[name].bundle.js',
       chunkFilename: isEnvProduction
         ? 'static/js/[name].[contenthash:8].chunk.js'
         : isEnvDevelopment && 'static/js/[name].chunk.js',
@@ -138,10 +140,7 @@ export default (webpackEnv, paths, options = {}) => {
         tls: false,
         child_process: false,
       },
-      plugins: [
-        new ModuleScopePlugin(paths.appSrc, [paths.appPackageJson]),
-        new TsconfigPathsPlugin(),
-      ],
+      plugins: [new ModuleScopePlugin(paths.appSrc, [paths.appPackageJson]), new TsconfigPathsPlugin()],
     },
     module: {
       strictExportPresence: true,

package/src/index.ts

@@ -1,3 +1,12 @@
+/**
+ * Public API of `@apollion-dsi/scripts` — the CRA-style CLI consumed by
+ * Apollion-based clients (Jovian, DEX-Aggregator, Fanaticofc). Detailed
+ * usage lives in {@link README.md}; this barrel only re-exports the
+ * three entry points consumer apps need.
+ *
+ * @packageDocumentation
+ */
+
 export { createAppPaths, AppPaths } from './config/paths';
 export { createDevServer } from './command/dev';
 export { createProductionBuild } from './command/build';

package/src/utils/checkRequiredFiles.ts

@@ -3,6 +3,15 @@ import path from 'path';
 
 import chalk from 'chalk';
 
+/**
+ * Verify every file in `files` exists on disk. Logs the first missing
+ * file to `console.log` (with chalk) and returns `false`; otherwise
+ * returns `true`. Used by the build/dev commands to fail fast before
+ * touching webpack.
+ *
+ * @param files  Absolute paths to required files (typically `paths.appHtml`,
+ *               `paths.appIndexJs`).
+ */
 export default function checkRequiredFiles(files: string[]): boolean {
   let currentFilePath: string | undefined;
   try {

package/src/utils/formatWebpackMessages.ts

@@ -1,3 +1,7 @@
+/**
+ * Normalized result of {@link formatWebpackMessages} — `errors` and
+ * `warnings` are always string arrays (empty if absent in the input).
+ */
 export type FormattedMessages = {
   errors: string[];
   warnings: string[];
@@ -23,6 +27,15 @@ function toString(item: unknown): string {
   return String(item);
 }
 
+/**
+ * Coerce webpack's `stats.toJson({ warnings, errors })` shape into a
+ * plain `{ errors, warnings }` of strings. Tolerates `null`, arrays of
+ * objects with `{ message, moduleName }`, raw primitives, or anything
+ * else (falls back to `JSON.stringify` / `String()`).
+ *
+ * @param json  Output of `stats.toJson({ warnings: true, errors: true })`
+ *              or any partially-shaped equivalent.
+ */
 export default function formatWebpackMessages(json: any): FormattedMessages {
   const errors = Array.isArray(json?.errors) ? json.errors.map(toString) : [];
   const warnings = Array.isArray(json?.warnings) ? json.warnings.map(toString) : [];

package/src/utils/getPublicUrlOrPath.ts

@@ -1,5 +1,24 @@
 import { URL } from 'url';
 
+/**
+ * Compute the absolute base URL (or path) every bundled asset is served from.
+ *
+ * Precedence: `envPublicUrl` → `homepage` → `'/'`.
+ *
+ * In **development**, absolute URLs collapse to their pathname so the
+ * dev-server doesn't try to fetch from a different origin; relative
+ * homepages (starting with `.`) collapse to `'/'` for the same reason.
+ *
+ * In **production**, the full URL (or pathname when only `homepage` is
+ * set) is preserved so CDN-rooted bundles resolve correctly.
+ *
+ * Adapted from `react-scripts` — semantics kept identical to ease migration.
+ *
+ * @param isEnvDevelopment  `true` when `NODE_ENV === 'development'`.
+ * @param homepage          `package.json#homepage` (project-level).
+ * @param envPublicUrl      `process.env.PUBLIC_URL` (per-invocation override).
+ * @returns A trailing-slash-normalized URL or absolute path.
+ */
 export default function getPublicUrlOrPath(
   isEnvDevelopment: boolean,
   homepage: string | undefined,

package/tsconfig.json

@@ -1,6 +1,6 @@
 {
   "include": ["src"],
-  "exclude": ["./src/template"],
+  "exclude": ["./src/template", "./src/__tests__"],
   "compilerOptions": {
     "outDir": "lib",
     "rootDir": "src",

package/tsconfig.test.json

@@ -0,0 +1,14 @@
+{
+  "extends": "./tsconfig.json",
+  "include": ["src", "src/__tests__"],
+  "exclude": [],
+  "compilerOptions": {
+    "noEmit": true,
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "isolatedModules": false,
+    "noImplicitAny": false,
+    "types": ["jest", "node"]
+  }
+}

package/verify-no-install-scripts.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * verify-no-install-scripts — supply-chain hardening (threat-model E2).
+ *
+ * Blocks `@apollion-dsi/*` workspaces from declaring lifecycle scripts that
+ * **run on consumer install** of the published package — the attack vector
+ * for malicious npm postinstall (event-stream / ua-parser-js precedent).
+ *
+ * **Strictly blocked (consumer-install-time):**
+ *   preinstall, install, postinstall
+ *
+ * **Allowed with caution (publish-time only — npm 7+ does NOT run these on
+ * consumer install):** prepare, prepublish, prepublishOnly, postpublish.
+ * These are legitimate for `yarn build` style workflows but still appear in
+ * the published tarball. Audit in PR review for any code that fetches
+ * remote resources or mutates the working tree.
+ *
+ * Exit 0 on clean, exit 1 if any forbidden hook found.
+ *
+ * @see ADR-006 §3.8 boundary B2 (anti-postinstall policy)
+ * @see ADR-006 §8.5 risk #7 (E2 NPM postinstall lateral)
+ * @see PRD-002 §S5
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const FORBIDDEN_HOOKS = ['preinstall', 'install', 'postinstall'];
+
+const REPO_ROOT = process.argv[2]
+	? path.resolve(process.argv[2])
+	: path.resolve(__dirname, '..', '..');
+
+const PACKAGES_DIR = path.join(REPO_ROOT, 'packages');
+
+function findPackageJsons() {
+	const out = [];
+	if (!fs.existsSync(PACKAGES_DIR)) return out;
+	for (const name of fs.readdirSync(PACKAGES_DIR)) {
+		const pkgPath = path.join(PACKAGES_DIR, name, 'package.json');
+		if (fs.existsSync(pkgPath)) out.push(pkgPath);
+	}
+	return out;
+}
+
+function scan(pkgPath) {
+	const data = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+	const name = data.name ?? '<unknown>';
+	const scripts = data.scripts ?? {};
+	const violations = FORBIDDEN_HOOKS.filter((hook) => Object.prototype.hasOwnProperty.call(scripts, hook));
+	return { name, pkgPath, violations };
+}
+
+function main() {
+	const results = findPackageJsons().map(scan);
+	const bad = results.filter((r) => r.violations.length > 0);
+
+	if (bad.length === 0) {
+		console.log(`✓ verify-no-install-scripts: ${results.length} package.json clean (no forbidden lifecycle hooks)`);
+		process.exit(0);
+	}
+
+	console.error('✗ verify-no-install-scripts: forbidden lifecycle hooks found:');
+	for (const r of bad) {
+		console.error(`  ${r.name} (${path.relative(REPO_ROOT, r.pkgPath)})`);
+		for (const hook of r.violations) {
+			console.error(`    - ${hook}: ${r.violations.length === 1 ? '' : ''}`);
+		}
+	}
+	console.error('');
+	console.error('  ADR-006 §3.8 boundary B2 + §8.5 risk E2 forbid install-time scripts');
+	console.error('  in @apollion-dsi/* workspaces to mitigate supply-chain attack vector.');
+	process.exit(1);
+}
+
+main();

package/.prettierrc.js

@@ -1 +0,0 @@
-module.exports = require('@apollion-dsi/eslint-config/prettier.config');

package/README.MD

@@ -1,91 +0,0 @@
-# Apollion Scripts
-
-Interface de linha de comando, contendo o template para iniciar, desenvolver e fazer o build de uma aplicação com Apollion Design System.
-
-## Desenvolvimento
-
-### Criando um novo projeto
-
-Você pode iniciar um novo projeto usando a nossa `CLI` com o comando a seguir:
-
-```bash
-$ npx @captalys-platform/scripts create project-name
-$ cd project-name
-$ yarn start
-# ou
-$ npm start
-```
-
-Você não precisa instalar ou configurar ferramentas como `webpack` e `babel`, ambos já vem configurados para que você possa focar no código. Além disso o template inclui `eslint`, `prettier`, `jest`, `commitLint` e `Typescript`. O template tem a seguinte estrutura:
-
-```
-project-name
-├── node_modules
-├── package.json
-├── tsconfig.json
-├── jest.config.js
-├── commitlint.config.js
-├── .eslintrc.js
-├── .editorconfig.js
-├── .gitignore
-├── .prettierrc.js
-├── public
-│   ├── index.html
-└── src
-    ├── index.tsx
-    ├── App.tsx
-    ├── App.test.tsx
-```
-
-### Projetos existentes
-
-1. Para projetos existentes, você pode usar nossa `CLI` da seguinte forma (na raiz do projeto)
-
-```bash
-$ npm install @captalys-platform/scripts --save-dev
-# ou
-$ yarn add @captalys-platform/scripts --dev
-```
-
-2. Você deve atualizar o campo `scripts` do `package.json`
-
-```json
-{
-  "scripts": {
-    "dev": "scripts dev",
-    "build": "scripts build",
-    "test": "scripts test"
-  }
-}
-```
-
-3. Para a aplicação funcionar é necessário utilizar a estrutura de pasta a seguir
-
-```
-project-name
-├── package.json
-├── public
-│   ├── index.html
-└── src
-    ├── index.tsx
-```
-
-## Comandos
-
-Estes são os comandos disponíveis no nosso template
-
-- `yarn start` ou `npm start`
-
-  Roda o projeto em um servidor de desenvolvimento, com reload automático, em http://localhost:3000/.
-
-- `yarn build` ou `npm build`
-
-  Cria o projeto para ser distribuído para produção, na pasta **build**.
-
-- `yarn test` ou `npm test`
-
-  Roda os testes com `jest --watch` nos arquivos alterados a partir do ultimo commit.
-
-## Licença
-
-© 2021 Captalys - Todos os direitos reservados.

package/audit-ci.json

@@ -1,5 +0,0 @@
-{
-  "moderate": true,
-  "package-manager": "yarn",
-  "report-type": "summary"
-}