@vibe-agent-toolkit/agent-skills 0.1.41-rc.8 → 0.1.42-rc.1

package/dist/files-config.d.ts

@@ -7,16 +7,78 @@
  * - Computing deferred paths for validation
  * - Copying declared build artifacts into a skill output dir (every build path)
  */
+import { type ValidationIssue } from '@vibe-agent-toolkit/agent-schema';
 import type { SkillFileEntry } from '@vibe-agent-toolkit/resources';
 export type { SkillFileEntry } from '@vibe-agent-toolkit/resources';
-export declare function buildArtifactHint(source: string): string;
-/** Result of matching a link target against files config */
-export interface FilesMatchResult {
-    /** Whether the link matched source or dest */
-    match: 'source' | 'dest';
-    /** The matching files entry */
-    entry: SkillFileEntry;
+/** One file a GLOB `files:` entry matched and the never-package list refused. */
+export interface DroppedGlobMatch {
+    /** The glob `source:` whose net caught it. */
+    source: string;
+    /**
+     * ABSOLUTE path of the refused file, forward-slashed.
+     *
+     * The reported subject: this is the one path in this record a reader can
+     * actually open. `dest` names a path that, by definition, does NOT exist —
+     * nothing was written there — so a finding anchored at the dest cannot be
+     * traced back to anything. Kept absolute rather than pre-relativized because
+     * the run's anchor is the caller's to choose (`locationRoot` may not be the
+     * project root when one run spans several projects); every emitter passes it
+     * through {@link issueLocation} at emit time.
+     */
+    absFile: string;
+    /**
+     * Skill-output-relative dest the file WOULD have had, spelled exactly as a
+     * COPIED dest is (see {@link normalizeRelPath}) so consumers can compare the
+     * two populations without re-deriving either. `checkBrokenPackagedLinks` keys
+     * its never-package remediation on this exact set: a link is "broken because
+     * VAT refused to package it" only when its target is one of THESE paths.
+     *
+     * A SET KEY, not a location: it is the coordinate system the packaged link
+     * graph is expressed in, and mixing it into an issue's `location` — which is
+     * always a source path to open — is what made one issue list speak two
+     * coordinate systems at once.
+     */
+    dest: string;
+}
+/** What {@link applyFilesConfig} accounted for, and what it deliberately did not. */
+export interface AppliedFilesConfig {
+    /**
+     * Every skill-output-relative dest this config accounts for, one per FILE
+     * (glob entries expanded). See {@link applyFilesConfig} for why the orphan
+     * check must be told this list.
+     */
+    dests: string[];
+    /**
+     * Files a GLOB matched that the never-package list dropped.
+     *
+     * Returned rather than written to a `warn` sink because a file vanishing from
+     * a bundle is a build FINDING, not a log line: it has to reach the structured
+     * report (`issueCounts`), or a CI consumer reads `warnings: 0` for a build
+     * that silently shipped less than the config asked for.
+     */
+    dropped: DroppedGlobMatch[];
 }
+/**
+ * Turn never-package drops into reportable findings.
+ *
+ * Lives here rather than in the packager because this module owns the concept:
+ * the drop and the issue describing it must not be able to disagree.
+ *
+ * Anchored at the SOURCE file, in ONE coordinate system for both the location
+ * and the message. The finding used to name the would-be `dest` in both, which
+ * meant the only path it gave you was an output path nothing was ever written to
+ * — so the issue list mixed output coordinates (this code) with source
+ * coordinates (every other pre-build code) and an adopter could not open the
+ * thing that went missing. The glob pattern stays in the message because it
+ * answers the second question ("which entry caught this?"), but it is no longer
+ * the only identifiable thing in the finding.
+ *
+ * @param locationRoot The ONE base this run anchors locations at. Required, not
+ *   defaulted to the project root: a defaulted anchor is how a multi-project run
+ *   silently emits paths relative to the wrong tree.
+ */
+export declare function droppedGlobMatchesToIssues(dropped: readonly DroppedGlobMatch[], locationRoot: string): ValidationIssue[];
+export declare function buildArtifactHint(source: string): string;
 /**
  * Normalize a relative path for comparison: forward slashes, no leading `./`.
  * The path's ROOT is the caller's business; this only fixes the spelling.
@@ -29,6 +91,27 @@ export interface FilesMatchResult {
  * `files:` config" about a copy VAT performed itself.
  */
 export declare function normalizeRelPath(p: string): string;
+/**
+ * The skill-output-relative dest a GLOB `files:` entry gives one absolute source
+ * path, or `undefined` when the entry's expansion would not include it.
+ *
+ * Answers, without running the glob, the question the packager must settle BEFORE
+ * anything is copied: "does the config already declare where this file goes?" A
+ * glob's expansion is late-bound to copy time ({@link copyGlobEntry}), so the path
+ * map used to have no entry for its matches — and a match that link traversal ALSO
+ * found was therefore dropped at its type-derived location while the glob copied
+ * it to the declared dest. Identical bytes shipped twice, the rewritten link
+ * pointed at traversal's copy, and the declared `dest:` was dead. One file, one
+ * dest: the declaration wins, and this is how the path map learns it.
+ *
+ * The three gates below are exactly {@link copyGlobEntry}'s own, restated as a
+ * predicate so the dest computed here is the dest the copy actually writes:
+ * under the static base, matching the magic remainder (`dot: true`, as the copy
+ * expands), and not refused by {@link partitionNeverPackaged}. A never-packaged
+ * match has NO dest — re-pointing the path map at one would rewrite a link to a
+ * file that never arrives.
+ */
+export declare function globEntryDest(entry: SkillFileEntry, projectRoot: string, absSource: string): string | undefined;
 /**
  * Merge defaults and per-skill files entries.
  *
@@ -39,22 +122,22 @@ export declare function normalizeRelPath(p: string): string;
  */
 export declare function mergeFilesConfig(defaults: SkillFileEntry[] | undefined, perSkill: SkillFileEntry[] | undefined): SkillFileEntry[];
 /**
- * Match a link target path against files config entries.
- *
- * Returns the matching entry and whether it matched on source or dest.
- * Source matches take priority over dest matches.
- *
- * For GLOB entries (`isGlob(entry.source)`), matching is by directory prefix:
- * - source match: link is equal to or under the glob's static base
- * - dest match: link is equal to or under entry.dest
+ * The skill-output-relative dests named by EXPLICIT (non-glob) `files:` entries.
  *
- * Single-file entries still match EXACTLY (unchanged).
+ * THE definition of "the config declared this output path", shared by every lane
+ * that has to decide whether a file in a bundle is there on purpose. Naming a
+ * `source`/`dest` pair is an unambiguous instruction to ship that file; a GLOB
+ * never named the file it caught, so its expansion is deliberately absent from
+ * this list — a net is not a declaration. (`walk-link-graph.ts`'s
+ * `refusesAgentInstructionFile` draws the same line on the link side, and
+ * {@link partitionNeverPackaged} on the copy side; all three must agree or the
+ * mechanisms disagree about one bundle.)
  *
- * @param linkTarget - Resolved link target path (relative to project root)
- * @param files - Merged files config entries
- * @returns Match result or null if no match
+ * Spelled via {@link normalizeRelPath}, which is the spelling a packaged file's
+ * output-relative path is computed with — so membership can be tested by exact
+ * equality, never by a prefix test.
  */
-export declare function matchLinkToFiles(linkTarget: string, files: SkillFileEntry[]): FilesMatchResult | null;
+export declare function explicitFilesConfigDests(files: readonly SkillFileEntry[]): string[];
 /** Options for {@link applyFilesConfig}. */
 export interface ApplyFilesConfigOptions {
     /** Merged `files:` entries to copy. */
@@ -97,19 +180,126 @@ export declare function verifyFilesIntegrity(pairs: {
  * diffing against the expected rel set is what catches a misrouted rebase, a
  * stale leftover, or a dropped file.
  *
- * SAFETY ASSUMPTION (why this can't false-positive): a glob entry OWNS its dest
- * directory (`skillOutputDir/<entry.dest>`) and the build wipes the skill output
- * dir before copying (skill-packager.ts removes `resolvedOutput` recursively
- * before any copy). Nothing else writes into this subtree, so any EXTRA file is a
- * genuine bug, not a co-tenant. This scoping is what makes the set check safe
- * here even though a project-wide "no extra files" check would not be.
+ * SAFETY ASSUMPTION (why this can't false-positive): a glob entry does NOT own
+ * its dest directory outright — another `files:` entry may legitimately declare a
+ * dest inside the same subtree, and that is exactly how the documented escape
+ * hatch works (an explicit `source: extras/README.md` re-ships a file the glob
+ * refused). So `expectedRel` is the union of what THIS entry copied and every
+ * other entry's declared dest under the same subtree, and the caller runs this
+ * only after ALL entries have copied — see {@link applyFilesConfig}. What is left
+ * over is a file no entry accounts for: a genuine bug, not a co-tenant. (The build
+ * wipes the skill output dir before copying — skill-packager.ts removes
+ * `resolvedOutput` recursively — so there are no stale files either.)
  *
  * @param destDir      Absolute path to the glob entry's dest subtree.
- * @param expectedRel  Forward-slash rel paths (relative to `destDir`) the copy
- *                     step wrote for THIS entry.
+ * @param expectedRel  Forward-slash rel paths (relative to `destDir`) that the
+ *                     whole `files:` config accounts for inside this subtree.
  * @param source       The entry's `source` (for error messages only).
  * @throws if the actual subtree omits an expected file or contains an extra one.
  */
 export declare function verifyDestSet(destDir: string, expectedRel: string[], source: string): Promise<void>;
-export declare function applyFilesConfig(opts: ApplyFilesConfigOptions): Promise<string[]>;
+/** One GLOB `files:` entry that currently expands to nothing at all. */
+export interface UnmatchedGlobEntry {
+    /** The glob `source:` that matched no files. */
+    source: string;
+    /**
+     * ABSOLUTE path of the directory it expanded under (the glob's static base),
+     * forward-slashed. Absolute for the same reason as
+     * {@link DroppedGlobMatch.absFile}: the run's anchor is the emitter's choice.
+     * The directory need not exist — "it isn't there yet" is the common case.
+     */
+    absBase: string;
+}
+/** One GLOB `files:` entry whose every match the never-package list refused. */
+export interface AllRefusedGlobEntry {
+    /** The glob `source:` that netted only never-packaged files. */
+    source: string;
+    /** ABSOLUTE path of the directory it expanded under, forward-slashed. */
+    absBase: string;
+    /**
+     * ABSOLUTE paths of every match, all of them refused. Carried in full because
+     * this finding SUPERSEDES the per-file drops for its entry (see
+     * {@link collectPreBuildGlobFindings}), so it is the only place those file
+     * names are still reported.
+     */
+    absRefused: string[];
+}
+/**
+ * What the project's GLOB `files:` entries look like BEFORE anything is built.
+ *
+ * The three buckets are MUTUALLY EXCLUSIVE per entry, and they are three of the
+ * FOUR verdicts `copyGlobEntry` reaches at copy time — one entry cannot be both
+ * "matched nothing" and "matched only refused files", and an entry counted in
+ * `allRefused` contributes no `dropped` rows. Overlapping buckets would let one
+ * config produce two findings naming two different causes.
+ *
+ * The fourth verdict has NO bucket: a `..` segment in the glob's magic remainder
+ * makes the pattern unexpandable, `expandGlobEntry` throws, and
+ * {@link collectPreBuildGlobFindings} skips the entry rather than mislabelling it.
+ * So a config certain to fail the build produces no pre-build finding at all —
+ * see the skip in that function for why nothing here can honestly carry it.
+ */
+export interface PreBuildGlobFindings {
+    /**
+     * Never-packaged files a glob would catch while still shipping something else.
+     * See {@link DroppedGlobMatch}.
+     */
+    dropped: DroppedGlobMatch[];
+    /** Globs that matched, but whose every match was refused — they ship nothing. */
+    allRefused: AllRefusedGlobEntry[];
+    /** Globs that currently match nothing — the other input the build dies on. */
+    unmatched: UnmatchedGlobEntry[];
+}
+/**
+ * What the project's GLOB `files:` entries would do, without copying anything.
+ *
+ * The pre-build half of {@link applyFilesConfig}: `vat skills validate` and
+ * `vat audit` can answer "what will this config fail to ship?" before a build
+ * exists, and they answer it by running THE expansion the copy runs
+ * ({@link expandGlobEntry}) — a second, independently written expansion would be
+ * free to disagree with the copy about what ships, which is the whole defect class
+ * this module exists to close.
+ *
+ * Non-throwing by construction, unlike {@link copyGlobEntry}: a pre-build gate runs
+ * before the artifact exists, so a glob over an unbuilt `dist/` matching nothing is
+ * the expected state, not a failure. `copyGlobEntry` still raises there, where the
+ * build HAS run and zero matches is real.
+ *
+ * That reasoning settles the SEVERITY of a failing expansion, not whether to
+ * mention it — and this used to return only `dropped`, so the gate reported the
+ * drop that is harmless by design (a glob is a net) and said nothing about either
+ * expansion outcome that is certain to fail the very next command. `unmatched`
+ * and `allRefused` end that silence, graded `info` and `warning` respectively (see
+ * FILES_GLOB_MATCHED_NOTHING / FILES_GLOB_MATCHED_ONLY_NEVER_PACKAGED).
+ *
+ * The three buckets partition the entries as two of `copyGlobEntry`'s three throws
+ * plus its success path do — same predicates, same order, one expansion. Its THIRD
+ * throw (`expandGlobEntry` refusing a `..` segment in the magic remainder) has no
+ * bucket, and the skip below explains why — but the consequence belongs here: this
+ * function's answer to "what will this config fail to ship?" is silent for that one
+ * malformed shape, which is the same class of silence `unmatched`/`allRefused` were
+ * added to end. Closing it needs a code of its own (a wrong-shaped PATTERN, not an
+ * unbuilt or unshippable artifact), or a `source` refine on `SkillFileEntrySchema`
+ * that rejects the pattern at config load and makes the skip unreachable.
+ *
+ * Drops re-shipped by an explicit entry are filtered out for the same reason
+ * {@link applyFilesConfig} filters them: reporting "it did not ship" about a file
+ * the documented escape hatch puts in the bundle tells an author their remediation
+ * failed when it worked. That filter is deliberately NOT applied to `allRefused`:
+ * `copyGlobEntry` throws on an entry whose own kept-set is empty no matter what
+ * any other entry ships, so filtering it would predict a green build that fails.
+ */
+export declare function collectPreBuildGlobFindings(filesConfig: readonly SkillFileEntry[], projectRoot: string): Promise<PreBuildGlobFindings>;
+/**
+ * Turn {@link collectPreBuildGlobFindings} into reportable pre-build issues.
+ *
+ * THE emitter for the pre-build gates, so a lane cannot pick up one half of the
+ * findings and quietly drop the other — which is how the zero-match went
+ * unreported for as long as it did.
+ *
+ * @param locationRoot The ONE base this run anchors locations at (see
+ *   {@link droppedGlobMatchesToIssues}).
+ */
+export declare function preBuildGlobFindingsToIssues(findings: PreBuildGlobFindings, locationRoot: string): ValidationIssue[];
+export declare function applyFilesConfig(opts: ApplyFilesConfigOptions): Promise<AppliedFilesConfig>;
 //# sourceMappingURL=files-config.d.ts.map

package/dist/files-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"files-config.d.ts","sourceRoot":"","sources":["../src/files-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAYpE,YAAY,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAapE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAUxD;AAED,4DAA4D;AAC5D,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,KAAK,EAAE,QAAQ,GAAG,MAAM,CAAC;IACzB,+BAA+B;IAC/B,KAAK,EAAE,cAAc,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAMlD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,cAAc,EAAE,GAAG,SAAS,EACtC,QAAQ,EAAE,cAAc,EAAE,GAAG,SAAS,GACrC,cAAc,EAAE,CA6ClB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,cAAc,EAAE,GACtB,gBAAgB,GAAG,IAAI,CAiCzB;AAED,4CAA4C;AAC5C,MAAM,WAAW,uBAAuB;IACtC,uCAAuC;IACvC,WAAW,EAAE,cAAc,EAAE,CAAC;IAC9B,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,GAC9C,IAAI,CAgBN;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EAAE,EACrB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAyBf;AAwMD,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAYvF"}
+{"version":3,"file":"files-config.d.ts","sourceRoot":"","sources":["../src/files-config.ts"],"names":[],"mappings":"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"}