An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file The public type surface of `@astryxdesign/cli/authoring`, and whether
* a reader of `astryx docs authoring` can reach the doc for each type in it.
*
* @input authoring/index.d.ts and the type modules it re-exports, parsed with
* jscodeshift and never imported or type-checked (consumer installs have no
* TypeScript); the self-docs on disk and in AUTHORING_SELF_DOCS; and the
* section keys `astryx docs authoring/field-reference --index` lists.
* @output {@link tracePublicAuthoringTypes}: each exported type and the module
* that declares it. {@link auditAuthoringSurface}: each module whose exported
* types a reader cannot reach and why, each export that cannot be traced,
* and each registered self-doc that documents nothing the surface exports.
* @position Read by Doctor's authoring-docs check. A type's doc is the self-doc
* beside the module that declares it, so a new public type needs a
* `*.doc.mjs` in its folder, listed in AUTHORING_SELF_DOCS. The barrel's
* parsers read those types and are not a shape anyone writes, so they need
* no section of their own.
*/
import * as fs from 'node:fs';
import * as path from 'node:path';
import jscodeshift from 'jscodeshift';
import {
AUTHORING_ROOT,
AUTHORING_SELF_DOCS,
isExperimentalSelfDoc,
selfDocSection,
discoverAuthoringSelfDocSources,
loadAuthoringSelfDocs,
} from './authoring-self-docs.mjs';
import {sectionKey} from './docs-section-key.mjs';
const j = jscodeshift.withParser('ts');
/** The barrel the `types` condition of `@astryxdesign/cli/authoring` names. */
export const AUTHORING_SURFACE = 'index.d.ts';
/** Modules read by parsing. Anything else is runtime JavaScript. */
const TYPE_MODULE_RE = /\.(?:ts|tsx|mts|cts)$/u;
/** A title only a declaration of that name can match. */
const IDENTIFIER_RE = /^[A-Za-z_$][\w$]*$/u;
/**
* @typedef {object} Tracer
* @property {string} root
* @property {Map<string, any[]>} parsed top-level statements by absolute path
*/
/**
* @typedef {'no-self-doc' | 'unregistered' | 'failed' | 'missing-section'} UnreadableReason
*/
/**
* @param {string} root
* @param {string} file
* @returns {string} `file` relative to `root`, with `/` separators
*/
function relative(root, file) {
return path.relative(root, file).split(path.sep).join('/');
}
/**
* @param {string} source a `/`-separated path relative to the root
* @returns {string}
*/
function folderOf(source) {
return path.posix.dirname(source);
}
/** @param {any} node @returns {string | undefined} */
function nameOf(node) {
return node?.name ?? node?.value;
}
/**
* Names a top-level statement declares, exported or not.
* @param {any} node
* @returns {string[]}
*/
function declaredNames(node) {
if (node?.type === 'VariableDeclaration') {
return node.declarations.flatMap((/** @type {any} */ d) =>
d.id?.type === 'Identifier' ? [d.id.name] : [],
);
}
return node?.id?.type === 'Identifier' ? [node.id.name] : [];
}
/**
* @param {Tracer} t
* @param {string} file
* @returns {any[]}
*/
function statementsOf(t, file) {
let body = t.parsed.get(file);
if (!body) {
try {
body = j(fs.readFileSync(file, 'utf8')).get().node.program.body;
} catch (error) {
throw new Error(
`${relative(t.root, file)} could not be parsed: ${error instanceof Error ? error.message : String(error)}`,
{cause: error},
);
}
t.parsed.set(/** @type {string} */ (file), /** @type {any[]} */ (body));
}
return /** @type {any[]} */ (body);
}
/**
* The file a relative specifier names, resolved as TypeScript resolves an ESM
* import in a type module: `./x.js` is `./x.ts` when that exists.
* @param {Tracer} t
* @param {string} from absolute path of the importing module
* @param {string} specifier
* @returns {string} absolute path
* @throws {Error} for a bare specifier, one that leaves the root, or one that
* names no file
*/
function resolveModule(t, from, specifier) {
const base = path.resolve(path.dirname(from), specifier);
const inside = relative(t.root, base);
const candidates = !specifier.startsWith('.')
? []
: inside === '..' || inside.startsWith('../') || path.isAbsolute(inside)
? []
: /\.js$/u.test(base)
? [base.replace(/\.js$/u, '.ts'), base.replace(/\.js$/u, '.d.ts'), base]
: /\.[cm]js$/u.test(base) || TYPE_MODULE_RE.test(base)
? [base]
: [
`${base}.ts`,
`${base}.d.ts`,
path.join(base, 'index.ts'),
path.join(base, 'index.d.ts'),
];
const found = candidates.find(file => {
try {
return fs.statSync(file).isFile();
} catch {
return false;
}
});
if (found == null) {
throw new Error(
`${relative(t.root, from)} names "${specifier}", which is not a file in ${path.basename(t.root)}/`,
);
}
return found;
}
/**
* The module that declares what `file` exports as `name`, following
* re-exports. A JavaScript module declares what it exports (its JSDoc
* typedefs included), so a trace stops there.
* @param {Tracer} t
* @param {string} file
* @param {string} name
* @param {Set<string>} [seen] `file\0name` pairs already on this trace
* @returns {string | null} absolute path, or null when `file` does not export
* `name`
*/
function declaringModule(t, file, name, seen = new Set()) {
if (!TYPE_MODULE_RE.test(file)) return file;
const visit = `${file}\u0000${name}`;
if (seen.has(visit)) return null;
seen.add(visit);
const body = statementsOf(t, file);
for (const statement of body) {
if (
statement.type === 'ExportNamedDeclaration' &&
declaredNames(statement.declaration).includes(name)
) {
return file;
}
}
for (const statement of body) {
if (statement.type !== 'ExportNamedDeclaration' || statement.declaration)
continue;
for (const specifier of statement.specifiers ?? []) {
if (nameOf(specifier.exported) !== name) continue;
const source = statement.source?.value;
if (specifier.type === 'ExportNamespaceSpecifier') {
return resolveModule(t, file, source);
}
const local = nameOf(specifier.local) ?? name;
const found =
source == null
? localBinding(t, file, body, local, seen)
: declaringModule(t, resolveModule(t, file, source), local, seen);
if (found == null) {
throw new Error(
`${relative(t.root, file)} exports ${name}${source == null ? '' : ` from "${source}"`}, which does not declare it`,
);
}
return found;
}
}
for (const statement of body) {
if (statement.type !== 'ExportAllDeclaration') continue;
const from = resolveModule(t, file, statement.source.value);
if (statement.exported != null) {
if (nameOf(statement.exported) === name) return from;
continue;
}
// What a JavaScript module exports cannot be listed by parsing, so a star
// through one never answers for a type.
if (!TYPE_MODULE_RE.test(from)) continue;
const found = declaringModule(t, from, name, seen);
if (found != null) return found;
}
return null;
}
/**
* The module that declares a binding local to `file`: `file` itself, or the
* one its import of that name traces to.
* @param {Tracer} t
* @param {string} file
* @param {any[]} body
* @param {string} local
* @param {Set<string>} seen
* @returns {string | null}
*/
function localBinding(t, file, body, local, seen) {
for (const statement of body) {
const declared =
statement.type === 'ExportNamedDeclaration'
? statement.declaration
: statement;
if (declaredNames(declared).includes(local)) return file;
if (statement.type !== 'ImportDeclaration') continue;
for (const specifier of statement.specifiers ?? []) {
if (nameOf(specifier.local) !== local) continue;
const from = resolveModule(t, file, statement.source.value);
if (specifier.type === 'ImportNamespaceSpecifier') return from;
const imported =
specifier.type === 'ImportDefaultSpecifier'
? 'default'
: (nameOf(specifier.imported) ?? local);
return declaringModule(t, from, imported, seen);
}
}
return null;
}
/**
* Every name a type module exports, stars included.
* @param {Tracer} t
* @param {string} file
* @param {Set<string>} [seen]
* @returns {string[]}
* @throws {Error} when a star passes through a JavaScript module, whose types
* cannot be listed by parsing
*/
function exportedNames(t, file, seen = new Set()) {
/** @type {Set<string>} */
const names = new Set();
if (seen.has(file)) return [];
seen.add(file);
for (const statement of statementsOf(t, file)) {
if (statement.type === 'ExportNamedDeclaration') {
for (const name of declaredNames(statement.declaration)) names.add(name);
for (const specifier of statement.specifiers ?? []) {
const name = nameOf(specifier.exported);
if (name != null) names.add(name);
}
} else if (statement.type === 'ExportAllDeclaration') {
const from = resolveModule(t, file, statement.source.value);
if (statement.exported != null) {
const name = nameOf(statement.exported);
if (name != null) names.add(name);
} else if (TYPE_MODULE_RE.test(from)) {
for (const name of exportedNames(t, from, seen)) {
if (name !== 'default') names.add(name);
}
} else {
throw new Error(
`${relative(t.root, file)} re-exports every type of "${statement.source.value}", a JavaScript module whose types cannot be listed`,
);
}
}
}
return [...names];
}
/**
* Every type `@astryxdesign/cli/authoring` exports, in the order index.d.ts
* lists them, each traced to the module that declares it. A value export that
* traces to a JavaScript module (a parser) is not a type and is left out;
* anything else that cannot be traced is reported, never dropped.
* @param {string} [root]
* @returns {{
* types: {name: string, module: string}[],
* untraced: {name: string, reason: string}[],
* }} `module` is relative to `root`
*/
export function tracePublicAuthoringTypes(root = AUTHORING_ROOT) {
return traceSurface({root, parsed: new Map()});
}
/**
* @param {Tracer} t
* @returns {ReturnType<typeof tracePublicAuthoringTypes>}
*/
function traceSurface(t) {
const surface = path.join(t.root, AUTHORING_SURFACE);
/** @type {{name: string, module: string}[]} */
const types = [];
/** @type {{name: string, reason: string}[]} */
const untraced = [];
/**
* @param {string} name
* @param {() => string | null} trace
* @param {boolean} typeOnly exported with `export type`
*/
const add = (name, trace, typeOnly) => {
let module;
try {
module = trace();
} catch (error) {
untraced.push({
name,
reason: error instanceof Error ? error.message : String(error),
});
return;
}
if (module == null) {
untraced.push({
name,
reason: `${AUTHORING_SURFACE} exports it, but no module declares it`,
});
} else if (typeOnly || TYPE_MODULE_RE.test(module)) {
types.push({name, module: relative(t.root, module)});
}
};
for (const statement of statementsOf(t, surface)) {
const typeOnly = statement.exportKind === 'type';
if (statement.type === 'ExportNamedDeclaration') {
for (const name of declaredNames(statement.declaration)) {
add(name, () => surface, true);
}
for (const specifier of statement.specifiers ?? []) {
const name = nameOf(specifier.exported) ?? '(unnamed)';
add(
name,
() => declaringModule(t, surface, name),
typeOnly || specifier.exportKind === 'type',
);
}
} else if (statement.type === 'ExportAllDeclaration') {
const source = statement.source.value;
if (statement.exported != null) {
const name = nameOf(statement.exported) ?? '(unnamed)';
add(name, () => resolveModule(t, surface, source), typeOnly);
continue;
}
let names;
try {
const from = resolveModule(t, surface, source);
if (!TYPE_MODULE_RE.test(from)) {
throw new Error(
`${AUTHORING_SURFACE} re-exports everything "${source}" exports, and what a JavaScript module exports cannot be listed`,
);
}
names = exportedNames(t, from);
} catch (error) {
untraced.push({
name: `* from "${source}"`,
reason: error instanceof Error ? error.message : String(error),
});
continue;
}
for (const name of names) {
if (name === 'default') continue;
add(name, () => declaringModule(t, surface, name), typeOnly);
}
}
}
return {types, untraced};
}
/**
* Whether an authored type module in `folder` (relative to the root) declares
* `name`. Declaration files are skipped: beside a self-doc they are generated
* from the JavaScript next to them, declare no authored type, and use syntax
* the parser reads only in declaration mode.
* @param {Tracer} t
* @param {string} folder
* @param {string} name
* @returns {boolean}
*/
function declaredIn(t, folder, name) {
const dir = path.join(t.root, folder);
let entries;
try {
entries = fs.readdirSync(dir, {withFileTypes: true});
} catch {
return false;
}
return entries.some(
entry =>
entry.isFile() &&
TYPE_MODULE_RE.test(entry.name) &&
!/\.d\.[cm]?ts$|\.test\.[cm]?tsx?$/u.test(entry.name) &&
statementsOf(t, path.join(dir, entry.name)).some(statement =>
declaredNames(
statement.type === 'ExportNamedDeclaration'
? statement.declaration
: statement,
).includes(name),
),
);
}
/**
* What stands between each type `@astryxdesign/cli/authoring` exports and a
* reader of `astryx docs authoring`. A type is readable when a self-doc beside
* the module that declares it is listed in AUTHORING_SELF_DOCS, loads, and
* renders a section the topic's index lists. A registered self-doc must
* document something public: a public type declared beside it, and, when its
* title is the name of a type declared beside it, that type.
* @param {{root?: string, sources?: string[], topicKeys?: Set<string> | null}} [options]
* `topicKeys` are the keys `astryx docs authoring/field-reference --index` lists; null skips
* that comparison.
* @returns {Promise<{
* types: number,
* unreadable: {module: string, names: string[], reason: UnreadableReason, source?: string, key?: string}[],
* untraced: {name: string, reason: string}[],
* unmatched: {source: string, key?: string, subject?: string}[],
* }>}
*/
export async function auditAuthoringSurface({
root = AUTHORING_ROOT,
sources = AUTHORING_SELF_DOCS,
topicKeys = null,
} = {}) {
/** @type {Tracer} */
const t = {root, parsed: new Map()};
const {types, untraced} = traceSurface(t);
/** @type {Map<string, string[]>} folder -> self-docs on disk in it */
const beside = new Map();
for (const source of discoverAuthoringSelfDocSources(root)) {
const folder = folderOf(source);
beside.set(folder, [...(beside.get(folder) ?? []), source]);
}
const registered = new Set(sources);
const {loaded, failed} = await loadAuthoringSelfDocs(sources, root);
const failedSources = new Set(failed.map(entry => entry.source));
/** @type {Map<string, string>} */
const keyOf = new Map(
loaded.map(entry => [entry.source, sectionKey(selfDocSection(entry.doc))]),
);
// An experimental self-doc is a section of the experimental route, never
// of `astryx docs authoring`, so the topic index is not asked for it.
const experimental = new Set(
loaded
.filter(entry => isExperimentalSelfDoc(entry.doc))
.map(entry => entry.source),
);
/**
* @param {string} source
* @returns {UnreadableReason | null}
*/
const blocked = source => {
if (!registered.has(source)) return 'unregistered';
if (failedSources.has(source) || !keyOf.has(source)) return 'failed';
const key = /** @type {string} */ (keyOf.get(source));
return topicKeys != null && !experimental.has(source) && !topicKeys.has(key)
? 'missing-section'
: null;
};
/** @type {Map<string, string[]>} declaring module -> its public types */
const byModule = new Map();
for (const {name, module} of types) {
byModule.set(module, [...(byModule.get(module) ?? []), name]);
}
/** @type {{module: string, names: string[], reason: UnreadableReason, source?: string, key?: string}[]} */
const unreadable = [];
for (const [module, names] of byModule) {
const docs = beside.get(folderOf(module)) ?? [];
if (docs.length === 0) {
unreadable.push({module, names, reason: 'no-self-doc'});
continue;
}
const reasons = docs.map(blocked);
if (reasons.includes(null)) continue;
const source = docs[0];
const key = keyOf.get(source);
unreadable.push({
module,
names,
reason: /** @type {UnreadableReason} */ (reasons[0]),
source,
...(key != null ? {key} : {}),
});
}
const publicFolders = new Set(types.map(({module}) => folderOf(module)));
const publicNames = new Set(types.map(({name}) => name));
/** @type {Map<string, any>} */
const docOf = new Map(loaded.map(entry => [entry.source, entry.doc]));
/** @type {{source: string, key?: string, subject?: string}[]} */
const unmatched = [];
for (const source of sources) {
const key = keyOf.get(source);
const keyed = key != null ? {key} : {};
const folder = folderOf(source);
if (!publicFolders.has(folder)) {
unmatched.push({source, ...keyed});
continue;
}
const subject = docOf.get(source)?.displayName;
if (
typeof subject === 'string' &&
IDENTIFIER_RE.test(subject) &&
!publicNames.has(subject) &&
declaredIn(t, folder, subject)
) {
unmatched.push({source, ...keyed, subject});
}
}
return {types: types.length, unreadable, untraced, unmatched};
}