akm-cli 0.10.261128 → 0.10.261129
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 +22 -0
- package/dist/cli.js +2 -0
- package/dist/commands/agent/contribute-cli.js +7 -1
- package/dist/commands/backups-cli.js +103 -0
- package/dist/commands/health.js +1 -34
- package/dist/commands/improve/reflect-noise.js +0 -1
- package/dist/commands/lint/base-linter.js +24 -48
- package/dist/commands/lint/bundle-skip.js +27 -0
- package/dist/commands/lint/index.js +83 -45
- package/dist/commands/lint/tracked-secrets.js +43 -0
- package/dist/commands/lint/types.js +58 -0
- package/dist/commands/proposal/repository.js +5 -1
- package/dist/commands/sources/stash-skeleton.js +7 -26
- package/dist/core/adapter/adapters/akm-adapter.js +2 -2
- package/dist/core/adapter/adapters/akm-workflow-adapter.js +6 -1
- package/dist/core/adapter/adapters/shared.js +13 -25
- package/dist/core/asset/lint-text.js +14 -13
- package/dist/core/asset/stale-path.js +63 -0
- package/dist/core/config/schema/sources-bundles.js +3 -0
- package/dist/output/shapes/passthrough.js +1 -0
- package/dist/output/text/lint-format.js +90 -1
- package/dist/output/text/migrate.js +5 -0
- package/dist/scripts/akm-migrate-node.js +1149 -791
- package/dist/scripts/akm-migrate.js +1149 -791
- package/dist/sources/include.js +1 -1
- package/dist/sources/snapshot-fetchers/website-ingest.js +0 -2
- package/dist/workspace/backups.js +21 -0
- package/dist/workspace/cli-child.js +5 -1
- package/dist/workspace-node.mjs +2 -0
- package/dist/workspace.d.ts +4 -0
- package/dist/workspace.js +1 -0
- package/docs/architecture/internals/health-advisories.md +1 -2
- package/docs/guides/bundles.md +5 -4
- package/docs/integration/bundling-akm.md +9 -1
- package/docs/reference/asset-types.md +1 -2
- package/docs/reference/cli.md +83 -3
- package/docs/reference/configuration.md +8 -2
- package/docs/reference/data-and-telemetry.md +1 -0
- package/docs/reference/env-and-secrets.md +9 -4
- package/docs/reference/website-sources.md +2 -2
- package/docs/reference/workspace.md +1 -0
- package/package.json +1 -1
- package/schemas/akm-config.json +34 -0
- package/dist/commands/health/stash-exposure.js +0 -64
|
@@ -7,20 +7,24 @@ import { factDiagnostics, MAX_SKILL_GROUP_DEPTH, matchWorkflowPlaceholder, memor
|
|
|
7
7
|
import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
|
|
8
8
|
import { adapterForId } from "../../core/adapter/registry.js";
|
|
9
9
|
import { createValidateContext } from "../../core/adapter/validate-context.js";
|
|
10
|
-
import { stashDirFor } from "../../core/asset/asset-placement.js";
|
|
10
|
+
import { refForFile, stashDirFor, typeForStashDir } from "../../core/asset/asset-placement.js";
|
|
11
11
|
import { parseFrontmatter } from "../../core/asset/frontmatter.js";
|
|
12
12
|
import { conceptIdForStashFile, displayRefForConceptId } from "../../core/asset/resolve-ref.js";
|
|
13
|
+
import { stalePathRoots } from "../../core/asset/stale-path.js";
|
|
13
14
|
import { deriveBundleIds } from "../../core/bundle-id.js";
|
|
14
15
|
import { compareCodePoints, isAkmRegistryCachePath, resolveStashDir, safeRealpath, samePath } from "../../core/common.js";
|
|
15
16
|
import { loadConfig, primaryBundlePath } from "../../core/config/config.js";
|
|
17
|
+
import { bundleKeyForContentRoot } from "../../core/config/config-sources.js";
|
|
16
18
|
import { UsageError } from "../../core/errors.js";
|
|
17
19
|
import { warn } from "../../core/warn.js";
|
|
18
20
|
import { resolveSourceEntries } from "../../indexer/search/search-source.js";
|
|
19
21
|
import { TASK_EXTENSION, TASK_NEAR_MISS_EXTENSION, taskExtensionDetail } from "../../tasks/source-v3.js";
|
|
20
22
|
import { resolveWorkflowSourceDomains } from "../../workflows/source-files.js";
|
|
21
23
|
import { runBaseChecks } from "./base-linter.js";
|
|
24
|
+
import { bundleLintSkip } from "./bundle-skip.js";
|
|
22
25
|
import { checkEnvForDangerousKeys } from "./env-key-rules.js";
|
|
23
|
-
import {
|
|
26
|
+
import { trackedSecretIssues } from "./tracked-secrets.js";
|
|
27
|
+
import { isAdvisoryLintIssue, LINT_RULES } from "./types.js";
|
|
24
28
|
// ── Constants ─────────────────────────────────────────────────────────────────
|
|
25
29
|
const STASH_SUBDIRS = [
|
|
26
30
|
"agents",
|
|
@@ -222,19 +226,9 @@ const KNOWN_ADAPTER_ISSUE_TYPES = new Set([
|
|
|
222
226
|
]);
|
|
223
227
|
/** Map one adapter {@link Diagnostic} onto a {@link LintIssue} — see `types.ts`'s `"adapter-diagnostic"` doc comment for the open→closed reconciliation. */
|
|
224
228
|
export function diagnosticToLintIssue(diag) {
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
if (KNOWN_ADAPTER_ISSUE_TYPES.has(diag.issue)) {
|
|
229
|
-
return { file: diag.file, issue: diag.issue, detail: diag.detail, fixed: diag.fixed, ...location };
|
|
230
|
-
}
|
|
231
|
-
return {
|
|
232
|
-
file: diag.file,
|
|
233
|
-
issue: "adapter-diagnostic",
|
|
234
|
-
detail: `[${diag.issue}] ${diag.detail}`,
|
|
235
|
-
fixed: diag.fixed,
|
|
236
|
-
...location,
|
|
237
|
-
};
|
|
229
|
+
if (KNOWN_ADAPTER_ISSUE_TYPES.has(diag.issue))
|
|
230
|
+
return { ...diag, issue: diag.issue };
|
|
231
|
+
return { ...diag, issue: "adapter-diagnostic", detail: `[${diag.issue}] ${diag.detail}` };
|
|
238
232
|
}
|
|
239
233
|
/**
|
|
240
234
|
* Lint a bundle through its OWN adapter's `validate()`: the
|
|
@@ -298,13 +292,7 @@ async function lintViaAdapter(adapterId, stashRoot, extraStashRoots, sources, cf
|
|
|
298
292
|
flagged.push(issue);
|
|
299
293
|
}
|
|
300
294
|
}
|
|
301
|
-
return {
|
|
302
|
-
ok: true,
|
|
303
|
-
fixed: [],
|
|
304
|
-
flagged,
|
|
305
|
-
warnings,
|
|
306
|
-
summary: { fixed: 0, flagged: flagged.length, warnings: warnings.length },
|
|
307
|
-
};
|
|
295
|
+
return { fixed: [], flagged, warnings };
|
|
308
296
|
}
|
|
309
297
|
function lintIssueDedupeKey(issue) {
|
|
310
298
|
return `${issue.file} ${issue.issue} ${issue.detail}`;
|
|
@@ -466,6 +454,8 @@ function appendMemoryStubIssue(ctx, issues) {
|
|
|
466
454
|
* both halves.
|
|
467
455
|
*/
|
|
468
456
|
function appendWorkflowStubIssue(ctx, issues) {
|
|
457
|
+
if (ctx.lintSkip?.includes("placeholder-stub"))
|
|
458
|
+
return;
|
|
469
459
|
const placeholder = matchWorkflowPlaceholder(ctx.body);
|
|
470
460
|
if (!placeholder)
|
|
471
461
|
return;
|
|
@@ -534,7 +524,8 @@ export function lintAssetFile(ctx, subdir) {
|
|
|
534
524
|
}
|
|
535
525
|
/** Lint one asset file of `subdir` and file its findings into `sinks` (the sweep loop body, shared with {@link lintFile}). */
|
|
536
526
|
function lintSweepFile(filePath, relPath, subdir, scope, { fixed, flagged, warnings }) {
|
|
537
|
-
const { stashRoot, extraStashRoots, fix, pruneDanglingEdges,
|
|
527
|
+
const { stashRoot, extraStashRoots, fix, pruneDanglingEdges, stalePathRoots } = scope;
|
|
528
|
+
const lintSkip = [...(scope.lintSkip ?? []), ...(scope.bundleSkip?.(relPath) ?? [])];
|
|
538
529
|
let raw;
|
|
539
530
|
try {
|
|
540
531
|
raw = fs.readFileSync(filePath, "utf8");
|
|
@@ -545,6 +536,7 @@ function lintSweepFile(filePath, relPath, subdir, scope, { fixed, flagged, warni
|
|
|
545
536
|
let data;
|
|
546
537
|
let body;
|
|
547
538
|
let frontmatter;
|
|
539
|
+
let bodyStartLine = 1;
|
|
548
540
|
// File-identity findings the per-type rules cannot produce: they describe
|
|
549
541
|
// the FILE (its extension, whether it parsed at all), not its fields.
|
|
550
542
|
const fileIssues = [];
|
|
@@ -564,7 +556,7 @@ function lintSweepFile(filePath, relPath, subdir, scope, { fixed, flagged, warni
|
|
|
564
556
|
frontmatter = null;
|
|
565
557
|
}
|
|
566
558
|
else {
|
|
567
|
-
({ data, content: body, frontmatter } = parseFrontmatter(raw));
|
|
559
|
+
({ data, content: body, frontmatter, bodyStartLine } = parseFrontmatter(raw));
|
|
568
560
|
}
|
|
569
561
|
// One file's checks — including its `--fix` mutations — must never abort
|
|
570
562
|
// the sweep: an uncaught throw here left the caller with an exception and
|
|
@@ -582,9 +574,11 @@ function lintSweepFile(filePath, relPath, subdir, scope, { fixed, flagged, warni
|
|
|
582
574
|
data,
|
|
583
575
|
body,
|
|
584
576
|
frontmatter,
|
|
577
|
+
bodyStartLine,
|
|
585
578
|
fix,
|
|
586
579
|
pruneDanglingEdges,
|
|
587
580
|
stashRoot,
|
|
581
|
+
stalePathRoots,
|
|
588
582
|
extraStashRoots,
|
|
589
583
|
lintSkip,
|
|
590
584
|
}, subdir),
|
|
@@ -662,6 +656,8 @@ function lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options) {
|
|
|
662
656
|
const fixed = [];
|
|
663
657
|
const flagged = [];
|
|
664
658
|
const warnings = [];
|
|
659
|
+
const bundleSkip = bundleLintSkip(cfg, stashRoot);
|
|
660
|
+
const roots = stalePathRoots(cfg, stashRoot);
|
|
665
661
|
const dirsToScan = options.typeFilter ? STASH_SUBDIRS.filter((d) => d === options.typeFilter) : STASH_SUBDIRS;
|
|
666
662
|
for (const subdir of dirsToScan) {
|
|
667
663
|
const dirPath = path.join(stashRoot, subdir);
|
|
@@ -705,7 +701,14 @@ function lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options) {
|
|
|
705
701
|
// rewrote files inside the registry cache.
|
|
706
702
|
if (isAkmRegistryCachePath(filePath))
|
|
707
703
|
continue;
|
|
708
|
-
lintSweepFile(filePath, path.relative(stashRoot, filePath), subdir, {
|
|
704
|
+
lintSweepFile(filePath, path.relative(stashRoot, filePath), subdir, {
|
|
705
|
+
stashRoot,
|
|
706
|
+
extraStashRoots,
|
|
707
|
+
fix,
|
|
708
|
+
pruneDanglingEdges: options.pruneDanglingEdges === true,
|
|
709
|
+
stalePathRoots: roots,
|
|
710
|
+
bundleSkip,
|
|
711
|
+
}, { fixed, flagged, warnings });
|
|
709
712
|
}
|
|
710
713
|
}
|
|
711
714
|
// ── Env dangerous-key pass ─────────────────────────────────────────────────
|
|
@@ -722,13 +725,7 @@ function lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options) {
|
|
|
722
725
|
// 2. `ok` is the shared `{ok, error, code}` failure indicator across the
|
|
723
726
|
// whole CLI; reusing it for "found stuff" forced callers to disambiguate
|
|
724
727
|
// a successful-but-flagged run from a hard error by inspecting fields.
|
|
725
|
-
return {
|
|
726
|
-
ok: true,
|
|
727
|
-
fixed,
|
|
728
|
-
flagged,
|
|
729
|
-
warnings,
|
|
730
|
-
summary: { fixed: fixed.length, flagged: flagged.length, warnings: warnings.length },
|
|
731
|
-
};
|
|
728
|
+
return { fixed, flagged, warnings };
|
|
732
729
|
}
|
|
733
730
|
/** The configured bundle root (or `--dir`) that contains `file`, deepest first; undefined when `file` is outside every bundle. */
|
|
734
731
|
function containingBundleRoot(file, roots) {
|
|
@@ -785,15 +782,7 @@ async function lintFile(file, options, cfg) {
|
|
|
785
782
|
if (adapterId !== "akm") {
|
|
786
783
|
const result = await lintViaAdapter(adapterId, root, sources.map((s) => s.path).filter((p) => p !== root && fs.existsSync(p)), sources, cfg, { ...options, typeFilter: undefined });
|
|
787
784
|
const only = (issues) => issues.filter((i) => path.resolve(realRoot, i.file) === absFile);
|
|
788
|
-
|
|
789
|
-
const warnings = only(result.warnings);
|
|
790
|
-
return {
|
|
791
|
-
ok: true,
|
|
792
|
-
fixed: [],
|
|
793
|
-
flagged,
|
|
794
|
-
warnings,
|
|
795
|
-
summary: { fixed: 0, flagged: flagged.length, warnings: warnings.length },
|
|
796
|
-
};
|
|
785
|
+
return finishLint({ fixed: [], flagged: only(result.flagged), warnings: only(result.warnings) }, cfg, options, root);
|
|
797
786
|
}
|
|
798
787
|
// The type comes from where the file sits, as the bundle sweep decides it.
|
|
799
788
|
const located = STASH_SUBDIRS.find((d) => relPath.split(path.sep)[0] === d);
|
|
@@ -831,16 +820,57 @@ async function lintFile(file, options, cfg) {
|
|
|
831
820
|
: [],
|
|
832
821
|
fix: options.fix === true,
|
|
833
822
|
pruneDanglingEdges: false,
|
|
823
|
+
stalePathRoots: stalePathRoots(cfg, root ?? path.dirname(absFile)),
|
|
824
|
+
bundleSkip: root ? bundleLintSkip(cfg, root) : undefined,
|
|
834
825
|
// Outside a bundle there are no other assets to resolve refs or a derived stub against.
|
|
835
826
|
lintSkip: root ? undefined : ["missing-ref", "orphaned-stub"],
|
|
836
827
|
}, sinks);
|
|
837
|
-
|
|
828
|
+
return finishLint(sinks, cfg, options, root);
|
|
829
|
+
}
|
|
830
|
+
/** The ref of an asset of the bundle at `root` by its bundle-relative `file`; undefined when `file` is not an asset path. */
|
|
831
|
+
function refOfFile(root, file, cfg) {
|
|
832
|
+
const type = typeForStashDir(file.split(/[\\/]/)[0] ?? "");
|
|
833
|
+
const conceptId = type ? refForFile(type, root, path.join(root, file)) : undefined;
|
|
834
|
+
if (conceptId === undefined)
|
|
835
|
+
return undefined;
|
|
836
|
+
const bundleId = bundleKeyForContentRoot(cfg, root);
|
|
837
|
+
return displayRefForConceptId(conceptId, bundleId, cfg.defaultBundle);
|
|
838
|
+
}
|
|
839
|
+
/**
|
|
840
|
+
* Turn what a pass found into the result: drop what the bundle's `lint.skip`
|
|
841
|
+
* names, give each finding its asset ref, narrow to `--rule`, and count the
|
|
842
|
+
* flagged findings per rule.
|
|
843
|
+
*/
|
|
844
|
+
function finishLint(found, cfg, options, root) {
|
|
845
|
+
const skippedRules = root ? bundleLintSkip(cfg, root) : () => [];
|
|
846
|
+
let rule = options.rule;
|
|
847
|
+
if (rule !== undefined && !LINT_RULES.includes(rule)) {
|
|
848
|
+
warn(`Warning: lint --rule "${rule}" is not a lint rule — valid rules: ${LINT_RULES.join(", ")}. Showing every rule.`);
|
|
849
|
+
rule = undefined;
|
|
850
|
+
}
|
|
851
|
+
const keep = (issue) => (rule === undefined || issue.issue === rule) && !skippedRules(issue.file).includes(issue.issue);
|
|
852
|
+
const fixed = found.fixed.filter((issue) => rule === undefined || issue.issue === rule);
|
|
853
|
+
const flagged = found.flagged.filter(keep);
|
|
854
|
+
const warnings = found.warnings.filter(keep);
|
|
855
|
+
if (root) {
|
|
856
|
+
for (const issue of [...fixed, ...flagged, ...warnings])
|
|
857
|
+
issue.ref ??= refOfFile(root, issue.file, cfg);
|
|
858
|
+
}
|
|
859
|
+
const byRule = {};
|
|
860
|
+
const assetsByRule = new Map();
|
|
861
|
+
for (const issue of flagged) {
|
|
862
|
+
const assets = (assetsByRule.get(issue.issue) ?? new Set()).add(issue.file);
|
|
863
|
+
assetsByRule.set(issue.issue, assets);
|
|
864
|
+
byRule[issue.issue] = { findings: (byRule[issue.issue]?.findings ?? 0) + 1, assets: assets.size };
|
|
865
|
+
}
|
|
838
866
|
return {
|
|
839
867
|
ok: true,
|
|
840
868
|
fixed,
|
|
841
869
|
flagged,
|
|
842
870
|
warnings,
|
|
843
871
|
summary: { fixed: fixed.length, flagged: flagged.length, warnings: warnings.length },
|
|
872
|
+
byRule,
|
|
873
|
+
...(rule === undefined ? {} : { rule }),
|
|
844
874
|
};
|
|
845
875
|
}
|
|
846
876
|
/**
|
|
@@ -855,6 +885,9 @@ async function lintFile(file, options, cfg) {
|
|
|
855
885
|
* `commands/improve/preparation.ts`) or is a test that can `await` it.
|
|
856
886
|
*/
|
|
857
887
|
export async function akmLint(options = {}) {
|
|
888
|
+
if (options.rule !== undefined && (options.fix || options.pruneDanglingEdges)) {
|
|
889
|
+
throw new UsageError("lint: --rule lists findings; run it without --fix or --prune-dangling-edges.", "INVALID_FLAG_VALUE");
|
|
890
|
+
}
|
|
858
891
|
// Fail closed on a mistyped invocation (§24.2 "Lint" release gate): a
|
|
859
892
|
// nonexistent --dir used to walk nothing and report a clean
|
|
860
893
|
// `ok:true, flagged:0`, silently passing scripted --fail-on-flagged gates.
|
|
@@ -873,8 +906,11 @@ export async function akmLint(options = {}) {
|
|
|
873
906
|
const configuredAdapter = sources.find((source) => samePath(source.path, stashRoot))?.adapterId;
|
|
874
907
|
const adapterId = configuredAdapter ?? detectAdapterId(stashRoot);
|
|
875
908
|
const extraStashRoots = sources.map((s) => s.path).filter((p) => p !== stashRoot && fs.existsSync(p));
|
|
876
|
-
if (adapterId !== "akm")
|
|
877
|
-
|
|
909
|
+
if (adapterId !== "akm") {
|
|
910
|
+
const found = await lintViaAdapter(adapterId, stashRoot, extraStashRoots, sources, cfg, options);
|
|
911
|
+
found.flagged.push(...trackedSecretIssues(stashRoot));
|
|
912
|
+
return finishLint(found, cfg, options, stashRoot);
|
|
913
|
+
}
|
|
878
914
|
// Same fail-closed rule for --type on the akm sweep: an unknown value used
|
|
879
915
|
// to filter the walk to ZERO directories — a false-clean result on the
|
|
880
916
|
// classic singular/plural typo ("workflow" for "workflows"). Non-akm
|
|
@@ -884,5 +920,7 @@ export async function akmLint(options = {}) {
|
|
|
884
920
|
`valid types: ${STASH_SUBDIRS.join(", ")}. The whole bundle was validated.`);
|
|
885
921
|
options = { ...options, typeFilter: undefined };
|
|
886
922
|
}
|
|
887
|
-
|
|
923
|
+
const found = lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options);
|
|
924
|
+
found.flagged.push(...trackedSecretIssues(stashRoot));
|
|
925
|
+
return finishLint(found, cfg, options, stashRoot);
|
|
888
926
|
}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
// This Source Code Form is subject to the terms of the Mozilla Public
|
|
2
|
+
// License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
3
|
+
// file, You can obtain one at https://mozilla.org/MPL/2.0/.
|
|
4
|
+
/**
|
|
5
|
+
* The `tracked-secrets` rule. Versioning a bundle is supported, so a tracked
|
|
6
|
+
* `env/` or `secrets/` file is not wrong by itself. The leak moment is a
|
|
7
|
+
* tracked file in a bundle that has a remote: only then can a `git push`
|
|
8
|
+
* send tokens or keys away. Lint flags exactly that, one finding per tracked
|
|
9
|
+
* file so each can be untracked or skipped (`lint.skip`) on its own.
|
|
10
|
+
*/
|
|
11
|
+
import { spawnSync } from "node:child_process";
|
|
12
|
+
import fs from "node:fs";
|
|
13
|
+
import path from "node:path";
|
|
14
|
+
const realGit = (bundleRoot, args) => {
|
|
15
|
+
const result = spawnSync("git", ["-C", bundleRoot, ...args], { encoding: "utf8", timeout: 5_000 });
|
|
16
|
+
return { ok: result.status === 0, stdout: (result.stdout ?? "").trim() };
|
|
17
|
+
};
|
|
18
|
+
/**
|
|
19
|
+
* One finding per `env/` or `secrets/` file the git repository at `bundleRoot`
|
|
20
|
+
* tracks, when the repository has a remote. Empty for a bundle without its own
|
|
21
|
+
* `.git` (unless a `git` seam is given), without a remote, or with nothing tracked.
|
|
22
|
+
*/
|
|
23
|
+
export function trackedSecretIssues(bundleRoot, git = realGit) {
|
|
24
|
+
if (git === realGit && !fs.existsSync(path.join(bundleRoot, ".git")))
|
|
25
|
+
return [];
|
|
26
|
+
if (!git(bundleRoot, ["rev-parse", "--is-inside-work-tree"]).ok)
|
|
27
|
+
return [];
|
|
28
|
+
const tracked = git(bundleRoot, ["ls-files", "--", "env", "secrets"]);
|
|
29
|
+
if (!tracked.ok || tracked.stdout.length === 0)
|
|
30
|
+
return [];
|
|
31
|
+
const remotes = git(bundleRoot, ["remote"]);
|
|
32
|
+
if (!remotes.ok || remotes.stdout.length === 0)
|
|
33
|
+
return [];
|
|
34
|
+
return tracked.stdout
|
|
35
|
+
.split("\n")
|
|
36
|
+
.filter(Boolean)
|
|
37
|
+
.map((file) => ({
|
|
38
|
+
file,
|
|
39
|
+
issue: "tracked-secrets",
|
|
40
|
+
detail: "tracked by git in a bundle with a remote, so a push can leak it",
|
|
41
|
+
fixed: false,
|
|
42
|
+
}));
|
|
43
|
+
}
|
|
@@ -1,6 +1,64 @@
|
|
|
1
1
|
// This Source Code Form is subject to the terms of the Mozilla Public
|
|
2
2
|
// License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
3
3
|
// file, You can obtain one at https://mozilla.org/MPL/2.0/.
|
|
4
|
+
/** Every rule `akm lint` reports; a rule name in `lint.skip` or `--rule` is one of these. */
|
|
5
|
+
export const LINT_RULES = [
|
|
6
|
+
"unquoted-colon",
|
|
7
|
+
"missing-updated",
|
|
8
|
+
"orphaned-stub",
|
|
9
|
+
"placeholder-stub",
|
|
10
|
+
"missing-name-or-type",
|
|
11
|
+
"missing-type",
|
|
12
|
+
"stale-path",
|
|
13
|
+
"missing-skill-md",
|
|
14
|
+
"invalid-task-yaml",
|
|
15
|
+
"missing-ref",
|
|
16
|
+
"redacted-content",
|
|
17
|
+
"dangerous-env-key",
|
|
18
|
+
"tracked-secrets",
|
|
19
|
+
"invalid-workflow-structure",
|
|
20
|
+
"missing-category",
|
|
21
|
+
/**
|
|
22
|
+
* A file the sweep reached but could not finish checking — the per-file
|
|
23
|
+
* dispatch threw (unreadable mid-run, a `--fix` write that failed in a way
|
|
24
|
+
* the fixer could not absorb). Reported in-band so a partial sweep is
|
|
25
|
+
* VISIBLE: before this code existed the throw escaped `akmLint()` entirely
|
|
26
|
+
* and the caller learned neither which file failed nor which fixes had
|
|
27
|
+
* already landed on disk (issue #761).
|
|
28
|
+
*/
|
|
29
|
+
"lint-failed",
|
|
30
|
+
// ── non-akm adapter `validate()` codes (akm 0.9.0 lint/adapter-dispatch wiring) ──
|
|
31
|
+
//
|
|
32
|
+
// These four are `llm-wiki`'s native structural checks
|
|
33
|
+
// (`core/adapter/adapters/llm-wiki-adapter.ts`), reachable now that `akm lint`
|
|
34
|
+
// dispatches every non-akm bundle through its OWN adapter's `validate()`
|
|
35
|
+
// instead of the akm-shaped per-file sweep. `missing-type` / `missing-ref`
|
|
36
|
+
// above are shared with `okf` (already closed members of this union).
|
|
37
|
+
"uncited-raw",
|
|
38
|
+
"missing-description",
|
|
39
|
+
"broken-xref",
|
|
40
|
+
"broken-source",
|
|
41
|
+
/**
|
|
42
|
+
* Non-fatal workflow compile ADVISORY (`compileWorkflowPlan().warnings` —
|
|
43
|
+
* e.g. a step with no `output:` schema, or a `params.<name>` reference to an
|
|
44
|
+
* undeclared param). Routed into `AkmLintResult.warnings`, never `flagged`,
|
|
45
|
+
* so `--fail-on-flagged` ignores it (see
|
|
46
|
+
* `core/adapter/adapters/akm-lint.ts#workflowFrontendDiagnostics`).
|
|
47
|
+
*/
|
|
48
|
+
"workflow-warning",
|
|
49
|
+
/**
|
|
50
|
+
* Fallback for a `Diagnostic.issue` code this union does not (yet) name.
|
|
51
|
+
* `Diagnostic.issue` (`core/adapter/types.ts`) is deliberately an OPEN
|
|
52
|
+
* `string` — any current or future `BundleAdapter.validate()` may emit a
|
|
53
|
+
* code this closed lint-command union has never heard of. Rather than
|
|
54
|
+
* silently dropping that finding (or throwing at the CLI boundary), the
|
|
55
|
+
* lint→adapter mapping (`commands/lint/index.ts#diagnosticToLintIssue`)
|
|
56
|
+
* folds an unrecognized code onto this member and preserves the ORIGINAL
|
|
57
|
+
* code in `detail` (prefixed `[<issue>] `) so nothing an adapter reports is
|
|
58
|
+
* ever lost, even though the closed union can't type it precisely.
|
|
59
|
+
*/
|
|
60
|
+
"adapter-diagnostic",
|
|
61
|
+
];
|
|
4
62
|
/**
|
|
5
63
|
* The issue codes that are ADVISORY: surfaced in lint output but never routed
|
|
6
64
|
* into `flagged`, so `--fail-on-flagged` cannot fail a run over one.
|
|
@@ -22,6 +22,7 @@ import { assembleAsset, serializeFrontmatter } from "../../core/asset/asset-seri
|
|
|
22
22
|
import { carryForwardBookkeepingFrontmatter, parseFrontmatter, replaceFrontmatterBlocks, } from "../../core/asset/frontmatter.js";
|
|
23
23
|
import { MEMORY_ARCHIVE_REL } from "../../core/asset/memory-archive.js";
|
|
24
24
|
import { parsePlacementRef } from "../../core/asset/resolve-ref.js";
|
|
25
|
+
import { stalePathRoots } from "../../core/asset/stale-path.js";
|
|
25
26
|
import { loadConfig } from "../../core/config/config.js";
|
|
26
27
|
import { ConfigError, NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
|
|
27
28
|
import { appendEvent } from "../../core/events.js";
|
|
@@ -987,6 +988,7 @@ function promotionLintBlockers(raw, assetPath, targetRoot, refType, config) {
|
|
|
987
988
|
let data;
|
|
988
989
|
let body;
|
|
989
990
|
let frontmatter;
|
|
991
|
+
let bodyStartLine = 1;
|
|
990
992
|
if (refType === "task") {
|
|
991
993
|
try {
|
|
992
994
|
const parsed = parseYaml(raw);
|
|
@@ -999,7 +1001,7 @@ function promotionLintBlockers(raw, assetPath, targetRoot, refType, config) {
|
|
|
999
1001
|
frontmatter = null;
|
|
1000
1002
|
}
|
|
1001
1003
|
else {
|
|
1002
|
-
({ data, content: body, frontmatter } = parseFrontmatter(raw));
|
|
1004
|
+
({ data, content: body, frontmatter, bodyStartLine } = parseFrontmatter(raw));
|
|
1003
1005
|
}
|
|
1004
1006
|
const resolvedRoot = path.resolve(targetRoot);
|
|
1005
1007
|
return runBaseChecks({
|
|
@@ -1009,8 +1011,10 @@ function promotionLintBlockers(raw, assetPath, targetRoot, refType, config) {
|
|
|
1009
1011
|
data,
|
|
1010
1012
|
body,
|
|
1011
1013
|
frontmatter,
|
|
1014
|
+
bodyStartLine,
|
|
1012
1015
|
fix: false,
|
|
1013
1016
|
stashRoot: targetRoot,
|
|
1017
|
+
stalePathRoots: stalePathRoots(config, targetRoot),
|
|
1014
1018
|
extraStashRoots: resolveSourceEntries(targetRoot, config)
|
|
1015
1019
|
.map((source) => source.path)
|
|
1016
1020
|
.filter((sourcePath) => path.resolve(sourcePath) !== resolvedRoot),
|
|
@@ -90,7 +90,7 @@ export function scaffoldScratch(stashDir) {
|
|
|
90
90
|
// Non-fatal — the bundle is usable without the scratch scaffold.
|
|
91
91
|
}
|
|
92
92
|
}
|
|
93
|
-
/** Add the root-scoped scratch ignore rule unless present.
|
|
93
|
+
/** Add the root-scoped scratch ignore rule unless present. */
|
|
94
94
|
export function ensureScratchGitignore(stashDir) {
|
|
95
95
|
try {
|
|
96
96
|
const gitignorePath = path.join(stashDir, ".gitignore");
|
|
@@ -106,38 +106,19 @@ export function ensureScratchGitignore(stashDir) {
|
|
|
106
106
|
}
|
|
107
107
|
}
|
|
108
108
|
const SCRATCH_GITIGNORE_RULE = `/${SCRATCH_DIR}/`;
|
|
109
|
-
/** Marks the akm-authored block in a stash `.gitignore` (idempotency anchor). */
|
|
110
|
-
const STASH_GITIGNORE_MARKER = "# akm: keep secret material out of git by default";
|
|
111
|
-
/** Documented opt-out for private bundles that deliberately version env/ and secrets/. */
|
|
112
|
-
export const STASH_GITIGNORE_TRACK_SECRETS_MARKER = "# akm: intentionally track env and secrets";
|
|
113
|
-
const STASH_GITIGNORE_BLOCK = [
|
|
114
|
-
STASH_GITIGNORE_MARKER,
|
|
115
|
-
"# env/ and secrets/ assets hold tokens and keys. They are ignored by default",
|
|
116
|
-
"# so `git push` can never leak them. To version a specific one (e.g. for a",
|
|
117
|
-
"# private-remote backup), un-ignore its path below once you accept the risk.",
|
|
118
|
-
"env/",
|
|
119
|
-
"secrets/",
|
|
120
|
-
"",
|
|
121
|
-
].join("\n");
|
|
122
109
|
/**
|
|
123
|
-
*
|
|
124
|
-
*
|
|
125
|
-
*
|
|
126
|
-
*
|
|
127
|
-
* Idempotent + non-clobbering: creates the file when absent, appends the akm
|
|
128
|
-
* block when the file exists but lacks it (preserving the user's own rules),
|
|
129
|
-
* and no-ops once the marker is present. A private bundle that deliberately
|
|
130
|
-
* versions all secret material can add `# akm: intentionally track env and
|
|
131
|
-
* secrets`; that explicit marker suppresses this helper entirely (#981).
|
|
110
|
+
* Add `env/` and `secrets/` to the bundle `.gitignore` when it mentions neither, so a
|
|
111
|
+
* new bundle does not commit its tokens and keys. A `.gitignore` that already names
|
|
112
|
+
* either one is the owner's choice and is left as written.
|
|
132
113
|
*/
|
|
133
114
|
export function ensureStashGitignore(stashDir) {
|
|
134
115
|
try {
|
|
135
116
|
const gitignorePath = path.join(stashDir, ".gitignore");
|
|
136
117
|
const existing = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, "utf8") : "";
|
|
137
|
-
if (existing.includes(
|
|
118
|
+
if (existing.includes("env/") || existing.includes("secrets/"))
|
|
138
119
|
return;
|
|
139
|
-
const gap = existing.length === 0 ? "" : existing.endsWith("\n") ? "
|
|
140
|
-
fs.writeFileSync(gitignorePath, `${existing}${gap}
|
|
120
|
+
const gap = existing.length === 0 ? "" : existing.endsWith("\n") ? "" : "\n";
|
|
121
|
+
fs.writeFileSync(gitignorePath, `${existing}${gap}env/\nsecrets/\n`);
|
|
141
122
|
}
|
|
142
123
|
catch {
|
|
143
124
|
// Non-fatal — the stash is usable without the ignore scaffold.
|
|
@@ -424,11 +424,11 @@ async function validate(c, changes, ctx) {
|
|
|
424
424
|
// checks need only a frontmatter-free placeholder here.
|
|
425
425
|
let parsed;
|
|
426
426
|
if (type === "task") {
|
|
427
|
-
parsed = { data: {}, content: raw, frontmatter: null };
|
|
427
|
+
parsed = { data: {}, content: raw, frontmatter: null, bodyStartLine: 1 };
|
|
428
428
|
}
|
|
429
429
|
else {
|
|
430
430
|
const p = parseFrontmatter(raw);
|
|
431
|
-
parsed = { data: p.data, content: p.content, frontmatter: p.frontmatter };
|
|
431
|
+
parsed = { data: p.data, content: p.content, frontmatter: p.frontmatter, bodyStartLine: p.bodyStartLine };
|
|
432
432
|
}
|
|
433
433
|
diagnostics.push(...(await runBaseValidateChecks(change.path, parsed, c.root, ctx)));
|
|
434
434
|
diagnostics.push(...(await perTypeValidateChecks({
|
|
@@ -94,7 +94,12 @@ async function validate(c, changes, ctx) {
|
|
|
94
94
|
if (!isWorkflowFile(raw))
|
|
95
95
|
continue;
|
|
96
96
|
const p = parseFrontmatter(raw);
|
|
97
|
-
const parsed = {
|
|
97
|
+
const parsed = {
|
|
98
|
+
data: p.data,
|
|
99
|
+
content: p.content,
|
|
100
|
+
frontmatter: p.frontmatter,
|
|
101
|
+
bodyStartLine: p.bodyStartLine,
|
|
102
|
+
};
|
|
98
103
|
diagnostics.push(...(await runBaseValidateChecks(relPath, parsed, c.root, ctx)));
|
|
99
104
|
diagnostics.push(...(await perTypeValidateChecks({
|
|
100
105
|
type: "workflow",
|
|
@@ -51,8 +51,10 @@ import { createHash } from "node:crypto";
|
|
|
51
51
|
import { BUNDLE_REF_RE } from "../../asset/asset-ref.js";
|
|
52
52
|
import { parseFrontmatter } from "../../asset/frontmatter.js";
|
|
53
53
|
import { checkUnquotedDescriptionColon } from "../../asset/frontmatter-lint.js";
|
|
54
|
-
import {
|
|
54
|
+
import { isSkillPath } from "../../asset/lint-text.js";
|
|
55
|
+
import { findStalePaths, stalePathRoots } from "../../asset/stale-path.js";
|
|
55
56
|
import { toPosix } from "../../common.js";
|
|
57
|
+
import { loadConfig } from "../../config/config.js";
|
|
56
58
|
// ── Small pure helpers, reused across the concrete adapters ──────────────────
|
|
57
59
|
/** Content hash feeding `IndexDocument.hash` (incrementality/fingerprints, `types.ts` doc comment). */
|
|
58
60
|
export function hashContent(content) {
|
|
@@ -75,8 +77,8 @@ export function readTags(value) {
|
|
|
75
77
|
/** Reserved files (case-insensitive) every concrete adapter recognizes but never indexes as a concept. */
|
|
76
78
|
export const RESERVED_FILES = new Set(["index.md", "log.md"]);
|
|
77
79
|
// ── Base validate checks (port of `BaseLinter.runBaseChecks`) ────────────────
|
|
78
|
-
function checkMissingUpdated(data, frontmatterText) {
|
|
79
|
-
return frontmatterText !== null && !("updated" in data);
|
|
80
|
+
function checkMissingUpdated(relPath, data, frontmatterText) {
|
|
81
|
+
return frontmatterText !== null && !("updated" in data) && !isSkillPath(relPath);
|
|
80
82
|
}
|
|
81
83
|
/** See file header: same intent as `markdown-insertion.ts#findFenceRegions`, not byte-identical. */
|
|
82
84
|
function stripFencedBlocksSimple(body) {
|
|
@@ -179,12 +181,12 @@ function readRefStringOrArray(value) {
|
|
|
179
181
|
*/
|
|
180
182
|
export async function runBaseValidateChecks(relPath, parsed, componentRoot, ctx) {
|
|
181
183
|
const diagnostics = [];
|
|
182
|
-
const { data, content: body, frontmatter } = parsed;
|
|
184
|
+
const { data, content: body, frontmatter, bodyStartLine } = parsed;
|
|
183
185
|
const unquotedColonDetail = checkUnquotedDescriptionColon(frontmatter);
|
|
184
186
|
if (unquotedColonDetail) {
|
|
185
187
|
diagnostics.push({ file: relPath, issue: "unquoted-colon", detail: unquotedColonDetail, fixed: false });
|
|
186
188
|
}
|
|
187
|
-
if (checkMissingUpdated(data, frontmatter)) {
|
|
189
|
+
if (checkMissingUpdated(relPath, data, frontmatter)) {
|
|
188
190
|
diagnostics.push({
|
|
189
191
|
file: relPath,
|
|
190
192
|
issue: "missing-updated",
|
|
@@ -192,27 +194,13 @@ export async function runBaseValidateChecks(relPath, parsed, componentRoot, ctx)
|
|
|
192
194
|
fixed: false,
|
|
193
195
|
});
|
|
194
196
|
}
|
|
195
|
-
const
|
|
196
|
-
|
|
197
|
-
...(frontmatter ?
|
|
197
|
+
const roots = stalePathRoots(loadConfig(), componentRoot);
|
|
198
|
+
const stale = [
|
|
199
|
+
...(frontmatter ? findStalePaths(frontmatter, 2, roots, componentRoot) : []),
|
|
200
|
+
...findStalePaths(body, bodyStartLine, roots, componentRoot),
|
|
198
201
|
];
|
|
199
|
-
for (const
|
|
200
|
-
|
|
201
|
-
if (home !== undefined && (await ctx.list(home)).length === 0)
|
|
202
|
-
continue; // another host's or user's path
|
|
203
|
-
const found = await ctx.readFile(candidate);
|
|
204
|
-
if (found !== null)
|
|
205
|
-
continue;
|
|
206
|
-
const portableHint = candidate.startsWith(componentRoot)
|
|
207
|
-
? ` (portable form: $AKM_BUNDLE_DIR${candidate.slice(componentRoot.length)})`
|
|
208
|
-
: "";
|
|
209
|
-
diagnostics.push({
|
|
210
|
-
file: relPath,
|
|
211
|
-
issue: "stale-path",
|
|
212
|
-
detail: `nonexistent path: ${candidate}${portableHint}`,
|
|
213
|
-
fixed: false,
|
|
214
|
-
});
|
|
215
|
-
}
|
|
202
|
+
for (const finding of stale)
|
|
203
|
+
diagnostics.push({ file: relPath, issue: "stale-path", fixed: false, ...finding });
|
|
216
204
|
for (const ref of extractProseRefTokens(body)) {
|
|
217
205
|
const { exists } = await ctx.resolveRef(ref);
|
|
218
206
|
if (!exists)
|
|
@@ -10,10 +10,10 @@
|
|
|
10
10
|
/**
|
|
11
11
|
* A path segment shaped like a run-time filename template rather than a
|
|
12
12
|
* literal reference: `<timestamp>`-style angle brackets, `{stamp}`/`${VAR}`
|
|
13
|
-
* braces, a `YYYYMMDD`/`HHMMSS`-style run of date-format letters,
|
|
14
|
-
* character. Such a path never exists under its literal spelling.
|
|
13
|
+
* braces, a `YYYYMMDD`/`HHMMSS`-style run of date-format letters, a glob
|
|
14
|
+
* character, or an elided `...` segment. Such a path never exists under its literal spelling.
|
|
15
15
|
*/
|
|
16
|
-
const PATH_PLACEHOLDER_PATTERN = /[<{]|[*?]|[YMDHS]{4,}
|
|
16
|
+
const PATH_PLACEHOLDER_PATTERN = /[<{]|[*?]|[YMDHS]{4,}|\.\.\./;
|
|
17
17
|
/** A line that presents a path as a record of the past or as an illustration, not as guidance to follow. */
|
|
18
18
|
const NON_CURRENT_LINE_PATTERN = /\b(?:historical(?:ly)?|previously|formerly|for example|for instance)\b|\be\.g\./i;
|
|
19
19
|
/** A heading whose section holds records or illustrations rather than current guidance. */
|
|
@@ -22,29 +22,30 @@ const NON_CURRENT_HEADING_PATTERN = /^#{1,6}\s.*\b(?:history|changelog|archive|e
|
|
|
22
22
|
function stripTrailingSentencePunctuation(token) {
|
|
23
23
|
return token.replace(/[.;:!?]+$/, "");
|
|
24
24
|
}
|
|
25
|
-
/**
|
|
26
|
-
export function
|
|
27
|
-
return
|
|
25
|
+
/** True for a file under a bundle's `skills/` directory: a skill carries no `updated` field. */
|
|
26
|
+
export function isSkillPath(relPath) {
|
|
27
|
+
return relPath.split(/[\\/]/)[0] === "skills";
|
|
28
28
|
}
|
|
29
29
|
/**
|
|
30
30
|
* Absolute paths in `text` presented as current guidance. Paths on lines or in
|
|
31
31
|
* sections that frame them as history or examples, run-time filename
|
|
32
32
|
* templates, and trailing sentence punctuation are all excluded.
|
|
33
33
|
*/
|
|
34
|
-
export function findCurrentPathReferences(text) {
|
|
35
|
-
const pathRe = /(
|
|
34
|
+
export function findCurrentPathReferences(text, firstLine = 1) {
|
|
35
|
+
const pathRe = /(?<=^|[\s"'`([=])\/[^\s"'`)\]>,:\[\n]+/g;
|
|
36
36
|
const out = [];
|
|
37
37
|
let inNonCurrentSection = false;
|
|
38
|
-
|
|
38
|
+
text.split(/\r?\n/).forEach((line, index) => {
|
|
39
39
|
if (/^#{1,6}\s/.test(line))
|
|
40
40
|
inNonCurrentSection = NON_CURRENT_HEADING_PATTERN.test(line);
|
|
41
41
|
if (inNonCurrentSection || NON_CURRENT_LINE_PATTERN.test(line))
|
|
42
|
-
|
|
42
|
+
return;
|
|
43
43
|
for (const match of line.matchAll(pathRe)) {
|
|
44
44
|
const candidate = stripTrailingSentencePunctuation(match[0]);
|
|
45
|
-
if (!PATH_PLACEHOLDER_PATTERN.test(candidate))
|
|
46
|
-
out.push(candidate);
|
|
45
|
+
if (candidate.length > 1 && !PATH_PLACEHOLDER_PATTERN.test(candidate)) {
|
|
46
|
+
out.push({ path: candidate, line: firstLine + index, lineText: line.trim() });
|
|
47
|
+
}
|
|
47
48
|
}
|
|
48
|
-
}
|
|
49
|
+
});
|
|
49
50
|
return out;
|
|
50
51
|
}
|