owenloop 0.5.9 → 0.5.10
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 +44 -0
- package/README.md +77 -37
- package/bin/owenloop.mjs +16 -1
- package/dist/packages/work/src/agent/loop.js +7 -0
- package/dist/packages/work/src/bundle/pull.d.ts +21 -0
- package/dist/packages/work/src/bundle/pull.js +118 -0
- package/dist/packages/work/src/exec/instructions.d.ts +4 -1
- package/dist/packages/work/src/exec/instructions.js +3 -0
- package/dist/packages/work/src/exec/loop.d.ts +1 -1
- package/dist/packages/work/src/exec/loop.js +92 -14
- package/dist/packages/work/src/harness/claude.js +16 -0
- package/dist/packages/work/src/harness/codex.d.ts +8 -0
- package/dist/packages/work/src/harness/codex.js +27 -1
- package/dist/packages/work/src/harness/contract.d.ts +9 -0
- package/dist/packages/work/src/roles/agent-run.js +38 -10
- package/dist/packages/work/src/roles/exec.js +25 -8
- package/dist/packages/work/src/shift/loop.js +118 -4
- package/dist/packages/work/src/shift/runtime.d.ts +3 -0
- package/dist/packages/work/src/shift/runtime.js +10 -1
- package/dist/packages/work/src/submit-proof.d.ts +11 -8
- package/dist/packages/work/src/submit-proof.js +11 -8
- package/dist/src/capabilities.d.ts +70 -6
- package/dist/src/capabilities.js +49 -6
- package/dist/src/capability-mapping-client.d.ts +29 -0
- package/dist/src/capability-mapping-client.js +160 -0
- package/dist/src/cli.d.ts +2 -2
- package/dist/src/cli.js +1196 -164
- package/dist/src/defs.d.ts +32 -1
- package/dist/src/defs.js +391 -79
- package/dist/src/engine.d.ts +62 -19
- package/dist/src/engine.js +180 -70
- package/dist/src/hub.d.ts +77 -0
- package/dist/src/hub.js +162 -0
- package/dist/src/implements.d.ts +56 -0
- package/dist/src/implements.js +790 -0
- package/dist/src/index.d.ts +8 -6
- package/dist/src/index.js +4 -3
- package/dist/src/mcp/serve.js +254 -45
- package/dist/src/mcp/server.d.ts +10 -7
- package/dist/src/mcp/server.js +53 -8
- package/dist/src/model.d.ts +46 -10
- package/dist/src/model.js +220 -74
- package/dist/src/store/def-source.d.ts +19 -0
- package/dist/src/store/def-source.js +87 -17
- package/dist/src/store/gc-recovery.d.ts +46 -0
- package/dist/src/store/gc-recovery.js +258 -0
- package/dist/src/store/gc.d.ts +94 -0
- package/dist/src/store/gc.js +562 -0
- package/dist/src/store/index.d.ts +3 -1
- package/dist/src/store/index.js +2 -0
- package/dist/src/store/install.d.ts +34 -5
- package/dist/src/store/install.js +73 -11
- package/dist/src/store/pre-commit-verifier.js +42 -2
- package/dist/src/store/snapshot-guard.d.ts +18 -0
- package/dist/src/store/snapshot-guard.js +94 -0
- package/dist/src/store.d.ts +64 -4
- package/dist/src/store.js +211 -8
- package/dist/src/types.d.ts +61 -17
- package/dist/src/util.js +4 -1
- package/docs/authoring.md +145 -8
- package/docs/bundles.md +19 -0
- package/docs/cli.md +270 -30
- package/docs/crypto.md +13 -7
- package/docs/design.md +107 -46
- package/docs/evals/mcp-charter-baseline.json +428 -0
- package/docs/mcp-charter-eval.md +124 -0
- package/docs/shift-logs.md +18 -0
- package/docs/wire-contracts.md +28 -7
- package/examples/workflows/compile-dev-playbook.yaml +1 -1
- package/examples/workflows/ship.yaml +28 -2
- package/package.json +2 -1
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
- package/plugins/claude-code/plugin/.mcp.json +1 -1
- package/plugins/claude-code/plugin/skills/author/SKILL.md +22 -0
- package/plugins/claude-code/plugin/skills/ephemeral/SKILL.md +95 -0
- package/plugins/claude-code/plugin/skills/graduate/SKILL.md +156 -0
- package/plugins/claude-code/plugin/skills/plan/SKILL.md +236 -0
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
- package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
- package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +22 -0
- package/plugins/codex/plugins/owenloop/skills/ephemeral/SKILL.md +95 -0
- package/plugins/codex/plugins/owenloop/skills/graduate/SKILL.md +156 -0
- package/plugins/codex/plugins/owenloop/skills/plan/SKILL.md +236 -0
package/dist/src/defs.d.ts
CHANGED
|
@@ -96,6 +96,22 @@ export declare function digestScopedCallsTargetKey(digest: string, target: strin
|
|
|
96
96
|
* spawns at runtime.
|
|
97
97
|
*/
|
|
98
98
|
export declare function resolveCallsTarget(defs: Map<string, WorkflowDef>, target: string, from: WorkflowDef): WorkflowDef | undefined;
|
|
99
|
+
/** A calls cycle and the resolved definition keys on its displayed path. */
|
|
100
|
+
export interface CallsCycleFinding {
|
|
101
|
+
message: string;
|
|
102
|
+
members: string[];
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* Report calls cycles in a flat def map. This is the Mode 2 analogue of the
|
|
106
|
+
* Mode 1 include-cycle guard in expandIncludes; the two edge kinds stay
|
|
107
|
+
* deliberately separate. Findings use resolved map identity, not bare call
|
|
108
|
+
* text, so CAS bundle siblings cannot be accidentally fused. The first finding
|
|
109
|
+
* is strict loading's legacy DFS witness. Further findings add at most one
|
|
110
|
+
* deterministic witness for each still-unattributed cyclic member, keeping
|
|
111
|
+
* authoring attribution polynomial and every finding's members consistent with
|
|
112
|
+
* its displayed path without enumerating exponentially many simple cycles.
|
|
113
|
+
*/
|
|
114
|
+
export declare function reportCallsCycles(defs: Map<string, WorkflowDef>): CallsCycleFinding[];
|
|
99
115
|
/** Load and validate a single workflow definition from a YAML file. */
|
|
100
116
|
export declare function loadDefFile(file: string): WorkflowDef;
|
|
101
117
|
/**
|
|
@@ -130,7 +146,8 @@ export declare function loadDefsUnfinalized(dir: string): Map<string, WorkflowDe
|
|
|
130
146
|
* (each def possibly still carrying `_includes`), it: expands each def's
|
|
131
147
|
* includes; runs the cross-def `calls:` checks (target existence, `callsInputs`
|
|
132
148
|
* key validity, exactly-one child output); runs `validateDef` per expanded def;
|
|
133
|
-
* and finally
|
|
149
|
+
* and finally performs the bounded first-cycle DFS over the whole expanded map.
|
|
150
|
+
* `reportCallsCycles` exposes the wider per-member authoring report. Returns the
|
|
134
151
|
* expanded, validated map. Throws `DefError` on the first problem — the same
|
|
135
152
|
* messages, in the same order, the filesystem loader has always produced (this
|
|
136
153
|
* is a pure extraction of what used to live inline in `loadDefs`).
|
|
@@ -153,6 +170,12 @@ export interface FinalizeDefsOptions {
|
|
|
153
170
|
*/
|
|
154
171
|
allowUnresolvedCalls?: boolean;
|
|
155
172
|
}
|
|
173
|
+
/**
|
|
174
|
+
* Return every direct cross-definition `calls:` error for one expanded
|
|
175
|
+
* definition. Strict loading uses the first result to retain its historical
|
|
176
|
+
* throw behavior; tolerant authoring commands can present the complete list.
|
|
177
|
+
*/
|
|
178
|
+
export declare function validateCallsEdges(def: WorkflowDef, defs: Map<string, WorkflowDef>, options?: FinalizeDefsOptions): string[];
|
|
156
179
|
export declare function finalizeDefs(raw: Map<string, WorkflowDef>, options?: FinalizeDefsOptions): Map<string, WorkflowDef>;
|
|
157
180
|
/** One file that `loadDefsRaw` could not turn into a def (malformed YAML, bad shape, duplicate name). */
|
|
158
181
|
export interface DefLoadFailure {
|
|
@@ -168,4 +191,12 @@ export interface DefLoadFailure {
|
|
|
168
191
|
* Two-phase: Phase 1 collects all defs. Phase 2 expands includes best-effort
|
|
169
192
|
* (silently skips expansion failures so the lint caller sees un-expanded defs).
|
|
170
193
|
*/
|
|
194
|
+
export declare function scanDefsRaw(dir: string, failures?: DefLoadFailure[]): Map<string, WorkflowDef>;
|
|
195
|
+
/** Best-effort include expansion for a complete, already-merged raw map. */
|
|
196
|
+
export declare function expandDefsRaw(raw: Map<string, WorkflowDef>): Map<string, WorkflowDef>;
|
|
197
|
+
/**
|
|
198
|
+
* Compatibility wrapper for tolerant single-directory loading. Raw loading
|
|
199
|
+
* builds and expands includes best-effort; callers explicitly invoke shared
|
|
200
|
+
* calls validation and cycle reporting against the complete definition map.
|
|
201
|
+
*/
|
|
171
202
|
export declare function loadDefsRaw(dir: string, failures?: DefLoadFailure[]): Map<string, WorkflowDef>;
|
package/dist/src/defs.js
CHANGED
|
@@ -915,13 +915,23 @@ export function expandIncludes(def, resolve, stack) {
|
|
|
915
915
|
stepIdx++;
|
|
916
916
|
}
|
|
917
917
|
}
|
|
918
|
-
|
|
918
|
+
const expanded = {
|
|
919
919
|
...def,
|
|
920
920
|
steps: resultSteps,
|
|
921
921
|
inputs: resultInputs,
|
|
922
922
|
outputs: resultOutputs.length > 0 ? resultOutputs : def.outputs,
|
|
923
923
|
_includes: undefined,
|
|
924
924
|
};
|
|
925
|
+
// CAS store roots are live loader provenance, deliberately non-enumerable so
|
|
926
|
+
// they never enter hashes or persisted snapshots. The spread above therefore
|
|
927
|
+
// cannot carry them. Preserve the original descriptor explicitly so an
|
|
928
|
+
// include-expanded CAS definition still coordinates its snapshot writes with
|
|
929
|
+
// bundle GC.
|
|
930
|
+
const storeRoots = Object.getOwnPropertyDescriptor(def, 'bundleStoreRoots');
|
|
931
|
+
if (storeRoots !== undefined) {
|
|
932
|
+
Object.defineProperty(expanded, 'bundleStoreRoots', storeRoots);
|
|
933
|
+
}
|
|
934
|
+
return expanded;
|
|
925
935
|
}
|
|
926
936
|
/** Build a validated `WorkflowDef` from a parsed YAML object (or throw DefError). */
|
|
927
937
|
export function parseDef(raw, source, baseDir) {
|
|
@@ -1893,6 +1903,150 @@ function unroutedCapabilityWarnings(def) {
|
|
|
1893
1903
|
}
|
|
1894
1904
|
return warnings;
|
|
1895
1905
|
}
|
|
1906
|
+
/** Whether a discovery-convention value is a YAML mapping. */
|
|
1907
|
+
function isDiscoveryMap(value) {
|
|
1908
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
1909
|
+
}
|
|
1910
|
+
/**
|
|
1911
|
+
* Return advisory issues for Owenloop's optional x.discovery convention.
|
|
1912
|
+
*
|
|
1913
|
+
* This deliberately does not assign a severity. W2.1 can promote these same
|
|
1914
|
+
* deterministic issues for library definitions without duplicating validation.
|
|
1915
|
+
* The parser and engine continue to treat all extension contents as opaque.
|
|
1916
|
+
*/
|
|
1917
|
+
function discoveryIssues(def) {
|
|
1918
|
+
const issues = [];
|
|
1919
|
+
const discovery = def.x?.discovery;
|
|
1920
|
+
if (discovery === undefined)
|
|
1921
|
+
return ['x.discovery: missing required discovery metadata'];
|
|
1922
|
+
if (!isDiscoveryMap(discovery))
|
|
1923
|
+
return ['x.discovery: expected a map'];
|
|
1924
|
+
const requiredString = (value, path) => {
|
|
1925
|
+
if (typeof value !== 'string' || value.trim() === '') {
|
|
1926
|
+
issues.push(path + ': expected a non-empty string');
|
|
1927
|
+
return undefined;
|
|
1928
|
+
}
|
|
1929
|
+
return value;
|
|
1930
|
+
};
|
|
1931
|
+
const requiredPhraseList = (value, path) => {
|
|
1932
|
+
if (!Array.isArray(value) || value.length === 0) {
|
|
1933
|
+
issues.push(path + ': expected a non-empty array of non-empty strings');
|
|
1934
|
+
return;
|
|
1935
|
+
}
|
|
1936
|
+
for (const [index, item] of value.entries())
|
|
1937
|
+
requiredString(item, path + '[' + index + ']');
|
|
1938
|
+
};
|
|
1939
|
+
/**
|
|
1940
|
+
* Validate a mapping in the order its fields were authored. Required
|
|
1941
|
+
* fields absent from the mapping follow in the convention's fixed order,
|
|
1942
|
+
* making both kinds of diagnostic deterministic.
|
|
1943
|
+
*/
|
|
1944
|
+
const visitMapFields = (value, allowed, path, visitKnownField) => {
|
|
1945
|
+
const allowedSet = new Set(allowed);
|
|
1946
|
+
const present = new Set();
|
|
1947
|
+
for (const key of Object.keys(value)) {
|
|
1948
|
+
if (!allowedSet.has(key)) {
|
|
1949
|
+
issues.push(path + '.' + key + ': unknown field');
|
|
1950
|
+
continue;
|
|
1951
|
+
}
|
|
1952
|
+
present.add(key);
|
|
1953
|
+
visitKnownField(key, value[key]);
|
|
1954
|
+
}
|
|
1955
|
+
for (const key of allowed)
|
|
1956
|
+
if (!present.has(key))
|
|
1957
|
+
visitKnownField(key, undefined);
|
|
1958
|
+
};
|
|
1959
|
+
const inputs = new Map(def.inputs.map((input) => [input.name, { schema: input.schema }]));
|
|
1960
|
+
const outputs = new Map((def.outputs ?? []).map((name) => {
|
|
1961
|
+
const artifact = def.steps.flatMap((step) => [...step.produces, ...(step.generates ?? [])])
|
|
1962
|
+
.find((produce) => produce.stem === name);
|
|
1963
|
+
return [name, { schema: artifact?.schema }];
|
|
1964
|
+
}));
|
|
1965
|
+
const validateInterfaceEntries = (value, path, declared) => {
|
|
1966
|
+
const fieldPath = 'x.discovery.interface.' + path;
|
|
1967
|
+
const singular = path === 'inputs' ? 'input' : 'output';
|
|
1968
|
+
if (!Array.isArray(value)) {
|
|
1969
|
+
issues.push(fieldPath + ': expected an array');
|
|
1970
|
+
return;
|
|
1971
|
+
}
|
|
1972
|
+
const seen = new Set();
|
|
1973
|
+
for (const [index, entry] of value.entries()) {
|
|
1974
|
+
const entryPath = fieldPath + '[' + index + ']';
|
|
1975
|
+
if (!isDiscoveryMap(entry)) {
|
|
1976
|
+
issues.push(entryPath + ': expected a map');
|
|
1977
|
+
continue;
|
|
1978
|
+
}
|
|
1979
|
+
visitMapFields(entry, ['name', 'summary', 'schemaRef'], entryPath, (key, fieldValue) => {
|
|
1980
|
+
switch (key) {
|
|
1981
|
+
case 'name': {
|
|
1982
|
+
const name = requiredString(fieldValue, entryPath + '.name');
|
|
1983
|
+
if (name === undefined)
|
|
1984
|
+
break;
|
|
1985
|
+
// Record every non-blank name before declaration lookup. This
|
|
1986
|
+
// preserves both useful findings for repeated unknown names.
|
|
1987
|
+
if (seen.has(name)) {
|
|
1988
|
+
issues.push(entryPath + '.name: duplicate workflow ' + singular + " '" + name + "'");
|
|
1989
|
+
}
|
|
1990
|
+
else {
|
|
1991
|
+
seen.add(name);
|
|
1992
|
+
}
|
|
1993
|
+
const artifact = declared.get(name);
|
|
1994
|
+
if (artifact === undefined) {
|
|
1995
|
+
issues.push(entryPath + '.name: unknown workflow ' + singular + " '" + name + "'");
|
|
1996
|
+
}
|
|
1997
|
+
else if (artifact.schema === undefined) {
|
|
1998
|
+
issues.push(entryPath + '.schemaRef: workflow ' + singular + " '" + name + "' has no schema");
|
|
1999
|
+
}
|
|
2000
|
+
break;
|
|
2001
|
+
}
|
|
2002
|
+
case 'summary':
|
|
2003
|
+
requiredString(fieldValue, entryPath + '.summary');
|
|
2004
|
+
break;
|
|
2005
|
+
case 'schemaRef': {
|
|
2006
|
+
const schemaRef = requiredString(fieldValue, entryPath + '.schemaRef');
|
|
2007
|
+
if (schemaRef !== undefined && !schemaRef.startsWith('#/')) {
|
|
2008
|
+
issues.push(entryPath + '.schemaRef: expected a local JSON pointer starting with \'#/\'');
|
|
2009
|
+
}
|
|
2010
|
+
break;
|
|
2011
|
+
}
|
|
2012
|
+
}
|
|
2013
|
+
});
|
|
2014
|
+
}
|
|
2015
|
+
for (const name of declared.keys()) {
|
|
2016
|
+
if (!seen.has(name))
|
|
2017
|
+
issues.push(fieldPath + ': missing workflow ' + singular + " '" + name + "'");
|
|
2018
|
+
}
|
|
2019
|
+
};
|
|
2020
|
+
const validateInterface = (value) => {
|
|
2021
|
+
if (!isDiscoveryMap(value)) {
|
|
2022
|
+
issues.push('x.discovery.interface: expected a map');
|
|
2023
|
+
return;
|
|
2024
|
+
}
|
|
2025
|
+
visitMapFields(value, ['inputs', 'outputs'], 'x.discovery.interface', (key, fieldValue) => {
|
|
2026
|
+
if (key === 'inputs')
|
|
2027
|
+
validateInterfaceEntries(fieldValue, 'inputs', inputs);
|
|
2028
|
+
else
|
|
2029
|
+
validateInterfaceEntries(fieldValue, 'outputs', outputs);
|
|
2030
|
+
});
|
|
2031
|
+
};
|
|
2032
|
+
visitMapFields(discovery, ['description', 'whenToUse', 'notFor', 'interface'], 'x.discovery', (key, value) => {
|
|
2033
|
+
switch (key) {
|
|
2034
|
+
case 'description':
|
|
2035
|
+
requiredString(value, 'x.discovery.description');
|
|
2036
|
+
break;
|
|
2037
|
+
case 'whenToUse':
|
|
2038
|
+
requiredPhraseList(value, 'x.discovery.whenToUse');
|
|
2039
|
+
break;
|
|
2040
|
+
case 'notFor':
|
|
2041
|
+
requiredPhraseList(value, 'x.discovery.notFor');
|
|
2042
|
+
break;
|
|
2043
|
+
case 'interface':
|
|
2044
|
+
validateInterface(value);
|
|
2045
|
+
break;
|
|
2046
|
+
}
|
|
2047
|
+
});
|
|
2048
|
+
return issues;
|
|
2049
|
+
}
|
|
1896
2050
|
/**
|
|
1897
2051
|
* Static lint over a workflow definition. Returns both the hard errors from
|
|
1898
2052
|
* `validateDef` (which `parseDef` / `loadDefFile` would throw on) and
|
|
@@ -1906,7 +2060,7 @@ function unroutedCapabilityWarnings(def) {
|
|
|
1906
2060
|
export function lintDef(def) {
|
|
1907
2061
|
const errors = validateDef(def);
|
|
1908
2062
|
const warnings = errors.length === 0
|
|
1909
|
-
? [...deadEndWarnings(def), ...danglingReduceSuffixWarnings(def), ...unroutedCapabilityWarnings(def)]
|
|
2063
|
+
? [...deadEndWarnings(def), ...danglingReduceSuffixWarnings(def), ...unroutedCapabilityWarnings(def), ...discoveryIssues(def)]
|
|
1910
2064
|
: [];
|
|
1911
2065
|
return { errors, warnings };
|
|
1912
2066
|
}
|
|
@@ -1982,49 +2136,195 @@ export function resolveCallsTarget(defs, target, from) {
|
|
|
1982
2136
|
const key = resolveCallsTargetKey(defs, target, from);
|
|
1983
2137
|
return key === undefined ? undefined : defs.get(key);
|
|
1984
2138
|
}
|
|
1985
|
-
|
|
2139
|
+
function buildCallsGraph(defs) {
|
|
2140
|
+
const keys = [...defs.keys()];
|
|
2141
|
+
const edges = new Map();
|
|
2142
|
+
for (const [key, def] of defs) {
|
|
2143
|
+
// WS-6: graph nodes are RESOLVED map keys, not bare calls text. Two bundles
|
|
2144
|
+
// may both export `build` without being fused into one graph node.
|
|
2145
|
+
const children = new Set();
|
|
2146
|
+
for (const step of def.steps) {
|
|
2147
|
+
if (step.calls === undefined)
|
|
2148
|
+
continue;
|
|
2149
|
+
const child = resolveCallsTargetKey(defs, step.calls, def);
|
|
2150
|
+
if (child !== undefined)
|
|
2151
|
+
children.add(child);
|
|
2152
|
+
}
|
|
2153
|
+
edges.set(key, [...children]);
|
|
2154
|
+
}
|
|
2155
|
+
return {
|
|
2156
|
+
keys,
|
|
2157
|
+
order: new Map(keys.map((key, index) => [key, index])),
|
|
2158
|
+
edges,
|
|
2159
|
+
};
|
|
2160
|
+
}
|
|
1986
2161
|
/**
|
|
1987
|
-
*
|
|
1988
|
-
*
|
|
1989
|
-
*
|
|
1990
|
-
*
|
|
1991
|
-
* Called from loadDefs Phase 2 after all defs are expanded and per-def validated.
|
|
2162
|
+
* Preserve the original tri-color DFS exactly for strict loading. It stops at
|
|
2163
|
+
* the first back edge, so finalizeDefs remains O(V+E) and retains its stable
|
|
2164
|
+
* first-cycle message and traversal precedence.
|
|
1992
2165
|
*/
|
|
1993
|
-
function
|
|
2166
|
+
function findFirstCallsCycle(graph) {
|
|
1994
2167
|
const WHITE = 0, GREY = 1, BLACK = 2;
|
|
1995
|
-
const color = new Map(
|
|
2168
|
+
const color = new Map(graph.keys.map((key) => [key, WHITE]));
|
|
1996
2169
|
const stack = [];
|
|
1997
|
-
|
|
1998
|
-
|
|
1999
|
-
|
|
2000
|
-
|
|
2001
|
-
|
|
2002
|
-
|
|
2003
|
-
|
|
2004
|
-
|
|
2005
|
-
|
|
2006
|
-
|
|
2007
|
-
|
|
2008
|
-
const callsEdges = new Set((def?.steps ?? []).filter((l) => l.calls).map((l) => l.calls));
|
|
2009
|
-
for (const edge of callsEdges) {
|
|
2010
|
-
const child = def === undefined ? undefined : resolveCallsTargetKey(defs, edge, def);
|
|
2011
|
-
if (child === undefined)
|
|
2012
|
-
continue; // missing-def error is reported separately in loadDefs
|
|
2013
|
-
const c = color.get(child) ?? WHITE;
|
|
2014
|
-
if (c === GREY) {
|
|
2015
|
-
const from = stack.indexOf(child);
|
|
2016
|
-
throw new DefError(`calls cycle: ${[...stack.slice(from), child].join(' -> ')}`);
|
|
2170
|
+
const visit = (key) => {
|
|
2171
|
+
color.set(key, GREY);
|
|
2172
|
+
stack.push(key);
|
|
2173
|
+
for (const child of graph.edges.get(key) ?? []) {
|
|
2174
|
+
const state = color.get(child) ?? WHITE;
|
|
2175
|
+
if (state === GREY)
|
|
2176
|
+
return [...stack.slice(stack.indexOf(child)), child];
|
|
2177
|
+
if (state === WHITE) {
|
|
2178
|
+
const found = visit(child);
|
|
2179
|
+
if (found !== undefined)
|
|
2180
|
+
return found;
|
|
2017
2181
|
}
|
|
2018
|
-
if (c === WHITE)
|
|
2019
|
-
visit(child);
|
|
2020
2182
|
}
|
|
2021
2183
|
stack.pop();
|
|
2022
|
-
color.set(
|
|
2184
|
+
color.set(key, BLACK);
|
|
2185
|
+
return undefined;
|
|
2186
|
+
};
|
|
2187
|
+
for (const key of graph.keys) {
|
|
2188
|
+
if ((color.get(key) ?? WHITE) !== WHITE)
|
|
2189
|
+
continue;
|
|
2190
|
+
const found = visit(key);
|
|
2191
|
+
if (found !== undefined)
|
|
2192
|
+
return found;
|
|
2193
|
+
}
|
|
2194
|
+
return undefined;
|
|
2195
|
+
}
|
|
2196
|
+
function cycleFingerprint(cycle) {
|
|
2197
|
+
const members = cycle.slice(0, -1);
|
|
2198
|
+
return members
|
|
2199
|
+
.map((_, index) => [...members.slice(index), ...members.slice(0, index)].join('\u0000'))
|
|
2200
|
+
.sort()[0] ?? '';
|
|
2201
|
+
}
|
|
2202
|
+
function canonicalizeCycle(cycle, order) {
|
|
2203
|
+
const members = cycle.slice(0, -1);
|
|
2204
|
+
let first = 0;
|
|
2205
|
+
for (let index = 1; index < members.length; index++) {
|
|
2206
|
+
if ((order.get(members[index]) ?? Number.MAX_SAFE_INTEGER) < (order.get(members[first]) ?? Number.MAX_SAFE_INTEGER)) {
|
|
2207
|
+
first = index;
|
|
2208
|
+
}
|
|
2209
|
+
}
|
|
2210
|
+
const rotated = [...members.slice(first), ...members.slice(0, first)];
|
|
2211
|
+
return [...rotated, rotated[0]];
|
|
2212
|
+
}
|
|
2213
|
+
/** Return each cyclic SCC, indexed by every member, using deterministic Tarjan traversal. */
|
|
2214
|
+
function cyclicComponentsByMember(graph) {
|
|
2215
|
+
let nextIndex = 0;
|
|
2216
|
+
const index = new Map();
|
|
2217
|
+
const lowlink = new Map();
|
|
2218
|
+
const stack = [];
|
|
2219
|
+
const onStack = new Set();
|
|
2220
|
+
const byMember = new Map();
|
|
2221
|
+
const visit = (key) => {
|
|
2222
|
+
index.set(key, nextIndex);
|
|
2223
|
+
lowlink.set(key, nextIndex);
|
|
2224
|
+
nextIndex++;
|
|
2225
|
+
stack.push(key);
|
|
2226
|
+
onStack.add(key);
|
|
2227
|
+
for (const child of graph.edges.get(key) ?? []) {
|
|
2228
|
+
if (!index.has(child)) {
|
|
2229
|
+
visit(child);
|
|
2230
|
+
lowlink.set(key, Math.min(lowlink.get(key), lowlink.get(child)));
|
|
2231
|
+
}
|
|
2232
|
+
else if (onStack.has(child)) {
|
|
2233
|
+
lowlink.set(key, Math.min(lowlink.get(key), index.get(child)));
|
|
2234
|
+
}
|
|
2235
|
+
}
|
|
2236
|
+
if (lowlink.get(key) !== index.get(key))
|
|
2237
|
+
return;
|
|
2238
|
+
const members = [];
|
|
2239
|
+
while (stack.length > 0) {
|
|
2240
|
+
const member = stack.pop();
|
|
2241
|
+
onStack.delete(member);
|
|
2242
|
+
members.push(member);
|
|
2243
|
+
if (member === key)
|
|
2244
|
+
break;
|
|
2245
|
+
}
|
|
2246
|
+
const cyclic = members.length > 1 || (graph.edges.get(key) ?? []).includes(key);
|
|
2247
|
+
if (!cyclic)
|
|
2248
|
+
return;
|
|
2249
|
+
const component = new Set(members);
|
|
2250
|
+
for (const member of members)
|
|
2251
|
+
byMember.set(member, component);
|
|
2252
|
+
};
|
|
2253
|
+
for (const key of graph.keys) {
|
|
2254
|
+
if (!index.has(key))
|
|
2255
|
+
visit(key);
|
|
2256
|
+
}
|
|
2257
|
+
return byMember;
|
|
2258
|
+
}
|
|
2259
|
+
/** Find one deterministic simple cycle through member inside its cyclic SCC. */
|
|
2260
|
+
function cycleThroughMember(member, component, graph) {
|
|
2261
|
+
const pathBack = (key, target, path, seen) => {
|
|
2262
|
+
for (const child of graph.edges.get(key) ?? []) {
|
|
2263
|
+
if (!component.has(child))
|
|
2264
|
+
continue;
|
|
2265
|
+
if (child === target)
|
|
2266
|
+
return [...path, child];
|
|
2267
|
+
if (seen.has(child))
|
|
2268
|
+
continue;
|
|
2269
|
+
seen.add(child);
|
|
2270
|
+
const found = pathBack(child, target, [...path, child], seen);
|
|
2271
|
+
if (found !== undefined)
|
|
2272
|
+
return found;
|
|
2273
|
+
}
|
|
2274
|
+
return undefined;
|
|
2023
2275
|
};
|
|
2024
|
-
for (const
|
|
2025
|
-
if (
|
|
2026
|
-
|
|
2276
|
+
for (const child of graph.edges.get(member) ?? []) {
|
|
2277
|
+
if (!component.has(child))
|
|
2278
|
+
continue;
|
|
2279
|
+
if (child === member)
|
|
2280
|
+
return [member, member];
|
|
2281
|
+
const found = pathBack(child, member, [child], new Set([member, child]));
|
|
2282
|
+
if (found !== undefined)
|
|
2283
|
+
return [member, ...found];
|
|
2027
2284
|
}
|
|
2285
|
+
return undefined;
|
|
2286
|
+
}
|
|
2287
|
+
/**
|
|
2288
|
+
* Report calls cycles in a flat def map. This is the Mode 2 analogue of the
|
|
2289
|
+
* Mode 1 include-cycle guard in expandIncludes; the two edge kinds stay
|
|
2290
|
+
* deliberately separate. Findings use resolved map identity, not bare call
|
|
2291
|
+
* text, so CAS bundle siblings cannot be accidentally fused. The first finding
|
|
2292
|
+
* is strict loading's legacy DFS witness. Further findings add at most one
|
|
2293
|
+
* deterministic witness for each still-unattributed cyclic member, keeping
|
|
2294
|
+
* authoring attribution polynomial and every finding's members consistent with
|
|
2295
|
+
* its displayed path without enumerating exponentially many simple cycles.
|
|
2296
|
+
*/
|
|
2297
|
+
export function reportCallsCycles(defs) {
|
|
2298
|
+
const graph = buildCallsGraph(defs);
|
|
2299
|
+
const first = findFirstCallsCycle(graph);
|
|
2300
|
+
if (first === undefined)
|
|
2301
|
+
return [];
|
|
2302
|
+
const cycles = [first];
|
|
2303
|
+
const seen = new Set([cycleFingerprint(first)]);
|
|
2304
|
+
const attributed = new Set(first.slice(0, -1));
|
|
2305
|
+
const components = cyclicComponentsByMember(graph);
|
|
2306
|
+
for (const member of graph.keys) {
|
|
2307
|
+
if (attributed.has(member))
|
|
2308
|
+
continue;
|
|
2309
|
+
const component = components.get(member);
|
|
2310
|
+
if (component === undefined)
|
|
2311
|
+
continue;
|
|
2312
|
+
const witness = cycleThroughMember(member, component, graph);
|
|
2313
|
+
if (witness === undefined)
|
|
2314
|
+
continue; // unreachable for a member of a cyclic SCC
|
|
2315
|
+
const cycle = canonicalizeCycle(witness, graph.order);
|
|
2316
|
+
for (const cycleMember of cycle.slice(0, -1))
|
|
2317
|
+
attributed.add(cycleMember);
|
|
2318
|
+
const fingerprint = cycleFingerprint(cycle);
|
|
2319
|
+
if (seen.has(fingerprint))
|
|
2320
|
+
continue;
|
|
2321
|
+
seen.add(fingerprint);
|
|
2322
|
+
cycles.push(cycle);
|
|
2323
|
+
}
|
|
2324
|
+
return cycles.map((cycle) => ({
|
|
2325
|
+
message: `calls cycle: ${cycle.join(' -> ')}`,
|
|
2326
|
+
members: cycle.slice(0, -1),
|
|
2327
|
+
}));
|
|
2028
2328
|
}
|
|
2029
2329
|
// ---- filesystem loading ------------------------------------------------------
|
|
2030
2330
|
/** Load and validate a single workflow definition from a YAML file. */
|
|
@@ -2103,51 +2403,59 @@ export function loadDefsUnfinalized(dir) {
|
|
|
2103
2403
|
}
|
|
2104
2404
|
return raw;
|
|
2105
2405
|
}
|
|
2406
|
+
/**
|
|
2407
|
+
* Return every direct cross-definition `calls:` error for one expanded
|
|
2408
|
+
* definition. Strict loading uses the first result to retain its historical
|
|
2409
|
+
* throw behavior; tolerant authoring commands can present the complete list.
|
|
2410
|
+
*/
|
|
2411
|
+
export function validateCallsEdges(def, defs, options = {}) {
|
|
2412
|
+
const errors = [];
|
|
2413
|
+
for (const step of def.steps) {
|
|
2414
|
+
if (!step.calls)
|
|
2415
|
+
continue;
|
|
2416
|
+
const childDef = resolveCallsTarget(defs, step.calls, def);
|
|
2417
|
+
if (!childDef) {
|
|
2418
|
+
if (options.allowUnresolvedCalls !== true
|
|
2419
|
+
&& options.allowUnresolvedVersionedCalls?.has(step.calls) !== true) {
|
|
2420
|
+
errors.push(`calls names workflow '${step.calls}' which does not exist`);
|
|
2421
|
+
}
|
|
2422
|
+
continue;
|
|
2423
|
+
}
|
|
2424
|
+
const childInputNames = new Set(childDef.inputs.map((input) => input.name));
|
|
2425
|
+
for (const key of Object.keys(step.callsInputs ?? {})) {
|
|
2426
|
+
if (!childInputNames.has(key)) {
|
|
2427
|
+
errors.push(`calls '${step.name}' maps input '${key}' which workflow '${step.calls}' does not declare`);
|
|
2428
|
+
}
|
|
2429
|
+
}
|
|
2430
|
+
const childOutputs = childDef.outputs ?? [];
|
|
2431
|
+
if (childOutputs.length === 0) {
|
|
2432
|
+
errors.push(`calls names workflow '${step.calls}' which declares no outputs:`);
|
|
2433
|
+
}
|
|
2434
|
+
if (childOutputs.length > 1) {
|
|
2435
|
+
errors.push(`calls names workflow '${step.calls}' which declares ${childOutputs.length} outputs:, calls: v1 requires exactly one`);
|
|
2436
|
+
}
|
|
2437
|
+
}
|
|
2438
|
+
return errors;
|
|
2439
|
+
}
|
|
2106
2440
|
export function finalizeDefs(raw, options = {}) {
|
|
2107
2441
|
const out = new Map();
|
|
2108
2442
|
const resolver = (name) => raw.get(name);
|
|
2109
2443
|
for (const [name, def] of raw) {
|
|
2110
2444
|
const expanded = expandIncludes(def, resolver);
|
|
2111
|
-
|
|
2112
|
-
|
|
2113
|
-
|
|
2114
|
-
// WS-6: `calls:` targets resolve through `resolveCallsTarget` (scope-aware),
|
|
2115
|
-
// NOT through the plain `resolver` used for `include:` expansion above.
|
|
2116
|
-
// `include:` is a DIFFERENT edge kind and is deliberately left on the flat
|
|
2117
|
-
// lookup — this workstream is `calls:`-only.
|
|
2118
|
-
for (const l of expanded.steps) {
|
|
2119
|
-
if (!l.calls)
|
|
2120
|
-
continue;
|
|
2121
|
-
const childDef = resolveCallsTarget(raw, l.calls, expanded);
|
|
2122
|
-
if (!childDef) {
|
|
2123
|
-
if (options.allowUnresolvedCalls === true
|
|
2124
|
-
|| options.allowUnresolvedVersionedCalls?.has(l.calls) === true)
|
|
2125
|
-
continue;
|
|
2126
|
-
throw new DefError(`calls names workflow '${l.calls}' which does not exist`);
|
|
2127
|
-
}
|
|
2128
|
-
const childInputNames = new Set(childDef.inputs.map((i) => i.name));
|
|
2129
|
-
for (const k of Object.keys(l.callsInputs ?? {})) {
|
|
2130
|
-
if (!childInputNames.has(k)) {
|
|
2131
|
-
throw new DefError(`calls '${l.name}' maps input '${k}' which workflow '${l.calls}' does not declare`);
|
|
2132
|
-
}
|
|
2133
|
-
}
|
|
2134
|
-
// M2B-OUTCOME v1: the called workflow must declare exactly one output.
|
|
2135
|
-
const childOutputs = childDef.outputs ?? [];
|
|
2136
|
-
if (childOutputs.length === 0) {
|
|
2137
|
-
throw new DefError(`calls names workflow '${l.calls}' which declares no outputs:`);
|
|
2138
|
-
}
|
|
2139
|
-
if (childOutputs.length > 1) {
|
|
2140
|
-
throw new DefError(`calls names workflow '${l.calls}' which declares ${childOutputs.length} outputs:, calls: v1 requires exactly one`);
|
|
2141
|
-
}
|
|
2142
|
-
}
|
|
2445
|
+
const callsErrors = validateCallsEdges(expanded, raw, options);
|
|
2446
|
+
if (callsErrors.length > 0)
|
|
2447
|
+
throw new DefError(callsErrors[0]);
|
|
2143
2448
|
const errors = validateDef(expanded);
|
|
2144
2449
|
if (errors.length) {
|
|
2145
2450
|
throw new DefError(`invalid workflow '${name}' (${def.dir ?? 'unknown'}):\n - ${errors.join('\n - ')}`);
|
|
2146
2451
|
}
|
|
2147
2452
|
out.set(name, expanded);
|
|
2148
2453
|
}
|
|
2149
|
-
//
|
|
2150
|
-
|
|
2454
|
+
// Preserve strict loading's first, stable cycle error after all per-def checks
|
|
2455
|
+
// without paying the wider authoring reporter's per-member attribution cost.
|
|
2456
|
+
const cycle = findFirstCallsCycle(buildCallsGraph(out));
|
|
2457
|
+
if (cycle !== undefined)
|
|
2458
|
+
throw new DefError(`calls cycle: ${cycle.join(' -> ')}`);
|
|
2151
2459
|
return out;
|
|
2152
2460
|
}
|
|
2153
2461
|
/**
|
|
@@ -2159,7 +2467,7 @@ export function finalizeDefs(raw, options = {}) {
|
|
|
2159
2467
|
* Two-phase: Phase 1 collects all defs. Phase 2 expands includes best-effort
|
|
2160
2468
|
* (silently skips expansion failures so the lint caller sees un-expanded defs).
|
|
2161
2469
|
*/
|
|
2162
|
-
export function
|
|
2470
|
+
export function scanDefsRaw(dir, failures) {
|
|
2163
2471
|
// Phase 1: build all defs, skipping (and recording) malformed files.
|
|
2164
2472
|
const raw = new Map();
|
|
2165
2473
|
const tryAdd = (file) => {
|
|
@@ -2189,7 +2497,10 @@ export function loadDefsRaw(dir, failures) {
|
|
|
2189
2497
|
tryAdd(full);
|
|
2190
2498
|
}
|
|
2191
2499
|
}
|
|
2192
|
-
|
|
2500
|
+
return raw;
|
|
2501
|
+
}
|
|
2502
|
+
/** Best-effort include expansion for a complete, already-merged raw map. */
|
|
2503
|
+
export function expandDefsRaw(raw) {
|
|
2193
2504
|
const out = new Map();
|
|
2194
2505
|
const resolver = (name) => raw.get(name);
|
|
2195
2506
|
for (const [name, def] of raw) {
|
|
@@ -2202,12 +2513,13 @@ export function loadDefsRaw(dir, failures) {
|
|
|
2202
2513
|
out.set(name, def);
|
|
2203
2514
|
}
|
|
2204
2515
|
}
|
|
2205
|
-
// M2-CYCLE: best-effort calls-cycle check so lint can surface cycle errors.
|
|
2206
|
-
try {
|
|
2207
|
-
detectCallsCycles(out);
|
|
2208
|
-
}
|
|
2209
|
-
catch {
|
|
2210
|
-
// Cycle errors are surfaced via validateDef in the lint caller; swallow here.
|
|
2211
|
-
}
|
|
2212
2516
|
return out;
|
|
2213
2517
|
}
|
|
2518
|
+
/**
|
|
2519
|
+
* Compatibility wrapper for tolerant single-directory loading. Raw loading
|
|
2520
|
+
* builds and expands includes best-effort; callers explicitly invoke shared
|
|
2521
|
+
* calls validation and cycle reporting against the complete definition map.
|
|
2522
|
+
*/
|
|
2523
|
+
export function loadDefsRaw(dir, failures) {
|
|
2524
|
+
return expandDefsRaw(scanDefsRaw(dir, failures));
|
|
2525
|
+
}
|