amanpal3/Dr-SKILLs / .agent/skills/archify
archify
UnverifiedCreate validated architecture, workflow, sequence, data-flow, lifecycle/state, ERD, class, tree, timeline, and waterfall diagrams as explorable standalone HTML with dark/light themes, motion and image/SVG/WebM export. Accept requirements or Mermaid; inspect repository evidence for code-backed diagrams. Use when visualizing systems, API calls, pipelines, schemas, histories, timings, or everyday steps, parts, relationships and states. Also turn an answer into a one-page explainer, with the conclusion first, structured panels, native diagrams and charts, when the user asks for a page, an explainer or an answer to share (做成一页, 用页面讲), or proactively when the user's rules opt in with an [archify explainer: ...] line. Not for dashboards.
renderers/shared/path-semantics.mjs
View on GitHubimport crypto from 'node:crypto';
import fs from 'node:fs';
import path from 'node:path';
const MAX_SYMLINK_DEPTH = 64;
const RECENT_PROBE_NAME_LIMIT = 128;
const recentProbeNames = new Set();
const WINDOWS_SMB_SHARE_FORBIDDEN = /[\u0000-\u001F"\/\\[\]:|<>+=;,?*]/u;
export function isWindowsIpcShare(share) {
return /^(?:IPC\$|pipe|mailslot)$/iu.test(share);
}
export function isValidWindowsSmbShareName(share) {
return typeof share === 'string'
&& share.length > 0
&& share.length <= 80
&& !WINDOWS_SMB_SHARE_FORBIDDEN.test(share)
&& !/[ .]$/u.test(share);
}
function result(status, code, details = {}) {
return {
status,
reason: {
code,
...details,
},
};
}
function unknown(code, details = {}) {
return result('unknown', code, details);
}
function systemFailure(code, error, details = {}) {
return unknown(code, {
...details,
...(typeof error?.code === 'string' ? { systemCode: error.code } : {}),
...(typeof error?.recoveryPath === 'string' ? { recoveryPath: error.recoveryPath } : {}),
...(typeof error?.restoredAtTarget === 'boolean'
? { restoredAtTarget: error.restoredAtTarget }
: {}),
});
}
function hostPath() {
return process.platform === 'win32' ? path.win32 : path.posix;
}
function absolutePath(input, side, basePath = process.cwd()) {
if (typeof input !== 'string' || input.length === 0) {
return {
ok: false,
failure: unknown('invalid-path', { side }),
};
}
try {
const pathApi = hostPath();
if (pathApi.isAbsolute(input)) return { ok: true, path: input };
if (pathApi.parse(input).root) {
return {
ok: false,
failure: unknown('drive-relative-path', { side }),
};
}
const separator = basePath.endsWith(pathApi.sep) ? '' : pathApi.sep;
return { ok: true, path: `${basePath}${separator}${input}` };
} catch (error) {
return {
ok: false,
failure: systemFailure('invalid-path', error, { side }),
};
}
}
function rootFailure(code, side) {
return {
ok: false,
failure: unknown(code, { side }),
};
}
function splitWindowsExtendedTail(tail, side, { internalRelativeLinkTarget = false } = {}) {
const authoredSegments = tail.split('\\');
// A single final separator is harmless, while an internal empty segment
// would require normalizing a raw extended path before it reaches Windows.
if (!internalRelativeLinkTarget
&& authoredSegments.slice(0, -1).some((component) => component.length === 0)) {
return rootFailure('windows-root-invalid', side);
}
const segments = authoredSegments.filter(Boolean);
if (!internalRelativeLinkTarget
&& segments.some((component) => component === '.' || component === '..')) {
return rootFailure('windows-root-invalid', side);
}
return { ok: true, segments };
}
function splitWindowsAbsolute(absolute, side, { internalRelativeLinkTarget = false } = {}) {
if (/^[\\/]{2}\.[\\/]/u.test(absolute)) {
return rootFailure('windows-namespace-unsupported', side);
}
if (/^[\\/]{2}\?[\\/]/u.test(absolute) && !absolute.startsWith('\\\\?\\')) {
return rootFailure('windows-namespace-unsupported', side);
}
if (absolute.startsWith('\\\\?\\')) {
if (absolute.includes('/')) return rootFailure('windows-root-invalid', side);
if (
/^\\\\\?\\(?:GLOBALROOT|Device)(?:\\|$)/iu.test(absolute)
|| /^\\\\\?\\Volume\{/iu.test(absolute)
) {
return rootFailure('windows-namespace-unsupported', side);
}
const extendedUnc = absolute.match(/^(\\\\\?\\UNC\\([^\\]+)\\([^\\]+))(?:\\(.*))?$/iu);
if (extendedUnc) {
if (isWindowsIpcShare(extendedUnc[3])) {
return rootFailure('windows-namespace-unsupported', side);
}
if (!isValidWindowsSmbShareName(extendedUnc[3])) {
return rootFailure('windows-root-invalid', side);
}
if ([extendedUnc[2], extendedUnc[3]].some((component) => component === '.' || component === '..')) {
return rootFailure('windows-root-invalid', side);
}
const tail = splitWindowsExtendedTail(
extendedUnc[4] || '',
side,
{ internalRelativeLinkTarget },
);
if (!tail.ok) return tail;
return {
ok: true,
root: `${extendedUnc[1]}\\`,
segments: tail.segments,
};
}
const extendedDrive = absolute.match(/^(\\\\\?\\[A-Za-z]:\\)(.*)$/u);
if (extendedDrive) {
const tail = splitWindowsExtendedTail(
extendedDrive[2],
side,
{ internalRelativeLinkTarget },
);
if (!tail.ok) return tail;
return {
ok: true,
root: extendedDrive[1],
segments: tail.segments,
};
}
return rootFailure('windows-root-invalid', side);
}
const unc = absolute.match(/^[\\/]{2}([^\\/]+)[\\/]([^\\/]+)(?:[\\/](.*))?$/u);
if (unc) {
if (isWindowsIpcShare(unc[2])) {
return rootFailure('windows-namespace-unsupported', side);
}
if (!isValidWindowsSmbShareName(unc[2])) {
return rootFailure('windows-root-invalid', side);
}
if ([unc[1], unc[2]].some((component) => component === '.' || component === '..')) {
return rootFailure('windows-root-invalid', side);
}
return {
ok: true,
root: `\\\\${unc[1]}\\${unc[2]}\\`,
segments: (unc[3] || '').split(/[\\/]+/u).filter(Boolean),
};
}
const drive = absolute.match(/^([A-Za-z]:)[\\/](.*)$/u);
if (drive) {
return {
ok: true,
root: `${drive[1]}\\`,
segments: drive[2].split(/[\\/]+/u).filter(Boolean),
};
}
return rootFailure('windows-root-invalid', side);
}
function splitAbsolute(absolute, side, options) {
if (process.platform === 'win32') return splitWindowsAbsolute(absolute, side, options);
const root = path.posix.parse(absolute).root;
return {
ok: true,
root,
segments: absolute.slice(root.length).split(/\/+/u).filter(Boolean),
};
}
function statBigInt(targetPath) {
return fs.statSync(targetPath, { bigint: true });
}
function ordinaryWindowsRoot(extendedRoot) {
const drive = extendedRoot.match(/^\\\\\?\\([A-Za-z]:\\)$/u);
if (drive) return drive[1];
const unc = extendedRoot.match(/^\\\\\?\\UNC\\([^\\]+)\\([^\\]+)\\$/iu);
return unc ? `\\\\${unc[1]}\\${unc[2]}\\` : null;
}
function hasStableIdentity(stat) {
return typeof stat?.dev === 'bigint'
&& typeof stat?.ino === 'bigint'
&& stat.ino !== 0n;
}
function compareKnownEntries(left, right, operation) {
if (hasStableIdentity(left.stat) && hasStableIdentity(right.stat)) {
const matches = left.stat.dev === right.stat.dev && left.stat.ino === right.stat.ino;
return result(matches ? 'match' : 'different', matches ? 'file-identity-match' : 'file-identity-different', {
operation,
method: 'bigint-stat',
});
}
// path-contract-allow: lexical-capability -- Canonical paths are compared inside the identity primitive.
if (left.realPath === right.realPath) {
return result('match', 'native-realpath-match', {
operation,
method: 'native-realpath',
});
}
return unknown('file-identity-unavailable', {
operation,
method: 'bigint-stat-and-native-realpath',
});
}
function rememberProbeName(name) {
recentProbeNames.add(name);
if (recentProbeNames.size > RECENT_PROBE_NAME_LIMIT) {
recentProbeNames.delete(recentProbeNames.values().next().value);
}
}
function probeInterference(message, code = 'ARCHIFY_PROBE_IDENTITY_CHANGED', details = {}) {
const error = new Error(message);
error.code = code;
Object.assign(error, details);
return error;
}
function sameStableIdentity(left, right) {
return hasStableIdentity(left)
&& hasStableIdentity(right)
&& left.dev === right.dev
&& left.ino === right.ino;
}
function preserveQuarantinedReplacement(quarantinePath, targetPath) {
try {
fs.linkSync(quarantinePath, targetPath);
return { restoredAtTarget: true };
} catch {
// Preserve the quarantined entry when the original name was concurrently
// occupied or the host cannot create a hard link. Never overwrite either.
return { restoredAtTarget: false };
}
}
function removeOwnedProbe(targetPath, expectedStat) {
let currentStat;
try {
currentStat = fs.lstatSync(targetPath, { bigint: true });
} catch (error) {
if (error?.code === 'ENOENT') {
return probeInterference('filesystem probe disappeared before cleanup', 'ARCHIFY_PROBE_MISSING');
}
return error;
}
if (!sameStableIdentity(expectedStat, currentStat)) {
return probeInterference('filesystem probe identity changed before cleanup');
}
const quarantineName = `.archify-path-semantics-cleanup-${process.pid}-${crypto.randomBytes(10).toString('hex')}`;
const quarantinePath = path.join(path.dirname(targetPath), quarantineName);
rememberProbeName(quarantineName);
try {
// Move the checked name into a fresh, unpublished quarantine namespace.
// A replacement introduced after the check is moved rather than deleted.
fs.renameSync(targetPath, quarantinePath);
} catch (error) {
return error;
}
let quarantineStat;
try {
quarantineStat = fs.lstatSync(quarantinePath, { bigint: true });
} catch (error) {
error.recoveryPath = quarantinePath;
error.restoredAtTarget = false;
return error;
}
if (!sameStableIdentity(expectedStat, quarantineStat)) {
const recovery = preserveQuarantinedReplacement(quarantinePath, targetPath);
return probeInterference(
'filesystem probe identity changed during cleanup',
'ARCHIFY_PROBE_IDENTITY_CHANGED',
{ recoveryPath: quarantinePath, ...recovery },
);
}
try {
// The quarantine spelling did not exist before the atomic rename and is
// never returned to callers. Legitimate target-path replacements therefore
// remain outside the only namespace we unlink.
fs.unlinkSync(quarantinePath);
return null;
} catch (error) {
error.recoveryPath = quarantinePath;
error.restoredAtTarget = false;
return error;
}
}
function resolvePlan({ root, segments }, side, depth) {
if (depth > MAX_SYMLINK_DEPTH) {
return {
ok: false,
failure: unknown('symlink-cycle', { side }),
};
}
let current;
let currentStat;
try {
current = fs.realpathSync.native(root);
} catch (error) {
// Node on Windows can report EISDIR while resolving a valid extended
// filesystem root (for example \\?\C:\). The namespace was already
// validated by splitWindowsAbsolute, so retain its exact spelling for
// traversal.
if (process.platform === 'win32'
&& error?.code === 'EISDIR'
&& ordinaryWindowsRoot(root)) {
current = root;
} else {
return {
ok: false,
failure: systemFailure('root-resolution-failed', error, { side }),
};
}
}
try {
currentStat = statBigInt(current);
} catch (error) {
// The same Node/Windows edge can occur during stat after realpath succeeds.
// A drive or share root is short enough for its ordinary spelling, while
// `current` remains namespaced so descendants keep long-path semantics.
const ordinaryRoot = process.platform === 'win32'
&& error?.code === 'EISDIR'
? ordinaryWindowsRoot(root)
: null;
if (ordinaryRoot && ordinaryRoot !== current) {
try {
currentStat = statBigInt(ordinaryRoot);
} catch (statError) {
return {
ok: false,
failure: systemFailure('root-resolution-failed', statError, { side }),
};
}
} else {
return {
ok: false,
failure: systemFailure('root-resolution-failed', error, { side }),
};
}
}
for (let index = 0; index < segments.length; index += 1) {
const segment = segments[index];
if (segment === '.') continue;
if (segment === '..') {
if (!currentStat.isDirectory()) {
return {
ok: false,
failure: unknown('ancestor-not-directory', { side, segmentIndex: index }),
};
}
try {
current = fs.realpathSync.native(hostPath().dirname(current));
currentStat = statBigInt(current);
} catch (error) {
return {
ok: false,
failure: systemFailure('path-resolution-failed', error, { side, segmentIndex: index }),
};
}
continue;
}
const candidate = hostPath().join(current, segment);
let candidateStat;
try {
candidateStat = fs.lstatSync(candidate, { bigint: true });
} catch (error) {
if (error?.code === 'ENOENT') {
if (!currentStat.isDirectory()) {
return {
ok: false,
failure: unknown('ancestor-not-directory', { side, segmentIndex: index }),
};
}
const unresolved = segments.slice(index).filter((item) => item !== '.');
if (unresolved.includes('..')) {
return {
ok: false,
failure: unknown('future-parent-traversal-indeterminate', {
side,
segmentIndex: index,
}),
};
}
return {
ok: true,
existing: false,
ancestor: {
realPath: current,
stat: currentStat,
},
unresolved,
};
}
if (error?.code === 'ENOTDIR') {
return {
ok: false,
failure: systemFailure('ancestor-not-directory', error, { side, segmentIndex: index }),
};
}
return {
ok: false,
failure: systemFailure('path-resolution-failed', error, { side, segmentIndex: index }),
};
}
if (candidateStat.isSymbolicLink()) {
let linkPlan;
try {
const authoredTarget = fs.readlinkSync(candidate);
const pathApi = hostPath();
const internalRelativeLinkTarget = !pathApi.isAbsolute(authoredTarget)
&& !pathApi.parse(authoredTarget).root;
const parsedTarget = absolutePath(authoredTarget, side, hostPath().dirname(candidate));
if (!parsedTarget.ok) return parsedTarget;
const target = splitAbsolute(parsedTarget.path, side, { internalRelativeLinkTarget });
if (!target.ok) return target;
linkPlan = {
root: target.root,
segments: [...target.segments, ...segments.slice(index + 1)],
};
} catch (error) {
return {
ok: false,
failure: systemFailure('symlink-resolution-failed', error, { side, segmentIndex: index }),
};
}
return resolvePlan(linkPlan, side, depth + 1);
}
if (index < segments.length - 1 && !candidateStat.isDirectory()) {
return {
ok: false,
failure: unknown('ancestor-not-directory', { side, segmentIndex: index }),
};
}
try {
current = fs.realpathSync.native(candidate);
currentStat = statBigInt(current);
} catch (error) {
return {
ok: false,
failure: systemFailure('path-resolution-failed', error, { side, segmentIndex: index }),
};
}
}
return {
ok: true,
existing: true,
entry: {
realPath: current,
stat: currentStat,
},
unresolved: [],
};
}
function resolveLocation(input, side) {
const parsed = absolutePath(input, side);
if (!parsed.ok) return parsed;
const plan = splitAbsolute(parsed.path, side);
if (!plan.ok) return plan;
return resolvePlan(plan, side, 0);
}
function semanticNameEnvelope(name) {
const names = new Set([name]);
const pending = [name];
while (pending.length > 0 && names.size <= 64) {
const current = pending.shift();
const candidates = [
current.normalize('NFC'),
current.normalize('NFD'),
current.toLocaleLowerCase('en-US'),
current.toLocaleUpperCase('en-US'),
];
for (const candidate of candidates) {
if (names.has(candidate)) continue;
names.add(candidate);
pending.push(candidate);
}
}
return names.size <= 64 ? names : null;
}
function semanticEnvelopesOverlap(leftName, rightName) {
const left = semanticNameEnvelope(leftName);
const right = semanticNameEnvelope(rightName);
if (!left || !right) return true;
for (const spelling of left) {
if (right.has(spelling)) return true;
}
return false;
}
function windowsDeviceName(name) {
const stem = name.split('.')[0].replace(/[ .]+$/u, '').toUpperCase();
return /^(?:CON|PRN|AUX|NUL|CONIN\$|CONOUT\$|COM[1-9¹²³]|LPT[1-9¹²³])$/u.test(stem);
}
function futureWindowsNameRisk(leftName, rightName) {
if (process.platform !== 'win32') return null;
const windowsShortName = /~[1-9][0-9]*(?:\.|$)/iu;
if (windowsShortName.test(leftName) || windowsShortName.test(rightName)) {
return unknown('future-short-name-indeterminate', { method: 'windows-8dot3' });
}
if (windowsDeviceName(leftName) || windowsDeviceName(rightName)) {
return unknown('future-device-name-indeterminate', { method: 'windows-device-name' });
}
if (/[ .]$/.test(leftName) || /[ .]$/.test(rightName)) {
return unknown('future-trim-name-indeterminate', { method: 'windows-trim-alias' });
}
return null;
}
/**
* Resolve one existing or future path through the host filesystem without
* exposing a string key for identity comparisons.
*/
export function resolvePhysicalLocation(targetPath) {
const resolution = resolveLocation(targetPath, 'target');
if (!resolution.ok) return resolution.failure;
if (resolution.existing) {
return {
status: 'resolved',
location: {
kind: 'existing',
path: resolution.entry.realPath,
},
reason: {
code: 'existing-native-realpath',
method: 'native-realpath',
},
};
}
return {
status: 'resolved',
location: {
kind: 'future',
ancestorPath: resolution.ancestor.realPath,
unresolved: [...resolution.unresolved],
},
reason: {
code: 'future-physical-ancestor',
method: 'native-realpath',
},
};
}
function probeNameAlias(directoryPath, leftName, rightName) {
if (leftName === rightName) {
return result('match', 'future-name-exact', { method: 'lexical-exact' });
}
if (recentProbeNames.has(leftName) || recentProbeNames.has(rightName)) {
return result('different', 'internal-probe-name', { method: 'probe-suppression' });
}
const windowsRisk = futureWindowsNameRisk(leftName, rightName);
if (windowsRisk) return windowsRisk;
if (!semanticEnvelopesOverlap(leftName, rightName)) {
return result('different', 'future-name-distinct', { method: 'semantic-envelope' });
}
const prefix = `.archify-path-semantics-${process.pid}-${crypto.randomBytes(10).toString('hex')}-`;
const probeName = `${prefix}${leftName}`;
const lookupName = `${prefix}${rightName}`;
const componentLength = (name) => process.platform === 'win32'
? name.length
: Buffer.byteLength(name, 'utf8');
if (componentLength(probeName) > 255 || componentLength(lookupName) > 255) {
return unknown('future-name-probe-unrepresentable', {
method: 'direct-filesystem-probe',
systemCode: 'ENAMETOOLONG',
});
}
let probePath;
let probeStat;
let descriptor;
let comparison;
let cleanupError;
try {
// Probe entries must live directly in the directory being queried. On
// Windows case sensitivity is per-directory and a child may not inherit it.
rememberProbeName(probeName);
rememberProbeName(lookupName);
probePath = path.join(directoryPath, probeName);
const lookupPath = path.join(directoryPath, lookupName);
descriptor = fs.openSync(probePath, 'wx', 0o600);
probeStat = fs.fstatSync(descriptor, { bigint: true });
let authoredStat;
let lookupStat;
try {
authoredStat = statBigInt(probePath);
lookupStat = statBigInt(lookupPath);
} catch (error) {
if (error?.code === 'ENOENT') {
comparison = result('different', 'future-name-different', { method: 'filesystem-probe' });
} else {
comparison = systemFailure('future-name-probe-failed', error, { method: 'filesystem-probe' });
}
}
if (!comparison) {
const identity = compareKnownEntries(
{ realPath: fs.realpathSync.native(probePath), stat: authoredStat },
{ realPath: fs.realpathSync.native(lookupPath), stat: lookupStat },
'future-name',
);
if (identity.status === 'match') {
comparison = result('match', 'future-name-alias', { method: 'filesystem-probe' });
} else if (identity.status === 'different') {
comparison = result('different', 'future-name-different', { method: 'filesystem-probe' });
} else {
comparison = identity;
}
}
} catch (error) {
comparison = systemFailure('future-name-probe-failed', error, { method: 'filesystem-probe' });
} finally {
// Pin the inode until cleanup finishes. Once the final handle is closed,
// an unlinked probe's inode can be reused by a replacement at the same name.
if (probeStat) cleanupError = removeOwnedProbe(probePath, probeStat);
if (descriptor !== undefined) {
try {
fs.closeSync(descriptor);
} catch (error) {
cleanupError = cleanupError ?? error;
}
}
}
if (cleanupError) {
return systemFailure('future-name-probe-cleanup-failed', cleanupError, {
method: 'filesystem-probe',
...(comparison ? { comparison: comparison.reason } : {}),
});
}
return comparison;
}
function sidecarCaseKey(component) {
// The candidate is accepted only after the containing filesystem confirms
// that the original grapheme and this spelling name the same entry.
return component.toLocaleUpperCase('en-US').toLocaleLowerCase('en-US');
}
function transformSidecarComponent(directoryPath, component, transform, phase) {
if (typeof Intl.Segmenter !== 'function') {
return {
ok: false,
failure: unknown('sidecar-unicode-segmentation-unavailable', {
operation: 'sidecar-namespace-key',
}),
};
}
const segmenter = new Intl.Segmenter('en-US', { granularity: 'grapheme' });
const comparisons = new Map();
const output = [];
for (const { segment } of segmenter.segment(component)) {
const candidate = transform(segment);
if (candidate === segment) {
output.push(segment);
continue;
}
const cacheKey = `${segment}\0${candidate}`;
let comparison = comparisons.get(cacheKey);
if (!comparison) {
comparison = probeNameAlias(directoryPath, segment, candidate);
comparisons.set(cacheKey, comparison);
}
if (comparison.status === 'unknown') {
return {
ok: false,
failure: unknown(`sidecar-${phase}-semantics-indeterminate`, {
operation: 'sidecar-namespace-key',
cause: comparison.reason,
}),
};
}
output.push(comparison.status === 'match' ? candidate : segment);
}
return {
ok: true,
component: output.join(''),
};
}
/**
* Produce a stable component for a sidecar namespace in one existing
* directory. The returned string is a collision-domain key, not a canonical
* path and must never be used to decide whether two filesystem entries match.
*/
export function sidecarNamespaceComponentKey(directoryPath, component) {
if (typeof component !== 'string' || component.length === 0
|| component === '.' || component === '..'
|| hostPath().basename(component) !== component) {
return unknown('invalid-sidecar-component', {
operation: 'sidecar-namespace-key',
});
}
const directory = resolveLocation(directoryPath, 'sidecar-directory');
if (!directory.ok) return directory.failure;
if (!directory.existing) {
return unknown('sidecar-directory-missing', {
operation: 'sidecar-namespace-key',
});
}
if (!directory.entry.stat.isDirectory()) {
return unknown('sidecar-parent-not-directory', {
operation: 'sidecar-namespace-key',
});
}
const normalized = transformSidecarComponent(
directory.entry.realPath,
component,
(segment) => segment.normalize('NFC'),
'normalization',
);
if (!normalized.ok) return normalized.failure;
const cased = transformSidecarComponent(
directory.entry.realPath,
normalized.component,
sidecarCaseKey,
'case',
);
if (!cased.ok) return cased.failure;
const renormalized = transformSidecarComponent(
directory.entry.realPath,
cased.component,
(segment) => segment.normalize('NFC'),
'normalization',
);
if (!renormalized.ok) return renormalized.failure;
return {
status: 'resolved',
directoryPath: directory.entry.realPath,
componentKey: renormalized.component,
reason: {
code: 'sidecar-namespace-key',
method: 'directory-filesystem-probe',
},
};
}
function compareUnmaterializedNames(leftName, rightName) {
if (leftName === rightName) {
return result('match', 'future-name-exact', { method: 'lexical-exact' });
}
const windowsRisk = futureWindowsNameRisk(leftName, rightName);
if (windowsRisk) return windowsRisk;
if (!semanticEnvelopesOverlap(leftName, rightName)) {
return result('different', 'future-name-distinct', { method: 'semantic-envelope' });
}
return unknown('future-descendant-semantics-indeterminate', {
method: 'unmaterialized-directory',
});
}
function compareFutureLocations(left, right) {
const ancestor = compareKnownEntries(left.ancestor, right.ancestor, 'future-ancestor');
if (ancestor.status !== 'match') return ancestor;
if (left.unresolved.length !== right.unresolved.length) {
return result('different', 'future-depth-different', {
operation: 'same-location',
leftDepth: left.unresolved.length,
rightDepth: right.unresolved.length,
});
}
let probedSegments = 0;
for (let index = 0; index < left.unresolved.length; index += 1) {
const names = index === 0
? probeNameAlias(
left.ancestor.realPath,
left.unresolved[index],
right.unresolved[index],
)
: compareUnmaterializedNames(left.unresolved[index], right.unresolved[index]);
if (names.reason.method === 'filesystem-probe') probedSegments += 1;
if (names.status !== 'match') {
const { code, ...reasonDetails } = names.reason;
return result(names.status, code, {
...reasonDetails,
operation: 'same-location',
segmentIndex: index,
});
}
}
return result('match', probedSegments > 0 ? 'future-location-alias' : 'future-location-exact', {
operation: 'same-location',
method: probedSegments > 0 ? 'filesystem-probe' : 'lexical-exact',
probedSegments,
});
}
/**
* Compare two existing filesystem entries by physical identity.
* Missing or unidentifiable entries return `unknown`, never `different`.
*/
export function sameEntry(leftPath, rightPath) {
const left = resolveLocation(leftPath, 'left');
if (!left.ok) return left.failure;
const right = resolveLocation(rightPath, 'right');
if (!right.ok) return right.failure;
if (!left.existing || !right.existing) {
return unknown('entry-missing', {
operation: 'same-entry',
missing: [
...(!left.existing ? ['left'] : []),
...(!right.existing ? ['right'] : []),
],
});
}
return compareKnownEntries(left.entry, right.entry, 'same-entry');
}
/**
* Compare two existing or future write targets using the containing filesystem's
* actual name semantics. Existing hard links and resolved symbolic links match.
*/
export function sameLocation(leftPath, rightPath) {
const left = resolveLocation(leftPath, 'left');
if (!left.ok) return left.failure;
const right = resolveLocation(rightPath, 'right');
if (!right.ok) return right.failure;
if (left.existing && right.existing) {
return compareKnownEntries(left.entry, right.entry, 'same-location');
}
if (left.existing !== right.existing) {
return result('different', 'location-existence-different', {
operation: 'same-location',
existing: left.existing ? 'left' : 'right',
});
}
return compareFutureLocations(left, right);
}
/** Compare the physical locations of the two paths' parent directories. */
export function sameParent(leftPath, rightPath) {
const left = absolutePath(leftPath, 'left');
if (!left.ok) return left.failure;
const right = absolutePath(rightPath, 'right');
if (!right.ok) return right.failure;
return sameLocation(hostPath().dirname(left.path), hostPath().dirname(right.path));
}
function parentEntry(entry) {
const parentPath = hostPath().dirname(entry.realPath);
// path-contract-allow: lexical-capability -- Both values are canonical paths captured by this primitive.
if (parentPath === entry.realPath) return null;
try {
const realPath = fs.realpathSync.native(parentPath);
return {
ok: true,
entry: {
realPath,
stat: statBigInt(realPath),
},
};
} catch (error) {
return {
ok: false,
failure: systemFailure('ancestor-resolution-failed', error, {
operation: 'contained-by',
}),
};
}
}
/**
* Determine physical containment in an existing directory. The comparison is
* inclusive and follows links; the target may exist or name a future location.
*/
export function containedBy(directoryPath, targetPath) {
const directory = resolveLocation(directoryPath, 'directory');
if (!directory.ok) return directory.failure;
if (directory.existing && !directory.entry.stat.isDirectory()) {
return unknown('container-not-directory', { operation: 'contained-by' });
}
const target = resolveLocation(targetPath, 'target');
if (!target.ok) return target.failure;
if (!directory.existing) {
if (target.existing) {
return unknown('container-missing', { operation: 'contained-by' });
}
const ancestor = compareKnownEntries(directory.ancestor, target.ancestor, 'contained-by');
if (ancestor.status !== 'match') return ancestor;
if (target.unresolved.length < directory.unresolved.length) {
return result('different', 'future-container-prefix-too-deep', {
operation: 'contained-by',
});
}
for (let index = 0; index < directory.unresolved.length; index += 1) {
const segment = index === 0
? probeNameAlias(
directory.ancestor.realPath,
directory.unresolved[index],
target.unresolved[index],
)
: compareUnmaterializedNames(
directory.unresolved[index],
target.unresolved[index],
);
if (segment.status === 'match') continue;
const { code, ...reasonDetails } = segment.reason;
return result(segment.status, code, {
...reasonDetails,
operation: 'contained-by',
segmentIndex: index,
});
}
return result('match', 'future-container-prefix-match', {
operation: 'contained-by',
target: 'future',
depth: target.unresolved.length - directory.unresolved.length,
});
}
let current;
if (!target.existing) {
current = target.ancestor;
} else if (target.entry.stat.isDirectory()) {
current = target.entry;
} else {
const parent = parentEntry(target.entry);
if (!parent?.ok) return parent?.failure ?? unknown('ancestor-resolution-failed', {
operation: 'contained-by',
});
current = parent.entry;
}
let depth = 0;
let identityWasUnknown = false;
while (current) {
const comparison = compareKnownEntries(directory.entry, current, 'contained-by');
if (comparison.status === 'match') {
return result('match', 'physical-ancestor-match', {
operation: 'contained-by',
depth,
target: target.existing ? 'existing' : 'future',
});
}
if (comparison.status === 'unknown') identityWasUnknown = true;
const parent = parentEntry(current);
if (parent === null) break;
if (!parent.ok) return parent.failure;
current = parent.entry;
depth += 1;
}
if (identityWasUnknown) {
return unknown('containment-identity-unavailable', {
operation: 'contained-by',
target: target.existing ? 'existing' : 'future',
});
}
return result('different', 'physical-ancestor-not-found', {
operation: 'contained-by',
target: target.existing ? 'existing' : 'future',
});
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |