agentweaver 0.1.17 → 0.1.18

package/dist/playbook/repo-inventory.js

@@ -0,0 +1,208 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+const IGNORED_DIRECTORIES = [".git", "node_modules", "dist", ".agentweaver/scopes/*/.artifacts/manifest-history"];
+const EXACT_IGNORED_DIRS = new Set([".git", "node_modules", "dist"]);
+function toPosix(relativePath) {
+    return relativePath.split(path.sep).join("/");
+}
+function shouldIgnoreDirectory(relativePath) {
+    if (!relativePath) {
+        return false;
+    }
+    const parts = toPosix(relativePath).split("/");
+    if (parts.some((part) => EXACT_IGNORED_DIRS.has(part))) {
+        return true;
+    }
+    return parts.length >= 5
+        && parts[0] === ".agentweaver"
+        && parts[1] === "scopes"
+        && parts[3] === ".artifacts"
+        && parts[4] === "manifest-history";
+}
+function walkFiles(root, directory = root) {
+    const entries = readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
+    const files = [];
+    for (const entry of entries) {
+        const absolutePath = path.join(directory, entry.name);
+        const relativePath = toPosix(path.relative(root, absolutePath));
+        if (entry.isDirectory()) {
+            if (!shouldIgnoreDirectory(relativePath)) {
+                files.push(...walkFiles(root, absolutePath));
+            }
+            continue;
+        }
+        if (entry.isFile()) {
+            files.push(relativePath);
+        }
+    }
+    return files.sort((left, right) => left.localeCompare(right));
+}
+function hasFile(files, filePath) {
+    return files.has(filePath);
+}
+function addObservation(target, kind, title, evidence, details) {
+    const evidence_paths = Array.from(new Set(evidence)).sort((left, right) => left.localeCompare(right));
+    if (evidence_paths.length === 0) {
+        return;
+    }
+    target.push({
+        kind,
+        title,
+        evidence_paths,
+        ...(details && Object.keys(details).length > 0 ? { details } : {}),
+    });
+}
+function findByRegex(files, pattern) {
+    return files.filter((filePath) => pattern.test(filePath)).sort((left, right) => left.localeCompare(right));
+}
+function readJsonIfPresent(root, relativePath) {
+    const filePath = path.join(root, relativePath);
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function detectTextUsage(root, files, pattern) {
+    const candidates = files.filter((filePath) => {
+        const absolutePath = path.join(root, filePath);
+        try {
+            if (statSync(absolutePath).size > 256 * 1024) {
+                return false;
+            }
+            return pattern.test(readFileSync(absolutePath, "utf8"));
+        }
+        catch {
+            return false;
+        }
+    });
+    return candidates.sort((left, right) => left.localeCompare(right));
+}
+export function collectRepoInventory(repositoryRoot, generatedAt = new Date().toISOString()) {
+    const root = path.resolve(repositoryRoot);
+    const files = walkFiles(root);
+    const fileSet = new Set(files);
+    const stack_indicators = [];
+    const test_structure = [];
+    const architecture_hints = [];
+    const quality_tooling = [];
+    const specification_files = [];
+    const runtime_configs = [];
+    const generated_code = [];
+    const packageJson = readJsonIfPresent(root, "package.json");
+    if (packageJson) {
+        const scripts = packageJson.scripts && typeof packageJson.scripts === "object" && !Array.isArray(packageJson.scripts)
+            ? Object.keys(packageJson.scripts).sort()
+            : [];
+        addObservation(stack_indicators, "node_package", "Node package manifest", ["package.json"], scripts.length > 0 ? { scripts } : {});
+        if (scripts.length > 0) {
+            addObservation(quality_tooling, "npm_scripts", "NPM scripts", ["package.json"], { scripts });
+        }
+    }
+    for (const [kind, title, evidence] of [
+        ["go_module", "Go module", "go.mod"],
+        ["maven_project", "Maven project", "pom.xml"],
+        ["gradle_project", "Gradle project", "build.gradle"],
+        ["gradle_kotlin_project", "Gradle Kotlin project", "build.gradle.kts"],
+        ["typescript_config", "TypeScript configuration", "tsconfig.json"],
+        ["dockerfile", "Dockerfile", "Dockerfile"],
+        ["makefile", "Makefile", "Makefile"],
+    ]) {
+        if (hasFile(fileSet, evidence)) {
+            addObservation(stack_indicators, kind, title, [evidence]);
+        }
+    }
+    addObservation(stack_indicators, "compose_file", "Compose runtime file", findByRegex(files, /(^|\/)(docker-)?compose\.(ya?ml|json)$/i));
+    const specFiles = findByRegex(files, /(^|\/)(openapi|swagger|asyncapi|graphql|schema|spec)[^/]*(\.(ya?ml|json|graphql|proto|md))$/i);
+    addObservation(specification_files, "api_or_specification", "API or specification files", specFiles);
+    if (specFiles.some((filePath) => /openapi|swagger/i.test(filePath))) {
+        addObservation(stack_indicators, "openapi_specification", "OpenAPI or Swagger specification", specFiles.filter((filePath) => /openapi|swagger/i.test(filePath)));
+    }
+    addObservation(test_structure, "test_directories", "Test directories", findByRegex(files, /(^|\/)(tests?|__tests__)\//i).map((filePath) => filePath.split("/").slice(0, -1).join("/")).filter(Boolean));
+    addObservation(test_structure, "go_tests", "Go test files", findByRegex(files, /_test\.go$/));
+    addObservation(test_structure, "typescript_tests", "TypeScript or JavaScript test files", findByRegex(files, /(\.|\/)(test|spec)\.[cm]?[tj]sx?$/));
+    addObservation(test_structure, "java_tests", "Java test files", findByRegex(files, /(^|\/)[^/]*(Test|IT)\.java$/));
+    addObservation(test_structure, "fixtures", "Fixture directories or files", findByRegex(files, /(^|\/)(fixtures?|testdata)\//i));
+    addObservation(test_structure, "testcontainers_usage", "Testcontainers usage", detectTextUsage(root, files, /testcontainers/i));
+    addObservation(test_structure, "mocks_usage", "Mock usage", detectTextUsage(root, files, /\b(mock|vi\.fn|jest\.fn|sinon)\b/i));
+    addObservation(architecture_hints, "handlers_or_controllers", "Handlers or controllers", findByRegex(files, /(^|\/)(handlers?|controllers?)\//i));
+    addObservation(architecture_hints, "services", "Service modules", findByRegex(files, /(^|\/)services?\//i));
+    addObservation(architecture_hints, "repositories", "Repository modules", findByRegex(files, /(^|\/)repositories?\//i));
+    addObservation(architecture_hints, "migrations", "Migration files", findByRegex(files, /(^|\/)migrations?\//i));
+    addObservation(architecture_hints, "dtos", "DTO modules", findByRegex(files, /(^|\/)(dto|dtos)\//i));
+    addObservation(generated_code, "generated_paths", "Generated code paths", findByRegex(files, /(^|\/)(generated|gen)\//i).concat(findByRegex(files, /\.(generated|gen)\./i)));
+    addObservation(runtime_configs, "environment_files", "Environment example files", findByRegex(files, /(^|\/)\.env(\.example|\.sample)?$/i));
+    addObservation(runtime_configs, "runtime_config_files", "Runtime configuration files", findByRegex(files, /(^|\/)(config|configs)\//i).concat(findByRegex(files, /(^|\/)(app|application|settings)\.(json|ya?ml|toml|properties)$/i)));
+    addObservation(quality_tooling, "eslint_config", "ESLint configuration", findByRegex(files, /(^|\/)(eslint\.config\.[cm]?js|\.eslintrc(\..*)?)$/i));
+    addObservation(quality_tooling, "prettier_config", "Prettier configuration", findByRegex(files, /(^|\/)(\.prettierrc(\..*)?|prettier\.config\.[cm]?js)$/i));
+    addObservation(quality_tooling, "golangci_lint", "golangci-lint configuration", findByRegex(files, /(^|\/)\.golangci\.ya?ml$/i));
+    addObservation(quality_tooling, "jest_or_vitest", "Jest or Vitest configuration", findByRegex(files, /(^|\/)(jest|vitest)\.config\.[cm]?[tj]s$/i));
+    addObservation(quality_tooling, "ci_config", "CI configuration", findByRegex(files, /(^|\/)(\.github\/workflows\/|\.gitlab-ci\.yml|Jenkinsfile)/i));
+    addObservation(quality_tooling, "custom_scripts", "Custom scripts", findByRegex(files, /(^|\/)(scripts?|bin)\//i));
+    const observations = [
+        ...stack_indicators,
+        ...test_structure,
+        ...architecture_hints,
+        ...quality_tooling,
+        ...specification_files,
+        ...runtime_configs,
+        ...generated_code,
+    ];
+    const evidence = Array.from(new Set(observations.flatMap((observation) => observation.evidence_paths))).sort((left, right) => left.localeCompare(right));
+    return {
+        summary: `Repository inventory captured ${evidence.length} evidence paths across stack, tests, architecture, quality, specifications, runtime config, and generated code.`,
+        repository_root: root,
+        generated_at: generatedAt,
+        ignored_directories: [...IGNORED_DIRECTORIES],
+        stack_indicators: stack_indicators.sort((left, right) => left.kind.localeCompare(right.kind)),
+        test_structure: test_structure.sort((left, right) => left.kind.localeCompare(right.kind)),
+        architecture_hints: architecture_hints.sort((left, right) => left.kind.localeCompare(right.kind)),
+        quality_tooling: quality_tooling.sort((left, right) => left.kind.localeCompare(right.kind)),
+        specification_files: specification_files.sort((left, right) => left.kind.localeCompare(right.kind)),
+        runtime_configs: runtime_configs.sort((left, right) => left.kind.localeCompare(right.kind)),
+        generated_code: generated_code.sort((left, right) => left.kind.localeCompare(right.kind)),
+        evidence,
+    };
+}
+function renderObservationList(observations) {
+    if (observations.length === 0) {
+        return "- No confirmed signals.";
+    }
+    return observations
+        .map((observation) => `- ${observation.title}: ${observation.evidence_paths.join(", ")}`)
+        .join("\n");
+}
+export function renderRepoInventoryMarkdown(inventory) {
+    return [
+        "# Repository Inventory",
+        "",
+        inventory.summary,
+        "",
+        "## Stack",
+        renderObservationList(inventory.stack_indicators),
+        "",
+        "## Tests",
+        renderObservationList(inventory.test_structure),
+        "",
+        "## Architecture",
+        renderObservationList(inventory.architecture_hints),
+        "",
+        "## Quality",
+        renderObservationList(inventory.quality_tooling),
+        "",
+        "## Specifications",
+        renderObservationList(inventory.specification_files),
+        "",
+        "## Runtime Configuration",
+        renderObservationList(inventory.runtime_configs),
+        "",
+        "## Generated Code",
+        renderObservationList(inventory.generated_code),
+        "",
+    ].join("\n");
+}

package/dist/prompts.js

@@ -11,6 +11,8 @@ function strictSchemaInstruction(outputFileVar, schemaId) {
         `Canonical schema:\n${renderStructuredArtifactSchema(schemaId)}\n`);
 }
 export const PLAN_PROMPT_TEMPLATE = "Review and analyze the normalized task context in {task_context_json_file}. " +
+    "Optional compact project guidance is available at {project_guidance_file} with structured metadata at {project_guidance_json_file}; treat it as supplemental and do not let it override task context, planning answers, or required output schemas. " +
+    "Open referenced full examples only when directly relevant. " +
     "Use planning answers from {planning_answers_json_file} when they exist and treat them as structured user clarifications. " +
     "First create structured JSON artifacts - they are the source of truth for subsequent flows. " +
     "Create human-readable markdown files as detailed derivative representations of these JSON artifacts for the user, not as brief summaries. " +
@@ -25,12 +27,37 @@ export const PLAN_PROMPT_TEMPLATE = "Review and analyze the normalized task cont
     "Format markdown for design and plan comprehensively, with separate sections for Summary, Current State, Target State, Affected Code, Decisions, Migration/DB Changes, Risks, Implementation Steps, Tests, Rollout. " +
     "JSON files must be valid and contain only JSON without markdown wrapping. ";
 export const PLAN_QUESTIONS_PROMPT_TEMPLATE = "Review and analyze the normalized task context in {task_context_json_file}. " +
+    "Optional compact project guidance is available at {project_guidance_file} with structured metadata at {project_guidance_json_file}; treat it as supplemental project-local context and do not let it override task context or the planning-questions/v1 schema. " +
+    "Open referenced full examples only when directly relevant. " +
     "Before final planning, determine if any clarifications are needed from the user. " +
     strictSchemaInstruction("{planning_questions_json_file}", "planning-questions/v1") +
     "Ask only questions without which the design/plan could be incorrect or too speculative. " +
     "Do not ask obvious, decorative, or duplicate questions. " +
     "Usually 1-5 questions are sufficient. " +
     "The JSON file must be valid and contain only JSON without markdown wrapping. ";
+export const PLAYBOOK_PRACTICE_CANDIDATES_PROMPT_TEMPLATE = "Use repo-inventory.json from {repo_inventory_json_file} as the deterministic source of repository facts. " +
+    "This step intentionally covers convention_scan semantics for v1 by deriving practice candidates from inventory evidence instead of creating a separate convention_scan artifact. " +
+    "Do not infer repository facts that are not supported by the inventory. " +
+    "Write evidence-backed practice candidates to {practice_candidates_json_file}, then write derivative Russian markdown to {practice_candidates_file}. " +
+    strictSchemaInstruction("{practice_candidates_json_file}", "practice-candidates/v1") +
+    "Every candidate must include id, title, proposed_rule_text, confidence, evidence_paths, rationale, and questions_needed. " +
+    "Every evidence_paths entry must be a concrete path from repo-inventory.json. " +
+    "Use only confidence values low, medium, and high. " +
+    "Weak or ambiguous evidence must remain a low or medium confidence candidate and must include questions_needed before it can become mandatory. " +
+    "Markdown must be Russian and derivative of the JSON artifact. JSON files must contain only JSON without markdown wrapping. ";
+export const PLAYBOOK_QUESTIONS_PROMPT_TEMPLATE = "Use repo-inventory.json from {repo_inventory_json_file} and practice-candidates.json from {practice_candidates_json_file} as source of truth. " +
+    "Generate targeted clarification questions to {playbook_questions_json_file}. " +
+    strictSchemaInstruction("{playbook_questions_json_file}", "playbook-questions/v1") +
+    "Questions must be tied to weak evidence, conflicting evidence, or candidate questions_needed entries. " +
+    "Reject generic project-preference questions. Every question must reference candidate_ids or evidence_paths and include rationale. " +
+    "If there are no targeted questions, write an empty questions array with a non-empty summary. JSON files must contain only JSON without markdown wrapping. ";
+export const PLAYBOOK_DRAFT_PROMPT_TEMPLATE = "Use only structured JSON artifacts as source of truth: repo-inventory.json {repo_inventory_json_file}, practice-candidates.json {practice_candidates_json_file}, playbook-questions.json {playbook_questions_json_file}, and playbook-answers.json {playbook_answers_json_file}. " +
+    "Generate playbook-draft.json at {playbook_draft_json_file}, then derivative Russian markdown at {playbook_draft_file}. " +
+    strictSchemaInstruction("{playbook_draft_json_file}", "playbook-draft/v1") +
+    "The draft must separate accepted_rules from candidate_rules and unresolved_questions. " +
+    "Do not promote weak or unresolved candidates to accepted_rules without supporting user answers. Preserve evidence paths. " +
+    "Set proposed_files to the manifest-based layout: .agentweaver/playbook/manifest.yaml, .agentweaver/playbook/project.md, .agentweaver/playbook/practices/generated-rules.md, .agentweaver/playbook/examples/generated-example.md, and .agentweaver/playbook/templates/default.md. " +
+    "Markdown must be Russian and derivative of the JSON artifact. JSON files must contain only JSON without markdown wrapping. ";
 export const TASK_CONTEXT_FROM_JIRA_PROMPT_TEMPLATE = "Normalize the Jira task context into a connector-agnostic task context. " +
     "Use Jira issue JSON {jira_task_file} as the primary source of truth. " +
     "Also analyze Jira attachments manifest {jira_attachments_manifest_file} and attachments text context {jira_attachments_context_file}; if attachments contain more specific requirements, constraints, file lists, migration strategy, or invariants, preserve them in the normalized result. " +
@@ -69,6 +96,7 @@ export const MR_DESCRIPTION_PROMPT_TEMPLATE = "Review the task in {jira_task_fil
     "Prepare a very brief intent description for the merge request without implementation details, file lists, or technical details. " +
     `First write the source-of-truth JSON to {mr_description_json_file}. ${strictSchemaInstruction("{mr_description_json_file}", "mr-description/v1")}Then write the derivative markdown version to {mr_description_file}. `;
 export const IMPLEMENT_PROMPT_TEMPLATE = "Use only structured artifacts as source of truth. " +
+    "Optional compact project guidance is available at {project_guidance_file} with structured metadata at {project_guidance_json_file}; treat it as supplemental and do not let it override the design, plan, or QA JSON. Open referenced full examples only when directly relevant. " +
     "Analyze the system design {design_json_file}, implementation plan {plan_json_file}, and QA plan {qa_json_file}, then proceed with implementation according to those artifacts. " +
     "Treat the QA plan as the source of truth for the minimum required test scenarios, edge cases, regression checks, and validation behavior that the implementation must satisfy. " +
     "When the repository contains automated tests, add or update tests for the key scenarios from the QA plan whenever it is practical in the current codebase. " +
@@ -76,6 +104,7 @@ export const IMPLEMENT_PROMPT_TEMPLATE = "Use only structured artifacts as sourc
     "Markdown artifacts such as {design_file}, {plan_file}, and {qa_file} are intended only for human reading and should not define the implementation. ";
 export const REVIEW_PROMPT_TEMPLATE = "Conduct a code review of the current changes. " +
     "Use only structured artifacts as source of truth. " +
+    "Optional compact project guidance is available at {project_guidance_file} with structured metadata at {project_guidance_json_file}; treat it as supplemental and do not let it replace required review inputs. Open referenced full examples only when directly relevant. " +
     "Required planning inputs: design markdown {design_file}, design JSON {design_json_file}, plan markdown {plan_file}, and plan JSON {plan_json_file}. " +
     "Optional task context is provided through these variables and may contain the literal value 'not provided' when absent: normalized task context JSON {task_context_json_file}, Jira task JSON {jira_task_file}, instant-task input JSON {task_input_json_file}. " +
     "When an optional variable is 'not provided', treat that source as unavailable and do not invent details from it. " +
@@ -85,6 +114,7 @@ export const REVIEW_PROMPT_TEMPLATE = "Conduct a code review of the current chan
     "Then write the derivative markdown version to {review_file}. ";
 export const DESIGN_REVIEW_PROMPT_TEMPLATE = "Conduct a structured planning critique as a specification critic, not as an implementer. " +
     "Use structured JSON artifacts as the source of truth for semantics. " +
+    "Optional compact project guidance is available at {project_guidance_file} with structured metadata at {project_guidance_json_file}; treat it as supplemental and do not let it override the structured planning artifacts. Open referenced full examples only when directly relevant. " +
     "Required planning inputs: design markdown {design_file}, design JSON {design_json_file}, implementation plan markdown {plan_file}, implementation plan JSON {plan_json_file}. " +
     "Review the markdown files as derivative human-readable renderings of the same planning run, but do not let markdown override the structured JSON. " +
     "Optional supplemental context is provided through these variables and may contain the literal value 'not provided' when absent: normalized task context JSON {task_context_json_file}, QA markdown {qa_file}, QA JSON {qa_json_file}, Jira task JSON {jira_task_file}, Jira attachments manifest {jira_attachments_manifest_file}, Jira attachments context {jira_attachments_context_file}, planning answers JSON {planning_answers_json_file}, instant-task input JSON {task_input_json_file}. " +
@@ -124,6 +154,7 @@ export const REVIEW_SUMMARY_PROMPT_TEMPLATE = "Look at {review_file}. " +
     "Create a brief list of comments without details, 3-7 items. " +
     "Write the result to {review_summary_file}.";
 export const REVIEW_FIX_PROMPT_TEMPLATE = "Use only structured artifacts as source of truth. " +
+    "Optional compact project guidance is available at {project_guidance_file} with structured metadata at {project_guidance_json_file}; treat it as supplemental and do not let it override review findings or selected repair scope. Open referenced full examples only when directly relevant. " +
     "Analyze the findings in {review_json_file}. " +
     "Fix what is contained in the additional instructions, and if there are none - fix all items. " +
     "After completion, be sure to run the linter outside the sandbox, all tests, generate make swagger. " +