framework-aidf 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (154) hide show
  1. package/CHANGELOG.md +174 -0
  2. package/INSTALLATION.md +140 -0
  3. package/LICENSE +21 -0
  4. package/QODER.md +88 -0
  5. package/README.md +142 -2
  6. package/UTILISATION.md +188 -0
  7. package/assets/adapters/qoder/agents/aidf-orchestrator.md +30 -0
  8. package/assets/adapters/qoder/rules/00-core.md +28 -0
  9. package/assets/adapters/qoder/rules/10-security.md +33 -0
  10. package/assets/adapters/qoder/rules/20-context.md +39 -0
  11. package/assets/core/AGENTS.fragment.md +18 -0
  12. package/assets/core/AIDF.md +107 -0
  13. package/assets/docs/APPFLOW.md +66 -0
  14. package/assets/docs/BACKEND.md +71 -0
  15. package/assets/docs/CHANGELOG.md +25 -0
  16. package/assets/docs/CONVENTIONS.md +95 -0
  17. package/assets/docs/DECISIONS.md +60 -0
  18. package/assets/docs/PLAN.md +53 -0
  19. package/assets/docs/PRD.md +88 -0
  20. package/assets/docs/SECURITY.md +94 -0
  21. package/assets/docs/TRD.md +78 -0
  22. package/assets/docs/UI-UX.md +71 -0
  23. package/assets/docs/constitution.md +86 -0
  24. package/assets/hooks/audit.mjs +45 -0
  25. package/assets/hooks/session-context.mjs +53 -0
  26. package/assets/integrations/spec-kit/mapping.yaml +92 -0
  27. package/assets/knowledge/best-practices/testing.md +53 -0
  28. package/assets/knowledge/best-practices/web-dev-baseline.md +39 -0
  29. package/assets/knowledge/rules/api.md +45 -0
  30. package/assets/knowledge/rules/sql.md +44 -0
  31. package/assets/knowledge/rules/typescript.md +50 -0
  32. package/assets/knowledge/security-references/owasp-baseline.md +58 -0
  33. package/assets/registry/activation-map.yaml +83 -0
  34. package/assets/registry/dependencies.yaml +35 -0
  35. package/assets/registry/skills.yaml +541 -0
  36. package/assets/registry/sources.yaml +396 -0
  37. package/assets/schemas/architecture/v1.json +110 -0
  38. package/assets/schemas/constraints/v1.json +93 -0
  39. package/assets/schemas/decision/v1.json +106 -0
  40. package/assets/schemas/discovery/v1.json +91 -0
  41. package/assets/schemas/requirement/v1.json +136 -0
  42. package/assets/schemas/security/threat-model/v1.json +127 -0
  43. package/assets/schemas/test-plan/v1.json +108 -0
  44. package/assets/skills/aidf-architecture-review/SKILL.md +49 -0
  45. package/assets/skills/aidf-backend-implementation/SKILL.md +47 -0
  46. package/assets/skills/aidf-database-design/SKILL.md +48 -0
  47. package/assets/skills/aidf-devops-engineering/SKILL.md +41 -0
  48. package/assets/skills/aidf-documentation-maintenance/SKILL.md +41 -0
  49. package/assets/skills/aidf-frontend-implementation/SKILL.md +44 -0
  50. package/assets/skills/aidf-phase-transition/SKILL.md +48 -0
  51. package/assets/skills/aidf-product-analysis/SKILL.md +47 -0
  52. package/assets/skills/aidf-project-context/SKILL.md +57 -0
  53. package/assets/skills/aidf-requirements-engineering/SKILL.md +52 -0
  54. package/assets/skills/aidf-security-review/SKILL.md +57 -0
  55. package/assets/skills/aidf-testing-validation/SKILL.md +48 -0
  56. package/assets/skills/aidf-ui-ux-implementation/SKILL.md +43 -0
  57. package/assets/workflows/gates.yaml +232 -0
  58. package/assets/workflows/phases.yaml +161 -0
  59. package/bin/aidf.mjs +12 -0
  60. package/demo/run-demo.mjs +97 -0
  61. package/docs/aidf/ADR-001-artefacts-architectur.md +126 -0
  62. package/docs/aidf/ADR-002-requirements-registry.md +145 -0
  63. package/docs/aidf/ADR-003-traceability-chain.md +145 -0
  64. package/docs/aidf/ADR-004-markdown-generation.md +134 -0
  65. package/docs/aidf/ADR-005-validation-and-tests.md +170 -0
  66. package/docs/aidf/ADR-006-cli-commands.md +189 -0
  67. package/docs/aidf/ADR-007-compatibility-and-migration.md +119 -0
  68. package/docs/aidf/ADR-008-schema-versioning.md +115 -0
  69. package/docs/aidf/ADR-009-artefacts-scope.md +84 -0
  70. package/docs/aidf/ARCHITECTURE.md +137 -0
  71. package/docs/aidf/COMPATIBILITY.md +90 -0
  72. package/docs/aidf/DECISIONS.md +200 -0
  73. package/docs/aidf/FRAMEWORK.md +38 -0
  74. package/docs/aidf/IDE-QODER.md +61 -0
  75. package/docs/aidf/INSTALL.md +99 -0
  76. package/docs/aidf/INVENTORY.md +72 -0
  77. package/docs/aidf/L1-ARCHITECTURE-RAPPORT.md +353 -0
  78. package/docs/aidf/LIMITATIONS.md +69 -0
  79. package/docs/aidf/MATRICE-0.1.0-vers-0.2.0.md +155 -0
  80. package/docs/aidf/SECURITY.md +86 -0
  81. package/docs/aidf/SKILLS.md +78 -0
  82. package/docs/aidf/SPECKIT.md +67 -0
  83. package/docs/aidf/USAGE.md +113 -0
  84. package/docs/aidf/VALIDATION.md +55 -0
  85. package/package.json +37 -4
  86. package/src/cli.mjs +148 -0
  87. package/src/commands/artefacts.mjs +129 -0
  88. package/src/commands/config.mjs +130 -0
  89. package/src/commands/context.mjs +55 -0
  90. package/src/commands/decision.mjs +142 -0
  91. package/src/commands/design.mjs +141 -0
  92. package/src/commands/docs.mjs +133 -0
  93. package/src/commands/doctor.mjs +210 -0
  94. package/src/commands/evidence.mjs +178 -0
  95. package/src/commands/install.mjs +154 -0
  96. package/src/commands/release.mjs +214 -0
  97. package/src/commands/requirements.mjs +196 -0
  98. package/src/commands/resources.mjs +181 -0
  99. package/src/commands/scan.mjs +139 -0
  100. package/src/commands/security.mjs +97 -0
  101. package/src/commands/setup.mjs +68 -0
  102. package/src/commands/skills.mjs +204 -0
  103. package/src/commands/speckit.mjs +78 -0
  104. package/src/commands/tests.mjs +81 -0
  105. package/src/commands/traceability.mjs +116 -0
  106. package/src/commands/uninstall.mjs +238 -0
  107. package/src/commands/validate.mjs +84 -0
  108. package/src/commands/workflow.mjs +137 -0
  109. package/src/core/adapters/base.mjs +32 -0
  110. package/src/core/adapters/generic.mjs +70 -0
  111. package/src/core/adapters/index.mjs +24 -0
  112. package/src/core/adapters/opencode.mjs +115 -0
  113. package/src/core/adapters/qoder.mjs +228 -0
  114. package/src/core/artefacts/index.mjs +1 -0
  115. package/src/core/artefacts/validation.mjs +161 -0
  116. package/src/core/bootstrap.mjs +179 -0
  117. package/src/core/config.mjs +123 -0
  118. package/src/core/context.mjs +187 -0
  119. package/src/core/design-engineering/complexity-classifier.mjs +78 -0
  120. package/src/core/design-engineering/engine.mjs +197 -0
  121. package/src/core/design-engineering/fallback/mockups.mjs +221 -0
  122. package/src/core/design-engineering/fallback/wireframes.mjs +114 -0
  123. package/src/core/design-engineering/figma/validators.mjs +178 -0
  124. package/src/core/design-engineering/index.mjs +9 -0
  125. package/src/core/design-engineering/visual-parity/capture.mjs +172 -0
  126. package/src/core/detect.mjs +220 -0
  127. package/src/core/docsgen.mjs +175 -0
  128. package/src/core/evidence.mjs +210 -0
  129. package/src/core/installer.mjs +377 -0
  130. package/src/core/manifest.mjs +53 -0
  131. package/src/core/paths.mjs +94 -0
  132. package/src/core/requirements/index.mjs +13 -0
  133. package/src/core/requirements/registry.mjs +234 -0
  134. package/src/core/resource-inventory.mjs +434 -0
  135. package/src/core/resources.mjs +280 -0
  136. package/src/core/security/threat-model.mjs +235 -0
  137. package/src/core/skills.mjs +353 -0
  138. package/src/core/source-skills.mjs +213 -0
  139. package/src/core/speckit.mjs +195 -0
  140. package/src/core/technology-decision/analyzer-deterministic.mjs +240 -0
  141. package/src/core/technology-decision/engine.mjs +157 -0
  142. package/src/core/technology-decision/generator.mjs +204 -0
  143. package/src/core/technology-decision/index.mjs +17 -0
  144. package/src/core/technology-decision/options/index.mjs +10 -0
  145. package/src/core/testplan.mjs +176 -0
  146. package/src/core/traceability/chain.mjs +488 -0
  147. package/src/core/traceability/index.mjs +12 -0
  148. package/src/core/workflow.mjs +471 -0
  149. package/src/util/args.mjs +69 -0
  150. package/src/util/frontmatter.mjs +26 -0
  151. package/src/util/fsx.mjs +208 -0
  152. package/src/util/logger.mjs +74 -0
  153. package/src/util/text.mjs +66 -0
  154. package/src/util/yaml.mjs +379 -0
@@ -0,0 +1,9 @@
1
+ // L3: Design Engineering Engine
2
+ // Main entry point for the design engineering engine
3
+
4
+ export { classifyComplexity } from './complexity-classifier.mjs';
5
+ export { runDesignWorkflow } from './engine.mjs';
6
+ export { validateFigma, testConnection, verifyIdentity, checkPermissions, checkFile } from './figma/validators.mjs';
7
+ export { generateSVGWireframe, generateHTMLWireframe } from './fallback/wireframes.mjs';
8
+ export { generateCSSMockup } from './fallback/mockups.mjs';
9
+ export { captureReference, captureImplementation, generateDiff, createReviewRequest, processReview } from './visual-parity/capture.mjs';
@@ -0,0 +1,172 @@
1
+ /**
2
+ * L3: Visual Parity Capture and Comparison
3
+ * Captures reference images and implementation screenshots for comparison.
4
+ */
5
+
6
+ /**
7
+ * Capture reference image from design source.
8
+ */
9
+ export async function captureReference(designSource, options = {}) {
10
+ // If Figma: capture from Figma (placeholder)
11
+ if (designSource?.type === 'figma') {
12
+ // In production, use Figma API to capture
13
+ return {
14
+ type: 'reference',
15
+ source: designSource,
16
+ imageData: null, // Placeholder
17
+ timestamp: new Date().toISOString(),
18
+ note: 'Figma capture not implemented'
19
+ };
20
+ }
21
+
22
+ // If local design: use provided image
23
+ if (designSource?.type === 'local' && designSource?.imagePath) {
24
+ return {
25
+ type: 'reference',
26
+ source: designSource,
27
+ imageData: null, // Would read file here
28
+ timestamp: new Date().toISOString()
29
+ };
30
+ }
31
+
32
+ // No reference available
33
+ return { type: 'missing_reference', reason: 'No reference image available' };
34
+ }
35
+
36
+ /**
37
+ * Capture implementation screenshot.
38
+ */
39
+ export async function captureImplementation(implementationUrl, options = {}) {
40
+ // Use browser automation if available
41
+ // For now, return placeholder
42
+ return {
43
+ type: 'implementation',
44
+ source: implementationUrl,
45
+ imageData: null, // Would capture screenshot here
46
+ timestamp: new Date().toISOString(),
47
+ note: 'Implementation capture not implemented'
48
+ };
49
+ }
50
+
51
+ /**
52
+ * Generate diff between reference and implementation.
53
+ */
54
+ export function generateDiff(reference, implementation, options = {}) {
55
+ const threshold = options.threshold || 0.05; // 5% difference threshold
56
+
57
+ if (!reference?.imageData || !implementation?.imageData) {
58
+ return {
59
+ type: 'diff',
60
+ comparison: 'skipped',
61
+ reason: 'Missing images',
62
+ differencePercentage: null,
63
+ threshold
64
+ };
65
+ }
66
+
67
+ // In production, use pixelmatch or similar
68
+ // For now, return placeholder
69
+ return {
70
+ type: 'diff',
71
+ comparison: 'pending_comparison',
72
+ reason: 'Image comparison not implemented',
73
+ differencePercentage: null,
74
+ threshold
75
+ };
76
+ }
77
+
78
+ /**
79
+ * Create review request for human approval.
80
+ */
81
+ export function createReviewRequest(diffResult, reference, implementation) {
82
+ return {
83
+ type: 'review_request',
84
+ reference: reference || null,
85
+ implementation: implementation || null,
86
+ diffResult,
87
+ reviewInstructions: [
88
+ 'Compare reference and implementation side-by-side',
89
+ 'Check for visual differences',
90
+ 'Verify accessibility compliance',
91
+ 'Check responsiveness',
92
+ 'Approve or request changes'
93
+ ],
94
+ approvalRequired: true, // Always require human approval
95
+ approvers: ['designer', 'frontend-dev', 'accessibility-expert']
96
+ };
97
+ }
98
+
99
+ /**
100
+ * Process review (human must approve).
101
+ */
102
+ export async function processReview(reviewRequest) {
103
+ const { reference, implementation, diffResult } = reviewRequest;
104
+
105
+ // Display to human reviewer (side-by-side comparison)
106
+ const reviewOutput = {
107
+ reference,
108
+ implementation,
109
+ diffResult,
110
+ summary: {
111
+ status: diffResult?.comparison || 'skipped',
112
+ differencePercentage: diffResult?.differencePercentage || null,
113
+ threshold: diffResult?.threshold || null
114
+ }
115
+ };
116
+
117
+ // Human review happens here (outside system)
118
+ // Reviewer either:
119
+ // - Approves: changes approved
120
+ // - Rejects: changes requested
121
+
122
+ // System NEVER auto-approves based on diff score
123
+ return {
124
+ status: 'awaiting_review', // System cannot approve
125
+ reviewOutput,
126
+ canAutoApprove: false, // Always requires human
127
+ autoApprovalScore: diffResult?.differencePercentage || null,
128
+ autoApprovalThreshold: diffResult?.threshold || null
129
+ };
130
+ }
131
+
132
+ /**
133
+ * Generate visual parity report.
134
+ */
135
+ export function generateVisualParityReport(reference, implementation, diffResult, reviewResult) {
136
+ return {
137
+ type: 'visual_parity_report',
138
+ timestamp: new Date().toISOString(),
139
+ reference: {
140
+ type: reference?.type || 'missing',
141
+ source: reference?.source || null,
142
+ timestamp: reference?.timestamp || null
143
+ },
144
+ implementation: {
145
+ type: implementation?.type || 'missing',
146
+ source: implementation?.source || null,
147
+ timestamp: implementation?.timestamp || null
148
+ },
149
+ diff: {
150
+ type: diffResult?.type || 'missing',
151
+ comparison: diffResult?.comparison || 'skipped',
152
+ differencePercentage: diffResult?.differencePercentage || null,
153
+ threshold: diffResult?.threshold || null
154
+ },
155
+ review: {
156
+ status: reviewResult?.status || 'not_started',
157
+ approved: reviewResult?.approved || null,
158
+ approver: reviewResult?.approver || null,
159
+ comments: reviewResult?.comments || null
160
+ },
161
+ verdict: reviewResult?.approved
162
+ ? 'APPROVED'
163
+ : reviewResult?.status === 'rejected'
164
+ ? 'REJECTED'
165
+ : 'PENDING_REVIEW',
166
+ notes: reviewResult?.approved
167
+ ? 'Visual parity confirmed by human reviewer'
168
+ : reviewResult?.status === 'rejected'
169
+ ? 'Visual changes requested by reviewer'
170
+ : 'Waiting for human review'
171
+ };
172
+ }
@@ -0,0 +1,220 @@
1
+ import os from 'node:os';
2
+ import path from 'node:path';
3
+ import { execFile } from 'node:child_process';
4
+ import { promisify } from 'node:util';
5
+ import { existsSync } from '../util/fsx.mjs';
6
+ import { readJson } from '../util/fsx.mjs';
7
+
8
+ const execFileAsync = promisify(execFile);
9
+
10
+ export async function runTool(command, args = [], options = {}) {
11
+ const { cwd = process.cwd(), timeout = 5000 } = options;
12
+ try {
13
+ const { stdout, stderr } = await execFileAsync(command, args, {
14
+ cwd,
15
+ timeout,
16
+ windowsHide: true,
17
+ maxBuffer: 1024 * 1024,
18
+ shell: false,
19
+ });
20
+ return { ok: true, stdout: stdout.trim(), stderr: stderr.trim() };
21
+ } catch (error) {
22
+ return {
23
+ ok: false,
24
+ stdout: (error.stdout ?? '').toString().trim(),
25
+ stderr: (error.stderr ?? '').toString().trim(),
26
+ code: error.code,
27
+ message: error.message,
28
+ };
29
+ }
30
+ }
31
+
32
+ async function which(command) {
33
+ const probe = process.platform === 'win32' ? 'where' : 'which';
34
+ const result = await runTool(probe, [command]);
35
+ return result.ok ? result.stdout.split(/\r?\n/)[0] : null;
36
+ }
37
+
38
+ export async function detectEnvironment() {
39
+ const home = os.homedir();
40
+ const qoderHome = path.join(home, '.qoder');
41
+ const qoderApp = process.platform === 'win32'
42
+ ? path.join(process.env.LOCALAPPDATA ?? '', 'Programs', 'Qoder IDE')
43
+ : null;
44
+ const tools = {};
45
+ for (const tool of ['node', 'npm', 'pnpm', 'yarn', 'bun', 'python', 'uv', 'git', 'gh', 'specify', 'qodercli', 'docker']) {
46
+ tools[tool] = await which(tool);
47
+ }
48
+ const nodeVersion = process.versions.node;
49
+ const specifyVersion = tools.specify ? await runTool(tools.specify, ['--version']) : null;
50
+ return {
51
+ os: {
52
+ platform: process.platform,
53
+ release: os.release(),
54
+ arch: os.arch(),
55
+ version: os.version ? os.version() : '',
56
+ },
57
+ shell: process.env.SHELL ?? process.env.ComSpec ?? 'unknown',
58
+ home,
59
+ tools,
60
+ node: {
61
+ version: nodeVersion,
62
+ execPath: process.execPath,
63
+ },
64
+ ide: {
65
+ qoder: {
66
+ installed: existsSync(qoderHome) || Boolean(qoderApp && existsSync(qoderApp)),
67
+ home: existsSync(qoderHome) ? qoderHome : null,
68
+ app: qoderApp && existsSync(qoderApp) ? qoderApp : null,
69
+ projectRules: '.qoder/rules',
70
+ projectSkills: '.qoder/skills',
71
+ projectAgents: '.qoder/agents',
72
+ projectSettings: '.qoder/settings.json',
73
+ agentsMd: true,
74
+ },
75
+ },
76
+ specKit: {
77
+ cliPath: tools.specify,
78
+ cliVersion: specifyVersion?.ok ? specifyVersion.stdout.split(/\r?\n/)[0] : null,
79
+ },
80
+ };
81
+ }
82
+
83
+ const LANGUAGE_MARKERS = [
84
+ { file: 'package.json', language: 'JavaScript/TypeScript', ecosystem: 'node' },
85
+ { file: 'tsconfig.json', language: 'TypeScript', ecosystem: 'node' },
86
+ { file: 'pyproject.toml', language: 'Python', ecosystem: 'python' },
87
+ { file: 'requirements.txt', language: 'Python', ecosystem: 'python' },
88
+ { file: 'Cargo.toml', language: 'Rust', ecosystem: 'rust' },
89
+ { file: 'go.mod', language: 'Go', ecosystem: 'go' },
90
+ { file: 'pom.xml', language: 'Java', ecosystem: 'java' },
91
+ { file: 'build.gradle', language: 'Java/Kotlin', ecosystem: 'java' },
92
+ { file: 'composer.json', language: 'PHP', ecosystem: 'php' },
93
+ { file: 'Gemfile', language: 'Ruby', ecosystem: 'ruby' },
94
+ { file: '*.csproj', language: 'C#', ecosystem: 'dotnet' },
95
+ ];
96
+
97
+ const FRAMEWORK_DEPS = {
98
+ react: 'React',
99
+ 'react-dom': 'React',
100
+ next: 'Next.js',
101
+ vue: 'Vue',
102
+ nuxt: 'Nuxt',
103
+ svelte: 'Svelte',
104
+ '@angular/core': 'Angular',
105
+ express: 'Express',
106
+ fastify: 'Fastify',
107
+ nestjs: 'NestJS',
108
+ '@nestjs/core': 'NestJS',
109
+ vite: 'Vite',
110
+ tailwindcss: 'Tailwind CSS',
111
+ prisma: 'Prisma',
112
+ '@prisma/client': 'Prisma',
113
+ drizzle: 'Drizzle ORM',
114
+ 'drizzle-orm': 'Drizzle ORM',
115
+ vitest: 'Vitest',
116
+ jest: 'Jest',
117
+ playwright: 'Playwright',
118
+ '@playwright/test': 'Playwright',
119
+ cypress: 'Cypress',
120
+ typescript: 'TypeScript',
121
+ zod: 'Zod',
122
+ trpc: 'tRPC',
123
+ graphql: 'GraphQL',
124
+ electron: 'Electron',
125
+ };
126
+
127
+ export async function detectProject(root) {
128
+ const languages = [];
129
+ for (const marker of LANGUAGE_MARKERS) {
130
+ if (marker.file.includes('*')) continue;
131
+ if (existsSync(path.join(root, marker.file))) {
132
+ languages.push({ language: marker.language, ecosystem: marker.ecosystem, marker: marker.file });
133
+ }
134
+ }
135
+
136
+ const packageJson = await readJson(path.join(root, 'package.json'), null);
137
+ const frameworks = [];
138
+ if (packageJson) {
139
+ const deps = { ...(packageJson.dependencies ?? {}), ...(packageJson.devDependencies ?? {}) };
140
+ for (const [dep, label] of Object.entries(FRAMEWORK_DEPS)) {
141
+ if (deps[dep]) frameworks.push(label);
142
+ }
143
+ }
144
+
145
+ const tests = {
146
+ packageManager: packageJson ? (existsSync(path.join(root, 'package-lock.json')) ? 'npm'
147
+ : existsSync(path.join(root, 'pnpm-lock.yaml')) ? 'pnpm'
148
+ : existsSync(path.join(root, 'yarn.lock')) ? 'yarn'
149
+ : existsSync(path.join(root, 'bun.lockb')) ? 'bun' : 'unknown') : null,
150
+ scripts: packageJson?.scripts ?? {},
151
+ directories: ['tests', 'test', '__tests__', 'spec', 'e2e'].filter((d) => existsSync(path.join(root, d))),
152
+ files: [],
153
+ runners: [],
154
+ };
155
+ if (packageJson) {
156
+ if (packageJson.devDependencies?.vitest || packageJson.dependencies?.vitest) tests.runners.push('vitest');
157
+ if (packageJson.devDependencies?.jest || packageJson.dependencies?.jest) tests.runners.push('jest');
158
+ if (packageJson.devDependencies?.['@playwright/test']) tests.runners.push('playwright');
159
+ if (packageJson.devDependencies?.mocha) tests.runners.push('mocha');
160
+ if (packageJson.scripts?.test) tests.runners.push('npm:test');
161
+ }
162
+ if (existsSync(path.join(root, 'pytest.ini')) || existsSync(path.join(root, 'conftest.py'))) tests.runners.push('pytest');
163
+ if (existsSync(path.join(root, 'phpunit.xml')) || existsSync(path.join(root, 'phpunit.xml.dist'))) tests.runners.push('phpunit');
164
+
165
+ const git = await runTool('git', ['rev-parse', '--is-inside-work-tree'], { cwd: root });
166
+ const gitInfo = {
167
+ repository: git.ok && git.stdout === 'true',
168
+ branch: null,
169
+ head: null,
170
+ dirty: null,
171
+ };
172
+ if (gitInfo.repository) {
173
+ const branch = await runTool('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: root });
174
+ const head = await runTool('git', ['rev-parse', '--short', 'HEAD'], { cwd: root });
175
+ const status = await runTool('git', ['status', '--porcelain'], { cwd: root });
176
+ gitInfo.branch = branch.ok ? branch.stdout : null;
177
+ gitInfo.head = head.ok ? head.stdout : null;
178
+ gitInfo.dirty = status.ok ? status.stdout.split(/\r?\n/).filter(Boolean).length : null;
179
+ }
180
+
181
+ const aiConfig = {
182
+ agentsMd: existsSync(path.join(root, 'AGENTS.md')),
183
+ claudeMd: existsSync(path.join(root, 'CLAUDE.md')),
184
+ qoderRules: existsSync(path.join(root, '.qoder', 'rules')),
185
+ qoderSkills: existsSync(path.join(root, '.qoder', 'skills')),
186
+ qoderSettings: existsSync(path.join(root, '.qoder', 'settings.json')),
187
+ cursorRules: existsSync(path.join(root, '.cursor', 'rules')),
188
+ copilotInstructions: existsSync(path.join(root, '.github', 'copilot-instructions.md')),
189
+ agentDir: existsSync(path.join(root, '.agent')),
190
+ specifyDir: existsSync(path.join(root, '.specify')),
191
+ };
192
+
193
+ const docs = {
194
+ readme: existsSync(path.join(root, 'README.md')),
195
+ docsDir: existsSync(path.join(root, 'docs')),
196
+ aidfDir: existsSync(path.join(root, '.aidf')),
197
+ };
198
+
199
+ const ci = ['.github/workflows', '.gitlab-ci.yml', 'azure-pipelines.yml', 'Jenkinsfile']
200
+ .filter((p) => existsSync(path.join(root, p)));
201
+
202
+ return {
203
+ root,
204
+ languages,
205
+ frameworks: [...new Set(frameworks)],
206
+ packageJson: packageJson
207
+ ? {
208
+ name: packageJson.name ?? null,
209
+ version: packageJson.version ?? null,
210
+ type: packageJson.type ?? null,
211
+ scripts: packageJson.scripts ?? {},
212
+ }
213
+ : null,
214
+ tests,
215
+ git: gitInfo,
216
+ aiConfig,
217
+ docs,
218
+ ci,
219
+ };
220
+ }
@@ -0,0 +1,175 @@
1
+ import path from 'node:path';
2
+ import { aidfPaths } from './paths.mjs';
3
+ import {
4
+ readJson, writeJson, writeAtomic, ensureDir, exists, readText, sha256Text, toPosix,
5
+ } from '../util/fsx.mjs';
6
+ import { loadRequirementsRegistry } from './requirements/registry.mjs';
7
+ import { loadTestPlan } from './testplan.mjs';
8
+ import { loadThreatModel, renderThreatModelMarkdown } from './security/threat-model.mjs';
9
+ import { collectArtefactFiles } from './traceability/chain.mjs';
10
+
11
+ export const GENERATED_DIR = '.aidf/docs/generated';
12
+ export const GENERATED_INDEX = '.aidf/docs/generated/.generated.json';
13
+
14
+ function generatedHeader(sourceId, sourceHash) {
15
+ return [
16
+ '<!-- AIDF-GENERATED',
17
+ `source: ${sourceId}`,
18
+ `source-sha256: ${sourceHash}`,
19
+ `generated-at: ${new Date().toISOString()}`,
20
+ '-->',
21
+ '',
22
+ ].join('\n');
23
+ }
24
+
25
+ function renderRequirements(registry) {
26
+ const lines = ['# Requirements', ''];
27
+ lines.push(`Total: ${registry.requirements?.length ?? 0}`);
28
+ lines.push('');
29
+ lines.push('| ID | Type | Status | Priority | Title |');
30
+ lines.push('|---|---|---|---|---|');
31
+ for (const r of registry.requirements ?? []) {
32
+ lines.push(`| ${r.id} | ${r.type} | ${r.status} | ${r.priority} | ${r.title} |`);
33
+ }
34
+ lines.push('');
35
+ for (const r of registry.requirements ?? []) {
36
+ const criteria = r.acceptanceCriteria ?? [];
37
+ if (criteria.length === 0) continue;
38
+ lines.push(`## ${r.id} — acceptance criteria`);
39
+ lines.push('');
40
+ for (const c of criteria) {
41
+ const text = typeof c === 'string' ? c : (c.description ?? c.text ?? c.id);
42
+ lines.push(`- ${text}`);
43
+ }
44
+ lines.push('');
45
+ }
46
+ return `${lines.join('\n')}\n`;
47
+ }
48
+
49
+ function renderTestPlan(plan) {
50
+ if (!plan) return null;
51
+ const lines = [`# Test Plan ${plan.id}`, ''];
52
+ lines.push(`- Status: ${plan.status}`);
53
+ lines.push(`- Cases: ${plan.testCases?.length ?? 0}`);
54
+ lines.push(`- Covers: ${(plan.links?.covers ?? []).join(', ') || 'none'}`);
55
+ lines.push('');
56
+ lines.push('## Strategy');
57
+ lines.push('');
58
+ lines.push(plan.strategy?.approach ?? '');
59
+ lines.push('');
60
+ lines.push(`Mock policy: ${plan.strategy?.mockPolicy ?? 'n/a'}`);
61
+ lines.push('');
62
+ lines.push('## Test cases');
63
+ lines.push('');
64
+ lines.push('| ID | Type | Status | Requirement | Command |');
65
+ lines.push('|---|---|---|---|---|');
66
+ for (const tc of plan.testCases ?? []) {
67
+ lines.push(`| ${tc.id} | ${tc.type} | ${tc.status} | ${tc.requirement ?? '-'} | \`${tc.command}\` |`);
68
+ }
69
+ lines.push('');
70
+ return `${lines.join('\n')}\n`;
71
+ }
72
+
73
+ function renderDecisions(artefacts) {
74
+ const decisions = [...artefacts.values()].filter((a) => a.type === 'decision');
75
+ if (decisions.length === 0) return null;
76
+ const lines = ['# Architecture Decisions', ''];
77
+ for (const d of decisions.sort((a, b) => String(a.id).localeCompare(String(b.id)))) {
78
+ lines.push(`## ${d.id} — ${d.title ?? d.id}`);
79
+ lines.push('');
80
+ lines.push(`- Status: ${d.status}`);
81
+ if (d.document?.recommendation?.stack) {
82
+ lines.push('- Recommendation:');
83
+ for (const s of d.document.recommendation.stack) {
84
+ lines.push(` - ${s.component}: ${s.option}${s.reason ? ` — ${s.reason}` : ''}`);
85
+ }
86
+ }
87
+ if (d.document?.humanApproval) {
88
+ lines.push(`- Human approval required: ${d.document.humanApproval.required ? 'yes' : 'no'}`);
89
+ }
90
+ lines.push('');
91
+ }
92
+ return `${lines.join('\n')}\n`;
93
+ }
94
+
95
+ /**
96
+ * Collect the generated Markdown documents for all canonical artefacts.
97
+ * Returns [{ file, content, sourceId, sourceHash, sourcePath }].
98
+ */
99
+ export async function collectGeneratedDocs(root) {
100
+ const docs = [];
101
+ const push = async (file, content, sourceId, sourcePath, sourceObj) => {
102
+ if (content == null) return;
103
+ const sourceHash = sha256Text(JSON.stringify(sourceObj ?? content));
104
+ docs.push({ file, content, sourceId, sourceHash, sourcePath });
105
+ };
106
+
107
+ const registry = await loadRequirementsRegistry(root);
108
+ await push('REQUIREMENTS.md', renderRequirements(registry), 'requirements',
109
+ toPosix(aidfPaths(root).artefacts.requirements), registry);
110
+
111
+ const plan = await loadTestPlan(root);
112
+ await push('TEST-PLAN.md', renderTestPlan(plan), plan?.id ?? 'test-plan',
113
+ toPosix(aidfPaths(root).artefacts.testPlan), plan);
114
+
115
+ const tm = await loadThreatModel(root);
116
+ if (tm) {
117
+ await push('THREAT-MODEL.md', renderThreatModelMarkdown(tm), tm.id,
118
+ toPosix(aidfPaths(root).artefacts['security/threat-model']), tm);
119
+ }
120
+
121
+ const artefacts = await collectArtefactFiles(root);
122
+ const artefactMap = new Map([...artefacts].map((f) => [f.id, f.body]));
123
+ await push('DECISIONS.md', renderDecisions(artefactMap), 'decisions',
124
+ toPosix(aidfPaths(root).artefacts.decisions), [...artefactMap.values()].filter((a) => a.type === 'decision'));
125
+
126
+ return docs;
127
+ }
128
+
129
+ /**
130
+ * Generate (or check) Markdown views of canonical artefacts.
131
+ * options.check: do not write; only report what would change and divergences.
132
+ */
133
+ export async function generateDocs(root, options = {}) {
134
+ const docs = await collectGeneratedDocs(root);
135
+ const dir = path.join(root, GENERATED_DIR);
136
+ const indexPath = path.join(root, GENERATED_INDEX);
137
+ const previousIndex = options.check ? await readJson(indexPath, {}) : await readJson(indexPath, {});
138
+ const previous = previousIndex.files ?? previousIndex;
139
+ const results = [];
140
+
141
+ for (const doc of docs) {
142
+ const target = path.join(dir, doc.file);
143
+ const content = `${generatedHeader(doc.sourceId, doc.sourceHash)}${doc.content}`;
144
+ const existed = await exists(target);
145
+ const previousOutputHash = previous[doc.file]?.outputHash ?? null;
146
+ let diverged = false;
147
+ if (existed && previousOutputHash) {
148
+ const current = await readText(target);
149
+ diverged = sha256Text(current) !== previousOutputHash;
150
+ }
151
+ let action = 'unchanged';
152
+ if (options.check) {
153
+ action = !existed ? 'missing' : diverged ? 'diverged' : 'current';
154
+ } else {
155
+ await ensureDir(dir);
156
+ await writeAtomic(target, content);
157
+ action = existed ? 'regenerated' : 'created';
158
+ }
159
+ results.push({
160
+ file: toPosix(path.join(GENERATED_DIR, doc.file)),
161
+ sourceId: doc.sourceId,
162
+ action,
163
+ diverged,
164
+ manualEdit: diverged,
165
+ });
166
+ previous[doc.file] = { sourceId: doc.sourceId, sourceHash: doc.sourceHash, outputHash: sha256Text(content) };
167
+ }
168
+
169
+ if (!options.check && docs.length > 0) {
170
+ await ensureDir(dir);
171
+ await writeJson(indexPath, { generatedAt: new Date().toISOString(), files: { ...(previousIndex.files ?? {}), ...previous } });
172
+ }
173
+
174
+ return { generated: results, directory: GENERATED_DIR, checkedOnly: Boolean(options.check) };
175
+ }