qfai 1.0.7 → 1.1.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 (25) hide show
  1. package/README.md +71 -10
  2. package/assets/init/.qfai/README.md +2 -1
  3. package/assets/init/.qfai/assistant/README.md +1 -1
  4. package/assets/init/.qfai/assistant/prompts/README.md +1 -1
  5. package/assets/init/.qfai/assistant/prompts/qfai-configure.md +31 -8
  6. package/assets/init/.qfai/assistant/prompts/qfai-verify.md +1 -1
  7. package/assets/init/.qfai/assistant/steering/README.md +6 -0
  8. package/assets/init/.qfai/assistant/steering/manifest.md +43 -0
  9. package/assets/init/.qfai/contracts/db/README.md +10 -3
  10. package/assets/init/.qfai/samples/guardrails/delta_with_guardrails.md +19 -0
  11. package/assets/init/.qfai/specs/README.md +4 -0
  12. package/assets/init/root/.github/workflows/qfai.yml +0 -2
  13. package/assets/init/root/qfai.config.yaml +1 -8
  14. package/dist/cli/index.cjs +873 -195
  15. package/dist/cli/index.cjs.map +1 -1
  16. package/dist/cli/index.mjs +859 -181
  17. package/dist/cli/index.mjs.map +1 -1
  18. package/dist/index.cjs +731 -221
  19. package/dist/index.cjs.map +1 -1
  20. package/dist/index.d.cts +91 -1
  21. package/dist/index.d.ts +91 -1
  22. package/dist/index.mjs +719 -216
  23. package/dist/index.mjs.map +1 -1
  24. package/package.json +1 -1
  25. package/assets/init/.qfai/assistant/prompts/qfai-pr.md +0 -209
package/dist/index.d.cts CHANGED
@@ -98,6 +98,68 @@ declare function findConfigRoot(startDir: string): Promise<ConfigSearchResult>;
98
98
  declare function loadConfig(root: string): Promise<ConfigLoadResult>;
99
99
  declare function resolvePath(root: string, config: QfaiConfig, key: ConfigPathKey): string;
100
100
 
101
+ type GuardrailType = "non-goal" | "not-now" | "trade-off";
102
+ type DecisionGuardrailEntry = {
103
+ id?: string;
104
+ type?: string;
105
+ guardrail?: string;
106
+ rationale?: string;
107
+ reconsider?: string;
108
+ related?: string;
109
+ keywords?: string[];
110
+ title?: string;
111
+ source: {
112
+ file: string;
113
+ line: number;
114
+ };
115
+ };
116
+ type DecisionGuardrail = {
117
+ id: string;
118
+ type: GuardrailType;
119
+ guardrail: string;
120
+ rationale?: string;
121
+ reconsider?: string;
122
+ related?: string;
123
+ keywords: string[];
124
+ title?: string;
125
+ source: {
126
+ file: string;
127
+ line: number;
128
+ };
129
+ };
130
+ type GuardrailIssueSeverity = "warning" | "error";
131
+ type GuardrailIssue = {
132
+ severity: GuardrailIssueSeverity;
133
+ code: string;
134
+ message: string;
135
+ file: string;
136
+ line?: number;
137
+ id?: string;
138
+ };
139
+ type GuardrailCheckResult = {
140
+ errors: GuardrailIssue[];
141
+ warnings: GuardrailIssue[];
142
+ };
143
+ type GuardrailLoadError = {
144
+ path: string;
145
+ message: string;
146
+ };
147
+ type GuardrailLoadResult = {
148
+ entries: DecisionGuardrailEntry[];
149
+ errors: GuardrailLoadError[];
150
+ files: string[];
151
+ };
152
+ declare function loadDecisionGuardrails(root: string, options?: {
153
+ paths?: string[];
154
+ specsRoot?: string;
155
+ }): Promise<GuardrailLoadResult>;
156
+ declare function extractDecisionGuardrailsFromMarkdown(markdown: string, filePath: string): DecisionGuardrailEntry[];
157
+ declare function normalizeDecisionGuardrails(entries: DecisionGuardrailEntry[]): DecisionGuardrail[];
158
+ declare function sortDecisionGuardrails(items: DecisionGuardrail[]): DecisionGuardrail[];
159
+ declare function filterDecisionGuardrailsByKeyword(items: DecisionGuardrail[], keyword: string | undefined): DecisionGuardrail[];
160
+ declare function formatGuardrailsForLlm(items: DecisionGuardrail[], max: number): string;
161
+ declare function checkDecisionGuardrails(entries: DecisionGuardrailEntry[]): GuardrailCheckResult;
162
+
101
163
  type IdPrefix = "SPEC" | "BR" | "SC" | "UI" | "API" | "DB" | "THEMA";
102
164
  type IdFormatPrefix = IdPrefix | "ADR";
103
165
  declare function extractIds(text: string, prefix: IdPrefix): string[];
@@ -148,6 +210,33 @@ type ReportTraceability = {
148
210
  contracts: ReportContractCoverage;
149
211
  specs: ReportSpecCoverage;
150
212
  };
213
+ type ReportGuardrailItem = {
214
+ id: string;
215
+ type: GuardrailType;
216
+ guardrail: string;
217
+ rationale?: string;
218
+ reconsider?: string;
219
+ related?: string;
220
+ source: {
221
+ file: string;
222
+ line: number;
223
+ };
224
+ };
225
+ type ReportGuardrails = {
226
+ total: number;
227
+ max: number;
228
+ truncated: boolean;
229
+ byType: {
230
+ nonGoal: number;
231
+ notNow: number;
232
+ tradeOff: number;
233
+ };
234
+ items: ReportGuardrailItem[];
235
+ scanErrors: Array<{
236
+ path: string;
237
+ message: string;
238
+ }>;
239
+ };
151
240
  type ReportData = {
152
241
  tool: "qfai";
153
242
  version: string;
@@ -157,6 +246,7 @@ type ReportData = {
157
246
  summary: ReportSummary;
158
247
  ids: ReportIds;
159
248
  traceability: ReportTraceability;
249
+ guardrails: ReportGuardrails;
160
250
  issues: Issue[];
161
251
  };
162
252
  declare function createReportData(root: string, validation?: ValidationResult, configResult?: ConfigLoadResult): Promise<ReportData>;
@@ -185,4 +275,4 @@ declare function validateSpecContent(text: string, file: string, requiredSection
185
275
 
186
276
  declare function validateTraceability(root: string, config: QfaiConfig): Promise<Issue[]>;
187
277
 
188
- export { type ConfigLoadResult, type ConfigPathKey, type ConfigSearchResult, type FailOn, type IdFormatPrefix, type IdPrefix, type Issue, type IssueCategory, type IssueLocation, type IssueSeverity, type OrphanContractsPolicy, type OutputFormat, type QfaiConfig, type QfaiOutputConfig, type QfaiPaths, type QfaiValidationConfig, type ReportContractCoverage, type ReportData, type ReportIds, type ReportSpecContractRefs, type ReportSpecCoverage, type ReportSummary, type ReportTraceability, type TraceabilitySeverity, type ValidationCounts, type ValidationResult, type ValidationTraceability, createReportData, defaultConfig, extractAllIds, extractIds, extractInvalidIds, findConfigRoot, formatReportJson, formatReportMarkdown, getConfigPath, lintSql, loadConfig, resolvePath, resolveToolVersion, validateContracts, validateDefinedIds, validateDeltas, validateProject, validateScenarioContent, validateScenarios, validateSpecContent, validateSpecs, validateTraceability };
278
+ export { type ConfigLoadResult, type ConfigPathKey, type ConfigSearchResult, type DecisionGuardrail, type DecisionGuardrailEntry, type FailOn, type GuardrailCheckResult, type GuardrailIssue, type GuardrailIssueSeverity, type GuardrailLoadError, type GuardrailLoadResult, type GuardrailType, type IdFormatPrefix, type IdPrefix, type Issue, type IssueCategory, type IssueLocation, type IssueSeverity, type OrphanContractsPolicy, type OutputFormat, type QfaiConfig, type QfaiOutputConfig, type QfaiPaths, type QfaiValidationConfig, type ReportContractCoverage, type ReportData, type ReportGuardrailItem, type ReportGuardrails, type ReportIds, type ReportSpecContractRefs, type ReportSpecCoverage, type ReportSummary, type ReportTraceability, type TraceabilitySeverity, type ValidationCounts, type ValidationResult, type ValidationTraceability, checkDecisionGuardrails, createReportData, defaultConfig, extractAllIds, extractDecisionGuardrailsFromMarkdown, extractIds, extractInvalidIds, filterDecisionGuardrailsByKeyword, findConfigRoot, formatGuardrailsForLlm, formatReportJson, formatReportMarkdown, getConfigPath, lintSql, loadConfig, loadDecisionGuardrails, normalizeDecisionGuardrails, resolvePath, resolveToolVersion, sortDecisionGuardrails, validateContracts, validateDefinedIds, validateDeltas, validateProject, validateScenarioContent, validateScenarios, validateSpecContent, validateSpecs, validateTraceability };
package/dist/index.d.ts CHANGED
@@ -98,6 +98,68 @@ declare function findConfigRoot(startDir: string): Promise<ConfigSearchResult>;
98
98
  declare function loadConfig(root: string): Promise<ConfigLoadResult>;
99
99
  declare function resolvePath(root: string, config: QfaiConfig, key: ConfigPathKey): string;
100
100
 
101
+ type GuardrailType = "non-goal" | "not-now" | "trade-off";
102
+ type DecisionGuardrailEntry = {
103
+ id?: string;
104
+ type?: string;
105
+ guardrail?: string;
106
+ rationale?: string;
107
+ reconsider?: string;
108
+ related?: string;
109
+ keywords?: string[];
110
+ title?: string;
111
+ source: {
112
+ file: string;
113
+ line: number;
114
+ };
115
+ };
116
+ type DecisionGuardrail = {
117
+ id: string;
118
+ type: GuardrailType;
119
+ guardrail: string;
120
+ rationale?: string;
121
+ reconsider?: string;
122
+ related?: string;
123
+ keywords: string[];
124
+ title?: string;
125
+ source: {
126
+ file: string;
127
+ line: number;
128
+ };
129
+ };
130
+ type GuardrailIssueSeverity = "warning" | "error";
131
+ type GuardrailIssue = {
132
+ severity: GuardrailIssueSeverity;
133
+ code: string;
134
+ message: string;
135
+ file: string;
136
+ line?: number;
137
+ id?: string;
138
+ };
139
+ type GuardrailCheckResult = {
140
+ errors: GuardrailIssue[];
141
+ warnings: GuardrailIssue[];
142
+ };
143
+ type GuardrailLoadError = {
144
+ path: string;
145
+ message: string;
146
+ };
147
+ type GuardrailLoadResult = {
148
+ entries: DecisionGuardrailEntry[];
149
+ errors: GuardrailLoadError[];
150
+ files: string[];
151
+ };
152
+ declare function loadDecisionGuardrails(root: string, options?: {
153
+ paths?: string[];
154
+ specsRoot?: string;
155
+ }): Promise<GuardrailLoadResult>;
156
+ declare function extractDecisionGuardrailsFromMarkdown(markdown: string, filePath: string): DecisionGuardrailEntry[];
157
+ declare function normalizeDecisionGuardrails(entries: DecisionGuardrailEntry[]): DecisionGuardrail[];
158
+ declare function sortDecisionGuardrails(items: DecisionGuardrail[]): DecisionGuardrail[];
159
+ declare function filterDecisionGuardrailsByKeyword(items: DecisionGuardrail[], keyword: string | undefined): DecisionGuardrail[];
160
+ declare function formatGuardrailsForLlm(items: DecisionGuardrail[], max: number): string;
161
+ declare function checkDecisionGuardrails(entries: DecisionGuardrailEntry[]): GuardrailCheckResult;
162
+
101
163
  type IdPrefix = "SPEC" | "BR" | "SC" | "UI" | "API" | "DB" | "THEMA";
102
164
  type IdFormatPrefix = IdPrefix | "ADR";
103
165
  declare function extractIds(text: string, prefix: IdPrefix): string[];
@@ -148,6 +210,33 @@ type ReportTraceability = {
148
210
  contracts: ReportContractCoverage;
149
211
  specs: ReportSpecCoverage;
150
212
  };
213
+ type ReportGuardrailItem = {
214
+ id: string;
215
+ type: GuardrailType;
216
+ guardrail: string;
217
+ rationale?: string;
218
+ reconsider?: string;
219
+ related?: string;
220
+ source: {
221
+ file: string;
222
+ line: number;
223
+ };
224
+ };
225
+ type ReportGuardrails = {
226
+ total: number;
227
+ max: number;
228
+ truncated: boolean;
229
+ byType: {
230
+ nonGoal: number;
231
+ notNow: number;
232
+ tradeOff: number;
233
+ };
234
+ items: ReportGuardrailItem[];
235
+ scanErrors: Array<{
236
+ path: string;
237
+ message: string;
238
+ }>;
239
+ };
151
240
  type ReportData = {
152
241
  tool: "qfai";
153
242
  version: string;
@@ -157,6 +246,7 @@ type ReportData = {
157
246
  summary: ReportSummary;
158
247
  ids: ReportIds;
159
248
  traceability: ReportTraceability;
249
+ guardrails: ReportGuardrails;
160
250
  issues: Issue[];
161
251
  };
162
252
  declare function createReportData(root: string, validation?: ValidationResult, configResult?: ConfigLoadResult): Promise<ReportData>;
@@ -185,4 +275,4 @@ declare function validateSpecContent(text: string, file: string, requiredSection
185
275
 
186
276
  declare function validateTraceability(root: string, config: QfaiConfig): Promise<Issue[]>;
187
277
 
188
- export { type ConfigLoadResult, type ConfigPathKey, type ConfigSearchResult, type FailOn, type IdFormatPrefix, type IdPrefix, type Issue, type IssueCategory, type IssueLocation, type IssueSeverity, type OrphanContractsPolicy, type OutputFormat, type QfaiConfig, type QfaiOutputConfig, type QfaiPaths, type QfaiValidationConfig, type ReportContractCoverage, type ReportData, type ReportIds, type ReportSpecContractRefs, type ReportSpecCoverage, type ReportSummary, type ReportTraceability, type TraceabilitySeverity, type ValidationCounts, type ValidationResult, type ValidationTraceability, createReportData, defaultConfig, extractAllIds, extractIds, extractInvalidIds, findConfigRoot, formatReportJson, formatReportMarkdown, getConfigPath, lintSql, loadConfig, resolvePath, resolveToolVersion, validateContracts, validateDefinedIds, validateDeltas, validateProject, validateScenarioContent, validateScenarios, validateSpecContent, validateSpecs, validateTraceability };
278
+ export { type ConfigLoadResult, type ConfigPathKey, type ConfigSearchResult, type DecisionGuardrail, type DecisionGuardrailEntry, type FailOn, type GuardrailCheckResult, type GuardrailIssue, type GuardrailIssueSeverity, type GuardrailLoadError, type GuardrailLoadResult, type GuardrailType, type IdFormatPrefix, type IdPrefix, type Issue, type IssueCategory, type IssueLocation, type IssueSeverity, type OrphanContractsPolicy, type OutputFormat, type QfaiConfig, type QfaiOutputConfig, type QfaiPaths, type QfaiValidationConfig, type ReportContractCoverage, type ReportData, type ReportGuardrailItem, type ReportGuardrails, type ReportIds, type ReportSpecContractRefs, type ReportSpecCoverage, type ReportSummary, type ReportTraceability, type TraceabilitySeverity, type ValidationCounts, type ValidationResult, type ValidationTraceability, checkDecisionGuardrails, createReportData, defaultConfig, extractAllIds, extractDecisionGuardrailsFromMarkdown, extractIds, extractInvalidIds, filterDecisionGuardrailsByKeyword, findConfigRoot, formatGuardrailsForLlm, formatReportJson, formatReportMarkdown, getConfigPath, lintSql, loadConfig, loadDecisionGuardrails, normalizeDecisionGuardrails, resolvePath, resolveToolVersion, sortDecisionGuardrails, validateContracts, validateDefinedIds, validateDeltas, validateProject, validateScenarioContent, validateScenarios, validateSpecContent, validateSpecs, validateTraceability };