@c4a/extract-ts 0.6.3 → 0.6.4

package/README.md

@@ -11,6 +11,34 @@ packages.
 
 **Depends on:** `@c4a/extract`, `web-tree-sitter`
 
+## React Router structural facts
+
+Projects that use `extractCustom()` can reuse `extractReactRouterRoutes()` to
+index JSX `<Route>` declarations and route-object arrays. It reports paths,
+components, redirects, conditions, import sources, notes, and source locations
+without classifying product meaning:
+
+```ts
+import { extractReactRouterRoutes } from "@c4a/extract-ts";
+
+const routes = extractReactRouterRoutes(source, "src/router.tsx", {
+  routeIdPrefix: "web",
+  mountPath: "/web",
+});
+```
+
+## TypeScript module export facts
+
+`extractTypeScriptModuleExports()` reads one TypeScript or TSX module and
+returns deterministic named exports, wildcard export targets, and all
+re-export targets. It does not resolve files or infer product meaning:
+
+```ts
+import { extractTypeScriptModuleExports } from "@c4a/extract-ts";
+
+const exports = extractTypeScriptModuleExports(source, "src/index.ts");
+```
+
 ## Current Extraction Coverage
 
 ### Entry Detection

package/README.zh-CN.md

@@ -0,0 +1,32 @@
+# @c4a/extract-ts
+
+Context 的 TypeScript/TSX 结构提取包。它实现 `@c4a/extract` 的插件协议，
+也是 SDK `extractTs({ source, collection: "codegraph" })` 阶段使用的默认
+提取器。
+
+除 TypeScript 符号、导出和 AST 关系外，包还提供可独立使用的 React Router
+结构提取：
+
+```ts
+import { extractReactRouterRoutes } from "@c4a/extract-ts";
+
+const routes = extractReactRouterRoutes(source, "src/router.tsx", {
+  routeIdPrefix: "web",
+  mountPath: "/web",
+});
+```
+
+该函数读取 JSX `<Route>` 和 route object 数组，返回路径、组件、重定向、
+条件、导入来源、注释及源码位置，不判断业务含义。项目可以在
+`extractCustom()` 中将这些结构事实映射为自己的候选。
+
+包还提供单文件导出面读取：
+
+```ts
+import { extractTypeScriptModuleExports } from "@c4a/extract-ts";
+
+const exports = extractTypeScriptModuleExports(source, "src/index.ts");
+```
+
+返回结果包含具名导出、通配导出目标和全部 re-export 目标。函数不解析文件、
+不追踪依赖，也不判断业务含义，适合由定制提取流程继续映射为领域事实。

package/index.js

@@ -13296,6 +13296,324 @@ class TypeScriptPlugin {
     return result;
   }
 }
+// src/reactRouter.ts
+import * as ts from "typescript";
+function compact(value) {
+  return value.replace(/\s+/gu, " ").trim();
+}
+function scalarValue(node2) {
+  if (!node2)
+    return;
+  if (ts.isStringLiteralLike(node2) || ts.isNoSubstitutionTemplateLiteral(node2))
+    return node2.text;
+  if (ts.isNumericLiteral(node2))
+    return Number(node2.text);
+  if (node2.kind === ts.SyntaxKind.TrueKeyword)
+    return true;
+  if (node2.kind === ts.SyntaxKind.FalseKeyword)
+    return false;
+  return;
+}
+function findDynamicImport(node2) {
+  let result;
+  const visit = (child) => {
+    if (result)
+      return;
+    if (ts.isCallExpression(child) && child.expression.kind === ts.SyntaxKind.ImportKeyword && child.arguments[0] && ts.isStringLiteralLike(child.arguments[0])) {
+      result = child.arguments[0].text;
+      return;
+    }
+    ts.forEachChild(child, visit);
+  };
+  visit(node2);
+  return result;
+}
+function parseSource(source, filePath) {
+  const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+  const imports = new Map;
+  const constants2 = new Map;
+  for (const statement of sourceFile.statements) {
+    if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier)) {
+      const moduleSource = statement.moduleSpecifier.text;
+      const clause = statement.importClause;
+      if (clause?.name)
+        imports.set(clause.name.text, moduleSource);
+      const bindings = clause?.namedBindings;
+      if (bindings && ts.isNamedImports(bindings)) {
+        for (const element of bindings.elements)
+          imports.set(element.name.text, moduleSource);
+      }
+      if (bindings && ts.isNamespaceImport(bindings))
+        imports.set(bindings.name.text, moduleSource);
+    }
+    if (!ts.isVariableStatement(statement))
+      continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || !declaration.initializer)
+        continue;
+      const scalar = scalarValue(declaration.initializer);
+      if (scalar !== undefined)
+        constants2.set(declaration.name.text, scalar);
+      const dynamicImport = findDynamicImport(declaration.initializer);
+      if (dynamicImport)
+        imports.set(declaration.name.text, dynamicImport);
+    }
+  }
+  return { sourceFile, imports, constants: constants2 };
+}
+function locationFor(filePath, sourceFile, node2) {
+  const start = sourceFile.getLineAndCharacterOfPosition(node2.getStart(sourceFile));
+  const end = sourceFile.getLineAndCharacterOfPosition(node2.getEnd());
+  return { path: filePath, startLine: start.line + 1, startColumn: start.character + 1, endLine: end.line + 1, endColumn: end.character + 1 };
+}
+function joinRoutePath(parent, child, index) {
+  if (index || !child || child === "/")
+    return parent || "/";
+  if (child.startsWith("/"))
+    return child.replace(/\/{2,}/gu, "/");
+  return `${parent.replace(/\/$/u, "")}/${child.replace(/^\//u, "")}`.replace(/\/{2,}/gu, "/");
+}
+function routeConditions(node2, sourceFile) {
+  const conditions = [];
+  let current = node2;
+  while (current?.parent) {
+    const parent = current.parent;
+    if (ts.isConditionalExpression(parent)) {
+      const condition = compact(parent.condition.getText(sourceFile));
+      conditions.push(current === parent.whenTrue ? condition : `!(${condition})`);
+    } else if (ts.isBinaryExpression(parent) && parent.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken && current === parent.right) {
+      conditions.push(compact(parent.left.getText(sourceFile)));
+    }
+    if (ts.isFunctionLike(parent))
+      break;
+    current = parent;
+  }
+  return [...new Set(conditions.reverse())];
+}
+function jsxAttributes(node2) {
+  const result = new Map;
+  for (const property of node2.attributes.properties)
+    if (ts.isJsxAttribute(property))
+      result.set(property.name.getText(), property);
+  return result;
+}
+function jsxExpression(attribute) {
+  const initializer = attribute?.initializer;
+  return initializer && ts.isJsxExpression(initializer) ? initializer.expression : undefined;
+}
+function jsxScalar(attribute, constants2) {
+  if (!attribute)
+    return;
+  if (!attribute.initializer)
+    return true;
+  if (ts.isStringLiteral(attribute.initializer))
+    return attribute.initializer.text;
+  const expression = jsxExpression(attribute);
+  return scalarValue(expression) ?? (expression && ts.isIdentifier(expression) ? constants2.get(expression.text) : undefined);
+}
+function descendantTags(node2) {
+  const tags = new Set;
+  const visit = (child) => {
+    if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child)) {
+      const opening = ts.isJsxElement(child) ? child.openingElement : child;
+      const tag = opening.tagName.getText();
+      if (child !== node2 && tag === "Route")
+        return;
+      if (!["Route", "Routes", "Suspense", "Fragment", "React.Fragment", "Navigate"].includes(tag))
+        tags.add(tag);
+    }
+    ts.forEachChild(child, visit);
+  };
+  visit(node2);
+  return [...tags];
+}
+function navigateTarget(node2, sourceFile) {
+  let target;
+  const visit = (child) => {
+    if (target)
+      return;
+    if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child)) {
+      const opening = ts.isJsxElement(child) ? child.openingElement : child;
+      if (child !== node2 && opening.tagName.getText() === "Route")
+        return;
+      if (opening.tagName.getText() === "Navigate") {
+        const attribute = jsxAttributes(opening).get("to");
+        const scalar = jsxScalar(attribute, new Map);
+        if (typeof scalar === "string")
+          target = scalar;
+        const expression = jsxExpression(attribute);
+        if (!target && expression) {
+          const text = expression.getText(sourceFile);
+          target = text.match(/pathname\s*:\s*['"]([^'"]+)['"]/u)?.[1] ?? compact(text);
+        }
+      }
+    }
+    ts.forEachChild(child, visit);
+  };
+  visit(node2);
+  return target;
+}
+function leadingNote(node2, sourceFile) {
+  const prefix = sourceFile.text.slice(Math.max(0, node2.getFullStart() - 600), node2.getStart(sourceFile));
+  const comments = [...prefix.matchAll(/\/\*+([\s\S]*?)\*\/|\/\/([^\n]*)/gu)];
+  const value = comments.at(-1)?.[1] ?? comments.at(-1)?.[2];
+  return value ? compact(value.replace(/^\s*\*\s?/gmu, "")) : undefined;
+}
+function componentSource(component, imports) {
+  const identifier = component?.match(/[A-Za-z_$][\w$]*/u)?.[0];
+  return identifier ? imports.get(identifier) : undefined;
+}
+function objectProperty(object2, name) {
+  for (const property of object2.properties) {
+    if (!ts.isPropertyAssignment(property) && !ts.isShorthandPropertyAssignment(property))
+      continue;
+    const key = property.name && (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)) ? property.name.text : undefined;
+    if (key !== name)
+      continue;
+    return ts.isPropertyAssignment(property) ? property.initializer : property.name;
+  }
+  return;
+}
+function extractReactRouterRoutes(source, filePath, options = {}) {
+  const parsed = parseSource(source, filePath);
+  const routeIdPrefix = options.routeIdPrefix ?? filePath;
+  const mountPath = options.mountPath ?? "/";
+  const ignoredCandidates = new Set(options.ignoredComponentCandidates ?? []);
+  const routes = [];
+  const relativePath = (fullPath) => {
+    if (mountPath === "/")
+      return fullPath;
+    if (fullPath === mountPath)
+      return "/";
+    return fullPath.startsWith(`${mountPath.replace(/\/$/u, "")}/`) ? fullPath.slice(mountPath.length) : fullPath;
+  };
+  const pushRoute = (input) => {
+    const fullPath = joinRoutePath(input.parentPath, input.path, input.index);
+    const candidates = input.candidates ?? (input.component ? [input.component] : []);
+    const location = locationFor(filePath, parsed.sourceFile, input.node);
+    const sourceModule = componentSource(input.component ?? candidates[0], parsed.imports);
+    const note = leadingNote(input.node, parsed.sourceFile);
+    routes.push({
+      id: `${routeIdPrefix}:${fullPath}:${location.startLine}`,
+      kind: input.redirectTo ? "redirect" : input.component || candidates.length > 0 ? "page" : "group",
+      relativePath: relativePath(fullPath),
+      fullPath,
+      index: input.index,
+      ...input.component ? { component: input.component } : candidates[0] ? { component: candidates[0] } : {},
+      ...sourceModule ? { componentSource: sourceModule } : {},
+      componentCandidates: candidates,
+      ...input.redirectTo ? { redirectTo: input.redirectTo } : {},
+      conditions: routeConditions(input.node, parsed.sourceFile),
+      ...note ? { note } : {},
+      location
+    });
+    if (input.children)
+      visitRouteObjects(input.children, fullPath);
+  };
+  const visitRouteObjects = (array, parentPath) => {
+    for (const element of array.elements) {
+      if (!ts.isObjectLiteralExpression(element))
+        continue;
+      const index = scalarValue(objectProperty(element, "index")) === true;
+      const pathValue = scalarValue(objectProperty(element, "path"));
+      const componentNode = objectProperty(element, "Component") ?? objectProperty(element, "element") ?? objectProperty(element, "lazy");
+      const component = componentNode ? compact(componentNode.getText(parsed.sourceFile)) : undefined;
+      const redirectNode = objectProperty(element, "redirectTo") ?? objectProperty(element, "to");
+      const redirect = scalarValue(redirectNode);
+      const children = objectProperty(element, "children");
+      pushRoute({
+        node: element,
+        parentPath,
+        path: typeof pathValue === "string" ? pathValue : "",
+        index,
+        ...component ? { component } : {},
+        ...typeof redirect === "string" ? { redirectTo: redirect } : {},
+        ...children && ts.isArrayLiteralExpression(children) ? { children } : {}
+      });
+    }
+  };
+  const visit = (node2, parentPath) => {
+    if (ts.isJsxElement(node2) || ts.isJsxSelfClosingElement(node2)) {
+      const opening = ts.isJsxElement(node2) ? node2.openingElement : node2;
+      if (opening.tagName.getText() === "Route") {
+        const attributes = jsxAttributes(opening);
+        const index = jsxScalar(attributes.get("index"), parsed.constants) === true;
+        const pathValue = jsxScalar(attributes.get("path"), parsed.constants);
+        const componentNode = jsxExpression(attributes.get("Component"));
+        const elementNode = jsxExpression(attributes.get("element"));
+        const component = componentNode ? compact(componentNode.getText(parsed.sourceFile)) : undefined;
+        const candidateNode = elementNode ?? componentNode ?? node2;
+        const candidates = (component ? [component] : descendantTags(candidateNode)).filter((candidate) => !ignoredCandidates.has(candidate));
+        const fullPath = joinRoutePath(parentPath, typeof pathValue === "string" ? pathValue : "", index);
+        const redirectTo = navigateTarget(candidateNode, parsed.sourceFile);
+        pushRoute({ node: node2, parentPath, path: typeof pathValue === "string" ? pathValue : "", index, ...component ? { component } : {}, candidates, ...redirectTo ? { redirectTo } : {} });
+        if (ts.isJsxElement(node2))
+          for (const child of node2.children)
+            visit(child, fullPath);
+        return;
+      }
+    }
+    if (ts.isCallExpression(node2)) {
+      const callee = node2.expression.getText(parsed.sourceFile);
+      if ((callee === "createBrowserRouter" || callee === "createHashRouter" || callee === "useRoutes") && node2.arguments[0] && ts.isArrayLiteralExpression(node2.arguments[0])) {
+        visitRouteObjects(node2.arguments[0], mountPath);
+      }
+    }
+    ts.forEachChild(node2, (child) => visit(child, parentPath));
+  };
+  visit(parsed.sourceFile, mountPath);
+  return routes.sort((left, right) => left.fullPath.localeCompare(right.fullPath) || left.location.startLine - right.location.startLine || left.location.startColumn - right.location.startColumn);
+}
+// src/moduleExports.ts
+import * as ts2 from "typescript";
+function exportedDeclarationName(statement) {
+  const exported = ts2.canHaveModifiers(statement) && ts2.getModifiers(statement)?.some((modifier) => modifier.kind === ts2.SyntaxKind.ExportKeyword);
+  if (!exported)
+    return;
+  if ((ts2.isFunctionDeclaration(statement) || ts2.isClassDeclaration(statement) || ts2.isInterfaceDeclaration(statement) || ts2.isTypeAliasDeclaration(statement) || ts2.isEnumDeclaration(statement)) && statement.name) {
+    return statement.name.text;
+  }
+  return;
+}
+function extractTypeScriptModuleExports(source, filePath = "module.ts") {
+  const sourceFile = ts2.createSourceFile(filePath, source, ts2.ScriptTarget.Latest, true, filePath.endsWith("x") ? ts2.ScriptKind.TSX : ts2.ScriptKind.TS);
+  const named = new Set;
+  const wildcard = new Set;
+  const targets = new Set;
+  for (const statement of sourceFile.statements) {
+    if (ts2.isExportDeclaration(statement)) {
+      const target = statement.moduleSpecifier && ts2.isStringLiteral(statement.moduleSpecifier) ? statement.moduleSpecifier.text : undefined;
+      if (target)
+        targets.add(target);
+      if (!statement.exportClause) {
+        if (target)
+          wildcard.add(target);
+      } else if (ts2.isNamedExports(statement.exportClause)) {
+        for (const element of statement.exportClause.elements)
+          named.add(element.name.text);
+      } else if (ts2.isNamespaceExport(statement.exportClause)) {
+        named.add(statement.exportClause.name.text);
+      }
+      continue;
+    }
+    const declarationName = exportedDeclarationName(statement);
+    if (declarationName)
+      named.add(declarationName);
+    if (ts2.isVariableStatement(statement) && ts2.getModifiers(statement)?.some((modifier) => modifier.kind === ts2.SyntaxKind.ExportKeyword)) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (ts2.isIdentifier(declaration.name))
+          named.add(declaration.name.text);
+      }
+    }
+  }
+  return {
+    named: [...named].sort(),
+    wildcard: [...wildcard].sort(),
+    targets: [...targets].sort()
+  };
+}
 export {
+  extractTypeScriptModuleExports,
+  extractReactRouterRoutes,
   TypeScriptPlugin
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/extract-ts",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "type": "module",
   "description": "TypeScript extraction plugin for C4A ExtractionResult v2",
   "license": "MIT",
@@ -13,6 +13,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "typescript": "^5.5.4",
     "web-tree-sitter": "^0.20.8"
   },
   "main": "./index.js"