@starci/hfs 4.0.10 → 4.1.0

package/runtime/scripts/hfs/architecture/frontend-grammar.mjs

@@ -0,0 +1,190 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { canonical, isInside } from './config.mjs';
+import { readJsonFile as readJson } from '../../lib/json.mjs';
+import { exportTargetStrings, isUnshadowedCommonJsRequire, relativePath } from './typescript.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
+import { sameOrUnder } from '../../lib/path-key.mjs';
+
+function grammarExport(manifest, packageName, specifier) {
+  const key = specifier === packageName ? '.' : `.${specifier.slice(packageName.length)}`;
+  const value = manifest?.exports?.[key];
+  const targets = exportTargetStrings(value);
+  return targets.length > 0 && targets.every(target => target.startsWith('./') && !target.includes('\\') && !target.split('/').includes('..'));
+}
+
+function grammarExportTargets(manifest, packageRoot, packageName, specifier) {
+  const key = specifier === packageName ? '.' : `.${specifier.slice(packageName.length)}`;
+  return exportTargetStrings(manifest?.exports?.[key]).filter(target => target.startsWith('./') && !target.includes('\\') && !target.split('/').includes('..'))
+    .map(target => canonical(path.resolve(packageRoot, target)));
+}
+
+function literalModules(ts, sourceFile, checker) {
+  const modules = [];
+  const visit = node => {
+    if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteralLike(node.moduleSpecifier)) {
+      modules.push({ node: node.moduleSpecifier, specifier: node.moduleSpecifier.text });
+    } else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference)
+      && node.moduleReference.expression && ts.isStringLiteralLike(node.moduleReference.expression)) {
+      modules.push({ node: node.moduleReference.expression, specifier: node.moduleReference.expression.text });
+    } else if (ts.isCallExpression(node) && node.arguments.length > 0 && ts.isStringLiteralLike(node.arguments[0])
+      && (node.expression.kind === ts.SyntaxKind.ImportKeyword || isUnshadowedCommonJsRequire(ts, checker, node.expression))) {
+      modules.push({ node: node.arguments[0], specifier: node.arguments[0].text });
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return modules;
+}
+
+function cssImports(content) {
+  const imports = [];
+  const withoutComments = content.replace(/\/\*[\s\S]*?\*\//g, match => match.replace(/[^\r\n]/g, ' '));
+  const pattern = new RegExp([String.raw`@import\s+(?:url\(\s*(?:(["'])`, String.raw`(.*?)\1|([^\s)]+))\s*\)|(["'])(.*?)\4)`].join(''), 'gi');
+  for (const match of withoutComments.matchAll(pattern)) {
+    imports.push({ specifier: match[2] ?? match[3] ?? match[5], index: match.index });
+  }
+  return imports;
+}
+
+function installRootFor(config) {
+  return config.packageRoot ?? config.root;
+}
+
+function installedPackageRoot(installRoot, packageName, from) {
+  for (let dir = from; isInside(installRoot, dir); dir = path.dirname(dir)) {
+    const candidate = path.join(dir, 'node_modules', ...packageName.split('/'));
+    if (fs.existsSync(path.join(candidate, 'package.json'))) return candidate;
+    if (dir === installRoot || path.dirname(dir) === dir) break;
+  }
+  return path.join(installRoot, 'node_modules', ...packageName.split('/'));
+}
+
+function grammarConsumers(config, grammar, local, installRoot) {
+  return grammar.consumerManifests.map(relative => {
+    const root = path.dirname(path.join(config.root, ...relative.split('/')));
+    const packageRoot = local?.root ?? installedPackageRoot(installRoot, grammar.package, root);
+    return { relative, root, packageRoot, packageManifest: readJson(path.join(packageRoot, 'package.json')),
+      manifest: readJson(path.join(config.root, ...relative.split('/'))) ?? {} };
+  });
+}
+
+function uniqueGrammarInstalls(consumers) {
+  return [...new Map(consumers.map(consumer => [consumer.packageRoot, consumer])).values()];
+}
+
+function grammarPackageRoot(installs, local, installRoot, packageName) {
+  return installs[0]?.packageRoot ?? local?.root ?? path.join(installRoot, 'node_modules', ...packageName.split('/'));
+}
+
+function addInstallContractProblems(install, installs, grammar, configRoot, problems) {
+  const where = installs.length > 1 ? ` (as ${install.relative} resolves it, ${relativePath(configRoot, install.packageRoot)})` : '';
+  if (install.packageManifest?.name !== grammar.package) problems.push(`installed package ${grammar.package} is unavailable or has a different name${where}`);
+  if (!grammarExport(install.packageManifest, grammar.package, grammar.entry)) problems.push(`${grammar.entry} is not a safe declared package export${where}`);
+  if (!grammarExport(install.packageManifest, grammar.package, grammar.styleEntry)) problems.push(`${grammar.styleEntry} is not a safe declared style export${where}`);
+  const actualPeers = Object.keys(install.packageManifest?.peerDependencies ?? {}).sort(byCodeUnit);
+  const selectedPeers = [...grammar.peers].sort(byCodeUnit);
+  if (JSON.stringify(actualPeers) !== JSON.stringify(selectedPeers)) {
+    problems.push(`${grammar.package} peerDependencies must exactly match the selected peers ${selectedPeers.join(', ')}${where}`);
+  }
+}
+
+function addConsumerDependencyProblems(grammar, consumers, problems) {
+  for (const consumer of consumers) if (!Object.hasOwn(consumer.manifest.dependencies ?? {}, grammar.package)) {
+    problems.push(`${consumer.relative} does not declare ${grammar.package} as a runtime dependency`);
+  }
+  for (const peer of grammar.peers) {
+    for (const consumer of consumers) if (!Object.hasOwn(consumer.manifest.dependencies ?? {}, peer) && !Object.hasOwn(consumer.manifest.peerDependencies ?? {}, peer)) {
+      problems.push(`${consumer.relative} does not declare Grammar peer ${peer}`);
+    }
+  }
+}
+
+function addGrammarStyleProblems(config, grammar, problems, styleBypasses) {
+  for (const source of grammar.styleSources) {
+    const content = fs.readFileSync(path.join(config.root, ...source.split('/')), 'utf8');
+    const grammarStyles = cssImports(content).filter(item => item.specifier === grammar.package || item.specifier.startsWith(`${grammar.package}/`));
+    if (!grammarStyles.some(item => item.specifier === grammar.styleEntry)) problems.push(`${source} does not import ${grammar.styleEntry}`);
+    for (const imported of grammarStyles) if (imported.specifier !== grammar.styleEntry) {
+      problems.push(`${source} imports Grammar style ${imported.specifier} outside the selected style entry`);
+      styleBypasses.push({ ruleId: 'ARCH_GRAMMAR_EXPORT_BYPASS', path: source,
+        line: content.slice(0, imported.index).split(/\r?\n/u).length, column: 1, package: grammar.package, specifier: imported.specifier,
+        message: `Style source must use the selected Grammar style entry ${grammar.styleEntry}; ${imported.specifier} is outside that contract.` });
+    }
+  }
+}
+
+function grammarOwner(consumers, fileName) {
+  return consumers.filter(consumer => isInside(consumer.root, fileName))
+    .sort((a, b) => b.root.length - a.root.length)[0] ?? null;
+}
+
+function sourceEdges(context, sourceFile) {
+  return new Map((context.edges.get(path.resolve(sourceFile.fileName)) ?? []).map(edge => [edge.node.getStart(sourceFile), edge]));
+}
+
+function grammarReferenceAllowed(reference, sourceFile, owner, edgesByStart, grammar, allowed) {
+  if (!allowed.has(reference.specifier)) return false;
+  const edge = edgesByStart.get(reference.node.getStart(sourceFile));
+  const expected = grammarExportTargets(owner.packageManifest, owner.packageRoot, grammar.package, reference.specifier);
+  return !edge || expected.includes(canonical(edge.to));
+}
+
+function reportGrammarReference(scan, sourceFile, reference, owner, edgesByStart) {
+  const { config, grammar, allowed, violations, makeViolation } = scan;
+  if (!sameOrUnder(reference.specifier, grammar.package)) return;
+  if (grammarReferenceAllowed(reference, sourceFile, owner, edgesByStart, grammar, allowed)) return;
+  violations.push(makeViolation(config, sourceFile, reference.node, 'ARCH_GRAMMAR_EXPORT_BYPASS',
+    `Product source must import the selected Grammar code entry ${grammar.entry} or style entry ${grammar.styleEntry}; ${reference.specifier} is outside that contract.`,
+    { specifier: reference.specifier, package: grammar.package }));
+}
+
+function inspectGrammarSource(scan, sourceFile) {
+  const { context, consumers, installs } = scan;
+  if (installs.some(install => isInside(install.packageRoot, sourceFile.fileName))) return;
+  const owner = grammarOwner(consumers, sourceFile.fileName);
+  if (!owner) return;
+  const edgesByStart = sourceEdges(context, sourceFile);
+  const references = literalModules(context.ts, sourceFile, context.checkerFor(sourceFile.fileName));
+  for (const reference of references) reportGrammarReference(scan, sourceFile, reference, owner, edgesByStart);
+}
+
+function addGrammarContractFinding(config, grammar, manifestFile, problems, violations) {
+  if (!problems.length) return;
+  violations.push({
+    ruleId: 'ARCH_GRAMMAR_CONTRACT_INVALID',
+    path: fs.existsSync(manifestFile) && isInside(config.root, manifestFile) ? relativePath(config.root, manifestFile) : 'package.json',
+    line: 1,
+    column: 1,
+    package: grammar.package,
+    message: `Grammar contract is invalid: ${problems.join('; ')}.`,
+  });
+}
+
+export function checkGrammar(config, context, makeViolation) {
+  const grammar = config.frontend.grammar;
+  if (!grammar) return [];
+  const violations = [];
+  const local = context.workspaces.find(workspace => workspace.name === grammar.package);
+  // Node resolution per consumer: in an npm-workspaces monorepo a consumer whose range differs from the
+  // hoisted copy gets its own apps/<app>/node_modules/<package> (one consumer: apps/app on 0.5.0 beside a hoisted
+  // 0.4.11). Every consumer is judged against the copy it actually resolves, never the hoisted one alone.
+  // An app installs once, at its root (config.packageRoot): a side folder has no node_modules of its own.
+  const installRoot = installRootFor(config);
+  const consumers = grammarConsumers(config, grammar, local, installRoot);
+  const installs = uniqueGrammarInstalls(consumers);
+  const packageRoot = grammarPackageRoot(installs, local, installRoot, grammar.package);
+  const manifestFile = path.join(packageRoot, 'package.json');
+  readJson(manifestFile);
+  const contractProblems = [];
+  const styleBypasses = [];
+  for (const install of installs) addInstallContractProblems(install, installs, grammar, config.root, contractProblems);
+  addConsumerDependencyProblems(grammar, consumers, contractProblems);
+  addGrammarStyleProblems(config, grammar, contractProblems, styleBypasses);
+  addGrammarContractFinding(config, grammar, manifestFile, contractProblems, violations);
+  const allowed = new Set([grammar.entry, grammar.styleEntry]);
+  violations.push(...styleBypasses);
+  const scan = { config, context, grammar, consumers, installs, allowed, violations, makeViolation };
+  for (const sourceFile of context.files) inspectGrammarSource(scan, sourceFile);
+  return violations;
+}

package/runtime/scripts/hfs/architecture/frontend-routing.mjs

@@ -0,0 +1,186 @@
+import path from 'node:path';
+import { reachableViolation, relativePath } from './typescript.mjs';
+
+function hasClientDirective(ts, sourceFile) {
+  return sourceFile.statements.find(statement => ts.isExpressionStatement(statement)
+    && ts.isStringLiteral(statement.expression) && statement.expression.text === 'use client');
+}
+
+function bindImportClause(ts, clause, edge, bindings) {
+  if (clause.name && !clause.isTypeOnly) bindings.set(clause.name.text, edge);
+  if (!clause.namedBindings) return;
+  if (ts.isNamespaceImport(clause.namedBindings)) bindings.set(clause.namedBindings.name.text, edge);
+  if (!ts.isNamedImports(clause.namedBindings)) return;
+  for (const element of clause.namedBindings.elements) {
+    if (!element.isTypeOnly && !clause.isTypeOnly) bindings.set(element.name.text, edge);
+  }
+}
+
+function importBindings(ts, sourceFile, edges) {
+  const byStart = new Map(edges.map(edge => [edge.node.getStart(sourceFile), edge]));
+  const bindings = new Map();
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement) || !statement.importClause || !ts.isStringLiteralLike(statement.moduleSpecifier)) continue;
+    const edge = byStart.get(statement.moduleSpecifier.getStart(sourceFile));
+    if (!edge) continue;
+    bindImportClause(ts, statement.importClause, edge, bindings);
+  }
+  return bindings;
+}
+
+function importedNames(ts, sourceFile, moduleName) {
+  const names = new Map();
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement) || statement.moduleSpecifier.text !== moduleName || !statement.importClause || statement.importClause.isTypeOnly) continue;
+    const named = statement.importClause.namedBindings;
+    if (!named || !ts.isNamedImports(named)) continue;
+    for (const element of named.elements) if (!element.isTypeOnly) names.set(element.name.text, element.propertyName?.text ?? element.name.text);
+  }
+  return names;
+}
+
+function jsxRootName(ts, tagName) {
+  if (ts.isIdentifier(tagName)) return tagName.text;
+  if (ts.isPropertyAccessExpression(tagName)) {
+    let current = tagName;
+    while (ts.isPropertyAccessExpression(current)) current = current.expression;
+    return ts.isIdentifier(current) ? current.text : null;
+  }
+  return null;
+}
+
+function addRouteVariableFunctions(ts, statement, variables) {
+  for (const declaration of statement.declarationList.declarations) {
+    if (ts.isIdentifier(declaration.name) && declaration.initializer
+      && (ts.isArrowFunction(declaration.initializer) || ts.isFunctionExpression(declaration.initializer))) variables.set(declaration.name.text, declaration.initializer);
+  }
+}
+
+function recordRouteStatement(ts, statement, state) {
+  if (ts.isVariableStatement(statement)) addRouteVariableFunctions(ts, statement, state.variables);
+  if (ts.isFunctionDeclaration(statement) && statement.name) state.functions.set(statement.name.text, statement);
+  if (ts.isFunctionDeclaration(statement) && statement.modifiers?.some(item => item.kind === ts.SyntaxKind.DefaultKeyword)) state.directDefault = statement;
+  if (ts.isExportAssignment(statement) && !statement.isExportEquals) state.exportNode = statement;
+}
+
+function routeFunction(ts, sourceFile) {
+  const state = { variables: new Map(), functions: new Map(), directDefault: null, exportNode: null };
+  for (const statement of sourceFile.statements) recordRouteStatement(ts, statement, state);
+  if (state.directDefault) return { fn: state.directDefault, exportNode: state.directDefault };
+  if (!state.exportNode || !ts.isIdentifier(state.exportNode.expression)) return { fn: null, exportNode: state.exportNode };
+  return { fn: state.variables.get(state.exportNode.expression.text) ?? state.functions.get(state.exportNode.expression.text) ?? null, exportNode: state.exportNode };
+}
+
+function routePageRoots(context, sourceFile, featureRoots) {
+  const workspace = context.workspaceOf(sourceFile.fileName);
+  if (!workspace) return featureRoots.map(root => path.join(root, 'pages'));
+  const local = featureRoots.filter(root => context.workspaceOf(root) === workspace);
+  return (local.length ? local : featureRoots).map(root => path.join(root, 'pages'));
+}
+
+function routingTermination(ts, statement, navigation) {
+  if (ts.isThrowStatement(statement)) return true;
+  if (ts.isBlock(statement)) return statement.statements.length > 0 && routingTermination(ts, statement.statements.at(-1), navigation);
+  const expression = ts.isExpressionStatement(statement) ? statement.expression : (ts.isReturnStatement(statement) && statement.expression) || null;
+  return Boolean(expression && ts.isCallExpression(expression) && ts.isIdentifier(expression.expression)
+    && ['redirect', 'notFound'].includes(navigation.get(expression.expression.text)));
+}
+
+function routingGuard(ts, node, navigation) {
+  return ts.isIfStatement(node) && !node.elseStatement && routingTermination(ts, node.thenStatement, navigation);
+}
+
+function routeNavigationCall(ts, node, navigation) {
+  return ts.isCallExpression(node) && ts.isIdentifier(node.expression)
+    && ['redirect', 'notFound'].includes(navigation.get(node.expression.text));
+}
+
+function recordRouteNode(ts, node, state, insideNavigationArgument) {
+  if (ts.isJsxSelfClosingElement(node) || ts.isJsxElement(node)) state.jsx.push(node);
+  if (ts.isIfStatement(node) || ts.isSwitchStatement(node) || (ts.isConditionalExpression(node) && !insideNavigationArgument)) state.decisions.push(node);
+}
+
+function visitRouteNode(ts, node, state, insideNavigationArgument = false) {
+  recordRouteNode(ts, node, state, insideNavigationArgument);
+  if (routeNavigationCall(ts, node, state.navigation)) {
+    state.adapterCalls.push(node);
+    for (const argument of node.arguments) visitRouteNode(ts, argument, state, true);
+    return;
+  }
+  ts.forEachChild(node, child => visitRouteNode(ts, child, state, insideNavigationArgument));
+}
+
+function collectRouteNodes(ts, routeFunction, navigation) {
+  const state = { jsx: [], adapterCalls: [], decisions: [], navigation };
+  visitRouteNode(ts, routeFunction, state);
+  return state;
+}
+
+function mountedRoutePages(ts, context, sourceFile, featureRoots, bindings, jsx, insideAny) {
+  const pages = routePageRoots(context, sourceFile, featureRoots);
+  return jsx.filter(node => {
+    const opening = ts.isJsxElement(node) ? node.openingElement : node;
+    const local = jsxRootName(ts, opening.tagName);
+    const edge = local ? bindings.get(local) : null;
+    return edge && Boolean(reachableViolation(context.edges, edge, target => insideAny(pages, target), { follow: candidate => candidate.reexport && candidate.runtime }));
+  });
+}
+
+function reportRouteComposition(at, route, scan, mountedPages) {
+  const { config, context, sourceFile, violations, violation } = at;
+  const navigationOnly = scan.jsx.length === 0 && scan.adapterCalls.length === 1;
+  if (!navigationOnly && (mountedPages.length !== 1 || scan.jsx.length !== 1)) {
+    violations.push(violation(config, sourceFile, route.fn, 'FE_ROUTE_ONE_PAGE', 'A page.tsx route must mount exactly one pages-tier component, or be a zero-JSX redirect/notFound adapter.', { ts: context.ts }));
+  }
+  return navigationOnly;
+}
+
+function reportRouteDecisions(at, decisions, navigation, navigationOnly) {
+  if (navigationOnly) return;
+  const { config, context, sourceFile, violations, violation } = at;
+  for (const decision of decisions) if (!routingGuard(context.ts, decision, navigation)) {
+    violations.push(violation(config, sourceFile, decision, 'FE_ROUTE_DRAWING_DECISION', 'Visual route files may use terminal redirect/notFound guards but cannot select or omit visual composition.', { ts: context.ts }));
+  }
+}
+
+function reportClientDirective(config, context, sourceFile, violations, violation) {
+  const clientDirective = hasClientDirective(context.ts, sourceFile);
+  if (clientDirective) violations.push(violation(config, sourceFile, clientDirective, 'FE_ROUTE_CLIENT_BOUNDARY', 'A page.tsx route adapter cannot own the client boundary.', { ts: context.ts }));
+}
+
+function routeHookName(ts, sourceFile, local) {
+  return sourceFile.statements.flatMap(statement => ts.isImportDeclaration(statement) && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings)
+    ? statement.importClause.namedBindings.elements.filter(item => item.name.text === local).map(item => item.name) : [])[0];
+}
+
+function reportForbiddenRouteHooks(config, context, sourceFile, navigation, violations, violation) {
+  const { ts } = context;
+  const forbiddenRouteHooks = new Set(['useRouter', 'usePathname', 'useSearchParams', 'useParams', 'useSelectedLayoutSegment', 'useSelectedLayoutSegments']);
+  for (const [local, imported] of navigation) if (forbiddenRouteHooks.has(imported)) {
+    const identifier = routeHookName(ts, sourceFile, local);
+    if (identifier) violations.push(violation(config, sourceFile, identifier, 'FE_ROUTE_CLIENT_HOOK', `Server route adapter imports ${imported}.`, { ts }));
+  }
+}
+
+export function checkRoute(config, context, sourceFile, roots, helpers) {
+  const { violation, insideAny, importsForSource } = helpers;
+  const { ts } = context;
+  const violations = [];
+  const edges = importsForSource(context, sourceFile.fileName);
+  const bindings = importBindings(ts, sourceFile, edges);
+  const route = routeFunction(ts, sourceFile);
+  if (!route.exportNode || !route.fn) {
+    violations.push({ ruleId: 'FE_ROUTE_DEFAULT_EXPORT', path: relativePath(config.root, sourceFile.fileName), line: 1, column: 1,
+      message: 'A page.tsx must default-export one local route function.' });
+    return violations;
+  }
+  const navigation = importedNames(ts, sourceFile, 'next/navigation');
+  const scan = collectRouteNodes(ts, route.fn, navigation);
+  const mountedPages = mountedRoutePages(ts, context, sourceFile, roots.features, bindings, scan.jsx, insideAny);
+  const at = { config, context, sourceFile, violations, violation };
+  const navigationOnly = reportRouteComposition(at, route, scan, mountedPages);
+  reportRouteDecisions(at, scan.decisions, navigation, navigationOnly);
+  reportClientDirective(config, context, sourceFile, violations, violation);
+  reportForbiddenRouteHooks(config, context, sourceFile, navigation, violations, violation);
+  return violations;
+}