@jterrazz/typescript 9.3.0 → 10.0.0

package/src/docs.test.ts

@@ -1,13 +1,13 @@
 import { expect, test } from 'vitest';
 
-import { auditDocs } from './docs.js';
+import { auditDocs, type DocsTree } from './docs.js';
 
 /**
  * The manual every repository carries, in its smallest compliant form: a map,
  * the three required spine chapters, and a brief that routes into it. Each test
  * breaks exactly one thing and reads the rule that names it.
  */
-function manual(overrides: Record<string, unknown> = {}) {
+function manual(overrides: Partial<DocsTree> = {}): DocsTree {
     return {
         agents: '# Agent brief\n\nThe corpus is docs/README.md.\n',
         files: [
@@ -27,19 +27,19 @@ function manual(overrides: Record<string, unknown> = {}) {
 }
 
 /** The rule ids a tree breaks, in the order the engine reports them. */
-function rules(tree: ReturnType<typeof manual>) {
-    return auditDocs(tree as never).map((violation) => violation.rule);
+function rules(tree: DocsTree) {
+    return auditDocs(tree).map((violation) => violation.rule);
 }
 
 /** The sentence one rule printed about a tree. */
-function sentence(tree: ReturnType<typeof manual>, rule: string) {
-    return auditDocs(tree as never).find((violation) => violation.rule === rule)?.message;
+function sentence(tree: DocsTree, rule: string) {
+    return auditDocs(tree).find((violation) => violation.rule === rule)?.message;
 }
 
 test('passes the smallest compliant manual', () => {
     // Given - a map, the three spine chapters, a brief that routes into them
     // Then - nothing to say
-    expect(auditDocs(manual() as never)).toEqual([]);
+    expect(auditDocs(manual())).toStrictEqual([]);
 });
 
 test('names a repository that carries no manual at all, and says nothing else', () => {
@@ -47,7 +47,7 @@ test('names a repository that carries no manual at all, and says nothing else',
     const tree = manual({ agents: null, files: [] });
 
     // Then - one sentence, not a cascade of every rule the absence breaks
-    expect(rules(tree)).toEqual(['docs-absent']);
+    expect(rules(tree)).toStrictEqual(['docs-absent']);
     expect(sentence(tree, 'docs-absent')).toBe(
         'docs/ is missing — every repository carries its own manual, starting at docs/README.md',
     );
@@ -61,7 +61,7 @@ test('names a docs/ with no map', () => {
     });
 
     // Then - the map is the one file an outside corpus points at
-    expect(rules(tree)).toEqual(['docs-map-missing']);
+    expect(rules(tree)).toStrictEqual(['docs-map-missing']);
     expect(sentence(tree, 'docs-map-missing')).toBe(
         'docs/README.md is missing — the map is the one file an outside corpus points at',
     );
@@ -101,7 +101,7 @@ test('names a chapter the map forgot', () => {
 test('names a map link that leaves the manual', () => {
     // Given - a map routing to the repository's own README
     const tree = manual({
-        links: { 'docs/README.md': [...manual().links['docs/README.md'], '../README.md'] },
+        links: { 'docs/README.md': [...(manual().links['docs/README.md'] ?? []), '../README.md'] },
     });
 
     // Then - the map routes to chapters, decisions/ and reference/, and nothing else
@@ -115,7 +115,7 @@ test('lets the map route to decisions/ and reference/', () => {
     const tree = manual({
         links: {
             'docs/README.md': [
-                ...manual().links['docs/README.md'],
+                ...(manual().links['docs/README.md'] ?? []),
                 'decisions/',
                 'reference/index.md',
             ],
@@ -123,14 +123,16 @@ test('lets the map route to decisions/ and reference/', () => {
     });
 
     // Then - neither is foreign
-    expect(rules(tree)).toEqual([]);
+    expect(rules(tree)).toStrictEqual([]);
 });
 
 test('names a chapter that is not NN-kebab.md', () => {
     // Given - a fourth chapter with one digit and an upper-case word
     const tree = manual({
         files: [...manual().files, 'docs/4-Lint_presets.md'],
-        links: { 'docs/README.md': [...manual().links['docs/README.md'], '4-Lint_presets.md'] },
+        links: {
+            'docs/README.md': [...(manual().links['docs/README.md'] ?? []), '4-Lint_presets.md'],
+        },
     });
 
     // Then - the mold is named, and the number it took is still judged
@@ -145,7 +147,7 @@ test('names chapter numbers that skip, and numbers claimed twice', () => {
         files: [...manual().files, 'docs/05-building.md', 'docs/05-presets.md'],
         links: {
             'docs/README.md': [
-                ...manual().links['docs/README.md'],
+                ...(manual().links['docs/README.md'] ?? []),
                 '05-building.md',
                 '05-presets.md',
             ],
@@ -179,7 +181,7 @@ test('names each missing spine chapter', () => {
     });
 
     // Then - developing and testing are each asked for
-    expect(rules(tree)).toEqual(['docs-spine-missing', 'docs-spine-missing']);
+    expect(rules(tree)).toStrictEqual(['docs-spine-missing', 'docs-spine-missing']);
     expect(sentence(tree, 'docs-spine-missing')).toBe(
         '02-developing.md is missing — the spine is architecture, developing, testing',
     );
@@ -208,41 +210,47 @@ test('asks for 04-operating.md from a published package', () => {
 test('never asks for 04-operating.md from a repository that ships nothing', () => {
     // Given - no image, no infrastructure, a private manifest
     // Then - the lint only ever requires; it never forbids a 04 either
-    expect(rules(manual())).toEqual([]);
+    expect(rules(manual())).toStrictEqual([]);
 });
 
 test('lets 05 follow 03 directly when the repository ships nothing', () => {
     // Given - 01-03 then 05, no 04 chapter, nothing that would ask for one
     const tree = manual({
         files: [...manual().files, 'docs/05-building.md'],
-        links: { 'docs/README.md': [...manual().links['docs/README.md'], '05-building.md'] },
+        links: {
+            'docs/README.md': [...(manual().links['docs/README.md'] ?? []), '05-building.md'],
+        },
     });
 
     // Then - 04 is the one gap the numbering excuses
-    expect(rules(tree)).toEqual([]);
+    expect(rules(tree)).toStrictEqual([]);
 });
 
 test('still asks for 04-operating.md from that same shape once it ships', () => {
     // Given - the same 01-03 + 05 shape, but an image this time
     const tree = manual({
         files: [...manual().files, 'docs/05-building.md'],
-        links: { 'docs/README.md': [...manual().links['docs/README.md'], '05-building.md'] },
+        links: {
+            'docs/README.md': [...(manual().links['docs/README.md'] ?? []), '05-building.md'],
+        },
         ships: { dockerfile: true, infrastructure: false, publishable: false },
     });
 
     // Then - the numbering stays clean; only the presence test speaks
-    expect(rules(tree)).toEqual(['docs-operating-missing']);
+    expect(rules(tree)).toStrictEqual(['docs-operating-missing']);
 });
 
 test('refuses a gap at 05 even though 04 may be absent', () => {
     // Given - 01-03 then 06, skipping past the one number the spine excuses
     const tree = manual({
         files: [...manual().files, 'docs/06-quality-checks.md'],
-        links: { 'docs/README.md': [...manual().links['docs/README.md'], '06-quality-checks.md'] },
+        links: {
+            'docs/README.md': [...(manual().links['docs/README.md'] ?? []), '06-quality-checks.md'],
+        },
     });
 
     // Then - only 04 is excused; 05 still has to be there
-    expect(rules(tree)).toEqual(['docs-chapter-numbering']);
+    expect(rules(tree)).toStrictEqual(['docs-chapter-numbering']);
 });
 
 test('names a chapter that is a journal, not a subject', () => {
@@ -250,7 +258,10 @@ test('names a chapter that is a journal, not a subject', () => {
     const tree = manual({
         files: [...manual().files, 'docs/04-design-exploration.md'],
         links: {
-            'docs/README.md': [...manual().links['docs/README.md'], '04-design-exploration.md'],
+            'docs/README.md': [
+                ...(manual().links['docs/README.md'] ?? []),
+                '04-design-exploration.md',
+            ],
         },
     });
 
@@ -303,7 +314,7 @@ function withDecisions(overrides: Record<string, unknown> = {}) {
 test('passes a well-formed decisions folder', () => {
     // Given - one record on the mold, beside the mold itself
     // Then - nothing to say
-    expect(rules(withDecisions())).toEqual([]);
+    expect(rules(withDecisions())).toStrictEqual([]);
 });
 
 test('names a decision file that is not NNN-kebab.md', () => {
@@ -349,7 +360,7 @@ test('names a decision whose heading claims another number', () => {
     });
 
     // Then - the same rule catches the disagreement
-    expect(rules(tree)).toEqual(['docs-decision-heading']);
+    expect(rules(tree)).toStrictEqual(['docs-decision-heading']);
 });
 
 test('names a decision outside the status vocabulary', () => {
@@ -383,7 +394,7 @@ test('accepts a superseded status that links the record replacing it', () => {
     });
 
     // Then - nothing to say
-    expect(rules(tree)).toEqual([]);
+    expect(rules(tree)).toStrictEqual([]);
 });
 
 test('refuses a superseded status with no link naming the successor', () => {
@@ -409,7 +420,7 @@ test('passes an empty decisions folder', () => {
     const tree = manual({ files: [...manual().files, 'docs/decisions/'] });
 
     // Then - a folder with nothing to number has no sequence to break
-    expect(rules(tree)).toEqual(['docs-template-missing']);
+    expect(rules(tree)).toStrictEqual(['docs-template-missing']);
 });
 
 test('passes a decisions folder holding only the template', () => {
@@ -419,7 +430,7 @@ test('passes a decisions folder holding only the template', () => {
     });
 
     // Then - nothing to say
-    expect(rules(tree)).toEqual([]);
+    expect(rules(tree)).toStrictEqual([]);
 });
 
 test('refuses a decision sequence that skips a number', () => {
@@ -497,7 +508,7 @@ test('lets a duplicated number pass the sequence check on its own', () => {
     });
 
     // Then - docs-decision-number still refuses it; the sequence itself is not the gap
-    expect(rules(tree)).toEqual(['docs-decision-number']);
+    expect(rules(tree)).toStrictEqual(['docs-decision-number']);
 });
 
 test('names a number two records claim', () => {
@@ -565,7 +576,7 @@ test('passes a stamped reference page', () => {
     });
 
     // Then - nothing to say
-    expect(rules(tree)).toEqual([]);
+    expect(rules(tree)).toStrictEqual([]);
 });
 
 test('names a repository whose brief does not route to the manual', () => {
@@ -583,7 +594,7 @@ test('names a brief that exists but routes elsewhere', () => {
     const tree = manual({ agents: '# Agent brief\n\nEverything you need is right here.\n' });
 
     // Then - the same rule
-    expect(rules(tree)).toEqual(['docs-agents-route']);
+    expect(rules(tree)).toStrictEqual(['docs-agents-route']);
 });
 
 test('names a chapter reaching into another repository', () => {
@@ -616,5 +627,5 @@ test('lets a chapter cite a sibling repository by url, and reach its own root',
     });
 
     // Then - a citation is not a reach, and the repository's own tree is fair game
-    expect(rules(tree)).toEqual([]);
+    expect(rules(tree)).toStrictEqual([]);
 });

package/src/index.d.ts

@@ -1,18 +1,22 @@
-type ConfigObject = Record<string, unknown>;
+import { type OxfmtConfig } from './oxfmt.js';
+import { type OxlintConfig } from './oxlint.js';
 
-declare const oxfmtConfig: ConfigObject;
+declare const oxfmtConfig: OxfmtConfig;
 
-declare const oxlintPresets: {
-    expo: ConfigObject;
-    hexagonal: ConfigObject;
-    next: ConfigObject;
-    node: ConfigObject;
+declare const oxlintProfiles: {
+    astro: OxlintConfig;
+    bun: OxlintConfig;
+    expo: OxlintConfig;
+    hexagonal: OxlintConfig;
+    library: OxlintConfig;
+    next: OxlintConfig;
+    node: OxlintConfig;
 };
 
 declare const defaultExport: {
     oxfmt: typeof oxfmtConfig;
-    oxlint: typeof oxlintPresets;
+    oxlint: typeof oxlintProfiles;
 };
 
-export { oxfmtConfig as oxfmt, oxlintPresets as oxlint };
+export { oxfmtConfig as oxfmt, oxlintProfiles as oxlint };
 export default defaultExport;

package/src/index.js

@@ -1,16 +1,23 @@
 import oxfmtConfig from '../presets/oxfmt/index.js';
-import hexagonalConfig from '../presets/oxlint/architectures/hexagonal.js';
-import expoConfig from '../presets/oxlint/expo.js';
-import nextConfig from '../presets/oxlint/next.js';
-import nodeConfig from '../presets/oxlint/node.js';
+import astroProfile from '../presets/oxlint/profiles/astro.js';
+import bunProfile from '../presets/oxlint/profiles/bun.js';
+import expoProfile from '../presets/oxlint/profiles/expo.js';
+import libraryProfile from '../presets/oxlint/profiles/library.js';
+import nextProfile from '../presets/oxlint/profiles/next.js';
+import nodeProfile from '../presets/oxlint/profiles/node.js';
+import hexagonalFragment from '../rules/architecture/hexagonal.js';
+import { compile } from '../rules/compile.js';
 
 export const oxfmt = oxfmtConfig;
 
 export const oxlint = {
-    expo: expoConfig,
-    hexagonal: hexagonalConfig,
-    next: nextConfig,
-    node: nodeConfig,
+    astro: astroProfile,
+    bun: bunProfile,
+    expo: expoProfile,
+    hexagonal: compile(hexagonalFragment),
+    library: libraryProfile,
+    next: nextProfile,
+    node: nodeProfile,
 };
 
 export default { oxfmt, oxlint };

package/src/oxfmt.d.ts

@@ -1,6 +1,19 @@
-type ConfigObject = Record<string, unknown>;
+/*
+ * The shape of a formatting config is oxfmt's own fact, so this entry does not
+ * restate it: `OxfmtConfig` and the two sorter shapes are re-exported from the
+ * tool, under the names a consumer already reads here. A hand copy drifts —
+ * this one had grown an `endOfLine: 'auto'` oxfmt does not accept, and a
+ * consumer's `defineConfig(base)` stopped type-checking because of it.
+ */
 
-declare const base: ConfigObject;
+import { type OxfmtConfig } from 'oxfmt';
+
+declare const base: OxfmtConfig;
 
 export { defineConfig } from 'oxfmt';
+export {
+    type OxfmtConfig,
+    type SortImportsUserConfig as SortImports,
+    type SortTailwindcssUserConfig as SortTailwindcss,
+} from 'oxfmt';
 export { base };

package/src/oxfmt.test.ts

@@ -8,6 +8,16 @@ test('exports the shared formatting preset', () => {
     expect(base).toMatchObject({ printWidth: 100, singleQuote: true, tabWidth: 4 });
 });
 
+test('gives the formatter the three sorters, so no lint rule owns an order', () => {
+    // Given - the shared preset
+    // Then - import order, package.json key order and Tailwind class order are oxfmt's
+    expect(base.sortImports).toMatchObject({ ignoreCase: true, order: 'asc' });
+    expect(base.sortPackageJson).toBeTruthy();
+    expect(base.sortTailwindcss).toStrictEqual({
+        functions: ['clsx', 'cn', 'cva', 'tv', 'twMerge', 'twJoin', 'tw'],
+    });
+});
+
 test("re-exports oxfmt's own defineConfig", () => {
     // Given - a config a consumer would write, with oxfmt declared nowhere in its project
     const config = { printWidth: 80 };

package/src/oxlint.d.ts

@@ -1,16 +1,63 @@
-type ConfigObject = Record<string, unknown>;
+/*
+ * The shape of a lint config is oxlint's own fact, so this entry does not
+ * restate it: `OxlintConfig` and `OxlintOverride` are re-exported from the
+ * tool, under the names a consumer already reads here. A hand copy drifts —
+ * this one had `plugins?: string[]` where oxlint takes a closed union, and a
+ * consumer's `defineConfig({ extends: [node] })` stopped type-checking.
+ */
+
+import { type OxlintConfig } from 'oxlint';
+
+/** A rule entry as oxlint reads it: a level, or a level and its options. */
+type RuleEntry = NonNullable<OxlintConfig['rules']>[string];
+
+/** One layer of a map: the files that belong to it, and what they may not import. */
+type Layer = {
+    allow?: string[];
+    deny: string[];
+    files: string[];
+    message: string;
+    name: string;
+};
 
-declare const expo: ConfigObject;
-declare const hexagonal: ConfigObject;
-declare const next: ConfigObject;
-declare const node: ConfigObject;
+declare const astro: OxlintConfig;
+declare const bun: OxlintConfig;
+declare const expo: OxlintConfig;
+declare const hexagonal: OxlintConfig;
+declare const library: OxlintConfig;
+declare const next: OxlintConfig;
+declare const node: OxlintConfig;
+
+/** The six boundaries the `hexagonal` fragment enforces, as a declared map. */
+declare const HEXAGONAL_MAP: readonly Layer[];
+
+/**
+ * Deterministic merge of oxlint config objects, left to right:
+ * jsPlugins/plugins/ignorePatterns/extends concatenated and deduped,
+ * rules/env/globals/options/settings shallow-merged (last wins),
+ * overrides concatenated.
+ */
+declare function compose(...configs: OxlintConfig[]): OxlintConfig;
 
 /**
- * Deterministic merge of oxlint config fragments, left to right:
- * jsPlugins/plugins/ignorePatterns/extends concatenated + deduped,
- * rules/categories shallow-merged (last wins), overrides concatenated.
+ * A declared layer map as an additive fragment: one `no-restricted-imports`
+ * override per layer, each carrying that layer's complete pattern list.
  */
-declare function compose(...fragments: ConfigObject[]): ConfigObject;
+declare function layers(definition: { id?: string; map: readonly Layer[] }): OxlintConfig;
 
 export { defineConfig } from 'oxlint';
-export { compose, expo, hexagonal, next, node };
+export { type OxlintConfig, type OxlintOverride } from 'oxlint';
+export {
+    astro,
+    bun,
+    compose,
+    expo,
+    hexagonal,
+    HEXAGONAL_MAP,
+    type Layer,
+    layers,
+    library,
+    next,
+    node,
+    type RuleEntry,
+};

package/src/oxlint.js

@@ -1,55 +1,24 @@
 /*
- * The tool-facing oxlint entry (`@jterrazz/typescript/oxlint`): the named
- * presets, the `compose()` helper, and oxlint's own `defineConfig`. Wiring is
- * EXPLICIT — a consumer composes exactly the fragments it wants, nothing is
- * auto-detected:
+ * The tool-facing oxlint entry (`@jterrazz/typescript/oxlint`): the six
+ * profiles, the `compose()` merger, the layer-map builder, and oxlint's own
+ * `defineConfig`. A consumer names a PROFILE, not a set of fragments:
  *
- *     import { testing } from '@jterrazz/test/oxlint';
- *     import { compose, node } from '@jterrazz/typescript/oxlint';
+ *     import { defineConfig, node } from '@jterrazz/typescript/oxlint';
  *
- *     export default compose(node, testing);
+ *     export default defineConfig({ extends: [node] });
+ *
+ * What each profile carries, and why every rule of every loaded plugin is
+ * decided by name, is [Lint presets](../docs/07-lint-presets.md).
+ *
+ * `rules/` holds the manifest — decisions, with a reason behind every `off`.
+ * What crosses this file is always a plain oxlint config, compiled from it.
  */
 
-/** Config keys concatenated across fragments, duplicates dropped (===). */
-const CONCAT_DEDUPE = new Set(['extends', 'ignorePatterns', 'jsPlugins', 'plugins']);
-/** Config keys concatenated verbatim (order matters, no dedupe). */
-const CONCAT = new Set(['overrides']);
-/** Config keys shallow-merged as objects — the LAST fragment wins per key. */
-const SHALLOW_MERGE = new Set(['categories', 'env', 'globals', 'rules', 'settings']);
+import hexagonalFragment from '../rules/architecture/hexagonal.js';
+import { layers as layersFragment } from '../rules/architecture/layers.js';
+import { compile } from '../rules/compile.js';
 
-/**
- * Deterministic merge of oxlint config fragments, left to right:
- * `jsPlugins` / `plugins` / `ignorePatterns` / `extends` are concatenated and
- * deduped, `rules` / `categories` (and env/globals/settings) are shallow-merged
- * with last-wins per key, `overrides` are concatenated, and any other key is
- * taken from the last fragment that sets it.
- */
-export function compose(...fragments) {
-    const merged = {};
-    for (const fragment of fragments) {
-        if (!fragment || typeof fragment !== 'object') {
-            continue;
-        }
-        for (const [key, value] of Object.entries(fragment)) {
-            if (value === undefined) {
-                continue;
-            }
-            if (CONCAT_DEDUPE.has(key)) {
-                const previous = Array.isArray(merged[key]) ? merged[key] : [];
-                const combined = [...previous, ...(Array.isArray(value) ? value : [value])];
-                merged[key] = combined.filter((entry, index) => combined.indexOf(entry) === index);
-            } else if (CONCAT.has(key)) {
-                const previous = Array.isArray(merged[key]) ? merged[key] : [];
-                merged[key] = [...previous, ...(Array.isArray(value) ? value : [value])];
-            } else if (SHALLOW_MERGE.has(key)) {
-                merged[key] = { ...merged[key], ...value };
-            } else {
-                merged[key] = value;
-            }
-        }
-    }
-    return merged;
-}
+export { merge as compose } from '../rules/compile.js';
 
 /* Oxlint's own `defineConfig`, re-exported from here: a bare
  * `import { defineConfig } from 'oxlint'` in a consumer's config resolves only
@@ -58,7 +27,23 @@ export function compose(...fragments) {
  * dependency — the one-devDependency shape holds on every package manager. */
 export { defineConfig } from 'oxlint';
 
-export { default as hexagonal } from '../presets/oxlint/architectures/hexagonal.js';
-export { default as expo } from '../presets/oxlint/expo.js';
-export { default as next } from '../presets/oxlint/next.js';
-export { default as node } from '../presets/oxlint/node.js';
+export { default as astro } from '../presets/oxlint/profiles/astro.js';
+export { default as bun } from '../presets/oxlint/profiles/bun.js';
+export { default as expo } from '../presets/oxlint/profiles/expo.js';
+export { default as library } from '../presets/oxlint/profiles/library.js';
+export { default as next } from '../presets/oxlint/profiles/next.js';
+export { default as node } from '../presets/oxlint/profiles/node.js';
+
+export { HEXAGONAL_MAP } from '../rules/architecture/hexagonal.js';
+
+/** The hexagonal layer map, ready to compose beside a profile. */
+export const hexagonal = compile(hexagonalFragment);
+
+/**
+ * A declared layer map as an additive oxlint fragment: one
+ * `no-restricted-imports` override per layer, each carrying that layer's
+ * complete pattern list (an oxlint override REPLACES, it never merges).
+ */
+export function layers(definition) {
+    return compile(layersFragment(definition));
+}