source-kb 0.2.2__py3-none-any.whl

presets/java-spring/doc_types.yaml

@@ -0,0 +1,269 @@
+# Doc type definitions for java-spring preset
+# Each doc_type defines: template, batch order, generation conditions, split overrides, and size expectations.
+# core/ code reads this config — no doc_type names are hardcoded in Python.
+
+doc_types:
+  source-tree-analysis:
+    filename: "source-tree-analysis.md"
+    template: "subagent-structure.md"
+    batch: 1
+    global_view: true
+    conditional: false
+    search_keywords: ["目录结构", "文件树", "类职责", "包结构", "文件", "源码结构"]
+    size_expectations: {"min": 50, "warn_max": 1000, "hard_max": 2000}
+
+  data-models:
+    filename: "data-models.md"
+    template: "subagent-model.md"
+    batch: 2
+    conditional: true
+    search_keywords: ["表", "字段", "实体", "模型", "DTO", "VO", "Entity", "Domain"]
+    dedup_patterns: ["| 字段 | 类型 |", "字段表格"]
+    split_override:
+      readwrite:
+        max_lines: 30000
+        max_files_per_shard: 500
+    size_expectations: {"min": 50, "warn_max": 1500, "hard_max": 3000}
+    validators:
+      - type: sampling_check
+        params:
+          source: field_names
+          sample_size: 5
+
+  enums-and-constants:
+    filename: "enums-and-constants.md"
+    template: "subagent-enum.md"
+    batch: 2
+    conditional: true
+    search_keywords: ["枚举", "常量", "状态码", "Enum", "Constant"]
+    split_override:
+      readwrite:
+        max_lines: 20000
+        max_files_per_shard: 300
+    size_expectations: {"min": 30, "warn_max": 2000, "hard_max": 4000}
+    validators:
+      - type: sampling_check
+        params:
+          source: enum_values
+          sample_size: 5
+
+  database-access:
+    filename: "database-access.md"
+    template: "subagent-database-access.md"
+    batch: 2
+    conditional: true
+    search_keywords: ["SQL", "Mapper", "DAO", "数据访问", "Repository", "查询", "事务"]
+    depends_on: ["data-models"]
+    size_expectations: {"min": 50, "warn_max": 1500, "hard_max": 3000}
+
+  api-contracts:
+    filename: "api-contracts.md"
+    template: "subagent-api.md"
+    batch: 3
+    conditional: true
+    search_keywords: ["接口", "API", "参数", "错误码", "URL", "Controller", "端点"]
+    depends_on: ["data-models"]
+    size_expectations: {"min": 50, "warn_max": 1500, "hard_max": 3000}
+    validators:
+      - type: skeleton_count_match
+        params:
+          skeleton_field: "controllers"
+          annotations: ["@RestController", "@Controller"]
+          doc_heading_level: 2
+          min_ratio: 0.5
+
+  architecture:
+    filename: "architecture.md"
+    template: "subagent-architecture.md"
+    batch: 3
+    conditional: false
+    search_keywords: ["架构", "依赖", "配置", "技术栈", "中间件", "分层", "部署"]
+    size_expectations: {"min": 50, "warn_max": 1000, "hard_max": 2000}
+
+  caching:
+    filename: "caching.md"
+    template: "subagent-caching.md"
+    batch: 3
+    conditional: true
+    search_keywords: ["Redis", "缓存", "key", "Memcached", "TTL", "Cache", "Caffeine"]
+    owns_keywords: ["Redis", "缓存键", "RedisConstant", "Jedis", "Memcached", "Caffeine", "EhCache", "GuavaCache", "CacheManager"]
+    dedup_patterns: ["缓存 Key 常量", "TTL", "CAS 流程"]
+    depends_on: ["data-models"]
+    size_expectations: {"min": 30, "warn_max": 800, "hard_max": 1500}
+
+  messaging:
+    filename: "messaging.md"
+    template: "subagent-messaging.md"
+    batch: 3
+    conditional: true
+    search_keywords: ["Kafka", "Pulsar", "topic", "消费", "消息", "MQ", "RabbitMQ", "Producer"]
+    owns_keywords: ["Kafka", "Topic", "Consumer", "Producer", "KafkaConfig", "Pulsar", "RabbitMQ", "RocketMQ", "MQListener"]
+    dedup_patterns: ["消息体 JSON", "消费逻辑", "Topic 清单"]
+    depends_on: ["data-models"]
+    size_expectations: {"min": 30, "warn_max": 600, "hard_max": 1200}
+
+  scheduled-tasks:
+    filename: "scheduled-tasks.md"
+    template: "subagent-scheduled.md"
+    batch: 3
+    conditional: true
+    search_keywords: ["定时任务", "Job", "cron", "调度", "Scheduled", "XxlJob"]
+    size_expectations: {"min": 20, "warn_max": 500, "hard_max": 1000}
+
+  error-handling:
+    filename: "error-handling.md"
+    template: "subagent-error-handling.md"
+    batch: 3
+    conditional: true
+    search_keywords: ["异常", "错误码", "Exception", "错误处理", "ControllerAdvice"]
+    size_expectations: {"min": 10, "warn_max": 400, "hard_max": 800}
+
+  security:
+    filename: "security.md"
+    template: "subagent-security.md"
+    batch: 3
+    conditional: true
+    search_keywords: ["认证", "鉴权", "权限", "Token", "Security", "登录", "Filter"]
+    size_expectations: {"min": 20, "warn_max": 500, "hard_max": 1000}
+
+  aop-and-interceptors:
+    filename: "aop-and-interceptors.md"
+    template: "subagent-aop.md"
+    batch: 3
+    conditional: true
+    search_keywords: ["切面", "AOP", "拦截器", "Aspect", "Interceptor", "Pointcut"]
+    size_expectations: {"min": 20, "warn_max": 500, "hard_max": 1000}
+
+  observability:
+    filename: "observability.md"
+    template: "subagent-observability.md"
+    batch: 3
+    conditional: true
+    search_keywords: ["监控", "指标", "日志", "告警", "Metrics", "Actuator", "健康检查"]
+    owns_keywords: ["MeterRegistry", "Counter", "Timer", "Gauge", "Actuator", "Micrometer"]
+    size_expectations: {"min": 20, "warn_max": 500, "hard_max": 1000}
+
+  async-and-events:
+    filename: "async-and-events.md"
+    template: "subagent-async-events.md"
+    batch: 3
+    conditional: true
+    search_keywords: ["异步", "事件", "@Async", "EventListener", "线程池", "CompletableFuture"]
+    owns_keywords: ["Spring Event", "ApplicationEvent", "EventListener"]
+    size_expectations: {"min": 30, "warn_max": 600, "hard_max": 1200}
+
+  external-integrations:
+    filename: "external-integrations.md"
+    template: "subagent-external-integrations.md"
+    batch: 3
+    conditional: true
+    search_keywords: ["外部调用", "Feign", "HTTP", "SDK", "第三方", "远程服务", "WebClient"]
+    owns_keywords: ["Feign", "外部调用", "远程服务"]
+    size_expectations: {"min": 30, "warn_max": 800, "hard_max": 1500}
+
+  business-logic:
+    filename: "business-logic.md"
+    template: "subagent-business.md"
+    batch: 4
+    conditional: true
+    search_keywords: ["怎么实现", "流程", "调用链", "业务逻辑", "方法实现", "Service"]
+    split_override:
+      output-only:
+        max_lines: 4000
+      readwrite:
+        max_lines: 8000
+        max_files_per_shard: 60
+    depends_on: ["data-models", "api-contracts", "enums-and-constants"]
+    size_expectations: {"min": 100, "warn_max": 3000, "hard_max": 5000}
+
+  utils:
+    filename: "utils.md"
+    template: "subagent-utils.md"
+    batch: 4
+    conditional: true
+    search_keywords: ["工具类", "工具方法", "Util", "Helper", "Common"]
+    split_override:
+      readwrite:
+        max_lines: 15000
+        max_files_per_shard: 100
+    depends_on: ["data-models"]
+    size_expectations: {"min": 30, "warn_max": 1000, "hard_max": 2000}
+
+  index:
+    filename: "index.md"
+    template: "subagent-index.md"
+    batch: 5
+    conditional: false
+    global_view: true
+    search_keywords: ["概览", "模块介绍", "有哪些功能", "导航", "索引"]
+    depends_on: ["business-logic", "architecture", "data-models"]
+    size_expectations: {"min": 20, "warn_max": 300, "hard_max": 600}
+
+# Split thresholds (mode-specific defaults)
+# Users can override in kb-project.yaml under `split:` key.
+# Adjust based on your LLM model's context window:
+#   - GPT-3.5/4: use output-only defaults
+#   - Claude Sonnet/Opus: can increase readwrite limits
+#   - Local models (Qwen/DeepSeek): may need lower limits
+split:
+  output-only:
+    max_bytes: 307200          # 300KB — prompt token budget constraint
+    max_lines: 8000
+    max_files_per_shard: 80
+    llm_sample_limit: 200      # [CLI only] Max files sampled for LLM-based split grouping
+    merge_threshold_ratio: 0.25
+  readwrite:
+    max_bytes: 2097152         # 2MB — Agent reads files individually, not token-limited
+    max_lines: 15000           # Controls doc granularity, not prompt size
+    max_files_per_shard: 200
+    merge_threshold_ratio: 0.25
+  hysteresis_ratio: 0.10
+  # [Both modes] Noise words filtered when deriving shard group names from class names
+  noise_words:
+    - service
+    - impl
+    - base
+    - controller
+    - manager
+    - handler
+    - listener
+    - api
+    - java
+    - abstract
+    - default
+
+# Timeouts and limits
+# All values can be overridden in kb-project.yaml under `limits:` key.
+# Adjust based on your LLM model's capabilities.
+limits:
+  min_doc_size_bytes: 500
+  max_source_inline_bytes: 300000
+  max_skeleton_inline_bytes: 50000
+  max_output_tokens: 8192
+  prior_docs_max_chars: 2000
+  shard_context_max_chars: 1500
+  spawn_timeout_default: 900
+  heartbeat_interval: 30
+  max_retries: 2
+  max_consecutive_failures: 3
+  failure_rate_threshold: 0.5
+  # Audit thresholds
+  audit_single_agent_threshold_bytes: 51200    # 50KB — docs below this use single-agent audit
+  audit_skeleton_threshold_bytes: 81920        # 80KB — skeleton inline limit for audit prompts
+  # Sync thresholds
+  sync_max_changed_files: 20                   # above this, suggest kb-audit instead of kb-sync
+  # LLM call limits
+  classify_max_tokens: 4096                    # max tokens for LLM classification calls
+  # Dedup thresholds
+  dedup_min_doc_size_bytes: 15360              # 15KB — docs smaller than this skip dedup
+  garbage_patterns:
+    - "<web_search>"
+    - "<read_file>"
+    - "<search_results>"
+    - "Search results for"
+
+# Parser preference chain
+parsers:
+  - jqassistant
+  - treesitter
+  - regex

presets/java-spring/hooks.py

@@ -0,0 +1,122 @@
+"""Java-Spring preset hooks — language/framework-specific logic.
+
+Moves all hardcoded Java/Spring assumptions out of core/ into this preset hook.
+Core modules call hooks.get_*() instead of hardcoding these values.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from core.preset_hooks import PresetHooks
+
+
+class Hooks(PresetHooks):
+    """Java/Spring Boot specific hooks."""
+
+    def get_business_suffixes(self) -> tuple[str, ...]:
+        return (
+            "ServiceImpl", "Service", "Handler", "Processor", "Manager",
+            "Facade", "Strategy", "Validator", "Factory",
+            "Listener", "Consumer", "Producer", "Client", "Feign", "Biz", "BizImpl",
+        )
+
+    def get_infra_suffixes(self) -> tuple[str, ...]:
+        return (
+            "Config", "Configuration", "Properties", "Interceptor",
+            "Filter", "Aspect", "Advisor", "Converter", "Mapper",
+        )
+
+    def get_data_suffixes(self) -> tuple[str, ...]:
+        return ("DTO", "VO", "DO", "Entity", "Enum", "Constant", "Constants")
+
+    def get_framework_types(self) -> set[str]:
+        return {
+            "RedisTemplate", "StringRedisTemplate", "RedissonClient", "RdcRedissonClient",
+            "RdcStringCacheTemplate", "RedisUtil",
+            "KafkaTemplate", "KafkaProducer", "KafkaConsumer",
+            "RestTemplate", "WebClient", "HttpClient",
+            "JdbcTemplate", "SqlSessionFactory", "DataSource",
+            "ObjectMapper", "Gson", "BeanMapperImplDozer",
+            "ThreadPoolExecutor", "ExecutorService", "ScheduledExecutorService",
+            "ThreadPoolTaskExecutor", "Executor",
+            "ApplicationContext", "BeanFactory", "Environment",
+            "ApplicationEventPublisher",
+            "TransactionTemplate", "PlatformTransactionManager",
+            "MongoTemplate", "ElasticsearchRestTemplate",
+            "KafkaListenerEndpointRegistry",
+            "UniqueNumUtil", "DictionaryUtil", "Logger",
+        }
+
+    def get_common_types(self) -> frozenset[str]:
+        return frozenset({
+            "String", "Integer", "Long", "Double", "Float", "Boolean", "Byte", "Short",
+            "Object", "Void", "BigDecimal", "BigInteger", "Date",
+            "LocalDate", "LocalDateTime", "Instant", "Duration",
+            "List", "Map", "Set", "Collection", "Optional", "Stream",
+            "HashMap", "ArrayList", "HashSet", "LinkedList",
+            "Serializable", "Comparable", "Iterable", "Iterator",
+            "Exception", "RuntimeException", "Throwable", "Logger", "Log",
+            "HttpServletRequest", "HttpServletResponse", "ResponseEntity",
+        })
+
+    def get_noise_terms(self) -> set[str]:
+        return {
+            "String", "Integer", "Long", "Boolean", "List", "Map", "Set",
+            "JSON", "HTTP", "API", "SQL", "Redis", "Kafka", "Spring", "Java",
+        }
+
+    def get_inject_annotations(self) -> set[str]:
+        return {"@Autowired", "@Resource", "@Inject", "@Value",
+                "Autowired", "Resource", "Inject"}
+
+    def get_controller_annotations(self) -> list[str]:
+        return ["@RestController", "@Controller"]
+
+    def get_entity_annotations(self) -> list[str]:
+        return ["@Entity", "@Table", "@TableName"]
+
+    def get_source_extensions(self) -> list[str]:
+        return [".java", ".kt"]
+
+    def get_test_path_patterns(self) -> list[str]:
+        return ["/test/", "/tests/", "/src/test/"]
+
+    def get_split_name_suffixes(self) -> tuple[str, ...]:
+        return ("ServiceImpl", "Service", "Handler", "Processor", "Manager", "Controller")
+
+    def count_source_files(self, source_cache: Path) -> tuple[int, int]:
+        """Count Java source files and lines (excluding test directories)."""
+        total_files, total_lines = 0, 0
+        if not source_cache.is_dir():
+            return 0, 0
+        for root, _, filenames in os.walk(source_cache):
+            root_str = str(root).replace("\\", "/")
+            if "/test/" in root_str or "/src/test/" in root_str:
+                continue
+            for fn in filenames:
+                if fn.endswith(".java") or fn.endswith(".kt"):
+                    total_files += 1
+                    try:
+                        with open(os.path.join(root, fn), encoding="utf-8", errors="replace") as f:
+                            total_lines += sum(1 for _ in f)
+                    except OSError:
+                        pass
+        return total_files, total_lines
+
+    def extract_package_from_fqn(self, fqn: str) -> str:
+        """Extract package from Java fully-qualified name."""
+        parts = fqn.rsplit(".", 1)
+        return parts[0] if len(parts) > 1 else ""
+
+    def get_focus_hint(self, doc_type: str) -> str:
+        """Return focus hints for LLM-based split planning."""
+        hints = {
+            "business-logic": "关注 Service、Handler、Processor 等业务处理类",
+            "data-models": "关注 Entity、DTO、VO 等数据模型类",
+            "architecture": "关注 Config、Interceptor、Filter 等架构组件",
+            "utils": "关注 Helper、Converter、Mapper 等工具类",
+            "api-contracts": "关注 Controller、API、Client 等接口类",
+        }
+        return hints.get(doc_type, "")