@agent-scope/manifest 1.19.0 → 1.20.1

package/dist/index.d.ts

@@ -30,6 +30,32 @@ interface PropDescriptor {
     required: boolean;
     /** Raw TypeScript type string as written in source. */
     rawType: string;
+    /**
+     * Where this prop is defined.
+     *
+     * `"own"`       — declared in the project's source files (component-specific prop).
+     * `"inherited"` — inherited from React/HTML/third-party types in node_modules
+     *                  (e.g. `onClick`, `className` from `React.ComponentProps<'button'>`).
+     *
+     * Omitted when the source cannot be determined (legacy extraction paths).
+     */
+    source?: "own" | "inherited";
+    /**
+     * For inherited props, which category the prop belongs to — determined by
+     * the declaring interface in the type definitions.
+     *
+     * `"react"` — React-specific (Attributes, RefAttributes, DOMAttributes — includes
+     *             ref, key, children, synthetic event handlers like onClick).
+     * `"html"`  — HTML element attributes (HTMLAttributes, ButtonHTMLAttributes, etc. —
+     *             includes className, style, id, disabled, title).
+     * `"aria"`  — Accessibility attributes (AriaAttributes — aria-label, aria-hidden, etc.).
+     *
+     * When the prop comes from a third-party package (not React), this is the
+     * package name (e.g. `"class-variance-authority"`).
+     *
+     * Omitted for own props or when the group cannot be determined.
+     */
+    sourceGroup?: string;
 }
 /**
  * How the component is exported from its module.
@@ -132,6 +158,32 @@ interface ComponentDescriptor {
      * `null` when no scope file is found next to the component source file.
      */
     scopeFile: ScopeFileMeta | null;
+    /**
+     * The collection this component belongs to (e.g. "Forms", "Navigation").
+     * `undefined` means ungrouped.
+     *
+     * Resolution precedence (highest → lowest):
+     * 1. `@collection <name>` TSDoc tag on the component declaration
+     * 2. `export const collection = "name"` in a co-located `.scope.ts` file
+     * 3. First matching pattern in `config.collections[].patterns`
+     */
+    collection?: string;
+    /**
+     * Whether this component is internal (not intended for external consumers).
+     * Defaults to `false`.
+     *
+     * Set to `true` when:
+     * - `@internal` TSDoc tag is present on the component declaration, OR
+     * - The component's `filePath` or `displayName` matches any pattern in
+     *   `config.internalPatterns`.
+     */
+    internal: boolean;
+    /**
+     * Search keywords extracted from `@keywords` TSDoc tag.
+     * Comma-separated values are split into individual strings.
+     * Empty when no `@keywords` tag is present.
+     */
+    keywords: string[];
 }
 /**
  * Metadata extracted from a `.scope.ts(x)` / `.scope.js(x)` file that lives
@@ -151,6 +203,17 @@ interface ScopeFileMeta {
      */
     hasWrapper: boolean;
 }
+/**
+ * Configuration for a named component collection.
+ */
+interface CollectionConfig {
+    /** Human-readable collection name (e.g. "Forms", "Navigation"). */
+    name: string;
+    /** Optional description of the collection. */
+    description?: string;
+    /** Glob patterns matching component file paths that belong to this collection. */
+    patterns: string[];
+}
 /**
  * A node in the composition tree.
  */
@@ -172,6 +235,11 @@ interface Manifest {
     components: Record<string, ComponentDescriptor>;
     /** Composition tree (child/parent relationships). */
     tree: Record<string, TreeNode>;
+    /**
+     * All defined collections, echoing `config.collections`.
+     * Empty array when no collections are configured.
+     */
+    collections: CollectionConfig[];
 }
 /**
  * Configuration for `generateManifest`.
@@ -199,6 +267,24 @@ interface ManifestConfig {
      * Defaults to `<rootDir>/tsconfig.json`.
      */
     tsConfigFilePath?: string;
+    /**
+     * Named component collections. Each entry maps a set of glob patterns to a
+     * collection name. Components whose `filePath` matches a pattern are assigned
+     * to that collection (config-level precedence — lower than TSDoc / .scope.ts).
+     */
+    collections?: CollectionConfig[];
+    /**
+     * Glob patterns for components that should be flagged as internal.
+     * Matched against both `filePath` and `displayName`.
+     * Config-level precedence — lower than an explicit `@internal` TSDoc tag.
+     */
+    internalPatterns?: string[];
+    /**
+     * Glob patterns identifying icon components. Matched against both
+     * `filePath` and `displayName`. Icon-matching components are
+     * automatically flagged as internal (hidden from sidebar/index).
+     */
+    iconPatterns?: string[];
 }
 
 /**
@@ -206,4 +292,4 @@ interface ManifestConfig {
  */
 declare function generateManifest(config: ManifestConfig): Manifest;
 
-export { type ComplexityClass, type ComponentDescriptor, type ExportType, type Manifest, type ManifestConfig, type PropDescriptor, type PropKind, type ScopeFileMeta, type SideEffects, type TreeNode, generateManifest };
+export { type CollectionConfig, type ComplexityClass, type ComponentDescriptor, type ExportType, type Manifest, type ManifestConfig, type PropDescriptor, type PropKind, type ScopeFileMeta, type SideEffects, type TreeNode, generateManifest };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { existsSync } from 'fs';
+import { realpathSync, existsSync, readFileSync } from 'fs';
 import { join, relative } from 'path';
 import { Project, Node } from 'ts-morph';
 
@@ -333,7 +333,7 @@ function expandUnionValues(type) {
   }
   return values.length > 0 ? values : void 0;
 }
-function buildPropDescriptor(type, required, defaultValue) {
+function buildPropDescriptor(type, required, defaultValue, source, sourceGroup) {
   const kind = resolvePropKind(type);
   const desc = {
     type: kind,
@@ -348,6 +348,12 @@ function buildPropDescriptor(type, required, defaultValue) {
     desc.default = defaultValue;
     desc.required = false;
   }
+  if (source !== void 0) {
+    desc.source = source;
+  }
+  if (sourceGroup !== void 0) {
+    desc.sourceGroup = sourceGroup;
+  }
   return desc;
 }
 function extractPropsFromType(typeName, sourceFile, defaultValues = {}) {
@@ -359,25 +365,47 @@ function extractPropsFromType(typeName, sourceFile, defaultValues = {}) {
       if (name.startsWith("[")) continue;
       const type = prop.getType();
       const required = !prop.hasQuestionToken();
-      props[name] = buildPropDescriptor(type, required, defaultValues[name]);
+      props[name] = buildPropDescriptor(type, required, defaultValues[name], "own");
     }
     return props;
   }
   const typeAlias = sourceFile.getTypeAlias(typeName);
   if (typeAlias) {
     const aliasType = typeAlias.getType();
-    if (aliasType.isObject()) {
+    if (aliasType.isObject() || aliasType.isIntersection()) {
       for (const prop of aliasType.getProperties()) {
         const name = prop.getName();
         if (name.startsWith("[")) continue;
         const decls = prop.getDeclarations();
-        const required = decls.length === 0 || !prop.getDeclarations().some((d) => Node.isPropertySignature(d) && d.hasQuestionToken());
+        let required = decls.length === 0 || !prop.getDeclarations().some((d) => Node.isPropertySignature(d) && d.hasQuestionToken());
         const valType = prop.getTypeAtLocation(sourceFile);
-        props[name] = buildPropDescriptor(valType, required, defaultValues[name]);
+        if (required && typeIncludesUndefined(valType)) {
+          required = false;
+        }
+        const { source, sourceGroup } = classifyPropSource(prop);
+        props[name] = buildPropDescriptor(
+          valType,
+          required,
+          defaultValues[name],
+          source,
+          sourceGroup
+        );
       }
     }
     return props;
   }
+  for (const importDecl of sourceFile.getImportDeclarations()) {
+    const match = importDecl.getNamedImports().find((ni) => {
+      const localName = ni.getAliasNode()?.getText() ?? ni.getName();
+      return localName === typeName;
+    });
+    if (!match) continue;
+    const importedFile = importDecl.getModuleSpecifierSourceFile();
+    if (importedFile) {
+      const originalName = match.getName();
+      return extractPropsFromType(originalName, importedFile, defaultValues);
+    }
+  }
   return props;
 }
 function inferPropsTypeName(params) {
@@ -474,6 +502,78 @@ function extractNameFromWrappedCall(node) {
   }
   return void 0;
 }
+function extractForwardRefPropsTypeNode(node) {
+  if (!Node.isCallExpression(node)) return void 0;
+  const expr = node.getExpression();
+  const name = expr.getText();
+  if (name === "React.forwardRef" || name === "forwardRef") {
+    const typeArgs = node.getTypeArguments();
+    if (typeArgs.length >= 2 && typeArgs[1]) {
+      return typeArgs[1];
+    }
+    return void 0;
+  }
+  const args = node.getArguments();
+  if (args[0] && Node.isCallExpression(args[0])) {
+    return extractForwardRefPropsTypeNode(args[0]);
+  }
+  return void 0;
+}
+function typeIncludesUndefined(type) {
+  if (type.isUndefined()) return true;
+  if (type.isUnion()) {
+    return type.getUnionTypes().some((t) => t.isUndefined());
+  }
+  return false;
+}
+var REACT_INTERFACES = /* @__PURE__ */ new Set([
+  "Attributes",
+  "RefAttributes",
+  "ClassAttributes",
+  "DOMAttributes"
+]);
+function classifyPropSource(prop) {
+  const decls = prop.getDeclarations();
+  if (decls.length === 0) return { source: "inherited" };
+  const allInNodeModules = decls.every(
+    (d) => d.getSourceFile().getFilePath().includes("/node_modules/")
+  );
+  if (!allInNodeModules) return { source: "own" };
+  for (const d of decls) {
+    const parent = d.getParent();
+    if (!Node.isInterfaceDeclaration(parent)) continue;
+    const ifaceName = parent.getName();
+    if (ifaceName === "AriaAttributes") return { source: "inherited", sourceGroup: "aria" };
+    if (ifaceName.endsWith("HTMLAttributes")) return { source: "inherited", sourceGroup: "html" };
+    if (REACT_INTERFACES.has(ifaceName)) return { source: "inherited", sourceGroup: "react" };
+  }
+  const filePath = decls[0]?.getSourceFile().getFilePath() ?? "";
+  const pkgMatch = filePath.match(/node_modules\/((?:@[^/]+\/)?[^/]+)/);
+  if (pkgMatch?.[1]) {
+    const pkg = pkgMatch[1];
+    if (pkg === "@types/react" || pkg === "react")
+      return { source: "inherited", sourceGroup: "react" };
+    return { source: "inherited", sourceGroup: pkg };
+  }
+  return { source: "inherited" };
+}
+function extractPropsFromResolvedType(resolvedType, sourceFile, defaultValues = {}) {
+  const props = {};
+  if (!resolvedType.isObject() && !resolvedType.isIntersection()) return props;
+  for (const prop of resolvedType.getProperties()) {
+    const name = prop.getName();
+    if (name.startsWith("[")) continue;
+    const decls = prop.getDeclarations();
+    let required = decls.length === 0 || !decls.some((d) => Node.isPropertySignature(d) && d.hasQuestionToken());
+    const valType = prop.getTypeAtLocation(sourceFile);
+    if (required && typeIncludesUndefined(valType)) {
+      required = false;
+    }
+    const { source, sourceGroup } = classifyPropSource(prop);
+    props[name] = buildPropDescriptor(valType, required, defaultValues[name], source, sourceGroup);
+  }
+  return props;
+}
 function nodeReturnsJsx(node) {
   let found = false;
   function visit(n) {
@@ -487,6 +587,62 @@ function nodeReturnsJsx(node) {
   visit(node);
   return found;
 }
+function matchGlob(pattern, value) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const regexStr = escaped.replace(/\*\*/g, "\xA7GLOBSTAR\xA7").replace(/\*/g, "[^/]*").replace(/§GLOBSTAR§/g, ".*");
+  const regex = new RegExp(`^${regexStr}$`, "i");
+  return regex.test(value);
+}
+function extractTsDocTags(declNode) {
+  let collection;
+  let internal = false;
+  const keywords = [];
+  const nodeWithDocs = declNode;
+  if (typeof nodeWithDocs.getJsDocs !== "function") {
+    return { collection, internal, keywords };
+  }
+  const jsDocs = nodeWithDocs.getJsDocs();
+  for (const jsDoc of jsDocs) {
+    for (const tag of jsDoc.getTags()) {
+      const tagName = tag.getTagName();
+      if (tagName === "collection") {
+        const comment = tag.getComment();
+        if (comment && typeof comment === "string") {
+          collection = comment.trim();
+        }
+      } else if (tagName === "internal") {
+        internal = true;
+      } else if (tagName === "keywords") {
+        const comment = tag.getComment();
+        if (comment && typeof comment === "string") {
+          for (const kw of comment.split(",")) {
+            const trimmed = kw.trim();
+            if (trimmed) keywords.push(trimmed);
+          }
+        }
+      }
+    }
+  }
+  return { collection, internal, keywords };
+}
+function readCollectionFromScopeFile(scopeFilePath, project) {
+  let sf = project.getSourceFile(scopeFilePath);
+  if (!sf) {
+    sf = project.addSourceFileAtPath(scopeFilePath);
+  }
+  for (const varStmt of sf.getVariableStatements()) {
+    if (!varStmt.isExported()) continue;
+    for (const varDecl of varStmt.getDeclarations()) {
+      if (varDecl.getName() !== "collection") continue;
+      const initializer = varDecl.getInitializer();
+      if (!initializer) continue;
+      if (Node.isStringLiteral(initializer)) {
+        return initializer.getLiteralValue();
+      }
+    }
+  }
+  return void 0;
+}
 function processSourceFile(sourceFile, rootDir, project) {
   const results = [];
   const filePath = relative(rootDir, sourceFile.getFilePath());
@@ -547,7 +703,10 @@ function processSourceFile(sourceFile, rootDir, project) {
         detectedHooks: detectHooks(fn),
         requiredContexts: detectRequiredContexts(fn, sourceFile, project),
         sideEffects: detectSideEffects(fn),
-        scopeFile: null
+        scopeFile: null,
+        // collection, internal, and keywords will be filled in after all components are collected
+        internal: false,
+        keywords: []
       }
     });
   }
@@ -585,7 +744,16 @@ function processSourceFile(sourceFile, rootDir, project) {
       }
       const propsTypeName = inferPropsTypeName(params);
       const defaults = extractDefaultsFromDestructuring(params);
-      const props = propsTypeName ? extractPropsFromType(propsTypeName, sourceFile, defaults) : {};
+      let props = {};
+      if (propsTypeName) {
+        props = extractPropsFromType(propsTypeName, sourceFile, defaults);
+      }
+      if (Object.keys(props).length === 0 && wrappers.forwardedRef) {
+        const propsTypeNode = extractForwardRefPropsTypeNode(initializer);
+        if (propsTypeNode) {
+          props = extractPropsFromResolvedType(propsTypeNode.getType(), sourceFile, defaults);
+        }
+      }
       const composes = collectJsxCompositions(bodyNode);
       const startLine = varDecl.getStartLineNumber();
       const endLine = varDecl.getEndLineNumber();
@@ -612,7 +780,9 @@ function processSourceFile(sourceFile, rootDir, project) {
           detectedHooks: detectHooks(bodyNode),
           requiredContexts: detectRequiredContexts(bodyNode, sourceFile, project),
           sideEffects: detectSideEffects(bodyNode),
-          scopeFile: null
+          scopeFile: null,
+          internal: false,
+          keywords: []
         }
       });
     }
@@ -661,19 +831,22 @@ function processSourceFile(sourceFile, rootDir, project) {
         detectedHooks: [],
         requiredContexts: [],
         sideEffects: detectSideEffects(cls),
-        scopeFile: null
+        scopeFile: null,
+        internal: false,
+        keywords: []
       }
     });
   }
   return results;
 }
 function generateManifest(config) {
+  const normalizedRootDir = realpathSync(config.rootDir);
   const {
-    rootDir,
     include = ["src/**/*.tsx", "src/**/*.ts"],
     exclude = ["**/node_modules/**", "**/*.test.*", "**/*.spec.*", "**/dist/**", "**/*.d.ts"],
-    tsConfigFilePath = join(rootDir, "tsconfig.json")
+    tsConfigFilePath = join(normalizedRootDir, "tsconfig.json")
   } = config;
+  const rootDir = normalizedRootDir;
   const project = new Project({
     tsConfigFilePath,
     skipAddingFilesFromTsConfig: true
@@ -729,11 +902,78 @@ function generateManifest(config) {
       desc.scopeFile = scopeMeta;
     }
   }
+  const configCollections = config.collections ?? [];
+  const internalPatterns = config.internalPatterns ?? [];
+  for (const [compName, desc] of Object.entries(allComponents)) {
+    const absFilePath = desc.filePath.startsWith("/") ? desc.filePath : join(rootDir, desc.filePath);
+    const sf = project.getSourceFile(absFilePath);
+    let tsdocCollection;
+    let tsdocInternal = false;
+    let tsdocKeywords = [];
+    if (sf) {
+      const fn = sf.getFunction(compName);
+      if (fn) {
+        const tags = extractTsDocTags(fn);
+        tsdocCollection = tags.collection;
+        tsdocInternal = tags.internal;
+        tsdocKeywords = tags.keywords;
+      }
+      if (tsdocCollection === void 0 && !tsdocInternal && tsdocKeywords.length === 0) {
+        const varDecl = sf.getVariableDeclaration(compName);
+        if (varDecl) {
+          const varStmt = varDecl.getVariableStatement();
+          if (varStmt) {
+            const tags = extractTsDocTags(varStmt);
+            tsdocCollection = tags.collection;
+            tsdocInternal = tags.internal;
+            tsdocKeywords = tags.keywords;
+          }
+        }
+      }
+      if (tsdocCollection === void 0 && !tsdocInternal && tsdocKeywords.length === 0) {
+        const cls = sf.getClass(compName);
+        if (cls) {
+          const tags = extractTsDocTags(cls);
+          tsdocCollection = tags.collection;
+          tsdocInternal = tags.internal;
+          tsdocKeywords = tags.keywords;
+        }
+      }
+    }
+    let scopeFileCollection;
+    if (desc.scopeFile) {
+      scopeFileCollection = readCollectionFromScopeFile(desc.scopeFile.filePath, project);
+    }
+    let configCollection;
+    for (const colConfig of configCollections) {
+      if (colConfig.patterns.some((p) => matchGlob(p, desc.filePath))) {
+        configCollection = colConfig.name;
+        break;
+      }
+    }
+    let configInternal = false;
+    if (internalPatterns.length > 0) {
+      configInternal = internalPatterns.some(
+        (p) => matchGlob(p, desc.filePath) || matchGlob(p, desc.displayName)
+      );
+    }
+    const iconPats = config.iconPatterns ?? [];
+    const isIcon = iconPats.length > 0 && iconPats.some((p) => matchGlob(p, desc.filePath) || matchGlob(p, desc.displayName));
+    const resolvedCollection = tsdocCollection ?? scopeFileCollection ?? configCollection;
+    if (resolvedCollection !== void 0) {
+      desc.collection = resolvedCollection;
+    }
+    desc.internal = tsdocInternal || configInternal || isIcon;
+    if (tsdocKeywords.length > 0) {
+      desc.keywords = tsdocKeywords;
+    }
+  }
   return {
     version: "0.1",
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     components: allComponents,
-    tree
+    tree,
+    collections: configCollections
   };
 }
 var SCOPE_EXTENSIONS = [".scope.tsx", ".scope.ts", ".scope.jsx", ".scope.js"];
@@ -743,7 +983,103 @@ function detectScopeFile(componentFilePath, rootDir) {
   for (const ext of SCOPE_EXTENSIONS) {
     const candidate = `${stem}${ext}`;
     if (existsSync(candidate)) {
-      return { filePath: candidate, scenarioNames: [], hasWrapper: false };
+      return readScopeFileMeta(candidate);
+    }
+  }
+  return null;
+}
+function readScopeFileMeta(filePath) {
+  const source = readFileSync(filePath, "utf-8");
+  const scenarioNames = extractScenarioNames(source);
+  const hasWrapper = /\bexport\s+(?:const|function)\s+wrapper\b/.test(source) || /\bwrapper\s*:/.test(source);
+  return { filePath, scenarioNames, hasWrapper };
+}
+function extractScenarioNames(source) {
+  const objectSource = extractScenarioObjectLiteral(source, /\bexport\s+const\s+scenarios\s*=\s*\{/) ?? extractScenarioObjectLiteral(source, /\bscenarios\s*:\s*\{/);
+  if (objectSource === null) return [];
+  const names = /* @__PURE__ */ new Set();
+  let depth = 0;
+  let quote = null;
+  let escaped = false;
+  let token = "";
+  const flushTokenAsKey = () => {
+    const name = token.trim().replace(/^['"]|['"]$/g, "");
+    if (depth === 0 && name && name !== "scenarios" && name !== "wrapper") {
+      names.add(name);
+    }
+    token = "";
+  };
+  for (let i = 0; i < objectSource.length; i += 1) {
+    const char = objectSource[i];
+    if (quote !== null) {
+      token += char;
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      token += char;
+      continue;
+    }
+    if (char === "{") {
+      depth += 1;
+      token = "";
+      continue;
+    }
+    if (char === "}") {
+      depth = Math.max(0, depth - 1);
+      token = "";
+      continue;
+    }
+    if (depth === 0 && char === ":") {
+      flushTokenAsKey();
+      continue;
+    }
+    if (depth === 0 && char === ",") {
+      token = "";
+      continue;
+    }
+    token += char;
+  }
+  return [...names];
+}
+function extractScenarioObjectLiteral(source, pattern) {
+  const match = pattern.exec(source);
+  if (!match) return null;
+  const openBraceIndex = source.indexOf("{", match.index);
+  if (openBraceIndex < 0) return null;
+  let depth = 0;
+  let quote = null;
+  let escaped = false;
+  for (let i = openBraceIndex; i < source.length; i += 1) {
+    const char = source[i];
+    if (quote !== null) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      continue;
+    }
+    if (char === "{") {
+      depth += 1;
+      continue;
+    }
+    if (char === "}") {
+      depth -= 1;
+      if (depth === 0) return source.slice(openBraceIndex + 1, i);
     }
   }
   return null;