@holmes-lab/holmes-kit 0.39.0 → 0.40.1
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.
- package/CHANGELOG.md +578 -6
- package/README.md +120 -41
- package/dist/.build-id +1 -1
- package/dist/holmes/admission/core/admission-policy.d.ts +37 -0
- package/dist/holmes/admission/core/admission-policy.js +147 -0
- package/dist/holmes/admission/core/bounded-reader.d.ts +56 -0
- package/dist/holmes/admission/core/bounded-reader.js +135 -0
- package/dist/holmes/admission/core/change-classifier.d.ts +34 -0
- package/dist/holmes/admission/core/change-classifier.js +278 -0
- package/dist/holmes/admission/core/config-loader.d.ts +30 -0
- package/dist/holmes/admission/core/config-loader.js +145 -0
- package/dist/holmes/admission/core/event-judgement.d.ts +37 -0
- package/dist/holmes/admission/core/event-judgement.js +251 -0
- package/dist/holmes/admission/core/path-rules.d.ts +35 -0
- package/dist/holmes/admission/core/path-rules.js +88 -0
- package/dist/holmes/admission/core/pin.d.ts +7 -0
- package/dist/holmes/admission/core/pin.js +29 -0
- package/dist/holmes/admission/core/ports.d.ts +48 -0
- package/dist/holmes/admission/core/ports.js +11 -0
- package/dist/holmes/admission/core/range-resolver.d.ts +32 -0
- package/dist/holmes/admission/core/range-resolver.js +51 -0
- package/dist/holmes/admission/core/self-containment.d.ts +1 -0
- package/dist/holmes/admission/core/self-containment.js +125 -0
- package/dist/holmes/admission/core/signature-source.d.ts +9 -0
- package/dist/holmes/admission/core/signature-source.js +4 -0
- package/dist/holmes/admission/core/transition-planner.d.ts +15 -0
- package/dist/holmes/admission/core/transition-planner.js +14 -0
- package/dist/holmes/admission/core/verdict.d.ts +38 -0
- package/dist/holmes/admission/core/verdict.js +17 -0
- package/dist/holmes/admission/core/wiring.d.ts +44 -0
- package/dist/holmes/admission/core/wiring.js +618 -0
- package/dist/holmes/admission/forge/git-object-port.d.ts +4 -0
- package/dist/holmes/admission/forge/git-object-port.js +132 -0
- package/dist/holmes/assoc/assoc-arm.d.ts +1 -1
- package/dist/holmes/assoc/assoc-arm.js +1 -1
- package/dist/holmes/cli/agents.d.ts +8 -0
- package/dist/holmes/cli/agents.js +9 -5
- package/dist/holmes/cli/approve-cli.d.ts +2 -0
- package/dist/holmes/cli/approve-cli.js +392 -0
- package/dist/holmes/cli/approve-ref.d.ts +13 -7
- package/dist/holmes/cli/approve-ref.js +30 -10
- package/dist/holmes/cli/approve-status.d.ts +26 -2
- package/dist/holmes/cli/approve-status.js +98 -18
- package/dist/holmes/cli/approve-watch.d.ts +5 -0
- package/dist/holmes/cli/approve-watch.js +10 -5
- package/dist/holmes/cli/approve.d.ts +49 -13
- package/dist/holmes/cli/approve.js +249 -67
- package/dist/holmes/cli/attest.js +2 -1
- package/dist/holmes/cli/autonomy.d.ts +4 -1
- package/dist/holmes/cli/autonomy.js +17 -10
- package/dist/holmes/cli/codex-oracle.d.ts +11 -0
- package/dist/holmes/cli/codex-oracle.js +5 -1
- package/dist/holmes/cli/codex-toml.d.ts +10 -0
- package/dist/holmes/cli/codex-toml.js +36 -2
- package/dist/holmes/cli/doctor-boundary.d.ts +76 -0
- package/dist/holmes/cli/doctor-boundary.js +308 -0
- package/dist/holmes/cli/doctor-locks.d.ts +15 -0
- package/dist/holmes/cli/doctor-locks.js +119 -0
- package/dist/holmes/cli/doctor.d.ts +2 -0
- package/dist/holmes/cli/doctor.js +34 -5
- package/dist/holmes/cli/flags.d.ts +23 -0
- package/dist/holmes/cli/flags.js +89 -0
- package/dist/holmes/cli/index.d.ts +5 -1
- package/dist/holmes/cli/index.js +226 -442
- package/dist/holmes/cli/init.js +33 -0
- package/dist/holmes/cli/interactive-prompt.d.ts +39 -2
- package/dist/holmes/cli/interactive-prompt.js +98 -16
- package/dist/holmes/cli/lock-recover.d.ts +5 -0
- package/dist/holmes/cli/lock-recover.js +126 -0
- package/dist/holmes/cli/mcp-processes.js +1 -1
- package/dist/holmes/cli/release-docs.js +1 -1
- package/dist/holmes/cli/run-exec.d.ts +141 -0
- package/dist/holmes/cli/run-exec.js +1435 -0
- package/dist/holmes/cli/run-provision.d.ts +3 -1
- package/dist/holmes/cli/run-provision.js +255 -44
- package/dist/holmes/cli/run-wiring.d.ts +69 -0
- package/dist/holmes/cli/run-wiring.js +270 -0
- package/dist/holmes/cli/run.d.ts +21 -0
- package/dist/holmes/cli/run.js +341 -92
- package/dist/holmes/cli/runtime-binding-approval.js +32 -19
- package/dist/holmes/cli/screen-safe.d.ts +3 -92
- package/dist/holmes/cli/screen-safe.js +18 -756
- package/dist/holmes/config/config.d.ts +19 -0
- package/dist/holmes/config/config.js +18 -3
- package/dist/holmes/cpg/foundation/language-matrix.js +2 -2
- package/dist/holmes/cpg/import-resolver.js +1 -1
- package/dist/holmes/governance/approval-decisions.d.ts +47 -0
- package/dist/holmes/governance/approval-decisions.js +29 -0
- package/dist/holmes/governance/approval-grants.d.ts +220 -1
- package/dist/holmes/governance/approval-grants.js +612 -33
- package/dist/holmes/governance/approval-queue.d.ts +26 -0
- package/dist/holmes/governance/approval-queue.js +109 -11
- package/dist/holmes/governance/approval-spend.d.ts +95 -0
- package/dist/holmes/governance/approval-spend.js +191 -0
- package/dist/holmes/governance/autonomous-shell.d.ts +61 -0
- package/dist/holmes/governance/autonomous-shell.js +332 -0
- package/dist/holmes/governance/autonomy.d.ts +12 -0
- package/dist/holmes/governance/autonomy.js +51 -15
- package/dist/holmes/governance/constitution.d.ts +5 -0
- package/dist/holmes/governance/constitution.js +32 -12
- package/dist/holmes/governance/full-autonomy.d.ts +10 -0
- package/dist/holmes/governance/full-autonomy.js +103 -7
- package/dist/holmes/governance/harness-catalog.d.ts +103 -0
- package/dist/holmes/governance/harness-catalog.js +348 -0
- package/dist/holmes/governance/human-channel.d.ts +38 -0
- package/dist/holmes/governance/human-channel.js +49 -0
- package/dist/holmes/governance/install-manifest.d.ts +22 -0
- package/dist/holmes/governance/install-manifest.js +160 -0
- package/dist/holmes/governance/ledger-rechain.js +2 -0
- package/dist/holmes/governance/ledger-store.conformance.d.ts +7 -1
- package/dist/holmes/governance/ledger-store.conformance.js +66 -0
- package/dist/holmes/governance/ledger-store.d.ts +88 -11
- package/dist/holmes/governance/ledger-store.js +186 -8
- package/dist/holmes/governance/provenance-chain.d.ts +16 -4
- package/dist/holmes/governance/provenance-chain.js +19 -4
- package/dist/holmes/governance/provenance-ledger.d.ts +6 -3
- package/dist/holmes/governance/provenance-ledger.js +53 -18
- package/dist/holmes/governance/push-gate-runner.d.ts +2 -0
- package/dist/holmes/governance/push-gate-runner.js +50 -9
- package/dist/holmes/governance/push-gate.d.ts +13 -2
- package/dist/holmes/governance/push-gate.js +106 -14
- package/dist/holmes/governance/recorded-pairs.d.ts +96 -0
- package/dist/holmes/governance/recorded-pairs.js +522 -0
- package/dist/holmes/governance/replica-id.d.ts +1 -1
- package/dist/holmes/governance/replica-id.js +1 -1
- package/dist/holmes/governance/spec-seam.d.ts +59 -0
- package/dist/holmes/governance/spec-seam.js +587 -0
- package/dist/holmes/governance/spend-kinds.d.ts +16 -0
- package/dist/holmes/governance/spend-kinds.js +18 -0
- package/dist/holmes/guardrail/advisory-line.d.ts +102 -0
- package/dist/holmes/guardrail/advisory-line.js +718 -0
- package/dist/holmes/guardrail/decision-ledger.d.ts +2 -1
- package/dist/holmes/guardrail/decision-ledger.js +2 -1
- package/dist/holmes/guardrail/impact-gate.d.ts +7 -0
- package/dist/holmes/guardrail/impact-gate.js +33 -6
- package/dist/holmes/guardrail/line-continuation.d.ts +8 -0
- package/dist/holmes/guardrail/line-continuation.js +39 -0
- package/dist/holmes/guardrail/operator-person.d.ts +28 -4
- package/dist/holmes/guardrail/operator-person.js +57 -11
- package/dist/holmes/guardrail/refusal-codes.d.ts +8 -3
- package/dist/holmes/guardrail/refusal-codes.js +64 -10
- package/dist/holmes/guardrail/risk-classifier.d.ts +15 -9
- package/dist/holmes/guardrail/risk-classifier.js +228 -16
- package/dist/holmes/guardrail/risk-gate.d.ts +2 -8
- package/dist/holmes/guardrail/risk-gate.js +7 -34
- package/dist/holmes/guardrail/risk-types.d.ts +10 -0
- package/dist/holmes/guardrail/run-plan-scope.js +3 -1
- package/dist/holmes/guardrail/run-refusals.js +24 -8
- package/dist/holmes/guardrail/run-stages.d.ts +5 -0
- package/dist/holmes/guardrail/run-stages.js +25 -5
- package/dist/holmes/guardrail/scope-judgment.js +1 -1
- package/dist/holmes/guardrail/shell-words.js +24 -3
- package/dist/holmes/guardrail/unresolved-write.d.ts +40 -0
- package/dist/holmes/guardrail/unresolved-write.js +556 -0
- package/dist/holmes/guardrail/write-target.d.ts +3 -0
- package/dist/holmes/guardrail/write-target.js +26 -5
- package/dist/holmes/hooks/pre-tool-use.d.ts +116 -1
- package/dist/holmes/hooks/pre-tool-use.js +1176 -170
- package/dist/holmes/hooks/rtm-refresh-child.d.ts +1 -1
- package/dist/holmes/hooks/rtm-refresh-child.js +1 -1
- package/dist/holmes/hooks/session-start.js +17 -1
- package/dist/holmes/hooks/stop.d.ts +23 -0
- package/dist/holmes/hooks/stop.js +86 -33
- package/dist/holmes/mcp/approval-adapters.js +3 -1
- package/dist/holmes/mcp/approval-commit.js +3 -2
- package/dist/holmes/mcp/approval-policy.d.ts +2 -1
- package/dist/holmes/mcp/approval-policy.js +3 -1
- package/dist/holmes/mcp/handlers/adoption.d.ts +1 -1
- package/dist/holmes/mcp/handlers/approval-ask.d.ts +3 -0
- package/dist/holmes/mcp/handlers/approval-ask.js +18 -7
- package/dist/holmes/mcp/handlers/entity-integration.d.ts +3 -3
- package/dist/holmes/mcp/handlers/entity-integration.js +29 -11
- package/dist/holmes/mcp/handlers/entity-renumber.d.ts +4 -4
- package/dist/holmes/mcp/handlers/entity-renumber.js +29 -11
- package/dist/holmes/mcp/handlers/entity-store.d.ts +2 -2
- package/dist/holmes/mcp/handlers/entity-store.js +133 -59
- package/dist/holmes/mcp/handlers/maintenance-analysis.d.ts +13 -0
- package/dist/holmes/mcp/handlers/maintenance-analysis.js +59 -2
- package/dist/holmes/mcp/handlers/operator-inspection.d.ts +9 -5
- package/dist/holmes/mcp/handlers/operator-inspection.js +79 -16
- package/dist/holmes/mcp/handlers/phase-queries.d.ts +1 -1
- package/dist/holmes/mcp/handlers/requirement-triage.d.ts +4 -4
- package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -2
- package/dist/holmes/mcp/handlers/review-evidence.js +35 -11
- package/dist/holmes/mcp/handlers/review-queries.d.ts +5 -0
- package/dist/holmes/mcp/handlers/review-queries.js +8 -1
- package/dist/holmes/mcp/handlers/review-verdict.d.ts +3 -0
- package/dist/holmes/mcp/handlers/review-verdict.js +10 -3
- package/dist/holmes/mcp/handlers/risk-assessment.d.ts +7 -2
- package/dist/holmes/mcp/handlers/risk-assessment.js +34 -12
- package/dist/holmes/mcp/handlers/runtime-binding-tool.d.ts +2 -2
- package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +6 -1
- package/dist/holmes/mcp/handlers/slice-orchestration.js +14 -1
- package/dist/holmes/mcp/handlers/spec-approval.d.ts +15 -3
- package/dist/holmes/mcp/handlers/spec-approval.js +32 -5
- package/dist/holmes/mcp/handlers/spec-authoring.d.ts +2 -2
- package/dist/holmes/mcp/handlers/spec-authoring.js +19 -2
- package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +11 -38
- package/dist/holmes/mcp/handlers/spec-lifecycle.js +441 -94
- package/dist/holmes/mcp/handlers/spec-queries.d.ts +2 -2
- package/dist/holmes/mcp/handlers/taint-screening.d.ts +1 -1
- package/dist/holmes/mcp/handlers/taint-screening.js +2 -2
- package/dist/holmes/mcp/handlers/test-execution.d.ts +471 -4
- package/dist/holmes/mcp/handlers/test-execution.js +199 -21
- package/dist/holmes/mcp/handlers/workspace-queries.d.ts +2 -2
- package/dist/holmes/mcp/handlers.d.ts +557 -82
- package/dist/holmes/mcp/handlers.js +74 -23
- package/dist/holmes/mcp/harness-attestation.d.ts +78 -5
- package/dist/holmes/mcp/harness-attestation.js +325 -53
- package/dist/holmes/mcp/maintenance-analyze.d.ts +6 -1
- package/dist/holmes/mcp/maintenance-analyze.js +13 -11
- package/dist/holmes/mcp/maintenance-evidence.d.ts +9 -0
- package/dist/holmes/mcp/maintenance-evidence.js +35 -3
- package/dist/holmes/mcp/requirement-triage-evidence.js +22 -13
- package/dist/holmes/mcp/server-staleness.js +1 -1
- package/dist/holmes/mcp/server.js +9 -8
- package/dist/holmes/mcp/spec-id-guard.js +1 -1
- package/dist/holmes/mcp/tool-schemas.d.ts +13 -0
- package/dist/holmes/mcp/tool-schemas.js +42 -9
- package/dist/holmes/project/act-root.d.ts +19 -0
- package/dist/holmes/project/act-root.js +100 -0
- package/dist/holmes/project/baseline.d.ts +15 -2
- package/dist/holmes/project/baseline.js +14 -8
- package/dist/holmes/project/bounded-group.d.ts +47 -0
- package/dist/holmes/project/bounded-group.js +140 -0
- package/dist/holmes/project/bounded-io.d.ts +51 -2
- package/dist/holmes/project/bounded-io.js +140 -6
- package/dist/holmes/project/change-source.d.ts +4 -0
- package/dist/holmes/project/change-source.js +14 -6
- package/dist/holmes/project/instance-id.d.ts +10 -0
- package/dist/holmes/project/instance-id.js +233 -0
- package/dist/holmes/project/machine-identity.d.ts +25 -0
- package/dist/holmes/project/machine-identity.js +133 -0
- package/dist/holmes/project/owned-lock.d.ts +84 -0
- package/dist/holmes/project/owned-lock.js +263 -0
- package/dist/holmes/project/plain-lock-fs.d.ts +2 -0
- package/dist/holmes/project/plain-lock-fs.js +126 -0
- package/dist/holmes/project/request-lock.d.ts +85 -0
- package/dist/holmes/project/request-lock.js +459 -0
- package/dist/holmes/project/root.d.ts +12 -4
- package/dist/holmes/project/root.js +29 -8
- package/dist/holmes/project/run-records.d.ts +19 -0
- package/dist/holmes/project/run-records.js +94 -12
- package/dist/holmes/project/screen-text.d.ts +94 -0
- package/dist/holmes/project/screen-text.js +763 -0
- package/dist/holmes/project/spend-lock.d.ts +82 -0
- package/dist/holmes/project/spend-lock.js +413 -0
- package/dist/holmes/refresh/freshness-coordinator.d.ts +1 -1
- package/dist/holmes/refresh/freshness-coordinator.js +1 -1
- package/dist/holmes/review/condition-hunk-replay.js +4 -2
- package/dist/holmes/review/confidence-calibration.d.ts +1 -1
- package/dist/holmes/review/confidence-calibration.js +1 -1
- package/dist/holmes/review/content-verify.js +1 -1
- package/dist/holmes/review/evidence-mode.d.ts +21 -0
- package/dist/holmes/review/evidence-mode.js +33 -0
- package/dist/holmes/review/head-worktree.d.ts +55 -0
- package/dist/holmes/review/head-worktree.js +329 -0
- package/dist/holmes/review/hop-ablation.d.ts +4 -4
- package/dist/holmes/review/hop-ablation.js +5 -5
- package/dist/holmes/review/mrp.js +13 -3
- package/dist/holmes/review/point-in-time-replay.js +12 -3
- package/dist/holmes/review/rank-diagnosis.d.ts +2 -2
- package/dist/holmes/review/rank-diagnosis.js +1 -1
- package/dist/holmes/review/replay-corpus.d.ts +10 -4
- package/dist/holmes/review/replay-corpus.js +25 -9
- package/dist/holmes/review/requirement-triage.js +2 -2
- package/dist/holmes/review/run-provenance.d.ts +45 -0
- package/dist/holmes/review/run-provenance.js +314 -0
- package/dist/holmes/review/semantic-arm.d.ts +3 -3
- package/dist/holmes/review/semantic-arm.js +3 -3
- package/dist/holmes/review/test-evidence.d.ts +174 -0
- package/dist/holmes/review/test-evidence.js +330 -2
- package/dist/holmes/review/test-outcomes.js +3 -1
- package/dist/holmes/review/test-reports.d.ts +94 -0
- package/dist/holmes/review/test-reports.js +382 -0
- package/dist/holmes/review/test-runner.d.ts +180 -58
- package/dist/holmes/review/test-runner.js +560 -324
- package/dist/holmes/review/test-selection-breadth.js +2 -2
- package/dist/holmes/review/test-units.d.ts +159 -0
- package/dist/holmes/review/test-units.js +814 -0
- package/dist/holmes/review/verdicts.d.ts +105 -8
- package/dist/holmes/review/verdicts.js +640 -36
- package/dist/holmes/rtm/anchor-census.d.ts +9 -0
- package/dist/holmes/rtm/anchor-census.js +151 -0
- package/dist/holmes/rtm/anchor-ids.d.ts +25 -1
- package/dist/holmes/rtm/anchor-ids.js +45 -2
- package/dist/holmes/rtm/comment-ranges.d.ts +2 -0
- package/dist/holmes/rtm/comment-ranges.js +104 -0
- package/dist/holmes/rtm/counted-tests.d.ts +1 -0
- package/dist/holmes/rtm/counted-tests.js +63 -0
- package/dist/holmes/rtm/impact-advisory.d.ts +1 -1
- package/dist/holmes/rtm/known-defects.js +1 -1
- package/dist/holmes/rtm/localize.js +1 -1
- package/dist/holmes/rtm/taint-benchmark.d.ts +1 -1
- package/dist/holmes/rtm/taint-vocabulary.d.ts +1 -1
- package/dist/holmes/rtm/test-scope.d.ts +31 -0
- package/dist/holmes/rtm/test-scope.js +166 -5
- package/dist/holmes/rtm/trace-gaps.js +1 -1
- package/dist/holmes/runtime/dispatch.d.ts +10 -0
- package/dist/holmes/runtime/dispatch.js +12 -1
- package/dist/holmes/semantic/cloud-usage.d.ts +1 -1
- package/dist/holmes/semantic/cloud-usage.js +1 -1
- package/dist/holmes/semantic/unreadable-paths.d.ts +1 -1
- package/dist/holmes/semantic/unreadable-paths.js +1 -1
- package/dist/holmes/spec/approval-blockers.js +1 -1
- package/dist/holmes/spec/entity-store.d.ts +6 -1
- package/dist/holmes/spec/entity-store.js +16 -2
- package/dist/holmes/spec/entity-transaction.d.ts +7 -2
- package/dist/holmes/spec/entity-transaction.js +87 -170
- package/dist/holmes/spec/spec-store.d.ts +12 -6
- package/dist/holmes/spec/spec-store.js +4 -2
- package/dist/holmes/spec/spec-types.js +1 -1
- package/dist/holmes/spec/succession-guard.d.ts +56 -0
- package/dist/holmes/spec/succession-guard.js +187 -0
- package/dist/holmes/spec/succession.d.ts +70 -0
- package/dist/holmes/spec/succession.js +171 -0
- package/dist/holmes/spec/transition-policy.d.ts +2 -2
- package/docs/install-guide.md +9 -3
- package/docs/language-support.md +78 -0
- package/package.json +4 -3
- package/playbooks/author-slice/PLAYBOOK.md +1 -1
- package/playbooks/promote-slice/PLAYBOOK.md +5 -1
- package/playbooks/publish/PLAYBOOK.md +47 -34
- package/dist/holmes/review/manual-baseline.d.ts +0 -209
- package/dist/holmes/review/manual-baseline.js +0 -2847
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.judgeChange = judgeChange;
|
|
4
|
+
const config_loader_1 = require("./config-loader");
|
|
5
|
+
const path_rules_1 = require("./path-rules");
|
|
6
|
+
const change_classifier_1 = require("./change-classifier");
|
|
7
|
+
const self_containment_1 = require("./self-containment");
|
|
8
|
+
const spec_parser_1 = require("../../spec/spec-parser");
|
|
9
|
+
const QUEUE_REMEDY = 'other ledgers and the queue: no re-ordering tool in 0.40.0 — the alarm stays for that push';
|
|
10
|
+
const LEDGER_REMEDY = 'provenance ledgers: `holmes-kit ledger rechain`';
|
|
11
|
+
const isNormalBlob = (e) => !e || (e.type === 'blob' && e.mode === '100644');
|
|
12
|
+
const DRAFTISH = new Set(['draft', 'review']);
|
|
13
|
+
function stateOf(reader, e, kind, path) {
|
|
14
|
+
if (!e)
|
|
15
|
+
return { state: 'absent' };
|
|
16
|
+
const bytes = reader.doc(e.oid);
|
|
17
|
+
if (bytes === null)
|
|
18
|
+
return 'size';
|
|
19
|
+
if (kind === 'spec')
|
|
20
|
+
return (0, change_classifier_1.docState)(bytes);
|
|
21
|
+
if ((0, path_rules_1.isDetectorWorkflow)(path)) {
|
|
22
|
+
const r = (0, change_classifier_1.preChecks)(bytes, 'workflow');
|
|
23
|
+
return r ? { state: 'unparseable', reason: r } : { state: 'draft' };
|
|
24
|
+
}
|
|
25
|
+
const r = (0, change_classifier_1.preChecks)(bytes, 'frontmatter');
|
|
26
|
+
if (r)
|
|
27
|
+
return { state: 'unparseable', reason: r };
|
|
28
|
+
try {
|
|
29
|
+
(0, spec_parser_1.parseSpec)(bytes.toString('utf8'));
|
|
30
|
+
}
|
|
31
|
+
catch (err) {
|
|
32
|
+
return { state: 'unparseable', reason: `does not parse (${String(err.message).split('\n')[0]})` };
|
|
33
|
+
}
|
|
34
|
+
return { state: 'draft' }; // a decision has no state rows; it is row 16
|
|
35
|
+
}
|
|
36
|
+
/** The table row that decides, as one contribution (first match wins). */
|
|
37
|
+
function tableRow(c, ctx) {
|
|
38
|
+
const t = (row, verdict, reason) => ({ level: 'table', axis: ctx.axis, row, verdict, reason });
|
|
39
|
+
const { base: b, head: h, kind, path } = c;
|
|
40
|
+
// row 1: a mode other than 100644, a symlink or a submodule; an ancestor that is not a tree
|
|
41
|
+
if (kind === 'ancestor' || !isNormalBlob(b) || !isNormalBlob(h))
|
|
42
|
+
return t(1, 'refused', `${path}: a mode other than 100644, a symlink, a submodule, or an ancestor that is not a tree`);
|
|
43
|
+
// row 2: any → unparseable (documents with a state: specs, decisions, the detector workflows)
|
|
44
|
+
let before, after;
|
|
45
|
+
if (kind === 'spec' || kind === 'decision' || (0, path_rules_1.isDetectorWorkflow)(path)) {
|
|
46
|
+
before = stateOf(ctx.reader, b, kind, path);
|
|
47
|
+
after = stateOf(ctx.reader, h, kind, path);
|
|
48
|
+
if (before === 'size' || after === 'size')
|
|
49
|
+
return t(2, 'incomplete', 'size: a parsed document over 1 MiB');
|
|
50
|
+
if (h && after.state === 'unparseable')
|
|
51
|
+
return t(2, 'refused', `unparseable: ${after.reason ?? ''}`);
|
|
52
|
+
}
|
|
53
|
+
if (kind === 'definition')
|
|
54
|
+
return t(3, 'needs-signature', 'a change to the detection definition');
|
|
55
|
+
if (kind === 'ledger' || kind === 'queue') {
|
|
56
|
+
if (kind === 'ledger' && !b) {
|
|
57
|
+
const replica = (0, path_rules_1.replicaOf)(path);
|
|
58
|
+
if (replica === null)
|
|
59
|
+
return t(4, 'refused', 'a new legacy ledger');
|
|
60
|
+
const allowed = 'config' in ctx.config && ctx.config.config.replicaAllow.includes(replica);
|
|
61
|
+
if (!allowed)
|
|
62
|
+
return t(4, 'needs-signature', `a new replica ledger (${replica}) not on replicaAllow`);
|
|
63
|
+
}
|
|
64
|
+
if (!h)
|
|
65
|
+
return t(6, 'refused', 'a ledger or the queue deleted');
|
|
66
|
+
const a = ctx.reader.append(b ? b.oid : null, h.oid);
|
|
67
|
+
if (a.ok)
|
|
68
|
+
return t(5, 'admit', 'append only');
|
|
69
|
+
const remedy = kind === 'queue' || !/^\.ax\/ledger\/provenance[.]/i.test(path) ? QUEUE_REMEDY : LEDGER_REMEDY;
|
|
70
|
+
return t(6, 'refused', `${a.union ? 'union merge inserted lines mid-file' : 'not append-only'} — ${remedy}`);
|
|
71
|
+
}
|
|
72
|
+
if (kind === 'audit')
|
|
73
|
+
return t(7, 'admit', 'audit');
|
|
74
|
+
if (kind === 'spec' && before && after && before !== 'size' && after !== 'size') {
|
|
75
|
+
const S = before.state, T = after.state;
|
|
76
|
+
const spec = after.spec;
|
|
77
|
+
const fm = (spec?.frontmatter ?? {});
|
|
78
|
+
const sealCheck = () => {
|
|
79
|
+
if (!spec)
|
|
80
|
+
return 'no document';
|
|
81
|
+
if (fm.approved_digest !== (0, change_classifier_1.specDigest)(spec))
|
|
82
|
+
return 'approved_digest is not the canonical digest';
|
|
83
|
+
return (0, change_classifier_1.parentBreach)(spec, ctx.headIndex, ctx.readHead, (id) => (0, change_classifier_1.onCycle)(id, ctx.headIndex, ctx.readHead));
|
|
84
|
+
};
|
|
85
|
+
if (S === 'unparseable' && T !== 'absent') {
|
|
86
|
+
const breach = T === 'approved' ? sealCheck() : null;
|
|
87
|
+
return breach ? t(8, 'refused', breach) : t(8, 'needs-signature', 'unparseable → parseable');
|
|
88
|
+
}
|
|
89
|
+
if ((S === 'absent' || DRAFTISH.has(S)) && DRAFTISH.has(T) && fm.approved_digest === undefined && fm.parent_digests === undefined)
|
|
90
|
+
return t(9, 'admit', 'draft, no seal');
|
|
91
|
+
if (DRAFTISH.has(S) && T === 'absent')
|
|
92
|
+
return t(10, 'admit', 'a draft deleted');
|
|
93
|
+
if ((S === 'absent' || DRAFTISH.has(S)) && T === 'approved') {
|
|
94
|
+
const breach = sealCheck();
|
|
95
|
+
return breach ? t(11, 'refused', breach) : t(11, 'needs-signature', 'sealed');
|
|
96
|
+
}
|
|
97
|
+
if (S === 'approved' && T === 'approved') {
|
|
98
|
+
const breach = spec ? (0, change_classifier_1.parentBreach)(spec, ctx.headIndex, ctx.readHead, (id) => (0, change_classifier_1.onCycle)(id, ctx.headIndex, ctx.readHead)) : null;
|
|
99
|
+
return breach ? t(12, 'refused', breach) : t(12, 'needs-signature', 'an approved spec changed');
|
|
100
|
+
}
|
|
101
|
+
if (S === 'approved' && DRAFTISH.has(T))
|
|
102
|
+
return t(13, 'needs-signature', 'an un-seal');
|
|
103
|
+
if ((S === 'approved' && T === 'outdated') || ((S === 'approved' || S === 'outdated') && T === 'absent'))
|
|
104
|
+
return t(14, 'needs-signature', 'retired or deleted');
|
|
105
|
+
if (S === 'outdated')
|
|
106
|
+
return t(15, 'needs-signature', 'outdated → another state');
|
|
107
|
+
}
|
|
108
|
+
return t(16, 'needs-signature', 'a protected path');
|
|
109
|
+
}
|
|
110
|
+
/** Every contribution of one change on one axis. */
|
|
111
|
+
function judgeChange(c, ctx) {
|
|
112
|
+
const out = [];
|
|
113
|
+
const cfg = ctx.config;
|
|
114
|
+
const isConfigAddition = (0, path_rules_1.fold)(c.path) === path_rules_1.CONFIG_PATH && !c.base && !!c.head;
|
|
115
|
+
if ('none' in cfg)
|
|
116
|
+
out.push({ level: 'path', axis: ctx.axis, verdict: 'refused', reason: 'branch creation: judged with no configuration' });
|
|
117
|
+
else if ('absent' in cfg && !isConfigAddition)
|
|
118
|
+
out.push({ level: 'path', axis: ctx.axis, verdict: 'refused', reason: cfg.absent });
|
|
119
|
+
else if ('refused' in cfg)
|
|
120
|
+
out.push({ level: 'path', axis: ctx.axis, verdict: 'refused', reason: cfg.refused });
|
|
121
|
+
if (ctx.collisions.has(c.path))
|
|
122
|
+
out.push({ level: 'key', axis: ctx.axis, verdict: 'refused', reason: 'a case or NFC collision' });
|
|
123
|
+
if (c.kind === 'spec' && c.head) {
|
|
124
|
+
const bytes = ctx.reader.doc(c.head.oid);
|
|
125
|
+
const st = bytes ? (0, change_classifier_1.docState)(bytes) : null;
|
|
126
|
+
if (st?.spec) {
|
|
127
|
+
const b = (0, change_classifier_1.keyRuleBreach)(c.path, st.spec, ctx.headIndex);
|
|
128
|
+
if (b)
|
|
129
|
+
out.push({ level: 'key', axis: ctx.axis, verdict: 'refused', reason: b });
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
if ((0, path_rules_1.isDetectorWorkflow)(c.path) && c.head) {
|
|
133
|
+
const bytes = ctx.reader.doc(c.head.oid);
|
|
134
|
+
// a document the pre-checks refuse is row 2's, not a workflow whose keys are judged (the closed key set would name
|
|
135
|
+
// every key of a YAML that is no workflow at all)
|
|
136
|
+
for (const f of bytes && (0, change_classifier_1.preChecks)(bytes, 'workflow') === null ? (0, self_containment_1.selfContainmentFindings)(bytes) : [])
|
|
137
|
+
out.push({ level: 'finding', axis: ctx.axis, verdict: 'refused', reason: f });
|
|
138
|
+
}
|
|
139
|
+
const row = tableRow(c, ctx);
|
|
140
|
+
out.push(row);
|
|
141
|
+
if (c.kind === 'definition' && row.row !== 3)
|
|
142
|
+
out.push({ level: 'table', axis: ctx.axis, row: 3, verdict: 'needs-signature', reason: 'a change to the detection definition' });
|
|
143
|
+
if (row.verdict === 'admit' && 'config' in cfg && cfg.config.extraSignatureKinds.some((k) => (0, config_loader_1.matchesKind)(k, c.path))) {
|
|
144
|
+
out.push({ level: 'table', axis: ctx.axis, verdict: 'needs-signature', reason: 'extraSignatureKinds' });
|
|
145
|
+
}
|
|
146
|
+
return out;
|
|
147
|
+
}
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Bounded reads over the object port (A-SPEC-792.37 §3 as draft 13 states it). A parsed document over 1 MiB is that
|
|
3
|
+
* entry's `incomplete` ("size"); more than 10,000 protected entries or 120 s on the injected clock is the event's
|
|
4
|
+
* `incomplete` ("entry limit", "time limit"). Ledgers and the queue are never parsed: the append check reads sizes,
|
|
5
|
+
* prefix hashes, the last bytes and, for the union reason, line hashes under a 1,000,000-line cap.
|
|
6
|
+
*/
|
|
7
|
+
import { Clock, ObjectPort, TreeEntry } from './ports';
|
|
8
|
+
export declare const MAX_DOC_BYTES: number;
|
|
9
|
+
export declare const MAX_ENTRIES = 10000;
|
|
10
|
+
export declare const DEADLINE_MS = 120000;
|
|
11
|
+
export declare const MAX_LINES = 1000000;
|
|
12
|
+
/** The event as a whole cannot be judged; `rangeUndefined` when its range is the reason. */
|
|
13
|
+
export declare class EventIncomplete extends Error {
|
|
14
|
+
readonly reason: string;
|
|
15
|
+
readonly rangeUndefined: boolean;
|
|
16
|
+
constructor(reason: string, rangeUndefined?: boolean);
|
|
17
|
+
}
|
|
18
|
+
export type AppendAnswer = {
|
|
19
|
+
ok: true;
|
|
20
|
+
} | {
|
|
21
|
+
ok: false;
|
|
22
|
+
union: boolean;
|
|
23
|
+
};
|
|
24
|
+
/**
|
|
25
|
+
* The port with every failure made an answer (review A-M2): a missing object, a timed-out child or an overflowing
|
|
26
|
+
* buffer is the event's `incomplete` with its reason, never an exception that escapes the judgement.
|
|
27
|
+
*/
|
|
28
|
+
/** @implements A-SPEC-792.50 (review 08:37, N5) — every ObjectPort method, by name: a class instance's methods are not own keys. */
|
|
29
|
+
export declare const PORT_METHODS: ReadonlyArray<keyof ObjectPort>;
|
|
30
|
+
/**
|
|
31
|
+
* @implements A-SPEC-792.50 (review 11:19 L-1) — the clock with every failure made an answer: a throw or a time that is
|
|
32
|
+
* not a finite number is the event's incomplete ("clock failed"), so no exception escapes and NaN never switches the
|
|
33
|
+
* 120 s limit off.
|
|
34
|
+
*/
|
|
35
|
+
export declare function guardClock(clock: Clock): Clock;
|
|
36
|
+
export declare function guardPort(port: ObjectPort): ObjectPort;
|
|
37
|
+
export declare class BoundedObjectReader {
|
|
38
|
+
readonly port: ObjectPort;
|
|
39
|
+
private readonly clock;
|
|
40
|
+
private readonly start;
|
|
41
|
+
private readonly trees;
|
|
42
|
+
constructor(port: ObjectPort, clock: Clock);
|
|
43
|
+
/** Throws EventIncomplete("time limit") once 120 s have passed on the clock (inclusive: 120,000 ms is the limit). */
|
|
44
|
+
tick(): void;
|
|
45
|
+
/** Many documents in one read (null when over 1 MiB). */
|
|
46
|
+
docs(oids: readonly string[]): Map<string, Buffer | null>;
|
|
47
|
+
entries(commit: string | null): TreeEntry[];
|
|
48
|
+
/** A document's bytes, or null when it is over 1 MiB. */
|
|
49
|
+
doc(oid: string): Buffer | null;
|
|
50
|
+
/** Whether `head` appends to `base` (null base = empty), by the streamed rule. */
|
|
51
|
+
append(base: string | null, head: string): AppendAnswer;
|
|
52
|
+
/** Base's lines are an ordered subsequence of head's (a union merge), both under the line cap. */
|
|
53
|
+
private unionInsert;
|
|
54
|
+
/** Whether `after`'s blob still begins with all of `before`'s (a ledger or queue not discarded). */
|
|
55
|
+
isPrefix(before: string, after: string | null): boolean;
|
|
56
|
+
}
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.BoundedObjectReader = exports.PORT_METHODS = exports.EventIncomplete = exports.MAX_LINES = exports.DEADLINE_MS = exports.MAX_ENTRIES = exports.MAX_DOC_BYTES = void 0;
|
|
4
|
+
exports.guardClock = guardClock;
|
|
5
|
+
exports.guardPort = guardPort;
|
|
6
|
+
exports.MAX_DOC_BYTES = 1024 * 1024;
|
|
7
|
+
exports.MAX_ENTRIES = 10_000;
|
|
8
|
+
exports.DEADLINE_MS = 120_000;
|
|
9
|
+
exports.MAX_LINES = 1_000_000;
|
|
10
|
+
/** The event as a whole cannot be judged; `rangeUndefined` when its range is the reason. */
|
|
11
|
+
class EventIncomplete extends Error {
|
|
12
|
+
reason;
|
|
13
|
+
rangeUndefined;
|
|
14
|
+
constructor(reason, rangeUndefined = false) {
|
|
15
|
+
super(reason);
|
|
16
|
+
this.reason = reason;
|
|
17
|
+
this.rangeUndefined = rangeUndefined;
|
|
18
|
+
this.name = 'EventIncomplete';
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
exports.EventIncomplete = EventIncomplete;
|
|
22
|
+
/**
|
|
23
|
+
* The port with every failure made an answer (review A-M2): a missing object, a timed-out child or an overflowing
|
|
24
|
+
* buffer is the event's `incomplete` with its reason, never an exception that escapes the judgement.
|
|
25
|
+
*/
|
|
26
|
+
/** @implements A-SPEC-792.50 (review 08:37, N5) — every ObjectPort method, by name: a class instance's methods are not own keys. */
|
|
27
|
+
exports.PORT_METHODS = ['entries', 'size', 'bytes', 'bytesMany', 'prefixSha256', 'lastByte', 'lineHashes', 'isAncestor', 'mergeBases', 'exists', 'shallow'];
|
|
28
|
+
/**
|
|
29
|
+
* @implements A-SPEC-792.50 (review 11:19 L-1) — the clock with every failure made an answer: a throw or a time that is
|
|
30
|
+
* not a finite number is the event's incomplete ("clock failed"), so no exception escapes and NaN never switches the
|
|
31
|
+
* 120 s limit off.
|
|
32
|
+
*/
|
|
33
|
+
function guardClock(clock) {
|
|
34
|
+
// review 12:32 N5: a clock that steps back fails too — the elapsed time would never reach the limit
|
|
35
|
+
let last = -Infinity;
|
|
36
|
+
return {
|
|
37
|
+
now: () => {
|
|
38
|
+
let t;
|
|
39
|
+
try {
|
|
40
|
+
t = clock.now();
|
|
41
|
+
}
|
|
42
|
+
catch {
|
|
43
|
+
throw new EventIncomplete('clock failed');
|
|
44
|
+
}
|
|
45
|
+
if (typeof t !== 'number' || !Number.isFinite(t) || t < last)
|
|
46
|
+
throw new EventIncomplete('clock failed');
|
|
47
|
+
last = t;
|
|
48
|
+
return t;
|
|
49
|
+
},
|
|
50
|
+
};
|
|
51
|
+
}
|
|
52
|
+
function guardPort(port) {
|
|
53
|
+
const guarded = {};
|
|
54
|
+
for (const name of exports.PORT_METHODS) {
|
|
55
|
+
guarded[name] = (...args) => {
|
|
56
|
+
try {
|
|
57
|
+
const f = port[name];
|
|
58
|
+
if (typeof f !== 'function')
|
|
59
|
+
throw new TypeError(`the port has no ${name}`);
|
|
60
|
+
return f.apply(port, args);
|
|
61
|
+
}
|
|
62
|
+
catch (e) {
|
|
63
|
+
if (e instanceof EventIncomplete)
|
|
64
|
+
throw e;
|
|
65
|
+
throw new EventIncomplete(`object read failed (${name}): ${String(e.message ?? e).slice(0, 160)}`);
|
|
66
|
+
}
|
|
67
|
+
};
|
|
68
|
+
}
|
|
69
|
+
return guarded;
|
|
70
|
+
}
|
|
71
|
+
class BoundedObjectReader {
|
|
72
|
+
port;
|
|
73
|
+
clock;
|
|
74
|
+
start;
|
|
75
|
+
trees = new Map();
|
|
76
|
+
constructor(port, clock) {
|
|
77
|
+
this.port = port;
|
|
78
|
+
this.clock = clock;
|
|
79
|
+
this.start = clock.now();
|
|
80
|
+
}
|
|
81
|
+
/** Throws EventIncomplete("time limit") once 120 s have passed on the clock (inclusive: 120,000 ms is the limit). */
|
|
82
|
+
tick() { if (this.clock.now() - this.start >= exports.DEADLINE_MS)
|
|
83
|
+
throw new EventIncomplete('time limit'); }
|
|
84
|
+
/** Many documents in one read (null when over 1 MiB). */
|
|
85
|
+
docs(oids) { this.tick(); return this.port.bytesMany(oids, exports.MAX_DOC_BYTES); }
|
|
86
|
+
entries(commit) {
|
|
87
|
+
if (commit === null)
|
|
88
|
+
return [];
|
|
89
|
+
let t = this.trees.get(commit);
|
|
90
|
+
if (!t) {
|
|
91
|
+
this.tick();
|
|
92
|
+
t = this.port.entries(commit);
|
|
93
|
+
this.trees.set(commit, t);
|
|
94
|
+
}
|
|
95
|
+
return t;
|
|
96
|
+
}
|
|
97
|
+
/** A document's bytes, or null when it is over 1 MiB. */
|
|
98
|
+
doc(oid) { this.tick(); return this.port.bytes(oid, exports.MAX_DOC_BYTES); }
|
|
99
|
+
/** Whether `head` appends to `base` (null base = empty), by the streamed rule. */
|
|
100
|
+
append(base, head) {
|
|
101
|
+
this.tick();
|
|
102
|
+
const bs = base === null ? 0 : this.port.size(base);
|
|
103
|
+
const hs = this.port.size(head);
|
|
104
|
+
const fail = () => ({ ok: false, union: base !== null && this.unionInsert(base, head) });
|
|
105
|
+
if (bs > 0 && this.port.lastByte(base) !== 0x0a)
|
|
106
|
+
return fail();
|
|
107
|
+
if (hs < bs)
|
|
108
|
+
return fail();
|
|
109
|
+
if (bs > 0 && this.port.prefixSha256(head, bs) !== this.port.prefixSha256(base, bs))
|
|
110
|
+
return fail();
|
|
111
|
+
if (hs > bs && this.port.lastByte(head) !== 0x0a)
|
|
112
|
+
return fail();
|
|
113
|
+
return { ok: true };
|
|
114
|
+
}
|
|
115
|
+
/** Base's lines are an ordered subsequence of head's (a union merge), both under the line cap. */
|
|
116
|
+
unionInsert(base, head) {
|
|
117
|
+
const b = this.port.lineHashes(base, exports.MAX_LINES);
|
|
118
|
+
const h = this.port.lineHashes(head, exports.MAX_LINES);
|
|
119
|
+
if (b === null || h === null || h.length <= b.length)
|
|
120
|
+
return false;
|
|
121
|
+
let i = 0;
|
|
122
|
+
for (const line of h)
|
|
123
|
+
if (i < b.length && line === b[i])
|
|
124
|
+
i++;
|
|
125
|
+
return i === b.length;
|
|
126
|
+
}
|
|
127
|
+
/** Whether `after`'s blob still begins with all of `before`'s (a ledger or queue not discarded). */
|
|
128
|
+
isPrefix(before, after) {
|
|
129
|
+
if (after === null)
|
|
130
|
+
return false;
|
|
131
|
+
const bs = this.port.size(before);
|
|
132
|
+
return this.port.size(after) >= bs && this.port.prefixSha256(after, bs) === this.port.prefixSha256(before, bs);
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
exports.BoundedObjectReader = BoundedObjectReader;
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import { Spec } from '../../spec/spec-parser';
|
|
2
|
+
import { specDigest } from '../../spec/spec-digest';
|
|
3
|
+
export type DocStateName = 'absent' | 'draft' | 'review' | 'approved' | 'outdated' | 'unparseable';
|
|
4
|
+
export interface DocState {
|
|
5
|
+
state: DocStateName;
|
|
6
|
+
reason?: string;
|
|
7
|
+
spec?: Spec;
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* The reason a document fails the pre-checks, or null. `frontmatter` checks a spec or decision document's frontmatter
|
|
11
|
+
* range and the whole document; `workflow` checks a whole YAML file (a detector workflow).
|
|
12
|
+
*/
|
|
13
|
+
export declare function preChecks(bytes: Buffer, mode: 'frontmatter' | 'workflow'): string | null;
|
|
14
|
+
/** A document's state, or `unparseable` with the reason. */
|
|
15
|
+
export declare function docState(bytes: Buffer): DocState;
|
|
16
|
+
/** The id a spec file name starts with, or null. */
|
|
17
|
+
export declare function idOfFileName(p: string): string | null;
|
|
18
|
+
/**
|
|
19
|
+
* Frontmatter id → the head spec paths carrying it (review A-M1: the store finds a spec by the id in its frontmatter,
|
|
20
|
+
* so the index does too). `read` answers a path's bytes, or null when they cannot be read; a document that does not
|
|
21
|
+
* parse carries no id. Paths are every spec-kind path of the head (case-folded, as `kindOf` reads them).
|
|
22
|
+
*/
|
|
23
|
+
export declare function specIndex(paths: readonly string[], read: (p: string) => Buffer | null): Map<string, string[]>;
|
|
24
|
+
/** The key-rule breach of one parsed spec at `p`, or null. */
|
|
25
|
+
export declare function keyRuleBreach(p: string, spec: Spec, index: Map<string, string[]>): string | null;
|
|
26
|
+
/** Paths whose fold (case and NFC) collides with another path's. */
|
|
27
|
+
export declare function foldCollisions(paths: readonly string[]): Set<string>;
|
|
28
|
+
/** Census: every key-rule breach among spec paths at a tree (path → reason). */
|
|
29
|
+
export declare function keyRuleBreaches(paths: string[], read: (p: string) => Buffer): Map<string, string>;
|
|
30
|
+
/** The relation and parent breach of a sealed spec at head (rows 8, 11, 12), or null. */
|
|
31
|
+
export declare function parentBreach(spec: Spec, index: Map<string, string[]>, read: (p: string) => Buffer, cycleCheck: (id: string) => boolean): string | null;
|
|
32
|
+
/** Whether `start` lies on a depends_on cycle among head documents: `start` is reachable from its own parents. */
|
|
33
|
+
export declare function onCycle(start: string, index: Map<string, string[]>, read: (p: string) => Buffer): boolean;
|
|
34
|
+
export { specDigest };
|
|
@@ -0,0 +1,278 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
3
|
+
if (k2 === undefined) k2 = k;
|
|
4
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
5
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
6
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
7
|
+
}
|
|
8
|
+
Object.defineProperty(o, k2, desc);
|
|
9
|
+
}) : (function(o, m, k, k2) {
|
|
10
|
+
if (k2 === undefined) k2 = k;
|
|
11
|
+
o[k2] = m[k];
|
|
12
|
+
}));
|
|
13
|
+
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
14
|
+
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
15
|
+
}) : function(o, v) {
|
|
16
|
+
o["default"] = v;
|
|
17
|
+
});
|
|
18
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
19
|
+
var ownKeys = function(o) {
|
|
20
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
21
|
+
var ar = [];
|
|
22
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
23
|
+
return ar;
|
|
24
|
+
};
|
|
25
|
+
return ownKeys(o);
|
|
26
|
+
};
|
|
27
|
+
return function (mod) {
|
|
28
|
+
if (mod && mod.__esModule) return mod;
|
|
29
|
+
var result = {};
|
|
30
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
31
|
+
__setModuleDefault(result, mod);
|
|
32
|
+
return result;
|
|
33
|
+
};
|
|
34
|
+
})();
|
|
35
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
+
exports.specDigest = void 0;
|
|
37
|
+
exports.preChecks = preChecks;
|
|
38
|
+
exports.docState = docState;
|
|
39
|
+
exports.idOfFileName = idOfFileName;
|
|
40
|
+
exports.specIndex = specIndex;
|
|
41
|
+
exports.keyRuleBreach = keyRuleBreach;
|
|
42
|
+
exports.foldCollisions = foldCollisions;
|
|
43
|
+
exports.keyRuleBreaches = keyRuleBreaches;
|
|
44
|
+
exports.parentBreach = parentBreach;
|
|
45
|
+
exports.onCycle = onCycle;
|
|
46
|
+
// @implements A-SPEC-792.50
|
|
47
|
+
/**
|
|
48
|
+
* The change classifier (A-SPEC-792.37 §2 as A-SPEC-792.50 amends it), on Holmes's own parser and digest.
|
|
49
|
+
*
|
|
50
|
+
* - The pre-checks make a document `unparseable`. In the frontmatter range `parseSpec` reads: an alias, an anchor, a
|
|
51
|
+
* merge key, a duplicate key, a custom tag, a directive or document marker, a `__proto__` / `constructor` /
|
|
52
|
+
* `prototype` key at any depth. Over the whole document: a BOM, a second frontmatter block, bytes that are not UTF-8.
|
|
53
|
+
* - The state maps `parseSpec().status` (draft, review, approved, outdated); a missing, non-string or unknown status is
|
|
54
|
+
* `unparseable`, so the server is never laxer than the parser.
|
|
55
|
+
* - Key rules: one id across the head tree, `specTypeOfId(id) === type` with `type` an own key of SPEC_TYPES, the
|
|
56
|
+
* type's folder, an H-SPEC subdirectory equal to its `req_type`, a file name `<id>.md` or `<id>_<slug>.md`.
|
|
57
|
+
*/
|
|
58
|
+
const yaml = __importStar(require("js-yaml"));
|
|
59
|
+
const spec_parser_1 = require("../../spec/spec-parser");
|
|
60
|
+
const spec_digest_1 = require("../../spec/spec-digest");
|
|
61
|
+
Object.defineProperty(exports, "specDigest", { enumerable: true, get: function () { return spec_digest_1.specDigest; } });
|
|
62
|
+
const spec_types_1 = require("../../spec/spec-types");
|
|
63
|
+
const path_rules_1 = require("./path-rules");
|
|
64
|
+
const FRONTMATTER = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
|
|
65
|
+
const PROTO_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
|
|
66
|
+
const hasOwn = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
|
|
67
|
+
/** The reason a YAML text uses a refused form, or null. */
|
|
68
|
+
function yamlFormsBreach(src) {
|
|
69
|
+
// A directive or a document marker starts at column 0; an indented `%` is a scalar's text (REQ-432, measured). A lone
|
|
70
|
+
// CR is a YAML line break too, and the `m` flag's `^` already starts a line after it (a CR, LF, U+2028 or U+2029).
|
|
71
|
+
if (/^(?:%|\.\.\.(?:[ \t]|$)|---(?:[ \t]|$))/m.test(src))
|
|
72
|
+
return 'a YAML directive or document marker';
|
|
73
|
+
let anchor = false;
|
|
74
|
+
let value;
|
|
75
|
+
try {
|
|
76
|
+
value = yaml.load(src, { schema: yaml.CORE_SCHEMA, listener: (event, state) => { if (event === 'close' && state.anchor)
|
|
77
|
+
anchor = true; } });
|
|
78
|
+
}
|
|
79
|
+
catch (e) {
|
|
80
|
+
return `YAML does not parse (${String(e.message).split('\n')[0]})`;
|
|
81
|
+
}
|
|
82
|
+
if (anchor)
|
|
83
|
+
return 'a YAML anchor or alias';
|
|
84
|
+
const walk = (v) => {
|
|
85
|
+
if (Array.isArray(v)) {
|
|
86
|
+
for (const x of v) {
|
|
87
|
+
const r = walk(x);
|
|
88
|
+
if (r)
|
|
89
|
+
return r;
|
|
90
|
+
}
|
|
91
|
+
return null;
|
|
92
|
+
}
|
|
93
|
+
if (typeof v !== 'object' || v === null)
|
|
94
|
+
return null;
|
|
95
|
+
for (const k of Object.getOwnPropertyNames(v)) {
|
|
96
|
+
if (k === '<<')
|
|
97
|
+
return 'a YAML merge key';
|
|
98
|
+
if (PROTO_KEYS.has(k))
|
|
99
|
+
return `a ${k} key`;
|
|
100
|
+
const r = walk(v[k]);
|
|
101
|
+
if (r)
|
|
102
|
+
return r;
|
|
103
|
+
}
|
|
104
|
+
return null;
|
|
105
|
+
};
|
|
106
|
+
return walk(value);
|
|
107
|
+
}
|
|
108
|
+
/**
|
|
109
|
+
* The reason a document fails the pre-checks, or null. `frontmatter` checks a spec or decision document's frontmatter
|
|
110
|
+
* range and the whole document; `workflow` checks a whole YAML file (a detector workflow).
|
|
111
|
+
*/
|
|
112
|
+
function preChecks(bytes, mode) {
|
|
113
|
+
if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf)
|
|
114
|
+
return 'a BOM';
|
|
115
|
+
let text;
|
|
116
|
+
try {
|
|
117
|
+
text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
|
|
118
|
+
}
|
|
119
|
+
catch {
|
|
120
|
+
return 'bytes that are not UTF-8';
|
|
121
|
+
}
|
|
122
|
+
const raw = text.replace(/\r\n/g, '\n');
|
|
123
|
+
if (mode === 'workflow')
|
|
124
|
+
return yamlFormsBreach(raw);
|
|
125
|
+
const m = FRONTMATTER.exec(raw);
|
|
126
|
+
if (!m)
|
|
127
|
+
return null; // no frontmatter: the state decides (unparseable)
|
|
128
|
+
if (/^\n*---\n/.test(m[2]))
|
|
129
|
+
return 'more than one frontmatter block';
|
|
130
|
+
return yamlFormsBreach(m[1]);
|
|
131
|
+
}
|
|
132
|
+
/** A document's state, or `unparseable` with the reason. */
|
|
133
|
+
function docState(bytes) {
|
|
134
|
+
const pre = preChecks(bytes, 'frontmatter');
|
|
135
|
+
if (pre)
|
|
136
|
+
return { state: 'unparseable', reason: pre };
|
|
137
|
+
let spec;
|
|
138
|
+
try {
|
|
139
|
+
spec = (0, spec_parser_1.parseSpec)(bytes.toString('utf8'));
|
|
140
|
+
}
|
|
141
|
+
catch (e) {
|
|
142
|
+
return { state: 'unparseable', reason: `does not parse (${String(e.message).split('\n')[0]})` };
|
|
143
|
+
}
|
|
144
|
+
const status = spec.frontmatter.status;
|
|
145
|
+
if (typeof status !== 'string')
|
|
146
|
+
return { state: 'unparseable', reason: 'status is missing or not a string' };
|
|
147
|
+
if (!spec_types_1.SPEC_STATUSES.includes(status))
|
|
148
|
+
return { state: 'unparseable', reason: `unknown status ${status}` };
|
|
149
|
+
if (!spec.id)
|
|
150
|
+
return { state: 'unparseable', reason: 'no id' };
|
|
151
|
+
return { state: status, spec };
|
|
152
|
+
}
|
|
153
|
+
/** The id a spec file name starts with, or null. */
|
|
154
|
+
function idOfFileName(p) {
|
|
155
|
+
const base = p.split('/').pop() ?? '';
|
|
156
|
+
return /^((?:REQ|H-SPEC|A-SPEC|C-SPEC|T-SPEC|ADR)-[0-9]+(?:\.[0-9]+)*)(?:_[^/]*)?\.md$/.exec(base)?.[1] ?? null;
|
|
157
|
+
}
|
|
158
|
+
/**
|
|
159
|
+
* Frontmatter id → the head spec paths carrying it (review A-M1: the store finds a spec by the id in its frontmatter,
|
|
160
|
+
* so the index does too). `read` answers a path's bytes, or null when they cannot be read; a document that does not
|
|
161
|
+
* parse carries no id. Paths are every spec-kind path of the head (case-folded, as `kindOf` reads them).
|
|
162
|
+
*/
|
|
163
|
+
function specIndex(paths, read) {
|
|
164
|
+
const out = new Map();
|
|
165
|
+
for (const p of paths) {
|
|
166
|
+
if (!(0, path_rules_1.fold)(p).startsWith(`${path_rules_1.SPEC_ROOT}/`) || !(0, path_rules_1.fold)(p).endsWith('.md'))
|
|
167
|
+
continue;
|
|
168
|
+
const bytes = read(p);
|
|
169
|
+
const id = bytes ? docState(bytes).spec?.id : undefined;
|
|
170
|
+
if (id)
|
|
171
|
+
out.set(id, [...(out.get(id) ?? []), p]);
|
|
172
|
+
}
|
|
173
|
+
return out;
|
|
174
|
+
}
|
|
175
|
+
/** The key-rule breach of one parsed spec at `p`, or null. */
|
|
176
|
+
function keyRuleBreach(p, spec, index) {
|
|
177
|
+
const type = spec.type;
|
|
178
|
+
if (typeof type !== 'string' || !hasOwn(spec_types_1.SPEC_TYPES, type))
|
|
179
|
+
return `type ${String(type)} is not a spec type`;
|
|
180
|
+
if ((0, spec_types_1.specTypeOfId)(spec.id) !== type)
|
|
181
|
+
return `id ${spec.id} is not of type ${type}`;
|
|
182
|
+
const parts = p.split('/');
|
|
183
|
+
const def = spec_types_1.SPEC_TYPES[type];
|
|
184
|
+
if (parts.slice(0, 2).join('/') !== path_rules_1.SPEC_ROOT || parts[2] !== def.folder)
|
|
185
|
+
return `${p} is not in ${def.folder}`;
|
|
186
|
+
const rest = parts.slice(3);
|
|
187
|
+
if (rest.length === 2) {
|
|
188
|
+
const reqType = spec.frontmatter.req_type;
|
|
189
|
+
if (type !== 'H-SPEC' || typeof reqType !== 'string' || reqType !== rest[0])
|
|
190
|
+
return `${p}: the subdirectory is not the req_type`;
|
|
191
|
+
}
|
|
192
|
+
else if (rest.length !== 1)
|
|
193
|
+
return `${p} is too deep`;
|
|
194
|
+
const name = rest[rest.length - 1];
|
|
195
|
+
if (!(name === `${spec.id}.md` || (name.startsWith(`${spec.id}_`) && name.endsWith('.md'))))
|
|
196
|
+
return `${p}: the file name is not the id`;
|
|
197
|
+
if ((index.get(spec.id) ?? []).length !== 1)
|
|
198
|
+
return `id ${spec.id} is at ${(index.get(spec.id) ?? []).length} paths`;
|
|
199
|
+
return null;
|
|
200
|
+
}
|
|
201
|
+
/** Paths whose fold (case and NFC) collides with another path's. */
|
|
202
|
+
function foldCollisions(paths) {
|
|
203
|
+
const groups = new Map();
|
|
204
|
+
for (const p of paths)
|
|
205
|
+
groups.set((0, path_rules_1.fold)(p), [...(groups.get((0, path_rules_1.fold)(p)) ?? []), p]);
|
|
206
|
+
return new Set([...groups.values()].filter((g) => g.length > 1).flat());
|
|
207
|
+
}
|
|
208
|
+
/** Census: every key-rule breach among spec paths at a tree (path → reason). */
|
|
209
|
+
function keyRuleBreaches(paths, read) {
|
|
210
|
+
const index = specIndex(paths, read);
|
|
211
|
+
const out = new Map();
|
|
212
|
+
const collisions = foldCollisions(paths);
|
|
213
|
+
for (const p of paths) {
|
|
214
|
+
if (collisions.has(p)) {
|
|
215
|
+
out.set(p, 'case or NFC collision');
|
|
216
|
+
continue;
|
|
217
|
+
}
|
|
218
|
+
const st = docState(read(p));
|
|
219
|
+
if (st.state === 'unparseable' || !st.spec)
|
|
220
|
+
continue;
|
|
221
|
+
const b = keyRuleBreach(p, st.spec, index);
|
|
222
|
+
if (b)
|
|
223
|
+
out.set(p, b);
|
|
224
|
+
}
|
|
225
|
+
return out;
|
|
226
|
+
}
|
|
227
|
+
/** The relation and parent breach of a sealed spec at head (rows 8, 11, 12), or null. */
|
|
228
|
+
function parentBreach(spec, index, read, cycleCheck) {
|
|
229
|
+
const def = spec_types_1.SPEC_TYPES[spec.type];
|
|
230
|
+
const fm = spec.frontmatter;
|
|
231
|
+
const digests = (typeof fm.parent_digests === 'object' && fm.parent_digests !== null ? fm.parent_digests : {});
|
|
232
|
+
if (def.parents.length === 0 && spec.dependsOn.length > 0)
|
|
233
|
+
return 'root-has-parent';
|
|
234
|
+
if (def.parents.length > 0 && spec.dependsOn.length === 0)
|
|
235
|
+
return 'orphan';
|
|
236
|
+
for (const key of Object.keys(digests))
|
|
237
|
+
if (!spec.dependsOn.includes(key))
|
|
238
|
+
return `parent_digests names ${key}, which is not in depends_on`;
|
|
239
|
+
for (const pid of spec.dependsOn) {
|
|
240
|
+
const at = index.get(pid) ?? [];
|
|
241
|
+
if (at.length !== 1)
|
|
242
|
+
return `parent ${pid} resolves to ${at.length} documents`;
|
|
243
|
+
const ps = docState(read(at[0]));
|
|
244
|
+
if (!ps.spec)
|
|
245
|
+
return `parent ${pid} does not parse`;
|
|
246
|
+
if (!def.parents.includes(ps.spec.type))
|
|
247
|
+
return `wrong-parent-type: ${pid} is ${ps.spec.type}`;
|
|
248
|
+
if (ps.state !== 'approved')
|
|
249
|
+
return `parent ${pid} is ${ps.state}`;
|
|
250
|
+
const sealed = ps.spec.frontmatter.approved_digest;
|
|
251
|
+
if (digests[pid] === undefined || digests[pid] !== sealed || sealed !== (0, spec_digest_1.specDigest)(ps.spec))
|
|
252
|
+
return `parent ${pid}'s digest does not match`;
|
|
253
|
+
}
|
|
254
|
+
if (cycleCheck(spec.id))
|
|
255
|
+
return 'a depends_on cycle';
|
|
256
|
+
return null;
|
|
257
|
+
}
|
|
258
|
+
/** Whether `start` lies on a depends_on cycle among head documents: `start` is reachable from its own parents. */
|
|
259
|
+
function onCycle(start, index, read) {
|
|
260
|
+
const deps = (id) => {
|
|
261
|
+
const at = index.get(id) ?? [];
|
|
262
|
+
if (at.length !== 1)
|
|
263
|
+
return [];
|
|
264
|
+
return docState(read(at[0])).spec?.dependsOn ?? [];
|
|
265
|
+
};
|
|
266
|
+
const seen = new Set();
|
|
267
|
+
const todo = [...deps(start)];
|
|
268
|
+
while (todo.length > 0) {
|
|
269
|
+
const id = todo.pop();
|
|
270
|
+
if (id === start)
|
|
271
|
+
return true;
|
|
272
|
+
if (seen.has(id))
|
|
273
|
+
continue;
|
|
274
|
+
seen.add(id);
|
|
275
|
+
todo.push(...deps(id));
|
|
276
|
+
}
|
|
277
|
+
return false;
|
|
278
|
+
}
|