@csark0812/skeleton 1.6.2 → 2.0.0

package/dist/hooks/customize-on-skill-read.js

@@ -3520,7 +3520,12 @@ var require_fast_uri = __commonJS((exports, module) => {
   }
   function resolve(baseURI, relativeURI, options) {
     const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
-    const resolved = resolveComponent(parse(baseURI, schemelessOptions), parse(relativeURI, schemelessOptions), schemelessOptions, true);
+    const { parsed: baseParsed, malformedAuthorityOrPort: baseMalformed } = parseWithStatus(baseURI, schemelessOptions);
+    const { parsed: relativeParsed, malformedAuthorityOrPort: relativeMalformed } = parseWithStatus(relativeURI, schemelessOptions);
+    if (baseMalformed || relativeMalformed) {
+      throw new Error(baseParsed.error || relativeParsed.error || "URI is malformed.");
+    }
+    const resolved = resolveComponent(baseParsed, relativeParsed, schemelessOptions, true);
     schemelessOptions.skipEscape = true;
     return serialize(resolved, schemelessOptions);
   }
@@ -3646,6 +3651,8 @@ var require_fast_uri = __commonJS((exports, module) => {
     return uriTokens.join("");
   }
   var URI_PARSE = /^(?:([^#/:?]+):)?(?:\/\/((?:([^#/?@]*)@)?(\[[^#/?\]]+\]|[^#/:?]*)(?::(\d*))?))?([^#?]*)(?:\?([^#]*))?(?:#((?:.|[\n\r])*))?/u;
+  var AUTHORITY_PREFIX = /^(?:[^#/:?]+:)?\/\/([^/?#]*)/;
+  var AUTHORITY_INTRODUCER_REGION = /^(?:[^#/:?]+:)?([/\\\t\n\r]*)/;
   function getParseError(parsed, matches) {
     if (matches[2] !== undefined && parsed.path && parsed.path[0] !== "/") {
       return 'URI path must start with "/" when authority is present.';
@@ -3675,6 +3682,25 @@ var require_fast_uri = __commonJS((exports, module) => {
         uri = "//" + uri;
       }
     }
+    const authorityMatch = uri.match(AUTHORITY_PREFIX);
+    if (authorityMatch !== null && authorityMatch[1].indexOf("\\") !== -1) {
+      parsed.error = "URI authority must not contain a literal backslash.";
+      malformedAuthorityOrPort = true;
+    }
+    const introducerMatch = uri.match(AUTHORITY_INTRODUCER_REGION);
+    if (introducerMatch !== null) {
+      const region = introducerMatch[1];
+      const normalizedRegion = region.replace(/[\t\n\r]/g, "");
+      if (normalizedRegion.length >= 2) {
+        if (normalizedRegion.slice(0, 2) !== "//") {
+          parsed.error = parsed.error || "URI authority must not contain a literal backslash.";
+          malformedAuthorityOrPort = true;
+        } else if (region.length !== normalizedRegion.length) {
+          parsed.error = parsed.error || "URI authority introducer must not contain whitespace.";
+          malformedAuthorityOrPort = true;
+        }
+      }
+    }
     const matches = uri.match(URI_PARSE);
     if (matches) {
       parsed.scheme = matches[1];

package/dist/plugin-types.d.ts

@@ -1,133 +1,14 @@
 /**
- * Public types for `@csark0812/skeleton/plugin-types`.
- * Kept hand-written so publishes stay independent of `.ts` extension emit quirks.
+ * Public types and helpers for skeleton plugin authors.
+ *
+ * ```ts
+ * import type { AuditRule, AuditContext } from "@csark0812/skeleton/plugin-types";
+ * import { issue, matchesGlobScope } from "@csark0812/skeleton/plugin-types";
+ * ```
  */
-
-export type Severity = "error" | "warning";
-
-export interface Issue {
-	rule: string;
-	file: string;
-	link?: string;
-	message: string;
-	severity: Severity;
-}
-
-export declare function issue(
-	rule: string,
-	file: string,
-	message: string,
-	opts?: { link?: string; severity?: Severity },
-): Issue;
-
-export type AuditSuite = "docs" | "skills";
-
-export interface AuditRule {
-	id: string;
-	global?: boolean;
-	suites?: AuditSuite[];
-	run: (ctx: AuditContext) => Issue[];
-}
-
-export type PolicyEntry =
-	| {
-			id: string;
-			message: string;
-			mode?: "pattern";
-			pattern: string;
-			scope?: string;
-			severity?: Severity;
-			canonical?: string;
-	  }
-	| {
-			id: string;
-			message: string;
-			mode: "fingerprint";
-			pattern?: string;
-			scope?: string;
-			severity?: Severity;
-			canonical?: string;
-	  };
-
-export interface CompiledPolicyEntry {
-	id: string;
-	message: string;
-	mode: "pattern" | "fingerprint";
-	pattern?: string;
-	scope?: string;
-	severity?: Severity;
-	canonical?: string;
-	regex: RegExp | null;
-}
-
-export interface PolicyFile {
-	name: string;
-	entries: CompiledPolicyEntry[];
-}
-
-export interface PolicyFileYaml {
-	name: string;
-	entries: PolicyEntry[];
-}
-
-export type MatchedPolicyEntry = CompiledPolicyEntry & { policyName: string };
-
-export interface ScanConfig {
-	include: string[];
-	exclude: string[];
-	nonPublicSkills?: string[];
-}
-
-export interface DenyConfig {
-	paths?: string[];
-}
-
-export interface CustomizeConfig {
-	alwaysInclude?: string[];
-}
-
-export interface DocsLintConfig {
-	nearDuplicateThreshold?: number;
-	ssotOverlapMin?: number;
-	ssotBetterMatchMargin?: number;
-	ssotPhraseCheck?: boolean;
-	ignorePairs?: [string, string][];
-	ignoreGlobs?: string[];
-}
-
-export interface SkeletonConfig {
-	scan: ScanConfig;
-	daysUntilStale: number;
-	deny?: DenyConfig;
-	customize?: CustomizeConfig;
-	docsLint?: DocsLintConfig;
-	plugins?: string[];
-	draftPathPrefixes?: string[];
-}
-
-export interface SkillRoot {
-	kind: "nested" | "flat";
-	relPath: string;
-}
-
-export interface SkillIndex {
-	roots: SkillRoot[];
-	slugs: string[];
-}
-
-export interface AuditContext {
-	root: string;
-	config: SkeletonConfig;
-	files: string[];
-	docMetaPaths: string[];
-	ssotEntries: Array<{ path: string; summary: string; form: string }>;
-	ssotErrors: Array<{ path: string; kind: string; detail: string }>;
-	/** @deprecated Prefer ssotEntries */
-	registryPaths: string[];
-	/** @deprecated Always false */
-	registryHasTableHeader: boolean;
-	skillIndex: SkillIndex;
-	policies: PolicyFile[];
-}
-
-export declare function matchesGlobScope(relPath: string, scope: string | undefined): boolean;
+export type { AuditContext } from "./audit/core/context.ts";
+export type { Issue, Severity } from "./audit/core/report.ts";
+export { issue } from "./audit/core/report.ts";
+export { matchesGlobScope } from "./audit/core/shared.ts";
+export type { CompiledPolicyEntry, MatchedPolicyEntry, PolicyEntry, PolicyFile, PolicyFileYaml, } from "./audit/policies/types.ts";
+export type { AuditRule, AuditSuite } from "./audit/rules/index.ts";

package/dist/plugin-types.js

@@ -1,12 +1,15 @@
 // src/audit/core/report.ts
-function issue(rule, file, details) {
+function issue(rule, file, details, options) {
   const message = typeof details === "string" ? details : details.message;
+  const selected = typeof details === "string" ? options : details;
   return {
     rule,
+    ...selected?.code ? { code: selected.code } : {},
     file,
-    link: typeof details === "string" ? undefined : details.link,
+    link: selected?.link,
     message,
-    severity: typeof details === "string" ? "error" : details.severity ?? "error"
+    ...selected?.remediation ? { remediation: selected.remediation } : {},
+    severity: selected?.severity ?? "error"
   };
 }
 // src/audit/core/shared.ts

package/dist/references/check.d.ts

@@ -0,0 +1,10 @@
+import type { SkillOwnershipConfig } from "../audit/config/types.ts";
+import type { AuditContext } from "../audit/core/context.ts";
+import { type Issue } from "../audit/core/report.ts";
+export declare function runGeneratedReferencesCheck(root: string, ownership?: SkillOwnershipConfig): Issue[];
+export declare function runGeneratedReferencesRule(ctx: AuditContext): Issue[];
+export declare const generatedReferencesRule: {
+    id: string;
+    global: boolean;
+    run: typeof runGeneratedReferencesRule;
+};

package/dist/references/constants.d.ts

@@ -0,0 +1,9 @@
+export declare const CANONICAL_REFS_DIR = ".skeleton/references";
+export declare const GENERATED_MARKER_START = "<!-- skeleton: generated-reference";
+export declare const GENERATED_MARKER_RE: RegExp;
+/** Markdown links targeting the old shared root references/ tree. */
+export declare const SHARED_REF_LINK_RE: RegExp;
+export declare function formatGeneratedHeader(sourceRelPath: string): string;
+export declare function stripGeneratedHeader(content: string): string;
+export declare function parseGeneratedSource(content: string): string | null;
+export declare function isGeneratedReference(content: string): boolean;

package/dist/references/discover.d.ts

@@ -0,0 +1,19 @@
+import type { SkillOwnershipConfig } from "../audit/config/types.ts";
+export interface SharedRefLink {
+    refPath: string;
+    sourceFile: string;
+}
+export interface SkillReferencePlan {
+    skill: string;
+    /** Repo-relative directory containing this concrete skill instance. */
+    skillDir: string;
+    refPaths: Set<string>;
+    links: SharedRefLink[];
+}
+/** Links still pointing at the old shared root references/ tree. */
+export declare function findSharedRefLinks(content: string, sourceFile: string): SharedRefLink[];
+export declare function discoverSkillReferencePlans(root: string, ownership?: SkillOwnershipConfig): SkillReferencePlan[];
+export declare function canonicalRefPath(_root: string, refPath: string): string;
+export declare function generatedRefPath(skillDir: string, refPath: string): string;
+export declare function rewriteSharedRefTarget(sourceFile: string, skillDir: string, refPath: string): string;
+export declare function rewriteSharedRefLinks(content: string, sourceFile: string, skillDir: string): string;

package/dist/result-types.d.ts

@@ -0,0 +1,72 @@
+import type { Issue } from "./audit/core/report.ts";
+export type CatalogStatus = "current" | "missing" | "stale" | "skipped-ci" | "not-applicable";
+export interface ReviewProofResult {
+    mode: "date" | "hash";
+    status: "not-enabled" | "not-checked" | "valid" | "invalid";
+    lockfile?: string;
+}
+export interface AuditResult {
+    schemaVersion: 1;
+    command: "audit";
+    ok: boolean;
+    exitCode: 0 | 1;
+    suite: string;
+    strict: boolean;
+    label: string;
+    scope: {
+        paths: string[];
+        fileCount?: number;
+    };
+    rules: {
+        requested: string[] | null;
+        executed: string[];
+    };
+    counts: {
+        errors: number;
+        warnings: number;
+    };
+    diagnostics: Issue[];
+    catalog: {
+        status: CatalogStatus;
+    };
+    reviewProof: ReviewProofResult;
+    successSuffix?: string;
+}
+export interface ValidateClassificationResult {
+    docs: string[];
+    code: string[];
+    skills: string[];
+    shell: string[];
+    json: string[];
+    policy: string[];
+    skipped: string[];
+    foreignSkills: string[];
+    missing: string[];
+    orphanPolicies: string[];
+}
+export type DocumentImpactReason = {
+    kind: "changed-document";
+} | {
+    kind: "changed-code-target";
+    target: string;
+};
+export interface ImpactedDocument {
+    path: string;
+    codeTargets: string[];
+    reasons: DocumentImpactReason[];
+}
+export interface ValidateChangedResult {
+    schemaVersion: 1;
+    command: "validate-changed";
+    ok: boolean;
+    exitCode: 0 | 1;
+    input: {
+        paths: string[];
+        staged: boolean;
+        base?: string;
+    };
+    classification: ValidateClassificationResult;
+    impactedDocuments: ImpactedDocument[];
+    audits: AuditResult[];
+    diagnostics: Issue[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@csark0812/skeleton",
-	"version": "1.6.2",
+	"version": "2.0.0",
 	"description": "SSOT audit CLI for agent harness repos",
 	"type": "module",
 	"bin": {
@@ -11,8 +11,13 @@
 			"types": "./dist/plugin-types.d.ts",
 			"default": "./dist/plugin-types.js"
 		},
+		"./result-types": {
+			"types": "./dist/result-types.d.ts",
+			"default": "./dist/result-types.js"
+		},
 		"./schemas/config.schema.json": "./schemas/config.schema.json",
-		"./schemas/policy-file.schema.json": "./schemas/policy-file.schema.json"
+		"./schemas/policy-file.schema.json": "./schemas/policy-file.schema.json",
+		"./schemas/result.schema.json": "./schemas/result.schema.json"
 	},
 	"files": [
 		"dist",
@@ -29,7 +34,7 @@
 	},
 	"packageManager": "bun@1.2.21",
 	"scripts": {
-		"build": "bun build src/cli.ts --target=node --outfile=dist/cli.js && bun build src/hooks/customize-on-skill-read.ts --target=node --outfile=dist/hooks/customize-on-skill-read.js && bun build src/plugin-types.ts --target=node --format=esm --outfile=dist/plugin-types.js --packages=external && cp types/plugin-types.d.ts dist/plugin-types.d.ts",
+		"build": "bun build src/cli.ts --target=node --outfile=dist/cli.js && bun build src/hooks/customize-on-skill-read.ts --target=node --outfile=dist/hooks/customize-on-skill-read.js && bun build src/plugin-types.ts --target=node --format=esm --outfile=dist/plugin-types.js --packages=external && bun build src/result-types.ts --target=node --format=esm --outfile=dist/result-types.js --packages=external && tsc -p tsconfig.types.json",
 		"test": "bun test",
 		"test:audit": "bun test src/audit/__tests__",
 		"test:cli": "bun test src/__tests__/cli",
@@ -45,6 +50,7 @@
 		"audit:skills": "bun src/cli.ts audit skills",
 		"audit:self": "bun src/cli.ts audit self",
 		"check": "bun run lint && bun test && bun run typecheck && bun run build && bun run audit:self",
+		"verify:package": "bun run build && bun scripts/verify-package.ts",
 		"start": "bun src/cli.ts --help",
 		"dev": "bun src/cli.ts --help",
 		"agent:test:live": "agent-test --suites-dir agent-suites --live --fail-on=behavior",
@@ -56,24 +62,27 @@
 		"agent:evidence:charts": "bun scripts/agent-evidence/render-charts.ts",
 		"agent:evidence:excerpt": "bun scripts/agent-evidence/excerpt-transcript.ts",
 		"agent:evidence:archive": "bash scripts/agent-evidence/archive-run.sh",
-		"prepack": "bun test && bun run typecheck && bun run build"
+		"prepack": "bun run check && bun scripts/verify-package.ts"
 	},
 	"dependencies": {
-		"ajv": "^8.17.1",
-		"github-slugger": "^2.0.0",
-		"remark": "^15.0.1",
-		"remark-gfm": "^4.0.1",
-		"smol-toml": "^1.8.0",
-		"tinyglobby": "^0.2.14",
-		"unist-util-visit": "^5.0.0",
-		"yaml": "^2.8.0"
+		"ajv": "8.20.0",
+		"github-slugger": "2.0.0",
+		"remark": "15.0.1",
+		"remark-gfm": "4.0.1",
+		"smol-toml": "1.8.0",
+		"tinyglobby": "0.2.14",
+		"unist-util-visit": "5.0.0",
+		"yaml": "2.9.0"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.5.3",
-		"@cursor/sdk": "^1.0.23",
-		"@post-print/agent-test": "^0.2.7",
-		"@types/bun": "^1.3.8",
-		"@types/github-slugger": "^2.0.0",
+		"@biomejs/biome": "2.5.3",
+		"@post-print/agent-test": "0.2.7",
+		"@types/bun": "1.3.8",
+		"@types/github-slugger": "2.0.0",
 		"typescript": "~7.0.2"
+	},
+	"overrides": {
+		"fast-uri": "3.1.5",
+		"undici": "6.28.0"
 	}
 }

package/schemas/config.schema.json

@@ -47,7 +47,7 @@
 		"docsLint": {
 			"type": "object",
 			"additionalProperties": false,
-			"description": "Near-duplicate and SSOT-summary lint tunables",
+			"description": "Near-duplicate, SSOT-summary, and code-fit lint tunables",
 			"properties": {
 				"nearDuplicateThreshold": {
 					"type": "number",
@@ -85,6 +85,17 @@
 					"type": "array",
 					"items": { "type": "string", "minLength": 1 },
 					"description": "Globs excluded from near-dupe / duplicate-SSOT"
+				},
+				"codeFitOverlapMin": {
+					"type": "number",
+					"minimum": 0,
+					"maximum": 1,
+					"description": "Min fraction of doc tokens that must also appear as code identifiers (default 0.03)"
+				},
+				"codeFitSurfaceCap": {
+					"type": "integer",
+					"minimum": 1,
+					"description": "Max auto-extracted surface names before surface= is required (default 25)"
 				}
 			}
 		},
@@ -126,6 +137,23 @@
 				}
 			}
 		},
+		"reviewProof": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["mode"],
+			"description": "Bind an explicit documentation review to exact document and code-target bytes",
+			"properties": {
+				"mode": {
+					"const": "hash",
+					"description": "Store SHA-256 review evidence"
+				},
+				"lockfile": {
+					"type": "string",
+					"minLength": 1,
+					"description": "Repo-relative review proof lockfile (default: .skeleton/review-lock.json)"
+				}
+			}
+		},
 		"plugins": {
 			"type": "array",
 			"items": { "type": "string", "minLength": 1 },

package/schemas/policy-file.schema.json

@@ -28,13 +28,16 @@
 				"message": { "type": "string" },
 				"scope": { "type": "string" },
 				"severity": { "enum": ["error", "warning"] },
-				"canonical": { "type": "string" }
+				"canonical": { "type": "string" },
+				"caseSensitive": { "type": "boolean" },
+				"placement": { "enum": ["any", "draft-only"] },
+				"handledBy": { "type": "string", "minLength": 1 }
 			},
 			"if": {
 				"properties": { "mode": { "const": "fingerprint" } },
 				"required": ["mode"]
 			},
-			"then": true,
+			"then": { "required": ["handledBy"] },
 			"else": { "required": ["pattern"] }
 		}
 	}