@hussmartinez/sdk-config 0.0.0-stage → 0.1.0

package/src/dependency-cruiser/index.js

@@ -0,0 +1,171 @@
+/**
+ * Matches a layer folder in a single-package repository (`src/core/model/…`)
+ * and in a workspace package (`packages/sdk-core/src/core/model/…`).
+ *
+ * @param {string} folder Path below `src/`, such as `core/model`.
+ * @returns {string}
+ */
+const layer = (folder) => `(?:^|/)src/${folder}/`;
+
+const TEST_FILE = "\\.test\\.[cm]?[jt]sx?$";
+/**
+ * Matches an npm package, whether dependency-cruiser resolved it into
+ * `node_modules` or left it as a bare name because it isn't installed.
+ *
+ * @param {string} names Alternation of package names, such as `react|react-dom`.
+ * @returns {string}
+ */
+const npmPackage = (names) => `(?:^|/node_modules/)(?:${names})(?:/|$)`;
+
+const UI_PACKAGES = npmPackage("react|react-dom|@hussmartinez/ui");
+const SDK_CORE = npmPackage("@hussmartinez/sdk-core");
+
+/** Layers outside the core, which the core never imports. */
+const OUTER_LAYERS = ["adapters", "features", "react", "element", "workers"];
+
+/**
+ * Forbidden edges between the layers of ADR 0008, as clarified by ADR 0017.
+ * Each rule names a layer and the layers it must never import; anything not
+ * listed is allowed. The inner core rules only cover edges within the core,
+ * because `layer-core` already keeps the whole core away from the outer layers.
+ *
+ * @type {Array<{ name: string, from: string, notTo: string[], comment: string }>}
+ */
+const LAYER_RULES = [
+  {
+    name: "layer-model",
+    from: layer("core/model"),
+    notTo: ["core/operations", "core/ports", "core/session"],
+    comment: "core/model holds pure domain types and imports no other layer.",
+  },
+  {
+    name: "layer-operations",
+    from: layer("core/operations"),
+    notTo: ["core/ports", "core/session"],
+    comment: "core/operations may import only core/model and core/errors.",
+  },
+  {
+    name: "layer-ports",
+    from: layer("core/ports"),
+    notTo: ["core/operations", "core/session"],
+    comment: "core/ports may import only core/model and core/errors.",
+  },
+  {
+    name: "layer-core",
+    from: layer("core"),
+    notTo: OUTER_LAYERS,
+    comment: "The core never depends on adapters, features or UI layers.",
+  },
+  {
+    name: "layer-adapters",
+    from: layer("adapters"),
+    notTo: ["core/operations", "core/session", "features", "react", "element"],
+    comment: "Adapters implement ports and may import only ports, model, errors and sdk-core.",
+  },
+  {
+    name: "layer-features",
+    from: layer("features"),
+    notTo: ["adapters", "element", "workers"],
+    comment: "Features build on the core and ui, never on a specific adapter.",
+  },
+];
+
+/**
+ * dependency-cruiser preset for the SDK family. It enforces the layer rules of
+ * ADR 0008, as clarified by ADR 0017, and keeps production code away from
+ * tests, cycles and undeclared packages. Paths work both in `<kind>-sdk`
+ * repositories and in workspaces.
+ *
+ * @type {import("dependency-cruiser").IConfiguration}
+ */
+const config = {
+  forbidden: [
+    ...LAYER_RULES.map(({ name, from, notTo, comment }) => ({
+      name,
+      comment,
+      severity: /** @type {const} */ ("error"),
+      from: { path: from },
+      to: { path: notTo.map(layer) },
+    })),
+    {
+      name: "layer-errors",
+      comment: "core/errors is a leaf that imports only core/model and sdk-core (ADR 0017).",
+      severity: "error",
+      from: { path: layer("core/errors") },
+      to: {
+        pathNot: [
+          layer("core/errors"),
+          layer("core/model"),
+          SDK_CORE,
+          // Already reported by layer-core and core-no-ui.
+          ...OUTER_LAYERS.map(layer),
+          UI_PACKAGES,
+        ],
+      },
+    },
+    {
+      name: "core-no-ui",
+      comment: "The core is headless and server-safe, so no React or ui (ADR 0017).",
+      severity: "error",
+      from: { path: layer("core") },
+      to: { path: UI_PACKAGES },
+    },
+    {
+      name: "no-circular",
+      comment: "Cycles make load order fragile and layers impossible to separate.",
+      severity: "error",
+      from: {},
+      to: { circular: true },
+    },
+    {
+      name: "not-to-unresolvable",
+      comment: "Every import must resolve to a file or an installed package.",
+      severity: "error",
+      from: {},
+      to: { couldNotResolve: true },
+    },
+    {
+      name: "no-non-package-json",
+      comment: "Every package used must be declared in the closest package.json.",
+      severity: "error",
+      from: {},
+      to: { dependencyTypes: ["npm-no-pkg", "npm-unknown"] },
+    },
+    {
+      name: "not-to-dev-dep",
+      comment: "Published code must not need a devDependency at runtime.",
+      severity: "error",
+      from: { path: "(?:^|/)src/", pathNot: TEST_FILE },
+      to: {
+        dependencyTypes: ["npm-dev"],
+        dependencyTypesNot: ["npm-peer", "type-only"],
+        pathNot: "(?:^|/)node_modules/@types/",
+      },
+    },
+    {
+      name: "not-to-test",
+      comment: "Production code must not import tests.",
+      severity: "error",
+      from: { pathNot: TEST_FILE },
+      to: { path: TEST_FILE },
+    },
+  ],
+  options: {
+    doNotFollow: { path: "(?:^|/)node_modules/" },
+    // Build output (dist, and temp for tsc declarations and api-extractor)
+    // and coverage aren't source. Fixtures break the rules on purpose.
+    exclude: { path: "(?:^|/)(?:coverage|dist|fixtures|temp)/" },
+    tsPreCompilationDeps: true,
+    combinedDependencies: false,
+    enhancedResolveOptions: {
+      exportsFields: ["exports"],
+      conditionNames: ["types", "import", "node", "default"],
+      extensions: [".ts", ".tsx", ".mts", ".js", ".jsx", ".mjs", ".json"],
+    },
+    reporterOptions: {
+      text: { highlightFocused: true },
+    },
+  },
+};
+
+export default config;

package/src/dependency-cruiser/lint-deps.js

@@ -0,0 +1,330 @@
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+import { allExtensions, cruise, format, getAvailableTranspilers } from "dependency-cruiser";
+import extractDepcruiseConfig from "dependency-cruiser/config-utl/extract-depcruise-config";
+import extractTSConfig from "dependency-cruiser/config-utl/extract-ts-config";
+
+/** Exit code when the cruise is clean and covers every source file. */
+export const EXIT_OK = 0;
+/** Exit code for rule violations or source files the cruise didn't analyse. */
+export const EXIT_FAILED = 1;
+/** Exit code for usage and configuration errors. */
+export const EXIT_USAGE = 2;
+
+const MAX_LISTED_FILES = 20;
+const DECLARATION_FILE = /\.d\.[cm]?ts$/;
+const TYPESCRIPT_EXTENSION = /^\.[cm]?tsx?$/;
+
+/**
+ * An error the user can fix, reported as a message without a stack trace.
+ */
+export class UsageError extends Error {
+  /** @override */
+  name = "UsageError";
+}
+
+/**
+ * @typedef {object} LintDepsOptions
+ * @property {string[]} paths Files and folders to cruise, relative to `cwd`.
+ * @property {string} [cwd] Working directory. Defaults to `process.cwd()`.
+ * @property {string} [configFile] dependency-cruiser configuration file.
+ *   Defaults to `.dependency-cruiser.js`.
+ */
+
+/**
+ * @typedef {object} LintDepsResult
+ * @property {number} exitCode {@link EXIT_OK}, {@link EXIT_FAILED} or {@link EXIT_USAGE}.
+ * @property {string} report dependency-cruiser's error report, for stdout.
+ * @property {string} problems Coverage and usage problems, for stderr.
+ */
+
+/**
+ * Runs dependency-cruiser once with the repository's configuration, and also
+ * fails when the cruise didn't analyse a tracked source file. A missing parser
+ * makes dependency-cruiser skip files silently: without TypeScript, every
+ * `.ts` file is left out, or kept as a module with no dependencies when a
+ * JavaScript file imports it, and the run still passes.
+ *
+ * The expected files are those tracked by git under `paths` whose extension
+ * the configuration resolves (`enhancedResolveOptions.extensions`) and
+ * dependency-cruiser can parse in principle, minus declaration files and the
+ * configuration's `exclude`, `doNotFollow` and `includeOnly` filters.
+ *
+ * @param {LintDepsOptions} options
+ * @returns {Promise<LintDepsResult>}
+ */
+export async function lintDeps({
+  paths,
+  cwd = process.cwd(),
+  configFile = ".dependency-cruiser.js",
+}) {
+  try {
+    if (paths.length === 0) {
+      throw new UsageError("Pass at least one file or folder to check.");
+    }
+
+    const config = await loadConfig(resolve(cwd, configFile), cwd);
+    const { options = {}, ...ruleSet } = config;
+    const expected = expectedSourceFiles(listTrackedFiles(paths, cwd), options);
+    if (expected.length === 0) {
+      throw new UsageError(
+        `git tracks no source files under ${paths.join(", ")}, so there is nothing to check.`,
+      );
+    }
+
+    const result = await runCruise(paths, cwd, options, ruleSet);
+    const { output: report, exitCode: violations } = await format(result, { outputType: "err" });
+
+    const missing = unanalysedFiles(expected, result);
+
+    return {
+      exitCode: violations > 0 || missing.length > 0 ? EXIT_FAILED : EXIT_OK,
+      report: typeof report === "string" ? report : "",
+      problems: missing.length > 0 ? describeMissing(missing) : "",
+    };
+  } catch (error) {
+    const message =
+      error instanceof UsageError
+        ? error.message
+        : `dependency-cruiser failed: ${errorText(error)}`;
+    return { exitCode: EXIT_USAGE, report: "", problems: `hm-lint-deps: ${message}\n` };
+  }
+}
+
+/**
+ * @param {string} configPath
+ * @param {string} cwd
+ * @returns {Promise<import("dependency-cruiser").IConfiguration>}
+ */
+async function loadConfig(configPath, cwd) {
+  /** @type {import("dependency-cruiser").IConfiguration} */
+  let config;
+  try {
+    config = await extractDepcruiseConfig(configPath, new Set(), cwd);
+  } catch (error) {
+    throw new UsageError(`Can't load the configuration ${configPath}: ${errorText(error)}`);
+  }
+  for (const option of /** @type {const} */ (["webpackConfig", "babelConfig"])) {
+    if (config.options?.[option]) {
+      throw new UsageError(`The ${option} option isn't supported. Use depcruise directly.`);
+    }
+  }
+  return config;
+}
+
+/**
+ * Lists tracked files, with `/` separators and relative to `cwd`.
+ *
+ * @param {string[]} paths
+ * @param {string} cwd
+ * @returns {string[]}
+ */
+function listTrackedFiles(paths, cwd) {
+  assertInsideWorkTree(cwd);
+  const output = git(["ls-files", "-z", "--", ...paths], cwd);
+  return output.split("\0").filter(Boolean);
+}
+
+/**
+ * Fails with a dedicated message only when `cwd` really isn't in a work tree.
+ * Any other git problem is reported in git's own words.
+ *
+ * @param {string} cwd
+ */
+function assertInsideWorkTree(cwd) {
+  /** @type {string} */
+  let inside;
+  try {
+    inside = git(["rev-parse", "--is-inside-work-tree"], cwd).trim();
+  } catch (error) {
+    if (!(error instanceof GitError && /not a git repository/i.test(error.message))) {
+      throw error;
+    }
+    inside = "false";
+  }
+  if (inside !== "true") {
+    throw new UsageError(
+      `${cwd} isn't inside a git work tree. hm-lint-deps compares the cruise with the files git tracks.`,
+    );
+  }
+}
+
+/**
+ * A git command failed. The message is git's first line of error output.
+ */
+class GitError extends UsageError {
+  /** @override */
+  name = "GitError";
+}
+
+/**
+ * Runs git and returns its output, or throws a {@link GitError} with git's own
+ * first error line, such as `git ls-files failed: … is outside repository`.
+ *
+ * @param {string[]} args
+ * @param {string} cwd
+ * @returns {string}
+ */
+function git(args, cwd) {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  } catch (error) {
+    const command = `git ${args[0]}`;
+    if (/** @type {NodeJS.ErrnoException} */ (error).code === "ENOENT") {
+      throw new GitError(`${command} failed: git isn't installed or isn't on the PATH.`);
+    }
+    const stderr = String(/** @type {{ stderr?: unknown }} */ (error).stderr ?? "");
+    const firstLine = stderr.split("\n").find((line) => line.trim() !== "") ?? errorText(error);
+    throw new GitError(`${command} failed: ${firstLine.replace(/^(?:fatal|error): /, "")}`);
+  }
+}
+
+/**
+ * Selects the files the cruise must analyse.
+ *
+ * @param {string[]} files Tracked files, relative to the working directory.
+ * @param {import("dependency-cruiser").ICruiseOptions} options
+ * @returns {string[]}
+ */
+export function expectedSourceFiles(files, options) {
+  const configured = options.enhancedResolveOptions?.extensions;
+  if (!configured || configured.length === 0) {
+    throw new UsageError(
+      "The configuration sets no enhancedResolveOptions.extensions, so the expected files are unknown.",
+    );
+  }
+  const parseable = new Set(allExtensions.map(({ extension }) => extension));
+  const extensions = configured.filter((extension) => parseable.has(extension));
+  const exclude = patterns(options.exclude);
+  const doNotFollow = patterns(options.doNotFollow);
+  const includeOnly = patterns(options.includeOnly);
+
+  return files.filter(
+    (file) =>
+      extensions.some((extension) => file.endsWith(extension)) &&
+      !DECLARATION_FILE.test(file) &&
+      !exclude.some((pattern) => pattern.test(file)) &&
+      !doNotFollow.some((pattern) => pattern.test(file)) &&
+      (includeOnly.length === 0 || includeOnly.some((pattern) => pattern.test(file))),
+  );
+}
+
+/**
+ * A file counts as analysed when it's in the cruise result and
+ * dependency-cruiser can parse its extension. The second check matters,
+ * because a file reached only through an import appears in the result even
+ * when it couldn't be parsed.
+ *
+ * @param {string[]} expected
+ * @param {import("dependency-cruiser").ICruiseResult} result
+ * @returns {string[]}
+ */
+function unanalysedFiles(expected, result) {
+  const cruised = new Set(result.modules.map((module) => module.source));
+  const unparseable = allExtensions
+    .filter(({ available }) => !available)
+    .map(({ extension }) => extension);
+  return expected.filter(
+    (file) =>
+      !cruised.has(file) || unparseable.some((extension) => extensionOf(file) === extension),
+  );
+}
+
+/**
+ * The longest known extension a file ends with, so `.d.ts` wins over `.ts`.
+ *
+ * @param {string} file
+ * @returns {string | undefined}
+ */
+function extensionOf(file) {
+  return allExtensions
+    .map(({ extension }) => extension)
+    .filter((extension) => file.endsWith(extension))
+    .sort((a, b) => b.length - a.length)[0];
+}
+
+/**
+ * @param {string | string[] | { path?: string | string[] } | undefined} option
+ * @returns {RegExp[]}
+ */
+function patterns(option) {
+  const value = typeof option === "object" && !Array.isArray(option) ? option.path : option;
+  if (value === undefined) {
+    return [];
+  }
+  return (Array.isArray(value) ? value : [value]).map((pattern) => new RegExp(pattern));
+}
+
+/**
+ * @param {string[]} paths
+ * @param {string} cwd
+ * @param {import("dependency-cruiser").ICruiseOptions} options
+ * @param {import("dependency-cruiser").IFlattenedRuleSet} ruleSet
+ * @returns {Promise<import("dependency-cruiser").ICruiseResult>}
+ */
+async function runCruise(paths, cwd, options, ruleSet) {
+  const tsConfigFile = options.tsConfig?.fileName;
+  const tsConfig = tsConfigFile ? extractTSConfig(resolve(cwd, tsConfigFile)) : undefined;
+  const { output } = await cruise(
+    paths,
+    { ...options, baseDir: cwd, ruleSet, validate: true },
+    {},
+    tsConfig ? { tsConfig } : {},
+  );
+  if (typeof output === "string") {
+    throw new Error("expected a structured cruise result");
+  }
+  return output;
+}
+
+/**
+ * @param {string[]} missing
+ * @returns {string}
+ */
+function describeMissing(missing) {
+  const listed = missing.slice(0, MAX_LISTED_FILES).map((file) => `  ${file}`);
+  if (missing.length > MAX_LISTED_FILES) {
+    listed.push(`  … and ${missing.length - MAX_LISTED_FILES} more`);
+  }
+  const count =
+    missing.length === 1 ? "1 tracked source file" : `${missing.length} tracked source files`;
+  return [
+    `hm-lint-deps: dependency-cruiser didn't analyse ${count}:`,
+    ...listed,
+    "",
+    likelyCause(missing),
+    "",
+  ].join("\n");
+}
+
+/**
+ * @param {string[]} missing
+ * @returns {string}
+ */
+function likelyCause(missing) {
+  const unavailable = allExtensions
+    .filter(
+      ({ available, extension }) =>
+        !available && missing.some((file) => extensionOf(file) === extension),
+    )
+    .map(({ extension }) => extension);
+
+  if (unavailable.length === 0) {
+    return "Likely cause: these files aren't reachable from the paths passed. Check them and the configuration's exclude, doNotFollow and includeOnly options.";
+  }
+
+  const cause = `Likely cause: dependency-cruiser can't parse ${unavailable.join(", ")} files in this environment, because their parser isn't installed or isn't a supported version.`;
+  if (!unavailable.some((extension) => TYPESCRIPT_EXTENSION.test(extension))) {
+    return `${cause} Run "depcruise --info" to see which parsers it found.`;
+  }
+  const typescript = getAvailableTranspilers().find(({ name }) => name === "typescript");
+  return `${cause} For TypeScript, install a version dependency-cruiser supports (typescript ${typescript?.version ?? "see depcruise --info"}).`;
+}
+
+/**
+ * @param {unknown} error
+ * @returns {string}
+ */
+function errorText(error) {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/lint-staged/index.js

@@ -0,0 +1,19 @@
+/**
+ * lint-staged preset for the `pre-commit` hook (ADR 0016): a secret scan,
+ * Biome with safe fixes, and stylelint for CSS, on staged files only.
+ *
+ * The globs don't overlap, because lint-staged runs globs concurrently and two
+ * tools writing the same file would race. Within a glob, the secret scan runs
+ * first, before anything rewrites the file.
+ */
+const SECRETLINT = "secretlint --maskSecrets";
+const BIOME = "biome check --write --no-errors-on-unmatched --files-ignore-unknown=true";
+const STYLELINT = "stylelint --allow-empty-input";
+
+/** @type {Record<string, string[]>} */
+const config = {
+  "*.css": [SECRETLINT, BIOME, STYLELINT],
+  "!(*.css)": [SECRETLINT, BIOME],
+};
+
+export default config;

package/src/secretlint/index.js

@@ -0,0 +1,21 @@
+import { fileURLToPath } from "node:url";
+
+/**
+ * secretlint preset for the SDK family: the recommended rules, which detect
+ * cloud, npm, GitHub, Slack and other credentials and private keys (ADR 0016).
+ *
+ * secretlint resolves rule ids from its own install location, so the rule
+ * package is resolved here, from the preset, and passed as an absolute path.
+ * Consumers don't need to install it themselves.
+ *
+ * @type {{ rules: Array<{ id: string }> }}
+ */
+const config = {
+  rules: [
+    {
+      id: fileURLToPath(import.meta.resolve("@secretlint/secretlint-rule-preset-recommend")),
+    },
+  ],
+};
+
+export default config;

package/src/stylelint/index.js

@@ -0,0 +1,69 @@
+import layerNamePattern from "./plugins/layer-name-pattern.js";
+import noLiteralValues from "./plugins/no-literal-values.js";
+import selectorScope from "./plugins/selector-scope.js";
+
+/** A lowercase, hyphen-separated name, such as `pdf-thumb`. */
+const NAME = "[a-z0-9]+(?:-[a-z0-9]+)*";
+
+/**
+ * Stylelint preset for the SDK family. It enforces the family's own rules:
+ * the `hm` namespace (ADR 0003), scoped selectors (ADR 0005) and tokens for
+ * every design value (ADR 0006). General CSS correctness and formatting are
+ * Biome's job, so this preset doesn't extend a general-purpose config.
+ *
+ * @type {import("stylelint").Config}
+ */
+const config = {
+  plugins: [layerNamePattern, noLiteralValues, selectorScope],
+  reportDescriptionlessDisables: true,
+  reportInvalidScopeDisables: true,
+  reportNeedlessDisables: true,
+  rules: {
+    "custom-property-pattern": [
+      `^hm-${NAME}$`,
+      {
+        message: /** @param {string} name */ (name) =>
+          `Expected custom property "--${name}" to start with "--hm-"`,
+      },
+    ],
+    "keyframes-name-pattern": [
+      `^hm-${NAME}$`,
+      {
+        message: /** @param {string} name */ (name) =>
+          `Expected keyframes "${name}" to start with "hm-"`,
+      },
+    ],
+    "selector-attribute-name-disallowed-list": [
+      ["/^data-(?!hm-)/"],
+      {
+        message: /** @param {string} name */ (name) =>
+          `Expected data attribute "${name}" to start with "data-hm-"`,
+      },
+    ],
+    "selector-class-pattern": [
+      `^hm-${NAME}(?:--${NAME})?$`,
+      {
+        message: /** @param {string} name */ (name) =>
+          `Expected class "${name}" to match ".hm-<part>" or ".hm-<part>--<variant>". Use ARIA or data-hm-* attributes for states`,
+      },
+    ],
+    "selector-id-pattern": [
+      `^hm-${NAME}$`,
+      {
+        message: /** @param {string} name */ (name) => `Expected id "${name}" to start with "hm-"`,
+      },
+    ],
+    "hm/layer-name-pattern": true,
+    "hm/no-literal-values": true,
+    "hm/selector-scope": true,
+  },
+  overrides: [
+    {
+      // Token definitions are where literal values belong.
+      files: ["**/*.tokens.css", "**/tokens/**/*.css"],
+      rules: { "hm/no-literal-values": null },
+    },
+  ],
+};
+
+export default config;

package/src/stylelint/plugins/adr.js

@@ -0,0 +1,11 @@
+const ADR_BASE_URL = "https://github.com/hussmartinez/sdk-core/blob/main/docs/adr/";
+
+/**
+ * Builds the documentation link shown next to a rule's warnings.
+ *
+ * @param {string} file ADR file name, such as `0003-hm-namespace.md`.
+ * @returns {string}
+ */
+export function adrUrl(file) {
+  return `${ADR_BASE_URL}${file}`;
+}