An open source design system that's fully customizable and agent ready
TypeScript
chore(cli): lint the CLI structure rules (#6617)
Joey665afc1a0cc9
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 820dbbf581..366ac19571 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -339,14 +339,19 @@ These are not free-form. `parseDoc` validates each at load, and a **drift harnesMost of the conventions above are mechanical, so they're checked rather than reviewed:-| Rule | Enforced by |-| ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |-| the layer directions hold: `authoring/` imports no other layer, `foundation/` never imports `api/` or `clients/`, `api/` never imports `clients/` | ESLint (`no-restricted-imports`) |-| zod stays sealed behind the `authoring/` parsers | ESLint (`no-restricted-imports`) |-| commands register via `defineCommand`, never straight onto Commander | ESLint (`no-restricted-syntax`) |-| each doc-type ships `type.ts` + `parse.mjs` + `<kind>.doc.mjs`, re-exports its parser, and appears in `parseDoc`'s `@returns` | `pnpm check:cli-structure` |-| each `api/<name>/` ships its typedefs, a `FunctionDoc`, and a test | `pnpm check:cli-structure` |-| every `CommandDoc`/`EnumDoc` matches the live CLI | the drift harness |+| Rule | Enforced by |+| ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |+| the layer directions hold: `authoring/` imports no other layer, `foundation/` never imports `api/` or `clients/`, `api/` never imports `clients/` | ESLint (`no-restricted-imports`) |+| zod stays sealed behind the `authoring/` parsers | ESLint (`no-restricted-imports`) |+| commands register via `defineCommand`, never straight onto Commander | ESLint (`no-restricted-syntax`) |+| a command handler must not access the environment: no filesystem, network, subprocess, Project, or discovery imports (INV22) | `pnpm check:cli-structure` |+| an API module (other than an adapter or helper imported only by adapters) must not access the environment (INV21) | `pnpm check:cli-structure` |+| a command handler must not build text with `.padEnd()`, `.padStart()`, `.repeat()`, or `new Block()` (INV23, FR3) | ESLint (`no-restricted-syntax`) + `pnpm check:cli-structure` |+| every executable `CommandDoc` `fn` must name a function exported from `api/index.mjs` (FR1) | `pnpm check:cli-structure` |+| every function exported from `api/index.mjs` must have a `FunctionDoc` whose `name` matches (FR2) | `pnpm check:cli-structure` |+| each doc-type ships `type.ts` + `parse.mjs` + `<kind>.doc.mjs`, re-exports its parser, and appears in `parseDoc`'s `@returns` | `pnpm check:cli-structure` |+| each `api/<name>/` ships its typedefs, a `FunctionDoc`, and a test | `pnpm check:cli-structure` |+| every `CommandDoc`/`EnumDoc` matches the live CLI | the drift harness |You never hand-write the `.d.mts` declarations. `packages/cli/scripts/sync-api-types.mjs` emits them for both `api/` and `authoring/` from the `.mjs` JSDoc — gitignored, regenerated at `prepack`, and stamped `@generated`. Edit the JSDoc and run `pnpm -F @astryxdesign/cli sync:api-types`.diff --git a/eslint.config.js b/eslint.config.jsindex 27e16a109a..64f3e88d0d 100644--- a/eslint.config.js+++ b/eslint.config.js@@ -729,6 +729,69 @@ export default defineConfig(],},},+ // ── INV23 + FR3: text-layout bans in command handlers ───────────────+ // Handlers must use the formatter kit (section, text, list, record,+ // records, code) rather than string padding or manual layout.+ // Extends the Commander-registration ban to the same file scope.+ {+ files: ['packages/cli/clients/cli/commands/**/*.mjs'],+ ignores: ['**/*.test.mjs', '**/*.doc.mjs'],+ rules: {+ 'no-restricted-syntax': [+ 'error',+ {+ selector:+ "CallExpression[callee.type='MemberExpression'][callee.property.name='command']",+ message:+ 'Register commands with defineCommand(parent, doc, {fn, action}) so --help and the manifest come from the colocated CommandDoc. See CONTRIBUTING > Working on the astryx CLI.',+ },+ {+ selector:+ "CallExpression[callee.property.name='padEnd']",+ message:+ 'Use the formatter kit — record(), records({layout: "inline"}), list() — not .padEnd() (INV23, FR3). See architecture:cli-surface.',+ },+ {+ selector:+ "CallExpression[callee.property.name='padStart']",+ message:+ 'Use the formatter kit — record(), records({layout: "inline"}), list() — not .padStart() (INV23, FR3). See architecture:cli-surface.',+ },+ {+ selector:+ "CallExpression[callee.property.name='repeat']",+ message:+ 'Use the formatter kit — section(), text(), code() — not .repeat() for layout (INV23, FR3). See architecture:cli-surface.',+ },+ {+ selector: "NewExpression[callee.name='Block']",+ message:+ 'Use the formatter kit constructors — section(), text(), list(), record(), records(), code() — not new Block() (INV23, FR3). See architecture:cli-surface.',+ },+ ],+ },+ },+ // Known gaps recorded in AST-042; remove an entry when the file is+ // fixed; do not add entries. check-cli-structure.mjs enforces the+ // exact-entry allowlist so a new text-layout violation in these files+ // still fails there.+ {+ files: [+ 'packages/cli/clients/cli/commands/build-theme.mjs',+ 'packages/cli/clients/cli/commands/docs.mjs',+ ],+ rules: {+ 'no-restricted-syntax': [+ 'error',+ {+ selector:+ "CallExpression[callee.type='MemberExpression'][callee.property.name='command']",+ message:+ 'Register commands with defineCommand(parent, doc, {fn, action}) so --help and the manifest come from the colocated CommandDoc. See CONTRIBUTING > Working on the astryx CLI.',+ },+ ],+ },+ },// CLI tests — relax author-ergonomics rules (test files emit freely and may// keep intentionally-unused fixtures). Must come after the CLI block above.{diff --git a/scripts/check-cli-structure.mjs b/scripts/check-cli-structure.mjsindex 3a3e12f37e..0e5ab3841f 100644--- a/scripts/check-cli-structure.mjs+++ b/scripts/check-cli-structure.mjs@@ -189,6 +189,440 @@ if (apiCount === 0) {);}+// ── 3. INV22 + INV21: environment imports ───────────────────────────+//+// Handlers (INV22) and non-adapter API modules (INV21) must not import+// filesystem, network, subprocess, Project, or discovery modules. Those+// belong in the API's _adapter.mjs and underscore-prefixed helpers imported+// only by that adapter.+//+// Each entry is an allowed set of ban categories for a file that predates+// these checks. An entry that becomes stale — the file no longer imports+// that category — MUST fail so the allowlist can only shrink.++/** Recursively collect .mjs files, excluding tests and docs.+ * @param {string} dir @returns {string[]} full paths */+function walkScopedMjs(dir) {+ /** @type {string[]} */+ const out = [];+ if (!fs.existsSync(dir)) return out;+ for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {+ const full = path.join(dir, entry.name);+ if (entry.isDirectory()) {+ out.push(...walkScopedMjs(full));+ } else if (+ entry.name.endsWith('.mjs') &&+ !entry.name.endsWith('.test.mjs') &&+ !entry.name.endsWith('.doc.mjs')+ ) {+ out.push(full);+ }+ }+ return out;+}++/**+ * Extract import/re-export module specifiers from a source file.+ * Catches both static (`import X from '…'`, `export {X} from '…'`) and+ * runtime dynamic (`await import('…')`) imports. JSDoc type-only imports+ * (`{import('…')}`) are excluded so they do not produce false positives.+ * @param {string} filePath+ * @returns {string[]}+ */+function importSources(filePath) {+ const src = fs.readFileSync(filePath, 'utf8');+ /** @type {string[]} */+ const out = [];+ // Static imports and re-exports+ for (const m of src.matchAll(/\bfrom\s+['"]([^'"]+)['"]/g)) {+ out.push(m[1]);+ }+ // Runtime dynamic imports — but not JSDoc type-only `{import('…')}`+ for (const m of src.matchAll(/(?<!\{)\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g)) {+ out.push(m[1]);+ }+ return out;+}++/**+ * Classify a module specifier into a ban category, or null if allowed.+ * @param {string} spec+ * @returns {'fs'|'child_process'|'net'|'project'|'discovery'|null}+ */+function banCategory(spec) {+ if (spec === 'node:fs' || spec === 'node:fs/promises') return 'fs';+ if (spec === 'node:child_process') return 'child_process';+ if (spec === 'node:net' || spec === 'node:http' || spec === 'node:https') return 'net';+ if (spec.includes('foundation/config/project')) return 'project';+ if (spec.includes('foundation/discovery/')) return 'discovery';+ return null;+}++/**+ * Scan files for banned environment imports and enforce the known-gap+ * allowlist. A new violation in an allowlisted file fails, and a stale+ * entry (the file no longer imports that category) also fails.+ *+ * @param {string} label invariant name for error messages+ * @param {string[]} files full paths to scan+ * @param {string} baseDir base for relative paths in the allowlist+ * @param {Map<string, Set<string>>} knownGaps relative-path → allowed categories+ * @returns {number} files checked+ */+function checkEnvironmentImports(label, files, baseDir, knownGaps) {+ let checked = 0;+ for (const filePath of files) {+ checked++;+ const rel = path.relative(baseDir, filePath);+ const sources = importSources(filePath);+ /** @type {Set<string>} */+ const found = new Set();+ for (const s of sources) {+ const cat = banCategory(s);+ if (cat) found.add(cat);+ }++ const allowed = knownGaps.get(rel);+ if (allowed) {+ for (const cat of found) {+ if (!allowed.has(cat)) {+ errors.push(+ `${label}: ${rel} has a new environment import (${cat}) not in the known-gap allowlist`,+ );+ }+ }+ for (const cat of allowed) {+ if (!found.has(cat)) {+ errors.push(+ `${label}: ${rel} no longer imports ${cat} — remove it from the ${label} allowlist so the list can only shrink`,+ );+ }+ }+ } else if (found.size > 0) {+ errors.push(+ `${label}: ${rel} imports ${[...found].join(', ')} — environment access belongs in the adapter (architecture:cli-surface)`,+ );+ }+ }+ return checked;+}++// --- INV22: command handlers ---+const HANDLER_DIR = path.join(CLI, 'clients/cli/commands');+/** @type {Map<string, Set<string>>} known gaps recorded in AST-042;+ * remove an entry when the file is fixed; do not add entries */+const INV22_KNOWN_GAPS = new Map([+ ['build-theme.mjs', new Set(['fs', 'child_process', 'project'])],+ ['component/index.mjs', new Set(['project', 'discovery'])],+ ['discover.mjs', new Set(['project'])],+ ['ensure-core-built.mjs', new Set(['fs', 'child_process'])],+ ['hook/index.mjs', new Set(['discovery'])],+ // remove with the layout command+ ['layout.mjs', new Set(['fs'])],+ ['search.mjs', new Set(['project'])],+ ['template.mjs', new Set(['fs', 'project'])],+]);+const handlerFiles = walkScopedMjs(HANDLER_DIR);+const inv22Count = checkEnvironmentImports(+ 'INV22', handlerFiles, HANDLER_DIR, INV22_KNOWN_GAPS,+);++// --- INV21: API non-adapter modules ---+//+// INV21 says environment access happens in "the subject's adapter:+// `_adapter.mjs` and any underscore-prefixed helper that only it imports."+// The exemption is computed from the import graph: a `_*.mjs` file is exempt+// when every file that runtime-imports it is itself exempt (adapters, or+// helpers that only adapters import). A helper imported by a leaf is not+// exempt and must appear in the allowlist.++/** Collect all non-test, non-doc .mjs files under a directory.+ * @param {string} dir @returns {string[]} */+function allMjsFiles(dir) {+ /** @type {string[]} */+ const out = [];+ if (!fs.existsSync(dir)) return out;+ for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {+ const full = path.join(dir, entry.name);+ if (entry.isDirectory()) out.push(...allMjsFiles(full));+ else if (entry.name.endsWith('.mjs') && !entry.name.endsWith('.test.mjs') && !entry.name.endsWith('.doc.mjs')) {+ out.push(full);+ }+ }+ return out;+}++/**+ * Compute the set of underscore-prefixed API files that are exempt per INV21:+ * adapters plus helpers whose every runtime importer is itself exempt.+ * @returns {Set<string>} full paths of exempt files+ */+function computeAdapterExemptions() {+ const allApiFiles = allMjsFiles(API);++ // Identify all underscore-prefixed files under api/+ /** @type {Set<string>} */+ const underscoreFiles = new Set();+ for (const f of allApiFiles) {+ if (path.basename(f).startsWith('_')) underscoreFiles.add(f);+ }++ // Build reverse import graph: for each underscore file, who imports it?+ // Only consider runtime imports within packages/cli (non-test, non-doc).+ const allCliFiles = allMjsFiles(CLI);+ /** @type {Map<string, Set<string>>} target → set of importers */+ const importedBy = new Map();+ for (const uf of underscoreFiles) importedBy.set(uf, new Set());++ for (const srcFile of allCliFiles) {+ const sources = importSources(srcFile);+ const srcDir = path.dirname(srcFile);+ for (const spec of sources) {+ if (!spec.startsWith('.')) continue;+ const resolved = path.resolve(srcDir, spec);+ // The spec might omit the extension or resolve to a directory index;+ // since underscore files are always spelled with `.mjs`, a direct+ // resolve is enough.+ if (underscoreFiles.has(resolved) && resolved !== srcFile) {+ importedBy.get(resolved)?.add(srcFile);+ }+ }+ }++ // Seed: _adapter.mjs files are unconditionally exempt.+ /** @type {Set<string>} */+ const exempt = new Set();+ for (const uf of underscoreFiles) {+ if (path.basename(uf) === '_adapter.mjs') exempt.add(uf);+ }++ // Fixed-point: a helper is exempt if every importer is exempt.+ let changed = true;+ while (changed) {+ changed = false;+ for (const uf of underscoreFiles) {+ if (exempt.has(uf)) continue;+ const importers = importedBy.get(uf);+ if (!importers || importers.size === 0) continue;+ let allExempt = true;+ for (const imp of importers) {+ if (!exempt.has(imp)) { allExempt = false; break; }+ }+ if (allExempt) {+ exempt.add(uf);+ changed = true;+ }+ }+ }++ return exempt;+}++const adapterExemptions = computeAdapterExemptions();++/** @param {string} filePath @returns {boolean} */+function isApiExempt(filePath) {+ if (adapterExemptions.has(filePath)) return true;+ const bn = path.basename(filePath);+ if (bn.endsWith('.type.mjs')) return true;+ const rel = path.relative(API, filePath);+ return rel === 'index.mjs' || rel === 'error.mjs' || rel === 'logger.mjs';+}++const apiScopedFiles = walkScopedMjs(API).filter(f => !isApiExempt(f));++/** @type {Map<string, Set<string>>} known gaps recorded in AST-042;+ * remove an entry when the file is fixed; do not add entries */+const INV21_KNOWN_GAPS = new Map([+ ['component/detail/showcase/showcase.mjs', new Set(['fs'])],+ ['component/detail/source/source.mjs', new Set(['fs'])],+ ['component/list/list.mjs', new Set(['discovery'])],+ ['docs/detail/section/section.mjs', new Set(['discovery'])],+ ['doctor/doctor.mjs', new Set(['fs', 'project', 'discovery'])],+ ['gap-report/gap-report.mjs', new Set(['child_process', 'discovery', 'project'])],+ ['hook/list/list.mjs', new Set(['discovery'])],+ ['init/run/run.mjs', new Set(['fs'])],+ ['integration/add-contribution.mjs', new Set(['discovery', 'fs'])],+ ['integration/add-helpers.mjs', new Set(['fs'])],+ ['integration/add-theme.mjs', new Set(['fs', 'discovery'])],+ ['integration/authoring-checks.mjs', new Set(['discovery'])],+ ['integration/pack-check.mjs', new Set(['fs', 'child_process', 'discovery'])],+ ['integration/validate-integration.mjs', new Set(['fs', 'discovery'])],+ // remove with the layout command+ ['layout/expand/expand.mjs', new Set(['fs'])],+ ['search/search.mjs', new Set(['discovery'])],+ // imported by a leaf (copy), not only by the adapter+ ['swizzle/_github.mjs', new Set(['child_process'])],+ ['swizzle/copy/copy.mjs', new Set(['fs', 'project', 'discovery'])],+ ['template/cdn/cdn.mjs', new Set(['fs'])],+ ['template/copy/copy.mjs', new Set(['fs', 'discovery'])],+ ['template/list/list.mjs', new Set(['discovery'])],+ ['template/show/show.mjs', new Set(['fs', 'discovery'])],+ ['template/skeleton/skeleton.mjs', new Set(['fs', 'discovery'])],+ ['template/template.mjs', new Set(['discovery'])],+ ['theme/add/add.mjs', new Set(['fs'])],+ ['theme/build/build.mjs', new Set(['fs', 'discovery'])],+ ['theme/palette/generate/generate.mjs', new Set(['fs'])],+ ['theme/targets/targets.mjs', new Set(['discovery'])],+ ['theme/template/template.mjs', new Set(['fs'])],+ ['upgrade/registry/registry.mjs', new Set(['fs'])],+ ['upgrade/run/run.mjs', new Set(['fs'])],+]);+const inv21Count = checkEnvironmentImports(+ 'INV21', apiScopedFiles, API, INV21_KNOWN_GAPS,+);++// ── 3b. INV23: text-layout patterns ─────────────────────────────────+//+// Handlers must use the formatter kit (section, text, list, record,+// records, code) rather than .padEnd(), .padStart(), .repeat(), or+// new Block() to build text columns.++/** @type {{re: RegExp, kind: string}[]} */+const TEXT_LAYOUT_PATTERNS = [+ {re: /\.padEnd\s*\(/g, kind: 'padEnd'},+ {re: /\.padStart\s*\(/g, kind: 'padStart'},+ {re: /\.repeat\s*\(/g, kind: 'repeat'},+ {re: /new\s+Block\s*\(/g, kind: 'new Block'},+];++/** @type {Map<string, Set<string>>} known gaps recorded in AST-042;+ * remove an entry when the file is fixed; do not add entries */+const INV23_KNOWN_GAPS = new Map([+ ['docs.mjs', new Set(['padEnd', 'repeat'])],+]);++let inv23Count = 0;+for (const filePath of handlerFiles) {+ inv23Count++;+ const rel = path.relative(HANDLER_DIR, filePath);+ const src = fs.readFileSync(filePath, 'utf8');+ /** @type {Set<string>} */+ const found = new Set();+ for (const {re, kind} of TEXT_LAYOUT_PATTERNS) {+ re.lastIndex = 0;+ if (re.test(src)) found.add(kind);+ }++ const allowed = INV23_KNOWN_GAPS.get(rel);+ if (allowed) {+ for (const kind of found) {+ if (!allowed.has(kind)) {+ errors.push(+ `INV23: ${rel} has a new text-layout call (${kind}) not in the known-gap allowlist`,+ );+ }+ }+ for (const kind of allowed) {+ if (!found.has(kind)) {+ errors.push(+ `INV23: ${rel} no longer uses ${kind} — remove it from the INV23 allowlist so the list can only shrink`,+ );+ }+ }+ } else if (found.size > 0) {+ errors.push(+ `INV23: ${rel} uses ${[...found].join(', ')} — use the formatter kit: section(), text(), list(), record(), records(), code()`,+ );+ }+}++// ── 4. FR1: CommandDoc fn → api/index.mjs export ────────────────────+//+// Every executable command's CommandDoc names in `fn` the API function it+// calls. That function must be exported from api/index.mjs, the public+// programmatic surface.++const apiIndexSrc = fs.readFileSync(path.join(API, 'index.mjs'), 'utf8');++/** Extract named function exports from api/index.mjs (skip type re-exports). */+const apiExports = new Set();+for (const m of apiIndexSrc.matchAll(/export\s*\{([^}]+)\}\s*from\s*['"]([^'"]+)['"]/g)) {+ if (m[2].endsWith('.type.mjs')) continue;+ for (const part of m[1].split(',')) {+ const trimmed = part.trim();+ // 'x as y' → exported name is y; 'x' → x+ const segments = trimmed.split(/\s+/);+ const name = segments[segments.length - 1];+ if (name && /^\w+$/.test(name)) apiExports.add(name);+ }+}++/** @type {Set<string>} known FR1 gaps: fn values not yet exported.+ * Remove an entry when the function is exported; do not add entries. */+const FR1_KNOWN_GAPS = new Set(['themeTemplate']);++let fr1Count = 0;++/** Walk CommandDoc files and check fn values.+ * @param {string} dir */+function checkCommandDocFn(dir) {+ for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {+ const full = path.join(dir, entry.name);+ if (entry.isDirectory()) {+ checkCommandDocFn(full);+ continue;+ }+ if (!entry.name.endsWith('.doc.mjs')) continue;+ const src = fs.readFileSync(full, 'utf8');+ const fnMatch = src.match(/fn:\s*['"](\w+)['"]/);+ if (!fnMatch) continue; // group-only CommandDoc (no fn field)+ fr1Count++;+ const fn = fnMatch[1];+ if (!apiExports.has(fn) && !FR1_KNOWN_GAPS.has(fn)) {+ errors.push(+ `FR1: CommandDoc ${path.relative(CLI, full)} names fn '${fn}' which is not exported from api/index.mjs`,+ );+ }+ }+}+checkCommandDocFn(path.join(CLI, 'clients/cli/commands'));++// Stale FR1 entries+for (const fn of FR1_KNOWN_GAPS) {+ if (apiExports.has(fn)) {+ errors.push(+ `FR1: '${fn}' is now exported from api/index.mjs — remove it from FR1_KNOWN_GAPS so the list can only shrink`,+ );+ }+}++// ── 5. FR2: api/index.mjs export → FunctionDoc ─────────────────────+//+// Every function exported from the public API must have a FunctionDoc+// under api/ whose `name` field matches.++const FR2_EXEMPT = new Set(['AstryxError', 'logger']);++/** Collect `name` values from all FunctionDoc files under api/. */+const docNames = new Set();+/** @param {string} dir */+function collectDocNames(dir) {+ for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {+ const full = path.join(dir, entry.name);+ if (entry.isDirectory()) {+ collectDocNames(full);+ continue;+ }+ if (!entry.name.endsWith('.doc.mjs')) continue;+ const src = fs.readFileSync(full, 'utf8');+ const nameMatch = src.match(/name:\s*['"](\w+)['"]/);+ if (nameMatch) docNames.add(nameMatch[1]);+ }+}+collectDocNames(API);++let fr2Count = 0;+for (const name of apiExports) {+ if (FR2_EXEMPT.has(name)) continue;+ fr2Count++;+ if (!docNames.has(name)) {+ errors.push(+ `FR2: api/index.mjs exports '${name}' but no FunctionDoc under api/ has name: '${name}'`,+ );+ }+}+if (errors.length > 0) {console.error('❌ CLI structure violations:\n');for (const e of errors) console.error(` ${e}`);@@ -199,5 +633,11 @@ if (errors.length > 0) {}console.log(- `✅ ${doctypeCount} doc-type(s) + ${apiCount} api folder(s) checked — CLI structure is intact.`,+ [+ `✅ CLI structure is intact:`,+ ` ${doctypeCount} doc-type(s), ${apiCount} api folder(s),`,+ ` ${inv22Count} handler(s) checked for INV22, ${inv21Count} api module(s) for INV21,`,+ ` ${inv23Count} handler(s) checked for INV23,`,+ ` ${fr1Count} CommandDoc fn(s) checked for FR1, ${fr2Count} api export(s) for FR2.`,+ ].join('\n'),);