traceforge-toolkit 0.1.0__py3-none-any.whl

traceforge/classify/rules.py

@@ -0,0 +1,215 @@
+"""Declarative classification helpers shared across all shell backends."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from traceforge.classify.config import ClassificationEngine
+    from traceforge.classify.core import Classification
+
+from traceforge.classify.core import Effect
+from traceforge.classify.coding import CodingRole
+
+
+class ShellActivity(StrEnum):
+    """Internal: what a shell command primarily does (command-local intent)."""
+
+    VERIFICATION = "verification"
+    DELIVERY = "delivery"
+    SETUP = "setup"
+    INVESTIGATION = "investigation"
+    IMPLEMENTATION = "implementation"
+
+
+SHELL_VERIFICATION = ShellActivity.VERIFICATION
+SHELL_DELIVERY = ShellActivity.DELIVERY
+SHELL_SETUP = ShellActivity.SETUP
+SHELL_INVESTIGATION = ShellActivity.INVESTIGATION
+SHELL_IMPLEMENTATION = ShellActivity.IMPLEMENTATION
+
+
+def activity_from_classification(cls: Classification) -> ShellActivity:
+    """Derive ShellActivity from a Classification's action/role dimensions."""
+    if cls.has_action("validate"):
+        return ShellActivity.VERIFICATION
+    if (
+        cls.has_action("configure")
+        or cls.has_scope("configuration.dependency")
+        or cls.has_role("orchestrator.package_manager")
+    ):
+        return ShellActivity.SETUP
+    if cls.has_action("retrieve") or cls.has_action("analyze"):
+        return ShellActivity.INVESTIGATION
+    if cls.has_role("persistence.version_control"):
+        return ShellActivity.DELIVERY
+    if cls.has_action("deliver"):
+        return ShellActivity.DELIVERY
+    if cls.has_action("persist") and cls.has_role("persistence"):
+        return ShellActivity.DELIVERY
+    return ShellActivity.IMPLEMENTATION
+
+
+@dataclass(frozen=True)
+class Rule:
+    """A declarative classification rule."""
+
+    binaries: frozenset[str]
+    activity: ShellActivity
+    subcmds: frozenset[str] | None = None
+    flags_require: frozenset[str] | None = None
+    flags_reject: frozenset[str] | None = None
+    role: CodingRole | str = ""
+    effect: Effect | str = ""
+    scope: str = ""
+    action: str = ""
+    phase: str = ""
+
+
+@dataclass(frozen=True)
+class BinaryInfo:
+    """Static metadata about a known binary."""
+
+    role: CodingRole | str
+    default_effect: Effect | None
+    network: bool = False
+    destructive: bool = False
+
+
+def _flags_satisfy(required: frozenset[str], actual: list[str]) -> bool:
+    """Check if actual flags satisfy required flags (with short-flag prefix matching)."""
+    actual_set = set(actual)
+    for req in required:
+        if req in actual_set:
+            continue
+        # Short-flag prefix match: -i matches -i.bak, -X matches -XPOST
+        if len(req) == 2 and req[0] == "-" and req[1] != "-":
+            if any(f.startswith(req) and len(f) > 2 for f in actual):
+                continue
+        return False
+    return True
+
+
+def match_rule(
+    binary: str,
+    subcmd: str | None,
+    flags: list[str],
+    *,
+    engine: ClassificationEngine,
+) -> Rule | None:
+    """Find the first matching rule for a (binary, subcmd, flags) tuple.
+
+    Uses the engine's pre-built binary→rules index for O(1) lookup instead
+    of scanning all rules.
+    """
+    for rule in engine.rules_by_binary.get(binary, ()):
+        if rule.subcmds is not None and subcmd not in rule.subcmds:
+            continue
+        if rule.flags_require is not None and not _flags_satisfy(rule.flags_require, flags):
+            continue
+        if rule.flags_reject is not None and rule.flags_reject.intersection(flags):
+            continue
+        return rule
+    return None
+
+
+def classify_binary(
+    binary: str,
+    subcmd: str | None,
+    flags: list[str],
+    all_words: list[str] | None = None,
+    *,
+    engine: ClassificationEngine,
+) -> ShellActivity:
+    """Classify a command into a ShellActivity using rules plus special cases."""
+    if not binary:
+        return ShellActivity.IMPLEMENTATION
+
+    rule = match_rule(binary, subcmd, flags, engine=engine)
+    npm_scripts = engine.npm_verify_scripts
+    interp_modules = engine.interpreter_verify_modules
+    if rule:
+        if binary in ("npm", "pnpm", "yarn") and subcmd == "run" and all_words:
+            script = all_words[2].lower() if len(all_words) > 2 else ""
+            if script in npm_scripts:
+                return SHELL_VERIFICATION
+            return SHELL_IMPLEMENTATION
+        return rule.activity
+
+    if binary in ("python", "python3", "node") and all_words and "-m" in all_words:
+        try:
+            m_idx = all_words.index("-m")
+            if m_idx + 1 < len(all_words) and all_words[m_idx + 1].lower() in interp_modules:
+                return SHELL_VERIFICATION
+        except ValueError:
+            pass
+
+    return SHELL_IMPLEMENTATION
+
+
+def effect_for_binary(
+    binary: str,
+    subcmd: str | None,
+    flags: list[str],
+    *,
+    engine: ClassificationEngine,
+    all_words: list[str] | None = None,
+) -> Effect | None:
+    """Determine effect from binary + context, using effect overrides and binary info."""
+    if binary in engine.effect_overrides:
+        from traceforge.classify.config import EffectOverrideConfig
+
+        override: EffectOverrideConfig = engine.effect_overrides[binary]
+
+        # Check flags (dash-prefixed words)
+        for fe in override.flag_effects:
+            if fe.mode == "any_present":
+                override_flags = set(fe.flags)
+                # Direct match
+                if override_flags.intersection(flags):
+                    return Effect(fe.effect)
+                # Prefix match for short flags with attached values (e.g., -i.bak matches -i)
+                for f in flags:
+                    if len(f) > 2 and f[0] == "-" and f[1] != "-":
+                        # Short flag with attached value: check if -X prefix matches
+                        short_prefix = f[:2]
+                        if short_prefix in override_flags:
+                            return Effect(fe.effect)
+
+        # For multi-level subcommands (e.g., docker system prune),
+        # check compound_subcmd_effects nested dict first
+        if subcmd and all_words and override.compound_subcmd_effects:
+            positionals = [w for w in all_words[1:] if not w.startswith("-")]
+            if len(positionals) >= 2:
+                parent = positionals[0]
+                child = positionals[1]
+                nested = override.compound_subcmd_effects.get(parent)
+                if nested and child in nested:
+                    return Effect(nested[child])
+
+        # Verb prefix matching for multi-level CLIs (aws <svc> <verb>, az <grp> <verb>)
+        # Skips the first positional (service/group name) to avoid collisions
+        # with service names that happen to also be verb-like words (e.g., 'connect').
+        if all_words and override.verb_prefix_effects:
+            positionals = [w for w in all_words[1:] if not w.startswith("-")]
+            # Start from index 1 to skip service/group name
+            for word in positionals[1:]:
+                for prefix, eff in override.verb_prefix_effects.items():
+                    if word == prefix or word.startswith(prefix + "-"):
+                        return Effect(eff)
+
+        if subcmd and subcmd in override.subcmd_effects:
+            return Effect(override.subcmd_effects[subcmd])
+
+        if override.default_effect is not None:
+            return Effect(override.default_effect)
+
+    bi = engine.binary_info
+    info = bi.get(binary)
+    if info:
+        if info.destructive:
+            return Effect.DESTRUCTIVE
+        return info.default_effect
+    return None

traceforge/classify/schema.yaml

@@ -0,0 +1,282 @@
+# Traceforge Tier 1 Schema — Source of truth for all dimension types.
+# Codegen reads this to produce src/traceforge/_generated.py.
+# CI enforces: make types && git diff --exit-code
+openapi: "3.1.0"
+info:
+  title: Traceforge Taxonomy Schema
+  version: "1.0.0"
+  description: >
+    Defines the finite vocabulary for every typed dimension in the Trace pipeline.
+    Tier 2 knowledge-base YAMLs are validated against these enums at runtime.
+
+components:
+  schemas:
+
+    EventKind:
+      type: string
+      description: "Canonical event kinds in <domain>.<object>.<phase> grammar."
+      enum:
+        - agent.completed
+        - agent.failed
+        - agent.handoff
+        - agent.spawned
+        - browser.action
+        - browser.launched
+        - browser.result
+        - checkpoint.created
+        - checkpoint.restored
+        - command.completed
+        - command.failed
+        - command.output
+        - command.started
+        - file.created
+        - file.deleted
+        - file.edited
+        - file.read
+        - guardrail.failed
+        - guardrail.passed
+        - guardrail.started
+        - hook.completed
+        - hook.failed
+        - hook.started
+        - input.received
+        - input.requested
+        - knowledge.query.completed
+        - knowledge.query.started
+        - llm.call.completed
+        - llm.call.failed
+        - llm.call.started
+        - llm.output.chunk
+        - llm.thinking.chunk
+        - mcp.connection.completed
+        - mcp.connection.failed
+        - mcp.connection.started
+        - memory.query.completed
+        - memory.query.started
+        - memory.save.completed
+        - memory.save.started
+        - message.assistant
+        - message.assistant.chunk
+        - message.system
+        - message.user
+        - permission.denied
+        - permission.granted
+        - permission.requested
+        - planning.completed
+        - planning.failed
+        - planning.started
+        - raw
+        - reasoning.completed
+        - reasoning.started
+        - session.abort
+        - session.ended
+        - session.error
+        - session.idle
+        - session.info
+        - session.paused
+        - session.resumed
+        - session.started
+        - session.warning
+        - skill.invoked
+        - task.completed
+        - task.failed
+        - task.started
+        - telemetry.usage
+        - tool.call.completed
+        - tool.call.failed
+        - tool.call.started
+        - tool.output
+        - tool.progress
+        - tool.result.chunk
+        - tool.validation.failed
+        - turn.ended
+        - turn.skipped
+        - turn.started
+        - workflow.completed
+        - workflow.failed
+        - workflow.started
+
+    Mechanism:
+      type: string
+      description: "How the tool interacts with the environment."
+      enum:
+        - communication.system
+        - communication.user
+        - database
+        - database.nosql
+        - database.sql
+        - delegation.agent
+        - filesystem
+        - network.http
+        - process
+        - process.shell
+        - unknown
+
+    Effect:
+      type: string
+      description: "What the tool does to state."
+      enum:
+        - destructive
+        - mutating
+        - read_only
+
+    Scope:
+      type: string
+      description: "What domain the action targets."
+      enum:
+        - artifact.build_output
+        - artifact.config
+        - artifact.container_image
+        - artifact.dependency
+        - artifact.documentation
+        - artifact.repository
+        - artifact.source_code
+        - artifact.test_code
+        - configuration.ci_cd
+        - configuration.dependency
+        - configuration.infrastructure
+        - external.api
+        - external.service
+        - state.deployment
+        - state.repository
+        - system.network
+        - system.os
+        - system.secrets
+
+    Role:
+      type: string
+      description: "What persona the tool fills."
+      enum:
+        - communicator.system_reporter
+        - communicator.user_prompt
+        - executor.container_runtime
+        - executor.script_runner
+        - modifier.file_editor
+        - orchestrator.ci_cd
+        - orchestrator.package_manager
+        - orchestrator.task_runner
+        - persistence.cache
+        - persistence.database
+        - persistence.version_control
+        - retriever.api_client
+        - retriever.file_browser
+        - retriever.search_index
+        - retriever.web_scraper
+        - validator.security_scanner
+        - validator.test_runner
+
+    Action:
+      type: string
+      description: "What verb the tool performs."
+      enum:
+        - analyze
+        - analyze.diff
+        - analyze.measure
+        - analyze.profile
+        - configure
+        - configure.install
+        - configure.provision
+        - configure.setup
+        - deliver
+        - deliver.deploy
+        - deliver.publish
+        - deliver.push
+        - deliver.release
+        - execute
+        - execute.repl
+        - execute.run_script
+        - execute.script
+        - execute.service
+        - generate
+        - generate.code
+        - generate.documentation
+        - generate.scaffold
+        - modify
+        - modify.edit
+        - modify.merge
+        - modify.rebase
+        - persist
+        - persist.commit
+        - persist.install
+        - persist.stage
+        - persist.write
+        - remove
+        - remove.clean
+        - remove.delete
+        - remove.teardown
+        - remove.uninstall
+        - retrieve
+        - retrieve.browse
+        - retrieve.diff
+        - retrieve.query
+        - retrieve.read
+        - retrieve.search
+        - transform
+        - transform.bundle
+        - transform.compile
+        - transform.format
+        - transform.refactor
+        - transform.transpile
+        - validate
+        - validate.build_check
+        - validate.lint
+        - validate.security_scan
+        - validate.test
+        - validate.typecheck
+
+    Capability:
+      type: string
+      description: "What capabilities/risks the tool exposes."
+      enum:
+        - budget_pressure
+        - credential_exposure
+        - elevated_privilege
+        - filesystem_read
+        - filesystem_write
+        - human_interaction
+        - integrity_unverified
+        - mcp_drift
+        - network_inbound
+        - network_outbound
+        - pii_exposure
+        - subprocess
+        - uses_credentials
+
+    Structure:
+      type: string
+      description: "Structural patterns detected in the invocation."
+      enum:
+        - conditional
+        - ifc_violation
+        - interactive
+        - parallel
+        - phase_anomaly
+        - piped
+        - sequential
+        - tainted_flow
+
+    RiskBand:
+      type: string
+      description: "Risk severity tier."
+      enum:
+        - safe
+        - caution
+        - danger
+        - critical
+        - unknown
+
+    Recommendation:
+      type: string
+      description: "Governance action to take."
+      enum:
+        - allow
+        - deny
+        - escalate
+        - warn
+
+    Decision:
+      type: string
+      description: "Gate verdict outcome."
+      enum:
+        - allow
+        - deny